pyiron_atomistics.atomistics.structure.atoms.Atoms

class pyiron_atomistics.atomistics.structure.atoms.Atoms(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, indices=None, elements=None, dimension=None, species=None, **qwargs)

Bases: Atoms

The Atoms class represents all the information required to describe a structure at the atomic scale. This class is derived from the ASE atoms class.

Parameters:

• elements (list/numpy.ndarray) – List of strings containing the elements or a list of atomistics.structure.periodic_table.ChemicalElement instances

• numbers (list/numpy.ndarray) – List of atomic numbers of elements

• symbols (list/numpy.ndarray) – List of chemical symbols

• positions (list/numpy.ndarray) – List of positions

• scaled_positions (list/numpy.ndarray) – List of scaled positions (relative coordinates)

• pbc (list/numpy.ndarray/boolean) – Tells if periodic boundary conditions should be applied on the three axes

• cell (list/numpy.ndarray instance) – A 3x3 array representing the lattice vectors of the structure

Note: Only one of elements/symbols or numbers should be assigned during initialization

indices

A list of size N which gives the species index of the structure which has N atoms

Type:

numpy.ndarray

__init__(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, indices=None, elements=None, dimension=None, species=None, **qwargs)

Methods

__init__([symbols, positions, numbers, ...])
add_high_symmetry_path(path)	Adds a new path to the dictionary of pathes for band structure calculations.
add_high_symmetry_points(new_points)	Adds new points to the dict of existing high symmetry points.
add_tag(**qwargs)	Add tags to the atoms object.
analyse_ovito_centro_symmetry([num_neighbors])	Analyse centrosymmetry parameter
analyse_ovito_cna_adaptive([mode])	Use common neighbor analysis
analyse_ovito_voronoi_volume()	Calculate the Voronoi volume of atoms
analyse_phonopy_equivalent_atoms()
analyse_pyscal_centro_symmetry([num_neighbors])	Analyse centrosymmetry parameter
analyse_pyscal_cna_adaptive([mode, ...])	Use common neighbor analysis
analyse_pyscal_diamond_structure([mode, ...])	Analyse diamond structure
analyse_pyscal_steinhardt_parameter([...])	Calculate Steinhardts parameters
analyse_pyscal_voronoi_volume()	Calculate the Voronoi volume of atoms
append(atom)	Append atom to end.
apply_strain(epsilon[, return_box, mode])	Apply a given strain on the structure.
center([vacuum, axis, about])	Center atoms in unit cell.
center_coordinates_in_unit_cell([origin, eps])	Wrap atomic coordinates within the supercell.
close()
cluster_analysis(id_list[, neighbors, ...])	param id_list:
convert_element(el[, pse])	Convert a string or an atom instance into a ChemicalElement instance
convert_formula(elements)	Convert a given chemical formula into a list of elements
copy()	Returns a copy of the instance
create_line_mode_structure([...])	Uses 'seekpath' to create a new structure with high symmetry points and path for band structure calculations.
edit()	Modify atoms interactively through ASE's GUI viewer.
euler_rotate([phi, theta, psi, center])	Rotate atoms via Euler angles (in degrees).
extend(other)	Extend atoms object by appending atoms from other.
find_mic(v[, vectors])	Find vectors following minimum image convention (mic).
find_neighbors_by_vector(vector[, ...])	param vector: vector by which positions are translated (and neighbors are searched)
from_dict(obj_dict)
from_hdf(hdf[, group_name])	Retrieve the object from a HDF5 file
fromdict(dct)	Rebuild atoms object from dictionary representation (todict).
get_all_distances([mic, vector])	Return distances of all of the atoms with all of the atoms.
get_angle(a1, a2, a3[, mic])	Get angle formed by three atoms.
get_angles(indices[, mic])	Get angle formed by three atoms for multiple groupings.
get_angular_momentum()	Get total angular momentum with respect to the center of mass.
get_array(name[, copy])	Get an array.
get_atomic_numbers()	Returns the atomic numbers of all the atoms in the structure
get_bonds([radius, max_shells, prec, ...])	param radius:
get_calculator()	Get currently attached calculator object.
get_cell([complete])	Get the three unit cell vectors as a class:ase.cell.Cell` object.
get_cell_lengths_and_angles()	Get unit cell parameters.
get_celldisp()	Get the unit cell displacement vectors.
get_center_of_mass()	returns: center of mass in A
get_charges()	Get calculated charges.
get_chemical_elements()	Returns the list of chemical element instances
get_chemical_formula()	Returns the chemical formula of structure
get_chemical_indices()	Returns the list of chemical indices as ordered in self.species
get_chemical_symbols()	Returns the chemical symbols for all the atoms in the structure
get_constraint()
get_density()	Returns the density in g/cm^3
get_dihedral(a0, a1, a2, a3[, mic])	Calculate dihedral angle.
get_dihedrals(indices[, mic])	Calculate dihedral angles.
get_dipole_moment()	Calculate the electric dipole moment for the atoms object.
get_distance(a0, a1[, mic, vector])	Return distance between two atoms.
get_distances(a, indices[, mic, vector])	Return distances of atom No.i with a list of atoms.
get_distances_array([p1, p2, mic, vectors])	Return distance matrix of every position in p1 with every position in p2.
get_equivalent_points(points[, use_magmoms, ...])	param points: 3d vector
get_extended_positions(width[, ...])	Get all atoms in the boundary around the supercell which have a distance to the supercell boundary of less than dist
get_forces([apply_constraint, md])	Calculate atomic forces.
get_global_number_of_atoms()	Returns the global number of atoms in a distributed-atoms parallel simulation.
get_high_symmetry_path()	Path used for band structure calculations
get_high_symmetry_points()	dictionary of high-symmetry points defined for this specific structure.
get_initial_charges()	Get array of initial charges.
get_initial_magnetic_moments()	Get array of initial magnetic moments.
get_ir_reciprocal_mesh(mesh[, is_shift, ...])	param mesh:
get_kinetic_energy()	Get the kinetic energy.
get_kinetic_stress([voigt])	Calculate the kinetic part of the Virial stress tensor.
get_kinetic_stresses([voigt])	Calculate the kinetic part of the Virial stress of all the atoms.
get_magnetic_moment()	Get calculated total magnetic moment.
get_magnetic_moments()	Get calculated local magnetic moments.
get_majority_species([return_count])	This function returns the majority species and their number in the box
get_masses()	Gets the atomic masses of all atoms in the structure
get_masses_dof()	Returns:
get_momenta()	Get array of momenta.
get_moments_of_inertia([vectors])	Get the moments of inertia along the principal axes.
get_neighborhood(positions[, num_neighbors, ...])	param position: Position in a box whose neighborhood information is analysed
get_neighbors([num_neighbors, tolerance, ...])	param num_neighbors: number of neighbors
get_neighbors_by_distance([cutoff_radius, ...])	param num_neighbors: number of neighbors
get_number_of_atoms()	Returns:
get_number_of_degrees_of_freedom()	Returns:
get_number_of_species()	Returns:
get_number_species_atoms()	Returns a dictionary with the species in the structure and the corresponding count in the structure
get_numbers_of_neighbors_in_sphere([...])	Function to compute the maximum number of neighbors in a sphere around each atom.
get_parent_basis()	Returns the basis with all user defined/special elements as the it's parent
get_parent_symbols()	Returns the chemical symbols for all the atoms in the structure even for user defined elements
get_pbc()	Get periodic boundary condition flags.
get_positions([wrap])	Get array of positions.
get_potential_energies()	Calculate the potential energies of all the atoms.
get_potential_energy([force_consistent, ...])	Calculate potential energy.
get_primitive_cell([symprec, angle_tolerance])	param symprec:
get_properties(properties)	This method is experimental; currently for internal use.
get_reciprocal_cell()	Get the three reciprocal lattice vectors as a 3x3 ndarray.
get_scaled_positions([wrap])	Get positions relative to unit cell.
get_shell_matrix([id_list, chemical_pair, ...])	Shell matrices for pairwise interaction.
get_spacegroup([symprec, angle_tolerance])	param symprec:
get_species_objects()	Returns:
get_species_symbols()	Returns the symbols of the present species
get_spherical_coordinates([x])	param x: coordinates to transform. If not set, the positions
get_stress([voigt, apply_constraint, ...])	Calculate stress tensor.
get_stresses([include_ideal_gas, voigt])	Calculate the stress-tensor of all the atoms.
get_symmetry([use_magmoms, use_elements, ...])	param use_magmoms: Whether to consider magnetic moments (cf.
get_symmetry_dataset([symprec, angle_tolerance])	param symprec:
get_tags()	Returns the keys of the stored tags of the structure
get_temperature()	Get the temperature in Kelvin.
get_total_energy()	Get the total energy - potential plus kinetic energy.
get_velocities()	Get array of velocities.
get_vertical_length([norm_order])	Return the length of the cell in each direction projected on the vector vertical to the plane.
get_volume([per_atom])	param per_atom: True if volume per atom is to be returned
get_voronoi_volume()	Calculate the Voronoi volume of atoms
get_wrapped_coordinates(positions[, epsilon])	Return coordinates in wrapped in the periodic cell
group_points_by_symmetry(points[, ...])	This function classifies the points into groups according to the box symmetry given by spglib.
has(name)	Check for existence of array.
is_skewed([tolerance])	Check whether the simulation box is skewed/sheared.
iterimages()
new_array(name, a[, dtype, shape])	Add new array.
numbers_to_elements(numbers)	Convert atomic numbers in element objects (needed for compatibility with ASE)
occupy_lattice(**qwargs)	Replaces specified indices with a given species
plot3d([mode, show_cell, show_axes, camera, ...])	Plot3d relies on NGLView or plotly to visualize atomic structures.
pop([i])	Remove and return atom at index i (default last).
pos_xyz()	Returns:
rattle([stdev, seed, rng])	Randomly displace atoms.
refine_cell([symprec, angle_tolerance])	param symprec:
repeat(rep)	Create new repeated atoms object.
repeat_points(points, rep[, centered])	Return points with repetition given according to periodic boundary conditions
reset_absolute(is_absolute)
rotate([a, v, center, rotate_cell, index_list])	Rotate atoms based on a vector and an angle, or two vectors.
rotate_dihedral(a1, a2, a3, a4, angle[, ...])	Rotate dihedral angle.
scaled_pos_xyz()	Returns:
select_index(el)	Returns the indices of a given element in the structure
select_parent_index(el)	Returns the indices of a given element in the structure ignoring user defined elements
set_absolute()
set_angle(a1[, a2, a3, angle, mask, ...])	Set angle (in degrees) formed by three atoms.
set_array(name, a[, dtype, shape])	Update array.
set_atomic_numbers(numbers)	Set atomic numbers.
set_calculator([calc])	Attach calculator object.
set_cell(cell[, scale_atoms, apply_constraint])	Set unit cell vectors.
set_celldisp(celldisp)	Set the unit cell displacement vectors.
set_center_of_mass(com[, scaled])	Set the center of mass.
set_chemical_symbols(symbols)	Set chemical symbols.
set_constraint([constraint])	Apply one or more constrains.
set_dihedral(a1, a2, a3, a4, angle[, mask, ...])	Set the dihedral angle (degrees) between vectors a1->a2 and a3->a4 by changing the atom indexed by a4.
set_distance(a0, a1, distance[, fix, mic, ...])	Set the distance between two atoms.
set_initial_charges([charges])	Set the initial charges.
set_initial_magnetic_moments([magmoms])	Set array of initial magnetic moments.
set_masses([masses])	Set atomic masses in atomic mass units.
set_momenta(momenta[, apply_constraint])	Set momenta.
set_pbc(pbc)	Set periodic boundary condition flags.
set_positions(newpositions[, apply_constraint])	Set positions, honoring any constraints.
set_relative()
set_repeat(vec)
set_scaled_positions(scaled)	Set positions relative to unit cell.
set_species(value)	Setting the species list
set_tags(tags)	Set tags for all atoms.
set_velocities(velocities)	Set the momenta by specifying the velocities.
symmetrize_vectors(vectors[, use_magmoms, ...])	Symmetrization of natom x 3 vectors according to box symmetries
to_ase()
to_dict()
to_hdf(hdf[, group_name])	Save the object in a HDF5 file
to_ovito()
to_pymatgen()
to_pyscal_system()
todict()	For basic JSON (non-database) support.
translate(displacement)	Translate atomic positions.
wrap(**wrap_kw)	Wrap positions to unit cell.
write(filename[, format])	Write atoms object to a file.

Attributes

analyse
ase_objtype
calc	Calculator object.
cell	The ase.cell.Cell for direct manipulation.
constraints	Constraints.
elements	A size N list of atomistics.structure.periodic_table.ChemicalElement instances according to the ordering of the atoms in the instance
number_of_lattice_vectors	Number of (non-zero) lattice vectors.
numbers	Attribute for direct manipulation of the atomic numbers.
pbc	Reference to pbc-flags for in-place manipulations.
positions	Attribute for direct manipulation of the positions.
species	A list of atomistics.structure.periodic_table.ChemicalElement instances
spins	Magnetic spins for each atom in the structure
symbols	Get chemical symbols as a ase.symbols.Symbols object.
velocities

add_high_symmetry_path(path)

Adds a new path to the dictionary of pathes for band structure calculations.

Parameters:

path (dict) – dictionary of lists of tuples with start and end point. E.G. {“my_path”: [(‘Gamma’, ‘X’), (‘X’, ‘Y’)]}

add_high_symmetry_points(new_points)

Adds new points to the dict of existing high symmetry points.

Parameters:

new_points (dict) – Points to add

add_tag(**qwargs)

Add tags to the atoms object.

Examples

For selective dynamics:

>>> self.add_tag(selective_dynamics=[False, False, False])

analyse_ovito_centro_symmetry(num_neighbors=12)

Analyse centrosymmetry parameter

Parameters:

num_neighbors (int) – number of neighbors

Returns:

list of centrosymmetry parameter

Return type:

list

analyse_ovito_cna_adaptive(mode='total')

Use common neighbor analysis

Parameters:

• mode ("total"/"numeric"/"str") –

  Controls the style and level of detail of the output. - total : return number of atoms belonging to each structure - numeric : return a per atom list of numbers- 0 for unknown,

  1 fcc, 2 hcp, 3 bcc and 4 icosa

  • str : return a per atom string of structures

• ovito_compatibility (bool) – use ovito compatibility mode

Returns:

(depends on mode)

analyse_ovito_voronoi_volume()

Calculate the Voronoi volume of atoms

analyse_pyscal_centro_symmetry(num_neighbors=12)

Analyse centrosymmetry parameter

Parameters:

num_neighbors (int) – number of neighbors

Returns:

list of centrosymmetry parameter

Return type:

list

analyse_pyscal_cna_adaptive(mode='total', ovito_compatibility=False)

Use common neighbor analysis

Parameters:

• mode ("total"/"numeric"/"str") –

  Controls the style and level of detail of the output. - total : return number of atoms belonging to each structure - numeric : return a per atom list of numbers- 0 for unknown,

  1 fcc, 2 hcp, 3 bcc and 4 icosa

  • str : return a per atom string of structures

• ovito_compatibility (bool) – use ovito compatibility mode

Returns:

(depends on mode)

analyse_pyscal_diamond_structure(mode='total', ovito_compatibility=False)

Analyse diamond structure

Parameters:

• mode ("total"/"numeric"/"str") – Controls the style and level

• output. (of detail of the) –

  • total : return number of atoms belonging to each structure

  • numericreturn a per atom list of numbers- 0 for unknown,

    1 fcc, 2 hcp, 3 bcc and 4 icosa

  • str : return a per atom string of structures

• ovito_compatibility (bool) – use ovito compatibility mode

Returns:

(depends on mode)

analyse_pyscal_steinhardt_parameter(neighbor_method='cutoff', cutoff=0, n_clusters=2, q=(4, 6), averaged=False, clustering=True)

Calculate Steinhardts parameters

Parameters:

• neighbor_method (str) – can be [‘cutoff’, ‘voronoi’]. (Default is ‘cutoff’.)

• cutoff (float) – Can be 0 for adaptive cutoff or any other value. (Default is 0, adaptive.)

• n_clusters (int/None) – Number of clusters for K means clustering or None to not cluster. (Default is 2.)

• q (list) – Values can be integers from 2-12, the required q values to be calculated. (Default is None, which uses (4, 6).)

• averaged (bool) – If True, calculates the averaged versions of the parameter. (Default is False.)

Returns:

(number of q’s, number of atoms) shaped array of q parameters numpy.ndarray: If clustering=True, an additional per-atom array of cluster ids is also returned

Return type:

numpy.ndarray

analyse_pyscal_voronoi_volume()

Calculate the Voronoi volume of atoms

append(atom)

Append atom to end.

apply_strain(epsilon, return_box=False, mode='linear')

Apply a given strain on the structure. It applies the matrix F in the manner:

```

new_cell = F @ current_cell

```

Parameters:

• epsilon (float/list/ndarray) – epsilon matrix. If a single number is set, the same strain is applied in each direction. If a 3-dim vector is set, it will be multiplied by a unit matrix.

• return_box (bool) – whether to return a box. If set to True, only the returned box will have the desired strain and the original box will stay unchanged.

• mode (str) – linear or lagrangian. If linear, F is equal to the epsilon - 1. If lagrangian, epsilon is given by (F^T * F - 1) / 2. It raises an error if the strain is not symmetric (if the shear components are given).

property calc

Calculator object.

property cell

The ase.cell.Cell for direct manipulation.

center(vacuum=None, axis=(0, 1, 2), about=None)

Center atoms in unit cell.

Centers the atoms in the unit cell, so there is the same amount of vacuum on all sides.

vacuum: float (default: None)

If specified adjust the amount of vacuum when centering. If vacuum=10.0 there will thus be 10 Angstrom of vacuum on each side.

axis: int or sequence of ints

Axis or axes to act on. Default: Act on all axes.

about: float or array (default: None)

If specified, center the atoms about <about>. I.e., about=(0., 0., 0.) (or just “about=0.”, interpreted identically), to center about the origin.

center_coordinates_in_unit_cell(origin=0, eps=0.0001)

Wrap atomic coordinates within the supercell.

Modifies object in place and returns itself.

Parameters:

• origin (float) – 0 to confine between 0 and 1, -0.5 to confine between -0.5 and 0.5

• eps (float) – Tolerance to detect atoms at cell edges

Returns:

reference to this structure

Return type:

pyiron_atomistics.atomistics.structure.atoms.Atoms

cluster_analysis(id_list, neighbors=None, radius=None, return_cluster_sizes=False)

Parameters:

• id_list

• neighbors

• radius

• return_cluster_sizes

Returns:

property constraints

Constraints.

convert_element(el, pse=None)

Convert a string or an atom instance into a ChemicalElement instance

Parameters:

• el (str/atomistics.structure.atom.Atom) – String or atom instance from which the element should be generated

• pse (atomistics.structure.periodictable.PeriodicTable) – PeriodicTable instance from which the element is generated (optional)

Returns:

The required chemical element

Return type:

atomistics.structure.periodictable.ChemicalElement

static convert_formula(elements)

Convert a given chemical formula into a list of elements

Parameters:

elements (str) – A string of the required chamical formula (eg. H2O)

Returns:

A list of elements corresponding to the formula

Return type:

list

copy()

Returns a copy of the instance

Returns:

A copy of the instance

Return type:

pyiron.atomistics.structure.atoms.Atoms

create_line_mode_structure(with_time_reversal=True, recipe='hpkot', threshold=1e-07, symprec=1e-05, angle_tolerance=-1.0)

Uses ‘seekpath’ to create a new structure with high symmetry points and path for band structure calculations.

Parameters:

• with_time_reversal (bool) – if False, and the group has no inversion symmetry, additional lines are returned as described in the HPKOT paper.

• recipe (str) – choose the reference publication that defines the special points and paths. Currently, only ‘hpkot’ is implemented.

• threshold (float) – the threshold to use to verify if we are in and edge case (e.g., a tetragonal cell, but a==c). For instance, in the tI lattice, if abs(a-c) < threshold, a EdgeCaseWarning is issued. Note that depending on the bravais lattice, the meaning of the threshold is different (angle, length, …)

• symprec (float) – the symmetry precision used internally by SPGLIB

• angle_tolerance (float) – the angle_tolerance used internally by SPGLIB

Returns:

new structure

Return type:

pyiron.atomistics.structure.atoms.Atoms

edit()

Modify atoms interactively through ASE’s GUI viewer.

Conflicts leading to undesirable behaviour might arise when matplotlib has been pre-imported with certain incompatible backends and while trying to use the plot feature inside the interactive GUI. To circumvent, please set matplotlib.use(‘gtk’) before calling this method.

property elements

A size N list of atomistics.structure.periodic_table.ChemicalElement instances according to the ordering of the atoms in the instance

Type:

numpy.ndarray

euler_rotate(phi: float = 0.0, theta: float = 0.0, psi: float = 0.0, center: Sequence[float] = (0.0, 0.0, 0.0)) → None

Rotate atoms via Euler angles (in degrees).

See e.g https://mathworld.wolfram.com/EulerAngles.html for explanation.

Note that the rotations in this method are passive and applied not to the atomic coordinates in the present frame but the frame itself.

Parameters:

• phi (float) – The 1st rotation angle around the z axis.

• theta (float) – Rotation around the x axis.

• psi (float) – 2nd rotation around the z axis.

• center (Sequence[float], default = (0.0, 0.0, 0.0)) – The point to rotate about. A sequence of length 3 with the coordinates, or ‘COM’ to select the center of mass, ‘COP’ to select center of positions or ‘COU’ to select center of cell.

extend(other)

Extend atoms object by appending atoms from other. (Extending the ASE function)

Parameters:

other (pyiron_atomistics.atomistics.structure.atoms.Atoms/ase.atoms.Atoms) – Structure to append

Returns:

The extended structure

Return type:

pyiron.atomistics.structure.atoms.Atoms

find_mic(v, vectors=True)

Find vectors following minimum image convention (mic). In principle this function does the same as ase.geometry.find_mic

Parameters:

• v (list/numpy.ndarray) – 3d vector or a list/array of 3d vectors

• vectors (bool) – Whether to return vectors (distances are returned if False)

Returns: numpy.ndarray of the same shape as input with mic

find_neighbors_by_vector(vector, return_deviation=False, num_neighbors=96)

Parameters:

• vector (list/np.ndarray) – vector by which positions are translated (and neighbors are searched)

• return_deviation (bool) – whether to return distance between the expect positions and real positions

Returns:

list of id’s for the specified translation

Return type:

np.ndarray

Example

a_0 = 2.832 structure = pr.create_structure(‘Fe’, ‘bcc’, a_0) id_list = structure.find_neighbors_by_vector([0, 0, a_0]) # In this example, you get a list of neighbor atom id’s at z+=a_0 for each atom. # This is particularly powerful for SSA when the magnetic structure has to be translated # in each direction.

from_hdf(hdf, group_name='structure')

Retrieve the object from a HDF5 file

Parameters:

• hdf (pyiron_base.generic.hdfio.FileHDFio) – HDF path to which the object is to be saved

• group_name (str) – Group name from which the Atoms object is retreived.

Returns:

The retrieved atoms class

Return type:

pyiron_atomistics.structure.atoms.Atoms

classmethod fromdict(dct)

Rebuild atoms object from dictionary representation (todict).

get_all_distances(mic=False, vector=False)

Return distances of all of the atoms with all of the atoms.

Use mic=True to use the Minimum Image Convention.

get_angle(a1, a2, a3, mic=False)

Get angle formed by three atoms.

Calculate angle in degrees between the vectors a2->a1 and a2->a3.

Use mic=True to use the Minimum Image Convention and calculate the angle across periodic boundaries.

get_angles(indices, mic=False)

Get angle formed by three atoms for multiple groupings.

Calculate angle in degrees between vectors between atoms a2->a1 and a2->a3, where a1, a2, and a3 are in each row of indices.

Use mic=True to use the Minimum Image Convention and calculate the angle across periodic boundaries.

get_angular_momentum()

Get total angular momentum with respect to the center of mass.

get_array(name, copy=True)

Get an array.

Returns a copy unless the optional argument copy is false.

get_atomic_numbers()

Returns the atomic numbers of all the atoms in the structure

Returns:

A list of atomic numbers

Return type:

numpy.ndarray

get_bonds(radius=inf, max_shells=None, prec=0.1, num_neighbors=20)

Parameters:

• radius

• max_shells

• prec – minimum distance between any two clusters (if smaller considered to be single cluster)

• num_neighbors

Returns:

get_calculator()

Get currently attached calculator object.

Deprecated since version 3.20.0: Please use the equivalent atoms.calc instead of atoms.get_calculator().

get_cell(complete=False)

Get the three unit cell vectors as a class:ase.cell.Cell` object.

The Cell object resembles a 3x3 ndarray, and cell[i, j] is the jth Cartesian coordinate of the ith cell vector.

get_cell_lengths_and_angles()

Get unit cell parameters. Sequence of 6 numbers.

First three are unit cell vector lengths and second three are angles between them:

[len(a), len(b), len(c), angle(b,c), angle(a,c), angle(a,b)]

in degrees.

Deprecated since version 3.21.0: Please use atoms.cell.cellpar() instead

get_celldisp()

Get the unit cell displacement vectors.

get_center_of_mass()

Returns:

center of mass in A

Return type:

com (float)

get_charges()

Get calculated charges.

get_chemical_elements()

Returns the list of chemical element instances

Returns:

A list of chemical element instances

Return type:

numpy.ndarray

get_chemical_formula()

Returns the chemical formula of structure

Returns:

The chemical formula as a string

Return type:

str

get_chemical_indices()

Returns the list of chemical indices as ordered in self.species

Returns:

A list of chemical indices

Return type:

numpy.ndarray

get_chemical_symbols()

Returns the chemical symbols for all the atoms in the structure

Returns:

A list of chemical symbols

Return type:

numpy.ndarray

get_density()

Returns the density in g/cm^3

Returns:

Density of the structure

Return type:

float

get_dihedral(a0, a1, a2, a3, mic=False)

Calculate dihedral angle.

Calculate dihedral angle (in degrees) between the vectors a0->a1 and a2->a3.

Use mic=True to use the Minimum Image Convention and calculate the angle across periodic boundaries.

get_dihedrals(indices, mic=False)

Calculate dihedral angles.

Calculate dihedral angles (in degrees) between the list of vectors a0->a1 and a2->a3, where a0, a1, a2 and a3 are in each row of indices.

Use mic=True to use the Minimum Image Convention and calculate the angles across periodic boundaries.

get_dipole_moment()

Calculate the electric dipole moment for the atoms object.

Only available for calculators which has a get_dipole_moment() method.

get_distance(a0, a1, mic=True, vector=False)

Return distance between two atoms. Use mic=True to use the Minimum Image Convention. vector=True gives the distance vector (from a0 to a1).

Parameters:

• a0 (int/numpy.ndarray/list) – position or atom ID

• a1 (int/numpy.ndarray/list) – position or atom ID

• mic (bool) – minimum image convention (True if periodic boundary conditions should be considered)

• vector (bool) – True, if instead of distnce the vector connecting the two positions should be returned

Returns:

distance or vectors in length unit

Return type:

float

get_distances(a, indices, mic=False, vector=False)

Return distances of atom No.i with a list of atoms.

Use mic=True to use the Minimum Image Convention. vector=True gives the distance vector (from a to self[indices]).

get_distances_array(p1=None, p2=None, mic=True, vectors=False)

Return distance matrix of every position in p1 with every position in p2. If p2 is not set, it is assumed that distances between all positions in p1 are desired. p2 will be set to p1 in this case. If both p1 and p2 are not set, the distances between all atoms in the box are returned.

Parameters:

• p1 (numpy.ndarray/list) – Nx3 array of positions

• p2 (numpy.ndarray/list) – Nx3 array of positions

• mic (bool) – minimum image convention

• vectors (bool) – return vectors instead of distances

Returns:

NxN if vector=False and NxNx3 if vector=True

Return type:

numpy.ndarray

get_equivalent_points(points, use_magmoms=False, use_elements=True, symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• points (list/ndarray) – 3d vector

• use_magmoms (bool) – cf. get_symmetry()

• use_elements (bool) – cf. get_symmetry()

• symprec (float) – cf. get_symmetry()

• angle_tolerance (float) – cf. get_symmetry()

Returns:

array of equivalent points with respect to box symmetries

Return type:

(ndarray)

get_extended_positions(width, return_indices=False, norm_order=2, positions=None)

Get all atoms in the boundary around the supercell which have a distance to the supercell boundary of less than dist

Parameters:

• width (float) – width of the buffer layer on every periodic box side within which all atoms across periodic boundaries are chosen.

• return_indices (bool) – Whether or not return the original indices of the appended atoms.

• norm_order (float) – Order of Lp-norm.

• positions (numpy.ndarray) – Positions for which the extended positions are returned. If None, the atom positions of the structure are used.

Returns:

Positions of all atoms in the extended box, indices of atoms in

their original option (if return_indices=True)

Return type:

numpy.ndarray

get_forces(apply_constraint=True, md=False)

Calculate atomic forces.

Ask the attached calculator to calculate the forces and apply constraints. Use apply_constraint=False to get the raw forces.

For molecular dynamics (md=True) we don’t apply the constraint to the forces but to the momenta. When holonomic constraints for rigid linear triatomic molecules are present, ask the constraints to redistribute the forces within each triple defined in the constraints (required for molecular dynamics with this type of constraints).

get_global_number_of_atoms()

Returns the global number of atoms in a distributed-atoms parallel simulation.

DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING!

Equivalent to len(atoms) in the standard ASE Atoms class. You should normally use len(atoms) instead. This function’s only purpose is to make compatibility between ASE and Asap easier to maintain by having a few places in ASE use this function instead. It is typically only when counting the global number of degrees of freedom or in similar situations.

get_high_symmetry_path()

Path used for band structure calculations

Returns:

dict of pathes with start and end points.

Return type:

dict

get_high_symmetry_points()

dictionary of high-symmetry points defined for this specific structure.

Returns:

high_symmetry_points

Return type:

dict

get_initial_charges()

Get array of initial charges.

get_initial_magnetic_moments()

Get array of initial magnetic moments.

Returns:

numpy.array()

get_ir_reciprocal_mesh(mesh, is_shift=array([0, 0, 0], dtype=int32), is_time_reversal=True, symprec=1e-05)

Parameters:

• mesh

• is_shift

• is_time_reversal

• symprec

Returns:

get_kinetic_energy()

Get the kinetic energy.

get_kinetic_stress(voigt=True)

Calculate the kinetic part of the Virial stress tensor.

get_kinetic_stresses(voigt=True)

Calculate the kinetic part of the Virial stress of all the atoms.

get_magnetic_moment()

Get calculated total magnetic moment.

get_magnetic_moments()

Get calculated local magnetic moments.

get_majority_species(return_count=False)

This function returns the majority species and their number in the box

Returns:

number of atoms of the majority species, chemical symbol and chemical index

get_masses()

Gets the atomic masses of all atoms in the structure

Returns:

Array of masses

Return type:

numpy.ndarray

get_masses_dof()

Returns:

get_momenta()

Get array of momenta.

get_moments_of_inertia(vectors=False)

Get the moments of inertia along the principal axes.

The three principal moments of inertia are computed from the eigenvalues of the symmetric inertial tensor. Note that the result can be “wrong” if a molecule is crossing periodic boundaries. Units of the moments of inertia are amu*angstrom**2.

Parameters:

vectors (bool) – If true, also return the principal axes as rows in a 3x3 matrix.

get_neighborhood(positions, num_neighbors=12, cutoff_radius=inf, width_buffer=1.2, mode='filled', norm_order=2)

Parameters:

• position – Position in a box whose neighborhood information is analysed

• num_neighbors (int) – Number of nearest neighbors

• cutoff_radius (float) – Upper bound of the distance to which the search is to be done

• width_buffer (float) – Width of the layer to be added to account for pbc.

• mode (str) – Representation of per-atom quantities (distances etc.). Choose from ‘filled’, ‘ragged’ and ‘flattened’.

• norm_order (int) – Norm to use for the neighborhood search and shell recognition. The definition follows the conventional Lp norm (cf. https://en.wikipedia.org/wiki/Lp_space). This is an feature and for anything other than norm_order=2, there is no guarantee that this works flawlessly.

Returns:

Neighbors instances with the neighbor

indices, distances and vectors

Return type:

pyiron.atomistics.structure.atoms.Tree

get_neighbors(num_neighbors=12, tolerance=2, id_list=None, cutoff_radius=inf, width_buffer=1.2, allow_ragged=None, mode='filled', norm_order=2)

Parameters:

• num_neighbors (int) – number of neighbors

• tolerance (int) – tolerance (round decimal points) used for computing neighbor shells

• id_list (list) – list of atoms the neighbors are to be looked for

• cutoff_radius (float) – Upper bound of the distance to which the search must be done

• width_buffer (float) – width of the layer to be added to account for pbc.

• allow_ragged (bool) – (Deprecated; use mode) Whether to allow ragged list of arrays or rectangular numpy.ndarray filled with np.inf for values outside cutoff_radius

• mode (str) – Representation of per-atom quantities (distances etc.). Choose from ‘filled’, ‘ragged’ and ‘flattened’.

• norm_order (int) – Norm to use for the neighborhood search and shell recognition. The definition follows the conventional Lp norm (cf. https://en.wikipedia.org/wiki/Lp_space). This is an feature and for anything other than norm_order=2, there is no guarantee that this works flawlessly.

Returns:

Neighbors instances with the neighbor

indices, distances and vectors

Return type:

structuretoolkit.analyse.neighbors.Neighbors

get_neighbors_by_distance(cutoff_radius=5, num_neighbors=None, tolerance=2, id_list=None, width_buffer=1.2, allow_ragged=None, mode='ragged', norm_order=2)

Parameters:

• num_neighbors (int) – number of neighbors

• tolerance (int) – tolerance (round decimal points) used for computing neighbor shells

• id_list (list) – list of atoms the neighbors are to be looked for

• cutoff_radius (float) – Upper bound of the distance to which the search must be done

• width_buffer (float) – width of the layer to be added to account for pbc.

• allow_ragged (bool) – (Deprecated; use mode) Whether to allow ragged list of arrays or rectangular numpy.ndarray filled with np.inf for values outside cutoff_radius

• mode (str) – Representation of per-atom quantities (distances etc.). Choose from ‘filled’, ‘ragged’ and ‘flattened’.

• norm_order (int) – Norm to use for the neighborhood search and shell recognition. The definition follows the conventional Lp norm (cf. https://en.wikipedia.org/wiki/Lp_space). This is an feature and for anything other than norm_order=2, there is no guarantee that this works flawlessly.

Returns:

Neighbors instances with the neighbor

indices, distances and vectors

Return type:

structuretoolkit.analyse.neighbors.Neighbors

get_number_of_atoms()

Returns:

get_number_of_degrees_of_freedom()

Returns:

get_number_of_species()

Returns:

get_number_species_atoms()

Returns a dictionary with the species in the structure and the corresponding count in the structure

Returns:

An ordered dictionary with the species and the corresponding count

Return type:

collections.OrderedDict

get_numbers_of_neighbors_in_sphere(cutoff_radius=10, num_neighbors=None, id_list=None, width_buffer=1.2)

Function to compute the maximum number of neighbors in a sphere around each atom. :param cutoff_radius: Upper bound of the distance to which the search must be done :type cutoff_radius: float :param num_neighbors: maximum number of neighbors found :type num_neighbors: int/None :param id_list: list of atoms the neighbors are to be looked for :type id_list: list :param width_buffer: width of the layer to be added to account for pbc. :type width_buffer: float

Returns:

for each atom the number of neighbors found in the sphere of radius

cutoff_radius (<= num_neighbors if specified)

Return type:

(np.ndarray)

get_parent_basis()

Returns the basis with all user defined/special elements as the it’s parent

Returns:

Structure without any user defined elements

Return type:

pyiron.atomistics.structure.atoms.Atoms

get_parent_symbols()

Returns the chemical symbols for all the atoms in the structure even for user defined elements

Returns:

A list of chemical symbols

Return type:

numpy.ndarray

get_pbc()

Get periodic boundary condition flags.

get_positions(wrap=False, **wrap_kw)

Get array of positions.

Parameters:

wrap: bool

wrap atoms back to the cell before returning positions

wrap_kw: (keyword=value) pairs

optional keywords pbc, center, pretty_translation, eps, see ase.geometry.wrap_positions()

get_potential_energies()

Calculate the potential energies of all the atoms.

Only available with calculators supporting per-atom energies (e.g. classical potentials).

get_potential_energy(force_consistent=False, apply_constraint=True)

Calculate potential energy.

Ask the attached calculator to calculate the potential energy and apply constraints. Use apply_constraint=False to get the raw forces.

When supported by the calculator, either the energy extrapolated to zero Kelvin or the energy consistent with the forces (the free energy) can be returned.

get_primitive_cell(symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• symprec

• angle_tolerance

Returns:

get_properties(properties)

This method is experimental; currently for internal use.

get_reciprocal_cell()

Get the three reciprocal lattice vectors as a 3x3 ndarray.

Note that the commonly used factor of 2 pi for Fourier transforms is not included here.

Deprecated since version 3.21.0: Please use atoms.cell.reciprocal()

get_scaled_positions(wrap=True)

Get positions relative to unit cell.

If wrap is True, atoms outside the unit cell will be wrapped into the cell in those directions with periodic boundary conditions so that the scaled coordinates are between zero and one.

If any cell vectors are zero, the corresponding coordinates are evaluated as if the cell were completed using cell.complete(). This means coordinates will be Cartesian as long as the non-zero cell vectors span a Cartesian axis or plane.

get_shell_matrix(id_list=None, chemical_pair=None, num_neighbors=100, tolerance=2, cluster_by_distances=False, cluster_by_vecs=False)

Shell matrices for pairwise interaction. Note: The matrices are always symmetric, meaning if you use them as bilinear operators, you have to divide the results by 2.

Parameters:

chemical_pair (list) – pair of chemical symbols (e.g. [‘Fe’, ‘Ni’])

Returns:

list of sparse matrices for different shells

Example

from pyiron_atomistics import Project structure = Project(‘.’).create_structure(‘Fe’, ‘bcc’, 2.83).repeat(2) J = -0.1 # Ising parameter magmoms = 2*np.random.random((len(structure)), 3)-1 # Random magnetic moments between -1 and 1 neigh = structure.get_neighbors(num_neighbors=8) # Iron first shell shell_matrices = neigh.get_shell_matrix() print(‘Energy =’, 0.5*J*magmoms.dot(shell_matrices[0].dot(matmoms)))

get_spacegroup(symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• symprec

• angle_tolerance

Returns:

https://atztogo.github.io/spglib/python-spglib.html

get_species_objects()

Returns:

get_species_symbols()

Returns the symbols of the present species

Returns:

List of the symbols of the species

Return type:

numpy.ndarray

get_spherical_coordinates(x=None)

Parameters:

x (list/ndarray) – coordinates to transform. If not set, the positions in structure will be returned.

Returns:

array in spherical coordinates

get_stress(voigt=True, apply_constraint=True, include_ideal_gas=False)

Calculate stress tensor.

Returns an array of the six independent components of the symmetric stress tensor, in the traditional Voigt order (xx, yy, zz, yz, xz, xy) or as a 3x3 matrix. Default is Voigt order.

The ideal gas contribution to the stresses is added if the atoms have momenta and include_ideal_gas is set to True.

get_stresses(include_ideal_gas=False, voigt=True)

Calculate the stress-tensor of all the atoms.

Only available with calculators supporting per-atom energies and stresses (e.g. classical potentials). Even for such calculators there is a certain arbitrariness in defining per-atom stresses.

The ideal gas contribution to the stresses is added if the atoms have momenta and include_ideal_gas is set to True.

get_symmetry(use_magmoms=False, use_elements=True, symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• use_magmoms (bool) – Whether to consider magnetic moments (cf.

• get_initial_magnetic_moments

• use_elements (bool) – If False, chemical elements will be ignored

• symprec (float) – Symmetry search precision

• angle_tolerance (float) – Angle search tolerance

Returns:

Symmetry class

Return type:

symmetry (pyiron.atomistics.structure.symmetry.Symmetry)

get_symmetry_dataset(symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• symprec

• angle_tolerance

Returns:

https://atztogo.github.io/spglib/python-spglib.html

get_tags()

Returns the keys of the stored tags of the structure

Returns:

Keys of the stored tags

Return type:

dict_keys

get_temperature()

Get the temperature in Kelvin.

get_total_energy()

Get the total energy - potential plus kinetic energy.

get_velocities()

Get array of velocities.

get_vertical_length(norm_order=2)

Return the length of the cell in each direction projected on the vector vertical to the plane.

Example:

For a cell [[1, 1, 0], [0, 1, 0], [0, 0, 1]], this function returns [1., 0.70710678, 1.] because the first cell vector is projected on the vector vertical to the yz-plane (as well as the y component on the xz-plane).

Parameters:

norm_order (int) – Norm order (cf. numpy.linalg.norm)

get_volume(per_atom=False)

Parameters:

per_atom (bool) – True if volume per atom is to be returned

Returns:

Volume in A**3

Return type:

volume (float)

get_voronoi_volume()

Calculate the Voronoi volume of atoms

get_wrapped_coordinates(positions, epsilon=1e-08)

Return coordinates in wrapped in the periodic cell

Parameters:

• positions (list/numpy.ndarray) – Positions

• epsilon (float) – displacement to add to avoid wrapping of atoms at borders

Returns:

Wrapped positions

Return type:

numpy.ndarray

group_points_by_symmetry(points, use_magmoms=False, use_elements=True, symprec=1e-05, angle_tolerance=-1.0)

This function classifies the points into groups according to the box symmetry given by spglib.

Parameters:

• points – (np.array/list) nx3 array which contains positions

• use_magmoms (bool) – Whether to consider magnetic moments (cf.

• get_initial_magnetic_moments

• use_elements (bool) – If False, chemical elements will be ignored

• symprec (float) – Symmetry search precision

• angle_tolerance (float) – Angle search tolerance

Returns: list of arrays containing geometrically equivalent positions

It is possible that the original points are not found in the returned list, as the positions outsie the box will be projected back to the box.

has(name)

Check for existence of array.

name must be one of: ‘tags’, ‘momenta’, ‘masses’, ‘initial_magmoms’, ‘initial_charges’.

is_skewed(tolerance=1e-08)

Check whether the simulation box is skewed/sheared. The algorithm compares the box volume and the product of the box length in each direction. If these numbers do not match, the box is considered to be skewed and the function returns True

Parameters:

tolerance (float) – Relative tolerance above which the structure is considered as skewed

Returns:

Whether the box is skewed or not.

Return type:

(bool)

new_array(name, a, dtype=None, shape=None)

Add new array.

If shape is not None, the shape of a will be checked.

property number_of_lattice_vectors

Number of (non-zero) lattice vectors.

Deprecated since version 3.21.0: Please use atoms.cell.rank instead

property numbers

Attribute for direct manipulation of the atomic numbers.

numbers_to_elements(numbers)

Convert atomic numbers in element objects (needed for compatibility with ASE)

Parameters:

numbers (list) – List of Element Numbers (as Integers; default in ASE)

Returns:

A list of elements as needed for pyiron

Return type:

list

occupy_lattice(**qwargs)

Replaces specified indices with a given species

property pbc

Reference to pbc-flags for in-place manipulations.

plot3d(mode='NGLview', show_cell=True, show_axes=True, camera='orthographic', spacefill=True, particle_size=1.0, select_atoms=None, background='white', color_scheme=None, colors=None, scalar_field=None, scalar_start=None, scalar_end=None, scalar_cmap=None, vector_field=None, vector_color=None, magnetic_moments=False, view_plane=array([0, 0, 1]), distance_from_camera=1.0, opacity=1.0, height=None)

Plot3d relies on NGLView or plotly to visualize atomic structures. Here, we construct a string in the “protein database”

The final widget is returned. If it is assigned to a variable, the visualization is suppressed until that variable is evaluated, and in the meantime more NGL operations can be applied to it to modify the visualization.

Parameters:

• mode (str) – NGLView, plotly or ase

• show_cell (bool) – Whether or not to show the frame. (Default is True.)

• show_axes (bool) – Whether or not to show xyz axes. (Default is True.)

• camera (str) – ‘perspective’ or ‘orthographic’. (Default is ‘perspective’.)

• spacefill (bool) – Whether to use a space-filling or ball-and-stick representation. (Default is True, use space-filling atoms.)

• particle_size (float) – Size of the particles. (Default is 1.)

• select_atoms (numpy.ndarray) – Indices of atoms to show, either as integers or a boolean array mask. (Default is None, show all atoms.)

• background (str) – Background color. (Default is ‘white’.)

• color_scheme (str) – NGLView color scheme to use. (Default is None, color by element.)

• colors (numpy.ndarray) – A per-atom array of HTML color names or hex color codes to use for atomic colors. (Default is None, use coloring scheme.)

• scalar_field (numpy.ndarray) – Color each atom according to the array value (Default is None, use coloring scheme.)

• scalar_start (float) – The scalar value to be mapped onto the low end of the color map (lower values are clipped). (Default is None, use the minimum value in scalar_field.)

• scalar_end (float) – The scalar value to be mapped onto the high end of the color map (higher values are clipped). (Default is None, use the maximum value in scalar_field.)

• scalar_cmap (matplotlib.cm) – The colormap to use. (Default is None, giving a blue-red divergent map.)

• vector_field (numpy.ndarray) – Add vectors (3 values) originating at each atom. (Default is None, no vectors.)

• vector_color (numpy.ndarray) – Colors for the vectors (only available with vector_field). (Default is None, vectors are colored by their direction.)

• magnetic_moments (bool) – Plot magnetic moments as ‘scalar_field’ or ‘vector_field’.

• view_plane (numpy.ndarray) – A Nx3-array (N = 1,2,3); the first 3d-component of the array specifies which plane of the system to view (for example, [1, 0, 0], [1, 1, 0] or the [1, 1, 1] planes), the second 3d-component (if specified, otherwise [1, 0, 0]) gives the horizontal direction, and the third component (if specified) is the vertical component, which is ignored and calculated internally. The orthonormality of the orientation is internally ensured, and therefore is not required in the function call. (Default is np.array([0, 0, 1]), which is view normal to the x-y plane.)

• distance_from_camera (float) – Distance of the camera from the structure. Higher = farther away. (Default is 14, which also seems to be the NGLView default value.)

• height (int/float/None) – height of the plot area in pixel (only available in plotly) Default: 600

• schemes (Possible NGLView color) – ” “, “picking”, “random”, “uniform”, “atomindex”, “residueindex”, “chainindex”, “modelindex”, “sstruc”, “element”, “resname”, “bfactor”, “hydrophobicity”, “value”, “volume”, “occupancy”

Returns:

The NGLView widget itself, which can be operated on further or viewed as-is.

Return type:

(nglview.NGLWidget)

Warning

• Many features only work with space-filling atoms (e.g. coloring by a scalar field).

• The colour interpretation of some hex codes is weird, e.g. ‘green’.

pop(i=-1)

Remove and return atom at index i (default last).

pos_xyz()

Returns:

property positions

Attribute for direct manipulation of the positions.

rattle(stdev=0.001, seed=None, rng=None)

Randomly displace atoms.

This method adds random displacements to the atomic positions, taking a possible constraint into account. The random numbers are drawn from a normal distribution of standard deviation stdev.

By default, the random number generator always uses the same seed (42) for repeatability. You can provide your own seed (an integer), or if you want the randomness to be different each time you run a script, then provide rng=numpy.random. For a parallel calculation, it is important to use the same seed on all processors!

refine_cell(symprec=1e-05, angle_tolerance=-1.0)

Parameters:

• symprec

• angle_tolerance

Returns:

https://atztogo.github.io/spglib/python-spglib.html

repeat(rep)

Create new repeated atoms object.

The rep argument should be a sequence of three positive integers like (2,3,1) or a single integer (r) equivalent to (r,r,r).

repeat_points(points, rep, centered=False)

Return points with repetition given according to periodic boundary conditions

Parameters:

• points (np.ndarray/list) – xyz vector or list/array of xyz vectors

• rep (int/list/np.ndarray) – Repetition in each direction. If int is given, the same value is used for every direction

• centered (bool) – Whether the original points should be in the center of repeated points.

Returns:

(np.ndarray) repeated points

rotate(a=0.0, v=None, center=(0, 0, 0), rotate_cell=False, index_list=None)

Rotate atoms based on a vector and an angle, or two vectors. This function is completely adopted from ASE code (https://wiki.fysik.dtu.dk/ase/_modules/ase/atoms.html#Atoms.rotate)

Parameters:

• a (float/list) – Angle that the atoms is rotated around the vecor ‘v’. If an angle is not specified, the length of ‘v’ is used as the angle (default). The angle can also be a vector and then ‘v’ is rotated into ‘a’.

• v (list/numpy.ndarray/string) – Vector to rotate the atoms around. Vectors can be given as strings: ‘x’, ‘-x’, ‘y’, … .

• center (tuple/list/numpy.ndarray/str) – The center is kept fixed under the rotation. Use ‘COM’ to fix the center of mass, ‘COP’ to fix the center of positions or ‘COU’ to fix the center of cell.

• False (rotate_cell =) – If true the cell is also rotated.

• index_list (list/numpy.ndarray) – Indices of atoms to be rotated

Examples:

Rotate 90 degrees around the z-axis, so that the x-axis is rotated into the y-axis:

>>> atoms = Atoms()
>>> atoms.rotate(90, 'z')
>>> atoms.rotate(90, (0, 0, 1))
>>> atoms.rotate(-90, '-z')
>>> atoms.rotate('x', 'y')
>>> atoms.rotate((1, 0, 0), (0, 1, 0))

rotate_dihedral(a1, a2, a3, a4, angle, mask=None, indices=None)

Rotate dihedral angle.

Same usage as in ase.Atoms.set_dihedral(): Rotate a group by a predefined dihedral angle, starting from its current configuration.

scaled_pos_xyz()

Returns:

select_index(el)

Returns the indices of a given element in the structure

Parameters:

el (str/atomistics.structures.periodic_table.ChemicalElement/list) – Element for which the indices should be returned

Returns:

An array of indices of the atoms of the given element

Return type:

numpy.ndarray

select_parent_index(el)

Returns the indices of a given element in the structure ignoring user defined elements

Parameters:

el (str/atomistics.structures.periodic_table.ChemicalElement) – Element for which the indices should be returned

Returns:

An array of indices of the atoms of the given element

Return type:

numpy.ndarray

set_angle(a1, a2=None, a3=None, angle=None, mask=None, indices=None, add=False)

Set angle (in degrees) formed by three atoms.

Sets the angle between vectors a2->*a1* and a2->*a3*.

If add is True, the angle will be changed by the value given.

Same usage as in ase.Atoms.set_dihedral(). If mask and indices are given, indices overwrites mask. If mask and indices are not set, only a3 is moved.

set_array(name, a, dtype=None, shape=None)

Update array.

If shape is not None, the shape of a will be checked. If a is None, then the array is deleted.

set_atomic_numbers(numbers)

Set atomic numbers.

set_calculator(calc=None)

Attach calculator object.

Deprecated since version 3.20.0: Please use the equivalent atoms.calc = calc instead of this method.

set_cell(cell, scale_atoms=False, apply_constraint=True)

Set unit cell vectors.

Parameters:

cell: 3x3 matrix or length 3 or 6 vector

Unit cell. A 3x3 matrix (the three unit cell vectors) or just three numbers for an orthorhombic cell. Another option is 6 numbers, which describes unit cell with lengths of unit cell vectors and with angles between them (in degrees), in following order: [len(a), len(b), len(c), angle(b,c), angle(a,c), angle(a,b)]. First vector will lie in x-direction, second in xy-plane, and the third one in z-positive subspace.

scale_atoms: bool

Fix atomic positions or move atoms with the unit cell? Default behavior is to not move the atoms (scale_atoms=False).

apply_constraint: bool

Whether to apply constraints to the given cell.

Examples:

Two equivalent ways to define an orthorhombic cell:

>>> atoms = Atoms('He')
>>> a, b, c = 7, 7.5, 8
>>> atoms.set_cell([a, b, c])
>>> atoms.set_cell([(a, 0, 0), (0, b, 0), (0, 0, c)])

FCC unit cell:

>>> atoms.set_cell([(0, b, b), (b, 0, b), (b, b, 0)])

Hexagonal unit cell:

>>> atoms.set_cell([a, a, c, 90, 90, 120])

Rhombohedral unit cell:

>>> alpha = 77
>>> atoms.set_cell([a, a, a, alpha, alpha, alpha])

set_celldisp(celldisp)

Set the unit cell displacement vectors.

set_center_of_mass(com, scaled=False)

Set the center of mass.

If scaled=True the center of mass is expected in scaled coordinates. Constraints are considered for scaled=False.

set_chemical_symbols(symbols)

Set chemical symbols.

set_constraint(constraint=None)

Apply one or more constrains.

The constraint argument must be one constraint object or a list of constraint objects.

set_dihedral(a1, a2, a3, a4, angle, mask=None, indices=None)

Set the dihedral angle (degrees) between vectors a1->a2 and a3->a4 by changing the atom indexed by a4.

If mask is not None, all the atoms described in mask (read: the entire subgroup) are moved. Alternatively to the mask, the indices of the atoms to be rotated can be supplied. If both mask and indices are given, indices overwrites mask.

Important: If mask or indices is given and does not contain a4, a4 will NOT be moved. In most cases you therefore want to include a4 in mask/indices.

Example: the following defines a very crude ethane-like molecule and twists one half of it by 30 degrees.

>>> atoms = Atoms('HHCCHH', [[-1, 1, 0], [-1, -1, 0], [0, 0, 0],
...                          [1, 0, 0], [2, 1, 0], [2, -1, 0]])
>>> atoms.set_dihedral(1, 2, 3, 4, 210, mask=[0, 0, 0, 1, 1, 1])

set_distance(a0, a1, distance, fix=0.5, mic=False, mask=None, indices=None, add=False, factor=False)

Set the distance between two atoms.

Set the distance between atoms a0 and a1 to distance. By default, the center of the two atoms will be fixed. Use fix=0 to fix the first atom, fix=1 to fix the second atom and fix=0.5 (default) to fix the center of the bond.

If mask or indices are set (mask overwrites indices), only the atoms defined there are moved (see ase.Atoms.set_dihedral()).

When add is true, the distance is changed by the value given. In combination with factor True, the value given is a factor scaling the distance.

It is assumed that the atoms in mask/indices move together with a1. If fix=1, only a0 will therefore be moved.

set_initial_charges(charges=None)

Set the initial charges.

set_initial_magnetic_moments(magmoms=None)

Set array of initial magnetic moments.

Parameters:

magmoms (None/numpy.ndarray/list/dict/float) – Default value is None (non magnetic calc). List, dict or single value assigning magnetic moments to the structure object.

Non-collinear calculations may be specified through using a dict/list (see last example)

If you want to make it non-magnetic, set None >>> structure.set_initial_magnetic_moments(None)

Example I input: np.ndarray / List Assigns site moments via corresponding list of same length as number of sites in structure >>> from pyiron_atomistics import Project >>> structure = Project(‘.’).create.structure.bulk(‘Ni’, cubic=True) >>> structure[-1] = ‘Fe’ >>> spin_list = [1, 2, 3, 4] >>> structure.set_initial_magnetic_moments(spin_list) >>> structure.get_initial_magnetic_moments() array([1, 2, 3, 4])

Example II input: dict Assigns species-specific magnetic moments >>> from pyiron_atomistics import Project >>> structure = Project(‘.’).create.structure.bulk(‘Ni’, cubic=True) >>> structure[-1] = ‘Fe’ >>> spin_dict = {‘Fe’: 1, ‘Ni’: 2} >>> structure.set_initial_magnetic_moments(spin_dict) >>> structure.get_initial_magnetic_moments() array([2, 2, 2, 1])

Example III input: float Assigns the same magnetic moment to all sites in the structure >>> from pyiron_atomistics import Project >>> structure = Project(‘.’).create.structure.bulk(‘Ni’, cubic=True) >>> structure[-1] = ‘Fe’ >>> structure.set_initial_magnetic_moments(1) >>> print(structure.get_initial_magnetic_moments()) array([1, 1, 1, 1])

Example IV input: dict/list for non-collinear magmoms. Assigns non-collinear magnetic moments to the sites in structure >>> from pyiron_atomistics import Project >>> structure = Project(‘.’).create.structure.bulk(‘Ni’, cubic=True) >>> structure[-1] = ‘Fe’

Option 1: List input sets vectors for each individual site >>> non_coll_magmom_vect = [[1, 2, 3]

[2, 3, 4], [3, 4, 5], [4, 5, 6]]

>>> structure.set_initial_magnetic_moments(non_coll_magmom_vect)
>>> print(structure.get_initial_magnetic_moments())
array([[1, 2, 3], [2, 3, 4], [3, 4, 5], [4, 5, 6]])

Option 2: Dict input sets magmom vectors for individual species: >>> print(structure.get_initial_magnetic_moments()) >>> non_coll_spin_dict = {‘Fe’: [2, 3, 4], ‘Ni’: [1, 2, 3]} >>> structure.set_initial_magnetic_moments(non_coll_spin_dict) >>> print(structure.get_initial_magnetic_moments()) array([[1, 2, 3], [1, 2, 3], [1, 2, 3], [2, 3, 4]])

set_masses(masses='defaults')

Set atomic masses in atomic mass units.

The array masses should contain a list of masses. In case the masses argument is not given or for those elements of the masses list that are None, standard values are set.

set_momenta(momenta, apply_constraint=True)

Set momenta.

set_pbc(pbc)

Set periodic boundary condition flags.

set_positions(newpositions, apply_constraint=True)

Set positions, honoring any constraints. To ignore constraints, use apply_constraint=False.

set_scaled_positions(scaled)

Set positions relative to unit cell.

set_species(value)

Setting the species list

Parameters:

value (list) – A list atomistics.structure.periodic_table.ChemicalElement instances

set_tags(tags)

Set tags for all atoms. If only one tag is supplied, it is applied to all atoms.

set_velocities(velocities)

Set the momenta by specifying the velocities.

property species

A list of atomistics.structure.periodic_table.ChemicalElement instances

Type:

list

property spins

Magnetic spins for each atom in the structure

Returns:

The magnetic moments for reach atom as a single value or a vector (non-collinear spins)

Return type:

numpy.ndarray/list

property symbols

Get chemical symbols as a ase.symbols.Symbols object.

The object works like atoms.numbers except its values are strings. It supports in-place editing.

symmetrize_vectors(vectors, use_magmoms=False, use_elements=True, symprec=1e-05, angle_tolerance=-1.0)

Symmetrization of natom x 3 vectors according to box symmetries

Parameters:

• vectors (ndarray/list) – natom x 3 array to symmetrize

• use_magmoms (bool) – cf. get_symmetry

• use_elements (bool) – cf. get_symmetry

• symprec (float) – cf. get_symmetry

• angle_tolerance (float) – cf. get_symmetry

Returns:

(np.ndarray) symmetrized vectors

to_hdf(hdf, group_name='structure')

Save the object in a HDF5 file

Parameters:

• hdf (pyiron_base.generic.hdfio.FileHDFio) – HDF path to which the object is to be saved

• group_name (str) – Group name with which the object should be stored. This same name should be used to retrieve the object

todict()

For basic JSON (non-database) support.

translate(displacement)

Translate atomic positions.

The displacement argument can be a float an xyz vector or an nx3 array (where n is the number of atoms).

wrap(**wrap_kw)

Wrap positions to unit cell.

Parameters:

wrap_kw: (keyword=value) pairs

optional keywords pbc, center, pretty_translation, eps, see ase.geometry.wrap_positions()

write(filename, format=None, **kwargs)

Write atoms object to a file.

see ase.io.write for formats. kwargs are passed to ase.io.write.