Docstrings · EnergyModelsInvestments.jl

EnergyModelsInvestments.EnergyModelsInvestments — Module

Main module for EnergyModelsInvestments.

This module implements functionalities allowing to run investment analysis.

It is in its current version extending EnergyModelsBase and cannot be used as a stand-alone module.

The extension EMIGeoExt includes furthermore the investment options for transmission modes as described in EnergyModelsGeography.

EnergyModelsInvestments.AbstractInvData — Type

AbstractInvData

Supertype for investment data for nodal investments.

EnergyModelsInvestments.AbstractInvestmentModel — Type

An abstract investment model type.

This abstract model type should be used when creating additional EnergyModel types that should utilize investments. An example for additional types is given by the inclusion of, e.g., SDDP.

EnergyModelsInvestments.BinaryInvestment — Type

BinaryInvestment <: Investment

Binary investment in a given capacity with binary variables. The chosen capacity within a strategic period is given by the field cap.

Binary investments introduce one binary variable for each strategic period.

Fields

cap::TimeProfile is the capacity used for the fixed investments.

EnergyModelsInvestments.BinaryInvestment — Method

When the field cap is not included, it is assumed that its value is FixedProfile(0). This behavior is only for allowing the legacy constructor to work, while it will be removed in the near future.

EnergyModelsInvestments.ContinuousInvestment — Type

ContinuousInvestment <: Investment

Continuous investment between a lower and upper bound.

Fields

min_add::TimeProfile is the minimum added capacity in a strategic period. In the case of ContinuousInvestment, this implies that the model must invest at least in this capacity in each strategic period.
max_add::TimeProfile is the maximum added capacity in a strategic period.

EnergyModelsInvestments.ContinuousInvestment — Method

When the fields min_add and max_add are not included, it is assumed that their values are FixedProfile(0). This behavior is only for allowing the legacy constructor to work, while it will be removed in the near future.

EnergyModelsInvestments.DiscreteInvestment — Type

DiscreteInvestment <: Investment

Discrete investment with integer variables using an increment. The increment for the discrete investment can be different for the individual strategic periods.

Discrete investments introduce one integer variable for each strategic period.

Fields

increment::TimeProfile is the used increment.

EnergyModelsInvestments.DiscreteInvestment — Method

When the field increment is not included, it is assumed that its value is FixedProfile(0). This behavior is only for allowing the legacy constructor to work, while it will be removed in the near future.

EnergyModelsInvestments.FixedInvestment — Type

FixedInvestment <: Investment

Fixed investment in a given capacity. The model is forced to invest in the capacity provided by the field cap.

Fields

cap::TimeProfile is capacity used for the fixed investments.

EnergyModelsInvestments.FixedInvestment — Method

EnergyModelsInvestments.Investment — Type

Investment

Investment type traits for nodes. The investment type corresponds to the chosen investment mode and includes the required input.

EnergyModelsInvestments.InvestmentData — Type

Abstract type for the extra data for investing in technologies.

EnergyModelsInvestments.InvestmentModel — Type

A concrete basic investment model type based on the standard OperationalModel as declared in EnergyModelsBase. The concrete basic investment model is similar to an OperationalModel, but allows for investments and additional discounting of future years.

Fields

emission_limit::Dict{<:ResourceEmit, <:TimeProfile} are the emission caps for the different emissions types considered.
emission_price::Dict{<:ResourceEmit, <:TimeProfile} are the prices for the different emissions types considered.
co2_instance is a ResourceEmit and corresponds to the type used for CO₂.
r::Float64 is the discount rate in the investment optimization.

EnergyModelsInvestments.LifetimeMode — Type

LifetimeMode

Supertype for the lifetime mode.

EnergyModelsInvestments.NoStartInvData — Type

NoStartInvData <: AbstractInvData

Investment data in which the initial capacity is not specified in the InvestmentData. Instead, the initial capacity is inferred from the capacity of the technology.

Fields

capex::TimeProfile is the capital costs for investing in a capacity. The value is relative to the added capacity.
max_inst::TimeProfile is the maximum installed capacity in a strategic period.
inv_mode::Investment is the chosen investment mode for the technology. The following investment modes are currently available: BinaryInvestment, DiscreteInvestment, ContinuousInvestment, SemiContinuousInvestment or FixedInvestment.
life_mode::LifetimeMode is type of handling the lifetime. Several different alternatives can be used: UnlimitedLife, StudyLife, PeriodLife or RollingLife.

EnergyModelsInvestments.PeriodLife — Type

PeriodLife <: LifetimeMode

The investment is considered to last only for the strategic period. The excess lifetime is considered in the rest value. If the lifetime is lower than the length of the period, reinvestment is considered as well.

Fields

lifetime::TimeProfile is the chosen lifetime of the technology.

EnergyModelsInvestments.PeriodLife — Method

When the field lifetime is not included, it is assumed that its value is FixedProfile(0). This behavior is only for allowing the legacy constructor to work, while it will be removed in the near future.

EnergyModelsInvestments.RollingLife — Type

RollingLife <: LifetimeMode

The investment is rolling to the next strategic periods and it is retired at the end of its lifetime or the end of the previous strategic period if its lifetime ends between two periods.

Fields

lifetime::TimeProfile is the chosen lifetime of the technology.

EnergyModelsInvestments.RollingLife — Method

EnergyModelsInvestments.SemiContiInvestment — Type

SemiContiInvestment <: Investment

Supertype for semi-continuous investments, that is the added capacity is either zero or between a minimum and a maximum value.

Semi-continuous investments introduce one binary variable for each strategic period.

EnergyModelsInvestments.SemiContinuousInvestment — Type

SemiContinuousInvestment <: Investment

Semi-continuous investments, that is the added capacity is either zero or between a minimum and a maximum value. In this subtype, the cost is crossing the origin, that is the CAPEX is still linear dependent on the

Semi-continuous investments introduce one binary variable for each strategic period.

Fields

min_add::TimeProfile is the minimum added capacity in a strategic period. In the case of SemiContinuousInvestment, this implies that the model must invest at least in this capacity in each strategic period. in this capacity in each strategic period where the model decides to invest. The model can also choose not too invest at all.
max_add::TimeProfile is the maximum added capacity in a strategic period.

EnergyModelsInvestments.SemiContinuousInvestment — Method

EnergyModelsInvestments.SemiContinuousOffsetInvestment — Type

SemiContinuousOffsetInvestment <: Investment

Semi-continuous investments, that is the added capacity is either zero or between a minimum and a maximum value. In this subtype, the cost is not crossing the origin. Instead, there is an offset (y- intercept) in the variable capex_cap, that is its value is larger or smaller than 0 at an invested capacity of 0 given by the field capex_offset. This allows to the user to use different slopes, and hence, account for economy of scales.

Semi-continuous investments introduce one binary variable for each strategic period.

Fields

max_add::TimeProfile is the maximum added capacity in a strategic period.
min_add::TimeProfile is the minimum added capacity in a strategic period. In the case of SemiContinuousOffsetInvestment, this implies that the model must invest at least in this capacity in each strategic period. in this capacity in each strategic period where the model decides to invest. The model can also choose not too invest at all.
capex_offset::TimeProfile is offset for the CAPEX in a strategic period.

EnergyModelsInvestments.SemiContinuousOffsetInvestment — Method

When the fields min_add, max_add, and capex_offset are not included, it is assumed that their values are FixedProfile(0). This behavior is only for allowing the legacy constructor to work, while it will be removed in the near future.

EnergyModelsInvestments.SingleInvData — Type

SingleInvData <: InvestmentData

Extra investment data for type investments. The extra investment data has only a single field in which AbstractInvData has to be added.

The advantage of separating AbstractInvData from the InvestmentData node is to allow easier separation of EnergyModelsInvestments and EnergyModelsBase and provides the user with the potential of introducing new capacities for types.

Fields

cap::AbstractInvData is the investment data for the capacity.

When multiple inputs are provided, a constructor directly creates the corresponding AbstractInvData.

Fields

capex::TimeProfile is the capital costs for investing in a capacity. The value is relative to the added capacity.
max_inst::TimeProfile is the maximum installed capacity in a strategic period.
initial::Real is the initial capacity. This results in the creation of a SingleInvData type for the investment data.
inv_mode::Investment is the chosen investment mode for the technology. The following investment modes are currently available: BinaryInvestment, DiscreteInvestment, ContinuousInvestment, SemiContinuousInvestment or FixedInvestment.
life_mode::LifetimeMode is type of handling the lifetime. Several different alternatives can be used: UnlimitedLife, StudyLife, PeriodLife or RollingLife. If life_mode is not specified, the model assumes an UnlimitedLife.

EnergyModelsInvestments.StartInvData — Type

StartInvData <: AbstractInvData

Investment data in which the initial capacity is specified in the InvestmentData. The structure is similiar to NoStartInvData with the addition of the field initial::Real, see below.

Fields in addition to NoStartInvData

initial::Real is the initial capacity.

EnergyModelsInvestments.StorageInvData — Type

StorageInvData <: InvestmentData

Extra investment data for storage investments. The extra investment data for storage investments can, but does not require investment data for the charge capacity of the storage (charge), increasing the storage capacity (level), or the doscharge capacity of the storage (discharge).

It uses the macro @kwdef to use keyword arguments and default values. Hence, the names of the parameters have to be specified.

Fields

charge::Union{AbstractInvData, Nothing} is the investment data for the charge capacity.
level::Union{AbstractInvData, Nothing} is the investment data for the level capacity.
discharge::Union{AbstractInvData, Nothing} is the investment data for the discharge capacity.

EnergyModelsInvestments.StudyLife — Type

StudyLife <: LifetimeMode

The investment lasts for the whole study period with adequate reinvestments at the end of the lifetime and considering the rest value.

Fields

lifetime::TimeProfile is the chosen lifetime of the technology.

EnergyModelsInvestments.StudyLife — Method

EnergyModelsInvestments.UnlimitedLife — Type

UnlimitedLife <: LifetimeMode

The investment's life is not limited. The investment costs do not consider any reinvestment or rest value.

EnergyModelsBase.check_node_data — Method

EMB.check_node_data(
    n::EMB.Node,
    data::InvestmentData,
    𝒯,
    modeltype::AbstractInvestmentModel,
    check_timeprofiles::Bool
)

Performs various checks on investment data for standard nodes.

Checks

Each node can only have a single InvestmentData.
All checks incorporated in the function check_inv_data.

EnergyModelsBase.check_node_data — Method

EMB.check_node_data(
    n::Storage,
    data::InvestmentData,
    𝒯,
    modeltype::AbstractInvestmentModel,
    check_timeprofiles::Bool,
)

Performs various checks on investment data for standard nodes. It is similar to the standard check nodes functions, but adds checks on

Checks

Each node can only have a single InvestmentData.
The InvestmentData must be StorageInvData.
For each individual investment field all checks incorporated in the function check_inv_data.

EnergyModelsBase.constraints_capacity_installed — Method

EMB.constraints_capacity_installed(
    m,
    n::EMB.Node,
    𝒯::TimeStructure,
    modeltype::AbstractInvestmentModel,
)

When the modeltype is an investment model, the function introduces the related constraints for the capacity expansion. The investment mode and lifetime mode are used for adding constraints.

The default function only accepts nodes with SingleInvData. If you have several capacities for investments, you have to dispatch specifically on the node type. This is implemented for Storage nodes.

EnergyModelsBase.constraints_capacity_installed — Method

EMB.constraints_capacity_installed(
    m,
    n::Storages,
    𝒯::TimeStructure,
    modeltype::AbstractInvestmentModel,
)

When the modeltype is an investment model and the node is a Storage node, the function introduces the related constraints for the capacity expansions for the fields :charge, :level, and :discharge. This requires the utilization of the StorageInvData investment type, in which the investment mode and lifetime mode are used for adding constraints for each capacity.

EnergyModelsBase.objective — Method

EMB.objective(m, 𝒩, 𝒯, 𝒫, modeltype::AbstractInvestmentModel)

Create objective function overloading the default from EMB for AbstractInvestmentModel.

Maximize Net Present Value from investments (CAPEX) and operations (OPEX and emission costs)

TODO:

Consider adding contributions from

revenue (as positive variable, adding positive)
maintenance based on usage (as positive variable, adding negative)

These variables would need to be introduced through the package SparsVariables.

Both are not necessary, as it is possible to include them through the OPEX values, but it would be beneficial for a better separation and simpler calculations from the results.

EnergyModelsBase.variables_capex — Method

EMB.variables_capex(m, 𝒩, 𝒯, 𝒫, modeltype::AbstractInvestmentModel)

Create variables for the capital costs for the invesments in storage and technology nodes.

Additional variables for investment in capacity:

:cap_capex - CAPEX costs for a technology
:cap_current - installed capacity for storage in each strategic period
:cap_add - added capacity
:cap_rem - removed capacity
:cap_invest_b - binary variable whether investments in capacity are happening
:cap_remove_b - binary variable whether investments in capacity are removed

Additional variables for investment in storage:

:stor_level_capex - CAPEX costs for increases in the capacity of a storage
:stor_level_current - installed capacity for storage in each strategic period
:stor_level_add - added capacity
:stor_level_rem - removed capacity
:stor_level_invest_b - binary variable whether investments in capacity are happening
:stor_level_remove_b - binary variable whether investments in capacity are removed
:stor_charge_capex - CAPEX costs for increases in the rate of a storage
:stor_charge_current - installed rate for storage in each strategic period
:stor_charge_add - added rate
:stor_charge_rem - removed rate
:stor_charge_invest_b - binary variable whether investments in rate are happening
:stor_charge_remove_b - binary variable whether investments in rate are removed

EnergyModelsInvestments.InvData — Method

InvData(;
    capex_cap::TimeProfile,
    cap_max_inst::TimeProfile,
    cap_max_add::TimeProfile,
    cap_min_add::TimeProfile,
    inv_mode::Investment = ContinuousInvestment(),
    cap_start::Union{Real, Nothing} = nothing,
    cap_increment::TimeProfile = FixedProfile(0),
    life_mode::LifetimeMode = UnlimitedLife(),
    lifetime::TimeProfile = FixedProfile(0),
)

Legacy constructor for a InvData.

The new storage descriptions allows now for a reduction in functions which is used to make EnergModelsInvestments less dependent on EnergyModelsBase.

The core changes to the existing structure is the move of the required parameters to the type Investment (e.g., the minimum and maximum added capacity is only required for investment mdodes that require these parameters) as well as moving the lifetime to the type [LifetimeMode], when required..

See the documentation for further information regarding how you can translate your existing model to the new model.

EnergyModelsInvestments.InvDataStorage — Method

InvDataStorage(;
    #Investment data related to storage power
    capex_rate::TimeProfile,
    rate_max_inst::TimeProfile,
    rate_max_add::TimeProfile,
    rate_min_add::TimeProfile,
    capex_stor::TimeProfile,
    stor_max_inst::TimeProfile,
    stor_max_add::TimeProfile,
    stor_min_add::TimeProfile,
    inv_mode::Investment = ContinuousInvestment(),
    rate_start::Union{Real, Nothing} = nothing,
    stor_start::Union{Real, Nothing} = nothing,
    rate_increment::TimeProfile = FixedProfile(0),
    stor_increment::TimeProfile = FixedProfile(0),
    life_mode::LifetimeMode = UnlimitedLife(),
    lifetime::TimeProfile = FixedProfile(0),
)

Storage descriptions were changed in EnergyModelsBase v0.7 resulting in the requirement for rewriting the investment options for Storage nodes.

See the documentation for further information regarding how you can translate your existing model to the new model.

EnergyModelsInvestments.TransInvData — Method

InvData(; capextrans::TimeProfile, transmaxinst::TimeProfile, transmaxadd::TimeProfile, transminadd::TimeProfile, invmode::Investment = ContinuousInvestment(), transstart::Union{Real, Nothing} = nothing, transincrement::TimeProfile = FixedProfile(0), capextransoffset::TimeProfile = FixedProfile(0), )

Legacy constructor for a InvData.

The new storage descriptions allows now for a reduction in functions which is used to make EnergModelsInvestments less dependent on EnergyModelsBase.

See the documentation for further information regarding how you can translate your existing model to the new model.

EnergyModelsInvestments.add_investment_constraints — Method

add_investment_constraints(
    m,
    element,
    inv_data::AbstractInvData,
    cap,
    prefix,
    𝒯ᴵⁿᵛ::TS.StratPeriods,
    disc_rate::Float64,
)

Core function for introducing constraints on the investments. The constraints include introducing bounds on the available capacities as well as the calculation of the CAPEX.

The function calls two additional subroutines, set_capacity_installation and set_capacity_cost which are used for introducing bounds on the investment variables and calculating the CAPEX contribution of each investments. The utilization of subroutines allows the introduction of dispatch for the individual investment and lifetime options.

Arguments

m: the JuMP model instance.
element: the element for which investment constraints should be added. Any potential element can be used. In EnergyModelsBase, the individual element is either a Node or a TransmissionMode.
inv_data::AbstractInvData: the investment data for the node and capacity cap.
prefix: the prefix used for variables for this element. This argument is used for extracting the individual investment variables.
cap: the field that is used if several capacities are provided.
𝒯ᴵⁿᵛ::TS.StratPeriods: the strategic periods structure.
disc_rate: the discount rate used in the lifetime calculation for reinvestment and end of life calculations.

EnergyModelsInvestments.capex — Method

capex(n::AbstractInvData, t_inv)

Returns the CAPEX of the investment data inv_data in investment period t_inv.

EnergyModelsInvestments.capex — Method

capex(inv_data::AbstractInvData)

Returns the CAPEX of the investment data inv_data as TimeProfile.

EnergyModelsInvestments.capex_offset — Method

capex_offset(inv_data::AbstractInvData, t_inv)

Returns the offset of the CAPEX of the investment data inv_data in investment period t_inv.

EnergyModelsInvestments.capex_offset — Method

capex_offset(inv_data::AbstractInvData)

Returns the offset of the CAPEX of the investment data inv_data as TimeProfile.

EnergyModelsInvestments.capex_offset — Method

capex_offset(inv_mode::SemiContinuousOffsetInvestment, t_inv)

Returns the offset of the CAPEX of the investment mode inv_mode in investment period t_inv.

EnergyModelsInvestments.capex_offset — Method

capex_offset(inv_mode::SemiContinuousOffsetInvestment)

Returns the offset of the CAPEX of the investment mode inv_mode as TimeProfile.

EnergyModelsInvestments.check_inv_data — Method

check_inv_data(
    inv_data::AbstractInvData,
    capacity_profile::TimeProfile,
    𝒯,
    message::String,
    check_timeprofiles::Bool,
)

Performs various checks on investment data introduced within EnergyModelsInvestments

Checks

For each field with TimeProfile:
- If the TimeProfile is a StrategicProfile, it will check that the profile is in accordance with the TimeStructure
- TimeProfiles in InvestmentData cannot include OperationalProfile, RepresentativeProfile, or ScenarioProfile as this is not allowed through indexing on the TimeProfile.
The field :min_add has to be less than :max_add if the investment mode is given by ContinuousInvestment or SemiContiInvestment.
Existing capacity cannot be larger than :max_inst capacity in the beginning. If NoStartInvData is used, it also checks that the the TimeProfile capacity_profile is not including OperationalProfile, RepresentativeProfile, or ScenarioProfile to avoid indexing problems.

EnergyModelsInvestments.discount_rate — Method

discount_rate(modeltype::AbstractInvestmentModel)

Returns the discount rate of EnergyModel modeltype

EnergyModelsInvestments.get_var_add — Method

get_var_add(m, prefix::Symbol, element)