From 42ef256c182f7de6242da3bc0e7a26200cffe878 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Wed, 20 Nov 2024 12:41:31 -0500 Subject: [PATCH] start of some doc fixes this improves the landing page and eliminates the preface also remove some old text that is no longer accurate finally, start working on the index --- sphinx_docs/source/data_structures.rst | 10 +++++- sphinx_docs/source/eos.rst | 31 ++++++++++++++----- sphinx_docs/source/getting_started.rst | 6 ++++ sphinx_docs/source/index.rst | 42 ++++++++++++++++++++------ sphinx_docs/source/networks.rst | 2 ++ sphinx_docs/source/nse.rst | 2 ++ sphinx_docs/source/one_zone_tests.rst | 2 ++ sphinx_docs/source/preface.rst | 30 ------------------ sphinx_docs/source/screening.rst | 12 +++++++- sphinx_docs/source/unit_tests.rst | 6 ++++ 10 files changed, 93 insertions(+), 50 deletions(-) delete mode 100644 sphinx_docs/source/preface.rst diff --git a/sphinx_docs/source/data_structures.rst b/sphinx_docs/source/data_structures.rst index a76cf1f0cc..8a4c4ccc3c 100644 --- a/sphinx_docs/source/data_structures.rst +++ b/sphinx_docs/source/data_structures.rst @@ -13,6 +13,8 @@ EOS ``eos_t`` --------- +.. index:: eos_t + The main data structure for interacting with the EOS is ``eos_t``. This is a collection of data specifying the microphysical state of the fluid that we are evaluating. This has many components. For a @@ -49,6 +51,8 @@ Networks ``burn_t`` ---------- +.. index:: burn_t + The main data structure for interacting with the reaction networks is ``burn_t``. This holds the composition (mass fractions), thermodynamic state, and a lot of internal information used by the reaction network @@ -89,7 +93,9 @@ the user will only need to fill/use the following information: ``rate_t``, ``rate_fr_t`` ------------------------- -The ``rate_t`` and ``rate_fr_t`` structures are used internally in a network to pass the +.. index:: rate_t + +The ``rate_t`` structure is used internally in a network to pass the raw reaction rate information (usually just the temperature-dependent terms) between various subroutines. It does not come out of the network-specific righthand side or Jacobian routines. @@ -97,6 +103,8 @@ network-specific righthand side or Jacobian routines. ``burn_type.H`` --------------- +.. index:: burn_type.H + In addition to defining the ``burn_t`` type, the header ``burn_type.H`` also defines integer indices into the solution vector that can be used to access the different components of the state: diff --git a/sphinx_docs/source/eos.rst b/sphinx_docs/source/eos.rst index f49d4987fa..32e13714e7 100644 --- a/sphinx_docs/source/eos.rst +++ b/sphinx_docs/source/eos.rst @@ -43,11 +43,6 @@ The entropy comes from the Sackur-Tetrode equation. Because of the complex way that composition enters into the entropy, the entropy formulation here is only correct for a :math:`\gamma = 5/3` gas. -Note that the implementation provided in Microphysics is the same as -the version shipped with MAESTRO, but more general than the -``gamma_law`` EOS provided with CASTRO. CASTRO’s default EOS only -fills the thermodynamic information in ``eos_t`` that is required -by the hydrodynamics module in CASTRO. polytrope --------- @@ -209,6 +204,8 @@ appropriate interpolation table from that site to use this. Interface and Modes =================== +.. index:: eos_t, eos_re_t, eos_rep_t, eos_rh_t, chem_eos_t + The EOS is called as: .. code:: c++ @@ -244,6 +241,11 @@ The *eos_type* passed in is one of * ``eos_rep_t`` : expands on ``eos_re_t`` to include pressure information +* ``eos_rh_t`` : expands on ``eos_rep_t`` to include enthalpy information + +* ``chem_eos_t`` : adds some quantities needed for the primordial chemistry EOS + and explicitly does not include the mass fractions. + In general, you should use the type that has the smallest set of information needed, since we optimize out needless quantities at compile type (via C++ templating) for ``eos_re_t`` and ``eos_rep_t``. @@ -260,6 +262,7 @@ compile type (via C++ templating) for ``eos_re_t`` and ``eos_rep_t``. Auxiliary Composition --------------------- +.. index:: USE_AUX_THERMO With ``USE_AUX_THERMO=TRUE``, we interpret the composition from the auxiliary variables. The auxiliary variables are @@ -298,6 +301,21 @@ The equation of state also needs :math:`\bar{Z}` which is easily computed as \bar{Z} = \bar{A} Y_e +Composition Derivatives +----------------------- + +.. index:: eos_extra_t, eos_re_extra_t, eos_rep_extra_t + +The derivatives $\partial p/\partial A$, $\partial p/\partial Z$, +and $\partial e/\partial A$, $\partial e/\partial Z$ are available via +the ``eos_extra_t``, ``eos_re_extra_t``, ``eos_rep_extra_t``, which +extends the non-"extra" variants with these additional fields. + +The composition derivatives can be used via the ``composition_derivatives()`` function +in ``eos_composition.H`` +to compute :math:`\partial p/\partial X_k |_{rho, T, X_j}`, :math:`\partial e/\partial X_k |_{rho, T, X_j}`, and :math:`\partial h/\partial X_k |_{rho, T, X_j}`. + + Initialization and Cutoff Values ================================ @@ -328,6 +346,3 @@ appropriate time for, say, loading an interpolation table into memory. The main evaluation routine is called ``actual_eos``. It should accept an eos_input and an eos_t state; see Section :ref:`data_structures`. - - - diff --git a/sphinx_docs/source/getting_started.rst b/sphinx_docs/source/getting_started.rst index a338f28ec6..b02c121249 100644 --- a/sphinx_docs/source/getting_started.rst +++ b/sphinx_docs/source/getting_started.rst @@ -5,6 +5,8 @@ Getting Started Standalone ========== +.. index:: AMREX_HOME + Microphysics can be used in a "standalone" fashion to run the unit tests and explore the behavior of the reaction networks. The main requirement is a copy of AMReX: @@ -23,6 +25,8 @@ to set the ``AMREX_HOME`` environment variable to point to the (where you change ``/path/to/amrex`` to your actual path). +.. index:: burn_cell + A good unit test to start with is ``burn_cell`` -- this is simply a one-zone burn. In ``Microphysics/`` do: @@ -45,6 +49,8 @@ Here ``inputs_aprox21`` is the inputs file that sets options. Running with AMReX Application Code =================================== +.. index:: MICROPHYSICS_HOME + Getting started with Microphysics using either CASTRO or MAESTROeX is straightforward. Because the modules here are already in a format that the AMReX codes understand, you only need to provide to the code diff --git a/sphinx_docs/source/index.rst b/sphinx_docs/source/index.rst index 7b48af3de1..c0e9fc7623 100644 --- a/sphinx_docs/source/index.rst +++ b/sphinx_docs/source/index.rst @@ -6,18 +6,36 @@ AMReX-Astro Microphysics ************************ -A collection of microphysics routines (equations of state, +AMReX-Astro Microphysics is a collection of microphysics routines (equations of state, reaction networks, ...) and utilities (ODE integrators, NSE solvers) for astrophysical simulation codes. -.. toctree:: - :maxdepth: 1 +The original design was to support the `AMReX +`_ codes `CASTRO +`_ and MAESTRO (now `MAESTROeX +`_). These all have a +consistent interface and the separate Microphysics repository allows +them to share the same equation of state, reaction networks, and more. +Later, Microphysics was adopted by the `Quokka `_ +simulation code. + +While there are a number of unit tests that exercise the functionality, +Microphysics is primarily intended to be used along with another simulation +code. At the moment, the interfaces and +build stubs are compatible with the AMReX codes and use the AMReX build +system. + +A number of the routines contained here we authored by other people. +We bundle them here with permission, usually changing the interfaces +to be compatible with our standardized interface. We in particular +thank Frank Timmes for numerous reaction networks and his equation +of state routines. - preface .. toctree:: :maxdepth: 1 :caption: Microphysics overview + :hidden: getting_started design @@ -28,6 +46,7 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 :caption: EOS and transport + :hidden: eos transport @@ -35,6 +54,7 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 :caption: Reaction networks + :hidden: networks-overview networks @@ -44,6 +64,7 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 :caption: ODE integrators + :hidden: integrators ode_integrators @@ -53,6 +74,7 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 :caption: Unit tests + :hidden: unit_tests comprehensive_tests @@ -61,13 +83,13 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 :caption: References + :hidden: zreferences +.. toctree:: + :maxdepth: 1 + :caption: Index + :hidden: -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + genindex diff --git a/sphinx_docs/source/networks.rst b/sphinx_docs/source/networks.rst index e0fd944f00..660054d3a4 100644 --- a/sphinx_docs/source/networks.rst +++ b/sphinx_docs/source/networks.rst @@ -56,6 +56,8 @@ for plotfile variables, and the mass number, :math:`A`, and proton number, :math The name of the inputs file by one of two make variables: +.. index:: NETWORK_INPUTS, GENERAL_NET_INPUTS + * ``NETWORK_INPUTS`` : this is simply the name of the "`.net`" file, without any path. The build system will look for it in the current directory and then in ``$(MICROPHYSICS_HOME)/networks/general_null/``. diff --git a/sphinx_docs/source/nse.rst b/sphinx_docs/source/nse.rst index 67b646b1f4..98861252db 100644 --- a/sphinx_docs/source/nse.rst +++ b/sphinx_docs/source/nse.rst @@ -7,6 +7,8 @@ instead of integrating the entire network when the conditions are appropriate. There are 2 different implementations of NSE in Microphysics, that have slightly different use cases. +.. index:: USE_NSE_TABLE, USE_NSE_NET + * :ref:`tabulated_nse` : this uses a table of NSE abundances given :math:`(\rho, T, Y_e)` generate from a large network (125 isotopes). The table also returns :math:`dY_e/dt` resulting from diff --git a/sphinx_docs/source/one_zone_tests.rst b/sphinx_docs/source/one_zone_tests.rst index ec9706a05e..9352a2e626 100644 --- a/sphinx_docs/source/one_zone_tests.rst +++ b/sphinx_docs/source/one_zone_tests.rst @@ -9,6 +9,8 @@ on a single zone to inspect the output directly. ``burn_cell`` ============= +.. index:: ``burn_cell`` + ``burn_cell`` is a simple one-zone burn that will evolve a state with a network for a specified amount of time. This can be used to understand the timescales involved in a reaction sequence or to diff --git a/sphinx_docs/source/preface.rst b/sphinx_docs/source/preface.rst deleted file mode 100644 index efb680fb48..0000000000 --- a/sphinx_docs/source/preface.rst +++ /dev/null @@ -1,30 +0,0 @@ -******* -Preface -******* - -Welcome to the AMReX-Astro Microphysics! - -In this User’s Guide we describe the microphysics modules designed to -enable simulations of stellar explosions. - -The original design was to support the AMReX codes CASTRO and -MAESTRO. These all have a consistent interface and are designed to -provide the users of those codes an easy experience in moving from the -barebones microphysics modules provided in those codes. For the -purposes of this user’s guide, the microphysical components we -currently deal with are the equation of state (EOS) and the nuclear -burning network. - -Microphysics is not a stand-alone code. It is intended to be used in -conjunction with a simulation code. At the moment, the interfaces and -build stubs are compatible with the AMReX codes. In many cases we -will provide test modules that demonstrate a minimal working example -for how to run the modules (leveraging the AMReX build system). The -goal is to make the support more general, and extend to other codes -in the future. - -A number of the routines contained here we authored by other people. -We bundle them here with permission, usually changing the interfaces -to be compatible with our standardized interface. We in particular -thank Frank Timmes for numerous reaction networks and his equation -of state routines. diff --git a/sphinx_docs/source/screening.rst b/sphinx_docs/source/screening.rst index 1d99a925c7..d1739aeb86 100644 --- a/sphinx_docs/source/screening.rst +++ b/sphinx_docs/source/screening.rst @@ -2,6 +2,8 @@ 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, @@ -51,4 +53,12 @@ The options are: Runtime Options ---------------- -* ``screening.enable_chabrier1998_quantum_corr = 1`` in the input file enables an additional quantum correction term added to the screening factor when ``SCREEN_METHOD=chabrier1998``. This is disabled by default since ``chabrier1998`` is often used along with ``USE_NSE_NET=TRUE``, and the NSE solver doesn't include quantum corrections. + +.. index:: screening.enable_chabrier1998_quantum_corr + +* ``screening.enable_chabrier1998_quantum_corr = 1`` in the input file + enables an additional quantum correction term added to the screening + factor when ``SCREEN_METHOD=chabrier1998``. This is disabled by + default since ``chabrier1998`` is often used along with + ``USE_NSE_NET=TRUE``, and the NSE solver doesn't include quantum + corrections. diff --git a/sphinx_docs/source/unit_tests.rst b/sphinx_docs/source/unit_tests.rst index a95a18de72..5a36b2c4af 100644 --- a/sphinx_docs/source/unit_tests.rst +++ b/sphinx_docs/source/unit_tests.rst @@ -43,6 +43,8 @@ Tests are divided into three categories: Comprehensive tests =================== +.. index:: test_aprox_rates, test_conductivity, test_eos, test_jac, test_neutrino_cooling, test_react, test_rhs, test_screening_templated, test_sdc + Each of these tests sets up a cube of data, $(\rho, T, X_k)$, with the range of $T$ and $\rho$, and the species to focus on for $X_k$ controlled by options in the input file. @@ -113,6 +115,8 @@ by options in the input file. One-zone tests ============== +.. index:: burn_cell, burn_cell_primordial_chem, burn_cell_sdc, eos_cell, jac_cell, nse_table_cell, test_ase, test_part_func + * ``burn_cell`` : given a $\rho$, $T$, and $X_k$, integrate a reaction network through a specified time @@ -157,6 +161,8 @@ One-zone tests Infrastructure tests ==================== +.. index:: test_linear_algebra, test_nse_interp, test_parameters, test_sdc_vode_rhs + * ``test_linear_algebra`` : create a diagonally dominant matrix, multiply it by a test vector, $x$,