Dss-python

To install all recommended packages, including OpenDSSDirect.py, AltDSS, matplotlib (to allow enabling plotting from DSS scripts) and pandas:


pip install dss-python[all]==0.15.7


In a typical Python environment, users will most likely have both matplotlib and pandas already installed.

❓AltDSS-Python

Like OpenDSSDirect.py, AltDSS-Python can also be used together with DSS-Python. Since multiple DSS engines are supported, there are utility functions to map across the packages. AltDSS-Python, or just AltDSS in this context, uses a whole different paradigm from the older Python packages, moving away from the "Active..." paradigm. The new AltDSS includes integration to all OpenDSS object types (access, creation, manipulation, all directly in Python), exposed as Python objects, and also allows using batches of DSS objects to accelerate some operations that would be otherwise slow in Python, pushing many operations to the engine, ranging from collected results for multiple objects, to efficient use of DSS properties. For example, bulk updating (incrementing/decrementing/multiplying/etc.) an int or float property for thousands of elements doesn't require copying the data and is done directly in the engine, after the input data for the operation is prepared in Python.

Engine updates

As usual, there have been a lot of changes our OpenDSS engine, AltDSS/DSS C-API. See https://github.com/dss-extensions/dss_capi/blob/master/docs/changelog.md#versions-014x for the complete changes since the last announced release here on GitHub. There are a few specific bugfixes, ports from the official OpenDSS, besides the on-going refactoring of the whole codebase.

To install all recommended packages, including OpenDSSDirect.py, AltDSS, matplotlib (to allow enabling plotting from DSS scripts) and pandas:


pip install dss-python[all]==0.15.6


In a typical Python environment, users will most likely have both matplotlib and pandas already installed.

❓AltDSS-Python

Like OpenDSSDirect.py, AltDSS-Python can also be used together with DSS-Python. Since multiple DSS engines are supported, there are utility functions to map across the packages. AltDSS-Python, or just AltDSS in this context, uses a whole different paradigm from the older Python packages, moving away from the "Active..." paradigm. The new AltDSS includes integration to all OpenDSS object types (access, creation, manipulation, all directly in Python), exposed as Python objects, and also allows using batches of DSS objects to accelerate some operations that would be otherwise slow in Python, pushing many operations to the engine, ranging from collected results for multiple objects, to efficient use of DSS properties. For example, bulk updating (incrementing/decrementing/multiplying/etc.) an int or float property for thousands of elements doesn't require copying the data and is done directly in the engine, after the input data for the operation is prepared in Python.

Engine updates

As usual, there have been a lot of changes our OpenDSS engine, AltDSS/DSS C-API. See https://github.com/dss-extensions/dss_capi/blob/master/docs/changelog.md#versions-014x for the complete changes since the last announced release here on GitHub. There are a few specific bugfixes, ports from the official OpenDSS, besides the on-going refactoring of the whole codebase.

DSS-Python 0.14.4 upgrades the DSS engine to address a bug fixed in OpenDSS v9.6.1.3, plus a couple minor improvements in our implementation.

There were also incremental changes in the internals of the [plotting system](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/Plotting.ipynb). The backend for equivalent to DSSEvents in the COM API has been implemented, but not exposed nicely in DSS-Python yet.

❓ What's this?

DSS-Python is a Python package that provides access to the DSS-Extensions engine, using DSS C-API and CFFI. This engine is a customized port of the Windows/Delphi code to Free Pascal, including several quality-of-life improvements for Python users. DSS-Python tries to provide a drop-in replacement from the official OpenDSS COM API, while adding some features/extensions. It is also the underlying package used by OpenDSSDirect.py since 2018. If you are new to DSS-Extensions, [see our FAQ here](https://github.com/dss-extensions/dss-extensions#faq), as well as https://dss-extensions.org/

Version 0.14.4 has been released on the official Python package repository (PyPI). Since version 0.14.0, the main DSS-Python package is pure Python, but relies on the new `dss-python-backend` to allow us easier iteration on Python features. The backend package is available for Windows, macOS and Linux. This release includes support for Intel x86 and x86-64, ARM platforms, including Apple's M1 and later.

Please feel free to open issues on GitHub or post on https://github.com/orgs/dss-extensions/discussions

**Note:** Although the majority of features are ported frequently from the official OpenDSS and validated with a large suite of tests, this is not supported by EPRI.

The main differences in behavior compared to the official OpenDSS implementation are listed in https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Some of the tests can also serve as examples of some features. For example, see [test_general.py/test_threading2](https://github.com/dss-extensions/dss_python/blob/master/tests/test_general.py#L368) for an example of how to use DSSContexts and Python threads.

Installation

Using pip (Python versions: 3.7 to 3.11):


pip install dss_python==0.14.4


The binary wheels are also available as attachments on this release announcement.

If you encounter issues installing on Linux, be sure to update your `pip` and `wheel` packages before reporting a problem (versions too old may fail).

For PyPy, we recommend the users to build the wheels. If you'd like to use PyPy but aren't able to easily build the packages, please [report here on GitHub](https://github.com/dss-extensions/dss_python/issues).

---

🐍 DSS-Python 0.14.4 changes

- Upgrade the backend to [**DSS C-API 0.13.4**](https://github.com/dss-extensions/dss_capi/releases/tag/0.13.4). Includes a bugfix to CapControl, some more error handling, DSSEvents backend functions. This matches the changes in OpenDSS v9.6.1.3, plus our custom changes as usual.
- Use better DSSContext pointer to IDSS mapping.
- Plotting: handle empty monitors better, ignore invalid channels.
- Documentation updated.

⚙️ DSS C-API 0.13.4 changes

[**check its repo for more info**](https://github.com/dss-extensions/dss_capi/)

Bugfix release for `CapControl`, couple with some incremental improvements.

This version should match OpenDSS v9.6.1.3 (SVN r3623).

- Ported from the official OpenDSS SVN code:
- `CapControl`, port SVN 3622: "Solves a bug introduced in version 9.6.1.2 when using CapControl in time or follow control modes." (by davismont).

- Added `DSSEvents`: Implement an initial set of functions analog to the COM interface. This was added for historical compatibility since use of `DSSEvents` is rarely seen. [This document from EPRI (2011)](https://restservice.epri.com/publicdownload/000000000001020090/0/Product) presents the equivalent in the COM interface. Examples will be added in our downstream projects when time allows (feel free to request one to signal interest in this feature).
- Handle better how the internal `SolutionAbort` is used. Some invalid states were not being handled on absence of float-point exceptions, leading to potential useless results (NaN) and even crashes.
- `VSource`: Abort the solution if Z1 is zero.
- API/ArrayDimensions: fix `CktElement_Get_NodeOrder`; add to `CktElement_Get_Powers`.

DSS-Python 0.14.3 upgrades the DSS engine mainly to address bugs fixed in OpenDSS v9.6.1.2 (some present for several years, read below), plus a couple minor fixes on our alternative implementation.

There was also incremental progress in the [plotting system](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/Plotting.ipynb).

---

DSS-Python is a Python package that provides access to the DSS-Extensions engine, using DSS C-API and CFFI. This engine is a customized port of the Windows/Delphi code to Free Pascal, including several quality-of-life improvements for Python users. DSS-Python tries to provide a drop-in replacement from the official OpenDSS COM API, while adding some features/extensions. It is also the underlying package used by OpenDSSDirect.py since 2018. If you are new to DSS-Extensions, [see our FAQ here](https://github.com/dss-extensions/dss-extensions#faq), as well as https://dss-extensions.org/

Version 0.14.3 has been released on the official Python package repository (PyPI). Since version 0.14.0, the main DSS-Python package is pure Python, but relies on the new `dss-python-backend` to allow us easier iteration on Python features. The backend package is available for Windows, macOS and Linux. This release includes support for Intel x86 and x86-64, ARM platforms, including Apple's M1 and later.

Please feel free to open issues on GitHub or post on https://github.com/orgs/dss-extensions/discussions

**Note:** Although the majority of features are ported frequently from the official OpenDSS and validated with a large suite of tests, this is not supported by EPRI.

The main differences in behavior compared to the official OpenDSS implementation are listed in https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Some of the tests can also serve as examples of some features. For example, see [test_general.py/test_threading2](https://github.com/dss-extensions/dss_python/blob/master/tests/test_general.py#L368) for an example of how to use DSSContexts and Python threads.

Installation

Using pip (Python versions: 3.7 to 3.11):


pip install dss_python==0.14.3


The binary wheels are also available as attachments on this release announcement.

If you encounter issues installing on Linux, be sure to update your `pip` and `wheel` packages before reporting a problem (versions too old may fail).

For PyPy, we recommend the users to build the wheels. If you'd like to use PyPy but aren't able to easily build the packages, please [report here on GitHub](https://github.com/dss-extensions/dss_python/issues).

---

🐍 DSS-Python 0.14.3 changes

- Upgrade the backend to [**DSS C-API 0.13.3**](https://github.com/dss-extensions/dss_capi/releases/tag/0.13.3). Includes important fixes to some OpenDSS components affected by bugs for several years. This matches the changes in OpenDSS v9.6.1.2, plus our custom changes as usual.
- Add `DSS.Error.UseExceptions` to allow disabling the automatic mapping of error numbers to Python exceptions. When disabling, users take full responsibility to actually check for errors through the `DSS.Error` interface.
- Add `DSSCompatFlags.SaveCalcVoltageBases`.
- Transformers: add a warning in the docstrings of `WdgCurrents`, `WdgVoltages` (these don't work well when the transformer has open terminals).
- Plotting: handle GICLines in circuit plots.

⚙️ DSS C-API 0.13.3 changes

[**check its repo for more info**](https://github.com/dss-extensions/dss_capi/)

Bugfix release for some components. No other major changes.

Fixes ported from the official OpenDSS v9.6.1.2 (SVN r3619) released on 2023-06-06, plus our custom changes (including new tests). Test circuits cross-validated as usual.

- `LoadShape`: check if there's any allocated pointer before normalizing. Since we provide more ways to fill the LoadShape data besides the official alternatives, we needed to add a few more checks in case of misuse to avoid using invalid pointers. Includes a minor fix to how manual values (set by the user) for `mean` and `stddev` are handled.
- `show` command: adjust formatting for `show variables`, `show isolated`, `show loops`, `show faults`.
- `GICTransformer`: clean-up the code and add a minor fix for `BusX`.
- Editor: tweak how the process is started; works better on Linux for terminal-based editors (GUI editors are recommended for a better experience though).
- Obj/API and headers: new functions and add a few warnings in the docs.
- New compatibility flag in `DSSCompatFlags`: add `SaveCalcVoltageBases`. On recent versions, running a `save circuit` doesn't include a `CalcVoltageBases` anymore since that causes issues for some users. We added the new flag `SaveCalcVoltageBases` to restore the old/original behavior. More options are planned for a future version in a dedicated function in the API.

- Ported (and complemented) from the official OpenDSS SVN code:
- `UPFC`, r3610: "Fixing losses in UPFC model, there was a bug introduced several years ago when trying to redefine losses based on residual currents (bad idea)." (by davismont)
- `CapControl`, r3615: "Fixing property requirement (element) for capcontrol in Time and Follow control modes", by davismont
- `Capacitor`/`Reactor`: fixes related to 1- or 2-phase LL objects and Yprim; NormAmps/EmergAmps.
- r3613: "Fixing bug in Yprim formation for 1-ph and 2-ph delta-connected capacitors. Fix to user-specified NormAmps and EmergAmps for capacitors, which were always being overridden with default values. Pending to check for same issues on Reactors." (by celsorocha)
- r3616: "Fixing bug in Yprim formation for 1-ph and 2-ph delta-connected reactors. Fix to user-specified NormAmps and EmergAmps for reactors, which were always being overridden with default values." (by celsorocha)
- Also includes an extra fix for a corner-case issue detected with our tests on DSS-Extensions.
- `PVSystem`/`Storage`/`InvControl`, r3597/r3598: "Adding current limiting capabilities to IBR in QSTS and dynamics modes. Examples also available." (by davismont). Also refactored more common code to InvBasedPCE on the DSS-Extensions version.

DSS-Python 0.14.2 upgrades the DSS engine, complements the plotting backend, and updates the JSON exports and Obj/Batch APIs. The following notebooks can give an overview of some features:

- [DSS-Extensions — Integrated plotting in Python](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/Plotting.ipynb)
- [DSS-Extensions — JSON exports](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/JSON.ipynb)

Both can be run with Google Colab (links included in the notebooks), but some features may work better on a local installation. As always, feedback is welcome!

---

DSS-Python is a Python package that provides access to the DSS-Extensions engine, using DSS C-API and CFFI. This engine is a customized port of the Windows/Delphi code to Free Pascal, including several quality-of-life improvements for Python users. DSS-Python tries to provide a drop-in replacement from the official OpenDSS COM API, while adding some features/extensions. It is also the underlying package used by OpenDSSDirect.py since 2018. If you are new to DSS-Extensions, [see our FAQ here](https://github.com/dss-extensions/dss-extensions#faq), as well as https://dss-extensions.org/

Version 0.14.2 has been released on the official Python package repository (PyPI). Since version 0.14.0, the main DSS-Python package is pure Python, but relies on the new `dss-python-backend` to allow us easier iteration on Python features. The backend package is available for Windows, macOS and Linux. This release includes support for Intel x86 and x86-64, ARM platforms, including Apple's M1 and later.

Please feel free to open issues on GitHub or post on https://github.com/orgs/dss-extensions/discussions

**Note:** Although the majority of features are ported frequently from the official OpenDSS and validated with a large suite of tests, this is not supported by EPRI.

The main differences in behavior compared to the official OpenDSS implementation are listed in https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Some of the tests can also serve as examples of some features. For example, see [test_general.py/test_threading2](https://github.com/dss-extensions/dss_python/blob/master/tests/test_general.py#L368) for an example of how to use DSSContexts and Python threads.

Installation

Using pip (Python versions: 3.7 to 3.11):


pip install dss_python==0.14.2


The binary wheels are also available as attachments on this release announcement.

If you encounter issues installing on Linux, be sure to update your `pip` and `wheel` packages before reporting a problem (versions too old may fail).

For PyPy, we recommend the users to build the wheels. If you'd like to use PyPy but aren't able to easily build the packages, please [report here on GitHub](https://github.com/dss-extensions/dss_python/issues).

---

⚙️ DSS C-API 0.13.2 changes

[**check its repo for more info**](https://github.com/dss-extensions/dss_capi/)

- Integrate some of the code ports from the official OpenDSS. A few changes were left in the `next_svn_merge` branch to be integrated after there is a new OpenDSS release.
- Fix and complement some header code and comments.
- Refactor more of the internal code (huge merge still pending).
- Plotting: callback messages now include bus marker information. [This is used only in Python at the moment](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/Plotting.ipynb).
- Add more error-checking to avoid accidental crashes in case of unexpected calls by the user code.
- `Text_CommandBlock`: rewritten, now reuses the internal `DoRedirect` function, which allows block comments and also complements the error backtrace, when necessary.
- `Obj_GetClassIdx`: fixed both header and implementation.
- Build scripts updated. The version in the header is automatically updated on release.
- JSON exports: new flags implemented, and whole behavior adjusted to better exporting all classes, including some problematic cases See [DSS-Extensions — JSON exports](https://github.com/dss-extensions/dss_python/blob/master/docs/examples/JSON.ipynb) for notes and examples.