GitHub

Public interface

Additional Data for Investments

General type structure

Additional data for investment is specified when creating the nodes through subtypes of the type AbstractInvData.

This additional data is node specific, not technology specific. It is hence possible to provide different values for the same technology through different instances of said technology. EnergyModelsInvestments provides two subtypes for AbstractInvData, NoStartInvData and StartInvData as explained in the following subsection.

It is also possible to create new subtypes with changing parameters.

Introducing new subtypes

If you introduce new subtypes to AbstractInvData, it is necessary that you either incorporate the fields outlined in the following subsection with the same names, or alternatively declare methods for the functions investment_mode, EMI.lifetime_mode, EMI.lifetime, EMI.max_installed, EMI.capex, and EMI.capex_offset for the new type.

AbstractInvData subtypes

AbstractInvData subtypes area used to add the required investment data to the individual technology capacities.

The following fields have to be added for all provided types:

  • capex::TimeProfile: Capital expenditures (CAPEX) of the Node. The capital expenditures are relative to the capacity. Hence, it is important to consider the unit for both costs and the energy of the technology. The total contribution to the objective function $y$ is then given through the equation $y = \texttt{capex} \times x$ where $x$ corresponds to the invested capacity.
  • max_inst::TimeProfile: Maximum installed capacity of the Node. The maximum installed capacity is limiting the total installed capacity of the Node. It is possible to have different values for different Nodes representing the same technology. This can be useful for, e.g., the potential for wind power in different regions.
  • inv_mode::Investment: Investment mode of the Node. The individual investment modes are explained in detail in Investment types.
  • life_mode::LifetimeMode: Lifetime mode of the Node. The lifetime mode is describing how the lifetime of the node is implemented. This includes as well final values and retiring of the individual technologies. The default value is UnlimitedLife. More information can be found in LifetimeMode.

The type StartInvData allows in addition for providing the initial capacity in the first year through:

  • initial::Real: Starting capacity of the technology in the first strategic period. The starting capacity is only valid for the first strategic period. This capacity will remain present in the simulation horizon, except if retiring is desired by the model. It is not possible to provide a reducing capacity over time for the initial capacity.

while it utilizes the capacity of the technology if the value is not provided through the function EMI.start_cap.

Warning

If you do not use StartInvData, you have to provide the function EMI.start_cap for your type. Otherwise, EnergyModelsInvestments is not able to deduce the starting capcity.

AbstractInvData types have constructors that allow omitting the last field, life_mode.

Warning

All fields that are provided as TimeProfile are accessed in strategic periods. This implies that the provided TimeProfiles are not allowed to have any variations below strategic periods through, e.g. the application of OperationalProfile or RepresentativeProfile. EnergyModelsBase provides explicit checks for the time profiles which is a beneficial approach if you use EnergyModelsInvestments without EnergyModelsBase.

EnergyModelsInvestments.NoStartInvData — Type
NoStartInvData <: AbstractInvData

Investment data in which the initial capacity is not specified in the AbstractInvData. Instead, the initial capacity is inferred from the capacity of the technology through the function start_cap(element, t_inv, inv_data::AbstractInvData, cap).

Fields

source

Additional functions

EnergyModelsInvestments provides additional functions for extracting field informations from the investment data:

In addition, it provides shell functions that can be used by the user for identifying nodes with investments or extracting the investments from a given element:

EnergyModelsInvestments.has_investment — Function
has_investment(element)

Return boolean indicating whether an element shall have variables and constraints constructed for investments.

The default implementation does not have an associated method. Instead, it is only used for dispatch in other packages.

source
EnergyModelsInvestments.investment_data — Function
investment_data(element)

Return the investment data of the element.

The default implementation results in an error as this function requires an additional method for the individual elements.

source

These shell functions are not directly used by EnergyModelsInvestments, but can be useful.

Investment modes

Different investment modes are available to help represent different situations. The investment mode is included in the field inv_mode in NoStartInvData and StartInvData. The investment mode determines how the model can invest and which constraints are imposed on the investments.

Potential fields in investment modes

Investment modes are including the required fields. These fields are given below with a detailed description in the individual subsections.

  • max_add::TimeProfile: The maximum added capacity in a strategic period. The maximum added capacity is providing the limit on how fast we can expend a given technology in a strategic period. In general, this value is dependent on the potential construction time and how fast it is possible to build a technology. It is introduced for ContinuousInvestment and SemiContiInvestment modes.
  • min_add::TimeProfile: The minimum added capacity in a strategic period. The minimum added capacity is providing the lower limit on investments in a strategic period. Its meaning changes, dependent on the chosen investment mode. It is introduced for ContinuousInvestment and SemiContiInvestment modes.
  • capex_offset::TimeProfile: CAPEX offset for the SemiContinuousOffsetInvestment mode. The offset can be best described with the equation $y = \texttt{capex} \times x + \texttt{capex\_offset}$ where $x$ corresponds to the invested capacity and $y$ to the total capital cost.
  • cap_increment::TimeProfile: Increment in the case of DiscreteInvestment. The increment corresponds to the potential increase in the case of DiscreteInvestment.

Investment

Investment is the abstract supertype for all investment modes. It is used to allow for a simple extension of the potential investment modes. It is also possible for the user to define new investment modes without major changes to the core structure through specifying a new subtype of Investment.

ContinuousInvestment

ContinuousInvestment is the default investment option for all investments, if no alternative is chosen. Continuous investments implies that you can invest in any capacity specified between min_add and max_add. This implies as well that, if min_add is specified, it is necessary to invest in every strategic period in at least this capacity. This approach is the standard approach in large energy system models as it avoids binary variables. However, it may lead to nonsensical solutions, e.g., investments into a 10~MW nuclear power plant.

Warning

Defining min_add::TimeProfile for this mode of investment will lead to a forced investment of at least min_add in each period.

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.
source

BinaryInvestment

BinaryInvestment implies that one can choose to invest to achieve the specified capacity in the given strategic period, or not. The capacity of the investment cannot be adjusted by the optimization.

Warning

This investment type leads to the addition of binary variables. The number of binary variables is equal to the number of strategic periods times the number of Nodes with the BinaryInvestment mode.

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.
source

DiscreteInvestment

DiscreteInvestment allow for only a discrete increase in the capacity. This increase is specified through the field increment. Hence, it can be also dependent on the strategic period.

DiscreteInvestment can for example be used to represent investment in modular technologies that can be scaled by adding several modules together. In addition, it is beneficial to include for technologies that experience significant economy of scale. In this situation, several instances with different increment and capex can be used

Note

This investment type leads to the addition of integer variables. The number of integer variables is equal to the number of strategic periods times the number of Nodes with the DiscreteInvestment mode.

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.
source

SemiContiInvestment

SemiContiInvestment is an abstract type used for two investment modes:

  1. SemiContinuousInvestment and
  2. SemiContinuousOffsetInvestment.

These investment modes are similar with respect to how you can increase the capacity. They differ however on how the overall cost is calculated. Both investment modes are in general similar to ContinuousInvestment, but the investment is either 0 or between a minimum and maximum value. This means you can define the field min_add::TimeProfile without forcing investment in the technology. Instead, the value determines that if the model decides to invest, then it has to at least invest in the value provided through min_add. This can be also described as:

$x = 0 \lor \texttt{min\_add} \leq x \leq \texttt{max\_add}$

with $x$ corresponding to the invested capacity

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.

source
Note

These investment modes leads to the addition of binary variables. The number of binary variables is equal to the number of strategic periods times the number of Nodes with the SemiContinuousInvestment and SemiContinuousOffsetInvestment mode.

SemiContinuousInvestment

The cost function in SemiContinuousInvestment is calculated in the same way as in ContinuousInvestment. The total contribution of invested capacity $x$ to the objective function $y$ is given through the equation

$y = \texttt{capex} \times x$.

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.
source

SemiContinuousOffsetInvestment

SemiContinuousOffsetInvestment is a type of investment similar to SemiContinuousInvestment and implemented for investments in transmission infrastructure. It does differ with respect to how the costs are calculated. A SemiContinuousOffsetInvestment has an offset in the cost implemented through the the field capex_offset. This offset corresponds to the theoretical cost at an invested capacity of 0.

While SemiContinuousInvestmentutilizes the same relative cost, even if a lower limit is specified, SemiContinuousOffsetInvestment allows for the specification of an offset in the cost through the field capex_offset. This offset is an absolute cost. It corresponds to the theoretical cost at an invested capacity of 0. This changes the contribution to the cost function from

$y = \texttt{capex} \times x$

to

$y = \texttt{capex} \times x + \texttt{capex\_offset}$

where $x$ corresponds to the invested capacity and $y$ to the total capital cost.

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.
source

FixedInvestment

FixedInvestment is a type of investment where an investment in the given capacity is forced. It allows to account for the investment cost of known investments. In practice, there is however not too much use in including the fixed investment, except if one is interested in the values of the dual variables.

The fields cap_min_add, cap_max_add, and cap_increment do not have a meaning when using FixedInvestment.

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.
source

LifetimeMode

EnergyModelsInvestments allows for differing descriptions for the lifetime of a technology. A key problem is when the lifetime of a technology is not equal to the duration of strategic periods. To this end, several ways to define the lifetime of a technology are available in the package and presented below.

It is also possible for the user to define new LifetimeModes. In practice, this requires only the introduction of a new subtype to LifetimeMode as well as a single function.

Existing capacity and lifetime

The current implementation does not provide a lifetime for the existing capacity, independently if you use NoStartInvData or StartInvData. This is caused by the background of development of EnergyModelsInvestments. However, we are aware of this situation and look into potential approaches for including it. One such approach is outlined in Issue 30.

UnlimitedLife

This LifetimeMode is used when the lifetime of a Node is not limited. No reinvestment is considered by the optimization and there is also ne salvage value (or rest value) at the end of the last strategic period. Hence, the costs are the same, independent of if the investments in the Node are happening in the first strategic period (and the technology is used for, e.g, 25 years) or the last strategic period (with a usage of, e.g., 5 years) when excluding discounting effects.

UnlimitedLife is the default lifetime mode, if no other mode is specified.

StudyLife

StudyLife includes the technology for the full investigated horizon. If the Lifetime is shorter than the remaining horizon, reinvestments are considered. These reinvestments are included in the costs of the investment strategic period, but discounted to their actual value.

As an example, consider investments with a lifetime of 20 years in 2030, while the study horizon ends in 2055. In this situation, reinvestments are required in 2050 to allow for operation in the last 5 years. The CAPEX are then correspondingly adjusted to account for both discounted reinvestments and final value in 2055.

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.
source

PeriodLife

PeriodLife is used to define that the investment is only lasting for the strategic period in which it happens. Additional year of lifetime are counted as a rest value. Reinvestment inside the strategic periods are also considered in case the lifetime is shorter than the length of the strategic period.

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.
source

RollingLife

RollingLife corresponds to the classical roll-over of investments from one strategic period to the next until the end of life is reached. In general, three different cases can be differentiated:

  1. The lifetime is shorter than the duration of the strategic period. In this situation, a PeriodLife is assumed.
  2. The lifetime equals the duration of the strategic period. In this situation, the capacity is retired at the end of the strategic period
  3. The lifetime is longer than the duration of the strategic period. This leaves however a problem if the lifetime does fall in-between two strategic periods, as it would be the case for a lifetime of, e.g., 8 years and two strategic periods of, e.g, 5 years. In this case, the technology would only be available for the first 3 years of the second strategic period leaving the question on how to handle this situation. EnergyModelsInvestments retires the technology at the last full strategic period and calculates the remaining value for the technology.
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.
source