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