Merge branch 'Flow-based' of https://github.com/IIT-EnergySystemModels/openTEPES into Flow-based

Author: arght

CHANGELOG.rst

@@ -4,6 +4,13 @@ Change Log
 [4.18.5] - 2025-05-20
 -----------------------
 - [CHANGED] introduce variable TTC forward and backward for the transmission lines
+
+[4.18.5] - 2025-05-19
+-----------------------
+- [CHANGED] add hourly mutually exclusive generators, generators can now be part of several mutually exclusive groups, exclusivity now applies to consumption too
+- [FIXED] change from titleside to title_side in output results to adapt to the latest plotly version
+- [CHANGED] add logfile for GAMS solver
+- [FIXED] fix error in the cost summary per area files
 - [FIXED] fix some errors in the output results
 - [FIXED] don't initialize some variables
 - [FIXED] don't fixed or count variables that have no value

README.rst

@@ -132,7 +132,7 @@ Miniconda (recommended)
    2. The `HiGHS <https://ergo-code.github.io/HiGHS/dev/interfaces/python/#python-getting-started>`_ is our recommendation if you want a free and open-source solver.
    3. Install openTEPES via pip by ``pip install openTEPES``
 
-Continue at `Get Started <#get-started>`_ and see the `Tips <#tips>`_.
+Continue at `Get Started <#get-started>`_.
 
 
 GitHub Repository (the hard way)
@@ -206,15 +206,6 @@ Then, the **results** should be written in the folder who is called with the cas
 
     ``openTEPES_run(<dir>, <case>, <solver>, <results>, <log>)``
 
-Tips
-####
-
-1. A complete documentation of the openTEPES model can be found at `<https://opentepes.readthedocs.io/en/latest/index.html>`_, which presents the mathematical formulation, input data and output results.
-2. Try modifying the **TimeStep** in **oT_Data_Parameter_<case>.csv** and see their effect on results.
-3. Using **0** or **1**, the optimization options can be activated or deactivated in **oT_Data_Option_<case>.csv**.
-4. If you need a nice python editor, think about using `PyCharm <https://www.jetbrains.com/pycharm/>`_. It has many features including project management, etc.
-5. We also suggest the use of `Gurobi <https://www.gurobi.com/academia/academic-program-and-licenses/>`_ (for Academics and Recent Graduates) as a solver to deal with MIP and LP problems instead of GLPK.
-
 Run the Tutorial
 ################
 

doc/rst/Download.rst

@@ -2,7 +2,7 @@
 
 Download & Installation
 =======================
-The **openTEPES** model has been developed using `Python 3.12.3 <https://www.python.org/>`_ and `Pyomo 6.9.2 <https://pyomo.readthedocs.io/en/stable/>`_ and it uses `Gurobi 12.0.1 <https://www.gurobi.com/products/gurobi-optimizer/>`_ as commercial MIP solver for which a free academic license is available.
+The **openTEPES** model has been developed using `Python 3.13.2 <https://www.python.org/>`_ and `Pyomo 6.9.2 <https://pyomo.readthedocs.io/en/stable/>`_ and it uses `Gurobi 12.0.2 <https://www.gurobi.com/products/gurobi-optimizer/>`_ as commercial MIP solver for which a free academic license is available.
 It uses Pyomo so that it is independent of the preferred solver. You can alternatively use one of the free solvers `HiGHS 1.10.0 <https://ergo-code.github.io/HiGHS/dev/installation/#Precompiled-Binaries>`_, `SCIP 9.2.1 <https://www.scipopt.org/index.php#download>`_, `GLPK 5.0 <https://www.gnu.org/software/glpk/>`_,
 and `CBC 2.10.12 <https://github.com/coin-or/Cbc/releases>`_. List the serial solver interfaces under Pyomo with this call::
 
@@ -39,7 +39,6 @@ Here, you have the input files of:
 
 Code
 ----
-
 The **openTEPES** code is provided under the `GNU Affero General Public License <https://www.gnu.org/licenses/agpl-3.0.en.html>`_:
 
 - the code can't become part of a closed-source commercial software product
@@ -68,7 +67,7 @@ There are 2 ways to get all required packages under Windows. We recommend using
    2. `HiGHS <https://ergo-code.github.io/HiGHS/dev/interfaces/python/#python-getting-started>`_ is our recommendation if you want a free and open-source solver.
    3. Install openTEPES via pip by ``pip install openTEPES``
 
-Continue at `Get Started <#get-started>`_ and see the `Tips <#tips>`_.
+Continue at `Get Started <#get-started>`_.
 
 
 **GitHub Repository (the hard way)**
@@ -78,7 +77,6 @@ Continue at `Get Started <#get-started>`_ and see the `Tips <#tips>`_.
 3. Set up the path by ``cd "C:\Users\<username>\...\openTEPES"``. (Note that the path is where the repository was cloned.)
 4. Install openTEPES via pip by ``pip install .``
 
-
 **Solvers**
 
 HiGHS
@@ -112,7 +110,6 @@ This option is activated by calling the openTEPES model with the solver name 'ga
 
 Get started
 -----------
-
 Developers
 
 By cloning the `openTEPES repository <https://github.com/IIT-EnergySystemModels/openTEPES/tree/master>`_, you can create branches and propose pull-request. Any help will be very appreciated.
@@ -141,15 +138,6 @@ Then, the **results** should be written in the folder who is called with the cas
 
     ``openTEPES_run(<dir>, <case>, <solver>, <results>, <log>)``
 
-Tips
------------
-
-1. A complete documentation of the openTEPES model can be found at `<https://opentepes.readthedocs.io/en/latest/index.html>`_, which presents the mathematical formulation, input data and output results.
-2. Try modifying the **TimeStep** in **oT_Data_Parameter_<case>.csv** and see their effect on results.
-3. Using **0** or **1**, the optimization options can be activated or deactivated in **oT_Data_Option_<case>.csv**.
-4. If you need a nice python editor, think about using `PyCharm <https://www.jetbrains.com/pycharm/>`_. It has many features including project management, etc.
-5. We also suggest the use of `Gurobi <https://www.gurobi.com/academia/academic-program-and-licenses/>`_ (for Academics and Recent Graduates) as a solver to deal with MIP and LP problems instead of GLPK.
-
 **Run the Tutorial**
 
 It can be run in Binder:

doc/rst/InputData.rst

@@ -341,7 +341,7 @@ Header                      Description
 ==========================  =======================================================================================================================================================================================  ===================================
 Node                        Name of the node where generator is located. If left empty, the generator is ignored
 Technology                  Technology of the generator (nuclear, coal, CCGT, OCGT, ESS, solar, wind, biomass, etc.)
-MutuallyExclusive           Mutually exclusive generator with the current one. Only exclusion in one direction is needed. It is computationally demanding.
+MutuallyExclusive           Mutually exclusive groups the generator belongs to. Only one generator per group can be committed simultaneously. It is computationally demanding.
 BinaryCommitment            Binary unit commitment decision                                                                                                                                                          Yes/No
 NoOperatingReserve          No contribution to operating reserve. Yes if the unit doesn't contribute to the operating reserve                                                                                        Yes/No
 OutflowsIncompatibility     Outflows are incompatible with the charging process (e.g., electric vehicle). This is not the case of an electrolyzer                                                                    Yes/No
@@ -387,7 +387,7 @@ ShutDownCost                Shutdown cost
 CO2EmissionRate             CO2 emission rate. It can be negative for units absorbing CO2 emissions as biomass                                                                                                       tCO2/MWh
 FixedInvestmentCost         Overnight investment (capital -CAPEX- and fixed O&M -FOM-) cost                                                                                                                          M€
 FixedRetirementCost         Overnight retirement (capital -CAPEX- and fixed O&M -FOM-) cost                                                                                                                          M€
-FixedChargeRate             Fixed-charge rate to annualize the overnight investment cost                                                                                                                             p.u.
+FixedChargeRate             Fixed-charge rate to annualize the overnight investment cost. Proportion of annual payment to return the overnight investment cost                                                       p.u.
 StorageInvestment           Storage capacity and energy inflows linked to the investment decision                                                                                                                    Yes/No
 BinaryInvestment            Binary unit investment decision                                                                                                                                                          Yes/No
 InvestmentLo                Lower bound of investment decision                                                                                                                                                       p.u.
@@ -443,7 +443,7 @@ Those generators or ESS with fixed cost >0  are considered candidate and can be
 
 Maximum, minimum, and initial storage values are considered proportional to the invested capacity for the candidate ESS units if StorageInvestment is activated.
 
-When there are several generators mutually exclusive you must create a cycle of mutual exclusivity for every two generators. For example, if three generators are mutually exclusive among them and only one of them can be committed, then generator 1 can be declared exclusive with generator 2 and generator 2 with generator 3 and generator 3 with generator 1.
+A generator can be in several groups, which must be separated by "\|" when inputted. So if Generator1 belongs to Group1 and Group2, the data entry should be "Group1\|Group2". If any of the generators in a group is an installation candidate it is assumed that the exclusivity is yearly, so only one of the generators can be committed in the whole Period. When all mutually exclusive generators in a group are already installed and functioning it is assumed that the exclusivity is hourly and which generator is committed can change every LoadLevel.
 
 If lower and upper bounds of investment/retirement decisions are very close (with a difference <1e-3) to 0 or 1 are converted into 0 and 1.
 
@@ -597,6 +597,8 @@ For example, these data can be used for defining the minimum and/or maximum ener
 Electricity transmission network
 --------------------------------
 
+At least one electric transmission line connecting two different nodes must be defined.
+
 A description of the circuit (initial node, final node, circuit) data included in the file ``oT_Data_Network.csv`` follows:
 
 ===================  ===============================================================================================================  ======
@@ -665,6 +667,8 @@ Internally, all the values below 1e-5 times the maximum system demand of each ar
 Node location
 -------------
 
+At least two different nodes must be defined.
+
 A description of the data included in the file ``oT_Data_NodeLocation.csv`` follows:
 
 ==============  ============  ================  ==
@@ -823,8 +827,8 @@ Header               Description
 InitialPeriod        Initial period (year) when the unit is installed or can be installed, if candidate                                   Year
 FinalPeriod          Final   period (year) when the unit is installed or can be installed, if candidate                                   Year
 Length               Pipeline length (only used for reporting purposes). If not defined, computed as 1.1 times the geographical distance  km
-TTC                  Total transfer capacity (maximum permissible thermal load) in forward  direction. Static pipeline rating             tH2
-TTCBck               Total transfer capacity (maximum permissible thermal load) in backward direction. Static pipeline rating             tH2
+TTC                  Total transfer capacity (maximum permissible hydrogen flow) in forward  direction. Static pipeline rating            tH2
+TTCBck               Total transfer capacity (maximum permissible hydrogen flow) in backward direction. Static pipeline rating            tH2
 SecurityFactor       Security factor to consider approximately N-1 contingencies. NTC = TTC x SecurityFactor                              p.u.
 FixedInvestmentCost  Overnight investment (capital -CAPEX- and fixed O&M -FOM-) cost                                                      M€
 FixedChargeRate      Fixed-charge rate to annualize the overnight investment cost                                                         p.u.
@@ -893,8 +897,8 @@ Header               Description
 InitialPeriod        Initial period (year) when the unit is installed or can be installed, if candidate                                   Year
 FinalPeriod          Final   period (year) when the unit is installed or can be installed, if candidate                                   Year
 Length               Pipeline length (only used for reporting purposes). If not defined, computed as 1.1 times the geographical distance  km
-TTC                  Total transfer capacity (maximum permissible thermal load) in forward  direction. Static pipeline rating             MW
-TTCBck               Total transfer capacity (maximum permissible thermal load) in backward direction. Static pipeline rating             MW
+TTC                  Total transfer capacity (maximum permissible heat flow) in forward  direction. Static pipeline rating                MW
+TTCBck               Total transfer capacity (maximum permissible heat flow) in backward direction. Static pipeline rating                MW
 SecurityFactor       Security factor to consider approximately N-1 contingencies. NTC = TTC x SecurityFactor                              p.u.
 FixedInvestmentCost  Overnight investment (capital -CAPEX- and fixed O&M -FOM-) cost                                                      M€
 FixedChargeRate      Fixed-charge rate to annualize the overnight investment cost                                                         p.u.

doc/rst/MathematicalFormulation.rst

@@ -658,7 +658,7 @@ Given that there are disjunctive constraints, which are only correct with binary
 
 **Hydrogen network operation**
 
-Balance of hydrogen generation by electrolyzers, hydrogen consumption from hydrogen heater using it, and demand at each node [tH2] «``eBalanceH2``»
+Balance of hydrogen generation by electrolyzers, hydrogen consumption from hydrogen heater using it, and demand at each node [tH2] «``eBalanceH2``». A transport model is used to model the hydrogen network.
 
 :math:`\sum_{e \in i} \frac{DUR^p_{\omega n}}{PF'_e} gc^p_{\omega ne} - \sum_{g \in i} gh^p_{\omega ng} + hns^p_{\omega ni} = DUR^p_{\omega n} DH^p_{\omega ni} + \sum_{jc} fh^p_{\omega nijc} - \sum_{jc} fh^p_{\omega njic} \quad \forall p \omega ni`
 
@@ -668,7 +668,7 @@ Energy conversion from any energy type to heating [p.u.] («``eEnergy2Heat``»)
 
 :math:`gh_{ne} = \frac{DUR^p_{\omega n}}{PF''_e} gc_{ne} \quad \forall ne`
 
-Balance of heat generation produced by CHPs and fuel heaters respectively and demand at each node [GW] «``eBalanceHeat``»
+Balance of heat generation produced by CHPs and fuel heaters respectively and demand at each node [GW] «``eBalanceHeat``». A transport model is used to model the heat network.
 
 :math:`\sum_{g \in i} gh^p_{\omega ng} + htns^p_{\omega ni} = DUR^p_{\omega n} DHt^p_{\omega ni} + \sum_{jc} fp^p_{\omega nijc} - \sum_{jc} fp^p_{\omega njic} \quad \forall p \omega ni`