StateSpaceModalAnalysis.h

// SPDX-FileCopyrightText: 2026 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
// SPDX-License-Identifier: MPL-2.0
#pragma once
 
#include <dpsim/Definitions.h>
#include <dpsim/MNAStateSpaceExtractor.h>
 
#include <vector>
 
namespace DPsim {
 
enum class StateSpaceAnalysisFrame {
  Native,
  GlobalDQ0,
};

class StateSpaceModalAnalysis {
public:
  explicit StateSpaceModalAnalysis(const MNAStateSpaceExtractor &extractor);

  void setAnalysisFrame(StateSpaceAnalysisFrame frame) {
    mAnalysisFrame = frame;
  }

  void setGlobalDq0Frame(Real omega, Real theta0 = 0.0) {
    mGlobalOmega = omega;
    mGlobalTheta0 = theta0;
  }

  void update();

  const CPS::VectorComp &getDiscreteEigenvalues() const {
    return mDiscreteEigenvalues;
  }

  const CPS::VectorComp &getContinuousEigenvalues() const {
    return mContinuousEigenvalues;
  }

  const CPS::MatrixComp &getRightEigenvectors() const {
    return mRightEigenvectors;
  }

  const CPS::MatrixComp &getLeftEigenvectors() const {
    return mLeftEigenvectors;
  }

  const CPS::MatrixComp &getParticipationFactors() const {
    return mParticipationFactors;
  }

  const std::vector<String> &getStateNames() const { return mStateNames; }
 
private:
  Matrix buildDiscreteStateMatrixInAnalysisFrame() const;
 
  Matrix buildGlobalDq0Transformation(Real theta) const;
 
  std::vector<String> buildStateNamesInAnalysisFrame() const;
 
  Complex mapDiscreteToContinuous(const Complex &z) const;
 
  const MNAStateSpaceExtractor &mExtractor;
 
  StateSpaceAnalysisFrame mAnalysisFrame = StateSpaceAnalysisFrame::Native;
 
  Real mGlobalOmega = 0.0;
 
  Real mGlobalTheta0 = 0.0;
 
  CPS::VectorComp mDiscreteEigenvalues;
 
  CPS::VectorComp mContinuousEigenvalues;
 
  CPS::MatrixComp mRightEigenvectors;
  CPS::MatrixComp mLeftEigenvectors;
  CPS::MatrixComp mParticipationFactors;
 
  std::vector<String> mStateNames;
};
 
} // namespace DPsim