add documentation for the modules 33_CDR and 39_CCU (done by Jessi)

modules/21_tax/on/equations.gms

@@ -63,7 +63,7 @@ v21_taxrevCO2luc(t,regi) =g= ( pm_taxCO2eq(t,regi)  + pm_taxCO2eqSCC(t,regi) + p
                            - p21_taxrevCO2LUC0(t,regi);
 
 ***---------------------------------------------------------------------------
-*'  Calculation of CCS tax: tax rate (defined as fraction(or multiplier) of O&M costs) times sequestration
+*'  Calculation of CCS tax: tax rate (defined as fraction(or multiplier) of O&M costs) times amount of CO2 sequestration
 *'  Documentation of overall tax approach is above at q21_taxrev.
 ***---------------------------------------------------------------------------
 q21_taxrevCCS(t,regi)$(t.val ge max(2010,cm_startyear))..
@@ -74,7 +74,7 @@ v21_taxrevCCS(t,regi)
 	- p21_taxrevCCS0(t,regi);
 
 ***---------------------------------------------------------------------------
-*'  Calculation of net negative emissions tax: tax rate (defined as fraction of carbon price) times negative emissions
+*'  Calculation of net-negative emissions tax: tax rate (defined as fraction of carbon price) times net-negative emissions
 *'  Documentation of overall tax approach is above at q21_taxrev.
 ***---------------------------------------------------------------------------
 q21_taxrevNetNegEmi(t,regi)$(t.val ge max(2010,cm_startyear))..
@@ -82,7 +82,7 @@ v21_taxrevNetNegEmi(t,regi) =g=  cm_frac_NetNegEmi * pm_taxCO2eq(t,regi) * v21_e
                                  - p21_taxrevNetNegEmi0(t,regi);
 
 ***---------------------------------------------------------------------------
-*'  Auxiliary calculation of negative emissions: 
+*'  Auxiliary calculation of net-negative emissions: 
 *'  v21_emiAllco2neg and v21_emiAllco2neg_slack are defined as positive variables
 *'  so as long as vm_emiAll is positive, v21_emiAllco2neg_slack adjusts so that sum is zero
 *'  if vm_emiAll is negative, in order to minimize tax v21_emiAllco2neg_slack becomes zero

modules/33_CDR/DAC/equations.gms

@@ -5,7 +5,11 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/DAC/equations.gms
-*** new default: gas for heat production is with CCS; assume 90% capture rate.
+
+***---------------------------------------------------------------------------
+*'  Calculation of (negative) CO2 emissions from direct air capture. The first part of the equation describes emissions captured from the ambient air, 
+*'  the second part calculates the CO2 captured from the gas used for heat production assuming 90% capture rate.
+***---------------------------------------------------------------------------
 q33_capconst_dac(t,regi)..
 	v33_emiDAC(t,regi)
 	=e=
@@ -13,26 +17,37 @@ q33_capconst_dac(t,regi)..
 	-  (1 / pm_eta_conv(t,regi,"gash2c")) * fm_dataemiglob("pegas","seh2","gash2c","cco2") * vm_otherFEdemand(t,regi,"fegas")
 	;
 
+***---------------------------------------------------------------------------
+*'  Sum of all CDR emissions other than BECCS and afforestation, which are calculated in the core.
+***---------------------------------------------------------------------------
 q33_emicdrregi(t,regi)..
 	vm_emiCdr(t,regi,"co2")
 	=e=
 	v33_emiDAC(t,regi);
 	
-*** fehes is only district heat. Use gas or h2 to generate heat for DAC plants. 
-*** vm_otherFEdemand(t,regi,"fegas") is calculated as the total energy demand for heat minus what is already covered by h2, i.e. vm_otherFEdemand(t,regi,"feh2s") and vice versa.
+***---------------------------------------------------------------------------
+*'  Calculation of energy demand of direct air capture. Heat can be provided by gas or H2; 
+*'  vm_otherFEdemand(t,regi,"fegas") is calculated as the total energy demand for heat minus what is already covered by h2, i.e. vm_otherFEdemand(t,regi,"feh2s") and vice versa.
+***---------------------------------------------------------------------------
 q33_otherFEdemand(t,regi,entyFe)..
     vm_otherFEdemand(t,regi,entyFe)
     =e=
     - vm_emiCdr(t,regi,"co2") * sm_EJ_2_TWa * p33_dac_fedem(entyFe)
     - vm_otherFEdemand(t,regi,"feh2s")$(sameas(entyFe,"fegas")) - vm_otherFEdemand(t,regi,"fegas")$(sameas(entyFe,"feh2s"))
     ;
-	
+
+***---------------------------------------------------------------------------
+*'  Preparation of captured emissions to enter the CCS chain.
+***---------------------------------------------------------------------------	
 q33_ccsbal(t,regi,ccs2te(ccsCo2(enty),enty2,te))..
 	sum(teCCS2rlf(te,rlf), vm_ccs_cdr(t,regi,enty,enty2,te,rlf))
 	=e=
 	-vm_emiCdr(t,regi,"co2")
 	;
 
+***---------------------------------------------------------------------------
+*'  Limit the amount of H2 from biomass to the demand without DAC.
+***---------------------------------------------------------------------------
 q33_H2bio_lim(t,regi,te)..	         
 	vm_prodSE(t,regi,"pebiolc","seh2",te)$pe2se("pebiolc","seh2",te)
 	=l=

modules/33_CDR/DAC/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/DAC.gms
 
+*' @description 
+*' In this realization, direct air capture can be used to remove CO2 from the atmosphere in addition to BECCS and afforestation. Based on Broehm et al. we assume an energy demand of 
+*' 2 GJ/tCO2 electricity and 10 GJ/tCO2 heat which can be met via gas or H2. If gas is used, the resulting CO2 is captured with a capture rate of 90%.
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "sets" $include "./modules/33_CDR/DAC/sets.gms"
 $Ifi "%phase%" == "declarations" $include "./modules/33_CDR/DAC/declarations.gms"

modules/33_CDR/DAC/sets.gms

@@ -7,7 +7,7 @@
 *** SOF ./modules/33_CDR/DAC/sets.gms
 sets
 
-te_dyn33(all_te)  "???"
+te_dyn33(all_te)  "all technologies"
 /
 		dac		"direct air capture"
 /

modules/33_CDR/all/equations.gms

@@ -6,13 +6,19 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/all/equations.gms
 
+***---------------------------------------------------------------------------
+*'  Calculation of the amount of ground rock spread in timestep t.
+***---------------------------------------------------------------------------
 q33_capconst_grindrock(t,regi)..
 	sum(rlf2,sum(rlf, v33_grindrock_onfield(t,regi,rlf,rlf2)))
 	=l=
 	sum(teNoTransform2rlf_dyn33(te,rlf2), vm_capFac(t,regi,"rockgrind") * vm_cap(t,regi,"rockgrind",rlf2))
 	;
 	
-* JeS: timestep in 2060 not yet quite right!  
+***---------------------------------------------------------------------------
+*'  Calculation of the total amount of ground rock on the fields in timestep t. The first part of the equation describes the decay of the rocks added until that time,
+*'  the rest describes the newly added rocks.
+***---------------------------------------------------------------------------
 q33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)$(ttot.val ge max(2010, cm_startyear))..
 	v33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)
 	=e=
@@ -21,6 +27,9 @@ q33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)$(ttot.val ge max(2010, cm_startyea
 	v33_grindrock_onfield(ttot,regi,rlf,rlf2) * (sum(tall $ ((tall.val le ttot.val) $ (tall.val gt (ttot.val-pm_ts(ttot)/2))),exp(-p33_co2_rem_rate(rlf) * (ttot.val-tall.val))))
 ;  
 
+***---------------------------------------------------------------------------
+*'  Calculation of (negative) CO2 emissions from enhanced weathering. 
+***---------------------------------------------------------------------------
 q33_emiEW(t,regi)..
 	v33_emiEW(t,regi)
 	=e=
@@ -29,20 +38,34 @@ q33_emiEW(t,regi)..
 		)
 	;	
 
-*** new default: gas for heat production is with CCS; assume 90% capture rate.	
+***---------------------------------------------------------------------------
+*'  Calculation of (negative) CO2 emissions from direct air capture. The first part of the equation describes emissions captured from the ambient air, 
+*'  the second part calculates the CO2 captured from the gas used for heat production assuming 90% capture rate.
+***---------------------------------------------------------------------------
 q33_capconst_dac(t,regi)..
 	v33_emiDAC(t,regi)
 	=e=
 	-sum(teNoTransform2rlf_dyn33(te,rlf2), vm_capFac(t,regi,"dac") * vm_cap(t,regi,"dac",rlf2))
 	-  (1 / pm_eta_conv(t,regi,"gash2c")) * fm_dataemiglob("pegas","seh2","gash2c","cco2") * vm_otherFEdemand(t,regi,"fegas")	
 	;
-	
+
+***---------------------------------------------------------------------------
+*'  Sum of all CDR emissions other than BECCS and afforestation, which are calculated in the core.
+***---------------------------------------------------------------------------	
 q33_emicdrregi(t,regi)..
 	vm_emiCdr(t,regi,"co2")
 	=e=
 	v33_emiEW(t,regi) + v33_emiDAC(t,regi)
 	;
-	
+
+***---------------------------------------------------------------------------
+*'  Calculation of energy demand of DAC and EW. 
+*'  The first part of the equation describes the electricity demand for grinding, 
+*'  the second part the diesel demand for transportation and spreading on crop fields.
+*'  The third part is DAC electricity demand and the last part is DAC heat demand.
+*'  Heat for DAC can be provided by gas or H2; vm_otherFEdemand(t,regi,"fegas") is calculated as the total 
+*'  DAC energy demand for heat minus what is already covered by h2, i.e. vm_otherFEdemand(t,regi,"feh2s") and vice versa.
+***---------------------------------------------------------------------------	
 q33_otherFEdemand(t,regi,entyFe)..
 	vm_otherFEdemand(t,regi,entyFe)
 	=e=
@@ -52,12 +75,18 @@ q33_otherFEdemand(t,regi,entyFe)..
    - vm_otherFEdemand(t,regi,"feh2s")$(sameas(entyFe,"fegas")) - vm_otherFEdemand(t,regi,"fegas")$(sameas(entyFe,"feh2s"))
 	;	
 	
+***---------------------------------------------------------------------------
+*'  Limit the amount of H2 from biomass to the demand without DAC.
+***---------------------------------------------------------------------------	
 q33_H2bio_lim(t,regi,te)..	         
 	vm_prodSE(t,regi,"pebiolc","seh2",te)$pe2se("pebiolc","seh2",te)
 	=l=
     vm_prodFe(t,regi,"seh2","feh2s","tdh2s") - vm_otherFEdemand(t,regi,"feh2s")
 	;
 
+***---------------------------------------------------------------------------
+*'  O&M costs of EW, consisting of fix costs for mining, grinding and spreading, and transportation costs.
+***---------------------------------------------------------------------------	
 q33_omcosts(t,regi)..
 	vm_omcosts_cdr(t,regi)
 	=e=
@@ -68,18 +97,27 @@ q33_omcosts(t,regi)..
 		)
 	)
 	;
-	
+
+***---------------------------------------------------------------------------
+*'  Limit total amount of ground rock on the fields to regional maximum potentials.
+***---------------------------------------------------------------------------		
 q33_potential(t,regi,rlf)..	
 	sum(rlf2,v33_grindrock_onfield_tot(t,regi,rlf,rlf2))
 	=l=
 	f33_maxProdGradeRegiWeathering(regi,rlf);	
-	
+
+***---------------------------------------------------------------------------
+*'  Preparation of captured emissions to enter the CCS chain.
+***---------------------------------------------------------------------------		
 q33_ccsbal(t,regi,ccs2te(ccsCo2(enty),enty2,te))..
 	sum(teCCS2rlf(te,rlf), vm_ccs_cdr(t,regi,enty,enty2,te,rlf))
 	=e=
 	-v33_emiDAC(t,regi)
 	;	
-  
+
+***---------------------------------------------------------------------------
+*'  An annual limit for the maximum amount of rocks spred [Gt] can be set via cm_LimRock, e.g. due to sustainability concerns.
+***---------------------------------------------------------------------------  
 q33_LimEmiEW(t,regi)..
              sum(rlf,
                   sum(rlf2,v33_grindrock_onfield(t,regi,rlf,rlf2))

modules/33_CDR/all/realization.gms

@@ -6,6 +6,11 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/all.gms
 
+*' @description 
+*' In this realization, direct air capture and enhanced weathering can be used to remove CO2 from the atmosphere in addition to BECCS and afforestation. Based on Broehm et al. we assume an energy demand of 
+*' 2 GJ/tCO2 electricity and 10 GJ/tCO2 heat for DAC which can be met via gas or H2. If gas is used, the resulting CO2 is captured with a capture rate of 90%.
+*' For EW, electricty is needed to grind the rocks and diesel is needed for transportation and spreading on crop fields.
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "sets" $include "./modules/33_CDR/all/sets.gms"
 $Ifi "%phase%" == "declarations" $include "./modules/33_CDR/all/declarations.gms"

modules/33_CDR/all/sets.gms

@@ -7,7 +7,7 @@
 *** SOF ./modules/33_CDR/all/sets.gms
 sets
 
-te_dyn33(all_te)  "???"
+te_dyn33(all_te)  "all technologies"
 /
 		rockgrind		"grinding rock for enhanced weathering"
 		dac		"direct air capture"

modules/33_CDR/module.gms

@@ -6,6 +6,12 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/33_CDR.gms
 
+*' @title CDR
+*'
+*' @description  The 33_CDR module calculates CO2 removed from the atmosphere by options other than BECCS or afforestation, which are calculated in the core.
+*'
+*' @authors Jessica Strefler
+
 *###################### R SECTION START (MODULETYPES) ##########################
 $Ifi "%CDR%" == "DAC" $include "./modules/33_CDR/DAC/realization.gms"
 $Ifi "%CDR%" == "all" $include "./modules/33_CDR/all/realization.gms"

modules/33_CDR/off/realization.gms

@@ -6,6 +6,9 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/off.gms
 
+*' @description 
+*' In this realization, no additional CDR option other than BECCS and afforestation is available.
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/33_CDR/off/declarations.gms"
 $Ifi "%phase%" == "bounds" $include "./modules/33_CDR/off/bounds.gms"

modules/33_CDR/weathering/equations.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/weathering/equations.gms
 
+***---------------------------------------------------------------------------
+*'  Calculation of the energy demand of enhanced weathering. The first part of the equation describes the electricity demand for grinding, 
+*'  the second part the diesel demand for transportation and spreading on crop fields.
+***---------------------------------------------------------------------------
 q33_otherFEdemand(t,regi,entyFe)$(sameas(entyFe,"feels") OR sameas(entyFe,"fedie"))..
 	vm_otherFEdemand(t,regi,entyFe)$(sameas(entyFe,"feels") OR sameas(entyFe,"fedie"))
 	=e=
@@ -13,13 +17,19 @@ q33_otherFEdemand(t,regi,entyFe)$(sameas(entyFe,"feels") OR sameas(entyFe,"fedie
    + sum(rlf$(rlf.val le 2), s33_rockfield_fedem$(sameas(entyFe,"fedie")) * sm_EJ_2_TWa * sum(rlf2,v33_grindrock_onfield(t,regi,rlf,rlf2)))
 	;
 
+***---------------------------------------------------------------------------
+*'  Calculation of the amount of ground rock spread in timestep t.
+***---------------------------------------------------------------------------
 q33_capconst_grindrock(t,regi)..
 	sum(rlf2,sum(rlf$(rlf.val le 2), v33_grindrock_onfield(t,regi,rlf,rlf2)))
 	=l=
 	sum(teNoTransform2rlf_dyn33(te,rlf2), vm_capFac(t,regi,"rockgrind") * vm_cap(t,regi,"rockgrind",rlf2))
 	;
 	
-* JeS: timestep in 2060 not yet quite right!  
+***---------------------------------------------------------------------------
+*'  Calculation of the total amount of ground rock on the fields in timestep t. The first part of the equation describes the decay of the rocks added until that time,
+*'  the rest describes the newly added rocks.
+***---------------------------------------------------------------------------
 q33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)$((ttot.val ge max(2010, cm_startyear))$(rlf.val le 2))..
 	v33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)$(rlf.val le 2)
 	=e=
@@ -28,6 +38,9 @@ q33_grindrock_onfield_tot(ttot,regi,rlf,rlf2)$((ttot.val ge max(2010, cm_startye
 	v33_grindrock_onfield(ttot,regi,rlf,rlf2)$(rlf.val le 2) * (sum(tall $ ((tall.val le ttot.val) $ (tall.val gt (ttot.val-pm_ts(ttot)/2))),exp(-p33_co2_rem_rate(rlf)$(rlf.val le 2) * (ttot.val-tall.val))))
 ;  
 
+***---------------------------------------------------------------------------
+*'  Calculation of (negative) CO2 emissions from enhanced weathering. 
+***---------------------------------------------------------------------------
 q33_emiEW(t,regi)..
 	v33_emiEW(t,regi)
 	=e=
@@ -36,12 +49,18 @@ q33_emiEW(t,regi)..
 	)
 	;
 
+***---------------------------------------------------------------------------
+*'  Sum of all CDR emissions other than BECCS and afforestation, which are calculated in the core.
+***---------------------------------------------------------------------------
 q33_emicdrregi(t,regi)..
 	vm_emiCdr(t,regi,"co2")
 	=e=
 	v33_emiEW(t,regi)
 	;
-	
+
+***---------------------------------------------------------------------------
+*'  O&M costs of EW, consisting of fix costs for mining, grinding and spreading, and transportation costs.
+***---------------------------------------------------------------------------	
 q33_omcosts_onfield(t,regi)..
 	vm_omcosts_cdr(t,regi)
 	=e=
@@ -52,12 +71,18 @@ q33_omcosts_onfield(t,regi)..
 		)
 	)
 	;
-	
+
+***---------------------------------------------------------------------------
+*'  Limit total amount of ground rock on the fields to regional maximum potentials.
+***---------------------------------------------------------------------------	
 q33_potential(t,regi,rlf)$(rlf.val le 2)..	
 	sum(rlf2,v33_grindrock_onfield_tot(t,regi,rlf,rlf2)$(rlf.val le 2))
 	=l=
 	f33_maxProdGradeRegiWeathering(regi,rlf)$(rlf.val le 2);
 
+***---------------------------------------------------------------------------
+*'  An annual limit for the maximum amount of rocks spred [Gt] can be set via cm_LimRock, e.g. due to sustainability concerns.
+***---------------------------------------------------------------------------
 q33_LimEmiEW(t,regi)..
              sum(rlf,
                   sum(rlf2,v33_grindrock_onfield(t,regi,rlf,rlf2))

modules/33_CDR/weathering/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/33_CDR/weathering.gms
 
+*' @description 
+*' In this realization, enhanced weathering of rocks can be used to remove CO2 from the atmosphere in addition to BECCS and afforestation. 
+*' Electricty is needed to grind the rocks and diesel is needed for transportation and spreading on crop fields.
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "sets" $include "./modules/33_CDR/weathering/sets.gms"
 $Ifi "%phase%" == "declarations" $include "./modules/33_CDR/weathering/declarations.gms"

modules/33_CDR/weathering/sets.gms

@@ -7,7 +7,7 @@
 *** SOF ./modules/33_CDR/weathering/sets.gms
 sets
 
-te_dyn33(all_te)   "???"
+te_dyn33(all_te)   "all technologies"
 /
 		rockgrind		"grinding rock for enhanced weathering"
 /

modules/39_CCU/module.gms

@@ -6,6 +6,12 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/39_CCU/39_CCU.gms
 
+*' @title CCU
+*'
+*' @description  The 39_CCU module calculates emissions from synthetic gas and liquids.
+*'
+*' @authors Laura Popin, Jessica Strefler
+
 *####################### R SECTION START (MODULETYPES) ##############################
 $Ifi "%CCU%" == "off" $include "./modules/39_CCU/off/realization.gms"
 $Ifi "%CCU%" == "on" $include "./modules/39_CCU/on/realization.gms"

modules/39_CCU/on/equations.gms

@@ -8,9 +8,8 @@
 
 
 ***---------------------------------------------------------------------------
-*** LP
-*** Managing the C/H ratio in CCU-Technologies
-*** amount of C temporary used in CCU-products in relation to the amount of hydrogen necessary [GtC/y]
+*' Managing the C/H ratio in CCU-Technologies
+*' amount of C temporary used in CCU-products in relation to the amount of hydrogen necessary [GtC/y]
 ***---------------------------------------------------------------------------
 
 q39_emiCCU(t,regi) ..