mythos.observables.triplet_angles
=================================

.. py:module:: mythos.observables.triplet_angles

.. autoapi-nested-parse::

   Observable for computing angles between atom triplets from a Martini trajectory.



Classes
-------

.. autoapisummary::

   mythos.observables.triplet_angles.TripletAngles
   mythos.observables.triplet_angles.TripletAnglesMapped


Functions
---------

.. autoapisummary::

   mythos.observables.triplet_angles._triplet_angle


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

.. py:function:: _triplet_angle(centers: jax.numpy.ndarray, triplet: jax.numpy.ndarray, displacement_fn: collections.abc.Callable) -> float

   Compute the angle (in radians) at the central atom of a triplet.

   The angle is measured at atom ``j`` between rays ``j→i`` and ``j→k``.

   :param centers: Positions of all atoms, shape ``(n_atoms, 3)``.
   :param triplet: Array of three atom indices ``[i, j, k]``.
   :param displacement_fn: Displacement function respecting boundary conditions.

   :returns: Angle in radians.


.. py:class:: TripletAngles

   Observable for computing angles between atom triplets for a single angle name.

   Given a :class:`MartiniTopology` and an angle name, this observable computes
   the angle at the central atom for all matching triplets across the trajectory.

   .. attribute:: topology

      The Martini topology containing angle information.

   .. attribute:: angle_name

      Angle name string to compute angles for.
      Has the form ``RESIDUE_BEAD1_BEAD2_BEAD3`` (e.g.
      ``"DMPC_NC3_PO4_GL1"``).  All angles in the topology matching
      this name will be included in the output.

   .. attribute:: displacement_fn

      Factory that, given a box size vector, returns a
      displacement function respecting periodic boundary conditions.


   .. py:attribute:: topology
      :type:  mythos.energy.martini.base.MartiniTopology


   .. py:attribute:: angle_name
      :type:  str


   .. py:attribute:: displacement_fn
      :type:  collections.abc.Callable


   .. py:method:: _matching_triplets() -> jax.numpy.ndarray

      Return topology angle rows whose derived name matches the angle name.

      :returns: Array of shape ``(n_matching, 3)`` with atom-index triplets.

      :raises ValueError: If no angles in the topology match the angle name.



   .. py:method:: __call__(trajectory: mythos.simulators.io.SimulatorTrajectory) -> jax.numpy.ndarray

      Compute angles for the requested angle name.

      :param trajectory: A :class:`SimulatorTrajectory` whose ``center`` has
                         shape ``(n_states, n_atoms, 3)`` and ``box_size`` has shape
                         ``(n_states, 3)``.

      :returns: Array of angles (in radians) with shape
                ``(n_states, n_matching_angles)``.



.. py:class:: TripletAnglesMapped

   Observable for computing angles between atom triplets for multiple angle names.

   Given a :class:`MartiniTopology` and a set of angle names, this observable
   computes the angle at the central atom for all matching triplets across the
   trajectory, returning a dictionary keyed by angle name.

   .. attribute:: topology

      The Martini topology containing angle information.

   .. attribute:: angle_names

      Tuple of angle name strings to compute angles for.
      Each name has the form ``RESIDUE_BEAD1_BEAD2_BEAD3`` (e.g.
      ``"DMPC_NC3_PO4_GL1"``).  All angles in the topology matching a
      given name will be included in the output.

   .. attribute:: displacement_fn

      Factory that, given a box size vector, returns a
      displacement function respecting periodic boundary conditions.


   .. py:attribute:: topology
      :type:  mythos.energy.martini.base.MartiniTopology


   .. py:attribute:: angle_names
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: displacement_fn
      :type:  collections.abc.Callable


   .. py:method:: __call__(trajectory: mythos.simulators.io.SimulatorTrajectory) -> dict[str, jax.numpy.ndarray]

      Compute angles for each requested angle name.

      :param trajectory: A :class:`SimulatorTrajectory` whose ``center`` has
                         shape ``(n_states, n_atoms, 3)`` and ``box_size`` has shape
                         ``(n_states, 3)``.

      :returns: Dictionary mapping each angle name to an array of angles (in
                radians) with shape ``(n_states, n_matching_angles)``.