cbm-exn

CBM-EXN is a CBM-CFS3 equivalent model, except that it is driven by net C increments. Therefore the difference between CBM-EXN, and CBM-CFS3 is that CBM-EXN runs without the merchantable volume to biomass conversion routines and instead accepts C increments for the MerchC foliage C and other C pools directly.

The other difference is that the CBM3 built-in HW, SW structure is removed, and each simulation record represents an individual cohort with age and species. This allows the flexibility of user-defined multi-cohort stand structuring via external grouping.

cbm_exn is built using the Model definition interfaces and classes

See cbm-exn-custom-ops for a step by step example for cbm_exn including overriding the default C ops

Functions and classes

libcbm.model.cbm_exn.cbm_exn_land_state.advance_spinup_state(spinup_vars: ModelVariables) → tuple[bool, ModelVariables]

Update the variables and state at the start of each spinup timestep.

Parameters:

spinup_vars (ModelVariables) – Collection of variables, parameters and state applicable to spinup procedure

Returns:

a tuple of the all finished flag,

and post-spinup-step modified ModelVariables

Return type:

tuple[bool, ModelVariables]

libcbm.model.cbm_exn.cbm_exn_land_state.end_spinup_step(spinup_vars: ModelVariables) → ModelVariables

Update the spinup state and variables at the end of each spinup timestep.

Parameters:

spinup_vars (ModelVariables) – spinup state and variables

Returns:

initialized state and variables

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_land_state.end_step(cbm_vars: ModelVariables, parameters: CBMEXNParameters) → ModelVariables

Assign the variables and state at the end of a CBM timestep.

Parameters:
Returns:

updated cbm state and variables

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_land_state.init_cbm_vars(model: CBMEXNModel, spinup_vars: ModelVariables) → ModelVariables

Initialze the CBM variables and state at the end of spinup and prior to CBM stepping

Parameters:
Returns:

initialized CBM variables, state, parameters ready for

CBM stepping

Return type:

CBMVariables

libcbm.model.cbm_exn.cbm_exn_land_state.start_step(cbm_vars: ModelVariables, parameters: CBMEXNParameters) → ModelVariables

Assign the variables and state at the start of a CBM timestep.

Parameters:
Returns:

updated cbm state and variables

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_model.initialize(parameters: dict | None = None, config_path: str | None = None, include_spinup_debug: bool = False) → Iterator[CBMEXNModel]

Initialize CBMEXNModel

Parameters:

  • parameters (dict, optional) – a dictionary of named parameters for running the cbm_exn module. During initialization any required parameters that are not defined in this dictionary will be drawn from the specified config_path.

  • config_path (str, optional) – path to directory containing cbm_exn parameters in json and csv formats. If unspecified, packaged defaults are used. See: libcbm.resources.get_cbm_exn_parameters_dir().

  • include_spinup_debug (bool, optional) – If set to true, the get_spinup_output of the returned class instance can be used to inspect timestep-by-timestep spinup output. This will cause slow spinup performance. Defaults to False.

Yields:

Iterator[CBMEXNModel] – instance of CBMEXNModel

class libcbm.model.cbm_exn.cbm_exn_model.SpinupReporter

Tracks step-by-step results during spinup for debugging purposes.

append_spinup_output(timestep: int, spinup_vars: ModelVariables) → None

Append a set of results to the spinup reporter

Parameters:

  • timestep (int) – the step number

  • spinup_vars (ModelVariables) – the spinup variables and state

get_output() → ModelVariables

Gets the accumulated spinup results

class libcbm.model.cbm_exn.cbm_exn_model.CBMEXNModel(cbm_model: CBMModel, parameters: CBMEXNParameters, spinup_reporter: SpinupReporter | None = None)

The CBMEXNModel: CBM-CFS3 with external net Aboveground Carbon biomass increments

compute(cbm_vars: ModelVariables, op_names: list[str])

Apply several sequential operations to the pools, and flux stored in the specified cbm_vars.

Parameters:

  • cbm_vars (ModelVariables) – Collection of CBM simulation variables. This function modifies the pools and flux dataframes stored within cbm_vars.

  • op_names (list[str]) – The list of matrix operations names to apply

property flux_names: list[str]

Get the list of flux indicator names, these form the columns for the flux dataframe.

Returns:

the flux indicator names

Return type:

list[str]

get_spinup_output() → ModelVariables | Dict[str, DataFrame]

If spinup debugging was enabled during construction of this class, a time-step by time-step account of the spinup routine for all stands is returned.

Raises:

ValueError – this class instance was not initialized to track spinup results.

Returns:

the timestep by timestep spinup results

Return type:

cbm_vars_type

property matrix_ops: ModelMatrixOps

ModelMatrixOps instance which computes and caches C matrix flows

Returns:

instance of ModelMatrixOps

Return type:

ModelMatrixOps

property parameters: CBMEXNParameters

CBM constant parameters

Returns:

CBM constant parameters

Return type:

CBMEXNParameters

property pool_names: list[str]

Get the list of pool names, also used as the column headers for the cbm_vars pools dataframe

Returns:

the pool names

Return type:

list[str]

spinup(spinup_input: ModelVariables | Dict[str, DataFrame], ops: list[dict] | None = None, op_sequence: list[str] | None = None) → ModelVariables | Dict[str, DataFrame]

initializes Carbon pools along the row axis of the specified spinup input using the CBM-CFS3 approach for spinup.

Parameters:

spinup_input (cbm_vars_type) – spinup variables and parameters

Returns:

initlaized CBM variables and state, prepared

for CBM stepping.

Return type:

cbm_vars_type

step(cbm_vars: ModelVariables | Dict[str, DataFrame], ops: list[dict] | None = None, disturbance_op_sequence: list[str] | None = None, step_op_sequence: list[str] | None = None) → ModelVariables | Dict[str, DataFrame]

Perform one timestep of the CBMEXNModel

Parameters:

cbm_vars (cbm_vars_type) – the simulation state and variables

Returns:

modified state and variables.

Return type:

cbm_vars_type

class libcbm.model.cbm_exn.cbm_exn_parameters.CBMEXNParameters(data: dict[str, list | DataFrame])

Class for storing and pre-processing parameters for cbm_exn.

flux_configuration() → list[dict]

returns cbm_exn’s raw flux inidicator json configuration

Returns:

flux indicator configuration

Return type:

list[dict]

get_decay_parameters() → dict[str, dict[str, float]]

Get decay parameters for all of the named dead organic matter (DOM) pools.

Returns:

a dictionary of named parameters

for DOM pool decays

Return type:

dict[str,dict[str, float]]

get_disturbance_matrices() → DataFrame

Gets a dataframe with disturbance matrix value information.

Columns:

* disturbance_matrix_id
* source_pool_id
* sink_pool_id
* proportion
Returns:

a table of disturbance matrix values for CBM

disturbance C pool flows.

Return type:

pd.DataFrame

get_disturbance_matrix_associations() → DataFrame

Gets a dataframe with disturbance matrix assocation information

Columns:

* disturbance_type_id
* spatial_unit_id
* sw_hw
* disturbance_matrix_id
Returns:

a table of values that associated disturbance matrix

ids with disturbance type, spatial unit and sw-hw forest type.

Return type:

pd.DataFrame

get_root_parameters() → dict[str, float]

get the CBM root parameters as a dictionary

Returns:

named root parameters as a dictionary of

name: parameter.

Return type:

dict[str, float]

get_slow_mixing_rate() → float

gets the CBM slow mixing rate parameter

Returns:

slow mixing rate

Return type:

float

get_sw_hw_map() → dict[int, int]

returns a map of species identifier to sw_hw where the value is either 0: sw or 1: hw

Returns:

dictionary of species id to 0 (sw) or 1 (hw)

Return type:

dict[int, int]

get_turnover_parameters() → DataFrame

gets a table of turnover parameters used for CBM proportional turnovers

Returns:

a pandas dataframe of the turnover parameters

Return type:

pd.DataFrame

pool_configuration() → list[str]

returns the cbm_exn pools as a list of strings

Returns:

pool names

Return type:

list[str]

libcbm.model.cbm_exn.cbm_exn_spinup.prepare_spinup_vars(spinup_input: ModelVariables, parameters: CBMEXNParameters, include_flux: bool = False) → ModelVariables

Initialize spinup variables and state.

Parameters:

  • spinup_input (ModelVariables) – A collection of dataframes for running CBM spinup.

  • model (CBMEXNModel) – Initialized cbm_exn model.

  • include_flux (bool) – If set to true space will be allocated for storing flux indicators through the spinup procedure.

Returns:

Inititlized cbm variables and state for running spinup.

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_spinup.spinup(model: CBMEXNModel, spinup_vars: ModelVariables, reporting_func: Callable[[int, ModelVariables], None] | None = None, ops: list[dict] | None = None, op_sequence: list[str] | None = None) → ModelVariables

Run the CBM spinup routine.

Parameters:

  • model (CBMEXNModel) – Initialized cbm_exn model.

  • spinup_vars (ModelVariables) – Spinup vars, as returned by cbm_exn_spinup.prepare_spinup_vars().

  • reporting_func (Callable[[int, ModelVariables], None], optional) – Optional function for accepting timestep-by-timestep spinup results for debugging. Defaults to None.

  • include_flux (bool, optional) – if reporting func is specified, flux values will additionally be tracked during the spinup process. Defaults to False.

Returns:

A collection of dataframes with initialized C pools and

state, ready for CBM stepping.

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_step.step(model: CBMEXNModel, cbm_vars: ModelVariables, ops: list[dict] | None = None, step_op_sequence: list[str] | None = None, disturbance_op_sequence: list[str] | None = None) → ModelVariables

Advance CBM state by one timestep, and track results.

This function updates state variables, performs disturbances for affected statnds and annual processes for all stands. The cbm_vars pools dataframe is updated with changed pool values. The cbm_vars flux dataframe tracks specific flows between pools for meaningful indicators.

Parameters:
Returns:

updated cbm_vars

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_step.step_annual_process(model: CBMEXNModel, cbm_vars: ModelVariables, ops: list[dict] | None = None, op_sequence: list[str] | None = None) → ModelVariables

Compute and track CBM annual processes.

Parameters:
Returns:

updated cbm_vars

Return type:

CBMVariables

libcbm.model.cbm_exn.cbm_exn_step.step_disturbance(model: CBMEXNModel, cbm_vars: ModelVariables, ops: list[dict] | None = None, op_sequence: list[str] | None = None) → ModelVariables

Compute and track disturbance matrix effects across multiple stands.

The “disturbance_type” series of the cbm_vars parameters dataframe is used to set the disturbance type. Zero or negative values indicate no disturbance.

The spatial_unit_id, and sw_hw series of the cbm_vars state dataframe is used to select the appropriate disturbance matrix.

Parameters:
Returns:

updated cbm_variables and state

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_variables.init_cbm_vars(n_rows: int, pool_names: list[str], flux_names: list[str], backend_type: BackendType) → ModelVariables

Initialize dataframe storage for cbm variables and state.

Member dataframes of cbm_vars:

* pools: the CBM pools
* flux: dataframe for tracking flux indicator values (akin to CBM-CFS3
    tblFluxIndicators)
* parameters: timestep parameters for each stand
* state: state variables
Parameters:

  • n_rows (int) – The number of rows in each member dataframe.

  • pool_names (list[str]) – The list of pool names, defines the columns of the cbm_vars pools dataframe.

  • flux_names (list[str]) – The list of flux indicator names, defines the columns of the cbm_vars flux dataframe.

  • backend_type (BackendType) – The backend storage type

Returns:

Initialized cbm_vars

Return type:

ModelVariables

libcbm.model.cbm_exn.cbm_exn_variables.init_flux(n_rows: int, flux_names: list[str], backend_type: BackendType) → DataFrame

Initialize the flux dataframe for cbm_vars. The values are all set to zero.

Parameters:

  • n_rows (int) – the number of rows in the resulting dataframe

  • flux_names (list[str]) – the list of flux names, this forms the columns of the resulting dataframe.

  • backend_type (BackendType) – The backend storage type

Returns:

initialized dataframe

Return type:

DataFrame

libcbm.model.cbm_exn.cbm_exn_variables.init_parameters(n_rows: int, backend_type: BackendType) → DataFrame

Initialize the flux dataframe for cbm_vars. The values are all set to zero in the case of integer columns, and np.nan for float columns

Columns:

* mean_annual_temperature (float) - the mean annual tempurature
    step parameter
* disturbance_type (int) - the disturbance type id step parameter
* merch_inc (float) - net aboveground merchantable C increment step
    parameter
* foliage_inc (float) - net aboveground foliage C increment step
    parameter
* other_inc (float) - net aboveground other C increment step
    parameter
Parameters:

  • n_rows (int) – the number of rows in the resulting dataframe

  • backend_type (BackendType) – The backend storage type

Returns:

initialized dataframe

Return type:

DataFrame

libcbm.model.cbm_exn.cbm_exn_variables.init_pools(n_rows: int, pool_names: list[str], backend_type: BackendType) → DataFrame

Initialize the pools dataframe for cbm_vars. The values are all set to zero.

Parameters:

  • n_rows (int) – the number of rows in the resulting dataframe

  • pool_names (list[str]) – the list of pool names, this forms the columns of the resulting dataframe.

  • backend_type (BackendType) – The backend storage type

Returns:

initialized dataframe

Return type:

DataFrame

libcbm.model.cbm_exn.cbm_exn_variables.init_spinup_state(n_rows: int, backend_type: BackendType) → DataFrame

Intitialze a dataframe containing CBM state variables specific to the spinup process. The values are all set to zero in the case of integer columns, and np.nan for float columns.

Columns:

* spinup_state - see:
    :py:class:`libcbm.model.model_definition.spinup_engine.SpinupState`
* age - the age
* delay_step - tracks the number of steps when in the delay state
* disturbance_type - set to indicate a historical or last pass
    disturbance should occur.
* rotation - the number of rotations that have occurred
* last_rotation_slow - the sum of slow C values at the end of the last
    rotation
* this_rotation_slow - the sum of slow C values for this rotation
* enabled - set to 0 when spinup has finished for the corresponding
    dataframe row
Parameters:

  • n_rows (int) – the number of rows in the resulting dataframe

  • backend_type (BackendType) – The backend storage type

Returns:

initialized dataframe

Return type:

DataFrame

libcbm.model.cbm_exn.cbm_exn_variables.init_state(n_rows: int, backend_type: BackendType) → DataFrame

Intitialze a dataframe containing CBM state variables. The values are all set to zero in the case of integer columns, and np.nan for float columns.

Identifiers correspond to values in the default parameters. See libcbm.model.cbm_exn.cbm_exn_parameters()

Columns:

* area (float) - area in hectares
* spatial_unit_id (int) - spatial unit identifier
* land_class_id (int) - UNFCCC land class identifier
* age (int) - the age
* species (int) - species identifier
* sw_hw (int) - flag indicating softwood when 0 and hardwood when 1
* time_since_last_disturbance (int) - the number of timesteps since
    the last disturbance event
* time_since_land_use_change (int) - the number of timesteps since a
    UNFCCC land class change occurred, or -1 if no change has occurred
* last_disturbance_type (int) - the id of the last disturbance type to
    occur
* enabled (int) - flag indicating all processes are disabled when 1
    and otherwise fully disabled meaning no changes to cbm_vars should
    occur
Parameters:

  • n_rows (int) – the number of rows in the resulting dataframe

  • backend_type (BackendType) – The backend storage type

Returns:

initialized dataframe

Return type:

DataFrame