.. _physics-haloEnvironment: Halo Environment ================ Class providing models of the large-scale environment of dark matter halos---the linear and non-linear overdensity of the surrounding density field on a characteristic smoothing scale (typically several Mpc). Environmental overdensity modulates halo formation rates (assembly bias), the critical overdensity for collapse, and the :term:`IGM` photo-ionization background. Implementations provide the overdensity PDF/CDF, its value for individual nodes, and the radius and mean mass of the environmental region, ranging from a uniform (field) environment to constrained local density models. **Default implementation:** ``haloEnvironmentUniform`` Methods ------- ``overdensityLinear`` → ``double precision`` Return the linear (pre-collapse) large-scale environmental overdensity for the given ``node``, optionally evaluated at the present day rather than at the node's cosmic time. * ``type (treeNode), intent(inout) :: node`` * ``logical , intent(in ), optional :: presentDay`` ``overdensityLinearGradientTime`` → ``double precision`` Return the gradient with time of the environmental linear overdensity for the given ``node``. * ``type (treeNode), intent(inout) :: node`` ``overdensityNonLinear`` → ``double precision`` Return the non-linear (post-collapse) large-scale environmental overdensity for the given ``node``, accounting for gravitational non-linear evolution of the surrounding density field. * ``type(treeNode), intent(inout) :: node`` ``environmentRadius`` → ``double precision`` Return the radius (in Mpc) of the spherical region over which the large-scale density is averaged to define the halo environment. ``environmentMass`` → ``double precision`` Return the mean mass (in :math:`\mathrm{M}_\odot`) enclosed within the environmental smoothing region, equal to the background matter density times the volume of the sphere of radius ``environmentRadius``. ``overdensityLinearMinimum`` → ``double precision`` Return the minimum linear overdensity for which the environmental overdensity :term:`PDF` is non-zero. ``overdensityLinearMaximum`` → ``double precision`` Return the maximum linear overdensity for which the environmental overdensity :term:`PDF` is non-zero. ``pdf`` → ``double precision`` Return the :term:`PDF` of the environmental overdensity for the given overdensity. * ``double precision, intent(in ) :: overdensity`` ``cdf`` → ``double precision`` Return the :term:`CDF` of the environmental overdensity for the given overdensity. * ``double precision, intent(in ) :: overdensity`` ``overdensityLinearSet`` → ``void`` Set the linear environmental overdensity for the given ``node``, allowing external code (e.g., constrained realization samplers) to assign a specific large-scale density to the node's host region. * ``type (treeNode), intent(inout) :: node`` * ``double precision , intent(in ) :: overdensity`` ``overdensityIsSettable`` → ``logical`` Return true if the environmental overdensity can be set externally via ``overdensityLinearSet``, allowing the caller to determine at runtime whether the environment model supports direct assignment. ``volumeFractionOccupied`` → ``double precision`` Return the fraction of the volume occupied by the regions described by this environment. ``isNodeDependent`` → ``logical`` Return true if the environment is node dependent (but false if the only dependency on the node is via its host tree). ``isTreeDependent`` → ``logical`` Return true if the environmental overdensity depends on the host merger tree (i.e., on ``node%hostTree``), as opposed to depending only on the individual node or being completely node-independent. .. _physics-haloEnvironmentFixed: ``haloEnvironmentFixed`` ------------------------ Implements a halo environment with a fixed, user-specified overdensity, representing a deterministic large-scale density field around a halo. The environmental overdensity is set by ``[overdensity]``, while the filtering scale for variance computations is specified by either ``[radiusEnvironment]`` or the corresponding environmental mass ``[massEnvironment]``. **Parameters** * ``[mass]`` (default ``100.0d0``) — The fixed mass (in :math:`\mathrm{M}_\odot`) assigned to all newly-formed seed black holes in this implementation, representing the initial black hole mass when a halo first forms a central black hole. * ``[spin]`` (default ``0.0d0``) — The dimensionless spin parameter (between :math:`-1` and :math:`+1`) assigned to all newly-formed seed black holes, where :math:`0` corresponds to a non-rotating Schwarzschild black hole and :math:`\pm 1` to a maximally rotating Kerr black hole. * ``[fraction]`` (default ``0.01d0``) — The fixed fraction :math:`f_\mathrm{outflow}` of the stellar energy input rate (normalized to a canonical :math:`1\,\mathrm{M}_\odot` population) that drives gas outflows, setting the mass loading factor for stellar feedback in the galaxy. * ``[escapeFraction]`` (default ``0.006d0``) — Escape fraction of ionizing photons from young HII regions. * ``[ageLimit]`` (default ``0.03d0``) — The age beyond which all ionizing photons are assumed to escape from HII regions. * ``[timescale]`` (default ``1.0d0``) — The timescale for star formation in the fixed timescale model. * ``[rateStarFormation]`` (default ``1.0d9``) — The rate of star formation in units of :math:`\mathrm{M}_\odot \hbox{Gyr}^{-1}`. * ``[proposalSize]`` — The fixed value of the proposal scaling parameter :math:`\gamma` used to scale the vector difference between two randomly selected chain states when forming differential evolution proposals. * ``[exponentValue]`` — The fixed value of the temperature-scaling exponent :math:`\alpha` by which the proposal size :math:`\gamma` is scaled as :math:`\gamma \propto T^{\alpha}` in tempered differential evolution runs. * ``[massResolution]`` (default ``5.0d9``) — The mass resolution to use when building merger trees. * ``[rootVariance]`` — The root variance of the random error distribution. * ``[velocityRadial]`` (default ``-0.90d0``) — The radial velocity (in units of the host virial velocity) to used for the fixed virial orbits distribution. Default value matches approximate peak in the distribution of :cite:t:`benson_orbital_2005`. * ``[velocityTangential]`` (default ``0.75d0``) — The tangential velocity (in units of the host virial velocity) to used for the fixed virial orbits distribution. Default value matches approximate peak in the distribution of :cite:t:`benson_orbital_2005`. * ``[rateCoefficient]`` — The rate coefficient (in units of cm\ :math:`^3` s\ :math:`^{-1}`) for radiative recombination. * ``[gamma]`` (default ``0.67d0``) — The multiplicative factor, :math:`\gamma`, used to compute the cooling coefficient. * ``[fractionLossAngularMomentum]`` (default ``0.3d0``) — Specifies the fraction of angular momentum that is lost from cooling/infalling gas. * ``[concentration]`` — The fixed NFW concentration parameter :math:`c = r_\mathrm{virial}/r_\mathrm{scale}` assigned to all halos regardless of mass or redshift, representing the ratio of the virial radius to the scale radius of the dark matter density profile. * ``[metallicity]`` — The metallicity (relative to Solar) of the :term:`IGM`. * ``[factor]`` (default ``sqrt(0.5d0)``) — The ratio of galaxy radius to :math:`\lambda r_\mathrm{vir}` in the "fixed" galactic structure radius solver algorithm. This will be applied to any component for which no component-specific value is provided. * ``[factorDisk]`` (default ``sqrt(0.5d0)``) — The ratio of galaxy radius to :math:`\lambda r_\mathrm{vir}` in the "fixed" galactic structure radius solver algorithm for disks. This will override the generic value supplied by ``[factor]`` for disks. * ``[factorSpheroid]`` (default ``sqrt(0.5d0)``) — The ratio of galaxy radius to :math:`\lambda r_\mathrm{vir}` in the "fixed" galactic structure radius solver algorithm for spheroids. This will override the generic value supplied by ``[factor]`` for spheroids. * ``[radiusFixed]`` (default ``var_str('virial')``) — The radius to use in the "fixed" galactic structure radius solver algorithm. Allowed options are "virial" and "turnaround". * ``[overdensity]`` — The fixed linear overdensity :math:`\delta` of the large-scale environment assigned uniformly to all halos; a positive value places halos in an overdense region, while negative values simulate voids. * ``[radiusEnvironment]`` (default ``0.0d0``) — The radius of the sphere used to determine the variance in the environmental density. * ``[massEnvironment]`` (default ``1.0d15``) — The mass within the sphere sphere used to determine the variance in the environmental density. * ``[densityContrastValue]`` (default ``200.0d0``) — The virial density contrast to use in the fixed value model. * ``[densityType]`` (default ``var_str('critical')``) — The reference density to use in the fixed value virial density contrast model. Either of ``critical`` and ``mean`` are allowed. * ``[turnAroundOverVirialRadius]`` (default ``2.0d0``) — The ratio of the turnaround to virial radii in the fixed value model. * ``[criticalOverdensity]`` (default ``(3.0d0/20.0d0)*(12.0d0*Pi)**(2.0d0/3.0d0)``) — The value to use for the critical overdensity for collapse of dark matter halos when using a fixed value. .. _physics-haloEnvironmentLogNormal: ``haloEnvironmentLogNormal`` ---------------------------- Implements a halo environment in which the large-scale overdensity follows a log-normal probability distribution, modeling the statistical distribution of cosmic environments around dark matter halos. The variance of the density field is computed within a sphere of radius given by ``[radiusEnvironment]``, drawn from the linear power spectrum. **Parameters** * ``[median]`` (default ``0.03687d0``) — The median value of the dimensionless Bullock spin parameter :math:`\lambda` in the log-normal distribution, representing the typical angular momentum content of dark matter halos at the present day. * ``[sigma]`` (default ``0.5102d0``) — The standard deviation :math:`\sigma` of :math:`\ln\lambda` in the log-normal spin distribution, controlling the spread of spin parameters across the halo population; larger values produce a broader distribution of angular momenta. * ``[mean]`` — The mean of the log-normal distribution (*ignoring* any imposed upper and lower limits). * ``[variance]`` — The variance of the log-normal distribution (*ignoring* any imposed upper and lower limits). * ``[x0]`` — The median (geometric mean) :math:`x_0 > 0` of the log-normal distribution; the distribution peaks at :math:`x_0 \exp(-\sigma^2)` and has median :math:`x_0`. * ``[sigma]`` — The logarithmic width (standard deviation of :math:`\ln x`) :math:`\sigma > 0` of the log-normal distribution; the distribution becomes more skewed and broader as :math:`\sigma` increases. * ``[limitLower]`` — The lower truncation limit :math:`x_\mathrm{min}` of the log-normal distribution; when set, the distribution is renormalized over :math:`[x_\mathrm{min}, x_\mathrm{max}]` rather than :math:`(0, \infty)`. * ``[limitUpper]`` — The upper truncation limit :math:`x_\mathrm{max}` of the log-normal distribution; when set, the distribution is renormalized over :math:`[x_\mathrm{min}, x_\mathrm{max}]` rather than :math:`(0, \infty)`. * ``[radiusEnvironment]`` (default ``7.0d0``) — The radius of the sphere used to determine the variance in the environmental density. .. _physics-haloEnvironmentNormal: ``haloEnvironmentNormal`` ------------------------- Implements a halo environment in which the large-scale overdensity follows a Gaussian (normal) probability distribution, modeling the statistical distribution of cosmic large-scale density fields around dark matter halos. The filtering scale and redshift at which the environment is defined are set by ``[massEnvironment]`` or ``[radiusEnvironment]`` and ``[redshift]``. **Methods** * ``calculationReset`` — Reset memoized calculations. **Parameters** * ``[rangeLower]`` — Lower integration limit for the normal distribution weight operator. * ``[rangeUpper]`` — Upper integration limit for the normal distribution weight operator. * ``[rootVariance]`` — Root variance for the normal distribution weight operator. * ``[extentLower]`` (default ``-huge(0.0d0)``) — Lower extent for the normal distribution weight operator. * ``[extentUpper]`` (default ``+huge(0.0d0)``) — Upper extent for the normal distribution weight operator. * ``[rangeLower]`` — Lower integration limit for the normal distribution weight operator. * ``[rangeUpper]`` — Upper integration limit for the normal distribution weight operator. * ``[rootVariance]`` — Root variance for the normal distribution weight operator. * ``[mean]`` — The mean :math:`\mu` of the normal (Gaussian) distribution, specifying the location of the peak of the probability density function; optionally constrained within :math:`[x_\mathrm{l}, x_\mathrm{u}]`. * ``[variance]`` — The variance :math:`S = \sigma^2 > 0` of the normal distribution, controlling the width of the Gaussian bell curve; the standard deviation is :math:`\sigma = \sqrt{S}` and the FWHM is :math:`2\sqrt{2\ln 2}\,\sigma`. * ``[limitLower]`` — The lower truncation limit :math:`x_\mathrm{l}` of the normal distribution; when set, the distribution is renormalized over :math:`[x_\mathrm{l}, x_\mathrm{u}]` rather than :math:`(-\infty, +\infty)`. * ``[limitUpper]`` — The upper truncation limit :math:`x_\mathrm{u}` of the normal distribution; when set, the distribution is renormalized over :math:`[x_\mathrm{l}, x_\mathrm{u}]` rather than :math:`(-\infty, +\infty)`. * ``[massEnvironment]`` (default ``1.0d15``) — The mass within the sphere sphere used to determine the variance in the environmental density. * ``[radiusEnvironment]`` (default ``7.0d0``) — The radius of the sphere used to determine the variance in the environmental density. * ``[redshift]`` (default ``0.0d0``) — The redshift at which the large-scale environmental overdensity is defined; the linear density variance and growth factor are evaluated at the corresponding cosmic time to normalize the Gaussian environmental PDF. .. _physics-haloEnvironmentUniform: ``haloEnvironmentUniform`` -------------------------- Implements a uniform halo environment. **(Default implementation)** **Parameters** * ``[massTreeMinimum]`` (default ``1.0d10``) — The minimum mass of merger tree base halos to consider when sampled masses from a distribution, in units of :math:`M_\odot`. * ``[massTreeMaximum]`` (default ``1.0d15``) — The maximum mass of merger tree base halos to consider when sampled masses from a distribution, in units of :math:`M_\odot`. * ``[treesPerDecade]`` (default ``10.0d0``) — The number of merger trees masses to sample per decade of base halo mass. * ``[limitLower]`` — The lower bound :math:`x_\mathrm{l}` of the uniform distribution, below which the probability density is zero; the distribution has constant density :math:`1/(x_\mathrm{u} - x_\mathrm{l})` over :math:`[x_\mathrm{l}, x_\mathrm{u}]`. * ``[limitUpper]`` — The upper bound :math:`x_\mathrm{u}` of the uniform distribution, above which the probability density is zero; the distribution has constant density :math:`1/(x_\mathrm{u} - x_\mathrm{l})` over :math:`[x_\mathrm{l}, x_\mathrm{u}]`.