add resource-type dispatch support and functional resource tests

- add resource-type dispatch integration in `model.jl` for variable creation and coupling constraints
- add resource type helpers in `resource.jl`
- extend functional docs index and internals references in `make.jl`, `index.md`, and `functions.md`
- add/expand end-to-end resource dispatch tests, including node/resource unpacking and bound constraints, in `test_resource.jl`
- add release note update in `NEWS.md`
- add new how-to page `extend-resource-functionality.md`

Author: espenbodal

NEWS.md

@@ -1,6 +1,6 @@
 # Release notes
 
-## Version 0.9.5 (2025-03-23)
+## Unversioned
 
 * New functions (`variables_flow_resource()`, `constraints_resource()`,  `constraints_couple_resource()`) that dispatch on resource types, which allow for creation of new resource-specific variables and constraints in extension packages.
 * New function to indentify the unique resource types of a vector of resources

docs/make.jl

@@ -58,6 +58,7 @@ makedocs(
         "How to" => Any[
             "Create a new element"=>"how-to/create_new_element.md",
             "Create a new node"=>"how-to/create-new-node.md",
+            "Extend resource functionality"=>"how-to/extend-resource-functionality.md",
             "Utilize TimeStruct"=>"how-to/utilize-timestruct.md",
             "Update models"=>"how-to/update-models.md",
             "Contribute to EnergyModelsBase"=>"how-to/contribute.md",

docs/src/how-to/extend-resource-functionality.md

@@ -0,0 +1,250 @@
+# [Extend resource functionality](@id how_to-extend-resource-functionality)
+
+```@meta
+CurrentModule = EMB
+```
+
+This guide shows how to extend resource functionality by adding a custom resource
+type and connecting it to custom variables and constraints through
+resource-dispatch functions. This is useful for modelling more complex
+resource behavior that cannot be captured by the default resource types where the standard
+behavior is built around energy or mass flow.
+
+The pattern follows the same structure as the resource dispatch test in
+`test/test_resource.jl`:
+
+1. Define a resource subtype with extra parameters.
+2. Optionally create a custom node subtype that uses the resource.
+3. Add resource-specific variables with `variables_flow_resource`.
+4. Add resource-specific constraints with `constraints_resource`.
+5. Couple node and link resource variables with `constraints_couple_resource`.
+
+The example in the test suite defines a `PotentialPower` resource that has a potential,
+with upper and lower bounds, in addition to energy flow. The flow of this potential
+in and out of junctions follow equality constraints, as opposed to the energy and mass flow
+which follow sum constraints.
+
+The notation below follows the same conventions as the implementation and tests:
+
+- `𝒩` for nodes
+- `ℒ` for links
+- `𝒫` for resources
+- `𝒯` for the time structure
+- `ℒᶠʳᵒᵐ`, `ℒᵗᵒ` for outgoing and incoming links of a node
+- `𝒫ᵒᵘᵗ`, `𝒫ⁱⁿ`, `𝒫ˡⁱⁿᵏ` for resource subsets on outputs, inputs, and links
+
+## 1. Define a special resource
+
+Create a subtype of [`Resource`](@ref) and keep `co2_int` as the second field for
+consistency with existing resource structures.
+
+```julia
+struct PotentialPower <: Resource
+    id::String
+    co2_int::Float64
+    potential_lower::Float64
+    potential_upper::Float64
+end
+
+EMB.is_resource_emit(::PotentialPower) = false
+lower_limit(p::PotentialPower) = p.potential_lower
+upper_limit(p::PotentialPower) = p.potential_upper
+```
+
+## 2. Define a custom node (optional)
+
+If your resource needs dedicated node behavior, create a custom node subtype.
+If the node subtype is parametrized, it can handle different types of resources
+in different ways without defining multiple node types. In the dispatch test,
+the custom node is an intermediate `NetworkNode` with a potential loss, but
+without a loss in energy flow.
+
+```julia
+struct PotentialLossNode{T<:PotentialPower} <: NetworkNode
+    id::Any
+    cap::TimeProfile
+    opex_var::TimeProfile
+    opex_fixed::TimeProfile
+    resource::T
+    input::Dict{<:Resource,<:Real}
+    output::Dict{<:Resource,<:Real}
+    data::Vector{<:ExtensionData}
+    loss_factor::Float64
+end
+
+function PotentialLossNode(
+    id,
+    cap::TimeProfile,
+    opex_var::TimeProfile,
+    opex_fixed::TimeProfile,
+    resource::T,
+    loss_factor::Float64,
+) where {T<:PotentialPower}
+    return PotentialLossNode{T}(
+        id,
+        cap,
+        opex_var,
+        opex_fixed,
+        resource,
+        Dict(resource => 1.0),
+        Dict(resource => 1.0),
+        ExtensionData[],
+        loss_factor,
+    )
+end
+```
+
+## 3. Declare resource-specific variables
+
+Use [`variables_flow_resource`](@ref) to create resource variables.
+
+Important:
+- Declare each variable name once.
+- Filter `𝒩` and `ℒ` down to the subsets that actually use the special resource.
+- Keep bounds in `constraints_resource` when they depend on dispatch logic.
+
+```julia
+function EMB.variables_flow_resource(
+    m,
+    𝒩::Vector{<:EMB.Node},
+    𝒫::Vector{<:PotentialPower},
+    𝒯,
+    modeltype::EnergyModel,
+)
+    output_nodes = filter(n -> any(p ∈ 𝒫 for p ∈ outputs(n)), 𝒩)
+    input_nodes = filter(n -> any(p ∈ 𝒫 for p ∈ inputs(n)), 𝒩)
+
+    @variable(
+        m, energy_potential_node_out[
+            n ∈ output_nodes, t ∈ 𝒯, p ∈ 𝒫; p ∈ outputs(n)
+        ]
+    )
+
+    @variable(
+        m, energy_potential_node_in[
+            n ∈ input_nodes, t ∈ 𝒯, p ∈ intersect(inputs(n), 𝒫)
+        ]
+    )
+end
+
+function EMB.variables_flow_resource(
+    m,
+    ℒ::Vector{<:Link},
+    𝒫::Vector{<:PotentialPower},
+    𝒯,
+    modeltype::EnergyModel,
+)
+    ℒᵉᵖ = filter(l -> any(p ∈ 𝒫 for p ∈ EMB.link_res(l)), ℒ)
+    @variable(m, energy_potential_link_in[ℒᵉᵖ, 𝒯, 𝒫])
+    @variable(m, energy_potential_link_out[ℒᵉᵖ, 𝒯, 𝒫])
+end
+```
+
+## 4. Add resource-specific constraints
+
+Use [`constraints_resource`](@ref) for custom node or link behavior.
+
+```julia
+function EMB.constraints_resource(
+    m,
+    n::PotentialLossNode,
+    𝒯,
+    𝒫::Vector{<:PotentialPower},
+    modeltype::EnergyModel,
+)
+    𝒫ᵒᵘᵗ = filter(p -> p ∈ 𝒫, outputs(n))
+    𝒫ⁱⁿ = filter(p -> p ∈ 𝒫, inputs(n))
+
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ],
+        m[:energy_potential_node_out][n, t, p] ==
+            n.loss_factor * m[:energy_potential_node_in][n, t, p]
+    )
+
+    # Bounds are added as constraints because they rely on `p`,
+    # which is an index in `energy_potential` variables.
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ],
+        m[:energy_potential_node_out][n, t, p] >= lower_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ],
+        m[:energy_potential_node_out][n, t, p] <= upper_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ⁱⁿ],
+        m[:energy_potential_node_in][n, t, p] >= lower_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ⁱⁿ],
+        m[:energy_potential_node_in][n, t, p] <= upper_limit(p)
+    )
+
+end
+
+function EMB.constraints_resource(
+    m,
+    n::EMB.Node,
+    𝒯,
+    𝒫::Vector{<:PotentialPower},
+    modeltype::EnergyModel,
+)
+    𝒫ᵒᵘᵗ = filter(p -> p ∈ 𝒫, outputs(n))
+    𝒫ⁱⁿ = filter(p -> p ∈ 𝒫, inputs(n))
+
+    # Bounds are added as constraints because they rely on `p`,
+    # which is an index in `energy_potential` variables.
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ],
+        m[:energy_potential_node_out][n, t, p] >= lower_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ],
+        m[:energy_potential_node_out][n, t, p] <= upper_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ⁱⁿ],
+        m[:energy_potential_node_in][n, t, p] >= lower_limit(p)
+    )
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ⁱⁿ],
+        m[:energy_potential_node_in][n, t, p] <= upper_limit(p)
+    )
+end
+
+function EMB.constraints_resource(
+    m,
+    l::Link,
+    𝒯,
+    𝒫::Vector{<:PotentialPower},
+    modeltype::EnergyModel,
+)
+    𝒫ˡⁱⁿᵏ = filter(p -> p ∈ 𝒫, EMB.link_res(l))
+    @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ˡⁱⁿᵏ],
+        m[:energy_potential_link_in][l, t, p] ==
+            m[:energy_potential_link_out][l, t, p]
+    )
+end
+```
+
+## 5. Couple node and link variables
+
+Use [`constraints_couple_resource`](@ref) to connect node and link resource variables.
+
+```julia
+function EMB.constraints_couple_resource(
+    m,
+    𝒩::Vector{<:EMB.Node},
+    ℒ::Vector{<:Link},
+    𝒫::Vector{<:PotentialPower},
+    𝒯,
+    modeltype::EnergyModel,
+)
+    for n ∈ 𝒩
+        ℒᶠʳᵒᵐ, ℒᵗᵒ = EMB.link_sub(ℒ, n)
+        𝒫ᵒᵘᵗ = filter(p -> p ∈ 𝒫, outputs(n))
+        𝒫ⁱⁿ = filter(p -> p ∈ 𝒫, inputs(n))
+
+        @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ᵒᵘᵗ, l ∈ ℒᶠʳᵒᵐ],
+            m[:energy_potential_node_out][n, t, p] ==
+                m[:energy_potential_link_in][l, t, p]
+        )
+
+        @constraint(m, [t ∈ 𝒯, p ∈ 𝒫ⁱⁿ, l ∈ ℒᵗᵒ],
+            m[:energy_potential_link_out][l, t, p] ==
+                m[:energy_potential_node_in][n, t, p]
+        )
+    end
+end
+```

docs/src/index.md

@@ -61,6 +61,7 @@ Depth = 1
 Pages = [
     "how-to/create_new_element.md",
     "how-to/create-new-node.md",
+    "how-to/extend-resource-functionality.md",
     "how-to/utilize-timestruct.md",
     "how-to/update-models.md",
     "how-to/contribute.md",

docs/src/library/internals/functions.md

@@ -100,5 +100,5 @@ res_sub
 collect_types
 sort_types
 res_types
-res_types_seg
+res_types_vec
 ```

src/model.jl

@@ -251,7 +251,7 @@ function variables_flow(m, 𝒩::Vector{<:Node}, 𝒳ᵛᵉᶜ, 𝒫, 𝒯, mode
     end
 
     # Create new flow variables for specific resource types
-    for p_sub in res_types_seg(𝒫)
+    for p_sub in res_types_vec(𝒫)
         variables_flow_resource(m, 𝒩, p_sub, 𝒯, modeltype)
     end
 
@@ -274,11 +274,16 @@ function variables_flow(m, ℒ::Vector{<:Link}, 𝒳ᵛᵉᶜ, 𝒫, 𝒯, model
     end
 
     # Create new flow variables for specific resource types
-    for p_sub in res_types_seg(𝒫)
+    for p_sub in res_types_vec(𝒫)
         variables_flow_resource(m, ℒ, p_sub, 𝒯, modeltype)
     end
 end
 
+# 5-parameter backward compatibility wrapper (for extension packages with old signature)
+function variables_flow(m, 𝒳::Vector{<:AbstractElement}, 𝒳ᵛᵉᶜ, 𝒯, modeltype::EnergyModel)
+    variables_flow(m, 𝒳, 𝒳ᵛᵉᶜ, Resource[], 𝒯, modeltype)
+end
+
 """
     variables_flow_resource(m, ℒ::Vector{<:Link}, 𝒫::Vector{<:Resource}, 𝒯, modeltype::EnergyModel)
     variables_flow_resource(m, 𝒩::Vector{<:Node}, 𝒫::Vector{<:Resource}, 𝒯, modeltype::EnergyModel)
@@ -605,7 +610,7 @@ function create_element(m, n::Node, 𝒯, 𝒫, modeltype::EnergyModel)
 
     # Constraints based on the resource types
     node_resources = Vector{Resource}(unique(vcat(inputs(n), outputs(n))))
-    for 𝒫ˢᵘᵇ in res_types_seg(node_resources)
+    for 𝒫ˢᵘᵇ in res_types_vec(node_resources)
         constraints_resource(m, n, 𝒯, 𝒫ˢᵘᵇ, modeltype)
     end
 end
@@ -615,7 +620,7 @@ function create_element(m, l::Link, 𝒯, 𝒫, modeltype::EnergyModel)
     create_link(m, l, 𝒯, 𝒫, modeltype)
 
     # Constraints based on the resource types
-    for 𝒫ˢᵘᵇ in res_types_seg(link_res(l))
+    for 𝒫ˢᵘᵇ in res_types_vec(link_res(l))
         constraints_resource(m, l, 𝒯, 𝒫ˢᵘᵇ, modeltype)
     end
 end
@@ -666,7 +671,7 @@ function constraints_couple(m, 𝒩::Vector{<:Node}, ℒ::Vector{<:Link}, 𝒫,
     end
 
     # Create new constraints for specific resource types
-    for p_sub in res_types_seg(𝒫)
+    for p_sub in res_types_vec(𝒫)
         constraints_couple_resource(m, 𝒩, ℒ, p_sub, 𝒯, modeltype)
     end
 end

src/structures/resource.jl

@@ -95,8 +95,8 @@ Return the unique resource types in an Vector of resources `𝒫`.
 res_types(𝒫::Vector{<:Resource}) = unique(map(x -> typeof(x), 𝒫))
 
 """
-    res_types_seg(𝒫::Vector{<:Resource})
+    res_types_vec(𝒫::Vector{<:Resource})
 
-Return a Vector-of-Vectors of resources segmented by the sub-types.
+Return a Vector-of-Vectors of resources by the concrete sub-types, if the input is empty it returns an empty Vector.
 """
-res_types_seg(𝒫::Vector{<:Resource}) = [Vector{rt}(filter(x -> isa(x, rt), 𝒫)) for rt in res_types(𝒫)]
+res_types_vec(𝒫::Vector{<:Resource}) = [Vector{rt}(filter(x -> isa(x, rt), 𝒫)) for rt in res_types(𝒫)]