DSS Extensions: multi-platform OpenDSS extensions

DSS Extensions enables cross-platform (Windows, Linux, macOS) multi-language interfaces and extensions for EPRI’s OpenDSS, based on an alternative extended DSS engine. OpenDSS is an open-source distribution system simulator.

Introduction

The extensions is built up of three layers:

Firstly, there is the official OpenDSS SVN repository, electricdss, hosted on SourceForge.net. A filtered copy, contaning only source code files, is provided on GitHub on the opendss-official-svn branch of the DSS C-API repository.

Secondly, the DSS C-API library exposes a customized, extended OpenDSS engine, adapted from the official OpenDSS code from electricdss. As the name suggests, this library provides a plain C interface. The interface tries to be feature compatible with the COM interface from the official OpenDSS distribution. What was initially intended as a API-only project has evolved to contain many customizations and extensions.

Lastly, there are several language specific extensions are built on top of DSS C-API. The following language specific extensions mimic the COM interface. As such, they can be used as drop-in replacements for code that already uses the official COM module on Windows, enabling multi-platform usage.

Additionally, OpenDSSDirect interfaces have been built on top of DSS C-API and the language extensions. See the following for more information:

These opendssdirect or odd interfaces are flexible to adapt and are not restricted by the COM API limitations. They are intended to provide a more Pythonic, Julian or language geared API. Although these projects now use DSS C-API, these projects originally used the official OpenDSSDirect.DLL interface, hence their names.

A recent new addition is the dss.hpp C++ header library. It exposes the DSS C-API functions in an organized set of classes. A namespace dss::classic contains an organization that resembles the organization provided by the official COM implementation, which the new dss::obj (working name). It is currently hosted within the DSS C-API repository.

Finally, there are slightly modified tests and examples from the official OpenDSS distribution here.

If you find yourself in need of a certain feature, feel free to open an issue in the respective repository.

Documentation

At the moment, quality and volume of documentation across the projects vary. In July 2022, the overall documentation effort was launched at the DSS Extentions hub repository.

For the low-level DSS C-API reference, there are files available at the docs folder, and the C header itself is commented for most functions. A Doxygen documentation site covering the main DSS C-API header and the new dss.hpp classes is available at https://dss-extensions.org/dss_capi/.

DSS_Python, DSS_Sharp and DSS_MATLAB try to follow and be compatible with the official COM implementation. As such, users can employ the official OpenDSS COM documentation for a general reference. An initial DSS Python reference can be seen at https://dss-extensions.org/dss_python/, and DSS_Sharp’s at https://dss-extensions.org/dss_sharp/.

OpenDSSDirect.py’s reference is available on https://dss-extensions.org/OpenDSSDirect.py/ and the docs for OpenDSSDirect.jl are in https://dss-extensions.org/OpenDSSDirect.jl/stable/

An important reminder is that most of the original COM API functionality is exposed in all projects. As expected, the calling convention and general package organization does change from package to package. The API extensions, which include many extra functions and toggles, try to follow the conventions of each package. See the known differences document for an overview of the changes you can expected from using a DSS Extensions project instead of the official OpenDSS.

Most of the documentation focuses on the API facet. For a reference of the OpenDSS commands and properties at script level, on the DSS basic scripting language, users can refer to the official OpenDSS documentation, or use DSS Extensions: OpenDSS Commands and Properties as a quick reference until we organize a general documentation covering important aspects of the projects listed here.