Skip to content

rothc_py.rothc

rothc_py.rothc

RothC model implementation.

This module provides the core implementation of the Rothamsted Carbon Model (RothC), including the rate modifier functions, decomposition logic, and the main RothC class.

RothC 

RothC(params: RothCParams)

Rothamsted Carbon Model.

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

Parameters:

  • params (RothCParams) –

    Model and site configuration parameters.

__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).

calculate_radiocarbon_age 

calculate_radiocarbon_age(pool_new: float, ract_new: float, conr: float) -> float

Calculate radiocarbon age from pool size and activity.

Uses the radioactive decay equation inverted to solve for age: age = -ln(remaining/initial) / lambda where lambda = ln(2) / half_life

Parameters:

  • pool_new (float) –

    Current pool size (t C/ha).

  • ract_new (float) –

    Radiocarbon activity (modern C equivalents).

  • conr (float) –

    Decay constant (1/mean_lifetime).

Returns:

  • float –

    Radiocarbon age in years.

decompose_pools 

decompose_pools(state: CarbonState, modern_c: float, rate_m: float, c_inp: float, fym_inp: float, dpm_rpm: float) -> CarbonState

Calculate decomposition and radiocarbon age for soil carbon pools.

Performs monthly carbon pool updates including: first-order decay kinetics, carbon flow between pools (DPM, RPM, BIO, HUM), CO2 respiration, and radiocarbon age calculations.

Parameters:

  • state (CarbonState) –

    Current carbon state (pools and ages).

  • modern_c (float) –

    Fraction of modern carbon (0.0 to 1.0).

  • rate_m (float) –

    Combined rate modifier.

  • c_inp (float) –

    Plant carbon input (t C/ha).

  • fym_inp (float) –

    Farmyard manure carbon input (t C/ha).

  • dpm_rpm (float) –

    Ratio of DPM to RPM in plant inputs.

Returns:

  • CarbonState –

    Tuple of (updated CarbonState, total CO2 respired this timestep in t C/ha).

decompose_single_pool 

decompose_single_pool(pool: float, rate_k: float, rate_m: float, tstep: float) -> tuple[float, float]

Decompose a carbon pool using first-order decay kinetics.

Parameters:

  • pool (float) –

    Carbon pool size (t C/ha).

  • rate_k (float) –

    Decomposition rate constant for this pool (per year).

  • rate_m (float) –

    Combined rate modifier (temperature × moisture × plant cover).

  • tstep (float) –

    Timestep (1/12 for monthly, 1/365 for daily).

Returns:

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).

moisture_rate_modifier 

moisture_rate_modifier(rain: float, pevap: float, pc: bool, swc: float) -> tuple[float, float]

Calculate the rate modifying factor for moisture.

Calculates soil moisture deficit and derives a rate modifier based on the soil water balance, accounting for rainfall, evaporation, and plant cover.

Parameters:

  • rain (float) –

    Monthly rainfall (mm).

  • pevap (float) –

    Open pan evaporation (mm).

  • pc (bool) –

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

  • swc (float) –

    Soil water content/deficit (mm).

Returns:

  • float –

    Tuple of (rate modifying factor for moisture, updated swc).

  • float –

    rm_moist is typically between 0.2 and 1.0.

partition_carbon_flows 

partition_carbon_flows(decomposed: float, x: float) -> tuple[float, float, float]

Partition decomposed carbon into CO2, BIO, and HUM fractions.

The partitioning coefficient x depends on clay content and determines the proportion lost as CO2 vs incorporated into biomass/humus.

Parameters:

  • decomposed (float) –

    Amount of carbon decomposed (t C/ha).

  • x (float) –

    Clay-dependent partitioning coefficient.

Returns:

plant_cover_rate_modifier 

plant_cover_rate_modifier(pc: bool) -> float

Calculate the plant retainment modifying factor.

Returns a reduced rate when the soil is covered by vegetation, representing reduced decomposition due to litter retention.

Parameters:

  • pc (bool) –

    Plant cover (False = no cover/bare soil, True = covered by crop).

Returns:

  • float –

    Rate modifying factor: 1.0 for bare soil, 0.6 for covered soil.

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) -> tuple[CarbonState, float]

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:

  • tuple[CarbonState, float] –

    Tuple of (updated CarbonState, total CO2 respired this timestep in t C/ha).

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:

temperature_rate_modifier 

temperature_rate_modifier(temp: float) -> float

Calculate the rate modifying factor for temperature.

Uses the Jenkinson equation to calculate the temperature rate modifier based on monthly mean air temperature.

Parameters:

  • temp (float) –

    Monthly mean air temperature (°C).

Returns:

  • float –

    Rate modifying factor for temperature (typically 0.0 to ~5.0).