chore: event descriptions added to glossary

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/cbmpartitioningmodule.cpp

@@ -55,13 +55,28 @@ namespace cbm {
         std::vector<const flint::IPool*> _pools;
     };
 
+    /**
+     * Subscribe to signals LocalDomainInit, TimingInit, DisturbanceEvent and TimingStep
+     *
+     * @param notificationCenter NotificationCenter&
+     * @return void
+     */
 	void CBMPartitioningModule::subscribe(NotificationCenter& notificationCenter) {		
         notificationCenter.subscribe(signals::LocalDomainInit,  &CBMPartitioningModule::onLocalDomainInit,  *this);
         notificationCenter.subscribe(signals::TimingInit,       &CBMPartitioningModule::onTimingInit,       *this);
         notificationCenter.subscribe(signals::DisturbanceEvent, &CBMPartitioningModule::onDisturbanceEvent, *this);
         notificationCenter.subscribe(signals::TimingStep,       &CBMPartitioningModule::onTimingStep,       *this);
     }
 
+    /**
+     * Initialise the values of CBMPartitioningModule._partition, CBMPartitioningModule._spinupParameters and CBMPartitioningModule._spu with variables "partition", "spinup_parameters" and "spu"
+     * from _landUnitData \n
+     * Invoke CBMPartitioningModule.fetchRecoveryRules() \n
+     * Initialise CBMPartitioningModule._agBiomassPools, CBMPartitioningModule._totalBiomassPools, CBMPartitioningModule._totalEcoPools, CBMPartitioningModule._disturbanceMortality with value of variable "disturbance_mortality" from _landUnitData , 
+     * CBMPartitioningModule._disturbanceCategories with value of variable "disturbance_categories" from _landUnitData \n 
+     * 
+     * @return void
+     */
 	void CBMPartitioningModule::doLocalDomainInit() {
         _partition = _landUnitData->getVariable("partition");
         _spinupParameters = _landUnitData->getVariable("spinup_parameters");
@@ -108,6 +123,11 @@ namespace cbm {
         }
     }
 
+    /**
+     * 
+     * 
+     * 
+     */
     void CBMPartitioningModule::doTimingInit() {
         _spuId = _spu->value();
         _cumulativeMortality = 0.0;
@@ -131,6 +151,13 @@ namespace cbm {
         }
     }
 
+    /**
+     * If the value of of the row, "disturbance" in parameter e, and column, CBMPartitioningModule._spuId, is < 0.2, 
+     * Invoke CBMPartitioningModule.doSmallDisturbanceEvent(), else invoke CBMPartitioningModule.doLargeDisturbanceEvent()
+     *
+     * @param e DynamicVar
+     * @return void
+     */
     void CBMPartitioningModule::doDisturbanceEvent(DynamicVar e) {
         auto& data = e.extract<const DynamicObject>();
         std::string disturbanceType = data["disturbance"];
@@ -142,6 +169,13 @@ namespace cbm {
         }
     }
 
+    /**
+     * 
+     * 
+     * 
+     * @param disturbanceType std::string
+     * @param mortality double
+     */
     void CBMPartitioningModule::doSmallDisturbanceEvent(std::string disturbanceType, double mortality) {
         auto disturbanceCategory = _disturbanceCategories[disturbanceType];
         std::string currentCategory = _partition->value();
@@ -271,6 +305,17 @@ namespace cbm {
         return recoveryRule;
     }
 
+    /**
+     * Create the Recovery Rules based on the disturbance type
+     * 
+     * If the disturbance type is not found in CBMPartitioningModule._recoveryRules, return a null pointer \n
+     * 
+     * 
+     * 
+     * 
+     * @param disturbanceType std::string
+     * @return std::shared_ptr<IRecoveryRule>
+     */
     std::shared_ptr<IRecoveryRule> CBMPartitioningModule::createRecoveryRule(std::string disturbanceType)
     {
         auto distTypeRulesIt = _recoveryRules.find(disturbanceType);
@@ -292,6 +337,7 @@ namespace cbm {
         const auto& distTypeRuleConfig = distTypeRuleIt->second;
         std::shared_ptr<IRecoveryRule> recoveryRule = nullptr;
 
+
         auto ruleType = std::get<0>(distTypeRuleConfig);
         if (ruleType == "years_since_disturbance") {
             int target = std::get<1>(distTypeRuleConfig);