System
- class atomman.System(atoms: Atoms | None = None, box: Box | None = None, pbc: Tuple[bool, bool, bool] | None = None, scale: bool = False, symbols: str | list | None = None, masses: float | list | None = None, model: str | IOBase | DataModelDict | None = None, safecopy: bool = False)
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:
- 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:
- atoms_prop(key: str | None = None, index: int | list | slice | None = None, value: Any | None = None, a_id: int | None = None, scale: bool = False) list | Atoms | ndarray | None
Extends Atoms.prop() by adding a scale argument.
- Parameters:
key (str, optional) – Per-atom 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.
- 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 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
- dmag(pos_0: int | list | slice | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], pos_1: int | list | slice | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
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
- dvect(pos_0: int | list | slice | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], pos_1: int | list | slice | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
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
- 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
- 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:
- 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:
- 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:
- rotate(uvws: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], tol: float | list | None = None, return_transform: bool = False) System
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.
- scale(value: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
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:
- unscale(value: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
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