Interface for using `TimeStruct

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 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 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 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)], 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}

TwoLevelTree(node::TreeNode; op_per_strat=8760.0)
TwoLevelTree(duration::S, branching::Vector, ts::OP; op_per_strat::Float64 = 1.0) where {S,T,OP<: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.

The default approach for creating a TwoLevelTree is by providing the root [TreeNode](@ref) with all its children nodes. In the case of a regular structure, that is all children nodes have the same duration, time structure ts, probability, and children itself, you can use a simplified constructor with the branching vector. 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, duration, and time structure.

Example

# Declare the individual time structure
day = SimpleTimes(24, 1)

# Regular tree with 3 strategic periods of duration 5, 3 branches for the second strategic
# period, and 6 branchs in the thirdand forth strategic period
regtree_1 = TwoLevelTree(5, [3, 2, 1], day)

# Equivalent structure using `TreeNode` and the different constructors
regtree_2 = TwoLevelTree(
    TreeNode(5, day, [
        TreeNode(5, day, 2,
            TreeNode(5, day, TreeNode(5, day))
        )
        TreeNode(5, day, [0.5, 0.5],
            TreeNode(5, day, TreeNode(5, day))
        )
        TreeNode(5, day, [
            TreeNode(5, day, TreeNode(5, day)),
            TreeNode(5, day, TreeNode(5, day)),
        ])
    ])
)

struct TreeNode{S,T,OP<:TimeStructure{T},COP<:Union{Nothing, TimeStructure{T}}}

TreeNode(duration::Number, ts::TimeStructure)
TreeNode(duration::Number, ts::TimeStructure, child::TreeNode)
TreeNode(duration::Number, ts::TimeStructure, len::Int64, children::TreeNode)
TreeNode(duration::Number, ts::TimeStructure, children::Vector{<:TreeNode})
TreeNode(duration::Number, ts::TimeStructure, probability::Vector{<:Float64}, sub_tn::TreeNode)

A subtype introduced for creating all potential structures of a TwoLevelTree.

A TreeNode is similar to a StratNode but does not require the calculation of all required parameters by the user. The parameters are automatically calculated when creating a TwoLevelTree for a given TreeNode.

The TreeNode has a given duration which is similar to the duration of a TwoLevel time structure and a single TimeStructure ts.

Constructors

The following constructors are included for the type:

• TreeNode(duration::Number, ts::TimeStructure): the last TreeNode within a branch, i.e., the leaf of the branch. It does not posess a child.
• TreeNode(duration::Number, ts::TimeStructure, child::TreeNode): a TreeNode with only a single child. i.e., a linear continuation.
• TreeNode(duration::Number, ts::TimeStructure, len::Int64, children::TreeNode): a TreeNode with len children, each with the same structure and probability.
• TreeNode(duration::Number, ts::TimeStructure, probability::Vector{<:Float64}, children::TreeNode): a TreeNode with len children, each with the same structure but a different probability.
• TreeNode(duration::Number, ts::TimeStructure, children::Vector{<:TreeNode}) corresponds to a number of different children with different structures, but the same probability.
• TreeNode(duration::Number, ts::TimeStructure, probability::Vector{<:Float64}, children::TreeNode): a TreeNode with length(probability) children, each with the same structure but a different probability.
• TreeNode(duration::Number, ts::TimeStructure, probability::Vector{<:Float64}, children::Vector{<:TreeNode}): a TreeNode with length(probability) children, each with a different structure and probability.

Example

day = SimpleTimes(24, 1)
# Provides a leaf node
TreeNode(2, day)

# Provides a linear node structure
TreeNode(2, day, TreeNode(2, day))

# Provides a tree node with two children with 70 % and 30 % probability, respectively
TreeNode(2, day, [0.7, 0.3], TreeNode(2, SimpleTimes(24, 1)))


# Provide a tree node with two children with 70 % (168 periods) and 30 % (24 periods)
# probability, respectively
TreeNode(2, day, [0.7, 0.3], [
    TreeNode(2, SimpleTimes(168, 1)),
    TreeNode(2, SimpleTimes(24, 1)),
])

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.

TwoLevelTree(duration, branching, ts; op_per_strat)

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::TwoLevel)
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 TwoLevel, strategic_scenarios returns a Vector with the TwoLevel as a single entry.

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.

withnext(iter)

Iterator wrapper that yields (t, next) where next is the next time period or nothing for the last time period.

Note that this iterator can not be used when iterating the nodes of a strategic tree structure, as the next node is not uniquely defined in that case.

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::AbstractStrategicPeriod, 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.

start_oper_time(t, ts)

Get the operational start time of the time period t in the time structure ts.

The operational start time is equal to the sum of the durations of all previous operational time periods in its operational time structure.

end_oper_time(t, ts)

Get the operational end time of the time period t in the time structure ts.

The operational end time is equal to the sum of the durations of all previous operational time periods in its operational time structure, including its own duration.

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])]
])

Discounter(discount_rate, ts::TimeStructure)
Discounter(discount_rate, timeunit_to_year, ts::TimeStructure)

Structure to hold discount information to be used for a time structure ts. The discount_rate is an absolute discount rate while the parameter timeunit_to_year is used convert the time units of strategic periods in the time structure to years (default value = 1.0).

As an example, consider the following time structure:

# Modelling of a day with hourly resolution for 50 years with a resolution of 5 years
periods = TwoLevel(10, 5 * 8760, SimpleTimes(24, 1))

# The parameter `timeunit_to_year` must in this case be 1 year / 8760 h
disc = Discounter(0.04, 1 / 8760, periods)

discount(t::Union{TimePeriod,TimeStructurePeriod}, time_struct::TimeStructure, discount_rate; type = "start", timeunit_to_year=1.0)
discount(disc::Discounter, t::Union{TimePeriod,TimeStructurePeriod}; type = "start")

Calculates the discount factor to be used for a time period t using a fixed discount_rate. The function can be either called using a Discounter type or by specifying the parameters (time structure ts, discount_rate and potentially timeunit_to_year) directly.

There are two types of discounting available:

1. Discounting to the start of the strategic period containing the time period:

   This can be achieved through specifying type="start". It is useful for investment costs

2. Discounting to the average of the over the whole strategic period:

   The average can be calculated either as a continuous average (type="avg") or as a discrete average that discounts to the start of each year (type="avg_year"). Average discounting is useful for operational costs.

The timeunit_to_year parameter is used to convert the time units of strategic periods in the time structure to years (default value = 1.0).

objective_weight(t::Union{TimePeriod,TimeStructurePeriod}, ts::TimeStructure, discount_rate; type = "start", timeunit_to_year = 1.0)
objective_weight(t::Union{TimePeriod,TimeStructurePeriod}, disc::Discounter; type = "start")

Calculates the overall objective weight for a time period t using a fixed discount_rate. The weight consideres both discounting, the probability and potential multiplicity of t The function can be either called using a Discounter type or by specifying the parameters (time structure ts, discount_rate and potentially timeunit_to_year) directly.

There are two types of discounting available:

1. Discounting to the start of the strategic period containing the time period:

   This can be achieved through specifying type="start". It is useful for investment costs

2. Discounting to the average of the over the whole strategic period:

   The average can be calculated either as a continuous average (type="avg") or as a discrete average that discounts to the start of each year (type="avg_year"). Average discounting is useful for operational costs.

The timeunit_to_year parameter is used to convert the time units of strategic periods in the time structure to years (default value = 1.0).