From 74ed9a03faf1371d0e3c1d5b0f598c4b7bf81071 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Tue, 21 May 2024 12:30:17 +0200
Subject: [PATCH 1/7] refactor selfsuff_reduced

---
 .../selfsuff_reduced/declarations.gms         |  2 ++
 .../21_trade/selfsuff_reduced/equations.gms   | 24 +++++++++++--------
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/modules/21_trade/selfsuff_reduced/declarations.gms b/modules/21_trade/selfsuff_reduced/declarations.gms
index f6ccffef43..c139fea5dd 100644
--- a/modules/21_trade/selfsuff_reduced/declarations.gms
+++ b/modules/21_trade/selfsuff_reduced/declarations.gms
@@ -15,6 +15,7 @@ parameters
 positive variables
  v21_excess_dem(k_trade)                 Global excess demand (mio. tDM per yr)
  v21_excess_prod(h,k_trade)              Superregional excess production (mio. tDM per yr)
+ v21_prod_baseline(h,k_trade)            Superregional production baseline value (mio. tDM per yr)
  vm_cost_trade(i)                        Regional  trade costs (mio. USD05MER per yr)
  v21_cost_trade_reg(h,k_trade)           Superregional trade costs for each tradable commodity (mio. USD05MER per yr)
  v21_import_for_feasibility(h,k_trade)   Additional imports to maintain feasibility (mio. tDM per yr)
@@ -23,6 +24,7 @@ positive variables
 equations
  q21_trade_glo(k_trade)                  Global production constraint (mio. tDM per yr)
  q21_notrade(h,k_notrade)                Superregional production constraint of non-tradable commodities (mio. tDM per yr)
+ q21_prod_baseline(h,k_trade)            Superregional production baseline value (mio. tDM per yr)
  q21_trade_reg(h,k_trade)                Superregional trade balances i.e. minimum self-sufficiency ratio (1)
  q21_trade_reg_up(h,k_trade)             Superregional trade balances i.e. maximum self-sufficiency ratio (1)
  q21_excess_dem(k_trade)                 Global excess demand (mio. tDM per yr)
diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index e32369522a..2096f16ecb 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -24,26 +24,30 @@
 *' If the trade balance reduction equals 1 (`f21_self_suff(ct,i2,k_trade) = 1`), all demand enters the self-sufficiency pool.
 *' If it equals 0, all demand enters the comparative advantage pool.
 
+*' Baseline value for a corridor in which the superregional production
+*' can move freely based on comparative advantage.
+
+ q21_prod_baseline(h2,k_trade).. 
+ v21_prod_baseline(h2,k_trade) =e= 
+ (sum(supreg(h2,i2),vm_supply(i2,k_trade)) + v21_excess_prod(h2,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,f21_self_suff(ct,h2,k_trade) < 1));
+
 *' 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_prod_baseline(h2,k_trade)
+ * 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));
+ v21_prod_baseline(h2,k_trade)
+ / 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.

From 4c08628fc5fd05249e3fa379249a8e50da4e0d3e Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Tue, 21 May 2024 14:28:16 +0200
Subject: [PATCH 2/7] added changelog entry, improved comments

---
 CHANGELOG.md                                    |  1 +
 modules/21_trade/selfsuff_reduced/equations.gms | 14 ++++++++------
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4dcc35db1a..4031bd43cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +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
 - **22_land_conservation and default.cfg** Added options for baseline protection
 - **15_food, default.cfg and scenario_config.csv** changed fader setup and introduced new switches for specifying food substitution scenarios and exogeneous food intake scenarios
 - **70_livestock, default.cfg and scenario_config.csv** changed fader setup and introduced new switches for specifying feed substitution with SCP scenarios
diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index 2096f16ecb..50a09eda24 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -12,19 +12,21 @@
  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 indicate the superregional trade constraint for the self-sufficiency pool.
+*' The share of superregional 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.
 *' If it equals 0, all demand enters the comparative advantage pool.
 
-*' Baseline value for a corridor in which the superregional production
+*'
+*' The below equation defines the baseline value for a corridor in which the superregional production
 *' can move freely based on comparative advantage.
 
  q21_prod_baseline(h2,k_trade).. 
@@ -34,7 +36,7 @@
  + (sum(supreg(h2,i2),vm_supply(i2,k_trade)) * sum(ct,f21_self_suff(ct,h2,k_trade)))
  $(sum(ct,f21_self_suff(ct,h2,k_trade) < 1));
 
-*' Lower bound for production.
+*' Lower bound of corridor for production.
 
  q21_trade_reg(h2,k_trade)..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =g=
@@ -42,7 +44,7 @@
  * sum(ct,i21_trade_bal_reduction(ct,k_trade))
  - v21_import_for_feasibility(h2,k_trade);
 
-*' Upper bound for production.
+*' Upper bound of corridor for production.
 
  q21_trade_reg_up(h2,k_trade) ..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =l=

From 996e8e2aac943b4d3333bdebce8da54b80b640c7 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Wed, 22 May 2024 10:56:27 +0200
Subject: [PATCH 3/7] updated documentation the  realization

---
 .../21_trade/selfsuff_reduced/equations.gms   | 27 ++++++++--------
 .../21_trade/selfsuff_reduced/realization.gms | 31 +++++++++++++------
 2 files changed, 35 insertions(+), 23 deletions(-)

diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index 50a09eda24..e3be98033a 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -6,7 +6,7 @@
 *** |  Contact: magpie@pik-potsdam.de
 
 *' @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)..
@@ -18,16 +18,15 @@
  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 equations indicate the superregional trade constraint for the self-sufficiency pool.
-*' The share of superregional 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.
 
 *'
-*' The below equation defines the baseline value for a corridor in which the superregional production
-*' can move freely based on comparative advantage.
+*' The below equation defines the baseline value for the production band.
 
  q21_prod_baseline(h2,k_trade).. 
  v21_prod_baseline(h2,k_trade) =e= 
@@ -36,7 +35,7 @@
  + (sum(supreg(h2,i2),vm_supply(i2,k_trade)) * sum(ct,f21_self_suff(ct,h2,k_trade)))
  $(sum(ct,f21_self_suff(ct,h2,k_trade) < 1));
 
-*' Lower bound of corridor for production.
+*' Lower bound for production.
 
  q21_trade_reg(h2,k_trade)..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =g=
@@ -44,7 +43,7 @@
  * sum(ct,i21_trade_bal_reduction(ct,k_trade))
  - v21_import_for_feasibility(h2,k_trade);
 
-*' Upper bound of corridor for production.
+*' Upper bound for production.
 
  q21_trade_reg_up(h2,k_trade) ..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =l=
@@ -52,7 +51,7 @@
  / 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=
@@ -60,20 +59,22 @@
  $(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].
+*' 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 regions.
 
  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 region 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));
diff --git a/modules/21_trade/selfsuff_reduced/realization.gms b/modules/21_trade/selfsuff_reduced/realization.gms
index 1e1a214358..a247a6c0f2 100644
--- a/modules/21_trade/selfsuff_reduced/realization.gms
+++ b/modules/21_trade/selfsuff_reduced/realization.gms
@@ -5,16 +5,27 @@
 *** |  MAgPIE License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: magpie@pik-potsdam.de
 
-*' @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 each product 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 bounds 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 a bit 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 goods `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, including trade margins and tariffs, are considered.
 *'
 *' ![Implementation of trade.](trade_pools.png){ width=100% }
 

From 1ba2f7e65fa797f5416f3e1c5819ee4a087de952 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Fri, 24 May 2024 15:41:01 +0200
Subject: [PATCH 4/7] use macro instead of new variable

---
 core/macros.gms                               |  7 +++++++
 .../selfsuff_reduced/declarations.gms         |  2 --
 .../21_trade/selfsuff_reduced/equations.gms   | 20 +++++--------------
 3 files changed, 12 insertions(+), 17 deletions(-)

diff --git a/core/macros.gms b/core/macros.gms
index 0103e94c73..91e59050a5 100644
--- a/core/macros.gms
+++ b/core/macros.gms
@@ -114,3 +114,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 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)))
\ No newline at end of file
diff --git a/modules/21_trade/selfsuff_reduced/declarations.gms b/modules/21_trade/selfsuff_reduced/declarations.gms
index c139fea5dd..f6ccffef43 100644
--- a/modules/21_trade/selfsuff_reduced/declarations.gms
+++ b/modules/21_trade/selfsuff_reduced/declarations.gms
@@ -15,7 +15,6 @@ parameters
 positive variables
  v21_excess_dem(k_trade)                 Global excess demand (mio. tDM per yr)
  v21_excess_prod(h,k_trade)              Superregional excess production (mio. tDM per yr)
- v21_prod_baseline(h,k_trade)            Superregional production baseline value (mio. tDM per yr)
  vm_cost_trade(i)                        Regional  trade costs (mio. USD05MER per yr)
  v21_cost_trade_reg(h,k_trade)           Superregional trade costs for each tradable commodity (mio. USD05MER per yr)
  v21_import_for_feasibility(h,k_trade)   Additional imports to maintain feasibility (mio. tDM per yr)
@@ -24,7 +23,6 @@ positive variables
 equations
  q21_trade_glo(k_trade)                  Global production constraint (mio. tDM per yr)
  q21_notrade(h,k_notrade)                Superregional production constraint of non-tradable commodities (mio. tDM per yr)
- q21_prod_baseline(h,k_trade)            Superregional production baseline value (mio. tDM per yr)
  q21_trade_reg(h,k_trade)                Superregional trade balances i.e. minimum self-sufficiency ratio (1)
  q21_trade_reg_up(h,k_trade)             Superregional trade balances i.e. maximum self-sufficiency ratio (1)
  q21_excess_dem(k_trade)                 Global excess demand (mio. tDM per yr)
diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index e3be98033a..18798e62c6 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -25,30 +25,20 @@
 *' [@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.
 
-*'
-*' The below equation defines the baseline value for the production band.
-
- q21_prod_baseline(h2,k_trade).. 
- v21_prod_baseline(h2,k_trade) =e= 
- (sum(supreg(h2,i2),vm_supply(i2,k_trade)) + v21_excess_prod(h2,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,f21_self_suff(ct,h2,k_trade) < 1));
-
 *' Lower bound for production.
 
  q21_trade_reg(h2,k_trade)..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =g=
- v21_prod_baseline(h2,k_trade)
- * sum(ct,i21_trade_bal_reduction(ct,k_trade))
- - v21_import_for_feasibility(h2,k_trade);
+  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=
- v21_prod_baseline(h2,k_trade)
- / sum(ct,i21_trade_bal_reduction(ct,k_trade));
+  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 superregions.

From 20a966f04d740e85080dfd632d6dab6fc886d4b7 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Fri, 24 May 2024 16:09:03 +0200
Subject: [PATCH 5/7] minor updates in documentation

---
 modules/21_trade/selfsuff_reduced/equations.gms   | 5 +++--
 modules/21_trade/selfsuff_reduced/realization.gms | 4 ++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index 18798e62c6..e02fe74a6b 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -24,6 +24,7 @@
 *' determined by a trade balance reduction factor for each commodity  `i21_trade_bal_reduction(ct,k_trade)`
 *' [@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 `baseline_production` is a macro defined in core/macros.gms.
 
 *' Lower bound for production.
 
@@ -50,7 +51,7 @@
  + sum(ct,f21_trade_balanceflow(ct,k_trade)) + sum(h2, v21_import_for_feasibility(h2,k_trade));
 
 *' 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 regions.
+*' 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=
@@ -64,7 +65,7 @@
  *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;
 
-* Superregional 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));
diff --git a/modules/21_trade/selfsuff_reduced/realization.gms b/modules/21_trade/selfsuff_reduced/realization.gms
index a247a6c0f2..b44e087013 100644
--- a/modules/21_trade/selfsuff_reduced/realization.gms
+++ b/modules/21_trade/selfsuff_reduced/realization.gms
@@ -14,12 +14,12 @@
 *' 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 bounds of the production band. 
+*' 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 a bit 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 goods `k_trade` is met by domestic production.
+*' 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 

From a2990871f86893b9093e60fc7341dd807e148f73 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Mon, 17 Jun 2024 09:04:44 +0200
Subject: [PATCH 6/7] rephrased and corrected module documentation

---
 core/macros.gms                                   | 2 +-
 modules/21_trade/selfsuff_reduced/realization.gms | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/core/macros.gms b/core/macros.gms
index 91e59050a5..1f91732a92 100644
--- a/core/macros.gms
+++ b/core/macros.gms
@@ -120,4 +120,4 @@ $macro 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)))
\ No newline at end of file
+       $((sum(ct,self_suff(ct,h2,k_trade)) < 1)))
diff --git a/modules/21_trade/selfsuff_reduced/realization.gms b/modules/21_trade/selfsuff_reduced/realization.gms
index b44e087013..99bb7c06ab 100644
--- a/modules/21_trade/selfsuff_reduced/realization.gms
+++ b/modules/21_trade/selfsuff_reduced/realization.gms
@@ -6,7 +6,7 @@
 *** |  Contact: magpie@pik-potsdam.de
 
 *' @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 each product in the superregions. 
+*' 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.
@@ -16,7 +16,7 @@
 *' 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 a bit by the upper bounds of the production band.
+*' 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.
@@ -25,7 +25,7 @@
 *' The superregional export shares `f21_exp_shr` distribute the total excess demand of the importing superregions 
 *' to the exporting superregions.
 *' 
-*' Trade costs, including trade margins and tariffs, are considered.
+*' Trade costs are the sum of trade margins (international transport costs) and trade tariffs.
 *'
 *' ![Implementation of trade.](trade_pools.png){ width=100% }
 

From f0cee84304cd0968e2cc38959c4d306c64f7f345 Mon Sep 17 00:00:00 2001
From: David Hoetten <davidho@pik-potsdam.de>
Date: Mon, 17 Jun 2024 09:15:58 +0200
Subject: [PATCH 7/7] renamed macro to comply with naming convention

---
 core/macros.gms                                 | 2 +-
 modules/21_trade/selfsuff_reduced/equations.gms | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/core/macros.gms b/core/macros.gms
index 1f91732a92..2ee55d7c47 100644
--- a/core/macros.gms
+++ b/core/macros.gms
@@ -116,7 +116,7 @@ $macro m58_LandLeft(pclandFull,setFull,vland,pcland) \
      - sum(manPeat58_alias$(sameas(manPeat58_alias,manPeat58)),pcland(j2,manPeat58_alias)))
 
 * macro for trade module
-$macro baseline_production(supply, excess_prod, self_suff) \
+$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))) \
diff --git a/modules/21_trade/selfsuff_reduced/equations.gms b/modules/21_trade/selfsuff_reduced/equations.gms
index e02fe74a6b..ce789e0cc0 100644
--- a/modules/21_trade/selfsuff_reduced/equations.gms
+++ b/modules/21_trade/selfsuff_reduced/equations.gms
@@ -24,13 +24,13 @@
 *' determined by a trade balance reduction factor for each commodity  `i21_trade_bal_reduction(ct,k_trade)`
 *' [@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 `baseline_production` is a macro defined in core/macros.gms.
+*' 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=
-  baseline_production(vm_supply, v21_excess_prod, f21_self_suff)
+  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);
 
@@ -38,7 +38,7 @@
 
  q21_trade_reg_up(h2,k_trade) ..
  sum(supreg(h2,i2),vm_prod_reg(i2,k_trade)) =l=
-  baseline_production(vm_supply, v21_excess_prod, f21_self_suff)
+  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