@@ -9,97 +9,174 @@ on a single zone to inspect the output directly.
99``burn_cell ``
1010=============
1111
12- .. index :: `` burn_cell``
12+ .. index :: burn_cell
1313
1414``burn_cell `` is a simple one-zone burn that will evolve a state with
1515a network for a specified amount of time. This can be used to
1616understand the timescales involved in a reaction sequence or to
17- determine the needed ODE tolerances.
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+
29+ $T = T(\r ho, 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).
1837
1938
2039Getting Started
2140---------------
2241
23- The ``burn_cell `` code are located in
24- ``Microphysics/unit_test/burn_cell ``. To run a simulation, ensure that
25- both an input file and an initial conditions file have been created
26- and are in the same directory as the executable.
27-
28- Input File
29- ----------
30-
31- These files are typically named as ``inputs_burn_network `` where network
32- is the network you wish to use for your testing.
33-
34- The structure of this file is is fairly self-explanatory. The run
35- prefix defined should be unique to the tests that will be run as they
36- will be used to identify all of the output files. Typically, the run
37- prefix involves the name of the network being tested. The ``atol ``
38- variables define absolute tolerances of the ordinary differential
39- equations and the ``rtol `` variables define the relative tolerances. The
40- second section of the input file collects the inputs that ``main.f90 ``
41- asks for so that the user does not have to input all 5+
42- parameters that are required every time the test is run. Each input
43- required is defined and initialized on the lines following
44- ``&cellparams ``. The use of the parameters is show below:
45-
46- .. table :: The definition of parameters used in the burn_cell unit tests and specified in the second half of each inputs file.
47-
48- +-----------------------+----------------------------------------+
49- | ``tmax `` | Maximum Time (s) |
50- +-----------------------+----------------------------------------+
51- | ``nsteps `` | Number of time subdivisions |
52- +-----------------------+----------------------------------------+
53- | ``density `` | State Density (:math: `\frac {g}{cm^3 }`) |
54- +-----------------------+----------------------------------------+
55- | ``temperature `` | State Temperature (K) |
56- +-----------------------+----------------------------------------+
57- | ``massfractions(i) `` | Mass Fraction for element i |
58- +-----------------------+----------------------------------------+
59-
60- Running the Code
61- ----------------
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, \m athrm{tmax}]$.
108+
109+ If there are multiple steps, then the first output will be at a time
110+ $\m athrm{tmax} / \m athrm{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+
62148
63149To run the code, enter the burn_cell directory and run::
64150
65151 ./main3d.gnu.ex inputs
66152
67153where ``inputs `` is the name of your inputs file.
68154
69- For each of the ``numsteps `` steps defined in the inputs
70- file, the code will output a files into a new directory titled
71- ``run_prefix_output `` where ``run_prefix `` is the run prefix defined in the
72- inputs file. Each output file will be named using the run prefix
73- defined in the inputs file and the corresponding timestep.
74-
75- Next, run ``burn_cell.py `` using python 3.x, giving the defined run prefix as an argument.
76- For example::
77-
78- python3 burn_cell.py react_aprox13
155+ Working with Output
156+ -------------------
79157
80- The ``burn_cell.py `` code will gather information from all of the
81- output files and compile them into three graphs explained below.
158+ .. note ::
82159
83- Graphs Output by ``burn_cell.py ``
84- ---------------------------------
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 ``.
85163
86- The file ``run-prefix_logX.png `` and ``run-prefix_logX.eps `` will display a
87- graph of the chemical abundances as a function of the time, both on
88- logarithmic scales, for all species involved in the simulation. An
89- example of this graph is shown below.
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.
90169
91- .. figure :: react_aprox13_logX.png
92- :alt: An example of a plot output by the burn_cell unit test. This is the logX output corresponding to the network aprox13.
93- :width: 4.5in
170+ The script ``plot_burn_cell.py `` can be used to visualize the evolution:
94171
95- An example of a plot output by the burn_cell unit test. This is the
96- logX output corresponding to the network aprox13.
172+ .. prompt :: bash
97173
174+ python plot_burn_cell.py state_over_time.txt
98175
176+ This will generate the following figure:
99177
100- The file ``run-prefix_ydot.png `` and ``run-prefix_ydot.eps `` will display the
101- molar fraction (mass fraction / atomic weight) as a function of time,
102- both on logarithmic scales, for all species involved in the code.
178+ .. figure :: state.png
179+ :alt: An example of a plot output by the burn_cell unit test.
103180
104- The file `` run-prefix_T-edot.png `` and `` run-prefix_T-edot.eps `` will display
105- the temperature and the energy generation rate as a function of time .
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 ``) .
0 commit comments