[ENG-1105] enable transmission (#108)

* Add test otoole data with transmission

* Add WIP transmission schemas

* Add transmission

* Added linear expressions for Trade Capacity

* Updated Linear Expresssions of costs and financials for trade

* Fixed consistency of names

* Updated energy balance constraints and variables to include Trade

* Add NewTradeCapacity variable

* Add import/export mask

* Remove DiscountRateTrade and sum TotalDiscountedCostTrade

* Import/export as positive numbers

* constraint import == 0

* Added new set of constraints for trade

* Replaced variables with linear expressions for trade in energy balance A

* Removed NetTrade variable

* Added NetTrade as a linear expression

* Reformatted

* Removed unused indices

* Update energy balance eqn name

* Rename transmission to trade

* add defaults

* CAISO-ERCOT update trade

* "Merge with main"

* Add missing addition in calculation of NetTrade

* add missing constraint

* add trade constraints to init

* Rename TotalTradeCapacityAnnual

* Remove trade

* add trade test

* WIP cost of capital trade

* Testing transmission constraints

* Updated variables and linear expressions for NetTrade and NetTradeAnual

* Updated Trade constraints

* Fix energy_balance_a and update test

* Added trade capacity constraints and solution variables

* Reverse import coords in trade constraint

* Updated trade constraints, financials, and losses

* Add validation to construct trade region pairs

* Update trade test

* Add DiscountRateTrade

* Separate trade into diff instances per commodity

* Update example CSVs

* Update test_otoole_roundtrip EXCLUDE_STEMS

* Remove otoole compare files

* add commodity as a param of Trade

* Update trade tests

* bugfix test_otoole_trade

* Update trade documentation

* Update region and model docs

* Remove redundant code

---------

Co-authored-by: Abhishek  Shivakumar <[email protected]>
Co-authored-by: Abhishek  Shivakumar <[email protected]>

docs/model.md

@@ -11,7 +11,7 @@ Required parameter.
 `time_definition` `(TimeDefinition)` - Single TimeDefinition class instance to contain all
 temporal data related to the model. Required parameter.
 
-`regions` `(List[Region])` - List of Region instances to contain region names and trade routes.
+`regions` `(List[Region])` - List of Region instances to contain region names.
 Required parameter.
 
 `commodities` `(List[Commodity])` - List of Commodity instances to contain all data related to
@@ -27,7 +27,10 @@ related to technologies.
 Required parameter.
 
 `storage` `(List[Storage])` - List of Storage instances to contain all data related to storage.
-Required parameter.
+Optional parameter, defaults to `None`.
+
+`trade` `(List[Trade])` - List of Trade instances to contain all data related to trade routes.
+Optional parameter, defaults to `None`.
 
 `depreciation_method` `({region:str})` - OSeMOSYS DepreciationMethod.
 Parameter defining the type of depreciation to be applied, must take values of 'sinking-fund' or

docs/region.md

@@ -1,39 +1,23 @@
 # Region
 
-The Region class contains data related to regions, including trade routes. One Region instance
+The Region class contains data related to regions. One Region instance
 is given for each region.
 
 ## Parameters
 
 `id` `(str)`: Used to represent the region name.
 
-`trade_routes` `({region:{commodity:{year:bool}}})` - OSeMOSYS TradeRoute.
-    Boolean tag indicating which other regions may trade the specified commodities with the
-    current region. Optional, defaults to `None`.
-
 ## Examples
 
-A simple example of how a region ("R1") might be defined as able to trade the commodity "COAL"
-with region "R2" is given below, along with how it can be used to create an instance of the
-Region class:
+A simple example of how a region ("R1") might be defined is given below, along with how it can
+be used to create an instance of the Region class:
 
 ```python
 from tz.osemosys.schemas.region import Region
 
 basic_region = dict(
     id="R1",
-    trade_routes={"R2": {"COAL": {"2020": True, "2021": True, "2022": True}}},
 )
 
 Region(**basic_region)
 ```
-
-This model can be expressed more simply using the wildcard `*` for dimensions over which data is
-repeated:
-
-```python
-basic_region = dict(
-    id="R1",
-    trade_routes={"R2": {"COAL": {"*": True}}},
-)
-```

docs/technology.md

@@ -9,9 +9,9 @@ documentation for a more detailed description.
 
 ## Parameters
 
-`id` `(str)`: Used to represent the technology name.
+`id` `(str)` - Used to represent the technology name.
 
-`operating_modes` `(List[OperatingMode])`: A list containing one OperatingMode object for each
+`operating_modes` `(List[OperatingMode])` - A list containing one OperatingMode object for each
 operating mode relevant to the current technology. Each OperatingMode object contains data
 relevant for the corresponding operating mode, ie.e. input/output/emission activity ratios,
 variable costs, tag linking the technology to storage. See the "Operating modes" documentation for
@@ -62,14 +62,16 @@ Total minimum existing (residual plus cumulatively installed) capacity allowed f
 in a specified year. Optional, defaults to `None`.
 
 `capacity_additional_max` `({region:{year:float}})` - OSeMOSYS TotalAnnualMaxCapacityInvestment.
-Maximum capacity of a technology, expressed in power units. Optional, defaults to `None`.
+Maximum capacity investment of a technology, expressed in power units. Optional, defaults to
+`None`.
 
 `capacity_additional_max_growth_rate` `({region:float})` - New parameter, OSeMOSYS style name CapacityAdditionalMaxGrowthRate. Maximum allowed percentage growth in the given technology's capacity year on year, expressed as a decimal (e.g. 0.2 for 20%). Optional, defaults to `None`.
 
 `capacity_additional_max_floor` `({region:float})` - New parameter, OSeMOSYS style name CapacityAdditionalMaxFloor. Maximum allowed growth in the given technology's capacity year on year, expressed in capacity units. If used in conjunction with capacity_additional_max_growth_rate it limits capacity growth to whichever is greater. Optional, defaults to `None`.
 
 `capacity_additional_min` `({region:{year:float}})` - OSeMOSYS TotalAnnualMinCapacityInvestment.
-Minimum capacity of a technology, expressed in power units. Optional, defaults to `None`.
+Minimum capacity investment of a technology, expressed in power units. Optional, defaults to
+`None`.
 
 `capacity_additional_min_growth_rate` `({region:float})` - New parameter, OSeMOSYS style name CapacityAdditionalMinGrowthRate. Minimum allowed percentage growth in the given technology's capacity year on year, expressed as a decimal (e.g. 0.2 for 20%). Optional, defaults to `None`.
 

docs/trade.md

@@ -0,0 +1,75 @@
+# Trade
+
+The Trade class contains all data related to trade routes (OSeMOSYS 'TradeRoute'). One Trade
+instance is given for each commodity (OSeMOSYS 'FUEL') that can be traded. The Trade class
+contains parameters additional to those found in base OSeMOSYS related to trade. These are based
+on the new parameters introduced in the below paper:
+
+https://www.sciencedirect.com/science/article/abs/pii/S0360544224000021
+
+These new parameters allow trade to be modelled in a way which is more similar to technologies,
+with capacities, capital costs, and maximum allowable investments.
+
+## Parameters
+
+`id` `(str)` - Used to describe the type of trade, e.g. electricity transmission, LNG trade.
+Required parameter.
+
+`commodity` `(str)` - The commodity which can be traded. Must match the commodities in the
+commodities classes. Required parameter.
+
+`trade_routes` `({region:{region:{year:bool}}})` - Boolean linking the regions which may trade
+the given commodity. By default is a unidirectional link, so that the link must be specified in
+both directions to allow bilateral trade. Required parameter, defaults to False for links not
+specified.
+
+`trade_loss` `({region:{region:{year:float}}})` - Percentage of a commodity which is lost when
+traded between regions (given as a decimal). Optional, defaults to 0.
+
+`residual_capacity` `({region:{region:{year:float}}})` - Residual trade capacity, given in
+capacity units. Note that any residual capacities will only work unidirectionally. Optional,
+defaults to 0.
+
+`capex` `({region:{region:{year:float}}})` - Overnight investment cost per trade capacity unit.
+Optional, defaults to 0.00001.
+
+`capacity_additional_max` `({region:{region:{year:float}}})` - Maximum capacity investment of
+the given trade route. Optional, defaults to `None`.
+
+`operational_life` `({region:{region:{year:int}}})` - Integer value of operating life in years
+for the given trade route. Optional, defaults to 1.
+
+`cost_of_capital` `({region:region})` - Cost of capital (discount rate) for investments in the
+given trade route. Optional, defaults to 0.1.
+
+`construct_region_pairs` `(bool)` - Boolean parameter which, is set as True, will take the given
+    input data and duplicate it for the opposite region:region direction if not already provided.
+    E.g. providing trade_routes = {"R1": {"R2": {"COMMODITY": {"2020": True}}}} and setting the
+    construct_region_pairs parameter to True will then construct trade_routes as:
+    trade_routes = {
+                "R1": {"R2": {"COMMODITY": {"2020": True}}},
+                "R2": {"R1": {"COMMODITY": {"2020": True}}},
+                }
+
+
+## Examples
+
+A simple example of a trade route for commodity 'electricity' is shown below. It includes 2
+regions, with electricity being marked as tradable in either direction between the 2 using the
+construct_region_pairs parameter:
+
+```python
+from tz.osemosys.schemas.trade import Trade
+
+basic_trade = dict(
+    id="electricity trade",
+    commodity="electricity",
+    trade_routes={"R1": {"R2": {"*": True}}},
+    capex={"R1": {"R2": {"*": 100}}},
+    operational_life={"R1": {"R2": {"*": 5}}},
+    trade_loss={"R1": {"R2": {"*": 0.1}}},
+    construct_region_pairs=True,
+)
+
+Trade(**basic_trade)
+```

examples/CAISO-ERCOT-IC/main.yaml

@@ -28,22 +28,36 @@ regions:
   - id: US-CA
     long_name: California
     description: "The US state of California"
-    trade_routes: {US-TX: {"*": {"*": True}}, PACIFIC-MARKET: {"*": {"*": True}}}
 
   - id: US-TX
     long_name: Texas
     description: "The US state of Texas"
-    trade_routes: {US-CA: {"*": {"*": True}}, ATLANTIC-MARKET: {"*": {"*": True}}}
 
   - id: ATLANTIC-MARKET
     long_name: atlantic market
     description: a node representing atlantic import markets
-    trade_routes: {US-TX: {"*": {"*": True}}}
 
   - id: PACIFIC-MARKET
     long_name: pacific market
     description: a node representing pacific import markets
-    trade_routes: {US-CA: {"*": {"*": True}}}
+
+# TRADE ROUTES
+trade:
+  - id: "ELEC trade"
+    long_name: "Electricity trade"
+    description: "trade route instance for the ELEC commodity"
+    commodity: "ELEC"
+    trade_routes: {
+      "US-CA":
+        {
+        "US-TX": {"*": True},
+        "PACIFIC-MARKET": {"*": True}
+        },
+      "US-TX":
+        {
+        "ATLANTIC-MARKET": {"*": True},
+        },
+    }
 
 # TIME DEFINTIONS
 time_definition:

examples/otoole_compat/input_csv/otoole-full-electricity-complete/CapitalCostTrade.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,YEAR,VALUE
+R1,R2,ELCNPLXX02,2020,0.01

examples/otoole_compat/input_csv/otoole-full-electricity-complete/DiscountRateTrade.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,VALUE
+R1,R2,ELCNPLXX02,0.05

examples/otoole_compat/input_csv/otoole-full-electricity-complete/OperationalLifeTrade.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,YEAR,VALUE
+R1,R2,ELCNPLXX02,2020,10

examples/otoole_compat/input_csv/otoole-full-electricity-complete/ResidualTradeCapacity.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,YEAR,VALUE
+R1,R2,ELCNPLXX02,2020,0.01

examples/otoole_compat/input_csv/otoole-full-electricity-complete/TotalAnnualMaxTradeInvestment.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,YEAR,VALUE
+R1,R2,ELCNPLXX02,2020,999

examples/otoole_compat/input_csv/otoole-full-electricity-complete/TradeLossBetweenRegions.csv

@@ -0,0 +1,2 @@
+REGION,_REGION,FUEL,YEAR,VALUE
+R1,R2,ELCNPLXX02,2020,0.01

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
   - Commodities: commodity.md
   - Regions: region.md
   - Time definition: time_definition.md
+  - Trade: trade.md
 repo_url: https://github.com/transition-zero/tz-osemosys
 
 theme: