Python bindings and tools based on the DSS C-API project, a customized OpenDSS implementation
DSS Python: Extended bindings for an implementation of EPRI's OpenDSS
Python bindings and misc tools for using the OpenDSS (EPRI Distribution System Simulator) engine through the alternative/unofficial implementation from the DSS C-API library. Based on DSS C-API, CFFI and NumPy, aiming for full COM compatibility on Windows, Linux and MacOS.
See also the other projects from DSS-Extensions.org:
- DSS C-API library: the base library that exposes a modified version of EPRI's OpenDSS through a more traditional C interface, built with the open-source Free Pascal compiler instead of Delphi. As of 2022, this base library includes several extensive changes, while retaining very good compatibility.
- OpenDSSDirect.py: if you don't need COM compatibility, or just would like to check its extra funcionalities. You can mix DSS Python and OpenDSSDirect.py -- for example, if you have old code using the official COM objects, you could quickly switch to DSS Python with very few code changes, and then use
opendssdirect.utilsto generate some DataFrames.
- OpenDSSDirect.jl: a Julia module, created by Tom Short (@tshort), recently migrated with the help of Dheepak Krishnamurthy (@kdheepak) to DSS C-API instead of the DDLL.
- DSS Sharp: available for .NET/C#, also mimics the COM classes, but Windows-only at the moment. Soon it will be possible to use it via COM too.
- DSS MATLAB: presents multi-platform integration (Windows, Linux, MacOS) with DSS C-API and is also very compatible with the COM classes.
Version 0.12.1 is based on OpenDSS revision 3460 (few commits after OpenDSS v188.8.131.52). While we plan to add a lot more funcionality into DSS Python, the main goal of creating a COM-compatible API has been reached. If you find an unexpected missing feature, please report it! Currently missing features that will be implemented eventualy are plotting (partial implementation available) and diakoptics (planned for future version).
This module mimics the COM structure (as exposed via
comtypes), effectively enabling multi-platform compatibility at Python level. Compared to other options, it provides easier migration from code that uses the official OpenDSS through COM.
Most of the COM documentation can be used as-is, but instead of returning tuples or lists, this modules returns/accepts NumPy arrays for numeric data exchange, which is usually preferred by the users.
The module depends on CFFI, NumPy and, optionally, SciPy.Sparse for reading the sparse system admittance matrix. Pandas and matplotlib might be added as optional dependencies to enable plotting and other features.
Brief release history
- 2022-07-16 / version 0.12.1: Very minor release to address a bug found in v0.12.0, to add the Storages API, and include the property descriptions/help.
- 2022-07-14 / version 0.12.0: Major release merging parallel features, multiple DSS engine instances, ZIP file support, incremental Y matrix updates, new API functions, partial plotting support, better performance, and so on. General usage examples for the new features will be incrementally added to https://github.com/dss-extensions/dss-extensions
- 2021-03-09 / version 0.10.7-1: Very minor release to fix issues with some of the energy meter reports.
- 2020-12-28 / version 0.10.7: Maintenance release to match DSS C-API 0.10.7, based on on OpenDSS revision 2963. Includes fixes and new features from the official OpenDSS.
- 2020-07-31 / version 0.10.6: Maintenance release to match DSS C-API 0.10.6, based on on OpenDSS revision 2909. New important settings:
- 2020-03-03 / version 0.10.5: Maintenance release to match DSS C-API 0.10.5, based on on OpenDSS revision 2837. Temporarily drops the v8 parallel-machine functions, as well as conda packages on Windows.
- 2019-11-16 / version 0.10.4: Maintenance release to match DSS C-API 0.10.4.
- 2019-05-22 / version 0.10.3: Some important fixes, better general performance, new API extensions, new features ported from COM and the OpenDSS version 8 codebase.
- 2019-02-28 / version 0.10.2: Some small fixes, adds the missing
CtrlQueue.Push, faster LoadShapes and new property
DSS.AllowEditorto toggle editor calls.
- 2019-02-17 / version 0.10.1: Integrate DSS C-API changes/fix, some small fixes, and more error-checking.
- 2018-11-17 / version 0.10.0: Lots of changes, fixes and new features. Check the new changelog document for a list.
- 2018-08-12 / version 0.9.8: Reorganize modules (v7 and v8), adds 8 missing methods and new backend methods for OpenDSSDirect.py v0.3+. Integrates many fixes from DSS_CAPI and the upstream OpenDSS.
- 2018-04-30 / version 0.9.7: Fix some of the setters that used array data.
- 2018-04-05 / version 0.9.6: Adds missing
- 2018-03-07 / version 0.9.4: Allows using
lenon several classes, fixes DSSProperty, and includes COM helpstrings as docstrings. Contains changes up to OpenDSS revision 2152.
- 2018-02-16 / version 0.9.3: Integrates COM interface fixes from revision 2136 (
Nextiteration on some elements)
- 2018-02-12 / version 0.9.2: Experimental support for OpenDSS-PM (at the moment, a custom patch is provided for FreePascal support) and port COM interface fixes (OpenDSS revision 2134)
- 2018-02-08 / version 0.9.1: First public release (OpenDSS revision 2123)
Changes in 0.10.7, since 0.10.6
Check the changelog document for a detailed list for all releases.
- Simple maintenance release.
- Updated to DSS C-API 0.10.7, which includes most changes up to OpenDSS v184.108.40.206.
- Includes an important bug fix related to the
CapRadiusDSS property. If your DSS scripts included the pattern
GMRac=... diam=...(in this order and without specifying
CapRadius), you should upgrade and re-evaluate the results.
- New API properties ported from the official COM interface:
Missing features and limitations
Most limitations are inherited from
dss_capi, i.e., these are not implemented:
DLL/ImplEvents.pas: seems too dependent on COM.
DLL/ImplDSSProgress.pas: would need a reimplementation depending on the target UI (GUI, text, headless, etc.).
- OpenDSS-GIS features are not implemented since they're not open-source.
In general, the DLL from
dss_capi provides more features than both the official Direct DLL and the COM object.
Besides most of the COM methods, some of the unique DDLL methods are also exposed in adapted forms, namely the methods from
GetCompressedYMatrix (check the source files for more information).
Since no GUI components are used in the FreePascal DLL, we are experimenting with different ways of handling OpenDSS errors. Currently, the
DSS.Text.Command call checks for OpenDSS errors (through the
DSS.Error interface) and converts those to Python exceptions. Ideally every error should be converted to Python exceptions, but that could negatively impact performance. You can manually trigger an error check by calling the function
CheckForError() from the main module.
On all major platforms, you can install directly from pip:
pip install dss_python
Or, if you're using the Anaconda distribution, you can try:
conda install -c dss-extensions dss_python
Binary wheels are provided for all major platforms (Windows, Linux and MacOS) and many combinations of Python versions (3.5 to 3.9). If you have issues with a specific version, please open an issue about it. Conda packages support at least Python 3.6 to 3.9 (varying according to the release).
After a successful installation, you can then import the
dss module from your Python interpreter.
Get the repository:
git clone https://github.com/dss-extensions/dss_python.git
Assuming you successfully built or downloaded the DSS C-API DLLs (check its repository for instructions), keep the folder organization as follows:
Open a command prompt in the
dss_python subfolder and run the build process:
python setup.py build python setup.py install
If you are familiar with
conda-build, there is a complete recipe to build DSS C-API, KLUSolve(X) and DSS Python in the
If you were using
win32com in code like:
import win32com.client dss_engine = win32com.client.gencache.EnsureDispatch("OpenDSSEngine.DSS")
import comtypes.client dss_engine = comtypes.client.CreateObject("OpenDSSEngine.DSS")
you can replace that fragment with:
import dss dss_engine = dss.DSS
If you need the mixed-cased handling (that is, you were not using early bindings with win32com), add a call to
Assuming you have a DSS script named
master.dss, you should be able to run it as shown below:
import dss dss_engine = dss.DSS dss_engine.Text.Command = "compile c:/dss_files/master.dss" dss_engine.ActiveCircuit.Solution.Solve() voltages = dss_engine.ActiveCircuit.AllBusVolts for i in range(len(voltages) // 2): print('node %d: %f + j%f' % (i, voltages[2*i], voltages[2*i + 1]))
Since the DLL is built using the Free Pascal compiler, which is not officially supported by EPRI, the results are validated running sample networks provided in the official OpenDSS distribution. The only modifications are done directly by the script, removing interactive features and some other minor issues. Most of the sample files from the official OpenDSS repository are used for validation.
The validation scripts is
tests/validation.py and requires the same folder structure as the building process. You need
win32com to run it on Windows.
As of version 0.11, the full validation suite can be run on the three supported platforms. This is possible by saving the official COM DLL output and loading it on macOS and Linux. We hope to automate this validation in the future.
Besides bug fixes, the main funcionality of this library is mostly done. Notable desirable features that may be implemented are:
- More and better documentation (watch https://github.com/dss-extensions/dss-extensions)
- Plotting and reports integrated in Python. Several of the plot types optionally available in DSS Python 0.12.0, buta few are missing. Reports and advanced integration are planned for a future feature.
Expect news about these items by version 0.13.
If you have any question, feel free to open a ticket on GitHub, or contact directly me through email (pmeira at ieee.org). Please allow me a few days to respond.
Credits / Acknowlegement
DSS Python is based on EPRI's OpenDSS via the
dss_capi project, check its licensing information.
This project is licensed under the (new) BSD, available in the
LICENSE file. It's the same license OpenDSS uses (
OPENDSS_LICENSE). OpenDSS itself uses KLUSolve and SuiteSparse, licensed under the GNU LGPL 2.1.
I thank my colleagues at the University of Campinas, Brazil, for providing feedback and helping me test this module.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for dss_python-0.12.1.post2-cp36-abi3-win_amd64.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-win32.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-macosx_11_0_arm64.whl
Hashes for dss_python-0.12.1.post2-cp36-abi3-macosx_10_15_x86_64.whl