.. _physics-galacticStructureSolver:

Galactic Structure Solver
=========================

Class providing solvers for galactic structure---algorithms that determine the sizes (half-mass or scale radii) of galactic components (disc, bulge, nuclear star cluster), e.g. by finding the equilibrium configuration that satisfies the angular momentum conservation constraint, i.e. the radius at which the specific angular momentum of the component matches that of the infalling gas. Solving for the structure may require self-consistent accounting of the gravitational potential from all components including dark matter, gas, and stars.

**Default implementation:** ``galacticStructureSolverEquilibrium``

Methods
-------

``solve`` → ``void``
   Solves for the structure of components in the given ``node``.

   * ``type (treeNode), intent(inout), target :: node``

   * ``logical , intent(in ), optional :: plausibilityOnly``

``revert`` → ``void``
   Revert the structure of components in the given ``node`` (if necessary to ensure that the structure solver will give the same result when called consecutively).

   * ``type(treeNode), intent(inout) :: node``

.. _physics-galacticStructureSolverEquilibrium:

``galacticStructureSolverEquilibrium``
--------------------------------------

An "equilibrium" solver for galactic structure that iteratively finds radii at which each galactic component is in equilibrium within the combined gravitational potential of dark matter and baryons. Convergence is controlled by ``[solutionTolerance]``, with optional inclusion of baryon self-gravity via ``[includeBaryonGravity]``.

**(Default implementation)**

**Parameters**

* ``[convergenceFailureIsFatal]`` (default ``.true.``) — If true, failure to achieve convergence in radii results in a fatal error.
* ``[includeBaryonGravity]`` (default ``.true.``) — Specifies whether or not gravity from baryons is included when solving for sizes of galactic components.
* ``[useFormationHalo]`` (default ``.false.``) — Specifies whether or not the "formation halo" should be used when solving for the radii of galaxies.
* ``[solveForInactiveProperties]`` (default ``.true.``) — If true, galactic structure is solved for during evaluation of inactive property integrals. Otherwise, structure is not solved for during this phase---this should only be used if the inactive property integrands *do not* depend on galactic structure.
* ``[solutionTolerance]`` (default ``1.0d-2``) — Maximum allowed mean fractional error in the radii of all components when seeking equilibrium solutions for galactic structure.

.. _physics-galacticStructureSolverFixed:

``galacticStructureSolverFixed``
--------------------------------

A galactic structure solver that determines the sizes of galactic components by assuming that radius equals

.. math::

    r
   = f_\mathrm{r} \lambda r_0

where :math:`r_0` is the virial or turnaround radius of the :term:`node` if ``[radiusFixed]``\ :math:`=`\ ``virialRadius`` or ``turnaround`` respectively, :math:`\lambda` is its spin parameter and :math:`f_\mathrm{r}=`\ ``[factor]`` is a parameter. Optionally, different values of :math:`f_\mathrm{r}` can be specified for disks and spheroids using the ``[factorDisk]`` and ``[factorSpheroid]`` parameters respectively---if either or both are not provided the value of ``[factor]`` will be used for the corresponding component.

**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-galacticStructureSolverLinear:

``galacticStructureSolverLinear``
---------------------------------

A galactic structure solver class that determines the sizes of galactic components by assuming that radius scales linearly with specific angular momentum such that

.. math::

   r = r_\mathrm{vir} j/j_\mathrm{vir}

where :math:`j` is the specific angular momentum of the :term:`component` (at whatever point in the profile is to be solved for), :math:`r` is radius, :math:`r_\mathrm{vir}` is the virial radius of the :term:`node` and :math:`j_\mathrm{vir}= r_\mathrm{vir} v_\mathrm{vir}` with :math:`v_\mathrm{vir}` being the virial velocity of the :term:`node`.

**Parameters**

* ``[coefficientConstant]`` (default ``1.67d0``) — The constant (zero-order) coefficient :math:`B_0` in the linear excursion-set barrier :math:`B(\sigma^2) = B_0 + B_1\,\sigma^2`; corresponds to the spherical collapse threshold :math:`\delta_\mathrm{c} \approx 1.686` in the simplest case.
* ``[coefficientLinear]`` (default ``0.0d0``) — The linear (first-order in :math:`\sigma^2`) coefficient :math:`B_1` in the excursion-set barrier :math:`B(\sigma^2) = B_0 + B_1\,\sigma^2`; a non-zero value produces a moving barrier that mimics ellipsoidal collapse corrections to the halo mass function.

.. _physics-galacticStructureSolverNull:

``galacticStructureSolverNull``
-------------------------------

A no-op galactic structure solver that performs no radius solving, useful as a placeholder when galactic structure calculations are not needed or as a baseline for testing.

**Parameters**

* ``[dimensionless]`` (default ``.true.``) — If true the null profile is considered to be dimensionless.

.. _physics-galacticStructureSolverSimple:

``galacticStructureSolverSimple``
---------------------------------

A galactic structure solver class that determines the sizes of galactic components by assuming that their self-gravity is negligible (i.e. that the gravitational potential well is dominated by dark matter) and that, therefore, baryons do not modify the dark matter density profile. The radius of a given :term:`component` is then found by solving

.. math::

   j = \sqrt{\G M_\mathrm{DM}(r) r},

where :math:`j` is the specific angular momentum of the :term:`component` (at whatever point in the profile is to be solved for), :math:`r` is radius and :math:`M(r)` is the mass of dark matter within radius :math:`r`. The parameter ``[useFormationHalo]`` controls whether the structure of the galaxy will be solved for using the properties of its present :term:`node` or those of its :term:`node` at the time of :term:`node` formation (which requires that "node formation" has been suitably defined and implemented by a component).

**Methods**

* ``calculationReset`` — Reset memoized calculations.

**Parameters**

* ``[efficiencyWind]`` (default ``2.2157d-3``) — The coupling efficiency of the black hole accretion-driven wind, defined as the fraction of the accreted rest-mass energy that is deposited as kinetic or thermal energy into the surrounding gas via AGN-driven outflows.
* ``[redshiftReionization]`` (default ``9.97d0``) — The redshift of reionization below which baryonic accretion onto halos is suppressed due to the ionizing background heating the intergalactic medium and preventing gas from accreting onto low-mass halos.
* ``[opticalDepthReionization]`` — The optical depth to electron scattering below which baryonic accretion is suppressed.
* ``[velocitySuppressionReionization]`` (default ``35.0d0``) — The velocity scale below which baryonic accretion is suppressed.
* ``[accretionNegativeAllowed]`` (default ``.true.``) — Specifies whether negative accretion (mass loss) is allowed in the simple halo accretion model.
* ``[accretionNewGrowthOnly]`` (default ``.false.``) — Specifies whether accretion from the :term:`IGM` is allowed only when a halo is growing past its previous greatest mass.
* ``[acceptedStateCount]`` (default ``100``) — The number of states to use in acceptance rate statistics.
* ``[timeStepRelative]`` (default ``0.1d0``) — The maximum allowed relative change in time for a single step in the evolution of a node.
* ``[timeStepAbsolute]`` (default ``1.0d0``) — The maximum allowed absolute change in time (in Gyr) for a single step in the evolution of a node.
* ``[timeStepMinimum]`` (default ``1.0d-6``) — The smallest timestep to use in profiling ODE solver steps.
* ``[timeStepMaximum]`` (default ``1.0d+1``) — The largest timestep to use in profiling ODE solver steps.
* ``[timeStepPointsPerDecade]`` (default ``3``) — The number of bins per decade of timestep to use when profiling ODE solver steps.
* ``[wavelength]`` (default ``1.0d4``) — The wavelength of the photon packet (in \AA).
* ``[wavelengthMinimum]`` (default ``0.5d4``) — The minimum wavelength of the photon packet (in \AA).
* ``[wavelengthMaximum]`` (default ``2.0d4``) — The maximum wavelength of the photon packet (in \AA).
* ``[luminosity]`` (default ``1.0d0``) — The luminosity of the photon packet (in :math:`L_\odot`).
* ``[massRatioMajorMerger]`` (default ``0.25d0``) — The mass ratio above which mergers are considered to be "major".
* ``[destinationGasMinorMerger]`` (default ``var_str('spheroid')``) — The component to which satellite galaxy gas moves to as a result of a minor merger.
* ``[destinationStarsMinorMerger]`` (default ``var_str('spheroid')``) — The component to which satellite galaxy stars move to as a result of a minor merger.
* ``[degreesOfFreedom]`` (default ``3.0d0``) — Number of degrees of freedom to assume when computing the energy density of cooling gas in the "simple" cooling time class.
* ``[timeScale]`` (default ``1.0d0``) — The timescale (in Gyr) for cooling in the simple cooling rate model.
* ``[reionizationRedshift]`` (default ``9.97d0``) — The redshift of reionization in the simple :term:`IGM` state model.
* ``[reionizationTemperature]`` (default ``1.0d4``) — The post-reionization temperature (in units of Kelvin) in the simple :term:`IGM` state model.
* ``[preReionizationTemperature]`` (default ``10.0d0``) — The pre-reionization temperature (in units of Kelvin) in the simple :term:`IGM` state model.
* ``[useFormationHalo]`` (default ``.false.``) — Specifies whether or not the "formation halo" should be used when solving for the radii of galaxies.
* ``[solveForInactiveProperties]`` (default ``.true.``) — If true, galactic structure is solved for during evaluation of inactive property integrals. Otherwise, structure is not solved for during this phase---this should only be used if the inactive property integrands *do not* depend on galactic structure.
* ``[rateFractionalMaximum]`` (default ``10.0d0``) — The maximum fractional mass loss rate per dynamical time in the simple model of mass loss due to tidal stripping.
* ``[beta]`` (default ``1.0d0``) — The scaling factor which multiplies the tidal mass loss rate.
* ``[OmegaMatter]`` (default ``0.3153d0``) — The density of matter in the Universe in units of the critical density.
* ``[OmegaBaryon]`` (default ``0.04930d0``) — The density of baryons in the Universe in units of the critical density.
* ``[OmegaDarkEnergy]`` (default ``0.6847d0``) — The density of dark energy in the Universe in units of the critical density.
* ``[temperatureCMB]`` (default ``2.72548d0``) — The present day temperature of the :term:`CMB` in units of Kelvin.
* ``[HubbleConstant]`` (default ``67.36d0``) — The present day value of the Hubble parameter in units of km/s/Mpc.