Merge pull request #474 from PyPSA/ng-docs

Update natural gas docs

docs/source/configtables/sector_natural_gas.csv

@@ -1,6 +1,11 @@
 ,Unit,Values,Description
 natural_gas,,,Options when implementing natural gas networks
--- force_exports,--,"bool {true, false}",Force imports/export limits to states/provinces outside of the model scope. Values are based on historic data aligned to weather year.
+-- imports,--,,Limits on imports compared to historical year
+--- min,per_unit,"float {>=0}",Minimum import requirememnt compared to historical year.
+--- max,per_unit,"float {>=0} or 'inf'",Maximum allowable imports compared to historical year.
+-- exports,--,,Limits on exports compared to historical year
+--- min,per_unit,"float {>=0}",Minimum export requirememnt compared to historical year.
+--- max,per_unit,"float {>=0} or 'inf'",Maximum allowable exports compared to historical year.
 -- cyclic_storage,--,"bool {true, false}",Apply cyclic storage constraints on linepack and underground storage
 -- standing_loss,per_unit,"float {0 <=, >= 1}","Leakage rate from pipelines. These leaks do NOT account towards emissions, just enforces gas production to replinish losses with cyclic constraints. "
 ,,,

docs/source/data-naturalgas.md

@@ -41,7 +41,7 @@ The natural gas network includes the following components. All components attach
 .. csv-table::
    :header-rows: 1
    :widths: 22,22,33
-   :file: datatables/natural_gas.csv
+   :file: datatables/natural_gas_components.csv
 ```
 
 :::{figure-md} gas-components
@@ -63,7 +63,22 @@ Regions outside the model scope include connections to neighbouring states (for
 | California      | Arizona           | Domestic      |
 | California      | Mexico            | International |
 
-Additionally, the user can choose to enforce boundary conditions on these connections. If applied, annual historical imports and exports to the neighbouring regions are retrieved from the EIA for the modelled weather year. Constraints are added to match the import/export values over the year.
+Additionally, the user can choose to enforce boundary conditions on these connections. If applied, annual historical imports and exports to the neighbouring regions are retrieved from the EIA for the modelled weather year. Minimum and maximum import/export constraints based on this reference value can then be specified through the following configuration file.
+
+Consider the [schematic below](gas-trade), showing how a single state is trading with a neighbouring state outside the models geographic scope. The following table shows how the user can specify import/export limits into and outof each state. Note, the constraints are applied at a state level, but each state must respect the same constraint configuration values.
+
+:::{figure-md} gas-trade
+<img src="./_static/natural_gas/gas-trade.png" width="250px">
+
+Simple Natural Gas Trading with Regions Outside Model Scope
+:::
+
+```{eval-rst}
+.. csv-table::
+   :header-rows: 1
+   :widths: 15,15,30,20,20
+   :file: datatables/natural_gas_trade.csv
+```
 
 ### Capacity Expansion
 
@@ -87,7 +102,7 @@ Listed below are the main datasources and assumptions applied to them to build t
 .. csv-table::
    :header-rows: 1
    :widths: 22,22,33
-   :file: datatables/natural_gas.csv
+   :file: datatables/natural_gas_sources.csv
 ```
 
 ## Validation

docs/source/datatables/natural_gas_components.csv

@@ -1,6 +1,6 @@
 Component,Operational Constraints,PyPSA-Component
-Underground Storage,Min/Max storage levels | Capacity;,Store + Links + Bus
+Underground Storage,Min/Max storage levels | Capacity,Store + Links + Bus
 Pipelines,Capacity,Links
 Linepack,Min/Max storage levels,Store
 Processing,Capacity,Store + Links + Bus
-Import/Exports,Capacity,Store + Links + Bus
+Import/Exports,Capacity | Annual Energy,Store + Links + Bus

docs/source/datatables/natural_gas_trade.csv

@@ -0,0 +1,19 @@
+Configuration Option,Configuration Value ,Description,Constraint ,Applied to
+``import.min``,0,No import requirement,Σ(p) >= 0,S2 S1 gas trade
+,0.5,Import at least half of historical year value ,Σ(p) >= 5000,S2 S1 gas trade
+,1,Import at least half of historical year value ,Σ(p) >= 10000,S2 S1 gas trade
+,2,Import at least double the historical year value ,Σ(p) >= 20000,S2 S1 gas trade
+``import.max``,0,No imports allowed,Σ(p) <= 0,S2 S1 gas trade
+,0.5,Import up to half of historical year value ,Σ(p) <= 5000,S2 S1 gas trade
+,1,Import up to the full historical year value ,Σ(p) <= 10000,S2 S1 gas trade
+,2,Import up to double the historical year value ,Σ(p) <= 20000,S2 S1 gas trade
+,inf,Unlimited Imports ,No constraint added,S2 S1 gas trade
+``export.min``,0,No exports requirement,Σ(p) >= 0,S1 S2 gas trade
+,0.5,Export at least half of historical year value ,Σ(p) >= 5000,S1 S2 gas trade
+,1,Export at least half of historical year value ,Σ(p) >= 10000,S1 S2 gas trade
+,2,Export at least double the historical year value ,Σ(p) >= 20000,S1 S2 gas trade
+``export.max``,0,No exports allowed,Σ(p) <= 0,S1 S2 gas trade
+,0.5,Export up to half of historical year value ,Σ(p) <= 5000,S1 S2 gas trade
+,1,Exportup to the historical year value ,Σ(p) <= 10000,S1 S2 gas trade
+,2,Export up to double the historical year value ,Σ(p) <= 20000,S1 S2 gas trade
+,inf,Unlimited Export ,No constraint added,S1 S2 gas trade