Regional target algorithm refactoring

main.gms

@@ -1605,21 +1605,30 @@ $setglobal c_SSP_forcing_adjust  forcing_SSP2   !! def = forcing_SSP2  !! regexp
 $setGlobal cm_regiExoPrice  off    !! def = off
 *** cm_regiExoPrice_fromFile "set exogenous co2 tax path for specific regions from another run, require regipol module to be set to regiCarbonPrice (e.g. "PathToGDX.gdx")"
 $setGlobal cm_regiExoPrice_fromFile  off    !! def = off
-*** cm_emiMktTarget "set a budget or year emission target, for all (all) or specific emission markets (ETS, ESD or other), and specific regions (e.g. DEU) or region groups (e.g. EU27)"
+*** cm_emiMktTarget "set a budget or year emission target, for all (all) or specific emission markets (ETS, ESR or other), and specific regions (e.g. DEU) or region groups (e.g. EU27)"
+***   Format: '<startYear>.<targetYear>.<region>.<market>.<year|budget>.<metric> <value>' [GtCO2 or GtCO2eq], comma separated.
 ***   Example on how to use:
 ***     cm_emiMktTarget = '2020.2050.EU27_regi.all.budget.netGHG_noBunkers 72, 2020.2050.DEU.all.year.netGHG_noBunkers 0.1'
 ***     sets a 72 GtCO2eq budget target for European 27 countries (EU27_regi), for all GHG emissions excluding bunkers between 2020 and 2050; and a 100 MtCO2 CO2eq emission target for the year 2050, for Germany"
 ***     cm_emiMktTarget = 'nzero'
 ***     loads hard-coded options for regional target scenarios defined in the module '47_regipol/regiCarbonPrice' declarations file.
 ***     The 'nzero' scenario applies declared net-zero targets for countries explicitly handled by the model (DEU, CHA, USA, IND, JPN, UKI, FRA and EU27_regi)
 ***     Requires regiCarbonPrice realization in regipol module
+***   Full documentation of the targets and of the carbon price convergence algorithm: tutorials/19_RegionalEmissionTargets.md
 $setGlobal cm_emiMktTarget  off    !! def = off
 *** Tolerance for regipol emission target deviations convergence.
 *** For budget targets the tolerance is measured relative to the target value. For year targets the tolerance is relative to 2005 emissions.
 ***   def = GLO 0.01, i.e. regipol emission targets must be met within 1% of target deviation
+***   Note the Nash iteration itself wobbles by roughly +-1%, so a tolerance far below 1% is asking for less than the noise.
 ***   Example on how to use:
 ***      cm_emiMktTarget_tolerance = 'GLO 0.004, DEU 0.01'. All regional emission targets will be considered converged if they have at most 0.4% of the target deviation, except for Germany that requires 1%.
 $setGlobal cm_emiMktTarget_tolerance  GLO 0.01    !! def = GLO 0.01
+*** cm_slopeParam "overwrite default values of the module 47 regional-target convergence constants (see p47_slopeParam in regiCarbonPrice/datainput.gms and tutorials/19_RegionalEmissionTargets.md section 1.3)"
+***   (off): use the default values set in the regiCarbonPrice datainput.gms
+***   otherwise: a list of slopeParam elements with the value to overwrite (only the listed ones change), e.g.
+***     cm_slopeParam = 'maxPrice 10000, reopenMax 5, enterFrac 0.8'
+***   To switch a knob OFF use a negligible value (1e-9), not 0: GAMS drops zero records, so 0 reads as "not listed".
+$setGlobal cm_slopeParam  off    !! def = off
 *** cm_scaleDemand - Rescaling factor on final energy and usable energy demand, for selected regions and over a phase-in window.
 *** Requires re-calibration in order to work.
 ***   Example on how to use:

modules/47_regipol/module.gms

@@ -13,21 +13,17 @@
 *'
 *'               The `regiCarbonPrice` realization has two purposes. First, it allows to determine region specific year or budget targets for CO2 or GHG emissions.
 *'               Second, it comprises region-specific adjustments that are always active in this realization and policies that can be activated by specific switches (see modules/47_regipol/regiCarbonPrice/bounds.gms).
-*'               On the emissions targets: Emissions targets can be activated via the switch cm_emiMktTarget and there are number of options that can be chosen to specify them
-*'               like the type of target (annual target or budget), the target year, the regions the target should be applied to,
-*'               the emissions metric (CO2, GHG, CO2 excl. bunkers/LULUCF etc.) and the emissions market (all, ETS, ESR). For example, setting cm_emiMktTarget to
-*'               "2020.2030.EU27_regi.all.year.netGHG_noLULUCF_noBunkers 3.16, 2035.2050.EU27_regi.all.year.netCO2 0.001" will apply two emissions targets to the region group "EU27_regi"
-*'               which consists of all model regions in the EU27 (for the definition of region groups, please see definition of the set regi_group): The first is a target of 3.16 GtCO2eq/yr annual ("year") emissions by 2030
-*'               in the metric of net greenhouse gas emissions without LULUCF and bunkers ("netGHG_noLULUCF_noBunkers", for definition of emissions metrics see modules/47_regipol/regiCarbonPrice/postsolve.gms)
-*'               for all emissions markets ("all"). The second defines a target of 1 Mt CO2/yr annual ("year") emissions by 2050 in the metric of net CO2 emissions ("netCO2") for all emissions markets ("all").
-*'               For details on the options please see the description of the switch.
-*'               When an emissions target is set via this switch, the carbon price in the target years and regions, to which it is applied, is adjusted over nash iterations in REMIND
-*'               until the desired emissions target is reached within a certain margin of tolerance defined by cm_emiMktTarget_tolerance. Note that also multiple emissions targets can be specified for
-*'               different years (e.g. the EU's 2030 and 2050 targets). The carbon price trajectory up to the target years are linear and the carbon price
-*'               is assumed to still increase linearly at a small rate after the last target year. Please check the parameter pm_emiMktTarget_dev_iter to see the emissions target convergence over iterations.
-*'               Note that these regional emissions targets of the module only overwrite the carbon price trajectory for the regions they are applied to, while the other regions keep the carbon price trajectories
-*'               that are adjusted in other parts of the model, in particular, from the global emissions target adjustment.
-*'               This means that these regional targets come on top of the global emissions target that REMIND aims to achieve.
+*'               On the emissions targets: activated via `cm_emiMktTarget`, which takes one or more targets of the form
+*'               `<startYear>.<targetYear>.<region>.<market>.<year|budget>.<metric> <value>`, e.g.
+*'               "2020.2030.EU27_regi.all.year.netGHG_noLULUCF_noBunkers 3.16" for a 3.16 GtCO2eq/yr EU27 target in 2030 covering all
+*'               emission markets. Targets may be annual or cumulative budgets, apply to a region or a region group, to all markets or to
+*'               ETS/ESR/other alone, and use any of the emission metrics in the emi_type_47 set (see regiCarbonPrice/postsolve.gms).
+*'               When a target is set, the carbon price of the affected regions and years is adjusted over the nash iterations until the
+*'               emissions land within `cm_emiMktTarget_tolerance` of the target. Several target years per region are solved sequentially.
+*'               These regional targets OVERRIDE the carbon price for their regions only - other regions keep the price they get from the
+*'               global emissions target - so they come on top of it. `pm_emiMktTarget_dev_iter` is the per-iteration deviation to inspect.
+*'               How the convergence algorithm works, every case it handles, all of its parameters and how to diagnose a run:
+*'               tutorials/19_RegionalEmissionTargets.md
 *'               On the regional bounds and adjustments: In the bounds file, there are a number of regionally hard-coded bounds to the model that aim to improve the representation of specific regions in REMIND.
 *'               They come on top of the bounds in the core of REMIND. The difference is that core defines bounds for all regions, while in this module region-specific adjustments are made which have not yet been generalized to all regions
 *'               and are not activated outside of the realization "regiCarbonPrice".

modules/47_regipol/none/not_used.txt

@@ -85,3 +85,4 @@ pm_emiLULUCF_GrassiShift,input,not needed
 vm_co2CCS,input,not needed
 cm_implicitPriceTarget_tolerance,input,not needed
 cm_implicitPePriceTarget_tolerance,input,not needed
+cm_iteration_max,input,not needed

modules/47_regipol/regiCarbonPrice/datainput.gms

@@ -19,10 +19,41 @@ pm_emiMktTarget_dev(ttot,ttot2,ext_regi,emiMktExt) = 0;
 ***--------------------------------------------------
 $IFTHEN.emiMkt not "%cm_emiMktTarget%" == "off" 
 
+*** Initialize carbon price convergence algorithm constants.
+*** slope fit and step size
+p47_slopeParam("maxWindow")=8; p47_slopeParam("minPriceSpread")=1e-2; p47_slopeParam("minR2")=0.5; p47_slopeParam("maxSteep")=5; p47_slopeParam("degenerateThreshold")=1e-2; p47_slopeParam("rescaleCapLo")=0.5; p47_slopeParam("rescaleCapHi")=2;
+*** convergence bands
+p47_slopeParam("enterFrac")=0.75; p47_slopeParam("aimMaxTries")=3; p47_slopeParam("exitFrac")=1.0; p47_slopeParam("persist")=2; p47_slopeParam("priceEps")=0;
+*** deviation normalisation and price ceiling
+p47_slopeParam("budgetDenomFloorFrac")=1e-2; p47_slopeParam("maxPrice")=0;
+*** give-up stops
+p47_slopeParam("noiseFloorMaxDev")=0.02; p47_slopeParam("noiseFloorBandWidth")=0.01; p47_slopeParam("noiseFloorBandWidthRel")=15; p47_slopeParam("noiseFloorRollback")=1; p47_slopeParam("parkedStop")=1; p47_slopeParam("infeasEmiTol")=5e-3; 
+p47_slopeParam("infeasStallFrac")=0.9; p47_slopeParam("divergeFactor")=10; p47_slopeParam("divergeMinBest")=1.0; p47_slopeParam("divergeBrakeMax")=2;
+*** re-open parameters
+p47_slopeParam("reopenMaxDev")=0.1; p47_slopeParam("reopenMax")=3; p47_slopeParam("reopenStepCap")=0.05; p47_slopeParam("reopenRefresh")=24;
+*** step bound for the squareDev fallbacks
+p47_slopeParam("fallbackStepFactor")=2; p47_slopeParam("fallbackStepFloor")=0.05;
+*** price rollback on freeze
+p47_slopeParam("rollbackBestFrac")=0.5; p47_slopeParam("rollbackMaxAge")=8; p47_slopeParam("rollbackVerify")=1;
+*** progressive oscillation dampening
+p47_slopeParam("dampFlipMin")=2; p47_slopeParam("dampProgFactor")=0.6; p47_slopeParam("dampFloor")=0.1;
+*** optional overwrite of individual constants from the scenario config, e.g. cm_slopeParam = 'maxPrice 10000, reopenMax 5'.
+$if not "%cm_slopeParam%" == "off"  parameter p_new_slopeParam(slopeParam) "slope/convergence parameters overwritten via cm_slopeParam" / %cm_slopeParam% /;
+$if not "%cm_slopeParam%" == "off"  p47_slopeParam(slopeParam)$p_new_slopeParam(slopeParam) = p_new_slopeParam(slopeParam);
+
+*** initialise the state parameters
+p47_targetState(targetState,ttot,ttot2,ext_regi,emiMktExt) = 0;
+p47_emiMktRefBudget(ttot,ttot2,ext_regi,emiMktExt) = 0;
+p47_targetMet(ttot,ext_regi)                    = 0;
+p47_allTargetsMet(ext_regi)                     = 0;
+p47_allTargetsFrozen(ext_regi)                  = 0;
+p47_unmetNoGiveUp(ext_regi)                     = 0;
+p47_currentConvergence_iter(iteration,ttot,ext_regi) = 0;
+
 *** Auxiliar parameters based on emission targets information
   loop((ttot,ttot2,ext_regi,emiMktExt,target_type_47,emi_type_47)$pm_emiMktTarget(ttot,ttot2,ext_regi,emiMktExt,target_type_47,emi_type_47), !!calculated sets that depends on data parameter
-    regiEmiMktTarget(ext_regi) = yes; !! assigning values to set containing extended regions that have regional emission targets  
-    regiANDperiodEmiMktTarget_47(ttot2,ext_regi) = yes; !! assigning values to set containing extended regions and terminal years of regional emission targets  
+    regiEmiMktTarget(ext_regi) = yes; !! assigning values to set containing extended regions that have regional emission targets
+    regiANDperiodEmiMktTarget_47(ttot2,ext_regi) = yes; !! assigning values to set containing extended regions and terminal years of regional emission targets
   );
 
 *** Calculating set containing regions that should be controlled by a given regional emission target. 
@@ -46,7 +77,6 @@ $IFTHEN.emiMkt not "%cm_emiMktTarget%" == "off"
       break$(p47_firstTargetYear(ext_regi));
     );
   );
-
 *** Assigning convergence tolerance to active regional targets
   parameter f47_emiMktTarget_tolerance(ext_regi) "tolerance for regipol emission target deviations convergence [#]" / %cm_emiMktTarget_tolerance% /;
   pm_emiMktTarget_tolerance(ext_regi)$(regiEmiMktTarget(ext_regi)) = 0.01; !! if no value is assigned to GLO, the default devation tolerance is set to 1%
@@ -75,7 +105,6 @@ p47_taxemiMkt_init(ttot,regi,emiMkt)$(p47_taxCO2eq_ref(ttot,regi) and (NOT(p47_t
       );
     );
   );
-
 *** if there is a European regional target, overwrite historical prices for Europe if the historical years are free in the cm_emiMktTarget run. 
 *** in this case, historical prices will reflect the ETS market observed prices instead of the values defined pm_taxCO2eq
   loop(ext_regi$regiEmiMktTarget(ext_regi),