Skip to content

Commit 3a85d81

Browse files
zingalezingale
authored
Merge branch 'development' into nse_docs_reorg
2 parents 24dfda7 + 8c5e060 commit 3a85d81

16 files changed

+365
-261
lines changed

‎.github/workflows/jac_cell.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ jobs:
3434
- name: Run jac_cell
3535
run: |
3636
cd unit_test/jac_cell
37-
./main3d.gnu.ex inputs_aprox13 > test.out
37+
./main3d.gnu.ex inputs > test.out
3838
3939
- name: Compare to stored output
4040
run: |

‎Docs/source/eos_cell.rst

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _sec:eos_cell:
2+
13
************
24
``eos_cell``
35
************
@@ -69,4 +71,6 @@ Output
6971
======
7072

7173
All output is directed to ``stdout`` and simply lists the entries in the
72-
full ``eos_t`` datatype.
74+
full ``eos_t`` datatype. Example output is shown below:
75+
76+
.. literalinclude:: ../../unit_test/eos_cell/ci-benchmarks/eos_helmholtz.out

‎Docs/source/eos_implementations.rst

+7-2
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,15 @@
22
Available Equations of State
33
****************************
44

5-
.. index:: eos_t
5+
.. index:: eos_t, EOS_DIR
66

77
The following equations of state are available in Microphysics.
88

9+
.. note::
10+
11+
The EOS is chosen at compile-time via the ``EOS_DIR`` make
12+
variable.
13+
914
.. note::
1015

1116
Except where noted, each of these EOSs will provide the full
@@ -188,7 +193,7 @@ the :math:`\gamma_i` for a specific species. The parameters are:
188193
``polytrope``
189194
=============
190195

191-
.. index:: eos.,polytrope_K, eos.polytrope_gamma, eos.polytrope_type, eos.polytrope_mu_e
196+
.. index:: eos.polytrope_K, eos.polytrope_gamma, eos.polytrope_type, eos.polytrope_mu_e
192197

193198
``polytrope`` represents a polytropic fluid, with equation of
194199
state:

‎Docs/source/jac_cell.rst

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
.. _sec:jac_cell:
2+
3+
************
4+
``jac_cell``
5+
************
6+
7+
.. index:: jac_cell, numerical_jacobian.H
8+
9+
``jac_cell`` is used to test the accuracy of an analytic Jacobian
10+
provided by a network, but comparing to a finite-difference
11+
approximation. Given a thermodynamic state, ``jac_cell`` evaluates
12+
the analytic Jacobian as well as a numerical approximation to it, and
13+
then outputs (to ``stdout``) the Jacobian elements side-by-side for
14+
each method of computing the Jacobian.
15+
16+
.. note::
17+
18+
Some integrators, like VODE, have their own numerical Jacobian
19+
routines. This test uses the implementation in
20+
``integration/util/numerical_jacobian.H``, which closely follows the ideas
21+
of the VODE numerical approximation, as described in :cite:`lsode`.
22+
23+
24+
Getting Started
25+
===============
26+
27+
The ``jac_cell`` code is located in
28+
``Microphysics/unit_test/jac_cell``. An inputs file which sets the
29+
default parameters for your thermodynamic state is needed to run the
30+
test.
31+
32+
Setting the thermodynamics
33+
--------------------------
34+
35+
The parameters that affect the thermodynamics are:
36+
37+
* ``unit_test.density`` : the initial density
38+
39+
* ``unit_test.temperature`` : the initial temperature
40+
41+
* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
42+
43+
* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
44+
45+
While the mass fractions can be set individually (using
46+
``unit_test.X1``, ``unit_test.X2``, ...), it is recommended to use
47+
``unit_test.uniform_xn=1`` to initialize all the mass fractions to be
48+
equal.
49+
50+
51+
Building and Running the Code
52+
=============================
53+
54+
The code can be built simply as:
55+
56+
.. prompt:: bash
57+
58+
make
59+
60+
.. note::
61+
62+
By default, this will build with the ``aprox13`` network, which
63+
uses the C++ templating method (:ref:`sec:templated_rhs`) of
64+
building the analytic Jacobian at compile-time. The network can be
65+
changed via the build parameter ``NETWORK_DIR``.
66+
67+
.. important::
68+
69+
The screening routines provided by Microphysics do not return the
70+
derivative of the screening factor with respect to composition. This
71+
means that the analytic Jacobian provided by the network will ignore
72+
this contribution, but the numerical Jacobian will implicitly include
73+
it.
74+
75+
To compare just the network Jacobian elements, it is suggested that
76+
you build with ``SCREEN_METHOD=null``.
77+
78+
79+
The build process will automatically create links in the build
80+
directory to any required EOS table.
81+
82+
To run the code, in the ``jac_cell`` directory run::
83+
84+
./main3d.gnu.ex inputs
85+
86+
where ``inputs`` is the provided inputs file. You may edit the
87+
thermodynamic state in that file prior to running.
88+
89+
90+
Output
91+
======
92+
93+
All output is directed to ``stdout``. Example output is shown below
94+
(this output includes screening, highlighting the difference that the
95+
screening composition derivatives make):
96+
97+
98+
.. literalinclude:: ../../unit_test/jac_cell/ci-benchmarks/jac_cell_aprox13.out

‎Docs/source/networks.rst

+9
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ of state and transport coefficient routines. Even if there are no
77
reactions taking place, a network still needs to be defined, so
88
Microphysics knows the properties of the fluid.
99

10+
.. index:: NETWORK_DIR
11+
12+
.. note::
13+
14+
The network is set at compile-time via the ``NETWORK_DIR``
15+
make variable.
16+
1017
.. tip::
1118

1219
If reactions can be ignored, then the ``general_null`` network can
@@ -21,6 +28,8 @@ Microphysics knows the properties of the fluid.
2128
``general_null``
2229
================
2330

31+
.. index:: general_null
32+
2433
``general_null`` is a bare interface for a nuclear reaction network ---
2534
no reactions are enabled. The
2635
data in the network is defined at compile type by specifying an

‎Docs/source/ode_integrators.rst

+8-3
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,14 @@ provide a routine to convert from the integrator’s internal
1515
representation to the ``burn_t`` type required by the ``actual_rhs``
1616
and ``actual_jac`` routine.
1717

18-
The name of the integrator can be selected at compile time using
19-
the ``INTEGRATOR_DIR`` variable in the makefile. Presently,
20-
the allowed options are:
18+
.. index:: INTEGRATOR_DIR
19+
20+
.. note::
21+
22+
The integrator is chosen at compile-time using
23+
the ``INTEGRATOR_DIR`` variable in the makefile.
24+
25+
Presently, allowed integrators are:
2126

2227
* ``BackwardEuler``: an implicit first-order accurate backward-Euler
2328
method. An error estimate is done by taking 2 half steps and

‎Docs/source/one_zone_tests.rst

+1
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ have analysis scripts, which we describe in the next sections.
1212

1313
burn_cell.rst
1414
eos_cell.rst
15+
jac_cell.rst

‎Docs/source/refs.bib

+9
Original file line numberDiff line numberDiff line change
@@ -774,3 +774,12 @@ @ARTICLE{tillotson:1962
774774
journal = {Internal Report, General Atomics},
775775
url = {https://apps.dtic.mil/sti/citations/AD0486711}
776776
}
777+
778+
@article{lsode,
779+
title = {Description and {Use} of {LSODE}, the {Livermore} {Solver} for {Ordinary} {Differential} {Equations}},
780+
language = {en},
781+
year = {1993},
782+
author = {{Radhakrishnan}, Krishnan and {Hindmarsh}, Alan C.},
783+
journal = {Lawrence Livermore National Laboratory Report UCRL-ID-113855},
784+
pages = {124}
785+
}

‎Docs/source/templated_networks.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _sec:templated_rhs:
2+
13
*********************************
24
Templated Network Righthand Sides
35
*********************************

‎Docs/source/unit_tests.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ One-zone tests
120120
* ``burn_cell`` :
121121

122122
given a $\rho$, $T$, and $X_k$, integrate a reaction network through a specified time
123-
and output the new state.
123+
and output the new state. See :ref:`sec:burn_cell` for more information.
124124

125125
* ``burn_cell_primordial_chem`` :
126126

@@ -133,14 +133,14 @@ One-zone tests
133133
* ``eos_cell`` :
134134

135135
given a $\rho$, $T$, and $X_k$, call the equation of state and print out
136-
the thermodynamic information.
136+
the thermodynamic information. See :ref:`sec:eos_cell` for more information.
137137

138138
* ``jac_cell`` :
139139

140140
for a single thermodynamic state, compute the analytic Jacobian
141141
(using the functions provided by the network) and a numerical
142142
finite-difference approximation to the Jacobian and output them,
143-
element-by-element, to the display.
143+
element-by-element, to the display. See :ref:`sec:jac_cell` for more information.
144144

145145
* ``nse_table_cell`` :
146146

‎unit_test/jac_cell/README.md

+6
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,9 @@
33
For a single thermodynamic condition, evaluate the Jacobian using both
44
the analytic version from the network and the finite-difference
55
numerical approximation.
6+
7+
Note: most analytic Jacobians do not consider the derivative of the
8+
screening factor with respect to composition. To get a more accurate
9+
comparison of how the analytic and numerical terms compare, considering
10+
just the reactive part, build with `SCREEN_METHOD=null`.
11+

‎unit_test/jac_cell/_parameters

-11
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,8 @@
11
@namespace: unit_test
22

3-
run_prefix string ""
4-
53
small_temp real 1.e5
64
small_dens real 1.e5
75

8-
# the final time to integrate to
9-
tmax real 1.e-2
10-
11-
# first output time -- we will output in nsteps logarithmically spaced steps between [tfirst, tmax]
12-
tfirst real 0.0
13-
14-
# number of steps (logarithmically spaced)
15-
nsteps int 100
16-
176
density real 1.e7
187

198
temperature real 3.e9

0 commit comments

Comments
 (0)