convert_cell_representation

mdcraft.lib.cell.convert_cell_representation(box_size: np.ndarray[float_t] | 'unit.Quantity' | Q_, output_format: str, /, *, n_dimensions: int | None = None) → np.ndarray[float_t] | 'unit.Quantity' | Q_[source]

Converts between cell representations for a box.

Two-dimensional (2D) systems

For a square box, the supported input and output formats are

  • its dimensions \((L_x,L_y)\), where \(L_x\) and \(L_y\) are the lengths along the \(x\)- and \(y\)-axes, respectively,

  • its lattice parameters \((a,b,\gamma)\), where \(a\) and \(b\) are the cell lengths and \(\gamma\) is the cell angle, and

  • its box vectors \((\mathbf{a};\mathbf{b})\).

Three-dimensional (3D) systems

For a cubic box, the supported input and output formats are

  • its dimensions \((L_x,L_y,L_z)\), where \(L_x\), \(L_y\), and \(L_z\) are the lengths along the \(x\)-, \(y\)-, and \(z\)-axes, respectively,

  • its lattice parameters \((a,b,c,\alpha,\beta,\gamma)\), where \(a\), \(b\), and \(c\) are the cell lengths and \(\alpha\), \(\beta\), and \(\gamma\) are the cell angles, and

  • its box vectors \((\mathbf{a};\mathbf{b};\mathbf{c})\).

Parameters:
box_sizenumpy.ndarray, openmm.unit.Quantity, or pint.Quantity, positional-only

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.

output_formatstr, positional-only

Desired cell representation.

Valid values:

  • "dimensions" for dimensions,

  • "parameters" for lattice parameters, or

  • "vectors" for box vectors.

n_dimensionsint, keyword-only, optional

Dimensionality of the box \(d\). Only used when box_size has shape \((3,)\).

Valid values: 2 or 3.

Returns:
new_representationnumpy.ndarray, openmm.unit.Quantity, or pint.Quantity

Cell representation in the desired format.

Note

Lattice parameters will always be returned in an array without explicit units, even if the starting cell representation is an OpenMM or Pint quantity.

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

Units: Same as those of box_size.

Examples

Let us start with a cubic simulation box with dimensions \((3,4,5)~\mathrm{nm}\):

>>> dimensions = np.array((3.0, 4.0, 5.0))

We can convert the dimensions to lattice parameters using

>>> convert_cell_representation(dimensions, "parameters")
array([3., 4., 5., 90., 90., 90.])

Alternatively, we can convert the dimensions to box vectors using

>>> convert_cell_representation(dimensions, "vectors")
array([[3., 0., 0.],
       [0., 4., 0.],
       [0., 0., 5.]])

If the dimensions are provided as an OpenMM or Pint quantity, the output will have units attached:

>>> convert_cell_representation(dimensions * unit.nanometer, "vectors")
Quantity(value=array([[3., 0., 0.],
       [0., 4., 0.],
       [0., 0., 5.]]), unit=nanometer)