DSS-Python#

DSS-Python uses CFFI and NumPy to expose the OpenDSS engine, as implemented in our alternative engine (AltDSS) through the AltDSS/DSS C-API library. OpenDSS is an open-source electric power distribution system simulator distributed by EPRI.

This package is available for Windows, Linux and macOS, including Intel and ARM processes, both 32 and 64-bit. As such, it enables OpenDSS to run in many environments the official implementation cannot, from a Raspberry Pi to a HPC cluster, and cloud environments like Google Colab (some of our notebooks examples are ready-to-run on Colab).

DSS-Python is part of DSS-Extensions, a larger effort to port the original OpenDSS to support more platforms (OSs, processor architectures), programming languages, and extend both the OpenDSS engine and API, represented in the AltDSS engine:

Overview of related projects

For alternatives for other programming languages, including in MATLAB, C++, C#/.NET, Rust and Go, please check https://dss-extensions.org/ and our hub repository at dss-extensions/dss-extensions for more documentation, discussions and the FAQ.

flowchart TD C["AltDSS engine/DSS C-API\n(libdss_capi)"] --> P["DSS-Python: Backend"] P --- DSSPY["DSS-Python\n(dss package)"] P --- ODDPY["<a href='https://dss-extensions.org/OpenDSSDirect.py'>OpenDSSDirect.py\n(opendssdirect package)</a>"] P --- ALTDSSPY["<a href='https://dss-extensions.org/AltDSS-Python/'>AltDSS-Python\n(altdss package)</a>"]

DSS-Python is one of three Python projects under DSS-Extensions. See DSS-Extensions — OpenDSS: Overview of Python APIs for a brief comparison between these and the official COM API. Both OpenDSSDirect.py and DSS-Python expose the classic OpenDSS API (closer to the COM implementation). For an alternative API which exposes all OpenDSS objects, batch operations, and a more intuitive API, check AltDSS-Python. If required, users can mix all three packages in the same project to access some of their unique features.

Brief introduction#

Install it with pip (or pip3 depending on your environment, or even python -m pip), e.g.:

pip install dss-python

To enable all the features available, which require more modules, use the all variation:

pip install dss-python[all]

In this documentation, since many features from DSS-Python are not available in the official version, we mark the extra features as “(API Extension)”. As such, the documentation could be somewhat useful for OpenDSS users stuck with the COM version. As a reminder, we provide patch_dss_com to introduce some of the quality-of-life features such as Python iterators and more to an OpenDSSengine.DSS COM object, in an effort to provide compatibility when users are either migrating, validating results or just need to provide support for both the official engine and the DSS-Extensions version. “(API Extension)” is used to mark whole classes, as seen below, or individual extra properties and functions. Not all extensions are marked, so be sure to check when in doubt.

Independent of which OpenDSS implementation you use, it is good practice to list the specific implementation begin used (e.g. from EPRI or from DSS-Extensions). At the moment we do not generate DOIs for our packages, but users can always cite a specific version on PyPI, e.g. https://pypi.org/project/dss-python/0.12.1/

Check http://dss-extensions.org and dss-extensions/dss-extensions for links to more documentation and examples. Besides our own documentation, the official OpenDSS documentation is extensive and covers various topics.

We recommend looking especially in the following resources:

https://opendss.epri.com/opendss_documentation.html
https://sourceforge.net/p/electricdss/code/3706/tree/trunk/Version8/Distrib/Doc/ (old version of the above, with separate PDFs, etc.)

See also https://dss-extensions.org/OpenDSSDirect.py/ for a package that uses function-style getters and setters, instead of Python properties, but reusing the base of this package. Most concepts presented here are shared and we avoid duplicating the effort. We envision a joint documentation site in the future. A new package called AltDSS-Python is being developed to address the limitations of both DSS-Python and OpenDSSDirect.py using an original approach.

Missing features and limitations#

Most limitations are inherited from dss_capi, i.e., these are not implemented:

DSSProgress from DLL/ImplDSSProgress.pas: would need a reimplementation depending on the target UI (GUI, text, headless, etc.). Can be achieved with the current API.
OpenDSS-GIS features are not implemented since they’re not open-source (nor free/openly available).

Previous missing features, such as support for most plot commands and the “Events” interface, have been implemented.

Extra features#

In general, the dss_capi library from DSS-Extensions provides more features than both the official Direct DLL and the COM object.

Besides most of the methods available in the OpenDSS COM DLL, some of the unique DDLL methods are also exposed in adapted forms, namely the methods from DYMatrix.pas, especially GetCompressedYMatrix (check the source files for more information).

While OpenDSS relies on windows/forms to report errors, or require the user to check the Error interface manually, most DSS-Extensions do that automatically for the majority of the API calls. We also introduce extended error messages, more thorough error checking in the Pascal code, and even some basic tracebacks for the .DSS script handling. All the changes combined should result in a more comfortable and fluid experience for the Python user.

TO BE EXPANDED

The DSS instance#

Although there are many classes and modules in DSS-Python, the main usage is typically through the default DSS instance, and that is the most interest aspect for most users.

DSS-Python tries to be a drop-in replacement for the official OpenDSS COM implementation, within reasonable limits. There are two main Python packages that allow instantiating COM objects, win32com and comtypes.

For a quick look into some Python APIs (COM, DSS-Python, OpenDSSDirect.py) for the OpenDSS (official or our alternative implementation), see DSS-Extensions — OpenDSS: Overview of Python APIs.

Usually, your code would contain the instantiation of the objects such as:

   import win32com.client 
   DSS = win32com.client.gencache.EnsureDispatch("OpenDSSEngine.DSS")

or maybe:

   import win32com.client 
   DSS = win32com.client.Dispatch("OpenDSSEngine.DSS")

or with comtypes:

   import comtypes.client
   DSS = comtypes.client.CreateObject("OpenDSSEngine.DSS")

Either way, to use DSS-Python and effectively migrate from the official OpenDSS COM interface, you can replace that fragment with:

   from dss import DSS

If the code didn’t depend on very specific details like lists vs tuples vs NumPy arrays, it should be compatible. Note that even replacing win32com with comtypes already introduces small inconsistencies. These, though, should not matter much in Python.

For a quick overview of DSS-Python, the main DSS class is organized as follows. Click through DSS to browse and discover other properties and methods, including many of the extensions we’ve been adding in the past several years.

Plotting and notebook integration#

Initial plotting support was added in DSS-Python v0.12.1, and an almost complete implementation is available since v0.14.2. There are some features lacking in comparison to the official implementation (as of June 2023), especially interactive inspection.

To enable:

   from dss import dss, plot
   plot.enable()

After that, running the plot commands from the text interface or compile/redirect scripts will try to use matplotlib to reproduce most of the plot options from the official OpenDSS.

   dss.Text.Command = 'compile some_circuit/Master.dss'
   dss.ActiveCircuit.Solution.Solve()
   dss.Text.Command = 'plot profile'

As a reminder, after activating, this can be used with OpenDSSDirect.py <https://dss-extensions.org/OpenDSSDirect.py/> too.

A notebook with an example gallery of various plot commands and how to customized the matplotlib output is available: ()[examples/Plotting].

Documentation#

The documentation pages are organized as follows.

General

Examples

API Reference

DSS-Python

Contents