polymerist.mdtools.openfftools.boxvectors
=========================================

.. py:module:: polymerist.mdtools.openfftools.boxvectors

.. autoapi-nested-parse::

   For obtaining, scaling, and manipulating box vectors for Topologies



Attributes
----------

.. autoapisummary::

   polymerist.mdtools.openfftools.boxvectors.Vector
   polymerist.mdtools.openfftools.boxvectors.VectorQuantity
   polymerist.mdtools.openfftools.boxvectors.BoxVectors
   polymerist.mdtools.openfftools.boxvectors.BoxVectorsQuantity


Exceptions
----------

.. autoapisummary::

   polymerist.mdtools.openfftools.boxvectors.BoxVectorError


Functions
---------

.. autoapisummary::

   polymerist.mdtools.openfftools.boxvectors.xyz_to_box_vectors
   polymerist.mdtools.openfftools.boxvectors.get_topology_bbox
   polymerist.mdtools.openfftools.boxvectors.pad_box_vectors
   polymerist.mdtools.openfftools.boxvectors.pad_box_vectors_uniform
   polymerist.mdtools.openfftools.boxvectors.box_vectors_flexible
   polymerist.mdtools.openfftools.boxvectors.get_box_volume
   polymerist.mdtools.openfftools.boxvectors.encloses_box_vectors


Module Contents
---------------

.. py:data:: Vector

.. py:data:: VectorQuantity

.. py:data:: BoxVectors

.. py:data:: BoxVectorsQuantity

.. py:exception:: BoxVectorError

   Bases: :py:obj:`Exception`


   Raised when a provided set of box vectors is invalid (for whatever reason)


.. py:function:: xyz_to_box_vectors(xyz: VectorQuantity) -> BoxVectorsQuantity

   Convert 3-vector of XYZ box dimensions into monoclinic box vectors in 3x3 diagonal reduced form

   :Parameters: **xyz** (*VectorQuantity*) -- 3-element vector with associated units whose components
                indicate the length of the box in the x, y, and z directions

   :returns: **box_vectors** -- A 3x3 matrix with associated units (same units as input vector)
             representing the monoclinic box vectors in reduced form
   :rtype: BoxVectorsQuantity


.. py:function:: get_topology_bbox(offtop: openff.toolkit.Topology) -> BoxVectorsQuantity

   Get the tight bounding box of an OpenFF Topology

   :Parameters: **offtop** (*Topology*) -- An OpenFF Topology

   :returns: **box_vectors** -- The unit-aware box vectors representing the smallest monoclinic
             bounding box which contains all atoms in the Topology
   :rtype: BoxVectorsQuantity


.. py:function:: pad_box_vectors(box_vectors: BoxVectorsQuantity, pad_vec: VectorQuantity) -> BoxVectorsQuantity

   Pad an array of box vectors by some fixed distance from each face
   Padding amount is set for each axis separately (i.e. x, y, and z)

   :Parameters: * **box_vectors** (*BoxVectorsQuantity*) -- The unit-aware box vectors array to pad
                * **pad_vec** (*VectorQuantity*) -- The padding vector specifying the amount to pad each pair of faces along each axis

                  E.g. a vector of np.array([1, 2, 3])*nanometer would pad the faces perpendicular to
                  the x axis by 1 nm, perpendicular to the y axis by 2 nm, and the z-axis by 3 nm
                  The lengths of the edges of the box would increase by 2, 4, and 6 nm along the x, y, and z axes, respectively

   :returns: **box_vectors** -- The padded box vectors
   :rtype: BoxVectorsQuantity


.. py:function:: pad_box_vectors_uniform(box_vectors: BoxVectorsQuantity, pad_amount: openmm.unit.Quantity) -> BoxVectorsQuantity

   Pad an array of box vectors by a fixed distance from each face of the box

   :Parameters: * **box_vectors** (*BoxVectorsQuantity*) -- The unit-aware box vectors array to pad
                * **pad_amount** (*Quantity*) -- The distance to pad out from each face of the box

                  For a box with initial dimensions (Lx, Ly, Lz), the dimensions of the box returned
                  after padding here will be (Lx + 2*pad_amount, Ly + 2*pad_amount, Lz + 2*pad_amount)

   :returns: **box_vectors** -- The padded box vectors
   :rtype: BoxVectorsQuantity


.. py:function:: box_vectors_flexible(box_vecs: Union[VectorQuantity, BoxVectorsQuantity]) -> BoxVectorsQuantity

   Allows for passing XYZ box dimensions


.. py:function:: get_box_volume(box_vectors: BoxVectorsQuantity, units_as_openm: bool = True) -> openmm.unit.Quantity

   Compute volume of a box given a set of 3x3 box vectors


.. py:function:: encloses_box_vectors(outer_box_vectors: BoxVectorsQuantity, inner_box_vectors: BoxVectorsQuantity) -> bool

   Check whether the unit cell defined by the inner box vectors is completely contained within the outer box vectors