Manual

The following sections will guide you through the Installation process, how to Run the Model, how to create Custom Scenarios and about the built-in Visualization.

Installation

Prerequisites

The Leelo.jl package uses JuMP.jl to build the mathematical model and IBM's CPLEX to solve said model's optimization problem. The CPLEX API is managed by the CPLEX.jl package. While JuMP.jl is solver independent, i.e. any supported solver can be chosen, CPLEX.jl requires IBM's CPLEX to be installed before installing it and adding it to the project.

To install IBM® ILOG® CPLEX® Optimization Studio follow the steps on their website. CPLEX is free for academia. After installation the CPLEX_STUDIO_BINARIES environment variable has to be set to the installation location, as shown below.

ENV["CPLEX_STUDIO_BINARIES"] = "C:\\Program Files\\CPLEX_Studio1210\\cplex\\bin\\x86-64_win\\"

The Leelo.jl Package

The first step to using Leelo.jl is to get the package and it's dependencies installed. Since it is not registered in the Julia General Registry, it needs to be added as unregistered package. This is done by adding it via the specific github repository URL.

using Pkg
Pkg.add("https://github.com/simjunky/Leelo")

Alternatively, especially if you want to make modifications to the model's code, instead of just the computed scenarios, you can just use git to clone the github repository to your PC. When doing so, to then use the packages functions, you need to use activate to switch from the standard Julia environment to the packages one. In the REPL navigate to the cloned directory, then use:

using Pkg
Pkg.activate(".")

From here on out, no matter which method you chose, you should be able to use Leelo.jl's functions as usual via:

using Leelo

The following Run the Model section gives an overview on how to run a simulation model. The Documentation gives a detailed overview of all provided functions.

Run the Model

The run_sim function is the main way to run a simulation. For each step of the simulation it automatically calls the associated functions:

• It reads the input files and creates a ModelData data structure, which holds all needed parameters.
• For each benchmark year of the simulation, it:
  • creates a new JuMP.Model and links it to the CPLEX optimizer.
  • adds model variables using JuMP.jl's @variable macro.
  • adds model constraints using JuMP.jl's @constraint macro.
  • defines the model's objective function.
  • calculates an optimal solution.
  • stores the results by writing them to a HDF5 file.
  • transitions the model parameters to the next year
• After all benchmark years have been calculated it visualizes some predefined aspects of the result.

To specify which scenario to run, the directory name <dir_name> containing all scenario related files can be passed to the run_sim function.

run_sim(scenario_dir = "<dir_name>")

The scenario_dir argument defaults to the test directory, which may not be present at your current working directory.
The <dir_name> directory must have the sub-directory <dir_name>/input_data, where all the input files must be located. Exemplary input files, which can be modified, can be cloned or downloaded from the package's github, with more info in Custom Scenarios.

The second optional argument of run_sim is config. It defaults to SingleObjectiveBasicConfig, which means the created model will only have the basic constraints. To add multi-service constrains, e.g. power reserves, to the model the SingleObjectiveMultiServiceConfig can be used.

run_sim(config = SingleObjectiveMultiServiceConfig())

The results are stored in a HDF5 file in the <dir_name>/output_data sub-directory. To view the data, use HDF®View. The values of a benchmark years variables are stored in a sub-group within the HDF5 file.
To create your own data evaluation, the HDF5.jl package can be used. To open the file use h5open, [] for specifiing the sub group and read to access the data within the variables.

using HDF5
file = h5open("<file_dir>/<file_name>.h5", "r")
var = read(file["parameters"], "interest_rate")
close(file)

Here, the variable interest_rate was read from the parametes sub-group and copied to the variable var. Always remember to close the file using close, when done.

Custom Scenarios

The real use of Leelo.jl is to create your own energy system scenarios.

To do this use the exemplary input files from the package's github as a starting ground. These are the files:

• scenario_setting.xlsx contains scenatio dimension such as number of nodes, timsteps and the years of the planning horizon.
• demand_profiles.xlsx contains the power demand for each timestep and node
• transmission_lines.xlsx contains the power lines connecting the nodes.
• conventional_generators.xlsx contains all fossil fuel dependent power generation technologies.
• renewable_generators.xlsx contains all renewable power generation technologies. They differ compared to the conventional generators by having an associated time dependent generation profile.
• renewable_profiles.xlsx contains these generation profiles for each renwable technology for each node and timestep.
• hydro_run_of_river.xlsx contains the different river-based hydro power plants. These also have generation profiles depending on water availability.
• hydro_run_of_river_profiles.xlsx contains these generation profiles for all river hydro power plants.
• hydro_cascades.xlsx contain all reservoir-based hydro power plants and their interconnectivity. They depend on inflow profiles to their reservoirs.
• hydro_cascades_profiles.xlsx contains the inflow profiles for hydro power reservoirs.
• storage_technologies.xlsx contains the different available storages and their storage medium.
• conversion_technologies.xlsx contains the available converters to store and recuperate power. With the help of these, more complex technologies, such as concentrated solar power can be modeled.
• CSP_profiles.clsx contains the generation profiles for concentrated solar power plants.
• preexisting_capacities.xlsx contains the already existing power capacity of each technology in each bus.

Each file contains parameters or generation profiles for the possible technologies. To add a certain technology, simply add a row to the respective file and fill out all cells of the table. Keep in mind that there needs to be an empty row after the last entry.
For some technologies, such as in conventional_generators.xlsx no further information is needed. For others, that depend on some generation profile, such as renewable_generators.xlsx, also data must be added in the connected renewable_profiles.xlsx file. All technologies require some power capacity to be added to preexisting_capacities.xlsx (it ca be zero).

To use your now generated scenario files, put them all into the <dir_name>/input_data sub directory of your scenario directory.

Visualization

The create_plots function runs all defined visualization functions. Its optional arguments are the scenario directory, and the filename of the HDF5 for the case it deviates from the default model_results.h5. This file must be in the <dir_name>/output_data sub-directory to be found.

create_plots(scenario_dir = "<dir_name>", file_name = "<file_name>.h5")

All the created plots are saved as PDF file in the <dir_name>/plots sub-directory.

If only one specific plot is of interest, then instead of the create_plots function, all visualization functions can be called directly. All of them are listed in the Documentation and are named with a plot_-prefix by convention.
These functions require an opened HDF5 file and the plot target directory as arguments. Therefore, the HDF5 result file needs to be opened first to call these functions. This is done using the HDF5.jl package.

using HDF5

# "r" opens the file in read-only mode
file = h5open("<dir_name>/output_data/<file_name>.h5", "r")

target_dir = "<dir_name>/plots"

# e.g. if you are interested in the total system cost
plot_total_cost(file, target_dir)

close(file)

It should be noted, that after opening the file using h5open it should always be closed using close.