API

IESopt

A general purpose solver agnostic energy system optimization framework.

struct Carrier
    name::String
    unit::Union{String, Nothing}
end

Represents a single (energy) carrier with a given name.

This is mostly used to represent various commodities that (easily) represent some form of energy (e.g. gas, water, ...), but also enables modelling commodities that are not (treated as) representing some type of energy (e.g. CO2). Specify unit to bind that carrier to an (arbitrary) unit that allows easier plotting and result analysis.

struct Snapshot
    name::_String
    id::_ID
    weight::_ScalarInput

    is_representative::Bool
    representative::_ID
end

Represent a specific timestamp, that can be tied to timeseries values.

Each Snapshot expects a name, that can be used to hold a timestamp (as String; therefore supporting arbitrary formats). The weight (default = 1.0) specifies the "probabilistic weight" of this Snapshot or the length of the timeperiod that begins there (a weight of 2 can therefore represent a 2-hour-resolution; this also allows a variable temporal resolution throughout the year/month/...).

A Connection is used to model arbitrary flows of energy between Nodes. It allows for limits, costs, delays, ...

A Decision represents a basic decision variable in the model that can be used as input for various other core component's settings, as well as have associated costs.

A Node represents a basic intersection/hub for energy flows. This can for example be some sort of bus (for electrical systems). It enforces a nodal balance equation (= "energy that flows into it must flow out") for every Snapshot. Enabling the internal state of the Node allows it to act as energy storage, modifying the nodal balance equation. This allows using Nodes for various storage tasks (like batteries, hydro reservoirs, heat storages, ...).

bus:
  type: Node
  carrier: electricity

store:
  type: Node
  carrier: hydrogen
  has_state: true
  state_lb: 0
  state_ub: 50

A Profile allows representing "model boundaries" - parts of initial problem that are not endogenously modelled - with a support for time series data. Examples are hydro reservoir inflows, electricity demand, importing gas, and so on. Besides modelling fixed profiles, they also allow different ways to modify the value endogenously.

demand_XY:
  type: Profile
  carrier: electricity
  node_from: grid
  value: demand_XY@input_file

fuel_gas:
  type: Profile
  carrier: gas
  node_to: country_gas_grid
  mode: create
  cost: 100.0

co2_cost:
  type: Profile
  carrier: co2
  node_from: total_co2
  mode: destroy
  cost: 150.0

sell_electricity:
  type: Profile
  carrier: electricity
  node_from: internal_grid_node
  mode: destroy
  cost: -30.0

A Unit allows transforming one (or many) forms of energy into another one (or many), given some constraints and costs.

gas_turbine:
  type: Unit
  inputs: {gas: gas_grid}
  outputs: {electricity: node, co2: total_co2}
  conversion: 1 gas -> 0.4 electricity + 0.2 co2
  capacity: 10 out:electricity

wind_turbine:
  type: Unit
  outputs: {electricity: node}
  conversion: ~ -> 1 electricity
  capacity: 10 out:electricity
  availability_factor: wind_factor@input_data
  marginal_cost: 1.7 per out:electricity

heatpump:
  type: Unit
  inputs: {electricity: grid}
  outputs: {heat: heat_system}
  conversion: 1 electricity -> cop@inputfile heat
  capacity: 10 in:electricity

run(filename::String; kwargs...)

Build, optimize, and return a model.

Arguments

• filename::String: The path to the top-level configuration file.

Keyword Arguments

Keyword arguments are passed to the generate!(...) function.

generate!(filename::String; @nospecialize(kwargs...))

Generate an IESopt model based on the top-level config in filename.

Arguments

• filename::String: The name of the file to load.

Keyword Arguments

To be documented.

Returns

• model::JuMP.Model: The generated IESopt model.

generate!(model::JuMP.Model, filename::String; kwargs...)

Generates an IESopt model from a given file and attaches an optimizer if necessary.

Arguments

• model::JuMP.Model: The JuMP model to be used.
• filename::String: The path to the file containing the model definition.

Keyword Arguments

To be documented.

Returns

• model::JuMP.Model: The generated IESopt model.

Notes

• The function validates the file before parsing and building the model.
• If the model is not in DIRECT mode and has no optimizer attached, an optimizer is attached.
• The function logs the model generation process and handles any exceptions that occur during generation.
• If an error occurs, detailed debug information and the stack trace are logged.

optimize!(model::JuMP.Model; kwargs...)

Optimize the given IESopt model with optional keyword arguments.

Arguments

• model::JuMP.Model: The IESopt model to be optimized.
• kwargs...: Additional keyword arguments to be passed to the JuMP.optimize! function.

Description

This function performs the following steps:

1. If there are constraint safety penalties, it relaxes the constraints based on these penalties.
2. Sets the verbosity of the solver output based on the model's configuration.
3. Logs the solver output to a file if logging is enabled and supported by the solver.
4. Calls JuMP.optimize! to solve the model.
5. Checks the result count and termination status to log the optimization outcome.
6. Analyzes the constraint safety results if there were any constraint safety penalties.
7. Extracts and saves the results if the model is solved and feasible.
8. Profiles the results after optimization.

Logging

• Logs messages about the relaxation of constraints, solver output, and optimization status.
• Logs warnings if the safety constraint feature is triggered or if unexpected result counts are encountered.
• Logs errors if the solver log file setup fails, if no results are returned, or if extracting results is not possible.

Returns

• nothing: This function does not return any value.

function get_component(model::JuMP.Model, component_name::AbstractString)

Get the component component_name from model.

function compute_IIS(model::JuMP.Model; filename::String = "")

Compute the IIS and print it. If filename is specified it will instead write all constraints to the given file. This will fail if the solver does not support IIS computation.

overview(file::String)

Extracts the most important information from an IESopt model file, and returns it as a dictionary.

pack(file::String; out::String="", method=:store)

Packs the IESopt model specified by the top-level config file file into single file.

The out argument specifies the output file name. If not specified, a temporary file is created. Returns the output file name. The method argument specifies the compression method to use. The default is :store, which means no compression is used. The other option is :deflate, which uses the DEFLATE compression method. The default (:auto) applies :store to all files below 1 MB, :deflate otherwise.

unpack(file::String; out::String="", force_overwrite::Bool=false)

Unpacks the IESopt model specified by file.

The out argument specifies the output directory. If not specified, a temporary directory is created. Returns the path to the top-level config file. The force_overwrite argument specifies whether to overwrite existing files.