.. _physics-intergalacticMediumState:

Intergalactic Medium State
==========================

Class providing the thermal and ionization state of the :term:`IGM`---the hydrogen and helium neutral, singly-ionized, and doubly-ionized fractions, the electron fraction, the temperature, and the electron-scattering optical depth as functions of cosmic time. These quantities evolve through the epoch of reionization and affect the cooling rates, photo-ionization suppression, and the UV background modelled elsewhere in Galacticus. The instantaneous Jeans mass computed from the IGM temperature governs the filtering mass scale for baryon accretion onto low-mass halos.

**Default implementation:** ``intergalacticMediumStateRecFast``

Methods
-------

``electronFraction`` → ``double precision``
   Return the electron fraction (relative to hydrogen) in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``neutralHydrogenFraction`` → ``double precision``
   Return the neutral fraction of hydrogen in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``singlyIonizedHydrogenFraction`` → ``double precision``
   Return the singly-ionized fraction of hydrogen in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``neutralHeliumFraction`` → ``double precision``
   Return the neutral fraction of helium in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``singlyIonizedHeliumFraction`` → ``double precision``
   Return the singly-ionized fraction of helium in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``doublyIonizedHeliumFraction`` → ``double precision``
   Return the doubly-ionized fraction of helium in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``metallicity`` → ``double precision``
   Return the metallicity (mass fraction) in the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``temperature`` → ``double precision``
   Return the temperature (in Kelvin) of the :term:`IGM` at the given time.

   * ``double precision, intent(in ) :: time``

``massJeans`` → ``double precision``
   Return the instantaneous Jeans mass (in :math:`\mathrm{M}_\odot`) at the given time.

   * ``double precision, intent(in ) :: time``

``electronScatteringOpticalDepth`` → ``double precision``
   Return the electron scattering optical depth from the present day back to the given ``time`` in the :term:`IGM`.

   * ``double precision, intent(in ) :: time``

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

``electronScatteringTime`` → ``double precision``
   Return the cosmological time at which the given electron scattering ``opticalDepth`` is reached (integrating from the present day) in the :term:`IGM`.

   * ``double precision, intent(in ) :: opticalDepth``

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

.. _physics-intergalacticMediumStateFile:

``intergalacticMediumStateFile``
--------------------------------

An :term:`IGM` state class which reads the state of the intergalactic medium from a file and interpolates in the tabulated results. The HDF5 file containing the table should have the following form:

.. code-block:: none

   HDF5 "igmState.hdf5" {
   GROUP "/" {
      ATTRIBUTE "fileFormat" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SCALAR
         DATA {
         (0): 1
         }
      }
      GROUP "Parameters" {
         ATTRIBUTE "HubbleConstant" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 67.8
            }
         }
         ATTRIBUTE "OmegaBaryon" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 0.0484
            }
         }
         ATTRIBUTE "OmegaDarkEnergy" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 0.692
            }
         }
         ATTRIBUTE "OmegaMatter" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 0.308
            }
         }
         ATTRIBUTE "Y_He" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 0.22
            }
         }
         ATTRIBUTE "temperatureCMB" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 2.725
            }
         }
      }
      DATASET "electronFraction" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 10000 ) / ( 10000 ) }
      }
      DATASET "hIonizedFraction" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 10000 ) / ( 10000 ) }
      }
      DATASET "heIonizedFraction" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 10000 ) / ( 10000 ) }
      }
      DATASET "matterTemperature" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 10000 ) / ( 10000 ) }
         ATTRIBUTE "units" {
            DATATYPE  H5T_STRING {
               STRSIZE 6;
               STRPAD H5T_STR_NULLTERM;
               CSET H5T_CSET_ASCII;
               CTYPE H5T_C_S1;
            }
            DATASPACE  SCALAR
            DATA {
            (0): "Kelvin"
            }
         }
         ATTRIBUTE "unitsInSI" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SCALAR
            DATA {
            (0): 1
            }
         }
      }
      DATASET "redshift" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 10000 ) / ( 10000 ) }
      }
   }
   }

The ``electronFraction``, ``hIonizedFraction``, ``heIonizedFraction``, and ``matterTemperature`` datasets contain the relevant quantity for each redshift in the ``redshift`` dataset.

**Methods**

* ``readFile`` — Read the named power spectrum file.

**Parameters**

* ``[fileName]`` (string) — The name of the file from which to read a tabulated transfer function.

.. _physics-intergalacticMediumStateInstantReionization:

``intergalacticMediumStateInstantReionization``
-----------------------------------------------

The intergalactic medium is assumed to be instantaneously and fully reionized at a fixed redshift, and heated to a fixed temperature. Prior to that, the reionization state is provided by some other class.

**Parameters**

* ``[electronScatteringOpticalDepth]`` (real; ≥ 0.0) — The optical depth to reionization in the instantReionization :term:`IGM` state model.
* ``[reionizationRedshift]`` (real; default ``9.97d0``) — The redshift of reionization in the instantReionization :term:`IGM` state model.
* ``[reionizationTemperature]`` (real; default ``1.0d4``) — The post-reionization temperature (in units of Kelvin) in the instantReionization :term:`IGM` state model.
* ``[presentDayTemperature]`` (real; default ``1.0d3``) — The present day temperature (in units of Kelvin) in the instantReionization :term:`IGM` state model.

.. _physics-intergalacticMediumStateInternal:

``intergalacticMediumStateInternal``
------------------------------------

The state of the intergalactic medium is solved for internally.

.. _physics-intergalacticMediumStateMetallicityAstraeusV:

``intergalacticMediumStateMetallicityAstraeusV``
------------------------------------------------

An :term:`IGM` state class which provides a fit to the metallicity evolution of the :term:`IGM` reported by :cite:t:`ucci_astraeus_2023`.

.. _physics-intergalacticMediumStateMetallicityFixed:

``intergalacticMediumStateMetallicityFixed``
--------------------------------------------

An intergalactic medium state decorator class that overrides the metallicity of an underlying :term:`IGM` state object with a single constant value given by ``[metallicity]``, while passing all other state properties through unchanged. This enables simple models where the :term:`IGM` metallicity is assumed to be uniform and time-independent.

**Parameters**

* ``[metallicity]`` (real) — The metallicity (relative to Solar) of the :term:`IGM`.

.. _physics-intergalacticMediumStateMetallicityPolynomial:

``intergalacticMediumStateMetallicityPolynomial``
-------------------------------------------------

An intergalactic medium state decorator class that overrides the metallicity of an underlying :term:`IGM` state with a redshift-dependent polynomial, :math:`Z(z)/Z_\odot = 10^{\sum_i c_i [\log_{10}(1+z)]^i}`, where the polynomial coefficients :math:`c_i` are provided via ``[coefficients]``. All other state properties are passed through unchanged.

**Parameters**

* ``[coefficients]`` (real) — The polynomial coefficients, :math:`c_i`, in the function :math:`Z(z)/Z_\odot = 10^{\sum_{i=0}^N c_i [\log_{10}(1+z)]^i}`.

.. _physics-intergalacticMediumStateRecFast:

``intergalacticMediumStateRecFast``
-----------------------------------

An :term:`IGM` state class which computes the state of the intergalactic medium using the `RecFast <https://www.astro.ubc.ca/people/scott/recfast.html>`_ code :cite:t:`seager_how_2000,wong_how_2008`. The  RecFast code will be downloaded and run to compute the intergalactic medium state as needed, which will then be stored for future use.

**(Default implementation)**

**Parameters**

* ``[fileName]`` (string) — The name of the file from which to read intergalactic medium state data. *(inherited from* ``intergalacticMediumStateFile``\ *)*

.. _physics-intergalacticMediumStateSimple:

``intergalacticMediumStateSimple``
----------------------------------

An :term:`IGM` state class which implements a simple model of reionization in which the universe is assumed to be fully neutral prior to the redshift given by ``[reionizationRedshift]`` and fully ionized thereafter. The temperature is given by ``[preReionizationTemperature]`` before reionization, and ``[reionizationTemperature]`` thereafter.

**Methods**

* ``calculationReset`` — Reset memoized calculations.

**Parameters**

* ``[reionizationRedshift]`` (real; default ``9.97d0``) — The redshift of reionization in the simple :term:`IGM` state model.
* ``[reionizationTemperature]`` (real; default ``1.0d4``) — The post-reionization temperature (in units of Kelvin) in the simple :term:`IGM` state model.
* ``[preReionizationTemperature]`` (real; default ``10.0d0``) — The pre-reionization temperature (in units of Kelvin) in the simple :term:`IGM` state model.