CNit Physics API

This section documents the main physics modules and submodules of the CNit package. Each module contains classes and functions for modeling various aspects of the carbon and nitrogen cycles.

Land Use

Handles land use and land cover change processes.

Land Use Flux Calculator for the CNit Model.

This module defines the LanduseCalculator class, which processes land use change forcing data and translates it into the specific fluxes required by the CNit model. The calculator handles both carbon and nitrogen land use fluxes with explicit separation of deforestation, afforestation (or reforestation), and regrowth dynamics.

Key Features:

1. Explicit Separation of Deforestation and Afforestation: Land use gross emissions (LUgrs) are separated into deforestation (LUdfst, always positive) and afforestation/reforestation (LUafst, always positive). This separation is critical for scenarios involving carbon dioxide removal (CDR) and net-zero targets where afforestation plays a significant role.

2. Regrowth Following Deforestation: Natural recovery after deforestation is represented through partial regrowth (LUrgr), calculated as a fraction of deforestation distributed over a regrowth timescale.

3. Decay Following Afforestation: Carbon sequestered through afforestation may not remain permanently due to vegetation turnover. The calculator includes an afforestation decay flux (LUafst_decay) that represents the gradual return of a fraction of sequestered carbon.

4. Flexible Input Methods: Supports two calculation methods:

   • Method 0: Uses net emissions (LUnet) as input (e.g., AFOLU emissions)

   • Method 1: Uses gross emissions (LUgrs) as input (e.g., harvest/deforestation data)

Land Use Flux Relationships:

The net land use emission is related to gross emission and regrowth by:

\[LUnet(t) = LUgrs(t) - LUrgr(t)\]

Gross emissions are further separated into deforestation and afforestation:

\[LUnet(t) = LUdfst(t) - LUrgr(t) - LUafst(t)\]

where:

• \(LUdfst(t) = \max(LUgrs(t), 0)\) (deforestation, positive)

• \(LUafst(t) = \max(-LUgrs(t), 0)\) (afforestation, positive)

Regrowth Dynamics:

For a deforestation event at time t, regrowth occurs as a constant flux over the regrowth period:

\[LUrgr(T) = \frac{\varphi \times LUdfst(t)}{\tau_{rgr}}, \quad \forall T \in [t+1, t+\tau_{rgr}]\]

where \(\varphi\) is the fraction that can regrow and \(\tau_{rgr}\) is the regrowth timescale.

Total regrowth at time t is the sum of contributions from all past deforestation events still undergoing recovery:

\[\begin{split}LUrgr(t) = \begin{cases} \sum_{T = \max(0, t - \tau_{rgr})}^{t-1} \frac{\varphi \times LUdfst(T)}{\tau_{rgr}} & \text{if } t \geq 1 \\ 0 & \text{if } t < 1 \end{cases}\end{split}\]

Afforestation Decay:

Similarly, for afforestation at time t, a fraction of sequestered carbon decays over time:

\[LUafst\_decay(T) = \frac{\phi \times LUafst(t)}{\tau_{afst\_decay}}, \quad \forall T \in [t+1, t+\tau_{afst\_decay}]\]

Total decay at time t sums all contributions from past afforestation events:

\[\begin{split}LUafst\_decay(t) = \begin{cases} \sum_{T = \max(0, t - \tau_{afst\_decay})}^{t-1} \frac{\phi \times LUafst(T)}{\tau_{afst\_decay}} & \text{if } t \geq 1 \\ 0 & \text{if } t < 1 \end{cases}\end{split}\]

where \(\phi\) is the afforestation decay fraction (default \(\phi = 1 - \varphi\)) and \(\tau_{afst\_decay}\) is the decay timescale (default: \(\tau_{afst\_decay} = \tau_{rgr}\)).

Calculation Algorithms:

The calculator uses two different algorithms depending on the input method:

Method 0: Net Emission as Input

When using net emissions as input (suitable for AFOLU emissions data), the algorithm iteratively calculates gross flux by adding regrowth, then propagates regrowth and decay effects forward in time:

1. Initialize first timestep with zero regrowth

2. For each timestep:

   1. Calculate gross flux: \(LUgrs(t) = LUnet(t) + LUrgr(t)\)

   2. If \(LUgrs(t) > 0\): Deforestation event

      • Set \(LUdfst(t) = LUgrs(t)\)

      • Add regrowth contribution to future timesteps: \(LUrgr(T) += \frac{\varphi \times LUdfst(t)}{\tau_{rgr}}\) for \(T \in [t+1, t+\tau_{rgr}]\)

   3. If \(LUgrs(t) < 0\): Afforestation event

      • Set \(LUafst(t) = -LUgrs(t)\)

      • Add decay contribution to future timesteps: \(LUafst\_decay(T) += \frac{\phi \times LUafst(t)}{\tau_{afst\_decay}}\) for \(T \in [t+1, t+\tau_{afst\_decay}]\)

3. Regrowth and decay contributions accumulate for all affected future timesteps

This method ensures that when net emissions are negative (indicating net sequestration beyond regrowth), the resulting negative gross flux is properly interpreted as afforestation rather than negative deforestation.

Method 1: Gross Emission as Input

When using gross emissions directly (suitable for harvest/deforestation data), the algorithm uses the provided gross flux and calculates regrowth and decay by propagating effects forward in time:

1. For each timestep with gross flux:

   1. If \(LUgrs(t) > 0\): Deforestation event

      • Set \(LUdfst(t) = LUgrs(t)\)

      • Add regrowth contribution to future timesteps: \(LUrgr(T) += \frac{\varphi \times LUdfst(t)}{\tau_{rgr}}\) for \(T \in [t+1, t+\tau_{rgr}]\)

   2. If \(LUgrs(t) < 0\): Afforestation event

      • Set \(LUafst(t) = -LUgrs(t)\)

      • Add decay contribution to future timesteps: \(LUafst\_decay(T) += \frac{\phi \times LUafst(t)}{\tau_{afst\_decay}}\) for \(T \in [t+1, t+\tau_{afst\_decay}]\)

2. Calculate net flux: \(LUnet(t) = LUgrs(t) - LUrgr(t)\)

This method is more straightforward when gross emissions are directly observed from data sources like forest harvest statistics.

Important Notes:

• \(LUafst\_decay\) is not part of the net land use flux equations. It provides a reference for afforestation-related decay independent of environmental changes, analogous to : math:LUrgr.

• \(LUrgr\) is explicitly part of NPP and is further modified by CO₂ fertilization and climate change.

• Decay of afforested carbon is implicitly included in vegetation turnover and is therefore already affected by environmental conditions.

• \(LUafst\_decay\) supports parameterization of NPP effects associated with afforestation and deforestation.

• Both algorithms use in-place array operations for efficiency when processing long time series.

• All arrays are modified in-place to minimize memory allocation.

• The algorithms properly handle edge cases including zero fluxes and boundary effects at the start and end of time series.

Typical Usage:

# Initialize calculator
lu_calc = LanduseCalculator(
    frc_rgr=Q(0.9, "1"),           # varphi = 0.9 (90% can regrow)
    tau_rgr=Q(100, "yr"),          # 100-year regrowth period
    method_cLU=Q(0, "1"),          # Use net carbon emissions
    method_nLU=Q(1, "1"),          # Use gross nitrogen emissions
)

# Calculate carbon fluxes
carbon_fluxes = lu_calc.calculate_CflxLU_series(
    CemsLUnet_s=net_emissions,
    CemsLUgrs_s=gross_emissions,
)

# Access results
deforestation = carbon_fluxes["CflxLUdfst"]
afforestation = carbon_fluxes["CflxLUafst"]
regrowth = carbon_fluxes["CflxLUrgr"]
cumulative_regrowth = carbon_fluxes["cumsum_CflxLUrgr"]

See also

cnit.physics.carbon_nitrogen_cycle.CarbonNitrogenCycleModel()

Main model using these land use fluxes

cnit.physics.effects.EffectLanduseCalculator()

Environmental effects from land use changes

class cnit.physics.landuse.LanduseCalculator

Bases: object

Calculator for land use change fluxes with explicit deforestation/afforestation separation.

This calculator processes land use change forcing data (net or gross emissions) and generates detailed flux time series including deforestation, afforestation, regrowth, and decay components. The separation of deforestation and afforestation is essential for scenarios involving carbon dioxide removal (CDR) and net-zero targets.

The calculator operates on annual time series and produces both instantaneous fluxes and cumulative quantities useful for tracking land use history and calculating environmental effects.

frc_rgr: Quantity

Fraction of deforestation that can regrow [dimensionless].

Represents the portion of deforested area that undergoes natural recovery. The remaining fraction (1 - frc_rgr) represents permanent land conversion with no natural regrowth.

tau_rgr: Quantity

Regrowth timescale [yr].

Time period over which regrowth occurs following deforestation. Regrowth is distributed as a constant flux over this period.

method_cLU: Quantity

Carbon land use flux calculation method [dimensionless].

Selects the input data type and calculation approach:

• 0: Use net emissions (CemsLUnet) as input, suitable for AFOLU emissions data where regrowth must be calculated from net emissions

• 1: Use gross emissions (CemsLUgrs) as input, suitable for harvest/deforestation data where gross emissions are directly observed

method_nLU: Quantity

Nitrogen land use flux calculation method [dimensionless].

Selects the input data type and calculation approach:

• 0: Use net emissions (NemsLUnet) as input (less commonly used)

• 1: Use gross emissions (NemsLUgrs) as input, suitable for gross deforestation data (typical for nitrogen)

calculate_CflxLU_series(CemsLUnet_s, CemsLUgrs_s)

Calculate carbon flux time series from land use change forcing.

This method processes land use change emissions and generates comprehensive flux time series including gross emissions, regrowth, deforestation, afforestation, and decay components. The method automatically separates deforestation (positive gross flux) from afforestation (negative gross flux).

Parameters:

• CemsLUnet_s (Quantity) – Net land use carbon emission time series [GtC/yr]. Represents the difference between gross emissions and regrowth. Used when method_cLU=0.

• CemsLUgrs_s (Quantity) – Gross land use carbon emission time series [GtC/yr]. Can be positive (deforestation) or negative (afforestation). Used when method_cLU=1.

Returns:

Dict[str, pint.Quantity] – Dictionary containing carbon flux time series:

Instantaneous Fluxes [GtC/yr]:

• CflxLUgrs: Gross land use flux (can be positive or negative)

• CflxLUrgr: Regrowth flux following deforestation (always non-negative)

• CflxLUdfst: Deforestation flux (always non-negative)

• CflxLUafst: Afforestation flux (always non-negative)

• CflxLUafst_decay: Decay flux following afforestation (always non-negative)

Cumulative Quantities [GtC]:

• cumsum_CflxLUrgr: Cumulative regrowth carbon

• cumsum_CflxLUdfst: Cumulative deforestation carbon

• cumsum_CflxLUafst: Cumulative afforestation carbon

• cumsum_CflxLUafst_decay: Cumulative decay from afforestation

Notes

Flux Relationships:

Net emissions relate to gross emissions and regrowth:

\[LUnet(t) = LUgrs(t) - LUrgr(t)\]

Gross emissions are separated into components:

\[LUnet(t) = LUdfst(t) - LUrgr(t) - LUafst(t)\]

where deforestation and afforestation are always positive:

\[ \begin{align}\begin{aligned}LUdfst(t) = \max(LUgrs(t), 0)\\LUafst(t) = \max(-LUgrs(t), 0)\end{aligned}\end{align} \]

Regrowth Calculation:

Regrowth following deforestation at time t:

\[LUrgr(T) = \frac{\varphi \times LUdfst(t)}{\tau_{rgr}}, \quad T \in [t+1, t+\tau_{rgr}]\]

Total regrowth is sum of all active regrowth contributions:

\[LUrgr(t) = \sum_{T=\max(0, t-\tau_{rgr})}^{t-1} \frac{\varphi \times LUdfst(T)}{\tau_{rgr}}\]

Afforestation Decay:

Decay following afforestation at time t:

\[LUafst\_decay(T) = \frac{\phi \times LUafst(t)}{\tau_{afst\_decay}}, \quad T \in [t+1, t+\tau_{afst\_decay}]\]

where by default \(\phi = 1 - \varphi\) and \(\tau_{afst\_decay} = \tau_{rgr}\).

Method Selection:

• Method 0: Calculates LUgrs from LUnet by adding calculated regrowth. Suitable when net emissions are the primary data source (e.g., AFOLU).

• Method 1: Uses LUgrs directly and calculates regrowth from it. Suitable when gross emissions are observed directly (e.g., harvest data).

Cumulative Quantities:

Cumulative values track the total historical land use changes and are used to calculate land use effects on ecosystem productivity (see EffectLanduseCalculator).

See also

calculate_NflxLU_series

Analogous nitrogen flux calculation

cnit.physics.effects.EffectLanduseCalculator()

Land use effects calculation using these fluxes

cnit.physics.carbon_cycle.CarbonCycleModel.run()

How these fluxes are used in carbon cycle

calculate_NflxLU_series(NemsLUnet_s, NemsLUgrs_s, NemsLUmin_s)

Calculate nitrogen flux time series from land use change forcing.

This method processes land use change emissions and generates comprehensive nitrogen flux time series. In addition to organic nitrogen fluxes (analogous to carbon), it includes direct mineral nitrogen emissions (e.g., NH₃, NOₓ, N₂O from agricultural land use change).

Parameters:

• NemsLUnet_s (Quantity) – Net land use nitrogen emission time series [GtN/yr]. Represents emissions from organic nitrogen pools. Used when method_nLU=0.

• NemsLUgrs_s (Quantity) – Gross land use nitrogen emission time series [GtN/yr]. Can be positive (deforestation) or negative (afforestation). Used when method_nLU=1.

• NemsLUmin_s (Quantity) – Direct land use nitrogen emission from mineral pool time series [GtN/yr]. Represents gaseous losses (NH₃, NOₓ, N₂O) during land conversion, primarily from agricultural activities.

Returns:

Dictionary containing nitrogen flux time series – Instantaneous Fluxes [GtN/yr]:

• NflxLUgrs: Gross land use flux from organic pools

• NflxLUrgr: Regrowth flux following deforestation

• NflxLUdfst: Deforestation flux (from organic pools)

• NflxLUafst: Afforestation flux (to organic pools)

• NflxLUafst_decay: Decay flux following afforestation

• NflxLUmin: Direct emission from mineral pool

Cumulative Quantities [GtN]:

• cumsum_NflxLUrgr: Cumulative regrowth nitrogen

• cumsum_NflxLUdfst: Cumulative deforestation nitrogen

• cumsum_NflxLUafst: Cumulative afforestation nitrogen

• cumsum_NflxLUafst_decay: Cumulative decay from afforestation

Notes

Nitrogen-Specific Considerations:

1. Organic vs Mineral Emissions:

   • LUgrs, LUrgr, LUdfst, LUafst: Affect organic nitrogen pools (plant, litter, soil)

   • LUmin: Directly affects mineral nitrogen pool, bypassing organic pools

2. Mineral Nitrogen Emissions: Direct mineral emissions (LUmin) typically include:

   • NH₃ volatilization from fertilizer application

   • NOₓ emissions from agricultural activities

   • N₂O emissions from soil disturbance

   These emissions do not go through organic matter turnover and are subtracted directly from the mineral nitrogen pool.

3. Stoichiometric Coupling: Organic nitrogen land use fluxes (LUgrs) are coupled to carbon fluxes through ecosystem C:N ratios, but mineral emissions (LUmin) are independent.

Typical Nitrogen Method:

Method 1 is typically used for nitrogen because gross deforestation data combined with C:N ratios provides more direct estimates of organic nitrogen losses than net emission calculations.

See also

calculate_CflxLU_series

Analogous carbon flux calculation

cnit.physics.nitrogen_cycle.NitrogenCycleModel.run()

How these fluxes are used in nitrogen cycle

Effects

Implements physical and biogeochemical effect calculations.

Effect Factor Calculators for the CNit Model.

This module defines the calculators responsible for computing the dimensionless “effect factors” (e.g., from temperature change, CO2, land use) that modify the rates of core carbon and nitrogen cycle processes.

The effect factors represent multiplicative modifiers applied to baseline process rates to account for environmental changes and feedbacks. Each calculator class handles a specific category of effects:

• EffectLanduseCalculator: Land use change effects (deforestation, afforestation, regrowth)

• EffectCO2Calculator: Atmospheric CO2 fertilization effects

• EffectTemperatureCalculator: Temperature-dependent process modifications

• EffectCarbonNitrogenCouplingCalculator: Carbon-nitrogen cycle feedback effects

All effect factors are dimensionless multipliers (typically near 1.0) that scale process rates up or down based on environmental conditions.

class cnit.physics.effects.EffectLanduseCalculator

Bases: object

Calculator for land use effects on carbon-nitrogen cycle processes.

This calculator computes land-use–induced modification factors for carbon and nitrogen cycle processes, accounting for deforestation, afforestation, and regrowth dynamics. It tracks cumulative land use changes and computes their effects on both Net Primary Production (NPP) and organic matter turnover rates.

The calculator implements two categories of land use effects:

1. Effects on NPP: Adjustments to primary production based on cumulative land use changes, blending instantaneous and equilibrium perspectives to capture both immediate impacts and long-term recovery dynamics

2. Effects on Turnovers: Short-term immediate effects on litter production, decomposition, and soil respiration based on current regrowth flux

Notes

Box Model Context and the Need for Land Use Effects

In a box model with constant turnover times, pool sizes naturally return to equilibrium after any perturbation. Without land use effects, the system would fully recover to its original state after deforestation or afforestation. The land use effects implemented here prevent this unrealistic full return by:

• Adjusting NPP to reflect permanent changes in productive land area

• Modifying turnover rates during recovery periods to capture transient dynamics

Dual Effect Framework

The calculator distinguishes between two complementary mechanisms:

• NPP adjustment (calculate_eff_LU_NPP): Modifies primary production to reflect net changes in productive land area, preventing full equilibrium return. This operates over longer timescales and controls the ultimate equilibrium state.

• Turnover adjustment (calculate_eff_LU_cLPLDSR, calculate_eff_LU_nLPLDSR): Capture immediate, short-term perturbations to organic matter cycling during recovery periods. These effects decay as regrowth completes, avoiding permanent equilibrium shifts.

Regrowth Flux as Proxy for Turnover Effects

The turnover effects use regrowth flux as a proxy for land use perturbation state because:

1. Regrowth reflects the recovering state of all past perturbations

2. It captures lagging effects that extend into the future

3. It embodies the principle “where there is regrowth, land use perturbation still takes effect”

4. It naturally decays to zero as recovery completes, ensuring no permanent change to equilibrium turnover rates

The regrowth flux provides a single, time-varying indicator of ongoing recovery that can be used as a proxy to parameterize how disturbance alters cycling rates during the transient recovery period.

sns_cLP2LUrgr: Quantity

Sensitivity of carbon litter production to regrowth flux [yr/GtC].

sns_cLD2LUrgr: Quantity

Sensitivity of carbon litter decomposition to regrowth flux [yr/GtC].

sns_cSR2LUrgr: Quantity

Sensitivity of carbon soil respiration to regrowth flux [yr/GtC]

sns_nLP2LUrgr: Quantity

Sensitivity of nitrogen litter production to regrowth flux [yr/GtC]

sns_nLD2LUrgr: Quantity

Sensitivity of nitrogen litter decomposition to regrowth flux [yr/GtC]

sns_nSR2LUrgr: Quantity

Sensitivity of nitrogen soil respiration to regrowth flux [yr/GtC]

calculate_eff_LU_NPP(cumsum_CflxLUrgr, cumsum_CflxLUdfst, cumsum_CflxLUafst, cumsum_CflxLUafst_decay, CplsPLS0, frc_rgr, frc_afst_decay)

Calculate the land use effect on Net Primary Production (NPP).

This method computes a multiplicative effect factor that accounts for both NPP reductions from deforestation and NPP enhancements from afforestation. The calculation addresses a fundamental limitation of box models: with constant turnover times, carbon pools always return to their equilibrium state following any perturbation. Land use effects on NPP prevent this unrealistic behavior by scaling NPP to reflect persistent changes in productive land area.

The method uses a refined parameterization that distinguishes between equilibrium (long-term potential) and instantaneous (current realized) effects, blending them to capture transient dynamics during ecosystem recovery and degradation.

Parameters:

• cumsum_CflxLUrgr (Quantity) – Cumulative regrowth carbon flux [GtC]. Total carbon accumulated through natural recovery following past deforestation events.

• cumsum_CflxLUdfst (Quantity) – Cumulative deforestation carbon flux [GtC]. Total carbon lost through all deforestation events.

• cumsum_CflxLUafst (Quantity) – Cumulative afforestation carbon flux [GtC]. Total carbon gained through afforestation and reforestation.

• cumsum_CflxLUafst_decay (Quantity) – Cumulative afforestation decay carbon flux [GtC]. Total carbon lost from afforested areas due to vegetation turnover.

• CplsPLS0 (Quantity) – Initial equilibrium total terrestrial carbon pool size (Plant + Litter + Soil) [GtC]. Represents the baseline productive land carbon before land use changes.

• frc_rgr (Quantity) – Regrowth fraction (varphi) [dimensionless]. Fraction of deforested area that can undergo natural recovery (typical values 0.8-0.95).

• frc_afst_decay (Quantity) – Afforestation decay fraction (phi) [dimensionless]. Fraction of afforested carbon that decays due to turnover (phi = 1 - varphi).

Returns:

Land use effect factor for NPP [dimensionless]. Multiplicative factor applied – to baseline NPP:

• Values < 1: Net NPP reduction (deforestation dominates)

• Values > 1: Net NPP enhancement (afforestation dominates)

• Value = 1: No net land use effect

Notes

The Box Model Equilibrium Return

In a box model framework with constant turnover times, carbon pools always return to their initial equilibrium state following any perturbation, whether deforestation or afforestation. This occurs because:

\[\frac{dC}{dt} = NPP - \frac{C}{\tau}\]

At equilibrium (dC/dt = 0): \(C_{eq} = NPP \times \tau\)

Without land use effects on NPP, any perturbation to C eventually returns to the original equilibrium regardless of land use history. This is unrealistic because deforestation should reduce productive land area (lower equilibrium), while afforestation should increase it.

Land use effects on NPP solve this by adjusting the equilibrium target to reflect net changes in productive land area, ensuring that long-term pool sizes reflect the persistent impact of land use change.

Deforestation Effect: Balancing Two Perspectives

Two complementary approaches characterize the deforestation effect:

1. Equilibrium Perspective (\(\epsilon_{LUdfst}^{eqm}\))

Represents the ultimate long-term NPP reduction assuming all potential regrowth is complete:

\[\epsilon_{LUdfst}^{eqm} = \frac{(1-\varphi) \sum_{0}^{t} LUdfst}{C_{Land0}}\]

where \(\varphi\) is the regrowth fraction (frc_rgr) and \(C_{Land0}\) is the initial equilibrium land carbon (CplsPLS0).

Physical interpretation: Only the non-regrowing fraction : math:(1-varphi) represents permanent loss of productive land. If \(\varphi = 0. 9\), then 90% of deforested area eventually recovers, so only 10% contributes to long-term NPP reduction.

Limitation: This assumes NPP immediately adjusts to the new equilibrium level after deforestation, potentially underestimating the effect during the regrowth period. The new equilibrium corresponds to the end of the regrowth period (\(\tau_{rgr}\)), so at time t during active regrowth, \(\epsilon_{LUdfst}^{eqm}\) underestimates the realized impact because it doesn’t account for lagged regrowth.

2. Instantaneous Perspective (\(\epsilon_{LUdfst}^{inst}\))

Represents the realized net impact at the current time:

\[\epsilon_{LUdfst}^{inst} = \frac{\sum_{0}^{t}(LUdfst - LUrgr)}{C_{Land0}}\]

Physical interpretation: The actual net carbon loss to date. This captures the current imbalance between cumulative deforestation and cumulative regrowth.

Temporal behavior:

• Early in regrowth period: \(\epsilon_{LUdfst}^{inst}\) is larger than \(\epsilon_{LUdfst}^{eqm}\) because regrowth hasn’t caught up

• Long-term (after \(\tau_{rgr}\)): Both converge to the same value

Limitations of Using Either Perspective Alone

Why \(\epsilon_{LUdfst}^{inst}\) alone overestimates the effect:

1. Simplified regrowth dynamics: The model assumes constant regrowth flux over \(\tau_{rgr}\), which doesn’t capture rapid initial regrowth in real ecosystems. This underestimates cumulative \(LUrgr\), exaggerating the net loss \((LUdfst - LUrgr)\).

2. Missing high NPP of young vegetation: Young regrowing forests have high NPP potential relative to their carbon stock, which isn’t captured in the simple cumulative carbon balance. The instantaneous effect treats all carbon equally, missing the fact that a small amount of regrowth carbon represents substantial NPP recovery.

Why \(\epsilon_{LUdfst}^{eqm}\) alone underestimates the effect:

• Assumes instantaneous adjustment to the post-regrowth equilibrium, ignoring the actual lag in recovery. During active regrowth, the realized NPP reduction is larger than the long-term equilibrium would suggest.

Combined Approach: Weighted Blending

The effective deforestation effect blends both perspectives with an adaptive weighting scheme:

\[\epsilon_{LUdfst} = \frac{1}{2}\left[(1+0.8\varphi) \times \epsilon_{LUdfst}^{eqm} + (1-0.8\varphi) \times \epsilon_{LUdfst}^{inst}\right]\]

Rationale for the 0.8φ tuning factor:

The factor : math:0.8varphi prevents problematic behavior at extreme regrowth fractions:

• Problem at high φ (e.g., \(\varphi = 1\)):

  • \(\epsilon_{LUdfst}^{eqm} = 0\) (all area recovers, no long-term effect)

  • \(\epsilon_{LUdfst}^{inst}\) remains large during regrowth

  • Simple average would give \(\epsilon_{LUdfst} = 0.5 \times \epsilon_{LUdfst}^{inst}\), overemphasizing the exaggerated instantaneous response

• Solution with 0.8φ weighting:

  • At \(\varphi = 1\): weights are (0.9, 0.1) rather than (0.5, 0.5)

  • Minimum 10% contribution from instantaneous effect: \((1 - 0.8 \times 1) / 2 = 0.1\)

  • Maximum 90% from equilibrium: \((1 + 0.8 \times 1) / 2 = 0.9\)

  • This preserves physically meaningful balance across the full regrowth range (0 ≤ φ ≤ 1)

• Behavior across regrowth fractions:

  • Low φ (more permanent deforestation): Both perspectives matter similarly

  • High φ (more regrowth): Equilibrium perspective dominates, appropriately reducing reliance on the exaggerated instantaneous effect

Afforestation Effect: Similar Blending Without Tuning

The equilibrium and instantaneous afforestation effects mirror the deforestation formulation:

\[\epsilon_{LUafst}^{eqm} = \frac{(1-\phi) \sum_{0}^{t} LUafst}{C_{Land,0}}\]

\[\epsilon_{LUafst}^{inst} = \frac{\sum_{0}^{t}(LUafst - LUafst\_decay)}{C_{Land,0}}\]

where \(\phi\) is the afforestation decay fraction (frc_afst_decay).

The effective afforestation effect uses a simple unweighted average:

\[\epsilon_{LUafst} = \frac{1}{2}\left[\epsilon_{LUafst}^{eqm} + \epsilon_{LUafst}^{inst}\right]\]

Why no φ adjustment for afforestation:

The decay of carbon in mature forests is a gradual process, unlike the potentially rapid initial regrowth after deforestation. The instantaneous effect for afforestation doesn’t suffer from the same exaggeration issues:

• Afforestation decay is slow and approximately linear (constant flux assumption is more realistic)

• There’s no equivalent to the “high NPP of young vegetation” bias working in the opposite direction

• Therefore, equilibrium and instantaneous perspectives are equally valid and don’t require adaptive weighting

Total Land Use Effect on NPP

The final multiplicative effect combines deforestation (NPP reduction) and afforestation (NPP amplification):

\[\epsilon_{LU(NPP)} = 1 - \epsilon_{LUdfst} + \epsilon_{LUafst}\]

Physical interpretation:

• \(-\epsilon_{LUdfst}\): Reduces NPP proportional to net deforestation impact

• \(+\epsilon_{LUafst}\): Increases NPP proportional to net afforestation impact

• Baseline of 1 represents no land use change

Example scenarios:

1. Heavy deforestation, no afforestation: \(\epsilon_{LUdfst} = 0.2\), \(\epsilon_{LUafst} = 0\) → \(\epsilon_{LU(NPP)} = 0.8\) (20% NPP reduction)

2. Heavy afforestation, no deforestation: \(\epsilon_{LUdfst} = 0\), \(\epsilon_{LUafst} = 0.15\) → \(\epsilon_{LU(NPP)} = 1.15\) (15% NPP increase)

3. Mixed: \(\epsilon_{LUdfst} = 0.1\), \(\epsilon_{LUafst} = 0.12\) → \(\epsilon_{LU(NPP)} = 1.02\) (2% net NPP increase)

See also

cnit.physics.landuse.LanduseCalculator.calculate_CflxLU_series()

Calculates cumulative land use fluxes

cnit.physics.carbon_cycle.CarbonNPPLPRCalculator.calculate()

Uses this effect to modify NPP

calculate_eff_LU_cLPLDSR(CflxLUrgr)

Calculate land use effect factors on carbon cycle turnover processes.

Computes exponential response factors for carbon litter production (cLP), litter decomposition (cLD), and soil respiration (cSR). These factors represent immediate, short-term effects of ongoing land use perturbations on organic matter cycling rates during recovery periods.

Parameters:

CflxLUrgr (pint.Quantity) – Current regrowth carbon flux [GtC/yr]. Serves as a proxy for the state of land use perturbation and ongoing recovery.

Returns:

• eff_LU_cLP (pint.Quantity) – Land use effect on carbon litter production [dimensionless].

• eff_LU_cLD (pint.Quantity) – Land use effect on carbon litter decomposition [dimensionless].

• eff_LU_cSR (pint.Quantity) – Land use effect on carbon soil respiration [dimensionless].

Notes

Why Turnover Effects Are Necessary

The NPP adjustment (calculate_eff_LU_NPP) prevents full equilibrium return in the long term, but it primarily controls the ultimate equilibrium state. These direct turnover effects are needed to capture the shorter-term immediate effects of land use perturbation during active recovery periods.

Without turnover effects, transient dynamics during recovery would be missing from the model, even though the long-term equilibrium is correctly adjusted.

Mathematical Formulation

Each effect factor follows an exponential response function:

\[\epsilon_{LU(i)} = \exp(s_{i2LUrgr} \times LUrgr)\]

where \(s_{i2LUrgr}\) is the sensitivity parameter for process \(i\) (litter production, litter decomposition, or soil respiration) and \(LUrgr\) is the current regrowth flux.

Why Regrowth Flux Is a Good Proxy

Using regrowth flux to parameterize turnover effects is appropriate because:

1. Reflects recovering state: Regrowth magnitude indicates how much past perturbation is still influencing the system

2. Captures lagging effects: Active regrowth means perturbation effects extend into the future (ongoing recovery)

3. Embodies “where regrowth occurs, perturbation persists”: The spatial and temporal extent of regrowth maps to perturbation influence

4. Natural decay: As regrowth completes, \(LUrgr \to 0\) and effects vanish, preventing permanent equilibrium shifts

5. Single time-varying indicator: Provides a convenient scalar measure of system-wide recovery status

Interpretation of Sensitivities

• Positive \(s_{i2LUrgr}\): Process rate increases with regrowth (e.g., high litter production in rapidly accumulating young forests)

• Negative \(s_{i2LUrgr}\): Process rate decreases with regrowth (e.g., reduced soil respiration as system recovers from disturbance pulse)

• Zero \(s_{i2LUrgr}\): Process rate unaffected by land use state

No Long-Term Equilibrium Change

Because regrowth is not forever (recovery eventually completes), these turnover effects naturally decay to 1.0 as \(LUrgr \to 0\). This means:

• Short-term perturbations to cycling rates are captured

• Long-term equilibrium turnover rates remain unchanged

• Only the NPP effect permanently alters the equilibrium state

calculate_eff_LU_nLPLDSR(CflxLUrgr)

Calculate land use effect factors on nitrogen turnover processes.

Computes exponential response factors for nitrogen litter production (nLP), litter decomposition (nLD), and soil respiration (nSR). These factors modify nitrogen turnover process rates based on the current regrowth flux.

The effect factors follow exponential response functions analogous to the carbon cycle effects (see calculate_eff_LU_cLPLDSR()).

Parameters:

CflxLUrgr (pint.Quantity) – Current regrowth carbon flux [GtC/yr]. Used as a proxy for ecosystem recovery state affecting nitrogen cycling.

Returns:

• eff_LU_nLP (pint.Quantity) – Land use effect on nitrogen litter production [dimensionless].

• eff_LU_nLD (pint.Quantity) – Land use effect on nitrogen litter decomposition [dimensionless].

• eff_LU_nSR (pint.Quantity) – Land use effect on nitrogen soil respiration (mineralization) [dimensionless].

Notes

While parameterized using carbon regrowth flux, these factors affect nitrogen cycling rates. This reflects the coupled nature of C-N cycling in ecosystems, where recovery of carbon stocks is accompanied by changes in nitrogen turnover.

Typical patterns include enhanced nitrogen mineralization during early regrowth (positive sensitivity for nSR) as accumulated organic matter decomposes.

class cnit.physics.effects.EffectCO2Calculator

Bases: object

Calculator of CO2 fertilization effects on Net Primary Production (NPP).

Implements multiple formulations of the CO2 fertilization effect, including logarithmic, rectangular hyperbolic (Gifford), and sigmoid forms. The calculator can blend between these formulations based on the method_CO2_NPP parameter to represent different assumptions about CO2 response saturation behavior.

The CO2 effect represents how elevated atmospheric CO2 concentrations enhance photosynthetic rates and water use efficiency in vegetation, leading to increased NPP. Different formulations capture different assumptions about saturation behavior at high CO2 levels and the shape of the CO2 response curve.

Notes

Physical Basis of CO2 Fertilization

Elevated CO2 enhances plant productivity through two main mechanisms:

1. Direct photosynthetic enhancement: Higher CO2 increases the rate of carbon fixation in the Calvin cycle (substrate availability)

2. Improved water use efficiency: Plants can partially close stomata while maintaining CO2 uptake, reducing water loss

The strength of CO2 fertilization varies by:

• Plant functional type (C3 vs. C4 photosynthesis)

• Nutrient availability (progressive nitrogen limitation)

• Water availability

• Temperature regime

Choice of Formulation

Different formulations represent different hypotheses about CO2 response:

• Logarithmic: No saturation, effect continues growing indefinitely. Simple and commonly used, but may overestimate effects at very high CO2.

• Rectangular hyperbolic: Moderate saturation following Michaelis-Menten kinetics. Based on photosynthesis theory (Gifford 1980).

• Sigmoid: Strong saturation with explicit maximum effect. Most conservative at high CO2, captures potential acclimation or nutrient limitation feedbacks.

Calibration Strategy

The rectangular hyperbolic sensitivity \(s^{rect}_{CO_2}\) is automatically derived to match the logarithmic form at two reference concentrations (340 and 680 ppm), ensuring smooth transitions when blending formulations.

sns_CO2_log: Quantity

Sensitivity of NPP to atmospheric CO₂ concentration changes (logarithmic form) [dimensionless].

sns_CO2_sig: Quantity

Sensitivity of NPP to atmospheric CO₂ concentration changes (sigmoid form) [ppm].

eff_CO2_sig_max: Quantity

Maximum CO2 effect factor for the sigmoid form [dimensionless].

CO2ref: Quantity

Atmospheric CO₂ concentration at pre-industrial level [ppm].

CO2b: Quantity

Atmospheric CO₂ concentration when NPP = 0 (for rectangular hyperbolic effect, default 31 ppm) [ppm].

method_CO2_NPP: Quantity

CO₂ effect factor calculation method (value from 0 to 2), otherwise eff_CO2 is set equal to 1.

calculate_eff_CO2_NPP(CO2)

Calculate the CO2 fertilization effect factor for Net Primary Production (NPP).

Computes a multiplicative factor representing how elevated CO2 enhances NPP relative to the reference concentration. The calculation can use pure or blended formulations depending on the method_CO2_NPP parameter.

Parameters:

CO2 (pint.Quantity) – Current atmospheric CO2 concentration [ppm].

Returns:

pint.Quantity – CO2 effect factor on NPP [dimensionless].

• Values > 1: CO2 fertilization (enhanced NPP)

• Values = 1: No effect (CO2 at reference level)

• Values < 1: Suppression (rare, only at very low CO2 below reference)

Notes

Three CO2 Effect Formulations

1. Logarithmic Form (simple, commonly used):

   \[\epsilon^{log}_{CO_2} = 1 + s^{log}_{CO_2} \times \ln(CO_2/CO_{2,ref})\]

   where \(CO_2\) is the current atmospheric CO2 concentration and \(CO_{2,ref}\) is the reference concentration (typically pre-industrial).

   Properties:

   • Effect factor = 1 at \(CO_2 = CO_{2,ref}\)

   • Logarithmic relationship implies diminishing but never-ceasing returns

   • No explicit saturation at high CO2

   • Commonly used in Earth system models (e.g., OSCAR, simple IAMs)

   Interpretation of \(s^{log}_{CO_2}\) (β parameter):

   • \(s^{log}_{CO_2} = 0.4\): Doubling CO2 increases NPP by ~28% (\(1 + 0.4 \times \ln(2) \approx 1.277\))

   • \(s^{log}_{CO_2} = 0.6\): Doubling CO2 increases NPP by ~42%

   • Literature estimates typically range from 0.2 to 0.6

2. Rectangular Hyperbolic Form (Gifford formulation, includes saturation):

   \[\epsilon^{rect}_{CO_2} = \frac{1/(CO_{2,ref}-CO_{2,b}) + s^{rect}_{CO_2}}{ 1/(CO_2-CO_{2,b}) + s^{rect}_{CO_2}}\]

   where \(CO_{2,b}\) is the CO2 compensation point (NPP = 0, typically ~31 ppm).

   Derivation of \(s^{rect}_{CO_2}\):

   To ensure smooth blending with the logarithmic form, \(s^{rect}_{CO_2}\) is derived by matching the effect ratio at two reference concentrations (340 and 680 ppm):

   \[r = \frac{\epsilon^{log}_{CO_2}(680)}{\epsilon^{log}_{CO_2}(340)} = \frac{\epsilon^{rect}_{CO_2}(680)}{\epsilon^{rect}_{CO_2}(340)}\]
   \[r = \frac{1 + s^{log}_{CO_2} \times \ln(680/CO_{2,ref})}{ 1 + s^{log}_{CO_2} \times \ln(340/CO_{2,ref})}\]
   \[s^{rect}_{CO_2} = \frac{(680-CO_{2,b}) - r(340-CO_{2,b})}{ (r-1)(680-CO_{2,b})(340-CO_{2,b})}\]

   Properties:

   • Based on Michaelis-Menten enzyme kinetics

   • Exhibits saturation at high CO2 levels

   • Approaches asymptote as \(CO_2 \to \infty\)

   • More physiologically grounded than logarithmic form

   • Used in some process-based terrestrial biosphere models

3. Sigmoid Form (flexible, allows specified maximum effect):

   \[\epsilon^{sig}_{CO_2} = \frac{\epsilon^{sig}_{CO_2,max}}{ 1 + (\epsilon^{sig}_{CO_2,max}-1) \times \exp(-s^{sig}_{CO_2}(CO_2/CO_{2,ref} - 1))}\]

   Properties:

   • Transitions smoothly from 1 at \(CO_{2,ref}\) to \(\epsilon^{sig}_{CO_2,max}\) at high CO2

   • Steepness controlled by \(s^{sig}_{CO_2}\)

   • Allows explicit specification of maximum possible enhancement

   • Can represent nutrient limitation or acclimation feedbacks

   • Most conservative at very high CO2 concentrations

Blending Between Formulations

The final effect factor is a linear blend controlled by method_CO2_NPP:

\[\begin{split}\epsilon_{CO_2} = \begin{cases} (1-m) \times \epsilon^{log}_{CO_2} + m \times \epsilon^{rect}_{CO_2} & 0 \le m \le 1 \\ (2-m) \times \epsilon^{rect}_{CO_2} + (m-1) \times \epsilon^{sig}_{CO_2} & 1 < m \le 2 \\ 1 & \text{otherwise} \end{cases}\end{split}\]

where \(m = \mathrm{method\_CO2\_NPP}\).

Blending rationale:

• Allows exploration of uncertainty in CO2 response shape

• Smooth transitions between formulations (no discontinuities)

• Can be calibrated against observations or expert judgment

• Value outside [0,2] disables CO2 fertilization entirely

class cnit.physics.effects.EffectTemperatureCalculator

Bases: object

Calculator of temperature effects for ecological processes.

Computes exponential and sigmoid temperature response factors for carbon and nitrogen cycle processes. Temperature effects generally accelerate biological rates (photosynthesis, respiration, decomposition, nitrogen transformations) following temperature-dependent kinetics described by Arrhenius-type or Q10 relationships.

All temperature effects are computed relative to a reference state (typically pre-industrial), using temperature change (dT) rather than absolute temperature. This approach simplifies parameter interpretation and maintains consistency with transient climate change simulations in Earth system models.

Notes

Exponential Temperature Response (Q10 Framework)

Most temperature effects use exponential formulations:

\[\epsilon_T = \exp(s_T \times \Delta T)\]

where \(s_T\) is the sensitivity parameter and \(\Delta T\) is temperature change from reference. This corresponds to the Q10 relationship:

\[Q_{10} = \exp(10 \times s_T)\]

Common Q10 values and corresponding sensitivities:

• Q10 = 1.5 → s = 0.0405 K⁻¹ (weak temperature dependence)

• Q10 = 2.0 → s = 0.0693 K⁻¹ (moderate, commonly used for soil respiration)

• Q10 = 2.5 → s = 0.0916 K⁻¹ (strong temperature dependence)

• Q10 = 3.0 → s = 0.1099 K⁻¹ (very strong, e.g., denitrification)

NPP Temperature Response: Monotonic vs. Peaked

The NPP temperature effect can represent two different hypotheses:

1. Monotonic increase (method_dT_NPP = 0): Simple exponential response, suitable for temperature-limited ecosystems (e.g., boreal, arctic)

2. Peaked response (method_dT_NPP = 1): Sigmoid with asymptote at 2×, representing thermal optima with reduced productivity at high temperatures (heat stress, drought coupling). Suitable for temperate to tropical systems.

sns_NPP2dT: Quantity

Sensitivity of NPP to temperature changes, exponential form [K^-1]

sns_NPP2dT_sig: Quantity

Sensitivity of NPP to temperature changes, sigmoid form [K^-1]

method_dT_NPP: Quantity

Blending parameter between exponential (0) and sigmoid (1) NPP responses [dimensionless, 0-1] [dimensionless]

sns_LPR2dT: Quantity

Sensitivity of litter production respiration to temperature changes [K^-1]

sns_cLP2dT: Quantity

Sensitivity of carbon litter production to temperature changes [K^-1]

sns_cLD2dT: Quantity

Sensitivity of carbon litter decomposition to temperature changes [K^-1]

sns_cSR2dT: Quantity

Sensitivity of carbon soil respiration (soil organic matter decomposition) to temperature changes [K^-1]

sns_PU2dT: Quantity

Sensitivity of nitrogen plant uptake to temperature changes [K^-1]

sns_BNF2dT: Quantity

Sensitivity of biological nitrogen fixation to temperature changes [K^-1]

sns_nLP2dT: Quantity

Sensitivity of nitrogen litter production to temperature changes [K^-1]

sns_nLD2dT: Quantity

Sensitivity of nitrogen litter decomposition to temperature changes [K^-1]

sns_nSR2dT: Quantity

Sensitivity of nitrogen soil respiration (soil organic matter decomposition) to temperature changes [K^-1]

sns_nLSgas2dT: Quantity

Sensitivity of mineral nitrogen gaseous loss to temperature changes [K ^-1]

calculate_eff_dT_NPPLPR(dT)

Calculate temperature effects for NPP and litter production respiration (LPR).

Computes multiplicative effect factors representing how temperature changes modify NPP and autotrophic respiration. The NPP effect uses a blended exponential-sigmoid formulation to optionally capture both temperature limitation and high-temperature stress.

Parameters:

dT (Quantity) – Change in temperature from pre-industrial [K]

Returns:

• eff_dT_NPP (pint.Quantity) – Temperature effect on Net Primary Production [dimensionless]. Values > 1 indicate warming enhances NPP; values < 1 indicate suppression.

• eff_dT_LPR (pint.Quantity) – Temperature effect on litter production respiration [dimensionless]. Typically > 1 for warming as autotrophic respiration increases.

Notes

NPP Temperature Effect (Blended Exponential-Sigmoid)

\[\epsilon_{T(NPP)} = (1 - m) \times e^{s_{NPP2dT}^{exp} \times \Delta T} + m \times \frac{2}{1 + e^{-s_{NPP2dT}^{sig} \times \Delta T}}\]

where:

• \(m = \mathrm{method\_dT\_NPP}\) (blending parameter, 0-1)

• \(s_{NPP2dT}^{exp} = \mathrm{sns\_NPP2dT}\) (exponential sensitivity)

• \(s_{NPP2dT}^{sig} = \mathrm{sns\_NPP2dT\_sig}\) (sigmoid sensitivity)

• \(\Delta T = dT\) (temperature change)

Interpretation by \(m\) value:

• \(m = 0\): Pure exponential, monotonic increase with temperature. Suitable for temperature-limited ecosystems (boreal, arctic) where warming consistently enhances productivity.

• \(m = 1\): Pure sigmoid, approaches asymptote of 2× at high temperatures. Represents systems with thermal optima where extreme warming causes heat stress, drought, or other limitations. Suitable for temperate to tropical ecosystems.

• \(0 < m < 1\): Weighted blend, allows intermediate behavior.

LPR Temperature Effect (Simple Exponential)

\[\epsilon_{T(LPR)} = e^{s_{LPR2dT} \times \Delta T}\]

where \(s_{LPR2dT} = \mathrm{sns\_LPR2dT}\).

Autotrophic respiration (growth and maintenance respiration associated with litter production) typically follows simple exponential temperature dependence with Q10 ~ 2.0-2.5 (\(s_{LPR}\) ~ 0.07-0.09 K⁻¹).

calculate_eff_dT_cLPLDSR(dT)

Calculate temperature effects for carbon cycle turnover processes.

Computes exponential temperature response factors for carbon litter production (LP), litter decomposition (LD), and soil respiration (SR). These factors modify organic matter turnover rates in response to temperature changes.

Parameters:

dT (pint.Quantity) – Change in temperature from reference [K].

Returns:

• eff_dT_cLP (pint.Quantity) – Temperature effect on carbon litter production [dimensionless].

• eff_dT_cLD (pint.Quantity) – Temperature effect on carbon litter decomposition [dimensionless].

• eff_dT_cSR (pint.Quantity) – Temperature effect on carbon soil respiration (SOM decomposition) [dimensionless].

Notes

Mathematical Formulation

Each effect follows a simple exponential (Q10-type) response:

\[\epsilon_{T(i)} = \exp(s_{i2dT} \times \Delta T)\]

Soil Respiration: Critical for Climate-Carbon Feedback

The soil respiration temperature sensitivity (sns_cSR2dT) is a key parameter determining climate-carbon feedback strength:

\[\epsilon_{T(cSR)} = \exp(s_{cSR2dT} \times \Delta T)\]

Typical Q10 values for soil respiration:

• Conservative: Q10 = 1.5 (\(s_{cSR2dT}\) = 0.041 K⁻¹)

• Moderate: Q10 = 2.0 (\(s_{cSR2dT}\) = 0.069 K⁻¹)

• High: Q10 = 2.5 (\(s_{cSR2dT}\) = 0.092 K⁻¹)

• Very high: Q10 = 3.0 (\(s_{cSR2dT}\) = 0.110 K⁻¹)

Feedback loop: Warming → Enhanced soil respiration → CO2 release → More warming. Magnitude depends critically on Q10.

Example: For 3 K warming:

• Q10 = 1.5 → 16% increase in soil respiration

• Q10 = 2.0 → 23% increase

• Q10 = 3.0 → 37% increase

This difference propagates to multi-decadal cumulative carbon losses.

Litter Production and Decomposition

• Litter production (sns_cLP2dT): May be positive (stress-induced turnover) or near zero (controlled by other factors like NPP and allocation). Often less temperature-sensitive than decomposition.

• Litter decomposition (sns_cLD2dT): Typically positive with Q10 ~ 2.0-2.5, similar to soil respiration. Microbial decomposer activity accelerates with warmth.

Limitations and Caveats

1. Moisture coupling: Temperature effects on decomposition are often modulated by moisture availability (not explicitly represented). In dry conditions, warming may reduce decomposition.

2. Substrate quality: Temperature sensitivity may vary with litter and soil organic matter chemistry (labile vs. recalcitrant).

3. Acclimation: Long-term studies suggest microbial communities may acclimate, reducing effective Q10 over time. Fixed Q10 may overestimate long-term feedback.

4. Depth dependence: Deep soil carbon may have different temperature sensitivity than surface layers.

calculate_eff_dT_PUBNF(dT)

Calculate temperature effects for nitrogen acquisition processes.

Computes exponential temperature response factors for plant nitrogen uptake (PU) and biological nitrogen fixation (BNF). These factors modify nitrogen acquisition rates affecting ecosystem nitrogen supply.

Parameters:

dT (pint.Quantity) – Change in temperature from reference [K].

Returns:

• eff_dT_PU (pint.Quantity) – Temperature effect on plant nitrogen uptake [dimensionless].

• eff_dT_BNF (pint.Quantity) – Temperature effect on biological nitrogen fixation [dimensionless].

Notes

Mathematical Formulation

Both effects use simple exponential responses:

\[\epsilon_{T(PU)} = \exp(s_{PU2dT} \times \Delta T)\]

\[\epsilon_{T(BNF)} = \exp(s_{BNF2dT} \times \Delta T)\]

Plant Nitrogen Uptake

Temperature affects N uptake through multiple mechanisms:

1. Root metabolic activity: Active transport across membranes is temperature-dependent (enzyme kinetics)

2. Root growth: Warmer soils promote root proliferation

3. Soil solution mobility: Diffusion and mass flow increase with temperature

4. Mycorrhizal activity: Symbiotic fungi are temperature-sensitive

Biological Nitrogen Fixation

Symbiotic N fixation (e.g., legumes + rhizobia, actinorhizal plants) is strongly temperature-dependent:

1. Nitrogenase enzyme kinetics: Optimal temperature typically 20-30°C

2. Bacterial growth rates: Exponential temperature dependence

3. Plant carbon allocation: Warmer temperatures may increase carbon supply to symbionts

4. Nodule formation: Temperature affects infection and nodulation

Interaction with Carbon-Nitrogen Coupling

These temperature effects interact with C-N coupling effects:

• Enhanced N uptake/fixation (temperature) may partially alleviate N limitation of CO2-fertilized NPP

• However, if warming also increases NPP (temperature effect), N demand increases, potentially intensifying N limitation

• Net effect on N limitation depends on the balance between enhanced supply (uptake, fixation, mineralization) and enhanced demand (NPP)

calculate_eff_dT_nLPLDSRLS(dT)

Calculate temperature effects for nitrogen cycle turnover processes.

Computes exponential temperature response factors for nitrogen litter production (LP), litter decomposition (LD), soil respiration/mineralization (SR), and gaseous losses (LSgas). These factors modify nitrogen cycling rates affecting ecosystem nitrogen availability.

Parameters:

dT (pint.Quantity) – Change in temperature from reference [K].

Returns:

• eff_dT_nLP (pint.Quantity) – Temperature effect on nitrogen litter production [dimensionless].

• eff_dT_nLD (pint.Quantity) – Temperature effect on nitrogen litter decomposition [dimensionless].

• eff_dT_nSR (pint.Quantity) – Temperature effect on nitrogen mineralization (soil respiration) [dimensionless].

• eff_dT_nLSgas (pint.Quantity) – Temperature effect on gaseous nitrogen losses (denitrification, volatilization) [dimensionless].

Notes

Mathematical Formulation

All effects use exponential responses:

\[\epsilon_{T(i)} = \exp(s_{i2dT} \times \Delta T)\]

Nitrogen Mineralization (nSR): Supply of Plant-Available N

Nitrogen mineralization (conversion of organic N to mineral NH4+ and NO3-) is temperature-sensitive, typically with Q10 ~ 2.0-2.5:

\[\epsilon_{T(nSR)} = \exp(s_{nSR2dT} \times \Delta T)\]

This is a critical process controlling N availability:

• Warming → Enhanced mineralization → More plant-available N

• May alleviate progressive nitrogen limitation under CO2 fertilization

• Often mirrors carbon soil respiration temperature sensitivity

Typical sensitivities: \(s_{nSR2dT}\) ~ 0.05-0.09 K⁻¹ (Q10 ~ 1.6-2.5).

Gaseous Nitrogen Losses (nLSgas): N Retention vs. Loss

Gaseous N losses include:

1. Denitrification (NO3- → N2O → N2): Anaerobic bacterial process, very temperature-sensitive (Q10 often > 2.5)

2. Volatilization (NH3 loss): Less temperature-sensitive but increases with warmth

3. Nitrification-denitrification (coupled processes): Both steps temperature-dependent

Denitrification is particularly important:

• Occurs in waterlogged/anoxic microsites

• Strong temperature dependence: \(s_{nLSgas2dT}\) ~ 0.08-0.12 K⁻¹ (Q10 ~ 2.2-3.3)

• Produces N2O (potent greenhouse gas) as intermediate

Trade-off: Warming increases both N mineralization (supply) and gaseous losses. Net effect on N availability depends on which process is more sensitive and on soil moisture/oxygen status.

class cnit.physics.effects.EffectCarbonNitrogenCouplingCalculator

Bases: object

Calculator of carbon-nitrogen coupling effects for ecological processes.

Computes bidirectional feedback effects between carbon and nitrogen cycles, representing the fundamental co-limitation of ecosystems by carbon (energy) and nitrogen (nutrients). This calculator implements two complementary types of coupling:

1. Nitrogen limitation of carbon processes (N → C effects): How nitrogen availability constrains NPP and carbon turnover

2. Carbon enhancement of nitrogen processes (C → N effects): How carbon availability (via NPP) enhances plant uptake and fixation

These coupling effects are critical for predicting ecosystem responses to CO2 fertilization and climate change, particularly the phenomenon of “progressive nitrogen limitation” where CO2-stimulated growth is increasingly constrained by nitrogen availability.

Switch Parameter

The switch_N parameter toggles nitrogen limitation effects:

• switch_N = 0: No N limitation (effects = 1.0)

• switch_N ≠ 0: N limitation active

sns_NPP2PUdef: Quantity

Sensitivity of net primary production to nitrogen plant uptake deficit [GtN/yr]

sns_cLP2PUdef: Quantity

Sensitivity of litter production (carbon) to nitrogen plant uptake deficit [GtN/yr]

sns_cLD2PUdef: Quantity

Sensitivity of litter decomposition (carbon) to nitrogen plant uptake deficit [GtN/yr]

sns_cSR2PUdef: Quantity

Sensitivity of soil respiration (carbon) to nitrogen plant uptake deficit [GtN/yr]

sns_PU2PUdef: Quantity

Sensitivity of plant uptake to N deficit.

Controls how strongly plant uptake responds to nitrogen deficiency [yr/GtN]. Higher values indicate stronger uptake response to N limitation.

sns_BNF2PUdef: Quantity

Sensitivity of biological nitrogen fixation to N deficit.

Controls how strongly fixation responds to nitrogen deficiency [yr/GtN]. Higher values indicate stronger fixation response to N limitation.

sns_nLP2PUdef: Quantity

Sensitivity of litter production (nitrogen) to nitrogen plant uptake deficit [GtN/yr]

sns_nLD2PUdef: Quantity

Sensitivity of litter decomposition (nitrogen) to nitrogen plant uptake deficit [GtN/yr]

sns_nSR2PUdef: Quantity

Sensitivity of sol respiration (nitrogen) to nitrogen plant uptake deficit [GtN/yr]

eff_C_PU_max: Quantity

Maximum effect of NPP on plant uptake.

Upper limit of the NPP-dependent multiplier on plant uptake rate [dimensionless]. Values > 1 allow enhanced uptake under high NPP conditions.

sns_PU2NPPrd: Quantity

Sensitivity of plant uptake to NPP.

Controls how strongly plant uptake responds to changes in NPP [dimensionless]. Higher values indicate stronger coupling between NPP and uptake.

eff_C_BNF_max: Quantity

Maximum effect of NPP on biological nitrogen fixation.

Upper limit of the NPP-dependent multiplier on fixation rate [dimensionless]. Values > 1 allow enhanced fixation under high NPP conditions.

sns_BNF2NPPrd: Quantity

Sensitivity of biological nitrogen fixation to NPP.

Controls how strongly fixation responds to changes in NPP [dimensionless]. Higher values indicate stronger coupling between NPP and fixation.

NPP0: Quantity

Reference net primary production.

Baseline NPP used to calculate relative changes in production [GtC/yr]. Used to normalize NPP effects on various processes.

calculate_eff_N_NPP(NflxPUdef, switch_N)

Calculate the carbon-nitrogen coupling effect for Net Primary Production (NPP).

Parameters:

• NflxPUdef (pint.Quantity) – Nitrogen plant uptake deficit [GtN/yr].

• switch_N (pint.Quantity) – Switch to enable/disable nitrogen limitation effects [0 or 1].

Returns:

pint.Quantity – Carbon-nitrogen coupling effect on NPP.

Notes

The carbon-nitrogen coupling effect on NPP is calculated as:

\[\begin{split} \epsilon_{N(NPP)} = \begin{cases} e^{-s_{NPP2PUdef} \times PUdef} & \text{if } \mathrm{ switch\_N} \neq 0 \\ 1 & \text{if } \mathrm{switch\_N} = 0 \end{cases}\end{split}\]

calculate_eff_N_cLPLDSR(NflxPUdef, switch_N)

Calculate carbon-nitrogen coupling effects for carbon cycle processes i: LP, LD, and SR.

Parameters:

• NflxPUdef (pint.Quantity) – Nitrogen plant uptake deficit [GtN/yr].

• switch_N (pint.Quantity) – Switch to enable/disable nitrogen limitation effects [0 or 1].

Returns:

• eff_N_cLP (pint.Quantity) – N effect on carbon litter production [dimensionless].

• eff_N_cLD (pint.Quantity) – N effect on carbon litter decomposition [dimensionless].

• eff_N_cSR (pint.Quantity) – N effect on carbon soil respiration [dimensionless].

Notes

Each effect is calculated as:

\[\begin{split}\epsilon_{N(i)} = \begin{cases} e^{s_{i2PUdef} \times PUdef} & \text{if } \mathrm{switch\_N} \neq 0 \\ 1 & \text{if } \mathrm{switch\_N} = 0 \end{cases}\end{split}\]

calculate_eff_C_PUBNF(CflxNPP, CflxNPP0)

Calculate carbon availability effects on nitrogen acquisition processes.

Parameters:

• CflxNPP (pint.Quantity) – Current Net Primary Production flux [GtC/yr].

• CflxNPP0 (pint.Quantity) – Reference Net Primary Production flux [GtC/yr].

Returns:

• eff_C_PU (pint.Quantity) – Carbon enhancement of plant N uptake [dimensionless].

• eff_C_BNF (pint.Quantity) – Carbon enhancement of biological N fixation [dimensionless].

Notes

Both effects use sigmoid formulations based on relative NPP change:

\[NPPrd = \Delta NPPrel = \frac{NPP}{NPP_0} - 1\]

\[\epsilon_{C(PU)} = \frac{\epsilon_{C(PU)_{max}}}{1 + (\epsilon_{C( PU)_{max}} - 1) \times e^{-s_{PU2NPPrd} \times NPPrd}}\]

\[\epsilon_{C(BNF)} = \frac{\epsilon_{C(BNF)_{max}}}{1 + (\epsilon_{C( BNF)_{max}} - 1) \times e^{-s_{BNF2NPPrd} \times NPPrd}}\]

The sigmoid form ensures the effect equals 1 at \(NPP = NPP_0\) and approaches \(\epsilon_{max}\) at high NPP, representing saturation of the carbon enhancement effect.

calculate_eff_N_PUBNF(NflxPUdef)

Calculate nitrogen deficit effects on nitrogen acquisition processes.

Parameters:

NflxPUdef (pint.Quantity) – Nitrogen plant uptake deficit [GtN/yr].

Returns:

• eff_N_PU (pint.Quantity) – N deficit effect on plant N uptake [dimensionless].

• eff_N_BNF (pint.Quantity) – N deficit effect on biological N fixation [dimensionless].

Notes

Both effects use exponential responses with positive exponents:

\[\epsilon_{N(PU)} = \exp(s_{PU2PUdef} \times PUdef)\]

\[\epsilon_{N(BNF)} = \exp(s_{BNF2PUdef} \times PUdef)\]

calculate_eff_N_nLPLDSR(NflxPUdef)

Calculate carbon-nitrogen coupling effects for nitrogen cycle processes: LP, LD, and SR

Parameters:

NflxPUdef (Quantity) – Nitrogen plant uptake deficit [GtN/yr]

Returns:

• eff_N_nLP (pint.Quantity) – N deficit effect on nitrogen litter production [dimensionless].

• eff_N_nLD (pint.Quantity) – N deficit effect on nitrogen litter decomposition [dimensionless].

• eff_N_nSR (pint.Quantity) – N deficit effect on nitrogen mineralization [dimensionless].

Notes

All effects use exponential responses with positive exponents:

\[\epsilon_{N(i)} = \exp(s_{i2PUdef} \times PUdef)\]

Carbon Cycle

Classes and functions for carbon cycle modeling.

MAGICC Terrestrial Carbon Cycle Model Implementation

This module provides the implementation of the carbon cycle component of MAGICC’s coupled carbon-nitrogen cycle model (CNit). It simulates the dynamics of terrestrial carbon pools and their responses to climate change, CO2 fertilization, nitrogen availability, and land use change.

Carbon Cycle Components:

• CarbonNPPLPRCalculator: Calculates net primary production (NPP) and litter production respiration (LPR) fluxes with environmental modifiers

• CarbonTurnoverCalculator: Computes organic matter breakdown fluxes (litter production, litter decomposition, soil respiration) based on pool sizes and turnover times

• CarbonCycleCalculator: Handles carbon mass balance and flux partitioning among plant, litter, and soil pools using empirical allocation fractions

• CarbonCycleModel: Solves the carbon cycle ODEs using scipy.integrate.solve_ivp

• CarbonCycleModelResult: Stores and processes carbon cycle simulation results

Key Model Features:

1. Three-Pool Structure: The model tracks carbon in plant, litter, and soil organic matter pools, representing the major terrestrial carbon reservoirs.

2. Annual Timestep with Cascading: The model operates on annual timesteps but accounts for rapid sub-annual cycling through empirical allocation fractions that represent carbon cascading through multiple pools within a year.

3. Environmental Modifiers: All process rates are modified by dimensionless effect factors representing:

   • Temperature effects on decomposition and respiration

   • CO2 fertilization effects on NPP

   • Nitrogen availability effects (carbon-nitrogen coupling)

   • Land use change effects on turnover rates

   (see effect_factor_calculators)

4. First-Order Kinetics: Carbon turnover from each pool follows first-order kinetics (flux = pool size / turnover time), modified by environmental effects.

5. Flux Partitioning: Input fluxes (NPP, land use) are partitioned among pools using empirical fractions that capture both direct allocation and rapid within-year cycling.

6. Carbon-Nitrogen Coupling: Nitrogen availability affects carbon cycle processes through limitation effects on NPP and decomposition rates (calculated via nitrogen cycle effects).

Model Structure:

The carbon cycle includes three terrestrial pools:

• Plant pool (CplsP): Carbon in living plant biomass (wood, leaves, roots, storage)

• Litter pool (CplsL): Carbon in dead plant material undergoing decomposition

• Soil pool (CplsS): Carbon in soil organic matter (humus, stable organic compounds)

Key processes:

• Carbon fixation: Net primary production (NPP) converting atmospheric CO₂ to organic carbon

• Autotrophic respiration: Litter production respiration (LPR) from fast turnover of plant tissues

• Organic matter turnover: Litter production (cLP), litter decomposition (cLD), soil respiration (cSR)

• Heterotrophic respiration: Total CO₂ release from decomposition (RH = LPR + cLD2A + cSR)

• Land use emissions: Carbon release from deforestation and land conversion (cLUgrs)

class cnit.physics.carbon_cycle.CarbonNPPLPRCalculator

Bases: object

Calculator for Net Primary Production and Litter Production Respiration carbon fluxes

NPP0: Quantity

Initial net primary production (NPP), base NPP without any effects [GtC/yr]

LPR0: Quantity

Initial Litter production respiration (LPR), base LPR without any effects [GtC/yr]

calculate(CflxLUrgr, eff_CO2_NPP, eff_dT_NPP, eff_N_NPP, eff_LU_NPP, eff_dT_LPR)

Calculate carbon fluxes for Net Primary Production and Litter Production Respiration

Parameters:

• eff_CO2_NPP (Quantity) – CO2 effect on NPP [dimensionless]

• eff_dT_NPP (Quantity) – Temperature effect on NPP [dimensionless]

• eff_dT_LPR (Quantity) – Temperature effect on LPR [dimensionless]

• eff_N_NPP (Quantity) – Carbon-nitrogen coupling effect on NPP [dimensionless]

• eff_LU_NPP (Quantity) – Land use effect on NPP [dimensionless]

• CflxLUrgr (Quantity) – Carbon flux from land-use regrowth [GtC/yr]

Returns:

Dict[str, Quantity] – Dictionary with keys:

• CflxNPP: Net Primary Production carbon flux [GtC/yr]

• CflxLPR: Litter Production Respiration carbon flux [GtC/yr]

Notes

The following formulas are used:

\[ \begin{align}\begin{aligned}NPP = (NPP_0 + LUrgr) \times \epsilon_{T(NPP)} \times \epsilon_{CO2} \times \epsilon_{N(NPP)} \times \epsilon_{LU(NPP)}\\LPR = LPR0 \times \epsilon_{T(LPR)} \times \epsilon_{CO2} \times \epsilon_{N(LPR)} \times \epsilon_{LU(NPP)}\end{aligned}\end{align} \]

class cnit.physics.carbon_cycle.CarbonTurnoverCalculator

Bases: object

Calculator for carbon turnover processes in terrestrial pools.

This calculator determines carbon fluxes between different pools in the terrestrial carbon cycle based on pool sizes, turnover times, and environmental effects. The turnover processes include:

• Litter production (cLP): Transfer from plant to litter pool

• Litter decomposition (cLD): Transfer from litter to soil pool

• Soil respiration (cSR): Release from soil organic matter to atmosphere

Each flux is controlled by pool size, baseline turnover time, and environmental effects including temperature, nitrogen availability, and land use change.

tau_CplsP: Quantity

Plant carbon pool turnover time under reference conditions [yr].

Determines the baseline rate at which carbon is transferred from plant biomass to litter through senescence and mortality.

tau_CplsL: Quantity

Litter carbon pool turnover time under reference conditions [yr].

Determines the baseline rate at which carbon is released from litter and transferred to soil organic matter through decomposition.

tau_CplsS: Quantity

Soil carbon pool turnover time under reference conditions [yr].

Determines the baseline rate at which carbon is released from soil organic matter through decomposition and respiration processes.

calculate(CplsP, CplsL, CplsS, eff_dT_cLP, eff_dT_cLD, eff_dT_cSR, eff_N_cLP, eff_N_cLD, eff_N_cSR, eff_LU_cLP, eff_LU_cLD, eff_LU_cSR)

Calculate carbon turnover fluxes from plant, litter, and soil carbon pools based on pool sizes, turnover times, and environmental effect factors.

Parameters:

• CplsP (Quantity) – Plant carbon pool size [GtC]. Total carbon contained in living plant biomass.

• CplsL (Quantity) – Litter carbon pool size [GtC]. Total carbon contained in dead plant material (litter).

• CplsS (Quantity) – Soil carbon pool size [GtC]. Total carbon contained in soil organic matter.

• eff_dT_cLP (Quantity) – Temperature effect on litter production carbon turnover [dimensionless].

• eff_dT_cLD (Quantity) – Temperature effect on litter decomposition carbon turnover [dimensionless].

• eff_dT_cSR (Quantity) – Temperature effect on soil respiration carbon turnover [dimensionless].

• eff_N_cLP (Quantity) – Carbon-nitrogen coupling effect on litter production [dimensionless].

• eff_N_cLD (Quantity) – Carbon-nitrogen coupling effect on litter decomposition [dimensionless].

• eff_N_cSR (Quantity) – Carbon-nitrogen coupling effect on soil respiration [dimensionless].

• eff_LU_cLP (Quantity) – Land use effect on litter production carbon turnover [dimensionless].

• eff_LU_cLD (Quantity) – Land use effect on litter decomposition carbon turnover [dimensionless].

• eff_LU_cSR (Quantity) – Land use effect on soil respiration carbon turnover [dimensionless].

Returns:

Dict[str, Quantity] – Dictionary with keys:

• CflxLP: Carbon flux from litter production [GtC/yr]

• CflxLD: Carbon flux from litter decomposition [GtC/yr]

• CflxSR: Carbon flux from soil respiration [GtC/yr]

Notes

The following formulas are used:

\[ \begin{align}\begin{aligned}cLP = \frac{C_P}{\tau_{C_P}} \times \epsilon_{T(cLP)} \times \epsilon_{N(cLP)} \times \epsilon_{LU(cLP)}\\cLD = \frac{C_L}{\tau_{C_L}} \times \epsilon_{T(cLD)} \times \epsilon_{N(cLD)} \times \epsilon_{LU(cLD)}\\cSR = \frac{C_S}{\tau_{C_S}} \times \epsilon_{T(cSR)} \times \epsilon_{N(cSR)} \times \epsilon_{LU(cSR)}\end{aligned}\end{align} \]

where:

• \(C_P\), \(C_L\), \(C_S\) are the plant, litter, and soil carbon pool sizes

• \(\tau_{C_P}\), \(\tau_{C_L}\), \(\tau_{C_S}\) are the respective turnover times

• \(\epsilon_{T}\) represents temperature effects

• \(\epsilon_{N}\) represents carbon-nitrogen coupling effects

• \(\epsilon_{LU}\) represents land use effects

Each flux is calculated using first-order kinetics where the turnover rate equals pool size divided by turnover time, modified by environmental effects. This formulation assumes that turnover processes follow exponential decay dynamics at baseline conditions, with multiplicative effects from environmental factors.

class cnit.physics.carbon_cycle.CarbonCycleCalculator

Bases: object

Calculator for terrestrial carbon cycle dynamics.

This class handles the complete carbon cycle by tracking carbon transfers between pools and calculating pool dynamics. The carbon cycle includes three main terrestrial pools:

• Plant carbon pool (CplsP): Carbon in living plant biomass

• Litter carbon pool (CplsL): Carbon in dead plant material

• Soil carbon pool (CplsS): Carbon in soil organic matter

Key processes include:

• Carbon fixation: Net primary production (NPP) converting atmospheric CO₂ to organic carbon

• Autotrophic respiration: Litter production respiration (LPR) releasing CO₂ from plant metabolism

• Organic matter turnover: Litter production (cLP), litter decomposition (cLD), and soil respiration (cSR)

• Heterotrophic respiration: Release of CO₂ from decomposition (RH = LPR + cLD2A + cSR)

• Land use changes: Gross deforestation (cLUgrs) releasing carbon to atmosphere

Each input flux is partitioned among pools using empirically-derived fractions that represent the distribution of carbon through different pathways in the terrestrial biosphere. These fractions account for the cascade of carbon through multiple pools within the annual timestep, capturing both immediate allocation and subsequent rapid turnover processes.

frc_NPP2P: Quantity

Fraction of net primary production allocated to plant pool [dimensionless].

Represents the portion of newly fixed carbon remaining in plant biomass at the end of the annual timestep, primarily in long-lived tissues (wood, structural tissues, storage organs) that do not turn over within the year.

frc_NPP2L: Quantity

Fraction of net primary production allocated to litter pool [dimensionless].

Represents newly fixed carbon that enters the litter pool within the annual timestep through rapid plant-to-litter turnover (e.g., fine root turnover, leaf senescence). The remainder (1 - frc_NPP2P - frc_NPP2L) goes to the soil pool, representing carbon that cycles through both plant and litter pools and enters soil within the annual timestep.

frc_cLP2L: Quantity

Fraction of litter production carbon retained in litter pool [dimensionless].

Represents carbon in plant materials that remain in the litter pool at the end of the annual timestep as recognizable plant structures. The remainder (1 - frc_cLP2L) goes directly to soil, representing materials that decompose rapidly and enter the soil pool within the annual timestep, bypassing extended residence in the litter stage.

frc_cLD2S: Quantity

Fraction of litter decomposition carbon transferred to soil pool [dimensionless].

Represents carbon incorporated into stable soil organic matter during decomposition. The remainder (1 - frc_cLD2S) is respired to the atmosphere (cLD2A), representing carbon released as CO₂ during litter breakdown.

frc_cLUgrs2P: Quantity

Fraction of gross deforestation carbon loss from plant pool [dimensionless].

Represents the distribution of carbon lost during land conversion, with this fraction coming from plant biomass removal or burning.

frc_cLUgrs2L: Quantity

Fraction of gross deforestation carbon loss from litter pool [dimensionless].

Represents carbon lost from litter during land conversion. The remainder (1 - frc_cLUgrs2P - frc_cLUgrs2L) comes from the soil pool.

calculate_dCpls_dt(CflxNPP, CflxLPR, CflxLP, CflxLD, CflxSR, CflxLUgrs)

Calculate rate of change for plant, litter, and soil carbon pools.

This method computes the time derivatives of terrestrial carbon pools based on inputs (NPP), autotrophic respiration (LPR), internal transfers (cLP, cLD), heterotrophic respiration (cSR), and land use changes (cLUgrs). Each input flux is partitioned among pools according to the fractional allocation parameters, which account for carbon cascading through multiple pools within the annual timestep.

Parameters:

• CflxNPP (Quantity) – Net primary production carbon flux [GtC/yr]. Total carbon fixation by plants after autotrophic respiration.

• CflxLPR (Quantity) – Litter production respiration carbon flux [GtC/yr]. Autotrophic respiration associated with plant tissue turnover.

• CflxLP (Quantity) – Litter production flux [GtC/yr]. Carbon transfer from plant to litter through senescence and mortality.

• CflxLD (Quantity) – Litter decomposition flux [GtC/yr]. Carbon release from litter through decomposition.

• CflxSR (Quantity) – Soil respiration flux [GtC/yr]. Carbon release from soil organic matter through decomposition (also called soil turnover).

• CflxLUgrs (Quantity) – Gross deforestation carbon flux [GtC/yr]. Carbon lost from system due to land conversion.

Returns:

List[Quantity] – List containing:

• dCplsP_dt: Rate of change of plant carbon pool [GtC/yr]

• dCplsL_dt: Rate of change of litter carbon pool [GtC/yr]

• dCplsS_dt: Rate of change of soil carbon pool [GtC/yr]

Notes

The pool dynamics follow mass balance equations:

Plant Pool:

\[\frac{dC_P}{dt} = NPP \times f_{NPP2P} - LPR - cLP - cLUgrs \times f_{cLUgrs2P}\]

Litter Pool:

\[\frac{dC_L}{dt} = NPP \times f_{NPP2L} + cLP \times f_{cLP2L} - cLD - cLUgrs \times f_{cLUgrs2L}\]

Soil Pool:

\[\frac{dC_S}{dt} = NPP \times f_{NPP2S} + cLP \times f_{cLP2S} + cLD \times f_{cLD2S} - cSR - cLUgrs \times f_{cLUgrs2S}\]

where:

• \(f_{NPP2S} = 1 - f_{NPP2P} - f_{NPP2L}\) represents NPP carbon cascading through plant→litter→soil within the annual timestep

• \(f_{cLP2S} = 1 - f_{cLP2L}\) represents rapid litter decomposition directly entering soil within the annual timestep

• \(f_{cLUgrs2S} = 1 - f_{cLUgrs2P} - f_{cLUgrs2L}\) (remainder from soil)

Important Note on Annual Timestep:

All allocation fractions account for the cascade of carbon through multiple pools within the annual timestep. For example, \(f_{NPP2S}\) does not represent direct allocation from atmosphere to soil, but rather carbon that is fixed by plants, then enters litter through turnover, and subsequently enters soil through decomposition—all within a single year. This approach effectively captures rapid cycling processes without explicitly modeling sub-annual dynamics.

calculate_Cflx_all(CflxNPP, CflxLPR, CflxLP, CflxLD, CflxSR, CflxLUgrs)

Calculate all carbon fluxes and their partitioning in the system.

This method computes the complete set of carbon fluxes including all partitioned flows between pools. Useful for detailed budget analysis and diagnostic output.

Parameters:

• CflxNPP (Quantity) – Net primary production carbon flux [GtC/yr].

• CflxLPR (Quantity) – Litter production respiration carbon flux [GtC/yr].

• CflxLP (Quantity) – Litter production flux [GtC/yr].

• CflxLD (Quantity) – Litter decomposition flux [GtC/yr].

• CflxSR (Quantity) – Soil respiration flux [GtC/yr] (also called soil turnover).

• CflxLUgrs (Quantity) – Gross deforestation carbon flux [GtC/yr].

Returns:

Dict[str, Quantity] – Dictionary containing all carbon fluxes and their partitioned components:

• Primary fluxes: CflxNPP, CflxLPR, CflxLP, CflxLD, CflxSR, CflxLUgrs

• NPP partitioning: CflxNPP2P, CflxNPP2L, CflxNPP2S

• LP partitioning: CflxLP2L, CflxLP2S

• LD partitioning: CflxLD2S, CflxLD2A

• LUgrs partitioning: CflxLUgrs2P, CflxLUgrs2L, CflxLUgrs2S

• Derived flux: CflxRH (total heterotrophic respiration = LPR + cLD2A + cSR)

Notes

Heterotrophic respiration (RH) is calculated as:

\[RH = LPR + cLD2A + cSR\]

where:

• \(LPR\) is litter production respiration (plant autotrophic respiration)

• \(cLD2A = cLD \times (1 - f_{cLD2S})\) is litter decomposition to atmosphere

• \(cSR\) is soil respiration (all assumed to be respired to atmosphere)

This represents the total flux of carbon from terrestrial organic matter to the atmosphere through respiration processes, which is a key component of the terrestrial carbon budget and climate feedbacks.

class cnit.physics.carbon_cycle.CarbonCycleModelResult

Bases: object

Results from running the carbon cycle model.

This class stores the complete output from a carbon cycle model simulation, including carbon pool states, fluxes, and all environmental effect modifiers. Results can be converted to an xarray Dataset for analysis and visualization.

The carbon cycle model tracks three terrestrial carbon pools:

• Plant carbon pool (CplsP): Carbon in living plant biomass

• Litter carbon pool (CplsL): Carbon in dead plant material

• Soil carbon pool (CplsS): Carbon in soil organic matter

Key processes represented include:

• Carbon fixation through net primary production (NPP)

• Litter production respiration (LPR)

• Organic matter turnover (cLP, cLD, cSR)

• Land use change emissions (cLUgrs)

• Environmental modifiers: temperature, nitrogen, and land use effects

Note:

All _t attributes are time-continuous functions created through linear interpolation of discrete time points. These functions map from time [yr] to their respective units, allowing for smooth temporal interpolation of forcing data and effect modifiers.

c_state: Dict[str, Quantity]

Carbon pool states over time [GtC].

Dictionary containing time series of carbon pools: - ‘CplsP’: Plant carbon pool - ‘CplsL’: Litter carbon pool - ‘CplsS’: Soil carbon pool

calc_c_turnover: CarbonTurnoverCalculator

Calculator for carbon turnover processes.

Instance of CarbonTurnoverCalculator containing turnover time parameters and methods for calculating organic matter breakdown fluxes (cLP, cLD, cSR).

calc_c_cycle: CarbonCycleCalculator

Calculator for carbon cycle mass balance.

Instance of CarbonCycleCalculator containing allocation fractions and methods for calculating flux partitioning and pool dynamics.

time_axis: Quantity

Time points for simulation [yr].

Array of discrete time points at which the model state is evaluated, typically representing annual timesteps.

CflxNPP_t: Callable[[Quantity], Quantity]

Time-interpolated net primary production flux function [GtC/yr].

Continuous function mapping time to NPP flux. Interpolated from discrete forcing data to allow smooth temporal variation.

CflxLPR_t: Callable[[Quantity], Quantity]

Time-interpolated litter production respiration flux function [GtC/yr].

Continuous function mapping time to LPR flux. Interpolated from discrete forcing data.

CflxLUgrs_t: Callable[[Quantity], Quantity]

Time-interpolated gross land use change flux function [GtC/yr].

Continuous function mapping time to land use emissions. Represents carbon lost to atmosphere during land conversion (deforestation, agricultural expansion). Interpolated from discrete forcing data.

eff_dT_cLP_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on litter production function [dimensionless].

Continuous function mapping time to temperature modifier for plant-to-litter carbon turnover. Interpolated from calculated temperature effects.

eff_dT_cLD_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on litter decomposition function [dimensionless].

Continuous function mapping time to temperature modifier for litter-to-soil carbon turnover. Interpolated from calculated temperature effects.

eff_dT_cSR_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on soil respiration function [dimensionless].

Continuous function mapping time to temperature modifier for soil organic matter decomposition. Interpolated from calculated temperature effects.

eff_N_cLP_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on litter production function [dimensionless].

Continuous function mapping time to nitrogen modifier for plant-to-litter carbon turnover. Represents carbon-nitrogen coupling effects on plant tissue turnover. Interpolated from calculated nitrogen effects.

eff_N_cLD_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on litter decomposition function [dimensionless].

Continuous function mapping time to nitrogen modifier for litter decomposition. Represents how nitrogen limitation affects decomposer activity. Interpolated from calculated nitrogen effects.

eff_N_cSR_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on soil respiration function [dimensionless].

Continuous function mapping time to nitrogen modifier for soil organic matter decomposition. Represents carbon-nitrogen coupling in soil respiration. Interpolated from calculated nitrogen effects.

eff_LU_cLP_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on litter production function [dimensionless].

Continuous function mapping time to land use modifier for plant-to-litter carbon turnover. Represents how land use change affects plant mortality rates. Interpolated from calculated land use effects.

eff_LU_cLD_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on litter decomposition function [dimensionless].

Continuous function mapping time to land use modifier for litter decomposition. Represents how land use change affects litter breakdown rates. Interpolated from calculated land use effects.

eff_LU_cSR_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on soil respiration function [dimensionless].

Continuous function mapping time to land use modifier for soil organic matter decomposition. Represents how land use change affects soil carbon dynamics. Interpolated from calculated land use effects.

add_non_state_variables()

Calculate derived variables and create xarray Dataset with complete results.

This method computes all diagnostic fluxes and derived quantities from the model state variables and returns a complete xarray Dataset containing:

• State variables: Carbon pools (CplsP, CplsL, CplsS)

• Turnover fluxes: Calculated from pools and environmental effects (cLP, cLD, cSR)

• All partitioned fluxes: NPP, LPR, and land use change distributed among pools

• Derived quantities: Total terrestrial carbon (CplsPLS), net terrestrial flux (CflxNetPLS)

• Heterotrophic respiration: Total CO₂ release from decomposition (CflxRH)

Returns:

xr.Dataset – Complete model results as xarray Dataset with time dimension and all variables labeled with descriptive names and units. The Dataset includes:

State Variables:

• CplsP, CplsL, CplsS: Individual pool sizes [GtC]

• CplsPLS: Total terrestrial carbon [GtC]

Primary Fluxes:

• CflxNPP: Net primary production [GtC/yr]

• CflxLPR: Litter production respiration [GtC/yr]

• CflxLP: Litter production [GtC/yr]

• CflxLD: Litter decomposition [GtC/yr]

• CflxSR: Soil respiration [GtC/yr]

• CflxLUgrs: Gross land use emissions [GtC/yr]

Partitioned Fluxes:

• CflxNPP2P, CflxNPP2L, CflxNPP2S: NPP allocation to each pool

• CflxLP2L, CflxLP2S: Litter production allocation

• CflxLD2S, CflxLD2A: Litter decomposition to soil and atmosphere

• CflxLUgrs2P, CflxLUgrs2L, CflxLUgrs2S: Land use emissions from each pool

Derived Fluxes:

• CflxRH: Total heterotrophic respiration [GtC/yr]

• CflxNetPLS: Net change in terrestrial carbon [GtC/yr]

Notes

The net terrestrial carbon flux is calculated using numerical differentiation:

\[cNetPLS = \frac{dC_{PLS}}{dt} = \frac{d(C_P + C_L + C_S)}{dt}\]

This represents the net carbon balance of the terrestrial biosphere, with positive values indicating carbon uptake (sink) and negative values indicating carbon release (source).

The heterotrophic respiration is calculated as:

\[RH = LPR + cLD2A + cSR\]

This represents total CO₂ release from decomposition processes, a key component of the terrestrial carbon budget and climate feedbacks.

class cnit.physics.carbon_cycle.CarbonCycleModel

Bases: object

MAGICC’s terrestrial carbon cycle model (carbon component of CNit).

This model simulates the dynamics of three terrestrial carbon pools in the terrestrial biosphere by solving a system of ordinary differential equations (ODEs) using scipy.integrate.solve_ivp. The model tracks carbon transfers between pools through processes including:

• Carbon fixation via net primary production (NPP)

• Litter production respiration (LPR)

• Organic matter turnover (litter production, litter decomposition, soil respiration)

• Land use change emissions

• Environmental modifiers (temperature, nitrogen availability, land use effects)

The model uses annual timesteps and accounts for rapid carbon cycling through empirical allocation fractions that represent carbon cascading through multiple pools within a year.

Time-continuous functions (suffixed with _t) are generated through linear interpolation of discrete time points and provide continuous values over the simulation period, allowing the ODE solver to evaluate fluxes at any time point.

calc_c_turnover: CarbonTurnoverCalculator

Calculator for carbon turnover processes.

Instance of CarbonTurnoverCalculator containing turnover time parameters (tau_CplsP, tau_CplsL, tau_CplsS) and methods for calculating organic matter breakdown fluxes based on pool sizes and environmental effects.

calc_c_cycle: CarbonCycleCalculator

Calculator for carbon cycle mass balance.

Instance of CarbonCycleCalculator containing allocation fractions (frc_NPP2P, frc_NPP2L, frc_cLP2L, frc_cLD2S, frc_cLUgrs2P, frc_cLUgrs2L) and methods for calculating flux partitioning and pool dynamics.

CplsP0: Quantity

Initial plant carbon pool size [GtC].

Carbon contained in living plant biomass at the start of the simulation (time0). Typical values range from 400-550 GtC for global simulations.

CplsL0: Quantity

Initial litter carbon pool size [GtC].

Carbon contained in dead plant material (litter) at the start of the simulation (time0). Typical values range from 40-70 GtC for global simulations.

CplsS0: Quantity

Initial soil carbon pool size [GtC].

Carbon contained in soil organic matter at the start of the simulation (time0). Typical values range from 1400-1700 GtC for global simulations.

time0: Quantity

Initialization time [yr].

Time point at which the initial pool sizes (CplsP0, CplsL0, CplsS0) apply. The simulation time_axis must start at or after this time. Typically set to the pre-industrial baseline year (1850).

switch_Cpls: list[int]

Carbon pool switches for [plant, litter, soil] [dimensionless].

Binary switches (1=enabled, 0=disabled) to selectively enable or disable pool dynamics. Useful for diagnostic purposes or simplified model configurations. Setting a switch to 0 freezes that pool at its initial value.

• switch_Cpls[0]: Plant pool switch

• switch_Cpls[1]: Litter pool switch

• switch_Cpls[2]: Soil pool switch

run(time_axis, CflxNPP_t, CflxLPR_t, CflxLUgrs_t, eff_dT_cLP_t, eff_dT_cLD_t, eff_dT_cSR_t, eff_N_cLP_t, eff_N_cLD_t, eff_N_cSR_t, eff_LU_cLP_t, eff_LU_cLD_t, eff_LU_cSR_t)

Run the carbon cycle model simulation.

This method solves the system of ODEs for carbon pool dynamics over the specified time period using scipy.integrate.solve_ivp. The solver uses time-continuous interpolated functions for all forcing data and environmental effects, allowing flexible time step selection during integration.

Parameters:

• time_axis (Quantity) – Time points for simulation [yr]. Must start at or after time0. These are the time points at which solution is explicitly evaluated.

• CflxNPP_t (Callable[[Quantity], Quantity]) – Time-interpolated net primary production flux function [GtC/yr]. Maps time to NPP, representing carbon fixation by plants.

• CflxLPR_t (Callable[[Quantity], Quantity]) – Time-interpolated litter production respiration flux function [GtC/yr]. Maps time to LPR, representing autotrophic respiration from tissue turnover.

• CflxLUgrs_t (Callable[[Quantity], Quantity]) – Time-interpolated gross land use change flux function [GtC/yr]. Maps time to land use emissions from deforestation and land conversion.

• eff_dT_cLP_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on litter production function [dimensionless]. Maps time to temperature modifier for plant-to-litter turnover.

• eff_dT_cLD_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on litter decomposition function [dimensionless]. Maps time to temperature modifier for litter-to-soil turnover.

• eff_dT_cSR_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on soil respiration function [dimensionless]. Maps time to temperature modifier for soil organic matter decomposition.

• eff_N_cLP_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on litter production function [dimensionless]. Maps time to nitrogen modifier for plant-to-litter turnover.

• eff_N_cLD_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on litter decomposition function [dimensionless]. Maps time to nitrogen modifier for litter decomposition.

• eff_N_cSR_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on soil respiration function [dimensionless]. Maps time to nitrogen modifier for soil respiration.

• eff_LU_cLP_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on litter production function [dimensionless]. Maps time to land use modifier for plant-to-litter turnover.

• eff_LU_cLD_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on litter decomposition function [dimensionless]. Maps time to land use modifier for litter decomposition.

• eff_LU_cSR_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on soil respiration function [dimensionless]. Maps time to land use modifier for soil respiration.

Returns:

CarbonCycleModelResult – Simulation results containing:

• Carbon pool time series (CplsP, CplsL, CplsS)

• References to calculator instances

• All input forcing and effect functions

• Methods to calculate derived fluxes and diagnostics

Raises:

• ValueError – If time_axis starts before time0. The simulation cannot run backwards from the initialization time.

• SolveError – If the numerical ODE solver fails to converge. This can occur due to numerical instability, runaway feedbacks, or inappropriate tolerance settings.

Notes

ODE System:

The model solves the following system of ODEs:

\[ \begin{align}\begin{aligned}\frac{dC_P}{dt} = NPP \times f_{NPP2P} - LPR - cLP - cLUgrs \times f_{cLUgrs2P}\\\frac{dC_L}{dt} = NPP \times f_{NPP2L} + cLP \times f_{cLP2L} - cLD - cLUgrs \times f_{cLUgrs2L}\\\frac{dC_S}{dt} = NPP \times f_{NPP2S} + cLP \times f_{cLP2S} + cLD \times f_{cLD2S} - cSR - cLUgrs \times f_{cLUgrs2S}\end{aligned}\end{align} \]

where turnover fluxes (cLP, cLD, cSR) are calculated from pool sizes and environmental effects using first-order kinetics.

Numerical Methods:

The solver uses scipy.integrate.solve_ivp with:

• Adaptive time stepping (solver selects appropriate substeps)

• Absolute tolerance: 1e-6 GtC

• Relative tolerance: 1e-3

• Default solver method (typically RK45)

Pool Switches:

Pool dynamics can be selectively disabled using switch_Cpls. When a switch is set to 0, the corresponding pool’s rate of change is forced to zero, effectively freezing that pool at its initial value throughout the simulation.

Time-Continuous Functions:

All _t arguments are callable functions created through linear interpolation of discrete time points. This allows the ODE solver to evaluate forcing data and environmental effects at any time point during integration, not just at the discrete output times specified in time_axis.

Nitrogen Cycle

Classes and functions for modeling nitrogen cycling.

MAGICC Terrestrial Nitrogen Cycle Model Implementation

This module provides the implementation of the nitrogen cycle component of MAGICC’s coupled carbon-nitrogen cycle model (CNit). It simulates the dynamics of terrestrial nitrogen pools and their interactions with carbon cycling, climate change, atmospheric deposition, fertilizer application, and land use change.

Nitrogen Cycle Components:

• NitrogenPUBNFCalculator: Calculates plant nitrogen uptake (PU) and biological nitrogen fixation (BNF) fluxes with environmental modifiers and nitrogen deficit feedbacks

• NitrogenTurnoverCalculator: Computes nitrogen turnover fluxes (litter production, litter decomposition, soil respiration, mineral losses) based on pool sizes and turnover times

• NitrogenCycleCalculator: Handles nitrogen mass balance and flux partitioning among plant, litter, soil, and mineral pools using empirical allocation fractions

• NitrogenCycleModel: Solves the nitrogen cycle ODEs in two stages using scipy.integrate.solve_ivp

• NitrogenCycleModelResult: Stores and processes nitrogen cycle simulation results

Key Model Features:

1. Four-Pool Structure: The model tracks nitrogen in plant, litter, soil organic matter, and mineral (plant-available inorganic) pools, representing both organic and inorganic nitrogen reservoirs.

2. Two-Stage Solution: The nitrogen cycle is solved in two sequential stages:

   • Stage 1: Organic nitrogen pools (plant, litter, soil)

   • Stage 2: Mineral nitrogen pool using net mineralization from Stage 1

   This approach reflects the coupling between organic matter decomposition and mineral nitrogen availability.

3. Nitrogen Deficit Feedback: A key feature is the explicit calculation of nitrogen deficit for plant uptake:

   \[PUdef = PUreq - PUavail\]

   where nitrogen requirement (PUreq) is based on NPP and stoichiometric N: C ratios, and nitrogen availability (PUavail) comes from mineralization and external inputs. This deficit drives compensatory responses in plant uptake efficiency and biological fixation.

4. Flux-Based Mineralization: Net mineralization is parameterized as a flux-based process rather than relying on explicit mineral pool dynamics. This approach is necessary for annual timestep integration, as the mineral nitrogen pool turnover time (days to weeks) is much shorter than the annual timestep. The flux-based approach captures essential nitrogen limitation dynamics without modeling sub-annual mineral pool fluctuations.

5. Annual Timestep with Cascading: The model operates on annual timesteps but accounts for rapid sub-annual cycling through empirical allocation fractions that represent nitrogen cascading through multiple pools within a year (e.g., nitrogen taken up by plants, then entering litter through turnover, then entering soil through decomposition—all within one year).

6. Environmental Modifiers: All process rates are modified by dimensionless effect factors representing:

   • Temperature effects on turnover and mineralization

   • Nitrogen availability effects (carbon-nitrogen coupling)

   • Land use change effects on turnover rates

   (see effect_factor_calculators)

7. Multiple Nitrogen Inputs: The model includes both natural and anthropogenic nitrogen inputs:

   • Biological nitrogen fixation (BNF): Natural N₂ fixation by microorganisms

   • Atmospheric deposition (AD): Wet and dry deposition from atmospheric sources

   • Fertilizer application (FT): Direct anthropogenic nitrogen addition

8. Nitrogen Losses: The model represents nitrogen losses through:

   • Gaseous emissions: Denitrification (N₂, N₂O, NO) and ammonia volatilization

   • Leaching: Nitrate leaching and dissolved organic nitrogen export

   • Land use change: Direct losses during deforestation and land conversion

Model Structure:

The nitrogen cycle includes four terrestrial pools:

• Plant pool (NplsP): Nitrogen in living plant biomass (structural and storage compounds)

• Litter pool (NplsL): Nitrogen in dead plant material undergoing decomposition

• Soil pool (NplsS): Nitrogen in soil organic matter (proteins, amino acids, humus)

• Mineral pool (NplsM): Plant-available inorganic nitrogen (primarily NH₄⁺ and NO₃⁻)

Key processes:

• External inputs: Biological nitrogen fixation (BNF), atmospheric deposition (AD), fertilizer application (FT)

• Plant uptake (PU): Transfer from mineral to organic pools

• Organic matter turnover: Litter production (nLP), litter decomposition (nLD), soil respiration/turnover (nSR)

• Mineralization: Release of plant-available nitrogen from organic matter decomposition (NetMIN = nLD2M + nSR)

• Nitrogen losses: Gaseous emissions and leaching from mineral pool (nLS)

• Land use emissions: Nitrogen lost from organic pools (nLUgrs) and mineral pool (nLUmin) during land conversion

class cnit.physics.nitrogen_cycle.NitrogenPUBNFCalculator

Bases: object

Calculator for nitrogen plant uptake and biological nitrogen fixation.

This class computes nitrogen fluxes in the terrestrial biosphere, including: - Plant uptake (PU) - Biological nitrogen fixation (BNF)

The calculator accounts for multiple environmental controls including temperature, carbon cycle dynamics, nitrogen availability, nitrogen deposition, and anthropogenic inputs (fertilization). A key feature is the plant uptake deficit feedback, where insufficient nitrogen availability for plant uptake (positive deficit) can stimulate compensatory responses in both uptake efficiency and biological fixation.

PU0: Quantity

Initial plant uptake rate, base rate of nitrogen uptake by plants under reference conditions without any environmental effects [GtN/yr].

BNF0: Quantity

Initial biological nitrogen fixation rate, base rate of nitrogen fixation by symbiotic and free-living organisms under reference conditions without any environmental effects [GtN/yr].

NCratio_PUreq: Quantity

Required nitrogen-to-carbon ratio for plant uptake [GtN/GtC]. Stoichiometric ratio determining nitrogen demand based on carbon uptake. This represents the N:C ratio needed to support new plant biomass production.

NetMIN0: Quantity

Initial net mineralization rate under reference conditions [GtN/yr]. Net mineralization is the balance between nitrogen release from organic matter decomposition (mineralization) and nitrogen uptake by microbes (immobilization). This flux is temperature-sensitive.

sns_NetMIN2dT: Quantity

Temperature sensitivity of net mineralization [1/K]. Controls how strongly mineralization responds to temperature changes. Higher values indicate stronger temperature effect on mineralization rates. Positive values indicate increased mineralization with warming.

NetMINlt0: Quantity

Long-term net mineralization rate under reference conditions [GtN/yr]. This component is sensitive to nitrogen deposition and changes in net primary productivity, representing slower-turnover mineral nitrogen pools.

sns_NetMINlt2AD: Quantity

Sensitivity of long-term net mineralization to nitrogen deposition [yr/GtN]. Controls how strongly long-term mineralization responds to cumulative nitrogen deposition. This represents priming effects where added nitrogen can stimulate or suppress organic matter decomposition.

calculate(eff_dT_PU, eff_C_PU, eff_N_PU, eff_dT_BNF, eff_C_BNF, eff_N_BNF)

Calculate nitrogen fluxes for plant uptake (PU) and biological nitrogen fixation (BNF).

Parameters:

• eff_dT_PU (Quantity) – Temperature effect on plant uptake [dimensionless]. Values > 1 indicate enhanced uptake with warming, < 1 indicate reduced uptake.

• eff_C_PU (Quantity) – Carbon cycle effect on plant uptake [dimensionless]. Represents how changes in NPP affect nitrogen uptake capacity. This is a sigmoid function of relative NPP change (see calculate_eff_C_PUBNF), where increased NPP enhances the ability to take up nitrogen up to a maximum value.

• eff_N_PU (Quantity) – Nitrogen cycle effect on plant uptake [dimensionless]. Represents the response of plant nitrogen uptake to nitrogen limitation. This is an exponential function of nitrogen deficit (see calculate_eff_N_PUBNF), where positive deficit (N limitation) can enhance uptake efficiency through mechanisms like increased root allocation, upregulation of N transporters, or mycorrhizal associations. With positive sensitivity (sns_PU2PUdef > 0), values > 1 indicate enhanced uptake under N limitation.

• eff_dT_BNF (Quantity) – Temperature effect on biological nitrogen fixation [dimensionless]. Values > 1 indicate enhanced fixation with warming.

• eff_C_BNF (Quantity) – Carbon cycle effect on biological nitrogen fixation [dimensionless]. Represents how changes in NPP affect BNF rates. BNF is energetically costly and requires carbon from photosynthesis. This is a sigmoid function of relative NPP change (see calculate_eff_C_PUBNF), where increased NPP provides more carbon energy to support fixation up to a maximum value.

• eff_N_BNF (Quantity) – Nitrogen cycle effect on biological nitrogen fixation [dimensionless]. Represents the response of BNF to nitrogen limitation. This is an exponential function of nitrogen deficit (see calculate_eff_N_PUBNF). With positive sensitivity (sns_BNF2PUdef > 0), N limitation (positive deficit) stimulates BNF as it becomes favorable to invest energy in fixation when soil N is scarce. With negative sensitivity, high N availability (negative deficit) can down-regulate fixation since it is energetically expensive and unnecessary when soil N is abundant.

Returns:

Dict[str, Quantity] – Dictionary with keys:

• NflxPU: Plant uptake nitrogen flux [GtN/yr]

• NflxBNF: Biological nitrogen fixation flux [GtN/yr]

Notes

The following formulas are used:

\[ \begin{align}\begin{aligned}PU = PU_0 \times \epsilon_{T(PU)} \times \epsilon_{C(PU)} \times \epsilon_{N(PU)}\\BNF = BNF_0 \times \epsilon_{T(BNF)} \times \epsilon_{C(BNF)} \times \epsilon_{N(BNF)}\end{aligned}\end{align} \]

where:

• \(PU_0\) is the initial plant uptake rate

• \(BNF_0\) is the initial biological nitrogen fixation rate

• \(\epsilon_{T}\) represents temperature effects

• \(\epsilon_{C}\) represents carbon cycle effects (NPP-driven enhancement via sigmoid response)

• \(\epsilon_{N}\) represents nitrogen deficit effects (exponential response to N limitation)

The carbon effects (\(\epsilon_{C(PU)}\) and \(\epsilon_{C(BNF)}\)) are computed as sigmoid functions of relative NPP change, ensuring smooth transitions from reference conditions and saturation at high productivity levels.

The nitrogen effects (\(\epsilon_{N(PU)}\) and \(\epsilon_{N(BNF)}\)) are exponential functions of the plant uptake deficit, representing compensatory responses when nitrogen availability for plant uptake is insufficient. When the deficit is positive (required > available for PU), these effects can enhance nitrogen acquisition, creating negative feedbacks that help maintain plant nitrogen supply.

calculate_NflxPU_req_avail_def(CflxNPP, CflxNPP0, NflxAD, NflxFT, dT)

Calculate required, available, and deficit nitrogen for plant uptake.

This method diagnoses the nitrogen budget specifically for plant uptake by comparing the nitrogen required for plant uptake (based on stoichiometric requirements for NPP) with the nitrogen available for plant uptake (from mineralization and external inputs). The plant uptake deficit determines whether plants have sufficient nitrogen to support their carbon uptake and is used to calculate feedback effects on various carbon-nitrogen processes.

The calculation uses potential NPP (NPP without nitrogen limitation) to determine nitrogen requirement, ensuring that the deficit calculation is independent of the current nitrogen limitation state. This allows for proper feedback dynamics in carbon-nitrogen coupling.

Parameters:

• CflxNPP (Quantity) – Net primary production carbon flux [GtC/yr]. This should be potential NPP (NPPpot) calculated with no nitrogen limitation effect (ε_N(NPP) = 1) to properly determine nitrogen requirement independent of current limitation.

• CflxNPP0 (Quantity) – Initial/reference net primary production carbon flux [GtC/yr]. Used to normalize NPP changes for long-term mineralization calculation.

• NflxAD (Quantity) – Nitrogen deposition flux [GtN/yr]. Atmospheric nitrogen deposition from anthropogenic and natural sources. All deposition is assumed to be immediately available for plant uptake.

• NflxFT (Quantity) – Nitrogen fertilizer flux [GtN/yr]. Direct fertilizer application (currently not used in calculation but included for future extension).

• dT (Quantity) – Temperature change relative to reference [K]. Used to calculate temperature-dependent mineralization.

Returns:

Dict[str, Quantity] – Dictionary with keys:

• NflxPUreq: Required nitrogen for plant uptake [GtN/yr]

• NflxPUavail: Total available nitrogen for plant uptake [GtN/yr]

• NflxPUavail_netMIN: Available nitrogen from net mineralization [GtN/yr]

• NflxPUdef: Nitrogen deficit (positive means demand exceeds supply) [GtN/yr]

Notes

The following formulas are used:

Nitrogen Required for Plant Uptake:

\[PUreq = NPPpot \times NCratio\]

where : math:NPPpot is the potential NPP (calculated without nitrogen limitation) and \(NCratio\) is the required nitrogen-to-carbon ratio (NCratio_PUreq). This reflects the requirement for plants to maintain specific carbon-to-nitrogen stoichiometry during carbon assimilation.

Nitrogen Available for Plant Uptake:

Nitrogen availability comes from two sources: atmospheric deposition and net mineralization. The net mineralization available for plant uptake (NetMIN) is separated into two components:

\[PUavail = AD + NetMIN0 \times e^{dT \times s_{netmin2dT}} + NetMINlt_0 \times e^{AD \times s_{netmin2AD}} \times \frac{NPPpot}{NPP0}\]

where:

• \(AD\) is atmospheric nitrogen deposition (assumed immediately available)

• \(NetMIN0\) is the baseline short-term net mineralization rate

• \(s_(netmin2dT)\) is the temperature sensitivity (sns_NetMIN2dT)

• \(dT\) is the temperature change

• \(NetMINlt0\) is the baseline long-term net mineralization rate

• \(s_{netmin2AD}\) is the sensitivity to nitrogen deposition (sns_NetMINlt2AD)

Components of Net Mineralization:

1. Short-term component (\(NetMIN_0 \times e^{dT \times sns_T}\)): Represents the portion of current net mineralization available for plant uptake from fast-turnover organic matter pools. Temperature-dependent because decomposition rates increase with warming.

2. Long-term component (\(NetMINlt0 \times e^{AD \times s_{netmin2AD}} \times \frac{NPPpot}{NPP0}\)): Represents nitrogen that accumulates in the mineral nitrogen pool (from the long-term past) and becomes available for plant uptake in the current timestep. Scaled by:

   • \(NPPpot/NPP0\) ratio: Higher NPP produces more organic matter substrate for decomposition/mineralization, controlling the baseline rate for long-term net mineralization

   • Exponential response to AD: Incorporates that net mineralization (mineralization - immobilization) is nitrogen-demanding, with deposition affecting the balance through priming effects (Cheng et al., 2019)

Plant Uptake Deficit:

\[PUdef = PUreq - PUavail\]

The plant uptake deficit represents the balance between nitrogen required and nitrogen available specifically for the plant uptake process:

• When \(PUdef > 0\): Nitrogen required exceeds availability, indicating nitrogen limitation on plant growth

• When \(PUdef < 0\): Nitrogen available exceeds requirement, indicating nitrogen surplus

This deficit is a key diagnostic variable used in nitrogen effect calculation to determine compensatory responses in various carbon-nitrogen processes (see methods in EffectCarbonNitrogenCouplingCalculator). The nitrogen effect on NPP follows an exponential response: \(\epsilon_{N(NPP)} = e^{s_{ NPP2PUdef} \times PUdef}\), where the resulting effect is used to calculate actual NPP from potential NPP.

This formulation does not explicitly represent the full ecosystem mineral nitrogen budget, which would include additional fluxes such as microbial immobilization, denitrification, and leaching. Net mineralization implicitly accounts for the balance between gross mineralization and microbial immobilization, while other nitrogen losses are not directly modeled in this simplified framework.

Methodological Rationale for the Flux-Based Approximation:

The parameterization of PUavail effectively approximates mineral nitrogen availability for plant uptake without explicitly relying on the current mineral nitrogen pool size. This flux-based approximation is necessary for representing nitrogen deficit at an annual timestep without modeling sub-annual dynamics of mineral nitrogen processes.

In complex carbon-nitrogen models, nitrogen availability is typically based on the current mineral nitrogen pool size (mass unit), and nitrogen requirement is computed from integrated fluxes in a given timestep (mass unit) (Thornton et al., 2007; Wiltshire et al., 2021; Zaehle et al., 2014). Competition from microbial immobilization is also considered in some complex models. However, in a model with an annual timestep like CNit, such a pool-based system would be inherently unstable: the mineral nitrogen pool size would be orders of magnitude smaller than the annual nitrogen demand, since the turnover time of the mineral nitrogen pool is substantially shorter than the annual timestep.

While the full ecosystem mineral nitrogen budget is usually balanced over long timescales (annual in CNit), short-term imbalances are the key that determines nutrient limitation on processes. To represent this effect, we transform the mineral nitrogen availability from a pool size basis to a flux basis by estimating the net mineralization fluxes that would be available for plant uptake over a year. This flux-based approach allows us to compare nitrogen supply and demand on comparable annual timescales, capturing the essential dynamics of nitrogen limitation without explicitly modeling the rapid turnover of mineral nitrogen pools.

class cnit.physics.nitrogen_cycle.NitrogenTurnoverCalculator

Bases: object

Calculator for nitrogen turnover processes in terrestrial pools.

This calculator determines nitrogen fluxes between different pools in the terrestrial nitrogen cycle based on pool sizes, turnover times, and environmental effects. The turnover processes include:

• Plant nitrogen turnover (nLP): Transfer from plant to litter pool

• Litter nitrogen decomposition (nLD): Transfer from litter to soil pool

• Soil nitrogen turnover (nSR): Release from soil organic matter

• Mineral nitrogen loss (nLS): Gaseous and leaching losses from mineral pool

Each flux is controlled by pool size, baseline turnover time, and environmental effects including temperature, nitrogen availability, and land use change.

tau_NplsP: Quantity

Plant nitrogen pool turnover time under reference conditions [yr].

Determines the baseline rate at which nitrogen is transferred from plant biomass to litter through senescence and mortality.

tau_NplsL: Quantity

Litter nitrogen pool turnover time under reference conditions [yr].

Determines the baseline rate at which nitrogen is released from litter and transferred to soil organic matter through decomposition.

tau_NplsS: Quantity

Soil nitrogen pool turnover time under reference conditions [yr].

Determines the baseline rate at which nitrogen is released from soil organic matter through decomposition and mineralization processes.

tau_NplsM: Quantity

Mineral nitrogen pool turnover time under reference conditions [yr].

Determines the baseline rate at which mineral nitrogen is lost from the system through gaseous emissions (denitrification, volatilization) and leaching.

frc_nLSgas: Quantity

Fraction of mineral nitrogen loss occurring as gaseous loss [dimensionless]. Partitions total mineral nitrogen loss between gaseous pathways (denitrification, volatilization) and leaching. Values range from 0 (all leaching) to 1 (all gaseous). Only gaseous losses are temperature-sensitive in this formulation.

calculate_nLPLDSR(NplsP, NplsL, NplsS, eff_dT_nLP, eff_dT_nLD, eff_dT_nSR, eff_N_nLP, eff_N_nLD, eff_N_nSR, eff_LU_nLP, eff_LU_nLD, eff_LU_nSR)

Calculate nitrogen turnover fluxes from plant, litter, and soil nitrogen pools based on pool sizes, turnover times, and environmental effect factors.

Parameters:

• NplsP (Quantity) – Plant nitrogen pool size [GtN]. Total nitrogen contained in living plant biomass.

• NplsL (Quantity) – Litter nitrogen pool size [GtN]. Total nitrogen contained in dead plant material (litter).

• NplsS (Quantity) – Soil nitrogen pool size [GtN]. Total nitrogen contained in soil organic matter.

• eff_dT_nLP (Quantity) – Temperature effect on litter production nitrogen turnover [dimensionless].

• eff_dT_nLD (Quantity) – Temperature effect on litter decomposition nitrogen turnover [dimensionless].

• eff_dT_nSR (Quantity) – Temperature effect on soil nitrogen turnover [dimensionless].

• eff_N_nLP (Quantity) – Carbon-nitrogen coupling effect on plant-to-litter turnover [dimensionless].

• eff_N_nLD (Quantity) – Carbon-nitrogen coupling effect on litter decomposition [dimensionless].

• eff_N_nSR (Quantity) – Carbon-nitrogen coupling effect on soil nitrogen turnover [dimensionless].

• eff_LU_nLP (Quantity) – Land use effect on litter production nitrogen turnover [dimensionless].

• eff_LU_nLD (Quantity) – Land use effect on litter decomposition nitrogen turnover [dimensionless].

• eff_LU_nSR (Quantity) – Land use effect on soil respiration nitrogen turnover [dimensionless].

Returns:

Dict[str, Quantity] – Dictionary with keys:

• NflxLP: Nitrogen flux from litter production [GtN/yr]

• NflxLD: Nitrogen flux from litter decomposition [GtN/yr]

• NflxSR: Nitrogen flux from soil respiration [GtN/yr]

Notes

The following formulas are used:

\[ \begin{align}\begin{aligned}nLP = \frac{N_P}{\tau_{N_P}} \times \epsilon_{T(nLP)} \times \epsilon_{N(nLP)} \times \epsilon_{LU(nLP)}\\nLD = \frac{N_L}{\tau_{N_L}} \times \epsilon_{T(nLD)} \times \epsilon_{N(nLD)} \times \epsilon_{LU(nLD)}\\nSR = \frac{N_S}{\tau_{N_S}} \times \epsilon_{T(nSR)} \times \epsilon_{N(nSR)} \times \epsilon_{LU(nSR)}\end{aligned}\end{align} \]

where:

• \(N_P\), \(N_L\), \(N_S\) are the plant, litter, and soil nitrogen pool sizes

• \(\tau_{N_P}\), \(\tau_{N_L}\), \(\tau_{N_S}\) are the respective turnover times

• \(\epsilon_{T}\) represents temperature effects

• \(\epsilon_{N}\) represents carbon-nitrogen coupling effects

• : math:epsilon_{LU} represents land use effects

Each flux is calculated using first-order kinetics where the turnover rate equals pool size divided by turnover time, modified by environmental effects. This formulation assumes that turnover processes follow exponential decay dynamics at baseline conditions, with multiplicative effects from environmental factors.

calculate_nLS(NplsM, eff_dT_nLSgas)

Calculate nitrogen loss flux from the mineral nitrogen pool.

This method calculates total nitrogen loss from the mineral pool through two pathways: gaseous losses (denitrification and volatilization) and leaching. Only gaseous losses are assumed to be temperature-sensitive.

Parameters:

• NplsM (Quantity) – Mineral nitrogen pool size [GtN]. Total plant-available mineral nitrogen in the soil.

• eff_dT_nLSgas (Quantity) – Temperature effect on gaseous nitrogen loss from mineral pool [dimensionless]. Values > 1 indicate enhanced gaseous losses with warming. Only affects the gaseous component of total losses.

Returns:

Dict[str, Quantity] – Dictionary with keys:

• NflxLS: Total nitrogen loss from mineral pool [GtN/yr]

Notes

The following formula is used:

\[nLS = \frac{N_M}{\tau_{N_M}} \times \left( f_{gas} \times \epsilon_{T(nLSgas)} + (1 - f_{gas}) \right)\]

where:

• \(N_M\) is the mineral nitrogen pool size

• \(\tau_{N_M}\) is the mineral nitrogen pool turnover time

• \(f_{gas}\) is the fraction of losses occurring as gaseous emissions (frc_nLSgas)

• \(\epsilon_{T(nLSgas)}\) is the temperature effect on gaseous losses

• \((1 - f_{gas})\) represents the leaching fraction, which is assumed temperature-insensitive

The total loss is partitioned between:

1. Gaseous losses (\(f_{gas}\) fraction): Temperature-sensitive losses through denitrification (conversion to N₂, N₂O, NO) and ammonia volatilization. These processes are enhanced by warming.

2. Leaching losses (\(1 - f_{gas}\) fraction): Temperature-insensitive losses through nitrate leaching and dissolved organic nitrogen export. These are primarily controlled by hydrology rather than temperature.

This formulation uses first-order kinetics for baseline losses with differential temperature sensitivity for the two loss pathways, reflecting their different controlling mechanisms.

class cnit.physics.nitrogen_cycle.NitrogenCycleCalculator

Bases: object

Calculator for terrestrial nitrogen cycle dynamics.

This class handles the complete nitrogen cycle by tracking nitrogen transfers between pools and calculating pool dynamics. The nitrogen cycle includes four main pools:

• Plant nitrogen pool (NplsP): Nitrogen in living plant biomass

• Litter nitrogen pool (NplsL): Nitrogen in dead plant material

• Soil nitrogen pool (NplsS): Nitrogen in soil organic matter

• Mineral nitrogen pool (NplsM): Plant-available inorganic nitrogen

Key processes include:

• External inputs: Biological nitrogen fixation (BNF), atmospheric deposition (AD), and fertilizer application (FT)

• Plant uptake (PU): Transfer from mineral to organic pools

• Organic matter turnover: Litter production (nLP), litter decomposition (nLD), and soil respiration (nSR)

• Mineralization: Release of mineral nitrogen from organic matter decomposition

• Losses: Gaseous emissions and leaching (nLS)

• Land use changes: Gross deforestation (nLUgrs) and direct mineral loss (nLUmin)

Each input flux is partitioned among pools using empirically-derived fractions that represent the distribution of nitrogen through different pathways in the terrestrial biosphere. These fractions account for the cascade of nitrogen through multiple pools within the annual timestep, capturing both immediate allocation and subsequent rapid turnover processes.

frc_BNF2P: Quantity

Fraction of biological nitrogen fixation allocated to plant pool [dimensionless].

Represents the portion of newly fixed nitrogen directly incorporated into plant biomass through symbiotic associations (e.g., legume-rhizobia symbiosis) or free-living fixers in the rhizosphere.

frc_BNF2L: Quantity

Fraction of biological nitrogen fixation allocated to litter pool [dimensionless].

Represents newly fixed nitrogen that enters the litter pool within the annual timestep through rapid plant-to-litter turnover (e.g., fine root turnover, leaf senescence of N-fixing plants). The remainder (1 - frc_BNF2P - frc_BNF2L) goes to the soil pool, representing nitrogen that cycles through both plant and litter pools and enters soil within the annual timestep.

frc_PU2P: Quantity

Fraction of plant nitrogen uptake allocated to plant pool [dimensionless].

Represents nitrogen remaining in plant biomass at the end of the annual timestep, primarily in long-lived tissues (wood, structural tissues, storage organs) that do not turn over within the year.

frc_PU2L: Quantity

Fraction of plant nitrogen uptake allocated to litter pool [dimensionless].

Represents nitrogen that cycles from mineral pool to plant and then to litter within the annual timestep through rapid turnover of short-lived tissues (fine roots, senescing leaves, reproductive structures). The remainder (1 - frc_PU2P - frc_PU2L) goes to the soil pool, representing nitrogen that cascades through plant, litter, and into soil within the annual timestep.

frc_nLP2L: Quantity

Fraction of litter production nitrogen retained in litter pool [dimensionless].

Represents nitrogen in plant materials that remain in the litter pool at the end of the annual timestep as recognizable plant structures. The remainder (1 - frc_nLP2L) goes directly to soil, representing materials that decompose rapidly and enter the soil pool within the annual timestep, bypassing extended residence in the litter stage.

frc_nLD2S: Quantity

Fraction of litter decomposition nitrogen transferred to soil pool [dimensionless].

Represents nitrogen incorporated into stable soil organic matter during decomposition. The remainder (1 - frc_nLD2S) is mineralized to the mineral pool (nLD2M), representing nitrogen released as plant-available forms (NH₄⁺, NO₃⁻) during litter breakdown.

frc_nLSgas: Quantity

Fraction of mineral nitrogen loss occurring as gaseous emissions [dimensionless].

Partitions mineral nitrogen losses between gaseous pathways (denitrification producing N₂, N₂O, NO; ammonia volatilization) and leaching (nitrate leaching, dissolved organic nitrogen export). Values range from 0 (all leaching) to 1 (all gaseous).

frc_nLUgrs2P: Quantity

Fraction of gross deforestation nitrogen loss from plant pool [dimensionless].

Represents the distribution of nitrogen lost during land conversion, with this fraction coming from plant biomass removal or burning.

frc_nLUgrs2L: Quantity

Fraction of gross deforestation nitrogen loss from litter pool [dimensionless].

Represents nitrogen lost from litter during land conversion. The remainder (1 - frc_nLUgrs2P - frc_nLUgrs2L) comes from the soil pool.

calculate_dNplsPLS_dt(NflxPU, NflxBNF, NflxLP, NflxLD, NflxSR, NflxLUgrs)

Calculate rate of change for plant, litter, and soil nitrogen pools.

This method computes the time derivatives of organic nitrogen pools based on inputs (BNF, PU), internal transfers (nLP, nLD), outputs (nSR), and land use changes (nLUgrs). Each input flux is partitioned among pools according to the fractional allocation parameters, which account for nitrogen cascading through multiple pools within the annual timestep.

Parameters:

• NflxPU (Quantity) – Plant nitrogen uptake flux [GtN/yr]. Total uptake from mineral pool.

• NflxBNF (Quantity) – Biological nitrogen fixation flux [GtN/yr]. New nitrogen entering system from atmospheric N₂.

• NflxLP (Quantity) – Litter production flux [GtN/yr]. Nitrogen transfer from plant to litter through senescence and mortality.

• NflxLD (Quantity) – Litter decomposition flux [GtN/yr]. Nitrogen release from litter through decomposition.

• NflxSR (Quantity) – Soil respiration flux [GtN/yr]. Nitrogen release from soil organic matter through decomposition (also called soil turnover).

• NflxLUgrs (Quantity) – Gross deforestation nitrogen flux [GtN/yr]. Nitrogen lost from system due to land conversion.

Returns:

List[Quantity] – List containing:

• dNplsP_dt: Rate of change of plant nitrogen pool [GtN/yr]

• dNplsL_dt: Rate of change of litter nitrogen pool [GtN/yr]

• dNplsS_dt: Rate of change of soil nitrogen pool [GtN/yr]

Notes

The pool dynamics follow mass balance equations:

Plant Pool:

\[\frac{dN_P}{dt} = BNF \times f_{BNF2P} + PU \times f_{PU2P} - nLP - nLUgrs \times f_{nLUgrs2P}\]

Litter Pool:

\[\frac{dN_L}{dt} = BNF \times f_{BNF2L} + PU \times f_{PU2L} + nLP \times f_{nLP2L} - nLD - nLUgrs \times f_{nLUgrs2L}\]

Soil Pool:

\[\frac{dN_S}{dt} = BNF \times f_{BNF2S} + PU \times f_{PU2S} + nLP \times f_{nLP2S} + nLD \times f_{nLD2S} - nSR - nLUgrs \times f_{nLUgrs2S}\]

where:

• \(f_{BNF2S} = 1 - f_{BNF2P} - f_{BNF2L}\) represents BNF nitrogen cascading through plant→litter→soil within the annual timestep

• \(f_{PU2S} = 1 - f_{PU2P} - f_{PU2L}\) represents uptake nitrogen cascading through plant→litter→soil within the annual timestep

• \(f_{nLP2S} = 1 - f_{nLP2L}\) represents rapid litter decomposition directly entering soil within the annual timestep

• \(f_{nLUgrs2S} = 1 - f_{nLUgrs2P} - f_{nLUgrs2L}\) (remainder from soil)

Important Note on Annual Timestep:

All allocation fractions account for the cascade of nitrogen through multiple pools within the annual timestep. For example, \(f_{PU2S}\) does not represent direct allocation from mineral to soil, but rather nitrogen that is taken up by plants, then enters litter through turnover, and subsequently enters soil through decomposition—all within a single year. This approach effectively captures rapid cycling processes without explicitly modeling sub-annual dynamics.

calculate_dNplsM_dt(NflxPU, NflxNetMIN, NflxLS, NflxAD, NflxFT, NflxLUmin)

Calculate rate of change for mineral nitrogen pool.

This method computes the time derivative of the mineral nitrogen pool based on inputs (AD, FT, NetMIN), outputs (PU, nLS), and land use changes (nLUmin).

Parameters:

• NflxPU (Quantity) – Plant nitrogen uptake flux [GtN/yr]. Removal of mineral N by plants.

• NflxNetMIN (Quantity) – Net mineralization flux [GtN/yr]. Release of mineral nitrogen from organic matter decomposition (mineralization minus microbial immobilization).

• NflxLS (Quantity) – Nitrogen loss flux from mineral pool [GtN/yr]. Combined gaseous and leaching losses.

• NflxAD (Quantity) – Atmospheric deposition flux [GtN/yr]. External input from wet and dry deposition.

• NflxFT (Quantity) – Fertilizer application flux [GtN/yr]. Anthropogenic input from agricultural fertilization.

• NflxLUmin (Quantity) – Direct mineral nitrogen loss from land use change [GtN/yr]. Mineral N lost during land conversion events.

Returns:

List[pint. Quantity] – List containing [dNplsM_dt] in units of [GtN/yr].

Notes

The mineral pool dynamics follow a mass balance equation:

\[\frac{dN_M}{dt} = AD + FT + NetMIN - PU - nLS - nLUmin\]

where:

• \(AD\) is atmospheric deposition

• \(FT\) is fertilizer application

• \(NetMIN\) is net mineralization (gross mineralization - immobilization)

• \(PU\) is plant uptake

• \(nLS\) is total loss (gaseous + leaching)

• \(nLUmin\) is land use-induced loss

The mineral nitrogen pool represents plant-available inorganic nitrogen (primarily NH₄⁺ and NO₃⁻) and typically has rapid turnover relative to organic pools. This pool mediates the coupling between organic nitrogen cycling and plant nitrogen demand.

calculate_Nflx_all(NflxPU, NflxBNF, NflxLP, NflxLD, NflxSR, NflxLS, NflxAD, NflxFT, NflxLUgrs, NflxLUmin)

Calculate all nitrogen fluxes and their partitioning in the system.

This method computes the complete set of nitrogen fluxes including all partitioned flows between pools. Useful for detailed budget analysis and diagnostic output.

Parameters:

• NflxPU (Quantity) – Plant nitrogen uptake flux [GtN/yr].

• NflxBNF (Quantity) – Biological nitrogen fixation flux [GtN/yr].

• NflxLP (Quantity) – Litter production flux [GtN/yr].

• NflxLD (Quantity) – Litter decomposition flux [GtN/yr].

• NflxSR (Quantity) – Soil respiration flux [GtN/yr] (also called soil turnover).

• NflxLS (Quantity) – Nitrogen loss flux [GtN/yr].

• NflxAD (Quantity) – Atmospheric deposition flux [GtN/yr].

• NflxFT (Quantity) – Fertilizer application flux [GtN/yr].

• NflxLUgrs (Quantity) – Gross deforestation nitrogen flux [GtN/yr].

• NflxLUmin (Quantity) – Direct mineral nitrogen loss from land use [GtN/yr].

Returns:

Dict[str, Quantity] – Dictionary containing all nitrogen fluxes and their partitioned components:

• Primary fluxes: NflxPU, NflxBNF, NflxLP, NflxLD, NflxSR, NflxLS, NflxAD, NflxFT, NflxLUgrs, NflxLUmin

• PU partitioning: NflxPU2P, NflxPU2L, NflxPU2S

• BNF partitioning: NflxBNF2P, NflxBNF2L, NflxBNF2S

• LP partitioning: NflxLP2L, NflxLP2S

• LD partitioning: NflxLD2S, NflxLD2M

• LUgrs partitioning: NflxLUgrs2P, NflxLUgrs2L, NflxLUgrs2S

• Derived flux: NflxNetMIN (total net mineralization = nLD2M + nSR)

Notes

Net mineralization (NetMIN) is calculated as:

\[NetMIN = nLD_{2M} + nSR\]

where:

• \(nLD_{2M} = nLD \times (1 - f_{nLD2S})\) is litter decomposition to mineral

• \(nSR\) is soil respiration (all assumed to mineralize)

This represents the total flux of nitrogen from organic to mineral forms, which is the internal source of plant-available nitrogen in the system.

class cnit.physics.nitrogen_cycle.NitrogenCycleModelResult

Bases: object

Results from running the nitrogen cycle model.

This class stores the complete output from a nitrogen cycle model simulation, including nitrogen pool states, fluxes, and all environmental effect modifiers. Results can be converted to an xarray Dataset for analysis and visualization.

The nitrogen cycle model tracks four terrestrial nitrogen pools:

• Plant nitrogen pool (NplsP): Nitrogen in living plant biomass

• Litter nitrogen pool (NplsL): Nitrogen in dead plant material

• Soil nitrogen pool (NplsS): Nitrogen in soil organic matter

• Mineral nitrogen pool (NplsM): Plant-available inorganic nitrogen

Key processes represented include:

• External inputs: Biological nitrogen fixation (BNF), atmospheric deposition (AD), and fertilizer application (FT)

• Plant uptake (PU): Transfer from mineral to organic pools

• Organic matter turnover (nLP, nLD, nSR)

• Mineral nitrogen losses (nLS): Gaseous emissions and leaching

• Land use changes: Gross deforestation (nLUgrs) and mineral losses (nLUmin)

• Environmental modifiers: temperature, nitrogen, and land use effects

Note:

All _t attributes are time-continuous functions created through linear interpolation of discrete time points. These functions map from time [yr] to their respective units, allowing for smooth temporal interpolation of forcing data and effect modifiers.

n_state: Dict[str, Quantity]

Nitrogen pool states over time [GtN].

Dictionary containing time series of nitrogen pools: - ‘NplsP’: Plant nitrogen pool - ‘NplsL’: Litter nitrogen pool - ‘NplsS’: Soil nitrogen pool - ‘NplsM’: Mineral nitrogen pool

calc_n_turnover: NitrogenTurnoverCalculator

Calculator for nitrogen turnover processes.

Instance of NitrogenTurnoverCalculator containing turnover time parameters and methods for calculating organic matter breakdown and mineral N loss fluxes (nLP, nLD, nSR, nLS).

calc_n_cycle: NitrogenCycleCalculator

Calculator for nitrogen cycle mass balance.

Instance of NitrogenCycleCalculator containing allocation fractions and methods for calculating flux partitioning and pool dynamics.

time_axis: Quantity

Time points for simulation [yr].

Array of discrete time points at which the model state is evaluated, typically representing annual timesteps.

NflxPU_t: Callable[[Quantity], Quantity]

Time-interpolated plant nitrogen uptake flux function [GtN/yr].

Continuous function mapping time to plant uptake flux. Interpolated from discrete forcing data to allow smooth temporal variation.

NflxBNF_t: Callable[[Quantity], Quantity]

Time-interpolated biological nitrogen fixation flux function [GtN/yr].

Continuous function mapping time to BNF flux. Represents new nitrogen entering the system from atmospheric N₂. Interpolated from discrete forcing data.

NflxAD_t: Callable[[Quantity], Quantity]

Time-interpolated atmospheric nitrogen deposition flux function [GtN/yr].

Continuous function mapping time to deposition flux. Represents external nitrogen input from wet and dry deposition. Interpolated from discrete forcing data.

NflxFT_t: Callable[[Quantity], Quantity]

Time-interpolated fertilizer application flux function [GtN/yr].

Continuous function mapping time to fertilizer flux. Represents anthropogenic nitrogen input from agricultural fertilization. Interpolated from discrete forcing data.

NflxLUgrs_t: Callable[[Quantity], Quantity]

Time-interpolated gross land use change nitrogen flux function [GtN/yr].

Continuous function mapping time to land use emissions. Represents nitrogen lost from organic pools during land conversion (deforestation, agricultural expansion). Interpolated from discrete forcing data.

NflxLUmin_t: Callable[[Quantity], Quantity]

Time-interpolated land use mineral nitrogen loss flux function [GtN/yr].

Continuous function mapping time to direct mineral nitrogen losses. Represents mineral N lost during land conversion events. Interpolated from discrete forcing data.

eff_dT_nLP_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on litter production function [dimensionless].

Continuous function mapping time to temperature modifier for plant-to-litter nitrogen turnover. Interpolated from calculated temperature effects.

eff_dT_nLD_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on litter decomposition function [dimensionless].

Continuous function mapping time to temperature modifier for litter-to-soil nitrogen turnover. Interpolated from calculated temperature effects.

eff_dT_nSR_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on soil respiration function [dimensionless].

Continuous function mapping time to temperature modifier for soil organic nitrogen turnover. Interpolated from calculated temperature effects.

eff_dT_nLSgas_t: Callable[[Quantity], Quantity]

Time-interpolated temperature effect on gaseous nitrogen losses function [dimensionless].

Continuous function mapping time to temperature modifier for gaseous emissions (denitrification, volatilization) from the mineral nitrogen pool. Interpolated from calculated temperature effects.

eff_N_nLP_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on litter production function [dimensionless].

Continuous function mapping time to nitrogen modifier for plant-to-litter nitrogen turnover. Represents carbon-nitrogen coupling effects on plant tissue turnover. Interpolated from calculated nitrogen effects.

eff_N_nLD_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on litter decomposition function [dimensionless].

Continuous function mapping time to nitrogen modifier for litter decomposition. Represents how nitrogen availability affects decomposer activity. Interpolated from calculated nitrogen effects.

eff_N_nSR_t: Callable[[Quantity], Quantity]

Time-interpolated nitrogen effect on soil respiration function [dimensionless].

Continuous function mapping time to nitrogen modifier for soil organic nitrogen turnover. Represents carbon-nitrogen coupling in soil processes. Interpolated from calculated nitrogen effects.

eff_LU_nLP_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on litter production function [dimensionless].

Continuous function mapping time to land use modifier for plant-to-litter nitrogen turnover. Represents how land use change affects plant mortality rates. Interpolated from calculated land use effects.

eff_LU_nLD_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on litter decomposition function [dimensionless].

Continuous function mapping time to land use modifier for litter decomposition. Represents how land use change affects litter breakdown rates. Interpolated from calculated land use effects.

eff_LU_nSR_t: Callable[[Quantity], Quantity]

Time-interpolated land use effect on soil respiration function [dimensionless].

Continuous function mapping time to land use modifier for soil organic nitrogen turnover. Represents how land use change affects soil nitrogen dynamics. Interpolated from calculated land use effects.

add_non_state_variables()

Calculate derived variables and create xarray Dataset with complete results.

This method computes all diagnostic fluxes and derived quantities from the model state variables and returns a complete xarray Dataset containing:

• State variables: Nitrogen pools (NplsP, NplsL, NplsS, NplsM)

• Turnover fluxes: Calculated from pools and environmental effects (nLP, nLD, nSR, nLS)

• All partitioned fluxes: PU, BNF, and land use change distributed among pools

• Derived quantities: Total organic nitrogen (NplsPLS), total terrestrial nitrogen (NplsPLSM), net terrestrial nitrogen flux (NflxNetPLSM)

• Net mineralization: Total nitrogen release from organic matter (NflxNetMIN)

Returns:

xr.Dataset – Complete model results as xarray Dataset with time dimension and all variables labeled with descriptive names and units. The Dataset includes:

State Variables:

• NplsP, NplsL, NplsS, NplsM: Individual pool sizes [GtN]

• NplsPLS: Total organic nitrogen (plant + litter + soil) [GtN]

• NplsPLSM: Total terrestrial nitrogen (organic + mineral) [GtN]

Primary Fluxes:

• NflxPU: Plant nitrogen uptake [GtN/yr]

• NflxBNF: Biological nitrogen fixation [GtN/yr]

• NflxAD: Atmospheric deposition [GtN/yr]

• NflxFT: Fertilizer application [GtN/yr]

• NflxLP: Litter production [GtN/yr]

• NflxLD: Litter decomposition [GtN/yr]

• NflxSR: Soil respiration (soil turnover) [GtN/yr]

• NflxLS: Mineral nitrogen losses [GtN/yr]

• NflxLUgrs: Gross land use emissions [GtN/yr]

• NflxLUmin: Land use mineral nitrogen losses [GtN/yr]

Partitioned Fluxes:

• NflxPU2P, NflxPU2L, NflxPU2S: Plant uptake allocation to each pool

• NflxBNF2P, NflxBNF2L, NflxBNF2S: BNF allocation to each pool

• NflxLP2L, NflxLP2S: Litter production allocation

• NflxLD2S, NflxLD2M: Litter decomposition to soil and mineral

• NflxLUgrs2P, NflxLUgrs2L, NflxLUgrs2S: Land use emissions from each pool

Derived Fluxes:

• NflxNetMIN: Total net mineralization (nLD2M + nSR) [GtN/yr]

• NflxNetPLSM: Net change in total terrestrial nitrogen [GtN/yr]

Notes

The net terrestrial nitrogen flux is calculated using numerical differentiation:

\[nNetPLSM = \frac{dN_{PLSM}}{dt} = \frac{d(N_P + N_L + N_S + N_M)}{dt}\]

This represents the net nitrogen balance of the terrestrial biosphere, with positive values indicating nitrogen accumulation and negative values indicating nitrogen loss.

The net mineralization is calculated as:

\[NetMIN = nLD2M + nSR\]

where:

• \(nLD2M = nLD \times (1 - f_{nLD2S})\) is litter decomposition to mineral

• \(nSR\) is soil respiration (all assumed to mineralize)

This represents the total flux of nitrogen from organic to mineral forms, which is the internal source of plant-available nitrogen in the system.

class cnit.physics.nitrogen_cycle.NitrogenCycleModel

Bases: object

MAGICC’s terrestrial nitrogen cycle model (nitrogen component of CNit).

This model simulates the dynamics of four terrestrial nitrogen pools in the terrestrial biosphere by solving a system of ordinary differential equations (ODEs) using scipy.integrate.solve_ivp. The model tracks nitrogen transfers between pools through processes including:

• External inputs: Biological nitrogen fixation (BNF), atmospheric deposition (AD), and fertilizer application (FT)

• Plant uptake (PU): Transfer from mineral to organic pools

• Organic matter turnover (litter production, litter decomposition, soil respiration)

• Mineralization: Release of plant-available nitrogen from organic matter

• Mineral nitrogen losses: Gaseous emissions and leaching

• Land use changes: Gross deforestation and direct mineral losses

• Environmental modifiers (temperature, nitrogen availability, land use effects)

The model uses annual timesteps and accounts for rapid nitrogen cycling through empirical allocation fractions that represent nitrogen cascading through multiple pools within a year.

The nitrogen cycle is solved in two stages: (1) organic nitrogen pools (plant, litter, soil) are solved first, then (2) the mineral nitrogen pool is solved using net mineralization calculated from the organic pool dynamics.

Time-continuous functions (suffixed with _t) are generated through linear interpolation of discrete time points and provide continuous values over the simulation period, allowing the ODE solver to evaluate fluxes at any time point.

calc_n_turnover: NitrogenTurnoverCalculator

Calculator for nitrogen turnover processes.

Instance of NitrogenTurnoverCalculator containing turnover time parameters (tau_NplsP, tau_NplsL, tau_NplsS, tau_NplsM) and methods for calculating organic matter breakdown and mineral N loss fluxes based on pool sizes and environmental effects.

calc_n_cycle: NitrogenCycleCalculator

Calculator for nitrogen cycle mass balance.

Instance of NitrogenCycleCalculator containing allocation fractions (frc_BNF2P, frc_BNF2L, frc_PU2P, frc_PU2L, frc_nLP2L, frc_nLD2S, frc_nLSgas, frc_nLUgrs2P, frc_nLUgrs2L) and methods for calculating flux partitioning and pool dynamics.

NplsP0: Quantity

Initial plant nitrogen pool size [GtN].

Nitrogen contained in living plant biomass at the start of the simulation (time0). Typical values range from 3-6 GtN for global simulations.

NplsL0: Quantity

Initial litter nitrogen pool size [GtN].

Nitrogen contained in dead plant material (litter) at the start of the simulation (time0). Typical values range from 0.5-2 GtN for global simulations.

NplsS0: Quantity

Initial soil nitrogen pool size [GtN].

Nitrogen contained in soil organic matter at the start of the simulation (time0). Typical values range from 95-140 GtN for global simulations.

NplsM0: Quantity

Initial mineral nitrogen pool size [GtN].

Plant-available inorganic nitrogen (primarily NH₄⁺ and NO₃⁻) at the start of the simulation (time0). Typical values range from 0.01-0.1 GtN for global simulations. This pool has much faster turnover than organic pools.

time0: Quantity

Initialization time [yr].

Time point at which the initial pool sizes (NplsP0, NplsL0, NplsS0, NplsM0) apply. The simulation time_axis must start at or after this time. Typically set to the pre-industrial baseline year (1850).

switch_Npls: list[int]

Nitrogen pool switches for [plant, litter, soil, mineral] [dimensionless].

Binary switches (1=enabled, 0=disabled) to selectively enable or disable pool dynamics. Useful for diagnostic purposes or simplified model configurations. Setting a switch to 0 freezes that pool at its initial value.

• switch_Npls[0]: Plant pool switch

• switch_Npls[1]: Litter pool switch

• switch_Npls[2]: Soil pool switch

• switch_Npls[3]: Mineral pool switch

run(time_axis, NflxPU_t, NflxBNF_t, NflxAD_t, NflxFT_t, NflxLUgrs_t, NflxLUmin_t, eff_dT_nLP_t, eff_dT_nLD_t, eff_dT_nSR_t, eff_dT_nLSgas_t, eff_N_nLP_t, eff_N_nLD_t, eff_N_nSR_t, eff_LU_nLP_t, eff_LU_nLD_t, eff_LU_nSR_t)

Run the nitrogen cycle model simulation.

This method solves the nitrogen cycle in two stages using scipy.integrate.solve_ivp: (1) Solves organic nitrogen pools (plant, litter, soil) first, then (2) Solves mineral nitrogen pool using net mineralization from stage 1.

The solver uses time-continuous interpolated functions for all forcing data and environmental effects, allowing flexible time step selection during integration.

Parameters:

• time_axis (Quantity) – Time points for simulation [yr]. Must start at or after time0. These are the time points at which solution is explicitly evaluated.

• NflxPU_t (Callable[[Quantity], Quantity]) – Time-interpolated plant nitrogen uptake flux function [GtN/yr]. Maps time to uptake from mineral to organic pools.

• NflxBNF_t (Callable[[Quantity], Quantity]) – Time-interpolated biological nitrogen fixation flux function [GtN/yr]. Maps time to new nitrogen entering from atmospheric N₂.

• NflxAD_t (Callable[[Quantity], Quantity]) – Time-interpolated atmospheric deposition flux function [GtN/yr]. Maps time to external nitrogen input from wet and dry deposition.

• NflxFT_t (Callable[[Quantity], Quantity]) – Time-interpolated fertilizer application flux function [GtN/yr]. Maps time to anthropogenic nitrogen input from agriculture.

• NflxLUgrs_t (Callable[[Quantity], Quantity]) – Time-interpolated gross land use change flux function [GtN/yr]. Maps time to nitrogen lost from organic pools during land conversion.

• NflxLUmin_t (Callable[[Quantity], Quantity]) – Time-interpolated land use mineral loss flux function [GtN/yr]. Maps time to direct mineral nitrogen losses during land conversion.

• eff_dT_nLP_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on litter production function [dimensionless]. Maps time to temperature modifier for plant-to-litter turnover.

• eff_dT_nLD_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on litter decomposition function [dimensionless]. Maps time to temperature modifier for litter-to-soil turnover.

• eff_dT_nSR_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on soil respiration function [dimensionless]. Maps time to temperature modifier for soil organic nitrogen turnover.

• eff_dT_nLSgas_t (Callable[[Quantity], Quantity]) – Time-interpolated temperature effect on gaseous losses function [dimensionless]. Maps time to temperature modifier for denitrification and volatilization.

• eff_N_nLP_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on litter production function [dimensionless]. Maps time to nitrogen availability modifier for plant-to-litter turnover.

• eff_N_nLD_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on litter decomposition function [dimensionless]. Maps time to nitrogen availability modifier for litter decomposition.

• eff_N_nSR_t (Callable[[Quantity], Quantity]) – Time-interpolated nitrogen effect on soil respiration function [dimensionless]. Maps time to nitrogen availability modifier for soil nitrogen turnover.

• eff_LU_nLP_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on litter production function [dimensionless]. Maps time to land use modifier for plant-to-litter turnover.

• eff_LU_nLD_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on litter decomposition function [dimensionless]. Maps time to land use modifier for litter decomposition.

• eff_LU_nSR_t (Callable[[Quantity], Quantity]) – Time-interpolated land use effect on soil respiration function [dimensionless]. Maps time to land use modifier for soil nitrogen turnover.

Returns:

NitrogenCycleModelResult – Simulation results containing:

• Nitrogen pool time series (NplsP, NplsL, NplsS, NplsM)

• References to calculator instances

• All input forcing and effect functions

• Methods to calculate derived fluxes and diagnostics

Raises:

• ValueError – If time_axis starts before time0. The simulation cannot run backwards from the initialization time.

• SolveError – If the numerical ODE solver fails to converge. This can occur due to numerical instability, runaway feedbacks, or inappropriate tolerance settings.

Notes

Two-Stage Solution:

The nitrogen cycle is solved in two stages because the mineral pool depends on net mineralization from organic pools:

1. Stage 1 - Organic pools (plant, litter, soil):

\[ \begin{align}\begin{aligned}\frac{dN_P}{dt} = BNF \times f_{BNF2P} + PU \times f_{PU2P} - nLP - nLUgrs \times f_{nLUgrs2P}\\\frac{dN_L}{dt} = BNF \times f_{BNF2L} + PU \times f_{PU2L} + nLP \times f_{nLP2L} - nLD - nLUgrs \times f_{nLUgrs2L}\\\frac{dN_S}{dt} = BNF \times f_{BNF2S} + PU \times f_{PU2S} + nLP \times f_{nLP2S} + nLD \times f_{nLD2S} - nSR - nLUgrs \times f_{nLUgrs2S}\end{aligned}\end{align} \]

2. Stage 2 - Mineral pool:

After solving organic pools, net mineralization is calculated:

\[NetMIN = nLD_{2M} + nSR\]

where \(nLD_{2M} = nLD \times (1 - f_{nLD2S})\) is the mineralized fraction of litter decomposition.

Then the mineral pool is solved:

\[\frac{dN_M}{dt} = AD + FT + NetMIN - PU - nLS - nLUmin\]

where turnover fluxes (nLP, nLD, nSR, nLS) are calculated from pool sizes and environmental effects using first-order kinetics.

Numerical Methods:

Both stages use scipy.integrate.solve_ivp with:

• Adaptive time stepping (solver selects appropriate substeps)

• Absolute tolerance: 1e-6 GtN

• Relative tolerance: 1e-3

• Default solver method (typically RK45)

• Stage 2 uses max_step=2 yr for stability due to fast mineral pool turnover

Pool Switches:

Pool dynamics can be selectively disabled using switch_Npls. When a switch is set to 0, the corresponding pool’s rate of change is forced to zero, effectively freezing that pool at its initial value throughout the simulation. If the mineral pool switch is 0, the mineral pool is set to zero throughout.

Time-Continuous Functions:

All _t arguments are callable functions created through linear interpolation of discrete time points. This allows the ODE solver to evaluate forcing data and environmental effects at any time point during integration, not just at the discrete output times specified in time_axis.

Carbon-Nitrogen Cycle

Simulates the coupled carbon-nitrogen cycle processes.

MAGICC Coupled Carbon-Nitrogen Cycle Model (CNit) Implementation

class cnit.physics.carbon_nitrogen_cycle.CarbonNitrogenCycleModel

Bases: object

MAGICC’s coupled terrestrial carbon-nitrogen cycle model (CNit).

This is the top-level model class that integrates the carbon and nitrogen cycles with their environmental drivers and feedback mechanisms. The model simulates the full terrestrial biogeochemistry system including:

• Carbon cycle dynamics (3 pools: plant, litter, soil)

• Nitrogen cycle dynamics (4 pools: plant, litter, soil, mineral)

• Carbon-nitrogen coupling through:

  • Nitrogen limitation effects on carbon processes (NPP, decomposition)

  • Carbon-driven nitrogen demand (stoichiometric requirements)

  • Nitrogen deficit feedbacks

• Environmental responses:

  • CO2 fertilization effects on NPP

  • Temperature effects on all processes

  • Land use change impacts (deforestation, afforestation, regrowth)

The model operates on annual timesteps and solves the carbon and nitrogen cycles iteratively to capture their bidirectional coupling. A key feature is the explicit calculation of nitrogen deficit (difference between nitrogen required and available for plant uptake), which creates feedback loops regulating both carbon and nitrogen cycling.

Model Architecture:

The model consists of several interconnected calculator components:

• Land Use Calculator (LanduseCalculator): Processes land use change emissions and regrowth fluxes for both carbon and nitrogen

• Effect Calculators: Compute environmental modifiers

  • EffectCO2Calculator: CO2 fertilization effects

  • EffectTemperatureCalculator: Temperature effects on all processes

  • EffectCarbonNitrogenCouplingCalculator: C-N coupling effects

  • EffectLanduseCalculator: Land use effects on turnover rates

• Flux Calculators:

  • CarbonNPPLPRCalculator: NPP and LPR with environmental modifiers

  • NitrogenPUBNFCalculator: PU and BNF with nitrogen deficit feedbacks

• Cycle Models:

  • CarbonCycleModel: Solves carbon pool dynamics (3 pools)

  • NitrogenCycleModel: Solves nitrogen pool dynamics (4 pools)

Coupling Strategy:

The carbon and nitrogen cycles are coupled through an iterative approach:

1. Calculate potential NPP (without nitrogen limitation)

2. Calculate nitrogen requirement based on NPP and stoichiometry

3. Calculate nitrogen availability from mineralization and external inputs

4. Calculate nitrogen deficit (required - available)

5. Apply nitrogen limitation effect to get actual NPP

6. Calculate nitrogen uptake and fixation based on actual NPP

7. Solve carbon cycle with nitrogen effects

8. Solve nitrogen cycle with carbon-driven demand

This approach ensures that carbon and nitrogen dynamics are mutually consistent while avoiding numerical instability from simultaneous solution.

Configuration:

The model can be initialized in two ways:

• from_dict(): Build from a parameter dictionary

• from_config(): Build from a CarbonNitrogenCycleModelConfig dataclass

Both methods automatically distribute parameters to the appropriate sub-components.

calc_lu: LanduseCalculator

Calculator for land use fluxes.

Processes land use change emissions (gross deforestation, net emissions) and regrowth for both carbon and nitrogen cycles. Tracks cumulative land use changes for calculating land use effects on productivity.

calc_eff_CO2: EffectCO2Calculator

Calculator for CO2 fertilization effects.

Computes the enhancement of NPP due to elevated atmospheric CO2 concentration through increased photosynthetic efficiency and water use efficiency.

calc_eff_dT: EffectTemperatureCalculator

Calculator for temperature effects.

Computes temperature modifiers for all carbon and nitrogen processes including NPP, LPR, decomposition, mineralization, plant uptake, biological fixation, and gaseous losses.

calc_eff_CN: EffectCarbonNitrogenCouplingCalculator

Calculator for carbon-nitrogen coupling effects.

Computes nitrogen limitation effects on carbon processes (NPP, decomposition) and carbon availability effects on nitrogen processes (plant uptake, fixation) based on nitrogen deficit and NPP changes.

calc_eff_LU: EffectLanduseCalculator

Calculator for land use effects.

Computes land use change effects on process rates (turnover, decomposition) based on land use history (regrowth, deforestation, afforestation).

calc_npp_lpr: CarbonNPPLPRCalculator

Calculator for net primary production (NPP) and litter production respiration (LPR).

Computes carbon fixation by plants (NPP) and associated autotrophic respiration (LPR) with environmental modifiers (CO2, temperature, nitrogen, land use).

calc_pu_bnf: NitrogenPUBNFCalculator

Calculator for plant nitrogen uptake (PU) and biological nitrogen fixation (BNF).

Computes nitrogen inputs to organic pools through plant uptake from mineral pool and biological fixation from atmosphere, with environmental modifiers and nitrogen deficit feedbacks.

mdl_c_cycle: CarbonCycleModel

Carbon cycle model component.

Solves the carbon pool dynamics (plant, litter, soil) using ODE integration. Receives nitrogen limitation effects from nitrogen cycle and provides NPP for nitrogen demand calculation.

mdl_n_cycle: NitrogenCycleModel

Nitrogen cycle model component.

Solves the nitrogen pool dynamics (plant, litter, soil, mineral) using two-stage ODE integration. Receives carbon-driven nitrogen demand and provides nitrogen limitation effects to carbon cycle.

switch_N: Quantity

Switch to enable/disable nitrogen cycle [dimensionless].

Controls whether nitrogen limitation effects are applied to carbon cycle: - 1: Full carbon-nitrogen coupling (default) - 0: Carbon cycle only (no nitrogen limitation)

When set to 0, the model runs as a carbon-only model with no nitrogen feedbacks.

classmethod from_dict(params)

Build a fully configured CarbonNitrogenCycleModel from a parameter dictionary.

This factory method creates all calculator and model components, then distributes parameters from the dictionary to the appropriate components based on attribute names.

Parameters:

params (dict) – Parameter dictionary for configuring calculators and sub-models. Keys should match attribute names of calculator/model components. Unknown keys raise an error.

Returns:

CarbonNitrogenCycleModel – Fully configured model instance ready to run.

Raises:

ValueError – If params contains keys that don’t match any component attribute names.

Examples

>>> params = {
...     'NPP0': Q(50, 'GtC/yr'),
...     'tau_CplsP':  Q(10, 'yr'),
...     'NCratio_PUreq': Q(0.02, 'GtN/GtC'),
...     'switch_N': Q(1, '1'),
... }
>>> model = CarbonNitrogenCycleModel.from_dict(params)

classmethod from_config(config)

Build a fully configured CarbonNitrogenCycleModel from a config dataclass.

This is a convenience wrapper around : meth:from_dict that accepts a configuration dataclass instead of a dictionary.

Parameters:

config (CarbonNitrogenCycleModelConfig) – Configuration dataclass containing all model parameters.

Returns:

CarbonNitrogenCycleModel – Fully configured model instance ready to run.

See also

from_dict

Build model from parameter dictionary

CarbonNitrogenCycleModelConfig

Configuration dataclass definition

run_experiments(experiments)

” Run multiple experiments with the model.

This method facilitates running multiple model scenarios with different configurations and/or forcing data. Results from all experiments are concatenated into a single dataset with an ‘experiment’ dimension.

Parameters:

experiments (List[CarbonNitrogenCycleExperimentConfig]) – List of experiment configurations. Each experiment specifies forcing data, nitrogen switch setting, and a name for identification.

Returns:

xr.Dataset – Dataset containing results for all experiments, with an ‘experiment’ dimension for comparison. Variables are aligned across experiments using outer join (missing values filled with NaN).

Examples

>>> exp1 = CarbonNitrogenCycleExperimentConfig(
...     name="control",
...     switch_N=Q(1, "1"),
...     # ...  forcing data ...
... )
>>> exp2 = CarbonNitrogenCycleExperimentConfig(
...     name="no_nitrogen",
...     switch_N=Q(0, "1"),
...     # ... forcing data ...
... )
>>> results = model.run_experiments([exp1, exp2])
>>> control_npp = results.sel(experiment="control")["CflxNPP"]
>>> no_n_npp = results.sel(experiment="no_nitrogen")["CflxNPP"]

run(time_axis, dT_s, CO2_s, CemsLUnet_s, CemsLUgrs_s, NflxAD_s, NflxFT_s, NemsLUnet_s, NemsLUgrs_s, NemsLUmin_s)

Run the coupled carbon-nitrogen cycle model.

This is the main simulation method that:

1. Processes land use change forcing

2. Calculates potential and actual NPP with nitrogen limitation

3. Calculates nitrogen deficit and feedbacks

4. Solves carbon cycle with nitrogen effects

5. Solves nitrogen cycle with carbon-driven demand (if nitrogen cycle exists)

6. Returns combined results

Parameters:

• time_axis (Quantity) – Time points for simulation [yr]. Must start at or after initialization time (time0) specified in model components.

• dT_s (Quantity) – Time series of temperature anomaly relative to preindustrial [K].

• CO2_s (Quantity) – Time series of atmospheric CO2 concentration [ppm].

• CemsLUnet_s (Quantity) – Time series of net land use carbon emissions [GtC/yr]. Includes both gross emissions and regrowth.

• CemsLUgrs_s (Quantity) – Time series of gross land use carbon emissions [GtC/yr]. From deforestation and land conversion only.

• NflxAD_s (Quantity) – Time series of atmospheric nitrogen deposition flux [GtN/yr]. Includes both natural and anthropogenic sources.

• NflxFT_s (Quantity) – Time series of nitrogen fertilizer application flux [GtN/yr]. Anthropogenic nitrogen input from agriculture.

• NemsLUnet_s (Quantity) – Time series of net land use nitrogen emissions [GtN/yr]. Includes both gross emissions and regrowth.

• NemsLUgrs_s (Quantity) – Time series of gross land use nitrogen emissions from organic pools [GtN/yr]. From deforestation and land conversion.

• NemsLUmin_s (Quantity) – Time series of land use nitrogen emissions from mineral pool [GtN/yr]. Direct mineral nitrogen losses during land conversion.

Returns:

xr.Dataset – Complete simulation results containing:

Carbon Cycle Variables:

• Pool sizes: CplsP, CplsL, CplsS, CplsPLS

• Primary fluxes: CflxNPP, CflxNPPpot, CflxLPR, CflxLPRpot

• Turnover fluxes: CflxLP, CflxLD, CflxSR

• Partitioned fluxes: CflxNPP2P/L/S, CflxLP2L/S, CflxLD2S/A, CflxLUgrs2P/L/S

• Derived fluxes: CflxRH, CflxNetPLS

• Land use: CflxLUgrs, CflxLUrgr, cumulative land use changes

Nitrogen Cycle Variables (if switch_N=1):

• Pool sizes: NplsP, NplsL, NplsS, NplsM, NplsPLS, NplsPLSM

• Primary fluxes: NflxPU, NflxBNF, NflxAD, NflxFT

• Turnover fluxes: NflxLP, NflxLD, NflxSR, NflxLS

• Partitioned fluxes: NflxPU2P/L/S, NflxBNF2P/L/S, NflxLP2L/S, NflxLD2S/M, NflxLUgrs2P/L/S

• Derived fluxes: NflxNetMIN, NflxNetPLSM

• Nitrogen budget: NflxPUreq, NflxPUavail, NflxPUavail_netMIN, NflxPUdef

• Land use: NflxLUgrs, NflxLUmin

Notes

Solution Sequence:

The model solves carbon and nitrogen cycles in sequence to maintain consistency:

1. Calculate potential NPP: NPP without nitrogen limitation (ε_N = 1)

2. Calculate nitrogen budget: Required vs available nitrogen for plant uptake

3. Calculate nitrogen deficit: PUdef = PUreq - PUavail

4. Apply nitrogen limitation: Calculate actual NPP with nitrogen effect

5. Solve carbon cycle: With nitrogen effects on all processes

6. Solve nitrogen cycle: With carbon-driven demand

Nitrogen Limitation:

When switch_N = 1, nitrogen limitation affects carbon processes through:

\[NPP_{actual} = NPP_{potential} \times \epsilon_{N(NPP)}\]

where the nitrogen effect depends on nitrogen deficit:

\[\epsilon_{N(NPP)} = e^{s_{NPP2PUdef} \times PUdef}\]

Negative deficit (nitrogen surplus) can enhance NPP, while positive deficit (nitrogen limitation) reduces NPP.

Model Switches:

The behavior can be controlled through switches: - switch_N = 0: Carbon-only mode (no nitrogen limitation) - switch_Cpls = [0,0,0]: Freeze all carbon pools - switch_Npls = [0,0,0,0]: Freeze all nitrogen pools

See also

calculate_CflxNPPLPR_NflxPUBNF

Core coupling calculation

cnit.physics.carbon_cycle.CarbonCycleModel.run()

Carbon cycle solution

cnit.physics.nitrogen_cycle.NitrogenCycleModel.run()

Nitrogen cycle solution

calculate_CflxNPPLPR_NflxPUBNF(dT, CO2, CflxLUrgr, cumsum_CflxLUrgr, cumsum_CflxLUdfst, cumsum_CflxLUafst, cumsum_CflxLUafst_decay, NflxAD, NflxFT)

Calculate coupled carbon and nitrogen fluxes with nitrogen limitation feedback.

This is the core coupling method that implements the nitrogen limitation feedback on NPP. It follows a two-step approach:

1. Calculate potential fluxes (without nitrogen limitation):

   • Potential NPP and LPR assuming no nitrogen constraint

   • Nitrogen requirement based on potential NPP and stoichiometry

   • Nitrogen availability from mineralization and external inputs

   • Nitrogen deficit (required - available)

2. Calculate actual fluxes (with nitrogen limitation):

   • Apply nitrogen limitation effect to get actual NPP and LPR

   • Calculate nitrogen uptake and fixation based on actual conditions

This approach ensures that nitrogen limitation is calculated based on the system’s potential carbon uptake, while the actual fluxes reflect nitrogen constraints.

Parameters:

• dT (Quantity) – Temperature anomaly [K]. Used for temperature effects on all processes.

• CO2 (Quantity) – Atmospheric CO2 concentration [ppm]. Used for CO2 fertilization effect.

• CflxLUrgr (Quantity) – Land use regrowth carbon flux [GtC/yr]. Adds to baseline NPP.

• cumsum_CflxLUrgr (Quantity) – Cumulative land use regrowth [GtC]. Used for land use effects.

• cumsum_CflxLUdfst (Quantity) – Cumulative deforestation [GtC]. Used for land use effects.

• cumsum_CflxLUafst (Quantity) – Cumulative afforestation [GtC]. Used for land use effects.

• cumsum_CflxLUafst_decay (Quantity) – Cumulative afforestation with decay [GtC]. Used for land use effects.

• NflxAD (Quantity) – Atmospheric nitrogen deposition flux [GtN/yr]. External nitrogen input.

• NflxFT (Quantity) – Nitrogen fertilizer flux [GtN/yr]. Anthropogenic nitrogen input.

Returns:

Dictionary containing the following time series – Carbon Fluxes:

• CflxNPP: Actual (nitrogen-limited) net primary production [GtC/yr]

• CflxLPR: Actual (nitrogen-limited) litter production respiration [GtC/yr]

• CflxNPPpot: Potential (non-nitrogen-limited) NPP [GtC/yr]

• CflxLPRpot: Potential (non-nitrogen-limited) LPR [GtC/yr]

Nitrogen Fluxes:

• NflxPU: Plant nitrogen uptake [GtN/yr]

• NflxBNF: Biological nitrogen fixation [GtN/yr]

Nitrogen Budget:

• NflxPUreq: Nitrogen required for plant uptake [GtN/yr]

• NflxPUavail: Nitrogen available for plant uptake [GtN/yr]

• NflxPUavail_netMIN: N available from net mineralization [GtN/yr]

• NflxPUdef: Nitrogen deficit for plant uptake [GtN/yr]

Notes

Nitrogen Limitation Feedback:

The nitrogen limitation on NPP follows:

\[NPP_{actual} = NPP_{potential} \times \epsilon_{N(NPP)}\]

where the nitrogen effect depends on nitrogen deficit:

\[\epsilon_{N(NPP)} = e^{s_{NPP2PUdef} \times PUdef}\]

Nitrogen Budget:

Nitrogen requirement is based on stoichiometry:

\[PUreq = NPP_{potential} \times NCratio_{PUreq}\]

Nitrogen availability includes:

\[PUavail = NetMIN + AD\]

where NetMIN has temperature-sensitive and long-term components.

Switch Behavior:

When nitrogen cycle is disabled (switch_N = 0 or NplsP0 = 0): - NPP = NPPpot (no nitrogen limitation) - All nitrogen fluxes set to NaN - Model runs in carbon-only mode

See also

cnit.physics.carbon_cycle.CarbonNPPLPRCalculator.calculate()

NPP and LPR calculation

cnit.physics.nitrogen_cycle.NitrogenPUBNFCalculator.calculate_NflxPU_req_avail_def()

Nitrogen plant uptake budget

cnit.physics.effects.EffectCarbonNitrogenCouplingCalculator.calculate_eff_N_NPP()

Nitrogen effect

calculate_mdl_eqm0(dT_s, CO2_s, CemsLUnet_s, CemsLUgrs_s, NflxAD_s, NflxFT_s, NemsLUnet_s, NemsLUgrs_s, NemsLUmin_s)

Calculate equilibrium initial state for the model.

This method calculates the equilibrium pool sizes and turnover times that would result from steady forcing conditions. It is typically used to initialize the model in equilibrium with preindustrial conditions before running transient simulations.

The method uses the first timestep values of all forcing to calculate steady-state fluxes, then uses inverse turnover calculations to determine equilibrium pool sizes and turnover times.

Parameters:

• dT_s (Quantity) – Time series of temperature anomaly [K]. Only first value used.

• CO2_s (Quantity) – Time series of atmospheric CO2 concentration [ppm]. Only first value used.

• CemsLUnet_s (Quantity) – Time series of net land use carbon emissions [GtC/yr]. Only first value used.

• CemsLUgrs_s (Quantity) – Time series of gross land use carbon emissions [GtC/yr]. Only first value used.

• NflxAD_s (Quantity) – Time series of atmospheric nitrogen deposition [GtN/yr]. Only first value used.

• NflxFT_s (Quantity) – Time series of nitrogen fertilizer [GtN/yr]. Only first value used.

• NemsLUnet_s (Quantity) – Time series of net land use nitrogen emissions [GtN/yr]. Only first value used.

• NemsLUgrs_s (Quantity) – Time series of gross land use nitrogen emissions [GtN/yr]. Only first value used.

• NemsLUmin_s (Quantity) – Time series of land use mineral nitrogen emissions [GtN/yr]. Only first value used.

Returns:

Dict[str, pint.Quantity] – Dictionary containing equilibrium values for:

Carbon Equilibrium:

• CflxLP_inverse, CflxLD_inverse, CflxSR_inverse: Turnover fluxes

• CflxLP2L_inverse, CflxLP2S_inverse: Litter production partitioning

• CflxLD2S_inverse, CflxLD2A_inverse: Litter decomposition partitioning

• tau_CplsP_inverse, tau_CplsL_inverse, tau_CplsS_inverse: Turnover times

Nitrogen Equilibrium (if nitrogen cycle active):

• NflxLP_inverse, NflxLD_inverse, NflxSR_inverse, NflxLS_inverse: Turnover fluxes

• NflxLP2L_inverse, NflxLP2S_inverse: Litter production partitioning

• NflxLD2S_inverse, NflxLD2M_inverse: Litter decomposition partitioning

• tau_NplsP_inverse, tau_NplsL_inverse, tau_NplsS_inverse, tau_NplsM_inverse: Turnover times

Notes

Equilibrium Concept:

At equilibrium, pool sizes are constant (dC/dt = 0, dN/dt = 0), which means:

• Inputs = Outputs for each pool

• Fluxes are determined by forcing conditions

• Pool sizes and turnover times are mutually consistent

Usage:

Typical workflow for equilibrium initialization:

# Calculate equilibrium
eqm = model.calculate_mdl_eqm0(
    dT_s=preindustrial_temp,
    CO2_s=preindustrial_CO2,
    # ... other preindustrial forcing ...
)

# Set initial pool sizes (if desired)
model.mdl_c_cycle.CplsP0 = eqm_pool_sizes["CplsP"]

# Set equilibrium turnover times
model.mdl_c_cycle.calc_c_turnover. tau_CplsP = eqm["tau_CplsP_inverse"]

See also

calculate_eqm0

Core equilibrium calculation

inverse_carbon_turnover

Carbon equilibrium equations

inverse_nitrogen_turnover

Nitrogen equilibrium equations

calculate_eqm0(dT, CflxNPP, CflxLPR, CflxLUgrs, CflxLUrgr, NflxPUdef, NflxPU, NflxBNF, NflxAD, NflxFT, NflxLUgrs, NflxLUmin)

Calculate equilibrium state from specified fluxes.

This method calculates equilibrium pool sizes and turnover times given a set of fluxes and environmental conditions. It assumes steady state (dC/dt = 0, dN/dt = 0) and solves for the pool sizes and turnover times that satisfy mass balance.

Parameters:

• dT (Quantity) – Temperature anomaly [K]. Used for calculating environmental effects.

• CflxNPP (Quantity) – Net primary production [GtC/yr]. Carbon input to system.

• CflxLPR (Quantity) – Litter production respiration [GtC/yr]. Autotrophic respiration.

• CflxLUgrs (Quantity) – Gross land use carbon emissions [GtC/yr]. Carbon output from system.

• CflxLUrgr (Quantity) – Land use regrowth [GtC/yr]. Used for land use effects.

• NflxPUdef (Quantity) – Nitrogen deficit [GtN/yr]. Used for nitrogen effects.

• NflxPU (Quantity) – Plant nitrogen uptake [GtN/yr]. N transfer from mineral to organic pools.

• NflxBNF (Quantity) – Biological nitrogen fixation [GtN/yr]. External N input.

• NflxAD (Quantity) – Atmospheric nitrogen deposition [GtN/yr]. External N input.

• NflxFT (Quantity) – Nitrogen fertilizer [GtN/yr]. External N input.

• NflxLUgrs (Quantity) – Gross land use nitrogen emissions [GtN/yr]. N output from organic pools.

• NflxLUmin (Quantity) – Land use mineral nitrogen losses [GtN/yr]. N output from mineral pool.

Returns:

Dict[str, pint.Quantity] – Dictionary containing equilibrium values (see : meth:calculate_mdl_eqm0 for complete list).

Notes

Equilibrium Mass Balance:

For each pool, at equilibrium (dX/dt = 0):

\[\sum Inputs = \sum Outputs\]

This allows solving for either: - Pool sizes (given fluxes and turnover times), or - Turnover times (given fluxes and pool sizes)

The inverse methods solve for turnover times from the equilibrium condition.

Environmental Effects:

All environmental effects are calculated at the specified conditions (dT, CO2, etc.) and applied to determine equilibrium turnover rates.

See also

inverse_carbon_turnover

Solve carbon equilibrium equations

inverse_nitrogen_turnover

Solve nitrogen equilibrium equations

inverse_turnover_flux(influx, outflux, pool_size_change)

Calculate turnover flux from mass balance.

This helper method calculates the turnover flux from a pool given the mass balance equation:

\[\frac{dPool}{dt} = Influx - Turnover - Outflux\]

Rearranging for turnover:

\[Turnover = Influx - Outflux - \frac{dPool}{dt}\]

At equilibrium (dPool/dt = 0):

\[Turnover = Influx - Outflux\]

Parameters:

• influx (Quantity) – Total input to pool [GtC/yr or GtN/yr].

• outflux (Quantity) – Total output from pool (excluding turnover) [GtC/yr or GtN/yr].

• pool_size_change (Quantity) – Rate of change of pool size [GtC/yr or GtN/yr]. Zero at equilibrium.

Returns:

Turnover flux from pool [GtC/yr or GtN/yr].

Notes

This method is used by both carbon and nitrogen equilibrium calculations. For equilibrium calculations, pool_size_change = 0.

inverse_carbon_turnover(CflxNPP, CflxLPR, CflxLUgrs, eff_dT_cLP, eff_dT_cLD, eff_dT_cSR, eff_N_cLP, eff_N_cLD, eff_N_cSR, eff_LU_cLP, eff_LU_cLD, eff_LU_cSR, CplsP=None, CplsL=None, CplsS=None, dCplsP_dt=<Quantity(0, 'gigatC / yr')>, dCplsL_dt=<Quantity(0, 'gigatC / yr')>, dCplsS_dt=<Quantity(0, 'gigatC / yr')>)

Calculate equilibrium carbon fluxes and turnover times from mass balance.

This method solves the carbon cycle equilibrium equations to determine:

1. Turnover fluxes (cLP, cLD, cSR) from mass balance

2. Partitioned fluxes using allocation fractions

3. Equilibrium turnover times from pool sizes and fluxes

The method works backwards from pool mass balance equations to infer the turnover fluxes that satisfy equilibrium conditions.

Parameters:

• CflxNPP (Quantity) – Net primary production [GtC/yr]. Carbon input flux.

• CflxLPR (Quantity) – Litter production respiration [GtC/yr]. Autotrophic respiration.

• CflxLUgrs (Quantity) – Gross land use carbon emissions [GtC/yr]. Carbon output flux.

• eff_dT_cLP (Quantity) – Temperature effects on carbon processes [dimensionless].

• eff_dT_cLD (Quantity) – Temperature effects on carbon processes [dimensionless].

• eff_dT_cSR (Quantity) – Temperature effects on carbon processes [dimensionless].

• eff_N_cLP (Quantity) – Nitrogen effects on carbon processes [dimensionless].

• eff_N_cLD (Quantity) – Nitrogen effects on carbon processes [dimensionless].

• eff_N_cSR (Quantity) – Nitrogen effects on carbon processes [dimensionless].

• eff_LU_cLP (Quantity) – Land use effects on carbon processes [dimensionless].

• eff_LU_cLD (Quantity) – Land use effects on carbon processes [dimensionless].

• eff_LU_cSR (Quantity) – Land use effects on carbon processes [dimensionless].

• CplsP (Quantity) – Current carbon pool sizes [GtC]. If None, uses initial values from model.

• CplsL (Quantity) – Current carbon pool sizes [GtC]. If None, uses initial values from model.

• CplsS (Quantity) – Current carbon pool sizes [GtC]. If None, uses initial values from model.

• dCplsP_dt (Quantity) – Pool size changes [GtC/yr]. Zero for equilibrium calculation.

• dCplsL_dt (Quantity) – Pool size changes [GtC/yr]. Zero for equilibrium calculation.

• dCplsS_dt (Quantity) – Pool size changes [GtC/yr]. Zero for equilibrium calculation.

Returns:

Dict[str, Quantity] – Dictionary containing:

Turnover Fluxes:

• CflxLP_inverse: Litter production [GtC/yr]

• CflxLD_inverse: Litter decomposition [GtC/yr]

• CflxSR_inverse: Soil respiration [GtC/yr]

Partitioned Fluxes:

• CflxLP2L_inverse, CflxLP2S_inverse: LP allocation

• CflxLD2S_inverse, CflxLD2A_inverse: LD allocation

Equilibrium Turnover Times:

• tau_CplsP_inverse: Plant pool turnover time [yr]

• tau_CplsL_inverse: Litter pool turnover time [yr]

• tau_CplsS_inverse: Soil pool turnover time [yr]

Notes

Mass Balance Equations:

For each pool at equilibrium:

\[ \begin{align}\begin{aligned}\frac{dC_P}{dt} = NPP2P - LPR - cLP - cLUgrs_P = 0\\\frac{dC_L}{dt} = NPP2L + cLP2L - cLD - cLUgrs_L = 0\\\frac{dC_S}{dt} = NPP2S + cLP2S + cLD2S - cSR - cLUgrs_S = 0\end{aligned}\end{align} \]

These are solved sequentially to find cLP, cLD, and cSR.

Turnover Time Calculation:

From first-order kinetics:

\[Flux = \frac{Pool}{\tau} \times \prod Effects\]

Rearranging:

\[\tau = \frac{Pool}{Flux} \times \prod Effects\]

See also

inverse_turnover_flux

Mass balance calculation

cnit.physics.carbon_cycle.CarbonTurnoverCalculator.calculate()

Forward turnover calculation

inverse_nitrogen_turnover(NflxPU, NflxBNF, NflxAD, NflxFT, NflxLUgrs, NflxLUmin, eff_dT_nLP, eff_dT_nLD, eff_dT_nSR, eff_dT_nLSgas, eff_N_nLP, eff_N_nLD, eff_N_nSR, eff_LU_nLP, eff_LU_nLD, eff_LU_nSR, NplsP=None, NplsL=None, NplsS=None, NplsM=None, dNplsP_dt=<Quantity(0, 'gigatN / yr')>, dNplsL_dt=<Quantity(0, 'gigatN / yr')>, dNplsS_dt=<Quantity(0, 'gigatN / yr')>, dNplsM_dt=<Quantity(0, 'gigatN / yr')>)

Calculate equilibrium nitrogen fluxes and turnover times from mass balance.

This method solves the nitrogen cycle equilibrium equations to determine: 1. Turnover fluxes (nLP, nLD, nSR, nLS) from mass balance 2. Partitioned fluxes using allocation fractions 3. Equilibrium turnover times from pool sizes and fluxes

Similar to : meth:inverse_carbon_turnover but includes the mineral nitrogen pool and its associated fluxes.

Parameters:

• NflxPU (Quantity) – Plant nitrogen uptake [GtN/yr]. Mineral to organic transfer.

• NflxBNF (Quantity) – Biological nitrogen fixation [GtN/yr]. External input.

• NflxAD (Quantity) – Atmospheric deposition [GtN/yr]. External input.

• NflxFT (Quantity) – Fertilizer application [GtN/yr]. External input.

• NflxLUgrs (Quantity) – Gross land use nitrogen emissions [GtN/yr]. Output from organic pools.

• NflxLUmin (Quantity) – Land use mineral nitrogen losses [GtN/yr]. Output from mineral pool.

• eff_dT_nLP (Quantity) – Temperature effects on nitrogen processes [dimensionless].

• eff_dT_nLD (Quantity) – Temperature effects on nitrogen processes [dimensionless].

• eff_dT_nSR (Quantity) – Temperature effects on nitrogen processes [dimensionless].

• eff_dT_nLSgas (Quantity) – Temperature effects on nitrogen processes [dimensionless].

• eff_N_nLP (Quantity) – Carbon-nitrogen coupling effects [dimensionless].

• eff_N_nLD (Quantity) – Carbon-nitrogen coupling effects [dimensionless].

• eff_N_nSR (Quantity) – Carbon-nitrogen coupling effects [dimensionless].

• eff_LU_nLP (Quantity) – Land use effects on nitrogen processes [dimensionless].

• eff_LU_nLD (Quantity) – Land use effects on nitrogen processes [dimensionless].

• eff_LU_nSR (Quantity) – Land use effects on nitrogen processes [dimensionless].

• NplsP (Quantity) – Current nitrogen pool sizes [GtN]. If None, uses initial values from model.

• NplsL (Quantity) – Current nitrogen pool sizes [GtN]. If None, uses initial values from model.

• NplsS (Quantity) – Current nitrogen pool sizes [GtN]. If None, uses initial values from model.

• NplsM (Quantity) – Current nitrogen pool sizes [GtN]. If None, uses initial values from model.

• dNplsP_dt (Quantity) – Pool size changes [GtN/yr]. Zero for equilibrium calculation.

• dNplsL_dt (Quantity) – Pool size changes [GtN/yr]. Zero for equilibrium calculation.

• dNplsS_dt (Quantity) – Pool size changes [GtN/yr]. Zero for equilibrium calculation.

• dNplsM_dt (Quantity) – Pool size changes [GtN/yr]. Zero for equilibrium calculation.

Returns:

Dict[str, pint.Quantity] – Dictionary containing:

Turnover Fluxes: - NflxLP_inverse, NflxLD_inverse, NflxSR_inverse, NflxLS_inverse

Partitioned Fluxes: - NflxLP2L_inverse, NflxLP2S_inverse: LP allocation - NflxLD2S_inverse, NflxLD2M_inverse: LD allocation

Equilibrium Turnover Times: - tau_NplsP_inverse, tau_NplsL_inverse, tau_NplsS_inverse, tau_NplsM_inverse

Notes

Mass Balance Equations:

For equilibrium in each pool:

\[ \begin{align}\begin{aligned}\frac{dN_P}{dt} = BNF2P + PU2P - nLP - nLUgrs_P = 0\\\frac{dN_L}{dt} = BNF2L + PU2L + nLP2L - nLD - nLUgrs_L = 0\\\frac{dN_S}{dt} = BNF2S + PU2S + nLP2S + nLD2S - nSR - nLUgrs_S = 0\\\frac{dN_M}{dt} = AD + FT + nLD2M + nSR - PU - nLS - nLUmin = 0\end{aligned}\end{align} \]

These are solved sequentially to find nLP, nLD, nSR, and nLS.

See also

inverse_carbon_turnover

Analogous carbon calculation

cnit.physics.nitrogen_cycle.NitrogenTurnoverCalculator.calculate_nLPLDSR()

Forward nitrogen turnover

cnit.physics.nitrogen_cycle.NitrogenTurnoverCalculator.calculate_nLS()

Forward mineral N losses