Choose datasets¶

---

Import Necessary Libraries and Modules¶

First, we import the essential libraries and modules required for this tutorial:

• pandas as pd: A powerful data manipulation library.
• Energyscope from energyscope.energyscope: The main class to initialize and run the EnergyScope model.
• infrastructure_qc_2020 from energyscope.models: Predefined models for different regions or configurations.
• postprocessing from energyscope.result: Functions and classes for handling and processing results.
• plot_sankey from energyscope.plots: Functions to create Sankey diagrams for visualizing energy flows.

In [1]:

import pandas as pd
from energyscope.energyscope import Energyscope
from energyscope.models import infrastructure_qc_2020
from energyscope.result import postprocessing
from energyscope.plots import  plot_sankey

import pandas as pd from energyscope.energyscope import Energyscope from energyscope.models import infrastructure_qc_2020 from energyscope.result import postprocessing from energyscope.plots import plot_sankey

---

Define Solver Options¶

The solver options determine how the optimization solver behaves during the calculation. In this section, we demonstrate two methods to specify these options:

Directly in the Code¶

You can define the solver options directly within your script by creating a dictionary.

In [2]:

solver_options = {
    'solver': 'cplex',
    'presolve_eps': 5e-9,
    'presolve_fixeps': 7e-10,
    'mipgap': 1e-10,
    'display_eps': 1e-10,
    'omit_zero_rows': 1,
    'omit_zero_cols': 1,
    'show_stats': 1,
    'solver_msg': 0,
    'cplex_options': 'integrality=5e-7'
}

solver_options = { 'solver': 'cplex', 'presolve_eps': 5e-9, 'presolve_fixeps': 7e-10, 'mipgap': 1e-10, 'display_eps': 1e-10, 'omit_zero_rows': 1, 'omit_zero_cols': 1, 'show_stats': 1, 'solver_msg': 0, 'cplex_options': 'integrality=5e-7' }

• Note: These options are specific to the CPLEX solver and control aspects like presolve tolerances, MIP gap, and output display.

Loading from a CSV File¶

Alternatively, you can load the solver options from a CSV file, which can be convenient for managing configurations externally.

In [3]:

solver_options = pd.read_csv('tutorial_input/solver_options_infrastructure_qc_2020.csv')
solver_options = dict(zip(solver_options['Option'], solver_options['Value']))   # Reformat dict

solver_options = pd.read_csv('tutorial_input/solver_options_infrastructure_qc_2020.csv') solver_options = dict(zip(solver_options['Option'], solver_options['Value'])) # Reformat dict

• Here, we read the CSV file into a Pandas DataFrame and then convert it into a dictionary that can be used by the model.

After loading the solver options, you can inspect them to ensure they have been set correctly:

In [4]:

solver_options

solver_options

Out[4]:

{'solver': 'cplex',
 'presolve_eps': '5.00E-09',
 'presolve_fixeps': '7.00E-10',
 'mipgap': '1.00E-10',
 'display_eps': '1.00E-10',
 'omit_zero_rows': '1',
 'omit_zero_cols': '1',
 'show_stats': '1',
 'solver_msg': '0',
 'cplex_options': 'integrality=5e-7'}

---

Initialize and Run the Model with Specific Dataset and Solver Options¶

In this section, we initialize the EnergyScope model using the infrastructure_qc_2020 dataset and apply the custom solver options defined earlier.

Initialize the Model¶

Create an instance of the Energyscope class with the infrastructure_qc_2020 model and the specified solver options.

In [5]:

es_infra_qc = Energyscope(model=infrastructure_qc_2020, solver_options=solver_options)

es_infra_qc = Energyscope(model=infrastructure_qc_2020, solver_options=solver_options)

• Model: The infrastructure_qc_2020 model represents the energy system of Quebec with monthly resolution.
• Solver Options: The solver_options dictionary configures the solver's behavior during optimization.

Run the Optimization¶

Execute the calculation to solve the optimization problem.

In [6]:

results_qc = es_infra_qc.calc()

results_qc = es_infra_qc.calc()

[INFO] Activating AMPL license with UUID

Presolve eliminates 14467 constraints and 10653 variables.
Adjusted problem:
15812 variables:
	814 binary variables
	14998 linear variables
21545 constraints, all linear; 108336 nonzeros
	9834 equality constraints
	11711 inequality constraints
1 linear objective; 1 nonzero.

Setting $presolve_fixeps < 4.28e-10 or >= 5.54e-09
could change presolve results.

License file /root/.local/share/hatch/env/virtual/energyscope/4BIeM0-F/docs/lib/python3.10/site-packages/ampl_module_base/bin/ampl.lic:

Today = 20251022; found license file "/root/.local/share/hatch/env/virtual/energyscope/4BIeM0-F/docs/lib/python3.10/site-packages/ampl_module_base/bin/ampl.lic":
# Bundle #7173.7706 expiring 20260115: ME-451 Advanced Energetics, Prof. Fran?ois Mar?chal, EPFL
68f883b5 22a3622a f83802ac 726707ae 075a51bd 4387d24b 3540175c 05bf2e81
30fa383a c6afb3b6 0b2910f8 515f018c 21968d36 3ecb5133 03701237 6dce52f5
73f8a92d 69652715 ed2a35e0 e1b5eb60 e7d29b2c 1023d1d7 6e03b637 71a23857
1a23037d 7d205e84 b0d3a000 3a4ac147 998b7857 255b8480 cb11f390 90248ce0
29cd63f2 681a0941 9a2d31c2 d792c8e7 1f9bbd64 a5da1631 f76af105 813726a6
fc60a480 a8d9e732 cdc9d5f0 3d014f82 47b22f2f b1039792 c9545042 d4e0aa81
079e91a4 e0b5f917 2506b114 7e52c3d0 9a1a8042 a1703341 c2e78132 6de57151
f61ae700 67970734 83032361 8e9701e0 deb8c0a0 001ef970 62e28412 5554eca1
edca6a8b 1accc8e4 25beb0d1 67841703 830939f4 1ac35dd3 7cea62e5 d84eda33
14206943 accae0a3 7cd8d647 41b90ae7 9e9db74a 7b71f803 d694e2c2 50e2d8a7
c9a0f80c 4b5133f3 96aca280 32d56c86 a76b4d6e 09af7fc2 1fab96b3 39b8fae2
e169286c 7469b065 a637b736 0d80bd12 2268a404 e71ff4c2 76037057 0c146e57
dec27706 5a6ef4a4 2b59f546 7d3586c1 27e46d00 c2817fd7 38268564 dd80f1f4
f88c5a7c eff03632 f02624b0 4e359d63 1c7a85dc 4fc485b7 82386281 1c8046e3
1cca04cc 6497aa72 37bd9662 40a5c702 da471802 687d0cc3 2deab5f0 7f5b5570
f81ea484 1abc7323 b34d16f1 5f1cf624 357764b2 781dd8c3 d6178131 0f5d0e40
8acbc905 3ff202c5 674821c7 f7d69576 4ed6423a f47814d4 fa6535a3 4b46ce87
de06e488 5730a957 49daf031 b033e396 04b1e989 cda00584 aaf08194 dda7a951
321d9202 16c3feb4 59ab7433 e97c9e20 e115ed02 47ba52fb 6544b451 d2bd

Computed 1-1-0-fbc949fe
runner--pdbxrphm-project-62195384-concurrent-0
6E:0F:9C:36:30:03

HOSTINFO.NPROC.4

HOSTINFO.CORES.4
No cplex license for this machine.

exit value 2

<BREAK>

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[6], line 1
----> 1 results_qc = es_infra_qc.calc()

File /builds/energyscope/energyscope/src/energyscope/energyscope.py:89, in Energyscope.calc(self, ds, parser)
     87 self.es_model.solve()
     88 if self.es_model.solve_result_num > 99:
---> 89     raise ValueError(f"No optimal solution found, see error: ", self.es_model.solve_result_num)
     91 return parser(self.es_model, id_run=0)

ValueError: ('No optimal solution found, see error: ', 999)

• This step runs the solver (e.g., CPLEX) with the specified options and computes the optimal energy system configuration.
• Output: You may see console outputs indicating the solver's progress and any warnings or errors.

Post-Process the Results¶

After obtaining the raw results, we apply post-processing to compute Key Performance Indicators (KPIs) and prepare the data for visualization.

In [7]:

results_qc = postprocessing(results_qc)

results_qc = postprocessing(results_qc)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[7], line 1
----> 1 results_qc = postprocessing(results_qc)

NameError: name 'results_qc' is not defined

• The postprocessing function enriches the results with additional analysis, making them ready for further interpretation and plotting.

---

Visualize Results with a Sankey Diagram¶

A Sankey diagram is an effective tool for visualizing energy flows within the system, showing how energy sources are converted and consumed.

Generate the Sankey Diagram¶

Use the plot_sankey function with the processed results to create the diagram.

In [8]:

fig = plot_sankey(results_qc)

fig = plot_sankey(results_qc)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[8], line 1
----> 1 fig = plot_sankey(results_qc)

NameError: name 'results_qc' is not defined

• This function processes the results and generates a Sankey diagram object.

Display the Diagram¶

Render the Sankey diagram within the notebook for immediate visualization.

In [9]:

fig.show(renderer="notebook")

fig.show(renderer="notebook")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[9], line 1
----> 1 fig.show(renderer="notebook")

NameError: name 'fig' is not defined

• The diagram will display in the output cell, providing a visual representation of the energy flows in the optimized system.

• Optional: You can save the diagram as an HTML file or an image for external use by uncommenting the following lines:

In [10]:

# fig.write_html("tutorial_output/sankey_infrastructure_qc_2020.html")
# fig.write_image('tutorial_output/sankey_infrastructure_qc_2020.png')

# fig.write_html("tutorial_output/sankey_infrastructure_qc_2020.html") # fig.write_image('tutorial_output/sankey_infrastructure_qc_2020.png')

---

By following these steps, you have:

• Imported the necessary libraries and modules.
• Defined solver options either directly or by loading from a CSV file.
• Initialized and ran the EnergyScope model using the infrastructure_qc_2020 dataset with custom solver configurations.
• Post-processed the results to compute KPIs and prepare for visualization.
• Visualized the energy flows using a Sankey diagram.

This tutorial demonstrates how to customize solver settings and work with different datasets, enabling you to perform more advanced analyses tailored to specific regions or scenarios.