Merge pull request #299 from JuliaDynamics/hw/metadata

add metadata helper functions

Author: hexaeder

NEWS.md

@@ -1,5 +1,12 @@
 # NetworkDynamics Release Notes
 
+## v0.10.2 Changelog
+- [#299](https://github.com/JuliaDynamics/NetworkDynamics.jl/pull/299) enhance metadata system with pattern matching and utility functions:
+  - Add String/Regex pattern matching for all metadata functions (`has_metadata`, `get_metadata`, `set_metadata!`, etc.)
+  - Add `strip_*!` functions to remove all metadata of a specific type from components
+  - Add `free_u()` and `free_p()` functions to identify variables/parameters without default values
+  - Support removing metadata by passing `nothing` or `missing` to `set_*!` functions
+
 ## v0.10.1 Changelog
 - [#294](https://github.com/JuliaDynamics/NetworkDynamics.jl/pull/294) add linear stability analysis functions: `isfixpoint`, `jacobian_eigenvals`, and `is_linear_stable` with support for both ODE and DAE systems
 - [#283](https://github.com/JuliaDynamics/NetworkDynamics.jl/pull/283) add automatic sparsity detection using `get_jac_prototype` and `set_jac_prototype!`

docs/src/API.md

@@ -121,28 +121,35 @@ get_metadata(::NetworkDynamics.ComponentModel, ::Symbol, ::Symbol)
 has_metadata(::NetworkDynamics.ComponentModel, ::Symbol, ::Symbol)
 set_metadata!(::NetworkDynamics.ComponentModel, ::Symbol, ::Symbol, ::Any)
 delete_metadata!(::NetworkDynamics.ComponentModel, ::Symbol, ::Symbol)
+strip_metadata!
 has_default
 get_default
 set_default!
 delete_default!
+strip_defaults!
 has_guess
 get_guess
 set_guess!
 delete_guess!
+strip_guesses!
 has_init
 get_init
 set_init!
 delete_init!
+strip_inits!
 has_bounds
 get_bounds
 set_bounds!
 delete_bounds!
+strip_bounds!
 set_defaults!
 set_interface_defaults!
 get_defaults_dict
 get_guesses_dict
 get_bounds_dict
 get_inits_dict
+free_u
+free_p
 ```
 
 ### Metadata and Inspection Utils

docs/src/metadata.md

@@ -22,7 +22,7 @@ details.
 ## Symbol Metadata
 Each component stores symbol metadata. The symbol metadata is a `Dict{Symbol, Dict{Symbol, Any}}` which stores a metadata dict per symbol. Symbols are everything that appears in [`sym`](@ref), [`psym`](@ref), [`obssym`](@ref) and [`insym`](@ref).
 
-To access the data, you can use the methods `has_metadata`, `get_metadata`, `set_metadata!` and `delete_metadata!` (see [Per Symbol Metadata API](@ref)).
+To access the data, you can use the methods `has_metadata`, `get_metadata`, `set_metadata!` and `delete_metadata!` (see [Per Symbol Metadata API](@ref)). These functions also support pattern matching using String or Regex patterns to match symbol names, making it easier to work with symbols containing special characters or when you only know part of the symbol name.
 
 Special cases for symbol metadata are:
 
@@ -31,7 +31,7 @@ Special cases for symbol metadata are:
 - `bounds`: Stores bounds for variables/parameters
 - `init`: Stores the solution of the "free" variables, this is rarely set manually but instead when calling [`initialize_component!`](@ref).
 
-For those, there are special functions `has_*`, `get_*`, `set_*!` and `delete_*!`. See [Per Symbol Metadata API](@ref).
+For those, there are special functions `has_*`, `get_*`, `set_*!`, `delete_*!` and `strip_*!`. The `strip_*!` functions remove all metadata of a specific type from all symbols in a component. See [Per Symbol Metadata API](@ref).
 
 These are closely aligned with the [metadata use in ModelingToolkit](@extref ModelingToolkit symbolic_metadata). They are automatically copied from the `ODESystem` if you use MTK models to create NetworkDynamics models.
 
@@ -42,5 +42,7 @@ common task. We provide several helper methods to do so. Please check out their
 - [`dump_state`](@ref)
 - [`dump_initial_state`](@ref)
 - [`get_initial_state`](@ref)
+- [`free_u`](@ref) - find variables without default values
+- [`free_p`](@ref) - find parameters without default values
 - [`describe_vertices`](@ref) (needs `DataFrames.jl` loaded)
 - [`describe_edges`](@ref) (needs `DataFrames.jl` loaded)

src/NetworkDynamics.jl

@@ -88,11 +88,11 @@ export initialize_component, initialize_component!, init_residual
 export initialize_componentwise, initialize_componentwise!, interface_values
 include("initialization.jl")
 
-export has_metadata, get_metadata, set_metadata!, delete_metadata!
-export has_default, get_default, set_default!, delete_default!, set_defaults!
-export has_guess, get_guess, set_guess!, delete_guess!
-export has_init, get_init, set_init!, delete_init!
-export has_bounds, get_bounds, set_bounds!, delete_bounds!
+export has_metadata, get_metadata, set_metadata!, delete_metadata!, strip_metadata!
+export has_default, get_default, set_default!, delete_default!, set_defaults!, strip_defaults!
+export has_guess, get_guess, set_guess!, delete_guess!, strip_guesses!
+export has_init, get_init, set_init!, delete_init!, strip_inits!
+export has_bounds, get_bounds, set_bounds!, delete_bounds!, strip_bounds!
 export has_graphelement, get_graphelement, set_graphelement!
 export get_initial_state, dump_initial_state, dump_state
 export has_callback, get_callbacks, set_callback!, add_callback!
@@ -101,6 +101,7 @@ export has_initformula, get_initformulas, set_initformula!, add_initformula!, de
 export has_position, get_position, set_position!
 export has_marker, get_marker, set_marker!
 export get_defaults_dict, get_guesses_dict, get_bounds_dict, get_inits_dict
+export free_p, free_u
 include("metadata.jl")
 
 export isfixpoint, is_linear_stable, jacobian_eigenvals

src/metadata.jl

@@ -18,19 +18,44 @@ function _assert_symbol_exists(c::ComponentModel, s::Symbol)
     return nothing
 end
 
+function _match_symbol_name(c::ComponentModel, pattern)
+    allsym = Symbol[]
+    append!(allsym, sym(c))
+    append!(allsym, psym(c))
+    hasinsym(c) && append!(allsym, insym_all(c))
+    append!(allsym, outsym_flat(c))
+    append!(allsym, obssym(c))
+    allssym = unique!(allsym)
+
+    fidx = findall(sym -> contains(string(sym), pattern), allsym)
+    if isempty(fidx)
+        throw(ArgumentError("No symbol matching pattern $pattern found in component model."))
+    elseif length(fidx) > 1
+        throw(ArgumentError("Multiple symbols matching pattern $pattern found in component model: $(allsym[fidx]). Please use a more specific pattern."))
+    end
+    return Symbol(allsym[only(fidx)])
+end
+
 """
     has_metadata(c::ComponentModel, sym::Symbol, key::Symbol)
     has_metadata(nw::Network, sni::SymbolicIndex, key::Symbol)
 
 Checks if symbol metadata `key` is present for symbol `sym` in a component model,
 or for a symbol referenced by `sni` in a network.
+
+`sym` can also be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
 Throws an error if the symbol does not exist in the component model.
 """
 function has_metadata(c::ComponentModel, sym::Symbol, key::Symbol)
     _assert_symbol_exists(c, sym)
     md = symmetadata(c)
     haskey(md, sym) && haskey(md[sym], key)
 end
+function has_metadata(c::ComponentModel, pattern::Union{String,Regex}, key::Symbol)
+    sym = _match_symbol_name(c, pattern)
+    has_metadata(c, sym, key)
+end
 function has_metadata(nw::Network, sym::SymbolicIndex, key::Symbol)
     has_metadata(getcomp(nw, sym), sym.subidx, key)
 end
@@ -41,12 +66,19 @@ end
 
 Retrieves the metadata `key` for symbol `sym` in a component model,
 or for a symbol referenced by `sni` in a network.
+
+`sym` can also be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
 Throws an error if the symbol does not exist in the component model.
 """
 function get_metadata(c::ComponentModel, sym::Symbol, key::Symbol)
     _assert_symbol_exists(c, sym)
     symmetadata(c)[sym][key]
 end
+function get_metadata(c::ComponentModel, pattern::Union{String,Regex}, key::Symbol)
+    sym = _match_symbol_name(c, pattern)
+    get_metadata(c, sym, key)
+end
 function get_metadata(nw::Network, sym::SymbolicIndex, key::Symbol)
     get_metadata(getcomp(nw, sym), sym.subidx, key)
 end
@@ -59,19 +91,29 @@ end
 
 Sets the metadata `key` for symbol `sym` to `value` in a component model,
 or for a symbol referenced by `sni` in a network.
+
+For component models, you can also use a `String` or `Regex` pattern to match symbol names:
+- String patterns use substring matching (e.g., `"δ"` matches `machine₊δ`)
+- Regex patterns use full regex matching (e.g., `r"P\$"` matches symbols ending with "P")
+This will error if there are none or multiple matches.
+
+If the pattern matches multiple symbols, an error is thrown. Use a more specific pattern.
 Throws an error if the symbol does not exist in the component model.
 """
 function set_metadata!(c::ComponentModel, sym::Symbol, key::Symbol, value)
     _assert_symbol_exists(c, sym)
     d = get!(symmetadata(c), sym, Dict{Symbol,Any}())
     d[key] = value
 end
+function set_metadata!(c::ComponentModel, pattern::Union{String,Regex}, key::Symbol, value)
+    sym = _match_symbol_name(c, pattern)
+    set_metadata!(c, sym, key, value)
+end
 function set_metadata!(nw::Network, sym::SymbolicIndex, key::Symbol, value)
     set_metadata!(getcomp(nw, sym), sym.subidx, key, value)
 end
 
 function set_metadata!(c::ComponentModel, sym::Symbol, pair::Pair)
-    _assert_symbol_exists(c, sym)
     set_metadata!(c, sym, pair.first, pair.second)
 end
 function set_metadata!(nw::Network, sym::SymbolicIndex, pair::Pair)
@@ -84,6 +126,9 @@ end
 
 Removes the metadata `key` for symbol `sym` in a component model,
 or for a symbol referenced by `sni` in a network.
+
+`sym` can also be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
 Returns `true` if the metadata existed and was removed, `false` otherwise.
 Throws an error if the symbol does not exist in the component model.
 """
@@ -99,14 +144,39 @@ function delete_metadata!(c::ComponentModel, sym::Symbol, key::Symbol)
     end
     return false
 end
+function delete_metadata!(c::ComponentModel, pattern::Union{String,Regex}, key::Symbol)
+    sym = _match_symbol_name(c, pattern)
+    delete_metadata!(c, sym, key)
+end
 delete_metadata!(nw::Network, sym::SymbolicIndex, key::Symbol) = delete_metadata!(getcomp(nw, sym), sym.subidx, key)
 
+"""
+    strip_metadata!(c::ComponentModel, key::Symbol)
+
+Remove all metadata of type `key` from the component.
+"""
+function strip_metadata!(c::ComponentModel, key::Symbol)
+    md_dict = symmetadata(c)
+    for (sym, sym_md) in md_dict
+        delete!(sym_md, key)
+    end
+    return c
+end
+strip_metadata!(nw::Network, sym::SymbolicIndex, key::Symbol) = strip_metadata!(getcomp(nw, sym), key)
+
 # generate default methods for some per-symbol metadata fields
 for md in [:default, :guess, :init, :bounds]
     fname_has = Symbol(:has_, md)
     fname_get = Symbol(:get_, md)
     fname_set = Symbol(:set_, md, :!)
     fname_del = Symbol(:delete_, md, :!)
+    fname_strip = if md == :guess
+        :strip_guesses!
+    elseif md == :bounds
+        :strip_bounds!
+    else
+        Symbol(:strip_, string(md)*"s", :!)
+    end
     @eval begin
         """
             has_$($(QuoteNode(md)))(c::ComponentModel, sym::Symbol)
@@ -115,6 +185,8 @@ for md in [:default, :guess, :init, :bounds]
         Checks if a `$($(QuoteNode(md)))` value is present for symbol `sym` in a component model,
         or for a symbol referenced by `sni` in a network.
 
+        `sym` can be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
         See also [`get_$($(QuoteNode(md)))`](@ref), [`set_$($(QuoteNode(md)))!`](@ref).
         """
         $fname_has(c::Comp_or_NW, sym) = has_metadata(c, sym, $(QuoteNode(md)))
@@ -126,6 +198,8 @@ for md in [:default, :guess, :init, :bounds]
         Returns the `$($(QuoteNode(md)))` value for symbol `sym` in a component model,
         or for a symbol referenced by `sni` in a network.
 
+        `sym` can be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
         See also [`has_$($(QuoteNode(md)))`](@ref), [`set_$($(QuoteNode(md)))!`](@ref).
         """
         $fname_get(c::Comp_or_NW, sym) = get_metadata(c, sym, $(QuoteNode(md)))
@@ -137,9 +211,19 @@ for md in [:default, :guess, :init, :bounds]
         Sets the `$($(QuoteNode(md)))` value for symbol `sym` to `value` in a component model,
         or for a symbol referenced by `sni` in a network.
 
+        If `value` is `nothing` or `missing`, the metadata is removed.
+
+        `sym` can be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
         See also [`has_$($(QuoteNode(md)))`](@ref), [`get_$($(QuoteNode(md)))`](@ref).
         """
-        $fname_set(c::Comp_or_NW, sym, val) = set_metadata!(c, sym, $(QuoteNode(md)), val)
+        function $fname_set(c::Comp_or_NW, sym, val)
+            if !isnothing(val) && !ismissing(val)
+                set_metadata!(c, sym, $(QuoteNode(md)), val)
+            else
+                delete_metadata!(c, sym, $(QuoteNode(md)))
+            end
+        end
 
         """
             delete_$($(QuoteNode(md)))!(c::ComponentModel, sym::Symbol)
@@ -148,9 +232,22 @@ for md in [:default, :guess, :init, :bounds]
         Removes the `$($(QuoteNode(md)))` value for symbol `sym` in a component model,
         or for a symbol referenced by `sni` in a network.
 
+        `sym` can be a String or Regex, to address the only symbol containing the pattern, see [`set_metadata!`](@ref) for details.
+
         See also [`has_$($(QuoteNode(md)))`](@ref), [`set_$($(QuoteNode(md)))!`](@ref).
         """
         $fname_del(c::Comp_or_NW, sym) = delete_metadata!(c, sym, $(QuoteNode(md)))
+
+        """
+            strip_$($(QuoteNode(md)))!(c::ComponentModel)
+            strip_$($(QuoteNode(md)))!(nw::Network, idx::Union{VIndex,EIndex})
+
+        Removes all `$($(QuoteNode(md)))` values from a component model,
+        or from a component referenced by `idx` in a network.
+
+        See also [`delete_$($(QuoteNode(md)))!`](@ref), [`set_$($(QuoteNode(md)))!`](@ref).
+        """
+        $fname_strip(c::Comp_or_NW) = strip_metadata!(c, $(QuoteNode(md)))
     end
 end
 
@@ -1042,3 +1139,39 @@ end
 
 function describe_vertices end
 function describe_edges end
+
+"""
+    free_p(cf::ComponentModel)
+    free_p(nw::Network)
+
+Returns the "free" parameters (parameters without default values) for the given system.
+
+# Returns
+- Vector of parameter symbols that do not have default values set
+
+See also: [`free_u`](@ref), [`has_default`](@ref), [`set_default!`](@ref)
+"""
+function free_p(cf::NetworkDynamics.ComponentModel)
+    return filter(p -> !NetworkDynamics.has_default(cf, p), NetworkDynamics.psym(cf))
+end
+function free_p(nw::Network)
+    setdiff(NetworkDynamics.SII.parameter_symbols(nw), keys(NetworkDynamics.SII.default_values(nw)))
+end
+
+"""
+    free_u(nw::Network)
+    free_u(cf::ComponentModel)
+
+Returns the "free" variables/states (variables without default values) for the given system.
+
+# Returns
+- Vector of variable/state symbols that do not have default values set
+
+See also: [`free_p`](@ref), [`has_default`](@ref), [`set_default!`](@ref)
+"""
+function free_u(nw::Network)
+    setdiff(NetworkDynamics.SII.variable_symbols(nw), keys(NetworkDynamics.SII.default_values(nw)))
+end
+function free_u(cf::NetworkDynamics.ComponentModel)
+    return filter(u -> !NetworkDynamics.has_default(cf, u), NetworkDynamics.sym(cf))
+end

src/show.jl

@@ -48,7 +48,7 @@ Base.show(io::IO, s::KAAggregator) = print(io, "KAAggregator($(repr(s.f)))")
 Base.show(io::IO, s::SequentialAggregator) = print(io, "SequentialAggregator($(repr(s.f)))")
 Base.show(io::IO, s::PolyesterAggregator) = print(io, "PolyesterAggregator($(repr(s.f)))")
 
-function Base.show(io::IO, ::MIME"text/plain", c::ComponentModel)
+function Base.show(io::IO, mime::MIME"text/plain", c::ComponentModel)
     type = string(typeof(c))
     print(io, type, styled" {NetworkDynamics_name::$(c.name)}")
     print(io, styled" {NetworkDynamics_fftype:$(fftype(c))}")
@@ -64,6 +64,14 @@ function Base.show(io::IO, ::MIME"text/plain", c::ComponentModel)
     styling = Dict{Int,Symbol}()
 
     print_states_params(io, c, styling)
+
+    # special known metadata of PowerDynamics
+    if has_metadata(c, :pfmodel)
+        pfm = get_metadata(c, :pfmodel)
+        printstyled(io, "\nPowerflow model ", color=:blue, bold=true)
+        print(io, ":", pfm.name)
+        pdim(pfm) > 0 && print(io, styled" with $(stylesymbolarray(pfm.psym, _pdef(pfm), _pguess(pfm)))")
+    end
 end
 
 function print_states_params(io, @nospecialize(c::ComponentModel), styling)