[skip ci] Nuclear reaction network documentation

data/net_data/nets/README.rst

@@ -2,6 +2,29 @@
 Reaction Networks
 =================
 
+Default treatment of nuclear energy generation
+----------------------------------------------
+
+By default, MESA tries to include the minimum number of isotopes
+requires to capture with some degree of accuracy the energy generation
+by thermonuclear processes. This is generally sufficient for stellar
+structure calculations, but not for detailed nucleosynthesis studies.
+
+The default behavior (see ``auto_extend_net`` in ``star_job``) is:
+- include only 8 isotopes (h1, he3, he4, c12, n14, o16, ne20, mg24)
+  until central depletion of helium (``basic.net``)
+- add si28 (``co_burn.net``) until central depletion of carbon
+- extend to a 21-isotope nuclear reaction network (``approx21.net``)
+  beyond carbon core burning, including a compound weak reaction that
+  allows for approximate treatment of electron captures and
+  deleptonization when approaching core-collapse.
+
+Each time isotopes and reactions are added to the network, by default
+abundances are re-scaled (see ``adjust_abundances_for_new_isos``).
+
+This default behavior can be changed using the ``change_net`` option
+in ``star_job``, see also ``default_net_name`` in ``controls``.
+
 Summary of available nets
 -------------------------
 

star/defaults/controls.defaults

@@ -6594,10 +6594,13 @@
       ! default_net_name
       ! ~~~~~~~~~~~~~~~~
 
-      ! Name of base reaction network.
-      ! Each net corresponds to a file in ``$MESA_DIR/data/net_data/nets``.
-      ! Look in that directory to see your network options,
-      ! or learn how to create your own net.
+      ! Name of base reaction network (including 8 isotopes to capture energy release)
+      ! Will auto-extend to ``co_burn.net`` (adding si28) at He depletion, and to
+      ! ``approx21.net`` (adding 21 isotopes and a "fake" electron capture reaction for
+      ! deleptonization, see ``fe56ec_fake_factor`` below). Each net corresponds to a
+      ! file in ``$MESA_DIR/data/net_data/nets``. Look in that directory to see
+      ! your network options, or learn how to create your own net.
+      ! See also ``change_net`` and related options in ``star_job.defaults``.
 
       ! ::
 

star/defaults/star_job.defaults

@@ -2380,8 +2380,15 @@
       ! ~~~~~~~~~~~~~~~~~~
 
       ! For switching reaction networks.
-      ! ``new_net_name`` only used if ``change_net`` if true. The list of network names can be found in `$MESA_DIR/data/net_data/nets`.
-
+      ! ``new_net_name`` only used if ``change_net`` if true.
+      ! If not specifying a new_net name, the default is to start with
+      ! ``basic.net`` (8 isotopes), extended to the ``co_burn.net`` (adding si28)
+      ! at helium depletion, and ``approx21.net`` (21 isotopes, including
+      ! compound reaction for electron captures) beyond carbon depletion.
+      ! The full list of network names and the isotopes and reactions
+      ! they include can be found in `$MESA_DIR/data/net_data/nets`.
+      ! See also ``enable_adaptive_network`` and ``auto_extend_net`` below,
+      ! and ``default_net_name`` in ``controls.defaults``
       ! ::
 
     change_net = .false.