SF_ECOGAL
=========

A star formation and feedback module designed for high-resolution simulations with a resolved ISM. Typically used in conjunction with the chemistry module :doc:`modules_sgchem` and the supernova-feedback module :doc:`modules_sne`.

TODO: add a short description of the probabilistic SF approach.

Usage
-----
The ``SF_ECOGAL`` master switch enables the module.

Additional Parameters
---------------------
Star Formation
^^^^^^^^^^^^^^
* ``SF_Mechanism`` Star formation prescription used. This parameter sets the criteria based on which a gas cell is marked as possibly or certainly star-forming. Currently, four modes are available and are labeled by the values 1-4:

  1. **Density threshold only:** In this mode, if a gas cell exceeds the density given by ``SFDensityThreshold``, it *always* forms a star
  2. **Density threshold + probabilistic:** Same as (1), but instead marks the cell as possibly-star-forming. The probabilistic approach is then used to determine whether it forms a star in the current timestep.
  3. **Jeans Mass + probabilistic:** A cell is marked as possibly star-forming if its mass exceeds 1/8th of its local Jeans mass :math:`M_J`. If its mass is larger than :math:`M_J`, a star is immediately formed. 
  4. **Jeans Mass + density threshold + velocity dispersion + probabilistic:** Same as (3) but two additional criteria need to be met by the cell: its density must exceed ``SFDensityThreshold``, and its gas must be converging (:math:`\nabla\cdot v < 0`).

  Note that models 3 & 4 also support additional features:

  * The 1/8 fraction of the Jeans mass can be customized at configuration time through ``JEANS_REFINEMENT`` (see below). 
  * Both can add the additional requirement that a cell must be a local potential peak to be labeled as star-forming. This is enabled with ``SF_ECOGAL_POTENTIALPEAK``.
  * In both models, star formation can be enforced if a given gas number density ``SFDensityThreshold`` is exceeded. This is enabled with ``SF_ECOGAL_FORCE_SF_IN_DENS_GAS``. Note that this requires the use of the SGChem chemistry module.

  To summarize, in the full SF model (model 4 + above additional constraints), a gas cell is possibly star-forming if it respects *all* of the following criteria:

  1. It is a local minimum of the gravitational potential
  2. :math:`\nabla\cdot v < 0`
  3. :math:`\rho \geq \rho_\mathrm{thresh}`
  4. :math:`M_\mathrm{cell} > M_J/N_\mathrm{J,SF}`

  If, in addition, it also satisfies one of the two following criteria, it **certainly** forms a star:

  5. :math:`M_\mathrm{cell} > M_J`
  6. :math:`n > n_\mathrm{thresh}` (only if ``SF_ECOGAL_FORCE_SF_IN_DENS_GAS`` is set)

* ``SFDensityThreshold``
  Density threshold for star formation, used by models 1,2 and 4. Note that this corresponds to a physical (i.e. proper) gas mass density in internal mass density units.
* ``SFEfficiency``
  Star-formation efficiency :math:`\varepsilon`. The star-formation rate (SFR) of a (possibly) star-forming gas cell is defined as

  :math:`\mathrm{SFR} = \varepsilon\frac{M_\mathrm{cell}}{t_\mathrm{ff}}`

* ``StellarTargetMass``
  Target mass of star particles, used when ``SF_ECOGAL_STELLAR_TARGET_MASS`` is set.
* ``ForceSFThreshold``
  Gas number density threshold for star formation, used when ``SF_ECOGAL_FORCE_SF_IN_DENS_GAS`` is set. Note that this corresponds to a physical (i.e. proper) gas number density in internal units.
  
Stellar Feedback setup
^^^^^^^^^^^^^^^^^^^^^^
* ``SNStellarLifetime``
  TODO
* ``LifetimeShorteningFactor``
  TODO
* ``TimeForLifetimeIncrease``
  TODO

Additional Config.sh Options
----------------------------
SF_ECOGAL
  Master switch to enable the module.
SF_ECOGAL_CHECKS
  TODO
SF_ECOGAL_POTENTIALPEAK
  Adds an additional SF criterion, namely that the gas cell must be a local potential peak, to SF mechanisms 3 and 4.
SF_ECOGAL_FORCE_SF_IN_DENS_GAS
  Adds an additional SF criterion, namely that the gas cell must exceed a provided number density threshold. Used for SF mechanisms 3 and 4.
SF_ECOGAL_STELLAR_TARGET_MASS
  Enforces a user-provided target mass for created star particles.
JEANS_REFINEMENT
  Enforce a custom value for the :math:`N_\mathrm{J,SF}` parameter appearing in SF models 3 & 4. A cell is then flagged as possibly star-forming if its mass exceeds 1/``JEANS_REFINEMENT`` of its local Jeans mass. When this flag is not set, :math:`N_\mathrm{J,SF}=8` is used by default.
SF_ECOGAL_FEEDBACK
  Master switch to enable stellar feedback.
SF_ECOGAL_FEEDBACK_REINJECT_MASS
  TODO
SF_ECOGAL_FEEDBACK_PHOTOION
  TODO
SF_ECOGAL_FEEDBACK_PHOTOION_STROMGRENAPPROX
  TODO
SF_ECOGAL_FEEDBACK_PHOTOION_DEBUG
  TODO


Authors
-------

  * Robin Tress (robin.tress@epfl.ch)
  * Junia Goeller (junia.goeller@uni-heidelberg.de)
  * Noé Brucy (noe@brucy.fr)
  * Patrick Hirling (patrick.hirling@epfl.ch)

Acknowledgements
----------------
 
The authors thank ...


Usage Policy and Citation
-------------------------

TODO

Papers to cite:

  * TODO