def get_disturbance_ops(self, disturbance_op, inventory,
parameters):
"""Sets up CBM disturbance matrices as a bulk matrix operations.
Args:
disturbance_op (int): Handle for a block of matrices as
allocated by the :py:func:`AllocateOp` function. Used to
compute disturbance event pool flows.
inventory (object): CBM inventory data. Used by this function to
find correct parameters from the set of disturbance parameters
passed to library initialization. Will not be modified by this
function. See:
:py:func:`libcbm.model.cbm_variables.initialize_inventory`
for a compatible definition
parameters (object): Read-only parameters used to set
disturbance type id to fetch the appropriate disturbance
matrix. See:
:py:func:`libcbm.model.cbm_variables.initialize_cbm_parameters`
for a compatible definition.
"""
spatial_unit = data_helpers.unpack_ndarrays(inventory).spatial_unit
disturbance_type = data_helpers.unpack_ndarrays(
parameters).disturbance_type
n = spatial_unit.shape[0]
opIds = (ctypes.c_size_t * (1))(*[disturbance_op])
self.handle.call(
"LibCBM_GetDisturbanceOps", opIds, n, spatial_unit,
disturbance_type)
def initialize_land_state(self, inventory, pools, state_variables):
"""Initializes CBM state to values appropriate for after running
spinup and before starting CBM stepping
Args:
inventory (object): CBM inventory data. Will not be modified by
this function. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_inventory`
for a compatible definition.
pools (numpy.ndarray or pandas.DataFrame): matrix of shape
n_stands by n_pools. The values in this matrix are updated by
this function for stands that have an afforestation pre-type
defined.
state_variables (pandas.DataFrame): simulation variables which
define all non-pool state in the CBM model. This
function call will alter this variable with CBM initial state
values. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_cbm_state_variables`
for a compatible definition.
"""
i = data_helpers.unpack_ndarrays(inventory)
v = data_helpers.unpack_ndarrays(state_variables)
n = i.last_pass_disturbance_type.shape[0]
poolMat = LibCBM_Matrix(data_helpers.get_ndarray(pools))
self.handle.call(
"LibCBM_InitializeLandState", n, i.last_pass_disturbance_type,
i.delay, i.age, i.spatial_unit, i.afforestation_pre_type_id,
poolMat, v.last_disturbance_type, v.time_since_last_disturbance,
v.time_since_land_class_change, v.growth_enabled, v.enabled,
v.land_class, v.age)
def get_decay_ops(self, dom_decay_op, slow_decay_op, slow_mixing_op,
inventory, parameters,
historical_mean_annual_temp=False):
"""Prepares dead organic matter decay bulk matrix operations.
Args:
dom_decay_op (int): Handle for a block of matrices as
allocated by the :py:func:`allocate_op` function. Used to
compute dom decay operations.
slow_decay_op (int): Handle for a block of matrices as
allocated by the :py:func:`allocate_op` function. Used to
compute slow pool decay operations.
slow_mixing_op (int): Handle for a block of matrices as
allocated by the :py:func:`allocate_op` function. Used to
compute slow pool mixing operations.
inventory (object): CBM inventory data. Used by this function to
find correct parameters from the set of decay parameters
passed to library initialization. Will not be modified by this
function. See:
:py:func:`libcbm.model.cbm_variables.initialize_inventory`
for a compatible definition
parameters (object): parameters for this timestep
historical_mean_annual_temp (bool, optional): If set to true, the
historical default mean annual temperature is used. This is
intended for spinup. If explicit mean annual temperature
is provided via the parameters argument, this parameter will
be ignored, and the explicit mean annual temp will be used.
Defaults to False.
"""
i = data_helpers.unpack_ndarrays(inventory)
p = data_helpers.unpack_ndarrays(parameters)
n = i.spatial_unit.shape[0]
opIds = (ctypes.c_size_t * (3))(
*[dom_decay_op, slow_decay_op, slow_mixing_op])
spatial_unit = data_helpers.get_nullable_ndarray(
i.spatial_unit, dtype=ctypes.c_int)
mean_annual_temp = \
data_helpers.get_nullable_ndarray(
p.mean_annual_temp) \
if "mean_annual_temp" in p.__dict__ else None
if mean_annual_temp is not None:
# If the mean annual temperature is specified, then omit the
# spatial unit, whose only purpose in the context of the decay
# routine is to fetch the mean annual temperature value from
# the CBM defaults database
spatial_unit = None
self.handle.call(
"LibCBM_GetDecayOps", opIds, n, spatial_unit,
historical_mean_annual_temp, mean_annual_temp)
def get_merch_volume_growth_ops(self, growth_op, overmature_decline_op,
classifiers, inventory, pools,
state_variables):
"""Computes CBM merchantable growth as a bulk matrix operation.
Args:
growth_op (int): Handle for a block of matrices as allocated by
the :py:func:`AllocateOp` function. Used to compute merch
volume growth operations.
overmature_decline_op (int): Handle for a block of matrices as
allocated by the :py:func:`AllocateOp` function. Used to
compute merch volume growth operations.
classifiers (pandas.DataFrame): matrix of classifier ids
associated with yield tables.
inventory (object): Used by this function to find correct spatial
parameters from the set of merch volume growth parameters.
Will not be modified by this function. See:
:py:func:`libcbm.model.cbm_variables.initialize_inventory`
for a compatible definition.
pools (numpy.ndarray or pandas.DataFrame): matrix of shape
n_stands by n_pools. Used by this function to compute a root
increment, and also to limit negative growth increments such
that a negative biomass pools are prevented. This parameter
is not modified by this function.
state_variables (pandas.DataFrame): simulation variables which
define all non-pool state in the CBM model. This function
call will not alter this parameter. See:
:py:func:`libcbm.model.cbm_variables.initialize_cbm_state_variables`
for a compatible definition
"""
n = pools.shape[0]
poolMat = LibCBM_Matrix(data_helpers.get_ndarray(pools))
opIds = (ctypes.c_size_t * (2))(*[growth_op, overmature_decline_op])
i = data_helpers.unpack_ndarrays(inventory)
classifiers_mat = LibCBM_Matrix_Int(
data_helpers.get_ndarray(classifiers))
v = data_helpers.unpack_ndarrays(state_variables)
last_disturbance_type = data_helpers.get_nullable_ndarray(
v.last_disturbance_type, dtype=ctypes.c_int)
time_since_last_disturbance = data_helpers.get_nullable_ndarray(
v.time_since_last_disturbance, dtype=ctypes.c_int)
growth_multiplier = data_helpers.get_nullable_ndarray(
v.growth_multiplier, dtype=ctypes.c_double)
growth_enabled = data_helpers.get_nullable_ndarray(
v.growth_enabled, dtype=ctypes.c_int)
self.handle.call(
"LibCBM_GetMerchVolumeGrowthOps", opIds, n, classifiers_mat,
poolMat, v.age, i.spatial_unit, last_disturbance_type,
time_since_last_disturbance, growth_multiplier, growth_enabled)
def advance_spinup_state(self, inventory, variables, parameters):
"""Advances spinup state variables through one spinup step.
Args:
inventory (object): CBM inventory data. Will not be modified by
this function. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_inventory`
for a compatible definition
variables (object): Spinup working variables. Defines all
non-pool simulation state during spinup. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_spinup_variables`
for a compatible definition
parameters (object): spinup parameters. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_spinup_parameters`
for a compatible definition
Returns:
int: The number of stands finished running the spinup routine
as of the end of this call.
"""
i = data_helpers.unpack_ndarrays(inventory)
p = data_helpers.unpack_ndarrays(parameters)
v = data_helpers.unpack_ndarrays(variables)
n = i.spatial_unit.shape[0]
# If return_interval, min_rotations, max_rotations are explicitly
# set by the user, ignore the spatial unit, which is used to set
# default value for these 3 variables.
return_interval = data_helpers.get_nullable_ndarray(
p.return_interval, dtype=ctypes.c_int)
min_rotations = data_helpers.get_nullable_ndarray(
p.min_rotations, dtype=ctypes.c_int)
max_rotations = data_helpers.get_nullable_ndarray(
p.max_rotations, dtype=ctypes.c_int)
spatial_unit = None
if return_interval is None or min_rotations is None \
or max_rotations is None:
spatial_unit = data_helpers.get_nullable_ndarray(
i.spatial_unit, dtype=ctypes.c_int)
n_finished = self.handle.call(
"LibCBM_AdvanceSpinupState", n, spatial_unit, return_interval,
min_rotations, max_rotations, i.age, i.delay, v.slow_pools,
i.historical_disturbance_type, i.last_pass_disturbance_type,
i.afforestation_pre_type_id, v.spinup_state, v.disturbance_type,
v.rotation, v.step, v.last_rotation_slow_C, v.growth_enabled,
v.enabled)
return n_finished
def get_turnover_ops(self, biomass_turnover_op, snag_turnover_op,
inventory):
"""Computes biomass turnovers and dead organic matter turnovers as
bulk matrix operations.
Args:
biomass_turnover_op (int): Handle for a block of matrices as
allocated by the :py:func:`allocate_op` function. Used to
compute biomass turnover operations.
snag_turnover_op (int): Handle for a block of matrices as
allocated by the :py:func:`allocate_op` function. Used to
compute dom (specifically snags) turnover operations.
inventory (object): CBM inventory data. Used by this function
to find correct parameters from the set of turnover parameters
passed to library initialization. Will not be modified by this
function. See:
:py:func:`libcbm.model.cbm_variables.initialize_inventory`
for a compatible definition.
"""
i = data_helpers.unpack_ndarrays(inventory)
n = i.spatial_unit.shape[0]
opIds = (ctypes.c_size_t * (2))(
*[biomass_turnover_op, snag_turnover_op])
self.handle.call(
"LibCBM_GetTurnoverOps", opIds, n, i.spatial_unit)
def advance_stand_state(self, classifiers, inventory, state_variables,
parameters):
"""Advances CBM stand variables through a timestep based on the
current simulation state.
Args:
classifiers (pandas.DataFrame): classifier values associated with
the inventory
inventory (object): CBM inventory data. Will not be modified by
this function. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_inventory`
for a compatible definition
state_variables (pandas.DataFrame): simulation variables which
define all non-pool state in the CBM model. Altered by this
function call. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_cbm_state_variables`
for a compatible definition
parameters (object): Read-only parameters used in a CBM timestep.
See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_cbm_parameters`
for a compatible definition.
"""
i = data_helpers.unpack_ndarrays(inventory)
v = data_helpers.unpack_ndarrays(state_variables)
p = data_helpers.unpack_ndarrays(parameters)
n = i.age.shape[0]
classifiersMat = LibCBM_Matrix_Int(
data_helpers.get_ndarray(classifiers))
self.handle.call(
"LibCBM_AdvanceStandState", n, classifiersMat,
i.spatial_unit, p.disturbance_type, p.reset_age,
v.last_disturbance_type, v.time_since_last_disturbance,
v.time_since_land_class_change, v.growth_enabled, v.enabled,
v.land_class, v.regeneration_delay, v.age)
def end_step(self, state_variables):
"""Applies end-of-timestep changes to the CBM state
Args:
state_variables (pandas.DataFrame): simulation variables which
define all non-pool state in the CBM model. This
function call will alter this variable with end-of-step
changes. See:
:py:func:`libcbm.model.cbm.cbm_variables.initialize_cbm_state_variables`
for a compatible definition
"""
v = data_helpers.unpack_ndarrays(state_variables)
n = v.age.shape[0]
self.handle.call(
"LibCBM_EndStep", n, v.enabled, v.growth_enabled, v.age,
v.regeneration_delay, v.time_since_last_disturbance,
v.time_since_land_class_change)
def end_spinup_step(self, pools, variables):
"""Applies end-of-timestep changes to the spinup state
Args:
pools (numpy.ndarray or pandas.DataFrame): matrix of shape
n_stands by n_pools. The values in this matrix are used to
compute a criteria for exiting the spinup routing. The
biomass pools are also zeroed for historical and last pass
disturbances.
variables (object): Spinup working variables. Defines all
non-pool simulation state during spinup. Set to an
end-of-timestep state by this function. See:
:py:func:`libcbm.model.cbm_variables.initialize_spinup_variables`
for a compatible definition
"""
v = data_helpers.unpack_ndarrays(variables)
n = v.age.shape[0]
poolMat = LibCBM_Matrix(data_helpers.get_ndarray(pools))
self.handle.call(
"LibCBM_EndSpinupStep", n, v.spinup_state, v.disturbance_type,
poolMat, v.age, v.slow_pools, v.growth_enabled)