Skip to content

DSS MATLAB 0.13.4
Compare
Choose a tag to compare
@PMeira PMeira released this 28 Jun 03:03
· 8 commits to master since this release
0.13.4
f87d2a1

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:

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.

Assets 5
Loading