Skip to content

rothc_py

rothc_py

Rothamsted Carbon Model (RothC) implementation in Python.

__version__ module-attribute 

__version__ = version('rothc_py')

CarbonState dataclass 

CarbonState(dpm: float, rpm: float, bio: float, hum: float, iom: float, soc: float, dpm_rc_age: float, rpm_rc_age: float, bio_rc_age: float, hum_rc_age: float, iom_age: float, total_rc_age: float, swc: float)

Soil carbon pool state for the RothC model.

Represents the state of all carbon pools and their radiocarbon ages at a given timestep.

Attributes:

  • dpm (float) –

    Decomposable Plant Material (t C/ha).

  • rpm (float) –

    Resistant Plant Material (t C/ha).

  • bio (float) –

    Microbial Biomass (t C/ha).

  • hum (float) –

    Humified Organic Matter (t C/ha).

  • iom (float) –

    Inert Organic Matter (t C/ha).

  • soc (float) –

    Total Soil Organic Carbon (t C/ha).

  • dpm_rc_age (float) –

    Radiocarbon age of DPM pool (years).

  • rpm_rc_age (float) –

    Radiocarbon age of RPM pool (years).

  • bio_rc_age (float) –

    Radiocarbon age of BIO pool (years).

  • hum_rc_age (float) –

    Radiocarbon age of HUM pool (years).

  • iom_age (float) –

    Radiocarbon age of IOM pool (years).

  • total_rc_age (float) –

    Radiocarbon age of total SOC (years).

  • swc (float) –

    Soil water content/deficit (mm).

zero classmethod 

zero() -> Self

Create a CarbonState with all pools initialized to zero.

The IOM age is set to the default value (50000 years).

RothC 

RothC(clay: float, depth: float, iom: float)

Rothamsted Carbon Model.

A class-based implementation of the RothC soil carbon model.

Parameters:

  • clay (float) –

    Clay content of the soil (%).

  • depth (float) –

    Depth of topsoil (cm).

  • iom (float) –

    Inert organic matter (t C/ha).

__call__ 

__call__(data: InputData, spinup_data: InputData) -> tuple[CarbonState, dict[str, list]]

Run the full RothC simulation (spin-up + forward).

Parameters:

  • data (InputData) –

    Dictionary containing monthly climate and input data for forward run.

  • spinup_data (InputData) –

    Dictionary containing monthly climate and input data for spin-up.

Returns:

  • tuple[CarbonState, dict[str, list]] –

    Tuple of (final carbon state, dict of monthly results where each key maps to a list of values).

forward 

forward(state: CarbonState, data: InputData) -> tuple[CarbonState, dict[str, list]]

Run the forward simulation from an initial state.

Parameters:

  • state (CarbonState) –

    Initial carbon state (typically from spin_up).

  • data (InputData) –

    Dictionary containing monthly climate and input data.

Returns:

  • tuple[CarbonState, dict[str, list]] –

    Tuple of (final carbon state, dict of monthly results where each key maps to a list of values).

run_timestep 

run_timestep(state: CarbonState, temp: float, rain: float, pevap: float, pc: bool, dpm_rpm: float, c_inp: float, fym_inp: float, modern_c: float) -> CarbonState

Run one timestep of the RothC model.

Calculates rate modifying factors for temperature, moisture, and plant cover, then performs decomposition and radiocarbon age updates.

Parameters:

  • state (CarbonState) –

    Current carbon state (pools and ages).

  • temp (float) –

    Monthly mean air temperature (°C).

  • rain (float) –

    Monthly rainfall (mm).

  • pevap (float) –

    Open pan evaporation (mm).

  • pc (bool) –

    Plant cover (False = no cover, True = covered).

  • dpm_rpm (float) –

    Ratio of DPM to RPM in plant inputs.

  • c_inp (float) –

    Plant carbon input (t C/ha).

  • fym_inp (float) –

    Farmyard manure carbon input (t C/ha).

  • modern_c (float) –

    Fraction of modern carbon (0.0 to 1.0).

Returns:

spin_up 

spin_up(data: InputData) -> tuple[CarbonState, int]

Spin up the RothC model to equilibrium.

This method iteratively applies the same climate/input data until the annual change in total organic carbon falls below a threshold.

Parameters:

  • data (InputData) –

    Dictionary containing monthly climate and input data.

Returns:

percent_modern_c 

percent_modern_c(start_date: datetime, n_months: int) -> list[float]

Returns the % modern radiocarbon values for a given time period.

Uses the actual atmospheric radiocarbon data provided by Rothamsted, which reproduces the curve of % modern C as in Fig 5 of the RothC description.

Parameters:

  • start_date (datetime) –

    The start date for the time series.

  • n_months (int) –

    Number of months to return.

Returns:

  • list[float] –

    List of % modern radiocarbon values for each month.

Notes

Only the year and month attributes of start_date are used. Any day or time information will be ignored.