System

class
atomman.
System
(atoms=None, box=None, pbc=None, scale=False, symbols=None, masses=None, model=None, safecopy=False) Bases:
object
A representation of an atomic system. This combines Atoms with Box and adds methods and attributes involving both.

atoms_df
(scale=False) Extends Atoms.df() by adding a scale argument.
 Parameters
scale (bool or list, optional) – Indicates if/which peratom properties are to be scaled to box relative values. If False (default), no properties will be scaled. If True, pos will be scaled. Multiple properties can be scaled by providing a list of the property names to scale.
 Returns
Tabulated DataFrame version of the atomic data.
 Return type
pandas.DataFrame

atoms_extend
(value, scale=False, symbols=None, safecopy=False) Extends Atoms.extend() to the System level by adding scale and symbols arguments.
 Parameters
value (atomman.Atoms or int) – An int value will result in the atoms object being extended by that number of atoms, with all peratom properties having default values (atype = 1, everything else = 0). For an Atoms value, the current atoms list will be extended by the correct number of atoms and all peratom properties in value will be copied over. Any properties defined in one Atoms object and not the other will be set to default values.
scale (bool, optional) – Flag indicating if position values in a supplied Atoms value are to be taken as absolute Cartesian (False, default) or in scaled box relative units (True).
symbols (tuple, list or None, optional) – Allows for the system’s symbols list to be updated. If not given, will use the current object’s symbols.
safecopy (bool, optional) – Flag indicating if values are to be copied before setting. If False (default), underlying objects may be shared between the new system and the current system and input parameters. If True, atoms and box will be deepcopied before setting. Note that safecopy=True may be considerably slower for large numbers of atoms and/or properties.
 Returns
A new System object with Atoms extended to contain all atoms and properties of the current object plus the additional atoms. The cuurent System object’s box and pbc (and symbols if not specified) will be copied over.
 Return type

atoms_prop
(key=None, index=None, value=None, a_id=None, scale=False) Extends Atoms.prop() by adding a scale argument.
 Parameters
key (str, optional) – Peratom property name.
value (any, optional) – Property values to assign.
a_id (int, optional) – Integer atom index. Left in for backwards compatibility.
scale (bool, optional) – Flag indicating if values should be scaled/unscaled. If True:  Values being retrieved are scaled from absolute Cartesian to box relative vectors.  Values being set are unscaled from box relative to absolute Cartesian vectors. Default value is False.

box_set
(**kwargs) Extends box.set() with a scale argument.
 Parameters
scale (bool) – If True, the scaled (boxrelative) positions remain unchanged. Default value is False (absolute positions unchanged).
kwargs (other) – Any other kwargs allowed by box.set().

dmag
(pos_0, pos_1) Computes the shortest distance between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.
 Parameters
pos_0 (numpy.ndarray or index) – Absolute Cartesian vector position(s) to use as reference point(s). If the value can be used as an index, then self.atoms.pos[pos_0] is taken.
pos_1 (numpy.ndarray or index) – Absolute Cartesian vector position(s) to find relative to pos_0. If the value can be used as an index, then self.atoms.pos[pos_1] is taken.
 Returns
The shortest vector magnitude from each pos_0 to pos_1 positions.
 Return type
numpy.ndarray

dvect
(pos_0, pos_1) Computes the shortest vector between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.
 Parameters
pos_0 (numpy.ndarray or index) – Absolute Cartesian vector position(s) to use as reference point(s). If the value can be used as an index, then self.atoms.pos[pos_0] is taken.
pos_1 (numpy.ndarray or index) – Absolute Cartesian vector position(s) to find relative to pos_0. If the value can be used as an index, then self.atoms.pos[pos_1] is taken.
 Returns
The shortest vectors from each pos_0 to pos_1 positions.
 Return type
numpy.ndarray

model
(box_unit=None, prop_name=None, unit=None, prop_unit=None) Generates a data model for the System object.
 Parameters
box_unit (str, optional) – Length unit to use for the box. Default value is ‘angstrom’.
prop_name (list, optional) – The Atoms properties to include. If neither prop_name nor prop_unit are given, all system properties will be included.
unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in boxscaled units. If neither unit nor prop_units given, pos will be given in Angstroms and all other values will not be converted.
prop_unit (dict, optional) – dictionary where the keys are the property keys to include, and the values are units to use. If neither unit nor prop_units given, pos will be given in Angstroms and all other values will not be converted.
 Returns
A JSON/XML data model for the current System object.
 Return type
DataModelDict.DataModelDict

neighborlist
(**kwargs) Builds a neighbor list for the system. The resulting NeighborList object is saved to the object as attribute ‘neighbors’.
 Parameters
cutoff (float, optional) – Radial cutoff distance for identifying neighbors. Must be given if model is not given.
model (str or filelike object, optional) – Gives the file path or content to load. If given, no other parameters are allowed.
initialsize (int, optional) – The number of neighbor positions to initially assign to each atom. Default value is 20.
deltasize (int, optional) – Specifies the number of extra neighbor positions to allow each atom when the number of neighbors exceeds the underlying array size. Default value is 10.
 Returns
The compiled list of neighbors.
 Return type

normalize
(style='lammps', return_transform=False) Normalizes a system’s box vectors and atom positions to be compatible with simulation codes.
 Parameters
 Returns
newsystem (atomman.System) – A new system that has been normalized.
transform (np.ndarray) – The transformation matrix associated with the normalization. Returned if return_transform is True.

r0
(neighbors=None) Identifies the shortest interatomic spacing between atoms in the system by comparing the shortest periodic box vector with the smallest dmags of all neighbor atoms.
 Parameters
neighbors (NeighborList, optional) – A precomputed NeighborList for the system. If not given, a new NeighborList will be computed using a cutoff distance based on the smallest dmag between atom 0 and the rest of the system’s atoms.
 Returns
The shortest interatomic spacing identified.
 Return type

rotate
(uvws, tol=None, return_transform=False) Transforms a System representing a periodic crystal cell from a standard orientation to a specified orientation. Note: if hexagonal indices are given, the vectors will be reduced to the smallest uvw integer representation.
 Parameters
uvws (numpy.ndarray) – A (3, 3) array of the Miller crystal vectors or a (3, 4) array of MillerBravais hexagonal crystal vectors to use in transforming the system. Values must be integers.
tol (list or float, optional) – Tolerance parameter used in determining which atoms are inside the box. Multiple values can be given as the identification may occasionally fail for a given ucell and tol. Default behavior will try tol values ranging from 1e4 to 1e8.
return_transform (bool, optional) – Indicates if the transformation matrix associated with the rotation is returned. Default value is False.
 Returns
atomman.System – A new fully periodic system rotated and transformed according to the uvws crystal vectors.
transform (np.ndarray) – The transformation matrix associated with the rotation. Returned if return_transform is True.

scale
(value) Scales 3D vectors from absolute Cartesian coordinates to relative box coordinates.
 Parameters
value (numpy.ndarray) – Values to scale.

supersize
(a_size, b_size, c_size) Creates a larger system from a given system by replicating it along the system’s box vectors.
The multiplier values *_size are taken to be integer tuples (m, n) where m <= 0 and n >= 0. The system multiplication works such that if n = m, then the seed system’s origin will be at the center of the new system. If only one integer is given, then it is assigned to m or n depending on its sign, and the other value is taken to be 0.
 Parameters
a_size (int or tuple of int) – Single int or two integers specifying replication along the avect direction.
 int or tuple of int (c_size) – Single int or two integers specifying replication along the bvect direction.
 int or tuple of int – Single int or two integers specifying replication along the cvect direction.
 Returns
A new system created by replicating the given seed system according to the *_size parameters.
 Return type

unscale
(value) Unscales 3D vectors from relative box coordinates to absolute Cartesian coordinates.
 Parameters
value (numpy.ndarray) – Values to unscale.

wrap
(return_imageflags=False) Wrap atoms around periodic boundaries and extend nonperiodic boundaries such that all atoms are within the box.
 Parameters
return_imageflags (bool, optional) – If True, an array of which image the atom was originally in is returned.
 Returns
The imageflags array
 Return type
numpy.NDarray of int
