Merge pull request #677 from DavidhoPIK/develop_refactor_selfsuff_red…

…uced

Refactor selfsuff reduced module

CHANGELOG.md

@@ -7,7 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### changed
--
+- **21_trade** refactor equations for enhanced readablility and improve documentation
 
 ### added
 - **scripts** added output report `EU_report.R` that uses `EU_report.Rmd`

core/macros.gms

@@ -115,3 +115,10 @@ $macro m58_LandLeft(pclandFull,setFull,vland,pcland) \
     (sum(&&setFull,pclandFull(j2,&&setFull)) \
      - sum(manPeat58_alias$(not sameas(manPeat58_alias,manPeat58)),vland(j2,manPeat58_alias)) \
      - sum(manPeat58_alias$(sameas(manPeat58_alias,manPeat58)),pcland(j2,manPeat58_alias)))
+
+* macro for trade module
+$macro m21_baseline_production(supply, excess_prod, self_suff) \
+    ((sum(supreg(h2,i2),supply(i2,k_trade)) + excess_prod(h2,k_trade)) \
+     $((sum(ct,self_suff(ct,h2,k_trade)) >= 1)) \
+     + (sum(supreg(h2,i2),vm_supply(i2,k_trade)) * sum(ct,self_suff(ct,h2,k_trade))) \
+       $((sum(ct,self_suff(ct,h2,k_trade)) < 1)))

modules/21_trade/selfsuff_reduced/equations.gms

@@ -6,68 +6,66 @@
 *** |  Contact: [email protected]
 
 *' @equations
-*' In the comparative advantage pool, the only active constraint is that the global supply is larger or equal to demand.
+*' In the comparative advantage pool, the main constraint is that the global supply is larger or equal to demand.
 *' This means that production can be freely allocated globally based on comparative advantages.
 
  q21_trade_glo(k_trade)..
   sum(i2 ,vm_prod_reg(i2,k_trade)) =g=
   sum(i2, vm_supply(i2,k_trade)) + sum(ct,f21_trade_balanceflow(ct,k_trade));
+
 *'
-*' For non-tradable commodites, the regional supply should be larger or equal to the regional demand.
+*' For non-tradable commodites, the superregional supply should be larger or equal to the superregional demand.
  q21_notrade(h2,k_notrade)..
   sum(supreg(h2,i2),vm_prod_reg(i2,k_notrade)) =g= sum(supreg(h2,i2), vm_supply(i2,k_notrade));
 
-*' The following equation indicates the regional trade constraint for the self-sufficiency pool.
-*' The share of regional demand that has to be fulfilled through the self-sufficiency pool is
+*'
+*' The following equations define the production band.
+*' The share of demand that has to be fulfilled through the self-sufficiency pool is
 *' determined by a trade balance reduction factor for each commodity  `i21_trade_bal_reduction(ct,k_trade)`
-*' according to the following equations [@schmitz_trading_2012].
-*' If the trade balance reduction equals 1 (`f21_self_suff(ct,i2,k_trade) = 1`), all demand enters the self-sufficiency pool.
+*' [@schmitz_trading_2012]. If the trade balance reduction equals 1, all demand enters the self-sufficiency pool.
 *' If it equals 0, all demand enters the comparative advantage pool.
+*' Note that `m21_baseline_production` is a macro defined in core/macros.gms.
 
 *' Lower bound for production.
 
  q21_trade_reg(h2,k_trade)..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =g=
- ((sum(supreg(h2,i2),vm_supply(i2,k_trade)) + v21_excess_prod(h2,k_trade))
- *sum(ct,i21_trade_bal_reduction(ct,k_trade)))
- $(sum(ct,f21_self_suff(ct,h2,k_trade) >= 1))
- + (sum(supreg(h2,i2),vm_supply(i2,k_trade))*sum(ct,f21_self_suff(ct,h2,k_trade))
- *sum(ct,i21_trade_bal_reduction(ct,k_trade)))
- $(sum(ct,f21_self_suff(ct,h2,k_trade) < 1))
- - v21_import_for_feasibility(h2,k_trade);
+  m21_baseline_production(vm_supply, v21_excess_prod, f21_self_suff)
+  * sum(ct,i21_trade_bal_reduction(ct,k_trade))
+  - v21_import_for_feasibility(h2,k_trade);
 
 *' Upper bound for production.
 
  q21_trade_reg_up(h2,k_trade) ..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =l=
- ((sum(supreg(h2,i2),vm_supply(i2,k_trade)) + v21_excess_prod(h2,k_trade))/sum(ct,i21_trade_bal_reduction(ct,k_trade)))
- $(sum(ct,f21_self_suff(ct,h2,k_trade) >= 1))
- + (sum(supreg(h2,i2),vm_supply(i2,k_trade))*sum(ct,f21_self_suff(ct,h2,k_trade))/sum(ct,i21_trade_bal_reduction(ct,k_trade)))
- $(sum(ct,f21_self_suff(ct,h2,k_trade) < 1));
+  m21_baseline_production(vm_supply, v21_excess_prod, f21_self_suff)
+  / sum(ct,i21_trade_bal_reduction(ct,k_trade));
 
 *' The global excess demand of each tradable good `v21_excess_demad` equals to
-*' the sum over all the imports of importing regions.
+*' the sum over all the imports of importing superregions.
 
  q21_excess_dem(k_trade)..
  v21_excess_dem(k_trade) =g=
  sum(h2, sum(supreg(h2,i2),vm_supply(i2,k_trade))*(1 - sum(ct,f21_self_suff(ct,h2,k_trade)))
  $(sum(ct,f21_self_suff(ct,h2,k_trade)) < 1))
  + sum(ct,f21_trade_balanceflow(ct,k_trade)) + sum(h2, v21_import_for_feasibility(h2,k_trade));
 
-*' Distributing the global excess demand to exporting regions is based on regional export shares [@schmitz_trading_2012].
-*' Export shares are derived from FAO data (see @schmitz_trading_2012 for details). They are 0 for importing regions.
+*' Distributing the global excess demand to exporting superregions is based on export shares [@schmitz_trading_2012].
+*' Export shares are derived from FAO data (see @schmitz_trading_2012 for details). They are 0 for importing superregions.
 
  q21_excess_supply(h2,k_trade)..
  v21_excess_prod(h2,k_trade) =e=
  v21_excess_dem(k_trade)*sum(ct,f21_exp_shr(ct,h2,k_trade));
 
-* Trade costs are associated with exporting regions. They are dependent on net exports, trade margin, and tariffs.
+* Trade costs are associated with exporting superregions. They are dependent on net exports, trade margin, and tariffs.
+
  q21_cost_trade_reg(h2,k_trade)..
  v21_cost_trade_reg(h2,k_trade) =g=
  (i21_trade_margin(h2,k_trade) + i21_trade_tariff(h2,k_trade))
  *sum(supreg(h2,i2), vm_prod_reg(i2,k_trade)-vm_supply(i2,k_trade)) 
  + v21_import_for_feasibility(h2,k_trade) * s21_cost_import;
 
-* Regional trade costs are the costs for each region aggregated over all the tradable commodities.
+* Superregional trade costs are the costs for each superregion aggregated over all the tradable commodities.
+
  q21_cost_trade(h2)..
  sum(supreg(h2,i2),vm_cost_trade(i2)) =e= sum(k_trade,v21_cost_trade_reg(h2,k_trade));

modules/21_trade/selfsuff_reduced/realization.gms

@@ -5,16 +5,27 @@
 *** |  MAgPIE License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: [email protected]
 
-*' @description Within this realization, there are two ways for a region to fulfill
-*' its demand for agricultural products: a self-sufficiency pool based on
-*' historical region specific trade patterns, and a comparative advantage pool
-*' based on most cost-efficient production.
-
-*' In the self-sufficiency pool, regional self-sufficiency ratios `f21_self_suff` defines
-*' how much of the demand of each region `i` for each traded goods `k_trade` has to be met by domestic production.
-*' Self sufficiency ratios smaller than one indicate that the region imports from the world market,
-*' while self-sufficiencies greater than one indicate that the region produces for export. Trade costs,
-*' inlucding trade margins and tariffs, are considered.
+*' @description In this realization trade patterns defined by self-sufficiency ratios and export shares, 
+*' together with regional demands, establish a baseline value for the production of traded products in the superregions. 
+*' Production is then allowed to fluctuate freely within a band around this baseline value, 
+*' only being enforced to maintain the condition of global production exceeding global demand.
+*' The width of the production band is determined by the `i21_trade_bal_reduction` (ptb) factor.
+*'
+*' Effectively, this factor splits the global demand into two pools: The `ptb` share of demand goes 
+*' into a pool for which the origin of products is fixed by the self-sufficiency ratios and export shares.
+*' This "self-sufficiency" pool thus implies minimum production levels in superregions, which are enforced by the 
+*' lower bound of the production band. 
+*' The remaining part of the demand can be allocated more freely based on comparative advantage 
+*' in production of different superregions, though still being constrained by the upper bounds of the production band.
+*'
+*' The superregional self-sufficiency ratios `f21_self_suff` define
+*' how much of the demand of each superregion `h` for each traded good `k_trade` is met by domestic production.
+*' Self-sufficiency ratios smaller than one indicate that the superregion imports from the world market,
+*' while self-sufficiencies greater than one indicate that the superregion produces for export. 
+*' The superregional export shares `f21_exp_shr` distribute the total excess demand of the importing superregions 
+*' to the exporting superregions.
+*' 
+*' Trade costs are the sum of trade margins (international transport costs) and trade tariffs.
 *'
 *' ![Implementation of trade.](trade_pools.png){ width=100% }