ExciterDC1.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/ExciterDC1.h>
 
using namespace CPS;
 
Signal::ExciterDC1::ExciterDC1(const String &name, CPS::Logger::Level logLevel)
    : SimSignalComp(name, name, logLevel) {}
 
void Signal::ExciterDC1::setParameters(
    std::shared_ptr<Base::ExciterParameters> parameters) {
 
  if (auto params =
          std::dynamic_pointer_cast<Signal::ExciterDC1Parameters>(parameters)) {
    mParameters = params;
 
    if (mParameters->Tr == 0) {
      SPDLOG_LOGGER_ERROR(mSLog, "ExciterDC1: Tr must be non-zero (used as "
                                 "divisor in voltage transducer)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Tb == 0) {
      SPDLOG_LOGGER_ERROR(mSLog, "ExciterDC1: Tb must be non-zero (used as "
                                 "divisor in regulator lead-lag block)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Ta == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog,
          "ExciterDC1: Ta must be non-zero (used as divisor in amplifier)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Tf == 0) {
      SPDLOG_LOGGER_ERROR(mSLog,
                          "ExciterDC1: Tf must be non-zero (used as divisor in "
                          "stabilizing feedback)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Tef == 0) {
      SPDLOG_LOGGER_ERROR(mSLog, "ExciterDC1: Tef must be non-zero (used as "
                                 "divisor in exciter output)");
      throw CPS::InvalidArgumentException();
    }
    if (mParameters->Ka == 0) {
      SPDLOG_LOGGER_ERROR(
          mSLog, "ExciterDC1: Ka must be non-zero (used as divisor when "
                 "computing initial amplifier input)");
      throw CPS::InvalidArgumentException();
    }
 
    SPDLOG_LOGGER_INFO(mSLog,
                       "\nExciterDC1 parameters:"
                       "\nType: DC1"
                       "\nTr: {:e}"
                       "\nTa: {:e}"
                       "\nKa: {:e}"
                       "\nTb: {:e}"
                       "\nTc: {:e}"
                       "\nTef: {:e}"
                       "\nKef: {:e}"
                       "\nTf: {:e}"
                       "\nKf: {:e}"
                       "\nAef: {:e}"
                       "\nBef: {:e}"
                       "\nMaximum amplifier Voltage: {:e}"
                       "\nMinimum amplifier Voltage: {:e}\n",
                       mParameters->Tr, mParameters->Ta, mParameters->Ka,
                       mParameters->Tb, mParameters->Tc, mParameters->Tef,
                       mParameters->Kef, mParameters->Tf, mParameters->Kf,
                       mParameters->Aef, mParameters->Bef, mParameters->MaxVa,
                       mParameters->MinVa);
  } else {
    SPDLOG_LOGGER_ERROR(
        mSLog, "Type of parameters class of {} has to be ExciterDC1Parameters!",
        this->name());
    throw CPS::TypeException();
  }
}
 
void Signal::ExciterDC1::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;
 
  // ceiling function
  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;

  mVb = mVin;

  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,
                     "Actually applied excitation system initial values:"
                     "\nVref : {:e}"
                     "\ninit Vr: {:e}"
                     "\ninit Vf: {:e}"
                     "\ninit Vb: {:e}"
                     "\ninit Vin: {:e}"
                     "\ninit Va: {:e}",
                     mVref, mVr, mVf, mVb, mVin, mVa);
  mSLog->flush();
}
 
Real Signal::ExciterDC1::step(Real Vd, Real Vq, Real dt, Real Vpss) {
  // Voltage magnitude calculation
  mVh = sqrt(pow(Vd, 2.) + pow(Vq, 2.));
 
  // update state variables at time k-1
  mVr_prev = mVr;
  mVf_prev = mVf;
  mVb_prev = mVb;
  mVin_prev = mVin;
  mVa_prev = mVa;
  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
  mVr = mVr_prev + dt / mParameters->Tr * (mVh - mVr_prev);
 
  // Regulator output
  mVb = mVb_prev * (1 - dt / mParameters->Tb) +
        dt / mParameters->Tb * (mVref + Vpss - mVr_prev - mVf_prev);
  mVin = dt * (mParameters->Tc / mParameters->Tb) *
             (mVref + Vpss - mVr_prev - mVf_prev - mVb_prev) +
         mVb;
 
  // Amplifier
  mVa = mVa_prev +
        dt / mParameters->Ta * (mVin_prev * mParameters->Ka - mVa_prev);
  if (mVa > mParameters->MaxVa)
    mVa = mParameters->MaxVa;
  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;
}