基于dss c-api项目的opendss绑定与工具
dss-python的Python项目详细描述
dss python:epri的opendss的非官方绑定
使用opendss(epri分发系统模拟器)的python绑定和其他工具。基于CFFI和DSS C-API,旨在在Windows、Linux和MacOS上实现完全的COM兼容性。
另请参见dss extensions.org中的其他项目
- DSS C-API库:通过更传统的C接口公开稍有修改的EPRI OpenDSS版本的基本库,使用开源的免费PASCAL编译器而不是Delphi构建。
- opendssdirect.py:如果不需要COM兼容性,或者只想检查其额外功能。您可以混合使用dss python和opendssdirect.py——例如,如果您有使用官方com对象的旧代码,您可以在很少更改代码的情况下快速切换到dss python,然后使用允许">
opendssdirect.utils
生成一些数据帧。 - opendssdirect.jl:由tom short(@tshort)创建的julia模块最近在dheepak krishnamurthy(@kdheepak)的帮助下迁移到dss c-api,而不是ddll。
- dss sharp:可用于.net/c,也可模拟COM类,但目前仅限于Windows。很快也可以通过COM使用它。
- DSS Matlab:提供了与DSS C-API的多平台集成(Windows、Linux、MacOS),并且与COM类也非常兼容。
版本0.10.3,基于OpenDSS版本2609(略高于OpenDSS V8.5.9.1和V7.6.5.86)。虽然我们计划在dss python中添加更多的功能,但创建一个com兼容api的主要目标已经实现。如果发现意外丢失的功能,请报告!
此模块模拟COM结构(通过win32com
或comtypes
公开),有效地实现了Python级别的多平台兼容性。
大多数COM文档都可以按原样使用,但这些模块返回/接受numpy数组进行数字数据交换,而不是返回元组或列表。
该模块依赖于cffi、numpy和scipy.sparse(可选)来读取稀疏系统导纳矩阵。
最近的更改
有关详细列表,请查看更改日志文档。
- 2019-05-22/0.10.3版:一些重要的修正,更好的通用性能,新的API扩展,从COM和OpenDSSversion8代码库移植的新功能。
- 2019-02-28/0.10.2版:一些小的修正,添加了丢失的
ctrlqueue.push
,更快的加载形状和新的属性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版:修复一些使用数组数据的setter。
- 2018-04-05/0.9.6版:增加缺失的
activecircuit.cktelements[index]
(或…cktelements(index)
)和activecircuit.bus[index]
(或…bus(index)
)。 - 2018-03-07/0.9.4版:允许在多个类上使用
len
,修复dsproperty,并将com帮助字符串包含为docstring。包含对OpenDSS版本2152的更改。 - 2018-02-16/0.9.3版:集成2136版的COM接口修复(
first
next
iteration on some elements) - 2018-02-12/0.9.2版:对OpenDSS PM的实验性支持(目前,为FreePascal支持提供了自定义补丁)和端口COM接口修复(OpenDSS版本2134)
- 2018-02-08/0.9.1版:首次公开发行(OpenDSS版本2123)
缺少功能和限制
大多数限制继承自dss\u capi
,也就是说,这些限制没有实现:
dssevents
fromdll/implevents.pas
:似乎过于依赖com。dsprogress
fromdll/impledsprogress.pas
:需要根据目标用户界面(gui、文本、headless等)重新实现。
一般来说,dss-capi中的dll提供了比官方直接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
或者,如果您使用的是蟒蛇分布,您可以使用:
conda install -c pmeira dss_python
所有主要平台(windows、linux和macos)和许多python版本(2.7、3.5到3.7)的组合都提供了二进制轮子。如果您对某个特定版本有问题,请打开一个有关该版本的问题。Conda软件包至少支持Python2.7、3.5、3.6和3.7。
成功安装后,您可以从python解释器导入dss
模块。
建筑
获取存储库:
git clone https://github.com/dss-extensions/dss_python.git
假设您成功地构建或下载了dss c-api dll(有关说明,请查看其存储库中的dss-capi/" rel="nofollow"),请按如下方式保留文件夹组织:
dss_capi/
dss_python/
electricdss-src/
在dss_python
子文件夹中打开命令提示符并运行生成过程:
python setup.py build
python setup.py install
如果您熟悉conda build,那么在conda子文件夹中有一个构建dss c-api、klusolve和dss python的完整方法。
示例用法
如果您在代码中使用win32com
,例如:
importwin32com.clientdss_engine=win32com.client.gencache.EnsureDispatch("OpenDSSEngine.DSS")
或通信类型
importcomtypes.clientdss_engine=comtypes.client.CreateObject("OpenDSSEngine.DSS")
您可以将该片段替换为:
importdssdss_engine=dss.DSS
如果您需要混合大小写处理(也就是说,您没有使用win32com的早期绑定),请添加对dss的调用。
假设您有一个名为master.dss
的dss脚本,您应该能够按如下所示运行它:
importdssdss_engine=dss.DSSdss_engine.Text.Command="compile c:/dss_files/master.dss"dss_engine.ActiveCircuit.Solution.Solve()voltages=dss_engine.ActiveCircuit.AllBusVoltsforiinrange(len(voltages)//2):print('node %d: %f + j%f'%(i,voltages[2*i],voltages[2*i+1]))
如果您想使用实验性的opendss pm接口(来自opendss v8),它是并排安装的,您可以将其导入为:
pip install dss_python
0
虽然它是实验性的,但它的大部分功能都在发挥作用。根据您的用例,并行接口可能是更好地使用计算机资源的一种简单方法。否则,您始终可以通过python使用通用的分布式计算资源。
请注意,V8替代版本可能会出现问题,一旦所有OpenDSS8+功能都集成到默认版本中,就应将其删除。
测试
由于dll是使用epri不支持的免费pascal编译器构建的,因此通过运行opendss官方发行版中提供的示例网络验证了结果。唯一的修改是由脚本直接完成的,删除了交互功能和其他一些小问题。来自官方opendss存储库的大多数示例文件都用于验证。
验证脚本是tests/validation.py
,需要与生成过程相同的文件夹结构。您需要win32com
才能在Windows上运行它。
从0.11版开始,完整的验证套件可以在三个受支持的平台上运行。这可以通过保存官方的com dll输出并将其加载到macos和linux上来实现。我们希望将来自动进行验证。
路线图
除了bug修复,这个库的主要功能主要完成。可以实现的显著的理想特性是:
- 更多更好的文档
- 在python中集成绘图和报告。
请按0.11版查看有关这些项目的新闻。
有问题吗?
如果你有任何问题,可以在github上开罚单,或者直接通过电子邮件联系我(pmeira at ieee.org)。请给我几天时间回复。
学分/知识
dss python是基于epri的opendss,通过dss-capi
项目,检查其许可信息。
此项目在(新的)BSD下获得许可,可在许可证
文件中找到。这与OpenDSS使用的许可证相同(OpenDSS_license
)。opendss本身使用了klusolve和suitesparse,这是根据gnu lgpl 2.1授权的。
我感谢我在巴西坎皮纳斯大学的同事提供反馈并帮助我测试这个模块。