HydroTurbineGovernor.cpp

// SPDX-FileCopyrightText: 2026 Institute for Automation of Complex Power Systems, EONERC, RWTH Aachen University
// SPDX-License-Identifier: MPL-2.0
 
#include <dpsim-models/Signal/HydroTurbineGovernor.h>
 
using namespace CPS;
using namespace CPS::Signal;
 
Signal::HydroTurbineGovernor::HydroTurbineGovernor(const String &name,
                                                   CPS::Logger::Level logLevel)
    : SimSignalComp(name, name, logLevel),
      mDelOm(mAttributes->create<Real>("DelOm")),
      mX1(mAttributes->create<Real>("X1")),
      mX2(mAttributes->create<Real>("X2")),
      mPgv(mAttributes->create<Real>("Pgv")) {}
 
void HydroTurbineGovernor::setParameters(
    std::shared_ptr<Base::GovernorParameters> parameters) {
  auto params =
      std::dynamic_pointer_cast<Signal::HydroGovernorParameters>(parameters);
  if (!params) {
    SPDLOG_LOGGER_ERROR(
        mSLog,
        "Type of parameters class of {} has to be HydroGovernorParameters!",
        this->name());
    throw CPS::TypeException();
  }
  if (params->R <= 0) {
    SPDLOG_LOGGER_ERROR(mSLog, "R must be positive for {}", this->name());
    throw CPS::InvalidArgumentException();
  }
  if (params->T1 <= 0) {
    SPDLOG_LOGGER_ERROR(mSLog, "T1 must be positive for {}", this->name());
    throw CPS::InvalidArgumentException();
  }
  if (params->T3 <= 0) {
    SPDLOG_LOGGER_ERROR(mSLog, "T3 must be positive for {}", this->name());
    throw CPS::InvalidArgumentException();
  }
  if (params->T1 == params->T3) {
    SPDLOG_LOGGER_ERROR(mSLog, "T1 must not equal T3 for {}", this->name());
    throw CPS::InvalidArgumentException();
  }
  mParameters = params;
 
  SPDLOG_LOGGER_INFO(mSLog,
                     "\nHydro Governor parameters:"
                     "\nOmRef: {:e}"
                     "\nR: {:e}"
                     "\nT1: {:e}"
                     "\nT2: {:e}"
                     "\nT3: {:e}"
                     "\nPmax: {:e}"
                     "\nPmin: {:e}\n",
                     mParameters->OmRef, mParameters->R, mParameters->T1,
                     mParameters->T2, mParameters->T3, mParameters->Pmax,
                     mParameters->Pmin);
  mSLog->flush();
}
 
void HydroTurbineGovernor::initializeStates(Real Pref) {
  if (Pref < mParameters->Pmin || Pref > mParameters->Pmax) {
    SPDLOG_LOGGER_ERROR(
        mSLog,
        "Pref of hydro governor {} must be in [Pmin, Pmax] = [{:f}, {:f}] pu",
        this->name(), mParameters->Pmin, mParameters->Pmax);
    throw CPS::InvalidArgumentException();
  }
  mPref = Pref;
  **mDelOm = 0;
  mDelOm_prev = 0;
  **mX1 = 0;
  mX1_prev = 0;
  **mX2 = 0;
  mX2_prev = 0;
  **mPgv = Pref;
 
  mCa =
      (mParameters->T1 - mParameters->T2) / (mParameters->T1 - mParameters->T3);
  mCb =
      (mParameters->T2 - mParameters->T3) / (mParameters->T1 - mParameters->T3);
 
  SPDLOG_LOGGER_INFO(mSLog,
                     "\nHydro Governor initial values:"
                     "\nPref: {:f}"
                     "\nDelOm: {:f}"
                     "\nX1: {:f}"
                     "\nX2: {:f}"
                     "\nPgv: {:f}",
                     mPref, **mDelOm, **mX1, **mX2, **mPgv);
  mSLog->flush();
}
 
Real HydroTurbineGovernor::step(Real Omega, Real dt) {
  // Shift state variables one step back
  mDelOm_prev = **mDelOm;
  mX1_prev = **mX1;
  mX2_prev = **mX2;
 
  // Compute input deviation
  **mDelOm = mParameters->OmRef - Omega;
 
  // Update PT1 states with forward Euler
  **mX1 = mX1_prev + (dt / mParameters->T1) * (mDelOm_prev - mX1_prev);
  **mX2 = mX2_prev + (dt / mParameters->T3) * (mDelOm_prev - mX2_prev);
 
  // Compute governor output before limiter
  Real Pgv_raw = mPref + (1.0 / mParameters->R) * (**mX1 * mCa + **mX2 * mCb);
 
  // Apply output limiter
  if (Pgv_raw > mParameters->Pmax)
    **mPgv = mParameters->Pmax;
  else if (Pgv_raw < mParameters->Pmin)
    **mPgv = mParameters->Pmin;
  else
    **mPgv = Pgv_raw;
 
  return **mPgv;
}