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));
327 std::shared_ptr<DPsim::RealTimeDataLogger>>(m,
328 "RealTimeDataLogger")
330 .def(py::init([](py::object filename, DPsim::Real final_time,
331 DPsim::Real time_step) {
333 py::module_::import(
"os").attr(
"fspath")(filename);
334 std::string s = py::cast<std::string>(fspath);
335 std::filesystem::path p(s);
336 return std::make_shared<DPsim::RealTimeDataLogger>(p, final_time,
339 "filename"_a,
"final_time"_a,
"time_step"_a)
341 .def(py::init([](py::object filename, std::size_t row_number) {
343 py::module_::import(
"os").attr(
"fspath")(filename);
344 std::string s = py::cast<std::string>(fspath);
345 std::filesystem::path p(s);
346 return std::make_shared<DPsim::RealTimeDataLogger>(p, row_number);
348 "filename"_a,
"row_number"_a)
350 .def(
"log_attribute",
351 py::overload_cast<
const CPS::String &, CPS::AttributeBase::Ptr,
352 CPS::UInt, CPS::UInt>(
353 &DPsim::DataLoggerInterface::logAttribute),
354 "name"_a,
"attr"_a,
"max_cols"_a = 0,
"max_rows"_a = 0)
356 .def(
"log_attribute",
357 py::overload_cast<
const std::vector<CPS::String> &,
358 CPS::AttributeBase::Ptr>(
359 &DPsim::DataLoggerInterface::logAttribute),
366 CPS::UInt rowsMax, CPS::UInt colsMax) {
367 logger.logAttribute(name, comp.
attribute(attr), rowsMax, colsMax);
369 "name"_a,
"attr"_a,
"comp"_a,
"rows_max"_a = 0,
"cols_max"_a = 0)
374 const std::vector<CPS::String> &names,
const CPS::String &attr,
376 logger.logAttribute(names, comp.
attribute(attr));
378 "names"_a,
"attr"_a,
"comp"_a);
380 py::class_<CPS::IdentifiedObject, std::shared_ptr<CPS::IdentifiedObject>>(
381 m,
"IdentifiedObject")
382 .def(
"name", &CPS::IdentifiedObject::name)
387 .def(
"print_attribute_list", &printAttributes)
388 .def(
"print_attribute", &printAttribute,
"attribute_name"_a)
389 .def(
"__str__", &getAttributeList);
392 py::class_<CPS::CIM::Reader>(m,
"CIMReader")
393 .def(py::init<std::string, CPS::Logger::Level, CPS::Logger::Level>(),
394 "name"_a,
"loglevel"_a = CPS::Logger::Level::info,
395 "comploglevel"_a = CPS::Logger::Level::off)
397 CPS::Real,
const std::list<CPS::String> &,
398 CPS::Domain, CPS::PhaseType, CPS::GeneratorType)) &
402 py::class_<CPS::CSVReader>(m,
"CSVReader")
403 .def(py::init<std::string,
const std::string &,
404 std::map<std::string, std::string> &, CPS::Logger::Level>())
411 m,
"TopologicalPowerComp");
412 py::class_<CPS::SimPowerComp<CPS::Complex>,
413 std::shared_ptr<CPS::SimPowerComp<CPS::Complex>>,
416 .def(
"set_intf_current", &CPS::SimPowerComp<CPS::Complex>::setIntfCurrent)
417 .def(
"set_intf_voltage", &CPS::SimPowerComp<CPS::Complex>::setIntfVoltage)
420 py::class_<CPS::SimPowerComp<CPS::Real>,
421 std::shared_ptr<CPS::SimPowerComp<CPS::Real>>,
424 .def(
"set_intf_current", &CPS::SimPowerComp<CPS::Real>::setIntfCurrent)
425 .def(
"set_intf_voltage", &CPS::SimPowerComp<CPS::Real>::setIntfVoltage)
427 py::class_<CPS::TopologicalNode, std::shared_ptr<CPS::TopologicalNode>,
429 .def(
"initial_single_voltage",
430 &CPS::TopologicalNode::initialSingleVoltage,
431 "phase_type"_a = CPS::PhaseType::Single);
435 m,
"TopologicalTerminal")
437 py::overload_cast<CPS::Complex>(&CPS::TopologicalTerminal::setPower))
438 .def(
"set_power", py::overload_cast<CPS::MatrixComp>(
439 &CPS::TopologicalTerminal::setPower));
441 py::class_<CPS::SimTerminal<CPS::Complex>,
442 std::shared_ptr<CPS::SimTerminal<CPS::Complex>>,
444 py::class_<CPS::SimTerminal<CPS::Real>,
445 std::shared_ptr<CPS::SimTerminal<CPS::Real>>,
449 py::module mEvent = m.def_submodule(
"event",
"events");
450 py::class_<DPsim::Event, std::shared_ptr<DPsim::Event>>(mEvent,
"Event");
451 py::class_<DPsim::SwitchEvent, std::shared_ptr<DPsim::SwitchEvent>,
452 DPsim::Event>(mEvent,
"SwitchEvent", py::multiple_inheritance())
453 .def(py::init<CPS::Real,
const std::shared_ptr<CPS::Base::Ph1::Switch>,
455 py::class_<DPsim::SwitchEvent3Ph, std::shared_ptr<DPsim::SwitchEvent3Ph>,
456 DPsim::Event>(mEvent,
"SwitchEvent3Ph", py::multiple_inheritance())
457 .def(py::init<CPS::Real,
const std::shared_ptr<CPS::Base::Ph3::Switch>,
461 py::module mBase = m.def_submodule(
"base",
"base models");
462 addBaseComponents(mBase);
464 py::module mDP = m.def_submodule(
"dp",
"dynamic phasor models");
465 addDPComponents(mDP);
467 py::module mEMT = m.def_submodule(
"emt",
"electromagnetic-transient models");
468 addEMTComponents(mEMT);
470 py::module mSP = m.def_submodule(
"sp",
"static phasor models");
471 mSP.attr(
"SimNode") = mDP.attr(
"SimNode");
472 addSPComponents(mSP);
474 py::module mSignal = m.def_submodule(
"signal",
"signal models");
475 addSignalComponents(mSignal);
478 m.attr(
"__version__") = VERSION_INFO;
480 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.