polyphys.simulate.core#

Shared LAMMPS pieces — polyphys.simulate.core#

The core module holds what the LAMMPS log, dump, and data-file modules of polyphys.simulate share: the simulation box, Box, and LammpsFormatError, the base class of their errors.

Added in version 0.6.0.

The box#

A LAMMPS box has an origin \(\mathbf{o} = (x_{lo}, y_{lo}, z_{lo})\), lengths \(l_x = x_{hi} - x_{lo}\), \(l_y\), and \(l_z\), and, when it is a restricted triclinic box, the tilt factors \(xy\), \(xz\), and \(yz\). Its edge vectors are

\[\mathbf{A} = (l_x, 0, 0), \quad \mathbf{B} = (xy, l_y, 0), \quad \mathbf{C} = (xz, yz, l_z).\]

Scaled coordinates \((s_a, s_b, s_c)\), the fractions of the edge vectors that dumps write as xs ys zs, map to Cartesian coordinates \(\mathbf{r} = \mathbf{o} + s_a \mathbf{A} + s_b \mathbf{B} + s_c \mathbf{C}\), and the image flags \((i_x, i_y, i_z)\) unwrap a wrapped position to \(\mathbf{r} + i_x \mathbf{A} + i_y \mathbf{B} + i_z \mathbf{C}\). In an orthogonal box the tilt factors are zero. Lengths are in the length unit of the run; nothing is converted.

References

The LAMMPS documentation of Howto_triclinic, and these lines of the LAMMPS source, release stable_30Sep2026_update1:

Dependencies#

  • Python standard library: dataclasses, gzip, pathlib

  • Third-party: numpy

Classes

Box(lo, hi[, tilt, boundary, triclinic])

A LAMMPS simulation box, orthogonal or restricted triclinic.

Exceptions

LammpsFormatError

A LAMMPS file is cut off or does not follow its format.

class polyphys.simulate.core.Box(lo, hi, tilt=<factory>, boundary=None, triclinic=False)[source]#

Bases: object

A LAMMPS simulation box, orthogonal or restricted triclinic.

Added in version 0.6.0.

Variables:
  • hi (lo,) – Shape (3,), float64: \((x_{lo}, y_{lo}, z_{lo})\) and \((x_{hi}, y_{hi}, z_{hi})\) of the box itself, with lo below hi, in the length unit of the run. Read-only.

  • tilt (numpy.ndarray) – Shape (3,), float64: the tilt factors \((xy, xz, yz)\); zeros by default. Read-only.

  • boundary (tuple of str or None) – The three boundary flags, such as ('pp', 'pp', 'ff'), as a dump gives them; None when the file does not say, as in a data file.

  • triclinic (bool) – True for a restricted triclinic box, whose tilt factors LAMMPS stores even when they are zero.

Raises:

ValueError – If lo, hi, or tilt does not have shape (3,), lo is not below hi, or an orthogonal box has a non-zero tilt factor.

Parameters:
  • lo (NDArray[float64])

  • hi (NDArray[float64])

  • tilt (NDArray[float64])

  • boundary (tuple[str, str, str] | None)

  • triclinic (bool)

Examples

>>> box = Box(lo=np.zeros(3), hi=np.full(3, 6.0),
...           tilt=np.array([1.0, 0.5, -0.5]), triclinic=True)
>>> box.lengths
array([6., 6., 6.])
>>> box.edges()
array([[ 6. ,  0. ,  0. ],
       [ 1. ,  6. ,  0. ],
       [ 0.5, -0.5,  6. ]])
boundary: tuple[str, str, str] | None = None#
edges()[source]#

Return the box edge vectors as the rows of a matrix.

Returns:

Shape (3, 3), float64: the rows are \(\mathbf{A} = (l_x, 0, 0)\), \(\mathbf{B} = (xy, l_y, 0)\), and \(\mathbf{C} = (xz, yz, l_z)\).

Return type:

numpy.typing.NDArray[numpy.double]

hi: numpy.typing.NDArray[numpy.float64]#
property lengths: numpy.typing.NDArray[numpy.float64]#

The box lengths \((l_x, l_y, l_z)\), hi minus lo.

lo: numpy.typing.NDArray[numpy.float64]#
tilt: numpy.typing.NDArray[numpy.float64]#
to_cartesian(scaled)[source]#

Return Cartesian coordinates of scaled coordinates.

Parameters:

scaled (numpy.typing.ArrayLike) – Shape (n_atoms, 3): the fractions \((s_a, s_b, s_c)\) of the edge vectors, as in the xs ys zs or xsu ysu zsu columns of a dump.

Returns:

Shape (n_atoms, 3), float64: \(\mathbf{o} + s_a \mathbf{A} + s_b \mathbf{B} + s_c \mathbf{C}\). Time and memory are \(O(n_a)\) for \(n_a\) atoms.

Return type:

numpy.typing.NDArray[numpy.double]

Examples

>>> box = Box(lo=np.array([1.0, 0.0, 0.0]),
...           hi=np.array([5.0, 4.0, 4.0]))
>>> box.to_cartesian([[0.5, 0.25, 0.0]])
array([[3., 1., 0.]])
triclinic: bool = False#
unwrap(positions, image)[source]#

Return wrapped positions unwrapped by their image flags.

Parameters:
Returns:

Shape (n_atoms, 3), float64: \(\mathbf{r} + i_x \mathbf{A} + i_y \mathbf{B} + i_z \mathbf{C}\). Time and memory are \(O(n_a)\).

Return type:

numpy.typing.NDArray[numpy.double]

Examples

>>> box = Box(lo=np.zeros(3), hi=np.full(3, 10.0))
>>> box.unwrap([[9.5, 5.0, 5.0]], [[-1, 0, 0]])
array([[-0.5,  5. ,  5. ]])
exception polyphys.simulate.core.LammpsFormatError[source]#

Bases: ValueError

A LAMMPS file is cut off or does not follow its format.

The base class of BrokenLogError, BrokenDumpError, and BrokenDataError, so one except clause catches a broken file of any of the three kinds. It is a ValueError.

Added in version 0.6.0.