AltDSS/DSS C-API 0.14.6a1

Preview for testing Oddie in downstream projects.

Full Changelog: 0.14.5...0.14.6a1

AltDSS/DSS C-API 0.14.5

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions as well as https://dss-extensions.org/ for general recommendations, references and notes.

Changes since 0.14.4

Minor release with a bugfix:

• Address issue with the classic LineGeometries API. Instead of using the number of input conductors, the API was using the number of effective conductors if reduce=yes. That doesn't make sense since the original conductors are not modified, hence the original number of conductors is now used throughout this API.
• The C headers also were updated to add a few more const qualifiers.

Git Changelog: 0.14.4...0.14.5

Changes from 0.14.3 to 0.14.4

Minor release, relevant changes only in the Alt API, i.e. no need to upgrade if you don't use it.

• Alt/Obj, Batch: adjust checks for new elements. Refactored some other internal code to simplify this kind of check.
• Alt/Obj: Expose internal object flags.
• ReduceAlgs: Very minor code clean-up.
• Header: Where possible, use uint32_t for bit sets (flags, options).

Changes from 0.14.2 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.

Changes from 0.14.1 to 0.14.2

Minor release to address issues found in the Alt API. Besides Lines_Get_Parent, the other changes do not affect behavior of the classic API functions.

• Alt/Bus: fix Lines/Loads/PCElements/PDElements when multiple elements are present
• Alt/CE: Fix Alt_CE_Get_RegisterValues in the C header.
• Alt/PDE: Check for missing solution in a few functions.
• Commands/CalcLaplacian: Give proper error message instead of crashing or giving "access violation" messages.
• Circuit/API: check if there is a circuit in Circuit_Save.
• Lines/API: adjust behavior of Lines_Get_Parent when the compat flag is off.

Changes from 0.14.0 to 0.14.1

Minor release to address issues found through AltDSS-Python. These shouldn't affect software that use only the classic API.

• Alt_PCE: implement two missing functions
• DSSObj, LineGeometry: for the alternative API, add array shortcuts for Wire; use the array shortcuts more.
• SetterFlags_AllowAllConductors:
  • Update value of SetterFlags_AllowAllConductors to 0x40000000 to avoid difficulties in Python.
  • Propagate setting when using Obj/Batch APIs; adjust Line.Conductors.

Changes from 0.13.4 to 0.14.0

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

AltDSS/DSS C-API 0.14.4

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions as well as https://dss-extensions.org/ for general recommendations, references and notes.

Changes since 0.14.3

Minor release, relevant changes only in the Alt API, i.e. no need to upgrade if you don't use it.

• Alt/Obj, Batch: adjust checks for new elements. Refactored some other internal code to simplify this kind of check.
• Alt/Obj: Expose internal object flags.
• ReduceAlgs: Very minor code clean-up.
• Header: Where possible, use uint32_t for bit sets (flags, options).

Changes from 0.14.2 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.

Changes from 0.14.1 to 0.14.2

Minor release to address issues found in the Alt API. Besides Lines_Get_Parent, the other changes do not affect behavior of the classic API functions.

• Alt/Bus: fix Lines/Loads/PCElements/PDElements when multiple elements are present
• Alt/CE: Fix Alt_CE_Get_RegisterValues in the C header.
• Alt/PDE: Check for missing solution in a few functions.
• Commands/CalcLaplacian: Give proper error message instead of crashing or giving "access violation" messages.
• Circuit/API: check if there is a circuit in Circuit_Save.
• Lines/API: adjust behavior of Lines_Get_Parent when the compat flag is off.

Full Git Changelog: 0.14.1...0.14.2

Changes from 0.14.0 to 0.14.1

Minor release to address issues found through AltDSS-Python. These shouldn't affect software that use only the classic API.

• Alt_PCE: implement two missing functions
• DSSObj, LineGeometry: for the alternative API, add array shortcuts for Wire; use the array shortcuts more.
• SetterFlags_AllowAllConductors:
  • Update value of SetterFlags_AllowAllConductors to 0x40000000 to avoid difficulties in Python.
  • Propagate setting when using Obj/Batch APIs; adjust Line.Conductors.

Full Git Changelog: 0.14.0...0.14.2

Changes from 0.13.4 to 0.14.0

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

AltDSS/DSS C-API 0.14.3

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

All derived/downstream projects, including the documentation sites and dss.hpp headers, will be updated in the next hours/days to use this new engine.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions as well as https://dss-extensions.org/ for general recommendations, references and notes.

Changes since 0.14.2

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

Changes from 0.14.1 to 0.14.2

Minor release to address issues found in the Alt API. Besides Lines_Get_Parent, the other changes do not affect behavior of the classic API functions.

• Alt/Bus: fix Lines/Loads/PCElements/PDElements when multiple elements are present
• Alt/CE: Fix Alt_CE_Get_RegisterValues in the C header.
• Alt/PDE: Check for missing solution in a few functions.
• Commands/CalcLaplacian: Give proper error message instead of crashing or giving "access violation" messages.
• Circuit/API: check if there is a circuit in Circuit_Save.
• Lines/API: adjust behavior of Lines_Get_Parent when the compat flag is off.

Full Git Changelog: 0.14.1...0.14.2

Changes from 0.14.0 to 0.14.1

Minor release to address issues found through AltDSS-Python. These shouldn't affect software that use only the classic API.

• Alt_PCE: implement two missing functions
• DSSObj, LineGeometry: for the alternative API, add array shortcuts for Wire; use the array shortcuts more.
• SetterFlags_AllowAllConductors:
  • Update value of SetterFlags_AllowAllConductors to 0x40000000 to avoid difficulties in Python.
  • Propagate setting when using Obj/Batch APIs; adjust Line.Conductors.

Full Git Changelog: 0.14.0...0.14.2

Changes from 0.13.4 to 0.14.0

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

AltDSS/DSS C-API 0.14.2

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

All derived/downstream projects, including the documentation sites and dss.hpp headers, will be updated in the next hours/days to use this new engine.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions

Changes since 0.14.1

Minor release to address issues found in the Alt API. Besides Lines_Get_Parent, the other changes do not affect behavior of the classic API functions.

• Alt/Bus: fix Lines/Loads/PCElements/PDElements when multiple elements are present
• Alt/CE: Fix Alt_CE_Get_RegisterValues in the C header.
• Alt/PDE: Check for missing solution in a few functions.
• Commands/CalcLaplacian: Give proper error message instead of crashing or giving "access violation" messages.
• Circuit/API: check if there is a circuit in Circuit_Save.
• Lines/API: adjust behavior of Lines_Get_Parent when the compat flag is off.

Full Git Changelog: 0.14.1...0.14.2

Changes from 0.14.0 to 0.14.1

Minor release to address issues found through AltDSS-Python. These shouldn't affect software that use only the classic API.

• Alt_PCE: implement two missing functions
• DSSObj, LineGeometry: for the alternative API, add array shortcuts for Wire; use the array shortcuts more.
• SetterFlags_AllowAllConductors:
  • Update value of SetterFlags_AllowAllConductors to 0x40000000 to avoid difficulties in Python.
  • Propagate setting when using Obj/Batch APIs; adjust Line.Conductors.

Full Git Changelog: 0.14.0...0.14.2

Changes from 0.13.4 to 0.14.0

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 the original behavior; note that may lead to erroneous interpretation of the data in the DSS properties. This was introduced in DSS C-API v0.14.0 and will be further developed for future versions.
  • SkipSideEffects (0x40). Some specific functions on the official OpenDSS APIs and internal code skip important side-effects. By default, on DSS-Extensions/AltDSS, those side-effects are enabled. Use this flag
    to try to follow the behavior of the official APIs. Beware that some side-effects are
    important and skipping them m...

AltDSS/DSS C-API 0.14.1

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

All derived/downstream projects, including the documentation sites and dss.hpp headers, will be updated in the next hours/days to use this new engine.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions

Changes since 0.14.0

Minor release to address issues found through AltDSS-Python. These shouldn't affect software that use only the classic API.

• Alt_PCE: implement two missing functions
• DSSObj, LineGeometry: for the alternative API, add array shortcuts for Wire; use the array shortcuts more.
• SetterFlags_AllowAllConductors:
  • Update value of SetterFlags_AllowAllConductors to 0x40000000 to avoid difficulties in Python.
  • Propagate setting when using Obj/Batch APIs; adjust Line.Conductors.

Full Git Changelog: 0.14.0...0.14.1

Changes since 0.13.4

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 the original behavior; note that may lead to erroneous interpretation of the data in the DSS properties. This was introduced in DSS C-API v0.14.0 and will be further developed for future versions.
  • SkipSideEffects (0x40). Some specific functions on the official OpenDSS APIs and internal code skip important side-effects. By default, on DSS-Extensions/AltDSS, those side-effects are enabled. Use this flag
    to try to follow the behavior of the official APIs. Beware that some side-effects are
    important and skipping them may result in incorrect results.
    This flag affects some of the classic API functions (Loads, Generators, Vsources) as well as the behavior of some specific DSS properties (Line: Rg, Xg, rho; Transformer/AutoTrans: XSCArray).

• New Alt and Obj families of functions. A new family of functions was added to allow most legacy API operations and new functionality directly on objects and batches, instead of relying on "active..." idiom. A new package, AltDSS-Python, will be published to illustrate the new approach. Since the engine is shared, users can mix both approach (e.g. use AltDSS-Python and OpenDSSDirect.py in the same script).

• Batch/API:

  • Allow using batches with simple functions that return float64/int32 for each object....

AltDSS/DSS C-API 0.14.0

AltDSS/DSS C-API is a library that exposes a plain C API for an unofficial/alternative implementation/port of OpenDSS, the Distribution System Simulator from EPRI (the Electric Power Research Institute), aiming for full COM compatibility and beyond. It allows using most of the OpenDSS features 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: AltDSS-Python, DSS-Python, OpenDSSDirect.py, OpenDSSDirect.jl (Julia language), DSS# (.NET/C# bindings), DSS MATLAB, AltDSS-Rust, AltDSS-Go, and the dss.hpp C++ header-only library, besides third-party projects.

All derived/downstream projects, including the documentation sites and dss.hpp headers, will be updated in the next hours/days to use this new engine.

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

For a growing general repository about the projects, see https://github.com/dss-extensions/dss-extensions

Changes since 0.13.4

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 the original behavior; note that may lead to erroneous interpretation of the data in the DSS properties. This was introduced in DSS C-API v0.14.0 and will be further developed for future versions.
  • SkipSideEffects (0x40). Some specific functions on the official OpenDSS APIs and internal code skip important side-effects. By default, on DSS-Extensions/AltDSS, those side-effects are enabled. Use this flag
    to try to follow the behavior of the official APIs. Beware that some side-effects are
    important and skipping them may result in incorrect results.
    This flag affects some of the classic API functions (Loads, Generators, Vsources) as well as the behavior of some specific DSS properties (Line: Rg, Xg, rho; Transformer/AutoTrans: XSCArray).

• New Alt and Obj families of functions. A new family of functions was added to allow most legacy API operations and new functionality directly on objects and batches, instead of relying on "active..." idiom. A new package, AltDSS-Python, will be published to illustrate the new approach. Since the engine is shared, users can mix both approach (e.g. use AltDSS-Python and OpenDSSDirect.py in the same script).

• Batch/API:

  • Allow using batches with simple functions that return float64/int32 for each object.
  • Allow using INT32_MAX and NaN for missing values, which can be skipped with the SetterFlags_SkipNA flag. Sooner or later, there should a better alternative, but this can be useful in the time being.

• Headers:

  • Remove stdint_compat.h. This was only required for very old or non-standard compiler like MSVC 2008. Users that require that can still source the file from older releases or get similar files from other sources.
  • Include stddef.h when building as C code.
  • Mark CktElement_Get_IsIsolated with (API Extension)
  • Add more const qualifiers. Especially useful for t...

AltDSS/DSS C-API 0.14.0rc2

Check for null pointers in a few more places, avoiding crashes (mostl…

…y with new OpenDSS users)

AltDSS/DSS C-API 0.14.0rc1

Obj: use INT32_MAX for NA values

AltDSS/DSS C-API 0.14.0b3

For testing downstream projects, final steps.

Changelog at https://github.com/dss-extensions/dss_capi/blob/0.14.0b3/docs/changelog.md#version-0140
Since 0.14.0b2: 0.14.0b2...0.14.0b3
Since 0.14.0b1: 0.14.0b1...0.14.0b3

Full Git Changelog: 0.13.4...0.14.0b3