search

dss-extensions / dss_capi

A multi-platform, customized C-API library and alternative implementation of OpenDSS (EPRI Distribution System Simulator) aiming for full COM compatibility. Unofficial/unsupported by EPRI, but extensively tested.
https://dss-extensions.org/
BSD 3-Clause "New" or "Revised" License
33 stars 13 forks source link
c electrical-engineering epri-opendss freepascal linux macos opendss opendssdirect powerflow short-circuit windows

readme

GitHub Actions: Builds GitHub downloads Supports Linux Supports macOS Supports Microsoft Windows

Para uma versão em português deste arquivo, veja README.pt-BR.md.

AltDSS/DSS C-API: a library with a C API for an Alternative implementation of EPRI's OpenDSS

Please see FAQ for a couple of notes.

This library exposes the OpenDSS/OpenDSS-PM v9+ engine in a plain C interface that tries to reproduce most of the COM methods, plus many extensions. In fact, most of the code was initially derived from the COM implementation files. The resulting DLL can be using directly by advanced users or, for example, through the DSS-Python package in Python, a module that mimics the COM structure (as exposed via win32com or comtypes), effectively enabling multi-platform compatibility at Python level.

Through the other projects under DSS-Extensions, DSS C-API enables projects to use the OpenDSS in multiple platforms (Windows, Linux, macOS) across multiple architectures (Intel x86, x86-64, ARM32, and ARM64, including Apple's M1 and M2). Most of the features added to this based library is shared across all other projects. If you need support for a language not listed below, please open a new issue (either here or in https://github.com/dss-extensions/dss-extensions/issues) and we will evaluate that language.

Overview of related repositories

If you are looking for the bindings to other languages:

Version 0.14.x is based on OpenDSS revision 3723 (exactly OpenDSS v9.8.0.1), with many extra/custom features.

For the source-code of a specific version, check the Git tags or the Releases page.

While the main objective of COM compatibility has been reached, this is still a work-in-progress and is subject to changes. Especially, there are planned changes targeting version 1.0.

Instead of using extra numeric parameters as in the official DDLL interface ("OpenDSSDirect" or "DCSL"), each original COM property is exposed as a pair of functions. For example, the load kVA property is exposed as:

    double Loads_Get_kva();
    void Loads_Set_kva(double Value);

Besides low-level details such as memory management, most of the COM documentation can be used as-is.

Starting in version 0.9.8, we disabled the opendsscmd.ini creation. You can set the default base frequency using the environment variable DSS_BASE_FREQUENCY, or just set it in the DSS scripts (recommended). This also means that the initial datapath is set to the current working directory.

Since 2019-03-05, the dss_capi repository contains all the Pascal code used to build DSS C-API. After the 0.10.x series of releases, all Pascal code is contained in the src/ folder. The src/CAPI/ folder contains the main API code, which sits besides the general OpenDSS code. Although there have been extensive changes to the official OpenDSS code, the upstream/official code is kept in the branch named opendss-official-svn and is periodically ported — see also the upstream branch document.

Recent changes

See the changelog for a detailed list.

Missing features and limitations

Closed-source features are not ported. New components or features without examples or tests are usually avoided until maturity is reached in the official OpenDSS.

Extra features

Besides most of the COM methods, some of the unique DDLL methods are also exposed in adapted forms, namely the methods from DYMatrix.pas, especially GetCompressedYMatrix (check the source files for more information). Also check the list of known differences for extra methods and options.

There are a growing number of API extensions. Some are pending documentation and examples.

Download

See the releases page. Pre-compiled files are available for Windows, Linux and MacOS.

Building

To build the DLL yourself:

On Windows

If you just need the DLL, you can download it from the releases page. Pre-release development versions can be downloaded from the build artifacts from the GitHub Actions workflow (you ).

Otherwise:

The output files will be placed into the lib/win_x64 folder.

If you just need the DLLs, you can also find the x64 DLLs and LIBs in the artifacts from the AppVeyor instance. These files are built after each commit to this repository and are kept for 6 months.

On Linux

If the provided DLLs are not compatible with your distribution, the current recommendation is to build your own KLUSolve, so you need to download and install its dependencies. Since most distributions should include compatible SuiteSparse packages (which include the KLU library), a modified version of KLUSolve is included in the klusolve subfolder. Overall instructions:

On MacOS

After taking care of KLUSolve and placing a copy of it in the same folder, overall instructions:

Similar steps are required for the ARM64 (aka "Apple Silicon" in marketing-speak) version.

Usage and examples

To understand the main concepts of DSS C-API and how it handles memory, see the usage document.

Two minimal samples (without DSS scripts, please bring your own) are available in examples. Add the appropriate subfolder from include and the library from lib to the compilation.

The source code from DSS-Python, OpenDSSDirect.py and OpenDSSDirect.jl are more complete and advanced examples of usage.

More general documentation will be available in the future at https://github.com/dss-extensions/dss-extensions and https://dss-extensions.org

Testing

Currently most testing/validation is based on DSS-Python. Other projects like OpenDSSDirect.py and OpenDSSDirect.jl also provide important tests that help us find and fix potential bugs.

Roadmap

Besides bug fixes, the main functionality of this library is mostly done. Notable desirable features that may be implemented are:

Questions?

If you have any question related to the development of this project, feel free to open a ticket on GitHub or contact me through email (pmeira at ieee.org). Please allow me a few days to respond.

Credits / Acknowledgment

This project was derived from EPRI's OpenDSS and the same style of license is used. See LICENSE and OPENDSS_LICENSE, also check each subfolder for more details.

Note that, since OpenDSS depends on KLU via KLUSolve, the KLU licensing conditions (LGPL or GPL, depending on how you build KLU) apply to the resulting binaries; from the DSS-Extensions KLUSolve repository, check the files klusolve/COPYING, klusolve/lgpl_2_1.txt, the SuiteSparse documentation and the Eigen3 documentation.

Also note that even though we don't add copyright notices to each of the files, most of files from the OpenDSS original codebase were modified to create the version presented today in this repository. Please refer to the Git commit history for more information.

Thanks to colleagues at the University of Campinas, Brazil, for providing feedback and helping me test this project, especially during its inception in 2016-2017, as well as everyone that reported issues and helped the development since the public release in 2018.