fluopy.kappa_squared
====================

.. py:module:: fluopy.kappa_squared

.. autoapi-nested-parse::

   Compute rotational effects expressed by κ².



Functions
---------

.. autoapisummary::

   fluopy.kappa_squared.simulate_rotational_motion
   fluopy.kappa_squared.kappa_squared
   fluopy.kappa_squared.integral_kappa_squared
   fluopy.kappa_squared.sample_kappa_squared_distribution


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

.. py:function:: simulate_rotational_motion(tau_rot: float, tau_life: float, dt: float = 1e-12, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

   Simulate rotational motion and return dipole orientations over the lifetime.

   :param tau_rot: The rotational diffusion time constant in s.
   :param tau_life: The lifetime of the dipole in s.
   :param dt: The time step for the simulation in s.
   :param seed: Seed.

   :returns: Two arrays containing the dipole orientations over time for two dipoles.
             Of length int(tau_life / dt).
   :rtype: tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]


.. py:function:: kappa_squared(d: numpy.typing.ArrayLike, a: numpy.typing.ArrayLike, r: numpy.typing.ArrayLike) -> numpy.typing.NDArray[numpy.float64]

   Calculate dipole orientation factor κ² for arrays of vectors.

   :param d: Donor dipole vectors of shape (N, 3).
   :param a: Acceptor dipole vectors of shape (N, 3).
   :param r: Unit vector from donor to acceptor of shape (N, 3).

   :returns: The value of κ² calculated from the input vectors.
   :rtype: npt.NDArray[np.float64]


.. py:function:: integral_kappa_squared(traj1: numpy.typing.ArrayLike, traj2: numpy.typing.ArrayLike, dt: float, r: numpy.typing.ArrayLike | None = None) -> float

   Calculate the time-averaged κ² using trapezoidal integration.

   :param traj1: Array of dipole orientations for the first dipole. Shape (N, 3).
   :param traj2: Array of dipole orientations for the second dipole. Shape (N, 3).
   :param dt: The time step for the simulation in s.
   :param r: Unit vector from donor to acceptor. If None, assumes z-axis [0, 0, 1].

   :returns: The time-averaged value of κ².
   :rtype: float


.. py:function:: sample_kappa_squared_distribution(k2_values: numpy.typing.ArrayLike, size: int = 100, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> numpy.typing.NDArray[numpy.float64]

   Sample from the distribution of κ² values utilizing Gaussian kernel-density
   estimation and logit transformation.

   :param k2_values: Array of κ² values between 0 and 4.
   :param size: Number of samples to generate.
   :param seed: A seed to initialize the BitGenerator.

   :returns: Samples from the κ² distribution.
   :rtype: npt.NDArray[np.float64]