Skip to content

DSS MATLAB 0.10.7-1
Compare
Choose a tag to compare
@PMeira PMeira released this 11 Mar 02:24
0.10.7-1
097a831

Upgrades DSS C-API to version 0.10.7-1. The only difference from version 0.10.7 is that this corrects an issue with energy meter reports. If you don't use the reports, you don't need to upgrade.

Slight modified release announcement from version 0.10.7 follows.

This DSS MATLAB release includes fixes and updates from the base OpenDSS engine, more unofficial extensions, as well as a reviewed error reporting system. This project uses the DSS C-API library version 0.10.7-1, based on OpenDSS revision 2963 (which is slightly newer than OpenDSS v9.1.3.3).

Please file an issue or contact the author for feedback (pmeira at ieee.org).

This release includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or GMRac=... diam=... (in this order and without specifying CapRadius), you should upgrade and re-evaluate the results.

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, which are not available in DSS C-API. You can, of course, use MATLAB's plotting capabilities.

📦 Downloads

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

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.

Changes from DSS C-API 0.10.7

  • Simple maintenance release, which includes most changes up to OpenDSS v9.1.3.4 (revision 2963).
  • Includes an important bug fix related to the CapRadius DSS property. If your DSS scripts included the pattern GMRac=... rad=... or GMRac=... diam=... (in this order and without specifying CapRadius), you should upgrade and re-evaluate the results.
  • This version should be fully API compatible with 0.10.3+.
  • A reference document listing the DSS commands and properties for all DSS elements is now available at https://github.com/dss-extensions/dss_capi/blob/0.10.x/docs/dss_properties.md
  • New functions API ported from the official OpenDSS include: Bus_Get_AllPCEatBus, Bus_Get_AllPDEatBus, CktElement_Get_TotalPowers, Meters_Get_ZonePCE.
  • The changes ported from the official OpenDSS include the following (check the repository for more details):
    • "Adds LineType property to LineCode and LineGeometry objects."
    • "Correcting bug found in storage device when operating in idling mode. It was preventing the solution of other test feeders (IEEE 9500)"
    • "Enabling fuel option for generator, fixing bug found in TotalPower command."
    • "Adding kvar compensation calculation for normalizing reactive power at feeder head. v 9.1.2.4"
    • "Adding: - Line type variable to line definition. - AllPCEatBus and AllPDEatBus commands to the executive command set. - AllPCEatBus and AllPDEatBus commands to bus interface in COM/DLL. (...)"
    • "Adding capability to energy meter for getting the list of all PCE (shunt) within a zone. Interface "AllPCEatZone" for COM/DLL created."
    • "Fixing bug found when calculating voltage bases with large amount of numbers (large array)."

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/0.10.x/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.

Assets 5
Loading