adding documentation to the code

Author: k4rst3ns

config/default.cfg

@@ -1860,7 +1860,13 @@ cfg$gms$s59_scm_scenario_start <- 2025   # def = 2025
 cfg$gms$s59_scm_scenario_target <- 2050   # def = 2050
 
 # * Soil carbon management recurring cost (USD17MER per ha)
-cfg$gms$s59_cost_scm_recur <- 80   # def = 80
+# * Soil carbon management practices on cropland involve increased crop residue inputs  
+# * through various agronomic practices. Literature estimates for these practices vary,  
+# * e.g., from 20 USD06MER per ha (Smith et al. 2008) to 90-115 USD21MER per ha  
+# * (Uludere Aragon et al. 2024), with a central estimate of 65 USD17MER per ha chosen  
+# * for this configuration. More details can be found in the input.gms file of the  
+# * corresponding realization
+cfg$gms$s59_cost_scm_recur <- 65   # def = 65
 
 # ***---------------------    60_bioenergy   -----------------------------------
 # * (1stgen_priced_dec18):    exogenous and price-based 1st generation bioenergy

literature.bib

@@ -1722,37 +1722,37 @@ @techreport{budynski_straw_2020
 }
 
 @article{smith_greenhouse_2008,
-	title = {Greenhouse gas mitigation in agriculture},
-	volume = {363},
-	copyright = {© 2007 The Royal Society},
-	issn = {0962-8436, 1471-2970},
-	url = {http://rstb.royalsocietypublishing.org/content/363/1492/789},
-	doi = {10.1098/rstb.2007.2184},
-	language = {en},
-	number = {1492},
-	urldate = {2016-12-13},
-	journal = {Philosophical Transactions of the Royal Society B: Biological Sciences},
-	author = {Smith, Pete and Martino, Daniel and Cai, Zucong and Gwary, Daniel and Janzen, Henry and Kumar, Pushpam and McCarl, Bruce and Ogle, Stephen and O'Mara, Frank and Rice, Charles and Scholes, Bob and Sirotenko, Oleg and Howden, Mark and McAllister, Tim and Pan, Genxing and Romanenkov, Vladimir and Schneider, Uwe and Towprayoon, Sirintornthep and Wattenbach, Martin and Smith, Jo},
-	month = feb,
-	year = {2008},
-	pmid = {17827109},
-	pages = {789--813},
+  title = {Greenhouse gas mitigation in agriculture},
+  volume = {363},
+  copyright = {© 2007 The Royal Society},
+  issn = {0962-8436, 1471-2970},
+  url = {http://rstb.royalsocietypublishing.org/content/363/1492/789},
+  doi = {10.1098/rstb.2007.2184},
+  language = {en},
+  number = {1492},
+  urldate = {2016-12-13},
+  journal = {Philosophical Transactions of the Royal Society B: Biological Sciences},
+  author = {Smith, Pete and Martino, Daniel and Cai, Zucong and Gwary, Daniel and Janzen, Henry and Kumar, Pushpam and McCarl, Bruce and Ogle, Stephen and O'Mara, Frank and Rice, Charles and Scholes, Bob and Sirotenko, Oleg and Howden, Mark and McAllister, Tim and Pan, Genxing and Romanenkov, Vladimir and Schneider, Uwe and Towprayoon, Sirintornthep and Wattenbach, Martin and Smith, Jo},
+  month = feb,
+  year = {2008},
+  pmid = {17827109},
+  pages = {789--813},
 }
 
 @article{uludere_aragon_realistic_2024,
-	title = {The {Realistic} {Potential} of {Soil} {Carbon} {Sequestration} in {U}.{S}. {Croplands} for {Climate} {Mitigation}},
-	volume = {12},
-	copyright = {© 2024. The Author(s).},
-	issn = {2328-4277},
-	url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2023EF003866},
-	doi = {10.1029/2023EF003866},
-	language = {en},
-	number = {6},
-	urldate = {2025-02-10},
-	journal = {Earth's Future},
-	author = {Uludere Aragon, Nazli and Xie, Yanhua and Bigelow, Daniel and Lark, Tyler J. and Eagle, Alison J.},
-	year = {2024},
-	note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1029/2023EF003866},
-	keywords = {climate mitigation, natural climate solutions, agricultural land use, carbon sequestration potential, conservation policy, cover cropping, stable croplands},
-	pages = {e2023EF003866},
+  title = {The {Realistic} {Potential} of {Soil} {Carbon} {Sequestration} in {U}.{S}. {Croplands} for {Climate} {Mitigation}},
+  volume = {12},
+  copyright = {© 2024. The Author(s).},
+  issn = {2328-4277},
+  url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2023EF003866},
+  doi = {10.1029/2023EF003866},
+  language = {en},
+  number = {6},
+  urldate = {2025-02-10},
+  journal = {Earth's Future},
+  author = {Uludere Aragon, Nazli and Xie, Yanhua and Bigelow, Daniel and Lark, Tyler J. and Eagle, Alison J.},
+  year = {2024},
+  note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1029/2023EF003866},
+  keywords = {climate mitigation, natural climate solutions, agricultural land use, carbon sequestration potential, conservation policy, cover cropping, stable croplands},
+  pages = {e2023EF003866},
 }

modules/59_som/cellpool_jan23/input.gms

@@ -8,13 +8,35 @@
 scalars
   s59_nitrogen_uptake  Maximum plant available nitrogen from soil organic matter loss (tN per ha)        / 0.2 /
   s59_fader_functional_form       Switch for functional form of faders (1) / 1 / 
-  s59_scm_target                  Share of soil carbon management on total cropland in target year (1) / 0.4 /
+  s59_scm_target                  Share of soil carbon management on total cropland in target year (1) / 0 /
   s59_scm_target_noselect         Share of soil carbon management on total cropland in target year (1) / 0 /
   s59_scm_scenario_start          Soil carbon management scenario start year / 2025 /
-  s59_scm_scenario_target         Soil carbon management scenario target year / 2045 /
-  s59_cost_scm_recur              Soil carbon management recurring cost (USD17MER per ha) / 62 /
+  s59_scm_scenario_target         Soil carbon management scenario target year / 2050 /
+  s59_cost_scm_recur              Soil carbon management recurring cost (USD17MER per ha) / 65 /
 ;
 
+* The implementation of soil carbon management on cropland refers to a diverse set of  
+* practices. According to IPCC guidelines 2006, they represent "significantly greater  
+* crop residue inputs over medium C input cropping systems due to additional practices,  
+* such as production of high residue yielding crops, use of green manures, cover crops,  
+* improved vegetated fallows, irrigation, frequent use of perennial grasses in annual  
+* crop rotations, but without manure applied."  
+
+* Literature estimates for the costs of these agronomic practices vary widely. Whereas  
+* Smith et al. 2008 estimates the costs of various agronomic practices at around 20  
+* USD06MER (= ~25 USD17MER) per ha, Uludere Aragon et al. 2024 found much higher costs  
+* for the individual practice of cover cropping, around 90-115 USD21MER (= ~80-105  
+* USD17MER) per ha. Uludere Aragon et al. 2024 highlights that changes in production  
+* costs—due to reduced fertilizer use or increased herbicide costs—as well as yield  
+* impacts can either raise or lower net overall farm costs. Given these uncertainties,  
+* we adopt an estimated cost of 65 USD17MER per ha, representing the midpoint between  
+* 25 and 105 USD17MER. Due to the lack of comprehensive cost data across all regions  
+* and the potential for cost changes over time in response to general economic trends,  
+* we apply a uniform cost assumption to avoid introducing large initial biases. Costs  
+* can be changed in the configuration file via `s59_cost_scm_recur` for using other 
+* assumptions.
+
+
 table f59_cratio_landuse(i,climate59_2019,kcr) Ratio of soil carbon relative to potential natural vegetation soil carbon for different landuse (1)
 $ondelim
 $include "./modules/59_som/cellpool_jan23/input/f59_ch5_F_LU_2019reg.cs3"

modules/59_som/cellpool_jan23/realization.gms

@@ -13,7 +13,11 @@
 *' This approach also accounts for the temporal dimension of soil organic carbon change,
 *' since it assumes a gradual step of 15% in the direction of the new equilibrium soil
 *' organic carbon pool each year. Stock change factors tracks crop types as well as
-*' management (e.g. irrigation) and input differences on cropland.
+*' management (e.g. irrigation) and input differences on cropland. 
+*' Dedicated soil carbon management can be switched on for a share of cropland,  
+*' characterized by a higher input factor, which according to the IPCC guidelines  
+*' reflects improved agronomic practices. Target shares are set exogenously and  
+*' are phased in over time.  
 
 *' @limitations It is assumed that pastures and rangelandes as well as managed forests
 *' do not change in soil carbon compared to the natural reference state. Moreover only