.. _physics-kinematicsDistribution:

Kinematics Distributions
========================

Class providing kinematics distributions for mass distribution components---the temperature, velocity dispersion, and mean radial velocity of particles (or fluid elements) as a function of position. For collisional (gaseous) components the temperature profile enters the cooling and feedback calculations; for collisionless (stellar and dark matter) components the velocity dispersion is computed by solving the spherical Jeans equation given the mass distribution and its potential.

Methods
-------

``isCollisional`` → ``logical``
   Return true if the kinematics is collisional.

``temperature`` → ``double precision``
   Return the temperature of the distribution at the given coordinates.

   * ``class(coordinate), intent(in ) :: coordinates``

``temperatureGradientLogarithmic`` → ``double precision``
   Return the logarithmic gradient of the temperature of the distribution at the given coordinates.

   * ``class(coordinate), intent(in ) :: coordinates``

``velocityRadial`` → ``double precision``
   Return the mean radial velocity at the given coordinate.

   * ``class(coordinate ), intent(in ) :: coordinates``

   * ``class(massDistributionClass), intent(inout) :: massDistributionEmbedding``

``velocityDispersion1D`` → ``double precision``
   Return the 1D velocity dispersion at the given coordinate.

   * ``class(coordinate ), intent(in ) :: coordinates``

   * ``class(massDistributionClass), intent(inout), target :: massDistribution_, massDistributionEmbedding``

``velocityDispersion1DNumerical`` → ``double precision``
   Return the 1D velocity dispersion at the given coordinate by numerically solving the Jeans equation.

   * ``class(coordinate ), intent(in ) :: coordinates``

   * ``class(massDistributionClass), intent(inout), target :: massDistribution_, massDistributionEmbedding``

``jeansEquationRadius`` → ``double precision``
   Return the radius variable used in solving the Jeans equation that corresponds to a given physical radius.

   * ``double precision , intent(in ) :: radius``

   * ``class (massDistributionClass), intent(inout) :: massDistributionEmbedding``

``jeansEquationIntegrand`` → ``double precision``
   Evaluate the integrand of the Jeans equation at the given ``radius``, returning :math:`\mathrm{G}M(r)\rho(r)/r^2` needed for numerical integration of the spherical Jeans equation to obtain the line-of-sight velocity dispersion.

   * ``double precision , intent(in ) :: radius``

   * ``class (massDistributionClass), intent(inout) :: massDistribution_, massDistributionEmbedding``

``solverSet`` → ``void``
   Set a sub-module scope pointers on a stack to allow recursive calls to functions.

   * ``class (massDistributionClass), intent(in ), target :: massDistribution_, massDistributionEmbedding``

``solverUnset`` → ``void``
   Unset a sub-module scope pointers on the stack.

``reset`` → ``void``
   Reset memoized (cached) velocity-dispersion state, so that a kinematics distribution attached to a re-initialized (e.g. pooled) mass distribution never returns stale results.

.. _physics-kinematicsDistributionBurkert:

``kinematicsDistributionBurkert``
---------------------------------

A kinematic distribution class for Burkert mass distributions.

**Methods**

* ``timeFreefallTabulate`` — Tabulate the freefall time as a function of radius in a scale-free Burkert mass distribution.

.. _physics-kinematicsDistributionCollisionless:

``kinematicsDistributionCollisionless``
---------------------------------------

A kinematic distribution class for collisionless (dark matter or stellar) mass distributions that computes the 1D velocity dispersion by numerically solving the isotropic Jeans equation. Convergence tolerances for the velocity dispersion integral are controlled by ``[toleranceRelativeVelocityDispersion]`` and ``[toleranceRelativeVelocityDispersionMaximum]``.

**Methods**

* ``tabulate`` — Tabulate the virial density contrast as a function of mass and time.
* ``restoreTable`` — Restore a tabulated solution from file.
* ``storeTable`` — Store a tabulated solution to file.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.

.. _physics-kinematicsDistributionCollisionlessTabulated:

``kinematicsDistributionCollisionlessTabulated``
------------------------------------------------

A kinematic distribution base class for collisionless mass distributions that computes the 1D velocity dispersion by numerically solving the isotropic Jeans equation and caching the results in tabulated form. Numerical convergence is governed by ``[toleranceRelativeVelocityDispersion]`` and ``[toleranceRelativeVelocityDispersionMaximum]``.

**Methods**

* ``parameters`` — Return parameters of the current mass distribution.
* ``factoryTabulation`` — Return an instance of the class with the given tabulation parameters.
* ``suffix`` — Return a suffix to append to table file names.
* ``fileRead`` — Read tabulation data from file.
* ``fileWrite`` — Write tabulation data to file.
* ``tabulate`` — (Re)tabulate the mass distribution.
* ``interpolate`` — Interpolate in the mass distribution.
* ``isTabulating`` — Return true if the thread associated with the object is tabulating.
* ``velocityDispersion1D`` — Compute the 1D velocity dispersion at the given coordinates.
* ``initialize`` — Initialize the container (specifically the number of parameters).
* ``nameParameter`` — Return the name of the index parameter for a given tabulation.
* ``countParameters`` — Return the number of parameters for a given tabulation.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.

.. _physics-kinematicsDistributionCuspNFW:

``kinematicsDistributionCuspNFW``
---------------------------------

A kinematic distribution class for the cusp-NFW dark matter profile of :cite:p:`delos_cusp-halo_2025`, which describes halos with a central density cusp transitioning to an NFW envelope. The 1D velocity dispersion is computed from tabulated solutions to the isotropic Jeans equation for this two-component density profile.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion.

.. _physics-kinematicsDistributionEnzoHydrostatic:

``kinematicsDistributionEnzoHydrostatic``
-----------------------------------------

A kinematic class that implements the "hydrostatic" temperature profile available in the :term:`ENZO` code. Specifically,

.. math::

   T(r) = \hbox{max}\left( {\mathrm{G} M(<r) \mu m_\mathrm{H} \over 3 \mathrm{k_B} r} , T_\mathrm{min} \right),

where :math:`M(<r)` is the total mass enclosed within radius :math:`r`, :math:`\mu` is the primordial mean atomic mass, and :math:`T_\mathrm{min}=100` K is a temperature floor introduced so as to avoid the temperature reaching arbitrarily low values.

**Methods**

* ``normalizationDensity`` — Return the normalization of the density profile.

.. _physics-kinematicsDistributionFiniteResolutionNFW:

``kinematicsDistributionFiniteResolutionNFW``
---------------------------------------------

A kinematic distribution class for finite-resolution NFW mass distributions.

**Methods**

* ``radiusEnclosingDensityTabulate`` — Tabulate the radius enclosing a given density as a function of density and core radius.
* ``radiusEnclosingMassTabulate`` — Tabulate the radius enclosing a given mass as a function of density and core radius.
* ``energyTabulate`` — Tabulate the energy as a function of concentration and core radius.
* ``densityScaleFree`` — The density of the profile in units where the mass and scale length are both 1.
* ``massEnclosedScaleFree`` — The mass enclosed of the profile in units where the mass and scale length are both 1.
* ``storeDensityTable`` — Store the tabulated radius-enclosing-density to file.
* ``restoreDensityTable`` — Attempt to restore the tabulated radius-enclosing-density from file, returning true if successful.
* ``storeMassTable`` — Store the tabulated radius-enclosing-mass to file.
* ``restoreMassTable`` — Attempt to restore the tabulated radius-enclosing-mass from file, returning true if successful.
* ``storeEnergyTable`` — Store the tabulated energy to file.
* ``restoreEnergyTable`` — Attempt to restore the tabulated energy from file, returning true if successful.
* ``suffix`` — Return a file name suffix (containing a source code digest.

.. _physics-kinematicsDistributionHeated:

``kinematicsDistributionHeated``
--------------------------------

A kinematic distribution class for mass distributions subject to external heating. The 1D velocity dispersion is computed by solving the Jeans equation modified to account for the additional energy injected by the heating source. The ``[velocityDispersionApproximate]`` flag enables an approximate solver for improved performance.

**Parameters**

* ``[velocityDispersionApproximate]`` (boolean; default ``.true.``) — If ``true``, radial velocity dispersion is computed using an approximate method in which we assume that :math:`\sigma_\mathrm{r}^2(r) \rightarrow \sigma_\mathrm{r}^2(r) - (2/3) \epsilon(r)`, where :math:`\epsilon(r)` is the specific heating energy. If ``false`` then radial velocity dispersion is computed by numerically solving the Jeans equation.
* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.
* ``[nonAnalyticSolver]`` (string; one of ``fallThrough``, ``numerical``; default ``fallThrough``) — Selects how solutions are computed when no analytic solution is available. If set to "``fallThrough``" then the solution ignoring heating is used, while if set to "``numerical``" then numerical solvers are used to find solutions.

.. _physics-kinematicsDistributionIsothermal:

``kinematicsDistributionIsothermal``
------------------------------------

An isothermal kinematic distribution class for collisional gas components in which all particles share a single uniform temperature. The 1D velocity dispersion is derived from the gas temperature ``[temperature]`` and mean atomic mass ``[massAtomicMean]``, appropriate for modelling thermally supported gas in hydrostatic equilibrium.

**Parameters**

* ``[temperature]`` (real) — The temperature (in Kelvin) of the isothermal gas distribution; used with ``massAtomicMean`` to compute the 1D velocity dispersion via :math:`\sigma^2 = k_\mathrm{B} T / (\mu m_\mathrm{H})`.
* ``[massAtomicMean]`` (real) — The mean atomic mass (in atomic mass units) of the distribution.
* ``[velocityDispersion]`` (real) — The 1D velocity dispersion (in km/s) of the isothermal distribution, used directly when no ``temperature`` is specified; sets the thermally broadened line-of-sight velocity spread.

.. _physics-kinematicsDistributionLam2013:

``kinematicsDistributionLam2013``
---------------------------------

A kinematic distribution class implementing the :cite:t:`lam_modeling_2013` model of radial velocity infall in halo accretion flows. The radial velocity profile is computed from the volume-averaged two-point correlation function and cosmological linear growth rate, encoding the infall dynamics around collapsed halos at a given redshift and virial mass.

**Parameters**

* ``[scaleFactorVelocity]`` (real; default ``1.0d0``) — A scale factor to be applied to inflow velocities.
* ``[redshift]`` (real) — The cosmological redshift of the halo, used to evaluate the cosmic time and the :cite:t:`lam_modeling_2013` infall velocity profile at the appropriate epoch.
* ``[massVirial]`` (real) — The virial mass (in :math:`\mathrm{M}_\odot`) of the halo whose accretion flow kinematics are modeled by the :cite:t:`lam_modeling_2013` framework.
* ``[radiusVirial]`` (real) — The virial radius (in Mpc) of the halo, setting the spatial scale for the :cite:t:`lam_modeling_2013` radial infall velocity profile.
* ``[overdensityCritical]`` (real) — The critical linear overdensity threshold for collapse used in the :cite:t:`lam_modeling_2013` accretion flow model to normalize the radial infall velocity.
* ``[rateLinearGrowth]`` (real) — The logarithmic derivative of the linear growth factor with respect to expansion factor.
* ``[radius]`` (real) — The radius in the tabulated volume-averaged correlation function.
* ``[correlationFunctionVolumeAveraged]`` (real) — The correlation in the tabulated volume-averaged correlation function.

.. _physics-kinematicsDistributionLocal:

``kinematicsDistributionLocal``
-------------------------------

A local kinematic distribution class in which the 1D velocity dispersion is given by

.. math::

   \sigma_\mathrm{1D}(\mathbf{r}) = \alpha V_\mathrm{c}(r),

where :math:`r = |\mathbf{r}|` and :math:`V_\mathrm{c}(r)` is the rotation curve. Here, :math:`\alpha=`\ ``[]`` is a parameter.

**Parameters**

* ``[alpha]`` (real; default ``1.0d0/sqrt(2.0d0)``) — The parameter :math:`\alpha` in the relation :math:`\sigma_\mathrm{1D}(\mathbf{r}) = \alpha V_\mathrm{c}(r)`.

.. _physics-kinematicsDistributionNFW:

``kinematicsDistributionNFW``
-----------------------------

A kinematic distribution class that computes the collisionless 1D velocity dispersion profile for Navarro-Frenk-White (NFW) dark matter mass distributions by solving the Jeans equation. A series approximation for the velocity dispersion integral can be selected via ``[useSeriesApproximation]`` to improve numerical efficiency.

**Methods**

* ``radiusEnclosingDensityTabulate`` — Tabulate the radius enclosing a given density as a function of density and core radius.
* ``radiusEnclosingMassTabulate`` — Tabulate the radius enclosing a given mass as a function of density and core radius.
* ``energyTabulate`` — Tabulate the energy as a function of concentration and core radius.
* ``densityScaleFree`` — The density of the profile in units where the mass and scale length are both 1.
* ``massEnclosedScaleFree`` — The mass enclosed of the profile in units where the mass and scale length are both 1.
* ``storeDensityTable`` — Store the tabulated radius-enclosing-density to file.
* ``restoreDensityTable`` — Attempt to restore the tabulated radius-enclosing-density from file, returning true if successful.
* ``storeMassTable`` — Store the tabulated radius-enclosing-mass to file.
* ``restoreMassTable`` — Attempt to restore the tabulated radius-enclosing-mass from file, returning true if successful.
* ``storeEnergyTable`` — Store the tabulated energy to file.
* ``restoreEnergyTable`` — Attempt to restore the tabulated energy from file, returning true if successful.
* ``suffix`` — Return a file name suffix (containing a source code digest.

**Parameters**

* ``[useSeriesApproximation]`` (boolean; default ``.true.``) — If true, use a fast series approximation to the velocity dispersion profile in an NFW mass distribution. The approximation matches the exact (dilogarithm-based) form to better than :math:`5\times 10^{-6}` in relative terms across :math:`r/r_\mathrm{s} \in [10^{-4},10^4]` (see ``tests.kinematic_distributions.NFW``).

.. _physics-kinematicsDistributionShi2016:

``kinematicsDistributionShi2016``
---------------------------------

A kinematic distribution class for the :cite:t:`shi_outer_2016` model of halo accretion flows.

**Methods**

* ``solve`` — Solve for the structure of the accretion flow.

.. _physics-kinematicsDistributionSIDMIsothermal:

``kinematicsDistributionSIDMIsothermal``
----------------------------------------

A kinematic distribution class implementing the "isothermal" approximation to the effects of SIDM based on the model of :cite:t:`jiang_semi-analytic_2023`.

.. _physics-kinematicsDistributionSoliton:

``kinematicsDistributionSoliton``
---------------------------------

A kinematic distribution class for the solitonic core mass distribution found in fuzzy dark matter halos. The 1D velocity dispersion profile is computed from tabulated solutions to the isotropic Jeans equation applied to the soliton density profile, encoding the quantum pressure support of ultralight axion dark matter.

**Methods**

* ``radiusMerge`` — Compute the radius at which the satellite will be merged in FDM models.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles.

.. _physics-kinematicsDistributionSolitonNFW:

``kinematicsDistributionSolitonNFW``
------------------------------------

A kinematic distribution class for the soliton-NFW mass distribution. In the NFW region, the velocity dispersion is computed using the analytic solution of :cite:t:`lokas_properties_2001`, plus a correction term which accounts for the difference in mass inside the soliton radius between the soliton and the NFW profile. Specifically, we solve the Jeans equation for a point mass (since outside of the soliton radius, the mass within it acts as a point mass) and the NFW density profile:

.. math::

   \frac{\mathrm{d}(\rho\sigma^2}{\mathrm{d}r} = - \frac{\mathrm{G} \Delta M}{r^2} \rho,

where :math:`\Delta M = M_\mathrm{soliton}(r_\mathrm{soliton}) - M_\mathrm{NFW}(r_\mathrm{soliton})`, and which has the solution:

.. math::

   \rho \sigma^2 = - \frac{\mathrm{G} \Delta M \rho_\mathrm{s}}{r_\mathrm{s}} \left( \frac{4}{r/r_\mathrm{s}} - \frac{1}{(r/r_\mathrm{s})^2} + \frac{2}{1+r/r_\mathrm{s}} + 6 \log \left[\frac{r}{r+r_\mathrm{s}}\right] \right).

Inside the soliton, the NFW solution is used as a boundary condition at :math:`r_\mathrm{soliton}`, and the Jeans equation is then solved using the soliton density profile, which results in a solution

.. math::

   \frac{\pi \mathrm{G} r_\mathrm{c}^2 \rho_\mathrm{c}^2}{20038287360 a^{3/2}}
   \left[
   -\sqrt{a} (169995 + 631540 y + 1200199 y^2 + 1317888 y^3 + 849849 y^4 + 300300 y^5 + 45045 y^6) (28672 + 169995 y + 631540 y^2 + 1200199 y^3 + 1317888 y^4 + 849849 y^5 + 300300 y^6 + 45045 y^7)/(1+y)^{14}
   +45045 \tan^{-1}(\sqrt{a} x) \left\{ -2 ( 14336 + 169995 y + 631540 y^2 + 1200199 y^3 + 1317888 y^4 + 849849 y^5 + 300300 y^6 + 45045 y^7)/[x (1+y)^7]
   -45045 \sqrt{a} \tan^{-1}(\sqrt{a} x) \right\}
   \right],

where :math:`x = r/r_\mathrm{c}` and :math:`y = a x^2`.

**Methods**

* ``computeProperties`` — Compute properties of the mass distribution.
* ``calculationReset`` — Reset memoized calculations.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion.

.. _physics-kinematicsDistributionSolitonNFWHeated:

``kinematicsDistributionSolitonNFWHeated``
------------------------------------------

A kinematic distribution class for a composite soliton-NFW mass distribution subject to heating, as occurs in fuzzy dark matter halos with a quantum-pressure-supported solitonic core embedded in an NFW envelope. The 1D velocity dispersion is computed by solving the isotropic Jeans equation for the heated composite profile.

**Methods**

* ``computeProperties`` — Compute properties of the mass distribution.
* ``calculationReset`` — Reset memoized calculations.

**Parameters**

* ``[toleranceRelativeVelocityDispersion]`` (real; default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion.
* ``[toleranceRelativeVelocityDispersionMaximum]`` (real; default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion.

.. _physics-kinematicsDistributionSphericalScaler:

``kinematicsDistributionSphericalScaler``
-----------------------------------------

A kinematic distribution decorator class that rescales the velocity dispersion of an underlying spherical kinematic distribution by applying independent scaling factors to the length and mass dimensions. The scale factors ``[factorScalingLength]`` and ``[factorScalingMass]`` allow the kinematic profile to be mapped between systems of different physical size or mass.

**Methods**

* ``initialize`` — (Re)initialize the scaling factors of the scaled mass distribution.

**Parameters**

* ``[factorScalingLength]`` (real) — The factor by which to scale lengths.
* ``[factorScalingMass]`` (real) — The factor by which to scale the mass.

.. _physics-kinematicsDistributionTruncated:

``kinematicsDistributionTruncated``
-----------------------------------

A kinematic distribution class for truncated mass distributions.

**Methods**

* ``truncationFunction`` — Compute the truncation fraction (and related quantities) from the radius.

.. _physics-kinematicsDistributionUndecorator:

``kinematicsDistributionUndecorator``
-------------------------------------

A kinematic distribution class for decorated mass distributions, that uses the undecorated mass distribution.

.. _physics-kinematicsDistributionZhao1996:

``kinematicsDistributionZhao1996``
----------------------------------

A kinematic distribution class for :cite:t:`zhao_analytical_1996` mass distributions.

**Methods**

* ``timeFreefallTabulate`` — Tabulate the freefall time as a function of radius in a scale-free Zhao1996 mass distribution.