abstract type TimeStructure{T<:Duration}

Abstract type representing different time structures that consists of one or more time periods.

The type 'T' gives the data type used for the duration of the time periods.

struct SimpleTimes{T} <: TimeStructure{T}

SimpleTimes(len::Integer, duration::Vector{T}) where {T<:Duration}
SimpleTimes(len::Integer, duration::Duration)
SimpleTimes(dur::Vector{T}) where {T<:Duration}

A simple time structure consisting of consecutive time periods of varying duration. SimpleTimes is always the lowest level in a TimeStruct time structure. if used.

An alternative for SimpleTimes is CalendarTimes

Example

uniform = SimpleTimes(5, 1.0) # 5 periods of equal length
varying = SimpleTimes([2, 2, 2, 4, 10]) # 5 periods of varying length

struct CalendarTimes{T} <: TimeStructure{T}

CalendarTimes(start_date, length, period)
CalendarTimes(start_date, end_date, period)
CalendarTimes(start_date, timezone, length, period)
CalendarTimes(start_date, end_date, timezone, period)

A time structure that iterates flexible calendar periods using calendar arithmetic. This time structure can be used at the lowest level of time structures similar to SimpleTimes.

Example

ts = CalendarTimes(Dates.DateTime(2023, 1, 1), 12, Dates.Month(1))
ts_zoned = CalendarTimes(Dates.DateTime(2023, 1, 1), tz"Europe/Berlin", 52, Dates.Week(1))

struct RepresentativePeriods{S<:Duration,T,OP<:TimeStructure{T}} <: TimeStructure{T}

RepresentativePeriods(len::Integer, duration::S, period_share::Vector{<:Real}, rep_periods::Vector{OP}) where {S<:Duration, T, OP<:TimeStructure{T}}
RepresentativePeriods(len::Integer, duration::S, rep_periods::TimeStructure{T}) where {S<:Duration, T}

RepresentativePeriods(duration::S, period_share::Vector{<:Real}, rep_periods::Vector{<:TimeStructure{T}}) where {S<:Duration, T}
RepresentativePeriods(duration::S, period_share::Vector{<:Real}, rep_periods::TimeStructure{T}) where {S<:Duration, T}

RepresentativePeriods(duration::S, rep_periods::Vector{<:TimeStructure{T}}) where {S<:Duration, T}

Time structure that allows a time period to be represented by one or more shorter representative time periods.

The representative periods are an ordered sequence of TimeStructures that are used for each representative period. In addition, each representative period has an associated share that specifies how much of the total duration that is attributed to it.

Example

# A year represented by two days with hourly resolution and relative shares of 0.7 and 0.3
RepresentativePeriods(8760, [0.7, 0.3], [SimpleTimes(24, 1), SimpleTimes(24,1)])
RepresentativePeriods(8760, [0.7, 0.3], SimpleTimes(24, 1))

# A year represented by two days with hourly resolution and relative shares of 0.5
RepresentativePeriods(2, 8760, SimpleTimes(24, 1))
RepresentativePeriods(8760, [SimpleTimes(24, 1), SimpleTimes(24,1)])

struct OperationalScenarios{T,OP<:TimeStructure{T}} <: TimeStructure{T}

OperationalScenarios(len::Integer, scenarios::Vector{OP}, probability::Vector{<:Real}) where {T, OP<:TimeStructure{T}
OperationalScenarios(len::Integer, oper::TimeStructure{T})

OperationalScenarios(oper::Vector{<:TimeStructure{T}}, prob::Vector)
OperationalScenarios(oper::Vector{<:TimeStructure{T}})

Time structure that have multiple scenarios where each scenario has its own time structure and an associated probability. These scenarios are in general represented as SimpleTimes.

Example

The following examples create a time structure with 2 operational scenarios corresponding to a single day with equal probability.

day = SimpleTimes(24, 1)
OperationalScenarios(2, day)
OperationalScenarios([day, day], [0.5, 0.5])
OperationalScenarios([day, day])

struct TwoLevel{S<:Duration,T,OP<:TimeStructure{T}} <: TimeStructure{T}

TwoLevel(len::Integer, duration::Vector{S}, operational::Vector{OP}, op_per_strat::Float64) where {S<:Duration, T, OP<:TimeStructure{T}}
TwoLevel(len::Integer, duration::S, oper::TimeStructure{T}; op_per_strat) where {S, T}
TwoLevel(len::Integer, oper::TimeStructure{T}; op_per_strat) where {T}

TwoLevel(duration::S, oper::Vector{OP}; op_per_strat) where {S, T, OP<:TimeStructure{T}}
TwoLevel(duration::Vector{S}, oper::TimeStructure{T}; op_per_strat) where {S, T}

TwoLevel(oper::Vector{<:TimeStructure{T}}; op_per_strat) where [T]

A time structure with two levels of time periods.

On the top level it has a sequence of strategic periods of varying duration. For each strategic period a separate time structure is used for operational decisions. Iterating the structure will go through all operational periods. It is possible to use different time units for the two levels by providing the number of operational time units per strategic time unit through the kewyord argument op_per_strat.

Potential time structures are SimpleTimes, CalendarTimes, OperationalScenarios, or RepresentativePeriods, as well as combinations of these.

_total_duration(op) / op_per_strat for op in oper

Example

# 5 years with 24 hours of operations for each year. Note that in this case we use as unit
# `hour` for both the duration of strategic periods and operational periods
TwoLevel(5, 8760, SimpleTimes(24, 1))

# The same time structure with the unit `year` for strategic periods and unit `hour` for
# operational periods
TwoLevel(5, 1, SimpleTimes(24, 1); op_per_strat=8760.0)

# All individual constructors
TwoLevel(2, ones(2), [SimpleTimes(24, 1), SimpleTimes(24, 1)], op_per_strat=8760.0)
TwoLevel(2, 1, SimpleTimes(24, 1); op_per_strat=8760.0)
TwoLevel(1, [SimpleTimes(24, 1), SimpleTimes(24, 1)]; op_per_strat=8760.0)
TwoLevel(ones(2), SimpleTimes(24, 1); op_per_strat=8760.0)

# Constructors without duration
TwoLevel([SimpleTimes(24, 1), SimpleTimes(24, 1)]; op_per_strat=8760.0)
TwoLevel(2, SimpleTimes(24, 1); op_per_strat=8760.0)

mutable struct TwoLevelTree{S,T,OP<:AbstractTreeNode{S,T}} <: TimeStructure{T}

Time structure allowing for a tree structure for the strategic level.

For each strategic node in the tree a separate time structure is used for operational decisions. Iterating the structure will go through all operational periods.

regular_tree(
    duration::S,
    branching::Vector,
    ts::OP;
    op_per_strat::Real=1.0,
) where {S, T, OP<:TimeStructure{T}}

Function for creating a regular tree with a uniform structure for each strategic period. Each strategic period is of equal length as given by duration and will have the same operational time structure ts. The vector branching specifies the number of branchings at each stage of the tree, excluding the first stage. The branches at each stage will all have equal probability.

mult_scen(scen)

Returns the multiplication factor to be used for this scenario when comparing with the overall set of operational scenarios.

If all scenarios in a set of operational scenarios are of equal duration (preferred usage), this factor is equal to one. Otherwise this factor would be equal to the ratio of the scenario with longest duration to the duration of the given scenario.

mult_repr(rp)

Returns the multiplication factor to be used for this representative period when comparing with the representative periods structure it is part of.

mult_strat(sp)

Returns the multiplication factor to be used for this strategic period when comparing the duration of the strategic period to the duration of the time structure being used for the strategic period.

probability_scen(scen)

The probability of a single scenario in a set of operational scenarios.

repr_periods(ts::TimeStructure)

This function returns a type for iterating through the individual representative periods of a TimeStructure. The type of the iterator is dependent on the type of the input TimeStructure.

When the TimeStructure is a TimeStructure, repr_periods returns a SingleReprPeriodWrapper. This corresponds to the default behavior.

When the TimeStructure is a RepresentativePeriods, repr_periods returns the iterator ReprPers.

When the TimeStructure is a StrategicPeriod, repr_periods returns the iterator StratReprPers.

When the TimeStructure is a SingleStrategicPeriod, repr_periods returns the correct behavior based on the substructure.

When the TimeStructure is a TwoLevel, repr_periods returns an Array of all StratReprPeriods.

When the TimeStructure is a StratNode, repr_periods returns the iterator StratNodeReprPers.

When the TimeStructure is a TwoLevelTree, repr_periods returns an Array of all StratNodeReprPeriods.

These are equivalent to a StratReprPeriod of a TwoLevel time structure.

opscenarios(ts::TimeStructure)

This function returns a type for iterating through the individual operational scenarios of a TimeStructure. The type of the iterator is dependent on the type of the input TimeStructure.

When the TimeStructure is a TimeStructure, opscenarios returns a SingleScenarioWrapper. This corresponds to the default behavior.

When the TimeStructure is an OperationalScenarios, opscenarios returns the iterator OpScens.

When the TimeStructure is a RepresentativePeriod with OperationalScenarios, opscenarios returns the iterator RepOpScens.

When the TimeStructure is a SingleReprPeriod, opscenarios returns the correct behavior based on the substructure.

When the TimeStructure is a RepresentativePeriods, opscenarios returns an Array of all ReprOpScenarios.

When the TimeStructure is a StrategicPeriod, opscenarios returns the iterator StratOpScens.

When the TimeStructure is a StrategicPeriod with RepresentativePeriods, opscenarios returns a vector of StratReprOpScenarios.

When the TimeStructure is a SingleStrategicPeriod, opscenarios returns the correct behavior based on the substructure.

When the TimeStructure is a TwoLevel, opscenarios returns a vector of StratOpScenarios.

When the TimeStructure is a TwoLevel with RepresentativePeriods, opscenarios returns a vector of StratReprOpScenarios.

When the TimeStructure is a StratNode, opscenarios returns the iterator StratNodeOpScens.

When the TimeStructure is a StratNodeReprPeriod with a RepresentativePeriod, opscenarios returns the iterator StratNodeReprOpScens.

When the TimeStructure is a StratNodeReprPeriod with a SingleReprPeriod, opscenarios returns the iterator StratNodeOpScens as the overall time structure does not include representative periods.

When the TimeStructure is a StratNode with RepresentativePeriods, opscenarios returns an Array of all StratNodeReprOpScenarios.

When the TimeStructure is a TwoLevelTree, opscenarios returns an Array of all StratNodeOpScenarios or StratNodeReprOpScenarios types, dependening on whether the TwoLevelTree includes RepresentativePeriods or not.

These are equivalent to a StratOpScenario and StratReprOpScenario of a TwoLevel time structure.

strat_periods(ts::TimeStructure)

This function returns a type for iterating through the individual strategic periods of a TimeStructure. The type of the iterator is dependent on the type of the input TimeStructure. The elements returned of the iterator will be subtypes of AbstractStrategicPeriod.

When the TimeStructure is a TimeStructure, strat_periods returns a SingleStrategicPeriodWrapper. This corresponds to the default behavior.

When the TimeStructure is a TwoLevel, strat_periods returns the iterator StratPers.

Example

periods = TwoLevel(5, SimpleTimes(10,1))
total_dur = sum(duration_strat(sp) for sp in strategic_periods(periods))

When the TimeStructure is a TwoLevelTree, strat_periods returns a StratTreeNodes type, which, through iteration, provides StratNode types.

These are equivalent to a StrategicPeriod of a TwoLevel time structure.

strategic_periods(ts)

Convenience constructor for strat_periods. Both names can be used interchangable.

strategic_scenarios(ts::TwoLevelTree)

This function returns a type for iterating through the individual strategic scenarios of a TwoLevelTree. The type of the iterator is dependent on the type of the input TimeStructure.

When the TimeStructure is a TimeStructure, strategic_scenarios returns a

When the TimeStructure is a TwoLevelTree, strategic_scenarios returns the iterator StrategicScenarios.

withprev(iter)

Iterator wrapper that yields (prev, t) where prev is the previous time period or nothing for the first time period.

chunk(iter, n; cyclic = false)

Iterator wrapper that yields chunks where each chunk is an iterator over at most n consecutive time periods starting at each time period of the original iterator.

It is possible to get the n consecutive time periods in a cyclic fashion, by setting cyclic to true.

chunk_duration(iter, dur)

Iterator wrapper that yields chunks based on duration where each chunk is an iterator over the following time periods until at least dur time is covered or the end is reached.

duration(t::TimePeriod)

The duration of a time period in number of operational time units.

isfirst(t::TimePeriod)

Returns true if the time period is the first in a sequence and has no previous time period

multiple(t::TimePeriod)

Returns the number of times a time period should be counted for the whole time structure.

multiple_strat(sp::StrategicPeriod, t)

Returns the number of times a time period t should be accounted for when accumulating over one single unit of strategic time.

Example

periods = TwoLevel(10, 1, SimpleTimes(24,1); op_per_strat = 8760)
for sp in strategic_periods(periods)
    hours_per_year = sum(duration(t) * multiple_strat(sp, t) for t in sp)
end

probability(t::TimePeriod)

Returns the probability associated with the time period.

FixedProfile(val)

Time profile with a constant value for all time periods.

Example

profile = FixedProfile(5)

OperationalProfile(vals::Vector{T}) where {T}

Time profile with a value that varies with the operational time period. This profile cannot be accessed using AbstractOperationalScenario, AbstractRepresentativePeriod, or AbstractStrategicPeriod.

If too few values are provided, the last provided value will be repeated.

Example

profile = OperationalProfile([1, 2, 3, 4, 5])

RepresentativeProfile(vals::Vector{P}) where {T, P<:TimeProfile{T}}
RepresentativeProfile(vals::Vector)

Time profile with a separate time profile for each representative period. This profile cannot be accessed using AbstractStrategicPeriod.

If too few profiles are provided, the last given profile will be repeated.

Example

# Varying values in each representative period
profile = RepresentativeProfile([OperationalProfile([1, 2]), OperationalProfile([3, 4, 5])])
 # The same value in each representative period
profile = RepresentativeProfile([1, 2, 3, 4, 5])

ScenarioProfile(vals::Vector{P}) where {T, P<:TimeProfile{T}}
ScenarioProfile(vals::Vector)

Time profile with a separate time profile for each scenario. This profile cannot be accessed using AbstractRepresentativePeriod or AbstractStrategicPeriod.

If too few profiles are provided, the last given profile will be repeated.

Example

# Varying values in each operational scenario
profile = ScenarioProfile([OperationalProfile([1, 2]), OperationalProfile([3, 4, 5])])
 # The same value in each operational scenario
profile = ScenarioProfile([1, 2, 3, 4, 5])

StrategicProfile(vals::Vector{P}) where {T, P<:TimeProfile{T}}
StrategicProfile(vals::Vector)

Time profile with a separate time profile for each strategic period.

If too few profiles are provided, the last given profile will be repeated.

Example

# Varying values in each strategic period
profile = StrategicProfile([OperationalProfile([1, 2]), OperationalProfile([3, 4, 5])])
 # The same value in each strategic period
profile = StrategicProfile([1, 2, 3, 4, 5])

StrategicStochasticProfile(vals::Vector{<:Vector{P}}) where {T, P<:TimeProfile{T}}
StrategicStochasticProfile(vals::Vector{<:Vector})

Time profile with a separate time profile for each strategic node in a TwoLevelTree structure.

If too few profiles are provided, the last given profile will be repeated, both for strategic periods and branches within a strategic period.

Example

 # The same value in each strategic period and branch
profile = StrategicStochasticProfile([[1], [21, 22]])
# Varying values in each strategic period and branch
profile = StrategicStochasticProfile([
    [OperationalProfile([11, 12])],
    [OperationalProfile([21, 22]), OperationalProfile([31, 32])]
])

discount(t, time_struct, discount_rate; type, timeunit_to_year)

Calculates the discount factor to be used for a time period t using a fixed 'discount_rate. There are two types of discounting available, either discounting to the start of the time period or calculating an approximate value for the average discount factor over the whole time period (type="avg"`).

objective_weight(t, time_struct, discount_rate; type, timeunit_to_year)

Returns an overall weight to be used for a time period t in the objective function considering both discounting, probability and possible multiplicity.

Discounter(discount_rate, timeunit_to_year, ts)

Structure to hold discount information to be used for a time structure.