add documentation for the module 41_emicapregi (done by Marian)

modules/41_emicapregi/AbilityToPay/realization.gms

@@ -6,6 +6,9 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/AbilityToPay.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the ability to pay principle  
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/AbilityToPay/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/AbilityToPay/datainput.gms"

modules/41_emicapregi/CandC/datainput.gms

@@ -15,14 +15,6 @@ Execute_Loadpoint "input_ref" p41_co2eq = vm_co2eq.l;
 p41_shEmi2005(regi) = p41_co2eq("2005",regi) / sum(regi2, p41_co2eq("2005",regi2) );
 display p41_shEmi2005;
 
-*LB* safe formulation of c_polscen = 11
-$ontext
-***  contraction & convergence (reference year 2020)  +++++++++
-        p41_lambda(tall) $(tall.val<2050) = (tall.val-2020) / 30;
-        p41_lambda(tall) $(tall.val>2049) = 1;
-$offtext
-
-*gl* calculate share of global emissions according to different burden sharing rules
      pm_shPerm(t,regi) =  p41_lambda(t) * pm_pop(t,regi) / sum(regi2,pm_pop(t,regi2))
          + (1 - p41_lambda(t)) * p41_shEmi2005(regi) / sum(regi2, p41_shEmi2005(regi2));
 *** EOF ./modules/41_emicapregi/CandC/datainput.gms

modules/41_emicapregi/CandC/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/CandC.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the contraction and convergence 
+*' rule (transition towards equal per capita allocation; with reference years 2005 and 2050)
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/CandC/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/CandC/datainput.gms"

modules/41_emicapregi/GDPint/datainput.gms

@@ -5,7 +5,8 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/GDPint/datainput.gms
-*gl* calculate share of global emissions according to different burden sharing rules
+
+*** calculate share of global emissions 
      pm_shPerm(t,regi)  =  pm_gdp_gdx(t,regi) / sum(regi2, pm_gdp_gdx(t,regi2));
 
 

modules/41_emicapregi/GDPint/realization.gms

@@ -6,6 +6,9 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/GDPint.gms
 
+*' @description
+*' Emission caps/permits are allocated according to GDP intensity
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/GDPint/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/GDPint/datainput.gms"

modules/41_emicapregi/POPint/datainput.gms

@@ -5,8 +5,8 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/POPint/datainput.gms
-*gl* calculate share of global emissions according to different burden sharing rules
-*ML* cumulated POP shares
+
+*** calculate share of global emissions 
      pm_shPerm(t,regi)  =  sum(t2, pm_pop(t2,regi))/sum((t2,regi2),pm_pop(t2,regi2));
 
 *** EOF ./modules/41_emicapregi/POPint/datainput.gms

modules/41_emicapregi/POPint/realization.gms

@@ -6,6 +6,11 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/POPint.gms
 
+*' @description
+*' Emission caps/permits are allocated according to each region's share on
+*' cumulated population 
+*' 
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/POPint/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/POPint/datainput.gms"

modules/41_emicapregi/PerCapitaConvergence/datainput.gms

@@ -6,7 +6,7 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/PerCapitaConvergence/datainput.gms
 
-***   contraction & convergence (reference year 2005)  +++++++++
+***   contraction & convergence (reference year 2020)  +++++++++
 p41_convergenceyear = 2050;
 p41_lambda(tall) $(tall.val < p41_convergenceyear) = (tall.val - 2020) / (p41_convergenceyear-2020);
 p41_lambda(tall) $(tall.val>2049) = 1;
@@ -21,14 +21,7 @@ display p41_shEmi2020;
 *** calculate global emissions pathway in cost-optimal scenario
 pm_emicapglob(ttot) = sum(regi, p41_co2eq(ttot,regi));
 
-*LB* safe formulation of c_polscen = 11
-$ontext
-***  contraction & convergence (reference year 2020)  +++++++++
-        p41_lambda(tall) $(tall.val<2050) = (tall.val-2020) / 30;
-        p41_lambda(tall) $(tall.val>2049) = 1;
-$offtext
-
-*gl* calculate share of global emissions according to different burden sharing rules
+*** calculate share of global emissions 
      pm_shPerm(t,regi) =  p41_lambda(t) * pm_pop(t,regi) / sum(regi2,pm_pop(t,regi2))
          + (1 - p41_lambda(t)) * p41_shEmi2020(regi) / sum(regi2, p41_shEmi2020(regi2));
 

modules/41_emicapregi/PerCapitaConvergence/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/PerCapitaConvergence.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the contraction and convergence 
+*' rule (transition towards equal per capita allocation; with reference years 2020 and 2050)
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/PerCapitaConvergence/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/PerCapitaConvergence/datainput.gms"

modules/41_emicapregi/exog/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/exog.gms
 
+*' @description
+*' Emission caps/permits are allocated from an exogenous emission path that have 
+*' to be provided "manually"
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/exog/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/exog/datainput.gms"

modules/41_emicapregi/module.gms

@@ -6,6 +6,20 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/41_emicapregi.gms
 
+*' @title Regional Emission Caps 
+*'
+*' @description
+*' This module computes reginal emission caps both in absolute terms and as share of global emissions.
+*' In a setting with emissions trading these caps represent allocated permits and permit shares, respectively.
+*' The allocation of caps and permits is based on different burden sharing rules.
+
+*' @limitations
+*' Permit allocation and emissions trading yield less robust results under Nash (decentralized optimization)
+*' compared to Negishi (Social planner optimization).
+
+*' @authors Marian Leimbach, Christoph Bertram
+
+
 *###################### R SECTION START (MODULETYPES) ##########################
 $Ifi "%emicapregi%" == "AbilityToPay" $include "./modules/41_emicapregi/AbilityToPay/realization.gms"
 $Ifi "%emicapregi%" == "CandC" $include "./modules/41_emicapregi/CandC/realization.gms"

modules/41_emicapregi/none/realization.gms

@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/none.gms
 
+*' @description
+*' No allocation of regional emission caps/permits - applies to tax scenarios and 
+*' no-tax scenarios without permit trading  
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/none/datainput.gms"
 $Ifi "%phase%" == "bounds" $include "./modules/41_emicapregi/none/bounds.gms"