nanotools.atoms module
This module defines the Atoms
class.
- class nanotools.atoms.Atoms(species: List[Species] = None, default_pseudo_preferences=[{'default': {'precision': 'DZP', 'type': 'OV', 'xc': 'PBE'}}], pseudo_preferences: List = None, formula: str = None, fractional_positions=None, ionic_charge=None, initial_magnetic_moment=0.0, initial_magnetic_moments=None, total_magnetic_moment=0.0, magnetic_moments=None, magnetic_radii=1.4, numspc: int = None, positions=None, species_indices: NDArray[Any, int64] = None, doping_ratios=None, valence_charge=None)[source]
Bases:
Base
Atoms
class.The
Atoms
class describes the atomic configuration: positions and species of the atoms. It also contains information about the charge of the system.- fractional_positions
Fractional coordinates of each atom. May be an array of row-vectors or the path to an xyz formatted file.
Examples:
atoms.fractional_positions = [[0,0,0],[0.25,0.25,0.25]] atoms.fractional_positions = "surface.xyz"
- Type:
2D array, str
- positions
Cartesian coordinates of each atom. May be an array of row-vectors or the path to an xyz formatted file.
Examples:
atoms.positions = [[0,0,0],[1.43,1.43,1.43]] atoms.positions = "surface.xyz"
- Type:
2D array, str
- species
Object containing species related parameters.
Examples:
atoms.species_indices = [0,1]
- Type:
list of
Species
- species_indices
Species index of each atom (atom <==> species correspondence).
- Type:
1D array
- ionic_charge
Total ionic charge.
- Type:
float
- initial_magnetic_moment
Initial magnetic moment.
- Type:
float
- initial_magnetic_moments
Initial magnetic moments.
- Type:
float
- valence_charge
Total valence charge.
Examples:
atoms.valence_charge = 63
- Type:
float
- add_species(species)[source]
Add a new species to the
Atoms
object.The input
Species
object is directly appended to the species list.- Parameters:
species (
Species
) – A properly initialized species object.
- get_formula(format=None)[source]
Returns the material’s formula.
- Parameters:
format (str, optional) – If format is not None, then recomputes the formula.
- Returns:
The material’s formula.
- Return type:
formula (str)
- get_ionic_charges()[source]
Returns the ionic charge of each atom based on the species information.
- get_positions(cell, displacement=None)[source]
Returns the atomic positions in Cartesian coordinates.
- get_species_indices()[source]
Returns the species indices.
For example, if the formula is “AuCu(3)” and the species labels are [“Cu”, “Au”] the function returns [2, 1, 1, 1].
Args:
- Returns:
Array containing the species indices.
- Return type:
species_indices (1D array)
- get_symbol(idx, standard=False)[source]
Returns the atomic symbol of a specific atom.
- Parameters:
idx (int) – Atom index.
standard (bool, optional) – If False, the species labels are returned as is. If True, the species labels are converted to the standard periodic table symbols. For instance, ‘Ga1’ will become ‘Ga’.
- get_symbols(standard=False)[source]
Returns the atomic symbols.
- Parameters:
standard (bool, optional) – If False, the species labels are returned as is. If True, the species labels are converted to the standard periodic table symbols. For instance, [‘Ga1’,’Ga2’] will become [‘Ga’,’Ga’].
- set_fractional_positions(fractional_positions, cell=None)[source]
Sets the atomic fractional_positions.
- set_initial_magnetic_moments(magnetic_moments, coordinates='spherical')[source]
Sets the initial magnetic moments.
The initial magnetic moments can be specified using arrays or in an xyz file. In non-collinear spin calculations, the columns of the arrays correspond to the spins in the x, y, z directions in Cartesian coordinates. The columns of the arrays correspond to the total spins and the angles theta and phi in spherical coordinates. In xyz files, the corresponding arrays are given as follows. The first two lines are the number of atoms and a comment. To parse spin, the function assumes the comment has four tags (usually species, x, y, z) and then sx, sy, sz or sr, st, sp at some point (not necessarily right after or in that order). The position of sx, sy, sz or sr, st, sp indicates which column has which spin component. For collinear spins, only sz or sr must be specified. Spins are automatically converted to spherical coordinates.
Examples:
3 species X Y Z sx sy sz Cr +8.021e+00 +1.039e+01 +1.039e+01 -4.999e+00 8.726e-03 3.061e-16 Cr +1.039e+01 +1.039e+01 +1.450e+01 3.535e+00 6.170e-03 3.535e+00 Cr +1.276e+01 +1.039e+01 +1.039e+01 3.535e+00 6.170e-03 -3.535e+00
- Parameters:
magnetic_moments (ndarray) – Array of initial magnetic moments. In collinear spin calculations, this should be a 1D array. In non-collinear spin calculations, this should be a 2D array. It can also be a string to an xyz file containing the spins.
coordinates (str, optional) – Coordinates system of the spins. Can be Cartesian or spherical.
Returns:
- set_species_indices(species)[source]
Sets the
species_indices
given a list of species.- Parameters:
species (list) – list of species labels.
- set_valence_charge(charge=None)[source]
Sets the total valence charge.
- Parameters:
charge (float, optional) – Total valence charge. If None, then the total ionic charge is used as a default valence charge, making the system neutral.
- to_vacuum(site, keep_aob=True)[source]
Converts an atom to a vacuum atom.
The pseudopotential of the atom in question is set to zero. The atomic orbital basis is retained, improving the basis completeness.
- Parameters:
site (int) – Site of the atom to be converted to vacuum.
keep_aob (bool) – If
True
, a vacuum atom with the same atomic orbital basis is created and introduced in place of the vacated atom; the atom is simply vacated otherwise.