OpenDSS bindings based on the DSS C-API project
Project description
dss_python: Unofficial bindings for EPRI's OpenDSS
Python bindings and misc tools for using OpenDSS (EPRI Distribution System Simulator). Based on CFFI and dss_capi
, aiming for full COM compatibility on Windows and Linux.
If you are looking for the C API library, see dss_capi
.
Version 0.9.8, based on OpenDSS revision 2246. This is a work-in-progress but it's deemed stable enough to be made public. Note that, while the interface with OpenDSS is stable (classic version), the OpenDSS-PM (actor-based parallel machine version) interface was integrated recently and is experimental.
This module mimics the COM structure (as exposed via win32com
or comtypes
), effectively enabling multi-platform compatibility at Python level.
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.
This module depends on CFFI, NumPy and, optionally, SciPy.Sparse for reading the sparse system admittance matrix.
Recent changes
- 2018-08-10 / 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
ActiveCircuit.CktElements[index]
(or...CktElements(index)
) andActiveCircuit.Buses[index]
(or...Buses(index)
). - 2018-03-07 / version 0.9.4: Allows using
len
on 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 (
First
Next
iteration 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)
Missing features and limitations
Most limitations are inherited from dss_capi
, i.e.:
-
Only the 64-bit version of OpenDSS is built. A 32-bit version should be possible with a few changes.
-
Currently not implemented:
DSSEvents
fromDLL/ImplEvents.pas
: seems too dependent on COM.DSSProgress
fromDLL/ImplDSSProgress.pas
: would need a reimplementation depending on the target UI (GUI, text, headless, etc.)
-
Although tests were successful on openSuse 42.3 (both CPython 3.6 and PyPy3.5 v5.10.1).
Extra features
Besides most of the COM methods, 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).
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.
Installing
On Windows (Python 2.7, 3.6 and 3.7), you can install directly from pip:
pip install dss_python
If successful, you can then import the dss
module from your Python interpreter.
Building
Get this repository:
git clone https://github.com/PMeira/dss_python.git
Assuming you successfully built or downloaded the dss_capi
(check its repository for instructions), keep the folder organization as follows:
dss_capi/
dss_python/
electricdss-src/
Open a command prompt in the dss_python
subfolder and run the build process:
python setup.py build
python setup.py install
Example usage
If you were using win32com
in code like:
import win32com.client
dss_engine = win32com.client.Dispatch("OpenDSSEngine.DSS")
or comtypes
:
import comtypes.client
dss_engine = comtypes.client.CreateObject("OpenDSSEngine.DSS")
you can replace that fragment with:
import dss
dss.use_com_compat()
dss_engine = dss.DSS
Assuming you have a DSS script named master.dss
, you should be able to run it as shown below:
import dss
dss.use_com_compat()
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]))
If you do not need the mixed-cased handling, you can omit the call to use_com_compat()
and use the casing used in this project.
If you want to play with the experimental OpenDSS-PM interface, it is installed side-by-side and you can import it as:
import dss.pm
dss.pm.use_com_compat()
dss_engine = dss.pm.DSS
Testing
Since the DLL is built using FreePascal, 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 minor other minor issues.
The validation scripts is tests/validation.py
and requires the same folder structure as the building process. You need win32com
to run it.
Currently, the following sample files from the official OpenDSS repository are used:
Distrib/EPRITestCircuits/ckt5/Master_ckt5.dss
Distrib/EPRITestCircuits/ckt7/Master_ckt7.dss
Distrib/EPRITestCircuits/ckt24/Master_ckt24.dss
Distrib/IEEETestCases/8500-Node/Master-unbal.dss
Distrib/IEEETestCases/IEEE 30 Bus/Master.dss
Distrib/IEEETestCases/NEVTestCase/NEVMASTER.DSS
Distrib/IEEETestCases/37Bus/ieee37.dss
Distrib/IEEETestCases/4Bus-DY-Bal/4Bus-DY-Bal.DSS
Distrib/IEEETestCases/4Bus-GrdYD-Bal/4Bus-GrdYD-Bal.DSS
Distrib/IEEETestCases/4Bus-OYOD-Bal/4Bus-OYOD-Bal.DSS
Distrib/IEEETestCases/4Bus-OYOD-UnBal/4Bus-OYOD-UnBal.DSS
Distrib/IEEETestCases/4Bus-YD-Bal/4Bus-YD-Bal.DSS
Distrib/IEEETestCases/4Bus-YY-Bal/4Bus-YY-Bal.DSS
Distrib/IEEETestCases/123Bus/IEEE123Master.dss
Distrib/IEEETestCases/123Bus/SolarRamp.DSS
Distrib/IEEETestCases/13Bus/IEEE13Nodeckt.dss
Test/IEEE13_LineSpacing.dss
Test/IEEE13_LineGeometry.dss
Test/IEEE13_LineAndCableSpacing.dss
Test/IEEE13_Assets.dss
Test/CableParameters.dss
Test/Cable_constants.DSS
Test/BundleDemo.DSS
Test/IEEE13_SpacingGeometry.dss
Test/TextTsCable750MCM.dss
Test/TestDDRegulator.dss
Test/XYCurvetest.dss
Test/PVSystemTestHarm.dss
Test/TestAuto.dss
Test/Stevenson.dss
Test/YgD-Test.dss
Test/Master_TestCapInterface.DSS
Test/LoadTest.DSS
Test/IEEELineGeometry.dss
Test/ODRegTest.dss
Test/MultiCircuitTest.DSS
Test/TriplexLineCodeCalc.DSS
Test/PVSystemTest-Duty.dss
Test/PVSystemTest.dss
Test/REACTORTest.DSS
On Windows 10, remember to set the compatibility layer to Windows 7 (set the environment variable __COMPAT_LAYER=WIN7RTM
), otherwise you may encounter issues with COM due to ASLR on Python 3.6.
There is no validation on Linux yet, since we cannnot run the COM module there. The most likely solution will be to pickle the data on Windows and load them on Linux.
Roadmap
Besides bug fixes, the main funcionality of this library is mostly done. Notable desirable features that may be implemented are:
- More and better documentation
- Create wheels for Linux distributions, maybe using the Anaconda stack.
- Create a more "Pythonic" API. This would break compatibility with COM, but may result in a more pleasant environment for using OpenDSS in Python.
Questions?
If you have any question, feel free to open a ticket on Github or contact me through Twitter. 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
).
I thank my colleagues at the University of Campinas, Brazil, for providing feedback and helping me test this module.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for dss_python-0.9.8-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2b70aa710adaf94a2b7788a83961e09b5d68fce86b71e6179df3eef599b4eae1 |
|
MD5 | ba5880084e09f4ee2dae675c6514d143 |
|
BLAKE2b-256 | 01449b7b908415f0e3ecbc413ebf6895b4465ca04c24d15d974ddac812e6cf2b |
Hashes for dss_python-0.9.8-cp37-cp37m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4f2a476901598b9640b1568212184aa03b6b70033e14952d17d1916822c18ae0 |
|
MD5 | 8864312cf4035d3367efd76a486fb27b |
|
BLAKE2b-256 | 8bda8001f7228a0edd1402a5314450a9ce9fec2e790d7191d234c3d8f9fd4a60 |
Hashes for dss_python-0.9.8-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4cf88de532d00c0a89157bb67d87e0b5b8c9ea0beacba1655cf3c4ae217b5cf0 |
|
MD5 | bcc9aa72bb58cff3b19d649c9812cc73 |
|
BLAKE2b-256 | a991b9259a1a5628c31261d51ac6f3110311c0583637b61eb75fa9970d1e38db |
Hashes for dss_python-0.9.8-cp37-cp37m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a54ae58e06842d47452fb7eabe56c9828b64c47185bfd0cac9c37cc61a00f18f |
|
MD5 | b8be59ec4b889ff318f89a26a93257b8 |
|
BLAKE2b-256 | a4b3d6c9b4064b2acd936e7ee67c1357430cdd7aca3f19f37c8b3bd29852ba49 |
Hashes for dss_python-0.9.8-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 26cad6c4fcc4184f5f4f5fe2ab911c541a208bbd97b7ed9952dcfdba58ebcefb |
|
MD5 | dda33deb76ae906f3cba81e87f40b479 |
|
BLAKE2b-256 | 45176cc425bf000d9b418ff470db4847cf4d3fefbcf74280c1065519744de6ff |
Hashes for dss_python-0.9.8-cp36-cp36m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0eae2829b4136a87d40fd19a4a2bf1cd8a6bfcd1ae11a0be5bd30722f5f822a3 |
|
MD5 | 50c1a27dd515ac3294a86dc7ad1f1ee4 |
|
BLAKE2b-256 | 079c62d81f32ef6f4855894a397bf15b55f8b329c3d3ae576cb6801afa6f8278 |
Hashes for dss_python-0.9.8-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5eb6135fdb9f290be628bd81e3db01b8b0aad9c255fddc2db0f770f41209241c |
|
MD5 | ed2cda84601e9ee2569410051495f237 |
|
BLAKE2b-256 | 408db895adaac785a37c895fc27c313c91f6c5474cea39d889cafbd2db56690a |
Hashes for dss_python-0.9.8-cp36-cp36m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 04b48992bdb1f98c3ba3c9596157fe4ce1d3db51b241bc13735f0f359e8906bf |
|
MD5 | f8def232283ecabe5e2311e9983d2cc4 |
|
BLAKE2b-256 | b8f9392798beaebd681c131904eb454f5a3e14b1790f6583a1b2cdd8e80bd4f7 |
Hashes for dss_python-0.9.8-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dde82879808578ecaaffb507026ec5cf4590bfa1dfe088182d3ea19e1ee04ba3 |
|
MD5 | 844d81de109081aafb696b16ad9d4ea7 |
|
BLAKE2b-256 | 6874ba6daf7e1b1e2bbaf746472c360a10d1954d9a8014a9d150ab69eeba844b |
Hashes for dss_python-0.9.8-cp35-cp35m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebdffe75fa82c0078a16b33a52705e3c3e86b8368aa64c74fff598e6f1e6bcd7 |
|
MD5 | 040ef25466a03566faadf008118a88b3 |
|
BLAKE2b-256 | 662c5784bf435887453e12313380de960f1ea3cc8bff9687fd73d394e7e31ada |
Hashes for dss_python-0.9.8-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d63d9f7ed5a24f2f2b4c69b64caa446ba89be91760fab077c6688ddbf4dc98b1 |
|
MD5 | c168f1bcf14adf2e24eae1633fd5e82a |
|
BLAKE2b-256 | 4780f64c7b4a619e7c1d37aabed57b9b193306893bd04566f0a2b9f383083681 |
Hashes for dss_python-0.9.8-cp35-cp35m-macosx_10_6_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c5522d364eddddf2d1c67ead6be193dc7a521850be066f3a63649207cde48814 |
|
MD5 | b28b6a76814ea24711e49941557c1d75 |
|
BLAKE2b-256 | 36c2d3039e8f30920762db98a5df084bdd93b3dce1994e0caa1faab81ef63f17 |
Hashes for dss_python-0.9.8-cp34-cp34m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bda92c3bc52cf7f0fb30c6fbac99247ce5392fd1e89517effb9bd41ceb363aaf |
|
MD5 | 5afe1986b43857186c0df19fb6ac45f6 |
|
BLAKE2b-256 | c1c9255de4d9b2c38f56c7e4764503ed0c49517829fce6eb664dcde541dfa8ac |
Hashes for dss_python-0.9.8-cp27-cp27mu-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 59bb53910bc0cae29889b7c433e5a90b825ac65d162d7851f2b16c981346f55e |
|
MD5 | 4f53ff72dab74ec339b62cc14b27ed27 |
|
BLAKE2b-256 | 41190a161227cc673021e3454f57d20b70504d94bb6d0bdf3e3f39175bf807b9 |
Hashes for dss_python-0.9.8-cp27-cp27m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cd0c69dae0e1be583b8d07ef30380074d02cd0670711b8b4b06498705641c5c4 |
|
MD5 | 8aff83e0e749b2e35d2a35d1ee885aa6 |
|
BLAKE2b-256 | 8a4dd07d961436749dfcbbcdda232186a860a79a591cee11b400187bfce4149e |
Hashes for dss_python-0.9.8-cp27-cp27m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1d003cd44436d03d846df6b5d39918c3d99cb78968270e354e2d958d6ec470d6 |
|
MD5 | 9438c6760188b6bb6e8f82b42afd637b |
|
BLAKE2b-256 | 915ffe75667f87b9bbad66029101ee1f81de8fe45d14cdaa4954260100df3112 |
Hashes for dss_python-0.9.8-cp27-cp27m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 30a6e01da74a001511c3720b65d1c861027830b7aef1fd8dbecd4e3a0fba3b1b |
|
MD5 | 2941c1c5b809ec1ec1d8e15728468d4e |
|
BLAKE2b-256 | 5a72833a8ffaf50263ac1cb7790310d2580710eb01094c85959f8038685e7d76 |
Hashes for dss_python-0.9.8-cp27-cp27m-macosx_10_6_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 588a761ed418a7841cdde96d85d8d40c0de35ac559d3f5250011982612747e23 |
|
MD5 | a6df5be66fbec82f72521317200e65af |
|
BLAKE2b-256 | e8b1c4df7d4e4285ca54ced7028b5b849e297e0fa9ba16b179e271ebb5e53c2e |