trunx documentation

Minimal release of the 3PG forestry model, containing only what is needed to run it via scripts/run_3pg_main.py.

Features

  • Pure JAX implementation of the 3PG forest growth model — jit- and autodiff-compatible

  • Multi-species, monthly time-step simulation of stand biomass, LAI, DBH, and other 3PG state variables

  • Automatic differentiation of simulation outputs with respect to model parameters, via jax.jacobian()

  • Reads site, climate, species, and parameter inputs directly from an Excel workbook

  • Built-in plotting of simulation outputs

Quick Example

The minimal entrypoint this release is built around:

"""Run the 3PG model end-to-end on the Solling reference dataset."""

import os

from trunx.config import threepg_data_folder
from trunx.gp3.PG3_model_impl import run_threepg_main

if __name__ == "__main__":
    file_path = os.path.join(threepg_data_folder, "solling_data.xlsx")
    fig, outputs = run_threepg_main(
        file_path, observed_data=None, plot_output=True, r_comparison=False
    )

Installation

uv sync

The R comparison interface (trunx.gp3.run_r3pg) is not included in this release. If you need it, install the required system packages (r-base-dev, libtirpc-dev) and run:

uv sync --extra r-interface

Usage

Place your input workbook at data/threepg_inputs/solling_data.xlsx (not included — supply your own; see trunx.gp3.PG3_model_impl.prepare_data() for the expected site/climate/species/parameters/observed sheet structure), then run:

uv run python scripts/run_3pg_main.py

Contents: