Add variable SSN base and EMT 3-phase piecewise-linear inductor (sogno-platform#474)

This PR adds a variable EMT V-type SSN inheritance branch and a
three-phase, two-terminal piecewise-linear inductor with flux state.

Author: georgii-tishenin

dpsim-models/include/dpsim-models/Components.h

@@ -87,6 +87,7 @@
 
 #include <dpsim-models/EMT/EMT_SSNComp.h>
 #include <dpsim-models/EMT/EMT_VTypeSSNComp.h>
+#include <dpsim-models/EMT/EMT_VTypeVariableSSNComp.h>
 
 #include <dpsim-models/EMT/EMT_Ph1_Capacitor.h>
 #include <dpsim-models/EMT/EMT_Ph1_CurrentSource.h>
@@ -132,13 +133,15 @@
 #endif
 #include <dpsim-models/EMT/EMT_Ph3_NetworkInjection.h>
 #include <dpsim-models/EMT/EMT_Ph3_PiLine.h>
+#include <dpsim-models/EMT/EMT_Ph3_PiecewiseLinearInductor.h>
 #include <dpsim-models/EMT/EMT_Ph3_RXLoad.h>
 #include <dpsim-models/EMT/EMT_Ph3_RxLine.h>
 #include <dpsim-models/EMT/EMT_Ph3_Switch.h>
 #include <dpsim-models/EMT/EMT_Ph3_SynchronGeneratorIdeal.h>
 #include <dpsim-models/EMT/EMT_Ph3_SynchronGeneratorTrStab.h>
 #include <dpsim-models/EMT/EMT_Ph3_SynchronGeneratorVBR.h>
 #include <dpsim-models/EMT/EMT_Ph3_Transformer.h>
+#include <dpsim-models/EMT/EMT_Ph3_TwoTerminalVTypeVariableSSNComp.h>
 
 #include <dpsim-models/Signal/CosineFMGenerator.h>
 #include <dpsim-models/Signal/DecouplingLine.h>

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_GenericTwoTerminalVTypeSSN.h

@@ -25,7 +25,7 @@ class GenericTwoTerminalVTypeSSN final
                              Logger::Level logLevel = Logger::Level::off)
       : GenericTwoTerminalVTypeSSN(name, name, logLevel) {}
 
-  SimPowerComp<Real>::Ptr clone(String name) final;
+  SimPowerComp<Real>::Ptr clone(String name) override final;
 };
 
 } // namespace Ph3

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_PiecewiseLinearInductor.h

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
+// SPDX-License-Identifier: MPL-2.0
+
+#pragma once
+
+#include <vector>
+
+#include <dpsim-models/EMT/EMT_Ph3_TwoTerminalVTypeVariableSSNComp.h>
+
+namespace CPS {
+namespace EMT {
+namespace Ph3 {
+
+/// \brief Three-phase, two-terminal, piecewise-linear flux-state inductor.
+///
+/// The component uses the state choice
+///
+///   x = phi_abc
+///   u = v_abc
+///   y = i_abc
+///
+/// with
+///
+///   d(phi)/dt = v
+///
+/// and a piecewise-linear constitutive relation
+///
+///   i_abc = f(phi_abc)
+///
+/// The piecewise-linear characteristic is assumed to be odd-symmetric and is
+/// provided by non-negative breakpoint vectors for flux and current.
+class PiecewiseLinearInductor final
+    : public TwoTerminalVTypeVariableSSNComp,
+      public SharedFactory<PiecewiseLinearInductor> {
+private:
+  std::vector<Real> mFluxBreakpoints;
+  std::vector<Real> mCurrentBreakpoints;
+
+  std::pair<Real, Real> slopeAndOffsetFromFlux(Real flux) const;
+
+protected:
+  Bool updateComponentParameters() override final;
+
+public:
+  using SharedFactory<PiecewiseLinearInductor>::make;
+
+  PiecewiseLinearInductor(String uid, String name,
+                          Logger::Level logLevel = Logger::Level::off);
+  PiecewiseLinearInductor(String name,
+                          Logger::Level logLevel = Logger::Level::off)
+      : PiecewiseLinearInductor(name, name, logLevel) {}
+
+  SimPowerComp<Real>::Ptr clone(String name) override final;
+
+  void setParameters(const std::vector<Real> &fluxBreakpoints,
+                     const std::vector<Real> &currentBreakpoints);
+};
+
+} // namespace Ph3
+} // namespace EMT
+} // namespace CPS

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_SSN_Full_Serial_RLC.h

@@ -41,7 +41,7 @@ class Full_Serial_RLC final : public TwoTerminalVTypeSSNComp,
   Full_Serial_RLC(String name, Logger::Level logLevel = Logger::Level::off)
       : Full_Serial_RLC(name, name, logLevel) {}
 
-  SimPowerComp<Real>::Ptr clone(String name) override;
+  SimPowerComp<Real>::Ptr clone(String name) override final;
 
   void setParameters(const Matrix &resistance, const Matrix &inductance,
                      const Matrix &capacitance);

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_SSN_Inductor.h

@@ -36,7 +36,7 @@ class Inductor final : public TwoTerminalVTypeSSNComp,
   Inductor(String name, Logger::Level logLevel = Logger::Level::off)
       : Inductor(name, name, logLevel) {}
 
-  SimPowerComp<Real>::Ptr clone(String name) override;
+  SimPowerComp<Real>::Ptr clone(String name) override final;
 
   void setParameters(const Matrix &inductance);
 };

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_TwoTerminalVTypeSSNComp.h

@@ -21,12 +21,13 @@ class TwoTerminalVTypeSSNComp : public VTypeSSNComp {
   TwoTerminalVTypeSSNComp(String uid, String name,
                           Logger::Level logLevel = Logger::Level::off);
 
-  MatrixComp buildInitialInputFromNodes(Real frequency) final;
+  MatrixComp buildInitialInputFromNodes(Real frequency) override final;
 
 public:
-  void mnaCompApplySystemMatrixStamp(SparseMatrixRow &systemMatrix) final;
-  void mnaCompApplyRightSideVectorStamp(Matrix &rightVector) final;
-  void mnaCompUpdateVoltage(const Matrix &leftVector) final;
+  void
+  mnaCompApplySystemMatrixStamp(SparseMatrixRow &systemMatrix) override final;
+  void mnaCompApplyRightSideVectorStamp(Matrix &rightVector) override final;
+  void mnaCompUpdateVoltage(const Matrix &leftVector) override final;
 };
 
 } // namespace Ph3

dpsim-models/include/dpsim-models/EMT/EMT_Ph3_TwoTerminalVTypeVariableSSNComp.h

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
+// SPDX-License-Identifier: MPL-2.0
+
+#pragma once
+
+#include <dpsim-models/EMT/EMT_VTypeVariableSSNComp.h>
+
+namespace CPS {
+namespace EMT {
+namespace Ph3 {
+
+/// \brief Abstract base class for three-phase, two-terminal, variable V-type
+/// SSN components.
+///
+/// This class implements the common three-phase/two-terminal logic:
+/// - reconstruction of the initial input voltage from terminal phasors
+/// - conductance matrix stamp
+/// - right-side history current stamp
+/// - interface voltage update from the MNA solution
+class TwoTerminalVTypeVariableSSNComp : public VTypeVariableSSNComp {
+protected:
+  TwoTerminalVTypeVariableSSNComp(String uid, String name,
+                                  Logger::Level logLevel = Logger::Level::off);
+
+  MatrixComp buildInitialInputFromNodes(Real frequency) override final;
+
+public:
+  void
+  mnaCompApplySystemMatrixStamp(SparseMatrixRow &systemMatrix) override final;
+  void mnaCompApplyRightSideVectorStamp(Matrix &rightVector) override final;
+  void mnaCompUpdateVoltage(const Matrix &leftVector) override final;
+};
+
+} // namespace Ph3
+} // namespace EMT
+} // namespace CPS

dpsim-models/include/dpsim-models/EMT/EMT_SSNComp.h

@@ -11,14 +11,10 @@ namespace EMT {
 
 /// \brief Abstract base class for EMT state-space nodal (SSN) components.
 ///
-/// This class provides the generic state-space and scheduling logic shared by
-/// all SSN component types:
-/// - storage of state-space matrices A, B, C, D
-/// - calculation of trapezoidal discrete-time matrices
-/// - steady-state initialization helpers
-/// - history-vector calculation
-/// - state update
-/// - generic pre-step and post-step dependency registration
+/// This class implements the common linear SSN logic shared by derived
+/// component types, including state-space parameter storage, trapezoidal
+/// discretization, steady-state initialization helpers, history-vector
+/// calculation, state update, and generic MNA scheduling.
 ///
 /// The exact interpretation of input and output quantities is defined in
 /// derived classes.
@@ -28,6 +24,8 @@ class SSNComp : public MNASimPowerComp<Real> {
   const Int mOutputSize;
 
 protected:
+  Real mTimeStep;
+
   Matrix mW;
   Matrix mYHist;
 
@@ -39,12 +37,12 @@ class SSNComp : public MNASimPowerComp<Real> {
   Matrix mdA;
   Matrix mdB;
 
-  const CPS::Attribute<Matrix>::Ptr mX;
+  const Attribute<Matrix>::Ptr mX;
 
   SSNComp(String uid, String name, Int inputSize, Int outputSize,
           Logger::Level logLevel = Logger::Level::off);
 
-  Matrix calculateHistoryVector() const;
+  virtual Matrix calculateHistoryVector() const;
 
   MatrixComp calculateSteadyStateStateFromInput(const MatrixComp &u,
                                                 Real frequency) const;
@@ -53,6 +51,11 @@ class SSNComp : public MNASimPowerComp<Real> {
 
   void updateState(const Matrix &uOld, const Matrix &uNew);
 
+  void recomputeDiscreteModel();
+
+  /// Hook for variable/time-varying SSN components.
+  virtual void updateStateSpaceModel();
+
   virtual Attribute<Matrix>::Ptr inputAttribute() const = 0;
   virtual Attribute<Matrix>::Ptr outputAttribute() const = 0;
 
@@ -61,20 +64,20 @@ class SSNComp : public MNASimPowerComp<Real> {
                      const Matrix &D);
 
   void mnaCompInitialize(Real omega, Real timeStep,
-                         Attribute<Matrix>::Ptr leftVector) final;
+                         Attribute<Matrix>::Ptr leftVector) override final;
 
-  void
-  mnaCompAddPreStepDependencies(AttributeBase::List &prevStepDependencies,
-                                AttributeBase::List &attributeDependencies,
-                                AttributeBase::List &modifiedAttributes) final;
+  void mnaCompAddPreStepDependencies(
+      AttributeBase::List &prevStepDependencies,
+      AttributeBase::List &attributeDependencies,
+      AttributeBase::List &modifiedAttributes) override final;
 
-  void mnaCompPreStep(Real time, Int timeStepCount) final;
+  void mnaCompPreStep(Real time, Int timeStepCount) override final;
 
-  void
-  mnaCompAddPostStepDependencies(AttributeBase::List &prevStepDependencies,
-                                 AttributeBase::List &attributeDependencies,
-                                 AttributeBase::List &modifiedAttributes,
-                                 Attribute<Matrix>::Ptr &leftVector) final;
+  void mnaCompAddPostStepDependencies(
+      AttributeBase::List &prevStepDependencies,
+      AttributeBase::List &attributeDependencies,
+      AttributeBase::List &modifiedAttributes,
+      Attribute<Matrix>::Ptr &leftVector) override final;
 };
 
 } // namespace EMT

dpsim-models/include/dpsim-models/EMT/EMT_VTypeSSNComp.h

@@ -22,20 +22,20 @@ class VTypeSSNComp : public SSNComp {
   VTypeSSNComp(String uid, String name, Int inputSize, Int outputSize,
                Logger::Level logLevel = Logger::Level::off);
 
-  Attribute<Matrix>::Ptr inputAttribute() const final;
-  Attribute<Matrix>::Ptr outputAttribute() const final;
+  Attribute<Matrix>::Ptr inputAttribute() const override final;
+  Attribute<Matrix>::Ptr outputAttribute() const override final;
 
   // Reconstruct the steady-state SSN input vector from node/terminal data.
   // For V-type SSN components, this corresponds to the interface voltage input.
   virtual MatrixComp buildInitialInputFromNodes(Real frequency) = 0;
 
 public:
-  void initializeFromNodesAndTerminals(Real frequency) final;
+  void initializeFromNodesAndTerminals(Real frequency) override;
 
-  void mnaCompUpdateCurrent(const Matrix &leftVector) final;
+  void mnaCompUpdateCurrent(const Matrix &leftVector) override final;
 
   void mnaCompPostStep(Real time, Int timeStepCount,
-                       Attribute<Matrix>::Ptr &leftVector) final;
+                       Attribute<Matrix>::Ptr &leftVector) override final;
 };
 
 } // namespace EMT

dpsim-models/include/dpsim-models/EMT/EMT_VTypeVariableSSNComp.h

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
+// SPDX-License-Identifier: MPL-2.0
+
+#pragma once
+
+#include <dpsim-models/EMT/EMT_VTypeSSNComp.h>
+#include <dpsim-models/Solver/MNAVariableCompInterface.h>
+
+namespace CPS {
+namespace EMT {
+
+/// \brief Abstract base class for variable EMT V-type SSN components.
+///
+/// This class extends VTypeSSNComp with support for time-varying or
+/// piecewise-linear state-space models whose MNA conductance stamp may change
+/// during simulation. An affine output term
+///
+///   y = C x + D u + F
+///
+/// is supported in addition to the linear state-space model.
+class VTypeVariableSSNComp : public VTypeSSNComp,
+                             public MNAVariableCompInterface {
+private:
+  Bool mParameterChanged;
+  Matrix mF;
+
+protected:
+  VTypeVariableSSNComp(String uid, String name, Int inputSize, Int outputSize,
+                       Logger::Level logLevel = Logger::Level::off);
+
+  Matrix calculateHistoryVector() const override final;
+  void updateStateSpaceModel() override final;
+
+  const Matrix &outputOffset() const;
+  void setOutputOffset(const Matrix &F);
+
+  /// Update the current stepwise-linearized component model.
+  /// Returns true if the MNA conductance stamp changed.
+  virtual Bool updateComponentParameters() = 0;
+
+public:
+  Bool hasParameterChanged() override final;
+
+  void initializeFromNodesAndTerminals(Real frequency) override final;
+};
+
+} // namespace EMT
+} // namespace CPS