Skip to content

DSS MATLAB 0.12.1 (major upgrade!)
Compare
Choose a tag to compare
@PMeira PMeira released this 16 Jul 16:15
· 26 commits to master since this release
0.12.1
8436b4b

This DSS MATLAB release includes fixes and major updates from our base OpenDSS engine library, DSS C-API. Highlights include Parallel/PM functions, ZIP file support, some JSON export functions, etc. Details below.

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

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

macOS ARM/M1 support will be added when there are stable MATLAB releases, probably in 2023.

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

  • Use TFPHashList where possible (replacing the custom, original THashList implementation from OpenDSS).

  • New LoadShape functions and internals:

    • Port memory-mapped files from the official OpenDSS, used when MemoryMapping=Yes from a DSS script while creating a LoadShape object.
    • Release the LoadShape_Set_Points function, which can be used for faster LoadShape input, memory-mapping externally, shared memory, chunked input, etc.

  • Some new functions:

    • Circuit_Get_ElementLosses
    • CktElement_Get_NodeRef

  • DSS_Get_COMErrorResults/DSS_Set_COMErrorResults: New compatibility setting for error/empty result. If enabled, in case of errors or empty arrays, the API returns arrays with values compatible with the official OpenDSS COM interface.

    For example, consider the function Loads_Get_ZIPV. If there is no active circuit or active load element:

    • In the disabled state (COMErrorResults=False), the function will return "[]", an array with 0 elements.
    • In the enabled state (COMErrorResults=True), the function will return "[0.0]" instead. This should
      be compatible with the return value of the official COM interface.

    Defaults to True/1 (enabled state) in the v0.12.x series. This will change to false in future series.

    This can also be set through the environment variable DSS_CAPI_COM_DEFAULTS. Setting it to 0 disables
    the legacy/COM behavior. The value can be toggled through the API at any time.

  • Drop function aliases: previously deprecated function aliases (LoadShapes_Set_Sinterval and LoadShapes_Get_sInterval) were removed to simplify the build process. Use LoadShapes_Set_SInterval and LoadShapes_Get_SInterval instead.

  • Monitor headers: From the official OpenDSS, since May 2021, the monitor binary stream doesn't include the header anymore. When porting the change to DSS Extensions, we took the opportunity to rewrite the related code, simplifying it. As such, the implementation in DSS Extensions deviates from the official one. Extra blank chars are not included, and fields should be more consistent. As a recommendation, if your code needs to be compatible with both implementations, trimming the fields should be enough.

  • Error messages: most messages are now more specific and, if running a DSS script from files, include the file names and line numbers.

  • Spectrum: To reduce overhead during object edits, now required to exist before the object that uses it. This is consistent with most of the other types in OpenDSS.

  • New object and batch APIs for direct manipulation of DSS objects and batches of objects

  • New experimental API for loading scripts/data from ZIP files

  • New convenience functions to bulk load commands from the API

  • User-models: headers updated, and removed support for user-models in LegacyModels mode. LegacyModels will be removed in v0.13.

  • New functions to export the DSS properties of objects as JSON-encoded strings

  • The C headers for our library were updated to include the const modifier for various of the parameters. A few function declarations were fixed.

  • Initial batch of i18n changes. The property and command descriptions are now provided in an external gettext catalog, allowing us to easily replace them (initial file contained in messages.zip)

Due to the high number of IO changes, we recommend checking the performance before and after the upgrade to ensure your use case is not affected negatively. If issues are found, please do report.

The changelog for version 0.12.0 will be updated if we notice missing items.

See also dss-extensions/dss_capi#109

Full Git Changelog: dss-extensions/dss_capi@0.10.7-1...0.12.1

Assets 5
Loading