GWForge.population.spin
=======================

.. py:module:: GWForge.population.spin


Attributes
----------

.. autoapisummary::

   GWForge.population.spin.choices
   GWForge.population.spin.DEFAULT_BBH_SPIN_PARAMETERS
   GWForge.population.spin.DEFAULT_PARAMETERS


Classes
-------

.. autoapisummary::

   GWForge.population.spin.Spin


Functions
---------

.. autoapisummary::

   GWForge.population.spin.truncated_normal
   GWForge.population.spin.default_spin_magnitude_density
   GWForge.population.spin.default_spin_tilt_density


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

.. py:data:: choices
   :value: ['Non-spinning', 'Aligned', 'Aligned-Bilby', 'Aligned-Uniform', 'Beta-Aligned',...


.. py:data:: DEFAULT_BBH_SPIN_PARAMETERS

.. py:function:: truncated_normal(value, mu, sigma, low, high)

   Truncated-normal density and its log-derivatives in ``mu`` and ``sigma``.

   The kernel both halves of the ``Default`` BBH spin model are built from: the
   magnitudes are one of these on :math:`[0, a_{\max}]`, and the cos-tilt
   mixture's Gaussian component is one on :math:`[t_{\min}, 1]`.

   With :math:`z = (x-\mu)/\sigma`, :math:`a = (\text{low}-\mu)/\sigma`,
   :math:`b = (\text{high}-\mu)/\sigma` and :math:`D = \Phi(b) - \Phi(a)`,

   .. math::

      \frac{\partial \ln N}{\partial \mu}
        = \frac{z}{\sigma} - \frac{\phi(a) - \phi(b)}{\sigma D},
      \qquad
      \frac{\partial \ln N}{\partial \sigma}
        = \frac{z^2 - 1}{\sigma} - \frac{a\phi(a) - b\phi(b)}{\sigma D}.

   :param value:
   :type value: array_like
   :param mu:
   :type mu: float
   :param sigma:
   :type sigma: float
   :param low:
   :type low: float
   :param high:
   :type high: float

   :returns: ``{"density": ..., "mu": ..., "sigma": ...}``, the latter two being
             ``d ln N / d mu`` and ``d ln N / d sigma``. ``density`` is zero outside
             ``[low, high]``.
   :rtype: dict


.. py:function:: default_spin_magnitude_density(magnitude, mu_chi, sigma_chi, amax=1.0)

   ``p(chi)`` for the ``Default`` BBH model: Eq. B15 of arXiv:2605.27226.

   A truncated Gaussian :math:`N_{[0, a_{\max}]}(\mu_\chi, \sigma_\chi)`, the
   same for both components. ``sigma_chi`` is a **standard deviation**; the Beta
   models take a variance and are a different model.


.. py:function:: default_spin_tilt_density(cosine, mu_t, sigma_t, xi_spin, t_min=-1.0)

   The **marginal** ``p(cos t)`` of one component: Eq. B16, one tilt at a time.

   .. math::
       p(\cos t) = \xi\, N_{[t_{\min}, 1]}(\mu_t, \sigma_t)
                   + \frac{1 - \xi}{1 - t_{\min}}.

   Careful: the model is joint over the *binary* -- one draw decides whether
   both tilts come from the Gaussian or both from the isotropic component -- so
   the density of the pair is **not** the product of two of these. It is

   .. math::
       p(\cos t_1, \cos t_2) = \xi\, N(\cos t_1) N(\cos t_2)
                             + \frac{1 - \xi}{(1 - t_{\min})^2},

   which is what :class:`GWForge.population_fisher.DefaultSpin` evaluates and
   what makes ``corr(cos t_1, cos t_2)`` non-zero. This marginal is the right
   thing to compare a one-dimensional histogram against, and nothing else.


.. py:data:: DEFAULT_PARAMETERS

.. py:class:: Spin(spin_model, number_of_samples, parameters=None)

   .. py:attribute:: spin_model
      :value: ''



   .. py:attribute:: number_of_samples


   .. py:attribute:: parameters


   .. py:method:: sample()

      Generate spin distribution samples based on the chosen parameterised model and its parameters.

      :returns: **dict**
      :rtype: A dictionary containing spin distribution samples.