Skip to content

DSS Sharp v0.13.1
Compare
Choose a tag to compare
@PMeira PMeira released this 03 Apr 09:20
· 12 commits to master since this release
0.13.1
c70e310

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_Get_CompatFlags function pair: introduced to address some current and potential future concerns about compatibility of results with the official OpenDSS. See the API docs for more info.
    • New DSS_Set_EnableArrayDimensions/DSS_Get_EnableArrayDimensions: for Array results in the API, implement optional matrix sizes; when setting DSS_Set_EnableArrayDimensions(true), the array size pointer will be filled with two extra elements to represent the matrix size (if the data is a matrix instead of a plain vector). For complex number, the dimensions are filled in relation to complex elements instead of double/float64 elements even though we currently reuse the double/float64 array interface. Issue: dss-extensions/dss_capi#113

Note that a couple of SVN changes were ignored on purpose since they introduced potential issues, while many other changes and bug-fixes did not affect the DSS C-API version since our implementation is quite different in some places.

Full Git Changelog for DSS C-API: dss-extensions/dss_capi@0.12.1...0.13.1

Assets 3
Loading