.. _physics-mergerProgenitorProperties:

Merger Progenitor Properties
============================

Class providing models of the effective properties of merger progenitors---the masses, radii, and angular momentum factors of the satellite and host galaxies immediately before a merger event, which are passed to the remnant size calculator. The progenitor properties determine the energy budget available to the merger remnant: the satellite mass, host spheroid mass, pre-merger host spheroid mass, effective radii, angular momentum factor, and the expected remnant spheroid and gas-spheroid masses used to compute the post-merger structure.

**Default implementation:** ``mergerProgenitorPropertiesStandard``

Methods
-------

``get`` → ``void``
   Calculates the effective masses, radii, and angular momentum factors of the satellite and host galaxy progenitors immediately before a merger event, providing the energy budget inputs required by remnant size calculators.

   * ``type (treeNode), intent(inout), target :: nodeSatellite , nodeHost``

   * ``double precision , intent( out) :: massSatellite , massHost``

   * ``double precision , intent( out) :: massSpheroidSatellite , massSpheroidHost``

   * ``double precision , intent( out) :: massSpheroidHostPreMerger, radiusSatellite``

   * ``double precision , intent( out) :: radiusHost , factorAngularMomentum``

   * ``double precision , intent( out) :: massSpheroidRemnant , massGasSpheroidRemnant``

.. _physics-mergerProgenitorPropertiesCole2000:

``mergerProgenitorPropertiesCole2000``
--------------------------------------

A merger progenitor properties class which uses the algorithms of :cite:t:`cole_hierarchical_2000` to compute progenitor properties. Masses of progenitors are set to

.. math::

   M_\mathrm{host|satellite} = \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j},

where :math:`M_{i,j}` is the mass of mass type :math:`j` in :term:`component` :math:`i`. Masses of progenitors that will end up in the remnant spheroid are set to

.. math::

   M_\mathrm{spheroid\,\,host|satellite} = \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j} \delta_{i,j},

where :math:`\delta_{i,j}=0` of mass type :math:`j` in :term:`component` :math:`i` will end up in the remnant spheroid and :math:`0` otherwise. Radii of material that will end up in the spheroid are set by finding the solution to:

.. math::

   \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j}(r) \delta_{i,j} = {1 \over 2}
   \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j} \delta_{i,j},

such that the radii are the half-mass radii of the material that will end up in the remnant spheroid. Finally, the angular momentum factor is set to

.. math::

   f_\mathrm{AM\,\,host|satellite} = {1 \over M_\mathrm{spheroid\,\,host|satellite}} \sum_{i=\mathrm{disk|spheroid}}
   \sum_{j=\mathrm{stars|gas}} M_{i,j} {J_{i,j} \over \mathrm{G} M^{3/2}_{i,j} r_{1/2\,\,i,j}} \delta_{i,j},

where :math:`J_{i,j}` is the angular momentum or pseudo-angular momentum of mass type :math:`j` in :term:`component` :math:`i`\ \footnoteThis is technically not quite what :cite:t:`cole_hierarchical_2000` do. Instead, when computing the masses of the material which ends up in the spheroid they include twice the mass of dark matter (accounting for the effects of adiabatic contraction) within the half-mass radius of each galaxy (as calculated above). The final angular momentum is then :math:`j=\sqrt{\mathrm{G} M_\mathrm{remnant} r_\mathrm{remnant}/2}` (where :math:`M_\mathrm{remnant}` includes the contribution from dark matter and the factor of :math:`2` appears to make this the half-mass). This approach is currently not used in Galacticus since there is no way to get the mass of dark matter enclosed accounting for adiabatic contraction in the general case. This is a solvable problem, and so this algorithm is expected to be modified to match that of :cite:t:`cole_hierarchical_2000` precisely in a future version of Galacticus..

**Methods**

* ``reform`` — Implements a halo reformation event.

**Parameters**

* ``[energyOrbital]`` (default ``1.0d0``) — The orbital energy used in the "cole2000" merger remnant sizes calculation in units of the characteristic orbital energy.
* ``[ignoreUnphysicalConditions]`` (default ``.false.``) — If true, ignore unphysical conditions (e.g. negative masses) and leave the size unchanged.
* ``[massFactorReformation]`` (default ``2.0d0``) — The factor by which halo mass must have increased to trigger a new formation event.
* ``[reformationOnPromotionOnly]`` (default ``.false.``) — Specifies whether halo reformation should occur only at node promotion events, or at the precise time that the halo mass has increased sufficiently in mass.

.. _physics-mergerProgenitorPropertiesSimple:

``mergerProgenitorPropertiesSimple``
------------------------------------

A merger progenitor properties class which uses a simple calculation.

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

.. _physics-mergerProgenitorPropertiesStandard:

``mergerProgenitorPropertiesStandard``
--------------------------------------

A merger progenitor properties class which implements a standard method to compute progenitor properties. Masses of progenitors are set to

.. math::

   M_\mathrm{host|satellite} = \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j},

where :math:`M_{i,j}` is the mass of mass type :math:`j` in :term:`component` :math:`i`. Masses of progenitors that will end up in the remnant spheroid are set to

.. math::

   M_\mathrm{spheroid\,\,host|satellite} = \sum_{i=\mathrm{disk|spheroid}} \sum_{j=\mathrm{stars|gas}} M_{i,j} \delta_{i,j},

where :math:`\delta_{i,j}=0` of mass type :math:`j` in :term:`component` :math:`i` will end up in the remnant spheroid and :math:`0` otherwise. Radii of material that will end up in the spheroid are set to

.. math::

   r_\mathrm{host|satellite} = {1 \over M_\mathrm{spheroid\,\,host|satellite}} \sum_{i=\mathrm{disk|spheroid}}
   \sum_{j=\mathrm{stars|gas}} M_{i,j} r_{1/2\,\,i,j} \delta_{i,j}.

Finally, the angular momentum factor is set to

.. math::

   f_\mathrm{AM\,\,host|satellite} = {1 \over M_\mathrm{spheroid\,\,host|satellite}} \sum_{i=\mathrm{disk|spheroid}}
   \sum_{j=\mathrm{stars|gas}} M_{i,j} {J_{i,j} \over \mathrm{G} M^{3/2}_{i,j} r_{1/2\,\,i,j}} \delta_{i,j},

where :math:`J_{i,j}` is the angular momentum or pseudo-angular momentum of mass type :math:`j` in :term:`component` :math:`i`.

**(Default implementation)**

**Methods**

* ``factors`` — Compute factors needed for tidal tensor calculation.
* ``tidalTensorGet`` — Get the tidal tensor.

**Parameters**

* ``[stellarDensityChangeBinaryMotion]`` (default ``.true.``) — If true, account for the change in stellar density caused by the black hole binary's motion through the stellar background when computing the hardening rate of the binary via stellar scattering.
* ``[computeVelocityDispersion]`` (default ``.false.``) — Specifies whether or not the velocity dispersion of dark matter and stars should be computed using Jeans equation in black hole binary hardening calculations. If ``false``, then the velocity dispersions are assumed to equal the characteristic velocity of dark matter and spheroid.
* ``[bondiHoyleAccretionEnhancementSpheroid]`` (default ``5.0d0``) — The factor by which the Bondi-Hoyle accretion rate of spheroid gas onto black holes is enhanced.
* ``[bondiHoyleAccretionEnhancementHotHalo]`` (default ``6.0d0``) — The factor by which the Bondi-Hoyle accretion rate of hot halo gas onto black holes is enhanced.
* ``[bondiHoyleAccretionEnhancementNuclearStarCluster]`` (default ``5.0d0``) — The factor by which the Bondi-Hoyle accretion rate of :term:`NSC` gas onto black holes is enhanced.
* ``[bondiHoyleAccretionHotModeOnly]`` (default ``.true.``) — Determines whether accretion from the hot halo should only occur if the halo is in the hot accretion mode.
* ``[bondiHoyleAccretionTemperatureSpheroid]`` (default ``1.0d2``) — The assumed temperature (in Kelvin) of gas in the spheroid when computing Bondi-Hoyle accretion rates onto black holes.
* ``[bondiHoyleAccretionTemperatureNuclearStarCluster]`` (default ``1.0d2``) — The assumed temperature (in Kelvin) of gas in the :term:`NSC` when computing Bondi-Hoyle accretion rates onto black holes.
* ``[instantaneousRecyclingApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing recycling rates.
* ``[instantaneousYieldApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing yield rates.
* ``[instantaneousEnergyInputApproximation]`` (default ``.false.``) — If true, then use an instantaneous recycling approximation when computing energy input rates.
* ``[massLongLived]`` (default ``1.0d0``) — The mass below which stars are assumed to be infinitely long-lived in the instantaneous approximation for stellar evolution.
* ``[ageEffective]`` (default ``13.8d0``) — The effective age to use for computing SNeIa yield when using the instantaneous stellar evolution approximation.
* ``[recycledFraction]`` (default ``0.0d0``) — The recycled fraction to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.)
* ``[metalYield]`` (default ``0.0d0``) — The metal yield to use in the instantaneous stellar evolution approximation. (If not specified it will be computed internally.)
* ``[integrationToleranceRelative]`` (default ``4.0d-3``) — The relative tolerance used when integrating the flux of stellar populations through filters.
* ``[integrationToleranceDegrade]`` (default ``.false.``) — If ``true``, automatically degrade the relative tolerance used when integrating the flux of stellar populations through filters to ensure convergence.
* ``[storeToFile]`` (default ``.true.``) — Specifies whether or not stellar populations luminosities (integrated under a filter) should be stored to file for rapid reuse.
* ``[storeDirectory]`` (default ``inputPath(pathTypeDataDynamic)//'stellarPopulations'``) — Specifies the directory to which stellar populations luminosities (integrated under a filter) should be stored to file for rapid reuse.
* ``[maximumAgeExceededIsFatal]`` (default ``.true.``) — Specifies whether or not exceeding the maximum available age of the stellar population is fatal.
* ``[inactiveBoundMass]`` (default ``.false.``) — Specifies whether or not the bound mass variable of the standard satellite component is inactive (i.e. does not appear in any ODE being solved).
* ``[odeToleranceAbsolute]`` (default ``0.01d0``) — The absolute tolerance used in solving differential equations for node evolution.
* ``[odeToleranceRelative]`` (default ``1.0d-2``) — The relative tolerance used in solving differential equations for node evolution.
* ``[odeJacobianStepSizeRelative]`` (default ``0.01d0``) — The relative step size to use when perturbing properties for purposes of computing a finite difference approximation to the ODE system Jacobian.
* ``[odeAlgorithm]`` (default ``var_str('rungeKuttaCashKarp')``) — The algorithm to use in the ODE solver.
* ``[odeAlgorithmNonJacobian]`` (default ``var_str('rungeKuttaCashKarp')``) — The algorithm to use in the ODE solver.
* ``[odeLatentIntegratorType]`` (default ``var_str('trapezoidal')``) — The type of integrator to use for latent variables.
* ``[odeLatentIntegratorOrder]`` (default ``15``) — The order of the integrator for latent variables.
* ``[odeLatentIntegratorIntervalsMaximum]`` (default ``1000``) — The maximum number of intervals allowed in the integrator for latent variables.
* ``[profileOdeEvolver]`` (default ``.false.``) — Specifies whether or not to profile the ODE evolver.
* ``[reuseODEStepSize]`` (default ``.true.``) — If true, re-use the previous ODE step size when resuming the evolution of a node. Otherwise, the initial step size is not specified.
* ``[enforceNonNegativity]`` (default ``.false.``) — If true, properties that are marked as non-negative (e.g. masses) will be evolved in such a way as to enforce that non-negativity.
* ``[allTreesExistAtFinalTime]`` (default ``.true.``) — Specifies whether or not all merger trees are expected to exist at the final requested output time. If set to false, then trees which finish before a given output time will be ignored.
* ``[dumpTreeStructure]`` (default ``.false.``) — Specifies whether merger tree structure should be dumped to a `dot <http://www.graphviz.org/>`_ file.
* ``[timestepHostRelative]`` (default ``0.1d0``) — The maximum allowed relative timestep for node evolution relative to the time of the host halo.
* ``[timestepHostAbsolute]`` (default ``1.0d0``) — The maximum allowed absolute timestep (in Gyr) for node evolution relative to the time of the host halo.
* ``[fractionTimestepSatelliteMinimum]`` (default ``0.0d0``) — The minimum fraction of the timestep imposed by the "satellite in host" criterion to evolve over. If the timestep allowed is smaller than this fraction, the actual timestep will be reduced to zero. This avoids forcing satellites to take a large number of very small timesteps, and instead defers evolving a satellite until a large timestep can be taken.
* ``[backtrackToSatellites]`` (default ``.false.``) — If true, after successfully evolving a node with satellites, revisit the satellites and attempt to evolve them again.
* ``[profileSteps]`` (default ``.false.``) — Specifies whether or not to profile the ODE evolver.
* ``[outputsGroupName]`` (default ``var_str('Outputs')``) — The name of the HDF5 group to which outputs will be written.
* ``[outputReferences]`` (default ``.false.``) — Specifies whether or not references to individual merger tree datasets should be output.
* ``[xAxisLabel]`` (default ``var_str('x')``) — Axis label for the property (x-axis) of the output analysis.
* ``[yAxisLabel]`` (default ``var_str('y')``) — Axis label for the function value (y-axis) of the output analysis.
* ``[targetLabel]`` (default ``var_str('')``) — Label identifying the comparison/target dataset, if any.
* ``[xAxisIsLog]`` (default ``.false.``) — Whether the x-axis should be displayed on a logarithmic scale.
* ``[yAxisIsLog]`` (default ``.false.``) — Whether the y-axis should be displayed on a logarithmic scale.
* ``[valueTarget]`` — Target dataset values to compare against, one per bin of the output analysis.
* ``[covarianceTarget]`` — Target-dataset covariance matrix corresponding to the ``valueTarget`` array.
* ``[initialMassForSupernovaeTypeII]`` (default ``8.0d0``) — The minimum mass that a star must have in order that is result in a Type II supernova.
* ``[supernovaEnergy]`` (default ``1.0d51``) — The canonical energy released per supernova event (in ergs), used to compute the total mechanical energy input from the supernova population; the default value of :math:`10^{51}` erg corresponds to the standard core-collapse supernova energy.
* ``[efficiency]`` (default ``0.1d0``) — Specifies the efficiency with which outflowing gas is stripped from the hot halo, following the prescription of :cite:author:`font_colours_2008` (:cite:year:`font_colours_2008`; i.e. this is the parameter :math:`\epsilon_\mathrm{strip}` in their eqn. 6).