GitHub

General functions of EnergyModelsBase

Index

Functions for running the model

The following functions are provided for both creating a model using EnergyModelsBase and solving said model. Both functions have the input case and model. run_model calls create_model in the function, hence, it is not necessary to call the function beforehand.

The case dictionary has to follow a certain outline. In this case, it is simplest to look at the provided examples.

Note

We are currently debating to replace the dictionary used for case as well with a composite type. This will lead to breacking changes, but should be simple to adjust for.

EnergyModelsBase.create_model — Function
create_model(
    case,
    modeltype::EnergyModel,
    m::JuMP.Model;
    check_timeprofiles::Bool = true,
    check_any_data::Bool = true,
)

Create the model and call all required functions.

Arguments

  • case - The case dictionary requiring the keys :T, :nodes, :links, and products. If the input is not provided in the correct form, the checks will identify the problem.
  • modeltype - Used modeltype, that is a subtype of the type EnergyModel.
  • m - the empty JuMP.Model instance. If it is not provided, then it is assumed that the input is a standard JuMP.Model.

Keyword arguments

  • check_timeprofiles=true - A boolean indicator whether the time profiles of the individual nodes should be checked or not. It is advised to not deactivate the check, except if you are testing new components. It may lead to unexpected behaviour and potential inconsistencies in the input data, if the time profiles are not checked.
  • check_any_data::Bool=true - A boolean indicator whether the input data is checked or not. It is advised to not deactivate the check, except if you are testing new features. It may lead to unexpected behaviour and even infeasible models.
source
EnergyModelsBase.run_model — Function
run_model(case::Dict, model::EnergyModel, optimizer)

Take the case data as a dictionary and the model and build and optimize the model. Returns the solved JuMP model.

The dictionary requires the keys:

  • :nodes::Vector{Node}
  • :links::Vector{Link}
  • :products::Vector{Resource}
  • :T::TimeStructure
source

Functions for extending the model

The following functions are used for developing new nodes. See the page Creating a new node for a detailed explanation on how to create a new node.

EnergyModelsBase.variables_node — Function
variables_node(m, 𝒩ˢᵘᵇ::Vector{<:Node}, 𝒯, modeltype::EnergyModel)

Default fallback method when no method is defined for a node type. No variables are created in this case.

source
variables_node(m, 𝒩ˢⁱⁿᵏ::Vector{<:Sink}, 𝒯, modeltype::EnergyModel)

When the node vector is a Vector{<:Sink}, both surplus (:sink_surplus) and deficit (:sink_deficit) variables are created to quantify when there is too much or too little energy for satisfying the demand.

source
EnergyModelsBase.create_node — Function
create_node(m, n::Source, 𝒯, 𝒫, modeltype::EnergyModel)

Set all constraints for a Source. Can serve as fallback option for all unspecified subtypes of Source.

Called constraint functions

source
create_node(m, n::NetworkNode, 𝒯, 𝒫, modeltype::EnergyModel)

Set all constraints for a NetworkNode. Can serve as fallback option for all unspecified subtypes of NetworkNode.

Called constraint functions

source
create_node(m, n::Storage, 𝒯, 𝒫, modeltype::EnergyModel)

Set all constraints for a Storage. Can serve as fallback option for all unspecified subtypes of Storage.

Called constraint functions

source
create_node(m, n::Sink, 𝒯, 𝒫, modeltype::EnergyModel)

Set all constraints for a Sink. Can serve as fallback option for all unspecified subtypes of Sink.

Called constraint functions

source
create_node(m, n::Availability, 𝒯, 𝒫, modeltype::EnergyModel)

Set all constraints for a Availability. Can serve as fallback option for all unspecified subtypes of Availability.

Availability nodes can be seen as routing nodes. It is not necessary to have more than one available node except if one wants to include as well transport between different Availability nodes with associated costs (not implemented at the moment).

source

Constraint functions

The following functions can be used in newly developed nodes to include constraints. See the pages Constraint functions and Data functions for a detailed explanation on their usage.

Warning

The function constraints_capacity_installed should not be changed. It is used for the inclusion of investments through EnergyModelsInvestments in the extension. It also has to be called, if you create a new function constraints_capacity.

EnergyModelsBase.constraints_flow_in — Function
constraints_flow_in(m, n, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_flow_in(m, n::Storage, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_flow_in(m, n::Storage{AccumulatingEmissions}, 𝒯::TimeStructure, modeltype::EnergyModel)

Function for creating the constraint on the outlet flow from a generic Node or Storage.

These functions serve as fallback option if no other method is specified for a specific Node.

source
EnergyModelsBase.constraints_flow_out — Function
constraints_flow_out(m, n::Node, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_flow_out(m, n::Storage, 𝒯::TimeStructure, modeltype::EnergyModel)

Function for creating the constraint on the outlet flow from a generic Node. This function serves as fallback option if no other function is specified for a Node.

source
EnergyModelsBase.constraints_capacity — Function
constraints_capacity(m, n::Node, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_capacity(m, n::Storage, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_capacity(m, n::Sink, 𝒯::TimeStructure, modeltype::EnergyModel)

Function for creating the constraints on the maximum capacity of a generic Node, Storage, and Sink.

These functions serve as fallback option if no other method is specified for a specific Node.

Dispatching on this function

If you create a new method for this function, it is crucial to call within said function the function constraints_capacity_installed(m, n, 𝒯, modeltype) if you want to include investment options.

source
EnergyModelsBase.constraints_capacity_installed — Method
constraints_capacity_installed(m, n::Node, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_capacity_installed(m, n::Storage, 𝒯::TimeStructure, modeltype::EnergyModel)
constraints_capacity_installed(m, l::Link, 𝒯::TimeStructure, modeltype::EnergyModel)

Function for creating the constraint on the installed capacity to the available capacity.

These functions serve as fallback option if no other method is specified for a specific Node or Link.

Dispatching on this function

This function should only be used to dispatch on the modeltype for providing investments. If you create new capacity variables (as it is the case for storage nodes), it is beneficial to include as well a method for this function and the corresponding node types.

source
EnergyModelsBase.constraints_level — Function
constraints_level(m, n::Storage, 𝒯, 𝒫, modeltype::EnergyModel)

Function for creating the level constraints of a Storage node. If you create a new Storage node, you should include this function in your calls. It provides all information required for the various StorageBehaviors.

source
EnergyModelsBase.constraints_level_aux — Function
constraints_level_aux(m, n::Storage, 𝒯, 𝒫, modeltype::EnergyModel)
constraints_level_aux(m, n::RefStorage{AccumulatingEmissions}, 𝒯, 𝒫, modeltype::EnergyModel)

Function for creating the Δ constraint for the level of a generic Storage node. EnergyModelsBase provides as well a method for a RefStorage{AccumulatingEmissions}.

source
EnergyModelsBase.constraints_opex_var — Function
constraints_opex_var(m, n::Node, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
constraints_opex_var(m, n::Storage, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
constraints_opex_var(m, n::Sink, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)

Function for creating the constraint on the variable OPEX of a generic Node, Storage, and Sink.

This function serves as fallback option if no other method is specified for a Node.

In the case of a Storage node, the fallback option includes variable OPEX for charge, level, and discharge if the node has the corresponding storage parameter. The individual contributions are in all situations calculated based on the installed capacities.

In the case of a Sink node, the variable OPEX is calculate through the penalties for both surplus and deficit.

source
EnergyModelsBase.constraints_opex_fixed — Function
constraints_opex_fixed(m, n::Node, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
constraints_opex_fixed(m, n::Storage, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
constraints_opex_fixed(m, n::Sink, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)

Function for creating the constraint on the fixed OPEX of a generic Node, Storage, and Sink.

This function serves as fallback option if no other method is specified for a Node.

The fallback option for Storage nodes includes fixed OPEX for charge, level, and discharge if the node has the corresponding storage parameter. The individual contributions are in all situations calculated based on the installed capacities.

In the case of a Storage node, the fallback option includes fixed OPEX for charge, level, and discharge if the node has the corresponding storage parameter. The individual contributions are in all situations calculated based on the installed capacities.

In the case of a Sink node, the fallback option fixes the value of the variable :opex_fixed to 0.

source
EnergyModelsBase.constraints_data — Function
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::EmissionsEnergy)
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::EmissionsProcess)
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::CaptureEnergyEmissions)
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::CaptureProcessEmissions)
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::CaptureProcessEnergyEmissions)

Constraints functions for calculating both the emissions and amount of CO₂ captured in the process. If the data ia a CaptureData, it provides the constraint for the variable :flow_out of CO₂.

There exist several configurations:

source
constraints_data(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel, data::Data)

Fallback option when data is specified, but it is not desired to add the constraints through this function. This is, e.g., the case for EnergyModelsInvestments as the capacity constraint has to be replaced.

source

In addition, auxiliary functions are introduced for the calculation of the previous level of storage nodes. These auxiliary functions provide the user with simple approaches for calculating the level balances.

EnergyModelsBase.previous_level — Function
previous_level(
    m,
    n::Storage,
    prev_pers::PreviousPeriods,
    cyclic_pers::CyclicPeriods,
    modeltype::EnergyModel,
)

Returns the level used as previous level of a Storage node depending on the type of PreviousPeriods.

The basic functionality is used in the case when the previous operational period is a TimePeriod, in which case it just returns the previous operational period.

source
previous_level(
    m,
    n::Storage,
    prev_pers::PreviousPeriods{<:NothingPeriod, Nothing, Nothing},
    cyclic_pers::CyclicPeriods,
    modeltype::EnergyModel,
)

When the previous operational and representative period are Nothing, the function returns the cyclic constraints within a strategic period. This is achieved through calling a subfunction previous_level_sp to avoid method ambiguities.

source
previous_level(
    m,
    n::Storage,
    prev_pers::PreviousPeriods{<:NothingPeriod, Nothing, Nothing},
    cyclic_pers::CyclicPeriods,
    modeltype::EnergyModel,
)

When the previous operational and representative period are Nothing and the storage node is an AccumulatingEmissions storage node, the function returns a value of 0.

source
previous_level(
    m,
    n::Storage,
    prev_pers::PreviousPeriods{<:NothingPeriod, <:TS.AbstractRepresentativePeriod, Nothing},
    cyclic_pers::CyclicPeriods,
    modeltype::EnergyModel,
)

When the previous operational period is Nothing, the previous representative period an AbstractRepresentativePeriod and the last period is an AbstractRepresentativePeriod, then the time structure does include RepresentativePeriods.

The cyclic default constraints returns the value at the end of the previous representative period while accounting for the number of repetitions of the representative period.

source
previous_level(
    m,
    n::Storage{CyclicRepresentative},
    prev_pers::PreviousPeriods{<:NothingPeriod, <:TS.AbstractRepresentativePeriod, Nothing},
    cyclic_pers::CyclicPeriods,
    modeltype::EnergyModel,
)

When the previous operational period is Nothing and the previous representative period an AbstractRepresentativePeriod then the time structure does include RepresentativePeriods.

The cyclic constraint for a CyclicRepresentative storage nodereturns the value at the end of the current representative period.

source
EnergyModelsBase.previous_level_sp — Function
previous_level_sp(
    m,
    n::Storage{<:Cyclic},
    cyclic_pers::CyclicPeriods,
    modeltype
)

Returns the previous period in the case of the first operational period (in the first representative period) of a strategic period.

The default functionality in the case of a Cyclic storage node in a TimeStructure without RepresentativePeriods returns the last operational period in the strategic period.

source
previous_level_sp(
    m,
    n::Storage{CyclicStrategic},
    cyclic_pers::CyclicPeriods{<:TS.AbstractRepresentativePeriod},
    modeltype::EnergyModel,
)

When a CyclicStrategic Storage node is coupled with a TimeStructure containing RepresentativePeriods, then the function calculates the level at the beginning of the first representative period through the changes in the level in the last representative period.

source
previous_level_sp(
    m,
    n::Storage{CyclicRepresentative},
    cyclic_pers::CyclicPeriods{<:TS.AbstractRepresentativePeriod},
    modeltype::EnergyModel,
)

When a CyclicRepresentative Storage node is coupled with a TimeStructure containing RepresentativePeriods, then the function returns the previous level as the level at the end of the current representative period.

source

Utility functions

The following function can be used in newly developed nodes to scale from operational to strategic periods. The function replaced the previously used function [EMB.multiple] which is still available with a deprecation warning.

EnergyModelsBase.scale_op_sp — Function
scale_op_sp(t_inv::TS.AbstractStrategicPeriod, t::TS.TimePeriod)

Provides a simplified function for returning the multiplication

$duration(t) * multiple\_strat(t\_inv, t) * probability(t)$

when operational periods are coupled with strategic periods. It is used to scale the value provided for operational periods to a duration of 1 of a strategic period.

Example

# Time structure representing to strategic periods with a duration of 4 years each and
# including a single week with hourly resolution
ts = TwoLevel(2, 4, SimpleTimes(168,1); op_per_strat=8760.0);

# Extracting the first strategic period and its first operational period
t_inv = first(strat_periods(ts))
t = first(t_inv)

# Calculating the value as 52.14 (number of weeks in a year)
scale_op_sp(t_inv, t)
source