System

Bases: object

A representation of an atomic system. This combines Atoms with Box and adds methods and attributes involving both.

property atoms: Atoms

underlying Atoms object.

Type:: atomman.Atoms

atoms_df(scale: bool = False) → DataFrame

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: Atoms | int, scale: bool = False, symbols: list | None = None, safecopy: bool = False) → System

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 current System object’s box and pbc (and symbols if not specified) will be copied over.

Return type:

atomman.System

property atoms_ix: _AtomsIndexer: Indexer for index slicing of Systems by per-atom properties.

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.

Returns:

list – If no parameters given, returns a list of all assigned property keys.
atomman.Atoms – If index or a_id is given without value or key, returns a new Atoms instance for the specified atom indices.
numpy.ndarray – If key (and index/a_id) is given without value, returns a copy of the data associated with that property key.

property atypes: tuple

List of int atom types.

Type:: tuple

property box: 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: str | None

The system’s reduced and sorted symbols composition.

Returns:: The system’s reduced and sorted symbols composition. Will return None if any symbols are missing
Return type:: str or None

Computes the shortest distance between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.

Parameters:

pos_0 (index or array-like object) – 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 (index or array-like object) – 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: str, **kwargs) → Any | None

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

Computes the shortest vector between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.

Parameters:

pos_0 (index or array-like object) – 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 (index or array-like object) – 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: tuple

The masses associated with each atype if given.

Type:: tuple

model(box_unit: str | None = None, prop_name: list | None = None, unit: list | None = None, prop_unit: dict | None = None) → DataModelDict

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: int

The number of atoms in the Atoms class.

Type:: int

property natypes: int

The number of atom types/symbols.

Type:: int

neighborlist(**kwargs) → NeighborList

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: str = 'lammps', return_transform: bool = False) → System | Tuple[System, ndarray]

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: ndarray

The periodic boundary condition settings.

Type:: numpy.ndarray of bool

r0(neighbors: NeighborList | None = None) → float

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

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 (array-like object) – 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.

Scales 3D vectors from absolute Cartesian coordinates to relative box coordinates.

Parameters:: value (array-like object) – Absolute Cartesian coordinates to scale.
Returns:: The relative box coordinates associated with the given values.
Return type:: numpy.ndarray

supersize(a_size: int | Tuple[int, int], b_size: int | Tuple[int, int], c_size: int | Tuple[int, int]) → System

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 (c_size -- int or tuple of) – Single int or two integers specifying replication along the bvect direction.
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: tuple

The element model symbols associated with each atype.

Type:: tuple

Unscales 3D vectors from relative box coordinates to absolute Cartesian coordinates.

Parameters:: value (numpy.ndarray) – Relative box coordinates to unscale.
Returns:: Absolute Cartesian coordinates associated with the given values.
Return type:: numpy.ndarray

wrap(return_imageflags: bool = False) → ndarray | None

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 - only returned if return_imageflags = True.
Return type:: numpy.NDarray of int

System

Table of Contents

Previous topic

Next topic