ExciterDC1Simp.cpp

// SPDX-FileCopyrightText: 2025 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
// SPDX-License-Identifier: MPL-2.0
 
#include <dpsim-models/Signal/ExciterDC1Simp.h>
 
using namespace CPS;
using namespace CPS::Signal;
 
ExciterDC1Simp::ExciterDC1Simp(const String &name, CPS::Logger::Level logLevel)
    : SimSignalComp(name, name, logLevel),
      mVh(mAttributes->create<Real>("Vh", 0)),
      mVr(mAttributes->create<Real>("Vr", 0)),
      mEf(mAttributes->create<Real>("Ef", 0.0)) {}
 
void ExciterDC1Simp::setParameters(
    std::shared_ptr<Base::ExciterParameters> parameters) {
 
  if (auto params = std::dynamic_pointer_cast<Signal::ExciterDC1SimpParameters>(
          parameters)) {
    mParameters = params;
 
    if (mParameters->Tr == 0) {
      SPDLOG_LOGGER_ERROR(mSLog, "ExciterDC1Simp: Tr must be non-zero (used as "
                                 "divisor in voltage transducer)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Ta == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog,
          "ExciterDC1Simp: Ta must be non-zero (used as divisor in amplifier)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Tf == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog, "ExciterDC1Simp: Tf must be non-zero (used as divisor "
                 "in stabilizing feedback)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Tef == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog, "ExciterDC1Simp: Tef must be non-zero (used as divisor "
                 "in exciter output)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Ka == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog, "ExciterDC1Simp: Ka must be non-zero (used as divisor "
                 "when computing initial amplifier input)");
      throw CPS::InvalidArgumentException();
    }
 
    SPDLOG_LOGGER_INFO(mSLog,
                       "\nExciterDC1Simp parameters:"
                       "\nTa: {:e}"
                       "\nKa: {:e}"
                       "\nTef: {:e}"
                       "\nKef: {:e}"
                       "\nTf: {:e}"
                       "\nKf: {:e}"
                       "\nTr: {:e}"
                       "\nAef: {:e}"
                       "\nBef: {:e}"
                       "\nMaximum amplifier Voltage: {:e}"
                       "\nMinimum amplifier Voltage: {:e}\n",
                       mParameters->Ta, mParameters->Ka, mParameters->Tef,
                       mParameters->Kef, mParameters->Tf, mParameters->Kf,
                       mParameters->Tr, mParameters->Aef, mParameters->Bef,
                       mParameters->MaxVa, mParameters->MinVa);
  } else {
    SPDLOG_LOGGER_ERROR(
        mSLog, "Type of parameters class of {} has to be ExciterDC1Simp!",
        this->name());
    throw CPS::TypeException();
  }
}
 
void ExciterDC1Simp::initializeStates(Real Vh_init, Real Ef_init) {
  //
  **mVh = Vh_init;
  **mEf = Ef_init;
  SPDLOG_LOGGER_INFO(mSLog,
                     "Initially set excitation system initial values:"
                     "\ninit Vh: {:e}"
                     "\ninit Ef: {:e}",
                     **mVh, **mEf);

  **mVr = **mVh;

  mVf = 0.0;

  mVsat = mParameters->Aef * exp(mParameters->Bef * abs(**mEf));

  mVa = mParameters->Kef * **mEf + mVsat * **mEf;
  if (mVa > mParameters->MaxVa)
    mVa = mParameters->MaxVa;
  if (mVa < mParameters->MinVa)
    mVa = mParameters->MinVa;

  mVin = mVa / mParameters->Ka;

  mVref = **mVr + mVin;

  if (std::abs(**mEf - mVa / (mVsat + mParameters->Kef)) > DOUBLE_EPSILON)
    SPDLOG_LOGGER_WARN(mSLog, "\nInitial conditions are not consistent!!!");
 
  SPDLOG_LOGGER_INFO(mSLog,
                     "\nActually applied excitation system initial values:"
                     "\nVref : {:e}"
                     "\ninit_Vr: {:e}"
                     "\ninit_Ef: {:e}"
                     "\ninit_Va: {:e}",
                     mVref, **mVr, **mEf, mVa);
  mSLog->flush();
}
 
Real ExciterDC1Simp::step(Real mVd, Real mVq, Real dt, Real Vpss) {
  // Voltage magnitude calculation
  **mVh = sqrt(pow(mVd, 2.) + pow(mVq, 2.));
 
  // update state variables at time k-1
  mVr_prev = **mVr;
  mVa_prev = mVa;
  mVf_prev = mVf;
  mEf_prev = **mEf;
 
  // compute state variables at time k using euler forward
 
  // saturation function
  mVsat = mParameters->Aef * exp(mParameters->Bef * abs(mEf_prev));
 
  // Voltage Transducer equation
  **mVr = **mVr + dt / mParameters->Tr * (**mVh - **mVr);
 
  // Voltage amplifier equation
  mVin = mVref + Vpss - **mVr - mVf;
  mVa = mVa_prev + dt / mParameters->Ta * (mVin * mParameters->Ka - mVa_prev);
  if (mVa > mParameters->MaxVa)
    mVa = mParameters->MaxVa;
  else if (mVa < mParameters->MinVa)
    mVa = mParameters->MinVa;
 
  // Stabilizing feedback
  mVf = (1. - dt / mParameters->Tf) * mVf_prev +
        dt * mParameters->Kf / (mParameters->Tf * mParameters->Tef) *
            (mVa_prev - (mVsat + mParameters->Kef) * mEf_prev);
 
  // Exciter output
  **mEf = mEf_prev + dt / mParameters->Tef *
                         (mVa_prev - (mVsat + mParameters->Kef) * mEf_prev);
 
  return **mEf;
}