Skip to content

Commit d22558f

Browse files
rwestrwest
committed
Adding documentation for new output writers.
1 parent c8bd5ac commit d22558f

2 files changed

Lines changed: 135 additions & 16 deletions

File tree

‎documentation/source/users/rmg/input.rst‎

Lines changed: 40 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1094,8 +1094,10 @@ Setting ``saveSeedToDatabase`` to ``True`` tells RMG (if generating a seed) to a
10941094

10951095
The ``units`` field is set to ``si``. Currently there are no other unit options.
10961096

1097-
Setting ``generateOutputHTML`` to ``True`` will let RMG know that you want to save 2-D images (png files in the local ``species`` folder) of all species in the generated core model. It will save a visualized
1098-
HTML file for your model containing all the species and reactions. Turning this feature off by setting it to ``False`` may save memory if running large jobs.
1097+
Setting ``generateOutputHTML`` to ``True`` will let RMG know that you want to save 2-D images (png files in the local ``species`` folder) of all species in the generated core model.
1098+
It will save a visualized HTML file for your model containing all the species and reactions.
1099+
Turning this feature off by setting it to ``False`` may save memory if running large jobs.
1100+
It can be configured using a dictionary of settings in place of the ``True`` statement, as described below.
10991101

11001102
Setting ``generatePlots`` to ``True`` will generate a number of plots describing the statistics of the RMG job, including the reaction model core and edge size and memory use versus execution time. These will be placed in the output directory in the plot/ folder.
11011103

@@ -1116,8 +1118,8 @@ Setting ``saveSeedModulus`` to ``-1`` will only save the seed from the last iter
11161118
Per-writer Output Configuration
11171119
--------------------------------
11181120

1119-
Each of the following options controls a separate output-format writer. Each
1120-
accepts ``True``, ``False``, or a Python dict with optional keys:
1121+
Each of the following options controls a separate output-format writer.
1122+
Each accepts ``True``, ``False``, or a Python dict with optional keys:
11211123

11221124
* ``'saveInterval'`` *(int)* — positive N writes every N iterations (iteration
11231125
numbering starts at 0); ``-1`` writes only at the very end of the run.
@@ -1140,17 +1142,44 @@ Examples::
11401142

11411143
``generateChemkin`` (default ``True``)
11421144
Controls the Chemkin writer. Output is written to the ``chemkin/`` folder.
1145+
When enabled, Cantera's ``ck2yaml`` converter is also run at the end of the
1146+
job to produce a ``cantera_from_ck/`` folder — see :ref:`output`.
11431147

11441148
``generateRMSYAML`` (default ``True``)
11451149
Controls the RMS YAML writer. Output is written to the ``rms/`` folder.
11461150

1147-
``generateCanteraYAML1`` (default ``False``)
1148-
Controls the Cantera YAML v1 writer. Output is written to the ``cantera1/``
1149-
folder. This writer is disabled by default.
1150-
1151-
``generateCanteraYAML2`` (default ``False``)
1152-
Controls the Cantera YAML v2 writer. Output is written to the ``cantera2/``
1153-
folder. This writer is disabled by default.
1151+
``generateCanteraYAML1`` (default ``False``) *(beta)*
1152+
Controls the *direct* Cantera YAML v1 writer. Output is written to the
1153+
``cantera1/`` folder. Unlike the ``cantera_from_ck`` route (which converts
1154+
a Chemkin file via ``ck2yaml``), this writer constructs the YAML directly
1155+
from RMG's internal Python objects without going through Chemkin at all.
1156+
It runs at every iteration (or on the configured schedule) so you get a
1157+
history of the growing mechanism.
1158+
1159+
.. warning::
1160+
1161+
This writer is in **beta**. The output should be valid Cantera YAML, but
1162+
it has been less extensively tested than the established
1163+
``cantera_from_ck`` route. If both this writer and the Chemkin writer
1164+
are enabled, a ``comparison_report.txt`` is generated at the end of the
1165+
run comparing the two outputs numerically. Please report discrepancies
1166+
on the `RMG-Py issue tracker
1167+
<https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_.
1168+
1169+
``generateCanteraYAML2`` (default ``False``) *(beta)*
1170+
Controls the *direct* Cantera YAML v2 writer. Output is written to the
1171+
``cantera2/`` folder. Like ``generateCanteraYAML1``, this writer bypasses
1172+
the Chemkin intermediate, but instead uses the Cantera Python API
1173+
(``ct.Solution``) to construct and serialise the mechanism. It also runs
1174+
at every iteration (or on the configured schedule).
1175+
1176+
.. warning::
1177+
1178+
This writer is in **beta**. It has been less extensively tested than the
1179+
established ``cantera_from_ck`` route. When enabled alongside the Chemkin
1180+
writer, a ``comparison_report.txt`` is generated at the end of the run.
1181+
Please report discrepancies on the `RMG-Py issue tracker
1182+
<https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_.
11541183

11551184
``generateOutputHTML`` (default ``False``)
11561185
Controls the HTML species-visualisation writer. Output is written to the

‎documentation/source/users/rmg/output.rst‎

Lines changed: 95 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,17 @@
44
Analyzing the Output Files
55
**************************
66

7-
You will see that a sucessfully executed RMG job will create multiple output files and folders:
7+
You will see that a sucessfully executed RMG job will create multiple output files and folders:
88
``output.html`` (if ``generateOutputHTML=True`` is specified)
9+
``/cantera_from_ck``
10+
``/cantera1`` (if ``generateCanteraYAML1=True`` is specified)
11+
``/cantera2`` (if ``generateCanteraYAML2=True`` is specified)
912
``/chemkin``
10-
``/pdep``
13+
``/pdep``
1114
``/plot``
15+
``/rms``
1216
``/solver``
13-
``/species``
17+
``/species``
1418
``RMG.log``
1519

1620
------------------
@@ -39,6 +43,92 @@ network.
3943

4044
------------------
4145
The Solver Folder
42-
------------------
43-
RMG currently includes a solver for isothermal batch reactors. This is in fact a critical part of the model enlargement algorithm. If you have included simulations in your input file, the solutions will be located in ``/solver``. You will probably only be interested in the files with the largest number tags.
46+
------------------
47+
RMG currently includes a solver for isothermal batch reactors. This is in fact a critical part of the model enlargement algorithm. If you have included simulations in your input file, the solutions will be located in ``/solver``. You will probably only be interested in the files with the largest number tags.
4448
Please note that up to and including RMG-Py version 2.3.0 these files showed mole fraction of each species at each step, but they now show amount (number of moles) of each species; you must divide by the sum if you wish to get a mole fraction.
49+
50+
------------------------------
51+
Cantera Output Folders
52+
------------------------------
53+
54+
RMG can write mechanisms in `Cantera <https://cantera.org>`_ YAML format via three distinct
55+
routes, producing up to three output folders. All three require Cantera to be installed in
56+
the conda environment (it is included in the standard ``rmg_env``).
57+
58+
``/cantera_from_ck``
59+
^^^^^^^^^^^^^^^^^^^^
60+
61+
This folder is always produced when the Chemkin writer is enabled (``generateChemkin=True``, the default).
62+
After the final RMG iteration, Cantera's own ``ck2yaml`` converter is used to translate the Chemkin-format files in ``/chemkin`` into Cantera YAML.
63+
This is the most thoroughly tested route and is the recommended output for production use.
64+
65+
``/cantera1`` *(beta)*
66+
^^^^^^^^^^^^^^^^^^^^^^
67+
68+
.. note::
69+
70+
The ``cantera1`` writer is in **beta**. It uses the Cantera Python API to construct and
71+
serialise the mechanism YAML, rather than writing the YAML by hand. It has been less
72+
extensively tested than the ``cantera_from_ck`` route. Please report any discrepancies.
73+
74+
This folder is created when ``generateCanteraYAML1=True`` is set in the ``options()`` block
75+
(disabled by default). The writer runs after every RMG iteration (or on the schedule set by
76+
``saveInterval``), so the folder accumulates a history of the growing mechanism.
77+
78+
Files generated:
79+
80+
* ``chem{NNNN}.yaml`` — mechanism snapshot at the iteration when the core contained *NNNN*
81+
species (e.g. ``chem0042.yaml``)
82+
* ``chem.yaml`` — copy of the latest snapshot; always reflects the current model state
83+
* ``chem_annotated.yaml`` — annotated version with SMILES, source, and kinetics comments
84+
(written when ``verboseComments=True`` for this writer)
85+
* ``chem_edge{NNNN}.yaml`` / ``chem_edge.yaml`` / ``chem_edge_annotated.yaml`` — edge-model
86+
equivalents (written when ``saveEdge=True``)
87+
* ``comparison_report.txt`` — numerical comparison of ``chem.yaml`` against the
88+
``cantera_from_ck`` translation (written at the end of the run if both writers are enabled;
89+
see below)
90+
91+
``/cantera2`` *(beta)*
92+
^^^^^^^^^^^^^^^^^^^^^^
93+
94+
.. note::
95+
96+
The ``cantera2`` writer is in **beta**. It generates Cantera YAML directly from RMG's
97+
internal Python data structures, without going through the Chemkin intermediate. While
98+
it should produce valid mechanisms, it has been less extensively tested than the
99+
``cantera_from_ck`` route. Please report any discrepancies.
100+
101+
This folder is created when ``generateCanteraYAML2=True`` is set in the ``options()`` block
102+
(disabled by default). Like ``cantera1``, it runs at every iteration (or on the configured
103+
schedule).
104+
105+
Files generated:
106+
107+
* ``chem{NNNN}.yaml`` / ``chem.yaml`` — latest mechanism snapshot and its labelled history
108+
* ``chem_annotated.yaml`` — annotated version (written when ``verboseComments=True``)
109+
* ``chem_edge{NNNN}.yaml`` / ``chem_edge.yaml`` / ``chem_edge_annotated.yaml`` — edge-model
110+
equivalents (written when ``saveEdge=True``)
111+
* ``comparison_report.txt`` — numerical comparison against the ``cantera_from_ck``
112+
translation (written at the end of the run if both writers are enabled)
113+
114+
Comparison Reports
115+
^^^^^^^^^^^^^^^^^^
116+
117+
When a direct-writer folder (``cantera1`` or ``cantera2``) is used alongside the Chemkin
118+
writer, RMG automatically compares the final ``chem.yaml`` from that folder against the
119+
``cantera_from_ck/chem.yaml`` produced by ``ck2yaml``. The comparison checks differences
120+
in the yaml data. Not all differences are necessarily problematic. Results are written to
121+
``comparison_report.txt`` inside the relevant direct-writer folder.
122+
123+
If you find that the two routes disagree in a problematic way, please open an issue on the
124+
`RMG-Py GitHub repository <https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_
125+
and include the ``comparison_report.txt`` and a minimal reproducing ``input.py``.
126+
127+
------------------------------
128+
The RMS YAML Folder
129+
------------------------------
130+
131+
The ``/rms`` folder contains the mechanism in
132+
`ReactionMechanismSimulator (RMS) <https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl>`_
133+
YAML format. This writer is enabled by default (``generateRMSYAML=True``) and writes at
134+
every iteration, unless configured otherwise by ``saveInterval``.

0 commit comments

Comments
 (0)