`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(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:

CarbonState –

Updated CarbonState.

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:

tuple[CarbonState, int] –

Tuple of (final carbon state at equilibrium, n_cycles).

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, clay: 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.
clay (float) –

Clay content of soil (%).
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 –

Updated CarbonState.

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:

tuple[float, float] –

Tuple of (remaining_pool, decomposed_amount).

moisture_rate_modifier

moisture_rate_modifier(rain: float, pevap: float, clay: float, depth: 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).
clay (float) –

Clay content of soil (%).
depth (float) –

Depth of topsoil (cm).
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:

tuple[float, float, float] –

Tuple of (co2, bio, hum) carbon amounts.

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.

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