Merge pull request #1641 from ReactionMechanismGenerator/SaveFilterTe…

…nsors Enable Restarting RMG Jobs from a Seed Mechanism
ReactionMechanismGenerator · Aug 12, 2019 · 3846fcc · 3846fcc
2 parents 3dcff2f + 9bd9589
commit 3846fcc
Show file tree

Hide file tree

Showing 64 changed files with 5,484 additions and 551 deletions.
diff --git a/documentation/source/users/rmg/input.rst b/documentation/source/users/rmg/input.rst
@@ -855,7 +855,6 @@ Miscellaneous options::
         generateSeedEachIteration=True,
         saveSeedToDatabase=True,
         units='si',
-        saveRestartPeriod=(1,'hour'),
         generateOutputHTML=True,
         generatePlots=False,
         saveSimulationProfiles=True,
@@ -867,14 +866,12 @@ Miscellaneous options::
 
 The ``name`` field is the name of any generated seed mechanisms
 
-Setting ``generateSeedEachIteration`` to ``True`` tells RMG to save and update a seed mechanism and thermo library during the current run
+Setting ``generateSeedEachIteration`` to ``True`` (default) tells RMG to save and update a seed mechanism and thermo library during the current run
 
 Setting ``saveSeedToDatabase`` to ``True`` tells RMG (if generating a seed) to also save that seed mechanism and thermo library directly into the database
 
 The ``units`` field is set to ``si``.  Currently there are no other unit options.
 
-The ``saveRestartPeriod`` indictes how frequently you wish to save restart files. For very large/long RMG jobs, this process can take a significant amount of time. In such cases, the user may wish to increase the time period for saving these restart files.
-
 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.
 
@@ -944,3 +941,41 @@ For example ::
 		maxNumSpecies=100
 	)
 
+Restarting from a Seed Mechanism
+=================================
+The only method for restarting an RMG-Py job is to restart the job from a seed mechanism. There are
+many scenarios when the user might want to do this, including continuing on a job that ran out of time or crashed as the
+result of a now fixed bug. To restart from a seed mechanism, the block below must be added on to the input file.  ::
+
+    restartFromSeed(path='seed')
+
+The ``path`` flag is the path to the seed mechanism folder, which contains three subfolders that must be titled as
+follows: filters, seed, seed_edge. The path can be a relative path from the input.py file or an absolute path on disk
+
+Alternatively, you may also specify the paths to each of the following files/directories: coreSeed (path to seed
+mechanism folder containing files named ``reactions.py`` and ```dictionary.txt``` that will go into the model core),
+edgeSeed (path to edge seed mechanism folder containing files named ``reactions.py`` and ```dictionary.txt``` that will
+go into the model edge), filters (an h5 binary file storing the uni-, bi-, and optionally tri-molecular thresholds
+generated by RMG from previous run (must be RMG version > 2.4.1)), speciesMap (a YAML file specifying what species are
+at each index in the filters). ::
+
+    restartFromSeed(coreSeed='seed/seed'  # Path to core seed folder. Must contain `reactions.py` and `dictionary.txt`
+                    edgeSeed='seed/seed_edge'  # Path to edge seed folder containing `reactions.py` and `dictionary.txt`
+                    filters='seed/filters/filters.h5',
+                    speciesMap='seed/filters/species_map.yml')
+
+Then, to restart from the seed mechanism the input file is submitted as normal. ::
+
+    python rmg.py input.py
+
+Once the restart job has begun, RMG will move the seed mechanism files to a new subfolder in the output directory
+entitled ``previous_restart``. This is to back-up the seed mechanism used for restarting, as everything in the ``seed``
+subfolder of the output directory is overwritten by RMG during the course of mechanism generation.
+
+RMG also outputs a file entitled ``restart_from_seed.py`` the first time a seed mechanism is generated during the course
+of an RMG job (so long as the RMG job was not itself a restarted job). This file is an exact duplicate of the original
+input file with the exception that the restart block has been added on automatically for convenience. In this way this
+file is treated in the exact way as a normal input file.
+
+Finally, **note that it is advised to turn on generating the seed each iteration so that you can restart an RMG job right where it left off**.
+This can be done by setting ``generateSeedEachIteration=True`` in the options block of the input file.
diff --git a/documentation/source/users/rmg/liquids.rst b/documentation/source/users/rmg/liquids.rst
@@ -286,7 +286,6 @@ This is an example of an input file for a liquid-phase system::
 
     options(
         units='si',
-        saveRestartPeriod=None,
         generateOutputHTML=False,
         generatePlots=False,
         saveSimulationProfiles=True,
@@ -348,7 +347,6 @@ This is an example of an input file for a liquid-phase system with constant spec
 
     options(
         units='si',
-        saveRestartPeriod=None,
         generateOutputHTML=False,
         generatePlots=False,
         saveSimulationProfiles=True,

diff --git a/documentation/source/users/rmg/output.rst b/documentation/source/users/rmg/output.rst
@@ -11,7 +11,6 @@ You will see that a sucessfully executed RMG job will create multiple output fil
 ``/plot``
 ``/solver``
 ``/species``  
-``restart.pkl``  
 ``RMG.log``
 
 ------------------

diff --git a/documentation/source/users/rmg/running.rst b/documentation/source/users/rmg/running.rst
@@ -12,9 +12,9 @@ Basic run::
 
 	python rmg.py input.py
 
-Run with a restart file (restart file should be located in same folder as input.py)::
+Run by restarting from a seed mechanism ::
 
-    python rmg.py input.py -r
+    python rmg.py input.py -r path/to/seed/
 
 Run with CPU profiling::
 

diff --git a/examples/reduction/minimal/input.py b/examples/reduction/minimal/input.py
@@ -54,7 +54,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generatePlots=False,
     saveEdgeSpecies=True,
     saveSimulationProfiles=True,

diff --git a/examples/rmg/.gitignore b/examples/rmg/.gitignore
@@ -1,7 +1,6 @@
 RMG.log
 RMG.profile
 RMG_backup.log
-restart.pkl
 output.xml
 cantera
 plot

diff --git a/examples/rmg/1,3-hexadiene/input.py b/examples/rmg/1,3-hexadiene/input.py
@@ -87,7 +87,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=(1,'hour'),
     generateOutputHTML=False,
     generatePlots=False,
 )
diff --git a/examples/rmg/MR_test/input.py b/examples/rmg/MR_test/input.py
@@ -244,9 +244,6 @@
     saveSeedToDatabase=False,
 	#only option is 'si'
     units='si',
-	#how often you want to save restart files.  
-	#takes significant amount of time. comment out if you don't want to save 
-    saveRestartPeriod=None,
 	#Draws images of species and reactions and saves the model output to HTML.  
 	#May consume extra memory when running large models.
     generateOutputHTML=True,

diff --git a/examples/rmg/SR_test/input.py b/examples/rmg/SR_test/input.py
@@ -59,7 +59,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
     saveEdgeSpecies=False,

diff --git a/examples/rmg/TEOS/input.py b/examples/rmg/TEOS/input.py
@@ -54,7 +54,6 @@
 
 options(
 	units='si',
-	saveRestartPeriod=None,
 	generateOutputHTML=False,
 	generatePlots=False,
 )
diff --git a/examples/rmg/c3h4/input.py b/examples/rmg/c3h4/input.py
@@ -59,7 +59,6 @@
 
 options(
 	units='si',
-	saveRestartPeriod=None,
 	generateOutputHTML=False,
 	generatePlots=False,
 )
diff --git a/examples/rmg/catalysis/ch4_o2/input.py b/examples/rmg/catalysis/ch4_o2/input.py
@@ -78,7 +78,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=True,
     generatePlots=False, # Enable to make plots of core and edge size etc. But takes a lot of the total runtime!
     saveEdgeSpecies=True,

diff --git a/examples/rmg/catalysis/methane_steam/input.py b/examples/rmg/catalysis/methane_steam/input.py
@@ -194,7 +194,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=True,
     generatePlots=False, # Enable to make plots of core and edge size etc.. But takes a lot of the total runtime!
     saveEdgeSpecies=True,

diff --git a/examples/rmg/ch3no2/input.py b/examples/rmg/ch3no2/input.py
@@ -82,7 +82,6 @@
 simulator(atol=1e-16,rtol=1e-8)
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
 )
diff --git a/examples/rmg/commented/input.py b/examples/rmg/commented/input.py
@@ -1,3 +1,15 @@
+# Uncomment either of the blocks below to restart from a seed mechanism
+#
+# # Option 1: Specify the path to an RMG (version > 2.4.1) generated seed mechanism folder, which contains all of the
+# # required files (core and edge seed, filters and mappings) in their default locations and names in the seed folder.
+# restartFromSeed(path='seed')  # Location of the seed mechanism (with `filters` subfolder) to load for restarting
+#
+# # Option 2: Specify the paths of each of the required files individually.
+# restartFromSeed(coreSeed='seed/seed'  # Path to core seed folder. Must contain `reactions.py` and `dictionary.txt`
+#                 edgeSeed='seed/seed_edge'  # Path to edge seed folder containing `reactions.py` and `dictionary.txt`
+#                 filters='seed/filters/filters.h5',
+#                 speciesMap='seed/filters/species_map.yml')
+
 # Data sources
 database(
     # overrides RMG thermo calculation of RMG with these values.
@@ -156,7 +168,7 @@
 options(
     # provides a name for the seed mechanism produced at the end of an rmg run default is 'Seed'
     name='SeedName',
-    # if True every iteration it saves the current model as libraries/seeds
+    # if True (default) every iteration it saves the current model as libraries/seeds
     # (and deletes the old one)
     # Unlike HTML this is inexpensive time-wise
     # note a seed mechanism will be generated at the end of a completed run and some incomplete
@@ -166,9 +178,6 @@
     saveSeedToDatabase=False,
     # only option is 'si'
     units='si',
-    # how often you want to save restart files.
-    # takes significant amount of time. comment out if you don't want to save
-    saveRestartPeriod=None,
     # Draws images of species and reactions and saves the model output to HTML.
     # May consume extra memory when running large models.
     generateOutputHTML=True,

diff --git a/examples/rmg/diesel/input.py b/examples/rmg/diesel/input.py
@@ -84,7 +84,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
 )
diff --git a/examples/rmg/e85/input.py b/examples/rmg/e85/input.py
@@ -85,7 +85,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=(1,'day'),
     generateOutputHTML=False,
     generatePlots=False,
 )

diff --git a/examples/rmg/ethane-oxidation/input.py b/examples/rmg/ethane-oxidation/input.py
@@ -65,7 +65,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
 )
diff --git a/examples/rmg/gri_mech_rxn_lib/input.py b/examples/rmg/gri_mech_rxn_lib/input.py
@@ -42,7 +42,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/liquid_phase/input.py b/examples/rmg/liquid_phase/input.py
@@ -54,7 +54,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
     saveSimulationProfiles=True,

diff --git a/examples/rmg/liquid_phase_constSPC/input.py b/examples/rmg/liquid_phase_constSPC/input.py
@@ -57,7 +57,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/methylformate/input.py b/examples/rmg/methylformate/input.py
@@ -161,7 +161,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=(1,'hour'),
     generateOutputHTML=False,
     generatePlots=False,
     saveSimulationProfiles=False,

diff --git a/examples/rmg/minimal/input.py b/examples/rmg/minimal/input.py
@@ -38,11 +38,11 @@
     toleranceMoveToCore=0.1,
     toleranceInterruptSimulation=0.1,
     maximumEdgeSpecies=100000,
+    filterReactions=True,
 )
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=True,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/minimal_dynamics/input.py b/examples/rmg/minimal_dynamics/input.py
@@ -43,7 +43,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=True,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/minimal_ml/input.py b/examples/rmg/minimal_ml/input.py
@@ -47,7 +47,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=True,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/minimal_multisurf/input.py b/examples/rmg/minimal_multisurf/input.py
@@ -60,7 +60,6 @@
 
 options(
     units='si',
-    saveRestartPeriod=None,
     generateOutputHTML=False,
     generatePlots=False,
     saveEdgeSpecies=True,

diff --git a/examples/rmg/minimal_restart_from_seed/restart_from_seed.py b/examples/rmg/minimal_restart_from_seed/restart_from_seed.py
@@ -0,0 +1,52 @@
+restartFromSeed(path='seed')
+
+# Data sources
+database(
+    thermoLibraries = ['primaryThermoLibrary'],
+    reactionLibraries = [],
+    seedMechanisms = [],
+    kineticsDepositories = ['training'],
+    kineticsFamilies = 'default',
+    kineticsEstimator = 'rate rules',
+)
+
+# List of species
+species(
+    label='ethane',
+    reactive=True,
+    structure=SMILES("CC"),
+)
+
+# Reaction systems
+simpleReactor(
+    temperature=(1350,'K'),
+    pressure=(1.0,'bar'),
+    initialMoleFractions={
+        "ethane": 1.0,
+    },
+    terminationConversion={
+        'ethane': 0.9,
+    },
+    terminationTime=(1e6,'s'),
+)
+
+simulator(
+    atol=1e-16,
+    rtol=1e-8,
+)
+
+model(
+    toleranceKeepInEdge=0.0,
+    toleranceMoveToCore=0.1,
+    toleranceInterruptSimulation=0.1,
+    maximumEdgeSpecies=100000,
+    filterReactions=True,
+)
+
+options(
+    units='si',
+    generateOutputHTML=True,
+    generatePlots=False,
+    saveEdgeSpecies=True,
+    saveSimulationProfiles=True,
+)
diff --git a/examples/rmg/minimal_restart_from_seed/seed/filters/filters.h5 b/examples/rmg/minimal_restart_from_seed/seed/filters/filters.h5