DSS Python：EPRI OpenDSS 实现的扩展绑定

Python 绑定和其他工具，用于通过 DSS C-API 库中的替代/非官方实现来使用 OpenDSS（EPRI 分发系统模拟器）引擎。基于 DSS C-API、CFFI 和 NumPy，旨在实现在 Windows、Linux 和 MacOS 上的完全 COM 兼容性。

另请参阅DSS-Extensions.org的其他项目：

• DSS C-API 库：基本库，通过更传统的 C 接口公开 EPRI 的 OpenDSS 的修改版本，使用开源 Free Pascal 编译器而不是 Delphi 构建。截至 2022 年，此基础库包含几项广泛的更改，同时保留了非常好的兼容性。
• OpenDSSDirect.py：如果您不需要 COM 兼容性，或者只是想检查它的额外功能。您可以混合使用 DSS Python 和 OpenDSSDirect.py ——例如，如果您有使用官方 COM 对象的旧代码，您可以快速切换到 DSS Python，只需很少的代码更改，然后用于opendssdirect.utils生成一些 DataFrame。
• OpenDSSDirect.jl：一个 Julia 模块，由 Tom Short (@tshort) 创建，最近在 Dheepak Krishnamurthy (@kdheepak) 的帮助下迁移到 DSS C-API 而不是 DDLL。
• DSS Sharp：可用于 .NET/C#，也模仿 COM 类，但目前仅限 Windows。很快就可以通过 COM 使用它了。
• DSS MATLAB：提供与 DSS C-API 的多平台集成（Windows、Linux、MacOS），并且与 COM 类非常兼容。

0.12.1 版基于 OpenDSS 修订版 3460（OpenDSS v9.4.1.2 之后很少提交）。虽然我们计划在 DSS Python 中添加更多功能，但创建与 COM 兼容的 API 的主要目标已经实现。如果您发现意外丢失的功能，请报告！目前缺少的最终将实现的功能是绘图（部分实现可用）和 diakoptics（计划在未来版本中使用）。

该模块模仿 COM 结构（通过win32comor公开comtypes），有效地实现 Python 级别的多平台兼容性。与其他选项相比，它提供了从使用官方 OpenDSS 的代码到 COM 的更轻松迁移。大多数 COM 文档都可以按原样使用，但该模块不返回元组或列表，而是返回/接受 NumPy 数组以进行数字数据交换，这通常是用户首选的。

该模块依赖于 CFFI、NumPy 和可选的 SciPy.Sparse 来读取稀疏系统导纳矩阵。Pandas 和 matplotlib 可以作为可选依赖项添加以启用绘图和其他功能。

简要发布历史

• 2022-07-16 / 版本 0.12.1：非常小的版本，用于解决 v0.12.0 中发现的错误，添加存储 API，并包含属性描述/帮助。
• 2022-07-14 / 0.12.0 版：主要版本合并并行功能、多个 DSS 引擎实例、ZIP 文件支持、增量 Y 矩阵更新、新 API 功能、部分绘图支持、更好的性能等。新功能的一般使用示例将逐步添加到https://github.com/dss-extensions/dss-extensions
• 2021-03-09 / 版本 0.10.7-1：非常小的版本，用于修复某些电表报告的问题。
• 2020-12-28 / 版本 0.10.7：维护版本以匹配 DSS C-API 0.10.7，基于 OpenDSS 修订版 2963。包括来自官方 OpenDSS 的修复和新功能。
• 2020-07-31 / 版本 0.10.6：维护版本以匹配 DSS C-API 0.10.6，基于 OpenDSS 修订版 2909。新的重要设置：DSS.LegacyModels和DSS.Error.ExtendedErrors。
• 2020-03-03 / 版本 0.10.5：维护版本以匹配 DSS C-API 0.10.5，基于 OpenDSS 修订版 2837。暂时删除 v8 并行机功能，以及 Windows 上的 conda 包。
• 2019-11-16 / 版本 0.10.4：维护版本以匹配 DSS C-API 0.10.4。
• 2019-05-22 / 版本 0.10.3：一些重要的修复、更好的通用性能、新的 API 扩展、从 COM 和 OpenDSS 版本 8 代码库移植的新功能。
• 2019-02-28 / 版本 0.10.2：一些小修复，添加了缺失的CtrlQueue.Push、更快的 LoadShapes 和新属性DSS.AllowEditor以切换编辑器调用。
• 2019-02-17 / 0.10.1 版：集成 DSS C-API 更改/修复、一些小修复和更多错误检查。
• 2018-11-17 / 0.10.0 版：许多更改、修复和新功能。检查新的变更日志文档以获取列表。
• 2018-08-12 / 0.9.8 版：重组模块（v7 和 v8），为 OpenDSSDirect.py v0.3+ 添加了 8 个缺失的方法和新的后端方法。集成了来自 DSS_CAPI 和上游 OpenDSS 的许多修复。
• 2018-04-30 / 版本 0.9.7：修复一些使用数组数据的设置器。
• 2018-04-05 / 0.9.6 版：添加缺失的ActiveCircuit.CktElements[index](or ...CktElements(index)) 和ActiveCircuit.Buses[index](or ...Buses(index))。
• 2018-03-07 / 版本 0.9.4：允许len在多个类上使用，修复 DSSProperty，并包含 COM 帮助字符串作为文档字符串。包含直到 OpenDSS 修订版 2152 的更改。
• 2018-02-16 / 0.9.3 版：集成了来自修订版 2136 的 COM 接口修复（First Next对某些元素进行迭代）
• 2018-02-12 / 版本 0.9.2：对 OpenDSS-PM 的实验性支持（目前，为 FreePascal 支持提供了一个自定义补丁）和端口 COM 接口修复（OpenDSS 修订版 2134）
• 2018-02-08 / 0.9.1 版：首次公开发布（OpenDSS 修订版 2123）

近期变动

自 0.10.6 以来 0.10.7 的变化

查看变更日志文档以获取所有版本的详细列表。

• 简单的维护版本。
• 更新到 DSS C-API 0.10.7，其中包括到 OpenDSS v9.1.3.4 的大部分更改。
• CapRadius包括与DSS 属性相关的重要错误修复。如果您的 DSS 脚本包含模式GMRac=... rad=...或GMRac=... diam=...（按此顺序且未指定CapRadius），您应该升级并重新评估结果。
• 从官方 COM 接口移植的新 API 属性：Bus.AllPCEatBus, Bus.AllPDEatBus, CktElement.TotalPowers,Meters.ZonePCE

缺少功能和限制

大多数限制都继承自dss_capi，即，这些限制没有实现：

• DSSEventsfrom DLL/ImplEvents.pas: 好像太依赖COM了。
• DSSProgressfrom DLL/ImplDSSProgress.pas: 需要根据目标 UI（GUI、文本、无头等）重新实现。
• OpenDSS-GIS 功能未实现，因为它们不是开源的。

一般来说，DLL fromdss_capi提供的功能比官方的 Direct DLL 和 COM 对象都多。

额外功能

除了大多数 COM 方法外，一些独特的 DDLL 方法也以改编的形式公开，即来自 的方法DYMatrix.pas，尤其是GetCompressedYMatrix（查看源文件以获取更多信息）。

由于 FreePascal DLL 中没有使用 GUI 组件，因此我们正在试验处理 OpenDSS 错误的不同方法。目前，该DSS.Text.Command调用检查 OpenDSS 错误（通过DSS.Error接口）并将其转换为 Python 异常。理想情况下，每个错误都应该转换为 Python 异常，但这可能会对性能产生负面影响。CheckForError()您可以通过从主模块调用该函数来手动触发错误检查。

安装

在所有主要平台上，您都可以直接从 pip 安装：

    pip install dss_python

或者，如果您使用的是 Anaconda 发行版，您可以尝试：

    conda install -c dss-extensions dss_python

为所有主要平台（Windows、Linux 和 MacOS）和 Python 版本（3.5 到 3.9）的许多组合提供了二进制轮子。如果您对特定版本有疑问，请打开一个关于它的问题。Conda 包至少支持 Python 3.6 到 3.9（根据版本而异）。

成功安装后，您可以dss从 Python 解释器中导入模块。

建造

获取存储库：

    git clone https://github.com/dss-extensions/dss_python.git

假设您成功构建或下载了 DSS C-API DLL（检查其存储库以获取说明），请保持文件夹组织如下：

dss_capi/
dss_python/

在子文件夹中打开命令提示符dss_python并运行构建过程：

python setup.py build
python setup.py install

如果您熟悉conda-build，则在子文件夹中有构建 DSS C-API、KLUSolve(X) 和 DSS Python 的完整配方conda。

示例用法

如果您win32com在以下代码中使用：

import win32com.client 
dss_engine = win32com.client.gencache.EnsureDispatch("OpenDSSEngine.DSS")

或comtypes：

import comtypes.client
dss_engine = comtypes.client.CreateObject("OpenDSSEngine.DSS")

您可以将该片段替换为：

import dss
dss_engine = dss.DSS

如果您需要混合大小写处理（也就是说，您没有使用 win32com 的早期绑定），请添加对dss.use_com_compat().

假设您有一个名为 的 DSS 脚本master.dss，您应该能够运行它，如下所示：

import dss
dss_engine = dss.DSS

dss_engine 。文本。命令 =  "编译 c:/dss_files/master.dss" 
dss_engine 。有源电路。解决方案。求解()
电压 =  dss_engine 。有源电路。所有总线电压

for  i  in  range ( len ( voltages )  //  2 ): 
    print ( 'node %d : %f + j %f '  %  ( i ,  voltages [ 2 * i ],  voltages [ 2 * i  +  1 ]))

测试

由于 DLL 是使用 EPRI 未正式支持的 Free Pascal 编译器构建的，因此结果经过验证，运行官方 OpenDSS 发行版中提供的示例网络。唯一的修改是直接由脚本完成的，删除了交互功能和其他一些小问题。来自官方 OpenDSS 存储库的大多数示例文件都用于验证。

验证脚本是tests/validation.py并且需要与构建过程相同的文件夹结构。您需要win32com在 Windows 上运行它。

从 0.11 版开始，完整的验证套件可以在三个受支持的平台上运行。这可以通过保存官方 COM DLL 输出并将其加载到 macOS 和 Linux 上来实现。我们希望将来能够自动执行此验证。

路线图

除了错误修复之外，这个库的主要功能已经完成。可以实现的显着理想特性是：

• 更多更好的文档（观看https://github.com/dss-extensions/dss-extensions）
• 绘图和报告集成在 Python 中。DSS Python 0.12.0 中可选的几种绘图类型，但缺少一些。报告和高级集成计划用于未来的功能。

期待 0.13 版有关这些项目的消息。

问题？

如果您有任何问题，请随时在 GitHub 上开票，或通过电子邮件直接与我联系（pmeira at ieee.org）。请允许我几天回复。

学分/致谢

DSS Python 是基于 EPRI 的 OpenDSS viadss_capi项目，查看其许可信息。

该项目在（新）BSD 下获得许可，可在LICENSE文件中找到。它与 OpenDSS 使用的许可证相同 ( OPENDSS_LICENSE)。OpenDSS 本身使用在 GNU LGPL 2.1 下许可的 KLUSolve 和 SuiteSparse。

感谢巴西坎皮纳斯大学的同事提供反馈并帮助我测试这个模块。