proceeding with CycleControl documentation

da/doc/source/cyclecontrol.rst

@@ -8,17 +8,9 @@ Valid options are defined in
 
 .. autofunction:: da.tools.initexit.ParseOptions
 
-and validated by
-
-.. autofunction:: da.tools.initexit.ValidateOptsArgs
-
-With the name of a valid rc-file, the CycleControl object is instantiated and validated 
-
-.. autoclass:: da.tools.initexit.CycleControl 
-   :members: LoadRc, ValidateRC
-
-The most important methods of the CycleControl object are:
+With the name of a valid rc-file, the CycleControl object is instantiated and validated.
+The most important method of the CycleControl object are listed below:
 
 .. autoclass:: da.tools.initexit.CycleControl 
-   :members: Initialize, ParseTimes, RandomSeed
+   :members: Initialize, Finalize, SubmitNextCycle, CollectSaveData, MoveSaveData
 

da/tools/initexit.py

@@ -192,11 +192,21 @@ Validate the contents of the rc-file given a dictionary of required keys. Curren
         return None
 
     def Initialize(self):
-        """ Determine how to proceed with this cycle: 
-        
-            (a) recover from crash : get the save data from the one-ago folder and replace the da_runtime variables with those from the save dir
-            (b) restart cycle      : use latest da_runtime variables from the exec dir
-            (c) fresh start        : set up the required file structure for this simulation
+        """ 
+        This method determines how to proceed with the cycle. Three options are implemented:
+
+            1. Fresh start  : set up the required file structure for this simulation and start
+            2. Restart      : use latest da_runtime variables from the exec dir and restart
+            3. Recover      : restart after crash by getting data from save/one-ago folder
+
+        The choice that gets executed depends on the presence of 
+
+            1. the -r option on the command line, this triggers a recover
+            2. the "time.restart : True" option in the da.rc file
+
+        The latter is automatically set if the filter submits the next cycle at the end of the current one, 
+        through method :meth:`SubmitNextCycle`.
+
         """        
 
 #
@@ -319,7 +329,15 @@ Validate the contents of the rc-file given a dictionary of required keys. Curren
 
     def Finalize(self):
         """
-        Finalize the da cycle, this means writing the save data and rc-files for the next run
+        Finalize the da cycle, this means writing the save data and rc-files for the next run. 
+        The following sequence of actions occur:
+
+            * Write the randomseed to file for reuse in next cycle
+            * Write a new rc-file with time.restart : True, and new time.start and time.end
+            * Collect all needed data needed for check-pointing (restart from current system state)
+            * Move the previous check pointing data out of the way, and replace with current
+            * Submit the next cycle
+
         """
 
         dummy = self.RandomSeed('write')
@@ -333,10 +351,10 @@ Validate the contents of the rc-file given a dictionary of required keys. Curren
             All files needded are written to the save/ directory.
             Currently, the following files are included
 
-            -) The randomseed.pickle file, also already in the save directory
-            -) The da_runtime.rc file
-            -) The savestate.yyyymmdd.nc file
-            -) ...
+            - The randomseed.pickle file, also already in the save directory
+            - The da_runtime.rc file
+            - The savestate.yyyymmdd.nc file
+            - ...
 
             Note that we assume that the transport model restart files are directly written to the save/ directory and do not need to be collected