Add MNA state-space extraction and modal analysis

[georgii-tishenin]

Summary

This PR adds state-space extraction for real-valued EMT simulations using the MNA solver. The implementation extracts the global discrete-time state matrix from the EMT MNA simulation model and provides a standalone state-space modal-analysis class for computing discrete-time and continuous-time eigenvalues.

Changes

• add MNAStateSpaceContributor infrastructure for component-level state-space contributions
• add MNAStateSpaceExtractor for extracting the discrete-time state matrix from real-valued EMT MNA models
• add StateSpaceModalAnalysis for computing discrete-time and continuous-time eigenvalues from the extracted state matrix
• integrate state-space extraction into the MNA direct solver task flow and expose it through Simulation
• expose state-space extraction and modal analysis in pybind
• add C++ example for EMT 3-phase RLC state-space extraction
• add Python notebook validation example with assertions

Notes

• The extraction is available for real-valued EMT domain simulations using the direct MNA solver.
• Supported state-contributing components are EMT 3-phase inductors, capacitors, and two-terminal V-type SSN components.
• Supported algebraic components without extraction states are EMT 3-phase resistors, voltage sources and switches. Testing of switches is not covered by examples in this PR.
• StateSpaceModalAnalysis is intentionally kept outside Simulation and MnaSolver; it operates on the extracted state-space model exposed by MNAStateSpaceExtractor.

Potential further steps:

• extend modal-analysis functionality, for example with participation factors, damping ratios, and additional modal metrics
• extend state-space extraction to other modeling domains, such as DP and SP
• support further component types, including composite network components
• support more variable components as the SSN component library is extended

Class interaction overview

classDiagram
    class Simulation
    class MnaSolver
    class MnaSolverDirect
    class StateSpaceExtractionTask

    class MNAStateSpaceExtractor
    class MNAStateSpaceContributor
    class MNAStateSpaceContributorFactory

    class InductorStateSpaceContributor
    class CapacitorStateSpaceContributor
    class SSNStateSpaceContributor

    class StateSpaceModalAnalysis

    Simulation --> MnaSolver : owns solver
    MnaSolver <|-- MnaSolverDirect
    MnaSolver --> MNAStateSpaceExtractor : owns
    MnaSolverDirect --> StateSpaceExtractionTask : creates
    StateSpaceExtractionTask --> MnaSolverDirect : calls

    MNAStateSpaceExtractor --> MNAStateSpaceContributorFactory : uses
    MNAStateSpaceContributorFactory ..> MNAStateSpaceContributor : creates
    MNAStateSpaceExtractor --> MNAStateSpaceContributor : owns contributors

    MNAStateSpaceContributor <|-- InductorStateSpaceContributor
    MNAStateSpaceContributor <|-- CapacitorStateSpaceContributor
    MNAStateSpaceContributor <|-- SSNStateSpaceContributor

    StateSpaceModalAnalysis ..> MNAStateSpaceExtractor : uses extracted state matrix

Loading

[codecov]

Codecov Report

❌ Patch coverage is 88.33333% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.00%. Comparing base (490b91e) to head (18ba87b).

Files with missing lines	Patch %	Lines
dpsim/src/MNAStateSpaceExtractor.cpp	87.36%	12 Missing ⚠️
dpsim/src/MNASolver.cpp	80.00%	5 Missing ⚠️
dpsim/src/StateSpaceModalAnalysis.cpp	80.00%	5 Missing ⚠️
dpsim/src/MNASolverDirect.cpp	75.00%	4 Missing ⚠️
dpsim/src/pybind/main.cpp	82.60%	4 Missing ⚠️
dpsim/src/Simulation.cpp	78.57%	3 Missing ⚠️
dpsim/src/MNAStateSpaceContributor.cpp	97.40%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #478      +/-   ##
==========================================
+ Coverage   65.50%   66.00%   +0.49%     
==========================================
  Files         395      401       +6     
  Lines       24006    24303     +297     
  Branches    12175    12332     +157     
==========================================
+ Hits        15725    16040     +315     
+ Misses       8280     8203      -77     
- Partials        1       60      +59     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.