From 8fd0d4aed4b7934a3a704fe938614685df988305 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Mon, 15 Jul 2024 17:13:08 -0400 Subject: [PATCH] rework the unit test docs (#1570) We split the current page into 3 separate pages and add descriptions for all of the unit tests --- sphinx_docs/source/comprehensive_tests.rst | 119 +++++++++ sphinx_docs/source/index.rst | 11 +- sphinx_docs/source/one_zone_tests.rst | 103 ++++++++ sphinx_docs/source/unit_tests.rst | 280 ++++++++------------- 4 files changed, 332 insertions(+), 181 deletions(-) create mode 100644 sphinx_docs/source/comprehensive_tests.rst create mode 100644 sphinx_docs/source/one_zone_tests.rst diff --git a/sphinx_docs/source/comprehensive_tests.rst b/sphinx_docs/source/comprehensive_tests.rst new file mode 100644 index 0000000000..5ea20ab663 --- /dev/null +++ b/sphinx_docs/source/comprehensive_tests.rst @@ -0,0 +1,119 @@ +************************ +Comprehensive Unit Tests +************************ + +Generally, for each test, you simply type ``make`` in the test +directory. There are a number of runtime parameters that can +control the behavior. These are specified (along with defaults) +in ``_parameters`` files in each test directory and can be +overridden in an inputs file or on the commandline. + +Some additional details on a few of the comprehensive unit tests +are given below. + +EOS test (``test_eos``) +======================= + +``Microphysics/unit_test/test_eos/`` is a unit test for the equations +of state in Microphysics. It sets up a cube of data, with +:math:`\rho`, :math:`T`, and :math:`X_k` varying along the three +dimensions, and then calls the EOS in each zone. Calls are done to +exercise all modes of calling the EOS, in order: + +- ``eos_input_rt``: We call the EOS using :math:`\rho, T`. this is the + reference call, and we save the :math:`h`, :math:`e`, :math:`p`, and + :math:`s` from here to use in subsequent calls. + +- ``eos_input_rh``: We call the EOS using :math:`\rho, h`, to recover + the original :math:`T`. To give the root finder some work to do, we + perturb the initial temperature. + + We store the relative error in :math:`T` in the output file. + +- ``eos_input_tp``: We call the EOS using :math:`T, p`, to recover the + original :math:`\rho`. To give the root finder some work to do, we + perturb the initial density. + + We store the relative error in :math:`\rho` in the output file. + +- ``eos_input_rp``: We call the EOS using :math:`\rho, p`, to recover + the original :math:`T`. To give the root finder some work to do, we + perturb the initial temperature. + + We store the relative error in :math:`T` in the output file. + +- ``eos_input_re``: We call the EOS using :math:`\rho, e`, to recover + the original :math:`T`. To give the root finder some work to do, we + perturb the initial temperature. + + We store the relative error in :math:`T` in the output file. + +- ``eos_input_ps``: We call the EOS using :math:`p, s`, to recover the + original :math:`\rho, T`. To give the root finder some work to do, + we perturb the initial density and temperature. + + Note: entropy is not well-defined for some EOSs, so we only attempt + the root find if :math:`s > 0`. + + We store the relative error in :math:`\rho, T` in the output file. + +- ``eos_input_ph``: We call the EOS using :math:`p, h`, to recover the + original :math:`\rho, T`. To give the root finder some work to do, + we perturb the initial density and temperature. + + We store the relative error in :math:`\rho, T` in the output file. + +- ``eos_input_th``: We call the EOS using :math:`T, h`, to recover the + original :math:`\rho`. To give the root finder some work to do, we + perturb the initial density. + + Note: for some EOSs, :math:`h = h(\rho)` (e.g., an ideal gas), so there + is no temperature dependence, and we do not do this test. + + We store the relative error in :math:`\rho` in the output file. + +This unit test is marked up with OpenMP directives and therefore also +tests whether the EOS is threadsafe. + +To compile for a specific EOS, e.g., helmholtz, do:: + + make EOS_DIR=helmholtz -j 4 + +Examining the output (an AMReX plotfile) will show you how big the +errors are. You can use the ``amrex/Tools/Plotfile/`` tool +``fextrema`` to display the maximum error for each variable. + + +Network test (``test_react``) +============================= + +``Microphysics/unit_test/test_react/`` is a unit test for the nuclear +reaction networks in Microphysics. It sets up a cube of data, with +:math:`\rho`, :math:`T`, and :math:`X_k` varying along the three +dimensions (as a :math:`16^3` domain), and then calls the EOS in each +zone. This test does the entire ODE integration of the network for +each zone. + +The state in each zone of our data cube is determined by the runtime +parameters ``dens_min``, ``dens_max``, ``temp_min``, and ``temp_max`` +for :math:`(\rho, T)`. Because each network carries different +compositions, we specify the composition through runtime parameters in +the ``&extern`` namelist: ``primary_species_1``, +``primary_species_2``, ``primary_species_3``. These primary species +will vary from X = 0.2 to X = 0.7 to 0.9 (depending on the number). +Only one primary species varies at a time. The non-primary species +will be set equally to share whatever fraction of 1 is not accounted +for by the primary species mass fractions. + +This test calls the network on each zone, running for a time +``tmax``. The full state, including new mass fractions and energy +release is output to a AMReX plotfile. + +You can compile for a specific integrator (e.g., ``VODE``) or +network (e.g., ``aprox13``) as:: + + make NETWORK_DIR=aprox13 INTEGRATOR_DIR=VODE -j 4 + +The loop over the burner is marked up for OpenMP and CUDA and +therefore this test can be used to assess threadsafety of the burners +as well as to optimize the GPU performance of the burners. diff --git a/sphinx_docs/source/index.rst b/sphinx_docs/source/index.rst index 5c547fcd43..7b48af3de1 100644 --- a/sphinx_docs/source/index.rst +++ b/sphinx_docs/source/index.rst @@ -24,7 +24,6 @@ for astrophysical simulation codes. data_structures autodiff rp_intro - unit_tests .. toctree:: :maxdepth: 1 @@ -53,7 +52,15 @@ for astrophysical simulation codes. .. toctree:: :maxdepth: 1 - :caption: references + :caption: Unit tests + + unit_tests + comprehensive_tests + one_zone_tests + +.. toctree:: + :maxdepth: 1 + :caption: References zreferences diff --git a/sphinx_docs/source/one_zone_tests.rst b/sphinx_docs/source/one_zone_tests.rst new file mode 100644 index 0000000000..ec9706a05e --- /dev/null +++ b/sphinx_docs/source/one_zone_tests.rst @@ -0,0 +1,103 @@ +************** +One Zone Tests +************** + +There are several tests that let you call the EOS or reaction network +on a single zone to inspect the output directly. + + +``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 +determine the needed ODE tolerances. + + +Getting Started +--------------- + +The ``burn_cell`` code are located in +``Microphysics/unit_test/burn_cell``. To run a simulation, ensure that +both an input file and an initial conditions file have been created +and are in the same directory as the executable. + +Input File +---------- + +These files are typically named as ``inputs_burn_network`` where network +is the network you wish to use for your testing. + +The structure of this file is is fairly self-explanatory. The run +prefix defined should be unique to the tests that will be run as they +will be used to identify all of the output files. Typically, the run +prefix involves the name of the network being tested. The ``atol`` +variables define absolute tolerances of the ordinary differential +equations and the ``rtol`` variables define the relative tolerances. The +second section of the input file collects the inputs that ``main.f90`` +asks for so that the user does not have to input all 5+ +parameters that are required every time the test is run. Each input +required is defined and initialized on the lines following +``&cellparams``. The use of the parameters is show below: + +.. table:: The definition of parameters used in the burn_cell unit tests and specified in the second half of each inputs file. + + +-----------------------+----------------------------------------+ + | ``tmax`` | Maximum Time (s) | + +-----------------------+----------------------------------------+ + | ``nsteps`` | Number of time subdivisions | + +-----------------------+----------------------------------------+ + | ``density`` | State Density (:math:`\frac{g}{cm^3}`) | + +-----------------------+----------------------------------------+ + | ``temperature`` | State Temperature (K) | + +-----------------------+----------------------------------------+ + | ``massfractions(i)`` | Mass Fraction for element i | + +-----------------------+----------------------------------------+ + +Running the Code +---------------- + +To run the code, enter the burn_cell directory and run:: + + ./main3d.gnu.ex inputs + +where ``inputs`` is the name of your inputs file. + +For each of the ``numsteps`` steps defined in the inputs +file, the code will output a files into a new directory titled +``run_prefix_output`` where ``run_prefix`` is the run prefix defined in the +inputs file. Each output file will be named using the run prefix +defined in the inputs file and the corresponding timestep. + +Next, run ``burn_cell.py`` using python 3.x, giving the defined run prefix as an argument. +For example:: + + python3 burn_cell.py react_aprox13 + +The ``burn_cell.py`` code will gather information from all of the +output files and compile them into three graphs explained below. + +Graphs Output by ``burn_cell.py`` +--------------------------------- + +The file ``run-prefix_logX.png`` and ``run-prefix_logX.eps`` will display a +graph of the chemical abundances as a function of the time, both on +logarithmic scales, for all species involved in the simulation. An +example of this graph is shown below. + +.. figure:: react_aprox13_logX.png + :alt: An example of a plot output by the burn_cell unit test. This is the logX output corresponding to the network aprox13. + :width: 4.5in + + An example of a plot output by the burn_cell unit test. This is the + logX output corresponding to the network aprox13. + + + +The file ``run-prefix_ydot.png`` and ``run-prefix_ydot.eps`` will display the +molar fraction (mass fraction / atomic weight) as a function of time, +both on logarithmic scales, for all species involved in the code. + +The file ``run-prefix_T-edot.png`` and ``run-prefix_T-edot.eps`` will display +the temperature and the energy generation rate as a function of time. diff --git a/sphinx_docs/source/unit_tests.rst b/sphinx_docs/source/unit_tests.rst index ab4d58e4b4..d9ba9c5d1e 100644 --- a/sphinx_docs/source/unit_tests.rst +++ b/sphinx_docs/source/unit_tests.rst @@ -1,10 +1,6 @@ -********** -Unit Tests -********** - - -Comprehensive Unit Tests -======================== +********************** +Overview of Unit Tests +********************** There are a few unit tests in Microphysics that operate on a generic EOS, reaction network, conductivity, or some smaller component to @@ -23,229 +19,155 @@ script. Most of these tests work with MPI+OpenMP, MPI+CUDA, and MPI+HIP +Tests are divided into three categories: -EOS test --------- - -``Microphysics/unit_test/test_eos/`` is a unit test for the equations -of state in Microphysics. It sets up a cube of data, with -:math:`\rho`, :math:`T`, and :math:`X_k` varying along the three -dimensions, and then calls the EOS in each zone. Calls are done to -exercise all modes of calling the EOS, in order: - -- ``eos_input_rt``: We call the EOS using :math:`\rho, T`. this is the - reference call, and we save the :math:`h`, :math:`e`, :math:`p`, and - :math:`s` from here to use in subsequent calls. - -- ``eos_input_rh``: We call the EOS using :math:`\rho, h`, to recover - the original :math:`T`. To give the root finder some work to do, we - perturb the initial temperature. - - We store the relative error in :math:`T` in the output file. - -- ``eos_input_tp``: We call the EOS using :math:`T, p`, to recover the - original :math:`\rho`. To give the root finder some work to do, we - perturb the initial density. - - We store the relative error in :math:`\rho` in the output file. - -- ``eos_input_rp``: We call the EOS using :math:`\rho, p`, to recover - the original :math:`T`. To give the root finder some work to do, we - perturb the initial temperature. - - We store the relative error in :math:`T` in the output file. - -- ``eos_input_re``: We call the EOS using :math:`\rho, e`, to recover - the original :math:`T`. To give the root finder some work to do, we - perturb the initial temperature. - - We store the relative error in :math:`T` in the output file. +* *comprehensive tests* work on a cube of data (usually + $\rho$, $T$, and composition varying along the three dimensions) and + are meant to exercise a wide range of input conditions. -- ``eos_input_ps``: We call the EOS using :math:`p, s`, to recover the - original :math:`\rho, T`. To give the root finder some work to do, - we perturb the initial density and temperature. + These are mainly used for regression testing. - Note: entropy is not well-defined for some EOSs, so we only attempt - the root find if :math:`s > 0`. +* *one-zone tests* allow you to evaluate the conditions for a + particular thermodynamic state. - We store the relative error in :math:`\rho, T` in the output file. + These are often used for interactive explorations and within the CI. -- ``eos_input_ph``: We call the EOS using :math:`p, h`, to recover the - original :math:`\rho, T`. To give the root finder some work to do, - we perturb the initial density and temperature. +* *infrastructure tests* test small bits of the solver, function + interfaces, or runtime infrastructure. - We store the relative error in :math:`\rho, T` in the output file. + These are not really meant for exploring the actual thermodynamic + state. -- ``eos_input_th``: We call the EOS using :math:`T, h`, to recover the - original :math:`\rho`. To give the root finder some work to do, we - perturb the initial density. - Note: for some EOSs, :math:`h = h(\rho)` (e.g., an ideal gas), so there - is no temperature dependence, and we do not do this test. - We store the relative error in :math:`\rho` in the output file. +Comprehensive tests +=================== -This unit test is marked up with OpenMP directives and therefore also -tests whether the EOS is threadsafe. +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. -To compile for a specific EOS, e.g., helmholtz, do:: +* ``test_aprox_rates`` : - make EOS_DIR=helmholtz -j 4 + call each of the hardcoded rate functions in ``Microphysics/rates/`` + on each cell in the data cube and store the output in a plotfile. -Examining the output (an AMReX plotfile) will show you how big the -errors are. You can use the ``amrex/Tools/Plotfile/`` tool -``fextrema`` to display the maximum error for each variable. +* ``test_conductivity`` : + call one of the conductivity routines (set via ``CONDUCTIVITY_DIR``) + on each cell in the data cube and store the output in a plotfile. -Network test ------------- +* ``test_eos`` : -``Microphysics/unit_test/test_react/`` is a unit test for the nuclear -reaction networks in Microphysics. It sets up a cube of data, with -:math:`\rho`, :math:`T`, and :math:`X_k` varying along the three -dimensions (as a :math:`16^3` domain), and then calls the EOS in each -zone. This test does the entire ODE integration of the network for -each zone. + call one of the equations of state (set via ``EOS_DIR``) on each + cell in the data cube. We first call it with $(\rho, T, X_k)$ as + input (``eos_input_rt``), and then test each of the other EOS modes + (``eos_input_rh``, ``eos_input_tp``, ``eos_input_rp``, + ``eos_input_re``, ``eos_input_ps``, ``eos_input_ph``, + ``eos_input_th``) and for each of these modes, we compute the error + in the recovered $T$ and/or $\rho$ (as appropriate). The full + thermodynamic state and errors are stored in a plotfile. -The state in each zone of our data cube is determined by the runtime -parameters ``dens_min``, ``dens_max``, ``temp_min``, and ``temp_max`` -for :math:`(\rho, T)`. Because each network carries different -compositions, we specify the composition through runtime parameters in -the ``&extern`` namelist: ``primary_species_1``, -``primary_species_2``, ``primary_species_3``. These primary species -will vary from X = 0.2 to X = 0.7 to 0.9 (depending on the number). -Only one primary species varies at a time. The non-primary species -will be set equally to share whatever fraction of 1 is not accounted -for by the primary species mass fractions. +* ``test_jac`` : -This test calls the network on each zone, running for a time -``tmax``. The full state, including new mass fractions and energy -release is output to a AMReX plotfile. + for each cell in the data cube, and for a specific network (set via + ``NETWORK_DIR``) call the analytic Jacobian provided by the network + and compute the numerical Jacobian (via finite differencing) and + store the relative difference between each approximation for each + Jacobian element in a plotfile. -You can compile for a specific integrator (e.g., ``VODE``) or -network (e.g., ``aprox13``) as:: +* ``test_neutrino_cooling`` : - make NETWORK_DIR=aprox13 INTEGRATOR_DIR=VODE -j 4 + for each cell in the data cube, call the neutrino cooling function + and store the output in a plotfile. -The loop over the burner is marked up for OpenMP and CUDA and -therefore this test can be used to assess threadsafety of the burners -as well as to optimize the GPU performance of the burners. +* ``test_react`` : + for each cell in the data cube, call the reaction network and + integrate to a specified time. Statistics about the number of RHS + calls are reported at the end. A lot of options can be set via the + inputs file to control the integration. -Aprox Rates Test ----------------- +* ``test_rhs`` : -``Microphysics/unit_test/test_aprox_rates`` just evaluates the -instantaneous reaction rates in ``Microphysics/rates/`` used by the -``iso7``, ``aprox13``, ``aprox19``, and ``aprox21`` reaction networks. -This uses the same basic ideas as the tests above---a cube of data is -setup and the rates are evaluated using each zone's thermodynamic -conditions. This test is not really network specific---it tests all -of the available rates. + for each cell in the data cube, call the network's righthand side and + Jacobian functions and store the output in a plotfile. The network + is controlled by the ``NETWORK_DIR`` variable. +* ``test_screening_templated`` : -Screening Test --------------- + for any of the templated-C++ networks, this test will loop over all of + the rates and calculate the screening factor (the screening routine can + be set via ``SCREEN_METHOD``). The factors for each cell in the data + cube are written to a plotfile. -``Microphysics/unit_test/test_screening`` just evaluates the screening -routine, using the ``aprox21`` reaction network. -This uses the same basic ideas as the tests above---a cube of data is -setup and the rates are evaluated using each zone's thermodynamic -conditions. +* ``test_sdc`` : + similar to ``test_react``, except now we exercise the SDC + integration infrastructure. The conserved state that is input to + the burner is chosen to have a Mach number of $0.1$ (and otherwise + use the thermodynamics from the data cube). No advective terms are + modeled. -``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 -determine the needed ODE tolerances. +One-zone tests +============== +* ``burn_cell`` : -Getting Started ---------------- + given a $\rho$, $T$, and $X_k$, integrate a reaction network through a specified time + and output the new state. -The ``burn_cell`` code are located in -``Microphysics/unit_test/burn_cell``. To run a simulation, ensure that -both an input file and an initial conditions file have been created -and are in the same directory as the executable. +* ``burn_cell_primordial_chem`` : -Input File ----------- + similar to ``burn_cell`` except specific for the primordial chemistry network. -These files are typically named as ``inputs_burn_network`` where network -is the network you wish to use for your testing. +* ``burn_cell_sdc`` : -The structure of this file is is fairly self-explanatory. The run -prefix defined should be unique to the tests that will be run as they -will be used to identify all of the output files. Typically, the run -prefix involves the name of the network being tested. The ``atol`` -variables define absolute tolerances of the ordinary differential -equations and the ``rtol`` variables define the relative tolerances. The -second section of the input file collects the inputs that ``main.f90`` -asks for so that the user does not have to input all 5+ -parameters that are required every time the test is run. Each input -required is defined and initialized on the lines following -``&cellparams``. The use of the parameters is show below: + similar to ``burn_cell`` except this uses the SDC integration code paths. -.. table:: The definition of parameters used in the burn_cell unit tests and specified in the second half of each inputs file. +* ``eos_cell`` : - +-----------------------+----------------------------------------+ - | ``tmax`` | Maximum Time (s) | - +-----------------------+----------------------------------------+ - | ``numsteps`` | Number of time subdivisions | - +-----------------------+----------------------------------------+ - | ``density`` | State Density (:math:`\frac{g}{cm^3}`) | - +-----------------------+----------------------------------------+ - | ``temperature`` | State Temperature (K) | - +-----------------------+----------------------------------------+ - | ``massfractions(i)`` | Mass Fraction for element i | - +-----------------------+----------------------------------------+ + given a $\rho$, $T$, and $X_k$, call the equation of state and print out + the thermodynamic information. -Running the Code ----------------- +* ``nse_table_cell`` : -To run the code, enter the burn_cell directory and run:: + given a $\rho$, $T$, and $Y_e$, evaluate the NSE state via table interpolation + and print it out. - ./main3d.gnu.exe with inputs +* ``test_ase`` : -where ``inputs`` is the name of your inputs file. + for the self-consistent NSE, take a $\rho$, $T$, and $Y_e$, and solve for the NSE + state. Then check the NSE condition to see if we are actually satisfying the NSE + criteria for the network. -For each of the ``numsteps`` steps defined in the inputs -file, the code will output a files into a new directory titled -``run_prefix_output`` where ``run_prefix`` is the run prefix defined in the -inputs file. Each output file will be named using the run prefix -defined in the inputs file and the corresponding timestep. +* ``test_part_func`` -Next, run ``burn_cell.py`` using python 3.x, giving the defined run prefix as an argument. -For example:: + exercise the partition function interpolation for a few select nuclei. - python3 burn_cell.py react_aprox13 -The ``burn_cell.py`` code will gather information from all of the -output files and compile them into three graphs explained below. +Infrastructure tests +==================== -Graphs Output by ``burn_cell.py`` ---------------------------------- +* ``test_linear_algebra`` : -The file ``run-prefix_logX.png`` and ``run-prefix_logX.eps`` will display a -graph of the chemical abundances as a function of the time, both on -logarithmic scales, for all species involved in the simulation. An -example of this graph is shown below. + create a diagonally dominant matrix, multiply it by a test vector, $x$, + to get $b = Ax$, and then call the linear algebra routines to see if we + we recover $x$ from $b$. -.. figure:: react_aprox13_logX.png - :alt: An example of a plot output by the burn_cell unit test. This is the logX output corresponding to the network aprox13. - :width: 4.5in +* ``test_nse_interp`` : - An example of a plot output by the burn_cell unit test. This is the - logX output corresponding to the network aprox13. + run various tests of the NSE interpolation routines. +* ``test_parameters`` : + a simple setup that initializes the runtime parameters and can be + used to test if we can override them at runtime via inputs or the + commandline. This uses both the global data and the struct form + of the runtime parameters. -The file ``run-prefix_ydot.png`` and ``run-prefix_ydot.eps`` will display the -molar fraction (mass fraction / atomic weight) as a function of time, -both on logarithmic scales, for all species involved in the code. +* ``test_sdc_vode_rhs`` : -The file ``run-prefix_T-edot.png`` and ``run-prefix_T-edot.eps`` will display -the temperature and the energy generation rate as a function of time. + a simple driver for the SDC RHS routines. Given a thermodynamic + state, it outputs the RHS that the integrator will see.