In CBMSpinupSequencer, updated to read peatlandId from peatland map, …

…and set variable peatland_class with the peatlandId. Enable peatland_class is writabler to prepare the transition from original peatland to different type peatland after certain disturbance.

docs: build source docs

Source/docs/glossary.md

@@ -4,4 +4,34 @@
 
 _landUnitData : Used to get reference to pools, state variables associated with a module and create and submit carbon transfers (createStockOperation/createProportionalOperation/submitOperation)
 
+### Events 
+
+The FLINT framework uses publish/subscribe messaging to control the lifecycle of a simulation. Module code can subscribe to these events to perform work at different stages. See CBMSequencer and CBMSpinupSequencer (notificationCenter.postNotification) for when these events are fired in a GCBM simulation, as well as moja::flint::SpatialTiledLocalDomainController for the framework-level events like onSystemInit.
+
+There are various events defined in the file [cbmmodulebase.h](https://github.com/moja-global/moja.canada/blob/develop/Source/moja.modules.cbm/include/moja/modules/cbm/cbmmodulebase.h)
+
+| Event | Description |
+| :-----------: | :---: |
+| `onSystemInit` | Fired once when the framework starts up. At this point, modules have access to member variables initialized in the configuration step (flint::IModule::configure), but not pools or data variables | 
+| `onSystemShutDown` | Fired once when the framework shuts down |
+| `onLocalDomainInit` | Event is fired once per thread at the start of the simulation - modules typically subscribe to this event in order to store references to pools and variables. Non-spatial variable data is also available at this stage, i.e. variables with fixed values in the JSON configuration files |
+| `onLocalDomainShutDown` | Fired once per thread when the simulation has ended |
+| `onTimingInit` | Fired once for each pixel just before simulation for that pixel begins. This event is typically used to initialize the starting state for the pixel |
+| `onTimingStep` | Invoked every timestep for a pixel’s simulation. Simulation is performed for the whole range of timesteps for a single land unit (pixel) before the framework moves on to the next land unit |
+| `onOutputStep` | Fired at the end of each timestep for a land unit (pixel), typically for output modules to subscribe to |
+| `onPreTimingSequence` | This event runs just before onTimingInit, for modules that need to do some work before that event |
+| `onTimingPrePostInit` | This event is fired by some of the other FLINT framework sequencers (i.e. CalendarSequencer) just after TimingInit, but is unused in GCBM; it is overridden in CBMModuleBase just for completeness |
+| `onTimingPostInit` | Fired just after TimingInit, before simulation begins for a pixel |
+| `onTimingPreEndStep` | Just before the end of the current timing step |
+| `onTimingEndStep` | When the current time step ends |
+| `onTimingPostStep` | Fired after the current timing step ends |
+| `onPrePostDisturbanceEvent` | Fired just before disturbance events in other non-GCBM FLINT framework sequencers. GCBM only uses this event in some of the peatland modules, which manually fire it before peatland-specific disturbance events |
+| `onDisturbanceEvent` | Fired when a disturbance event occurs along with an optional “payload” argument. In the GCBM, the payload contains the disturbance type and the disturbance matrix, which defines all the carbon pool transfers resulting from the disturbance. Other modules have a chance to modify the disturbance matrix before the carbon pool transfers are processed; for example, the peatland modules watch for fire disturbances and add peatland carbon pool transfers to the fire matrix, which doesn’t normally include them |
+| `onError` | Fired on the occurrence of an error | 
+| `onPostNotification` | Not used |
+
+
+
+
+
 [Back to Home](README.md)

Source/moja.modules.cbm/include/moja/modules/cbm/cbmmodulebase.h

@@ -1,3 +1,11 @@
+/**
+ * @file
+ * The FLINT framework uses publish/subscribe messaging to control the lifecycle of a simulation. 
+ * Module code can subscribe to these events to perform work at different stages. 
+ * See CBMSequencer and CBMSpinupSequencer (notificationCenter.postNotification) 
+ * for when these events are fired in a GCBM simulation, as well as moja::flint::SpatialTiledLocalDomainController 
+ * for the framework-level events like onSystemInit.
+ */
 #ifndef MOJA_MODULES_CBM_CBMMODULEBASE_H_
 #define MOJA_MODULES_CBM_CBMMODULEBASE_H_
 
@@ -14,7 +22,6 @@ namespace cbm {
 class CBMModuleBase : public flint::ModuleBase {
 public:
 	virtual ~CBMModuleBase() = default;
-
 	void onSystemInit() override							 { doWithHandling([this]() { this->doSystemInit(); }); }
 	void onSystemShutdown() override						 { doWithHandling([this]() { this->doSystemShutdown(); }); }
 	void onLocalDomainInit() override						 { doWithHandling([this]() { this->doLocalDomainInit(); }); }

Source/moja.modules.cbm/src/ageclasshelper.cpp

@@ -3,7 +3,6 @@
  * Utility functions for age class calculations
  */
 
-
 #include "moja/modules/cbm/ageclasshelper.h"
 
 #include <boost/format.hpp>

Source/moja.modules.cbm/src/cbmdisturbancelistener.cpp

@@ -1,6 +1,6 @@
 /**
 * @file
-*  The CBMDisturbanceListener module reads the stack of disturbance layers for each 
+* The CBMDisturbanceListener module reads the stack of disturbance layers for each 
 * pixel and determines which events to apply in each year of the simulation. For each 
 * disturbance event in the current time step for the current pixel, the module informs the 
 * model with data about the event, i.e., the disturbance type name, disturbance type 
@@ -32,7 +32,7 @@ namespace moja {
 
 
 			/**
-            *  Configuration function.
+            * Configuration function.
             *
 			* If parameter config has variable "vars", and it is not empty, \n 
 			* add each layer in config["vars"] to CBMDisturbanceListener._layerNames \n
@@ -251,9 +251,7 @@ namespace moja {
 			* If the parameter eventData contains the variables "disturbance_type", "disturbance_id" 
 			* check if CBMDisturbanceListener._distTypeNames has eventData["disturbance_type_id"] and the value of 
 			* disturbance id corresponds to disturbance name \n
-			* 
-			* Else if, parameter eventData contains only "disturbance_id", check if check if CBMDisturbanceListener._distTypeNames has eventData["disturbance_type_id"]
-			* 
+			* Else if, parameter eventData contains only "disturbance_id", check if check if CBMDisturbanceListener._distTypeNames has eventData["disturbance_type_id"] \n
 			* Else report the absence of a disturbance name and id
 			* 
 			* @param eventData DynamicObject
@@ -582,8 +580,6 @@ namespace moja {
 			}
 
 			/**
-			* Insert Disturbance Matrix Associations
-			*
 			* For each dmAssociation in variable "disturbance_matrix_associations" of _landUnitData, 
 			* insert the "disturbance_type", "spatial_unit_id" and "disturbance_matrix_id" as a pair of pairs into CBMDisturbanceListener._dmAssociations
 			*
@@ -605,8 +601,6 @@ namespace moja {
 			}
 
 			/**
-			 * Get land and class transitions
-			 * 
 			 * For each tranistion in variable "land_class_transitions" of _landUnitData, 
 			 * insert the "disturbance_type" and "land_class_transition" as a pair into CBMDisturbanceListener._landClassTransitions
 			 * 
@@ -713,11 +707,30 @@ namespace moja {
 
 
 			/**
-			 * For each  
+			 * Determine the various subconditions based on the configuration
+			 * 
+			 * An shared pointer of type IDisturbanceSubCondition, subConditions, is created to store all the subConditions \n
+			 * 
+			 * For each condition in parameter config, if the first element of the condition, (condition.first), is either "disturbance_type", "run_conditions", 
+			 * "override_conditions" or "override_disturbance_type", the next configuration object is checked \n
+			 * If condition.first is "disturbance_sequence", all the historical disturbances are added to an object of DisturbanceHistoryCondition. 
+			 * A shared pointer of DisturbanceSequenceSubCondition containing the timing, disturbance history and sequence of disturbance events is added to subConditions
+			 * and the next condition is visited \n
+			 * 
+			 * Extract the comparison type (<, =, >=, <->, !=) and target of value of condition.second \n
+			 * 
+			 * If the condition is a single variable, the condition.first is present in _landUnitData, a shared pointer of VariableDisturbanceSubCondition is added to subConditions
+			 * and the next condition is visited \n
+			 * 
+			 * Based on whether the condition is on one or more pools, a shared pointer of PoolDisturbanceSubCondition is added to subConditions
+			 * and the next condition is visited \n
 			 * 
+			 * An object of CompositeDisturbanceSubCondition with the subConditions is returned
 			 * 
+			 * @param config DynamicObject&
+			 * @return shared_ptr<IDisturbanceSubCondition>
 			 * 
-			 ************************/
+			 */
 			std::shared_ptr<IDisturbanceSubCondition> CBMDisturbanceListener::createSubCondition(const DynamicObject& config) {
 				std::vector<std::shared_ptr<IDisturbanceSubCondition>> subConditions;
 				for (const auto& kvp : config) {

Source/moja.modules.cbm/src/cbmflataggregatorlandunitdata.cpp

@@ -1,9 +1,6 @@
 /**
 * @file
-* The brief description goes here.
-*
-* The detailed description if any, goes here
-* ******/
+*/
 #include "moja/modules/cbm/cbmflataggregatorlandunitdata.h"
 #include "moja/modules/cbm/timeseries.h"
 

Source/moja.modules.cbm/src/cbmlandclasstransitionmodule.cpp

@@ -84,21 +84,18 @@ namespace cbm {
     }
 
     /**
-    * Set initial decay status.
+    * Set initial decay status
     * 
     * Assign CBMLandClassTransitionModule._lastCurrentLandClass as CBMLandClassTransitionModule._currentLandClass value (string). \n
-    * Invoke setUnfcccLandClass(). \n
-    * Assign CBMLandClassTransitionModule._yearsSinceTransition as 0. \n
-    * Initialise bool variable isForest as CBMLandClassTransitionModule._isForest value. \n
-    * Initialise variable standCreationDisturbance as getCreationDisturbance(). \n
-    * Initialise bool variable deforestedInSpinup as CBMLandClassTransitionModule._landClassTransistions[standCreationDisturbance] !=""&& \n
-    * !CBMLandClassTransitionModule._landclassForestStatus[CBMLandClassTransitionModule._landClassTransitions[standCreationDisturbance]]. \n
-    * If the carbon in a stand is initially a forest land class and the last_pass disturbance \n
-    * is a deforestation event, set CBMLandClassTransitionModule._isDecaying to true. \n
-    * if not, set CBMLandClassTransitionModule._isDecaying to false.
+    * Invoke CBMLandClassTransitionModule.setUnfcccLandClass(), set CBMLandClassTransitionModule._yearsSinceTransition to 0 \n
+    * Set the initial stand decaying status. The carbon in a stand always decays unless the stand is initially a non-forest land class and the last-pass disturbance was not a deforestation event - i.e. a non-forest stand that
+    * will be afforested at some point has its decay paused until then \n
+    * If the value of CBMLandClassTransitionModule._isForest is false and land was deforested in spinup, then set 
+    * CBMLandClassTransitionModule._isDecaying to false, else set it to true
     * 
     * @return void
     * ************************/
+
     void CBMLandClassTransitionModule::doTimingInit() {
         _lastCurrentLandClass = _currentLandClass->value().convert<std::string>();
         setUnfcccLandClass();
@@ -121,7 +118,6 @@ namespace cbm {
     }
 
     /**
-    * 
     * Iterate CBMLandClassTransitionModule.yearsSinceTransition by 1; \n
     * Initialise string varaible currentLandClass as CBMLandClassTransitionModule._currentLandClass value. \n
     * if currentLandClass is equal to CBMLandClassTransitionModule._lastCurrentLandClass, invoke updateRemainigStatus() using currentLandClass as a parameter and \n
@@ -151,9 +147,7 @@ namespace cbm {
     }
 
     /**
-    * getCreationDisturbance.
-    * 
-    * if CBMLandClassTransitionModule._lastPassDisturbanceTimeseries is not equal to nullptr, \n
+    * If CBMLandClassTransitionModule._lastPassDisturbanceTimeseries is not equal to nullptr, \n
     * initialise constant variable lastPassTimeseries as CBMLandClassTransitionModule._lastPassDisturbanceTimeSeries value. \n
     * if lastPassTimeseries is not empty, initialise integer variable maxYear as -1. \n
     * Initialise string variable creationDisturbance. \n
@@ -193,16 +187,10 @@ namespace cbm {
     }
 
     /**
-    * fetchLandClasstransitions
-    * 
-    * Initialise constant variable transitions as land_class_transitions value. \n
-    * if transitions is a vector, for each constant variable transition in transitions (vector<DynamicObject>). \n
-    * Initialise string variables disturbanceType as transition["disturbance_type"] and landClass as transition["land_class_transition"]. \n
-    * Invoke make_pair() using disturbanceType and landClass and insert it into CBMLandClassTransitionModule._landClassTransitions. \n
-    * if not, initialise string variables disturbanceType as transitions["disturbance_type"] and landClass as transitions["land_class_transition"]. \n
-    * Insert disturbanceType,landClass into CBMLandClassTransitionModule._landClassTransitions.
-    * 
-    * @return void
+     * Insert the values of "disturbance_type" and "land_class_transition" as a pair in "land_class_transitions"
+     * from variable _landUnitData into CBMLandClassTransitionModule._landClassTransitions
+     * 
+     * @return void
     * ************************/
     void CBMLandClassTransitionModule::fetchLandClassTransitions() {
         const auto& transitions = _landUnitData->getVariable("land_class_transitions")->value();
@@ -220,19 +208,13 @@ namespace cbm {
     }
 
     /**
-    * updateRemainingStatus
-    * 
-    * Initialise string variable historicLandClass as CBMLandClassTransitionModule._historicLandClass value. \n
-    * if landClass is equal to hisitoricLandClass end program. 
-    * 
-    * Initialise intege variable targetYears as CBMLandClassTransitionModule._landClassElapsedTime[landClass]. \n
-    * if CBMLandClassTransitionModule._yearsSinceTransition is greater than targetYears, \n
-    * set CBMLandClassTransitionModule._historicLandClass as landClass. \n
-    * invoke CBMLandClassTransitionModule.setUnfccLandClass(). \n
-    * 
-    * @param landClass string
-    * @return void
-    * ************************/
+     * If the parameter landClass is the same as CBMLandClassTransitionModule._historicLandClass, return \n
+     * If the value of parameter landClass CBMLandClassTransitionModule._landClassElapsedTime is > CBMLandClassTransitionModule.targetYears,
+     * set the value of _historicLandClass to landClass and invoke CBMLandClassTransitionModule.setUnfcccLandClass()
+     * 
+     * @param landClass string
+     * @return void
+     */
     void CBMLandClassTransitionModule::updateRemainingStatus(std::string landClass) {
         // The 10/20-year "flip" when X_R_Y becomes Y_R_Y, i.e. CL_R_FL -> FL_R_FL.
         std::string historicLandClass = _historicLandClass->value();
@@ -248,8 +230,6 @@ namespace cbm {
     }
 
     /**
-    * setUnfcccLandClass
-    * 
     * Assign string variable currentLandClass as CBMLandClassTransitionModule._currentLandClass, \n
     * CBMLandClassTransitionModule._isForest as CBMLandClassTransitionModule._landClassForestStatus[currentLandClass] \n,
     * CBMLandClassTransitionModule._unfcccLandClass based on CBMLandClassTransitionModule._historicLandClass \n

Source/moja.modules.cbm/src/cbmlandunitdatatransform.cpp

@@ -1,9 +1,6 @@
 /**
 * @file
-* The brief description goes here.
-*
-* The detailed description if any, goes here
-* ******/
+*/
 #include "moja/modules/cbm/cbmlandunitdatatransform.h"
 
 #include <moja/flint/ivariable.h>
@@ -60,18 +57,12 @@ namespace cbm {
     };
 
     /**
-    * Initialise constant variable table as CBMLandUnitDataTransform._varToUse value.
-    * For each constant variable row in table,
-    * Assign CBMLandUnitDataTransform._resultsObject["spatial_unit_id"] as row["spatial_unit_id"],
-    * CBMLandUnitDataTransform._resultsObject["landUnitArea"] as row["landUnitArea"],
-    * CBMLandUnitDataTransform._resultsObject["age"] as row["age"],
-    * CBMLandUnitDataTransform._resultsObject["growth_curve_id"] as row["growth_curve_id"]
-    * CBMLandUnitDataTransform._resultsObject["admin_boundary"] as row["admin_boundary"],
-    * CBMLandUnitDataTransform._resultsObject["eco_boundary"] as row["eco_boundary"] and
-    * CBMLandUnitDataTransform._resultsObject["climate_time_series_id"] as row["climate_time_series_id"].
-    * 
-    * @return DynamicVar&
-    * ************************/
+     * For each row in CBMLandUnitDataTransform._varToUse, set the values of "spatial_unit_id", "landUnitArea", "age", "growth_curve_id",
+     * "admin_boundary", "eco_boundary", "climate_time_series_id" in each row to CBMLandUnitDataTransform._resultsObject \n
+     * Assign CBMLandUnitDataTransform._resultsObject to CBMLandUnitDataTransform._results and return
+     * 
+     * @return DynamicVar&
+     */
     const DynamicVar& CBMLandUnitDataTransform::value() const {
         const auto& table = _varToUse->value();
         for (const auto& row : table) {