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) coordinates [in]

temperatureGradientLogarithmic → double precision

Return the logarithmic gradient of the temperature of the distribution at the given coordinates.

• class(coordinate) coordinates [in]

velocityRadial → double precision

Return the mean radial velocity at the given coordinate.

• class(coordinate) coordinates [in]

• class(massDistributionClass) massDistributionEmbedding [inout]

velocityDispersion1D → double precision

Return the 1D velocity dispersion at the given coordinate.

• class(coordinate) coordinates [in]

• class(massDistributionClass) massDistribution_ [inout]

• class(massDistributionClass) massDistributionEmbedding [inout]

velocityDispersion1DNumerical → double precision

Return the 1D velocity dispersion at the given coordinate by numerically solving the Jeans equation.

• class(coordinate) coordinates [in]

• class(massDistributionClass) massDistribution_ [inout]

• class(massDistributionClass) massDistributionEmbedding [inout]

jeansEquationRadius → double precision

Return the radius variable used in solving the Jeans equation that corresponds to a given physical radius.

• double precision radius [in]

• class(massDistributionClass) massDistributionEmbedding [inout]

jeansEquationIntegrand → double precision

Evaluate the integrand of the Jeans equation at the given radius, returning \(\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 radius [in]

• class(massDistributionClass) massDistribution_ [inout]

• class(massDistributionClass) massDistributionEmbedding [inout]

solverSet

Set a sub-module scope pointers on a stack to allow recursive calls to functions.

• class(massDistributionClass) massDistribution_ [in]

• class(massDistributionClass) massDistributionEmbedding [in]

solverUnset

Unset a sub-module scope pointers on the stack.

reset

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.

kinematicsDistributionBurkert

A kinematic distribution class for Burkert mass distributions.

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].

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.

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].

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.

kinematicsDistributionCuspNFW

A kinematic distribution class for the cusp-NFW dark matter profile of (Delos, 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 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.

kinematicsDistributionEnzoHydrostatic

A kinematic class that implements the “hydrostatic” temperature profile available in the ENZO code. Specifically,

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

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

kinematicsDistributionFiniteResolutionNFW

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

Methods

velocityDispersion1DTabulate

Tabulate the enclosed mass as a function of radius and core radius.

• class(massDistributionSphericalFiniteResolutionNFW) massDistributionEmbedding [inout]

• double precision radius [in]

• double precision radiusCore [in]

storeVelocityDispersionTable

Store the tabulated velocity dispersion to file.

restoreVelocityDispersionTable

Attempt to restore the tabulated velocity dispersion from file, returning true if successful.

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 \(\sigma_\mathrm{r}^2(r) \rightarrow \sigma_\mathrm{r}^2(r) - (2/3) \epsilon(r)\), where \(\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.

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 \(\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.

kinematicsDistributionLam2013

A kinematic distribution class implementing the Lam et al. (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 Lam et al. (2013) infall velocity profile at the appropriate epoch.

• [massVirial] (real) — The virial mass (in \(\mathrm{M}_\odot\)) of the halo whose accretion flow kinematics are modeled by the Lam et al. (2013) framework.

• [radiusVirial] (real) — The virial radius (in Mpc) of the halo, setting the spatial scale for the Lam et al. (2013) radial infall velocity profile.

• [overdensityCritical] (real) — The critical linear overdensity threshold for collapse used in the Lam et al. (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.

kinematicsDistributionLocal

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

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

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

Parameters

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

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.

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 \(5\times 10^{-6}\) in relative terms across \(r/r_\mathrm{s} \in [10^{-4},10^4]\) (see tests.kinematic_distributions.NFW).

kinematicsDistributionShi2016

A kinematic distribution class for the Shi (2016) model of halo accretion flows.

kinematicsDistributionSIDMIsothermal

A kinematic distribution class implementing the “isothermal” approximation to the effects of SIDM based on the model of Jiang et al. (2023).

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.

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.

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 Łokas and Mamon (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:

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

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

\[\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 \(r_\mathrm{soliton}\), and the Jeans equation is then solved using the soliton density profile, which results in a solution

\[\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 \(x = r/r_\mathrm{c}\) and \(y = a x^2\).

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.

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.

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.

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.

Parameters

• [factorScalingLength] (real) — The multiplicative factor applied to all length scales in the underlying kinematic distribution; used to rescale the distribution from one physical size to another.

• [factorScalingMass] (real) — The multiplicative factor applied to the mass normalization of the underlying kinematic distribution; used to rescale the distribution from one physical mass to another.

kinematicsDistributionTruncated

A kinematic distribution class for truncated mass distributions.

kinematicsDistributionUndecorator

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

kinematicsDistributionZhao1996

A kinematic distribution class for Zhao (1996) mass distributions.