DSS MATLAB: a multi-platform MATLAB package for DSS C-API, an unofficial implementation of EPRI's OpenDSS

---

📦 Downloads available here for Linux, macOS and Windows

Note that the repository itself doesn't contain the binaries since this is a multi-platform project. If you download the Git repository, you still need the binary files from the DSS C-API library. Please head on to the Releases page for downloads.

---

This is version of a set of MATLAB classes that expose the DSS C-API library with the same structure as the COM object, with the same extensions as DSS Python. This is the equivalent of DSS Python and DSS Sharp for MATLAB usage.

Please see https://dss-extensions.org/ for a general introduction and useful links for all projects under DSS Extensions.

A new repository to coordinate documentation and other shared features across all DSS Extensions is now available at https://github.com/dss-extensions/dss-extensions

Related projects:

• OpenDSS: The main OpenDSS project, maintained by EPRI.
• DSS C-API: Custom OpenDSS C-API library, which also includes some patches.
• DSS Python: Python bindings that mimics the official COM interface (property-style access to items).
• OpenDSSDirect.py: Function-style bindings and useful tools (originally based on the DCSL/OpenDSSDirect.DLL).
• OpenDSSDirect.jl: Julia bindings to DSS C-API (originally based on the DCSL/OpenDSSDirect.DLL).
• DSS Sharp: .NET assembly to use the native DLL, mimics the COM object as used in .NET.

Version 0.12.1, released on 2022-07-16, covers most of the COM functions and classes, besides some extensions from DSS C-API. If you find a missing function or unexpected behavior, please open an issue on GitHub to both help us track and hopefully fix it, and also inform other users. This project uses the DSS C-API library version 0.12.1, based on OpenDSS revision 3460 (few commits after OpenDSS v9.4.1.2).

Highlights from 0.12.1

• Parallel API is now supported. Diakoptics and a few corner features are still disabled (under reimplementation).

• Storage API added.

• Support for ZIP files

• Several new functions across the different classes

• Initial support for exporting JSON data

• Better error messages

• 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/master/docs/dss_properties.md

A long list of changes is available at DSS C-API changelog.

Usage

1. Download a package from the releases page.

2. Add the folder containing +DSS_MATLAB to your MATLAB path.

3. Instantiate DSS_MATLAB.IDSS. For example:

dss = DSS_MATLAB.IDSS;

4. If you find issues or missing features, feel free to open an issue ticket on GitHub or email me (pmeira at ieee.org).

If your code is based on DSSStartup.m from the examples, 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;    

On 2019-07-02, a simple example for the IEEE13 system was added in 13Bus.zip if you want to try DSS_MATLAB with a sample circuit. This file is now also included in the download package.

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

As a general advice (valid for the official COM version 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 history

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.

See the DSS C-API project for more details and source files.