Getting Started¶
OpenDSSDirect.py is a package in the DSS Extensions project. As such, it doesn’t require EPRI’s OpenDSS to be installed. OpenDSSDirect.py provides it’s own customized engine through DSS-Python, which in turn enables us to run the DSS engine on Windows, Linux and macOS (including newer Apple ARM processors).
For a comparison of the general Python-level API, including a list of our extra functions, please check DSS Extensions — OpenDSS: Overview of Python APIs. That documents introduces and compares DSS-Python, OpenDSSDirect.py, and the official COM implementation.
To use OpenDSSDirect.py, open a Python interpreter and type the following command:
[1]:
import opendssdirect as dss
The dss module has submodules that act as interfaces to various components in OpenDSS. The full list of the modules is shown below.
dss.ActiveClass
dss.Basic
dss.Bus
dss.CapControls
dss.Capacitors
dss.Circuit
dss.CktElement
dss.Element
dss.Executive
dss.Fuses
dss.Generators
dss.Isource
dss.Lines
dss.LoadShape
dss.Loads
dss.Meters
dss.Monitors
dss.PDElements
dss.PVsystems
dss.Parser
dss.Properties
dss.Reclosers
dss.RegControls
dss.Relays
dss.Sensors
dss.Settings
dss.Solution
dss.SwtControls
dss.Topology
dss.Transformers
dss.Vsources
dss.XYCurves
These modules are the higher level interface to OpenDSS. The dss module also has a lower level interface in dss.dss_lib. The higher level interface uses the lower level interface to call the appropriate functions. For the most part, a OpenDSSDirect.py user will not need to use the lower level interface, but knowing that it exists can be useful.
[2]:
dss.Text.Command('Redirect ../../tests/data/13Bus/IEEE13Nodeckt.dss')
👉 In previous versions of this document, we used to recommend ``dss.run_command()``. Unfortunately the error-checking from ``run_command`` can be confusing and we cannot change it, for historical and backwards-compatibility reasons.
We can print all bus names using the following.
[3]:
for i in dss.Circuit.AllBusNames():
print(i)
sourcebus
650
rg60
633
634
671
645
646
692
675
611
652
670
632
680
684
Using the pandas interface¶
The utils module implements helper functions that make it easier to use the interface.
An optional pandas interface is also provided in the package, so making it easier to get data from OpenDSS. See installation instructions for how to install the requirements for this interface.
All load data can be attained using the loads_to_dataframe function.
[4]:
dss.utils.loads_to_dataframe()
[4]:
| CVRCurve | CVRvars | CVRwatts | CFactor | Class | Growth | IsDelta | Model | Name | NumCust | ... | kV | kW | kVABase | kvar | kWh | kWhDays | puSeriesRL | XfkVA | Phases | AllocationFactor | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 671 | 2.0 | 1.0 | 4.0 | 1 | True | 1 | 671 | 1 | ... | 4.16 | 1155.0 | 1330.272528 | 660.0 | 0.0 | 30.0 | 50.0 | 0.0 | 3 | 0.5 | ||
| 634a | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 634a | 1 | ... | 0.277 | 160.0 | 194.164878 | 110.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 634b | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 634b | 1 | ... | 0.277 | 120.0 | 150.0 | 90.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 634c | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 634c | 1 | ... | 0.277 | 120.0 | 150.0 | 90.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 645 | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 645 | 1 | ... | 2.4 | 170.0 | 211.009478 | 125.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 646 | 2.0 | 1.0 | 4.0 | 1 | True | 2 | 646 | 1 | ... | 4.16 | 230.0 | 265.186727 | 132.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 692 | 2.0 | 1.0 | 4.0 | 1 | True | 5 | 692 | 1 | ... | 4.16 | 170.0 | 227.378539 | 151.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 675a | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 675a | 1 | ... | 2.4 | 485.0 | 520.888664 | 190.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 675b | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 675b | 1 | ... | 2.4 | 68.0 | 90.686272 | 60.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 675c | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 675c | 1 | ... | 2.4 | 290.0 | 359.226948 | 212.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 611 | 2.0 | 1.0 | 4.0 | 1 | False | 5 | 611 | 1 | ... | 2.4 | 170.0 | 187.882942 | 80.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 652 | 2.0 | 1.0 | 4.0 | 1 | False | 2 | 652 | 1 | ... | 2.4 | 128.0 | 154.207652 | 86.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 670a | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 670a | 1 | ... | 2.4 | 17.0 | 19.723083 | 10.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 670b | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 670b | 1 | ... | 2.4 | 66.0 | 76.157731 | 38.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 | ||
| 670c | 2.0 | 1.0 | 4.0 | 1 | False | 1 | 670c | 1 | ... | 2.4 | 117.0 | 135.325533 | 68.0 | 0.0 | 30.0 | 50.0 | 0.0 | 1 | 0.5 |
15 rows × 37 columns
Similarly, all transformer data can be attained using the transformers_to_dataframe function
[5]:
dss.utils.transformers_to_dataframe()
[5]:
| IsDelta | MaxTap | MinTap | Name | NumTaps | NumWindings | R | Rneut | Tap | Wdg | ... | Xlt | Xneut | kV | kVA | Idx | CoreType | RdcOhms | WdgCurrents | WdgVoltages | LossesByType | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| sub | False | 1.1 | 0.9 | sub | 32 | 2 | 0.0005 | -1.0 | 1.0 | 2 | ... | 4.0 | 0.0 | 4.16 | 5000.0 | 1 | 0 | 0.000005 | [10.886838403101137, -5.9590983105881605, -10.... | [2401.562774320432, -0.46690091155609226, -120... | [32.28780525899492, 262.4687364427373, 32.2878... |
| reg1 | False | 1.1 | 0.9 | reg1 | 32 | 2 | 0.005 | -1.0 | 1.05625 | 2 | ... | 30.0 | 0.0 | 2.4 | 1666.0 | 2 | 0 | 0.000147 | [521.2749200067483, -285.3283304735087, -521.2... | [2536.356120228099, -0.5793286234950956] | [122.09388323919848, 123.85831108468119, 122.0... |
| reg2 | False | 1.1 | 0.9 | reg2 | 32 | 2 | 0.005 | -1.0 | 1.0375 | 2 | ... | 30.0 | 0.0 | 2.4 | 1666.0 | 3 | 0 | 0.000147 | [-339.30622841604054, -271.7993979600724, 339.... | [-1246.2598772664523, -2157.4877137350218] | [65.34575459547341, 67.07771651400253, 65.3457... |
| reg3 | False | 1.1 | 0.9 | reg3 | 32 | 2 | 0.005 | -1.0 | 1.05625 | 2 | ... | 30.0 | 0.0 | 2.4 | 1666.0 | 4 | 0 | 0.000147 | [-36.93235703278333, 623.9901740467176, 36.932... | [-1267.5877694598496, 2196.935539327288] | [135.08947523473762, 136.85396666557062, 135.0... |
| xfm1 | False | 1.1 | 0.9 | xfm1 | 32 | 2 | 0.55 | -1.0 | 1.0 | 2 | ... | 1.0 | 0.0 | 0.48 | 500.0 | 5 | 0 | 0.000718 | [64.7216815965744, -50.18299905784306, -64.721... | [273.1208520924334, -15.653268696155022, -149.... | [5552.6587844858295, 10096.246342088038, 5552.... |
5 rows × 23 columns
A full list of available functions is listed below:
dss.utils.capacitors_to_dataframe
dss.utils.fuses_to_dataframe
dss.utils.generators_to_dataframe
dss.utils.isource_to_dataframe
dss.utils.lines_to_dataframe
dss.utils.loads_to_dataframe
dss.utils.loadshape_to_dataframe
dss.utils.meters_to_dataframe
dss.utils.monitors_to_dataframe
dss.utils.pvsystems_to_dataframe
dss.utils.reclosers_to_dataframe
dss.utils.regcontrols_to_dataframe
dss.utils.relays_to_dataframe
dss.utils.sensors_to_dataframe
dss.utils.transformers_to_dataframe
dss.utils.vsources_to_dataframe
dss.utils.xycurves_to_dataframe