Box

class atomman.Box(**kwargs)

Bases: atomman.region.Shape.Shape, object

A representation of a triclinic (parallelepiped) box.

property a: float

The a lattice parameter (magnitude of avect).

Type

float

property alpha: float

The alpha lattice angle in degrees (angle between bvect and cvect).

Type

float

property avect: numpy.ndarray

Vector associated with the a box dimension.

Type

numpy.ndarray

property b: float

The b lattice parameter (magnitude of avect).

Type

float

property beta: float

The beta lattice angle in degrees (angle between avect and cvect).

Type

float

property bvect: numpy.ndarray

Vector associated with the b box dimension.

Type

numpy.ndarray

property c: float

The c lattice parameter (magnitude of avect).

Type

float

classmethod cubic(a: float) atomman.core.Box.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

atomman.Box

property cvect: numpy.ndarray

Vector associated with the c box dimension.

Type

numpy.ndarray

property gamma: float

The gamma lattice angle in degrees (angle between avect and bvect).

Type

float

classmethod hexagonal(a: float, c: float) atomman.core.Box.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

atomman.Box

identifyfamily(rtol: float = 1e-05, atol: float = 1e-08) Optional[str]

Tests if the box is consistent with a standard representation of a crystal system cell.

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

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: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], inclusive: bool = True) numpy.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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if the box is a standard cubic cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if the box is a standard hexagonal cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard monoclinic cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if the box is a standard orthorhombic cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if the box is a standard rhombohedral cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if the box is a standard tetragonal cell, False otherwise.

Return type

bool

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

Parameters
  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard triclinic cell, False otherwise.

Return type

bool

property lx: float

LAMMPS lx box length (avect[0] for normalized boxes).

Type

float

property ly: float

LAMMPS ly box length (bvect[1] for normalized boxes).

Type

float

property lz: float

LAMMPS lz box length (cvect[2] for normalized boxes).

Type

float

model(model: Optional[Union[str, io.IOBase, DataModelDict.DataModelDict.DataModelDict]] = None, length_unit: str = 'angstrom') Optional[DataModelDict.DataModelDict.DataModelDict]

Reads or generates a data model for the box.

Parameters
  • model (str or DataModelDict, optional) – JSON/XML formatted data, or path to file containing said data. If not given, then a model for the current box will be returned.

  • length_unit (str, optional) – Unit of length to save box values in if data model is to be generated. Default value is ‘angstrom’.

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) atomman.core.Box.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

atomman.Box

property origin: numpy.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) atomman.core.Box.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

atomman.Box

plane_crystal_to_cartesian(indices: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) numpy.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.

property planes: Tuple[atomman.region.Plane.Plane]

The box’s planes represented as atomman.region.Plane objects.

Type

tuple

position_cartesian_to_relative(cartpos: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) numpy.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: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) numpy.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: numpy.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: Optional[Union[int, Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = 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: Optional[Union[int, Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = 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: npt.ArrayLike, bvect: npt.ArrayLike, cvect: npt.ArrayLike, origin: Optional[:npt.ArrayLike] = 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) atomman.core.Box.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

atomman.Box

classmethod triclinic(a: float, b: float, c: float, alpha: float, beta: float, gamma: float) atomman.core.Box.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

atomman.Box

classmethod trigonal(a: float, alpha: float) atomman.core.Box.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

atomman.Box

vector_crystal_to_cartesian(indices: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) numpy.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.

property vects: numpy.ndarray

Array containing all three box vectors. Can be set directly.

Type

numpy.ndarray

property volume: float

The volume of the box.

Type

float

property xhi: float

LAMMPS xhi box hi term (origin[0] + lx for normalized boxes).

Type

float

property xlo: float

LAMMPS xlo box lo term (origin[0] for normalized boxes).

Type

float

property xy: float

LAMMPS xy box tilt factor (bvect[0] for normalized boxes).

Type

float

property xz: float

LAMMPS xz box tilt factor (cvect[0] for normalized boxes).

Type

float

property yhi: float

LAMMPS yhi box hi term (origin[1] + ly for normalized boxes).

Type

float

property ylo: float

LAMMPS ylo box lo term (origin[1] for normalized boxes).

Type

float

property yz: float

LAMMPS yz box tilt factor (cvect[1] for normalized boxes).

Type

float

property zhi: float

LAMMPS zhi box hi term (origin[2] + lz for normalized boxes).

Type

float

property zlo: float

LAMMPS zlo box lo term (origin[2] for normalized boxes).

Type

float