Merge pull request #2800 to add native Cantera YAML writing

See #2800 for details.

Enable in your options block with:

    generateCanteraYAML1=True,
    generateCanteraYAML2=True,

Or customize with settings like:

    generateChemkin={'saveInterval': 1, 'saveEdge': False},
    generateRMSYAML={'saveInterval': 5},
    generateCanteraYAML1={'saveInterval': 5, 'saveEdge':True},
    generateCanteraYAML2={'saveInterval': 5, 'saveEdge':False, 'verboseComments':True},

See provided examples and documentation for more.

Author: rwest

documentation/source/users/rmg/input.rst

@@ -1073,13 +1073,17 @@ Miscellaneous options::
         units='si',
         generateOutputHTML=True,
         generatePlots=False,
-		generatePESDiagrams=False,
+        generatePESDiagrams=False,
         saveSimulationProfiles=True,
         verboseComments=False,
         saveEdgeSpecies=True,
         keepIrreversible=True,
         trimolecularProductReversible=False,
-        saveSeedModulus=-1
+        saveSeedModulus=-1,
+        generateChemkin=True,
+        generateRMSYAML=True,
+        generateCanteraYAML1=False,
+        generateCanteraYAML2=False,
     )
 
 The ``name`` field is the name of any generated seed mechanisms
@@ -1090,25 +1094,97 @@ Setting ``saveSeedToDatabase`` to ``True`` tells RMG (if generating a seed) to a
 
 The ``units`` field is set to ``si``.  Currently there are no other unit options.
 
-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
-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.
+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 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.
+It can be configured using a dictionary of settings in place of the ``True`` statement, as described below.
 
 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.
 
 Setting ``generatePESDiagrams`` to ``True`` will generate potential energy surface diagrams for each pressure dependent network in the model.  These diagrams will be saved in the ``pdep/`` folder in the output directory. Only applicable if pressure dependence is enabled.
 
 Setting ``saveSimulationProfiles`` to ``True`` will make RMG save csv files of the simulation in .csv files in the ``solver/`` folder.  The filename will be ``simulation_1_26.csv`` where the first number corresponds to the reaciton system, and the second number corresponds to the total number of species at the point of the simulation.  Therefore, the highest second number will indicate the latest simulation that RMG has complete while enlarging the core model.  The information inside the csv file will provide the time, reactor volume in m^3, as well as mole fractions of the individual species.
 
-Setting ``verboseComments`` to ``True`` will make RMG generate chemkin files with complete verbose commentary for the kinetic and thermo parameters.  This will be helpful in debugging what values are being averaged for the kinetics.  Note that this may produce very large files.
+Setting ``verboseComments`` to ``True`` will make RMG generate chemkin files with complete verbose commentary for the kinetic and thermo parameters.  This will be helpful in debugging what values are being averaged for the kinetics.  Note that this may produce very large files.  This is a global fallback; individual writers can override it (see below).
 
-Setting ``saveEdgeSpecies`` to ``True`` will make RMG generate chemkin files of the edge reactions in addition to the core model in files such as ``chem_edge.inp`` and ``chem_edge_annotated.inp`` files located inside the ``chemkin`` folder.  These files will be helpful in viewing RMG's estimate for edge reactions and seeing if certain reactions one expects are actually in the edge or not.
+Setting ``saveEdgeSpecies`` to ``True`` will make RMG generate chemkin files of the edge reactions in addition to the core model in files such as ``chem_edge.inp`` and ``chem_edge_annotated.inp`` files located inside the ``chemkin`` folder.  These files will be helpful in viewing RMG's estimate for edge reactions and seeing if certain reactions one expects are actually in the edge or not.  This is a global fallback; individual writers can override it (see below).
 
 Setting ``keepIrreversible`` to ``True`` will make RMG import library reactions as is, whether they are reversible or irreversible in the library. Otherwise, if ``False`` (default value), RMG will force all library reactions to be reversible, and will assign the forward rate from the relevant library.
 
 Setting ``trimolecularProductReversible`` to ``False`` will not allow families with three products to react in the reverse direction. Default is ``True``.
 
 Setting ``saveSeedModulus`` to ``-1`` will only save the seed from the last iteration at the end of an RMG job. Alternatively, the seed can be saved every ``n`` iterations by setting ``saveSeedModulus`` to ``n``.
 
+Per-writer Output Configuration
+--------------------------------
+
+Each of the following options controls a separate output-format writer.
+Each accepts ``True``, ``False``, or a Python dict with optional keys:
+
+* ``'saveInterval'`` *(int)* — positive N writes every N iterations (iteration
+  numbering starts at 0); ``-1`` writes only at the very end of the run.
+  Defaults to ``1`` (every iteration) for writers that are on by default.
+* ``'verboseComments'`` *(bool, optional)* — overrides the global
+  ``verboseComments`` flag for this writer only.
+* ``'saveEdge'`` *(bool, optional)* — overrides the global ``saveEdgeSpecies``
+  flag for this writer only.
+
+Examples::
+
+    # Chemkin: save only at the end, with verbose comments and edge species
+    generateChemkin={'saveInterval': -1, 'verboseComments': True, 'saveEdge': True}
+
+    # RMS YAML: save every 5 iterations
+    generateRMSYAML={'saveInterval': 5}
+
+    # Cantera YAML v2: save every iteration with verbose comments
+    generateCanteraYAML2={'saveInterval': 1, 'verboseComments': True, 'saveEdge': False}
+
+``generateChemkin`` (default ``True``)
+  Controls the Chemkin writer.  Output is written to the ``chemkin/`` folder.
+  When enabled, Cantera's ``ck2yaml`` converter is also run at the end of the
+  job to produce a ``cantera_from_ck/`` folder — see :ref:`output`.
+
+``generateRMSYAML`` (default ``True``)
+  Controls the RMS YAML writer.  Output is written to the ``rms/`` folder.
+
+``generateCanteraYAML1`` (default ``False``) *(beta)*
+  Controls the *direct* Cantera YAML v1 writer.  Output is written to the
+  ``cantera1/`` folder.  Unlike the ``cantera_from_ck`` route (which converts
+  a Chemkin file via ``ck2yaml``), this writer constructs the YAML directly
+  from RMG's internal Python objects without going through Chemkin at all.
+  It runs at every iteration (or on the configured schedule) so you get a
+  history of the growing mechanism.
+
+  .. warning::
+
+     This writer is in **beta**.  The output should be valid Cantera YAML, but
+     it has been less extensively tested than the established
+     ``cantera_from_ck`` route.  If both this writer and the Chemkin writer
+     are enabled, a ``comparison_report.txt`` is generated at the end of the
+     run comparing the two outputs numerically.  Please report discrepancies
+     on the `RMG-Py issue tracker
+     <https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_.
+
+``generateCanteraYAML2`` (default ``False``) *(beta)*
+  Controls the *direct* Cantera YAML v2 writer.  Output is written to the
+  ``cantera2/`` folder.  Like ``generateCanteraYAML1``, this writer bypasses
+  the Chemkin intermediate, but instead uses the Cantera Python API
+  (``ct.Solution``) to construct and serialise the mechanism.  It also runs
+  at every iteration (or on the configured schedule).
+
+  .. warning::
+
+     This writer is in **beta**.  It has been less extensively tested than the
+     established ``cantera_from_ck`` route.  When enabled alongside the Chemkin
+     writer, a ``comparison_report.txt`` is generated at the end of the run.
+     Please report discrepancies on the `RMG-Py issue tracker
+     <https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_.
+
+``generateOutputHTML`` (default ``False``)
+  Controls the HTML species-visualisation writer.  Output is written to the
+  ``species/`` folder.  Accepts ``True``/``False`` or the same dict format.
+
 Species Constraints
 =====================
 

documentation/source/users/rmg/output.rst

@@ -4,13 +4,17 @@
 Analyzing the Output Files
 **************************
 
-You will see that a sucessfully executed RMG job will create multiple output files and folders: 
+You will see that a sucessfully executed RMG job will create multiple output files and folders:
 ``output.html`` (if ``generateOutputHTML=True`` is specified)
+``/cantera_from_ck``
+``/cantera1`` (if ``generateCanteraYAML1=True`` is specified)
+``/cantera2`` (if ``generateCanteraYAML2=True`` is specified)
 ``/chemkin``
-``/pdep``  
+``/pdep``
 ``/plot``
+``/rms``
 ``/solver``
-``/species``  
+``/species``
 ``RMG.log``
 
 ------------------
@@ -39,6 +43,92 @@ network.
 
 ------------------
 The Solver Folder
------------------- 
-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.  
+------------------
+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.
 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.
+
+------------------------------
+Cantera Output Folders
+------------------------------
+
+RMG can write mechanisms in `Cantera <https://cantera.org>`_ YAML format via three distinct
+routes, producing up to three output folders.  All three require Cantera to be installed in
+the conda environment (it is included in the standard ``rmg_env``).
+
+``/cantera_from_ck``
+^^^^^^^^^^^^^^^^^^^^
+
+This folder is always produced when the Chemkin writer is enabled (``generateChemkin=True``, the default).
+After the final RMG iteration, Cantera's own ``ck2yaml`` converter is used to translate the Chemkin-format files in ``/chemkin`` into Cantera YAML.
+This is the most thoroughly tested route and is the recommended output for production use.
+
+``/cantera1`` *(beta)*
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   The ``cantera1`` writer is in **beta**.  It uses the Cantera Python API to construct and
+   serialise the mechanism YAML, rather than writing the YAML by hand.  It has been less
+   extensively tested than the ``cantera_from_ck`` route.  Please report any discrepancies.
+
+This folder is created when ``generateCanteraYAML1=True`` is set in the ``options()`` block
+(disabled by default).  The writer runs after every RMG iteration (or on the schedule set by
+``saveInterval``), so the folder accumulates a history of the growing mechanism.
+
+Files generated:
+
+* ``chem{NNNN}.yaml`` — mechanism snapshot at the iteration when the core contained *NNNN*
+  species (e.g. ``chem0042.yaml``)
+* ``chem.yaml`` — copy of the latest snapshot; always reflects the current model state
+* ``chem_annotated.yaml`` — annotated version with SMILES, source, and kinetics comments
+  (written when ``verboseComments=True`` for this writer)
+* ``chem_edge{NNNN}.yaml`` / ``chem_edge.yaml`` / ``chem_edge_annotated.yaml`` — edge-model
+  equivalents (written when ``saveEdge=True``)
+* ``comparison_report.txt`` — numerical comparison of ``chem.yaml`` against the
+  ``cantera_from_ck`` translation (written at the end of the run if both writers are enabled;
+  see below)
+
+``/cantera2`` *(beta)*
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   The ``cantera2`` writer is in **beta**.  It generates Cantera YAML directly from RMG's
+   internal Python data structures, without going through the Chemkin intermediate.  While
+   it should produce valid mechanisms, it has been less extensively tested than the
+   ``cantera_from_ck`` route.  Please report any discrepancies.
+
+This folder is created when ``generateCanteraYAML2=True`` is set in the ``options()`` block
+(disabled by default).  Like ``cantera1``, it runs at every iteration (or on the configured
+schedule).
+
+Files generated:
+
+* ``chem{NNNN}.yaml`` / ``chem.yaml`` — latest mechanism snapshot and its labelled history
+* ``chem_annotated.yaml`` — annotated version (written when ``verboseComments=True``)
+* ``chem_edge{NNNN}.yaml`` / ``chem_edge.yaml`` / ``chem_edge_annotated.yaml`` — edge-model
+  equivalents (written when ``saveEdge=True``)
+* ``comparison_report.txt`` — numerical comparison against the ``cantera_from_ck``
+  translation (written at the end of the run if both writers are enabled)
+
+Comparison Reports
+^^^^^^^^^^^^^^^^^^
+
+When a direct-writer folder (``cantera1`` or ``cantera2``) is used alongside the Chemkin
+writer, RMG automatically compares the final ``chem.yaml`` from that folder against the
+``cantera_from_ck/chem.yaml`` produced by ``ck2yaml``.  The comparison checks differences
+in the yaml data. Not all differences are necessarily problematic.  Results are written to
+``comparison_report.txt`` inside the relevant direct-writer folder.
+
+If you find that the two routes disagree in a problematic way, please open an issue on the
+`RMG-Py GitHub repository <https://github.com/ReactionMechanismGenerator/RMG-Py/issues>`_
+and include the ``comparison_report.txt`` and a minimal reproducing ``input.py``.
+
+------------------------------
+The RMS YAML Folder
+------------------------------
+
+The ``/rms`` folder contains the mechanism in
+`ReactionMechanismSimulator (RMS) <https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl>`_
+YAML format.  This writer is enabled by default (``generateRMSYAML=True``) and writes at
+every iteration, unless configured otherwise by ``saveInterval``.

documentation/source/users/rmg/running.rst

@@ -48,9 +48,9 @@ at the command line will print the documentation from ``util.py``, which is repr
 	  -P, --postprocess     postprocess profiling statistics from previous
 	                        [failed] run; does not run the simulation
 	  -t DD:HH:MM:SS, --walltime DD:HH:MM:SS
-	                        set the maximum execution time
+	                        set the maximum execution time (overrides input.py if provided)
 	  -i MAXITER, --maxiter MAXITER
-	                        set the maximum number of RMG iterations
+	                        set the maximum number of RMG iterations (overrides input.py if provided)
 	  -n MAXPROC, --maxproc MAXPROC
 	                        max number of processes used during reaction
 	                        generation
@@ -73,7 +73,7 @@ Run with multiprocessing for reaction generation and QMTP::
 
     python rmg.py -n <Max number of processes allowed> input.py 
 
-Run with setting a limit on the maximum execution time::
+Run with setting a limit on the maximum execution time (if specified, then the command-line value overrides any value read from ``input.py``)::
 
 	python rmg.py -t <DD:HH:MM:SS> input.py
 

examples/rmg/1,3-hexadiene/input.py

@@ -90,4 +90,9 @@
     generateOutputHTML=False,
     generatePlots=False,
     generatePESDiagrams=True,
+    # Large model: write output every 5 iterations and skip edge species to reduce I/O
+    generateChemkin={'saveInterval': 1, 'saveEdge': False},
+    generateRMSYAML={'saveInterval': 5},
+    generateCanteraYAML1={'saveInterval': 5},
+    generateCanteraYAML2={'saveInterval': 5},
 )

examples/rmg/MR_test/input.py

@@ -260,9 +260,9 @@
     #Sets a time limit in the form DD:HH:MM:SS after which the RMG job will stop. Useful for profiling on jobs that
     #do not converge.
     #wallTime = '00:00:00', 
+    #When keepIrreversible=False (default), forces RMG to import library reactions as reversible. 
+    #Otherwise, if set to True, RMG will import library reactions while keeping the reversibility as specified.
     keepIrreversible=False,
-    #Forces RMG to import library reactions as reversible (default). Otherwise, if set to True, RMG will import library
-    #reactions while keeping the reversibility as as.
 )
 
 # optional module allows for correction to unimolecular reaction rates at low pressures and/or temperatures.

examples/rmg/ch3no2/input.py

@@ -80,8 +80,13 @@
 )
 
 simulator(atol=1e-16,rtol=1e-8)
+
 options(
     units='si',
     generateOutputHTML=False,
     generatePlots=False,
+    # Large model: write output every 5 iterations to reduce I/O
+    generateChemkin={'saveInterval': 5, 'saveEdge': False},
+    generateRMSYAML={'saveInterval': 5},
+    generateCanteraYAML2={'saveInterval': 10, 'saveEdge': True},
 )

examples/rmg/commented/input.py

@@ -221,23 +221,47 @@
     generatePESDiagrams=False,
     # saves mole fraction of species in 'solver/' to help you create plots
     saveSimulationProfiles=False,
-    # gets RMG to output comments on where kinetics were obtained in the chemkin file.
-    # useful for debugging kinetics but increases memory usage of the chemkin output file
+    # Global fallback for verbose comments (comments on where kinetics were obtained).
+    # Useful for debugging kinetics but increases output file size.
+    # Individual writers can override this with their own verboseComments key.
     verboseComments=False,
-    # gets RMG to generate edge species chemkin files. Uses lots of memory in output.
-    # Helpful for seeing why some reaction are not appearing in core model.
+    # Global fallback for saving edge-species files. Uses lots of memory in output.
+    # Helpful for seeing why some reactions are not appearing in the core model.
+    # Individual writers can override this with their own saveEdge key.
     saveEdgeSpecies=False,
-    # Sets a time limit in the form DD:HH:MM:SS after which the RMG job will stop. Useful for profiling on jobs that
-    # do not converge.
-    # wallTime = '00:00:00',
-    # Forces RMG to import library reactions as reversible (default). Otherwise, if set to True, RMG will import library
-    # reactions while keeping the reversibility as as.
+    # Sets a time limit in the form DD:HH:MM:SS after (or shortly before) which the RMG job will stop.
+    # Useful for profiling on jobs that do not converge.
+    wallTime = '00:00:00:00',
+    # If keepIrreversible=False (default) forces RMG to import library reactions as reversible.
+    # If set to True, RMG will import library reactions while keeping the reversibility as specified.
     keepIrreversible=False,
     # Allows families with three products to react in the diverse direction (default).
     trimolecularProductReversible=True,
     # Allows a seed to be saved every n iterations.
     # The default of -1 causes the iteration to only be saved at the end of the RMG job
-    saveSeedModulus=-1
+    saveSeedModulus=-1,
+    #
+    # --- Per-writer output configuration ---
+    # Each writer accepts True/False or a dict with keys:
+    #   'saveInterval': N  (positive = every N iterations; -1 = end of run only)
+    #   'verboseComments': True/False  (overrides the global verboseComments above)
+    #   'saveEdge': True/False  (overrides the global saveEdgeSpecies above)
+    #
+    # Chemkin writer: always on by default; saves every iteration.
+    generateChemkin=True,
+    # generateChemkin={'saveInterval': -1, 'verboseComments': True, 'saveEdge': True},
+    #
+    # RMS YAML writer: always on by default; saves every iteration.
+    generateRMSYAML=True,
+    # generateRMSYAML={'saveInterval': -1},
+    #
+    # Cantera YAML v1 writer: off by default.
+    generateCanteraYAML1=False,
+    # generateCanteraYAML1={'saveInterval': -1, 'verboseComments': True, 'saveEdge': False},
+    #
+    # Cantera YAML v2 writer: off by default.
+    generateCanteraYAML2=False,
+    # generateCanteraYAML2={'saveInterval': 1, 'verboseComments': True, 'saveEdge': True},
 )
 
 # optional module allows for correction to unimolecular reaction rates at low pressures and/or temperatures.