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.

property atoms

underlying Atoms object.

Type

atomman.Atoms

atoms_df(scale=False)

Extends Atoms.df() by adding a scale argument.

Parameters

scale (bool or list, optional) – Indicates if/which per-atom 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 per-atom 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 per-atom 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

atomman.System

property atoms_ix

Indexer for index slicing of Systems by per-atom properties.

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) – Per-atom property name.

  • index (int, list, slice, optional) – Index of atoms.

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

property atypes

List of int atom types.

Type

tuple

property box

underlying Box object.

Type

atommman.Box

box_set(**kwargs)

Extends box.set() with a scale argument.

Parameters
  • scale (bool) – If True, the scaled (box-relative) positions remain unchanged. Default value is False (absolute positions unchanged).

  • kwargs (other) – Any other kwargs allowed by box.set().

property composition

The system’s reduced and sorted symbols composition.

Returns

The system’s reduced and sorted symbols composition. Will return None if symbols are missing

Return type

str or None

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

dump(style, **kwargs)

Convert a System to another format.

Parameters
  • style (str) – Indicates the format of the content to dump the atomman.System as.

  • kwargs – Any extra keyword arguments to pass to the underlying dump methods.

Returns

Any content returned by the underlying dump methods.

Return type

str, object or tuple

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

property masses

The masses associated with each atype if given.

Type

tuple

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 box-scaled 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

property natoms

The number of atoms in the Atoms class.

Type

int

property natypes

The number of atom types/symbols.

Type

int

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 file-like 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

atomman.NeighborList

normalize(style='lammps', return_transform=False)

Normalizes a system’s box vectors and atom positions to be compatible with simulation codes.

Parameters
  • style (str, optional) – Indicates the normalization style to use. Default (and only current option) is ‘lammps’.

  • return_transform (bool, optional) – Indicates if the transformation matrix associated with the normalization is returned. Default value is False.

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.

property pbc

The periodic boundary condition settings.

Type

list of bool

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 pre-computed 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

float

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 Miller-Bravais 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 1e-4 to 1e-8.

  • 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

atomman.System

property symbols

The element model symbols associated with each atype.

Type

tuple

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 non-periodic 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