lammpsio.Box¶

class lammpsio.Box(low, high, tilt=None)¶

Simulation box.

In LAMMPS, the simulation box is specified by three parameters: low, high, and tilt. low defines the origin (lower corner) of the box, while high specifies how far the box extends along each axis. The difference between high and low gives three lengths $L_x$, $L_y$, and $L_z$. tilt has three factors ($L_{xy}$, $L_{xz}$, $L_{yz}$) that skew the edges to create non-orthorhombic simulation boxes. These parameters define a box matrix consisting of three lattice vectors a, b, and c:

\[\begin{split}[\mathbf{a} \quad \mathbf{b} \quad \mathbf{c} ] = \begin{bmatrix} L_x & L_{xy} & L_{xz} \\ 0 & L_y & L_{yz} \\ 0 & 0 & L_z \end{bmatrix}\end{split}\]

For more details on how to convert between the LAMMPS parameters and box matrix see the LAMMPS documentation.

Warning

high is the upper bound of the simulation box only when it is orthorhombic.

Parameters:

low (list) – Origin of the box
high (list) – High parameter used to compute edge lengths.
tilt (list) – Tilt factors xy, xz, and yz for a triclinic box. Default of None is a strictly orthorhombic box, implying all are zero.

Examples

Construct a orthorhombic simulation box with edge lengths (10, 10, 10) and origin (-5, -5, 5):

box = lammpsio.Box(low=[-5, -5, -5], high=[5, 5, 5])

The tilt defaults to None, meaning the box is orthorhombic.

Construct a triclinic simulation box:

box = lammpsio.Box(
    low=[-5.0, -5.0, -5.0],
    high=[5.0, 5.0, 5.0],
    tilt=[1.0, -2.0, 0.5]
)

This box has the same nominal $L_x$, $L_y$, and $L_z$ as the orthorhombic box, but now it also has tilt factors (1, -2, 0.5).

Methods:

`cast`(value)	Cast from an array.
`from_hoomd_convention`(box_data[, low, ...])	Cast from HOOMD-blue convention.
`from_matrix`(low, matrix[, force_triclinic])	Cast from an origin and matrix.
`to_hoomd_convention`()	Convert to HOOMD-blue convention.
`to_matrix`()	Convert to an origin and matrix.

Attributes:

`high`	High parameter.
`low`	Low parameter.
`tilt`	Tilt parameters.

classmethod cast(value)¶

Cast from an array.

If value has 6 elements, it is unpacked as an orthorhombic box:

x_lo, y_lo, z_lo, x_hi, y_hi, z_hi = value

If value has 9 elements, it is unpacked as a triclinic box:

x_lo, y_lo, z_lo, x_hi, y_hi, z_hi, xy, xz, yz = value

Parameters:: value (list) – 6-element or 9-element array representing the box.
Returns:: A simulation box.
Return type:: Box

Examples

Construct an orthorhombic simulation box by casting an array:

box = lammpsio.Box.cast([-5.0, -5.0, -5.0, 5.0, 5.0, 5.0])

The array defines an orthorhombic box, with (-5.0, -5.0, -5.0) being cast to the low and (5.0, 5.0, 5.0) being cast to the high lists in the Box format.

to_matrix()¶

Convert to an origin and matrix.

Parameters:

box (Box) – The box to convert.

Returns:

list – Origin of the box.
numpy.ndarray –

Upper triangular matrix in LAMMPS style:
```
[[lx, xy, xz],
 [0, ly, yz],
 [0, 0, lz]]
```

Examples

Convert a box to an origin and matrix:

low, matrix = box.to_matrix()

low is the origin of the box, and matrix is the upper triangular matrix that defines the box dimensions and tilt factors.

classmethod from_matrix(low, matrix, force_triclinic=False)¶

Cast from an origin and matrix.

Parameters:

low (list) – Origin of the box.
matrix (numpy.ndarray) – Box matrix.
force_triclinic (bool) – If True, forces the box to be triclinic even if the tilt factors are zero. Default is False.

Returns:

A simulation box.

Return type:

Box

Examples

Construct an orthorhombic simulation box from a low and matrix:

box = lammpsio.Box.from_matrix(
    low=[0, 0, 0],
    matrix=[
        [1, 0, 0],
        [0, 1, 0],
        [0, 0, 1]
    ],
    force_triclinic=True)

If the tilt factors in the matrix are set to zero, the method sets the tilt factors to None by default. By setting the force_triclinic to True, the tilt factors are set to (0, 0, 0).

Construct a triclinic simulation box from a low and matrix:

box = lammpsio.Box.from_matrix(
    low=[0, 0, 0],
    matrix=[
        [1, 1.0, -2.0],
        [0, 1, 0.5],
        [0, 0, 1]
    ])

This creates a triclinic box of unit length in each direction with origin at (0, 0, 0) and the tilt factors (1.0, -2.0, 0.5).

to_hoomd_convention()¶

Convert to HOOMD-blue convention.

This convention for defining the box is based on HOOMD-blue.

Parameters:: box (Box) – The box to convert.
Returns:: A matrix of box dimensions in HOOMD-blue convention.
Return type:: numpy.ndarray

Examples

Convert a LAMMPS simulation box to HOOMD-blue convention:

box = lammpsio.Box([-5, -5, -5], [5, 5, 5]).to_hoomd_convention()

This creates an orthorhombic box of dimensions (10, 10, 10) with low at (-5, -5, -5) and center of the box at (0, 0, 0). In accordance with the HOOMD-blue convention, the tilt factors are either normalized by $L_{y}$ for $L_{xy}$ tilt factor and $L_{z}$ for $L_{yz}$ and $L_{xz}$ tilt factors. If tilt factors are None, they are set to zero.

classmethod from_hoomd_convention(box_data, low=None, force_triclinic=False, dimensions=None)¶

Cast from HOOMD-blue convention.

Parameters:

box_data (list) – An array of box dimensions in HOOMD-blue convention.
low (list) – Origin of the box. If None, the box is centered at the origin. Default is None.
force_triclinic (bool) – If True, forces the box to be triclinic even if the tilt factors are zero. Default is False.
dimensions (int) – The number of dimensions of the box. If None, it is inferred from the box data. Default is None.

Returns:

box – A simulation box in LAMMPS convention.

Return type:

Box

Examples

Convert a HOOMD-blue simulation box to the LAMMPS convention:

hoomd_box = numpy.array([10, 10, 10, 0, 0, 0])
lammps_box = lammpsio.Box.from_hoomd_convention(
    box_data=hoomd_box,
    low=[0, 0, 0]
)

This creates a orthorhombic box of dimensions $L_x = 10, L_y = 10$ and $L_z = 10$ with tilt factors set to (0, 0, 0). If low is None, the box is centered at (0, 0, 0). However, since low is set to (0, 0, 0), the box is centered at (5, 5, 5). The tilt factors are multiplied by $L_y$ for $L_{xy}$ and $L_z$ for $L_{xz}$ and $L_{yz}$ to convert them to the LAMMPS convention.

Note

$L_z$ is changed to one if the input $L_z$ is zero, as LAMMPS does not allow zero height box.

property low¶

Low parameter.

The low of the box is the origin.

Type:: (3,) numpy.ndarray of float

property high¶

High parameter.

The high of the box is used to compute the lengths $L_x$, $L_y$, and $L_z$.

Type:: (3,) numpy.ndarray of float

property tilt¶

Tilt parameters.

The 3 tilt factors, $L_{xy}$, $L_{xz}$, and $L_{yz}$ define the shape of the box. The default of None is strictly orthorhombic, meaning all are zero.

Type:: (3,) numpy.ndarray of float