# 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`

.

`EnergyModelsInvestments.AbstractInvData`

— Type`AbstractInvData`

Supertype for investment data for nodal investments.

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.

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`Node`

s 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`

.

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`

.

All fields that are provided as `TimeProfile`

are accessed in strategic periods. This implies that the provided `TimeProfile`

s 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**

is the capital costs for investing in a capacity. The value is relative to the added capacity.`capex::TimeProfile`

is the maximum installed capacity in a strategic period.`max_inst::TimeProfile`

is the chosen investment mode for the technology. The following investment modes are currently available:`inv_mode::Investment`

`BinaryInvestment`

,`DiscreteInvestment`

,`ContinuousInvestment`

,`SemiContinuousInvestment`

or`FixedInvestment`

.is type of handling the lifetime. Several different alternatives can be used:`life_mode::LifetimeMode`

`UnlimitedLife`

,`StudyLife`

,`PeriodLife`

or`RollingLife`

.

`EnergyModelsInvestments.StartInvData`

— Type`StartInvData <: AbstractInvData`

Investment data in which the initial capacity is specified in the `AbstractInvData`

. The structure is similiar to `NoStartInvData`

with the addition of the field ** initial::Real**, see below.

**Fields in addition to NoStartInvData**

is the initial capacity.`initial::Real`

### Additional functions

`EnergyModelsInvestments`

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

`EnergyModelsInvestments.investment_mode`

— Function`investment_mode(inv_data::AbstractInvData)`

Return the investment mode of the investment data `inv_data`

. By default, all investments are continuous.

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.

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

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`

.

`EnergyModelsInvestments.Investment`

— Type`Investment`

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

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

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**

is the minimum added capacity in a strategic period. In the case of`min_add::TimeProfile`

`ContinuousInvestment`

, this implies that the model**must**invest at least in this capacity in each strategic period.is the maximum added capacity in a strategic period.`max_add::TimeProfile`

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

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 `Node`

s 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**

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

`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

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 `Node`

s 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**

is the used increment.`increment::TimeProfile`

`SemiContiInvestment`

`SemiContiInvestment`

is an abstract type used for two investment modes:

`SemiContinuousInvestment`

and`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

**. This can be also described as:**

`min_add`

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

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 `Node`

s 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**

is the minimum added capacity in a strategic period. In the case of`min_add::TimeProfile`

`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.is the maximum added capacity in a strategic period.`max_add::TimeProfile`

`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 `SemiContinuousInvestment`

utilizes 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**

is the maximum added capacity in a strategic period.`max_add::TimeProfile`

is the minimum added capacity in a strategic period. In the case of`min_add::TimeProfile`

`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.is offset for the CAPEX in a strategic period.`capex_offset::TimeProfile`

`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**

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

`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 `LifetimeMode`

s. In practice, this requires only the introduction of a new subtype to `LifetimeMode`

as well as a single function.

`EnergyModelsInvestments.LifetimeMode`

— Type`LifetimeMode`

Supertype for the lifetime mode.

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.

`EnergyModelsInvestments.UnlimitedLife`

— Type`UnlimitedLife <: LifetimeMode`

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

`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**

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

`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**

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

`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:

- The lifetime is shorter than the duration of the strategic period. In this situation, a
`PeriodLife`

is assumed. - The lifetime equals the duration of the strategic period. In this situation, the capacity is retired at the end of the strategic period
- 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**

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