🌲 GOBLIN_CBM_runner, a CBM CFS3 interface for the GOBLIN model

Based on the GOBLIN (General Overview for a Backcasting approach of Livestock INtensification) LifeCycle Analysis tool, the cbm_runner package generates the data requried for the CBM CFS3 (libcbm_py) tool. It also interfaces with the tool directly, generating results in a single dataframe for all scenarios.

The outputs are related to biomass, and dead organic matter. These are summed into a total ecosystem value.

The estimated volumns are all in t of C.

Installation

Install from git hub.

pip install "goblin_cbm_runner@git+https://github.com/GOBLIN-Proj/goblin_cbm_runner.git@main" 

Install from PyPI

pip install goblin_cbm_runner

v0.6.0 note: From v0.6.0 the package targets GOBLIN_lite only — GeoGoblin / geo-runner support was removed (fork the 0.5.0 line if you need it). The old Runner / DataManager entry point has been replaced by the scenario generators below. Output is archive-only: call export_archive() to write a self-describing SQLite .db; no CSVs are written automatically.

Usage

There are four entry points. All accept a scenario DataFrame and produce an annual carbon-flux DataFrame plus a SQLite archive.

National pipeline — NationalScenarioGenerator

The standard national simulation (Forest Management + Afforestation + Scenarios) using the bundled Irish database, to 2070.

from goblin_cbm_runner.scenario_generator import NationalScenarioGenerator

nsg = NationalScenarioGenerator(
    scenario_data=scenario_df,          # pandas DataFrame of scenarios
    afforestation_data=afforest_df,     # pandas DataFrame of afforestation areas
    config={"afforest_delay": 5, "annual_rate_pre_delay": 1200},
    comprehensive=False,                # True to also capture pools/flux/state validation tables
)

results = nsg.run_flux_simulation()     # annual flux DataFrame (all scenarios + baseline)
nsg.export_archive("./simulation_archive.db")

Dynamic pipeline — DynamicScenarioGenerator

Extends FM and AF beyond 2070 with NAI-based (Net Annual Increment) harvest, and extends the scenario end year to match.

from goblin_cbm_runner.dynamic_scenario_generator import DynamicScenarioGenerator

dsg = DynamicScenarioGenerator(
    scenario_data=scenario_df,
    afforestation_data=afforest_df,
    config={"afforest_delay": 5, "annual_rate_pre_delay": 1200},
    dynamic_config={"harvest_ratio": 0.75, "dynamic_years": 50},  # optional; 0.75 recommended
)

# Use ONE of the two entry points (alternatives, not sequential steps):
results = dsg.run_flux_simulation()            # extended FM + AF + SC (already includes the -1 baseline)
# baseline = dsg.run_baseline_flux_simulation()  # extended FM + AF only — use INSTEAD for baseline-only
dsg.export_archive("./dynamic_archive.db")

Standard pipeline (user CSVs) — StandardSimGenerator

Run a simulation from your own inventory CSV files with an explicit disturbance schedule — no internal database of stands required (the bundled AIDB is still used for CBM parameters).

from goblin_cbm_runner.standard_sim_generator import StandardSimGenerator

# Copy and edit the template CSVs first:
StandardSimGenerator.get_template("./my_forest/")

gen = StandardSimGenerator(
    csv_directory="./my_forest/",
    config={"baseline_year": 2020, "end_year": 2050},
    scenario=0,
)
results = gen.run_flux_simulation()
gen.export_archive("./standard_archive.db")

Dynamic standard pipeline (user CSVs + NAI) — DynamicStandardSimGenerator

Your own inventory CSVs with NAI-based dynamic harvest. Omit end_year for "NAI from day 1", or set it for a static warm-up period before the dynamic phase.

from goblin_cbm_runner.dynamic_standard_sim_generator import DynamicStandardSimGenerator

gen = DynamicStandardSimGenerator(
    csv_directory="./my_forest/",
    config={"baseline_year": 2020},                              # omit end_year → years=0
    dynamic_config={"harvest_ratio": 0.75, "dynamic_years": 30},
)
results = gen.run_flux_simulation()
gen.export_archive("./dynamic_standard_archive.db")

Runnable versions of all four live in tests/examples/ (nsg_example.py, dsg_example.py, standard_sim_example.py, dynamic_standard_sim_example.py).

CBM Disturbance Sort Types Note

libcbm_py is not a direct conversion of the CBM-CFS3 model, and there are some small differences.

One key difference is the available sort types for stand disturbances. Some sorting options in CBM-CFS3 are not available in libcbm_py, while others may function slightly differently.

In particular, the "Sort by time since softwood component was last harvested" (4) and "Sort by time since hardwood component was last harvested" (13) are missing from libcbm_py. These sorts help prioritize stands based on past harvests, which can be important for disturbance modeling.

Below, we provide the full set of sort types from CBM-CFS3, followed by the available sorts in libcbm_py, along with suggested approximations for missing sorts.

Sort Types from CBM-CFS3

The following table lists all disturbance sort types available in CBM-CFS3:

Available Sort Types in libcbm_py

Below are the disturbance sort types that are implemented in libcbm_py:

{
    1: "PROPORTION_OF_EVERY_RECORD",
    2: "MERCHCSORT_TOTAL",
    3: "SORT_BY_SW_AGE",
    5: "SVOID",
    6: "RANDOMSORT",
    7: "TOTALSTEMSNAG",
    8: "SWSTEMSNAG",
    9: "HWSTEMSNAG",
    10: "MERCHCSORT_SW",
    11: "MERCHCSORT_HW",
    12: "SORT_BY_HW_AGE",
}

License

This project is licensed under the terms of the MIT license.