Rework of TwoLevelTree

docs/make.jl

@@ -10,8 +10,16 @@ pages = [
         "Discounting" => "manual/discount.md",
     ],
     "API reference" => "reference/api.md",
+    "Internal reference" => "reference/internal.md",
 ]
 
+DocMeta.setdocmeta!(
+    TimeStruct,
+    :DocTestSetup,
+    :(using TimeStruct);
+    recursive = true,
+)
+
 Documenter.makedocs(
     sitename = "TimeStruct",
     format = Documenter.HTML(;

docs/src/reference/api.md

@@ -1,7 +1,7 @@
+
 ```@meta
 CurrentModule = TimeStruct
 ```
-
 # Available time structures
 
 ```@docs
@@ -28,13 +28,17 @@ OperationalScenarios
 TwoLevel
 ```
 
+```@docs
+TwoLevelTree
+regular_tree
+```
+
 # Properties of time periods
 
 ```@docs
 duration
 ```
 
-
 ```@docs
 isfirst
 ```
@@ -43,7 +47,6 @@ isfirst
 multiple
 ```
 
-
 ```@docs
 probability
 ```
@@ -60,6 +63,11 @@ opscenarios
 
 ```@docs
 strat_periods
+strategic_periods
+```
+
+```@docs
+strategic_scenarios
 ```
 
 ```@docs
@@ -97,6 +105,10 @@ ScenarioProfile
 StrategicProfile
 ```
 
+```@docs
+StrategicStochasticProfile
+```
+
 # Discounting
 
 ```@docs

docs/src/reference/internal.md

@@ -0,0 +1,82 @@
+# Internal types
+
+```@meta
+CurrentModule = TimeStruct
+```
+
+## Strategic period types ([`TwoLevelTree`](@ref))
+
+### Single types
+
+```@docs
+AbstractTreeNode
+StratNode
+StrategicScenario
+```
+
+### Iterator types
+
+```@docs
+AbstractTreeStructure
+StratTreeNodes
+
+```
+
+## Strategic period types ([`TwoLevel`](@ref))
+
+### Single types
+
+```@docs
+AbstractStrategicPeriod
+StrategicPeriod
+```
+
+### Iterator types
+
+```@docs
+```
+
+## Representative period types
+
+### Single types
+
+```@docs
+AbstractRepresentativePeriod
+RepresentativePeriod
+StratNodeReprPeriod
+```
+
+### Iterator types
+
+```@docs
+StratNodeReprPeriods
+```
+
+## Operational scenarios types
+
+### Single types
+
+```@docs
+OperationalScenario
+StratOperationalScenario
+StratNodeOperationalScenario
+StratNodeReprOpscenario
+```
+
+### Iterator types
+
+```@docs
+StrategicScenarios
+StratNodeOpScens
+StratNodeReprOpscenarios
+```
+
+## Operational period types
+
+```@docs
+TimePeriod
+SimplePeriod
+CalendarPeriod
+OperationalPeriod
+TreePeriod
+```

src/TimeStruct.jl

@@ -12,14 +12,17 @@ include("calendar.jl")
 include("representative.jl")
 include("stochastic.jl")
 include("twolevel.jl")
-include("twoleveltree.jl")
 include("strat_periods.jl")
 include("repr_periods.jl")
 include("opscenarios.jl")
-include("profiles.jl")
 include("utils.jl")
 include("discount.jl")
 
+include("tree_nodes.jl")
+include("twoleveltree.jl")
+
+include("profiles.jl")
+
 export TimeStructure
 export SimpleTimes
 export CalendarTimes
@@ -34,13 +37,12 @@ export OperationalProfile
 export ScenarioProfile
 export StrategicProfile
 export StrategicStochasticProfile
-export DynamicStochasticProfile
 export RepresentativeProfile
 
 export opscenarios
 export repr_periods
 export strat_periods, strategic_periods
-export regular_tree, strat_nodes, scenarios
+export regular_tree, strat_nodes, strategic_scenarios
 export withprev, chunk, chunk_duration
 export isfirst, duration, duration_strat, multiple, probability
 export multiple_strat

src/profiles.jl

@@ -165,18 +165,63 @@ function Base.getindex(
     return _value_lookup(RepresentativeIndexable(T), rp, period)
 end
 
-struct StrategicStochasticProfile{T} <: TimeProfile{T}
-    vals::Vector{Vector{T}}
-end
-function Base.getindex(ssp::StrategicStochasticProfile, i::TimePeriod)
-    return ssp.vals[_strat_per(i)][_branch(i)]
-end
+"""
+    StrategicStochasticProfile(vals::Vector{<:Vector{P}}) where {T<:Number, P<:TimeProfile{T}}
+    StrategicStochasticProfile(vals::Vector{<:Vector{<:Number}})
+
+Time profile with a separate time profile for each strategic node in a [`TwoLevelTree`](@ref)
+structure.
 
-struct DynamicStochasticProfile{T<:Number} <: TimeProfile{T}
-    vals::Vector{<:Vector{<:TimeProfile{T}}}
+If too few profiles are provided, the last given profile will be repeated, both for strategic
+periods and branches within a strategic period.
+
+## Example
+```julia
+ # 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])]
+])
+```
+"""
+struct StrategicStochasticProfile{T<:Number,P<:TimeProfile{T}} <: TimeProfile{T}
+    vals::Vector{<:Vector{P}}
+end
+function StrategicStochasticProfile(vals::Vector{<:Vector{<:Number}})
+    return StrategicStochasticProfile([
+        [FixedProfile(v_2) for v_2 in v_1] for v_1 in vals
+    ])
+end
+
+function _value_lookup(
+    ::HasStratTreeIndex,
+    ssp::StrategicStochasticProfile,
+    period,
+)
+    sp_prof = ssp.vals[_strat_per(period) > length(ssp.vals) ? end :
+             _strat_per(period)]
+    branch_prof =
+        sp_prof[_branch(period) > length(sp_prof) ? end : _branch(period)]
+    return branch_prof[period]
+end
+
+function _value_lookup(
+    ::NoStratTreeIndex,
+    ssp::StrategicStochasticProfile,
+    period,
+)
+    return error(
+        "Type $(typeof(period)) can not be used as index for a strategic stochastic profile",
+    )
 end
-function Base.getindex(ssp::DynamicStochasticProfile, i::TimePeriod)
-    return ssp.vals[_strat_per(i)][_branch(i)][i]
+
+function Base.getindex(
+    ssp::StrategicStochasticProfile,
+    period::T,
+) where {T<:Union{TimePeriod,TimeStructure}}
+    return _value_lookup(StrategicTreeIndexable(T), ssp, period)
 end
 
 Base.getindex(TP::TimeProfile, inds...) = [TP[i] for i in inds]

src/strat_periods.jl

@@ -205,4 +205,10 @@ _strat_per(ssp::SingleStrategicPeriod) = 1
 strat_periods(ts::TimeStructure) = SingleStrategicPeriodWrapper(ts)
 
 # Allow strategic_periods() in addition to strat_periods()
+
+"""
+    strategic_periods(ts)
+
+Internal convenience constructor for [`strat_periods`](@ref).
+"""
 strategic_periods(ts) = strat_periods(ts)