scale_coordinates

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

Scales the Cartesian coordinates of entities in a general parallelogram or triclinic box to get the fractional coordinates.

The relationship between Cartesian coordinates \(\mathbf{r}\) and the fractional coordinates \(\mathbf{f}\) can be described by the matrix transformation \(\mathbf{r}=\mathbf{h}\mathbf{f}\), where

Two-dimensional systems

\(\mathbf{h}\) is the cell tensor (matrix of box vectors \(\mathrm{A}\) and \(\mathrm{B}\)):

\[\begin{split}\begin{pmatrix}r_x\\r_y\end{pmatrix} =\begin{pmatrix}A_x&A_y\\B_x&B_y\end{pmatrix} \begin{pmatrix}f_x\\f_y\end{pmatrix}.\end{split}\]

Three-dimensional systems

\(\mathbf{h}\) is the cell tensor (matrix of box vectors \(\mathrm{A}\), \(\mathrm{B}\), and \(\mathrm{C}\)):

\[\begin{split}\begin{pmatrix}r_x\\r_y\\r_z\end{pmatrix} =\begin{pmatrix}A_x&A_y&A_z\\B_x&B_y&B_z\\C_x&C_y&C_z \end{pmatrix}\begin{pmatrix}f_x\\f_y\\f_z\end{pmatrix}.\end{split}\]

As such, the Cartesian coordinates can be scaled to fractional coordinates using \(\mathbf{f}=\mathbf{h}^{-1}\mathbf{r}\).

Parameters:

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

Cartesian 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.

scaled_flagsarray-like, optional

Flags indicating whether the coordinates are already scaled along the respective axes. If not provided, all flags are assumed to be False.

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:

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

Scaled coordinates. Only returned when in_place=False.

Shape: Same as coordinates.

Examples

Let us start with the coordinates of two entities in a general triclinic simulation box:

>>> coordinates = np.array(
...     (
...         (2.2613350843332274, 1.6329931618554523, -0.6154574548966636),
...         (1.899521470839911, 2.0684580050169066, -1.1488539158071056)
...     )
... )
>>> box_vectors = np.array(
...     (
...         (9 / np.sqrt(11), 3 / np.sqrt(11), 3 / np.sqrt(11)),
...         (-4 / np.sqrt(6), 8 / np.sqrt(6), 4 / np.sqrt(6)),
...         (5 / np.sqrt(66), 20 / np.sqrt(66), -35 / np.sqrt(66))
...     )
... )

We can scale the coordinates to get the fractional coordinates:

>>> scale_coordinates(coordinates, box_vectors)
>>> coordinates
array([[0.5       , 0.5       , 0.5       ],
       [0.33333333, 0.5       , 0.6       ]])

Now, let us assume that the coordinates are already scaled along the \(z\)-axis. We can scale the coordinates in just the \(x\)- and \(y\)-axes:

>>> coordinates = np.array(
...     (
...         (2.2613350843332274, 1.6329931618554523, 0.5),
...         (1.899521470839911, 2.0684580050169066, 0.6)
...     )
... )
>>> scale_coordinates(coordinates, box_vectors, (False, False, True))
>>> coordinate
array([[0.5       , 0.5       , 0.5       ],
       [0.33333333, 0.5       , 0.6       ])

Finally, let us assume that the coordinates are already scaled along the \(x\)- and \(z\)-axes. We can scale the coordinates in just the \(y\)-axis:

>>> coordinates = np.array(
...     (
...         (0.5, 1.6329931618554523, 0.5),
...         (1 / 3, 2.0684580050169066, 0.6)
...     )
... )
>>> scale_coordinates(coordinates, box_vectors, (True, False, True))
>>> coordinates
array([[0.5       , 0.5       , 0.5       ],
       [0.33333333, 0.5       , 0.6       ])