11#include <pybind11/complex.h>
12#include <pybind11/eigen.h>
13#include <pybind11/functional.h>
14#include <pybind11/iostream.h>
15#include <pybind11/pybind11.h>
16#include <pybind11/stl.h>
19#include <dpsim-models/IdentifiedObject.h>
20#include <dpsim/RealTimeSimulation.h>
21#include <dpsim/Simulation.h>
23#include <dpsim-models/CSVReader.h>
25#include <dpsim/pybind/Attributes.h>
26#include <dpsim/pybind/BaseComponents.h>
27#include <dpsim/pybind/DPComponents.h>
28#include <dpsim/pybind/EMTComponents.h>
29#include <dpsim/pybind/SPComponents.h>
30#include <dpsim/pybind/SignalComponents.h>
31#include <dpsim/pybind/Utils.h>
35namespace py = pybind11;
36using namespace pybind11::literals;
38PYBIND11_MODULE(dpsimpy, m) {
41 -----------------------
42 The Python bindings provide access to most of the DPsim features implemented in C++.
43 It is possible to run powerflow, quasi-static, dynamic phasor and electromagnetic transient simulations
44 and to parameterize all components of the network from Python.
48 py::enum_<CPS::Logger::Level>(m,
"LogLevel")
49 .value(
"trace", CPS::Logger::Level::trace)
50 .value(
"debug", CPS::Logger::Level::debug)
51 .value(
"info", CPS::Logger::Level::info)
52 .value(
"warn", CPS::Logger::Level::warn)
53 .value(
"err", CPS::Logger::Level::err)
54 .value(
"critical", CPS::Logger::Level::critical)
55 .value(
"off", CPS::Logger::Level::off);
57 py::class_<CPS::Math>(m,
"Math")
58 .def_static(
"single_phase_variable_to_three_phase",
60 .def_static(
"single_phase_parameter_to_three_phase",
62 .def_static(
"single_phase_power_to_three_phase",
65 py::enum_<DPsim::Solver::Behaviour>(m,
"SolverBehaviour")
66 .value(
"Initialization", DPsim::Solver::Behaviour::Initialization)
67 .value(
"Simulation", DPsim::Solver::Behaviour::Simulation);
69 py::enum_<CPS::Domain>(m,
"Domain")
70 .value(
"SP", CPS::Domain::SP)
71 .value(
"DP", CPS::Domain::DP)
72 .value(
"EMT", CPS::Domain::EMT);
74 py::enum_<CPS::PhaseType>(m,
"PhaseType")
75 .value(
"A", CPS::PhaseType::A)
76 .value(
"B", CPS::PhaseType::B)
77 .value(
"C", CPS::PhaseType::C)
78 .value(
"ABC", CPS::PhaseType::ABC)
79 .value(
"Single", CPS::PhaseType::Single);
81 py::enum_<CPS::PowerflowBusType>(m,
"PowerflowBusType")
82 .value(
"PV", CPS::PowerflowBusType::PV)
83 .value(
"PQ", CPS::PowerflowBusType::PQ)
84 .value(
"VD", CPS::PowerflowBusType::VD)
85 .value(
"None", CPS::PowerflowBusType::None);
87 py::enum_<CPS::GeneratorType>(m,
"GeneratorType")
88 .value(
"PVNode", CPS::GeneratorType::PVNode)
89 .value(
"TransientStability", CPS::GeneratorType::TransientStability)
90 .value(
"IdealVoltageSource", CPS::GeneratorType::IdealVoltageSource)
91 .value(
"SG3OrderVBR", CPS::GeneratorType::SG3OrderVBR)
92 .value(
"SG4OrderVBR", CPS::GeneratorType::SG4OrderVBR)
93 .value(
"SG5OrderVBR", CPS::GeneratorType::SG5OrderVBR)
94 .value(
"SG6aOrderVBR", CPS::GeneratorType::SG6aOrderVBR)
95 .value(
"SG6bOrderVBR", CPS::GeneratorType::SG6bOrderVBR)
96 .value(
"FullOrderVBR", CPS::GeneratorType::FullOrderVBR)
97 .value(
"FullOrder", CPS::GeneratorType::FullOrder)
98 .value(
"NONE", CPS::GeneratorType::None);
100 py::enum_<DPsim::Solver::Type>(m,
"Solver")
101 .value(
"MNA", DPsim::Solver::Type::MNA)
102 .value(
"DAE", DPsim::Solver::Type::DAE)
103 .value(
"NRP", DPsim::Solver::Type::NRP);
105 py::enum_<DPsim::DirectLinearSolverImpl>(m,
"DirectLinearSolverImpl")
106 .value(
"Undef", DPsim::DirectLinearSolverImpl::Undef)
107 .value(
"DenseLU", DPsim::DirectLinearSolverImpl::DenseLU)
108 .value(
"SparseLU", DPsim::DirectLinearSolverImpl::SparseLU)
109 .value(
"KLU", DPsim::DirectLinearSolverImpl::KLU)
110 .value(
"CUDADense", DPsim::DirectLinearSolverImpl::CUDADense)
111 .value(
"CUDASparse", DPsim::DirectLinearSolverImpl::CUDASparse)
112 .value(
"CUDAMagma", DPsim::DirectLinearSolverImpl::CUDAMagma);
114 py::enum_<DPsim::SCALING_METHOD>(m,
"scaling_method")
115 .value(
"no_scaling", DPsim::SCALING_METHOD::NO_SCALING)
116 .value(
"sum_scaling", DPsim::SCALING_METHOD::SUM_SCALING)
117 .value(
"max_scaling", DPsim::SCALING_METHOD::MAX_SCALING);
119 py::enum_<DPsim::FILL_IN_REDUCTION_METHOD>(m,
"fill_in_reduction_method")
120 .value(
"amd", DPsim::FILL_IN_REDUCTION_METHOD::AMD)
121 .value(
"amd_nv", DPsim::FILL_IN_REDUCTION_METHOD::AMD_NV)
122 .value(
"amd_ra", DPsim::FILL_IN_REDUCTION_METHOD::AMD_RA)
123 .value(
"colamd", DPsim::FILL_IN_REDUCTION_METHOD::COLAMD);
125 py::enum_<DPsim::PARTIAL_REFACTORIZATION_METHOD>(
126 m,
"partial_refactorization_method")
127 .value(
"no_partial_refactorization",
128 DPsim::PARTIAL_REFACTORIZATION_METHOD::NO_PARTIAL_REFACTORIZATION)
129 .value(
"factorization_path",
130 DPsim::PARTIAL_REFACTORIZATION_METHOD::FACTORIZATION_PATH)
131 .value(
"refactorization_restart",
132 DPsim::PARTIAL_REFACTORIZATION_METHOD::REFACTORIZATION_RESTART);
134 py::enum_<DPsim::USE_BTF>(m,
"use_btf")
135 .value(
"no_btf", DPsim::USE_BTF::NO_BTF)
136 .value(
"do_btf", DPsim::USE_BTF::DO_BTF);
138 py::enum_<CPS::CSVReader::Mode>(m,
"CSVReaderMode")
139 .value(
"AUTO", CPS::CSVReader::Mode::AUTO)
140 .value(
"MANUAL", CPS::CSVReader::Mode::MANUAL);
142 py::enum_<CPS::CSVReader::DataFormat>(m,
"CSVReaderFormat")
143 .value(
"HHMMSS", CPS::CSVReader::DataFormat::HHMMSS)
144 .value(
"SECONDS", CPS::CSVReader::DataFormat::SECONDS)
145 .value(
"HOURS", CPS::CSVReader::DataFormat::HOURS)
146 .value(
"MINUTES", CPS::CSVReader::DataFormat::MINUTES);
148 m.attr(
"RMS3PH_TO_PEAK1PH") = RMS3PH_TO_PEAK1PH;
149 m.attr(
"PEAK1PH_TO_RMS3PH") = PEAK1PH_TO_RMS3PH;
150 m.attr(
"P_SNUB_TRANSFORMER") = P_SNUB_TRANSFORMER;
151 m.attr(
"Q_SNUB_TRANSFORMER") = Q_SNUB_TRANSFORMER;
155 py::class_<DPsim::DirectLinearSolverConfiguration>(
156 m,
"DirectLinearSolverConfiguration")
158 .def(
"set_fill_in_reduction_method",
159 &DPsim::DirectLinearSolverConfiguration::setFillInReductionMethod)
160 .def(
"set_scaling_method",
161 &DPsim::DirectLinearSolverConfiguration::setScalingMethod)
162 .def(
"set_partial_refactorization_method",
164 setPartialRefactorizationMethod)
165 .def(
"set_btf", &DPsim::DirectLinearSolverConfiguration::setBTF)
166 .def(
"get_scaling_method",
167 &DPsim::DirectLinearSolverConfiguration::getScalingMethod)
168 .def(
"get_fill_in_reduction_method",
169 &DPsim::DirectLinearSolverConfiguration::getFillInReductionMethod)
170 .def(
"get_partial_refactorization_method",
172 getPartialRefactorizationMethod)
173 .def(
"get_btf", &DPsim::DirectLinearSolverConfiguration::getBTF);
175 py::class_<DPsim::Simulation>(m,
"Simulation")
176 .def(py::init<std::string, CPS::Logger::Level>(),
"name"_a,
177 "loglevel"_a = CPS::Logger::Level::off)
178 .def(
"name", &DPsim::Simulation::name)
179 .def(
"set_time_step", &DPsim::Simulation::setTimeStep)
180 .def(
"set_final_time", &DPsim::Simulation::setFinalTime)
182 .def(
"set_system", &DPsim::Simulation::setSystem)
184 .def(
"set_solver", &DPsim::Simulation::setSolverType)
185 .def(
"set_domain", &DPsim::Simulation::setDomain)
191 .def(
"add_interface", &DPsim::Simulation::addInterface,
"interface"_a)
192 .def(
"log_idobj_attribute", &DPsim::Simulation::logIdObjAttribute,
196 .def(
"do_init_from_nodes_and_terminals",
197 &DPsim::Simulation::doInitFromNodesAndTerminals)
198 .def(
"do_system_matrix_recomputation",
199 &DPsim::Simulation::doSystemMatrixRecomputation)
201 .def(
"do_frequency_parallelization",
203 .def(
"do_split_subnets", &DPsim::Simulation::doSplitSubnets)
204 .def(
"set_tearing_components", &DPsim::Simulation::setTearingComponents)
206 .def(
"set_solver_component_behaviour",
208 .def(
"set_direct_solver_implementation",
209 &DPsim::Simulation::setDirectLinearSolverImplementation)
210 .def(
"set_direct_linear_solver_configuration",
211 &DPsim::Simulation::setDirectLinearSolverConfiguration)
214 py::class_<DPsim::RealTimeSimulation, DPsim::Simulation>(m,
215 "RealTimeSimulation")
216 .def(py::init<std::string, CPS::Logger::Level>(),
"name"_a,
217 "loglevel"_a = CPS::Logger::Level::info)
218 .def(
"name", &DPsim::RealTimeSimulation::name)
219 .def(
"set_time_step", &DPsim::RealTimeSimulation::setTimeStep)
220 .def(
"set_final_time", &DPsim::RealTimeSimulation::setFinalTime)
222 .def(
"set_system", &DPsim::RealTimeSimulation::setSystem)
226 .def(
"set_solver", &DPsim::RealTimeSimulation::setSolverType)
227 .def(
"set_domain", &DPsim::RealTimeSimulation::setDomain);
229 py::class_<CPS::SystemTopology, std::shared_ptr<CPS::SystemTopology>>(
231 .def(py::init<CPS::Real, CPS::TopologicalNode::List,
232 CPS::IdentifiedObject::List>())
233 .def(py::init<CPS::Real, CPS::Matrix, CPS::TopologicalNode::List,
234 CPS::IdentifiedObject::List>())
235 .def(py::init<CPS::Real>())
238 .def(
"node", py::overload_cast<std::string_view>(
240 .def(
"node", py::overload_cast<CPS::UInt>(
242 .def(
"connect_component",
243 py::overload_cast<CPS::SimPowerComp<CPS::Real>::Ptr,
244 CPS::SimNode<CPS::Real>::List>(
246 .def(
"connect_component",
247 py::overload_cast<CPS::SimPowerComp<CPS::Complex>::Ptr,
248 CPS::SimNode<CPS::Complex>::List>(
254 .def(
"_repr_svg_", &DPsim::SystemTopology::render)
255 .def(
"render_to_file", &DPsim::SystemTopology::renderToFile)
259 .def_readwrite(
"components_at_node",
262 .def(
"list_idobjects", &DPsim::SystemTopology::listIdObjects)
264 "systemPF"_a,
"domain"_a)
269 py::class_<DPsim::Interface, std::shared_ptr<DPsim::Interface>>(m,
273 std::shared_ptr<DPsim::DataLoggerInterface>>(m,
274 "DataLoggerInterface")
275 .def(
"log_attribute",
276 py::overload_cast<
const CPS::String &, CPS::AttributeBase::Ptr,
277 CPS::UInt, CPS::UInt>(
278 &DPsim::DataLoggerInterface::logAttribute),
279 "name"_a,
"attr"_a,
"max_cols"_a = 0,
"max_rows"_a = 0)
281 .def(
"log_attribute",
282 py::overload_cast<
const std::vector<CPS::String> &,
283 CPS::AttributeBase::Ptr>(
284 &DPsim::DataLoggerInterface::logAttribute),
287 .def(
"log_attribute",
289 const std::vector<CPS::String> &names,
const CPS::String &attr,
291 logger.logAttribute(names, comp.
attribute(attr));
295 std::shared_ptr<DPsim::DataLogger>>(m,
"Logger")
296 .def(py::init<std::string>())
298 .def_static(
"get_log_dir", &CPS::Logger::logDir)
299 .def(
"log_attribute",
300 py::overload_cast<
const CPS::String &, CPS::AttributeBase::Ptr,
301 CPS::UInt, CPS::UInt>(
302 &DPsim::DataLogger::logAttribute),
303 "name"_a,
"attr"_a,
"max_cols"_a = 0,
"max_rows"_a = 0)
305 .def(
"log_attribute",
306 py::overload_cast<
const std::vector<CPS::String> &,
307 CPS::AttributeBase::Ptr>(
308 &DPsim::DataLogger::logAttribute),
315 CPS::UInt rowsMax, CPS::UInt colsMax) {
316 logger.logAttribute(name, comp.
attribute(attr), rowsMax, colsMax);
318 "name"_a,
"attr"_a,
"comp"_a,
"rows_max"_a = 0,
"cols_max"_a = 0)
320 .def(
"log_attribute",
323 logger.logAttribute(names, comp.
attribute(attr));
326 py::class_<CPS::IdentifiedObject, std::shared_ptr<CPS::IdentifiedObject>>(
327 m,
"IdentifiedObject")
328 .def(
"name", &CPS::IdentifiedObject::name)
333 .def(
"print_attribute_list", &printAttributes)
334 .def(
"print_attribute", &printAttribute,
"attribute_name"_a)
335 .def(
"__str__", &getAttributeList);
338 py::class_<CPS::CIM::Reader>(m,
"CIMReader")
339 .def(py::init<std::string, CPS::Logger::Level, CPS::Logger::Level>(),
340 "name"_a,
"loglevel"_a = CPS::Logger::Level::info,
341 "comploglevel"_a = CPS::Logger::Level::off)
343 CPS::Real,
const std::list<CPS::String> &,
344 CPS::Domain, CPS::PhaseType, CPS::GeneratorType)) &
348 py::class_<CPS::CSVReader>(m,
"CSVReader")
349 .def(py::init<std::string,
const std::string &,
350 std::map<std::string, std::string> &, CPS::Logger::Level>())
357 m,
"TopologicalPowerComp");
358 py::class_<CPS::SimPowerComp<CPS::Complex>,
359 std::shared_ptr<CPS::SimPowerComp<CPS::Complex>>,
362 .def(
"set_intf_current", &CPS::SimPowerComp<CPS::Complex>::setIntfCurrent)
363 .def(
"set_intf_voltage", &CPS::SimPowerComp<CPS::Complex>::setIntfVoltage)
366 py::class_<CPS::SimPowerComp<CPS::Real>,
367 std::shared_ptr<CPS::SimPowerComp<CPS::Real>>,
370 .def(
"set_intf_current", &CPS::SimPowerComp<CPS::Real>::setIntfCurrent)
371 .def(
"set_intf_voltage", &CPS::SimPowerComp<CPS::Real>::setIntfVoltage)
373 py::class_<CPS::TopologicalNode, std::shared_ptr<CPS::TopologicalNode>,
375 .def(
"initial_single_voltage",
376 &CPS::TopologicalNode::initialSingleVoltage,
377 "phase_type"_a = CPS::PhaseType::Single);
381 m,
"TopologicalTerminal")
383 py::overload_cast<CPS::Complex>(&CPS::TopologicalTerminal::setPower))
384 .def(
"set_power", py::overload_cast<CPS::MatrixComp>(
385 &CPS::TopologicalTerminal::setPower));
387 py::class_<CPS::SimTerminal<CPS::Complex>,
388 std::shared_ptr<CPS::SimTerminal<CPS::Complex>>,
390 py::class_<CPS::SimTerminal<CPS::Real>,
391 std::shared_ptr<CPS::SimTerminal<CPS::Real>>,
395 py::module mEvent = m.def_submodule(
"event",
"events");
396 py::class_<DPsim::Event, std::shared_ptr<DPsim::Event>>(mEvent,
"Event");
397 py::class_<DPsim::SwitchEvent, std::shared_ptr<DPsim::SwitchEvent>,
398 DPsim::Event>(mEvent,
"SwitchEvent", py::multiple_inheritance())
399 .def(py::init<CPS::Real,
const std::shared_ptr<CPS::Base::Ph1::Switch>,
401 py::class_<DPsim::SwitchEvent3Ph, std::shared_ptr<DPsim::SwitchEvent3Ph>,
402 DPsim::Event>(mEvent,
"SwitchEvent3Ph", py::multiple_inheritance())
403 .def(py::init<CPS::Real,
const std::shared_ptr<CPS::Base::Ph3::Switch>,
407 py::module mBase = m.def_submodule(
"base",
"base models");
408 addBaseComponents(mBase);
410 py::module mDP = m.def_submodule(
"dp",
"dynamic phasor models");
411 addDPComponents(mDP);
413 py::module mEMT = m.def_submodule(
"emt",
"electromagnetic-transient models");
414 addEMTComponents(mEMT);
416 py::module mSP = m.def_submodule(
"sp",
"static phasor models");
417 mSP.attr(
"SimNode") = mDP.attr(
"SimNode");
418 addSPComponents(mSP);
420 py::module mSignal = m.def_submodule(
"signal",
"signal models");
421 addSignalComponents(mSignal);
424 m.attr(
"__version__") = VERSION_INFO;
426 m.attr(
"__version__") =
"dev";
SystemTopology loadCIM(Real systemFrequency, const fs::path &filename, Domain domain=Domain::DP, PhaseType phase=PhaseType::Single, GeneratorType genType=GeneratorType::None)
Parses data from CIM files into the CPS data structure.
void assignLoadProfile(SystemTopology &sys, Real start_time=-1, Real time_step=1, Real end_time=-1, CSVReader::Mode mode=CSVReader::Mode::AUTO, CSVReader::DataFormat format=CSVReader::DataFormat::SECONDS)
assign load profile to corresponding load object
AttributeBase::Ptr attribute(const String &name) const
Return pointer to an attribute.
static void setLogDir(String path)
Set env variable CPS_LOG_DIR and overwrite.
static Matrix singlePhasePowerToThreePhase(Real power)
To convert single phase power to symmetrical three phase.
static Matrix singlePhaseParameterToThreePhase(Real parameter)
To convert single phase parameters to symmetrical three phase ones.
static MatrixComp singlePhaseVariableToThreePhase(Complex var_1ph)
To convert single phase complex variables (voltages, currents) to symmetrical three phase ones.
SimTerminal< VarType >::Ptr terminal(UInt index)
Get pointer to Terminal.
void connect(typename SimNode< VarType >::List nodes)
Sets all nodes and checks for nominal number of Nodes for this Component.
IdentifiedObject::List mComponents
List of network components.
std::shared_ptr< Type > node(UInt index)
Returns TopologicalNode by index in node list.
void initWithPowerflow(const SystemTopology &systemPF, CPS::Domain domain)
Initialize nodes and SG power from PowerFlow.
void removeComponent(const String &name)
Remove system component.
void addTearComponent(IdentifiedObject::Ptr component)
Adds component and initializes frequencies.
std::shared_ptr< Type > component(const String &name)
Returns Component by name.
TopologicalNode::List mNodes
List of network nodes.
void addComponents(const IdentifiedObject::List &components)
Add multiple components.
void connectComponentToNodes(typename SimPowerComp< VarType >::Ptr component, typename SimNode< VarType >::List simNodes)
Connect component to simNodes.
void addComponent(IdentifiedObject::Ptr component)
Adds component and initializes frequencies.
IdentifiedObject::List mTearComponents
std::map< TopologicalNode::Ptr, TopologicalPowerComp::List > mComponentsAtNode
Map of network components connected to network nodes.
Extending Simulation class by real-time functionality.
void run(const Timer::StartClock::duration &startIn=std::chrono::seconds(1))
void doFrequencyParallelization(Bool value)
Compute phasors of different frequencies in parallel.
void logLUTimes()
Write LU decomposition times measurements to log file.
Real next()
Run until next time step.
void addLogger(DataLoggerInterface::Ptr logger)
Add a new data logger.
void setSolverAndComponentBehaviour(Solver::Behaviour behaviour)
set solver and component to initialization or simulation behaviour
CPS::AttributeBase::Ptr getIdObjAttribute(const String &comp, const String &attr)
CHECK: Can these be deleted? getIdObjAttribute + "**attr =" should suffice.
void start()
Start simulation without advancing in time.
void doSteadyStateInit(Bool f)
activate steady state initialization
void addEvent(Event::Ptr e)
Schedule an event in the simulation.
void run()
Run simulation until total time is elapsed.
void logAttribute(String name, CPS::AttributeBase::Ptr attr)
CHECK: Can we store the attribute name / UID intrinsically inside the attribute?
void stop()
Stop simulation including scheduler and interfaces.