Improvement to CapacityCostLink (#8)

* Modified `CapacityCostLink` to allow for `Vector{<:Number}`
* Represents sub periods with different durations

Author: JulStraus

NEWS.md

@@ -1,5 +1,11 @@
 # Release notes
 
+## Version 0.2.11 (2026-02-16)
+
+### Enhancements
+
+* Extended the link `CapacityCostLink` to also accept a vector of durations for the individual sub periods.
+
 ## Version 0.2.10 (2026-01-05)
 
 ### Enhancements

Project.toml

@@ -1,7 +1,7 @@
 name = "EnergyModelsFlex"
 uuid = "a81b9388-333d-4b63-81f2-910b060b544c"
 authors = ["Sigrid Aunsmo, Sigmund Eggen Holm, Jon Vegard Venås, and Per Åslid"]
-version = "0.2.10"
+version = "0.2.11"
 
 [deps]
 EnergyModelsBase = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"

docs/src/library/internals/methods-EMF.md

@@ -9,14 +9,16 @@ Pages = ["methods-EMF.md"]
 ## [Check methods](@id lib-int-met-check)
 
 ```@docs
-EnergyModelsFlex.check_period_ts
-EnergyModelsFlex.check_limits_default
-EnergyModelsFlex.check_input
+EMF.check_period_ts
+EMF.check_limits_default
+EMF.check_input
+EMF.check_cap_price_periods
 ```
 
 ## [Utility functions](@id lib-int-links-fun_utils)
 
 ```@docs
-EnergyModelsFlex.avg_cap_price
-EnergyModelsFlex.create_sub_periods
+EMF.get_avg_cap_price
+EMF.get_sub_periods
+EMF.get_sub_pers_durations
 ```

docs/src/links/capacitycostlink.md

@@ -44,10 +44,22 @@ The following additional fields are included for [`CapacityCostLink`](@ref) link
   The price per unit of maximum capacity usage over the sub-periods.
   This value is averaged over sub-periods as defined by `cap_price_periods`.
   All values have to be non-negative.
-- **`cap_price_periods::Int64`** :\
-  The number of sub-periods within a year for which the capacity cost is calculated.
+  !!! danger "Price values"
+
+      The value given in `cap_price` is interpreted on the strategic-period scale (*e.g.*, if a strategic-period duration of `1` corresponds to 1 year, then the natural unit is €/GW/year).
+      Capacity costs are calculated per sub-period and then summed over the strategic period.
+      This means a constant value (*e.g.,* €/GW/year) is effectively applied once for each sub-period (based on the peak within that sub-period), and is not automatically scaled by sub-period duration.
+
+      Example: With `cap_price = 100 €/GW/year`, `cap_price_periods = 12`, and a peak usage of 1 GW in each month, the model computes a total cost of 12 × 100 = 1200 €/year.
+
+      To achieve seasonal/monthly peak charges, define multiple `cap_price_periods` and provide `cap_price` values that represent the intended charge per sub-period (or scale the values accordingly).
+
+      It is planned to change this behavior in the future.
+      The change corresponds to a breaking change as we change the behavior of the model.
+- **`cap_price_periods::Union{Int64, Vector{<:Number}}`** :\
+  The number of sub-periods within a year for which the capacity cost is calculated (if specifying an `Int64`) or the duration of the individual sub periods (if specifying a `Vector{<:Number}`).
   This allows modeling of varying peak demands across seasons.
-  The value must be positive.
+  The value must be positive if your are using an `Int64` (and hence specifiy the number of periods) or all values of be positive and summing up to the specified scaling factor between operational and strategic period durations (the parameter `op_per_strat`) if you are using a `Vector{<:Number}`.
 
   !!! tip "Number of sub-periods"
       For investment periods with many operational periods, consider increasing the number of `cap_price_periods`.
@@ -126,15 +138,19 @@ The capacity cost is calculated as:
 \texttt{ccl\_cap\_use\_cost}[l, t_{sub}] = \texttt{ccl\_cap\_use\_max}[l, t_{sub}] \times \overline{cap\_price}(l, t_{sub})
 ```
 
-where ``\overline{cap\_price}`` is the average capacity price over the sub-period.
+where ``\overline{cap\_price}`` is the average capacity price over the sub-period calculated as:
+
+```math
+\overline{cap\_price}(l, t_{sub}) = \frac{\sum_{t \in t_{sub}} cap\_price(l, t) \times duration(t)}{\sum_{t \in t_{sub}} duration(t)}
+```
 
 Finally, costs are aggregated to each strategic period:
 
 ```math
 \texttt{link\_opex\_var}[l, t_{inv}] = \sum_{t_{sub} \in t_{inv}} \texttt{ccl\_cap\_use\_cost}[l, t_{sub}]
 ```
 
-In addition, the energy flow of the constrained resource should not exceed the maximum pipe capacity, which is included through the following constraint:
+In addition, the energy flow of the constrained resource should not exceed the maximum capacity, which is included through the following constraint:
 
 ```math
 \texttt{flow\_in}[l, t, cap\_resource(l)] \leq \texttt{link\_cap\_inst}[l, t]

src/link/checks.jl

@@ -4,9 +4,11 @@
 This method checks that the *[`CapacityCostLink`](@ref)* link is valid.
 
 ## Checks
- - The field `cap` is required to be non-negative.
- - The field `cap_price` is required to be non-negative.
- - The field `cap_price_period` is required to be positive.
+- The field `cap` is required to be non-negative.
+- The field `cap_price` is required to be non-negative.
+- The field `check_cap_price_periods` must follow the rules oulined in the subfunction
+  [`check_cap_price_periods`](@ref), that is it must either be a positive number or the
+  durations must sum up to the value `op_per_strat` of the time structure.
 """
 function EMB.check_link(l::CapacityCostLink, 𝒯, ::EnergyModel, ::Bool)
     @assert_or_log(
@@ -17,14 +19,46 @@ function EMB.check_link(l::CapacityCostLink, 𝒯, ::EnergyModel, ::Bool)
         all(cap_price(l)[t] ≥ 0 for t ∈ 𝒯),
         "The capacity price must be non-negative."
     )
+    check_cap_price_periods(l, 𝒯, cap_price_periods(l))
+end
+
+"""
+    check_cap_price_periods(l::CapacityCostLink, 𝒯, price_pers::Int64)
+    check_cap_price_periods(l::CapacityCostLink, 𝒯, price_pers::Vector{<:Number})
+
+This method checks that the field `check_cap_price_periods` is correct.
+
+## Checks
+- If the field is an `Int64`, the field `check_cap_price_periods` is required to be positive.
+- If the field is an `Vector{<:Number}`, the field `check_cap_price_periods` is required to sum
+  up to the value `op_per_strat` and each value in the `Vector` must be positive.
+- The individual capacity price periods must be able to represent the operational time
+  structure
+"""
+function check_cap_price_periods(l::CapacityCostLink, 𝒯, price_pers::Int64)
+    @assert_or_log(
+        price_pers > 0,
+        "The number of sub periods of a strategic period must be positive."
+    )
+    price_pers > 0 && @assert_or_log(
+        vcat(get_sub_periods(l, 𝒯)...) == collect(𝒯),
+        "The operational period durations could not accumulate into `cap_price_periods =
+        $(price_pers)` sub periods of each strategic period."
+    )
+end
+function check_cap_price_periods(l::CapacityCostLink, 𝒯, price_pers::Vector{<:Number})
+    @assert_or_log(
+        sum(price_pers) ≈ 𝒯.op_per_strat,
+        "The duration of all sub periods must be equal to the value `op_per_strat` of the " *
+        "time structure."
+    )
     @assert_or_log(
-        cap_price_periods(l) > 0,
-        "The the number of sub periods of a year must be positive."
+        all(price_pers .> 0),
+        "Each sub period must have a positive duration."
     )
-    sub_periods = create_sub_periods(l, 𝒯)
     @assert_or_log(
-        vcat(sub_periods...) == collect(𝒯),
+        vcat(get_sub_periods(l, 𝒯)...) == collect(𝒯),
         "The operational period durations could not accumulate into `cap_price_periods =
-        $(cap_price_periods(l))` sub periods of each strategic period."
+        $(length(price_pers))` sub periods of each strategic period."
     )
 end

src/link/datastructures.jl

@@ -1,5 +1,5 @@
 """
-    CapacityCostLink
+    struct CapacityCostLink <: Link
 
 A link between two nodes with costs on the link usage for the resource `cap_resource`. All
 other resources have no costs associated with their usage (follows the
@@ -11,20 +11,28 @@ other resources have no costs associated with their usage (follows the
 - **`to::Node`** is the node to which there is flow out of the link.
 - **`cap::TimeProfile`** is the capacity of the link for the `cap_resource`.
 - **`cap_price::TimeProfile`** is the price of capacity usage for the `cap_resource`.
-- **`cap_price_periods::Int64`** is the number of sub periods of a year.
+- **`cap_price_periods::Union{Int64, Vector{<:Number}}`** is either the number of sub periods
+  within a strategic period (if specified as `Int64`) or the minimum durations of the
+  individual sub periods within a strategic period (if specified as `Vector{<:Number}`).
 - **`cap_resource::Resource`** is the resource used by `CapacityCostLink`
-- **`formulation::Formulation`** is the used formulation of links. The field
-  `formulation` is conditional through usage of a constructor.
+- **`formulation::Formulation`** is the used formulation of links. The field `formulation`
+  is conditional through usage of a constructor.
 - **`data::Vector{<:ExtensionData}`** is the additional data (*e.g.*, for investments). The
   field `data` is conditional through usage of a constructor.
+
+!!! note "Sub periods"
+    You can specify either the total number of sub periods within a `CapacityCostLink` as
+    `Int64` or the durations of each sub period if using a `Vector{<:Number}`. The latter
+    requires you to be careful when considering the durations of the individual sub periods
+    and the total duration of sub periods within the operational time structure.
 """
 struct CapacityCostLink <: EMB.Link
     id::Any
     from::EMB.Node
     to::EMB.Node
     cap::TimeProfile
     cap_price::TimeProfile
-    cap_price_periods::Int64
+    cap_price_periods::Union{Int64, Vector{<:Number}}
     cap_resource::Resource
     formulation::EMB.Formulation
     data::Vector{<:ExtensionData}
@@ -36,7 +44,7 @@ function CapacityCostLink(
     to::EMB.Node,
     cap::TimeProfile,
     cap_price::TimeProfile,
-    cap_price_periods::Int64,
+    cap_price_periods::Union{Int64, Vector{<:Number}},
     cap_resource::Resource,
     formulation::EMB.Formulation,
 )
@@ -58,7 +66,7 @@ function CapacityCostLink(
     to::EMB.Node,
     cap::TimeProfile,
     cap_price::TimeProfile,
-    cap_price_periods::Int64,
+    cap_price_periods::Union{Int64, Vector{<:Number}},
     cap_resource::Resource,
     data::Vector{<:ExtensionData},
 )
@@ -80,7 +88,7 @@ function CapacityCostLink(
     to::EMB.Node,
     cap::TimeProfile,
     cap_price::TimeProfile,
-    cap_price_periods::Int64,
+    cap_price_periods::Union{Int64, Vector{<:Number}},
     cap_resource::Resource,
 )
     return CapacityCostLink(
@@ -147,8 +155,8 @@ cap_price(l::CapacityCostLink, t) = l.cap_price[t]
 """
     cap_price_periods(l::CapacityCostLink)
 
-Returns the number of sub-periods within a year for which a price is calculated of a capacity
-cost link `l`.
+Returns either the number of sub-periods within a strategic period for which a price is
+calculated or the vector of the durations of the sub-periods of a capacity cost link `l`.
 """
 cap_price_periods(l::CapacityCostLink) = l.cap_price_periods
 

src/link/model.jl

@@ -8,8 +8,8 @@ Creates the following additional variable for **ALL** capacity cost links:
   for a [`CapacityCostLink`](@ref) `l` in operational period `t`.
 """
 function EMB.variables_element(m, ℒˢᵘᵇ::Vector{<:CapacityCostLink}, 𝒯, ::EnergyModel)
-    @variable(m, ccl_cap_use_max[ℒˢᵘᵇ, 𝒯] >= 0)
-    @variable(m, ccl_cap_use_cost[ℒˢᵘᵇ, 𝒯] >= 0)
+    @variable(m, ccl_cap_use_max[ℒˢᵘᵇ, 𝒯] ≥ 0)
+    @variable(m, ccl_cap_use_cost[ℒˢᵘᵇ, 𝒯] ≥ 0)
 end
 
 """
@@ -33,7 +33,7 @@ function EMB.create_link(
     p_cap = cap_resource(l)
 
     # Create sub-periods based on the user-defined number of sub periods of a year
-    𝒯ˢᵘᵇ = create_sub_periods(l, 𝒯)
+    𝒯ˢᵘᵇ = get_sub_periods(l, 𝒯)
 
     # Capacity cost link where output equals input (no losses)
     @constraint(m, [t ∈ 𝒯],
@@ -52,7 +52,7 @@ function EMB.create_link(
     # Capacity cost constraint
     @constraint(m, [t_sub ∈ 𝒯ˢᵘᵇ],
         m[:ccl_cap_use_cost][l, t_sub[end]] ==
-        m[:ccl_cap_use_max][l, t_sub[end]] * avg_cap_price(l, t_sub)
+        m[:ccl_cap_use_max][l, t_sub[end]] * get_avg_cap_price(l, t_sub)
     )
 
     # Sum up costs for each sub_period into the strategic period cost
@@ -68,42 +68,57 @@ function EMB.create_link(
 end
 
 """
-    avg_cap_price(l::CapacityCostLink, t_sub::Vector{TS.TimePeriod})
+    get_avg_cap_price(l::CapacityCostLink, t_sub::Vector{TS.TimePeriod})
 
 Return the average capacity price over the sub period `t_sub` for the [`CapacityCostLink`](@ref) `l`.
 """
-function avg_cap_price(l::CapacityCostLink, t_sub::Vector{<:TS.TimePeriod})
+function get_avg_cap_price(l::CapacityCostLink, t_sub::Vector{<:TS.TimePeriod})
     return sum(cap_price(l, t) * duration(t) for t ∈ t_sub) / sum(duration(t) for t ∈ t_sub)
 end
 
 """
-    create_sub_periods(l::CapacityCostLink, 𝒯)
+    get_sub_periods(l::CapacityCostLink, 𝒯)
 
-Extract sub periods of the [`CapacityCostLink`](@ref) `l`.
+Return the vector of sub periods of the [`CapacityCostLink`](@ref) `l`.
 """
-function create_sub_periods(l::CapacityCostLink, 𝒯)
-    # Calculate the length of each sub period
-    sub_period_duration::Float64 = 𝒯.op_per_strat / cap_price_periods(l)
+function get_sub_periods(l::CapacityCostLink, 𝒯)
+    # Calculate the duration of each sub period
+    sub_pers_durations = get_sub_pers_durations(l, 𝒯)
 
-    # Create a vector collecting all `TimePeriod`s of each sub period into a vector for each
-    # sub period
+    # Create a vector collecting all `TimePeriod`s of each sub period into a vector
     sub_periods = Vector{TS.TimePeriod}[]
     for t_inv ∈ strategic_periods(𝒯)
-        accumulated_duration::Float64 = 0.0
+    idx = 1
+        accumulated_duration = 0.0
         sub_period = TS.TimePeriod[]
         for t ∈ t_inv
             push!(sub_period, t)
             accumulated_duration += duration(t) * multiple_strat(t_inv, t)
 
             # Check if the accumulated time of the periods in `sub_period` fills up a sub
             # period duration
-            if accumulated_duration ≈ sub_period_duration
+            if accumulated_duration ≈ sub_pers_durations[idx]
                 push!(sub_periods, sub_period)
                 sub_period = TS.TimePeriod[]
-                accumulated_duration = 0
+                accumulated_duration = 0.0
+                idx += 1
             end
         end
     end
 
     return sub_periods
 end
+
+"""
+    get_sub_pers_durations(l::CapacityCostLink, 𝒯)
+    get_sub_pers_durations(l::CapacityCostLink, 𝒯, price_pers::Int64)
+    get_sub_pers_durations(l::CapacityCostLink, 𝒯, price_pers::Vector{<:Number})
+
+Returns the individual durations of the different sub periods within a time structure `𝒯`
+and [`CapacityCostLink`](@ref) `l`.
+"""
+get_sub_pers_durations(l::CapacityCostLink, 𝒯) =
+    get_sub_pers_durations(l, 𝒯, cap_price_periods(l))
+get_sub_pers_durations(l::CapacityCostLink, 𝒯, price_pers::Int64) =
+    ones(price_pers) * 𝒯.op_per_strat / price_pers
+get_sub_pers_durations(l::CapacityCostLink, 𝒯, price_pers::Vector{<:Number}) = price_pers