Added RTD dcumentation of the EAGLE entropy floor.

doc/RTD/source/SubgridModels/EAGLE/index.rst

@@ -14,6 +14,59 @@ the parameters and values output in the snapshots.
 Entropy floors
 ~~~~~~~~~~~~~~
 
+The gas particles in the EAGLE model are prevented from cooling below a
+certain temperature. The temperature limit depends on the density of the
+particles. Two floors are used in conjonction. Both are implemented as
+polytropic "equations of states" :math:`P = P_c
+\left(\rho/\rho_c\right)^\gamma`, with the constants derived from the user
+input given in terms of temperature and Hydrogen number density.
+
+The first limit, labelled as ``Cool``, is typically used to prevent
+low-density high-metallicity particles to cool below the warm phase because
+of over-cooling induced by the absence of metal diffusion. This limit plays
+only a small role in practice. The second limit, labelled as ``Jeans``, is
+used to prevent the fragmentation of high-density gas into clumps that
+cannot be resolved by the solver. The two limits are sketched on the
+following figure. An additional over-density criterion is applied to
+prevent gas not collapsed into structures from being affected.
+
+.. figure:: EAGLE_entropy_floor.svg
+    :width: 400px
+    :align: center
+    :figclass: align-center
+    :alt: Phase-space diagram displaying the two entropy floors used
+	  in the EAGLE model.
+
+    Temperature-density plane with the two entropy floors used in the EAGLE
+    model indicated by the black lines. Gas particles are not allowed to be
+    below either of these two floors; they are hence forbidden to enter the
+    grey-shaded region. The floors are specified by the position in the
+    plane of the starting point of each line (black circle) and their slope
+    (dashed lines). The parameter names governing the behaviour of the
+    floors are indicated on the figure. Note that unlike what is shown on
+    the figure for clarity reasons, typical values for EAGLE runs place
+    both anchors at the same temperature.
+
+
+The model is governed by 4 parameters for each of the two
+limits. These are given in the ``EAGLEEntropyFloor`` section of the
+YAML file. The parameters are the Hydrogen number density (in
+:math:`cm^{-3}`) and temperature (in :math:`K`) of the anchor point of
+each floor as well as the power-law slope of each floor and the
+minimal over-density required to apply the limit [#f1]_. For a normal
+EAGLE run, that section of the parameter file reads:
+
+.. code:: YAML
+
+  EAGLEEntropyFloor:
+     Jeans_density_threshold_H_p_cm3: 0.1       # Physical density above which the EAGLE Jeans limiter entropy floor kicks in, expressed in Hydrogen atoms per cm^3.
+     Jeans_over_density_threshold:    10.       # Overdensity above which the EAGLE Jeans limiter entropy floor can kick in.
+     Jeans_temperature_norm_K:        8000      # Temperature of the EAGLE Jeans limiter entropy floor at the density threshold, expressed in Kelvin.
+     Jeans_gamma_effective:           1.3333333 # Slope the of the EAGLE Jeans limiter entropy floor
+     Cool_density_threshold_H_p_cm3:  1e-5      # Physical density above which the EAGLE Cool limiter entropy floor kicks in, expressed in Hydrogen atoms per cm^3.
+     Cool_over_density_threshold:     10.       # Overdensity above which the EAGLE Cool limiter entropy floor can kick in.
+     Cool_temperature_norm_K:         8000      # Temperature of the EAGLE Cool limiter entropy floor at the density threshold, expressed in Kelvin.
+     Cool_gamma_effective:            1.        # Slope the of the EAGLE Cool limiter entropy floor
 
 
 .. _EAGLE_chemical_tracers:
@@ -25,7 +78,7 @@ The gas particles in the EAGLE model carry metal abundance information in the
 form of metal mass fractions. We follow explicitly 9 of the 11 elements that
 `Wiersma et al. (2009)b <http://adsabs.harvard.edu/abs/2009MNRAS.399..574W>`_
 traced in their chemical enrichment model. These are: `H`, `He`, `C`, `N`, `O`,
-`Ne`, `Mg`, `Si` and `Fe` [#f1]_. We additionally follow the total metal mass fraction
+`Ne`, `Mg`, `Si` and `Fe` [#f2]_. We additionally follow the total metal mass fraction
 (i.e. absolute metallicity) `Z`. This is typically larger than the sum of the 7
 metals that are individually traced since this will also contain the
 contribution of all the elements that are not individually followed.  We note
@@ -343,9 +396,15 @@ Black-hole accretion
 AGN feedback
 ~~~~~~~~~~~~
 
-.. [#f1] `Wiersma et al. (2009)b
+.. [#f1] Recall that in a non-cosmological run the critical density is
+	 set to 0, effectively removing the over-density
+	 constraint of the floors.
+
+.. [#f2] `Wiersma et al. (2009)b
 	 <http://adsabs.harvard.edu/abs/2009MNRAS.399..574W>`_ originally also
 	 followed explicitly `Ca` and and `S`. They are omitted in the EAGLE
 	 model but, when needed, their abundance with respect to solar is
 	 assumed to be the same as the abundance of `Si` with respect to solar
 	 (See the section :ref:`EAGLE_cooling`)
+
+

doc/RTD/source/SubgridModels/EAGLE/plot_EAGLE_entropy_floor.py

+import matplotlib
+matplotlib.use("Agg")
+from pylab import *
+from scipy import stats
+
+# Plot parameters
+params = {
+    "axes.labelsize": 10,
+    "axes.titlesize": 10,
+    "font.size": 9,
+    "legend.fontsize": 9,
+    "xtick.labelsize": 10,
+    "ytick.labelsize": 10,
+    "text.usetex": True,
+    "figure.figsize": (3.15, 3.15),
+    "figure.subplot.left": 0.15,
+    "figure.subplot.right": 0.99,
+    "figure.subplot.bottom": 0.13,
+    "figure.subplot.top": 0.99,
+    "figure.subplot.wspace": 0.15,
+    "figure.subplot.hspace": 0.12,
+    "lines.markersize": 6,
+    "lines.linewidth": 2.0,
+    "text.latex.unicode": True,
+}
+rcParams.update(params)
+rc("font", **{"family": "sans-serif", "sans-serif": ["Times"]})
+
+# Equations of state
+eos_cool_rho = np.logspace(-5, 5, 1000)
+eos_cool_T = eos_cool_rho**0. * 8000.
+eos_Jeans_rho = np.logspace(-1, 5, 1000)
+eos_Jeans_T = (eos_Jeans_rho/ 10**(-1))**(1./3.) * 4000.
+
+# Plot the phase space diagram
+figure()
+subplot(111, xscale="log", yscale="log")
+plot(eos_cool_rho, eos_cool_T, 'k-', lw=1.)
+plot(eos_Jeans_rho, eos_Jeans_T, 'k-', lw=1.)
+plot([1e-10, 1e-5], [8000, 8000], 'k:', lw=0.6)
+plot([1e-10, 1e-1], [4000, 4000], 'k:', lw=0.6)
+plot([1e-5, 1e-5], [20, 8000], 'k:', lw=0.6)
+plot([1e-1, 1e-1], [20, 4000], 'k:', lw=0.6)
+plot([3e-6, 3e-4], [28000, 28000], 'k--', lw=0.6)
+text(3e-6, 22500, "$n_{\\rm H}~\\widehat{}~{\\tt Cool\\_gamma\\_effective}$", va="top", fontsize=7)
+plot([3e-1, 3e1], [15000., 15000.*10.**(2./3.)], 'k--', lw=0.6)
+text(3e-1, 200000, "$n_{\\rm H}~\\widehat{}~{\\tt Jeans\\_gamma\\_effective}$", va="top", rotation=43, fontsize=7)
+text(0.95e-5, 25, "${\\tt Cool\\_density\\_threshold\\_H\\_p\\_cm3}$", rotation=90, va="bottom", ha="right", fontsize=7)
+text(0.95e-1, 25, "${\\tt Jeans\\_density\\_threshold\\_H\\_p\\_cm3}$", rotation=90, va="bottom", ha="right", fontsize=7)
+text(5e-8, 8800, "${\\tt Cool\\_temperature\\_norm\\_K}$", va="bottom", fontsize=7)
+text(5e-8, 4400, "${\\tt Jeans\\_temperature\\_norm\\_K}$", va="bottom", fontsize=7)
+fill_between([1e-5, 1e5], [10, 10], [8000, 8000], color='0.9')
+fill_between([1e-1, 1e5], [4000, 400000], color='0.9')
+scatter([1e-5], [8000], s=4, color='k')
+scatter([1e-1], [4000], s=4, color='k')
+xlabel("${\\rm Density}~n_{\\rm H}~[{\\rm cm^{-3}}]$", labelpad=0)
+ylabel("${\\rm Temperature}~T~[{\\rm K}]$", labelpad=2)
+xlim(3e-8, 3e3)
+ylim(20., 2e5)
+savefig("EAGLE_entropy_floor.png", dpi=200)