fresh_cbm.effects

Project cached stand states onto block-level target cells.

The cache is aspatial and per-hectare. This module applies block/fragment area weights and returns the base values and per-block effects for a set of target cells. It has no WS4 dependency; a consumer can combine the carbon result with its own simulator accounts.

class fresh_cbm.effects.BlockEffects(blocks: tuple[int, ...], cells: tuple[tuple[int, str], ...], base: ndarray, effects: ndarray)

Bases: object

Area-weighted base values and per-block effects.

Parameters:

• blocks (tuple of int) – Blocks in effect-row order.

• cells (tuple of (int, str)) – Target cells in column order.

• base (numpy.ndarray) – Untreated totals across every fragment.

• effects (numpy.ndarray) – Shape (blocks, cells); current-chain minus untreated per block.

totals(keep: Mapping[int, bool]) → dict[Cell, float]

Return target totals for a binary keep/remove genome.

Parameters:

keep (mapping of int to bool) – Whether each block keeps its current chain.

Returns:

dict of (int, str) to float – Base plus included block effects.

fresh_cbm.effects.build_block_effects(cache: StateCache, fragments: pd.DataFrame, chains: Mapping[int, Chain], cells: Sequence[Cell]) → BlockEffects

Project cached states onto block-level target cells.

Parameters:

• cache (StateCache) – A loaded, validated cache.

• fragments (pandas.DataFrame) – Rows with block_id, track_id, age, and area_ha.

• chains (mapping of int to tuple) – Current chain per scheduled block.

• cells (sequence of (int, str)) – Target cells to project.

Returns:

BlockEffects – Base values and per-block current-chain effects.

Raises:

ValueError – When a fragment, state, chain, or cell is outside the cache contract.