relentless.model.TriclinicBox#

class relentless.model.TriclinicBox(Lx, Ly, Lz, xy, xz, yz, convention='LAMMPS')#

Triclinic box.

A TriclinicBox is defined by three edge vectors a, b, and c that form a right-hand basis. These vectors are defined by deformation of an orthorhombic box oriented along the Cartesian axes and having three vectors of length \(L_x\), \(L_y\), and \(L_z\), respectively. The box is then tilted by factors \(xy\), \(xz\), and \(yz\), which are upper off-diagonal elements of the matrix of box vectors. As a result, the a vector is always aligned along the \(x\) axis, while the other two vectors may be tilted.

The box is centered at the origin \((0,0,0)\).

Parameters:

  • Lx (float) – Length along the \(x\) axis.

  • Ly (float) – Length along the \(y\) axis.

  • Lz (float) – Length along the \(z\) axis.

  • xy (float) – First tilt factor.

  • xz (float) – Second tilt factor.

  • yz (float) – Third tilt factor.

  • convention ({'LAMMPS', 'HOOMD'}) – Convention for defining the tilt factors.

Notes

Convention

The tilt factors can be defined using one of two conventions. In the LAMMPS convention, the basis vectors are:

\[\mathbf{a} = (L_x,0,0) \quad \mathbf{b} = (xy,L_y,0) \quad \mathbf{c} = (xz,yz,L_z)\]

In the HOOMD simulation convention, the basis vectors are:

\[\mathbf{a} = (L_x,0,0) \quad \mathbf{b} = (xy \cdot L_y,L_y,0) \quad \mathbf{c} = (xz \cdot L_z,yz \cdot L_z,L_z)\]

Methods

as_array([convention])

Convert to array of lengths and tilt factors.

coordinate_to_fraction(r)

Make fractional coordinates from Cartesian coordinates.

fraction_to_coordinate(x)

Make Cartesian coordinates from fractional coordinates.

from_json(data)

Deserialize from a dictionary.

to_json()

Serialize as a dictionary.

wrap(positions)

Wrap positions subject to periodic boundary conditions.

Attributes

extent

Extent of the region.

high

low

as_array(convention=None)#

Convert to array of lengths and tilt factors.

Parameters:

convention ({'LAMMPS','HOOMD'}, optional) – Convention to use for the tilt factors. Default of None will use the convention for the box.

Returns:

An array containing (Lx,Ly,Lz,xy,xz,yz) according to the convention.

Return type:

numpy.ndarray

coordinate_to_fraction(r)#

Make fractional coordinates from Cartesian coordinates.

The Cartesian coordinates r are projected onto the three (potentially nonorthogonal) basis vectors defining the box to yield fractional coordinates x such that:

\[\mathbf{r} = \mathbf{r}_{\rm low} + (\mathbf{a}\quad\mathbf{b}\quad\mathbf{c}) \cdot \mathbf{x}\]

where \(\mathbf{r}_{\rm low}\) is the lower bound of the box, i.e., low.

Parameters:

r (array_like) – Cartesian coordinates (or array of).

Returns:

Fractional coordinates x corresponding to r.

Return type:

numpy.ndarray

property extent#

Extent of the region.

Type:

float

fraction_to_coordinate(x)#

Make Cartesian coordinates from fractional coordinates.

The fractional coordinates x are converted to Cartesian coordinates r using the basis vectors of the box. See coordinate_to_fraction() for the definition of these coordinates.

Parameters:

r (array_like) – Fractional coordinates (or array of).

Returns:

Cartesian coordinates r corresponding to x.

Return type:

numpy.ndarray

classmethod from_json(data)#

Deserialize from a dictionary.

Parameters:

data (dict) – The serialized equivalent of the TriclinicBox object. The keys of data should be ('Lx','Ly','Lz','xy','xz','yz','convention'). The lengths and tilt factors should be floats, and the convention should be a string.

Returns:

A new TriclinicBox object constructed from the data.

Return type:

TriclinicBox

Raises:

ValueError – If the convention specified is not 'LAMMPS' or 'HOOMD'.

to_json()#

Serialize as a dictionary.

The dictionary contains the three box lengths Lx, Ly, and Lz, the three tilt factors xy, xz, and yz, and the convention for the tilt factors.

Returns:

The serialized TriclinicBox.

Return type:

dict

wrap(positions)#

Wrap positions subject to periodic boundary conditions.

Three-dimensional periodic boundary conditions are applied to ensure the positions lie within the box. This is achieved by converting to fractional coordinates, bounding the fractional coordinates within \([0,1)\), then converting back to Cartesian coordinates.

Parameters:

positions (array_like) – Position vector(s).

Returns:

Wrapped position(s).

Return type:

numpy.ndarray