DSS MATLAB 0.14.3-1

Version 0.14.3-1 only affects the MATLAB code, fixing an issue with calllib and some minor issues in the following functions/properties:

• Monitors.Channel
• Monitors.AsMatrix
• Monitors.dblFreq
• Monitors.dblHour
• ActiveCktElement.Properties

The example was also updated to use those functions.

Watch for another release, which will include updates to DSS engine, soon (expected by November 8).

❓ What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/ and https://github.com/dss-extensions/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

⚙️ DSS C-API Version 0.14

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

Changes from 0.14.1 to 0.14.3

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

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 since 0.13.4

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

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

DSS MATLAB 0.14.3

Version 0.14.3 upgrades the engine to AltDSS/DSS C-API 0.14.3. Compared to v0.14.1, there are a few important bugfixes.

This DSS MATLAB release only updates the engine due to the bugfixes that comes with it, but doesn't expose some new functions just yet.

We are including a package for ARM64 macs ("Apple Silicon"). MATLAB support for these machines is very recent, please feel free to report issues regarding it.

❓ What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/ and https://github.com/dss-extensions/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

⚙️ DSS C-API Version 0.14

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

Changes from 0.14.1 to 0.14.3

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

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 since 0.13.4

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

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

DSS MATLAB 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 DSS MATLAB release only updates the engine due to the bugfixes that comes with it, but doesn't expose some new functions just yet.

We are including a package for ARM64 macs ("Apple Silicon"). MATLAB support for these machines is very recent, please feel free to report issues regarding it.

❓ What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/ and https://github.com/dss-extensions/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

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

DSS MATLAB 0.13.4-2

Version 0.13.4-2 is a bugfix release. Compared to 0.13.4:

• It fixes reading most integer arrays, thanks to a user report.
• Due to user requents, we also included a tentative package for ARM64 macs ("Apple Silicon"). MATLAB support for these machines is very recent, please feel free to report issues regarding it.

Version 0.14.0 should be released in Jan 2024, matching the new engine version.

Read below regarding engine changes in the original 0.13.4 release.

❓ What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

⚙️ DSS C-API Version 0.13.4

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.

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.4-2_linux_x64.tar.gz
• macOS Intel: dss_matlab_v0.13.4-2_macos_x64.tar.gz
• macOS ARM64 (Apple Silicon): dss_matlab_v0.13.4-2_macos_arm64.tar.gz
• Windows: dss_matlab_v0.13.4-2_win_x64.zip

Since the stable release for native MATLAB on macOS ARM/M1/etc. ("Apple Silicon") is very recent, the package above was added for wider testing; please report issues you find. ARM support is already available for other DSS-Extensions and follows the same testing as the other platforms.

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

Some documentation?

Remember that this package is meant to be a drop-in replacement for the official COM implementation, consequently the official documents/help already covers a lot. Conversely, a lot of our documentation can be used with the official OpenDSS implementation (just ignore anything marked "API Extension").

1. The basic MATLAB help command can be used to get a list of functions and properties available in the objects.
2. The DSS-Python reference can be useful for discoverability, e.g. The DSS instance. DSS Sharp reference is also an alternative.
3. We have an online document listing most DSS properties and commands at DSS-Extensions: OpenDSS Commands and Properties.
4. This official OpenDSS COM lists the official API contents: OpenDSSComDoc.pdf
5. There is another official document in a less accessible format that can be used for those still learning the basics, but remember we offer a wider range of features: official OpenDSS_COM.chm on SourceForge. This includes some basic examples of usage.

This last one is a CHM file (Winhelp, compressed HTML files), Windows supports it natively.
On Linux, there are multiple CHM readers, such as KchmViewer — check your package manager or store for more.
On macOS, this fork of iCHM works, and there are some alternatives in the Apple App Store.
Wine also comes with a CHM reader.

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

Most of these apply indirectly to DSS_MATLAB.

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 MATLAB 0.13.4

Version 0.13.4 is a bugfix release. Read below regarding engine changes.

❓ What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

⚙️ DSS C-API Version 0.13.4

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.

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.4_linux_x64.tar.gz
• macOS: dss_matlab_v0.13.4_macos_x64.tar.gz
• Windows: dss_matlab_v0.13.4_win_x64.zip

macOS ARM/M1/etc. ("Apple Silicon") support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS-Extensions and it should be easy to use it on ARM Macs (just replace the binaries from DSS C-API, which are already available).

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

Some documentation?

Remember that this package is meant to be a drop-in replacement for the official COM implementation, consequently the official documents/help already covers a lot. Conversely, a lot of our documentation can be used with the official OpenDSS implementation (just ignore anything marked "API Extension").

1. The basic MATLAB help command can be used to get a list of functions and properties available in the objects.
2. The DSS-Python reference can be useful for discoverability, e.g. The DSS instance. DSS Sharp reference is also an alternative.
3. We have an online document listing most DSS properties and commands at DSS-Extensions: OpenDSS Commands and Properties.
4. This official OpenDSS COM lists the official API contents: OpenDSSComDoc.pdf
5. There is another official document in a less accessible format that can be used for those still learning the basics, but remember we offer a wider range of features: official OpenDSS_COM.chm on SourceForge. This includes some basic examples of usage.

This last one is a CHM file (Winhelp, compressed HTML files), Windows supports it natively.
On Linux, there are multiple CHM readers, such as KchmViewer — check your package manager or store for more.
On macOS, this fork of iCHM works, and there are some alternatives in the Apple App Store.
Wine also comes with a CHM reader.

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

Most of these apply indirectly to DSS_MATLAB.

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 MATLAB 0.13.3

Version 0.13.3 is a bugfix release. Read below regarding engine changes.

What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

⚙️ DSS C-API Version 0.13.3

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.

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.3_linux_x64.tar.gz
• macOS: dss_matlab_v0.13.3_macos_x64.tar.gz
• Windows: dss_matlab_v0.13.3_win_x64.zip

macOS ARM/M1/etc. support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS-Extensions and it should be easy to use it on ARM Macs (just replace the binaries from DSS C-API).

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

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

Most of these apply indirectly to DSS_MATLAB.

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 MATLAB 0.13.2

Version 0.13.2 is a minor release. On the MATLAB side, the comment strings were updated. Read below regarding engine changes.

What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

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

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.2_linux_x64.tar.gz
• macOS: dss_matlab_v0.13.2_macos_x64.tar.gz
• Windows: dss_matlab_v0.13.2_win_x64.zip

macOS ARM/M1/etc. support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS-Extensions and it should be easy to use it on ARM Macs (just replace the binaries from DSS C-API).

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

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

Most of these apply indirectly to DSS_MATLAB.

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 MATLAB 0.13.1

Version 0.13.1 is a minor release to address a minor concern related to a potential issue with three of the PVSystem properties. Slight updated version 0.13.0 release notes follow.

This version includes ported updates from DSS-Python 0.13, integrating our base library, DSS C-API 0.13. Specific to DSS_MATLAB:

• Add missing file
• DSS.AdvancedTypes mode: when enabled, the package can return complex numbers and matrices!
• DSS.CompatFlags: some toggles for compatibility with the official OpenDSS on some specific points.
• DSS.AllowDOScmd: toggle running system commands from DSS scripts
• Fix many docstring typos
• Fix some arrays of strings: some functions were broken during the DSSContext migration.
• Use enums for some properties: easier to read, more maintainable.
• Introduce a few new functions added in the official COM API.
• Updated our simple example script.

See also the DSS C-API 0.13.0 notes.

What's this?

DSS MATLAB 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 and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.1_linux_x64.tar.gz
• macOS: dss_matlab_v0.13.1_macos_x64.tar.gz
• Windows: dss_matlab_v0.13.1_win_x64.zip

macOS ARM/M1/etc. support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS Extensions and it should be easy to use it on ARM Macs (just replace the binaries from DSS C-API).

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

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

Most of these apply indirectly to DSS_MATLAB.

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 MATLAB 0.13.0

This version includes ported updates from DSS-Python 0.13, integrating our base library, DSS C-API 0.13. Specific to DSS_MATLAB:

• Add missing file
• DSS.AdvancedTypes mode: when enabled, the package can return complex numbers and matrices!
• DSS.CompatFlags: some toggles for compatibility with the official OpenDSS on some specific points.
• DSS.AllowDOScmd: toggle running system commands from DSS scripts
• Fix many docstring typos
• Fix some arrays of strings: some functions were broken during the DSSContext migration.
• Use enums for some properties: easier to read, more maintainable.
• Introduce a few new functions added in the official COM API.
• Updated our simple example script.

See also the DSS C-API 0.13.0 notes.

What's this?

DSS MATLAB is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes EPRI's OpenDSS with a custom API intended to replace and extend the functionality of the official COM object API. For other languages: check DSS Python, OpenDSSDirect.py and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS-Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.13.0_linux_x64.tar.gz
• macOS: dss_matlab_v0.13.0_macos_x64.tar.gz
• Windows: dss_matlab_v0.13.0_win_x64.zip

macOS ARM/M1/etc. support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS Extensions and it should be easy to use it on ARM Macs (just replace the binaries from DSS C-API).

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

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

Most of these apply indirectly to DSS_MATLAB.

Credits / Acknowlegement

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 MATLAB 0.12.2

This DSS MATLAB release includes fixes to the Monitors.ByteStream property, and to several functions when used with the parallel-machine/actors enabled. In version 0.12.1, part of the functions were returning the results from the first actor, always.

The engine is still kept as DSS C-API 0.12.1. An updated release will follow in a week or two after to expose the latest OpenDSS updates.

Please file an issue or contact the author for feedback (pmeira at ieee.org) if you encounter unexpected behavior.

What's this?

DSS MATLAB is a member of the family of multi-platform language bindings based on the DSS C-API project, which exposes EPRI's OpenDSS with a custom API intended to replace and extend the functionality of the official COM object API. For other languages: check DSS Python, OpenDSSDirect.py and DSS Sharp. See more alternatives at https://dss-extensions.org/

As with DSS Python and DSS Sharp, 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. Most of the missing features are related to the plotting methods from OpenDSS and A-Diakoptics, which are not available in DSS C-API yet. You can, of course, use MATLAB's plotting capabilities.

We are currently evaluating reimplementing DSS_MATLAB using MEX. This would potentially allow us to integrate some plotting functions and also parfor support with pool('threads').

📦 Downloads

Download the file according to your platform, as each file contains platform-specific binaries:

• Linux: dss_matlab_v0.12.2_linux_x64.tar.gz
• macOS: dss_matlab_v0.12.2_macos_x64.tar.gz
• Windows: dss_matlab_v0.12.2_win_x64.zip

macOS ARM/M1 support will be added when there are stable MATLAB releases, probably in 2023. ARM support is already available for other DSS Extensions.

If you want to try DSS_MATLAB with a sample circuit, a simple example for the IEEE13 system is also included in the download package, under the examples folder. Continue reading for more.

Basic usage

1. Download and extract the package appropriate for your system.
2. Add the folder containing +DSS_MATLAB to your MATLAB path (e.g. path(path, 'c:\dss_matlab');).
3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

If you code is based on DSSStartup.m from the examples included in the official distribution, in general you only need to replace the Obj = actxserver('OpenDSSEngine.DSS'); line. That is, update DSSStartup.m to:

%--------------------------------------------------------------------------
function [Start,Obj,Text] = DSSStartup
    % Function for starting up the DSS
    
    %instantiate the DSS Object
    Obj = DSS_MATLAB.IDSS;
    %
    %Start the DSS.   Only needs to be executed the first time w/in a
    %Matlab session
    Start = Obj.Start(0);

    % Define the text interface
    Text = Obj.Text;    

If you want more code to play with, you can use the MATLAB examples from the official OpenDSS distribution, from a local installation (e.g. C:\OpenDSS\Examples\Matlab) or from the official SVN repository.

Sandia's GridPV toolbox has been confirmed to work with very minor changes. Note that the toolbox seems to be out-of-date for some features, so don't expect everything to work even with COM (e.g. Google Maps integration seems broken).

As a general advice (valid for COM and DSS_MATLAB), avoid using the get function without parameters on OpenDSS classes. Some properties like First and Next used for iteration of elements change the current active element and can lead to misleading data!

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

Most of these apply indirectly to DSS_MATLAB.

The list of important changes through development is also useful.

Credits / Acknowlegement

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

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