SGCHEM ====== A set of routines for modelling gas-phase chemistry and cooling. Several chemical networks are currently implemented: * Network 1 -- primordial chemistry (see Glover 2015 `a `_, `b `_ and refs. therein) * Network 4 -- Simple H chemistry from `Glover & Mac Low (2007) `_ * Network 5 -- Network 4 + approximate CO chemistry from `Nelson & Langer (1997) `_ * Network 15 -- H, C, O network based on `Glover & Mac Low (2007) `_, `Nelson & Langer (1999) `_; see `Glover & Clark (2012) `_ for a full description * Network 10 -- Network 5 + a reduced version of network 1, for a more detailed treatment of the primordial H chemistry. Intended for cosmological simulations. Usage ----- All abundances are given relative to the total number density of hydrogen nuclei: :math:`x_i = \frac{n_i}{n_\mathrm{H}},\quad \mathrm{with}\quad n_\mathrm{H}=\frac{\rho X}{m_p}`, where :math:`X` is the global fraction of hydrogen by mass. Note that with this convention, the :math:`\mathrm{H_2}` abundance is :math:`x_\mathrm{H_2} = 0.5` in gas in which all of the hydrogen is in molecular form. To convert from an abundance :math:`x_i` (by number, relative to H) to a mass fraction :math:`f_i \equiv M_i / M`, simply use :math:`x_i = \frac{1}{X}\frac{m_p}{m_i} f_i`, **Network 1** (Primordial chemisitry): Six chemical species are given in the snapshot files, They are stored in the following order: :math:`\mathrm{H_2,\ H^+,\ D^+,\ HD,\ He^+,\ He^{++}}`. **Network 5** (Simplified hydrogen & NL97 CO chemistry): Three chemical species are given in the snapshot files. They are stored in the following order: :math:`\mathrm{H}_2, \mathrm{H}^+, \mathrm{CO}`. **Network 10** (NL97 & simplified primordial chemistry): Three chemical species are given in the snapshot files. They are stored in the following order: :math:`\mathrm{H}_2, \mathrm{H}^+, \mathrm{CO}`. Additional Parameters --------------------- A number of additional parameter determine the behaviour of the ``SGChem`` module. Their typical values depend on the network being used, which is generally determined by the type of simulation being conducted. In a few cases, the physical meaning of the parameter also changes with the choice of network, which will be indicated in boldface below. Initial Abundances ^^^^^^^^^^^^^^^^^^ SGChemConstInitAbundances Can be set to 0 or 1. If set to 1 and starting with flag 0 (from initial conditions), it sets the relative abundances to the values specified below. SGChemInitH2Abund Initial abundance of :math:`\mathrm{H_2}`. Important for all networks. For cosmological runs: e.g. set to 2.0e-6. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitHPAbund Initial abundance of :math:`\mathrm{H^+}`. Important for all networks. For cosmological runs: e.g. set to 0.0004. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitHePAbund Initial abundance of :math:`\mathrm{He^+}`. Important for all networks. For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitDIIAbund Initial abundance of :math:`\mathrm{D^+}`. Important for network 1 (but needs to be set in any case). For cosmological runs: e.g. set to ``DeutAbund`` :math:`\times` ``SGChemInitHPAbund``. Used if started from initial conditions and with parameter flag ``SGChemConstInitAbundances`` set to 1. SGChemInitHDAbund Initial abundance of :math:`\mathrm{HD}`. Important for network 1 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitHeIIIAbund Initial abundance of :math:`\mathrm{He^{++}}`. Important for network 1 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitCPAbund Initial abundance of :math:`\mathrm{C^+}`. Important for networks 5, 7, 10 and 15 (but needs to be set in any case). Set to 0 otherwise. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitCOAbund Initial abundance of :math:`\mathrm{CO}`. Important for network 15 (but needs to be set in any case). Set to 0 otherwise. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitCHxAbund Initial abundance of the CHx pseduospecies. Important for network 15 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitOHxAbund Initial abundance of the OHx pseduospecies. Important for network 15 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitHCOPAbund Initial abundance of :math:`\mathrm{HCO^+}` Important for network 15 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. SGChemInitMPAbund Initial abundance of :math:`\mathrm{M^+}`. (:math:`\mathrm{M}` is a representative low ionization potential metal used in network 15). Important for network 15 (but needs to be set in any case). For cosmological runs: e.g. set to 0. Used if started from initial conditions and with parameter flag SGChemConstInitAbundances set to 1. Gas Metallicity and Element abundances ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CarbAbund Elemental abundance (by number, relative to hydrogen) of carbon. Set to 0 for network 1, and to a multiple of the local ISM value (1.5e-4) in other cases. Can be obtained from a carbon mass fraction :math:`f_C` through ``CarbAbund`` = :math:`(12X)^{-1}f_C`. OxyAbund Elemental abundance of oxygen. Set to 0 for network 1, and to a multiple of the local ISM value (3.2e-4) in other cases. Can be obtained from an oxygen mass fraction :math:`f_O` through ``OxyAbund`` = :math:`(16X)^{-1}f_O`. MAbund Elemental abundance of "M" [see above]. Set to 0 for network 1. ZAtom Total metallicity, relative to solar. Influences strength of high-temperature atomic cooling rate. Set to 0 for network 1. Can be obtained from a metallicity :math:`Z` through ``ZAtom`` = :math:`Z / Z_\odot`. DeutAbund Elemental abundance of deuterium. Important for network 1. For cosmological runs: e.g. set to 2.6e-5. Other Chemistry Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^ AtomicCoolOption SGCHEM contains several different models for the atomic cooling function at high temperatures. Currently available options are: 1. ... 2. ... 3. ... For runs using network 1, set to 2. H2OpacityOption Determines what approximation is used to model `\mathrm{H_2}` cooling in the optically thick limit. Only important in very dense gas [n > 1e8 cm^-3]. Currently available options are: 0. no opacity correction; use this if the calculation will never reach densities > 1e8 cm^-3 1. power-law fit from Ripamonti & Abel (2004) 2. improved power-law fit from Greif et al (2013) 3. LVG approximation from Clark et al (2011) InitDustTemp Initial dust temperature, needs to be set (but ignored e.g. in network 1). DustToGasRatio Dust-to-gas ratio, relative to the value for the local ISM. Can be varied independently of metallicity. For runs using network 1, should generally be set to 0. SGChemApplySelfShieldingFactor Enable self-shielding of the extragalactic UV background in dense gas following `Rahmati et al. (2013) `_. This applies to the tabulated photometric rates provided through ``SGCHEM_ADD_CONSTANT_PHOTORATES`` (see below). Set to 0 to disable self-shielding, and to 1 to enable it. UVFieldStrength Strength of UV field. This parameter has a **different meaning for different networks**. Depending on the chemistry network selected, a different UV spectrum and normalization convention is used. * For runs using network 1, the spectrum is that of a black body with temperature :math:`T=10^5 \mathrm{\ K}`, cut off at the Lyman limit :math:`h\nu=13.6 \mathrm{\ eV}`. The field intensity is normalized such that setting ``UVFieldStrength=1`` results in a spectral intensity of :math:`J_{\nu} = 10^{-21}` :math:`\mathrm{erg\ s^{-1}\ cm^{-2}\ Hz^{-1}\ sr^{-1}}` at the Lyman limit. In other words, ``UVFieldStrength`` is equivalent to the :math:`J_{21}` parameter used by many high-z studies. * For runs using chemistry networks other than network 1, the `Draine (1978) `_ field is used instead. This field is normalized in `Habing (1968) `_ units, so that ``UVFieldStrength`` corresponds to the :math:`\chi` parameter in Eq. (23) of `Draine & Bertoldi (1996) `_. For the local ISM, an appropriate default value is 1.7 (per Draine, 1978). .. this is the value of the mean specific intensity at the Lyman limit (13.6 eV) in units of [:math:`10^{-21}` :math:`\mathrm{erg\ s^{-1}\ cm^{-2}\ Hz^{-1}\ sr^{-1}}`] - i.e. it's equivalent to the :math:`J_{21}` parameter used by many high-z studies. value of the UV field strength in `Habing (1968) `_ units, given by e.g. Eq. 23 in `Draine & Bertoldi (1996) `_. For the local ISM, an appropriate default value is 1.7 (per `Draine, 1978 `_). :math:`\lambda u_\lambda = 4 \cdot 10^{-14} \chi \lambda_3^{-5} ()`, where :math:`\lambda_3 \equiv \lambda / 10^3 \mathrm{\ \angstrom}`. LWBGType Sets the redshift-evolution of the Lyman-Werner background field, when using network 1. When set to 0, a constant field (parametrized by ``UVFieldStrength``) is assumed throughout the run. When set to 1, the field is turned off before ``LWBGStartRedsh``, and set to the value specified by ``UVFieldStrength`` afterwards. Unused for networks other than 1. LWBGStartRedsh Start redshift for Lyman-Werner background. Unused if ``LWBGType`` is not set to 1. Additional Config.sh Options ---------------------------- SGCHEM Master switch used to enable SGChem framework CHEMISTRYNETWORK Selects chemistry network used in the code. No default: user must explicitly select a network. Currently, valid values are 1, 4, 5 or 15, as described above. [The odd numbering is for historical reasons] MCMA Enables the modified consistent multispecies advection (MCMA) algorithm described in Glover et al (2010), which ensures local conservation of total elemental abundances even when species containing multiple elements (e.g. CO) are advected. Only needed (and implemented) for chemistry network 15. SGCHEM_VARIABLE_Z Allows the metallicity and dust-to-gas ratio to vary between different cells. If this option is not selected, the total gas-phase metallicity, the values of selected elemental abundances (C, O, etc.) and the dust-to-gas ratio are global variables. If this option is selected, these are converted to local variables that can vary from cell to cell. This adds some memory overhead and so is not enabled by default. SGCHEM_VARIABLE_ISRF Allows the strength of the interstellar radiation field to vary spatially. If this option is not selected, the radiation field strength is a global variable (although not a constant - it is still allowed to vary over time). If this option is selected, it becomes a local variable, with a value specified by the find_and_set_local_ISRF routine in sgchem.c. At the moment, this routine assumes that you are running a simulation of a present-day Milky Way type galaxy, but it will be simple to generalize the infrastructure to support other ISRF models. SGCHEM_VARIABLE_CRION Allows the strength of the cosmic ray ionization rate to vary spatially. If this option is not selected, the cosmic ray ionization rate is a global variable. If this option is selected, then it becomes a local variable. If the COSMIC_RAYS option is also selected, the value of the local variable is set by the local cosmic ray energy density. Otherwise, a simple Galactic model is used. See the routine find_and_set_local_CRION in sgchem.c for details. SGCHEM_ADD_CONSTANT_PHOTORATES Adds the option to include a set of constant photometric ionization/heating rates which are added to the chemical rates. This is typically used to model a spatially constant extragalactic UV background (e.g. `Haardt & Madau (2012) `_ or `Faucher-Giguère et al. (2009) `_) Rates can be provided for the following radiative processes: * Ionization of atomic hydrogen: :math:`\mathrm{H} + \gamma \rightarrow \mathrm{H^+} + \mathrm{e^-}` * Heating of atomic hydrogen * Ionization of molecular hydrogen: :math:`\mathrm{H_2} + \gamma \rightarrow \mathrm{H_2^+} + \mathrm{e^-}` * Heating of molecular hydrogen * Photodissociation of molecular hydrogen: :math:`\mathrm{H_2} + \gamma \rightarrow \mathrm{H} + \mathrm{H}` * Heating of dust grains Where photoheating of dust is treated in two separate energy bands: 1. :math:`6\ \mathrm{eV} < h\nu < 13.6\ \mathrm{eV}`. These photons also contribute to photoelectric heating of the gas 2. :math:`h\nu < 6\ \mathrm{eV}`. These softer photons contribute only to determining the dust temperature. These rates can be redshift-dependent and must be provided in CGS units through a HDF5 table. The first four rates can optionally be attenuated to account for self-shielding in dense gas, following the Rahmati et al. (2013) model. This is enabled through the parameter ``SGChemApplySelfShieldingFactor``. CHEM_IMAGE Enables support for the output of chemical and dust information in the makeimage code. SGCHEM_ACCRETION_LUMINOSITY Enables support for accretion luminosity heating from accreting protostars. Only useful in combination with SINK_PARTICLES. Does not account for dust, so only really useful in simulations run with CHEMISTRYNETWORK=1 SGCHEM_NO_HIGHN_DCHEM Disables explicit tracking of deuterium chemistry at high densities (specifically, H nuclei number densities n > 1e8 cm^-3). When selected, the HD/H2 and D+/H+ ratios are assumed to have their equilibrium values. This option is highly recommended for anyone running simulations with primordial gas chemistry (CHEMISTRYNETWORK=1) at very high densities, as it can lead to a very significant speed-up of the chemistry solver. This option has no effect when any of the other chemistry networks are used. SGCHEM_DUMP_THERMAL_RATES Output individual cooling & heating rates for each cell in snapshot. This significantly increases the snapshot size and hence is disabled by default. Currently, only supports chemistry networks 4 and 5. DEBUG_EVOLVE Todo. DEBUG_RATE_EQ These options switch on additional debugging output in the chemistry solver. This can result in immense amounts of data being written to the screen, so you are advised not to turn these options on unless you already know what you are doing. SGCHEM_NO_MOLECULES Switches off all molecular chemistry. Molecular species are still advected, but the chemical source and sink terms are set to zero. May be useful for testing purposes. NOTE: at present, only chemistry network 1 supports this option. Enabling it when running with any other network is useless but should be harmless. SGCHEM_GONG17_TEST Our implementation of the Gong et al. (2017) simplified CO chemistry network (CHEMISTRYNETWORK 16) differs from the one presented in their paper in several respects, in one case because of an error in their implementation and in a number of other cases because we choose to adopt different rate coefficients for some reactions (e.g. H2 formation on dust grains, where we account for the dependence of gas and dust temperatures and Gong et al. do not). However, for testing purposes, it can be useful to run with exactly the same setup as in their tests. This compile-time flag enables this. It should **not** be used for production runs. OLD_CO_SELF_SHIELDING Our default treatment of CO self-shielding and the shielding of CO by H2 is based on Visser et al (2009). However, we have run a number of simulations with a treatment based on the earlier work of Lee et al (1996). This older treatment is selected by this compile-time flag. It is not recommended for new simulations, but is retained in the code for backwards compatibility. Authors ------- * Simon Glover (glover@uni-heidelberg.de) * Rowan Smith (rowanjsmith.astro@googlemail.com) * Paul Clark (paul.clark@astro.cf.ac.uk) * Tilman Hartwig (Tilman.Hartwig@ipmu.jp) [network 1] Acknowledgements ---------------- The authors thank Anna Schauer, Katharina Wollenberg, Mattis Magg, Robin Tress and Ondrej Jaura for their help with testing various aspects of the SGCHEM module. Further thanks go to Anna Schauer for contributing the time-varying LW background option and for helping with the documentation. Usage Policy and Citation ------------------------- Please contact the authors before using this code, so that we can avoid any unnecessary project overlap. Co-authorship on publications produced with the code is not required, although we are happy to actively collaborate with users of the code that are interested in doing so. Papers to cite: * Please contact the authors for details, as the precise list will depend on which features of the code are being used.