rename to jacobian_eigenvals

Author: hexaeder

NEWS.md

@@ -1,6 +1,7 @@
 # NetworkDynamics Release Notes
 
 ## 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!`
 - [#285](https://github.com/JuliaDynamics/NetworkDynamics.jl/pull/285) rename `delete_initconstraint!` -> `delete_initconstaints!` and `delete_initformula!` -> `delete_initformulas!`
 

docs/src/API.md

@@ -179,6 +179,13 @@ delete_initformulas!
 interface_values
 ```
 
+## Linear Stability Analysis
+```@docs
+isfixpoint
+jacobian_eigenvals
+is_linear_stable
+```
+
 ## Callbacks API
 ### Define Callbacks
 ```@docs

docs/src/initialization.md

@@ -227,3 +227,6 @@ nothing #hide
 
 **Applying Constraints**: Constraints can be either added to the metadata of components ([`set_initconstraint!`](@ref), [`add_initconstraint!`](@ref)) or passed as `additional_initconstraint` to the
 [`initialize_component[!]`](@ref NetworkDynamics.initialize_component) functions.
+
+## Analysing Fixpoints
+In order to analyse fixpoints NetworkDynamis provides the functions [`isfixpoint`](@ref), [`is_linear_stable`](@ref) and [`jacobian_eigenvals`](@ref).

src/NetworkDynamics.jl

@@ -103,7 +103,7 @@ export has_marker, get_marker, set_marker!
 export get_defaults_dict, get_guesses_dict, get_bounds_dict, get_inits_dict
 include("metadata.jl")
 
-export isfixpoint, is_linear_stable, linear_eigenvals
+export isfixpoint, is_linear_stable, jacobian_eigenvals
 include("linear_stability.jl")
 
 include("show.jl")

src/linear_stability.jl

@@ -25,12 +25,12 @@ the eigenvalues of the Jacobian matrix (or reduced Jacobian for constrained syst
 A fixpoint is linearly stable if all eigenvalues of the Jacobian have negative
 real parts. For systems with algebraic constraints (non-identity mass matrix),
 the reduced Jacobian is used following the approach in [1].
-See [`linear_eigenvals`](@ref) for more details.
+See [`jacobian_eigenvals`](@ref) for more details.
 
 # Arguments
 - `nw::Network`: The network dynamics object
 - `s0::NWState`: The state to check for linear stability (must be a fixpoint)
-- `kwargs...`: Additional keyword arguments passed to `linear_eigenvals`
+- `kwargs...`: Additional keyword arguments passed to `jacobian_eigenvals`
 
 # Returns
 - `Bool`: `true` if the fixpoint is linearly stable, `false` otherwise
@@ -40,7 +40,7 @@ See [`linear_eigenvals`](@ref) for more details.
 """
 function is_linear_stable(nw::Network, s0; kwargs...)
     isfixpoint(nw, s0) || error("The state s0 is not a fixpoint of the network nw.")
-    λ = linear_eigenvals(nw, s0; kwargs...)
+    λ = jacobian_eigenvals(nw, s0; kwargs...)
     if all(λ -> real(λ) < 0.0, λ)
         return true
     else
@@ -49,7 +49,7 @@ function is_linear_stable(nw::Network, s0; kwargs...)
 end
 
 """
-    linear_eigenvals(nw::Network, s0::NWState; eigvalf=LinearAlgebra.eigvals)
+    jacobian_eigenvals(nw::Network, s0::NWState; eigvalf=LinearAlgebra.eigvals)
 
 Compute the eigenvalues of the Jacobian matrix for linear stability analysis of
 the network dynamics at state `s0`.
@@ -89,7 +89,7 @@ For constrained systems (M ≠ I, differential-algebraic equations):
 # References
 [1] "Power System Modelling and Scripting", F. Milano, Chapter 7.2.
 """
-function linear_eigenvals(nw::Network, s0; eigvalf=LinearAlgebra.eigvals)
+function jacobian_eigenvals(nw::Network, s0; eigvalf=LinearAlgebra.eigvals)
     x0, p, t = uflat(s0), pflat(s0), s0.t # unpack state
     M = nw.mass_matrix
 

test/linear_stability_test.jl

@@ -25,14 +25,14 @@ using Test
         s_non_fix.v[1, :s] = 1.0
         @test !isfixpoint(nw, s_non_fix)
 
-        # Test linear_eigenvals function
-        λ = linear_eigenvals(nw, s0)
+        # Test jacobian_eigenvals function
+        λ = jacobian_eigenvals(nw, s0)
         @test length(λ) == 3  # Should have 3 eigenvalues for 3 vertices
         @test all(real.(λ) .≤ 0)  # All eigenvalues should have non-positive real parts
         @test nw.mass_matrix == I  # Verify unconstrained system
 
         # Test custom eigenvalue function
-        λ_custom = linear_eigenvals(nw, s0; eigvalf=eigvals)
+        λ_custom = jacobian_eigenvals(nw, s0; eigvalf=eigvals)
         @test λ ≈ λ_custom
 
         # Test is_linear_stable function
@@ -62,7 +62,7 @@ using Test
         @test isfixpoint(nw, s0)
 
         # Test eigenvalue computation
-        λ = linear_eigenvals(nw, s0)
+        λ = jacobian_eigenvals(nw, s0)
         @test length(λ) == 8  # 4 nodes × 2 states each
 
         # Test stability (should be stable for this configuration)
@@ -92,7 +92,7 @@ using Test
         @test isfixpoint(nw, s0)
 
         # Test eigenvalue computation for DAE system (should use reduced Jacobian)
-        λ = linear_eigenvals(nw, s0)
+        λ = jacobian_eigenvals(nw, s0)
         @test length(λ) == 3  # Should have 3 eigenvalues (differential variables only)
         @test all(real.(λ) .< 0)  # Should be stable