matscipy.opls

Functions

twochar(name)

Ensures that the particle names have a length of exactly two characters.

Classes

`AnglesData`([name_value_hash])	Store spring constants and equilibrium angles for harmonic potentials and ensure correct handling of permutations.
`BondData`([name_value_hash])	Store spring constants and equilibrium distances for harmonic potentials and ensure correct handling of permutations.
`CutoffList`([name_value_hash])	Store cutoffs for pair interactions and ensure correct handling of permutations.
`DihedralsData`([name_value_hash])	Store energy constants for dihedral potentials and ensure correct handling of permutations.
`LJQData`(args)	Store Lennard-Jones parameters and charges for each particle type.
`OPLSStructure`(args, *kwargs)	Extension of the `ase.Atoms` class for non-reactive simulations.

matscipy.opls.twochar(name)

Ensures that the particle names have a length of exactly two characters.

Parameters:: name (str) – Particle name.
Returns:: Particle name with exactly 2 characters.
Return type:: str

class matscipy.opls.LJQData(args)

Bases: dict

Store Lennard-Jones parameters and charges for each particle type. In the simplest version, each particle type has one set of Lennard-Jones parameters, with geometric mixing applied between parameters of different types. Parameters for individual pairs of particle types can be specified in the lj_pairs dictionary.

Example: Set the Lennard-Jones and Coulomb cutoffs to 12 and 8 Angstroms, geometric mixing of the Lennard-Jones parameters for particles C1 and C2 and between C2 and C3, custom parameters and cutoff for the interaction between C1 and C3:

LJQData.lj_cutoff = 12.0
LJQData.c_cutoff  =  8.0

LJQData['C1'] = [LJ-epsilon (eV), LJ-sigma (A), charge (e)]
LJQData['C2'] = [LJ-epsilon (eV), LJ-sigma (A), charge (e)]
LJQData['C3'] = [LJ-epsilon (eV), LJ-sigma (A), charge (e)]

LJQData.lj_pairs['C1-C3'] = [epsilon (eV), sigma (A), cutoff (A)]

Methods

`clear`()
`copy`()
`fromkeys`(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`(/)	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()

__init__(args)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(iterable, value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(key, default=<unrepresentable>, /): If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(/)

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class matscipy.opls.BondData(name_value_hash=None)

Bases: object

Store spring constants and equilibrium distances for harmonic potentials and ensure correct handling of permutations. See documentation of the LAMMPS bond_style harmonic command for details.

Methods

`get_name`(aname, bname)	Returns the name of the bond type between two particle types as it is defined internally.
`get_value`(aname, bname)	Returns the potential parameters for a bond between two particles of type `aname` and `bname`, i.e. the spring constant and the equilibrium distance.
`name_value`(aname, bname)	Returns the name of a bond type between two particles of type `aname` and `bname` as stored internally and the corresponding potential parameters, i.e. the spring constant and the equilibrium distance.
`set_names`(names)	Create a list of participating particles from a list of bond types.

__init__(name_value_hash=None)

Parameters:

name_value_hash (dict, optional) –

Bond names and corresponding potential parameters, e.g.

{'AA-BB': [10., 1.], 'AA-CC': [20., 2.], ...}.

set_names(names)

Create a list of participating particles from a list of bond types.

Parameters:

names (list) –

List of bond type names, e.g.

['AA-BB', 'AA-CC', ...]

get_name(aname, bname)

Returns the name of the bond type between two particle types as it is defined internally. If one particle is named AA and the other is named BB, the bond type between them could be either AA-BB or BB-AA. The parameters would be the same and are stored only once.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

Bond-name, either aname-bname or bname-aname.

Return type:

str

name_value(aname, bname)

Returns the name of a bond type between two particles of type aname and bname as stored internally and the corresponding potential parameters, i.e. the spring constant and the equilibrium distance.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

name (str) – Bond-name, either aname-bname or bname-aname.
parameters (list) – Potential parameters, i.e. spring constant and equilibrium distance.

get_value(aname, bname)

Returns the potential parameters for a bond between two particles of type aname and bname, i.e. the spring constant and the equilibrium distance.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

Potential parameters, i.e. spring constant and equilibrium distance.

Return type:

list

class matscipy.opls.CutoffList(name_value_hash=None)

Bases: BondData

Store cutoffs for pair interactions and ensure correct handling of permutations. Cutoffs can be used to automatically find all interacting atoms of a matscipy.opls.OPLSStructure object based on a simple distance criterion.

Methods

`get_name`(aname, bname)	Returns the name of the bond type between two particle types as it is defined internally.
`get_value`(aname, bname)	Returns the potential parameters for a bond between two particles of type `aname` and `bname`, i.e. the spring constant and the equilibrium distance.
`name_value`(aname, bname)	Returns the name of a bond type between two particles of type `aname` and `bname` as stored internally and the corresponding potential parameters, i.e. the spring constant and the equilibrium distance.
`set_names`(names)	Create a list of participating particles from a list of bond types.

max

max()

__init__(name_value_hash=None)

Parameters:

name_value_hash (dict, optional) –

Bond names and corresponding potential parameters, e.g.

{'AA-BB': [10., 1.], 'AA-CC': [20., 2.], ...}.

get_name(aname, bname)

Returns the name of the bond type between two particle types as it is defined internally. If one particle is named AA and the other is named BB, the bond type between them could be either AA-BB or BB-AA. The parameters would be the same and are stored only once.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

Bond-name, either aname-bname or bname-aname.

Return type:

str

get_value(aname, bname)

Returns the potential parameters for a bond between two particles of type aname and bname, i.e. the spring constant and the equilibrium distance.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

Potential parameters, i.e. spring constant and equilibrium distance.

Return type:

list

name_value(aname, bname)

Returns the name of a bond type between two particles of type aname and bname as stored internally and the corresponding potential parameters, i.e. the spring constant and the equilibrium distance.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.

Returns:

name (str) – Bond-name, either aname-bname or bname-aname.
parameters (list) – Potential parameters, i.e. spring constant and equilibrium distance.

set_names(names)

Create a list of participating particles from a list of bond types.

Parameters:

names (list) –

List of bond type names, e.g.

['AA-BB', 'AA-CC', ...]

class matscipy.opls.AnglesData(name_value_hash=None)

Bases: object

Store spring constants and equilibrium angles for harmonic potentials and ensure correct handling of permutations. See documentation of the LAMMPS angle_style harmonic command for details.

Methods

`add_name`(aname, bname, cname)	Add an angle type to the internal list if not already present.
`get_name`(aname, bname, cname)	Returns the name of the angle type between three particle types as it is defined internally.
`name_value`(aname, bname, cname)	Returns the name of an angle type between three particles of type `aname`, `bname` and `cname` as stored internally and the corresponding potential parameters.
`set_names`(names)	Create a list of participating particles from a list of angle types.

__init__(name_value_hash=None)

Parameters:

name_value_hash (dict, optional) –

Angle names and corresponding potential parameters, e.g.

{'AA-BB-CC': [10., 1.], 'AA-CC-BB': [20., 2.], ...}

set_names(names)

Create a list of participating particles from a list of angle types.

Parameters:

names (list) –

List of angle type names, e.g.

['AA-BB-CC', 'AA-CC-BB', ...]

add_name(aname, bname, cname)

Add an angle type to the internal list if not already present.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.

get_name(aname, bname, cname)

Returns the name of the angle type between three particle types as it is defined internally. If the particles are named AA, BB, CC, the angle type could be AA-BB-CC or CC-BB-AA. The parameters would be the same and are stored only once.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.

Returns:

Angle-name, either aname-bname-cname or cname-bname-aname.

Return type:

str

name_value(aname, bname, cname)

Returns the name of an angle type between three particles of type aname, bname and cname as stored internally and the corresponding potential parameters.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.

Returns:

name (str) – Angle-name, either aname-bname-cname or cname-bname-aname.
parameters (list) – Potential parameters.

class matscipy.opls.DihedralsData(name_value_hash=None)

Bases: object

Store energy constants for dihedral potentials and ensure correct handling of permutations. See documentation of the LAMMPS dihedral_style opls command for details.

Methods

`add_name`(aname, bname, cname, dname)	Add a dihedral type to the internal list if not already present.
`get_name`(aname, bname, cname, dname)	Add a dihedral type to the internal list if not already present.
`name_value`(aname, bname, cname, dname)	Returns the name of a dihedral type between four particles of type `aname`, `bname`, `cname` and `dname` as stored internally and the corresponding potential parameters.
`set_names`(names)	Create a list of participating particles from a list of dihedral types.

__init__(name_value_hash=None)

Parameters:

name_value_hash (dict, optional) –

Dihedral names and corresponding potential parameters, e.g.

{'AA-BB-CC-DD': [1., 1., 1., 1.],
 'AA-BB-AA-BB': [2., 2., 2., 2.], ...}

set_names(names)

Create a list of participating particles from a list of dihedral types.

Parameters:

names (list) –

List of dihedral type names, e.g.

['AA-BB-CC-DD', 'AA-BB-AA-BB', ...]

add_name(aname, bname, cname, dname)

Add a dihedral type to the internal list if not already present.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.
dname (str) – Name of fourth particle.

get_name(aname, bname, cname, dname)

Add a dihedral type to the internal list if not already present.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.
dname (str) – Name of fourth particle.

name_value(aname, bname, cname, dname)

Returns the name of a dihedral type between four particles of type aname, bname, cname and dname as stored internally and the corresponding potential parameters.

Parameters:

aname (str) – Name of first particle.
bname (str) – Name of second particle.
cname (str) – Name of third particle.
dname (str) – Name of fourth particle.

Returns:

name (str) – Angle-name, either aname-bname-cname-dname or dname-cname-bname-aname.
parameters (list) – Potential parameters.

class matscipy.opls.OPLSStructure(*args, **kwargs)

Bases: Atoms

Extension of the ase.Atoms class for non-reactive simulations.

Attributes:

calc: Calculator object.
cell: The ase.cell.Cell for direct manipulation.
constraints: Constraints of the atoms.
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.
symbols: Get chemical symbols as a ase.symbols.Symbols object.

Methods

`append`(atom)	Append atom to the end.
`center`([vacuum, axis, about])	Center atoms in unit cell.
`copy`()	Return a copy.
`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.
`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`([angles])	Returns an array of all angle types and an array of all angles in the system.
`get_angular_momentum`()	Get total angular momentum with respect to the center of mass.
`get_array`(name[, copy])	Get an array.
`get_atomic_numbers`()	Get integer array of atomic numbers.
`get_bonds`([bonds])	Returns an array of all bond types and an array of all bonds in the system.
`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`([scaled, indices])	Get the center of mass.
`get_charges`()	Return an array of atomic charges.
`get_chemical_formula`([mode, empirical])	Get the chemical formula as a string based on the chemical symbols.
`get_chemical_symbols`()	Get list of chemical symbol strings.
`get_dihedral`(a0, a1, a2, a3[, mic])	Calculate dihedral angle.
`get_dihedrals`([dihedrals, full_output])	Returns an array of all dihedral types and an array of all dihedrals in the system.
`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_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_initial_charges`()	Get array of initial charges.
`get_initial_magnetic_moments`()	Get array of initial magnetic moments.
`get_kinetic_energy`()	Get the kinetic energy.
`get_magnetic_moment`()	Get calculated total magnetic moment.
`get_magnetic_moments`()	Get calculated local magnetic moments.
`get_masses`()	Get array of masses in atomic mass units.
`get_momenta`()	Get array of momenta.
`get_moments_of_inertia`([vectors])	Get the moments of inertia along the principal axes.
`get_neighbors`()	Find all atoms which might interact with each other based on a simple distance criterion.
`get_number_of_atoms`()
`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_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_stress`([voigt, apply_constraint, ...])	Calculate stress tensor.
`get_stresses`([include_ideal_gas, voigt])	Calculate the stress-tensor of all the atoms.
`get_tags`()	Get integer array of tags.
`get_temperature`()	Get the temperature in Kelvin.
`get_total_energy`()	Get the total energy - potential plus kinetic energy.
`get_types`()	Returns a unique list of atom types.
`get_velocities`()	Get array of velocities.
`get_volume`()	Get volume of unit cell.
`has`(name)	Check for existence of array.
`new_array`(name, a[, dtype, shape])	Add new array.
`pop`([i])	Remove and return atom at index i (default last).
`rattle`([stdev, seed, rng])	Randomly displace atoms.
`repeat`(rep)	Create new repeated atoms object.
`rotate`(a, v[, center, rotate_cell])	Rotate atoms based on a vector and an angle, or two vectors.
`rotate_dihedral`(a1, a2, a3, a4, angle[, ...])	Rotate dihedral angle.
`set_angle`(a1[, a2, a3, angle, mask, ...])	Set angle (in degrees) formed by three atoms.
`set_array`(name, a[, dtype, shape])	Update array.
`set_atom_data`(atom_data)	Set Lennard-Jones parameters and atomic charges.
`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_cutoffs`(cutoffs)	Add a CutoffList object to the structure.
`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 the 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_scaled_positions`(scaled)	Set positions relative to unit cell.
`set_tags`(tags)	Set tags for all atoms.
`set_types`(types)	Set a type for each atom to specify the interaction with its neighbors.
`set_velocities`(velocities)	Set the momenta by specifying the velocities.
`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.

iterimages

default_map = {'Al': 'Al', 'Ar': 'Ar', 'BR': 'Br', 'Be': 'Be', 'C0': 'Ca', 'Li': 'Li', 'Mg': 'Mg'}

__init__(*args, **kwargs): Set a type for each atom to specify the interaction with its neighbors. This enables atoms of the same element to have different interaction potentials. During initialization, the types are initially derived from the chemical symbols of the atoms.

append(atom)

Append atom to the end.

Parameters:: atom (ase.Atoms) – The particle to append.

set_types(types)

Set a type for each atom to specify the interaction with its neighbors. This enables atoms of the same element to have different interaction potentials.

Parameters:: types (list) – A list of strings that specify the type of each atom.

get_types()

Returns a unique list of atom types.

Returns:: Particle types. Each element is a str with two characters.
Return type:: numpy.ndarray

set_cutoffs(cutoffs)

Add a CutoffList object to the structure. This allows the matscipy.opls.OPLSStructure.get_neighbors() method to find all interacting atoms of the structure based on a simple distance criterion.

Parameters:: cutoffs (opls.CutoffList) – Cutoffs.

get_neighbors(): Find all atoms which might interact with each other based on a simple distance criterion.

set_atom_data(atom_data)

Set Lennard-Jones parameters and atomic charges. Notice that each atom has exactly one set of Lennard-Jones parameters. Parameters for interactions between different types of atoms are calculated by geometric mixing. See documentation of the LAMMPS pair_modify command for details.

Parameters:: atom_data (dict) – Dictionary containing Lennard-Jones parameters and charges for each particle type. key: Particle type, one or two characters, value: [LJ-epsilon, LJ-sigma, charge].

get_charges()

Return an array of atomic charges. Same functionality as the ase.Atoms.get_charges() method, but atomic charges are taken from a user definition instead of the result of a calculation.

Returns:: Particle charges.
Return type:: numpy.ndarray

get_bonds(bonds=None)

Returns an array of all bond types and an array of all bonds in the system. This method also checks if potential parameters for all found bonds are present.

Parameters:

bonds (opls.BondData, optional) – Pairwise potential parameters. Can be set here or elsewhere in the code, e.g. by setting the attribute matscipy.opls.OPLSStructure.bonds. If it is present, this method runs a test to check if interaction parameters are defined for all present bonds.

Returns:

bond_types (numpy.ndarray) – Array of strings characterizing all present bond types. Example: A system consists of particles with the types A1 and A2. If all particles interact with each other, bond_types will be
```
['A1-A1', 'A1-A2', 'A2-A2']
```
If there were no interactions between the types A1 and A2, bond_types would be
```
['A1-A1', 'A2-A2']
```
bond_list (numpy.ndarray) – bond_list.shape = (n, 3) where n is the number of particles in the system. Contains arrays of 3 integers for each bond in the system. First number: interaction type, index of bond_types, second and third numbers: indicees of participating particles. Example: A system consists of 3 particles of type AA, all particles are interacting. bond_types would be
```
['AA-AA']
```
and bond_list would be
```
[[0, 0, 1], [0, 0, 2], [0, 1, 2]]
```

Raises:

RuntimeError – If self.bonds is present and bonds are found for which no parameters are defined. In this case a warning a full list of all affected bonds will be printed on STDOUT.

get_angles(angles=None)

Returns an array of all angle types and an array of all angles in the system. This method also checks if potential parameters for all found angles are present.

Parameters:

angles (opls.AnglesData, optional) – Potential parameters. Can be set here or elsewhere in the code, e.g. by setting the attribute matscipy.opls.OPLSStructure.angles.

Returns:

ang_types (list) – Array of strings characterizing all present angle types. Example: A system consists of atoms of types A1 and A2, all conceivable angle types are present in the system. ang_types would be
```
['A1-A1-A1', 'A1-A1-A2', 'A1-A2-A1', 'A1-A2-A2', 'A2-A1-A2', 'A2-A2-A2']
```
ang_list (list) – len(ang_list) = n where n is the number of particles in the system. Each list entry is a list of 4 integers, characterizing the angles present in the system. Example: A system contains 7 atoms, (0,1,2) of type A1 and (3,4,5,6) of type A2. If there are angles between (0,1,2), (0,3,4) and (0,5,6), ang_list would be
```
['A1-A1-A1', 'A2-A1-A2']
```
and ang_list would be
```
[[0, 0, 1, 2], [1, 0, 3, 4], [1, 0, 5, 6]]
```

Raises:

RuntimeError – If self.angles is present and angles are found for which no parameters are defined. In this case a warning a full list of all affected angles will be printed on STDOUT.

ase_objtype = 'atoms'

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.

property constraints: Constraints of the atoms.

copy(): Return a copy.

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.

euler_rotate(phi=0.0, theta=0.0, psi=0.0, center=(0, 0, 0))

Rotate atoms via Euler angles (in degrees).

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

Parameters:

center :: 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.
phi :: The 1st rotation angle around the z axis.
theta :: Rotation around the x axis.
psi :: 2nd rotation around the z axis.

extend(other): Extend atoms object by appending atoms from other.

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_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(): Get integer array of atomic numbers.

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(scaled=False, indices=None)

Get the center of mass.

Parameters:

scaled (bool) – If True, the center of mass in scaled coordinates is returned.
indices (list | slice | str, default: None) – If specified, the center of mass of a subset of atoms is returned.

get_chemical_formula(mode='hill', empirical=False)

Get the chemical formula as a string based on the chemical symbols.

Parameters:

mode: str

There are four different modes available:

‘all’: The list of chemical symbols are contracted to a string, e.g. [‘C’, ‘H’, ‘H’, ‘H’, ‘O’, ‘H’] becomes ‘CHHHOH’.

‘reduce’: The same as ‘all’ where repeated elements are contracted to a single symbol and a number, e.g. ‘CHHHOCHHH’ is reduced to ‘CH3OCH3’.

‘hill’: The list of chemical symbols are contracted to a string following the Hill notation (alphabetical order with C and H first), e.g. ‘CHHHOCHHH’ is reduced to ‘C2H6O’ and ‘SOOHOHO’ to ‘H2O4S’. This is default.

‘metal’: The list of chemical symbols (alphabetical metals, and alphabetical non-metals)

empirical, bool (optional, default=False)

Divide the symbol counts by their greatest common divisor to yield an empirical formula. Only for mode metal and hill.

get_chemical_symbols()

Get list of chemical symbol strings.

Equivalent to list(atoms.symbols).

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(dihedrals=None, full_output=False)

Returns an array of all dihedral types and an array of all dihedrals in the system. This method also checks if potential parameters for all found dihedrals are present.

Parameters:

dihedrals (opls.DihedralsData, optional) – Potential parameters. Can be set here or elsewhere in the code, e.g. by setting the attribute matscipy.opls.OPLSStructure.dihedrals.
full_output (bool, optional) – Print a full list of all found dihedrals on STDOUT for which no potential parameters are defined. By default, only one example is printed. Having the full list is sometimes helpful for debugging.

Returns:

dih_types (list) – Array of strings characterizing all present dihedral types. Example: Consider a system consisting of one benzene molecule. There are three possible types of dihedrals and dih_type would be
```
['C-C-C-C', 'C-C-C-H', 'H-C-C-H']
```
dih_list (list) – len(dih_list) = n where n is the number of particles in the system. Each list entry is a list of 5 integers, characterizing the dihedrals present in the system. Example: Consider a system consisting of one benzene molecule with the C atoms (0,1,2,3,4,5) and the H atoms (6,7,8,9,10,11). dih_type would be
```
['C-C-C-C', 'C-C-C-H', 'H-C-C-H']
```
and dih_list would be
```
[[0, 0, 1, 2, 3], [0, 1, 2, 3, 4], ... , [1, 6, 0, 1, 2],
 [1, 7, 1, 2, 3], ... , [2, 6, 0, 1, 7], [2, 7, 1, 2, 8], ...]
```

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=False, 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).

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_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_initial_charges(): Get array of initial charges.

get_initial_magnetic_moments(): Get array of initial magnetic moments.

get_kinetic_energy(): Get the kinetic energy.

get_magnetic_moment(): Get calculated total magnetic moment.

get_magnetic_moments(): Get calculated local magnetic moments.

get_masses(): Get array of masses in atomic mass units.

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. Periodic boundary conditions are ignored. Units of the moments of inertia are amu*angstrom**2.

get_number_of_atoms(): Deprecated since version 3.18.1: You probably want len(atoms). Or if your atoms are distributed, use (and see) get_global_number_of_atoms().

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_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_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_tags(): Get integer array of tags.

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_volume(): Get volume of unit cell.

has(name)

Check for existence of array.

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

iterimages()

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.

property pbc: Reference to pbc-flags for in-place manipulations.

pop(i=-1): Remove and return atom at index i (default last).

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!

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).

rotate(a, v, center=(0, 0, 0), rotate_cell=False)

Rotate atoms based on a vector and an angle, or two vectors.

Parameters:

a = None:: Angle that the atoms is rotated around the vector ‘v’. ‘a’ can also be a vector and then ‘a’ is rotated into ‘v’.
v:: Vector to rotate the atoms around. Vectors can be given as strings: ‘x’, ‘-x’, ‘y’, … .
center = (0, 0, 0):: 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.
rotate_cell = False:: If true the cell is also 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.

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 the initial magnetic moments.

Use either one or three numbers for every atom (collinear or non-collinear spins).

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_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 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.

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.