DSS Sharp 0.14.4

This is the same as 0.14.3, but adds some missing enum flags in DSSCompatFlags, especially for DSSCompatFlags.ActiveLine. Read below in the changelog for the importance of this flag -- if you relied on the Lines interface always using the current ActiveCktElement, you need to use this flag to keep the old behavior.

---

Version 0.14.4 upgrades the engine to AltDSS/DSS C-API 0.14.3. There are few bugfixes. This version tracks OpenDSS v9.8.0.1, released on 2024-01-31. Read below for the list of changes.

In 0.14.x, new features at C# level include experimental whole circuit save/load using JSON-encoded strings, and a new circuit Save function that allows customization of the saved data.

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
The package contains the required native binaries and should handle copying the DLLs to the output folders correctly for most common scenarios.
Integrating the whole project (.csproj) into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

❓ What's this?

DSS Sharp is a member of DSS-Extensions, a family of multi-platform language bindings based on the AltDSS/DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl. New projects include AltDSS-Rust and AltDSS-Go. A new style of API, with more modern and hopefully simpler approach, is being developed on AltDSS-Python -- the lessons learned from that project will reflect in the final design of the new API implementation for the other languages.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ AltDSS/DSS C-API Version 0.14.x

Changes from 0.14.1 to 0.14.3

• Header/Alt: fix dss_obj_float64_int32_func_t (returns double, not int32_t).
• Header: add enums for (state) variables for several components (Generator, IndMach012, PVSystem, Storage, UPFC, VCCS).
• API/YMatrix: check for valid circuit in a few more functions.
• API/Circuit: adjust SetActiveElement to be more conformant with the official version, i.e., returns -1 for non-circuit elements.
• API/CircuitElement: in the classic API, call the Alt implementations for Open/Close/IsOpen to reduce code duplication.
• Alt/CircuitElement:
  • Fix error message
  • Fix logic for DisplayName
  • Fix 13+ old bug in Open/Close/IsOpen -- the terminal parameters was being effectively ignored, applying the operations to the active terminal; also add check for valid terminal index.
• API/Capacitors: fix Close (same issue as CE).
• API/Batch:
  • Implement BatchOperation_Divide; needed for integers, and could be slightly better for floats, even though it's a tiny bit slower in modern processors.
  • Generalize Batch_SetFloat64Array/Batch_SetIn32Array to Batch_Float64Array/Batch_In32Array. This allows dropping the basic batch operations to the engine for array values, and allow for future optimizations in C++. In the current Pascal codebase, this is still better than running the operations on user-side due to memory layout and potential extra memory allocations when running on user-side.
  • Add Batch_CreateByFloat64PropertyRange to allow creating batches based on the value of a float64 property.
  • Add Batch_FilterByFloat64PropertyRange and Batch_FilterByInt32Property to allow filtering existing batches into new batches.
  • Make sure to zero all elements in intermediate buffers to avoid potential issues, especially with disabled elements grabbing values from the previous element.

Full Git Changelog: dss-extensions/dss_capi@0.14.1...0.14.3

Changes from 0.13.4 to 0.14.1

Long list, click to expand

Starting on this version, we will call DSS C-API and related projects AltDSS, an alternative implementation of OpenDSS, to make it more clear that this is not supported by EPRI and many extra features are not present in the official OpenDSS. Watch the DSS-Extensions org on GitHub for more announcements soon, including some support for the official implementation (still Windows-only at the moment). The name change **does not** mean compatibility or other aspects are expected to change, the project will still follow the basic guidelines of compatibility that have been followed since 2018.

This version should match OpenDSS v9.8.0.1 (SVN r3723). Remember to check the compatibility flags and Known differences.

• Another large internal (Pascal) code refactoring step and general clean-up. Check the commits for details, too many to list. A last step is under progress and will be merged in the next major release.

• Capitalization of property names adjusted! A first pass was done to try to make the property names more uniform. Since OpenDSS is case insensitive, we are free to change the capitalization as we see fit. In the past, the official OpenDSS already changed some property names, so a general suggestion for users that process the property names is to transform the names to upper or lower cases before comparing. This should ensure better stability across past and future versions of both DSS-Extensions and the official OpenDSS. For code that do not check the names in a case insensitive approach, DSS C-API 0.14.0 provides a function to adjust the property names (Settings_SetPropertyNameStyle), allowing the user to choose between three alternatives: the "Modern" version with adjusted capitalization; "Lowercase" names; and "Legacy" names. "Legacy" names can be used to avoid updating the names.

• Introduces a preview of JSON schema (new), JSON export (updated) and import (new). Too many details to include in the changelog. Includes many updates to the internal metadata. A separate project will be posted at https://github.com/dss-extensions/AltDSS-Schema and community feedback is welcome. Note: the JSON schema will be used for projects and features beyond JSON IO.

• Introduced options and improve correctness for save circuit. During the testing of the JSON dump, issues were fixed when saving Line, LineGeometry, Transformer, AutoTrans, XfmrCode. The issues vary from simple omissions to invalid exported DSS code. The property tracking feature below also helps generating clear and valid DSS scripts from save circuit, eliminating properties invalidated when changing some component definitions. To allow easier control of the save function without modifying the DSS language, a new Save function was added to the circuit API (Circuit_Save), coupled with the new DSSSaveFlags enumeration, which contains the option flags. This function also allows exporting the whole circuit as a single string.

• Introduce property tracking. Setting some properties now mark conflicting property definitions as unset. This affects some functionality for saving circuits and is also used for the JSON schema, for instance. An example: a user creates a load with kW=10 kvar=0. Later, the user updates the load, setting PF=0.9. Setting the power factor toggles the load internal state to use kW and PF as the load definition, but kvar is still marked as set. The DSS engine correctly tracks the order that properties were defined, so everything works as expected. Now, with the growing usage of DSS implementation to export the circuit, every single user is required to correctly implement this tracking if they want to ensure compatibility. That is, dumping the data from this example generator in an unordered dictionary/map/etc. for processing and later dumping back to DSS scripts will result in the wrong model.

  • Users can, of course, still query the value of all properties.
  • See also NoPropertyTracking compat flag.
  • Currently implemented, at least partially, in the following DSS classes (plus Lines and Loads API): LineCode, LineGeometry, LoadShape, Generator, Load, PVSystem, Storage, VSource, Fault, Line, Reactor, Transformer.
  • This functionally may be extended to other classes in future versions, if required.

• Introduce "Setter" flags. These are flags used to tweak...

DSS Sharp 0.14.3

Version 0.14.3 upgrades the engine to AltDSS/DSS C-API 0.14.3. There are few bugfixes. This version tracks OpenDSS v9.8.0.1, released on 2024-01-31. Read below for the list of changes.

In 0.14.x, new features at C# level include experimental whole circuit save/load using JSON-encoded strings, and a new circuit Save function that allows customization of the saved data.

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
The package contains the required native binaries and should handle copying the DLLs to the output folders correctly for most common scenarios.
Integrating the whole project (.csproj) into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

❓ What's this?

DSS Sharp is a member of DSS-Extensions, a family of multi-platform language bindings based on the AltDSS/DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl. New projects include AltDSS-Rust and AltDSS-Go. A new style of API, with more modern and hopefully simpler approach, is being developed on AltDSS-Python -- the lessons learned from that project will reflect in the final design of the new API implementation for the other languages.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ AltDSS/DSS C-API Version 0.14.x

Changes from 0.14.1 to 0.14.3

• Header/Alt: fix dss_obj_float64_int32_func_t (returns double, not int32_t).
• Header: add enums for (state) variables for several components (Generator, IndMach012, PVSystem, Storage, UPFC, VCCS).
• API/YMatrix: check for valid circuit in a few more functions.
• API/Circuit: adjust SetActiveElement to be more conformant with the official version, i.e., returns -1 for non-circuit elements.
• API/CircuitElement: in the classic API, call the Alt implementations for Open/Close/IsOpen to reduce code duplication.
• Alt/CircuitElement:
  • Fix error message
  • Fix logic for DisplayName
  • Fix 13+ old bug in Open/Close/IsOpen -- the terminal parameters was being effectively ignored, applying the operations to the active terminal; also add check for valid terminal index.
• API/Capacitors: fix Close (same issue as CE).
• API/Batch:
  • Implement BatchOperation_Divide; needed for integers, and could be slightly better for floats, even though it's a tiny bit slower in modern processors.
  • Generalize Batch_SetFloat64Array/Batch_SetIn32Array to Batch_Float64Array/Batch_In32Array. This allows dropping the basic batch operations to the engine for array values, and allow for future optimizations in C++. In the current Pascal codebase, this is still better than running the operations on user-side due to memory layout and potential extra memory allocations when running on user-side.
  • Add Batch_CreateByFloat64PropertyRange to allow creating batches based on the value of a float64 property.
  • Add Batch_FilterByFloat64PropertyRange and Batch_FilterByInt32Property to allow filtering existing batches into new batches.
  • Make sure to zero all elements in intermediate buffers to avoid potential issues, especially with disabled elements grabbing values from the previous element.

Full Git Changelog: dss-extensions/dss_capi@0.14.1...0.14.3

Changes from 0.13.4 to 0.14.1

Long list, click to expand

Starting on this version, we will call DSS C-API and related projects AltDSS, an alternative implementation of OpenDSS, to make it more clear that this is not supported by EPRI and many extra features are not present in the official OpenDSS. Watch the DSS-Extensions org on GitHub for more announcements soon, including some support for the official implementation (still Windows-only at the moment). The name change **does not** mean compatibility or other aspects are expected to change, the project will still follow the basic guidelines of compatibility that have been followed since 2018.

This version should match OpenDSS v9.8.0.1 (SVN r3723). Remember to check the compatibility flags and Known differences.

• Another large internal (Pascal) code refactoring step and general clean-up. Check the commits for details, too many to list. A last step is under progress and will be merged in the next major release.

• Capitalization of property names adjusted! A first pass was done to try to make the property names more uniform. Since OpenDSS is case insensitive, we are free to change the capitalization as we see fit. In the past, the official OpenDSS already changed some property names, so a general suggestion for users that process the property names is to transform the names to upper or lower cases before comparing. This should ensure better stability across past and future versions of both DSS-Extensions and the official OpenDSS. For code that do not check the names in a case insensitive approach, DSS C-API 0.14.0 provides a function to adjust the property names (Settings_SetPropertyNameStyle), allowing the user to choose between three alternatives: the "Modern" version with adjusted capitalization; "Lowercase" names; and "Legacy" names. "Legacy" names can be used to avoid updating the names.

• Introduces a preview of JSON schema (new), JSON export (updated) and import (new). Too many details to include in the changelog. Includes many updates to the internal metadata. A separate project will be posted at https://github.com/dss-extensions/AltDSS-Schema and community feedback is welcome. Note: the JSON schema will be used for projects and features beyond JSON IO.

• Introduced options and improve correctness for save circuit. During the testing of the JSON dump, issues were fixed when saving Line, LineGeometry, Transformer, AutoTrans, XfmrCode. The issues vary from simple omissions to invalid exported DSS code. The property tracking feature below also helps generating clear and valid DSS scripts from save circuit, eliminating properties invalidated when changing some component definitions. To allow easier control of the save function without modifying the DSS language, a new Save function was added to the circuit API (Circuit_Save), coupled with the new DSSSaveFlags enumeration, which contains the option flags. This function also allows exporting the whole circuit as a single string.

• Introduce property tracking. Setting some properties now mark conflicting property definitions as unset. This affects some functionality for saving circuits and is also used for the JSON schema, for instance. An example: a user creates a load with kW=10 kvar=0. Later, the user updates the load, setting PF=0.9. Setting the power factor toggles the load internal state to use kW and PF as the load definition, but kvar is still marked as set. The DSS engine correctly tracks the order that properties were defined, so everything works as expected. Now, with the growing usage of DSS implementation to export the circuit, every single user is required to correctly implement this tracking if they want to ensure compatibility. That is, dumping the data from this example generator in an unordered dictionary/map/etc. for processing and later dumping back to DSS scripts will result in the wrong model.

  • Users can, of course, still query the value of all properties.
  • See also NoPropertyTracking compat flag.
  • Currently implemented, at least partially, in the following DSS classes (plus Lines and Loads API): LineCode, LineGeometry, LoadShape, Generator, Load, PVSystem, Storage, VSource, Fault, Line, Reactor, Transformer.
  • This functionally may be extended to other classes in future versions, if required.

• Introduce "Setter" flags. These are flags used to tweak how the property update is done. Notably,AvoidFullRecalc (some other flags are only using by the engine, internally): some specific properties like Load.kW can be updated both directly through a DSS script (or Text interface), or through the dedicated Loads API in any of the specific language bindings of the many APIs. The...

DSS Sharp 0.14.1

Version 0.14.1 upgrades the engine to AltDSS/DSS C-API 0.14.1. There are some important bugfixes, a few changes ported from the official OpenDSS, and a lot of new features in our engine. This version tracks OpenDSS v9.8.0.1, released on 2024-01-31 (read below for the list of changes).

New features at C# level include experimental whole circuit save/load using JSON-encoded strings, and a new circuit Save function that allows customization of the saved data.

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
The package contains the required native binaries and should handle copying the DLLs to the output folders correctly for most common scenarios.
Integrating the whole project (.csproj) into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

❓ What's this?

DSS Sharp is a member of DSS-Extensions, a family of multi-platform language bindings based on the AltDSS/DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl. New projects include AltDSS-Rust and AltDSS-Go. A new style of API, with more modern and hopefully simpler approach, is being developed on AltDSS-Python -- the lessons learned from that project will reflect in the final design of the new API implementation for the other languages.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ DSS C-API Version 0.14

Changes since 0.13.4

Long list, click to expand

Starting on this version, we will call DSS C-API and related projects AltDSS, an alternative implementation of OpenDSS, to make it more clear that this is not supported by EPRI and many extra features are not present in the official OpenDSS. Watch the DSS-Extensions org on GitHub for more announcements soon, including some support for the official implementation (still Windows-only at the moment). The name change **does not** mean compatibility or other aspects are expected to change, the project will still follow the basic guidelines of compatibility that have been followed since 2018.

This version should match OpenDSS v9.8.0.1 (SVN r3723). Remember to check the compatibility flags and Known differences.

• Another large internal (Pascal) code refactoring step and general clean-up. Check the commits for details, too many to list. A last step is under progress and will be merged in the next major release.

• Capitalization of property names adjusted! A first pass was done to try to make the property names more uniform. Since OpenDSS is case insensitive, we are free to change the capitalization as we see fit. In the past, the official OpenDSS already changed some property names, so a general suggestion for users that process the property names is to transform the names to upper or lower cases before comparing. This should ensure better stability across past and future versions of both DSS-Extensions and the official OpenDSS. For code that do not check the names in a case insensitive approach, DSS C-API 0.14.0 provides a function to adjust the property names (Settings_SetPropertyNameStyle), allowing the user to choose between three alternatives: the "Modern" version with adjusted capitalization; "Lowercase" names; and "Legacy" names. "Legacy" names can be used to avoid updating the names.

• Introduces a preview of JSON schema (new), JSON export (updated) and import (new). Too many details to include in the changelog. Includes many updates to the internal metadata. A separate project will be posted at https://github.com/dss-extensions/AltDSS-Schema and community feedback is welcome. Note: the JSON schema will be used for projects and features beyond JSON IO.

• Introduced options and improve correctness for save circuit. During the testing of the JSON dump, issues were fixed when saving Line, LineGeometry, Transformer, AutoTrans, XfmrCode. The issues vary from simple omissions to invalid exported DSS code. The property tracking feature below also helps generating clear and valid DSS scripts from save circuit, eliminating properties invalidated when changing some component definitions. To allow easier control of the save function without modifying the DSS language, a new Save function was added to the circuit API (Circuit_Save), coupled with the new DSSSaveFlags enumeration, which contains the option flags. This function also allows exporting the whole circuit as a single string.

• Introduce property tracking. Setting some properties now mark conflicting property definitions as unset. This affects some functionality for saving circuits and is also used for the JSON schema, for instance. An example: a user creates a load with kW=10 kvar=0. Later, the user updates the load, setting PF=0.9. Setting the power factor toggles the load internal state to use kW and PF as the load definition, but kvar is still marked as set. The DSS engine correctly tracks the order that properties were defined, so everything works as expected. Now, with the growing usage of DSS implementation to export the circuit, every single user is required to correctly implement this tracking if they want to ensure compatibility. That is, dumping the data from this example generator in an unordered dictionary/map/etc. for processing and later dumping back to DSS scripts will result in the wrong model.

  • Users can, of course, still query the value of all properties.
  • See also NoPropertyTracking compat flag.
  • Currently implemented, at least partially, in the following DSS classes (plus Lines and Loads API): LineCode, LineGeometry, LoadShape, Generator, Load, PVSystem, Storage, VSource, Fault, Line, Reactor, Transformer.
  • This functionally may be extended to other classes in future versions, if required.

• Introduce "Setter" flags. These are flags used to tweak how the property update is done. Notably,AvoidFullRecalc (some other flags are only using by the engine, internally): some specific properties like Load.kW can be updated both directly through a DSS script (or Text interface), or through the dedicated Loads API in any of the specific language bindings of the many APIs. The dedicated API does not force a YPrim update and full load model recalculation.

  • When using this flag AvoidFullRecalc in the Obj/Batch APIs, the behavior will follow the dedicated Loads API.
  • Other flags include ImplicitSizes and AllowAllConductors. Both are currently used for enabling some of the JSON Schema functionally.
  • For batch operations, SkipNA was introduced to allow handling scenarios with non-uniform data.
  • The relevant API functions were updated to include an extra function argument with the setter flags.
  • Is this AvoidFullRecalc the same as SkipSideEffects compat flag? No. AvoidFullRecalc is still valid and by design (including some behavior listed in OpenDSS docs), whereas SkipSideEffects is potentially unintended behavior.

• New compatibility flags in DSSCompatFlags:

  • ActiveLine (0x10). In the official OpenDSS implementation, the Lines API use the active circuit element instead of the active line. This can lead to unexpected behavior if the user is not aware of this detail. For example, if the user accidentally enables any other circuit element, the next time they use the Lines API, the line object that was previously enabled is overwritten with another unrelated object. This flag enables this behavior above if compatibility at this level is required. On DSS-Extensions, we changed the behavior to follow what most of the other APIs do: use the active object in the internal list, starting on version v0.14.0.
  • NoPropertyTracking (0x20): On DSS-Extensions/AltDSS, when setting a property invalidates a previous input value, the engine will try to mark the invalidated data as unset. This allows for better exports and tracking of the current state of DSS objects. Set this flag to disable this behavior, following the original OpenDSS implementation for potential compatibility with older software that may require th...

DSS Sharp v0.13.4

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

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
The package contains the required native binaries and should handle copying the DLLs to the output folders correctly for most common scenarios.
Integrating the whole project (.csproj) into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

❓ What's this?

DSS Sharp is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ 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.

DSS Sharp v0.13.3

Version 0.13.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.

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
The package contains the required native binaries and should handle copying the DLLs to the output folders correctly for most common scenarios.
Integrating the whole project (.csproj) into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

What's this?

DSS Sharp is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ DSS C-API 0.13.3 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.

DSS Sharp v0.13.2

Version 0.13.2 is a minor release. On the C# side, the comment strings were updated, as well as the DSSJSONFlags enum. Read below regarding engine changes.

The package is available as an attachment here, and from NuGet: https://www.nuget.org/packages/dss_sharp/
Integrating the whole project into an existing solution is also possible, but remember to download the native dependencies.

For an example of usage, see https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample

What's this?

DSS Sharp is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes an alternative/customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

⚙️ DSS C-API Version 0.13.2

Minor release.

• 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.
• 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 for notes and examples.

DSS Sharp v0.13.1

This new release upgrades to DSS C-API 0.13.1. Other changes specific to DSS Sharp are:

• The (multi-platform) NuGet package now handles better the native DLLs when targeting .NET Framework apps; it's available at https://www.nuget.org/packages/dss_sharp
• Added a simple WinForms example, including some notes, in https://github.com/dss-extensions/dss_sharp/tree/master/examples/WinFormsAppSample
• Expose the new C-API functions. See especially CompatFlags. More details in the DSS C-API notes below.
• New Error.UseExceptions: Previously, we forced the use of exceptions. Now users can easily toggle the behavior. The default will still be to use exceptions for the safety of new users, besides the added convenience. Usage: set engine.Error.UseExceptions = false to deactivate the automatic mapping. Other toggles as Error.EarlyAbort and CompatFlags should be enough to more closely match the logic of older programs using the official COM DLL even for the more lax usage of OpenDSS.
• Adjust many comments to include extra information and/or provide better IDE experience.

The docs at https://dss-extensions.org/dss_sharp/ still need to be updated. The XML help is included in the package and should complement it, for the time being.

Full Git Changelog: 0.12.1...0.13.1

What's this?

DSS Sharp is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes a customized implementation of the original EPRI's OpenDSS, with a custom API intended to replace and extend the functionality of the official COM object API, while also adding and improving some of the DSS engine internals. For other languages, check: DSS-Python, OpenDSSDirect.py, DSS MATLAB, and OpenDSSDirect.jl.

See more at https://dss-extensions.org/ and also our FAQ.

As with DSS-Python, this package tries to mimic the COM object structure to facilitate the transition and keep most of the existing code valid. The package is usually faster than the COM object for various tasks. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics.

Known differences and more

We maintain a list of important differences between the official COM implementation and DSS C-API at:

https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md

Credits / Acknowledgement

This project is derived from EPRI's OpenDSS and the same style of license (BSD style) is used. As OpenDSS, the project also depends on KLUSolve and SuiteSparse, licensed under the LGPL. The licenses are included in the installation packages.

See the DSS C-API project for more details and source files.

---

DSS C-API 0.13.x 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 dss-extensions/OpenDSSDirect.py#121
• Parser: properly error out when given excessive number of elements for matrices; implemented due to the report in dss-extensions/OpenDSSDirect.py#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 buggy, so we only ported now to remove the burden of porting this down the line. If you find issues, feel free to report here on DSS Extensions, but we recommended checking first with the official OpenDSS -- if the issue is also found in the official version, prefer to report in the official OpenDSS forum first so everyone gets the fixes and our implementation doesn't diverge too much.
  • CktElement/API: add a few new functions related to state variables.
  • Circuit, Line: port the LongLineCorrection flag now that it seems to be fixed upstream. Note that we didn't publish releases with the previous buggy version from the upstream OpenDSS (that applied the long-line correction for everything).
  • LineSpacing: port side-effect from upstream; changing nconds now reallocates and doesn't leak previously allocated memory. Not a common operation, so it's not very relevant.
  • CktElement: port code for handling losses in AutoTrans
• Other API updates:
  • DSSContext API: allow null pointer for the prime/default instance. This should ease the transition. Issue: dss-extensions/dss_capi#119
  • Error API: add Error_Set_Description to allow easier setting an error message from callbacks (this is for advanced usage)
  • Batch and Obj API:
    • For a couple of fast-path operations, add checks for edit state, automatically issuing BeginEdit and EndEdit for the objects in the batch.
    • Allow passing strings (object names) instead of pointers for object references
    • Automatically add new elements to the current DSSContext (since we have not yet published a manipulation API)
    • For symmetric matrices, if the user passes only the triangle, follow the same convention as the Text interface. Includes specific fix for (parts of) complex matrices (like the R or X matrices when internally Z is stored). If the user provides full matrices, the previous behavior was correct, no changes required.
  • Fuses_Reset: fix C header (remove extra/unused parameter)
  • Fuses_Get_State and Fuses_Get_NormalState: add missing string copy. Sometimes this could cause memory corruption.
  • Bus_Get_ZSC012Matrix: check for nulls
  • Bus_Get_AllPCEatBus, Bus_Get_AllPDEatBus: faster implementations
  • Meters_Get_CountBranches: reimplemented
  • Monitors_Get_dblHour: For harmonics solution, return empty array. Previously, it was returning a large array instead of a single element ([0]) array. A small issue adjusted for compatibility with the official COM API results.
  • Reactors_Set_Bus1: Match the side-effects of the property API for two-terminal reactors.
  • New DSS_Set_CompatFlags...

DSS Sharp v0.12.1

A new, rewritten DSS Sharp has been published. This released is based on the new DSS C-API, which itself had parts rewritten to achieve our goals. We plan to release a v1.0 package when all remaining features (notably diakoptics) are ported to DSS C-API.

The main changes include:

• NuGet package is now available: https://www.nuget.org/packages/dss_sharp
• Initial (WIP) HTML docs at https://dss-extensions.org/dss_sharp/
• Multi-platform support -- while still pending more testing (especially in the packaging aspects), besides Windows, Linux and macOS are also supported, including ARM.
• Use the new DSS Context API, available in DSS C-API 0.12. This enables users to create multiple DSS instances in the same process. For backwards compatibility, the static method dss_sharp.DSS.NewContext() is used to create new instances, while the default constructor is bound to the default/prime DSS instance.
• Allow using .NET std 2.1 (#if NETSTANDARD2_1_OR_GREATER) to use UTF8 conversion strings; default build is still .NET 4.5 -- users should restrict inputs to ASCII on that.
• Implement GR usage (less memory allocations). See https://github.com/dss-extensions/dss_capi/blob/0.12.1/docs/usage.md#global-result-gr-new-in-v0100
• Check for OpenDSS errors for most API calls, mapping them to DSSException.
• Add support for most of the API extensions (properties, toggles and full classes). https://github.com/dss-extensions/dss_capi/blob/0.12.1/docs/known_differences.md
• Update project file
• Drop CmathLib -- not really required in .NET.
• Several new classes, including support for the Parallel features of the official OpenDSS (we still recommend user-threads in C#), ZIP file support, extended error messages both in the API and when running scripts, and more.
• Include enums matching the COM implementation. Some of the annoyances were kept for compatibility only.

Pending potential bugs, the main objective of DSS Sharp (good compatibility with the official COM implementation) has been achieved.
We are considering a cleaner and more modern alternative. If you have comments or feature requests, please feel free to post a new issue or reach me via email (pmeira at ieee.org).

Since the amount of changes in DSS C-API was significant, we reproduce its release announcement below.

DSS C-API 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 du...

0.10.1a1

Updated version with the recent API changes (DSS C-API 0.10) and smalls complements per #2.

A proper release should be done in a few days if no major issues are found.