EMT_Ph3_SSN_GFM.h

Go to the documentation of this file.

// 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 {

class SSN_GFM final : public TwoTerminalVTypeVariableSSNComp,
                      public SharedFactory<SSN_GFM> {
 
private:
  static constexpr Int mStateSize = 17;
  static constexpr Int mInputSize = 3;
  static constexpr Int mOutputSize = 3;
 
  enum StateIndex : Int {
    PFiltered = 0,
    QFiltered = 1,
    Omega = 2,
    Theta = 3,
    VoltageMagnitude = 4,
 
    VoltageIntegratorD = 5,
    VoltageIntegratorQ = 6,
 
    CurrentIntegratorD = 7,
    CurrentIntegratorQ = 8,
 
    DelayVoltageD = 9,
    DelayVoltageQ = 10,
 
    VcA = 11,
    VcB = 12,
    VcC = 13,
 
    IfA = 14,
    IfB = 15,
    IfC = 16
  };
 
  // Electrical parameters
  Real mLf;
  Real mCf;
  Real mRf;
  Real mRc;
 
  // Nominal quantities and references
  Real mOmegaN;
  Real mNominalVoltage;
  Real mPRef;
  Real mQRef;
 
  // VSG parameters
  Real mVirtualInertia;
  Real mDampingCoefficient;
  Real mVoltageDroopGain;
  Real mReactiveIntegralGain;
 
  // Voltage controller
  Real mKpVoltage;
  Real mKiVoltage;
 
  // Current controller
  Real mKpCurrent;
  Real mKiCurrent;
 
  // Active damping and measurement dynamics
  Real mActiveDampingGain;
  Real mPowerFilterCutoff;
  Real mDelayBandwidth;
 
  // Virtual output impedance (opt-in). Zero recovers the islanded model.
  Real mVirtualResistance;
  Real mVirtualReactance;
 
  // Scale on the grid-current feedforward in the voltage loop (1 = islanded).
  Real mGridCurrentFeedforward;
 
  // Proportional Q-V droop (opt-in). Cutoff > 0 selects droop over the integral
  // excitation. Setpoint is captured at initialization.
  Real mReactivePowerDroop;
  Real mReactiveDroopCutoff;
  Real mVoltageSetpoint;
 
  // Numerical linearization settings
  Real mJacobianRelativeStep;
  Real mJacobianAbsoluteStep;
 
  // Logging attributes
  const Attribute<Real>::Ptr mPInst;
  const Attribute<Real>::Ptr mQInst;
  const Attribute<Real>::Ptr mOmegaGFM;
  const Attribute<Real>::Ptr mThetaGFM;
  const Attribute<Real>::Ptr mVoltageMagnitudeGFM;
 
  const Attribute<Real>::Ptr mVcD;
  const Attribute<Real>::Ptr mVcQ;
 
  const Attribute<Real>::Ptr mIGridD;
  const Attribute<Real>::Ptr mIGridQ;
 
  const Attribute<Real>::Ptr mIfD;
  const Attribute<Real>::Ptr mIfQ;
 
  const Attribute<Real>::Ptr mVoltageReferenceD;
  const Attribute<Real>::Ptr mVoltageReferenceQ;
 
  Matrix getParkTransformMatrix(Real theta) const;
 
  Matrix getInverseParkTransformMatrix(Real theta) const;

  void evaluateStateDerivative(const Matrix &x, const Matrix &u,
                               Matrix &stateDerivative) const;

  void evaluateOutput(const Matrix &x, const Matrix &u, Matrix &output) const;

  void buildStateSpaceModel(const Matrix &x, const Matrix &u, Matrix &A,
                            Matrix &B, Matrix &C, Matrix &D, Matrix &E,
                            Matrix &F) const;

  Real regularizedOmega(Real omega) const;
 
protected:
  Bool updateComponentParameters() override final;
 
  void updateLogAttributes(const Matrix &u) const override final;
 
public:
  using SharedFactory<SSN_GFM>::make;
 
  SSN_GFM(String uid, String name, Logger::Level logLevel = Logger::Level::off);
 
  SSN_GFM(String name, Logger::Level logLevel = Logger::Level::off)
      : SSN_GFM(name, name, logLevel) {}
 
  std::vector<String> getLocalStateNames() const override final;
  Matrix getState() const;
  Matrix getStateDerivative() const;
  Matrix getInterfaceVoltage() const;
  Matrix getInterfaceCurrent() const;
  std::vector<SSNComp::LocalAbcStateBlock>
  getLocalAbcStateBlocks() const override final;

  void setParameters(Real lf, Real cf, Real rf, Real rc, Real nominalVoltage,
                     Real omegaN, Real pRef, Real qRef, Real virtualInertia,
                     Real dampingCoefficient, Real voltageDroopGain,
                     Real reactiveIntegralGain, Real kpVoltage, Real kiVoltage,
                     Real kpCurrent, Real kiCurrent, Real activeDampingGain,
                     Real powerFilterCutoff, Real delayBandwidth);

  void setNumericalLinearizationParameters(Real relativeStep,
                                           Real absoluteStep);

  void setVirtualImpedance(Real virtualResistance, Real virtualReactance = 0.0);

  void setGridCurrentFeedforward(Real scale);

  void setReactivePowerDroop(Real droopGain, Real cutoff);

  void calculateAnalyticalJacobians(const Matrix &x, const Matrix &u, Matrix &A,
                                    Matrix &B, Matrix &C, Matrix &D) const;

  void calculateNumericalJacobians(const Matrix &x, const Matrix &u, Matrix &A,
                                   Matrix &B, Matrix &C, Matrix &D) const;
 
  void initializeFromNodesAndTerminals(Real frequency) override final;
};
 
} // namespace Ph3
} // namespace EMT
} // namespace CPS