mythos.energy.martini.base
==========================

.. py:module:: mythos.energy.martini.base

.. autoapi-nested-parse::

   Common Martini Energy Utilities.



Classes
-------

.. autoapisummary::

   mythos.energy.martini.base.MartiniTopology
   mythos.energy.martini.base.MartiniEnergyFunction
   mythos.energy.martini.base.MartiniEnergyConfiguration


Functions
---------

.. autoapisummary::

   mythos.energy.martini.base.get_periodic
   mythos.energy.martini.base.derive_bond_names
   mythos.energy.martini.base.derive_angle_names


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

.. py:function:: get_periodic(box_size: mythos.utils.types.Vector3D) -> callable

   Return displacement function given box_size.


.. py:function:: derive_bond_names(residue_names: tuple[str, Ellipsis], atom_names: tuple[str, Ellipsis], bonded_neighbors: mythos.utils.types.Arr_N) -> tuple[str, Ellipsis]

   Derive bond names aligned with *bonded_neighbors*.

   Each name has the form ``RESIDUE_BEAD1_BEAD2``, e.g. ``DMPC_GL1_GL2``.


.. py:function:: derive_angle_names(residue_names: tuple[str, Ellipsis], atom_names: tuple[str, Ellipsis], angles: mythos.utils.types.Arr_N) -> tuple[str, Ellipsis]

   Derive angle names aligned with *angles*.

   Each name has the form ``RESIDUE_BEAD1_BEAD2_BEAD3``,
   e.g. ``DMPC_NC3_PO4_GL1``.


.. py:class:: MartiniTopology

   Class representing the topology of a Martini system.

   This class contains information about the atom types, bonded interactions,
   and angles in the system. It can be used to construct energy functions and
   to interpret simulation results.

   .. attribute:: atom_types

      A tuple of atom type names.

   .. attribute:: atom_names

      A tuple of atom names.

   .. attribute:: residue_names

      A tuple of residue names.

   .. attribute:: angles

      An array of shape (n_angles, 3) containing the indices of the
      atoms involved in each angle.

   .. attribute:: bonded_neighbors

      An array of shape (n_bonds, 2) containing the indices
      of the bonded pairs of atoms.


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


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


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


   .. py:attribute:: angles
      :type:  mythos.utils.types.Arr_N


   .. py:attribute:: bonded_neighbors
      :type:  mythos.utils.types.Arr_N


   .. py:method:: from_universe(universe: MDAnalysis.Universe) -> MartiniTopology
      :classmethod:


      Create a MartiniTopology from a Universe object.



   .. py:method:: from_tpr(tpr_file: pathlib.Path) -> MartiniTopology
      :classmethod:


      Create a MartiniTopology from a TPR format topology file.



   .. py:property:: bond_names
      :type: tuple[str, Ellipsis]


      Return bond names based on atom names and bonded neighbors.


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


      Return angle names based on atom names and angles.


.. py:class:: MartiniEnergyFunction

   Bases: :py:obj:`mythos.energy.base.BaseEnergyFunction`


   Base class for Martini energy functions.


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


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


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


   .. py:attribute:: angles
      :type:  mythos.utils.types.Arr_N


   .. py:attribute:: displacement_fn
      :type:  callable


   .. py:method:: __post_init__(topology: None = None) -> None


   .. py:method:: from_topology(topology: MartiniTopology, **kwargs) -> MartiniEnergyFunction
      :classmethod:


      Create an energy function from a MartiniTopology.



   .. py:property:: bond_names
      :type: tuple[str, Ellipsis]


      Return bond names based on atom names and bonded neighbors.


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


      Return angle names based on atom names and angles.


.. py:class:: MartiniEnergyConfiguration(couplings: dict[str, list[str]] | None = None, **kwargs)

   Base class for Martini energy function configurations.

   Given the large size and sparse inclusion of parameters in Martini models,
   this class implements parameters as a dictionary while supporting operations
   of configuration classes used in EnergyFunction.

   This class also supports parameter coupling, where a single proxy parameter
   controls multiple underlying parameters. Couplings should be provided as a
   dictionary of lists, where each key is a proxy parameter name and the value
   is a list of target parameter names that it controls. The `params` field of
   this will be populated with the expanded parameters.

   Subclasses can override `__post_init__` for additional initialization logic.
   Parameters will be available in `self.params` after initialization.


   .. py:attribute:: couplings


   .. py:attribute:: reversed_couplings


   .. py:attribute:: params


   .. py:method:: __post_init__() -> None

      Hook for additional initialization in subclasses.



   .. py:method:: init_params() -> MartiniEnergyConfiguration

      Dependent params initialization. Default to no-op.



   .. py:property:: opt_params
      :type: dict[str, any]


      Returns the parameters to optimize.


   .. py:method:: __getitem__(key: str) -> any


   .. py:method:: __contains__(key: str) -> bool


   .. py:method:: __or__(other: MartiniEnergyConfiguration) -> MartiniEnergyConfiguration

      Merge two configurations, with `other` taking precedence.