Box
- class atomman.Box(**kwargs)
-
A representation of a triclinic (parallelepiped) box.
- property alpha: float
The alpha lattice angle in degrees (angle between bvect and cvect).
- Type:
- classmethod cubic(a: float) Box
Initializes a Box in standard cubic setting using only cubic lattice parameters.
a = b = c, alpha = beta = gamma = 90
- Parameters:
a (-) – The a lattice constant
- Return type:
- property gamma: float
The gamma lattice angle in degrees (angle between avect and bvect).
- Type:
- classmethod hexagonal(a: float, c: float) Box
Initializes a Box in standard hexagonal setting using only hexagonal lattice parameters.
a = b != c, alpha = beta = 90, gamma = 120
- Parameters:
a (-) – The a lattice constant
c (-) – The c lattice constant
- Return type:
- identifyfamily(rtol: float = 1e-05, atol: float = 1e-08) str | None
Tests if the box is consistent with a standard representation of a crystal system cell.
- Parameters:
- Returns:
‘cubic’, ‘hexagonal’, ‘tetragonal’, ‘rhombohedral’, ‘orthorhombic’, ‘monoclinic’ or ‘triclinic’ if it matches any. None if no matches.
- Return type:
str or None
- Raises:
ValueError – If the box is not consistent with a standard cell.
- inside(pos: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], inclusive: bool = True) ndarray
Indicates if position(s) are inside the shape.
- Parameters:
pos (array-like object) – Nx3 array of coordinates.
inclusive (bool, optional) – Indicates if points on the shape’s boundaries are to be included. Default value is True.
- Returns:
N array of bool values: True if inside shape
- Return type:
numpy.NDArray
- is_lammps_norm() bool
Tests if box is compatible with LAMMPS. Note: large box tilt factors not checked. The LAMMPS command ‘box tilt large’ may be needed to run LAMMPS.
- iscubic(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard cubic cell: a = b = c alpha = beta = gamma = 90
- ishexagonal(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard hexagonal cell: a = b != c alpha = beta = 90 gamma = 120
- ismonoclinic(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard monoclinic cell: a != b != c alpha = gamma = 90 beta != 90
- isorthorhombic(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard orthorhombic cell: a != b != c alpha = beta = gamma = 90
- isrhombohedral(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard rhombohedral cell: a = b = c alpha = beta = gamma != 90
- istetragonal(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard tetragonal cell: a = b != c alpha = beta = gamma = 90
- istriclinic(rtol: float = 1e-05, atol: float = 1e-08) bool
Tests if the box is consistent with a standard triclinic cell: a != b != c alpha != 90 beta != 90 gamma != 90
- model(model: str | IOBase | DataModelDict | None = None, length_unit: str = 'angstrom') DataModelDict | None
Reads or generates a data model for the box.
- Parameters:
- Returns:
A JSON/XML equivalent data model for the box. Returned if model is not given
- Return type:
DataModelDict.DataModelDict
- classmethod monoclinic(a: float, b: float, c: float, beta: float) Box
Initializes a Box in standard monoclinic setting using only monoclinic lattice parameters.
a != b != c, alpha = gamma = 90, beta > 90
- Parameters:
a (-) – The a lattice constant
b (-) – The b lattice constant
c (-) – The c lattice constant
beta (-) – The beta lattice angle in degrees
- Return type:
- property origin: ndarray
Box origin position where vects are added to define the box. Can be set directly.
- Type:
numpy.ndarray
- classmethod orthorhombic(a: float, b: float, c: float) Box
Initializes a Box in standard orthorhombic setting using only orthorhombic lattice parameters.
a != b != c, alpha = beta = gamma = 90
- Parameters:
a (-) – The a lattice constant
b (-) – The b lattice constant
c (-) – The c lattice constant
- Return type:
- plane_crystal_to_cartesian(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
Converts crystal planar indices to Cartesian plane normal vectors based on the box’s lattice vectors. Note: the algorithm used requires that the planar indices be integers.
- Parameters:
indices (array-like object) – (…, 3) array of [hkl] Miller crystallographic indices or (…, 4) array of [hkil] Miller-Bravais crystallographic indices.
box (atomman.Box) – Box that defines the lattice cell vectors to use.
- Returns:
(…, 3) array of Cartesian vectors corresponding to plane normals.
- Return type:
np.ndarray of float
- Raises:
ValueError – If indices dimensions are not (…, 3) or (…, 4), or if hexagonal indices given with non-hexagonal box.
- position_cartesian_to_relative(cartpos: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
Converts position vectors from absolute Cartesian coordinates to relative box coordinates based on the box’s vects and origin.
- Parameters:
cartpos (array-like object) – (…, 3) array of Cartesian position vectors.
- Returns:
(…, 3) array of the relative positions corresponding to cartpos.
- Return type:
numpy.ndarray
- Raises:
ValueError – If cartpos dimensions are not (…, 3).
- position_relative_to_cartesian(relpos: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
Converts position vectors from relative box coordinates to absolute Cartesian coordinates based on the box’s vects and origin.
- Parameters:
relpos (array-like object) – (…, 3) array of relative position vectors.
- Returns:
(…, 3) array of the absolute Cartesian positions corresponding to relpos.
- Return type:
numpy.ndarray
- Raises:
ValueError – If relpos dimensions are not (…, 3).
- property reciprocal_vects: ndarray
Array of the crystallographic reciprocal box vectors. These have not been scaled by the factor of 2 pi.
- Type:
numpy.ndarray
- set(**kwargs)
Sets a Box’s dimensions. If parameters besides origin are given they must completely define the box. Allowed parameter sets are:
no parameters -> box is set to square unit box with origin = [0,0,0].
origin. -> Only origin is changed (same as setting origin directly).
vects, (and origin).
avect, bvect, cvect, (and origin).
a, b, c, (alpha, beta, gamma, and origin).
lx, ly, lz, (xy, xz, yz, and origin).
xlo, xhi, ylo, yhi, zlo, zhi, (xy, xz, and yz).
See the description of class methods and attributes for more details on the allowed parameters.
- set_abc(a: float, b: float, c: float, alpha: float = 90.0, beta: float = 90.0, gamma: float = 90.0, origin: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None)
Set the box using crystal cell lattice parameters and angles.
- Parameters:
a (float) – The a lattice parameter.
b (float) – The b lattice parameter.
c (float) – The c lattice parameter.
alpha (float, optional) – The alpha lattice angle in degrees (angle between b and c vectors). Default value is 90.0.
beta (float, optional) – The beta lattice angle in degrees (angle between a and c vectors). Default value is 90.0.
gamma (float, optional) – The gamma lattice angle in degrees (angle between a and b vectors). Default value is 90.0.
origin (array-like object, optional) – The 3D vector for the box origin position. Default value is (0,0,0).
- set_hi_los(xlo: float, xhi: float, ylo: float, yhi: float, zlo: float, zhi: float, xy: float = 0.0, xz: float = 0.0, yz: float = 0.0)
Set the box using LAMMPS box hi’s, lo’s and tilt factors.
- Parameters:
xlo (float) – The LAMMPS xlo box lo term.
xhi (float) – The LAMMPS xhi box hi term.
ylo (float) – The LAMMPS ylo box lo term.
yhi (float) – The LAMMPS yhi box hi term.
zlo (float) – The LAMMPS zlo box lo term.
zhi (float) – The LAMMPS zhi box hi term.
xy (float, optional) – The LAMMPS box tilt factor in the xy direction. Default value is 0.0.
xz (float, optional) – The LAMMPS box tilt factor in the xz direction. Default value is 0.0.
yz (float, optional) – The LAMMPS box tilt factor in the yz direction. Default value is 0.0.
- set_lengths(lx: float, ly: float, lz: float, xy: float = 0.0, xz: float = 0.0, yz: float = 0.0, origin: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None)
Set the box using LAMMPS box lengths and tilt factors.
- Parameters:
lx (float) – The LAMMPS box length in the x direction.
ly (float) – The LAMMPS box length in the y direction.
lz (float) – The LAMMPS box length in the z direction.
xy (float, optional) – The LAMMPS box tilt factor in the xy direction. Default value is 0.0.
xz (float, optional) – The LAMMPS box tilt factor in the xz direction. Default value is 0.0.
yz (float, optional) – The LAMMPS box tilt factor in the yz direction. Default value is 0.0.
origin (array-like object, optional) – The 3D vector for the box origin position. Default value is (0,0,0).
- set_vectors(avect: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], bvect: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], cvect: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], origin: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None)
Set the box using the three box vectors.
- Parameters:
avect (array-like object) – The 3D vector for the a box dimension.
bvect (array-like object) – The 3D vector for the b box dimension.
cvect (array-like object) – The 3D vector for the c box dimension.
origin (array-like object, optional) – The 3D vector for the box origin position. Default value is (0,0,0).
- classmethod tetragonal(a: float, c: float) Box
Initializes a Box in standard tetragonal setting using only tetragonal lattice parameters.
a = b != c, alpha = beta = gamma = 90
- Parameters:
a (-) – The a lattice constant
c (-) – The c lattice constant
- Return type:
- classmethod triclinic(a: float, b: float, c: float, alpha: float, beta: float, gamma: float) Box
Initializes a Box in standard triclinic setting using only triclinic lattice parameters.
a != b != c, alpha != beta != gamma
- Parameters:
a (-) – The a lattice constant
b (-) – The b lattice constant
c (-) – The c lattice constant
alpha (-) – The alpha lattice angle in degrees
beta (-) – The beta lattice angle in degrees
gamma (-) – The gamma lattice angle in degrees
- Return type:
- classmethod trigonal(a: float, alpha: float) Box
Initializes a Box in standard trigonal setting using only trigonal lattice parameters.
a = b = c, alpha = beta = gamma < 120
- Parameters:
a (-) – The a lattice constant
alpha (-) – The alpha lattice angle in degrees
- Return type:
- vector_crystal_to_cartesian(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray
Converts crystal indices to Cartesian vectors relative to the box’s lattice vectors.
- Parameters:
indices (array-like object) – (…, 3) array of [uvw] Miller crystallographic indices or (…, 4) array of [uvtw] Miller-Bravais crystallographic indices.
- Returns:
(…, 3) array of Cartesian vectors.
- Return type:
np.ndarray of float
- Raises:
ValueError – If indices dimensions are not (…, 3) or (…, 4), or if hexagonal indices given with non-hexagonal box.