Merge branch 'development' into tolerance_compare_plot

Docs/rp.py

@@ -46,6 +46,8 @@ def pretty_category(path):
         return f"CONDUCTIVITY_DIR={subdir}"
     if path.startswith("integration/"):
         return f"INTEGRATOR_DIR={subdir}"
+    if path.startswith("opacity/"):
+        return f"OPACITY_DIR={subdir}"
     return path
 
 
@@ -65,9 +67,9 @@ def make_rest_table(param_files):
 
         # open the file
         try:
-            f = open(pf, "r")
-        except IOError:
-            sys.exit("ERROR: {} does not exist".format(pf))
+            f = open(pf)
+        except OSError:
+            sys.exit(f"ERROR: {pf} does not exist")
 
         descr = r""
 

Docs/source/screening.rst

@@ -4,8 +4,45 @@ Screening of Reaction Rates
 
 .. index:: SCREEN_METHOD
 
-Screening of reaction rates can be computed using several different methods,
-controlled by the make parameter ``SCREEN_METHOD``.  For example,
+Introduction
+------------
+
+Plasma screening is the enhancement of nuclear reaction rates, :math:`R`
+due to the Coulomb coupling of the surrounding plasma and electrons
+and ions. The enhancement of the reaction rates is done via the form:
+
+.. math::
+   R_{\mathrm{scr}} = R \exp{(h)}
+
+where :math:`R_{\mathrm{scr}}` is the screened reaction rate and :math:`h`
+characterizes the magnitude of the screening.
+Plasma screening can be broken up to different regimes depending
+on the Coulomb coupling parameter, :math:`\Gamma`,
+of the reaction rate reactants. Generally, :math:`\Gamma \ll 1` and
+:math:`\Gamma \gtrsim 1` correspond to weak and strong screening regimes,
+respectively. :math:`\Gamma` is defined as:
+
+.. math::
+   \Gamma = \alpha(Z_1, Z_2) \Gamma_e
+
+where :math:`\alpha(Z_1, Z_2)` characterizes the Coulomb strength of
+the reactants, its definition can vary slightly depending on the
+screening routine. :math:`\Gamma_e` is the Coulomb coupling parameter
+depending only on the thermodynamic conditions.
+
+.. math::
+   \Gamma_e= e^2 \frac{\sqrt[3]{4 \pi n_e / 3}}{k_B T}
+
+where :math:`e` is the electron charge and :math:`n_e` is the
+electron number density.
+
+
+Screening Options
+-----------------
+
+The screening enhancement factor can be can be computed using
+several different methods, controlled by the make parameter ``SCREEN_METHOD``.
+For example,
 
 .. prompt:: bash
 
@@ -19,19 +56,24 @@ The options are:
 
   This is the screening routine from the Kepler stellar evolution code
   and is the default used with the distributed versions of the "aprox"
-  family of reaction networks.  It uses the screening described in
-  :cite:`graboske:1973` for the weak limit and :cite:`jancovici:1977`,
-  :cite:`alastuey:1978`, :cite:`itoh:1979` for the strong limit. The
-  overall procedure is described in :cite:`Wallace:1982`.
+  family of reaction networks. In the weak screenng regime,
+  :math:`\Gamma < 0.3`, it uses screening described in
+  :cite:`graboske:1973`. In the strong screening regime,
+  :math:`\Gamma > 0.8`, it uses screening described in
+  :cite:`jancovici:1977`, :cite:`alastuey:1978`, :cite:`itoh:1979`.
+  For the intermediate screening regime, :math:`0.3 < \Gamma < 0.8`,
+  a weighted blending between the weak and strong screening are used.
+  The overall procedure is described in :cite:`Wallace:1982`.
 
   This is the default screening method.
 
 * ``chugunov2007`` :
 
   This implements the screening of :cite:`chugunov:2007`, following
-  :cite:`yakovlev:2006` to extend to binary mixtures.
+  :cite:`yakovlev:2006` to extend to binary mixtures. It is suitable
+  for :math:`\Gamma \lesssim 600`.
 
-* ``chugunov2009``
+* ``chugunov2009`` :
 
   This implements the screening of :cite:`chugunov:2009`.  The main
   difference is that the 2007 one calculates an effective coupling
@@ -42,17 +84,23 @@ The options are:
   This includes the portion in the appendix that blends in the weak
   screening limit.
 
-* ``chabrier1998``:
+* ``chabrier1998`` :
 
-  This implements the screening of :cite:`Chabrier_1998` as well as the quantum corrections for strong screening according to screen5. This is suggested in the appendix of :cite:`Calder_2007`. This screening is compatible with NSE calculations unlike ``screen5``, ``chugunov2007``, and ``chugunov2009``. This screening should be valid in the weak screening regime, :math:`\Gamma < 0.1`, and strong screening regime, :math:`1 \lesssim \Gamma \lesssim 160`.
+  This implements the screening of :cite:`Chabrier_1998` as well as
+  the quantum corrections for strong screening according to screen5,
+  which is suggested in the appendix of :cite:`Calder_2007`.
+  This screening is compatible with NSE calculations unlike ``screen5``,
+  ``chugunov2007``, and ``chugunov2009``. This screening is valid in the
+  weak screening regime, :math:`\Gamma < 0.1`, and strong screening regime,
+  :math:`1 \lesssim \Gamma \lesssim 160`.
 
 * ``null`` :
 
   This disables screening by always returning 1 for the screening
   enhancement factor.
 
 Runtime Options
-----------------
+---------------
 
 .. index:: screening.enable_chabrier1998_quantum_corr
 

EOS/gamma_law/_parameters

@@ -1,4 +1,9 @@
 @namespace: eos
 
+# ratio of specific heats
 eos_gamma            real     5.e0/3.e0
-eos_assume_neutral   bool     1
+
+# when computing mu / Abar, do we assume that the composition is atoms
+# or ionized, and therefore include the electron contributions
+# separately?
+eos_assume_neutral bool 1

EOS/multigamma/_parameters

@@ -1,14 +1,25 @@
 @namespace: eos
 
+# default ratio of specific heats used for all components unless specified
+# explicitly as species a, b, or c
 eos_gamma_default       real          1.4
 
+# name of species "a"
 species_a_name          string        ""
+
+# ratio of specific heats for species "a"
 species_a_gamma         real          1.4
 
+# name of species "b"
 species_b_name          string        ""
+
+# ratio of specific heats for species "b"
 species_b_gamma         real          1.4
 
+# name of species "c"
 species_c_name          string        ""
+
+# ratio of specific heats for species "c"
 species_c_gamma         real          1.4
 
 

EOS/polytrope/_parameters

@@ -1,7 +1,17 @@
 @namespace: eos
 
+# polytrope type: 1 is non-relativistic, fully degenerate electron
+# gas; 2 is fully-relativistic, fully degenerate gas.  If these are
+# set, then only pulytrope_mu_e needs to be set.
 polytrope_type       int      0
+
+# density exponent for pressure, P = K rho**gamma
 polytrope_gamma      real     0.0e0
+
+# proportionality constant in EOS, P = K rho**gamma
 polytrope_K          real     0.0e0
+
+# mean molecular weight per electron for the cases when polytrope_type
+# is 1 or 2.  In that case, we have P = K (rho / mu_e)**gamma
 polytrope_mu_e       real     2.0e0
 

EOS/rad_power_law/_parameters

@@ -1,5 +1,10 @@
 @namespace: eos
 
+# specific heat proportionality constant, K, c_v = K rho**m T**(-n)
 eos_const_c_v        real     -1.e0
+
+# specific heat density exponent, m, c_v = K rho**m T**(-n)
 eos_c_v_exp_m        real      0.e0
+
+# specific heat (negative) temperature exponent, n, c_v = K rho**m T**(-n)
 eos_c_v_exp_n        real      0.e0

EOS/tillotson/_parameters

@@ -1,13 +1,27 @@
 @namespace: eos
 
 eos_la               real     0.5
+
 eos_lb               real     1.3
+
+# minimum energy
 eos_e_0              real     1.6e11
+
+# reference density
 eos_rho_0            real     2.7
+
+
 eos_A                real     1.8e11
+
 eos_B                real     1.8e11
+
 eos_e_s              real     3.5e10
+
 eos_e_s_prime        real     1.8e11
+
 eos_alpha            real     5.0
+
 eos_beta             real     5.0
+
+# specific heat
 eos_c_v              real     7.9e6

conductivity/constant/_parameters

@@ -1,5 +1,6 @@
 @namespace: conductivity
 
+# constant value of the conductivity, in erg/s/cm/K
 const_conductivity   real     1.0e0
 
 

conductivity/constant_opacity/_parameters

@@ -1,5 +1,6 @@
 @namespace: conductivity
 
+# opacity value, in units of cm**2/g
 const_opacity        real     7.0e-2
 
 

conductivity/powerlaw/_parameters

@@ -1,6 +1,9 @@
 @namespace: conductivity
 
+# proportionality constant, C, in k = C T**m
 cond_coeff       real 1.0
+
+# temperature exponent, m, in k = C T**m
 cond_exponent    real 1.0
 
 

integration/_parameters

@@ -21,10 +21,17 @@ burner_verbose           bool     0
 
 # Tolerances for the solver (relative and absolute), for the
 # species and energy equations.
+
+# relative tolerance for species
 rtol_spec                real      1.e-12
+
+# relative tolerance for energy
 rtol_enuc                real      1.e-6
 
+# absolute tolerance for species
 atol_spec                real      1.e-8
+
+# absolute tolerance for energy
 atol_enuc                real      1.e-6
 
 # Whether to renormalize the mass fractions at each step in the evolution
@@ -69,10 +76,17 @@ retry_swap_jacobian       bool    1
 # Tolerances for the solver (relative and absolute), for the
 # species and energy equations.  If set to < 0, then the same
 # value as the first attempt is used.
+
+# relative tolerance for species on retry
 retry_rtol_spec                real      -1
+
+# relative tolerance for energy on retry
 retry_rtol_enuc                real      -1
 
+# absolute tolerance for species on retry
 retry_atol_spec                real      -1
+
+# absolute tolerance for energy on retry
 retry_atol_enuc                real      -1
 
 # in the clean_state process, do we clip the species such that they