Internal functions

create_element(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel)
create_element(m, l::Link, 𝒯, 𝒫, modeltype::EnergyModel)

Default fallback method for an element type if no other method is defined for a given type. This function calls subfunctions to maintain backwards compatibility and simplify the differentiation in extension packages.

EnergyModelsBase provides the user with two element types, Link and Node:

• Node - the subfunction is create_node.
• Link - the subfunction is create_link.

create_link(m, l::Link, 𝒯, 𝒫, modeltype::EnergyModel)
create_link(m, l::Direct, 𝒯, 𝒫, modeltype::EnergyModel)
create_link(m, 𝒯, 𝒫, l::Link, modeltype::EnergyModel, formulation::Formulation)

Set the constraints for a Link.

variables_element(m, 𝒩ˢᵘᵇ::Vector{<:Node}, 𝒯, modeltype::EnergyModel)
variables_element(m, ℒˢᵘᵇ::Vector{<:Link}, 𝒯, modeltype::EnergyModel)

Default fallback method for a vector of elements if no other method is defined for a given vector of element subtypes. This function calls subfunctions to maintain backwards compatibility and simplify the differentiation in extension packages.

EnergyModelsBase provides the user with two element types, Link and Node:

• Node - the subfunction is variables_node.
• Link - the subfunction is variables_link.

variables_ext_data(m, _::Type{<:ExtensionData}, 𝒳::Vector{<:AbstractElement}, 𝒯, 𝒫, modeltype::EnergyModel)

Default fallback method for the variables creation for a data type of a Vector{<:AbstractElement} 𝒳 if no other method is defined. The default method does not specify any variables.

objective(m, 𝒳ᵛᵉᶜ, 𝒫, 𝒯, modeltype::EnergyModel)

Create the objective for the optimization problem for a given modeltype.

The default option includes to the objective function:

• the variable and fixed operating expenses for the individual nodes,
• the variable and fixed operating expenses for the individual links, and
• the cost for the emissions.

The values are not discounted.

This function serve as fallback option if no other method is specified for a specific modeltype.

objective_operational(m, 𝒳, 𝒯ᴵⁿᵛ::TS.AbstractStratPers, modeltype::EnergyModel)

Create JuMP expressions indexed over the investment periods 𝒯ᴵⁿᵛ for different elements 𝒳. The expressions correspond to the operational expenses of the different elements. The expressions are not discounted and do not take the duration of the investment periods into account.

By default, objective expressions are included for:

• 𝒳 = 𝒩::Vector{<:Node}. In the case of a vector of nodes, the function returns the sum of the variable and fixed OPEX for all nodes whose method of the function has_opex returns true.
• 𝒳 = 𝒩::Vector{<:Link}. In the case of a vector of links, the function returns the sum of the variable and fixed OPEX for all links whose method of the function has_opex returns true.
• 𝒳 = 𝒩::Vector{<:Resource}. In the case of a vector of resources, the function returns the costs associated to the emissions using the function emission_price.

emissions_operational(m, 𝒳, 𝒫ᵉᵐ, 𝒯, modeltype::EnergyModel)

Create JuMP expressions indexed over the operational periods 𝒯 for different elements 𝒳. The expressions correspond to the total emissions of a given element type.

By default, emissions expressions are included for:

• 𝒳 = 𝒩::Vector{<:Node}. In the case of a vector of nodes, the function returns the sum of the emissions of all nodes whose method of the function has_emissions returns true. These nodes should be automatically identified without user intervention.
• 𝒳 = 𝒩::Vector{<:Link}. In the case of a vector of links, the function returns the sum of the emissions of all links whose method of the function has_emissions returns true.

constraints_emissions(m, 𝒳ᵛᵉᶜ, 𝒫, 𝒯, modeltype::EnergyModel)

Create constraints for the emissions accounting for both operational and strategic periods.

constraints_elements(m, 𝒳::Vector{<:AbstractElement}, 𝒳ᵛᵉᶜ, 𝒫, 𝒯, modeltype::EnergyModel)

Loop through all entries of the elements vector and call the subfunction create_element for creating the internal constraints of the entries of the elements vector.

constraints_couple(m, 𝒩::Vector{<:Node}, ℒ::Vector{<:Link}, 𝒫, 𝒯, modeltype::EnergyModel)
constraints_couple(m, ℒ::Vector{<:Link}, 𝒩::Vector{<:Node}, 𝒫, 𝒯, modeltype::EnergyModel)

Create the couple constraints in EnergyModelsBase.

Only couplings between two types are introducded in energy models base. A fallback solution is available for the coupling between AbstractElements while a method is implemented for the coupling between a Link and a Node.

constraints_level_iterate(
    m,
    n::Storage,
    prev_pers::PreviousPeriods,
    cyclic_pers::CyclicPeriods,
    per,
    ts::RepresentativePeriods,
    modeltype::EnergyModel,
)

Iterate through the individual time structures of a Storage node. This iteration function should in general allow for all necessary functionality for incorporating modifications.

In the case of RepresentativePeriods, this is achieved through calling the function constraints_level_rp to introduce, e.g., cyclic constraints as it is in the default case.

constraints_level_iterate(
    m,
    n::Storage,
    prev_pers::PreviousPeriods,
    per,
    ts::OperationalScenarios,
    modeltype::EnergyModel,
)

In the case of OperationalScenarios, this is achieved through calling the function constraints_level_scp. In the default case, no constraints are added.

constraints_level_iterate(
    m,
    n::Storage,
    prev_pers::PreviousPeriods,
    per,
    ts::SimpleTimes,
    modeltype::EnergyModel,
)

In the case of SimpleTimes, the iterator function is at its lowest level. In this situation,the previous level is calculated using the function previous_level and used for the storage balance. The the approach for calculating the previous_level is depending on the types in the parameteric type PreviousPeriods.

In addition, additional bounds can be included on the initial level within an operational period.

constraints_level_rp(m, n::Storage, per, modeltype::EnergyModel)

Provides additional contraints for representative periods.

The default approach is to set the total change in all representative periods within a strategic period to 0. This implies that the Storage node cannot accumulate energy between individual strategic periods.

constraints_level_rp(m, n::Storage{<:Accumulating}, per, modeltype::EnergyModel)

When a Storage{<:Accumulating} is used, the cyclic constraint for restricting the level change within a strategic period to 0 (through setting the sum of :stor_level_Δ_rp within a strategic period to 0) is not implemented as accumulation within a strategic period is desirable.

This implies that Accumulating behaviours require the developer to introduce the function previous_level in the case of prev_pers = PreviousPeriods{<:NothingPeriod, Nothing, Nothing}.

constraints_level_rp(m, n::Storage{CyclicRepresentative}, per, modeltype::EnergyModel)

When a Storage{CyclicRepresentative} is used, the change in the representative period is constrained to 0.

constraints_level_scp(m, n::Storage, per, modeltype::EnergyModel)

Provides additional constraints for scenario periods.

The default approach is to not provide any constraints.

constraints_level_scp(m, n::Storage{<:Cyclic}, per::TS.AbstractStrategicPeriod, modeltype::EnergyModel)

When a Storage{<:Cyclic} is used in a time structure without RepresentativeProfile, the final level in an operational scenario is constrained to be the same in all operational scenarios for the cyclic constraints.

constraints_level_scp(m, n::Storage{CyclicRepresentative}, per::TS.AbstractRepresentativePeriod, modeltype::EnergyModel)

When a Storage{CyclicRepresentative} is used, the final level in an operational scenario is constrained to be the same in all operational scenarios.

This function is required in addition to enforce the CyclicRepresentative constraint.

constraints_level_bounds(
    m,
    n::Storage,
    t::TS.TimePeriod,
    prev_pers::TS.TimePeriod,
    modeltype::EnergyModel,
)

Provides bounds on the initial storage level in an operational period to account for the level being modelled at the end of the operational periods.

The default approach is to not provide bounds.

constraints_level_bounds(
    m,
    n::Storage,
    t::TS.TimePeriod,
    cyclic_pers::CyclicPeriods{<:TS.AbstractRepresentativePeriod},
    modeltype::EnergyModel,
)

When representative periods are used and the previous operational period is nothing, then bounds are incorporated to avoid that the initial level storage level is violating the maximum and minimum level.

variables_capacity(m, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)
variables_capacity(m, ℒ::Vector{<:Link}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)

Declaration of different capacity variables for the element types introduced in EnergyModelsBase. EnergyModelsBase introduces two elements for an energy system, and hence, provides the user with two individual methods:

variables_flow(m, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)
variables_flow(m, ℒ::Vector{<:Link}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)

Declaration of flow OPEX variables for the element types introduced in EnergyModelsBase. EnergyModelsBase introduces two elements for an energy system, and hence, provides the user with two individual methods:

By default, all nodes 𝒩 and links ℒ only allow for unidirectional flow. You can specify bidirectional flow through providing a method to the function is_unidirectional for new link/node types.

variables_opex(m, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)
variables_opex(m, ℒ::Vector{<:Link}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)

Declaration of different OPEX variables for the element types introduced in EnergyModelsBase. EnergyModelsBase introduces two elements for an energy system, and hence, provides the user with two individual methods:

variables_capex(m, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)
variables_capex(m, ℒ::Vector{<:Link}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)

Declaration of different capital expenditures variables for the element types introduced in EnergyModelsBase. EnergyModelsBase introduces two elements for an energy system, and hence, provides the user with two individual methods:

The default method is empty but it is required for multiple dispatch in investment models.

variables_emission(m, ℒ::Vector{<:Node}, 𝒫, 𝒯, modeltype::EnergyModel)
variables_emission(m, ℒ::Vector{<:Link}, 𝒫, 𝒯, modeltype::EnergyModel)
variables_emission(m, 𝒯, 𝒫, modeltype::EnergyModel)

Declaration of emissions variables for the element types introduced in EnergyModelsBase as well as global emission variables. EnergyModelsBase introduces two elements for an energy system, and hence, provides the user with in total three individual methods, including the global variables:

The inclusion of node and link emissions require that the function has_emissions returns true for the given node or link. This is by default achieved for nodes through inclusion of EmissionData in nodes while links require you to explicitly provide a method for your link type.

variables_elements(m, 𝒳::Vector{<:AbstractElement}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)

Loop through all element subtypes and create variables specific to each subtype. It starts at the top level and subsequently move through the branches until it reaches a leave.

That is, for nodes, variables_element will be called on a Node before it is called on NetworkNode-nodes.

The function subsequently calls the subroutine variables_element for creating the variables only for a subset of the elements.

variables_element_ext_data(m, 𝒳::Vector{<:AbstractElement}, 𝒳ᵛᵉᶜ, 𝒯, 𝒫,modeltype::EnergyModel)

Loop through all data subtypes and create variables specific to each subtype. It starts at the top level and subsequently move through the branches until it reaches a leave.

The function subsequently calls the subroutine variables_ext_data for creating the variables for the nodes that have the corresponding data types.

check_data(case, modeltype::EnergyModel, check_timeprofiles::Bool)

Check if the case data is consistent. Use the @assert_or_log macro when testing. Currently only checking node data.

check_case_data(case)

Checks the case dictionary is in the correct format.

Checks

• The individual elements vector must be unique, that it is not possible to have two vector of nodes within the elements vector.
• Check that the coupling functions do return elements and not only an empty vector

check_model(case, modeltype::EnergyModel, check_timeprofiles::Bool)

Checks the modeltype .

Checks

• All ResourceEmits require a corresponding value in the field emission_limit.
• The emission_limit time profiles cannot have a finer granulation than StrategicProfile.

Conditional checks (if check_timeprofiles=true)

• The profiles in emission_limit have to have the same length as the number of strategic periods.
• The profiles in emission_price have to follow the time structure as outlined in check_profile.

check_elements(log_by_element, _::Vector{<:AbstractElement}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)
check_elements(log_by_element, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)
check_elements(log_by_element, ℒ::Vector{<:Link}}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Checks the individual elements vector. It has implemented methods for both Vector{<:Node} and Vector{<:Link}.

check_node(n::Node, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Check that the fields of a Node corresponds to required structure.

The default approach calls the subroutine check_node_default which provides the user with default checks for Source, NetworkNode, Availability, Storage, and Sink nodes.

check_link(n::Link, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Check that the fields of a Link corresponds to required structure. The default functionality does not check anthing, aside from the checks performed in check_elements.

check_node_default(n::Node, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

This method checks that a Node node is valid. By default, that does not include any checks.

check_node_default(n::Availability, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

This method checks that an Availability node is valid. By default, that does not include any checks.

check_node_default(n::Source, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Subroutine that can be utilized in other packages for incorporating the standard tests for a Source node.

Checks

• The field cap is required to be non-negative.
• The values of the dictionary output are required to be non-negative.
• The value of the field fixed_opex is required to be non-negative and accessible through a StrategicPeriod as outlined in the function check_fixed_opex(n, 𝒯ᴵⁿᵛ, check_timeprofiles).

check_node_default(n::NetworkNode, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Subroutine that can be utilized in other packages for incorporating the standard tests for a NetworkNode node.

Checks

• The field cap is required to be non-negative.
• The values of the dictionary input are required to be non-negative.
• The values of the dictionary output are required to be non-negative.
• The value of the field fixed_opex is required to be non-negative and accessible through a StrategicPeriod as outlined in the function check_fixed_opex(n, 𝒯ᴵⁿᵛ, check_timeprofiles).

check_node_default(n::Storage, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Subroutine that can be utilized in other packages for incorporating the standard tests for a Storage node.

Checks

• The TimeProfile of the field capacity in the type in the field charge is required to be non-negative if the chosen composite type has the field capacity.
• The TimeProfile of the field capacity in the type in the field level is required to be non-negative`.
• The TimeProfile of the field capacity in the type in the field discharge is required to be non-negative if the chosen composite type has the field capacity.
• The TimeProfile of the field fixed_opex is required to be non-negative and accessible through a StrategicPeriod as outlined in the function check_fixed_opex(n, 𝒯ᴵⁿᵛ, check_timeprofiles) for the chosen composite type.
• The values of the dictionary input are required to be non-negative.
• The specified storage Resource must be included in the dictionary input.
• The values of the dictionary output are required to be non-negative.
• The specified storage Resource must be included in the dictionary output.

check_node_default(n::Sink, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Subroutine that can be utilized in other packages for incorporating the standard tests for a Sink node.

Checks

• The field cap is required to be non-negative.
• The values of the dictionary input are required to be non-negative.
• The dictionary penalty is required to have the keys :deficit and :surplus.
• The sum of the values :deficit and :surplus in the dictionary penalty has to be non-negative to avoid an infeasible model.

check_node_data(n::Node, data::ExtensionData, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)
check_node_data(n::Node, data::EmissionsData, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Check that the included ExtensionData types of a Node correspond to required structure.

Checks EmissionsData

• Each node can only have a single EmissionsData.
• Time profiles for process emissions, if present.
• The value of the field co2_capture is required to be in the range $[0, 1]$, if CaptureData is used.

check_link_data(l::Link, data::ExtensionData, 𝒯, modeltype::EnergyModel, check_timeprofiles::Bool)

Check that the included ExtensionData types of a Link correspond to required structure.

check_fixed_opex(n, 𝒯ᴵⁿᵛ, check_timeprofiles::Bool)

Checks that the fixed opex value follows the given TimeStructure. This check requires that a function opex_fixed(n) is defined for the input n which returns a TimeProfile.

Checks

• The opex_fixed time profile cannot have a finer granulation than StrategicProfile.

Conditional checks (if check_timeprofiles=true)

• The profiles in opex_fixed have to have the same length as the number of strategic periods.

check_time_structure(x::AbstractElement, 𝒯)

Check that all fields of a AbstractElement that are of type TimeProfile correspond to the time structure 𝒯.

check_profile(fieldname, value::TimeProfile, 𝒯)

Check that an individual TimeProfile corresponds to the time structure 𝒯. It currently does not include support for identifying OperationalScenarios.

check_profile(fieldname, value::TimeProfile, ts::TimeStructure, p_msg)

Check that an individual TimeProfile corresponds to the time structure ts in strategic period sp. The function flow is designed to provide errors in all situations in which the the TimeProfile does not correspond to the chosen TimeStructure through the application of the @assert_or_log macro.

Examples for inconsistent combinations:

ts = SimpleTimes(3, 1)

# A too long OperationalProfile resulting in omitting the last 2 values
value = OperationalProfile([1, 2, 3, 4, 5])

# A too short OperationalProfile resulting in repetition of the last value once
value = OperationalProfile([1, 2])

If you use a more detailed TimeProfile than the TimeStructure, it will provide you with a warning, e.g., using RepresentativeProfile without RepresentativePeriods.

check_strategic_profile(time_profile::TimeProfile, message::String)

Function for checking that an individual TimeProfile does not include the wrong type for strategic indexing.

Checks

• TimeProfiles accessed in StrategicPeriods cannot include OperationalProfile, ScenarioProfile, or RepresentativeProfile as this is not allowed through indexing on the TimeProfile.

check_representative_profile(time_profile::TimeProfile, message::String)

Function for checking that an individual TimeProfile does not include the wrong type for representative periods indexing.

Input

• time_profile - The time profile that should be checked.
• message - A message that should be printed after the type of profile.

Checks

• TimeProfiles accessed in RepresentativePeriods cannot include OperationalProfile or ScenarioProfile as this is not allowed through indexing on the TimeProfile.

check_scenario_profile(time_profile::TimeProfile, message::String)

Function for checking that an individual TimeProfile does not include the wrong type for scenario indexing.

Checks

• TimeProfiles accessed in RepresentativePeriods cannot include OperationalProfile or ScenarioProfile as this is not allowed through indexing on the TimeProfile.

compile_logs(case, log_by_element)

Simple method for showing all log messages.

is_network_node(n::Node)

Checks whether node n is a NetworkNode node.

is_sink(n::Node)

Checks whether node n is a Sink node.

is_source(n::Node)

Checks whether node n is a Source node.

is_storage(n::Node)

Checks whether node n is a Storage node.

is_resource_emit(p::Resource)

Checks whether the Resource p is of type ResourceEmit.

has_charge_OPEX_fixed(n::Storage)

Returns logic whether the node has a charge fixed OPEX contribution.

has_charge_OPEX_var(n::Storage)

Returns logic whether the node has a charge variable OPEX contribution.

has_charge_cap(n::Storage)

Returns logic whether the node has a charge capacity.

has_discharge_OPEX_fixed(n::Storage)

Returns logic whether the node has a discharge fixed OPEX contribution.

has_discharge_OPEX_var(n::Storage)

Returns logic whether the node has a discharge variable OPEX contribution.

has_discharge_cap(n::Storage)

Returns logic whether the node has a discharge capacity.

has_level_OPEX_fixed(n::Storage)

Returns logic whether the node has a level fixed OPEX contribution.

has_level_OPEX_var(n::Storage)

Returns logic whether the node has a level variable OPEX contribution.

nodes_sub(𝒩::Array{<:Node}, sub)

Returns nodes that are of type sub for a given Array 𝒩::Array{<:Node}.

link_res(l::Link)

Return the resources transported for a given link l.

The default approach is to use the intersection of the inputs of the to node and the outputs of the from node.

link_sub(ℒ::Vector{<:Link}, n::Node)

Return connected links from the vector ℒ for a given node n as array. The first subarray corresponds to the from field, while the second to the to field.

res_em(𝒫::Array{<:Resource})
res_em(𝒫::Dict)

Returns all emission resources for a

• a given array ::Array{<:Resource}. The output is in this case an Array{<:Resource}
• a given dictionary ::Dict. The output is in this case a dictionary Dict with the correct fields

res_not(𝒩::Array{<:Resource}, res_inst)
res_not(𝒫::Dict, res_inst::Resource)

Return all resources that are not res_inst for

• a given array ::Array{<:Resource}. The output is in this case an Array{<:Resource}
• a given dictionary ::Dict. The output is in this case a dictionary Dict with the correct fields

res_sub(𝒫::Array{<:Resource}, sub = ResourceEmit)

Return resources that are of type sub for a given Array ::Array{Resource}.

collect_types(types_list)

Return a Dict of all the give types_list and their supertypes. The keys in the dictionary are the types, and their corresponding value is the number in the type hierarchy.

As an example, Node is at the top and will thus have the value 1. Types just below Node will have value 2, and so on.

sort_types(types_list::Dict)

Sort the result of collect_types and return a vector where a supertype comes before all its subtypes.