OpenDSSDirect.py v0.9.4

OpenDSSDirect.py v0.9.4 includes two fixes:

• Fixed in our DSS engine, the LineGeometries API now returns all conductors even if reduce=yes.
• The to_altdss() function now works again.

An upcoming release is expected for the next week, including bringing back support for the official OpenDSSDirect.DLL on Windows, within its limitations (in terms of API, features and platforms, for the moment).

Recently, we've released the refactored OpenDSSDirect.py, v0.9, that allows multiple OpenDSS engines, Python iteration for classes, safer access (avoids some common issues we observed throughout the years), and more. There is an update/upgrade guide at the documentation site: https://dss-extensions.org/OpenDSSDirect.py/updating_to_0.9.html

❓ What's this?

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS-Extensions project.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for important changes in the ecosystem, starting in v0.9.

ℹ️ Recent news

Besides the codebase update for v0.9, the documentation and examples have also been updated, and will be better integrated into the new DSS-Extensions site soon, which does contain shared documentation, including DSS language/data model reference and notes about the classic OpenDSS API (based on the original COM implementation).

Other highlights in v0.9: there are new functions to save the circuit which customized flags, and the work-in-progress JSON implementation now allows both saving and loading whole circuits.

❓AltDSS-Python

Like DSS-Python, AltDSS-Python can also be used together with OpenDSSDirect.py. 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.

OpenDSSDirect.py v0.9.3

In v0.9.3, we started pinning, again, exact versions of DSS-Python to make it easier for users to track the changes. We expect to integrate to PyPI to automate the releases in the future.

In the past month, we've released the refactored OpenDSSDirect.py that allows multiple OpenDSS engines, Python iteration for classes, safer access (avoids some common issues we observed throughout the years), and more. There is an update/upgrade guide at the documentation site: https://dss-extensions.org/OpenDSSDirect.py/updating_to_0.9.html

Although v0.9.0 was released on 2024-02-12, we held this announcement until now to allow the new companion package to be tested more before recommending it. Some features that initially were expected to land on OpenDSSDirect.py have now been published under this new package, AltDSS-Python. Check its site for the motivation, examples, and API reference.

❓ What's this?

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS-Extensions project.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for important changes in the ecosystem, starting in v0.9.

ℹ️ Recent news

Besides the codebase update for v0.9, the documentation and examples have also been updated, and will be better integrated into the new DSS-Extensions site soon, which does contain shared documentation, including DSS language/data model reference and notes about the classic OpenDSS API (based on the original COM implementation).

Other highlights in v0.9: there are new functions to save the circuit which customized flags, and the work-in-progress JSON implementation now allows both saving and loading whole circuits.

❓AltDSS-Python

Like DSS-Python, AltDSS-Python can also be used together with OpenDSSDirect.py. 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.

OpenDSSDirect.py v0.8.4

Version 0.8.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, which is shared with DSS-Python. The backend for equivalent to DSSEvents in the COM API has been implemented, but not exposed nicely in Python yet.

❓ What's this?

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS-Extensions project.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for other important changes including bugfixes, new features, and changes in behavior.

Full Git Changelog: v0.8.3...v0.8.4

🐍 DSS-Python 0.14.4 changes

• Upgrade the backend to DSS C-API 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

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) 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.

OpenDSSDirect.py v0.8.3

Version 0.8.3 is being released to include recent bugfixes to the DSS engine (some present for several years, read below), porting the updates from OpenDSS v9.6.1.2.

There was also incremental progress in the plotting system, which is shared with DSS-Python.

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS-Extensions project.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for other important changes including bugfixes, new features, and changes in behavior.

❓ What's this?

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS-Extensions project.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for other important changes including bugfixes, new features, and changes in behavior.

Full Git Changelog: v0.8.2...v0.8.3

🐍 DSS-Python 0.14.3 changes

• Upgrade the backend to DSS C-API 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.4 changes

check its repo for more info

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.

OpenDSSDirect.py v0.8.1

Version 0.8.1 is a minor release to address a minor concern related to a potential issue with three of the PVSystem properties in our DSS engine (DSS C-API). Version 0.8.0 notes follow.

---

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS Extensions project.

OpenDSSDirect.py v0.8.0 upgrades DSS-Python and DSS C-API to the latest versions, integrating most changes from the official OpenDSS up to March 2023. There are minor changes in the codebase, but enough changes in the DSS engine to justify a new version, especially the new features of the inverter-based models and related changes.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes, new features, and changes in behavior.

Full Git Changelog: v0.7.0...v0.8.0

DSS-Python 0.13.0

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, as well as https://dss-extensions.org/

Version 0.13.0 has been released on the official Python package repository (PyPI) for Windows, macOS and Linux. This release includes support for Intel x86 and x86-64, ARM platforms, including Apple's M1 and later. Coming in the following days:

• Some Linux ARM packages will be uploaded later, since they have to be manually prepared at the moment.
• For Anaconda cloud (channel dss-extensions), packages will also be uploaded in the coming days.
• The documentation and other sites need to be updated.
• An upcoming minor release should target plotting, specifically. This releases already handles many types of plot commands, but some are still pending or need to be fixed.

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

As mentioned in the changelog (copied below), some of the new tests prepared for this version can also serve as examples of some features. For example, see test_general.py/test_threading2 for an example of how to use DSSContexts and Python threads.

DSS-Python 0.13.0: changes since 0.12.1

• Engine updated to DSS C-API 0.13.0, which is very compatible with OpenDSS 9.6.1.1 (plus some official SVN commits up to rev 3595, plus our own changes.
• New test suite, which runs many more files and validates more of the API. We now use pytest for some more complex tests, while the numeric validation is done with the new compare_outputs.py.
• New DSS.AdvancedTypes: toggle matrix shapes and complex numbers in many of the properties and functions of the API. This is disabled by default.
• New DSS.CompatFlags: to address some concerns about compatibility, we added a few toggles to toggle behavior that matches the official OpenDSS more closely. This flags will be refined in later releases.
• Drop deprecated IR classes and a few undocumented functions.
• Use more enums throughout the code, which helps both readability and documentation. Some enums were complemented.
• DSS.AdvancedTypes toggle: enabling AdvancedTypes allows using array/matrix shapes and complex numbers as results from properties/functions in the API.
• Plotting: Implement several plot types. Only a few issues need to be addressed to consider the plotting system complete!
• Notebook integration: Initial prototype available. It is enabled automatically when DSS.Plotting.enable() is run in a notebook, providing integration with some DSS messages and outputs.
  • It also registers the %%dss cell magic. Use it in a cell to run DSS-language code directly. We found it useful for exploration and learning.
• Updated patch_dss_com to patch a few more classes.
• Drop Python 3.6 support, include 3.11 officially in the tests.
• DSSContext disposal: use CFFI to track the disposal of the contexts instead of manually tracking. This could remove memory leaks if you application creates too many DSSContexts (which is not recommended).
• DSS.Obj: remove some redundant properties, fix several issues. While it's not complete yet (some known limitations), you can see the tests for a few examples of how to create circuits without .DSS scripts/files in tests/test_obj.py and tests/test_batch.py -- the first creates each object explicitly, while the second uses batch operations to fill properties from arrays and lists.
• Add typing_extensions as a dependency to address Python typing needs in the main API code and the new Obj API.
• Docs: mark more properties as "(API Extension)".
• Internal code refactoring and clean-up.

Full Git Changelog: dss-extensions/DSS-Python@0.12.1-2...0.13.0

DSS C-API 0.13.0 changes

check its repo for more info

• Clean-up several files to ease the transition from Pascal to C++; more enum usage, remove redundant internal properties, rename some class members, etc. Some final steps still remain (that work is done in private branches).
• Fixes a couple of minor memory leaks.
• Removed our old Legacy Models mechanism. Right now, the API functions still exist, but will have no effect when setting and will throw an error. For a future version, the functions will be removed. This toggle was introduced in 2020, some time after the removal of the legacy models in the official OpenDSS. We believe users had enough time to fully migrate and the extra maintenance burden is not justified anymore.
• Transition some deprecated and buggy properties to throw specific errors, instead of generic messages. Issue: dss-extensions/dss_capi#118
• Export command: When the user provides a filename, use it as-is, otherwise could be an invalid path in case-sensitive file systems (e.g. Linux, most likely).
• Dump and Save commands: in some cases, our internal "hybrid enums" were not being converted correctly for dumps. A few classes had incomplete dump implementations since v0.12.0; some strings needed to be escaped for correct output.
• CtrlQueue: adjust string formatting of items; although this doesn't affect the numeric results, the strings from the queue had some truncated numbers.
• Property system: For compatibility with the official version, allow autoresizing some arrays when given conflicting number of elements through the text interface or scripts.
• Like property: Although not recommended and deprecated in the official OpenDSS, the sequence of properties filled in the original copy is also copied. If you use Like, remember to check if the copy actually worked since some classes are known to not copy every property correctly.
• Plotting and UI: The engine side plotting callback system is now complete. There are fixes for DaisyPlot and GeneralDataPlot, especially multi-platform handling. Changed how some properties are exposed in the JSON interchange to the callbacks. Implement argument handling and callback dispatch for DI_Plot, CompareCases and YearlyCurves.
• New commands: Fix potential issue with null pointers and duplicate names when DuplicatesAllowed=False.
• EnergyMeter: Fix error message when the metered element is not a PDElement.
• CIMXML export: Fix issues present since v0.12.0; reported in #121
• Parser: properly error out when given excessive number of elements for matrices; implemented due to the report in #122
• Port most changes from the official OpenDSS up to SVN revision 3595 (OpenDSS v9.6.1.1 + a couple of CIMXML updates); check OpenDSS v9.6.1.1 README.txt for some complementary info to the list below.
  • Relay, UPFC, UPFCControl changes ported.
  • CIMXML exports: Various updates.
  • RegControl: More log and debug trace entries.
  • LoadMult: Set SystemYChanged when changing LoadMult through a DSS script or DSS command (doesn't affect Solution_Set_LoadMult)
  • Port PVSystem, Storage, InvControl, and StorageController changes, including the new grid-forming mode (GFM). For DSS Extensions, we added a new class InvBasedPCE to avoid some redundancy and make things clearer.
  • Port DynamicExp and related functionality. In our implementation, we also add a new class DynEqPCE to avoid some redundant code (could still be improved). the...

OpenDSSDirect.py v0.8.0

This package provides a multi-platform, function-style, direct interface to the OpenDSS engine implementation from the DSS Extensions project.

OpenDSSDirect.py v0.8.0 upgrades DSS-Python and DSS C-API to the latest versions, integrating most changes from the official OpenDSS up to March 2023. There are minor changes in the codebase, but enough changes in the DSS engine to justify a new version, especially the new features of the inverter-based models and related changes.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS-Python, DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes, new features, and changes in behavior.

Full Git Changelog: v0.7.0...v0.8.0

DSS-Python 0.13.0

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, as well as https://dss-extensions.org/

Version 0.13.0 has been released on the official Python package repository (PyPI) for Windows, macOS and Linux. This release includes support for Intel x86 and x86-64, ARM platforms, including Apple's M1 and later. Coming in the following days:

• Some Linux ARM packages will be uploaded later, since they have to be manually prepared at the moment.
• For Anaconda cloud (channel dss-extensions), packages will also be uploaded in the coming days.
• The documentation and other sites need to be updated.
• An upcoming minor release should target plotting, specifically. This releases already handles many types of plot commands, but some are still pending or need to be fixed.

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

As mentioned in the changelog (copied below), some of the new tests prepared for this version can also serve as examples of some features. For example, see test_general.py/test_threading2 for an example of how to use DSSContexts and Python threads.

DSS-Python 0.13.0: changes since 0.12.1

• Engine updated to DSS C-API 0.13.0, which is very compatible with OpenDSS 9.6.1.1 (plus some official SVN commits up to rev 3595, plus our own changes.
• New test suite, which runs many more files and validates more of the API. We now use pytest for some more complex tests, while the numeric validation is done with the new compare_outputs.py.
• New DSS.AdvancedTypes: toggle matrix shapes and complex numbers in many of the properties and functions of the API. This is disabled by default.
• New DSS.CompatFlags: to address some concerns about compatibility, we added a few toggles to toggle behavior that matches the official OpenDSS more closely. This flags will be refined in later releases.
• Drop deprecated IR classes and a few undocumented functions.
• Use more enums throughout the code, which helps both readability and documentation. Some enums were complemented.
• DSS.AdvancedTypes toggle: enabling AdvancedTypes allows using array/matrix shapes and complex numbers as results from properties/functions in the API.
• Plotting: Implement several plot types. Only a few issues need to be addressed to consider the plotting system complete!
• Notebook integration: Initial prototype available. It is enabled automatically when DSS.Plotting.enable() is run in a notebook, providing integration with some DSS messages and outputs.
  • It also registers the %%dss cell magic. Use it in a cell to run DSS-language code directly. We found it useful for exploration and learning.
• Updated patch_dss_com to patch a few more classes.
• Drop Python 3.6 support, include 3.11 officially in the tests.
• DSSContext disposal: use CFFI to track the disposal of the contexts instead of manually tracking. This could remove memory leaks if you application creates too many DSSContexts (which is not recommended).
• DSS.Obj: remove some redundant properties, fix several issues. While it's not complete yet (some known limitations), you can see the tests for a few examples of how to create circuits without .DSS scripts/files in tests/test_obj.py and tests/test_batch.py -- the first creates each object explicitly, while the second uses batch operations to fill properties from arrays and lists.
• Add typing_extensions as a dependency to address Python typing needs in the main API code and the new Obj API.
• Docs: mark more properties as "(API Extension)".
• Internal code refactoring and clean-up.

Full Git Changelog: dss-extensions/DSS-Python@0.12.1-2...0.13.0

DSS C-API 0.13.0 changes

check its repo for more info

• Clean-up several files to ease the transition from Pascal to C++; more enum usage, remove redundant internal properties, rename some class members, etc. Some final steps still remain (that work is done in private branches).
• Fixes a couple of minor memory leaks.
• Removed our old Legacy Models mechanism. Right now, the API functions still exist, but will have no effect when setting and will throw an error. For a future version, the functions will be removed. This toggle was introduced in 2020, some time after the removal of the legacy models in the official OpenDSS. We believe users had enough time to fully migrate and the extra maintenance burden is not justified anymore.
• Transition some deprecated and buggy properties to throw specific errors, instead of generic messages. Issue: dss-extensions/dss_capi#118
• Export command: When the user provides a filename, use it as-is, otherwise could be an invalid path in case-sensitive file systems (e.g. Linux, most likely).
• Dump and Save commands: in some cases, our internal "hybrid enums" were not being converted correctly for dumps. A few classes had incomplete dump implementations since v0.12.0; some strings needed to be escaped for correct output.
• CtrlQueue: adjust string formatting of items; although this doesn't affect the numeric results, the strings from the queue had some truncated numbers.
• Property system: For compatibility with the official version, allow autoresizing some arrays when given conflicting number of elements through the text interface or scripts.
• Like property: Although not recommended and deprecated in the official OpenDSS, the sequence of properties filled in the original copy is also copied. If you use Like, remember to check if the copy actually worked since some classes are known to not copy every property correctly.
• Plotting and UI: The engine side plotting callback system is now complete. There are fixes for DaisyPlot and GeneralDataPlot, especially multi-platform handling. Changed how some properties are exposed in the JSON interchange to the callbacks. Implement argument handling and callback dispatch for DI_Plot, CompareCases and YearlyCurves.
• New commands: Fix potential issue with null pointers and duplicate names when DuplicatesAllowed=False.
• EnergyMeter: Fix error message when the metered element is not a PDElement.
• CIMXML export: Fix issues present since v0.12.0; reported in #121
• Parser: properly error out when given excessive number of elements for matrices; implemented due to the report in #122
• Port most changes from the official OpenDSS up to SVN revision 3595 (OpenDSS v9.6.1.1 + a couple of CIMXML updates); check OpenDSS v9.6.1.1 README.txt for some complementary info to the list below.
  • Relay, UPFC, UPFCControl changes ported.
  • CIMXML exports: Various updates.
  • RegControl: More log and debug trace entries.
  • LoadMult: Set SystemYChanged when changing LoadMult through a DSS script or DSS command (doesn't affect Solution_Set_LoadMult)
  • Port PVSystem, Storage, InvControl, and StorageController changes, including the new grid-forming mode (GFM). For DSS Extensions, we added a new class InvBasedPCE to avoid some redundancy and make things clearer.
  • Port DynamicExp and related functionality. In our implementation, we also add a new class DynEqPCE to avoid some redundant code (could still be improved). the Generator and the new InvBasePCE derive from this new DynEqPCE. Note: the DynamicEq functionality from the upstream still seems incomplete and some things are not fully implemented or maybe...

OpenDSSDirect.py v0.7.0

This release upgrades DSS Python and DSS C-API to the latest versions, exposing new modules (Storages, Parallel, ZIP) and several functions, as well as integrating the most changes from the official OpenDSS.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS Python, DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes.

Full Git Changelog: v0.6.1...v0.7.0

DSS C-API 0.12 announcement

Version 0.12.1

Incremental release to address a bug found right after v0.12.0 was released.

• Fixes handling of Voltexceptionreport option
• DSS_ExtractSchema: include property descriptions, if loaded.
• Examples: add a simple OpenMP example in C using DSSContexts

Original announcement for v0.12.0 follows.

---

DSS C-API is a library that exposes a plain C API for an unofficial implementation of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using OpenDSS on Windows, Linux and macOS with compatible behavior across multiple processor architectures. It is the lower level API used by the other projects in DSS Extensions: DSS Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings) and DSS MATLAB.

See the changelog for a complete list of changes since 0.10.0.
See also the updated "Known Differences" document, which lists the main differences between the DSS C-API codebase and the main/official OpenDSS.

The downstream projects will be updated following this release, and a new repository for general documentation and collaboration was created at https://github.com/dss-extensions/dss-extensions

This is a long-delayed upgrade that enhances several aspects of this implementation of the OpenDSS engine. Users can now expect more regular and prompt updates.

Changes since 0.10.7

Includes porting of most official OpenDSS features up to revision 3460. Check the OpenDSS SVN commits for details.

This version still maintains basic compatibility with the 0.10.x series of releases, but there are many important changes. Version 0.13 will break API and ABI compatibility since function signatures and datatypes will be extensively adjusted. Still, if you use DSS C-API through one of the projects from DSS Extensions, we expect that your code will require few or no changes.

• The binary releases now use Free Pascal 3.2.2.

• The library name was changed from dss_capi_v7 to dss_capi. The codebase was cleaned up and reorganized.

• The code was finally unified, merging remaining features from OpenDSS v8+ (with few exceptions). Most of the DSS PM commands and functions were enabled. To achieve this, most of the global variables from the OpenDSS engine were encapsulated in a new class, a DSS Context class. Multi-threaded features are based on DSSContexts, both the original OpenDSS PM features and new extensions.

• Using DSS Contexts, user threads are now possible.

• Initial ARM64/AARCH64 support added. ARM32 building scripts were also added. Support includes Apple M1 support, including parallel/multi-threading features.

• Finally use KLUSolveX (our KLUSolve fork, rewritten and extended), enabling incremental Y updates for transformers and capacitor banks. Documentation including usage notes and limitations still not written. This was planned for version v0.13, but moved back to v0.12 to enable ARM32 (armv7l) support and better results in ARM64 (aarch64).

• Experimental callbacks for plotting and message output. Expect initial support in Python soon after DSS C-API v0.12 is released.

• Introduce AllowChangeDir mechanism: defaults to enabled state for backwards compatibility. When disabled, the engine will not change the current working directory in any situation. This is exposed through a new pair of functions
  DSS_Set_AllowChangeDir and DSS_Get_AllowChangeDir, besides the environment variable DSS_CAPI_ALLOW_CHANGE_DIR.

• New setting to toggle DOScmd command. Can be controlled through the environment variable DSS_CAPI_ALLOW_DOSCMD or functions DSS_Get_AllowDOScmd/DSS_Set_AllowDOScmd.

• Use OutputDirectory more. OutputDirectory is set to the current DataPath if DataPath is writable. If not, it's set to a general location (%LOCALAPPDATA%/dss-extensions and /tmp/dss-extensions since this release). This should make life easier for a user running files from a read-only location. Note that this is only an issue when running a compile command. If the user only uses redirect commands, the DataPath and OutputDirectory are left empty, meaning the files are written to the current working directory (CWD), which the user can control through the programming language driving DSS C-API. Note that the official OpenDSS COM behavior is different, since it loads the DataPath saved in the registry and modifies the CWD accordingly when OpenDSS is initialized.

• File IO rewritten to drop deprecated Pascal functions and features. This removes some limitations related to long paths due to the legacy implementation being limited to 255 chars.

• Reworked TPowerTerminal to achieve better memory layout. This makes simulations running LoadsTerminalCheck=false and LoadsTerminalCheck=true closer in performance, yet disabling the check is still faster.

• Use TFPHashList where possible (replacing the custom, original THashList implementation from OpenDSS).

• New LoadShape functions and internals:

  • Port memory-mapped files from the official OpenDSS, used when MemoryMapping=Yes from a DSS script while creating a LoadShape object.
  • Release the LoadShape_Set_Points function, which can be used for faster LoadShape input, memory-mapping externally, shared memory, chunked input, etc.

• Some new functions:

  • Circuit_Get_ElementLosses
  • CktElement_Get_NodeRef

• DSS_Get_COMErrorResults/DSS_Set_COMErrorResults: New compatibility setting for error/empty result. If enabled, in case of errors or empty arrays, the API returns arrays with values compatible with the official OpenDSS COM interface.

  For example, consider the function Loads_Get_ZIPV. If there is no active circuit or active load element:

  • In the disabled state (COMErrorResults=False), the function will return "[]", an array with 0 elements.
  • In the enabled state (COMErrorResults=True), the function will return "[0.0]" instead. This should
    be compatible with the return value of the official COM interface.

  Defaults to True/1 (enabled state) in the v0.12.x series. This will change to false in future series.

  This can also be set through the environment variable DSS_CAPI_COM_DEFAULTS. Setting it to 0 disables
  the legacy/COM behavior. The value can be toggled through the API at any time.

• Drop function aliases: previously deprecated function aliases (LoadShapes_Set_Sinterval and LoadShapes_Get_sInterval) were removed to simplify the build process. Use LoadShapes_Set_SInterval and LoadShapes_Get_SInterval instead.

• Monitor headers: From the official OpenDSS, since May 2021, the monitor binary stream doesn't include the header anymore. When porting the change to DSS Extensions, we took the opportunity to rewrite the related code, simplifying it. As such, the implementation in DSS Extensions deviates from the official one. Extra blank chars are not included, and fields should be more consistent. As a recommendation, if your code needs to be compatible with both implementations, trimming the fields should be enough.

• Error messages: most messages are now more specific and, if running a DSS script from files, include the file names and line numbers.

• Spectrum: To reduce overhead during object edits, now required to exist before the object that uses it. This is consistent with most of the other types in OpenDSS.

• New object and batch APIs for direct manipulation of DSS objects and batches of objects

• New experimental API for loading scripts/data from ZIP files

• New convenience functions to bulk load commands from the API

• User-models: headers updated, and removed support for user-models in LegacyModels mode. LegacyModels will be removed in v0.13.

• New functions to export the DSS properties of objects as JSON-encoded strings

• The C headers for our library were updated to include the const modifier for various of the parameters. A few function declarations were fixed.

• Initial batch of i18n changes. The property and command descriptions are now provided in an external gettext catalog, allowing us to easily replace them (initial file contained in messages.zip)

Due to the high number of IO changes, we recommend checking the performance before and after the upgrade to ensure your use case is not affected negatively. If issues are found, please do report.

The changelog for version 0.12.0 will be updated if we notice missing items.

See also dss-extensions/dss_capi#109

Full Git Changelog: dss-extensions/dss_capi@0.10.7-1...0.12.1

OpenDSSDirect.py v0.6.1

OpenDSSDirect.py version 0.6.1 upgrades to DSS_Python 0.10.7-1. The only difference from version 0.6.0 is that DSS_Python 0.10.7-1 corrects an issue with energy meter reports. If you don't use the reports, you don't need to upgrade to this version from 0.6.0.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

We are also testing a conda package. You can use our dss-extensions channel, e.g. conda install -c dss-extensions opendssdirect.py=0.6.1.

As OpenDSSDirect.py accumulates changes from DSS_Python (all ported to OpenDSSDirect.py), DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes.

Changes from DSS_Python 0.10.7-1

• Correct issue with energy meter reports.

Changes from DSS_Python 0.10.7

DSS_Python is the project that focuses on providing an interface, at Python level, that can be used as a drop-in replacement for the official OpenDSS COM interface. Users can combine both OpenDSSDirect.py and DSS_Python in the same application, sharing the same OpenDSS engine.

• Maintenance release.
• Updated to DSS C-API 0.10.7, which includes most changes up to OpenDSS v9.1.3.4.
• Includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or 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: Bus.AllPCEatBus, Bus.AllPDEatBus, CktElement.TotalPowers, Meters.ZonePCE

Changes from DSS C-API 0.10.7

• Simple maintenance release, which includes most changes up to OpenDSS v9.1.3.4 (revision 2963).
• Includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or GMRac=... diam=... (in this order and without specifying CapRadius), you should upgrade and re-evaluate the results.
• This version should be fully API compatible with 0.10.3+.
• A reference document listing the DSS commands and properties for all DSS elements is now available at https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/dss_properties.md
• New functions API ported from the official OpenDSS include: Bus_Get_AllPCEatBus, Bus_Get_AllPDEatBus, CktElement_Get_TotalPowers, Meters_Get_ZonePCE.
• The changes ported from the official OpenDSS include the following (check the repository for more details):
  • "Adds LineType property to LineCode and LineGeometry objects."
  • "Correcting bug found in storage device when operating in idling mode. It was preventing the solution of other test feeders (IEEE 9500)"
  • "Enabling fuel option for generator, fixing bug found in TotalPower command."
  • "Adding kvar compensation calculation for normalizing reactive power at feeder head. v 9.1.2.4"
  • "Adding: - Line type variable to line definition. - AllPCEatBus and AllPDEatBus commands to the executive command set. - AllPCEatBus and AllPDEatBus commands to bus interface in COM/DLL. (...)"
  • "Adding capability to energy meter for getting the list of all PCE (shunt) within a zone. Interface "AllPCEatZone" for COM/DLL created."
  • "Fixing bug found when calculating voltage bases with large amount of numbers (large array)."

OpenDSSDirect.py v0.6.0

OpenDSSDirect.py version 0.6.0 upgrades to DSS_Python 0.10.7. The version was bumped to v0.6.0 to reflect that support for Python 2.7 was dropped (at the moment, you can still build DSS_Python from source for Python 2.7 if you need it) and Python 3.9 was added.

This release includes bugfixes and new features, among them:

• Bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or GMRac=... diam=... (in this order and without specifying CapRadius), you should upgrade and re-evaluate the results. The issue also affect the official OpenDSS package.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS_Python (all ported to OpenDSSDirect.py), DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes.

Changes from DSS_Python 0.10.7

DSS_Python is the project that focuses on providing an interface, at Python level, that can be used as a drop-in replacement for the official OpenDSS COM interface. Users can combine both OpenDSSDirect.py and DSS_Python in the same application, sharing the same OpenDSS engine.

• Maintenance release.
• Updated to DSS C-API 0.10.7, which includes most changes up to OpenDSS v9.1.3.4.
• Includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or 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: Bus.AllPCEatBus, Bus.AllPDEatBus, CktElement.TotalPowers, Meters.ZonePCE

Changes from DSS C-API 0.10.7

• Simple maintenance release, which includes most changes up to OpenDSS v9.1.3.4 (revision 2963).
• Includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or GMRac=... diam=... (in this order and without specifying CapRadius), you should upgrade and re-evaluate the results.
• This version should be fully API compatible with 0.10.3+.
• A reference document listing the DSS commands and properties for all DSS elements is now available at https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/dss_properties.md
• New functions API ported from the official OpenDSS include: Bus_Get_AllPCEatBus, Bus_Get_AllPDEatBus, CktElement_Get_TotalPowers, Meters_Get_ZonePCE.
• The changes ported from the official OpenDSS include the following (check the repository for more details):
  • "Adds LineType property to LineCode and LineGeometry objects."
  • "Correcting bug found in storage device when operating in idling mode. It was preventing the solution of other test feeders (IEEE 9500)"
  • "Enabling fuel option for generator, fixing bug found in TotalPower command."
  • "Adding kvar compensation calculation for normalizing reactive power at feeder head. v 9.1.2.4"
  • "Adding: - Line type variable to line definition. - AllPCEatBus and AllPDEatBus commands to the executive command set. - AllPCEatBus and AllPDEatBus commands to bus interface in COM/DLL. (...)"
  • "Adding capability to energy meter for getting the list of all PCE (shunt) within a zone. Interface "AllPCEatZone" for COM/DLL created."
  • "Fixing bug found when calculating voltage bases with large amount of numbers (large array)."

OpenDSSDirect.py v0.5.0

OpenDSSDirect.py version 0.5.0 upgrades to DSS_Python 0.10.6. The version was bumped to v0.5.0 to reflect changes with the default behavior.

With this set of releases from the DSS Extensions project, most API calls are checked, avoiding surprising/confusing messages when the errors are not handled immediately. In OpenDSSDirect.py, the error messages provided in the OpenDSS Error interface are automatically mapped to Python exceptions and should now provide a better context for the errors.

Two new important compatibility settings are introduced:

• opendssdirect.Error.ExtendedErrors (defaults to enabled state): this new mechanism provides more error messages from the validation checks at the API level. You can disable the new messages, falling back to the previous behavior, using opendssdirect.Error.ExtendedErrors(False).
• opendssdirect.Basic.LegacyModels (defaults to disabled state): in OpenDSS v9.0, the old PVSystem, Storage, ... models were deprecated and removed from the official release. In ODD.py, you can toggle the old models using opendssdirect.Basic.LegacyModels(True). The current/new models, previously known as PVSystem2, Storage2, ... have been validated with the official tests and enabled by default.

OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html

As OpenDSSDirect.py accumulates changes from DSS_Python (all ported to OpenDSSDirect.py), DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes.

Changes from DSS_Python 0.10.6

DSS_Python is the project that focuses on providing an interface, at Python level, that can be used as a drop-in replacement for the official OpenDSS COM interface. Users can combine both OpenDSSDirect.py and DSS_Python in the same application, sharing the same OpenDSS engine.

• Updated to DSS C-API 0.10.6, which includes most changes up to OpenDSS v9.0.0.3.
• Debug builds of DSS C-API are now included. See the Debugging document.
• New DSS.LegacyModels: allow using the legacy/deprecated models for PVsystem, Storage, InvControl, and StorageController.
• New DSS.Error.ExtendedErrors: controls if the new extended error messages are used.
• Many new properties and functions in DSS.ActiveCircuit.PDElements.
• Now most of the low-level API calls are checked, mapping the errors from the DSS.Error interface to Python exceptions more frequently.

Changes from DSS C-API 0.10.6

DSS C-API is the low-level, extended OpenDSS library used in the DSS Extensions project. It provides a plain C interface, easily used by many programming languages.

• This version should be fully API compatible with 0.10.3+. The behavior of some functions changed with the new extensions. Especially, empty strings are explicitly return as nulls instead of "\0". This conforms to the behavior already seen in arrays of strings.
• The binary releases now use Free Pascal 3.2.0. We observed the solution process is around 6% faster, and results are even closer to the official OpenDSS.
• The releases now include both the optimized/default binary and a non-optimized/debug version. See the Debugging document for more.
• Extended API validation and Extended Errors mechanism:
  • The whole API was reviewed to add basic checks for active circuit and element access.
  • By default, invalid accesses now result in errors reported through the Error interface. This can be disabled to achieve the previous behavior, more compatible with the official COM implementation -- that is, ignore the error, just return a default/invalid value and assume the user has handled it.
  • The mechanism can be toggled by API functions DSS_Set_ExtendedErrors and DSS_Get_ExtendedErrors, or environment variable DSS_CAPI_EXTENDED_ERRORS=0 to disable (defaults to enabled state).
• New Legacy Models mechanism:
  • OpenDSS 9.0+ dropped the old PVsystem, Storage, InvControl, and StorageController models, replacing with the new versions previously known as PVsystem2, Storage2, InvControl2 and StorageController2.
  • The behavior and parameters from the new models are different -- they are better, more complete and versatile models. Check the official OpenDSS docs and examples for further information.
  • The implementation of the new models in DSS C-API was validated successfully with all test cases available. As such, we mirror the decision to make them the default models.
  • As an extension, we implemented the Legacy Models option. By toggling it, a clear command will be issued and the alternative models will be loaded. This should allow users to migrate to the new version but, if something that used to work with the old models stopped working somehow, the user can toggle the old models. The idea is to keep reproducibility of results while we keep updating the engine and the API.
  • Since EPRI dropped/deprecated the old models, we might drop them too, in a future release. Please open an issue on GitHub or send a message if those old models are important to you.
  • The mechanism can be controlled by API functions DSS_Set_LegacyModels and DSS_Get_LegacyModels, or environment variable DSS_CAPI_LEGACY_MODELS=1 to enable (defaults to disabled state).
• WireData API: expose the CapRadius property as a new pair of functions.
• PDElements API: extended with many batch functions exposing equivalents to some CSV reports: AllNames, AllMaxCurrents, AllPctNorm, AllPctEmerg, AllCurrents, AllCurrentsMagAng, AllCplxSeqCurrents, AllSeqCurrents, AllPowers, AllSeqPowers, AllNumPhases, AllNumConductors, AllNumTerminals.
• CktElement_Get_SeqPowers: fix issue for positive sequence circuits (wrong results could corrupt memory).
• Many API functions were optimized to avoid unnecessary allocations and copies.
• Some bugs found in DSS C-API and also reported upstream (already fixed in SVN):
  • CapRadius DSS property: if the radius was initialized using GMRac, CapRadius was left uninitialized, resulting in invalid/NaN values.
  • Sensors API: some functions edited capacitors instead of sensors.
• Updated to the official OpenDSS revision 2903, corresponding to versions 9.0.0+. Changes include:
  • ExportCIMXML: updated.
  • Relay: Fix in GetPropertyValue.
  • Line: In DumpProperties and MakePosSequence, the length is handled differently for lines with LineGeometry or LineSpacing.
  • Bus API: new LineList, LoadList functions.
  • Lines API: SeasonRating now returns NormAmps if there's no SeasonSignal.
  • New command DSS Zsc012: "Returns symmetrical component short circuit impedances Z0, Z1, and Z2 for the ACTIVE 3-PHASE BUS. Determined from Zsc matrix."
  • PVsystem2, Storage2, InvControl2, StorageController2 updated and renamed.