Reader.h

Go to the documentation of this file.

/* Copyright 2017-2021 Institute for Automation of Complex Power Systems,
 *                     EONERC, RWTH Aachen University
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *********************************************************************************/
 
#pragma once
 
#include <list>
#include <map>
#include <type_traits>
#include <utility>
 
#include <dpsim-models/Components.h>
#include <dpsim-models/Definitions.h>
#include <dpsim-models/Filesystem.h>
#include <dpsim-models/Logger.h>
#include <dpsim-models/SimNode.h>
#include <dpsim-models/SimPowerComp.h>
#include <dpsim-models/SimTerminal.h>
#include <dpsim-models/SystemTopology.h>
 
/* ====== WARNING =======
 *
 * DO NOT INCLUDE ANY CIM++ Headers here!
 *
 * CIM++ has more than 600 Headers files.
 * Including them here will also include them in <DPsim.h>
 * Which will have a huge impact on compile time!
 *
 * Use forward declarations instead!
 */
 
/* Forward declarations */
class CIMModel;
class BaseClass;
#ifdef CGMES_BUILD
#include <UnitMultiplier.hpp>
namespace CIMPP {
class SvVoltage;
class SvPowerFlow;
class ACLineSegment;
class SynchronousMachine;
class ExternalNetworkInjection;
class EnergyConsumer;
class PowerTransformer;
class EquivalentShunt;
class TopologicalNode;
class ConductingEquipment;
class Disconnector;
class Breaker;
}; // namespace CIMPP
#else
#include <CIMNamespaces.hpp>
#endif
 
namespace CPS {
namespace CIM {
template <typename T, typename = void>
struct has_value_member : std::false_type {};
 
template <typename T>
struct has_value_member<T,
                        std::void_t<decltype(std::declval<const T &>().value)>>
    : std::true_type {};
 
template <typename T> const auto &cimString(const T &field) {
  if constexpr (has_value_member<T>::value) {
    return field.value;
  } else {
    return field;
  }
}
 
class InvalidTopology {};
 
class Reader {
public:
  enum class VoltageTargetUnit { Auto, PerUnit, Absolute };
 
private:
  Logger::Log mSLog;
  Logger::Level mComponentLogLevel;
  CIMModel *mModel;
  IdentifiedObject::List mComponents;
  Real mFrequency;
  Real mOmega;
  Domain mDomain;
  GeneratorType mGeneratorType;
  PhaseType mPhase;
  std::map<String, TopologicalNode::Ptr> mPowerflowNodes;
  std::map<String, TopologicalPowerComp::Ptr> mPowerflowEquipment;
  std::map<String, TopologicalTerminal::Ptr> mPowerflowTerminals;
  Bool mUseProtectionSwitches = false;
  VoltageTargetUnit mExtnetVoltageTargetUnit = VoltageTargetUnit::Auto;
 
  // #### shunt component settings ####
  Bool mSetShuntCapacitor = false;
  Real mShuntCapacitorValue = -1;
  Bool mSetShuntConductance = false;
  Real mShuntConductanceValue = 1e-6;
 
  // #### General Functions ####
  static Real unitValue(Real value, CIMPP::UnitMultiplier mult);
  void processSvVoltage(CIMPP::SvVoltage *volt);
  void processSvPowerFlow(CIMPP::SvPowerFlow *flow);
  template <typename VarType>
  void processTopologicalNode(CIMPP::TopologicalNode *topNode);
  void addFiles(const fs::path &filename);
  void addFiles(const std::list<fs::path> &filenames);
  void parseFiles();
  SystemTopology systemTopology();
 
  // #### Mapping Functions ####
  Matrix::Index mapTopologicalNode(String mrid);
  TopologicalPowerComp::Ptr mapComponent(BaseClass *obj);
  Bool isSupportedConductingEquipment(BaseClass *obj) const;
  TopologicalPowerComp::Ptr mapACLineSegment(CIMPP::ACLineSegment *line);
  TopologicalPowerComp::Ptr mapPowerTransformer(CIMPP::PowerTransformer *trans);
  TopologicalPowerComp::Ptr
  mapSynchronousMachine(CIMPP::SynchronousMachine *machine);
  TopologicalPowerComp::Ptr mapEnergyConsumer(CIMPP::EnergyConsumer *consumer);
  TopologicalPowerComp::Ptr
  mapExternalNetworkInjection(CIMPP::ExternalNetworkInjection *extnet);
  TopologicalPowerComp::Ptr mapEquivalentShunt(CIMPP::EquivalentShunt *shunt);
  TopologicalPowerComp::Ptr mapDisconnector(CIMPP::Disconnector *disc);
  TopologicalPowerComp::Ptr mapBreaker(CIMPP::Breaker *cb);
 
  // #### Helper Functions ####
  Real determineBaseVoltageAssociatedWithEquipment(
      CIMPP::ConductingEquipment *equipment);
 
public:
  Reader(String name, Logger::Level logLevel = Logger::Level::info,
         Logger::Level componentLogLevel = Logger::Level::off);
  virtual ~Reader();

  SystemTopology loadCIM(Real systemFrequency, const fs::path &filename,
                         Domain domain = Domain::DP,
                         PhaseType phase = PhaseType::Single,
                         GeneratorType genType = GeneratorType::None);
  SystemTopology loadCIM(Real systemFrequency,
                         const std::list<fs::path> &filenames,
                         Domain domain = Domain::DP,
                         PhaseType phase = PhaseType::Single,
                         GeneratorType genType = GeneratorType::None);
  SystemTopology loadCIM(Real systemFrequency,
                         const std::list<CPS::String> &filenamesString,
                         Domain domain = Domain::DP,
                         PhaseType phase = PhaseType::Single,
                         GeneratorType genType = GeneratorType::None);
 
  // #### shunt component settings ####
  void setShuntCapacitor(Real v);
  void setShuntConductance(Real v);
  void useProtectionSwitches(Bool value = true);
  void setExtnetVoltageTargetUnit(VoltageTargetUnit unit);
};
} // namespace CIM
} // namespace CPS
 
#if defined(BASECLASS_H) && !defined(READER_CPP)
#error "Do not include CIMpp headers into CPS/DPsim headers!"
#endif