wrap_coordinates

mdcraft.lib.cell.wrap_coordinates(coordinates: np.ndarray[float_t], box_size: np.ndarray[float_t] | 'unit.Quantity' | Q_, wrap_flags: np.ndarray[np.bool_] | None = None, *, in_place: bool = True) → None | np.ndarray[float_t] | 'unit.Quantity' | Q_

Wraps the coordinates of entities into a general parallelogram or triclinic unit cell.

Given coordinates \(\mathbf{r}\) and cell tensor \(\mathbf{h}\) consisting of the box vectors \((\mathbf{a};\mathbf{b}[;\mathbf{c}])\), the wrapped coordinates can be computed using

\[\mathbf{r}_{\mathrm{wrapped}}=\mathbf{h} \left([\mathbf{h}^{-1}\mathbf{r}]\bmod1\right).\]

Parameters:

coordinatesnumpy.ndarray, openmm.unit.Quantity, or pint.Quantity

Coordinates \(\mathrm{r}\) of \(N\) entities.

Shape: \((N,d)\), where \(d\in\{2,3\}\) is the dimensionality.

Reference unit: \(\mathrm{nm}\).

box_sizenumpy.ndarray, openmm.unit.Quantity, or pint.Quantity

Dimensions \((L_x,L_y[,L_z])\), lattice parameters \((a,b[,c,\alpha,\beta],\gamma)\), or box vectors \((\mathbf{a};\mathbf{b}[;\mathbf{c}])\).

Note

Lattice parameters should always be provided in an array without explicit units.

Shapes: \((d,)\) for dimensions, \((3,)\) (2D) or \((6,)\) (3D) for lattice parameters, or \((d,d)\) for box vectors.

Reference units: \(\mathrm{nm}\) for lengths and degrees (\(^\circ\)) for angles.

wrap_flagsarray-like, optional

Flags indicating whether the coordinates should be wrapped along the respective axes. If not provided, all flags are assumed to be True.

Shape: \((d,)\).

in_placebool, keyword-only, default: True

Specifies whether to modify the coordinates array in-place. If True, coordinates must be a NumPy array.

Returns:

wrapped_coordinatesnumpy.ndarray, openmm.unit.Quantity, or pint.Quantity

Wrapped coordinates. Only returned when in_place=False.

Shape: Same as coordinates.

Unit: Same as coordinates.