From a5ca6de90ed9dcebc84b8c8f3ba75c9abaa1c73a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 13:56:20 -0600 Subject: [PATCH 01/73] TN: Crops: Convert to Markdown. --- ...rst => CLM50_Tech_Note_Crop_Irrigation.md} | 502 ++++++++---------- doc/source/tech_note/index.rst | 2 +- 2 files changed, 231 insertions(+), 273 deletions(-) rename doc/source/tech_note/Crop_Irrigation/{CLM50_Tech_Note_Crop_Irrigation.rst => CLM50_Tech_Note_Crop_Irrigation.md} (51%) mode change 100755 => 100644 diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md old mode 100755 new mode 100644 similarity index 51% rename from doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst rename to doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index ec43a50cd8..c03150efbb --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,75 +1,61 @@ -.. _rst_Crops and Irrigation: +(rst_crops and irrigation)= -Crops and Irrigation -==================== +# Crops and Irrigation -.. _Summary of CLM5.0 updates relative to the CLM4.5: +(summary-of-clm5-0-updates-relative-to-the-clm4-5)= -Summary of CLM5.0 updates relative to the CLM4.5 ------------------------------------------------- +## Summary of CLM5.0 updates relative to the CLM4.5 -We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). +We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note ({ref}`Oleson et al. 2013 `). CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the BGC configuration: - New crop functional types - - All crop areas are actively managed - - Fertilization rates updated based on crop type and geographic region - - New Irrigation triggers - - Phenological triggers vary by latitude for some crop types - - Ability to simulate transient crop management - - Adjustments to allocation and phenological parameters - - Crops reaching their maximum LAI triggers the grain fill phase - - Grain C and N pools are included in a 1-year product pool - - C for annual crop seeding comes from the grain C pool - - Initial seed C for planting is increased from 1 to 3 g C/m^2 -These updates appear in detail in the sections below. Many also appear in :ref:`Levis et al. (2016) `. +These updates appear in detail in the sections below. Many also appear in {ref}`Levis et al. (2016) `. + +### Available new features since the CLM5 release -Available new features since the CLM5 release -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Addition of bioenergy crops - Ability to customize crop calendars (sowing windows/dates, maturity requirements) using stream files - Cropland soil tillage - Crop residue removal -.. _The crop model: +(the-crop-model)= -The crop model: cash and bioenergy crops ----------------------------------------- +## The crop model: cash and bioenergy crops -Introduction -^^^^^^^^^^^^ +### Introduction Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), and those are now incorporated into CLM5. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 \[CLM3.0, {ref}`Oleson et al. (2004) ` \] (not published), then coupled to the CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and those are now incorporated into CLM5. -With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. +With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. -.. _Crop plant functional types: +(crop-plant-functional-types)= -Crop plant functional types -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Crop plant functional types -To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by :ref:`Portmann et al. (2010)` for present day. New in CLM5, crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries (:ref:`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter :numref:`rst_Transient Landcover Change`. +To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by {ref}`Portmann et al. (2010)` for present day. New in CLM5, crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries ({ref}`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter {numref}`rst_Transient Landcover Change`. -CLM5 includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by :ref:`Badger and Dirmeyer (2015)` and described by :ref:`Levis et al. (2016)`, or from available observations as described by :ref:`Cheng et al. (2019)`. The representations of sugarcane, rice, cotton, tropical corn, and tropical soy were new in CLM5; miscanthus and switchgrass were added after the CLM5 release. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States (:ref:`Cheng et al., 2019`). +CLM5 includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. The representations of sugarcane, rice, cotton, tropical corn, and tropical soy were new in CLM5; miscanthus and switchgrass were added after the CLM5 release. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). -In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop (:numref:`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in :numref:`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. +In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. -.. _Table Crop plant functional types: +(table crop plant functional types)= +```{eval-rst} .. table:: Crop plant functional types (PFTs) included in CLM5BGCCROP. === =========================== ================ =========================== @@ -140,83 +126,77 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr 77 rainfed tropical soybean active rainfed tropical soybean 78 irrigated tropical soybean active irrigated tropical soybean === =========================== ================ =========================== +``` -.. _Phenology: +(phenology)= -Phenology -^^^^^^^^^ +### Phenology -CLM5-BGC includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). CLM5-BGC-crop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. +CLM5-BGC includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter {numref}`rst_Vegetation Phenology and Turnover`). CLM5-BGC-crop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. -.. _Planting: - -Planting -'''''''' +(planting)= -All crops must meet the following requirements between the minimum planting date and the maximum planting date (for the northern hemisphere) in :numref:`Table Crop phenology parameters`: +#### Planting -.. math:: - :label: 25.1 +All crops must meet the following requirements between the minimum planting date and the maximum planting date (for the northern hemisphere) in {numref}`Table Crop phenology parameters`: - \begin{array}{c} - {T_{10d} >T_{p} } \\ - {T_{10d}^{\min } >T_{p}^{\min } } \\ - {GDD_{8} \ge GDD_{\min } } - \end{array} +$$ +\begin{array}{c} +{T_{10d} >T_{p} } \\ +{T_{10d}^{\min } >T_{p}^{\min } } \\ +{GDD_{8} \ge GDD_{\min } } +\end{array} +$$ (25.1) -where :math:`{T}_{10d}` is the 10-day running mean of :math:`{T}_{2m}`, (the simulated 2-m air temperature during each model time step) and :math:`T_{10d}^{\min}` is the 10-day running mean of :math:`T_{2m}^{\min }` (the daily minimum of :math:`{T}_{2m}`). :math:`{T}_{p}` and :math:`T_{p}^{\min }` are crop-specific coldest planting temperatures (:numref:`Table Crop phenology parameters`), :math:`{GDD}_{8}` is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation :eq:`25.3`), and :math:`{GDD}_{min }`\ is the minimum growing degree day requirement (:numref:`Table Crop phenology parameters`). :math:`{GDD}_{8}` does not change as quickly as :math:`{T}_{10d}` and :math:`T_{10d}^{\min }`, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the :math:`{GDD}_{8}` threshold is met. If the requirements in equation :eq:`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as :math:`{GDD}_{8} > 0`. In the southern hemisphere (SH) the NH requirements apply 6 months later. +where ${T}_{10d}$ is the 10-day running mean of ${T}_{2m}$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $T_{2m}^{\min }$ (the daily minimum of ${T}_{2m}$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), ${GDD}_{8}$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). ${GDD}_{8}$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the ${GDD}_{8}$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as ${GDD}_{8} > 0$. In the southern hemisphere (SH) the NH requirements apply 6 months later. -At planting, each crop seed pool is assigned 3 gC m\ :sup:`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (:math:`{CN}_{leaf}` in :numref:`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, :math:`{GDD}_{mat}`, according to the following AgroIBIS rules: +At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, ${GDD}_{mat}$, according to the following AgroIBIS rules: -.. math:: - :label: 25.2 +$$ +\begin{array}{lll} +GDD_{{\rm mat}}^{{\rm corn,sugarcane}} =0.85 GDD_{{\rm 8}} & {\rm \; \; \; and\; \; \; }& 950 `, {ref}`Crawford et al. 1982 `, {ref}`Simpson et al. 1983 `, {ref}`Ta and Weiland 1992 `, {ref}`Barbottin et al. 2005 `, {ref}`Gallais et al. 2006 `, {ref}`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue and is calculated as -Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth season is remobilized and used for grain development (:ref:`Pollmer et al. 1979 `, :ref:`Crawford et al. 1982 `, :ref:`Simpson et al. 1983 `, :ref:`Ta and Weiland 1992 `, :ref:`Barbottin et al. 2005 `, :ref:`Gallais et al. 2006 `, :ref:`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue and is calculated as +$$ +leaf\_ to\_ retransn=N_{leaf} -\frac{C_{leaf} }{CN_{leaf}^{f} } +$$ (25.6) -.. math:: - :label: 25.6 +$$ +stemn\_ to\_ retransn=N_{stem} -\frac{C_{stem} }{CN_{stem}^{f} } +$$ (25.7) - leaf\_ to\_ retransn=N_{leaf} -\frac{C_{leaf} }{CN_{leaf}^{f} } +$$ +frootn\_ to\_ retransn=N_{froot} -\frac{C_{froot} }{CN_{froot}^{f} } +$$ (25.8) -.. math:: - :label: 25.7 +where ${C}_{leaf}$, ${C}_{stem}$, and ${C}_{froot}$ is the carbon in the plant leaf, stem, and fine root, respectively, ${N}_{leaf}$, ${N}_{stem}$, and ${N}_{froot}$ is the nitrogen in the plant leaf, stem, and fine root, respectively, and $CN^f_{leaf}$, $CN^f_{stem}$, and $CN^f_{froot}$ is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively ({numref}`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ (${CN_{[organ]}^{f} }$ in {numref}`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. - stemn\_ to\_ retransn=N_{stem} -\frac{C_{stem} }{CN_{stem}^{f} } +(harvest to food and seed)= -.. math:: - :label: 25.8 - - frootn\_ to\_ retransn=N_{froot} -\frac{C_{froot} }{CN_{froot}^{f} } - -where :math:`{C}_{leaf}`, :math:`{C}_{stem}`, and :math:`{C}_{froot}` is the carbon in the plant leaf, stem, and fine root, respectively, :math:`{N}_{leaf}`, :math:`{N}_{stem}`, and :math:`{N}_{froot}` is the nitrogen in the plant leaf, stem, and fine root, respectively, and :math:`CN^f_{leaf}`, :math:`CN^f_{stem}`, and :math:`CN^f_{froot}` is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively (:numref:`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ (:math:`{CN_{[organ]}^{f} }` in :numref:`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. - -.. _Harvest to food and seed: - -Harvest -''''''' +#### Harvest Whereas live crop C and N in grain was formerly transferred to the litter pool upon harvest, CLM5 splits this between "food" and "seed" pools. In the former—more generally a "crop product" pool—C and N decay to the atmosphere over one year, similar to how the wood product pools work. The latter is used in the subsequent year to account for the C and N required for crop seeding. Live leaf and stem biomass at harvest is transferred to biofuel, removed residue, and/or litter pools. -For the biofuel crops Miscanthus and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool as described for "food" harvest above. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter :math:`biofuel\_harvfrac` (0-1). +For the biofuel crops Miscanthus and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool as described for "food" harvest above. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter $biofuel\_harvfrac$ (0-1). -50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter :math:`crop\_residue\_removal\_frac` (0–1). The default 50% is derived from :ref:`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. +50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter $crop\_residue\_removal\_frac$ (0–1). The default 50% is derived from {ref}`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. -The following equations illustrate how this works. Subscript :math:`p` refers to either the leaf or live stem biomass pool. +The following equations illustrate how this works. Subscript $p$ refers to either the leaf or live stem biomass pool. -.. math:: - :label: 25.9 +$$ +CF_{p,biofuel} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} + \right) * biofuel\_harvfrac +$$ (25.9) - CF_{p,biofuel} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * biofuel\_harvfrac +$$ +CF_{p,removed\_residue} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} + \right) * (1 - biofuel\_harvfrac) * crop\_residue\_removal\_frac +$$ (harv_c_to_removed_residue) -.. math:: - :label: harv_c_to_removed_residue - - CF_{p,removed\_residue} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * (1 - biofuel\_harvfrac) * crop\_residue\_removal\_frac - -.. math:: - :label: 25.11 - - CF_{p,litter} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) +CF_{p,alloc} +$$ +CF_{p,litter} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} + \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) +CF_{p,alloc} +$$ (25.11) with corresponding nitrogen fluxes: -.. math:: - :label: 25.12 - - NF_{p,biofuel} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * biofuel\_harvfrac +$$ +NF_{p,biofuel} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} + \right) * biofuel\_harvfrac +$$ (25.12) -.. math:: - :label: harv_n_to_removed_residue +$$ +NF_{p,removed\_residue} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} + \right) * \left( 1 - biofuel\_harvfrac \right) * crop\_residue\_removal\_frac +$$ (harv_n_to_removed_residue) - NF_{p,removed\_residue} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1 - biofuel\_harvfrac \right) * crop\_residue\_removal\_frac +$$ +NF_{p,litter} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} + \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) +$$ (25.14) -.. math:: - :label: 25.14 +where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and $biofuel\_harvfrac$ is the harvested fraction of leaf/livestem for biofuel feedstocks. - NF_{p,litter} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) +Annual food crop yields (g dry matter m{sup}`-2`) can be calculated by saving the GRAINC_TO_FOOD_ANN variable once per year, then postprocessing with Equation {eq}`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. -where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and :math:`biofuel\_harvfrac` is the harvested fraction of leaf/livestem for biofuel feedstocks. +$$ +\text{Grain yield} = \frac{GRAINC\_TO\_FOOD\_ANN)*0.85}{0.45} +$$ (25.15) -Annual food crop yields (g dry matter m\ :sup:`-2`) can be calculated by saving the GRAINC_TO_FOOD_ANN variable once per year, then postprocessing with Equation :eq:`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. - -.. math:: - :label: 25.15 - - \text{Grain yield} = \frac{GRAINC\_TO\_FOOD\_ANN)*0.85}{0.45} - -.. _Table Crop allocation parameters: +(table crop allocation parameters)= +```{eval-rst} .. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM5BGCCROP. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ @@ -592,138 +557,130 @@ Annual food crop yields (g dry matter m\ :sup:`-2`) can be calculated by saving :math:`CN^f_{froot}` 0 40 0 0 40 0 0 0 0 0 :math:`{CN}_{grain}` 50 50 50 50 50 50 50 50 50 50 =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ +``` -Notes: Crop growth phases and corresponding variables are described throughout the text. :math:`{CN}_{leaf}`, :math:`{CN}_{stem}`, and :math:`{CN}_{froot}` are the target C:N ratios used during the leaf emergence phase (phase 2). +Notes: Crop growth phases and corresponding variables are described throughout the text. ${CN}_{leaf}$, ${CN}_{stem}$, and ${CN}_{froot}$ are the target C:N ratios used during the leaf emergence phase (phase 2). -.. _Other Features: +(other-features)= -Other Features -^^^^^^^^^^^^^^ +### Other Features -.. _Physical Crop Characteristics: +(physical-crop-characteristics)= -Physical Crop Characteristics -''''''''''''''''''''''''''''' -Leaf area index (*L*) is calculated as a function of specific leaf area (SLA, :numref:`Table Crop phenology parameters`) and leaf C. Stem area index (*S*) is equal to 0.1\ *L* for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2\ *L* for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to simulate a post-harvest "stubble" on the ground. +#### Physical Crop Characteristics -Crop heights at the top and bottom of the canopy, :math:`{z}_{top}` and :math:`{z}_{bot}` (m), come from the AgroIBIS formulation: +Leaf area index (*L*) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index (*S*) is equal to 0.1*L* for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2*L* for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to simulate a post-harvest "stubble" on the ground. -.. math:: - :label: 25.16 +Crop heights at the top and bottom of the canopy, ${z}_{top}$ and ${z}_{bot}$ (m), come from the AgroIBIS formulation: - \begin{array}{l} - {z_{top} =z_{top}^{\max } \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ - {z_{bot} =0.02{\rm m}} - \end{array} +$$ +\begin{array}{l} +{z_{top} =z_{top}^{\max } \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ +{z_{bot} =0.02{\rm m}} +\end{array} +$$ (25.16) -where :math:`z_{top}^{\max }` is the maximum top-of-canopy height of the crop (:numref:`Table Crop phenology parameters`) and :math:`L_{\max }` is the maximum leaf area index (:numref:`Table Crop allocation parameters`). +where $z_{top}^{\max }$ is the maximum top-of-canopy height of the crop ({numref}`Table Crop phenology parameters`) and $L_{\max }$ is the maximum leaf area index ({numref}`Table Crop allocation parameters`). -.. _Interactive fertilization: +(interactive-fertilization)= -Interactive Fertilization -''''''''''''''''''''''''' -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field ``manunitro``. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States :ref:`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current CLM5BGCCROP, manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +#### Interactive Fertilization -.. math:: - :label: 25.17 +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current CLM5BGCCROP, manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: - f = n \times 86400 +$$ +f = n \times 86400 +$$ (25.17) where *n* is set to 20 fertilizer application days and 86400 is the number of seconds per day. When the crop enters phase 2 (leaf emergence) of its growth cycle, fertilizer application begins by initializing fertilizer amount to the total fertilizer at each column within the grid cell divided by the initialized *f*. Fertilizer is applied and *f* is decremented each time step until a zero balance on the counter is reached. -.. _Biological nitrogen fixation for soybeans: +(biological-nitrogen-fixation-for-soybeans)= -Biological nitrogen fixation for soybeans -''''''''''''''''''''''''''''''''''''''''' -Biological N fixation for soybeans is calculated by the fixation and uptake of nitrogen module (Chapter :numref:`rst_FUN`) and is the same as N fixation in natural vegetation. Unlike natural vegetation, where a fraction of each PFT are N fixers, all soybeans are treated as N fixers. +#### Biological nitrogen fixation for soybeans -.. _Latitude vary base tempereature for growing degree days: +Biological N fixation for soybeans is calculated by the fixation and uptake of nitrogen module (Chapter {numref}`rst_FUN`) and is the same as N fixation in natural vegetation. Unlike natural vegetation, where a fraction of each PFT are N fixers, all soybeans are treated as N fixers. -Latitudinal variation in base growth tempereature -''''''''''''''''''''''''''''''''''''''''''''''''' -For most crops, :math:`GDD_{T_{{\rm 2m}} }` (growing degree days since planting) is the same in all locations. However, for both rainfed and irrigated spring wheat and sugarcane, the calculation of :math:`GDD_{T_{{\rm 2m}} }` allows for latitudinal variation: +(latitude-vary-base-tempereature-for-growing-degree-days)= -.. math:: - :label: 25.18 +#### Latitudinal variation in base growth tempereature - latitudinal\ variation\ in\ base\ T = \left\{ - \begin{array}{lr} - baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ - baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 - \end{array} \right\} +For most crops, $GDD_{T_{{\rm 2m}} }$ (growing degree days since planting) is the same in all locations. However, for both rainfed and irrigated spring wheat and sugarcane, the calculation of $GDD_{T_{{\rm 2m}} }$ allows for latitudinal variation: -where :math:`baset` is the *base temperature for GDD* (7\ :sup:`th` row) in :numref:`Table Crop phenology parameters`. Such latitudinal variation in base temperature could slow :math:`GDD_{T_{{\rm 2m}} }` accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. +$$ +latitudinal\ variation\ in\ base\ T = \left\{ +\begin{array}{lr} +baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ +baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 +\end{array} \right\} +$$ (25.18) -.. _Separate reproductive pool: +where $baset$ is the *base temperature for GDD* (7{sup}`th` row) in {numref}`Table Crop phenology parameters`. Such latitudinal variation in base temperature could slow $GDD_{T_{{\rm 2m}} }$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. -Separate reproductive pool -'''''''''''''''''''''''''' -One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM5BGCCROP, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. +(separate-reproductive-pool)= -.. _Tillage: +#### Separate reproductive pool -Tillage -''''''' -Tillage is represented as an enhancement of the decomposition rate coefficient; see section :numref:`decomp_mgmt_modifiers`. +One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation {eq}`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM5BGCCROP, as allocation declines in stem, leaf, and root pools (see section {numref}`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. -.. _The irrigation model: +(tillage)= -The irrigation model --------------------- +#### Tillage -The CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to the soil moisture conditions simulated by the CLM. This irrigation algorithm is based loosely on the implementation of :ref:`Ozdogan et al. (2010) `. +Tillage is represented as an enhancement of the decomposition rate coefficient; see section {numref}`decomp_mgmt_modifiers`. -When irrigation is enabled, the crop areas of each grid cell are divided into irrigated and rainfed fractions according to a dataset of areas equipped for irrigation (:ref:`Portmann et al. 2010 `). Irrigated and rainfed crops are placed on separate soil columns, so that irrigation is only applied to the soil beneath irrigated crops. +(the-irrigation-model)= -In irrigated croplands, a check is made once per day to determine whether irrigation is required on that day. This check is made in the first time step after 6 AM local time. Irrigation is required if crop leaf area :math:`>` 0, and the available soil water is below a specified threshold. +## The irrigation model -The soil moisture deficit :math:`D_{irrig}` is +The CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to the soil moisture conditions simulated by the CLM. This irrigation algorithm is based loosely on the implementation of {ref}`Ozdogan et al. (2010) `. -.. math:: - :label: 25.61 +When irrigation is enabled, the crop areas of each grid cell are divided into irrigated and rainfed fractions according to a dataset of areas equipped for irrigation ({ref}`Portmann et al. 2010 `). Irrigated and rainfed crops are placed on separate soil columns, so that irrigation is only applied to the soil beneath irrigated crops. - D_{irrig} = \left\{ - \begin{array}{lr} - w_{target} - w_{avail} &\qquad w_{thresh} > w_{avail} \\ - 0 &\qquad w_{thresh} \le w_{avail} - \end{array} \right\} +In irrigated croplands, a check is made once per day to determine whether irrigation is required on that day. This check is made in the first time step after 6 AM local time. Irrigation is required if crop leaf area $>$ 0, and the available soil water is below a specified threshold. -where :math:`w_{target}` is the irrigation target soil moisture (mm) +The soil moisture deficit $D_{irrig}$ is -.. math:: - :label: 25.62 +$$ +D_{irrig} = \left\{ +\begin{array}{lr} +w_{target} - w_{avail} &\qquad w_{thresh} > w_{avail} \\ +0 &\qquad w_{thresh} \le w_{avail} +\end{array} \right\} +$$ (25.61) - w_{target} = \sum_{j=1}^{N_{irr}} \theta_{target} \Delta z_{j} \ . +where $w_{target}$ is the irrigation target soil moisture (mm) -The irrigation moisture threshold (mm) is +$$ +w_{target} = \sum_{j=1}^{N_{irr}} \theta_{target} \Delta z_{j} \ . +$$ (25.62) -.. math:: - :label: 25.63 - - w_{thresh} = f_{thresh} \left(w_{target} - w_{wilt}\right) + w_{wilt} - -where :math:`w_{wilt}` is the wilting point soil moisture (mm) +The irrigation moisture threshold (mm) is -.. math:: - :label: 25.64 +$$ +w_{thresh} = f_{thresh} \left(w_{target} - w_{wilt}\right) + w_{wilt} +$$ (25.63) - w_{wilt} = \sum_{j=1}^{N_{irr}} \theta_{wilt} \Delta z_{j} \ , +where $w_{wilt}$ is the wilting point soil moisture (mm) -and :math:`f_{thresh}` is a tuning parameter. The available moisture in the soil (mm) is +$$ +w_{wilt} = \sum_{j=1}^{N_{irr}} \theta_{wilt} \Delta z_{j} \ , +$$ (25.64) -.. math:: - :label: 25.65 +and $f_{thresh}$ is a tuning parameter. The available moisture in the soil (mm) is - w_{avail} = \sum_{j=1}^{N_{irr}} \theta_{j} \Delta z_{j} \ , +$$ +w_{avail} = \sum_{j=1}^{N_{irr}} \theta_{j} \Delta z_{j} \ , +$$ (25.65) -Note that :math:`w_{target}` is truly supposed to give the target soil moisture value that we're shooting for whenever irrigation happens; then the soil moisture deficit :math:`D_{irrig}` gives the difference between this target value and the current soil moisture. The irrigation moisture threshold :math:`w_{thresh}`, on the other hand, gives a threshold at which we decide to do any irrigation at all. The way this is written allows for the possibility that one may not want to irrigate every time there becomes even a tiny soil moisture deficit. Instead, one may want to wait until the deficit is larger before initiating irrigation; at that point, one doesn't want to just irrigate up to the "threshold" but instead up to the higher "target". The target should always be greater than or equal to the threshold. +Note that $w_{target}$ is truly supposed to give the target soil moisture value that we're shooting for whenever irrigation happens; then the soil moisture deficit $D_{irrig}$ gives the difference between this target value and the current soil moisture. The irrigation moisture threshold $w_{thresh}$, on the other hand, gives a threshold at which we decide to do any irrigation at all. The way this is written allows for the possibility that one may not want to irrigate every time there becomes even a tiny soil moisture deficit. Instead, one may want to wait until the deficit is larger before initiating irrigation; at that point, one doesn't want to just irrigate up to the "threshold" but instead up to the higher "target". The target should always be greater than or equal to the threshold. -:math:`N_{irr}` is the index of the soil layer corresponding to a specified depth :math:`z_{irrig}` (:numref:`Table Irrigation parameters`) and :math:`\Delta z_{j}` is the thickness of the soil layer in layer :math:`j` (section :numref:`Vertical Discretization`). :math:`\theta_{j}` is the volumetric soil moisture in layer :math:`j` (section :numref:`Soil Water`). :math:`\theta_{target}` and :math:`\theta_{wilt}` are the target and wilting point volumetric soil moisture values, respectively, and are determined by inverting :eq:`7.94` using soil matric potential parameters :math:`\Psi_{target}` and :math:`\Psi_{wilt}` (:numref:`Table Irrigation parameters`). After the soil moisture deficit :math:`D_{irrig}` is calculated, irrigation in an amount equal to :math:`\frac{D_{irrig}}{T_{irrig}}` (mm/s) is applied uniformly over the irrigation period :math:`T_{irrig}` (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., added to :math:`{q}_{grnd,liq}`: section :numref:`Canopy Water`). +$N_{irr}$ is the index of the soil layer corresponding to a specified depth $z_{irrig}$ ({numref}`Table Irrigation parameters`) and $\Delta z_{j}$ is the thickness of the soil layer in layer $j$ (section {numref}`Vertical Discretization`). $\theta_{j}$ is the volumetric soil moisture in layer $j$ (section {numref}`Soil Water`). $\theta_{target}$ and $\theta_{wilt}$ are the target and wilting point volumetric soil moisture values, respectively, and are determined by inverting {eq}`7.94` using soil matric potential parameters $\Psi_{target}$ and $\Psi_{wilt}$ ({numref}`Table Irrigation parameters`). After the soil moisture deficit $D_{irrig}$ is calculated, irrigation in an amount equal to $\frac{D_{irrig}}{T_{irrig}}$ (mm/s) is applied uniformly over the irrigation period $T_{irrig}$ (s). Irrigation water is applied directly to the ground surface, bypassing canopy interception (i.e., added to ${q}_{grnd,liq}$: section {numref}`Canopy Water`). -To conserve mass, irrigation is removed from river water storage (Chapter :numref:`rst_MOSART`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that river water storage is maintained above a specified threshold. +To conserve mass, irrigation is removed from river water storage (Chapter {numref}`rst_MOSART`). When river water storage is inadequate to meet irrigation demand, there are two options: 1) the additional water can be removed from the ocean model, or 2) the irrigation demand can be reduced such that river water storage is maintained above a specified threshold. -.. _Table Irrigation parameters: +(table irrigation parameters)= +```{eval-rst} .. table:: Irrigation parameters +--------------------------------------+-------------+ @@ -737,6 +694,7 @@ To conserve mass, irrigation is removed from river water storage (Chapter :numre +--------------------------------------+-------------+ | :math:`\Psi_{wilt}` (mm) | -150000 | +--------------------------------------+-------------+ +``` -.. add a reference to surface data in chapter2 - To accomplish this we downloaded data of percent irrigated and percent rainfed corn, soybean, and temperate cereals (wheat, barley, and rye) (:ref:`Portmann et al. 2010 `), available online from *ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* +% add a reference to surface data in chapter2 +% To accomplish this we downloaded data of percent irrigated and percent rainfed corn, soybean, and temperate cereals (wheat, barley, and rye) (:ref:`Portmann et al. 2010 `), available online from *ftp://ftp.rz.uni-frankfurt.de/pub/uni-frankfurt/physische\_geographie/hydrologie/public/data/MIRCA2000/harvested\_area\_grids.* diff --git a/doc/source/tech_note/index.rst b/doc/source/tech_note/index.rst index 61ccae4361..56cd7d3334 100644 --- a/doc/source/tech_note/index.rst +++ b/doc/source/tech_note/index.rst @@ -42,7 +42,7 @@ CLM Technical Note Plant_Mortality/CLM50_Tech_Note_Plant_Mortality.rst Fire/CLM50_Tech_Note_Fire.rst Methane/CLM50_Tech_Note_Methane.rst - Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst + Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md Transient_Landcover/CLM50_Tech_Note_Transient_Landcover.rst DGVM/CLM50_Tech_Note_DGVM.rst BVOCs/CLM50_Tech_Note_BVOCs.rst From fdc74bfcf2f5b7c417a8a637694bd29a9f1a2797 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 14:02:26 -0600 Subject: [PATCH 02/73] TN: Crops: Remove CLM history lessons. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 41 +++---------------- 1 file changed, 6 insertions(+), 35 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index c03150efbb..e6f1a38778 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -2,35 +2,6 @@ # Crops and Irrigation -(summary-of-clm5-0-updates-relative-to-the-clm4-5)= - -## Summary of CLM5.0 updates relative to the CLM4.5 - -We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note ({ref}`Oleson et al. 2013 `). - -CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the BGC configuration: - -- New crop functional types -- All crop areas are actively managed -- Fertilization rates updated based on crop type and geographic region -- New Irrigation triggers -- Phenological triggers vary by latitude for some crop types -- Ability to simulate transient crop management -- Adjustments to allocation and phenological parameters -- Crops reaching their maximum LAI triggers the grain fill phase -- Grain C and N pools are included in a 1-year product pool -- C for annual crop seeding comes from the grain C pool -- Initial seed C for planting is increased from 1 to 3 g C/m^2 - -These updates appear in detail in the sections below. Many also appear in {ref}`Levis et al. (2016) `. - -### Available new features since the CLM5 release - -- Addition of bioenergy crops -- Ability to customize crop calendars (sowing windows/dates, maturity requirements) using stream files -- Cropland soil tillage -- Crop residue removal - (the-crop-model)= ## The crop model: cash and bioenergy crops @@ -39,7 +10,7 @@ These updates appear in detail in the sections below. Many also appear in {ref}` Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 \[CLM3.0, {ref}`Oleson et al. (2004) ` \] (not published), then coupled to the CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and those are now incorporated into CLM5. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 \[CLM3.0, {ref}`Oleson et al. (2004) ` \] (not published), then coupled to the CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and those are now incorporated into CLM5 and later. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. @@ -47,9 +18,9 @@ With interactive crop management and, therefore, a more accurate representation ### Crop plant functional types -To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by {ref}`Portmann et al. (2010)` for present day. New in CLM5, crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries ({ref}`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter {numref}`rst_Transient Landcover Change`. +To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by {ref}`Portmann et al. (2010)` for present day. Crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries ({ref}`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter {numref}`rst_Transient Landcover Change`. -CLM5 includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. The representations of sugarcane, rice, cotton, tropical corn, and tropical soy were new in CLM5; miscanthus and switchgrass were added after the CLM5 release. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM5 includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. @@ -420,7 +391,7 @@ Notes: Allocation changes based on the crop phenology phases phenology (section {numref}`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop's leaf, live stem, fine root, and reproductive pools. -Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops: one during the leaf emergence phase (phenology phase 2), and a second during grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root C:N ratios for phase 2 are calculated using the new CLM5 carbon and nitrogen allocation scheme (Chapter {numref}`rst_CN Allocation`), which provides a target C:N value ({numref}`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growing season. +Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops: one during the leaf emergence phase (phenology phase 2), and a second during grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root C:N ratios for phase 2 are calculated using the standard CLM carbon and nitrogen allocation scheme (Chapter {numref}`rst_CN Allocation`), which provides a target C:N value ({numref}`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growing season. The BGC part of the model keeps track of a term representing excess maintenance respiration, which supplies the carbon required for maintenance respiration during periods of low photosynthesis (Chapter {numref}`rst_Plant Respiration`). Carbon supply for excess maintenance respiration cannot continue to happen after harvest for annual crops, so at harvest the excess respiration pool is turned into a flux that extracts CO{sub}`2` directly from the atmosphere. This way any excess maintenance respiration remaining at harvest is eliminated as if such respiration had not taken place. @@ -481,7 +452,7 @@ where ${C}_{leaf}$, ${C}_{stem}$, and ${C}_{froot}$ is the carbon in the plant l #### Harvest -Whereas live crop C and N in grain was formerly transferred to the litter pool upon harvest, CLM5 splits this between "food" and "seed" pools. In the former—more generally a "crop product" pool—C and N decay to the atmosphere over one year, similar to how the wood product pools work. The latter is used in the subsequent year to account for the C and N required for crop seeding. +CLM splits live crop grain C and N between "food" and "seed" pools. In the former—more generally a "crop product" pool—C and N decay to the atmosphere over one year, similar to how the wood product pools work. The latter is used in the subsequent year to account for the C and N required for crop seeding. Live leaf and stem biomass at harvest is transferred to biofuel, removed residue, and/or litter pools. @@ -586,7 +557,7 @@ where $z_{top}^{\max }$ is the maximum top-of-canopy height of the crop ({numref #### Interactive Fertilization -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current CLM5BGCCROP, manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: $$ f = n \times 86400 From b565241f5d99604b48bb133a81952d70a5e55c6b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 14:17:11 -0600 Subject: [PATCH 03/73] Crop TN: Mostly avoid mentioning CLM version. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index e6f1a38778..abcb658c59 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -20,14 +20,14 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by {ref}`Portmann et al. (2010)` for present day. Crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries ({ref}`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter {numref}`rst_Transient Landcover Change`. -CLM5 includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. (table crop plant functional types)= ```{eval-rst} -.. table:: Crop plant functional types (PFTs) included in CLM5BGCCROP. +.. table:: Crop plant functional types (PFTs) included in CLM with managed crops on (`BgcCrop` component sets). === =========================== ================ =========================== IVT Plant function types (PFTs) Management Class Crop Parameters Used @@ -103,7 +103,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr ### Phenology -CLM5-BGC includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter {numref}`rst_Vegetation Phenology and Turnover`). CLM5-BGC-crop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. +CLM includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter {numref}`rst_Vegetation Phenology and Turnover`). CLM uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. @@ -168,7 +168,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $GDD_{T_{ (table crop phenology parameters)= ```{eval-rst} -.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM5BGCCROP. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (`BgcCrop` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. :header-rows: 1 * - \ @@ -505,7 +505,7 @@ $$ (25.15) (table crop allocation parameters)= ```{eval-rst} -.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM5BGCCROP. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (`BgcCrop` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ \ temperate corn spring wheat temperate soybean cotton rice sugarcane tropical corn tropical soybean miscanthus switchgrass @@ -557,7 +557,7 @@ where $z_{top}^{\max }$ is the maximum top-of-canopy height of the crop ({numref #### Interactive Fertilization -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: $$ f = n \times 86400 @@ -591,7 +591,7 @@ where $baset$ is the *base temperature for GDD* (7{sup}`th` row) in {numref}`Tab #### Separate reproductive pool -One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation {eq}`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM5BGCCROP, as allocation declines in stem, leaf, and root pools (see section {numref}`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. +One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation {eq}`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM, as allocation declines in stem, leaf, and root pools (see section {numref}`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. (tillage)= From e1937c80674622796bc34b4d0bc4a78912d347d6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 14:18:20 -0600 Subject: [PATCH 04/73] Crops TN: No "the CLM." --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index abcb658c59..6449b5ce86 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -12,7 +12,7 @@ Groups developing Earth System Models generally account for the human footprint AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 \[CLM3.0, {ref}`Oleson et al. (2004) ` \] (not published), then coupled to the CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and those are now incorporated into CLM5 and later. -With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. +With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. (crop-plant-functional-types)= @@ -603,7 +603,7 @@ Tillage is represented as an enhancement of the decomposition rate coefficient; ## The irrigation model -The CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to the soil moisture conditions simulated by the CLM. This irrigation algorithm is based loosely on the implementation of {ref}`Ozdogan et al. (2010) `. +CLM includes the option to irrigate cropland areas that are equipped for irrigation. The application of irrigation responds dynamically to the simulated soil moisture conditions. This irrigation algorithm is based loosely on the implementation of {ref}`Ozdogan et al. (2010) `. When irrigation is enabled, the crop areas of each grid cell are divided into irrigated and rainfed fractions according to a dataset of areas equipped for irrigation ({ref}`Portmann et al. 2010 `). Irrigated and rainfed crops are placed on separate soil columns, so that irrigation is only applied to the soil beneath irrigated crops. From 99d02550751fdd5b716c84e2c3cf50d53388b7e2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 14:23:48 -0600 Subject: [PATCH 05/73] Crops TN: Convert italics to math. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 6449b5ce86..78180c1bb6 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -145,7 +145,7 @@ GDD_{{\rm 10}} =GDD_{10} +T_{2{\rm m}} -T_{f} -10 & \quad {\rm \; \; \; where\; \end{array} $$ (25.3) -where, if ${T}_{2m}$ - ${T}_{f}$ takes on values outside the above ranges within a day, then it equals the minimum or maximum value in the range for that day. ${T}_{f}$ is the freezing temperature of water and equals 273.15 K, ${T}_{2m}$ is the 2-m air temperature in units of K, and *GDD* is in units of degree-days. +where, if ${T}_{2m}$ - ${T}_{f}$ takes on values outside the above ranges within a day, then it equals the minimum or maximum value in the range for that day. ${T}_{f}$ is the freezing temperature of water and equals 273.15 K, ${T}_{2m}$ is the 2-m air temperature in units of K, and $GDD$ is in units of degree-days. (leaf-emergence)= @@ -157,7 +157,7 @@ According to AgroIBIS, leaves may emerge when the growing degree-days of soil te #### Grain fill -The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $GDD_{T_{soi} }$ but for 2-m air temperature, $GDD_{T_{{\rm 2m}} }$, must reach a heat unit threshold, *h*, of of 40 to 65% of ${GDD}_{mat}$ (see Phase 3 % ${GDD}_{mat}$ in {numref}`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the ${GDD}_{mat}$ is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $GDD_{T_{soi} }$ but for 2-m air temperature, $GDD_{T_{{\rm 2m}} }$, must reach a heat unit threshold, $h$, of of 40 to 65% of ${GDD}_{mat}$ (see Phase 3 % ${GDD}_{mat}$ in {numref}`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the ${GDD}_{mat}$ is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. (harvest)= @@ -406,7 +406,7 @@ $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} )\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } \le 1} \\ {a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (25.4) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients ({numref}`Table Crop allocation parameters`), and *h* is a heat unit threshold defined in section {numref}`Grain fill`. At a crop-specific maximum leaf area index, ${L}_{max}$ ({numref}`Table Crop allocation parameters`), carbon allocation is directed exclusively to the fine roots. +where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients ({numref}`Table Crop allocation parameters`), and $h$ is a heat unit threshold defined in section {numref}`Grain fill`. At a crop-specific maximum leaf area index, ${L}_{max}$ ({numref}`Table Crop allocation parameters`), carbon allocation is directed exclusively to the fine roots. (grain fill to harvest)= @@ -540,7 +540,7 @@ Notes: Crop growth phases and corresponding variables are described throughout t #### Physical Crop Characteristics -Leaf area index (*L*) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index (*S*) is equal to 0.1*L* for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2*L* for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the *S* is kept at 0.25 to simulate a post-harvest "stubble" on the ground. +Leaf area index ($L$) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index ($S$) is equal to 0.1$L$ for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2$L$ for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the $S$ is kept at 0.25 to simulate a post-harvest "stubble" on the ground. Crop heights at the top and bottom of the canopy, ${z}_{top}$ and ${z}_{bot}$ (m), come from the AgroIBIS formulation: @@ -557,13 +557,13 @@ where $z_{top}^{\max }$ is the maximum top-of-canopy height of the crop ({numref #### Interactive Fertilization -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, $f$, is set as soon as the leaf emergence phase for crops initiates: $$ f = n \times 86400 $$ (25.17) -where *n* is set to 20 fertilizer application days and 86400 is the number of seconds per day. When the crop enters phase 2 (leaf emergence) of its growth cycle, fertilizer application begins by initializing fertilizer amount to the total fertilizer at each column within the grid cell divided by the initialized *f*. Fertilizer is applied and *f* is decremented each time step until a zero balance on the counter is reached. +where $n$ is set to 20 fertilizer application days and 86400 is the number of seconds per day. When the crop enters phase 2 (leaf emergence) of its growth cycle, fertilizer application begins by initializing fertilizer amount to the total fertilizer at each column within the grid cell divided by the initialized $f$. Fertilizer is applied and $f$ is decremented each time step until a zero balance on the counter is reached. (biological-nitrogen-fixation-for-soybeans)= From 472997421f853ffc114468a2e31efb36704684d6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 14:25:01 -0600 Subject: [PATCH 06/73] Crops TN: Use \times instead of *. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 78180c1bb6..49c4e3f8ea 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -464,34 +464,34 @@ The following equations illustrate how this works. Subscript $p$ refers to eithe $$ CF_{p,biofuel} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * biofuel\_harvfrac + \right) \times biofuel\_harvfrac $$ (25.9) $$ CF_{p,removed\_residue} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * (1 - biofuel\_harvfrac) * crop\_residue\_removal\_frac + \right) \times (1 - biofuel\_harvfrac) \times crop\_residue\_removal\_frac $$ (harv_c_to_removed_residue) $$ CF_{p,litter} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) +CF_{p,alloc} + \right) \times \left( 1-biofuel\_harvfrac \right) \times \left( 1-crop\_residue\_removal\_frac \right) +CF_{p,alloc} $$ (25.11) with corresponding nitrogen fluxes: $$ NF_{p,biofuel} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * biofuel\_harvfrac + \right) \times biofuel\_harvfrac $$ (25.12) $$ NF_{p,removed\_residue} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1 - biofuel\_harvfrac \right) * crop\_residue\_removal\_frac + \right) \times \left( 1 - biofuel\_harvfrac \right) \times crop\_residue\_removal\_frac $$ (harv_n_to_removed_residue) $$ NF_{p,litter} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) * \left( 1-biofuel\_harvfrac \right) * \left( 1-crop\_residue\_removal\_frac \right) + \right) \times \left( 1-biofuel\_harvfrac \right) \times \left( 1-crop\_residue\_removal\_frac \right) $$ (25.14) where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and $biofuel\_harvfrac$ is the harvested fraction of leaf/livestem for biofuel feedstocks. @@ -499,7 +499,7 @@ where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is Annual food crop yields (g dry matter m{sup}`-2`) can be calculated by saving the GRAINC_TO_FOOD_ANN variable once per year, then postprocessing with Equation {eq}`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. $$ -\text{Grain yield} = \frac{GRAINC\_TO\_FOOD\_ANN)*0.85}{0.45} +\text{Grain yield} = \frac{GRAINC\_TO\_FOOD\_ANN) \times 0.85}{0.45} $$ (25.15) (table crop allocation parameters)= From 733d304216359343576c33062dff229bebbd1824 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 15:10:01 -0600 Subject: [PATCH 07/73] UG: Running custom crop cals: Fix cross-ref label. --- .../Running-with-custom-crop-calendars.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/Running-with-custom-crop-calendars.rst b/doc/source/users_guide/running-special-cases/Running-with-custom-crop-calendars.rst index 5e2b1998cc..34271d0027 100644 --- a/doc/source/users_guide/running-special-cases/Running-with-custom-crop-calendars.rst +++ b/doc/source/users_guide/running-special-cases/Running-with-custom-crop-calendars.rst @@ -1,7 +1,7 @@ -.. running-with-custom-crop-calendars: - .. include:: ../substitutions.rst +.. _running-with-custom-crop-calendars: + ======================================= Running with custom crop calendars ======================================= From aeea5ef36635c75ee179343ee30b288074b560c1 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 15:15:48 -0600 Subject: [PATCH 08/73] Crops TN: Update sowing window info. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 29 +++---------------- .../References/CLM50_Tech_Note_References.rst | 8 +++++ 2 files changed, 12 insertions(+), 25 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 49c4e3f8ea..22889e9823 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -111,7 +111,9 @@ Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from #### Planting -All crops must meet the following requirements between the minimum planting date and the maximum planting date (for the northern hemisphere) in {numref}`Table Crop phenology parameters`: +Each crop can be planted in each gridcell once per year, in the "sowing window." This is, by default, defined for each crop in each gridcell, with the start and end of the window drawn from the input files `stream_fldFileName_swindow_start` and `stream_fldFileName_swindow_end`, respectively. These sowing windows are centered on the sowing dates developed for phase 3 of the Inter-Sectoral Impacts Model Intercomparison Project's Agriculture sector runs ({ref}`Jägermeyr et al., 2021 `, {ref}`Rabin et al., 2023 `). The widths of the sowing windows are based on the original sowing windows from the `min_NH_planting_date`, `max_NH_planting_date`, `min_SH_planting_date`, and `max_SH_planting_date` parameters, which remain on the parameter file but are ignored by default (i.e., unless you set `cropcals_rx = .false.` in `user_nl_clm`). See {ref}`running-with-custom-crop-calendars`. + +To be planted, a crop patch must meet the following requirements sometime within its sowing window: $$ \begin{array}{c} @@ -121,7 +123,7 @@ $$ \end{array} $$ (25.1) -where ${T}_{10d}$ is the 10-day running mean of ${T}_{2m}$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $T_{2m}^{\min }$ (the daily minimum of ${T}_{2m}$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), ${GDD}_{8}$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). ${GDD}_{8}$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the ${GDD}_{8}$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as ${GDD}_{8} > 0$. In the southern hemisphere (SH) the NH requirements apply 6 months later. +where ${T}_{10d}$ is the 10-day running mean of ${T}_{2m}$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $T_{2m}^{\min }$ (the daily minimum of ${T}_{2m}$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), ${GDD}_{8}$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). ${GDD}_{8}$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the ${GDD}_{8}$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as ${GDD}_{8} > 0$. At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, ${GDD}_{mat}$, according to the following AgroIBIS rules: @@ -193,28 +195,6 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $GDD_{T_{ - 77, 78 - 71, 72 - 73, 74 - * - :math:`Date_{planting}^{min}` - - April 1 - - April 1 - - May 1 - - April 1 - - Janurary 1 - - Janurary 1 - - March 20 - - April 15 - - April 1 - - April 1 - * - :math:`Date_{planting}^{max}` - - June 15 - - June 15 - - June 15 - - May 31 - - Feburary 28 - - March 31 - - April 15 - - June 31 - - June 15 - - June 15 * - :math:`T_{p}`\(K) - 283.15 - 280.15 @@ -373,7 +353,6 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $GDD_{T_{ Notes: -- $Date_{planting}^{min}$ and $Date_{planting}^{max}$ are the minimum and maximum planting dates (defining the "sowing window") in the Northern Hemisphere; the corresponding dates in the Southern Hemisphere are shifted by 6 months. (See Sect. {numref}`Planting`.) These parameters can also be set with more geographic variation via input map stream files `stream_fldFileName_swindow_start` and `stream_fldFileName_swindow_end`. - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $GDD_{mat}$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 7dbd7399dd..e635c733ec 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -684,6 +684,10 @@ Jacksonetal1996: E., and Schulze, E. D. 1996. A global analysis of root distribu Jackson, T.L., Feddema, J.J., Oleson, K.W., Bonan, G.B., and Bauer, J.T. 2010. Parameterization of urban characteristics for global climate modeling. Annals of the Association of American Geographers. 100:848-865. +.. _Jägermeyretal2021: + +Jägermeyr, J., Müller, C., Minoli, S., Ray, D., & Siebert, S. (2021). GGCMI Phase 3 crop calendar [Data set]. Zenodo. https://doi.org/10.5281/zenodo.5062513. See also: https://www.isimip.org/gettingstarted/input-data-bias-adjustment/details/115/ + .. _JenkinsonColeman2008: Jenkinson, D. and Coleman, K. 2008. The turnover of organic carbon in subsoils. Part 2. Modelling carbon turnover. European Journal of Soil Science 59:400-413. @@ -1297,6 +1301,10 @@ Purves, D.W. et al., 2008. Predicting and understanding forest dynamics using a Qian, T et al., 2006. Simulation of global land surface conditions from 1948 to 2004: Part I: Forcing data and evaluations. J. Hydrometeorology 7, pp. 953-975. +.. _Rabinetal2023: + +Rabin, S., Sacks, W., Lombardozzi, D., Xia, L. & Robock, A., 2023. Observation-based sowing dates and cultivars significantly affect yield and irrigation for some crops in the Community Land Model (CLM5). Geosci. Model Dev. 16, 7253–7273 (2023). DOI 10.5194/gmd-16-7253-2023. https://gmd.copernicus.org/articles/16/7253/2023/ + .. _RamankuttyFoley1998: Ramankutty, N., and Foley, J. A., 1998. Characterizing patterns of global land use: An analysis of global croplands data. Global Biogeochemical Cycles, 12, 667-685. From f4b6c8541ac695c32bf9c01ad440040cc9214482 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 15:25:44 -0600 Subject: [PATCH 09/73] Crops TN: Clarify "leaf emergence" phase. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 22889e9823..32f683ddce 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -153,6 +153,8 @@ where, if ${T}_{2m}$ - ${T}_{f}$ takes on values outside the above ranges within #### Leaf emergence +The "leaf emergence" phase is the period of vegetative growth between when the leaves first emerge from the soil to when filling of the reproductive organ begins. + According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($GDD_{T_{soi} }$ ), which is tracked since planting, reaches 1 to 5% of ${GDD}_{mat}$ (see Phase 2 % ${GDD}_{mat}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $GDD_{T_{soi} }$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $GDD_{T_{{\rm 2m}} }$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. (grain fill)= From 6bcc8579ecdd270a6cd9992da069e40b06a66ff2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 15:27:59 -0600 Subject: [PATCH 10/73] Crops TN: Simplify reference to maintenance respiration. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 32f683ddce..994a7e134d 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -374,7 +374,7 @@ Allocation changes based on the crop phenology phases phenology (section {numref Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops: one during the leaf emergence phase (phenology phase 2), and a second during grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root C:N ratios for phase 2 are calculated using the standard CLM carbon and nitrogen allocation scheme (Chapter {numref}`rst_CN Allocation`), which provides a target C:N value ({numref}`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growing season. -The BGC part of the model keeps track of a term representing excess maintenance respiration, which supplies the carbon required for maintenance respiration during periods of low photosynthesis (Chapter {numref}`rst_Plant Respiration`). Carbon supply for excess maintenance respiration cannot continue to happen after harvest for annual crops, so at harvest the excess respiration pool is turned into a flux that extracts CO{sub}`2` directly from the atmosphere. This way any excess maintenance respiration remaining at harvest is eliminated as if such respiration had not taken place. +Carbon supply for excess maintenance respiration (Chapter {numref}`rst_Plant Respiration`) cannot continue to happen after harvest for annual crops, so at harvest the excess respiration pool is turned into a flux that extracts CO{sub}`2` directly from the atmosphere. This way any excess maintenance respiration remaining at harvest is eliminated as if such respiration had not taken place. (leaf emergence to grain fill)= From c8de0562cf958a57cf4a2ec22ddfbdb4c4abe5da Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 28 May 2026 15:29:42 -0600 Subject: [PATCH 11/73] Crops TN: Fix typos. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 994a7e134d..c1c15a8ea3 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -370,7 +370,7 @@ Notes: ### Allocation -Allocation changes based on the crop phenology phases phenology (section {numref}`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop's leaf, live stem, fine root, and reproductive pools. +Allocation changes based on the crop phenology phase (section {numref}`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop's leaf, live stem, fine root, and reproductive pools. Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops: one during the leaf emergence phase (phenology phase 2), and a second during grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root C:N ratios for phase 2 are calculated using the standard CLM carbon and nitrogen allocation scheme (Chapter {numref}`rst_CN Allocation`), which provides a target C:N value ({numref}`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growing season. @@ -552,9 +552,9 @@ where $n$ is set to 20 fertilizer application days and 86400 is the number of se Biological N fixation for soybeans is calculated by the fixation and uptake of nitrogen module (Chapter {numref}`rst_FUN`) and is the same as N fixation in natural vegetation. Unlike natural vegetation, where a fraction of each PFT are N fixers, all soybeans are treated as N fixers. -(latitude-vary-base-tempereature-for-growing-degree-days)= +(latitude-vary-base-temperature-for-growing-degree-days)= -#### Latitudinal variation in base growth tempereature +#### Latitudinal variation in base growth temperature For most crops, $GDD_{T_{{\rm 2m}} }$ (growing degree days since planting) is the same in all locations. However, for both rainfed and irrigated spring wheat and sugarcane, the calculation of $GDD_{T_{{\rm 2m}} }$ allows for latitudinal variation: From 88116c1c74dc860e512e98d24863f2fba9269b1d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 29 May 2026 10:52:21 -0600 Subject: [PATCH 12/73] Crops TN: Just refer to fsurdat and flanduse_timeseries docs. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index c1c15a8ea3..86af863dfa 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -18,7 +18,7 @@ With interactive crop management and, therefore, a more accurate representation ### Crop plant functional types -To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop grid cell coverage is assigned from satellite data (similar to all natural PFTs), and the managed crop type proportions within the crop area is based on the dataset created by {ref}`Portmann et al. (2010)` for present day. Crop area is extrapolated through time using the dataset provided by Land Use Model Intercomparison Project (LUMIP), which is part of CMIP6 Land use timeseries ({ref}`Lawrence et al. 2016 `). For more details about how crop distributions are determined, see Chapter {numref}`rst_Transient Landcover Change`. +To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`. CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). From 5d67e39f81e16699dc2ab0f9c78ce85b2e0e2845 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 10:00:34 -0600 Subject: [PATCH 13/73] Crops TN: Add line breaks to Eq 25.4. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 86af863dfa..3ff249096a 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -384,7 +384,10 @@ During phase 2, the allocation coefficients (fraction of available C) to each C pool are defined as: $$ -\begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} )\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } \le 1} \\ {a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} +\begin{array}{l} {a_{repr} =0} \\ +{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} )\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } \le 1} \\ +{a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (25.4) where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients ({numref}`Table Crop allocation parameters`), and $h$ is a heat unit threshold defined in section {numref}`Grain fill`. At a crop-specific maximum leaf area index, ${L}_{max}$ ({numref}`Table Crop allocation parameters`), carbon allocation is directed exclusively to the fine roots. From c3cddb4e3a9a4014275b4695d809a4fe6d878b5c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 10:04:49 -0600 Subject: [PATCH 14/73] Crops TN: Clarify logic in Eq. 25.4. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 3ff249096a..0ceca8a6e4 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -385,7 +385,7 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ -{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} )\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } {\rm \; \; \; where\; \; \; }\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} } \le 1} \\ +{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} }, 1\right)} \\ {a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (25.4) From 8da89a4b109cee41afca82d37adbdb0ef58b1d36 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 10:06:29 -0600 Subject: [PATCH 15/73] Crops TN: Relabel Eq. 25.4 to eq-lfemerg-allocations. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 0ceca8a6e4..e57cb9ff7b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -388,7 +388,7 @@ $$ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} }, 1\right)} \\ {a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} -$$ (25.4) +$$ (eq-lfemerg-allocations) where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients ({numref}`Table Crop allocation parameters`), and $h$ is a heat unit threshold defined in section {numref}`Grain fill`. At a crop-specific maximum leaf area index, ${L}_{max}$ ({numref}`Table Crop allocation parameters`), carbon allocation is directed exclusively to the fine roots. From 7ab265a2532b3a1695f4134ecd8b53f848b67543 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 10:07:15 -0600 Subject: [PATCH 16/73] Crops TN: eq-lfemerg-allocations: Change a cdot to a times. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index e57cb9ff7b..0f8d21b310 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -386,7 +386,7 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} )\cdot \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) From 53a59dc3254527c30f632db07d975774dd023098 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 10:35:43 -0600 Subject: [PATCH 17/73] Crops TN: Reference eq-lfemerg-allocations. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 0f8d21b310..f784462e92 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -396,7 +396,7 @@ where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final #### Grain fill -The calculation of $a_{froot}$ remains the same from phase 2 to phase 3. During grain fill (phase 3), other allocation coefficients change to: +The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg-allocations)) to phase 3. During grain fill (phase 3), other allocation coefficients change to: $$ \begin{array}{ll} From 178b3626f79148ad2957129b0946112b9b98b4b4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 11:05:24 -0600 Subject: [PATCH 18/73] Crops TN: Phase-transition HUI threshold symbols now have subscript phase name. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index f784462e92..3974ecc33b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -155,13 +155,13 @@ where, if ${T}_{2m}$ - ${T}_{f}$ takes on values outside the above ranges within The "leaf emergence" phase is the period of vegetative growth between when the leaves first emerge from the soil to when filling of the reproductive organ begins. -According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($GDD_{T_{soi} }$ ), which is tracked since planting, reaches 1 to 5% of ${GDD}_{mat}$ (see Phase 2 % ${GDD}_{mat}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $GDD_{T_{soi} }$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $GDD_{T_{{\rm 2m}} }$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. +According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($GDD_{T_{soi} }$ ), which is tracked since planting, reaches 1 to 5% of ${GDD}_{mat}$ (see $h_{lfemerg}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $GDD_{T_{soi} }$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $GDD_{T_{{\rm 2m}} }$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. (grain fill)= #### Grain fill -The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $GDD_{T_{soi} }$ but for 2-m air temperature, $GDD_{T_{{\rm 2m}} }$, must reach a heat unit threshold, $h$, of of 40 to 65% of ${GDD}_{mat}$ (see Phase 3 % ${GDD}_{mat}$ in {numref}`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the ${GDD}_{mat}$ is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $GDD_{T_{soi} }$ but for 2-m air temperature, $GDD_{T_{{\rm 2m}} }$, must reach a heat unit threshold, $h_{grain}$, of 40 to 65% of ${GDD}_{mat}$ (see {numref}`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the ${GDD}_{mat}$ is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. (harvest)= @@ -252,7 +252,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $GDD_{T_{ - ≤ 2100 - 950-1850 - 950-1850 - * - Phase 2 % :math:`{GDD}_{mat}` + * - :math:`h_{lfemerg}` (% :math:`{GDD}_{mat}`) - 3% - 5% - 3% @@ -263,7 +263,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $GDD_{T_{ - 3% - 3% - 3% - * - Phase 3 % :math:`{GDD}_{mat}` + * - :math:`h_{grainfill}` (% :math:`{GDD}_{mat}`) - 65% - 60% - 50% @@ -358,6 +358,7 @@ Notes: - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $GDD_{mat}$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. +- $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $GDD_{mat}$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). - $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $GDD_{mat}$. - $z_{top}^{\max }$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). - SLA is specific leaf area (see Chapter {numref}`rst_Photosynthetic Capacity`). @@ -386,11 +387,11 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{GDD_{T_{{\rm 2m}} } }{GDD_{{\rm mat}} }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{GDD_{T_{{\rm 2m}} } }{h_{grain}} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients ({numref}`Table Crop allocation parameters`), and $h$ is a heat unit threshold defined in section {numref}`Grain fill`. At a crop-specific maximum leaf area index, ${L}_{max}$ ({numref}`Table Crop allocation parameters`), carbon allocation is directed exclusively to the fine roots. +where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed exclusively to the fine roots. See {numref}`Table Crop allocation parameters` for parameter values. (grain fill to harvest)= @@ -401,16 +402,16 @@ The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg $$ \begin{array}{ll} a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1 \\ +a_{leaf} =a_{leaf} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h_{grain}}{GDD_{{\rm mat}} d_{L} -h_{grain}} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h_{grain}}{GDD_{{\rm mat}} d_{L} -h_{grain}} \le 1 \\ \\ a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h}{GDD_{{\rm mat}} d_{L} -h} \le 1 \\ +a_{livestem} =a_{livestem} \left(1-\frac{GDD_{T_{{\rm 2m}} } -h_{grain}}{GDD_{{\rm mat}} d_{L} -h_{grain}} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{GDD_{T_{{\rm 2m}} } -h_{grain}}{GDD_{{\rm mat}} d_{L} -h_{grain}} \le 1 \\ \\ a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} $$ (25.5) -where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, and $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients ({numref}`Table Crop allocation parameters`). +where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. (nitrogen-retranslocation-for-crops)= From 39ca4ec2c515b003d262f5d6b15fef4366c79d88 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 11:38:30 -0600 Subject: [PATCH 19/73] Crops TN: Add math macros for GDD symbols. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 65 +++++++++++-------- 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 3974ecc33b..9ce4bdb3d1 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,3 +1,12 @@ + +$$\newcommand{\gddmat}{GDD_\textrm{mat}}$$ +$$\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$$ +$$\newcommand{\ttwom}{T_\textrm{2m}}$$ +$$\newcommand{\gddacctwom}{GDD_{\ttwom}}$$ +$$\newcommand{\gddzero}{GDD_0}$$ +$$\newcommand{\gddeight}{GDD_8}$$ +$$\newcommand{\gddten}{GDD_{10}}$$ + (rst_crops and irrigation)= # Crops and Irrigation @@ -119,35 +128,35 @@ $$ \begin{array}{c} {T_{10d} >T_{p} } \\ {T_{10d}^{\min } >T_{p}^{\min } } \\ -{GDD_{8} \ge GDD_{\min } } +{\gddeight \ge GDD_{\min } } \end{array} $$ (25.1) -where ${T}_{10d}$ is the 10-day running mean of ${T}_{2m}$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $T_{2m}^{\min }$ (the daily minimum of ${T}_{2m}$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), ${GDD}_{8}$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). ${GDD}_{8}$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the ${GDD}_{8}$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as ${GDD}_{8} > 0$. +where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeight$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeight$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeight$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeight > 0$. -At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, ${GDD}_{mat}$, according to the following AgroIBIS rules: +At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, $\gddmat$, according to the following AgroIBIS rules: $$ \begin{array}{lll} -GDD_{{\rm mat}}^{{\rm corn,sugarcane}} =0.85 GDD_{{\rm 8}} & {\rm \; \; \; and\; \; \; }& 950 Date: Sun, 31 May 2026 11:57:06 -0600 Subject: [PATCH 20/73] Crops TN: Use math macros for baset and ztopmx. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 9ce4bdb3d1..fbaa2e1792 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -6,6 +6,8 @@ $$\newcommand{\gddacctwom}{GDD_{\ttwom}}$$ $$\newcommand{\gddzero}{GDD_0}$$ $$\newcommand{\gddeight}{GDD_8}$$ $$\newcommand{\gddten}{GDD_{10}}$$ +$$\newcommand{\parambaset}{T_\textrm{base}}$$ +$$\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$$ (rst_crops and irrigation)= @@ -239,7 +241,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 50 - 50 - 50 - * - base temperature for GDD (°C) + * - :math:`parambaset` (°C) - 8 - 0 - 10 @@ -366,10 +368,11 @@ Notes: - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. +- $\parambaset$ is the minimum temperature for accumulating growing degree-days. - $\gddmat$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. - $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $\gddmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). - $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddmat$. -- $z_{top}^{\max }$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). +- $\paramztopmx$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). - SLA is specific leaf area (see Chapter {numref}`rst_Photosynthetic Capacity`). - $\chi _{L}$ is the leaf orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. (See Sect. {numref}`Canopy Radiative Transfer`.) - grperc is the growth respiration factor (see Sect. {numref}`Growth Respiration`). @@ -540,12 +543,12 @@ Crop heights at the top and bottom of the canopy, ${z}_{top}$ and ${z}_{bot}$ (m $$ \begin{array}{l} -{z_{top} =z_{top}^{\max } \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ +{z_{top} = \paramztopmx \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ {z_{bot} =0.02{\rm m}} \end{array} $$ (25.16) -where $z_{top}^{\max }$ is the maximum top-of-canopy height of the crop ({numref}`Table Crop phenology parameters`) and $L_{\max }$ is the maximum leaf area index ({numref}`Table Crop allocation parameters`). +where $\paramztopmx$ is the maximum top-of-canopy height of the crop ({numref}`Table Crop phenology parameters`) and $L_{\max }$ is the maximum leaf area index ({numref}`Table Crop allocation parameters`). (interactive-fertilization)= @@ -574,12 +577,12 @@ For most crops, $\gddacctwom$ (growing degree days since planting) is the same i $$ latitudinal\ variation\ in\ base\ T = \left\{ \begin{array}{lr} -baset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ -baset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 +\parambaset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ +\parambaset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 \end{array} \right\} $$ (25.18) -where $baset$ is the *base temperature for GDD* (7{sup}`th` row) in {numref}`Table Crop phenology parameters`. Such latitudinal variation in base temperature could slow $\gddacctwom$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. +where $\parambaset$ is the *base temperature for GDD* (7{sup}`th` row) in {numref}`Table Crop phenology parameters`. Such latitudinal variation in base temperature could slow $\gddacctwom$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. (separate-reproductive-pool)= From d5dd124c5ca2f2f7dc6359c5c2fdcc14ce8dd694 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 16:51:09 -0600 Subject: [PATCH 21/73] Crops TN: Update maturity requirement section w/ new behavior. Delete info about old behavior. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 75 +++++++++++-------- 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index fbaa2e1792..1039a66e09 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,11 +1,19 @@ $$\newcommand{\gddmat}{GDD_\textrm{mat}}$$ +$$\newcommand{\gddmatbl}{\gddmat^\textrm{bl}}$$ $$\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$$ $$\newcommand{\ttwom}{T_\textrm{2m}}$$ $$\newcommand{\gddacctwom}{GDD_{\ttwom}}$$ $$\newcommand{\gddzero}{GDD_0}$$ $$\newcommand{\gddeight}{GDD_8}$$ $$\newcommand{\gddten}{GDD_{10}}$$ +$$\newcommand{\gddx}{GDD_x}$$ +$$\newcommand{\gddzerorun}{\overline{\gddzero}^\textrm{20yr}}$$ +$$\newcommand{\gddeightrun}{\overline{\gddeight}^\textrm{20yr}}$$ +$$\newcommand{\gddtenrun}{\overline{\gddten}^\textrm{20yr}}$$ +$$\newcommand{\gddxrun}{\overline{\gddx}^\textrm{20yr}}$$ +$$\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$$ +$$\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$$ $$\newcommand{\parambaset}{T_\textrm{base}}$$ $$\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$$ @@ -130,35 +138,50 @@ $$ \begin{array}{c} {T_{10d} >T_{p} } \\ {T_{10d}^{\min } >T_{p}^{\min } } \\ -{\gddeight \ge GDD_{\min } } +{\gddeightrun \ge GDD_{\min } } \end{array} $$ (25.1) -where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeight$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeight$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeight$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeight > 0$. +where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeightrun$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeightrun$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeightrun$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeightrun > 0$. -At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). The model updates the average growing degree-days necessary for the crop to reach vegetative and physiological maturity, $\gddmat$, according to the following AgroIBIS rules: +At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). + +#### Maturity requirement +At planting, CLM determines how many growing degree-days will be needed for the crop to reach maturity and thus be harvested. By default (i.e., `cropcals_rx_adapt = .true.`), this is set according to two input files with PFT-specific maps: +- `stream_fldfilename_cultivar_gdds` ($\gddmatbl$): the average growing-degree days to reach maturity in the "baseline" period. +- `stream_fldFileName_gdd20_baseline` ($\gddxrunbl$): the means over the baseline period of $\gddzerorun$, $\gddeightrun$, and $\gddtenrun$. + +Maturity requirement, $\gddmat$, is then calculated as: $$ -\begin{array}{lll} -\gddmat^{{\rm corn,sugarcane}} = 0.85 \gddeight & {\rm \; \; \; and\; \; \; }& 950 <\gddmat^{{\rm corn,sugarcane}} <1850{}^\circ {\rm days} \\ -\gddmat^{{\rm spring\ wheat,cotton}} = \gddzero & {\rm \; \; \; and\; \; \; } & \gddmat^{{\rm spring\ wheat,cotton}} <1700{}^\circ {\rm days} \\ -\gddmat^{{\rm temp.soy}} = \gddten & {\rm \; \; \; and\; \; \; } & \gddmat^{{\rm temp.soy}} <1900{}^\circ {\rm days} \\ -\gddmat^{{\rm rice}} = \gddzero & {\rm \; \; \; and\; \; \; } & \gddmat^{{\rm rice}} <2100{}^\circ {\rm days} \\ -\gddmat^{{\rm trop.soy}} = \gddten & {\rm \; \; \; and\; \; \; } & \gddmat^{{\rm trop.soy}} <2100{}^\circ {\rm days} -\end{array} -$$ (25.2) +\gddmat = \max \left( 1,\ \gddmatbl \times \frac{\gddxrun}{\gddxrunbl} \right), +$$ (gddmat-rx-adapt) + +where $x$ is 0 (wheat, cotton, and rice), 8 (corn, sugarcane, _Miscanthus_, and switchgrass), or 10 (soybean). This allows the maturity requirement to "adapt" over time, being lower in cool periods and higher in warm periods. The baseline period is the 1980-2009 growing seasons (i.e., seasons where planting occurred in those calendar years, inclusive); baseline values were calculated based on a half-degree, land-only run with CRU-JRA climate forcings (Rabin et al., in prep.). The minimum value of 1 avoids numeric issues when $\gddmat$ is in the denominator of a calculation. + +- **Check baseline period** + +If `cropcals_rx_adapt` is false but `cropcals_rx` is true, the calculation is just $\gddmat = \gddmatbl$. + +If both `cropcals_rx_adapt` and `cropcals_rx` are false, or if $\gddmatbl$ is negative, then CLM sets $\gddmat$ according to various crop-specific rules based on $\gddx$, the PFT-specific parameter `hybgdd`, and hard-coded minimum and maximum values. -where $\gddzero$, $\gddeight$, and $\gddten$ are the 20-year running mean growing degree-days tracked from April through September (NH) over 0°C, 8°C, and 10°C, respectively, with maximum daily increments of 26 degree-days (for $\gddzero$) or 30 degree-days (for $\gddeight$ and $\gddten$). Equation {eq}`25.3` shows how we calculate $\gddzero$, $\gddeight$, and $\gddten$ for each model timestep: +Equation {eq}`25.3` shows how we calculate $\gddzero$, $\gddeight$, and $\gddten$ for each model timestep: $$ -\begin{array}{lll} -\gddzero =\gddzero +T_{2{\rm m}} -T_{f} & \quad {\rm \; \; \; where\; \; \; } & 0 \le T_{2{\rm m}} -T_{f} \le 26{}^\circ {\rm days} \\ -\gddeight =\gddeight +T_{2{\rm m}} -T_{f} -8 & \quad {\rm \; \; \; where\; \; \; } & 0 \le T_{2{\rm m}} -T_{f} -8\le 30{}^\circ {\rm days} \\ -\gddten =\gddten +T_{2{\rm m}} -T_{f} -10 & \quad {\rm \; \; \; where\; \; \; } & 0 \le T_{2{\rm m}} -T_{f} -10\le 30{}^\circ {\rm days} -\end{array} +\gddx = \gddx + \frac{\max \left( \gddxdaymax,\ \min \left[ 0,\ \ttwom - 273.15 - x \right] \right)}{48} $$ (25.3) -where, if $\ttwom$ - ${T}_{f}$ takes on values outside the above ranges within a day, then it equals the minimum or maximum value in the range for that day. ${T}_{f}$ is the freezing temperature of water and equals 273.15 K, $\ttwom$ is the 2-m air temperature in units of K, and $GDD$ is in units of degree-days. +where $\ttwom$ is the 2-m air temperature (K), 273.15 K is the freezing temperature of water, and $GDD$ is in units of °C-days. $\gddxdaymax$, the maximum daily growing degree-day accumulation, is 26°C for $x=0$ and 30°C for $x=8$ and $x=10$. + +- **Is there a pre-existing symbol for number of timesteps in a day that we could use instead of 48?** + +By default, the $\gddx$ values are set to zero at the beginning of the "$\gddx$ season" and then accumulated through its end: from April 1 through September 30 in the Northern Hemisphere and from October 1 through March 31 in the Southern Hemisphere. (Setting `stream_gdd20_seasons = .true.` would instead take those start and end dates from PFT-specific maps in the input files `stream_fldFileName_gdd20_season_start` and `stream_fldFileName_gdd20_season_end`, respectively; however, this is not scientifically supported.) At the end of each $\gddx$ season, the final value of $\gddx$ is incorporated into $\gddxrun$ like so: + +$$ +\gddxrun = \frac{\gddxrun \times \min(n-1, 19) + \gddx}{20}, +$$ (update-gddxrun) + +where $n$ is the number of years that $\gddxrun$ gas been calculated for. Note that this is not a true rolling 20-year mean, which would come with a memory cost in the simulation as a 20-member array would need to be saved for each PFT. (leaf-emergence)= @@ -172,7 +195,7 @@ According to AgroIBIS, leaves may emerge when the growing degree-days of soil te #### Grain fill -The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $h_{grain}$, of 40 to 65% of $\gddmat$ (see {numref}`Table Crop phenology parameters`). For crops with the C4 photosynthetic pathway (temperate and tropical corn, sugarcane), the $\gddmat$ is based on an empirical function and ranges between 950 and 1850. The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $h_{grain}$, of 40 to 65% of $\gddmat$ (see {numref}`Table Crop phenology parameters`). The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. (harvest)= @@ -241,7 +264,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 50 - 50 - 50 - * - :math:`parambaset` (°C) + * - :math:`\parambaset` (°C) - 8 - 0 - 10 @@ -252,17 +275,6 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 10 - 8 - 8 - * - :math:`\gddmat` (degree-days) - - 950-1850 - - ≤ 1700 - - ≤ 1900 - - ≤ 1700 - - ≤ 2100 - - 950-1850 - - 950-1850 - - ≤ 2100 - - 950-1850 - - 950-1850 * - :math:`h_{lfemerg}` (% :math:`\gddmat`) - 3% - 5% @@ -369,7 +381,6 @@ Notes: - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $\parambaset$ is the minimum temperature for accumulating growing degree-days. -- $\gddmat$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. - $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $\gddmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). - $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddmat$. - $\paramztopmx$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). From b5ec5daf51664976eea1a84a416f657fb791c551 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 31 May 2026 16:53:42 -0600 Subject: [PATCH 22/73] Crops TN: Reduce number of blank lines from math macro defs. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 1039a66e09..0cf378d267 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,21 +1,21 @@ -$$\newcommand{\gddmat}{GDD_\textrm{mat}}$$ -$$\newcommand{\gddmatbl}{\gddmat^\textrm{bl}}$$ -$$\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$$ -$$\newcommand{\ttwom}{T_\textrm{2m}}$$ -$$\newcommand{\gddacctwom}{GDD_{\ttwom}}$$ -$$\newcommand{\gddzero}{GDD_0}$$ -$$\newcommand{\gddeight}{GDD_8}$$ -$$\newcommand{\gddten}{GDD_{10}}$$ -$$\newcommand{\gddx}{GDD_x}$$ -$$\newcommand{\gddzerorun}{\overline{\gddzero}^\textrm{20yr}}$$ -$$\newcommand{\gddeightrun}{\overline{\gddeight}^\textrm{20yr}}$$ -$$\newcommand{\gddtenrun}{\overline{\gddten}^\textrm{20yr}}$$ -$$\newcommand{\gddxrun}{\overline{\gddx}^\textrm{20yr}}$$ -$$\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$$ -$$\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$$ -$$\newcommand{\parambaset}{T_\textrm{base}}$$ -$$\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$$ +$\newcommand{\gddmat}{GDD_\textrm{mat}}$ +$\newcommand{\gddmatbl}{\gddmat^\textrm{bl}}$ +$\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$ +$\newcommand{\ttwom}{T_\textrm{2m}}$ +$\newcommand{\gddacctwom}{GDD_{\ttwom}}$ +$\newcommand{\gddzero}{GDD_0}$ +$\newcommand{\gddeight}{GDD_8}$ +$\newcommand{\gddten}{GDD_{10}}$ +$\newcommand{\gddx}{GDD_x}$ +$\newcommand{\gddzerorun}{\overline{\gddzero}^\textrm{20yr}}$ +$\newcommand{\gddeightrun}{\overline{\gddeight}^\textrm{20yr}}$ +$\newcommand{\gddtenrun}{\overline{\gddten}^\textrm{20yr}}$ +$\newcommand{\gddxrun}{\overline{\gddx}^\textrm{20yr}}$ +$\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$ +$\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$ +$\newcommand{\parambaset}{T_\textrm{base}}$ +$\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$ (rst_crops and irrigation)= From 4996d0253c24812ebea5a80c677f549ec543ec51 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 1 Jun 2026 08:52:14 -0600 Subject: [PATCH 23/73] Crops TN: Phenology: Delete bit about non-crop PFTs. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 0cf378d267..aad75fd8aa 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -122,7 +122,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr ### Phenology -CLM includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter {numref}`rst_Vegetation Phenology and Turnover`). CLM uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. +CLM uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. From cbd7a0b5d245f920382a99301b275c5fc480ddb3 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 1 Jun 2026 09:55:23 -0600 Subject: [PATCH 24/73] Crops TN: Improve crop phen params table caption. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index aad75fd8aa..d9e148e663 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -206,7 +206,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct (table crop phenology parameters)= ```{eval-rst} -.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (`BgcCrop` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (``BgcCrop`` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. Where there are two values in a cell, they refer to the rainfed and irrigated functional types, respectively. :header-rows: 1 * - \ From 72b847c9b8cfecf71301e57283d31f9f9b16365c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 2 Jun 2026 10:29:11 -0600 Subject: [PATCH 25/73] Crops TN: Refer to section on landunits and soil cols. --- doc/doc-builder | 2 +- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/doc-builder b/doc/doc-builder index 15e171dfcf..6607280dd7 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 15e171dfcf77ca2bd85415a99a50ad3994c608c4 +Subproject commit 6607280dd7a96d5606fbd6e8abe547ac0da4d62f diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index d9e148e663..1fe9a1f462 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -37,7 +37,7 @@ With interactive crop management and, therefore, a more accurate representation ### Crop plant functional types -To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`. +To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). From 0b655964a6ec3e9192b17078b1dcedc3743b1c15 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 3 Jun 2026 14:48:16 -0600 Subject: [PATCH 26/73] Crops TN: Clarify allocation after reaching max LAI. --- ccs_config | 2 +- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/ccs_config b/ccs_config index 39683243b4..7020eb9a16 160000 --- a/ccs_config +++ b/ccs_config @@ -1 +1 @@ -Subproject commit 39683243b4e8e5b4576fd1b828c3ec4c9e15bc6b +Subproject commit 7020eb9a16a2c1cde7b7fbb588e08dbb7b1ce85c diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 1fe9a1f462..c48cd9d691 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -414,7 +414,7 @@ $$ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed exclusively to the fine roots. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to the fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. (grain fill to harvest)= @@ -436,6 +436,8 @@ $$ (25.5) where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. +As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, ${L}_{max}$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. + (nitrogen-retranslocation-for-crops)= #### Nitrogen retranslocation for crops From 959b7956f34fd9c3b4f0fac03bd5cba44e670f2a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 3 Jun 2026 15:00:38 -0600 Subject: [PATCH 27/73] Crops TN: New math macro \huigrain. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index c48cd9d691..2bdc97ec22 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -14,6 +14,7 @@ $\newcommand{\gddtenrun}{\overline{\gddten}^\textrm{20yr}}$ $\newcommand{\gddxrun}{\overline{\gddx}^\textrm{20yr}}$ $\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$ $\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$ +$\newcommand{\huigrain}{h_{grain}}$ $\newcommand{\parambaset}{T_\textrm{base}}$ $\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$ @@ -195,7 +196,7 @@ According to AgroIBIS, leaves may emerge when the growing degree-days of soil te #### Grain fill -The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $h_{grain}$, of 40 to 65% of $\gddmat$ (see {numref}`Table Crop phenology parameters`). The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $\huigrain$, of 40 to 65% of $\gddmat$ (see {numref}`Table Crop phenology parameters`). The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. (harvest)= @@ -410,7 +411,7 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{\gddacctwom }{\gddmat }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{h_{grain}} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\huigrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) @@ -425,16 +426,16 @@ The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg $$ \begin{array}{ll} a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom -h_{grain}}{\gddmat d_{L} -h_{grain}} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom -h_{grain}}{\gddmat d_{L} -h_{grain}} \le 1 \\ +a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \le 1 \\ \\ a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom -h_{grain}}{\gddmat d_{L} -h_{grain}} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom -h_{grain}}{\gddmat d_{L} -h_{grain}} \le 1 \\ +a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \le 1 \\ \\ a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} $$ (25.5) -where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $\huigrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, ${L}_{max}$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. From bbd2386ba0e7eea1dc64f1aaffdda634c3acf254 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 3 Jun 2026 15:05:56 -0600 Subject: [PATCH 28/73] Crops TN: Better indicate threshold GDD/mat levels. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 45 ++++++++++--------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 2bdc97ec22..07d903e018 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,6 +1,6 @@ -$\newcommand{\gddmat}{GDD_\textrm{mat}}$ -$\newcommand{\gddmatbl}{\gddmat^\textrm{bl}}$ +$\newcommand{\gddthreshmat}{GDD_\textrm{*mat}}$ +$\newcommand{\gddthreshmatbl}{\gddthreshmat^\textrm{bl}}$ $\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$ $\newcommand{\ttwom}{T_\textrm{2m}}$ $\newcommand{\gddacctwom}{GDD_{\ttwom}}$ @@ -14,7 +14,8 @@ $\newcommand{\gddtenrun}{\overline{\gddten}^\textrm{20yr}}$ $\newcommand{\gddxrun}{\overline{\gddx}^\textrm{20yr}}$ $\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$ $\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$ -$\newcommand{\huigrain}{h_{grain}}$ +$\newcommand{\huithreshlfemerg}{h_\textrm{*lfemerg}}$ +$\newcommand{\huithreshgrain}{h_\textrm{*grain}}$ $\newcommand{\parambaset}{T_\textrm{base}}$ $\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$ @@ -149,22 +150,22 @@ At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain prod #### Maturity requirement At planting, CLM determines how many growing degree-days will be needed for the crop to reach maturity and thus be harvested. By default (i.e., `cropcals_rx_adapt = .true.`), this is set according to two input files with PFT-specific maps: -- `stream_fldfilename_cultivar_gdds` ($\gddmatbl$): the average growing-degree days to reach maturity in the "baseline" period. +- `stream_fldfilename_cultivar_gdds` ($\gddthreshmatbl$): the average growing-degree days to reach maturity in the "baseline" period. - `stream_fldFileName_gdd20_baseline` ($\gddxrunbl$): the means over the baseline period of $\gddzerorun$, $\gddeightrun$, and $\gddtenrun$. -Maturity requirement, $\gddmat$, is then calculated as: +Maturity requirement, $\gddthreshmat$, is then calculated as: $$ -\gddmat = \max \left( 1,\ \gddmatbl \times \frac{\gddxrun}{\gddxrunbl} \right), +\gddthreshmat = \max \left( 1,\ \gddthreshmatbl \times \frac{\gddxrun}{\gddxrunbl} \right), $$ (gddmat-rx-adapt) -where $x$ is 0 (wheat, cotton, and rice), 8 (corn, sugarcane, _Miscanthus_, and switchgrass), or 10 (soybean). This allows the maturity requirement to "adapt" over time, being lower in cool periods and higher in warm periods. The baseline period is the 1980-2009 growing seasons (i.e., seasons where planting occurred in those calendar years, inclusive); baseline values were calculated based on a half-degree, land-only run with CRU-JRA climate forcings (Rabin et al., in prep.). The minimum value of 1 avoids numeric issues when $\gddmat$ is in the denominator of a calculation. +where $x$ is 0 (wheat, cotton, and rice), 8 (corn, sugarcane, _Miscanthus_, and switchgrass), or 10 (soybean). This allows the maturity requirement to "adapt" over time, being lower in cool periods and higher in warm periods. The baseline period is the 1980-2009 growing seasons (i.e., seasons where planting occurred in those calendar years, inclusive); baseline values were calculated based on a half-degree, land-only run with CRU-JRA climate forcings (Rabin et al., in prep.). The minimum value of 1 avoids numeric issues when $\gddthreshmat$ is in the denominator of a calculation. - **Check baseline period** -If `cropcals_rx_adapt` is false but `cropcals_rx` is true, the calculation is just $\gddmat = \gddmatbl$. +If `cropcals_rx_adapt` is false but `cropcals_rx` is true, the calculation is just $\gddthreshmat = \gddthreshmatbl$. -If both `cropcals_rx_adapt` and `cropcals_rx` are false, or if $\gddmatbl$ is negative, then CLM sets $\gddmat$ according to various crop-specific rules based on $\gddx$, the PFT-specific parameter `hybgdd`, and hard-coded minimum and maximum values. +If both `cropcals_rx_adapt` and `cropcals_rx` are false, or if $\gddthreshmatbl$ is negative, then CLM sets $\gddthreshmat$ according to various crop-specific rules based on $\gddx$, the PFT-specific parameter `hybgdd`, and hard-coded minimum and maximum values. Equation {eq}`25.3` shows how we calculate $\gddzero$, $\gddeight$, and $\gddten$ for each model timestep: @@ -190,19 +191,19 @@ where $n$ is the number of years that $\gddxrun$ gas been calculated for. Note t The "leaf emergence" phase is the period of vegetative growth between when the leaves first emerge from the soil to when filling of the reproductive organ begins. -According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddmat$ (see $h_{lfemerg}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. +According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddthreshmat$ (see $h_{lfemerg}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. (grain fill)= #### Grain fill -The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $\huigrain$, of 40 to 65% of $\gddmat$ (see {numref}`Table Crop phenology parameters`). The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. +The grain fill phase (phase 3) begins in one of two ways. The first potential trigger is based on temperature, similar to phase 2. A variable tracked since planting, similar to $\gddaccsoil$ but for 2-m air temperature, $\gddacctwom$, must reach a heat unit threshold, $\huithreshgrain$, of 40 to 65% of $\gddthreshmat$ (see {numref}`Table Crop phenology parameters`). The second potential trigger for phase 3 is based on leaf area index. When the maximum value of leaf area index is reached in phase 2 ({numref}`Table Crop allocation parameters`), phase 3 begins. In phase 3, the leaf area index begins to decline in response to a background litterfall rate calculated as the inverse of leaf longevity for the PFT as done in the BGC part of the model. (harvest)= #### Harvest -Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacctwom$ reaches 100% of $\gddmat$ or the number of days past planting reaches a crop-specific maximum ({numref}`Table Crop phenology parameters`), then the crop is harvested. Harvest occurs in one time step using the BGC leaf offset algorithm. +Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacctwom$ reaches 100% of $\gddthreshmat$ or the number of days past planting reaches a crop-specific maximum ({numref}`Table Crop phenology parameters`), then the crop is harvested. Harvest occurs in one time step using the BGC leaf offset algorithm. (table crop phenology parameters)= @@ -276,7 +277,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 10 - 8 - 8 - * - :math:`h_{lfemerg}` (% :math:`\gddmat`) + * - :math:`\huithreshlfemerg` (% :math:`\gddthreshmat`) - 3% - 5% - 3% @@ -287,7 +288,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 3% - 3% - 3% - * - :math:`h_{grainfill}` (% :math:`\gddmat`) + * - :math:`\huithreshgrain` (% :math:`\gddthreshmat`) - 65% - 60% - 50% @@ -382,8 +383,8 @@ Notes: - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $\parambaset$ is the minimum temperature for accumulating growing degree-days. -- $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $\gddmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). -- $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddmat$. +- $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $\gddthreshmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). +- $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddthreshmat$. - $\paramztopmx$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). - SLA is specific leaf area (see Chapter {numref}`rst_Photosynthetic Capacity`). - $\chi _{L}$ is the leaf orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. (See Sect. {numref}`Canopy Radiative Transfer`.) @@ -410,12 +411,12 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ -{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{\gddacctwom }{\gddmat }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\huigrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\huithreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $h_{grain}$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to the fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to the fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. (grain fill to harvest)= @@ -426,16 +427,16 @@ The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg $$ \begin{array}{ll} a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \le 1 \\ +a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \le 1 \\ \\ a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \huigrain}{\gddmat d_{L} - \huigrain} \le 1 \\ +a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \le 1 \\ \\ a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} $$ (25.5) -where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $\huigrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, ${L}_{max}$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. From d4b9bef2900a4220dda65872b66401270f81e196 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 3 Jun 2026 17:41:29 -0600 Subject: [PATCH 29/73] More complete and accurate description of HUI threshold for grainfill. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 26 ++++++++++++++----- .../References/CLM50_Tech_Note_References.rst | 4 +++ 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 07d903e018..3106fa522c 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -1,4 +1,5 @@ +$\newcommand{\gddthreshgrain}{GDD_\textrm{*grain}}$ $\newcommand{\gddthreshmat}{GDD_\textrm{*mat}}$ $\newcommand{\gddthreshmatbl}{\gddthreshmat^\textrm{bl}}$ $\newcommand{\gddaccsoil}{GDD_{T_\textrm{soi}}}$ @@ -16,6 +17,7 @@ $\newcommand{\gddxrunbl}{\overline{\gddx}^\textrm{20-yr,bl}}$ $\newcommand{\gddxdaymax}{\gddx^\textrm{daymax}}$ $\newcommand{\huithreshlfemerg}{h_\textrm{*lfemerg}}$ $\newcommand{\huithreshgrain}{h_\textrm{*grain}}$ +$\newcommand{\huithreshgrainactual}{h_\textrm{*grain}^{'}}$ $\newcommand{\parambaset}{T_\textrm{base}}$ $\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$ @@ -191,7 +193,7 @@ where $n$ is the number of years that $\gddxrun$ gas been calculated for. Note t The "leaf emergence" phase is the period of vegetative growth between when the leaves first emerge from the soil to when filling of the reproductive organ begins. -According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddthreshmat$ (see $h_{lfemerg}$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. +According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddthreshmat$ (see $\huithreshlfemerg$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. (grain fill)= @@ -383,7 +385,7 @@ Notes: - $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) - $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $\parambaset$ is the minimum temperature for accumulating growing degree-days. -- $h_{lfemerg}$ and $h_{grainfill}$ are, respectively, the threshold fractions of $\gddthreshmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). +- $\huithreshlfemerg$ and $\huithreshgrain$ are, respectively, the threshold fractions of $\gddthreshmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). However, note the adjustment applied to $\huithreshgrain$ for some crops (Eq. {eq}`corn-huigrain-adjustment`). - $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddthreshmat$. - $\paramztopmx$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). - SLA is specific leaf area (see Chapter {numref}`rst_Photosynthetic Capacity`). @@ -412,11 +414,23 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\huithreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to the fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. + +For most crops, $\gddthreshgrain$ is equal to $\gddthreshmat$ times the PFT parameter $\huithreshgrain$ (`grnfill`). However, for corn, sugarcane, miscanthus, and switchgrass, an adjustment is applied ({ref}`Kucharik 2003 `; C.J. Kucharik, pers. comm.): + +$$ +\begin{aligned} +c &= \max \left( 73,\ \min \left[135, \frac{\gddthreshmat + 53.683}{13.882} \right] \right) \\ +\huithreshgrainactual &= \min \left( \max \left[ -0.002 * \left( c - 73 \right) + \huithreshgrain,\ \huithreshgrain-0.1 \right],\ \huithreshgrain \right) \\ +\gddthreshgrain &= \gddthreshmat \times \huithreshgrainactual +\end{aligned} +$$ (corn-huigrain-adjustment) + +At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. (grain fill to harvest)= @@ -427,10 +441,10 @@ The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg $$ \begin{array}{ll} a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \le 1 \\ +a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \le 1 \\ \\ a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \huithreshgrain}{\gddthreshmat d_{L} - \huithreshgrain} \le 1 \\ +a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \le 1 \\ \\ a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} diff --git a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst index 0846ec32a6..f3721c05f3 100644 --- a/doc/source/tech_note/References/CLM50_Tech_Note_References.rst +++ b/doc/source/tech_note/References/CLM50_Tech_Note_References.rst @@ -776,6 +776,10 @@ Koven, C.D., G. Hugelius, D.M. Lawrence, and W.R. Wieder, 2017: Higher climatolo Kucharik, C.J., J.M. Norman, and S.T. Gower, 1998. Measurements of branch area and adjusting leaf area index indirect measurements. Agricultural and Forest Meteorology 91.1, pp. 69-88. +.. _kucharik2003: + +Kucharik, C.J., 2003. Evaluation of a Process-Based Agro-Ecosystem Model (Agro-IBIS) across the U.S. Corn Belt: Simulations of the Interannual Variability in Maize Yield. Earth Interactions 7, paper 14. DOI: 10.1175/1087-3562(2003)007<0001:EOAPAM>2.0.CO;2. + .. _Kuchariketal2000: Kucharik, C.J., Foley, J.A., Delire, C., Fisher, V.A., Coe, M.T., Lenters, J.D., Young-Molling, C., and Ramankutty, N. 2000. Testing the performance of a dynamic global ecosystem model: water balance, carbon balance, and vegetation structure. Global Biogeochem. Cycles 14: 795–825. From aed8bc87a5548ebacfe0e8e8d376db34d77a4437 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 4 Jun 2026 10:48:35 -0600 Subject: [PATCH 30/73] Crops TN: Fix sentence about tropical param values. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 3106fa522c..f35426b7f1 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -43,7 +43,7 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. -CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were developed for the Amazon Basin, and planting date window is shifted by six months relative to the Northern Hemisphere. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. From 43808d38792f57c836e91a0f64b717de7b49da34 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 10:19:46 -0600 Subject: [PATCH 31/73] Crops TN: crop allocation params table now list-table. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 226 ++++++++++++++++-- 1 file changed, 202 insertions(+), 24 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index f35426b7f1..d0452e2bd5 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -530,32 +530,210 @@ $$ (25.15) (table crop allocation parameters)= -```{eval-rst} -.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (`BgcCrop` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. - - =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ - \ temperate corn spring wheat temperate soybean cotton rice sugarcane tropical corn tropical soybean miscanthus switchgrass - =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ - IVT 17, 18 19, 20 23, 24 41, 42 61, 62 67, 68 75, 76 77, 78 71, 72 73, 74 - :math:`a_{leaf}^{i}` 0.6 0.9 0.85 0.85 0.75 0.6 0.6 0.85 0.9 0.7 - :math:`{L}_{max}` (m :sup:`2` m :sup:`-2`) 5 7 6 6 7 5 5 6 10 6.5 - :math:`a_{froot}^{i}` 0.1 0.05 0.2 0.2 0.1 0.1 0.1 0.2 0.11 0.14 - :math:`a_{froot}^{f}` 0.05 0 0.2 0.2 0 0.05 0.05 0.2 0.09 0.09 - :math:`a_{leaf}^{f}` 0 0 0 0 0 0 0 0 0 0 - :math:`a_{livestem}^{f}` 0 0.05 0.3 0.3 0.05 0 0 0.3 0 0 - :math:`d_{L}` 1.05 1.05 1.05 1.05 1.05 1.05 1.05 1.05 1.05 1.05 - :math:`d_{alloc}^{stem}` 2 1 5 5 1 2 2 5 2 2 - :math:`d_{alloc}^{leaf}` 5 3 2 2 3 5 5 2 5 5 - :math:`{CN}_{leaf}` 25 20 20 20 20 25 25 20 25 25 - :math:`{CN}_{stem}` 50 50 50 50 50 50 50 50 50 50 - :math:`{CN}_{froot}` 42 42 42 42 42 42 42 42 42 42 - :math:`CN^f_{leaf}` 65 65 65 65 65 65 65 65 65 65 - :math:`CN^f_{stem}` 120 100 130 130 100 120 120 130 120 120 - :math:`CN^f_{froot}` 0 40 0 0 40 0 0 0 0 0 - :math:`{CN}_{grain}` 50 50 50 50 50 50 50 50 50 50 - =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ +```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). +:header-rows: 1 + +* - Parameter + - temperate corn + - spring wheat + - temperate soybean + - cotton + - rice + - sugarcane + - tropical corn + - tropical soybean + - miscanthus + - switchgrass +* - PFT index (1-based) + - 17, 18 + - 19, 20 + - 23, 24 + - 41, 42 + - 61, 62 + - 67, 68 + - 75, 76 + - 77, 78 + - 71, 72 + - 73, 74 +* - $a_{leaf}^{i}$ + - 0.6 + - 0.9 + - 0.85 + - 0.85 + - 0.75 + - 0.6 + - 0.6 + - 0.85 + - 0.9 + - 0.7 +* - ${L}_{max}$ (m{sup}`2` m{sup}`-2`) + - 5 + - 7 + - 6 + - 6 + - 7 + - 5 + - 5 + - 6 + - 10 + - 6.5 +* - $a_{froot}^{i}$ + - 0.1 + - 0.05 + - 0.2 + - 0.2 + - 0.1 + - 0.1 + - 0.1 + - 0.2 + - 0.11 + - 0.14 +* - $a_{froot}^{f}$ + - 0.05 + - 0 + - 0.2 + - 0.2 + - 0 + - 0.05 + - 0.05 + - 0.2 + - 0.09 + - 0.09 +* - $a_{leaf}^{f}$ + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 +* - $a_{livestem}^{f}$ + - 0 + - 0.05 + - 0.3 + - 0.3 + - 0.05 + - 0 + - 0 + - 0.3 + - 0 + - 0 +* - $d_{L}$ + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 + - 1.05 +* - $d_{alloc}^{stem}$ + - 2 + - 1 + - 5 + - 5 + - 1 + - 2 + - 2 + - 5 + - 2 + - 2 +* - $d_{alloc}^{leaf}$ + - 5 + - 3 + - 2 + - 2 + - 3 + - 5 + - 5 + - 2 + - 5 + - 5 +* - ${CN}_{leaf}$ + - 25 + - 20 + - 20 + - 20 + - 20 + - 25 + - 25 + - 20 + - 25 + - 25 +* - ${CN}_{stem}$ + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 +* - ${CN}_{froot}$ + - 42 + - 42 + - 42 + - 42 + - 42 + - 42 + - 42 + - 42 + - 42 + - 42 +* - $CN^f_{leaf}$ + - 65 + - 65 + - 65 + - 65 + - 65 + - 65 + - 65 + - 65 + - 65 + - 65 +* - $CN^f_{stem}$ + - 120 + - 100 + - 130 + - 130 + - 100 + - 120 + - 120 + - 130 + - 120 + - 120 +* - $CN^f_{froot}$ + - 0 + - 40 + - 0 + - 0 + - 40 + - 0 + - 0 + - 0 + - 0 + - 0 +* - ${CN}_{grain}$ + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 ``` + Notes: Crop growth phases and corresponding variables are described throughout the text. ${CN}_{leaf}$, ${CN}_{stem}$, and ${CN}_{froot}$ are the target C:N ratios used during the leaf emergence phase (phase 2). (other-features)= From 79472cffa69ff7657c0573dd9a3c881096910531 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 10:48:10 -0600 Subject: [PATCH 32/73] Crops TN: Update crop alloc params table values. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 141 ++++++++++-------- 1 file changed, 76 insertions(+), 65 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index d0452e2bd5..70166f2c57 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -20,6 +20,22 @@ $\newcommand{\huithreshgrain}{h_\textrm{*grain}}$ $\newcommand{\huithreshgrainactual}{h_\textrm{*grain}^{'}}$ $\newcommand{\parambaset}{T_\textrm{base}}$ $\newcommand{\paramztopmx}{z_\textrm{top}^\textrm{max}}$ +$\newcommand{\paramaleaff}{a_\textrm{leaf}^f}$ +$\newcommand{\paramfleafi}{a_\textrm{leaf}^i}$ +$\newcommand{\paramarooti}{a_\textrm{froot}^i}$ +$\newcommand{\paramarootf}{a_\textrm{froot}^f}$ +$\newcommand{\paramastemf}{a_\textrm{livestem}^f}$ +$\newcommand{\paramlaimx}{L_\textrm{max}}$ +$\newcommand{\paramdeclfact}{d_L}$ +$\newcommand{\paramallconsl}{d_\textrm{alloc}^\textrm{leaf}}$ +$\newcommand{\paramallconss}{d_\textrm{alloc}^\textrm{stem}}$ +$\newcommand{\paramleafcn}{CN_\textrm{leaf}}$ +$\newcommand{\paramfleafcn}{\paramleafcn^\textrm{f}}$ +$\newcommand{\paramlivewdcn}{CN_\textrm{stem}}$ +$\newcommand{\paramfstemcn}{\paramlivewdcn^\textrm{f}}$ +$\newcommand{\paramfrootcn}{CN_\textrm{froot}}$ +$\newcommand{\paramffrootcn}{\paramfrootcn^\textrm{f}}$ +$\newcommand{\paramgraincn}{CN_\textrm{grain}}$ (rst_crops and irrigation)= @@ -148,7 +164,7 @@ $$ (25.1) where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeightrun$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeightrun$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeightrun$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeightrun > 0$. -At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves (${CN}_{leaf}$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). +At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves ($\paramleafcn$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). #### Maturity requirement At planting, CLM determines how many growing degree-days will be needed for the crop to reach maturity and thus be harvested. By default (i.e., `cropcals_rx_adapt = .true.`), this is set according to two input files with PFT-specific maps: @@ -413,12 +429,12 @@ each C pool are defined as: $$ \begin{array}{l} {a_{repr} =0} \\ -{a_{froot} =a_{froot}^{i} -(a_{froot}^{i} -a_{froot}^{f} ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{a_{leaf}^{i} (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ +{a_{froot} = \paramarooti -(\paramarooti - \paramarootf ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ +{a_{leaf} =(1-a_{froot} ) \times \frac{\paramfleafi (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ {a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) -where $a_{leaf}^{i}$, $a_{froot}^{i}$, and $a_{froot}^{f}$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. +where $\paramfleafi$, $\paramarooti$, and $\paramarootf$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. For most crops, $\gddthreshgrain$ is equal to $\gddthreshmat$ times the PFT parameter $\huithreshgrain$ (`grnfill`). However, for corn, sugarcane, miscanthus, and switchgrass, an adjustment is applied ({ref}`Kucharik 2003 `; C.J. Kucharik, pers. comm.): @@ -430,7 +446,7 @@ c &= \max \left( 73,\ \min \left[135, \frac{\gddthreshmat + 53.683}{13.882} \rig \end{aligned} $$ (corn-huigrain-adjustment) -At a crop-specific maximum leaf area index, ${L}_{max}$, carbon allocation is directed almost exclusively to fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. +At a crop-specific maximum leaf area index, $\paramlaimx$, carbon allocation is directed almost exclusively to fine roots, with only 0.001% of carbon going to leaves. See {numref}`Table Crop allocation parameters` for parameter values. (grain fill to harvest)= @@ -440,19 +456,19 @@ The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg $$ \begin{array}{ll} -a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le a_{leaf}^{f} \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \right)^{d_{alloc}^{leaf} } \ge a_{leaf}^{f} & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \le 1 \\ +a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le \paramaleaff \quad {\rm else} \\ +a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconsl } \ge \paramaleaff & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ \\ -a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le a_{livestem}^{f} \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \right)^{d_{alloc}^{stem} } \ge a_{livestem}^{f} & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat d_{L} - \gddthreshgrain} \le 1 \\ +a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le \paramastemf \quad {\rm else} \\ +a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconss } \ge \paramastemf & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ \\ a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} \end{array} $$ (25.5) -where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $d_{L}$, $d_{alloc}^{leaf}$ and $d_{alloc}^{stem}$ are leaf area index and leaf and stem allocation decline factors, $a_{leaf}^{f}$ and $a_{livestem}^{f}$ are final values of these allocation coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. +where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $\paramdeclfact$, $\paramallconsl$ and $\paramallconss$ are leaf area index and leaf and stem allocation decline factors, $\paramaleaff$ and $\paramastemf$ are final values of these allocation coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. -As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, ${L}_{max}$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. +As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, $\paramlaimx$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. (nitrogen-retranslocation-for-crops)= @@ -461,18 +477,18 @@ As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth season is remobilized and used for grain development ({ref}`Pollmer et al. 1979 `, {ref}`Crawford et al. 1982 `, {ref}`Simpson et al. 1983 `, {ref}`Ta and Weiland 1992 `, {ref}`Barbottin et al. 2005 `, {ref}`Gallais et al. 2006 `, {ref}`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue and is calculated as $$ -leaf\_ to\_ retransn=N_{leaf} -\frac{C_{leaf} }{CN_{leaf}^{f} } +leaf\_ to\_ retransn=N_{leaf} -\frac{C_{leaf} }{\paramfleafcn} $$ (25.6) $$ -stemn\_ to\_ retransn=N_{stem} -\frac{C_{stem} }{CN_{stem}^{f} } +stemn\_ to\_ retransn=N_{stem} -\frac{C_{stem} }{\paramfstemcn} $$ (25.7) $$ -frootn\_ to\_ retransn=N_{froot} -\frac{C_{froot} }{CN_{froot}^{f} } +frootn\_ to\_ retransn=N_{froot} -\frac{C_{froot} }{\paramffrootcn} $$ (25.8) -where ${C}_{leaf}$, ${C}_{stem}$, and ${C}_{froot}$ is the carbon in the plant leaf, stem, and fine root, respectively, ${N}_{leaf}$, ${N}_{stem}$, and ${N}_{froot}$ is the nitrogen in the plant leaf, stem, and fine root, respectively, and $CN^f_{leaf}$, $CN^f_{stem}$, and $CN^f_{froot}$ is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively ({numref}`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ (${CN_{[organ]}^{f} }$ in {numref}`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. +where ${C}_{leaf}$, ${C}_{stem}$, and ${C}_{froot}$ is the carbon in the plant leaf, stem, and fine root, respectively, ${N}_{leaf}$, ${N}_{stem}$, and ${N}_{froot}$ is the nitrogen in the plant leaf, stem, and fine root, respectively, and $\paramfleafcn$, $\paramfstemcn$, and $\paramffrootcn$ is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively ({numref}`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ (${CN_{[organ]}^{f} }$ in {numref}`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. (harvest to food and seed)= @@ -530,10 +546,11 @@ $$ (25.15) (table crop allocation parameters)= -```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). +```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). **TODO: Delete $\paramgraincn$? Not mentioned anywhere else on this page.** :header-rows: 1 * - Parameter + - Variable - temperate corn - spring wheat - temperate soybean @@ -544,7 +561,8 @@ $$ (25.15) - tropical soybean - miscanthus - switchgrass -* - PFT index (1-based) +* - IVT + - n/a - 17, 18 - 19, 20 - 23, 24 @@ -555,8 +573,9 @@ $$ (25.15) - 77, 78 - 71, 72 - 73, 74 -* - $a_{leaf}^{i}$ - - 0.6 +* - $\paramfleafi$ + - `fleafi` + - 0.75 - 0.9 - 0.85 - 0.85 @@ -566,8 +585,9 @@ $$ (25.15) - 0.85 - 0.9 - 0.7 -* - ${L}_{max}$ (m{sup}`2` m{sup}`-2`) - - 5 +* - $\paramlaimx$ (m{sup}`2` m{sup}`-2`) + - `laimx` + - 6.2 - 7 - 6 - 6 @@ -577,40 +597,32 @@ $$ (25.15) - 6 - 10 - 6.5 -* - $a_{froot}^{i}$ +* - $\paramarooti$ + - `arooti` - 0.1 - - 0.05 + - 0.3 - 0.2 - 0.2 - - 0.1 - - 0.1 + - 0.3 + - 0.3 - 0.1 - 0.2 - 0.11 - 0.14 -* - $a_{froot}^{f}$ +* - $\paramarootf$ + - `arootf` - 0.05 - 0 - 0.2 - 0.2 - 0 - - 0.05 + - 0.1 - 0.05 - 0.2 - 0.09 - 0.09 -* - $a_{leaf}^{f}$ - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 -* - $a_{livestem}^{f}$ +* - $\paramastemf$ + - `astemf` - 0 - 0.05 - 0.3 @@ -621,21 +633,11 @@ $$ (25.15) - 0.3 - 0 - 0 -* - $d_{L}$ - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 - - 1.05 -* - $d_{alloc}^{stem}$ +* - $\paramallconss$ + - `allconss` - 2 - 1 - - 5 + - 2 - 5 - 1 - 2 @@ -643,7 +645,8 @@ $$ (25.15) - 5 - 2 - 2 -* - $d_{alloc}^{leaf}$ +* - $\paramallconsl$ + - `allconsl` - 5 - 3 - 2 @@ -654,7 +657,8 @@ $$ (25.15) - 2 - 5 - 5 -* - ${CN}_{leaf}$ +* - $\paramleafcn$ + - `leafcn` - 25 - 20 - 20 @@ -663,9 +667,10 @@ $$ (25.15) - 25 - 25 - 20 - - 25 - - 25 -* - ${CN}_{stem}$ + - 20 + - 20 +* - $\paramlivewdcn$ + - `livewdcn` - 50 - 50 - 50 @@ -676,7 +681,8 @@ $$ (25.15) - 50 - 50 - 50 -* - ${CN}_{froot}$ +* - $\paramfrootcn$ + - `frootcn` - 42 - 42 - 42 @@ -687,7 +693,8 @@ $$ (25.15) - 42 - 42 - 42 -* - $CN^f_{leaf}$ +* - $\paramfleafcn$ + - `fleafcn` - 65 - 65 - 65 @@ -698,7 +705,8 @@ $$ (25.15) - 65 - 65 - 65 -* - $CN^f_{stem}$ +* - $\paramfstemcn$ + - `fstemcn` - 120 - 100 - 130 @@ -709,7 +717,8 @@ $$ (25.15) - 130 - 120 - 120 -* - $CN^f_{froot}$ +* - $\paramffrootcn$ + - `ffrootcn` - 0 - 40 - 0 @@ -720,7 +729,8 @@ $$ (25.15) - 0 - 0 - 0 -* - ${CN}_{grain}$ +* - $\paramgraincn$ + - `graincn` - 50 - 50 - 50 @@ -732,9 +742,10 @@ $$ (25.15) - 50 - 50 ``` - - -Notes: Crop growth phases and corresponding variables are described throughout the text. ${CN}_{leaf}$, ${CN}_{stem}$, and ${CN}_{froot}$ are the target C:N ratios used during the leaf emergence phase (phase 2). +- Crop growth phases and corresponding variables are described throughout the text. +- $\paramleafcn$, $\paramlivewdcn$, and $\paramgraincn$ are the target C:N ratios used during the leaf emergence phase (phase 2). +- $\paramaleaff$ (parameter `aleaff`) is zero for all crops. +- $\paramdeclfact$ is 1.05 for all crops. (other-features)= From 4a5bafcf3d27219cbdc3dac1fae63b977361b0c2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 17:03:16 -0600 Subject: [PATCH 33/73] Crops TN: Improve eq on N retransloc --- .../CLM50_Tech_Note_Crop_Irrigation.md | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 70166f2c57..23f43f1675 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -36,6 +36,10 @@ $\newcommand{\paramfstemcn}{\paramlivewdcn^\textrm{f}}$ $\newcommand{\paramfrootcn}{CN_\textrm{froot}}$ $\newcommand{\paramffrootcn}{\paramfrootcn^\textrm{f}}$ $\newcommand{\paramgraincn}{CN_\textrm{grain}}$ +$\newcommand{\paramorgancn}{CN_\textrm{[organ]}}$ +$\newcommand{\paramforgancn}{\paramorgancn^\textrm{f}}$ +$\newcommand{\corgan}{C_\textrm{[organ]}}$ +$\newcommand{\norgan}{N_\textrm{[organ]}}$ (rst_crops and irrigation)= @@ -474,21 +478,13 @@ As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at #### Nitrogen retranslocation for crops -Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth season is remobilized and used for grain development ({ref}`Pollmer et al. 1979 `, {ref}`Crawford et al. 1982 `, {ref}`Simpson et al. 1983 `, {ref}`Ta and Weiland 1992 `, {ref}`Barbottin et al. 2005 `, {ref}`Gallais et al. 2006 `, {ref}`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized depends on the C:N ratio of the plant tissue and is calculated as +Nitrogen retranslocation in crops occurs when nitrogen that was used for tissue growth of leaves, stems, and fine roots during the early growth season is remobilized and used for grain development ({ref}`Pollmer et al. 1979 `, {ref}`Crawford et al. 1982 `, {ref}`Simpson et al. 1983 `, {ref}`Ta and Weiland 1992 `, {ref}`Barbottin et al. 2005 `, {ref}`Gallais et al. 2006 `, {ref}`Gallais et al. 2007 `). Nitrogen allocation for crops follows that of natural vegetation, is supplied in CLM by the soil mineral nitrogen pool, and depends on C:N ratios for leaves, stems, roots, and organs. Nitrogen demand during organ development is fulfilled through retranslocation from leaves, stems, and roots. Nitrogen retranslocation is initiated at the beginning of the grain fill stage for all crops except soybean, for which retranslocation is after LAI decline. Nitrogen stored in the leaf and stem is moved into a storage retranslocation pool for all crops, and for wheat and rice, nitrogen in roots is also released into the retranslocation storage pool. The quantity of nitrogen mobilized from an organ to the retranslocation pool is calculated as $$ -leaf\_ to\_ retransn=N_{leaf} -\frac{C_{leaf} }{\paramfleafcn} -$$ (25.6) +\norgan - \frac{\corgan}{\paramforgancn} +$$ (n-from-organ-to-retrans-pool) -$$ -stemn\_ to\_ retransn=N_{stem} -\frac{C_{stem} }{\paramfstemcn} -$$ (25.7) - -$$ -frootn\_ to\_ retransn=N_{froot} -\frac{C_{froot} }{\paramffrootcn} -$$ (25.8) - -where ${C}_{leaf}$, ${C}_{stem}$, and ${C}_{froot}$ is the carbon in the plant leaf, stem, and fine root, respectively, ${N}_{leaf}$, ${N}_{stem}$, and ${N}_{froot}$ is the nitrogen in the plant leaf, stem, and fine root, respectively, and $\paramfleafcn$, $\paramfstemcn$, and $\paramffrootcn$ is the post-grain fill C:N ratio of the leaf, stem, and fine root respectively ({numref}`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ (${CN_{[organ]}^{f} }$ in {numref}`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. +where $\corgan$ and $\norgan$ are the carbon and nitrogen in the organ, respectively, and $\paramforgancn$ is the C:N ratio of the organ ({numref}`Table Crop allocation parameters`). Since C:N measurements are often taken from mature crops, pre-grain development C:N ratios for leaves, stems, and roots in the model are optimized to allow maximum nitrogen accumulation for later use during organ development, and post-grain fill C:N ratios are assigned the same as crop residue. After nitrogen is moved into the retranslocated pool, the nitrogen in this pool is used to meet plant nitrogen demand by assigning the available nitrogen from the retranslocated pool equal to the plant nitrogen demand for each organ ($\paramforgancn$ in {numref}`Table Crop allocation parameters`). Once the retranslocation pool is depleted, soil mineral nitrogen pool is used to fulfill plant nitrogen demands. (harvest to food and seed)= From 2cf4b530f4987b6ac2413a30302d84f9d7633d38 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 17:07:38 -0600 Subject: [PATCH 34/73] Crops TN: Alloc params table: Delete unnecessary notes. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 23f43f1675..f54b30122f 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -738,8 +738,6 @@ $$ (25.15) - 50 - 50 ``` -- Crop growth phases and corresponding variables are described throughout the text. -- $\paramleafcn$, $\paramlivewdcn$, and $\paramgraincn$ are the target C:N ratios used during the leaf emergence phase (phase 2). - $\paramaleaff$ (parameter `aleaff`) is zero for all crops. - $\paramdeclfact$ is 1.05 for all crops. From 9ed249bfb47d57ba53c2d599cd9aed1cfd458598 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 17:10:12 -0600 Subject: [PATCH 35/73] Crops TN: Remove a TODO (now on PR). --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index f54b30122f..0ba0a7dc5a 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -542,7 +542,7 @@ $$ (25.15) (table crop allocation parameters)= -```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). **TODO: Delete $\paramgraincn$? Not mentioned anywhere else on this page.** +```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). :header-rows: 1 * - Parameter From 115d081b2458577c73d3405e06e0ca28bdd79c66 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 5 Jun 2026 17:21:26 -0600 Subject: [PATCH 36/73] Crops TN: Mention declfact param name --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 0ba0a7dc5a..38a413b223 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -739,7 +739,7 @@ $$ (25.15) - 50 ``` - $\paramaleaff$ (parameter `aleaff`) is zero for all crops. -- $\paramdeclfact$ is 1.05 for all crops. +- $\paramdeclfact$ (parameter `declfact`) is 1.05 for all crops. (other-features)= From e0e6987ffc0890aebb1548b66f8048712915c428 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sat, 6 Jun 2026 15:10:34 -0600 Subject: [PATCH 37/73] Crops TN: Pheno/morph params table now md. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 337 +++++++++--------- 1 file changed, 168 insertions(+), 169 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 38a413b223..586bf9dae9 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -229,175 +229,174 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct (table crop phenology parameters)= -```{eval-rst} -.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (``BgcCrop`` component sets). Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. Where there are two values in a cell, they refer to the rainfed and irrigated functional types, respectively. - :header-rows: 1 - - * - \ - - temperate corn - - spring wheat - - temperate soybean - - cotton - - rice - - sugarcane - - tropical corn - - tropical soybean - - miscanthus - - switchgrass - * - IVT - - 17, 18 - - 19, 20 - - 23, 24 - - 41, 42 - - 61, 62 - - 67, 68 - - 75, 76 - - 77, 78 - - 71, 72 - - 73, 74 - * - :math:`T_{p}`\(K) - - 283.15 - - 280.15 - - 286.15 - - 294.15 - - 294.15 - - 294.15 - - 294.15 - - 294.15 - - 283.15 - - 283.15 - * - :math:`T_{p}^{ min }`\(K) - - 279.15 - - 272.15 - - 279.15 - - 283.15 - - 283.15 - - 283.15 - - 283.15 - - 283.15 - - 279.15 - - 279.15 - * - :math:`{GDD}_{min}` (degree-days) - - 50 - - 50 - - 50 - - 50 - - 50 - - 50 - - 50 - - 50 - - 50 - - 50 - * - :math:`\parambaset` (°C) - - 8 - - 0 - - 10 - - 10 - - 10 - - 10 - - 10 - - 10 - - 8 - - 8 - * - :math:`\huithreshlfemerg` (% :math:`\gddthreshmat`) - - 3% - - 5% - - 3% - - 3% - - 1% - - 3% - - 3% - - 3% - - 3% - - 3% - * - :math:`\huithreshgrain` (% :math:`\gddthreshmat`) - - 65% - - 60% - - 50% - - 50% - - 40% - - 65% - - 50% - - 50% - - 40% - - 40% - * - Max. growing season length (:math:`mxmat`) - - 165 - - 150 - - 150 - - 160 - - 150 - - 300 - - 160 - - 150 - - 210 - - 210 - * - :math:`z_{top}^{\max }` (m) - - 2.5 - - 1.2 - - 0.75 - - 1.5 - - 1.8 - - 4 - - 2.5 - - 1 - - 2.5 - - 2.5 - * - SLA (m :sup:`2` leaf g :sup:`-1` C) - - 0.05 - - 0.035 - - 0.035 - - 0.035 - - 0.035 - - 0.05 - - 0.05 - - 0.035 - - 0.057 - - 0.049 - * - :math:`\chi _{L}` index - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - * - grperc - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - * - flnr - - 0.293 - - 0.41 - - 0.41 - - 0.41 - - 0.41 - - 0.293 - - 0.293 - - 0.41 - - 0.293 - - 0.293 - * - fcur - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 +```{list-table} Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). Where there are two values in a cell, they refer to the rainfed and irrigated functional types, respectively. +:header-rows: 1 + +* - Parameter + - temperate corn + - spring wheat + - temperate soybean + - cotton + - rice + - sugarcane + - tropical corn + - tropical soybean + - miscanthus + - switchgrass +* - IVT + - 17, 18 + - 19, 20 + - 23, 24 + - 41, 42 + - 61, 62 + - 67, 68 + - 75, 76 + - 77, 78 + - 71, 72 + - 73, 74 +* - $T_{p}$ (K) + - 283.15 + - 280.15 + - 286.15 + - 294.15 + - 294.15 + - 294.15 + - 294.15 + - 294.15 + - 283.15 + - 283.15 +* - $T_{p}^{ min }$ (K) + - 279.15 + - 272.15 + - 279.15 + - 283.15 + - 283.15 + - 283.15 + - 283.15 + - 283.15 + - 279.15 + - 279.15 +* - ${GDD}_{min}$ (degree-days) + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 + - 50 +* - $\parambaset$ (°C) + - 8 + - 0 + - 10 + - 10 + - 10 + - 10 + - 10 + - 10 + - 8 + - 8 +* - $\huithreshlfemerg$ (% $\gddthreshmat$) + - 3% + - 5% + - 3% + - 3% + - 1% + - 3% + - 3% + - 3% + - 3% + - 3% +* - $\huithreshgrain$ (% $\gddthreshmat$) + - 65% + - 60% + - 50% + - 50% + - 40% + - 65% + - 50% + - 50% + - 40% + - 40% +* - Max. growing season length ($mxmat$) + - 165 + - 150 + - 150 + - 160 + - 150 + - 300 + - 160 + - 150 + - 210 + - 210 +* - $z_{top}^{\max }$ (m) + - 2.5 + - 1.2 + - 0.75 + - 1.5 + - 1.8 + - 4 + - 2.5 + - 1 + - 2.5 + - 2.5 +* - SLA (m {sup}`2` leaf g {sup}`-1` C) + - 0.05 + - 0.035 + - 0.035 + - 0.035 + - 0.035 + - 0.05 + - 0.05 + - 0.035 + - 0.057 + - 0.049 +* - $\chi _{L}$ index + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 + - -0.5 +* - grperc + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 + - 0.11 +* - flnr + - 0.293 + - 0.41 + - 0.41 + - 0.41 + - 0.41 + - 0.293 + - 0.293 + - 0.41 + - 0.293 + - 0.293 +* - fcur + - 1 + - 1 + - 1 + - 1 + - 1 + - 1 + - 1 + - 1 + - 1 + - 1 ``` Notes: From dae312c59784b5479247326e0aa8ac37f385776e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sat, 6 Jun 2026 15:12:48 -0600 Subject: [PATCH 38/73] Crops TN: Pheno/morph params table: Add variable col. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 586bf9dae9..5c5241723c 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -233,6 +233,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct :header-rows: 1 * - Parameter + - Variable - temperate corn - spring wheat - temperate soybean @@ -244,6 +245,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - miscanthus - switchgrass * - IVT + - n/a - 17, 18 - 19, 20 - 23, 24 @@ -255,6 +257,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 71, 72 - 73, 74 * - $T_{p}$ (K) + - ??? - 283.15 - 280.15 - 286.15 @@ -266,6 +269,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 283.15 - 283.15 * - $T_{p}^{ min }$ (K) + - ??? - 279.15 - 272.15 - 279.15 @@ -277,6 +281,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 279.15 - 279.15 * - ${GDD}_{min}$ (degree-days) + - ??? - 50 - 50 - 50 @@ -288,6 +293,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 50 - 50 * - $\parambaset$ (°C) + - ??? - 8 - 0 - 10 @@ -299,6 +305,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 8 - 8 * - $\huithreshlfemerg$ (% $\gddthreshmat$) + - ??? - 3% - 5% - 3% @@ -310,6 +317,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 3% - 3% * - $\huithreshgrain$ (% $\gddthreshmat$) + - ??? - 65% - 60% - 50% @@ -321,6 +329,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 40% - 40% * - Max. growing season length ($mxmat$) + - ??? - 165 - 150 - 150 @@ -332,6 +341,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 210 - 210 * - $z_{top}^{\max }$ (m) + - ??? - 2.5 - 1.2 - 0.75 @@ -343,6 +353,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 2.5 - 2.5 * - SLA (m {sup}`2` leaf g {sup}`-1` C) + - ??? - 0.05 - 0.035 - 0.035 @@ -354,6 +365,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 0.057 - 0.049 * - $\chi _{L}$ index + - ??? - -0.5 - -0.5 - -0.5 @@ -365,6 +377,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - -0.5 - -0.5 * - grperc + - ??? - 0.11 - 0.11 - 0.11 @@ -376,6 +389,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 0.11 - 0.11 * - flnr + - ??? - 0.293 - 0.41 - 0.41 @@ -387,6 +401,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 0.293 - 0.293 * - fcur + - ??? - 1 - 1 - 1 From 7d0e1a850435d63ff313248a83ea6c02fc837742 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 7 Jun 2026 16:25:21 +0200 Subject: [PATCH 39/73] Crops TN: Update crop phenology/morphology table. Update values; delete parameters not mentioned anywhere in this chapter. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 123 ++++++------------ 1 file changed, 37 insertions(+), 86 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 5c5241723c..29fd171cd9 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -40,6 +40,9 @@ $\newcommand{\paramorgancn}{CN_\textrm{[organ]}}$ $\newcommand{\paramforgancn}{\paramorgancn^\textrm{f}}$ $\newcommand{\corgan}{C_\textrm{[organ]}}$ $\newcommand{\norgan}{N_\textrm{[organ]}}$ +$\newcommand{\paramplantingtemp}{T_\textrm{p}}$ +$\newcommand{\paramminplantingtemp}{\paramplantingtemp^\textrm{min}}$ +$\newcommand{\paramgddmin}{GDD_\textrm{min}}$ (rst_crops and irrigation)= @@ -160,13 +163,13 @@ To be planted, a crop patch must meet the following requirements sometime within $$ \begin{array}{c} -{T_{10d} >T_{p} } \\ -{T_{10d}^{\min } >T_{p}^{\min } } \\ -{\gddeightrun \ge GDD_{\min } } +{T_{10d} > \paramplantingtemp} \\ +{T_{10d}^{\min } > \paramminplantingtemp} \\ +{\gddeightrun \ge \paramgddmin} \end{array} $$ (25.1) -where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). ${T}_{p}$ and $T_{p}^{\min }$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeightrun$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and ${GDD}_{min }$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeightrun$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeightrun$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeightrun > 0$. +where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). $\paramplantingtemp$ and $\paramminplantingtemp$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeightrun$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and $\paramgddmin$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeightrun$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeightrun$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeightrun > 0$. At planting, each crop seed pool is assigned 3 gC m{sup}`-2` from its grain product pool. The seed carbon is transferred to the leaves upon leaf emergence. An equivalent amount of seed leaf N is assigned given the PFT's C to N ratio for leaves ($\paramleafcn$ in {numref}`Table Crop allocation parameters`; this differs from AgroIBIS, which uses a seed leaf area index instead of seed C). @@ -256,8 +259,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 77, 78 - 71, 72 - 73, 74 -* - $T_{p}$ (K) - - ??? +* - $\paramplantingtemp$ (K) + - `planting_temp` - 283.15 - 280.15 - 286.15 @@ -268,8 +271,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 294.15 - 283.15 - 283.15 -* - $T_{p}^{ min }$ (K) - - ??? +* - $\paramminplantingtemp$ (K) + - `min_planting_temp` - 279.15 - 272.15 - 279.15 @@ -280,8 +283,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 283.15 - 279.15 - 279.15 -* - ${GDD}_{min}$ (degree-days) - - ??? +* - $\paramgddmin$ (degree-days) + - `gddmin` - 50 - 50 - 50 @@ -292,8 +295,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 50 - 50 - 50 -* - $\parambaset$ (°C) - - ??? +* - $\parambaset$ (°C) + - `baset` - 8 - 0 - 10 @@ -304,8 +307,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 10 - 8 - 8 -* - $\huithreshlfemerg$ (% $\gddthreshmat$) - - ??? +* - $\huithreshlfemerg$ (% $\gddthreshmat$) + - `lfemerg` - 3% - 5% - 3% @@ -316,8 +319,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 3% - 3% - 3% -* - $\huithreshgrain$ (% $\gddthreshmat$) - - ??? +* - $\huithreshgrain$ (% $\gddthreshmat$) + - `grnfill` - 65% - 60% - 50% @@ -328,20 +331,20 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 50% - 40% - 40% -* - Max. growing season length ($mxmat$) - - ??? +* - Max. growing season length + - `mxmat` - 165 - 150 - - 150 - - 160 - - 150 - - 300 + - 180 + - 225 + - 180 + - 360 - 160 - 150 - 210 - 210 -* - $z_{top}^{\max }$ (m) - - ??? +* - $\paramztopmx$ (m) + - `ztopmx` - 2.5 - 1.2 - 0.75 @@ -352,8 +355,8 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 1 - 2.5 - 2.5 -* - SLA (m {sup}`2` leaf g {sup}`-1` C) - - ??? +* - SLA (m {sup}`2` leaf g {sup}`-1` C) + - `slatop` - 0.05 - 0.035 - 0.035 @@ -362,71 +365,19 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - 0.05 - 0.05 - 0.035 - - 0.057 - - 0.049 -* - $\chi _{L}$ index - - ??? - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 - - -0.5 -* - grperc - - ??? - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 - - 0.11 -* - flnr - - ??? - - 0.293 - - 0.41 - - 0.41 - - 0.41 - - 0.41 - - 0.293 - - 0.293 - - 0.41 - - 0.293 - - 0.293 -* - fcur - - ??? - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 - - 1 + - 0.035 + - 0.035 ``` Notes: -- $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) -- $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. +- $\paramplantingtemp$ and $\paramminplantingtemp$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. {numref}`Planting`.) +- $\paramgddmin$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. {numref}`Planting` for details. - $\parambaset$ is the minimum temperature for accumulating growing degree-days. - $\huithreshlfemerg$ and $\huithreshgrain$ are, respectively, the threshold fractions of $\gddthreshmat$ a crop must reach to enter the leaf-emergence phase (phase 2) and grain-filling phase (phase 3). However, note the adjustment applied to $\huithreshgrain$ for some crops (Eq. {eq}`corn-huigrain-adjustment`). -- $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddthreshmat$. +- `mxmat` is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $\gddthreshmat$. - $\paramztopmx$ is the maximum top-of-canopy height of a crop (see Sect. {numref}`Vegetation Structure`). - SLA is specific leaf area (see Chapter {numref}`rst_Photosynthetic Capacity`). -- $\chi _{L}$ is the leaf orientation index, equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. (See Sect. {numref}`Canopy Radiative Transfer`.) -- grperc is the growth respiration factor (see Sect. {numref}`Growth Respiration`). -- flnr is the fraction of leaf N in the Rubisco enzyme (a.k.a. $N_{cb}$ in Sect. {numref}`Plant Nitrogen`). -- fcur is the fraction of allocation that goes to currently displayed growth (i.e., that is not sent to storage). See Sect. {numref}`Carbon Allocation to New Growth`. (allocation)= @@ -765,16 +716,16 @@ $$ (25.15) Leaf area index ($L$) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index ($S$) is equal to 0.1$L$ for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2$L$ for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the $S$ is kept at 0.25 to simulate a post-harvest "stubble" on the ground. -Crop heights at the top and bottom of the canopy, ${z}_{top}$ and ${z}_{bot}$ (m), come from the AgroIBIS formulation: +Crop heights at the top and bottom of the canopy, $\paramztopmx$ and ${z}_{bot}$ (m), come from the AgroIBIS formulation: $$ \begin{array}{l} -{z_{top} = \paramztopmx \left(\frac{L}{L_{\max } -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{L_{\max } -1} \le 1} \\ +{z_{top} = \paramztopmx \left(\frac{L}{\paramlaimx -1} \right)^{2} \ge 0.05{\rm \; where\; }\frac{L}{\paramlaimx -1} \le 1} \\ {z_{bot} =0.02{\rm m}} \end{array} $$ (25.16) -where $\paramztopmx$ is the maximum top-of-canopy height of the crop ({numref}`Table Crop phenology parameters`) and $L_{\max }$ is the maximum leaf area index ({numref}`Table Crop allocation parameters`). +where $\paramztopmx$ is the maximum top-of-canopy height of the crop ({numref}`Table Crop phenology parameters`) and $\paramlaimx$ is the maximum leaf area index ({numref}`Table Crop allocation parameters`). (interactive-fertilization)= From 2d79c4fde34a67b25910a7c28be5c7e327b23dc4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 10:25:00 +0200 Subject: [PATCH 40/73] Fix out-of-date submodules. --- ccs_config | 2 +- doc/doc-builder | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ccs_config b/ccs_config index 7020eb9a16..39683243b4 160000 --- a/ccs_config +++ b/ccs_config @@ -1 +1 @@ -Subproject commit 7020eb9a16a2c1cde7b7fbb588e08dbb7b1ce85c +Subproject commit 39683243b4e8e5b4576fd1b828c3ec4c9e15bc6b diff --git a/doc/doc-builder b/doc/doc-builder index 6607280dd7..15e171dfcf 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 6607280dd7a96d5606fbd6e8abe547ac0da4d62f +Subproject commit 15e171dfcf77ca2bd85415a99a50ad3994c608c4 From a5150507a20ec6c03196968c054fb27d661bf106 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 10:29:52 +0200 Subject: [PATCH 41/73] Crops TN: Refer to mxmat in text. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 29fd171cd9..ae58beb1a1 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -228,7 +228,7 @@ The grain fill phase (phase 3) begins in one of two ways. The first potential tr #### Harvest -Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacctwom$ reaches 100% of $\gddthreshmat$ or the number of days past planting reaches a crop-specific maximum ({numref}`Table Crop phenology parameters`), then the crop is harvested. Harvest occurs in one time step using the BGC leaf offset algorithm. +Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacctwom$ reaches 100% of $\gddthreshmat$ or the number of days past planting reaches a crop-specific maximum (`mxmat`; {numref}`Table Crop phenology parameters`), then the crop is harvested. Harvest occurs in one time step using the BGC leaf offset algorithm. (table crop phenology parameters)= From 58ff7e2f30cbadd227185df758d8e679c023eca7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 10:37:01 +0200 Subject: [PATCH 42/73] Crops TN: Improve intro. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index ae58beb1a1..42e87fb124 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -54,11 +54,11 @@ $\newcommand{\paramgddmin}{GDD_\textrm{min}}$ ### Introduction -Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. +Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. For a long time, this was accomplished using natural vegetation types—particularly grasses—because they resemble many common crops, but now it is more common to explicitly represent land management such as crop type, planting, harvesting, fertilization, irrigation, and more. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 \[CLM3.0, {ref}`Oleson et al. (2004) ` \] (not published), then coupled to the CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and those are now incorporated into CLM5 and later. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled (not published) as a proof-of-concept in CLM3.0 ({ref}`Oleson et al. (2004) `), then CLM3.5 ({ref}`Levis et al. 2009 `)m and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and beginning with CLM5 crops have been incorporated into the main codebase. -With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. +With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). The CLM crop model uses the same physiology as the natural vegetation but with different crop-specific parameter values, phenology, allocation, as well as management (fertilizer, irrigation, tillage, and residue removal). (crop-plant-functional-types)= From da67237c18313c71da448041e1047be6c15c550e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 10:58:05 +0200 Subject: [PATCH 43/73] Crops TN: Simplify crop PFT table. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 136 +++++++++--------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 42e87fb124..bbc6a3df6e 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -75,74 +75,74 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr ```{eval-rst} .. table:: Crop plant functional types (PFTs) included in CLM with managed crops on (`BgcCrop` component sets). - === =========================== ================ =========================== - IVT Plant function types (PFTs) Management Class Crop Parameters Used - === =========================== ================ =========================== - 15 c3 unmanaged rainfed crop none not applicable - 16 c3 unmanaged irrigated crop none not applicable - 17 rainfed temperate corn active rainfed temperate corn - 18 irrigated temperate corn active irrigated temperate corn - 19 rainfed spring wheat active rainfed spring wheat - 20 irrigated spring wheat active irrigated spring wheat - 21 rainfed winter wheat inactive rainfed spring wheat - 22 irrigated winter wheat inactive irrigated spring wheat - 23 rainfed temperate soybean active rainfed temperate soybean - 24 irrigated temperate soybean active irrigated temperate soybean - 25 rainfed barley inactive rainfed spring wheat - 26 irrigated barley inactive irrigated spring wheat - 27 rainfed winter barley inactive rainfed spring wheat - 28 irrigated winter barley inactive irrigated spring wheat - 29 rainfed rye inactive rainfed spring wheat - 30 irrigated rye inactive irrigated spring wheat - 31 rainfed winter rye inactive rainfed spring wheat - 32 irrigated winter rye inactive irrigated spring wheat - 33 rainfed cassava inactive rainfed rice - 34 irrigated cassava inactive irrigated rice - 35 rainfed citrus inactive rainfed spring wheat - 36 irrigated citrus inactive irrigated spring wheat - 37 rainfed cocoa inactive rainfed rice - 38 irrigated cocoa inactive irrigated rice - 39 rainfed coffee inactive rainfed rice - 40 irrigated coffee inactive irrigated rice - 41 rainfed cotton active rainfed cotton - 42 irrigated cotton active irrigated cotton - 43 rainfed datepalm inactive rainfed cotton - 44 irrigated datepalm inactive irrigated cotton - 45 rainfed foddergrass inactive rainfed spring wheat - 46 irrigated foddergrass inactive irrigated spring wheat - 47 rainfed grapes inactive rainfed spring wheat - 48 irrigated grapes inactive irrigated spring wheat - 49 rainfed groundnuts inactive rainfed rice - 50 irrigated groundnuts inactive irrigated rice - 51 rainfed millet inactive rainfed tropical corn - 52 irrigated millet inactive irrigated tropical corn - 53 rainfed oilpalm inactive rainfed rice - 54 irrigated oilpalm inactive irrigated rice - 55 rainfed potatoes inactive rainfed spring wheat - 56 irrigated potatoes inactive irrigated spring wheat - 57 rainfed pulses inactive rainfed spring wheat - 58 irrigated pulses inactive irrigated spring wheat - 59 rainfed rapeseed inactive rainfed spring wheat - 60 irrigated rapeseed inactive irrigated spring wheat - 61 rainfed rice active rainfed rice - 62 irrigated rice active irrigated rice - 63 rainfed sorghum inactive rainfed tropical corn - 64 irrigated sorghum inactive irrigated tropical corn - 65 rainfed sugarbeet inactive rainfed spring wheat - 66 irrigated sugarbeet inactive irrigated spring wheat - 67 rainfed sugarcane active rainfed sugarcane - 68 irrigated sugarcane active irrigated sugarcane - 69 rainfed sunflower inactive rainfed spring wheat - 70 irrigated sunflower inactive irrigated spring wheat - 71 rainfed miscanthus active rainfed miscanthus - 72 irrigated miscanthus active irrigated miscanthus - 73 rainfed switchgrass active rainfed switchgrass - 74 irrigated switchgrass active irrigated switchgrass - 75 rainfed tropical corn active rainfed tropical corn - 76 irrigated tropical corn active irrigated tropical corn - 77 rainfed tropical soybean active rainfed tropical soybean - 78 irrigated tropical soybean active irrigated tropical soybean - === =========================== ================ =========================== + === =========================== ============================= + IVT Plant function types (PFTs) Simulated as + === =========================== ============================= + 15 c3 unmanaged rainfed crop n/a (off if managed crops on) + 16 c3 unmanaged irrigated crop n/a (off if managed crops on) + 17 rainfed temperate corn (itself) + 18 irrigated temperate corn (itself) + 19 rainfed spring wheat (itself) + 20 irrigated spring wheat (itself) + 21 rainfed winter wheat rainfed spring wheat + 22 irrigated winter wheat irrigated spring wheat + 23 rainfed temperate soybean (itself) + 24 irrigated temperate soybean (itself) + 25 rainfed barley rainfed spring wheat + 26 irrigated barley irrigated spring wheat + 27 rainfed winter barley rainfed spring wheat + 28 irrigated winter barley irrigated spring wheat + 29 rainfed rye rainfed spring wheat + 30 irrigated rye irrigated spring wheat + 31 rainfed winter rye rainfed spring wheat + 32 irrigated winter rye irrigated spring wheat + 33 rainfed cassava rainfed rice + 34 irrigated cassava irrigated rice + 35 rainfed citrus rainfed spring wheat + 36 irrigated citrus irrigated spring wheat + 37 rainfed cocoa rainfed rice + 38 irrigated cocoa irrigated rice + 39 rainfed coffee rainfed rice + 40 irrigated coffee irrigated rice + 41 rainfed cotton (itself) + 42 irrigated cotton (itself) + 43 rainfed datepalm rainfed cotton + 44 irrigated datepalm irrigated cotton + 45 rainfed foddergrass rainfed spring wheat + 46 irrigated foddergrass irrigated spring wheat + 47 rainfed grapes rainfed spring wheat + 48 irrigated grapes irrigated spring wheat + 49 rainfed groundnuts rainfed rice + 50 irrigated groundnuts irrigated rice + 51 rainfed millet rainfed tropical corn + 52 irrigated millet irrigated tropical corn + 53 rainfed oilpalm rainfed rice + 54 irrigated oilpalm irrigated rice + 55 rainfed potatoes rainfed spring wheat + 56 irrigated potatoes irrigated spring wheat + 57 rainfed pulses rainfed spring wheat + 58 irrigated pulses irrigated spring wheat + 59 rainfed rapeseed rainfed spring wheat + 60 irrigated rapeseed irrigated spring wheat + 61 rainfed rice (itself) + 62 irrigated rice (itself) + 63 rainfed sorghum rainfed tropical corn + 64 irrigated sorghum irrigated tropical corn + 65 rainfed sugarbeet rainfed spring wheat + 66 irrigated sugarbeet irrigated spring wheat + 67 rainfed sugarcane (itself) + 68 irrigated sugarcane (itself) + 69 rainfed sunflower rainfed spring wheat + 70 irrigated sunflower irrigated spring wheat + 71 rainfed miscanthus (itself) + 72 irrigated miscanthus (itself) + 73 rainfed switchgrass (itself) + 74 irrigated switchgrass (itself) + 75 rainfed tropical corn (itself) + 76 irrigated tropical corn (itself) + 77 rainfed tropical soybean (itself) + 78 irrigated tropical soybean (itself) + === =========================== ============================= ``` (phenology)= From bf506e2f247385f488580f6b86e68d186130e62b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:00:32 +0200 Subject: [PATCH 44/73] Crops TN: Crop PFT table now list-table. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 269 +++++++++++++----- 1 file changed, 198 insertions(+), 71 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index bbc6a3df6e..2082069d59 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -72,77 +72,204 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr (table crop plant functional types)= -```{eval-rst} -.. table:: Crop plant functional types (PFTs) included in CLM with managed crops on (`BgcCrop` component sets). - - === =========================== ============================= - IVT Plant function types (PFTs) Simulated as - === =========================== ============================= - 15 c3 unmanaged rainfed crop n/a (off if managed crops on) - 16 c3 unmanaged irrigated crop n/a (off if managed crops on) - 17 rainfed temperate corn (itself) - 18 irrigated temperate corn (itself) - 19 rainfed spring wheat (itself) - 20 irrigated spring wheat (itself) - 21 rainfed winter wheat rainfed spring wheat - 22 irrigated winter wheat irrigated spring wheat - 23 rainfed temperate soybean (itself) - 24 irrigated temperate soybean (itself) - 25 rainfed barley rainfed spring wheat - 26 irrigated barley irrigated spring wheat - 27 rainfed winter barley rainfed spring wheat - 28 irrigated winter barley irrigated spring wheat - 29 rainfed rye rainfed spring wheat - 30 irrigated rye irrigated spring wheat - 31 rainfed winter rye rainfed spring wheat - 32 irrigated winter rye irrigated spring wheat - 33 rainfed cassava rainfed rice - 34 irrigated cassava irrigated rice - 35 rainfed citrus rainfed spring wheat - 36 irrigated citrus irrigated spring wheat - 37 rainfed cocoa rainfed rice - 38 irrigated cocoa irrigated rice - 39 rainfed coffee rainfed rice - 40 irrigated coffee irrigated rice - 41 rainfed cotton (itself) - 42 irrigated cotton (itself) - 43 rainfed datepalm rainfed cotton - 44 irrigated datepalm irrigated cotton - 45 rainfed foddergrass rainfed spring wheat - 46 irrigated foddergrass irrigated spring wheat - 47 rainfed grapes rainfed spring wheat - 48 irrigated grapes irrigated spring wheat - 49 rainfed groundnuts rainfed rice - 50 irrigated groundnuts irrigated rice - 51 rainfed millet rainfed tropical corn - 52 irrigated millet irrigated tropical corn - 53 rainfed oilpalm rainfed rice - 54 irrigated oilpalm irrigated rice - 55 rainfed potatoes rainfed spring wheat - 56 irrigated potatoes irrigated spring wheat - 57 rainfed pulses rainfed spring wheat - 58 irrigated pulses irrigated spring wheat - 59 rainfed rapeseed rainfed spring wheat - 60 irrigated rapeseed irrigated spring wheat - 61 rainfed rice (itself) - 62 irrigated rice (itself) - 63 rainfed sorghum rainfed tropical corn - 64 irrigated sorghum irrigated tropical corn - 65 rainfed sugarbeet rainfed spring wheat - 66 irrigated sugarbeet irrigated spring wheat - 67 rainfed sugarcane (itself) - 68 irrigated sugarcane (itself) - 69 rainfed sunflower rainfed spring wheat - 70 irrigated sunflower irrigated spring wheat - 71 rainfed miscanthus (itself) - 72 irrigated miscanthus (itself) - 73 rainfed switchgrass (itself) - 74 irrigated switchgrass (itself) - 75 rainfed tropical corn (itself) - 76 irrigated tropical corn (itself) - 77 rainfed tropical soybean (itself) - 78 irrigated tropical soybean (itself) - === =========================== ============================= +```{list-table} Crop plant functional types (PFTs) included in CLM with managed crops on (BgcCrop component sets). +:header-rows: 1 + +* - IVT + - Plant functional type (PFT) + - Simulated as +* - 15 + - c3 unmanaged rainfed crop + - n/a (off if managed crops on) +* - 16 + - c3 unmanaged irrigated crop + - n/a (off if managed crops on) +* - 17 + - rainfed temperate corn + - (itself) +* - 18 + - irrigated temperate corn + - (itself) +* - 19 + - rainfed spring wheat + - (itself) +* - 20 + - irrigated spring wheat + - (itself) +* - 21 + - rainfed winter wheat + - rainfed spring wheat +* - 22 + - irrigated winter wheat + - irrigated spring wheat +* - 23 + - rainfed temperate soybean + - (itself) +* - 24 + - irrigated temperate soybean + - (itself) +* - 25 + - rainfed barley + - rainfed spring wheat +* - 26 + - irrigated barley + - irrigated spring wheat +* - 27 + - rainfed winter barley + - rainfed spring wheat +* - 28 + - irrigated winter barley + - irrigated spring wheat +* - 29 + - rainfed rye + - rainfed spring wheat +* - 30 + - irrigated rye + - irrigated spring wheat +* - 31 + - rainfed winter rye + - rainfed spring wheat +* - 32 + - irrigated winter rye + - irrigated spring wheat +* - 33 + - rainfed cassava + - rainfed rice +* - 34 + - irrigated cassava + - irrigated rice +* - 35 + - rainfed citrus + - rainfed spring wheat +* - 36 + - irrigated citrus + - irrigated spring wheat +* - 37 + - rainfed cocoa + - rainfed rice +* - 38 + - irrigated cocoa + - irrigated rice +* - 39 + - rainfed coffee + - rainfed rice +* - 40 + - irrigated coffee + - irrigated rice +* - 41 + - rainfed cotton + - (itself) +* - 42 + - irrigated cotton + - (itself) +* - 43 + - rainfed datepalm + - rainfed cotton +* - 44 + - irrigated datepalm + - irrigated cotton +* - 45 + - rainfed foddergrass + - rainfed spring wheat +* - 46 + - irrigated foddergrass + - irrigated spring wheat +* - 47 + - rainfed grapes + - rainfed spring wheat +* - 48 + - irrigated grapes + - irrigated spring wheat +* - 49 + - rainfed groundnuts + - rainfed rice +* - 50 + - irrigated groundnuts + - irrigated rice +* - 51 + - rainfed millet + - rainfed tropical corn +* - 52 + - irrigated millet + - irrigated tropical corn +* - 53 + - rainfed oilpalm + - rainfed rice +* - 54 + - irrigated oilpalm + - irrigated rice +* - 55 + - rainfed potatoes + - rainfed spring wheat +* - 56 + - irrigated potatoes + - irrigated spring wheat +* - 57 + - rainfed pulses + - rainfed spring wheat +* - 58 + - irrigated pulses + - irrigated spring wheat +* - 59 + - rainfed rapeseed + - rainfed spring wheat +* - 60 + - irrigated rapeseed + - irrigated spring wheat +* - 61 + - rainfed rice + - (itself) +* - 62 + - irrigated rice + - (itself) +* - 63 + - rainfed sorghum + - rainfed tropical corn +* - 64 + - irrigated sorghum + - irrigated tropical corn +* - 65 + - rainfed sugarbeet + - rainfed spring wheat +* - 66 + - irrigated sugarbeet + - irrigated spring wheat +* - 67 + - rainfed sugarcane + - (itself) +* - 68 + - irrigated sugarcane + - (itself) +* - 69 + - rainfed sunflower + - rainfed spring wheat +* - 70 + - irrigated sunflower + - irrigated spring wheat +* - 71 + - rainfed miscanthus + - (itself) +* - 72 + - irrigated miscanthus + - (itself) +* - 73 + - rainfed switchgrass + - (itself) +* - 74 + - irrigated switchgrass + - (itself) +* - 75 + - rainfed tropical corn + - (itself) +* - 76 + - irrigated tropical corn + - (itself) +* - 77 + - rainfed tropical soybean + - (itself) +* - 78 + - irrigated tropical soybean + - (itself) ``` (phenology)= From 05db816df3c5022a4ed8db7c63b25b00117504a6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:12:21 +0200 Subject: [PATCH 45/73] Crops TN: Mention mergetoclmpft var name. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- doc/source/users_guide/using-clm-tools/paramfile-tools.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 2082069d59..35752f679b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -68,7 +68,7 @@ To allow crops to coexist with natural vegetation in a grid cell, the vegetated CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). -In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`. It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. +In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. (table crop plant functional types)= diff --git a/doc/source/users_guide/using-clm-tools/paramfile-tools.md b/doc/source/users_guide/using-clm-tools/paramfile-tools.md index 84b4d496eb..51c82bdf1d 100644 --- a/doc/source/users_guide/using-clm-tools/paramfile-tools.md +++ b/doc/source/users_guide/using-clm-tools/paramfile-tools.md @@ -5,6 +5,7 @@ This guide describes the features and usage of the `query_paramfile` and `set_pa Note that you need to have the `ctsm_pylib` conda environment activated to use these tools. See Sect. {numref}`using-ctsm-pylib` for more information. +(query-paramfile)= ## `query_paramfile` **Purpose:** Print the values of one or more parameters from a CTSM parameter file (netCDF format). From 37c0c352986641bbc3c32191a6fe752cd4962f92 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:16:07 +0200 Subject: [PATCH 46/73] Crops TN: Define IVT. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 35752f679b..532a37459b 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -72,7 +72,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr (table crop plant functional types)= -```{list-table} Crop plant functional types (PFTs) included in CLM with managed crops on (BgcCrop component sets). +```{list-table} Crop plant functional types (PFTs) included in CLM with managed crops on (BgcCrop component sets). IVT is the integer used to refer to each vegetation type in the FORTRAN code. :header-rows: 1 * - IVT From 56a915341bfa43bd130d8a3a0ae7742c085acd3d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:24:03 +0200 Subject: [PATCH 47/73] Crops TN: Explain how to get pure mgd crops. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 4 +++- doc/source/users_guide/using-clm-tools/paramfile-tools.md | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 532a37459b..164b658043 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -68,7 +68,9 @@ To allow crops to coexist with natural vegetation in a grid cell, the vegetated CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). -In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. +In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). + +It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not simulated, such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). (table crop plant functional types)= diff --git a/doc/source/users_guide/using-clm-tools/paramfile-tools.md b/doc/source/users_guide/using-clm-tools/paramfile-tools.md index 51c82bdf1d..52bff402d7 100644 --- a/doc/source/users_guide/using-clm-tools/paramfile-tools.md +++ b/doc/source/users_guide/using-clm-tools/paramfile-tools.md @@ -33,6 +33,7 @@ Print values for specific PFTs: tools/param_utils/query_paramfile -i paramfile.nc -p needleleaf_evergreen_temperate_tree,c4_grass medlynintercept medlynslope ``` +(set-paramfile)= ## `set_paramfile` **Purpose:** Change values of one or more parameters in a CTSM parameter file (netCDF format). From ad41c56814726338e5cb47a1a68fcdeb40352954 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:26:15 +0200 Subject: [PATCH 48/73] Crops TN: Mention that trying to enable inactive crops will fail. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 164b658043..7d0e8f163c 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -72,6 +72,8 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not simulated, such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). +Enabling the inactive crop PFTs will cause the model to error due to certain logic in the code that does not yet handle those PFTs; see the related [GitHub issue](https://github.com/ESCOMP/CTSM/issues/3388). + (table crop plant functional types)= ```{list-table} Crop plant functional types (PFTs) included in CLM with managed crops on (BgcCrop component sets). IVT is the integer used to refer to each vegetation type in the FORTRAN code. From 99be27f35f207469f601410dd96c548818ec28a2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:35:26 +0200 Subject: [PATCH 49/73] Crops TN: Fix typo --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 7d0e8f163c..ba7a00d5a0 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -56,7 +56,7 @@ $\newcommand{\paramgddmin}{GDD_\textrm{min}}$ Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. For a long time, this was accomplished using natural vegetation types—particularly grasses—because they resemble many common crops, but now it is more common to explicitly represent land management such as crop type, planting, harvesting, fertilization, irrigation, and more. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled (not published) as a proof-of-concept in CLM3.0 ({ref}`Oleson et al. (2004) `), then CLM3.5 ({ref}`Levis et al. 2009 `)m and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and beginning with CLM5 crops have been incorporated into the main codebase. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation ({ref}`Kucharik et al. 2000 `) and interactive crop management ({ref}`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled (not published) as a proof-of-concept in CLM3.0 ({ref}`Oleson et al. (2004) `), then CLM3.5 ({ref}`Levis et al. 2009 `) and later released to the community with CLM4CN ({ref}`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request ({ref}`Levis et al. 2016 `), and beginning with CLM5 crops have been incorporated into the main codebase. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., {ref}`Kucharik and Brye 2003 `; {ref}`Lobell et al. 2006 `). The CLM crop model uses the same physiology as the natural vegetation but with different crop-specific parameter values, phenology, allocation, as well as management (fertilizer, irrigation, tillage, and residue removal). From 8618470e96ee15368f3b62c5f08b23020439df87 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 11:35:44 +0200 Subject: [PATCH 50/73] Crops TN: Replace some math symbols with monospaced text. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index ba7a00d5a0..aea3960316 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -43,6 +43,8 @@ $\newcommand{\norgan}{N_\textrm{[organ]}}$ $\newcommand{\paramplantingtemp}{T_\textrm{p}}$ $\newcommand{\paramminplantingtemp}{\paramplantingtemp^\textrm{min}}$ $\newcommand{\paramgddmin}{GDD_\textrm{min}}$ +$\newcommand{\parambiofuelharvfrac}{\texttt{biofuel_harvfrac}}$ +$\newcommand{\paramcropresidueremovalfrac}{\texttt{crop_residue_removal_frac}}$ (rst_crops and irrigation)= @@ -590,50 +592,50 @@ CLM splits live crop grain C and N between "food" and "seed" pools. In the forme Live leaf and stem biomass at harvest is transferred to biofuel, removed residue, and/or litter pools. -For the biofuel crops Miscanthus and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool as described for "food" harvest above. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter $biofuel\_harvfrac$ (0-1). +For the biofuel crops Miscanthus and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool as described for "food" harvest above. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter `biofuel_harvfrac` (0-1). -50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter $crop\_residue\_removal\_frac$ (0–1). The default 50% is derived from {ref}`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. +50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter `crop_residue_removal_frac` (0–1). The default 50% is derived from {ref}`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. The following equations illustrate how this works. Subscript $p$ refers to either the leaf or live stem biomass pool. $$ CF_{p,biofuel} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) \times biofuel\_harvfrac + \right) \times \parambiofuelharvfrac $$ (25.9) $$ CF_{p,removed\_residue} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) \times (1 - biofuel\_harvfrac) \times crop\_residue\_removal\_frac + \right) \times (1 - \parambiofuelharvfrac) \times \paramcropresidueremovalfrac $$ (harv_c_to_removed_residue) $$ CF_{p,litter} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} - \right) \times \left( 1-biofuel\_harvfrac \right) \times \left( 1-crop\_residue\_removal\_frac \right) +CF_{p,alloc} + \right) \times \left( 1-\parambiofuelharvfrac \right) \times \left( 1-\paramcropresidueremovalfrac \right) +CF_{p,alloc} $$ (25.11) with corresponding nitrogen fluxes: $$ NF_{p,biofuel} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) \times biofuel\_harvfrac + \right) \times \parambiofuelharvfrac $$ (25.12) $$ NF_{p,removed\_residue} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) \times \left( 1 - biofuel\_harvfrac \right) \times crop\_residue\_removal\_frac + \right) \times \left( 1 - \parambiofuelharvfrac \right) \times \paramcropresidueremovalfrac $$ (harv_n_to_removed_residue) $$ NF_{p,litter} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \right.} \Delta t} - \right) \times \left( 1-biofuel\_harvfrac \right) \times \left( 1-crop\_residue\_removal\_frac \right) + \right) \times \left( 1-\parambiofuelharvfrac \right) \times \left( 1-\paramcropresidueremovalfrac \right) $$ (25.14) -where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and $biofuel\_harvfrac$ is the harvested fraction of leaf/livestem for biofuel feedstocks. +where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and `biofuel_harvfrac` is the harvested fraction of leaf/livestem for biofuel feedstocks. -Annual food crop yields (g dry matter m{sup}`-2`) can be calculated by saving the GRAINC_TO_FOOD_ANN variable once per year, then postprocessing with Equation {eq}`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. +Annual food crop yields (g dry matter m{sup}`-2`) can be calculated by saving the `GRAINC_TO_FOOD_ANN` variable once per year, then postprocessing with Equation {eq}`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. $$ -\text{Grain yield} = \frac{GRAINC\_TO\_FOOD\_ANN) \times 0.85}{0.45} +\text{Grain yield} = \frac{\texttt{GRAINC_TO_FOOD_ANN} \times 0.85}{0.45} $$ (25.15) (table crop allocation parameters)= From 91087f1d2f54e612819ed6604078adaa4b063f97 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 12:56:35 +0200 Subject: [PATCH 51/73] Crops TN: Clarify crop food and product pools. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index aea3960316..de365051b5 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -588,11 +588,11 @@ where $\corgan$ and $\norgan$ are the carbon and nitrogen in the organ, respecti #### Harvest -CLM splits live crop grain C and N between "food" and "seed" pools. In the former—more generally a "crop product" pool—C and N decay to the atmosphere over one year, similar to how the wood product pools work. The latter is used in the subsequent year to account for the C and N required for crop seeding. +CLM splits live crop grain C and N between "food" and "seed" pools. In the former, C and N decay to the atmosphere over approximately one year. Specifically, $E = P^k$, where $E$ is the emissions in one timestep, $P$ is the product pool before emissions, and $k$ is a decay constant set to 0.0001296. The seed pool is used in the subsequent year to account for the C and N required for crop seeding. -Live leaf and stem biomass at harvest is transferred to biofuel, removed residue, and/or litter pools. +Live leaf and stem biomass at harvest is transferred to biofuel, removed residue, and/or litter pools. The harvested biofuel and removed residue pools (together, the "crop product" pool) emit their C and N to the atmosphere with a turnover time of approximately one year (as for the food pool above). -For the biofuel crops Miscanthus and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool as described for "food" harvest above. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter `biofuel_harvfrac` (0-1). +For the biofuel crops, _Miscanthus_ and switchgrass, 70% of live leaf and stem biomass at harvest is transferred to the crop product pool. This value can be changed for these crops—or set to something other than the default zero for any other crop—with the parameter `biofuel_harvfrac` (0-1). 50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter `crop_residue_removal_frac` (0–1). The default 50% is derived from {ref}`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. From 2af8e18787aa3389843300d52b0312a7b15b7468 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 14:38:32 +0200 Subject: [PATCH 52/73] Crops TN: Convert irrig params table to list-table. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 32 +++++++++++-------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index de365051b5..58b7c0a0e2 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -958,20 +958,24 @@ To conserve mass, irrigation is removed from river water storage (Chapter {numre (table irrigation parameters)= -```{eval-rst} -.. table:: Irrigation parameters - - +--------------------------------------+-------------+ - | Parameter | | - +======================================+=============+ - | :math:`f_{thresh}` | 1.0 | - +--------------------------------------+-------------+ - | :math:`z_{irrig}` (m) | 0.6 | - +--------------------------------------+-------------+ - | :math:`\Psi_{target}` (mm) | -3400 | - +--------------------------------------+-------------+ - | :math:`\Psi_{wilt}` (mm) | -150000 | - +--------------------------------------+-------------+ +```{list-table} Irrigation parameters +:header-rows: 1 + +* - Parameter + - Units + - Value +* - $f_{thresh}$ + - Unitless + - 1.0 +* - $z_{irrig}$ + - m + - 0.6 +* - $\Psi_{target}$ + - mm + - -3400 +* - $\Psi_{wilt}$ + - mm + - -150000 ``` % add a reference to surface data in chapter2 From a1068bb4e8a142cda510f15ab833a381938c94c0 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 14:47:03 +0200 Subject: [PATCH 53/73] Crops TN: Irrig params table: Add param names --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 58b7c0a0e2..957596b6ac 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -958,22 +958,27 @@ To conserve mass, irrigation is removed from river water storage (Chapter {numre (table irrigation parameters)= -```{list-table} Irrigation parameters +```{list-table} Irrigation parameters. Values in "Parameter" column are the associated namelist variable, if the value is not hard-coded in the model code. :header-rows: 1 -* - Parameter +* - Symbol + - Parameter - Units - Value * - $f_{thresh}$ + - `irrig_threshold_fraction` - Unitless - 1.0 * - $z_{irrig}$ + - `irrig_depth` - m - 0.6 * - $\Psi_{target}$ + - `irrig_target_smp` - mm - -3400 * - $\Psi_{wilt}$ + - (Hard-coded) - mm - -150000 ``` From 1ff581c693b0dcc3dd801e232e6d9015ae4f9136 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 16:46:46 +0200 Subject: [PATCH 54/73] Crops TN: grnfill alloc eqn: Split into 'organ', repr. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 957596b6ac..d75a3094f5 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -25,10 +25,12 @@ $\newcommand{\paramfleafi}{a_\textrm{leaf}^i}$ $\newcommand{\paramarooti}{a_\textrm{froot}^i}$ $\newcommand{\paramarootf}{a_\textrm{froot}^f}$ $\newcommand{\paramastemf}{a_\textrm{livestem}^f}$ +$\newcommand{\paramaorganf}{a_\textrm{organ}^f}$ $\newcommand{\paramlaimx}{L_\textrm{max}}$ $\newcommand{\paramdeclfact}{d_L}$ $\newcommand{\paramallconsl}{d_\textrm{alloc}^\textrm{leaf}}$ $\newcommand{\paramallconss}{d_\textrm{alloc}^\textrm{stem}}$ +$\newcommand{\paramallconso}{d_\textrm{alloc}^\textrm{organ}}$ $\newcommand{\paramleafcn}{CN_\textrm{leaf}}$ $\newcommand{\paramfleafcn}{\paramleafcn^\textrm{f}}$ $\newcommand{\paramlivewdcn}{CN_\textrm{stem}}$ @@ -554,23 +556,26 @@ At a crop-specific maximum leaf area index, $\paramlaimx$, carbon allocation is #### Grain fill -The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg-allocations)) to phase 3. During grain fill (phase 3), other allocation coefficients change to: +The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg-allocations)) to phase 3. During grain fill (phase 3), leaf and stem allocation coefficients change to: $$ \begin{array}{ll} -a_{leaf} =a_{leaf}^{i,3} & {\rm when} \quad a_{leaf}^{i,3} \le \paramaleaff \quad {\rm else} \\ -a_{leaf} =a_{leaf} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconsl } \ge \paramaleaff & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ - \\ -a_{livestem} =a_{livestem}^{i,3} & {\rm when} \quad a_{livestem}^{i,3} \le \paramastemf \quad {\rm else} \\ -a_{livestem} =a_{livestem} \left(1-\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconss } \ge \paramastemf & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ - \\ -a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} +a_{organ} = a_{organ}^{i,3} & {\rm when} \quad a_{organ}^{i,3} \le \paramaorganf \quad {\rm else} \\ +\\ +a_{organ} = a_{organ} \left( 1 - \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconso} \ge \paramaorganf & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ +\\ \end{array} $$ (25.5) -where $a_{leaf}^{i,3}$ and $a_{livestem}^{i,3}$ (initial values) equal the last $a_{leaf}$ and $a_{livestem}$ calculated in phase 2, $\paramdeclfact$, $\paramallconsl$ and $\paramallconss$ are leaf area index and leaf and stem allocation decline factors, $\paramaleaff$ and $\paramastemf$ are final values of these allocation coefficients, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. See {numref}`Table Crop allocation parameters` for parameter values. +where $\textrm{organ}$ is either $\textrm{leaf}$ or $\textrm{stem}$, $a_{organ}^{i,3}$ (initial values) equals the last $a_{organ}$ calculated in phase 2, $\paramdeclfact$ and $\paramallconso$ are allocation decline factors, $\paramaorganf$ is the parameterized value of these allocation coefficients at maturity, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. (See {numref}`Table Crop allocation parameters` for parameter values.) + +As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, $\paramlaimx$, leaf allocation is reduced to 0.001%. + +After allocation to fine roots, leaves, and stem, the rest of the carbon goes to the reproductive pool: -As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at a crop-specific maximum leaf area index, $\paramlaimx$, leaf allocation is reduced to 0.001%. The rest of the carbon that would have gone to leaves instead goes to the reproductive pool. +$$ +a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} +$$ (alloc-grnfill-repr) (nitrogen-retranslocation-for-crops)= From a6aba2ab506733583a9a698545970e08b5549295 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 16:50:03 +0200 Subject: [PATCH 55/73] Crops TN: Define fracthrugrnfill math macro. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index d75a3094f5..9f3c571385 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -47,6 +47,7 @@ $\newcommand{\paramminplantingtemp}{\paramplantingtemp^\textrm{min}}$ $\newcommand{\paramgddmin}{GDD_\textrm{min}}$ $\newcommand{\parambiofuelharvfrac}{\texttt{biofuel_harvfrac}}$ $\newcommand{\paramcropresidueremovalfrac}{\texttt{crop_residue_removal_frac}}$ +$\newcommand{\fracthrugrnfill}{\frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain}}$ (rst_crops and irrigation)= @@ -562,7 +563,7 @@ $$ \begin{array}{ll} a_{organ} = a_{organ}^{i,3} & {\rm when} \quad a_{organ}^{i,3} \le \paramaorganf \quad {\rm else} \\ \\ -a_{organ} = a_{organ} \left( 1 - \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \right)^{\paramallconso} \ge \paramaorganf & {\rm where} \quad \frac{\gddacctwom - \gddthreshgrain}{\gddthreshmat \paramdeclfact - \gddthreshgrain} \le 1 \\ +a_{organ} = a_{organ} \left( 1 - \fracthrugrnfill \right)^{\paramallconso} \ge \paramaorganf & {\rm where} \quad \fracthrugrnfill \le 1 \\ \\ \end{array} $$ (25.5) From 17f5d9ae79a5e4f3567625febefaab57e897bf59 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 17:24:57 +0200 Subject: [PATCH 56/73] Crops TN: Rearrange and relabel eqn about leaf/stem alloc in grnfill. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 9f3c571385..129ba1d64c 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -560,13 +560,11 @@ At a crop-specific maximum leaf area index, $\paramlaimx$, carbon allocation is The calculation of $a_{froot}$ remains the same from phase 2 (Eq. [](#eq-lfemerg-allocations)) to phase 3. During grain fill (phase 3), leaf and stem allocation coefficients change to: $$ -\begin{array}{ll} -a_{organ} = a_{organ}^{i,3} & {\rm when} \quad a_{organ}^{i,3} \le \paramaorganf \quad {\rm else} \\ -\\ -a_{organ} = a_{organ} \left( 1 - \fracthrugrnfill \right)^{\paramallconso} \ge \paramaorganf & {\rm where} \quad \fracthrugrnfill \le 1 \\ -\\ -\end{array} -$$ (25.5) +\begin{aligned} +x &= \min \left[1,\ \fracthrugrnfill \right] \\ +a_{organ} &= \min \left( a_{organ}^{i,3},\ \max \left[ \paramaorganf,\ a_{organ} \left( 1 - x \right)^{\paramallconso} \right] \right) +\end{aligned} +$$ (alloc-grnfill-leafstem) where $\textrm{organ}$ is either $\textrm{leaf}$ or $\textrm{stem}$, $a_{organ}^{i,3}$ (initial values) equals the last $a_{organ}$ calculated in phase 2, $\paramdeclfact$ and $\paramallconso$ are allocation decline factors, $\paramaorganf$ is the parameterized value of these allocation coefficients at maturity, and $\huithreshgrain$ is the heat unit threshold to enter the grain-filling phase. (See {numref}`Table Crop allocation parameters` for parameter values.) @@ -904,7 +902,7 @@ where $\parambaset$ is the *base temperature for GDD* (7{sup}`th` row) in {numre #### Separate reproductive pool -One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation {eq}`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM, as allocation declines in stem, leaf, and root pools (see section {numref}`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. +One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation {eq}`alloc-grnfill-leafstem` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM, as allocation declines in stem, leaf, and root pools (see section {numref}`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. (tillage)= From a3fdb490a04336d82175a16954e01d35d4df43e4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 17:43:53 +0200 Subject: [PATCH 57/73] Crops TN: Use subscript for C3 and C4. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 129ba1d64c..a91c6c38f2 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -71,9 +71,9 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. -CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C4 plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). -In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C3 crop ({numref}`Table Crop plant functional types`) treated as a second C3 grass. The unmanaged C3 crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C3 irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C3 or C4), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). +In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C{sub}`3` crop ({numref}`Table Crop plant functional types`) treated as a second C{sub}`3` grass. The unmanaged C{sub}`3` crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C{sub}`3` irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C{sub}`3` or C{sub}`4`), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not simulated, such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). @@ -88,10 +88,10 @@ Enabling the inactive crop PFTs will cause the model to error due to certain log - Plant functional type (PFT) - Simulated as * - 15 - - c3 unmanaged rainfed crop + - C{sub}`3` unmanaged rainfed crop - n/a (off if managed crops on) * - 16 - - c3 unmanaged irrigated crop + - C{sub}`3` unmanaged irrigated crop - n/a (off if managed crops on) * - 17 - rainfed temperate corn From 0023bc8253e4578a8e3cbb1450060265efe4f791 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 17:46:41 +0200 Subject: [PATCH 58/73] Crops TN: "Enabling the inactive crop PFTs" warning now admonition. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index a91c6c38f2..922f312c94 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -77,7 +77,9 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not simulated, such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). +```{warning} Enabling the inactive crop PFTs will cause the model to error due to certain logic in the code that does not yet handle those PFTs; see the related [GitHub issue](https://github.com/ESCOMP/CTSM/issues/3388). +``` (table crop plant functional types)= From a46d8e2e7d8c611a1b279c497f336c2635a21f7d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 8 Jun 2026 17:51:39 +0200 Subject: [PATCH 59/73] Crops TN: Crop PFT table: Clarify unmanaged vs managed" --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 922f312c94..a88d323f0e 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -83,7 +83,7 @@ Enabling the inactive crop PFTs will cause the model to error due to certain log (table crop plant functional types)= -```{list-table} Crop plant functional types (PFTs) included in CLM with managed crops on (BgcCrop component sets). IVT is the integer used to refer to each vegetation type in the FORTRAN code. +```{list-table} Crop plant functional types (PFTs) included in CLM. IVT is the integer used to refer to each vegetation type in the FORTRAN code. :header-rows: 1 * - IVT @@ -91,10 +91,10 @@ Enabling the inactive crop PFTs will cause the model to error due to certain log - Simulated as * - 15 - C{sub}`3` unmanaged rainfed crop - - n/a (off if managed crops on) + - (itself) * - 16 - C{sub}`3` unmanaged irrigated crop - - n/a (off if managed crops on) + - (itself) * - 17 - rainfed temperate corn - (itself) From f68906f9c14860023aba096b6d5f2e0ee28fd5ec Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 9 Jun 2026 11:46:14 +0200 Subject: [PATCH 60/73] Crops TN: Clarify unmanaged crops not USUALLY simulated. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index a88d323f0e..55070b7e00 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -75,7 +75,7 @@ CLM includes ten actively managed crop types (temperate soybean, tropical soybea In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C{sub}`3` crop ({numref}`Table Crop plant functional types`) treated as a second C{sub}`3` grass. The unmanaged C{sub}`3` crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C{sub}`3` irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C{sub}`3` or C{sub}`4`), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). -It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not simulated, such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). +It should be noted that PFT-level history output merges all crop types into the actively managed crop type, so analysis of crop-specific output will require use of the land surface input dataset to remap the yields of each actively and inactively managed crop type. Otherwise, the actively managed crop type will include yields for that crop type and all inactively managed crop types that are using the same parameter set. Note that if a "pure" simulation of the actively-managed crop types is desired, the `mergetoclmpft` parameter of the other crop types should be set to something not usually simulated in runs with managed crops on (`BgcCrop` component sets), such as 15 (C{sub}`3` unmanaged crops; see [](#set-paramfile)). ```{warning} Enabling the inactive crop PFTs will cause the model to error due to certain logic in the code that does not yet handle those PFTs; see the related [GitHub issue](https://github.com/ESCOMP/CTSM/issues/3388). From 9a218dbec7609e6545051e6e41820c5cd1eb356a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 9 Jun 2026 14:30:38 +0200 Subject: [PATCH 61/73] Docs: Add setting disclaimer substitution strings. --- .gitmodules | 2 +- doc/doc-builder | 2 +- doc/substitutions.py | 26 +++++++++++++++++++++++++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/.gitmodules b/.gitmodules index 87460be5f3..6203068b84 100644 --- a/.gitmodules +++ b/.gitmodules @@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial [submodule "doc-builder"] path = doc/doc-builder url = https://github.com/ESMCI/doc-builder -fxtag = v3.2.1 +fxtag = v3.3 fxrequired = ToplevelOptional # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed fxDONOTUSEurl = https://github.com/ESMCI/doc-builder diff --git a/doc/doc-builder b/doc/doc-builder index 15e171dfcf..a0370bab03 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 15e171dfcf77ca2bd85415a99a50ad3994c608c4 +Subproject commit a0370bab038f8c4351104a4fcfde80b9d02949a6 diff --git a/doc/substitutions.py b/doc/substitutions.py index 29b6fb54de..1fae4915b0 100644 --- a/doc/substitutions.py +++ b/doc/substitutions.py @@ -60,4 +60,28 @@ "dirmenu_entry": "clmdoc", "description": "One line description of project.", "category": tex_category, -} \ No newline at end of file +} + +############################### +### Purely custom variables ### +############################### + +nonparamfile_disclaimer_md = ( + "**Note:** The values here should be up-to-date with those used in {{version_label}}," + " but there may be mistakes." +) +nonparamfile_disclaimer_rst = ( + "**Note:** The values here should be up-to-date with those used in |version_label|," + " but there may be mistakes." +) + +paramfile_disclaimer_md = ( + nonparamfile_disclaimer_md + + " If you want to check the values for your version, use" + " [](query-paramfile) on the `paramfile` for your case." +) +paramfile_disclaimer_rst = ( + nonparamfile_disclaimer_rst + + " If you want to check the values for your version, use" + " :ref:`query-paramfile` on the ``paramfile`` for your case." +) From 9a4434e3ea832ae40a58934df4eb9de22aa08832 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 9 Jun 2026 14:31:12 +0200 Subject: [PATCH 62/73] Crops TN: Add disclaimer to parameter tables. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 55070b7e00..e135f9144f 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -83,12 +83,12 @@ Enabling the inactive crop PFTs will cause the model to error due to certain log (table crop plant functional types)= -```{list-table} Crop plant functional types (PFTs) included in CLM. IVT is the integer used to refer to each vegetation type in the FORTRAN code. +```{list-table} Crop plant functional types (PFTs) included in CLM. IVT is the integer used to refer to each vegetation type in the FORTRAN code. {{paramfile_disclaimer_md}} :header-rows: 1 * - IVT - Plant functional type (PFT) - - Simulated as + - Simulated as (`mergetoclmpft`) * - 15 - C{sub}`3` unmanaged rainfed crop - (itself) @@ -370,7 +370,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct (table crop phenology parameters)= -```{list-table} Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). Where there are two values in a cell, they refer to the rainfed and irrigated functional types, respectively. +```{list-table} Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). Where there are two values in a cell, they refer to the rainfed and irrigated functional types, respectively. {{paramfile_disclaimer_md}} :header-rows: 1 * - Parameter @@ -646,7 +646,7 @@ $$ (25.15) (table crop allocation parameters)= -```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). +```{list-table} Crop allocation parameters for the active crop plant functional types (PFTs) in CLM with managed crops on (BgcCrop component sets). {{paramfile_disclaimer_md}} :header-rows: 1 * - Parameter @@ -964,7 +964,7 @@ To conserve mass, irrigation is removed from river water storage (Chapter {numre (table irrigation parameters)= -```{list-table} Irrigation parameters. Values in "Parameter" column are the associated namelist variable, if the value is not hard-coded in the model code. +```{list-table} Irrigation parameters. Values in the "Parameter" column are the associated namelist variable, if the value is not hard-coded in the model code. {{nonparamfile_disclaimer_md}} :header-rows: 1 * - Symbol From d370031d87988fab05d6a9497e117f5a74b51699 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 9 Jun 2026 14:33:35 +0200 Subject: [PATCH 63/73] Crops TN: Clarify "functional form." --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index e135f9144f..d3b7063689 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -71,7 +71,7 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. -CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form—i.e., they differ in only a few parameters. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C{sub}`3` crop ({numref}`Table Crop plant functional types`) treated as a second C{sub}`3` grass. The unmanaged C{sub}`3` crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C{sub}`3` irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C{sub}`3` or C{sub}`4`), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). From 5372828e1cd1a9f32928c1bc4d9edf09ce572097 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 9 Jun 2026 14:41:53 +0200 Subject: [PATCH 64/73] Crops TN: Always say "stem," not "live stem." --- .../CLM50_Tech_Note_Crop_Irrigation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index d3b7063689..4f3b798c82 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -24,7 +24,7 @@ $\newcommand{\paramaleaff}{a_\textrm{leaf}^f}$ $\newcommand{\paramfleafi}{a_\textrm{leaf}^i}$ $\newcommand{\paramarooti}{a_\textrm{froot}^i}$ $\newcommand{\paramarootf}{a_\textrm{froot}^f}$ -$\newcommand{\paramastemf}{a_\textrm{livestem}^f}$ +$\newcommand{\paramastemf}{a_\textrm{stem}^f}$ $\newcommand{\paramaorganf}{a_\textrm{organ}^f}$ $\newcommand{\paramlaimx}{L_\textrm{max}}$ $\newcommand{\paramdeclfact}{d_L}$ @@ -71,7 +71,7 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. -CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form—i.e., they differ in only a few parameters. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf & livestem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form—i.e., they differ in only a few parameters. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf and stem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C{sub}`3` crop ({numref}`Table Crop plant functional types`) treated as a second C{sub}`3` grass. The unmanaged C{sub}`3` crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C{sub}`3` irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C{sub}`3` or C{sub}`4`), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). @@ -354,7 +354,7 @@ where $n$ is the number of years that $\gddxrun$ gas been calculated for. Note t The "leaf emergence" phase is the period of vegetative growth between when the leaves first emerge from the soil to when filling of the reproductive organ begins. -According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddthreshmat$ (see $\huithreshlfemerg$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. +According to AgroIBIS, leaves may emerge when the growing degree-days of soil temperature to 0.05 m depth ($\gddaccsoil$ ), which is tracked since planting, reaches 1 to 5% of $\gddthreshmat$ (see $\huithreshlfemerg$ in {numref}`Table Crop phenology parameters`). The base temperature threshold values for $\gddaccsoil$ are listed in {numref}`Table Crop phenology parameters` (the same base temperature threshold values are also used for $\gddacctwom$ in section {numref}`Grain Fill`), and leaf emergence (crop phenology phase 2) starts when this threshold is met. Leaf onset occurs in the first time step of phase 2, at which moment all seed C is transferred to leaf C. Subsequently, the leaf area index generally increases throughout phase 2 until it reaches a predetermined maximum value. Stem and root C also increase throughout phase 2 based on the carbon allocation algorithm in section {numref}`Leaf emergence to grain fill`. Note that, since all represented crops are herbaceous, their stem biomass is all is live stem. (grain fill)= @@ -521,7 +521,7 @@ Notes: ### Allocation -Allocation changes based on the crop phenology phase (section {numref}`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop's leaf, live stem, fine root, and reproductive pools. +Allocation changes based on the crop phenology phase (section {numref}`Phenology`). Simulated C assimilation begins every year upon leaf emergence in phase 2 and ends with harvest at the end of phase 3; therefore, so does the allocation of such C to the crop's leaf, stem, fine root, and reproductive pools. Typically, C:N ratios in plant tissue vary throughout the growing season and tend to be lower during early growth stages and higher in later growth stages. In order to account for this seasonal change, two sets of C:N ratios are established in CLM for the leaf, stem, and fine root of crops: one during the leaf emergence phase (phenology phase 2), and a second during grain fill phase (phenology phase 3). This modified C:N ratio approach accounts for the nitrogen retranslocation that occurs during the grain fill phase (phase 3) of crop growth. Leaf, stem, and root C:N ratios for phase 2 are calculated using the standard CLM carbon and nitrogen allocation scheme (Chapter {numref}`rst_CN Allocation`), which provides a target C:N value ({numref}`Table Crop allocation parameters`) and allows C:N to vary through time. During grain fill (phase 3) of the crop growth cycle, a portion of the nitrogen in the plant tissues is moved to a storage pool to fulfill nitrogen demands of organ (reproductive pool) development, such that the resulting C:N ratio of the plant tissue is reflective of measurements at harvest. All C:N ratios were determined by calibration process, through comparisons of model output versus observations of plant carbon throughout the growing season. @@ -538,7 +538,7 @@ $$ \begin{array}{l} {a_{repr} =0} \\ {a_{froot} = \paramarooti -(\paramarooti - \paramarootf ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ {a_{leaf} =(1-a_{froot} ) \times \frac{\paramfleafi (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ -{a_{livestem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} +{a_{stem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} $$ (eq-lfemerg-allocations) where $\paramfleafi$, $\paramarooti$, and $\paramarootf$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. @@ -575,7 +575,7 @@ As in the leaf-emergence phase (Sect {numref}`leaf emergence to grain fill`), at After allocation to fine roots, leaves, and stem, the rest of the carbon goes to the reproductive pool: $$ -a_{repr} =1-a_{froot} -a_{livestem} -a_{leaf} +a_{repr} =1-a_{froot} -a_{stem} -a_{leaf} $$ (alloc-grnfill-repr) (nitrogen-retranslocation-for-crops)= @@ -602,7 +602,7 @@ For the biofuel crops, _Miscanthus_ and switchgrass, 70% of live leaf and stem b 50% of any remaining live leaf and stem biomass at harvest (after biofuel removal, if any) is removed to the crop product pool to represent off-field uses such as use for animal feed and bedding. This value can be changed with the parameter `crop_residue_removal_frac` (0–1). The default 50% is derived from {ref}`Smerald et al. 2023 `, who found a global average of 50% of residues left on the field. This includes residues burned in the field, meaning that our implementation implictly assumes the CLM crop burning representation will handle those residues appropriately. -The following equations illustrate how this works. Subscript $p$ refers to either the leaf or live stem biomass pool. +The following equations illustrate how this works. Subscript $p$ refers to either the leaf or stem biomass pool. $$ CF_{p,biofuel} = \left({CS_{p} \mathord{\left/ {\vphantom {CS_{p} \Delta t}} \right.} \Delta t} @@ -636,7 +636,7 @@ NF_{p,litter} = \left({NS_{p} \mathord{\left/ {\vphantom {NS_{p} \Delta t}} \ri \right) \times \left( 1-\parambiofuelharvfrac \right) \times \left( 1-\paramcropresidueremovalfrac \right) $$ (25.14) -where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and `biofuel_harvfrac` is the harvested fraction of leaf/livestem for biofuel feedstocks. +where CF is the carbon flux, CS is stored carbon, NF is the nitrogen flux, NS is stored nitrogen, and `biofuel_harvfrac` is the harvested fraction of leaf/stem for biofuel feedstocks. Annual food crop yields (g dry matter m{sup}`-2`) can be calculated by saving the `GRAINC_TO_FOOD_ANN` variable once per year, then postprocessing with Equation {eq}`25.15`. This calculation assumes that grain C is 45% of the total dry weight. Additionally, harvest is not typically 100% efficient, so analysis needs to assume that harvest efficiency is less---we use 85%. From d198657ab52ff09be00064a2efcf947af3198b4e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 09:55:11 +0200 Subject: [PATCH 65/73] Crops TN: Remove ref to a table row number. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 4f3b798c82..c5b3120dad 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -898,7 +898,7 @@ latitudinal\ variation\ in\ base\ T = \left\{ \end{array} \right\} $$ (25.18) -where $\parambaset$ is the *base temperature for GDD* (7{sup}`th` row) in {numref}`Table Crop phenology parameters`. Such latitudinal variation in base temperature could slow $\gddacctwom$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. +where $\parambaset$ is the base temperature for GDD ({numref}`Table Crop phenology parameters`). Such latitudinal variation in base temperature could slow $\gddacctwom$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane. (separate-reproductive-pool)= From a3cca827b3376972fecff89cbcda6cfb036abd42 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 10:23:00 +0200 Subject: [PATCH 66/73] Crops TN: Clarify a sentence --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index c5b3120dad..5e7d13babb 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -888,7 +888,7 @@ Biological N fixation for soybeans is calculated by the fixation and uptake of n #### Latitudinal variation in base growth temperature -For most crops, $\gddacctwom$ (growing degree days since planting) is the same in all locations. However, for both rainfed and irrigated spring wheat and sugarcane, the calculation of $\gddacctwom$ allows for latitudinal variation: +For most crops, $\gddacctwom$ (growing degree days since planting) is the same in all locations. However, for spring wheat and sugarcane, the calculation of $\gddacctwom$ allows for latitudinal variation: $$ latitudinal\ variation\ in\ base\ T = \left\{ From b825a75a4b00482a0b81f7bb05969902e7802aab Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 11:09:46 +0200 Subject: [PATCH 67/73] Crops TN: Align lfemerg alloc eqn. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 5e7d13babb..eb3c7e3e49 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -535,10 +535,12 @@ During phase 2, the allocation coefficients (fraction of available C) to each C pool are defined as: $$ -\begin{array}{l} {a_{repr} =0} \\ -{a_{froot} = \paramarooti -(\paramarooti - \paramarootf ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right)} \\ -{a_{leaf} =(1-a_{froot} ) \times \frac{\paramfleafi (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1} \\ -{a_{stem} =1-a_{repr} -a_{froot} -a_{leaf} } \end{array} +\begin{aligned} +a_{repr} &= 0 \\ +a_{froot} &= \paramarooti -(\paramarooti - \paramarootf ) \times {\rm min}\left(\frac{\gddacctwom }{\gddthreshmat }, 1\right) \\ +a_{leaf} &= (1-a_{froot} ) \times \frac{\paramfleafi (e^{-b} -e^{-b\frac{\gddacctwom }{\gddthreshgrain} } )}{e^{-b} -1} {\rm \; \; \; where\; \; \; }b=0.1 \\ +a_{stem} &= 1-a_{repr} - a_{froot} - a_{leaf} +\end{aligned} $$ (eq-lfemerg-allocations) where $\paramfleafi$, $\paramarooti$, and $\paramarootf$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. From 0d835bf48038ac19f82d1e79af98318fd0269b2a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 11:32:38 +0200 Subject: [PATCH 68/73] Crops TN: Explain 48 in equation. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index eb3c7e3e49..d0e0ded952 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -336,9 +336,7 @@ $$ \gddx = \gddx + \frac{\max \left( \gddxdaymax,\ \min \left[ 0,\ \ttwom - 273.15 - x \right] \right)}{48} $$ (25.3) -where $\ttwom$ is the 2-m air temperature (K), 273.15 K is the freezing temperature of water, and $GDD$ is in units of °C-days. $\gddxdaymax$, the maximum daily growing degree-day accumulation, is 26°C for $x=0$ and 30°C for $x=8$ and $x=10$. - -- **Is there a pre-existing symbol for number of timesteps in a day that we could use instead of 48?** +where $\ttwom$ is the 2-m air temperature (K), 273.15 K is the freezing temperature of water, and $GDD$ is in units of °C-days. $\gddxdaymax$, the maximum daily growing degree-day accumulation, is 26°C for $x=0$ and 30°C for $x=8$ and $x=10$. The division by 48 is to adjust for the number of timesteps in a day. By default, the $\gddx$ values are set to zero at the beginning of the "$\gddx$ season" and then accumulated through its end: from April 1 through September 30 in the Northern Hemisphere and from October 1 through March 31 in the Southern Hemisphere. (Setting `stream_gdd20_seasons = .true.` would instead take those start and end dates from PFT-specific maps in the input files `stream_fldFileName_gdd20_season_start` and `stream_fldFileName_gdd20_season_end`, respectively; however, this is not scientifically supported.) At the end of each $\gddx$ season, the final value of $\gddx$ is incorporated into $\gddxrun$ like so: From e39c05e95fe0ae8b9bc6aacc1f6a31e1f3c71d79 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 11:50:03 +0200 Subject: [PATCH 69/73] Crops TN: Fix min/max in GDD per-timestep eqn. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index d0e0ded952..bcd03fa1bf 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -333,7 +333,7 @@ If both `cropcals_rx_adapt` and `cropcals_rx` are false, or if $\gddthreshmatbl$ Equation {eq}`25.3` shows how we calculate $\gddzero$, $\gddeight$, and $\gddten$ for each model timestep: $$ -\gddx = \gddx + \frac{\max \left( \gddxdaymax,\ \min \left[ 0,\ \ttwom - 273.15 - x \right] \right)}{48} +\gddx = \gddx + \frac{\min \left( \gddxdaymax,\ \max \left[ 0,\ \ttwom - 273.15 - x \right] \right)}{48} $$ (25.3) where $\ttwom$ is the 2-m air temperature (K), 273.15 K is the freezing temperature of water, and $GDD$ is in units of °C-days. $\gddxdaymax$, the maximum daily growing degree-day accumulation, is 26°C for $x=0$ and 30°C for $x=8$ and $x=10$. The division by 48 is to adjust for the number of timesteps in a day. From 7d479a12990aee17da080b4fddbb563f96cb5148 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 12:02:00 +0200 Subject: [PATCH 70/73] Crops TN: Consistently use _Miscanthus_. --- .../CLM50_Tech_Note_Crop_Irrigation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index bcd03fa1bf..cdb68e3c17 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -71,7 +71,7 @@ With interactive crop management and, therefore, a more accurate representation To allow crops to coexist with natural vegetation in a grid cell, the vegetated land unit is separated into a naturally vegetated land unit and a managed crop land unit. Unlike the plant functional types (PFTs) in the naturally vegetated land unit, the managed crop PFTs in the managed crop land unit do not share soil columns and thus permit for differences in the land management between crops. Each crop type has a rainfed and an irrigated PFT that are on independent soil columns. Crop area distributions are defined as explained in Sects. {numref}`Surface Data` and {numref}`rst_Transient Landcover Change`; see Sect. {numref}`Surface Heterogeneity and Data Structure` for more information on land units and soil columns. -CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, miscanthus, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form—i.e., they differ in only a few parameters. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. Miscanthus and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf and stem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). +CLM includes ten actively managed crop types (temperate soybean, tropical soybean, temperate corn, tropical corn, spring wheat, cotton, rice, sugarcane, _Miscanthus_, and switchgrass) that are chosen based on the availability of corresponding algorithms in AgroIBIS and as developed by {ref}`Badger and Dirmeyer (2015)` and described by {ref}`Levis et al. (2016)`, or from available observations as described by {ref}`Cheng et al. (2019)`. Sugarcane and tropical corn are both C{sub}`4` plants and are therefore represented using the temperate corn functional form—i.e., they differ in only a few parameters. Tropical soybean uses the temperate soybean functional form, while rice and cotton use the wheat functional form. In tropical regions, parameter values were originally developed for the Amazon Basin. Plantation areas of bioenergy crops are projected to expand throughout the 21st century as a major energy source to replace fossil fuels and mitigate climate change. _Miscanthus_ and switchgrass are perennial bioenergy crops and have quite different physiological traits and land management practices than annual crops, such as longer growing seasons, higher productivity, and lower demands for nutrients and water. About 70% of biofuel aboveground biomass (leaf and stem) is removed at harvest. Parameter values were developed by using observation data collected at the University of Illinois Energy Farm located in Central Midwestern United States ({ref}`Cheng et al., 2019`). In addition, CLM's default list of plant functional types (PFTs) includes an irrigated and unirrigated unmanaged C{sub}`3` crop ({numref}`Table Crop plant functional types`) treated as a second C{sub}`3` grass. The unmanaged C{sub}`3` crop is only used when the crop model is not active and has grid cell coverage assigned from satellite data, and the unmanaged C{sub}`3` irrigated crop type is currently not used since irrigation requires the crop model to be active. The default list of PFTs also includes twenty-one inactive crop PFTs that do not yet have associated parameters required for active management. Each of the inactive crop types is simulated using the parameters of the spatially closest associated crop type that is most similar to the functional type (e.g., C{sub}`3` or C{sub}`4`), which is required to maintain similar phenological parameters based on temperature thresholds. Information detailing which parameters are used for each crop type is included in {numref}`Table Crop plant functional types`; this information can also be found in the parameter file (variable `mergetoclmpft`; see [](#query-paramfile)). @@ -258,10 +258,10 @@ Enabling the inactive crop PFTs will cause the model to error due to certain log - irrigated sunflower - irrigated spring wheat * - 71 - - rainfed miscanthus + - rainfed _Miscanthus_ - (itself) * - 72 - - irrigated miscanthus + - irrigated _Miscanthus_ - (itself) * - 73 - rainfed switchgrass @@ -381,7 +381,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When $\gddacct - sugarcane - tropical corn - tropical soybean - - miscanthus + - _Miscanthus_ - switchgrass * - IVT - n/a @@ -543,7 +543,7 @@ $$ (eq-lfemerg-allocations) where $\paramfleafi$, $\paramarooti$, and $\paramarootf$ are initial and final values of these coefficients (respectively parameters `fleafi`, `arooti`, and `arootf`), and $\gddthreshgrain$ is the growing degree-day threshold to enter the grain-filling phase. -For most crops, $\gddthreshgrain$ is equal to $\gddthreshmat$ times the PFT parameter $\huithreshgrain$ (`grnfill`). However, for corn, sugarcane, miscanthus, and switchgrass, an adjustment is applied ({ref}`Kucharik 2003 `; C.J. Kucharik, pers. comm.): +For most crops, $\gddthreshgrain$ is equal to $\gddthreshmat$ times the PFT parameter $\huithreshgrain$ (`grnfill`). However, for corn, sugarcane, _Miscanthus_, and switchgrass, an adjustment is applied ({ref}`Kucharik 2003 `; C.J. Kucharik, pers. comm.): $$ \begin{aligned} @@ -659,7 +659,7 @@ $$ (25.15) - sugarcane - tropical corn - tropical soybean - - miscanthus + - _Miscanthus_ - switchgrass * - IVT - n/a @@ -853,7 +853,7 @@ $$ (25.15) #### Physical Crop Characteristics -Leaf area index ($L$) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index ($S$) is equal to 0.1$L$ for temperate and tropical corn, sugarcane, switchgrass, and miscanthus and 0.2$L$ for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the $S$ is kept at 0.25 to simulate a post-harvest "stubble" on the ground. +Leaf area index ($L$) is calculated as a function of specific leaf area (SLA, {numref}`Table Crop phenology parameters`) and leaf C. Stem area index ($S$) is equal to 0.1$L$ for temperate and tropical corn, sugarcane, switchgrass, and _Miscanthus_ and 0.2$L$ for other crops, as in AgroIBIS. All live C and N pools go to 0 after crop harvest, but the $S$ is kept at 0.25 to simulate a post-harvest "stubble" on the ground. Crop heights at the top and bottom of the canopy, $\paramztopmx$ and ${z}_{bot}$ (m), come from the AgroIBIS formulation: @@ -870,7 +870,7 @@ where $\paramztopmx$ is the maximum top-of-canopy height of the crop ({numref}`T #### Interactive Fertilization -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, $f$, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to _Miscanthus_. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, $f$, is set as soon as the leaf emergence phase for crops initiates: $$ f = n \times 86400 From 73b0fbd00fdf057d074fa46116cce16fc821f805 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 10 Jun 2026 12:05:10 +0200 Subject: [PATCH 71/73] Crops TN: Make some var names literals. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index cdb68e3c17..9d2337393d 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -870,7 +870,7 @@ where $\paramztopmx$ is the maximum top-of-canopy height of the crop ({numref}`T #### Interactive Fertilization -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to _Miscanthus_. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, $f$, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) ({ref}`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m{sup}`2`/yr is specified on the land surface data set by the field `CONST_FERTNITRO_CFT`. In transient simulations, annual fertilizer application is specified on the land use time series file by the field `FERTNITRO_CFT`, which is also in g N/m{sup}`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field `manunitro`. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to _Miscanthus_. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States {ref}`(Cheng et al., 2019)` rather than the LUMIP timeseries. Manure N is applied at a rate of 0.002 kg N/m{sup}`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM inherits this legacy, although denitrification rates are slower in the current version of the model ({ref}`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, $f$, is set as soon as the leaf emergence phase for crops initiates: $$ f = n \times 86400 From 246d9d7700959d93fb53f562dd0153524ed86ea9 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 11 Jun 2026 09:15:10 +0200 Subject: [PATCH 72/73] Crops TN: Align an equation. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 9d2337393d..7012b277e6 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -300,11 +300,11 @@ Each crop can be planted in each gridcell once per year, in the "sowing window." To be planted, a crop patch must meet the following requirements sometime within its sowing window: $$ -\begin{array}{c} -{T_{10d} > \paramplantingtemp} \\ -{T_{10d}^{\min } > \paramminplantingtemp} \\ -{\gddeightrun \ge \paramgddmin} -\end{array} +\begin{align} +T_{10d} &> \paramplantingtemp \\ +T_{10d}^{\min } &> \paramminplantingtemp \\ +\gddeightrun &\ge \paramgddmin +\end{align} $$ (25.1) where ${T}_{10d}$ is the 10-day running mean of $\ttwom$, (the simulated 2-m air temperature during each model time step) and $T_{10d}^{\min}$ is the 10-day running mean of $\ttwom^{\min }$ (the daily minimum of $\ttwom$). $\paramplantingtemp$ and $\paramminplantingtemp$ are crop-specific coldest planting temperatures ({numref}`Table Crop phenology parameters`), $\gddeightrun$ is the 20-year running mean growing degree-days (units are °C day) tracked from April through September (NH) above 8°C with maximum daily increments of 30 degree-days (see equation {eq}`25.3`), and $\paramgddmin$is the minimum growing degree day requirement ({numref}`Table Crop phenology parameters`). $\gddeightrun$ does not change as quickly as ${T}_{10d}$ and $T_{10d}^{\min }$, so it determines whether it is warm enough for the crop to be planted in a grid cell, while the 2-m air temperature variables determine the day when the crop may be planted if the $\gddeightrun$ threshold is met. If the requirements in equation {eq}`25.1` are not met by the maximum planting date, crops are still planted on the maximum planting date as long as $\gddeightrun > 0$. From 89f970624cdae3ea80cfe88cb52d12545cd3c8fb Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 11 Jun 2026 09:16:13 +0200 Subject: [PATCH 73/73] Crops TN: Simplify lat variation in base T. --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md index 7012b277e6..262ef6f17d 100644 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.md @@ -888,14 +888,10 @@ Biological N fixation for soybeans is calculated by the fixation and uptake of n #### Latitudinal variation in base growth temperature -For most crops, $\gddacctwom$ (growing degree days since planting) is the same in all locations. However, for spring wheat and sugarcane, the calculation of $\gddacctwom$ allows for latitudinal variation: +For most crops, $\gddacctwom$ (growing degree days since planting) is the same in all locations. However, for spring wheat and sugarcane within 30° of the Equator, the calculation of $\gddacctwom$ allows for latitudinal variation: $$ -latitudinal\ variation\ in\ base\ T = \left\{ -\begin{array}{lr} -\parambaset +12 - 0.4 \times latitude &\qquad 0 \le latitude \le 30 \\ -\parambaset +12 + 0.4 \times latitude &\qquad -30 \le latitude \le 0 -\end{array} \right\} +\parambaset^{\prime} = \parambaset + 12 - 0.4 \times \mid latitude \mid $$ (25.18) where $\parambaset$ is the base temperature for GDD ({numref}`Table Crop phenology parameters`). Such latitudinal variation in base temperature could slow $\gddacctwom$ accumulation extend the growing season for regions within 30°S to 30°N for spring wheat and sugarcane.