Skip to content

Commit ffe1683

Browse files
zingalezingale
authored
split the one_zone_test docs into files (#1726)
this will let us easily document other tests
1 parent 2508d29 commit ffe1683

File tree

2 files changed

+181
-175
lines changed

2 files changed

+181
-175
lines changed

‎Docs/source/burn_cell.rst

+175
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
*************
2+
``burn_cell``
3+
*************
4+
5+
.. index:: burn_cell
6+
7+
``burn_cell`` is a simple one-zone burn that will evolve a state with
8+
a network for a specified amount of time. This can be used to
9+
understand the timescales involved in a reaction sequence or to
10+
determine the needed ODE tolerances. This is designed to work
11+
with the Strang-split integration wrappers. The system that is evolved
12+
has the form:
13+
14+
.. math::
15+
16+
\begin{align*}
17+
\frac{dX_k}{dt} &= \dot{\omega}_k(\rho, X_k, T) \\
18+
\frac{de}{dt} &= \epsilon(\rho, X_k, T)
19+
\end{align*}
20+
21+
with density held constant and the temperature found via the equation of state,
22+
$T = T(\rho, X_k, e)$.
23+
24+
25+
.. note::
26+
27+
Since the energy evolves due to the heat release (or loss)
28+
from reactions, the temperature will change during the burn
29+
(unless ``integrator.call_eos_in_rhs=0`` is set).
30+
31+
32+
Getting Started
33+
===============
34+
35+
The ``burn_cell`` code is located in
36+
``Microphysics/unit_test/burn_cell``. An inputs file which sets the
37+
default parameters for your choice of network is needed to run the
38+
test. There are a number of inputs files in the unit test directory
39+
already with a name list ``inputs_network``, where ``network``
40+
is the network you wish to use for your testing. These can be
41+
used as a starting point for any explorations.
42+
43+
44+
Setting the thermodynamics
45+
--------------------------
46+
47+
The parameters that affect the thermodynamics are:
48+
49+
* ``unit_test.density`` : the initial density
50+
51+
* ``unit_test.temperature`` : the initial temperature
52+
53+
* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
54+
55+
* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
56+
57+
The composition can be set either by setting each mass fraction explicitly via the
58+
parameters, ``unit_test.X1``, ``unit_test.X2``, ...,
59+
e.g.:
60+
61+
::
62+
63+
unit_test.X1 = 0.5
64+
unit_test.X2 = 0.2
65+
unit_test.X3 = 0.2
66+
unit_test.X4 = 0.1
67+
68+
where parameters up to ``X35`` are available. If the values don't sum to ``1``
69+
initially, then the test will do a normalization. This normalization can be
70+
disabled by setting:
71+
72+
::
73+
74+
unit_test.skip_initial_normalization = 1
75+
76+
77+
Alternately, the composition can be set automatically by initializing all
78+
of the mass fractions equally (to $1/N$, where $N$ is the number of species),
79+
by setting:
80+
81+
::
82+
83+
unit_test.init_species_all_equal = 1
84+
85+
86+
Controlling time
87+
----------------
88+
89+
The test will run unit a time ``unit_test.tmax``, outputting the state
90+
at regular intervals. The parameters controlling the output are:
91+
92+
* ``unit_test.tmax`` : the end point of integration.
93+
94+
* ``unit_test.tfirst`` : the first time interval to output.
95+
96+
* ``unit_test.nsteps`` : the number of steps to divide the integration into,
97+
logarithmically-spaced.
98+
99+
If there is only a single step, ``unit_test.nsteps = 1``, then we integrate
100+
from $[0, \mathrm{tmax}]$.
101+
102+
If there are multiple steps, then the first output will be at a time
103+
$\mathrm{tmax} / \mathrm{nsteps}$, and the steps will be
104+
logarithmically-spaced afterwards.
105+
106+
107+
Integration parameters
108+
----------------------
109+
110+
The tolerances, choice of Jacobian, and other integration parameters
111+
can be set via the usual Microphysics runtime parameters, e.g.
112+
``integrator.atol_spec``.
113+
114+
115+
Building and Running the Code
116+
=============================
117+
118+
The code can be built simply as:
119+
120+
.. prompt:: bash
121+
122+
make
123+
124+
and the network and integrator can be changed using the normal
125+
Microphysics build system parameters, e.g.,
126+
127+
.. prompt:: bash
128+
129+
make NETWORK_DIR=aprox19 INTEGRATOR_DIR=rkc
130+
131+
The build process will automatically create links in the build
132+
directory to the EOS table and any reaction rate tables needed by your
133+
choice of network.
134+
135+
136+
.. important::
137+
138+
You need to do a ``make clean`` before rebuilding with a different
139+
network or integrator.
140+
141+
142+
To run the code, enter the burn_cell directory and run::
143+
144+
./main3d.gnu.ex inputs
145+
146+
where ``inputs`` is the name of your inputs file.
147+
148+
Working with Output
149+
===================
150+
151+
.. note::
152+
153+
For this part, we'll assume that the default ``aprox13`` and
154+
``VODE`` options were used for the network and integrator, and the
155+
test was run with ``inputs.aprox13``.
156+
157+
As the code runs, it will output to ``stdout`` details of the initial
158+
and final state and the number of integration steps taken (along with whether
159+
the burn was successful). The full history of the thermodynamic state will also be output to a file,
160+
``state_over_time.txt``, with each line corresponding to one of the
161+
``nsteps`` requested in the time integration.
162+
163+
The script ``plot_burn_cell.py`` can be used to visualize the evolution:
164+
165+
.. prompt:: bash
166+
167+
python plot_burn_cell.py state_over_time.txt
168+
169+
This will generate the following figure:
170+
171+
.. figure:: state.png
172+
:alt: An example of a plot output by the burn_cell unit test.
173+
174+
Only the most abundant species are plotted. The number of species to plot and the
175+
limits of $X$ can be set via runtime parameters (see ``python plot_burn_cell.py -h``).

‎Docs/source/one_zone_tests.rst

+6-175
Original file line numberDiff line numberDiff line change
@@ -3,180 +3,11 @@ One Zone Tests
33
**************
44

55
There are several tests that let you call the EOS or reaction network
6-
on a single zone to inspect the output directly.
6+
on a single zone to inspect the output directly. Some of these
7+
have analysis scripts, which we describe in the next sections.
78

9+
.. toctree::
10+
:maxdepth: 1
11+
:hidden:
812

9-
``burn_cell``
10-
=============
11-
12-
.. index:: burn_cell
13-
14-
``burn_cell`` is a simple one-zone burn that will evolve a state with
15-
a network for a specified amount of time. This can be used to
16-
understand the timescales involved in a reaction sequence or to
17-
determine the needed ODE tolerances. This is designed to work
18-
with the Strang-split integration wrappers. The system that is evolved
19-
has the form:
20-
21-
.. math::
22-
23-
\begin{align*}
24-
\frac{dX_k}{dt} &= \dot{\omega}_k(\rho, X_k, T) \\
25-
\frac{de}{dt} &= \epsilon(\rho, X_k, T)
26-
\end{align*}
27-
28-
with density held constant and the temperature found via the equation of state,
29-
$T = T(\rho, X_k, e)$.
30-
31-
32-
.. note::
33-
34-
Since the energy evolves due to the heat release (or loss)
35-
from reactions, the temperature will change during the burn
36-
(unless ``integrator.call_eos_in_rhs=0`` is set).
37-
38-
39-
Getting Started
40-
---------------
41-
42-
The ``burn_cell`` code is located in
43-
``Microphysics/unit_test/burn_cell``. An inputs file which sets the
44-
default parameters for your choice of network is needed to run the
45-
test. There are a number of inputs files in the unit test directory
46-
already with a name list ``inputs_network``, where ``network``
47-
is the network you wish to use for your testing. These can be
48-
used as a starting point for any explorations.
49-
50-
51-
Setting the thermodynamics
52-
^^^^^^^^^^^^^^^^^^^^^^^^^^
53-
54-
The parameters that affect the thermodynamics are:
55-
56-
* ``unit_test.density`` : the initial density
57-
58-
* ``unit_test.temperature`` : the initial temperature
59-
60-
* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
61-
62-
* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
63-
64-
The composition can be set either by setting each mass fraction explicitly via the
65-
parameters, ``unit_test.X1``, ``unit_test.X2``, ...,
66-
e.g.:
67-
68-
::
69-
70-
unit_test.X1 = 0.5
71-
unit_test.X2 = 0.2
72-
unit_test.X3 = 0.2
73-
unit_test.X4 = 0.1
74-
75-
where parameters up to ``X35`` are available. If the values don't sum to ``1``
76-
initially, then the test will do a normalization. This normalization can be
77-
disabled by setting:
78-
79-
::
80-
81-
unit_test.skip_initial_normalization = 1
82-
83-
84-
Alternately, the composition can be set automatically by initializing all
85-
of the mass fractions equally (to $1/N$, where $N$ is the number of species),
86-
by setting:
87-
88-
::
89-
90-
unit_test.init_species_all_equal = 1
91-
92-
93-
Controlling time
94-
^^^^^^^^^^^^^^^^
95-
96-
The test will run unit a time ``unit_test.tmax``, outputting the state
97-
at regular intervals. The parameters controlling the output are:
98-
99-
* ``unit_test.tmax`` : the end point of integration.
100-
101-
* ``unit_test.tfirst`` : the first time interval to output.
102-
103-
* ``unit_test.nsteps`` : the number of steps to divide the integration into,
104-
logarithmically-spaced.
105-
106-
If there is only a single step, ``unit_test.nsteps = 1``, then we integrate
107-
from $[0, \mathrm{tmax}]$.
108-
109-
If there are multiple steps, then the first output will be at a time
110-
$\mathrm{tmax} / \mathrm{nsteps}$, and the steps will be
111-
logarithmically-spaced afterwards.
112-
113-
114-
Integration parameters
115-
^^^^^^^^^^^^^^^^^^^^^^
116-
117-
The tolerances, choice of Jacobian, and other integration parameters
118-
can be set via the usual Microphysics runtime parameters, e.g.
119-
``integrator.atol_spec``.
120-
121-
122-
Building and Running the Code
123-
-----------------------------
124-
125-
The code can be built simply as:
126-
127-
.. prompt:: bash
128-
129-
make
130-
131-
and the network and integrator can be changed using the normal
132-
Microphysics build system parameters, e.g.,
133-
134-
.. prompt:: bash
135-
136-
make NETWORK_DIR=aprox19 INTEGRATOR_DIR=rkc
137-
138-
The build process will automatically create links in the build
139-
directory to the EOS table and any reaction rate tables needed by your
140-
choice of network.
141-
142-
143-
.. important::
144-
145-
You need to do a ``make clean`` before rebuilding with a different
146-
network or integrator.
147-
148-
149-
To run the code, enter the burn_cell directory and run::
150-
151-
./main3d.gnu.ex inputs
152-
153-
where ``inputs`` is the name of your inputs file.
154-
155-
Working with Output
156-
-------------------
157-
158-
.. note::
159-
160-
For this part, we'll assume that the default ``aprox13`` and
161-
``VODE`` options were used for the network and integrator, and the
162-
test was run with ``inputs.aprox13``.
163-
164-
As the code runs, it will output to ``stdout`` details of the initial
165-
and final state and the number of integration steps taken (along with whether
166-
the burn was successful). The full history of the thermodynamic state will also be output to a file,
167-
``state_over_time.txt``, with each line corresponding to one of the
168-
``nsteps`` requested in the time integration.
169-
170-
The script ``plot_burn_cell.py`` can be used to visualize the evolution:
171-
172-
.. prompt:: bash
173-
174-
python plot_burn_cell.py state_over_time.txt
175-
176-
This will generate the following figure:
177-
178-
.. figure:: state.png
179-
:alt: An example of a plot output by the burn_cell unit test.
180-
181-
Only the most abundant species are plotted. The number of species to plot and the
182-
limits of $X$ can be set via runtime parameters (see ``python plot_burn_cell.py -h``).
13+
burn_cell.rst

0 commit comments

Comments
 (0)