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. We track the changes there and port accordingly, with a few exceptions.DSS C-API: Custom OpenDSS C-API library (a.k.a. AltDSS), which also includes customize code and extra features, maintaining very good compatibility.include/ directory). Allows using DSS C-API more comfortably from C++, abstract memory management and low-level details such as API conventions of the DSS C-API library.DSS-Python: Python bindings that mimics the official COM interface (property-style access to items). Very similar to DSS_MATLAB, but for Python. Some new and experimental features are tested there first (for example, plotting integration).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.AltDSS-Rust] and [AltDSS-Go] are new projects targeting Rust and Go programming languages.Currently, this package 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 currently uses the DSS C-API library version 0.13.x.
Upgrades the engine to AltDSS/DSS C-API 0.14.x. There are some important bugfixes, a few changes ported from the official OpenDSS, and a lot of new features in our engine.
This first update only updates the engine. Some new functions still need to be exposed to the MATLAB level, notably Circuit_Save.
See also the AltDSS/DSS C-API release notes.
Port updates from DSS-Python 0.13, integrating our base library, DSS C-API 0.13. Specific to DSS_MATLAB:
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 scriptsSee also the DSS C-API 0.13.0 notes.
Migrate to the DSSContext (ctx_*) API. This fixes some results when using multiple actors (PM).
Monitors: fix ByteStream
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.
Download a package from the releases page.
Add the folder containing +DSS_MATLAB to your MATLAB path.
Instantiate DSS_MATLAB.IDSS. For example:
dss = DSS_MATLAB.IDSS;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!
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").
help command can be used to get a list of functions and properties available in the objects. 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.
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.