mythos.utils.math
=================

.. py:module:: mythos.utils.math

.. autoapi-nested-parse::

   Math utilities for DNA sequence analysis.



Functions
---------

.. autoapisummary::

   mythos.utils.math.principal_axes_to_euler_angles
   mythos.utils.math.euler_angles_to_quaternion
   mythos.utils.math.smooth_abs
   mythos.utils.math.clamp
   mythos.utils.math.mult


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

.. py:function:: principal_axes_to_euler_angles(x: mythos.utils.types.Arr_Nucleotide_3, y: mythos.utils.types.Arr_Nucleotide_3, z: mythos.utils.types.Arr_Nucleotide_3) -> tuple[mythos.utils.types.Arr_Nucleotide, mythos.utils.types.Arr_Nucleotide, mythos.utils.types.Arr_Nucleotide]

   Convert principal axes to Tait-Bryan Euler angles.

   A utility function for converting a set of principal axes
   (that define a rotation matrix) to a commonly used set of
   Tait-Bryan Euler angles.

   There are two options to compute the Tait-Bryan angles. Each can be seen at the respective links:
   (1) From wikipedia (under Tait-Bryan angles): https://en.wikipedia.org/wiki/Euler_angles
   (2) Equation 10A-C: https://danceswithcode.net/engineeringnotes/rotations_in_3d/rotations_in_3d_part1.html

   However, note that the definition from Wikipedia (i.e. the one using arcsin) has numerical stability issues,
   so we use the definition from (2) (i.e. the one using arctan2)

   Note that if we were following (1), we would do:
   psi = onp.arcsin(x[1] / onp.sqrt(1 - x[2]**2))
   theta = onp.arcsin(-x[2])
   phi = onp.arcsin(y[2] / onp.sqrt(1 - x[2]**2))

   Note that Tait-Bryan (i.e. Cardan) angles are *not* proper euler angles


.. py:function:: euler_angles_to_quaternion(psi: mythos.utils.types.Arr_Nucleotide, theta: mythos.utils.types.Arr_Nucleotide, phi: mythos.utils.types.Arr_Nucleotide) -> mythos.utils.types.Arr_Nucleotide_4

   Convert Euler angles to quaternions.

   A utility function for converting euler angles to quaternions.
   Used when converting a trajectory DataFrame to a set of states.

   We follow the ZYX convention. For details, see page A-11 in
   https://ntrs.nasa.gov/api/citations/19770024290/downloads/19770024290.pdf
   from the following set of documentation:
   https://ntrs.nasa.gov/citations/19770024290


.. py:function:: smooth_abs(x: mythos.utils.types.ARR_OR_SCALAR, eps: mythos.utils.types.Scalar = 1e-10) -> mythos.utils.types.ARR_OR_SCALAR

   A smooth absolute value function.

   Note that a non-zero eps gives continuous first dervatives.

   https://math.stackexchange.com/questions/1172472/differentiable-approximation-of-the-absolute-value-function


.. py:function:: clamp(x: mythos.utils.types.ARR_OR_SCALAR, lo: mythos.utils.types.Scalar = -1.0, hi: mythos.utils.types.Scalar = 1.0) -> mythos.utils.types.ARR_OR_SCALAR

   Clamp a value between two values.


.. py:function:: mult(a: mythos.utils.types.Arr_N, b: mythos.utils.types.Arr_N) -> mythos.utils.types.Arr_N

   Element-wise multiplication of two arrays w/ sum reduction.