Skip to content

AltDSS/DSS C-API 0.14.1
Compare
Choose a tag to compare
@PMeira PMeira released this 17 Feb 01:58
· 47 commits to master since this release
0.14.1
8b3da5b

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.
    • 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 the new Rust and Golang bindings.

  • Specific bug fixes:

    • AutoTrans: fix DumpProperties, readd bank property (unused internally).
    • Commands/Save: add version and timestamp to master file.
    • DynamicExp and DynEqPCE: fix DumpProperties; extend to support JSON in/out.
    • Generator: fix default value for D (as DSS property); previously, the value was left uninitialized. It seems to only affect user models, so it doesn't seem like a big issue. Explicitly providing a value would also work fine as a workaround.
    • Line and LineCode: fix formatting issues in DumpProperties
    • LoadShape: fix some issues when copying/saving data when using float32 data (which users need to explicitly opt-in).
    • PriceShape/TempShape: adjust setters for mean/stddev properties
    • Relay: fix handling of DOC_PhaseCurveInner (DSS property)
    • Reactor: in some situations, R and X were not synched with Z. Fixed by removing the internal duplication (does not affect user code).
    • Sensor: DeltaDirection was not initialized; make clear an explicit action.
    • SwtControl: If no element is attached (misuse), set state as "none".
    • Transformers/API: Transformers_Get_LossesByType and Transformers_Get_AllLossesByType now check if the transformer is enabled.
    • API/general: avoid tiny memory leaks (pointer size, 8 bytes) on empty data and some error situations.
    • Bus/classic API: fix Bus_Get_N_interrupts; was previously returning the duration instead.
    • Circuit_Capacity (API, command): fix register index, remove magic numbers. (Bug introduced back in 2008!)
    • Circuit/API: fix Circuit_Enable and Circuit_Disable (enabling/disabling circuit elements by name). An equivalent fix is included in the official OpenDSS v9.7.1.1, in the COM interface. Additionally, provide error message when trying to use invalid element names.
    • Obj/Batch API: better handling of booleans. With this change, any non-zero value is interpreted as true, which simplifies integration with other programming languages. This was the original intention.
    • API/Iteration: Fix issues with iteration in a few of the internal functions which could have resulted in empty results in some situations. These situations occurred only during testing, so we don't expect many users were affected.

  • Misc:

    • Error handling: add a few numeric checks, and check for errors in more places during solution algorithms. The changes should help finding issues earlier and/or more easily.
    • Check for null pointers (usually missing circuit solution) in a few more places.
    • Properties/capitalization: adjust capitalization of nearly all property names. Use lowercase for description keys (help strings). Feedback on the capitalization is welcome. As a reminder, OpenDSS is case-insensitive, but other other are not. Providing a better internal representation of the properties will help other tools to use the internal names without extra work (no need for each tool to adjust capitalization), and it doesn't affect the DSS engine itself nor compatibility with the upstream OpenDSS.
    • Obj/API: introduce ExtraClassIDs to get some special lists.
    • Classic to Obj/Alt API bridge: add many *_Get_Pointer functions (e.g. CktElement_Get_Pointer, Loads_Get_Pointer). These functions return a pointer that can be used in the Obj API. This should enable an easier migration from the classic API, or allow users to use the Obj API to complement the classic API where the latter is lacking.
    • API/Callbacks: dss_callback_message_t function signature extended with two more arguments. We are not aware of any user using these, but if you are, remember to update your callbacks.
    • API/Extended errors: add a few more checks, and disable some error messages when extended errors are disabled. (Extended errors are extra error checks introduced to signal wrong usage of the DSS engine; extra = not present in the original/official codebase)
    • API/Text: microoptimize Text_CommandBlock for single commands. That is, users could use Text_CommandBlock for both single and multi-line strings without performance impacts. We did not replace Text_Set_Command in order to avoid potential compatibility issues.
    • API/Events: generalize the API for event extensions.
    • API/Obj: handle incorrect array sizes better, add error messages.

  • Ported from the official SVN:

    • r3637: "Removing force EventLog for StorageController to match all the other controls and their defaults." (by davismont)
    • r3640: "Updated "Show" fault study report to better arrange output. (...)" (by aovallev)
    • r3642: "Skipping disabled meters when interpolating all meters." (by celsorocha)
    • r3646: updates to TInvDynamicVars.CalcGFMYprim (by davismont)

Full Git Changelog: 0.13.4...0.14.1

Precompiled binaries

Most of the binaries available here are built through GitHub Actions, as are most of the development builds (you need to be logged in to be able to download dev builds). Linux ARM32 binaries will be added manually if there are any requests (please feel free to create a new issue on GitHub).

Users rarely need to build the Pascal binaries themselves, since there aren't many Free Pascal compiler flags that affect them. We do recommend building KLUSolveX optimized for your machines, especially for HPC clusters (since it's built as a shared library, you don't need to worry about Free Pascal).

Checksums

SHA256

f276a76146e3be6a1ee2ce3c6ac8d8631d60e631095ba82a4932f34c1f5cda6b  dss_capi_0.14.1_darwin_arm64.tar.gz
6df521076b336723b3b6b41ace9ab69b1dd03f4df7609a81eb23ac637789caad  dss_capi_0.14.1_darwin_x64.tar.gz
3aea6a4ed7f63b61271cd266f8cae8f683ef3619260d9587b79d81cdae9f47c5  dss_capi_0.14.1_linux_arm64.tar.gz
6caf2b31a298cef7093c0025ad4b1d5cb068829d95078e2d47ddebdbc89a8221  dss_capi_0.14.1_linux_x64.tar.gz
a9217c15c2f78a012b501e97b68436e6b4f0a057cb0323fa54941907fc8f4c77  dss_capi_0.14.1_linux_x86.tar.gz
254cb52a68108a82b2649195dc3d834fa8e04ac38648f5793eba90a2008c75e2  dss_capi_0.14.1_win_x64.zip
ba4f42fb6fe63565e7a5eb5e37d429b0ca33857b1466e393098edf13ce77ced9  dss_capi_0.14.1_win_x86.zip
020ce922189a339ce74bed9b629a9a9b7c405d002ccb8dc92565afdc57280575  messages.tar.gz
41b9040faddc682b7dde2a276981a8e9670997fadd64b0e09d85daadfc60dd68  messages.zip

SHA512

fd1a04d82a5f5d550fffcca6ab3a48c06fed722b33898eba43143ee528ddd200bc52f6a00922b3689703c2853c20a3c5c8e33fc121ca8cc3ded01424743c5e9a  dss_capi_0.14.1_darwin_arm64.tar.gz
8dcf86e860d16fa7cb2b1d1cd7be5fae41b70c0df8aa90226e322dec987aefeb7ef0ccf37e0f8e9ec1edff1d6a5084850c68f0c6b5d3293b41a687860f55dbee  dss_capi_0.14.1_darwin_x64.tar.gz
bba2f2e776e23f365577c12805be2c2f87074122d70890a724f17983b52729eaec30f820f80f646b9b49316d40f1635c6df62b83bf292ee4fc5bbe38bc71285e  dss_capi_0.14.1_linux_arm64.tar.gz
f1d80b8947ce6a44d6b0afaf6a95793d99b4d95ea7c3e1987a4d3221a8dc84286c89cf9390dba150f470bcd85cad29da1eb8ee3a98a21827c6e37431fd699199  dss_capi_0.14.1_linux_x64.tar.gz
f95d50ef072685388b8b28cb95dca506e36ec1b1469dd5a9d65807869985be24fd95840e64681216058fdc0f9f1b684f7e76d5bd3b9c8431de89a89e71f36a99  dss_capi_0.14.1_linux_x86.tar.gz
b2e55f4e5bdec00caa9f24052c9119f81c4410f08e7ef20aefdb9f35f8d4288afcbcb3eb7d03cdc48c9a45ff715805191e7a40f6a020c2383641e37344b47631  dss_capi_0.14.1_win_x64.zip
51c6c8720ae5157df4c4e61432fac5056d71438b55d1e8b6b9ca0f3fe0f66ca1a4e5a7d3ca60b9c57c15852962157f3f54445b7f0e7944763206b2f9995c94d7  dss_capi_0.14.1_win_x86.zip
0af95f0f4754e7b8f0f316732fe21475a6ab49ad13172710a9f3d3797f639686d2cd2b5ea20a312dd80f5b33da4464e2411733fe5a8f6e04f6e51cabe13fecb9  messages.tar.gz
a2e5acaf55e51f61d17431a7e66d1173e178ad12bcffa87a70ac503b2a0b5ee63695fbde05c3204aed59a92207bd1dab903768835f0f0da94e0ade19804f22cf  messages.zip
Assets 13
Loading