mythos.observables.persistence_length
=====================================

.. py:module:: mythos.observables.persistence_length

.. autoapi-nested-parse::

   Persistence length observable.



Attributes
----------

.. autoapisummary::

   mythos.observables.persistence_length.TARGETS
   mythos.observables.persistence_length.get_all_l_vectors


Classes
-------

.. autoapisummary::

   mythos.observables.persistence_length.PersistenceLength


Functions
---------

.. autoapisummary::

   mythos.observables.persistence_length.persistence_length_fit
   mythos.observables.persistence_length.vector_autocorrelate
   mythos.observables.persistence_length.compute_metadata


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

.. py:data:: TARGETS

.. py:function:: persistence_length_fit(correlations: jax.numpy.ndarray, l0_av: float) -> tuple[float, float]

   Computes the Lp given correlations in alignment decay and average distance between base pairs.

   Lp obeys the following equality: `<l_n * l_0> = exp(-n<l_0> / Lp)`, where `<l_n * l_0>` represents the
   average correlation between adjacent base pairs (`l_0`) and base pairs separated by a distance of
   `n` base pairs (`l_n`). This relationship is linear in log space, `log(<l_n * l_0>) = -n<l_0> / Lp`.
   So, given the average correlations across distances and the average distance between adjacent base pairs,
   we compute Lp via a linear fit.

   :param correlations: a (max_dist,) array containing the average correlation between
                        base pairs separated by distances up to `max_dist`
   :type correlations: jnp.ndarray
   :param l0_av: the average distance between adjacent base pairs
   :type l0_av: jnp.ndarray


.. py:function:: vector_autocorrelate(vecs: jax.numpy.ndarray) -> jax.numpy.ndarray

   Computes the average correlations in alignment decay between a list of vector.

   Given an ordered list of n vectors (representing vectors between adjacent
   base pairs), computes the average correlation between all pairs of vectors
   separated by a distance `d` for all distances `d < n`. Note that multiple
   pairs of vectors are included for all values < n-1.

   :param vecs: a (n, 3) array of vectors corresponding to
                displacements between midpoints of adjacent base pairs.
   :type vecs: jnp.ndarray


.. py:data:: get_all_l_vectors

.. py:function:: compute_metadata(base_sites: jax.numpy.ndarray, quartets: jax.numpy.ndarray, displacement_fn: collections.abc.Callable, skip_ends: bool) -> tuple[jax.numpy.ndarray, float]

   Computes (i) average correlations in alignment decay and (ii) average distance between base pairs.


.. py:class:: PersistenceLength

   Bases: :py:obj:`mythos.observables.base.BaseObservable`


   Computes the persistence length (Lp) from a trajectory.

   To model Lp, we assume an infinitely long, semi-flexible polymer, in which
   correlations in alignment decay exponentially with separation. So, to
   compute Lp, we need the average correlations across many states, as well as
   the average distance between adjacent base pairs. This observable computes
   these two quantities for a single state, and the average of these quantities
   across a trajectory can be postprocessed to compute a value for Lp.

   The callable of this class computes the weighted fitted Lp for a trajectory,
   while the `lp_fit` method computes the fitted Lp and offset. The
   `get_all_corrs_and_l0s` method computes the correlations and average
   distance between adjacent base pairs for each state in a trajectory.

   :param quartets: a (n_bp-1, 2, 2) array containing the pairs of adjacent base
   :param pairs: for which to compute the Lp
   :param displacement_fn: a function for computing displacements between two
                           positions
   :param truncate: if provided, only consider correlations up to this distance
   :param skip_ends: if True, skip the first two and last two quartets when
   :param computing:


   .. py:attribute:: quartets
      :type:  jax.numpy.ndarray


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


   .. py:attribute:: truncate
      :type:  int | None
      :value: None



   .. py:attribute:: skip_ends
      :type:  bool
      :value: True



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

      Validate the input.



   .. py:method:: __call__(trajectory: mythos.simulators.io.SimulatorTrajectory, weights: jax.numpy.ndarray | None = None) -> float

      Calculate the fitted persistence length for a trajectory.

      :param trajectory: the trajectory to calculate the persistence length for
      :param weights: if provided, a (n_states,) array of weights to apply to
                      correlations

      :returns: the fitted persistence length



   .. py:method:: lp_fit(trajectory: mythos.simulators.io.SimulatorTrajectory, weights: jax.numpy.ndarray | None = None) -> tuple[float, float]

      Calculate the fitted persistence length and offset for a trajectory.

      See arguments for `__call__`.

      :returns: the fitted persistence length and offset



   .. py:method:: get_all_corrs_and_l0s(trajectory: mythos.simulators.io.SimulatorTrajectory) -> tuple[jax.numpy.ndarray, mythos.utils.types.ARR_OR_SCALAR]

      Calculate alignment decay and average distance correlations for adjacent base pairs.

      :param trajectory: the trajectory to calculate the persistence length for

      :returns: tuple of (correlations, decay) the correlations in alignment decay
                and the the average distance between adjacent base pairs for each
                state. The former will have shape (n_states, n_quartets-1) and the
                latter will have shape (n_states,).