Document agricultural costs (26_agCosts).

modules/26_agCosts/costs/datainput.gms

@@ -9,7 +9,10 @@
 
 pm_NXagr(tall,all_regi) = 0;
 
-*** Read total landuse cost (including bioenergy and MAC cost)
+*' **Total agricultural costs (including MAC costs)** 
+*' Total agricultural costs for REMIND standalone runs (not coupled to MAgPIE) are read from a lookup table
+*' dependent of SSP and RCP. The costs have been derived from MAgPIE runs and include bioenergy and MAC costs.
+
 parameter p26_totLUcostLookup(tall,all_regi,all_LU_emi_scen,all_rcp_scen)  "regional total landuse cost"
 /
 $ondelim
@@ -18,7 +21,7 @@ $offdelim
 /
 ;
 
-*DK* In coupled runs overwrite landuse costs from look-up table with actual MAgPIE values.
+*' In coupled runs landuse costs are directly transferred from MAgPIE run instead of reading them from the look-up table.
 $if %cm_MAgPIE_coupling% == "on"  table p26_totLUcost_coupling(tall,all_regi)  "total landuse cost from MAgPIE"
 $if %cm_MAgPIE_coupling% == "on"  $ondelim
 $if %cm_MAgPIE_coupling% == "on"  $include "./modules/26_agCosts/costs/input/p26_totLUcost_coupling.csv";
@@ -26,12 +29,17 @@ $if %cm_MAgPIE_coupling% == "on"  $offdelim
 $if %cm_MAgPIE_coupling% == "on"  ;
 
 *** Total land use costs including MAC costs (either from look-up table for standalone runs or from MAgPIE in coupled runs)
+*' @code
 $if %cm_MAgPIE_coupling% == "off" p26_totLUcosts_withMAC(ttot,regi) = p26_totLUcostLookup(ttot,regi,"%cm_LU_emi_scen%","%cm_rcp_scen%");
 $if %cm_MAgPIE_coupling% == "on"  p26_totLUcosts_withMAC(ttot,regi) = p26_totLUcost_coupling(ttot,regi);
 
-*** Land use emissions MAC cost from MAgPIE
-*** In standalone runs LU MAC costs are calcualted endogenously in REMIND AND they already included in the exogenous total landuse costs (p26_totLUcostLookup). 
-*** Therefore, substract the exact same LU MAC costs again that are already included in the exogenous total landuse costs.
+*' **Land use emissions MAC cost**
+*' In *standalone runs* land use MAC costs are calcualted endogenously in REMIND. Since they are also included 
+*' in the exogenous total landuse costs (p26_totLUcostLookup) they need to besubstracted from these total
+*' landuse costs. In coupled runs the land use MAC is deactivated in REMIND and MAC costs are included in the total land use
+*' costs that are transferred from MAgPIE.
+*' @stop
+
 parameter p26_macCostLuLookup(tall,all_regi,all_LU_emi_scen,all_rcp_scen)  "land use emissions MAC cost from MAgPIE"
 /
 $ondelim
@@ -40,8 +48,9 @@ $offdelim
 /
 ;
 
+*' @code
 *** MAC costs (either from look-up table for standalone runs or zero in coupled runs because MAgPIE's total costs already include MAC costs)
 $if %cm_MAgPIE_coupling% == "off" p26_macCostLu(ttot,regi) = p26_macCostLuLookup(ttot,regi,"%cm_LU_emi_scen%","%cm_rcp_scen%");
 $if %cm_MAgPIE_coupling% == "on"  p26_macCostLu(ttot,regi) = 0;
-
+*' @stop 
 *** EOF ./modules/26_agCosts/costs/datainput.gms

modules/26_agCosts/costs/declarations.gms

@@ -6,10 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/26_agCosts/costs/declarations.gms
 parameter
-pm_totLUcosts(tall,all_regi)           "total landuse costs (agriculture, bioenergy, MAC, etc), in standalone runs MAC costs are substituted by costs from teh REMIND-MAC"
-p26_totLUcosts_withMAC(tall,all_regi)  "total landuse costs including MAC (agriculture, bioenergy, MAC, etc)"
-p26_macCostLu(tall,all_regi)           "Land use emissions MAC cost"
-pm_NXagr(tall,all_regi)                "net agricultural exports"
+pm_totLUcosts(tall,all_regi)           "Total landuse costs (agriculture, bioenergy, MAC, etc). In standalone runs MAC costs are substituted by costs from the endogenous REMIND-MAC [T$US]"
+p26_totLUcosts_withMAC(tall,all_regi)  "Total landuse costs including agricultural MAC costs (agriculture, bioenergy, MAC, etc) [T$US]"
+p26_macCostLu(tall,all_regi)           "Land use emissions MAC cost [T$US]"
+pm_NXagr(tall,all_regi)                "Net agricultural exports"
 ;
 
 *** EOF ./modules/26_agCosts/costs/declarations.gms

modules/26_agCosts/costs/presolve.gms

@@ -5,7 +5,18 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 
-*** Substitude MAC LU costs for stand alone runs by data from REMIND-MAC-LU
-*** in coupled runs the two last components are zero and the original data from MAgPIE are used
-*** For standalone runs dont include mac costs for CO2luc, because they are already implicitly included in p26_totLUcosts_withMAC (and not in p26_macCostLu)
+*' @code
+*' **Total agricultural costs (excluding MAC costs)**
+*' For standalone runs replace exogenous land use MAC cots (p26_macCostLu) with endogenous land use MAC costs (pm_macCost). 
+*' Note: dont include mac costs for CO2luc, because they are already implicitly included in p26_totLUcosts_withMAC (and not in p26_macCostLu).
+*' In coupled runs these two components are zero and the original data from MAgPIE are used.
 pm_totLUcosts(ttot,regi) =  p26_totLUcosts_withMAC(ttot,regi) - p26_macCostLu(ttot,regi) + sum(enty$(emiMacMagpie(enty) AND (NOT emiMacMagpieCO2(enty))), pm_macCost(ttot,regi,enty));
+
+*' **Bioenergy costs**
+*' For standalone and coupled runs costs for biomass production are calculated endogenously (v30_pebiolc_costs). Since they
+*' are also included in the exogenous total landuse costs (p26_totLUcostLookup) they need to be substracted from these total
+*' landuse costs. This is done in the biomass module ([30_biomass]) by calculating them before the main solve as a
+*' parameter (p30_pebiolc_costs_emu_preloop), and during the optimization substracting this parameter from the fuel costs
+*' while including the variable v30_pebiolc_costs.
+
+*' @stop
\ No newline at end of file

modules/26_agCosts/costs/realization.gms

@@ -6,6 +6,12 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/26_agCosts/costs.gms
 
+*' @description
+*' Agricultural production costs in REMIND consist of the following components: actual production costs 
+*' (land conversion, crop cultivation, irrigation, technological change, ...), bioenergy costs, cost for abating
+*' emissions accruing from agricultural activity (marginal abatement costs = MAC cost). 
+
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/26_agCosts/costs/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/26_agCosts/costs/datainput.gms"

modules/26_agCosts/module.gms

@@ -6,6 +6,12 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/26_agCosts/26_agCosts.gms
 
+*' @title Agricultural costs
+*'
+*' @description This module calculates the costs for agricultural production which is exogenous to REMIND.
+*'
+*' @authors Franziska Piontek, David Klein
+
 *###################### R SECTION START (MODULETYPES) ##########################
 $Ifi "%agCosts%" == "costs" $include "./modules/26_agCosts/costs/realization.gms"
 $Ifi "%agCosts%" == "costs_trade" $include "./modules/26_agCosts/costs_trade/realization.gms"