[CropAndSoil] Re-implement nutrient cycling residue composition factor per SWAT 3:1.2.8 by matthew7838 · Pull Request #3150 · RuminantFarmSystems/RuFaS

matthew7838 · 2026-07-20T19:00:47Z

Re-implements _calculate_nutrient_cycling_residue_composition_factor in mineralization_decomp.py so it actually uses the nitrogen and phosphorus terms per SWAT 3:1.2.8, instead of unconditionally returning 1.

Context

Issue(s) closed by this pull request: closes #2990

Background from the issue: the constant return 1 was introduced in #1865 to work around #1810, where very large C:N / C:P ratios (>30,000:1 in some soil layers) drove the factor to functionally zero. Per @morrowcj's SME grooming (after checking with KFosterReed), the nitrogen-modeling changes made since then have addressed the conditions behind #1810, so the SWAT logic can be restored with a clamped lower bound.

What

MineralizationDecomposition._calculate_nutrient_cycling_residue_composition_factor now returns max(min([nitrogen_term, phosphorus_term, 1]), 1e-5) rather than discarding both terms and returning 1.
Removed the now-obsolete assert nitrogen_term is not None and phosphorus_term is not None line, which existed only to keep the unused terms from being flagged.
Updated the docstring: dropped the "temporary fix" note and the # TODO pointing at [Crop and Soil] Confirm the function _calculate_nutrient_cycling_residue_composition_factor in mineralization_decomp.py is working correctly. #2990, and documented where the 1e-5 lower bound comes from.
Updated test_calculate_nutrient_cycling_residue_composition_factor to exercise the real behavior.
Regenerated the end-to-end expected results, since soil nitrogen outputs change (see Test plan).

Why

The method is called by mineralize_and_decompose_nitrogen to get the residue composition factor that feeds the decay rate constant. Returning a hard-coded 1 meant the effect of soil C, N, and P on the decomposition rate factor was not modeled at all — the C:N and C:P ratios were computed and then thrown away, so residue decomposition ran at the same rate regardless of residue nutrient composition. That does not match SWAT 3:1.2.8.

How

Implements the equation as specified in the issue:

Upper bound of 1 comes from SWAT — the factor should never accelerate decomposition above the base rate, and both terms exceed 1 whenever C:N < 25 or C:P < 200.
Lower bound of 1e-5 (functionally zero) is the SME-suggested clamp that keeps pathological C:N / C:P ratios from collapsing the decay rate constant to exactly zero, which is the failure mode that motivated the original workaround in Temporary Replacement of Soil N Mineralization Rate factor calculation method with fixed value #1810.

Test plan

Run with updated unit tests.
SME's review with different scenarios.

Input Changes

No schema or user-facing input changes. The 12 input/data/end_to_end_testing/*/e2e_json_*_filter.json files are modified only because the end-to-end expected results are stored inline in them and were regenerated.

Output Changes

N/A

Filter

{
  "multiple": [
    {
      "name": "issue_2990_soil_nitrogen",
      "filters": [
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(fresh_organic|active_organic|stable_organic)_nitrogen_content.*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(nitrate_content|ammonium_content|percolated_nitrates|percolated_ammonium).*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(nitrous_oxide_emissions|dinitrogen_emissions|ammonia_emissions).*",
        "FieldDataReporter\\.send_soil_daily_variables\\.(profile_nitrates_total|profile_ammonium_total|profile_fresh_organic_nitrogen_total|profile_active_organic_nitrogen_total).*",
        "FieldDataReporter\\.send_soil_daily_variables\\.(nitrate_runoff|ammonium_runoff|eroded_(fresh|active|stable)_organic_nitrogen).*",
        "FieldDataReporter\\.send_soil_annual_variables\\.annual_.*(nitrogen|nitrates|ammonium|ammonia).*",
        "FieldDataReporter\\.send_soil_layer_annual_variables\\.annual_(nitrous_oxide|ammonia)_emissions_total.*"
      ]
    },
    {
      "name": "issue_2990_soil_carbon",
      "filters": [
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(active|slow|passive)_carbon.*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(passive_to_active|slow_to_active|active_carbon_to_slow|active_carbon_to_passive).*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(soil|plant)_(structural|metabolic)_(active|slow)_carbon.*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(soil|plant)_active_decompose_carbon.*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(structural_litter_amount|metabolic_litter_amount|total_soil_carbon_amount|soil_overall_carbon_fraction).*",
        "FieldDataReporter\\.send_soil_daily_variables\\.profile_carbon_emissions.*",
        "FieldDataReporter\\.send_soil_layer_annual_variables\\.annual_.*carbon.*"
      ]
    },
    {
      "name": "issue_2990_crop_growth_and_uptake",
      "filters": [
        "FieldDataReporter\\.send_crop_daily_variables\\.(biomass|biomass_growth|biomass_growth_max|above_ground_biomass|root_biomass|cut_biomass).*",
        "FieldDataReporter\\.send_crop_daily_variables\\.(wet_yield_collected|yield_nitrogen|yield_phosphorus|crop_nitrogen|optimal_crop_nitrogen).*",
        "FieldDataReporter\\.send_crop_daily_variables\\.(leaf_area_index|leaf_area_added|optimal_leaf_area_change|usable_light|growth_factor).*",
        "FieldDataReporter\\.send_crop_daily_variables\\.(total|potential)_(nitrogen|phosphorus)_uptake.*",
        "FieldDataReporter\\.send_crop_daily_variables\\.(nitrogen_stress|phosphorus_stress|water_stress).*"
      ]
    },
    {
      "name": "issue_2990_water_phosphorus_and_erosion",
      "filters": [
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(water_content|water_factor|temperature|evaporated_water_content|percolated_water|percolated_phosphorus).*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(labile_inorganic|active_inorganic)_phosphorus_content.*",
        "FieldDataReporter\\.send_soil_layer_daily_variables\\.(labile|active)_inorganic_unbalanced_counter.*",
        "FieldDataReporter\\.send_crop_daily_variables\\.(max_transpiration|cumulative_transpiration|cumulative_evaporation|cumulative_evapotranspiration|water_uptake|water_deficiency|canopy_water).*",
        "FieldDataReporter\\.send_soil_daily_variables\\.(infiltrated_water|water_evaporated|accumulated_runoff|eroded_sediment).*",
        "FieldDataReporter\\.send_soil_daily_variables\\.(soil_phosphorus_runoff|runoff_fertilizer_phosphorus|machine_.*phosphorus).*",
        "FieldDataReporter\\.send_soil_annual_variables\\.annual_(soil_evaporation_total|surface_runoff_total|eroded_sediment_total|soil_phosphorus_runoff).*",
        "FieldDataReporter\\.send_vadose_zone_layer_daily_variables\\..*"
      ]
    }
  ]
}

github-actions · 2026-07-20T19:07:41Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

github-actions · 2026-07-20T19:07:42Z

🚨 Please update the changelog. This PR cannot be merged until changelog_WIP.md is updated.

github-actions · 2026-07-20T19:18:32Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

github-actions · 2026-07-20T19:18:33Z

🚨 Please update the changelog. This PR cannot be merged until changelog_WIP.md is updated.

github-actions · 2026-07-20T19:33:26Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

github-actions · 2026-07-20T19:34:55Z

Current Coverage: %

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

github-actions · 2026-07-20T19:34:56Z

🚨 Some tests have failed.

github-actions · 2026-07-21T12:26:37Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

ew3361zh

lgtm!

ew3361zh · 2026-07-21T18:50:54Z

        Notes
        -----
        The values of the constant used to determine the nitrogen and phosphorus terms are 25 and 200, respectively.
+        Minimum value in the max() return was suggested by SME on issue#2990


Maybe I'm misreading it but it seems like the suggestion comes from SWAT, not the SME?

I believe that SWAT did not mention the floor value; it was mentioned by Clay in the issue comments, which functionally sets the floor as 0.

ew3361zh · 2026-07-21T18:53:58Z

            milk_protein_content=1,
        )
-        for _ in range(randint(0, 100))
+        for _ in range(randint(1, 100))


why is this updated?

So this is another bug that's causing a 1/400 failure that was never triggered before, so no one caught it. I got lucky (or unlucky) with this PR, and it got triggered.

github-actions · 2026-07-22T06:45:12Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

allisterakun

LGTM!

Resolve conflicts in changelog_WIP.md (keep both #3128 and #3150 entries) and the 12 end-to-end filter files. The e2e expected results are regenerated from the merged code so they reflect both dev's heifer ADG floor (#3128) and this branch's mineralization factor change (#3150).

github-actions · 2026-07-23T11:06:50Z

Current Coverage: 99%

Mypy errors on cs-decomp branch: 1135
Mypy errors on dev branch: 1136
1 fewer errors on cs-decomp branch

matthew7838 and others added 5 commits July 21, 2026 03:42

Algo re-implementation

fe06b39

Updated tests

c43b72e

Merge c43b72e into 536c0f9

be4f129

Apply Black Formatting

a33bacf

Update badges on README

9bf67f8

matthew7838 and others added 3 commits July 21, 2026 04:10

Update e2e filters

c56156c

Merge c56156c into 536c0f9

8015429

Apply Black Formatting

6638809

matthew7838 and others added 3 commits July 21, 2026 04:26

Add changelog entry

b16643e

Updated e2e filters and updated change log

9c8976c

Merge 9c8976c into 536c0f9

ff9ab96

github-actions Bot force-pushed the cs-decomp branch from 9c8976c to d8beed9 Compare July 20, 2026 19:28

Apply Black Formatting

77989b0

github-actions Bot force-pushed the cs-decomp branch from d8beed9 to 77989b0 Compare July 20, 2026 19:30

matthew7838 requested review from allisterakun, ew3361zh and morrowcj July 20, 2026 19:33

Update badges on README

1a9b2e8

matthew7838 and others added 5 commits July 21, 2026 21:14

Fixed failing tests

a302b8f

Merge remote-tracking branch 'origin/cs-decomp' into cs-decomp

eb99138

Merge eb99138 into 536c0f9

9f4bfdf

Apply Black Formatting

fc45962

Update badges on README

1046407

ew3361zh approved these changes Jul 21, 2026

View reviewed changes

matthew7838 and others added 3 commits July 22, 2026 15:38

Addressed Niko's variable naming suggestion

1eb35a7

Merge 1eb35a7 into 536c0f9

513e1a8

Apply Black Formatting

3e5a1c0

allisterakun approved these changes Jul 22, 2026

View reviewed changes

matthew7838 and others added 3 commits July 23, 2026 19:49

Merge 9e2d5d8 into ec06483

0348c06

Apply Black Formatting

81f037b

Uh oh!

Conversation

matthew7838 commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

What

Why

How

Test plan

Input Changes

Output Changes

Filter

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

ew3361zh left a comment

Choose a reason for hiding this comment

Uh oh!

ew3361zh Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

matthew7838 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ew3361zh Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

matthew7838 Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 22, 2026

Uh oh!

allisterakun left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthew7838 commented Jul 20, 2026 •

edited

Loading

matthew7838 Jul 22, 2026 •

edited

Loading