Iteration utilities

Basic iteration

All time structures are iterable over their operational time periods:

julia> using TimeStruct
julia> function iterate_ex(periods::TimeStructure) for t in periods println(t) end enditerate_ex (generic function with 1 method)

Iteration with previous

In many settings, e.g., tracking of storage, it is convenient to have access to the previous time period. By using the custom iterator withprev, it is possible to return both the previous and current time period as a tuple when iterating:

julia> using TimeStruct
julia> periods = SimpleTimes(5, 1);
julia> collect(withprev(periods))5-element Vector{Any}: (nothing, t1) (t1, t2) (t2, t3) (t3, t4) (t4, t5)

A variant of this is the withnext iterator that returns the current and next period (or nothing if none).

Both wrappers use isfirst to start anew in each operational scenario, representative period, and strategic period. They hence work for time structures, strategic periods, representative periods, and the partitions of partition_duration, but not for scenarios, which are not ordered. When iterating the nodes of a TwoLevelTree, withprev returns the parent node as previous node. All wrappers of this page also accept iterators without known length, e.g., Iterators.filter.

Iteration with chunks of time periods

Sometimes it is convenient to iterate through the time periods as chunks of a fixed number of periods or minimum duration, e.g., in production planning with minimum production runs. To simplify this process, there are several iterator wrappers that allow this kind of iteration pattern.

The chunk function iterates through a time structure, returning subsequences of length at most n starting at each time period.

julia> periods = SimpleTimes(5,1)SimpleTimes{Int64}(5, [1, 1, 1, 1, 1], 5)
julia> collect(collect(ts) for ts in chunk(periods, 3))5-element Vector{Vector{TimeStruct.SimplePeriod{Int64}}}: [t1, t2, t3] [t2, t3, t4] [t3, t4, t5] [t4, t5] [t5]

This wrapper can be used for, e.g., modeling of startup processes with a minimum uptime. The following example shows how this can be implemented as part of a JuMP model:

using JuMP, TimeStruct

periods = SimpleTimes(5,1)

m = Model()
@variable(m, startup[periods], Bin)
@variable(m, shutdown[periods], Bin)

for ts in chunk(periods, 3)
    @constraint(m, sum(shutdown[t] for t in ts) <= 3 * (1 - startup[first(ts)]))
end
3 startup[t1] + shutdown[t1] + shutdown[t2] + shutdown[t3] ≤ 3
3 startup[t2] + shutdown[t2] + shutdown[t3] + shutdown[t4] ≤ 3
3 startup[t3] + shutdown[t3] + shutdown[t4] + shutdown[t5] ≤ 3
3 startup[t4] + shutdown[t4] + shutdown[t5] ≤ 3
3 startup[t5] + shutdown[t5] ≤ 3

Similarly, if modeling startup decisions with a minimum downtime, it is possible to reverse the original time periods and then chunk:

for ts in chunk(Iterators.reverse(periods), 3)
    @constraint(m, sum(shutdown[t] for t in ts) <= 3 * (1 - startup[first(ts)]))
end
3 startup[t5] + shutdown[t3] + shutdown[t4] + shutdown[t5] ≤ 3
3 startup[t4] + shutdown[t2] + shutdown[t3] + shutdown[t4] ≤ 3
3 startup[t3] + shutdown[t1] + shutdown[t2] + shutdown[t3] ≤ 3
3 startup[t2] + shutdown[t1] + shutdown[t2] ≤ 3
3 startup[t1] + shutdown[t1] ≤ 3

It is also possible to get cyclic behavior by setting the cyclic argument to true. If reaching the end before the required number of time periods, the chunk will continue from the first time period.

for ts in chunk(periods, 3; cyclic = true)
    @constraint(m, sum(shutdown[t] for t in ts) <= 3 * (1 - startup[first(ts)]))
end
3 startup[t1] + shutdown[t1] + shutdown[t2] + shutdown[t3] ≤ 3
3 startup[t2] + shutdown[t2] + shutdown[t3] + shutdown[t4] ≤ 3
3 startup[t3] + shutdown[t3] + shutdown[t4] + shutdown[t5] ≤ 3
3 startup[t4] + shutdown[t1] + shutdown[t4] + shutdown[t5] ≤ 3
3 startup[t5] + shutdown[t1] + shutdown[t2] + shutdown[t5] ≤ 3

Chunks based on duration

If working with a time structure that has varying duration for its time periods, it can be more convenient to use chunks based on their combined duration.

The chunk_duration function iterates through a time structure, returning subsequences with a duration of at least dur starting at each time period.

julia> periods = SimpleTimes(5,[1, 2, 1, 1.5, 0.5, 2])SimpleTimes{Float64}(5, [1.0, 2.0, 1.0, 1.5, 0.5, 2.0], 8.0)
julia> collect(collect(ts) for ts in chunk_duration(periods, 3))5-element Vector{Vector{TimeStruct.SimplePeriod{Float64}}}: [t1, t2] [t2, t3] [t3, t4, t5] [t4, t5] [t5]

Indexing

It is in general not advised to use indexing directly for the introduced operational time structures and iterators. Instead, it is beneficial to use the time structures directly as iterators. However, TimeStruct supports indexing in the following cases.

Indexing of operational time structures

It is possible to use indices for operational time structures, either directly using SimpleTimes or CalendarTimes, or by accessing a strategic period, representative period, or operational scenario that directly contains one of them. An index outside of the time structure results in a BoundsError.

julia> periods = TwoLevel(3, 100, SimpleTimes(10,1));
julia> scenario = first(opscenarios(periods))sp1-sc1
julia> scenario[3]sp1-t3

Structures with several nested time structures, e.g., a TwoLevel, cannot be indexed.

Indexing of iterators

The iterators returned by strat_periods, repr_periods, opscenarios, and strategic_scenarios can be indexed with itr[i] and support eachindex, keys, and itr[begin]:

julia> sps = strat_periods(periods);
julia> sps[2]sp2
julia> sps[end]sp3
julia> eachindex(sps)Base.OneTo(3)

itr[end] and last(itr) are only available for iterators of strategic and representative periods. They are not available for iterators of scenarios, as scenarios are not ordered, nor for the nodes of a TwoLevelTree, as a tree has several last nodes. For the same reason, last is not defined for a TwoLevelTree.

Ordering of periods

Strategic and representative periods can be compared with < and hence be sorted after collect. Representative periods within strategic periods are compared first by their strategic period and then by their representative period, so that sorting follows the order of iteration:

julia> rps = RepresentativePeriods(2, 100, [0.5, 0.5], [SimpleTimes(5, 1), SimpleTimes(5, 1)]);
julia> rp_pers = repr_periods(TwoLevel(2, 100, rps))4-element Vector{TimeStruct.StratReprPeriod{Int64, TimeStruct.RepresentativePeriod{Int64, SimpleTimes{Int64}}}}: sp1-rp1 sp1-rp2 sp2-rp1 sp2-rp2
julia> sort(rp_pers; rev = true)4-element Vector{TimeStruct.StratReprPeriod{Int64, TimeStruct.RepresentativePeriod{Int64, SimpleTimes{Int64}}}}: sp2-rp2 sp2-rp1 sp1-rp2 sp1-rp1

The nodes of a TwoLevelTree form only a partial order: n1 < n2 is true if n1 is an ancestor of n2. Nodes that are not on one path from the root are not ordered, as neither is smaller than the other. sort, max, and min use instead isless, which compares only the strategic periods of the nodes, so that sorting puts ancestors before their descendants.

julia> tree = TwoLevelTree(3, [2, 2], SimpleTimes(5, 1));
julia> sc_1, sc_2 = strategic_scenarios(tree);
julia> root = first(strat_periods(sc_1));
julia> leaf_1 = strat_periods(sc_1)[end];
julia> leaf_2 = strat_periods(sc_2)[end];
julia> root < leaf_1, leaf_1 < leaf_2, leaf_2 < leaf_1(true, false, false)

Operational and strategic scenarios are not ordered and cannot be compared with <.