nanotools.atoms module

This module defines the Atoms class.

class nanotools.atoms.Atoms(species: List[Species] | None = None, default_pseudo_preferences=[{'default': {'precision': 'DZP', 'type': 'OV', 'xc': 'PBE'}}], pseudo_preferences: List | None = None, formula: str | None = 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 = None, positions=None, species_indices: NDArray[Any, int64] | None = 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_fractional_positions(cell)[source]: Returns the fractional atomic positions.

get_ionic_charges()[source]: Returns the ionic charge of each atom based on the species information.

get_label(idx)[source]: Returns the label of the idx-th atom.

get_labels()[source]: Returns the labels of all atoms.

get_magnetic_moments()[source]: Returns an array containing the magnetic moment of each atom.

get_number_of_atoms()[source]: Returns the number of atoms.

get_number_of_species()[source]: Returns the number of species.

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_species_labels(standard=False)[source]: Returns the set of species labels.

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’].

get_total_magnetic_moment()[source]: Returns the total magnetic moment.

set_fractional_positions(fractional_positions, cell=None)[source]: Sets the atomic fractional_positions.

set_initial_magnetic_moment(total_magnetic_moment)[source]: Sets the total initial magnetic moment.

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_ionic_charge()[source]: Sets the total ionic charge based on the species information.

set_magnetic_moments(magnetic_moments)[source]: Sets the radii used in magnetic moment integration.

set_magnetic_radii(magnetic_radii)[source]: Sets the radii used in magnetic moment integration.

set_positions(positions, cell=None)[source]: Sets the atomic positions.

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.