.. _physics-massDistributionHeating: Heating of Mass Distributions ============================= Class providing heating models for mass distributions---the specific energy deposited into the dark matter or stellar distribution as a function of radius, arising from processes such as tidal heating, dynamical friction, or baryonic feedback. The specific energy and its radial gradient are used to modify the density profile of the mass distribution, capturing the effect of non-gravitational energy injection on the structure of halos and galaxies. Methods ------- ``specificEnergy`` → ``double precision`` Return the specific energy at the given radius. * ``double precision , intent(in ) :: radius`` * ``class (massDistributionClass), intent(inout) :: massDistribution_`` ``specificEnergyGradient`` → ``double precision`` Return the radial gradient of the specific energy at the given radius. * ``double precision , intent(in ) :: radius`` * ``class (massDistributionClass), intent(inout) :: massDistribution_`` ``specificEnergyIsEverywhereZero`` → ``logical`` Return true if the specific energy is zero everywhere (i.e. no heating). .. _physics-massDistributionHeatingDecayingDarkMatter: ``massDistributionHeatingDecayingDarkMatter`` --------------------------------------------- Implements heating from decays and response to mass loss. The mass loss heating is parameterized as: .. math:: \epsilon(r) = \gamma \frac{\mathrm{G}\Delta M(r)}{r}, where :math:`\gamma=`\ ``[gamma]`` sets the magnitude of the heating. **Methods** * ``computeFactors`` — Compute memoized factors. **Parameters** * ``[gamma]`` (default ``0.5d0``) — Parameter controlling the magnitude of heating due to mass loss. * ``[includeKickHeating]`` (default ``.true.``) — Parameter controlling whether heating due to velocity kicks is to be included. * ``[radiusEscape]`` — The radius beyond which a particle is assumed to have escaped the potential. * ``[time]`` — The time at which decays should be evaluated. * ``[gamma]`` (default ``0.5d0``) — Parameter controlling the magnitude of heating due to mass loss. * ``[includeKickHeating]`` (default ``.true.``) — Parameter controlling whether heating due to velocity kicks is to be included. .. _physics-massDistributionHeatingImpulsiveOutflow: ``massDistributionHeatingImpulsiveOutflow`` ------------------------------------------- A mass distribution heating class that computes heating due to impulsive outflows---i.e. outflows occurring on timescales that are small relative to the dynamical time of the halo. The model assumed is that the energy injection is given by .. math:: \dot{\epsilon}(r) = \alpha \frac{\mathrm{G} \dot{M}_\mathrm{outflow}(r)}{r} f\left( \frac{t_\phi}{t_\mathrm{dyn}} \right), where :math:`\alpha` is a normalization factor, :math:`t_\phi = M_\mathrm{gas}/\dot{M}_\mathrm{outflow}` is the timescale for the outflow, and :math:`t_\mathrm{dyn} = r_{1/2}/v_{1/2}` is the dynamical time at the half-mass radius. The quantity .. math:: \dot{\epsilon}^\prime = \dot{M}_\mathrm{outflow} f\left( \frac{t_\phi}{t_\mathrm{dyn}} \right), if provided as an argument to the class constructor. **Parameters** * ``[impulsiveEnergyFactor]`` (default ``1.0d0``) — The parameter :math:`\alpha` appearing in the impulsive outflow heating rate. * ``[energyImpulsiveOutflowDisk]`` — The impulsive energy of outflows from the disk. * ``[energyImpulsiveOutflowSpheroid]`` — The impulsive energy of outflows from the spheroid. * ``[impulsiveEnergyFactor]`` (default ``1.0d0``) — The parameter :math:`\alpha` appearing in the impulsive outflow heating rate. .. _physics-massDistributionHeatingMonotonic: ``massDistributionHeatingMonotonic`` ------------------------------------ A mass distribution heating class which takes another heating source and enforces monotonic heating energy perturbation. This is achieved by enforcing the constraint that .. math:: \mathrm{d}/\mathrm{d}r \left[ \frac{\epsilon}{\mathrm{G} M(r) / r} \right] > 0, where :math:`\epsilon` is the specific heating energy :cite:p:`du_tidal_2024`. At radii smaller than the shell-crossing radius defined by the above condition the specific energy is assumed to be proportional to :math:`\mathrm{G} M(r) / r`, with a smooth transition through this radius. **Methods** * ``computeSolution`` — Compute a solution for the heated profile. **Parameters** * ``[nonAnalyticSolver]`` (default ``var_str('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. * ``[toleranceRelativeVelocityDispersion]`` (default ``1.0d-6``) — The relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles. * ``[toleranceRelativeVelocityDispersionMaximum]`` (default ``1.0d-3``) — The maximum relative tolerance to use in numerical solutions for the velocity dispersion in dark-matter-only density profiles. * ``[radiusVirial]`` — The virial radius (in Mpc) of the halo, defining the outer boundary up to which the monotonic heating calculation tracks the energy-ordered shell mapping from the initial to heated density profile. * ``[nonAnalyticSolver]`` (default ``var_str('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. * ``[componentType]`` (default ``var_str('unknown')``) — The component type that this mass distribution represents. * ``[massType]`` (default ``var_str('unknown')``) — The mass type that this mass distribution represents. .. _physics-massDistributionHeatingMonotonicWeak: ``massDistributionHeatingMonotonicWeak`` ---------------------------------------- A mass distribution heating class which takes another heating source and enforces monotonic heating energy perturbation. This class enforces a weaker condition (compared to :galacticus-class:`massDistributionHeatingMonotonic`): .. math:: \frac{\mathrm{d}r_\mathrm{f}}{\mathrm{d}r_\mathrm{i}} > 0, where :math:`r_\mathrm{i}` and :math:`r_\mathrm{f}` are the initial and final radii of the shell respectively. Note that this condition does not ensure that the gradient of the specific heating energy is continuous through the shell-crossing radius. As such, the heated density profile may be discontinuous at this radius also. Using the fact that .. math:: -\frac{\mathrm{G}M}{2 r_\mathrm{f}} = -\frac{\mathrm{G}M}{2 r_\mathrm{i}} + \epsilon(r_\mathrm{i}), where :math:`\epsilon(r)` is the specific heating energy as a function of radius, and :math:`M` is the mass enclosed by the shell, we can re-write the above condition as .. math:: \frac{\mathrm{d}\epsilon}{\mathrm{d}r_\mathrm{i}} r_\mathrm{i} - \epsilon(r_\mathrm{i}) \frac{4 \pi r_\mathrm{i}^3 \rho_\mathrm{i}(r_\mathrm{i})}{M} + \frac{\mathrm{G}M}{2r_\mathrm{i}} > \xi \frac{\mathrm{G}M}{r_\mathrm{i}}, where :math:`\rho_\mathrm{i}(r_\mathrm{i})` is the density in the unheated profile. Here, :math:`\xi` should equal zero to precisely match the criterion for no shell-crossing. However, it is often useful to allow :math:`\xi` to be a small positive number---this avoids getting too close to the boundary of the shell crossing region (where the density can diverge as there is, by definition, a caustic in density at this point). **Parameters** * ``[toleranceShellCrossing]`` (default ``1.0d-3``) — The tolerance adopted in determining if the no-shell-crossing assumption is valid. * ``[toleranceShellCrossing]`` (default ``1.0d-3``) — The tolerance adopted in determining if the no-shell-crossing assumption is valid. .. _physics-massDistributionHeatingNull: ``massDistributionHeatingNull`` ------------------------------- A null mass distribution heating class. The heating energy is always zero. **Parameters** * ``[dimensionless]`` (default ``.true.``) — If true the null profile is considered to be dimensionless. .. _physics-massDistributionHeatingSummation: ``massDistributionHeatingSummation`` ------------------------------------ A mass distribution heating class that sums heating over other classes. **Methods** * ``list`` — Return a list of all sub-components. .. _physics-massDistributionHeatingTidal: ``massDistributionHeatingTidal`` -------------------------------- A mass distribution heating model which accounts for heating due to tidal shocking. The model follows the general approach of :cite:t:`gnedin_tidal_1999`. The change in the specific energy of particles at radius :math:`r` in a halo is given by :math:`\Delta \epsilon = \Delta \epsilon_1 + \Delta \epsilon_2`, where :math:`\Delta \epsilon_1`, and :math:`\Delta \epsilon_2` are the first and second order perturbations respectively. The first order term is given by :math:`\Delta \epsilon_1 = Q r^2` where :math:`Q` is the tidal tensor integrated along the orbital path (see, for example, :cite:author:`taylor_dynamics_2001` :cite:year:`taylor_dynamics_2001`), while the second order term is given by :math:`\Delta \epsilon_2 = (2/3) f \sigma_\mathrm{rms} (1+\chi_\mathrm{r,v}) \sqrt{\Delta \epsilon_1}` :cite:p:`gnedin_tidal_1999`. For the particle velocity dispersion, :math:`v_\mathrm{rms}`, we use :math:`\sqrt{3} \sigma_\mathrm{r}(r)`, the radial velocity dispersion in the dark matter profile scaled to the total velocity dispersion assuming an isotropic velocity distribution. The position-velocity correlation function, :math:`\chi_\mathrm{r,v}`, is taken to be a constant given by the parameter ``[correlationVelocityRadius]``. The coefficient, :math:`f=`\ ``[coefficientSecondOrder]`` is introduced to allow some freedom to adjust the contribution of the second order term. It is degenerate with the value of :math:`\chi_\mathrm{r,v}` but is introduced to allow for possible future promotion of :math:`\chi_\mathrm{r,v}` from a constant to a function of the dark matter profile potential :cite:p:`gnedin_self-consistent_1999`. **Methods** * ``specificEnergyTerms`` — Compute the first and second order energy perturbations. * ``initialize`` — (Re)initialize the parameters of the tidal heating distribution. **Parameters** * ``[coefficientSecondOrder0]`` (default ``0.0d0``) — The coefficient, :math:`a_0`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[coefficientSecondOrder1]`` (default ``0.0d0``) — The coefficient, :math:`a_1`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[coefficientSecondOrder2]`` (default ``0.0d0``) — The coefficient, :math:`a_2`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[correlationVelocityRadius]`` (default ``-1.0d0``) — The velocity-position correlation function, :math:`\chi_\mathrm{r,v}`, as defined by :cite:t:`gnedin_self-consistent_1999` which controls the strength of the second order heating term. * ``[efficiencyDecay]`` (default ``1.0d0``) — Efficiency of the decay of the tidal tensor integral. * ``[applyPreInfall]`` (default ``.false.``) — If true, tidal heating is applied pre-infall. * ``[applyPreInfall]`` (default ``.false.``) — If true, tidal mass loss is applied pre-infall. * ``[heatSpecificNormalized]`` — The normalized specific tidal heating, :math:`Q = \epsilon / r^2`. * ``[coefficientSecondOrder0]`` (default ``0.0d0``) — The coefficient, :math:`a_0`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[coefficientSecondOrder1]`` (default ``0.0d0``) — The coefficient, :math:`a_1`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[coefficientSecondOrder2]`` (default ``0.0d0``) — The coefficient, :math:`a_2`, appearing in the second-order heating term, :math:`f_2 = a_0 + a_1 \mathrm{d}\log \rho/\mathrm{d} \log r + a_2 (\mathrm{d}\log \rho/\mathrm{d} \log r)^2`. * ``[correlationVelocityRadius]`` (default ``-1.0d0``) — The velocity-position correlation function, :math:`\chi_\mathrm{r,v}`, as defined by :cite:t:`gnedin_self-consistent_1999` which controls the strength of the second order heating term. .. _physics-massDistributionHeatingTwoBodyRelaxation: ``massDistributionHeatingTwoBodyRelaxation`` -------------------------------------------- A mass distribution heating class that computes heating due to two-body relaxation. **Parameters** * ``[massParticle]`` — The particle mass to use for two-body relaxation calculations. * ``[lengthSoftening]`` — The softening length to use for two-body relaxation calculations. * ``[timeStart]`` — The time at which two-body relaxation is assumed to have begun. * ``[efficiency]`` — The dimensionless efficiency factor (between 0 and 1) controlling what fraction of the energy transferred by two-body gravitational scattering actually heats the dark matter halo, accounting for partial thermalization of the relaxation energy. * ``[massParticle]`` — The particle mass to use for two-body relaxation calculations. * ``[lengthSoftening]`` — The softening length to use for two-body relaxation calculations. * ``[timeRelaxing]`` — The time for which the system has been relaxing. * ``[efficiency]`` — The fractional efficiency of two-body relaxation heating.