qtcad.atoms.atoms module

class qtcad.atoms.atoms.Atoms(x: tuple | ndarray, y: tuple | ndarray, z: tuple | ndarray, unit_cell: UnitCellZincblende = None, crystal_dir: ndarray = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), rng_seed: int = None, vff_params_name: str = 'Niquet', verbose: bool = True)

Bases: Atoms

Atomic structure of a heterostructure.

It is assumed that the heterostructure is grown along the \(z\) axis and that it has the shape of a box (or in more technical terms, a rectangular parallelepiped). All the edges of the box are assumed to be parallel to either the \(x\) axis, the \(y\) axis, or the \(z\) axis. The heterostructure may include random alloying and rough heterointerfaces; it may not include crystallographic defects.

Attributes:

  • atom_species (Numpy.ndarray) – Vector whose elements are strings describing the atomic species (e.g. “Si”) of each atom in the structure.

  • atom_pos (Numpy.ndarray) – Matrix whose rows are the positions of the atoms in the structure; the ordering of the rows matches the ordering of atoms in atom_species.

  • atom_sublat (Numpy.ndarray) – Vector whose elements are integers describing the sublattice indices of each atom in the structure; the ordering of the rows matches the ordering of atoms in atom_species. The sublattice indices may take values between 0 and 7, namely, there is one possible sublattice index for each atom in the conventional (cubic) unit cell.

  • atom_num (int) – Number of atoms in the structure.

  • x (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(x\) axis.

  • y (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(y\) axis.

  • z (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(z\) axis.

  • unit_cell (UnitCellZincblende) – Unit cell to be sufficiently repeated to obtain an atomic structure filling the desired volume of space.

  • crystal_dir (Numpy.ndarray) – Matrix of integers specifying crystal directions in terms of primitive lattice vectors of the conventional (cubic) unit cell. The first (second, third) row of the matrix specifies the crystal direction to be made parallel to the \(x\) (\(y\), \(z\)) axis.

  • vff_params_name (str) – Name of the Keating valence force-field model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. Used to obtain the equilibrium bond lengths, which are used to establish which pairs of atoms are nearest neighbors as well as to compute the atomistic strain tensor, and in the Keating valence force-field model solver. Set to “Niquet” unless specified through the qtcad.atoms.atoms.Atoms.set_vff_params() method.

  • tb_params_name (str or tuple of str) – If a str, name of the tight-binding model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. If a tuple, names of the tight-binding model parameter sets ordered according to precedence; if multiple parameter sets are available for a given atom or pair of atoms, the parameter set is set to the available parameter set whose name first appears in the tuple. The parameter set names include “Niquet”, “Boykin”, “Vogl”, “Klimeck_cb”, “Klimeck_vb”, and “Kim”. Only used in the atomistic tight-binding Schrödinger equation solver. Set to (“Niquet”, “Kim”) unless specified through the qtcad.atoms.atoms.Atoms.set_tb_params() method.

  • verbose (bool) – Whether information pertaining to atomic structure manipulation is printed.

  • phi (callable) – Function which specifies the electric potential in the atomic structure. It takes as input three floats, the Cartesian coordinates of a point in space, and outputs a float, the value of the electric potential at that point. None (corresponding to zero electric potential) unless specified through the qtcad.atoms.atoms.Atoms.set_potential() method. At most one of phi and d can be specified at a time.

  • d (qtcad.device.device.Device) – Device containing attributes mesh and phi which respectively describe the finite-element mesh and the electric potential obtained via a finite-element Poisson solver; used to specify the electric potential in the atomic structure. None (corresponding to zero electric potential) unless specified through the qtcad.atoms.atoms.Atoms.set_potential_from_device() method. At most one of phi and d can be specified at a time.

  • B (tuple) – Vector of the Cartesian coordinates of an external, constant magnetic field. None (corresponding to zero magnetic field) unless specified through the qtcad.atoms.atoms.Atoms.set_Bfield() method.

  • soc (bool) – Whether spin-orbit coupling is considered in the atomistic tight-binding Schrödinger equation solver. False unless specified through the qtcad.atoms.atoms.Atoms.set_soc() method.

  • zeeman (bool) – Whether the Zeeman effect is considered in the atomistic tight-binding Schrödinger equation solver. False unless specified through the qtcad.atoms.atoms.Atoms.set_Zeeman() method.

  • energies (Numpy.ndarray) – Vector containing the eigenenergies obtained via the atomistic tight-binding Schrödinger equation solver, sorted in increasing order.

  • eigenfunctions (tuple of qtcad.atoms.wavefunction.Wavefunction) – The corresponding atomistic tight-binding eigenfunctions. The global phase of each eigenfunction is fixed so that the coefficient with the largest magnitude is real and positive.

__init__(x: tuple | ndarray, y: tuple | ndarray, z: tuple | ndarray, unit_cell: UnitCellZincblende = None, crystal_dir: ndarray = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), rng_seed: int = None, vff_params_name: str = 'Niquet', verbose: bool = True) → None

Check that the inputs are well-defined and tile the unit cell so as to fill the volume of the box.

Parameters:

  • x (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(x\) axis.

  • y (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(y\) axis.

  • z (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the box along the \(z\) axis.

  • unit_cell (UnitCellZincblende, optional) – Unit cell to be sufficiently repeated to obtain an atomic structure filling the desired volume of space. Default: unit cell of bulk, unstrained silicon.

  • crystal_dir (Numpy.ndarray, optional) – Matrix of integers specifying crystal directions in terms of primitive lattice vectors of the conventional (cubic) unit cell. The first (second, third) row of the matrix specifies the crystal direction to be made parallel to the \(x\) (\(y\), \(z\)) axis. Default: identity matrix Numpy.identity(3, dtype=int).

  • rng_seed (int, optional) – Seed for the random number generator used to construct random alloys. If None, the seed is set from fresh, unpredictable entropy from the operating system. Default: None.

  • vff_params_name (str, optional) – Name of the Keating valence force-field model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. Used to obtain the equilibrium bond lengths, which are used to establish which pairs of atoms are nearest neighbors as well as to compute the atomistic strain tensor, and in the Keating valence force-field model solver. Surface atoms with fewer than two nearest neighbors are excluded from the atomic structure; the notion of nearest neighbor is established by the equilibrium bond lengths. Default: “Niquet”.

  • verbose (bool, optional) – Whether information pertaining to atomic structure manipulation is printed. Default: True.

get_atomistic_strain_tensor() → ndarray

Compute atomistic strain tensor on each atomic site.

The implementation is based on Eq. 19 of [PKW+98]. In the reference unstrained atomic structure, the nearest neighbors of each atom are assumed to lie along the directions of the corners of a regular tetrahedron with bond lengths normalized to the equilibrium bond lengths.

Returns:

Numpy.ndarray – Strain tensor for each atomic site; the first index is the atomic site index, and the second and third indices are Cartesian direction indices. The strain tensor is set to 0 for surface atoms.

new_layer(z_bot: float | RoughSurface, z_top: float | RoughSurface, atom_species: ndarray, method: str = 'stochastic') → None

Define the geometry and material composition of a heterostructure layer. Alter the material composition of the layer accordingly.

Parameters:

  • z_bot (float or RoughSurface) – Bottom surface of the layer along the \(z\) axis. If a float, the surface is assumed to be perfectly flat.

  • z_top (float or RoughSurface) – Top surface of the layer along the \(z\) axis. If a float, the surface is assumed to be perfectly flat.

  • atom_species (Numpy.ndarray) – For a heterostructure layer with a crystalline structure, vector whose elements are strings describing the atomic species (e.g. “Si”) of each atom of the conventional (cubic) unit cell in the layer; it should contain 8 elements. For a randomly-alloyed heterostructure layer, matrix whose first column contains strings describing the atomic species (e.g. “Si”) of each atom in the random alloy, and whose second column contains float between 0.0 and 1.0 describing the ratio of the corresponding atomic species in the random alloy.

  • method (str, optional) – For a randomly-alloyed heterostructure layer (i.e., for cases where atom_species has two columns), method by which the random alloy is constructed. If “stochastic”, each atom in the heterostructure layer is independently replaced with one of the atomic species in the first column of atom_species according to the probabilities provided in the second column; this may result in a chemical composition which slightly deviates from the target ratios, which reflects the inherent stochastic composition of finite random alloys. If “fixed”, the random alloy is generated such that the overall chemical composition exactly matches the ratios specified in the second column of atom_species. This input is ignored if atom_species has only one column. Default: “stochastic”.

print_energies(decimals: int = 8) → None

Print the eigenenergies obtained via the atomistic tight-binding Schrödinger equation solver in units of electronvolts.

Parameters:

decimals (int, optional) – Number of decimals to print.

save(path: str) → None

Save the atomic structure to a file.

Parameters:

path (str) – Path to the file in which to save the atomic structure; all file extensions are accepted.

save_energies(path: str) → None

Save to a .txt file the eigenenergies obtained via the atomistic tight-binding Schrödinger equation solver in units of electronvolts.

Parameters:

path (str) – Path to the .txt file in which to save the eigenenergies.

save_xyz(path: str, comment: str = '') → None

Save .xyz file of the atomic structure.

Parameters:

  • path (str) – Path in which the .xyz file is to be saved.

  • comment (str, optional) – Content of the comment line of the .xyz file. Default: "".

Note

By convention, the atomic coordinates stored in the .xyz file are expressed in units of angstroms rather than metres.

set_Bfield(B: tuple | ndarray) → None

Set an external, constant magnetic field in the atomic structure.

This magnetic field is used in the atomistic tight-binding Schrödinger equation solver. The impact of the magnetic field on the offsite blocks of the tight-binding Hamiltonian is modeled through the Peierls substitution, whereby the standard momentum \(\mathbf{p}\) is effectively replaced by the generalized momentum \(\mathbf{p}-e\mathbf{A}\), where \(e\) is the elementary charge and \(\mathbf{A}\) is the magnetic vector potential. The impact of the magnetic field on the onsite blocks of the tight-binding Hamiltonian is (optionally) modeled through the Zeeman effect, whereby the Zeeman Hamiltonian \(-\mathbf{\mu}\cdot\mathbf{B}\), where \(\mathbf{\mu}\) is the magnetic moment and \(\mathbf{B}\) is the magnetic field, is effectively added to the Hamiltonian.

Parameters:

B (tuple or Numpy.ndarray) – Vector of the Cartesian coordinates of an external, constant magnetic field.

set_Zeeman(value: bool) → None

Set whether the Zeeman effect is considered in the atomistic tight-binding Schrödinger equation solver.

Parameters:

value (bool) – Whether the Zeeman effect is considered.

set_potential(phi: Callable) → None

Set the electric potential in the atomic structure from a function.

This potential is used in the atomistic tight-binding Schrödinger equation solver, specifically by adding \(-e \varphi\) on the diagonal of the Hamiltonian, where \(e\) is the elementary charge and \(\varphi\) is the electric potential.

Parameters:

phi (callable) – Function which specifies the electric potential in the atomic structure. It takes as input three floats, the Cartesian coordinates of a point in space, and outputs a float, the value of the electric potential at that point.

Note

This method sets self.d to None.

set_potential_from_device(d: Device) → None

Set the electric potential in the atomic structure from the results of a finite-element simulation stored in a Device object.

This potential is used in the atomistic tight-binding Schrödinger equation solver, specifically by adding \(-e \varphi\) on the diagonal of the Hamiltonian, where \(e\) is the elementary charge and \(\varphi\) is the electric potential.

Parameters:

d (qtcad.device.device.Device) – Device containing attributes mesh and phi which respectively describe the finite-element mesh and the electric potential obtained via a finite-element Poisson solver.

Note

This method sets self.phi to None.

set_soc(value: bool) → None

Set whether spin-orbit coupling is considered in the atomistic tight-binding Schrödinger equation solver.

Parameters:

value (bool) – Whether spin-orbit coupling is considered.

set_tb_params(tb_params_name: str | Tuple[str, ...]) → None

Set the parameter set for the atomistic tight-binding Schrödinger equation solver.

Parameters:

tb_params_name (str or tuple of str) – If a str, name of the tight-binding model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted. If a tuple, names of the tight-binding model parameter sets ordered according to precedence; if multiple parameter sets are available for a given atom or pair of atoms, the parameter set is set to the available parameter set whose name first appears in the tuple. The parameter set names include “Niquet”, “Boykin”, “Vogl”, “Klimeck_cb”, “Klimeck_vb”, and “Kim”.

Note

The parameter sets are defined in the qtcad.atoms.materials module.

set_vff_params(vff_params_name: str) → None

Set the parameter set to compute the atomistic strain tensor and for the Keating valence force-field model solver.

Parameters:

vff_params_name (str) – Name of the Keating valence force-field model parameter set, which is typically the name of the first author of the paper from which the parameters were extracted.

Note

The parameter sets are defined in the qtcad.atoms.materials module.

strain_atomic_structure(strain_tensor: Callable) → None

Apply strain to atomic structure.

The displacement of the atoms from their current position is obtained by integrating the strain tensor along a line joining an arbitrary reference point to the position of the atom. The resulting atomic positions are stored in self.atom_pos.

Parameters:

strain_tensor (callable) – Function which specifies the desired strain tensor in the atomic structure. It takes as input three floats, the Cartesian coordinates of a point in space, and outputs a symmetric \(3\times 3\) matrix (Numpy.ndarray), the value of the strain tensor at that point.

Note

Since this method is based on the continuum, infinitesimal strain tensor formalism, it may result in atomic structures whose atomistic strain tensor (as computed from qtcad.atoms.atoms.Atoms.get_atomistic_strain_tensor()) deviates from the input strain tensor.

class qtcad.atoms.atoms.SubAtoms(parent: Atoms, x: tuple | ndarray, y: tuple | ndarray, z: tuple | ndarray)

Bases: SubAtoms

Restricted atomic structure of a heterostructure typically used as an input to the atomistic tight-binding Schrödinger equation solver.

__init__(parent: Atoms, x: tuple | ndarray, y: tuple | ndarray, z: tuple | ndarray) → None

Check that the inputs are well-defined and construct the atomic structure within a restricted region of the box.

Parameters:

  • parent (qtcad.atoms.atoms.Atoms) – Atomic structure from which to extract the restricted atomic structure.

  • x (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the restricted region along the x axis.

  • y (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the restricted region along the y axis.

  • z (tuple or Numpy.ndarray) – Vector with two elements specifying the minimal and maximal positions of the restricted region along the z axis.

qtcad.atoms.atoms.load(path: str) → Atoms

Load an atomic structure from a file.

Parameters:

path (str) – Path to the file from which to load the atomic structure.

Returns:

qtcad.atoms.atoms.Atoms – Atoms object loaded from the file.