简介这份资源是 OpenDSSOpen Distribution System Simulator的官方中文简明用户指导手册面向电力系统仿真初学者、配电系统规划与设计人员以及高校相关专业师生用于解决英文文档阅读门槛高、上手 OpenDSS 困难的问题。压缩包内仅含 1 个 PDF 文件大小约 1.04MB内容为繁体中文译本对应 Program Revision 7.62016 年 3 月版由 Jason Sexauer 编写、李慧娟翻译正文含目录与插图索引。手册从「什么是 OpenDSS」讲起依次介绍电路模型、图形用户界面GUI的使用方法并附有 EPRI 的 BSD 风格许可协议与版权声明便于读者理解软件的使用权限与免责条款。借助这份文档读者可以建立对 OpenDSS 仿真流程的整体认识掌握配电网络建模、潮流与电压分析等基础操作思路也可将其作为查阅电路元件参数与 GUI 功能的中文速查资料。目前已有 1341 人学习下载适合作为入门阶段的第一份参考资料。1. 母线不是主角为什么一个配网仿真器把“节点”放在从属位置翻开这份 OpenDSS 中文手册最反直觉的一句话是母线并不重要真正重要的是元件。做配网潮流的人都清楚绝大多数工具以母线为中心所有计算围绕母线的电压幅值和相角展开母线编号就是矩阵下标。OpenDSS 把母线做成“用到时才生成”的副产品节点索引在元件成型的过程中被动产生。这个看似自找麻烦的选择直接决定了它后面所有能力的上限——能不能描述任意相数的变压器接线、能不能把负荷挂成一个随频率变化的函数、能不能让一年 8760 个时间点在同一个模型上跑完。搞懂这条主线再看那份手册里的元件表、命令语法和 COM 接口就不是背 API而是看一个系统怎么组织自己的世界。2. 电路模型的三层结构传输元件、转换元件与辅助元件怎么拼出一张网2.1 母线、节点与 Node 0一个 bus 为什么能装下多个 node手册里有句话容易被略过母线可以有 [1..N] 个节点母线是电路元件的连接点。在很多电力系统分析软件里母线和节点基本是同一概念在 OpenDSS 里却是两个层级。母线是容器节点是容器里编号的槽位。Node 0 永远被当作参考节点、接地节点、0 V 节点其余节点传统上对应其他相比如 node 2 是 B 相。指定母线位置时要把节点带上node 0 除外因为它被认为一直存在三相母线写成BUSNAME.1.2.3。为什么非要让 node 0 隐式存在因为节点导纳矩阵需要一个永远在场的参考锚点。如果把接地也做成一个可分配的节点编号每次新建元件都要问“接地是几号”矩阵的参考行和参考列就得跟着元件增删动态搬家。把 0 号焊死等于给整个网络一个不动的原点——所有对地导纳直接 stamp 到第 0 行第 0 列永远不用重排。这是很典型的“用一个约定换掉一堆分支判断”的做法。再看BUSNAME.1.2.3这种写法。数字是节点编号但是否对应 A/B/C 相不是母线自己决定的而是连接在它上面的元件决定的。一个三相线路接进来它看到 1、2、3 三个节点一个单相负荷接在.2上它只看到 B 相。母线只提供“这里有三个可连接的槽位”语义由元件赋予。这就是所谓的“元件中心”模型语义在元件身上母线只是被引用出来的地址空间。2.2 电力传输元件与电力转换元件的边界手册把电路模块分成两类。电力传输PD元件通常由两个或更多终端组成基本功能是从一点向其他点运送电能最典型的是线路和变压器所以它们一般是多终端电容器和电感器是例外并联入网时只有单端。电力转换PC元件把电能转换成其他形式或反过来大部分只有一个电网连接点所以是多相的单终端最典型的是发电机和负荷。这个“终端数”不是分类学上的洁癖它决定了元件往节点导纳矩阵里写什么形状的块。两端的传输元件贡献的是一个分块矩阵元件类型终端数对 Y 矩阵的贡献典型代表传输元件串联2 个及以上2×2 分块含互导纳线路、变压器传输元件并联1 个对角块只有自导纳并联电容器、电抗器转换元件1 个多相对角块 电流注入项负荷、发电机线路和变压器是线性的参数固定可以直接把导纳写进矩阵解一次线性方程就出结果。负荷不是线性的——恒功率负荷的电流随电压变化写成导纳就等于假装它是恒阻抗结果会偏。常见的实现思路是把负荷处理成电流注入先假定一个电压算出当前功率对应的注入电流解一次用新电压重算电流再解直到两次电压差小于收敛阈值。这也是为什么 OpenDSS 的求解器本质上是一个迭代过程而不是一次 LU 分解就收工。理解这一点手册里“这个软件接近于谐波分析软件或动态软件而不是一般意义上的潮流计算软件”这句话就落到了实处。谐波分析和动态仿真天生就要处理频率相关、时变、非线性的元件它们的求解框架本来就是“注入电流 迭代”。反过来用谐波工具解正常潮流是容易的用正常潮流工具解谐波则要伤筋动骨。这是一次单向的降维兼容。2.3 辅助元件把参数从硬编码里解放出来辅助元件是这套模型里最容易被低估的一层。它们不向 Y 矩阵 stamp 任何东西但决定了模型能不能复用、能不能时变、能不能被观察。手册列出的常用辅助元件可以按职能分成三组参数供给类LineCode定义线路类型比如阻抗LineGeometry、LineSpacing、WireData一起用从几何平均半径GMR这类基本物理参数出发推导线路参数Spectrum定义一个传输元件发出的谐波频谱。时间序列类LoadShape定义负荷曲线的相乘因子或实际 kW/kvar供时间段仿真使用。观察与控制类EnergyMeter收集一条馈线上的计量信息Monitor收集具体元件的潮流结果CapControl和RegControl模拟可控电容器和可控线路调压器。参数供给类的价值在于“一处定义、多处引用”。十条同型号线路如果每条都把 R、X、C 手写一遍改一个参数要改十处翻车概率随行数线性上升。抽成LineCode之后线路对象只持有类型引用参数变更收敛到一个点。控制类辅助元件则引入了一个外层循环这是很多人第一次用会觉得“玄学”的地方。CapControl要在求解完成后读电压、判断是否越过投切门槛、投切后修改电容器状态、再触发一次求解。所以一次完整的Solve内部可能包含多轮“求解—控制动作—再求解”直到控制不再动作或者撞上迭代上限。手册的工作流里让你先设仿真模式再解电路顺序不是仪式是因为控制动作依赖求解结果而求解模式决定结果的时间粒度。2.4 动态生成母线的代价与收益把母线降级成副产品收益和代价都很实在。收益是建模灵活度不同相数的变压器接线、非标准拓扑、特殊的负荷模型都不需要先去“申请”母线编号。传统工具里你新建一个三绕组变压器得先建三个母线对象、起三个名字、填三组基准电压然后才连线在元件中心模型里你在变压器参数里直接写busHV.1.2.3那个母线就被这句话创造出来了。代价有三个都在手册的工作流里留下了痕迹。第一没有稳定的全局节点编号矩阵规模在解析完所有元件之前是未知的。这就是为什么工作流第 3a 步要求先跑Calc Voltage bases——它负责生成母线节点列表、寻找基本电压把动态的东西固化下来。跳过这一步直接解得到的可能是全零结果。第二脚本顺序有意义。元件必须被“注册”之后才存在后面的语句才能引用它。这跟声明式配置文件不一样它更像一段可执行的建模程序。第三元件名就是身份。改名不叫改名叫新建一个对象旧名字上的引用全部悬空。这一点在拼接多个 dss 文件时特别容易出事。3. 命令即模型文本命令处理器怎么把一行字符串变成电路对象3.1 两种命令动词作用于元件与不作用于元件手册明确区分了两类命令。第一类直接作用于电路元件比如New和Edit格式是CommandVerb ElementClass.Element.Param1Val1, Param2Val2第二类不直接作用在元件上比如Plot、Export、Set、Solve格式退化成CommandVerb Param1Val1, Param2Value 2, Param3(1 2 3)常用动词就那几个New生成新元件Edit编辑指定元件Set定义仿真参数Solve在当前电路上求解Show用文本显示潮流结果Export把结果输出到文本或 CSVPlot把结果画出来。还有一个细节如果没有指明具体动词默认是Edit。这个默认值很省事也很危险——一行拼错的命令不会报“未知动词”而是被当成编辑操作作用在你当前的活动元件上。为什么整套系统长成“一行一命令”的样子因为它的第一身份是一个命令处理器不是图形程序。GUI 里的每一个按钮都能翻译成等价的命令行Edit菜单下的Record Script甚至能把你在界面上做的操作录成 dss 文件。这意味着调试路径是统一的界面上点出来的问题可以在脚本里复现脚本里的问题可以逐行选中按 Ctrl-D 执行看哪一行炸。这条设计在二十年后的今天看依然是对的。3.2 参数解析逗号、空白、引号与括号数组的边界解析规则看着琐碎但每一条都对应一种真实的数据形态。参数和值可以用逗号或空白空格、制表符分开如果值本身需要分隔符就用下面这几种包裹方式包裹符含义典型用途...字符串带空格的名称、文件路径...字符串同上风格备选(...)数组一组数值空格分隔[...]数组同上{...}嵌入数学表达式需要计算的值双引号和单引号都表示字符串功能上可互换但手册鼓励遵循标准格式别混着来。理由很实际解析器要在“这是分隔符”和“这是值的一部分”之间做判断引号是最省事的边界标记。数组用小括号或中括号包住内部再用空白分隔这样就避免了和参数之间的逗号打架。大括号更特殊它表示这里不是字面量而是一个要现场求值的数学表达式——参数化建模的入口。命名规则同样有讲究。元件的全名是ElementClass.ElementName格式属性的全名是ElementClass.ElementName.PropertyName。当同一条命令连续作用于同一个元件的不同属性时除第一个之外其他属性不需要写全名。这就是为什么手册里的例子写成New Line.L1 Bus1SourceBus.1.2.3 Bus2LoadBus.1.2.3 Phases3 Length1 Edit Line.L1 R10.058 X10.12 C13.4第二条命令里的R1、X1、C1都省略了Line.L1.前缀。代价是一旦你切了活动上下文却没意识到这些短名会安静地作用到错误的元件上。血泪经验是跨文件、跨段落编辑时宁可把全名写满多敲十几个字符比事后追一个“参数改了没效果”的 bug 便宜太多。3.3 多行命令与外部文件包含编译期与运行期的分界手册提到文本可以通过三种途径进入系统在程序窗口里选中执行、通过 COM 接口传字符串、或者用Compile、Redirect从标准文本文件读入。前两种是“一条一条喂”第三种是“整包读”。这里有个必须分清的区别我一般会这么理解Compile是重置式的它先清空当前的电路定义再把目标文件当成一个完整电路重新构建相当于“打开一个新工程”Redirect是插入式的它在当前上下文里把文件内容逐行执行相当于 C 语言里的#include共享同一个命名空间和同一套已定义的对象。这个区别直接决定了工程怎么组织。常见的做法是拆成三层底层是元件库文件各种LineCode、LoadShape、Spectrum定义用Redirect引入多个案例共享中层是电网本体文件描述具体的线路、变压器、负荷顶层是场景文件只负责Set仿真模式、改几个参数、Solve、Export。顶层用Compile或Redirect拉起下面的文件。如果全用Compile你在元件库里定义的东西会在下一次Compile时被清掉如果全用Redirect几次运行之间残留的对象会互相污染问题非常隐蔽。同名对象被重复定义时会发生什么是这套模型里最需要警惕的一点。因为元件名就是身份键重复定义通常表现为覆盖或者报错具体行为取决于动词和上下文。稳妥的做法是让每个元件在整条引入链上只被New一次其余地方一律Edit。3.4 一个最小可跑的电路脚本把上面这些串起来一个能跑通的最简模型长这样! 新建一个电路并命名为 DemoClear 会清掉之前所有定义 Clear New Circuit.Demo basekv12.47 pu1.0 phases3 ! 定义线路类型单位长度的正序阻抗与容抗 New LineCode.LC1 nphases3 R10.058 X10.12 C13.4 unitskm ! 用上面定义的类型建一条线路两端都是三相母线 New Line.L1 bus1SourceBus.1.2.3 bus2LoadBus.1.2.3 linecodeLC1 length1.0 ! 建一个三相恒功率负荷接在 LoadBus 上 New Load.LD1 bus1LoadBus.1.2.3 phases3 connwye kV7.2 kW1500 pf0.95 ! 先算电压基准生成母线节点列表 Calc VoltageBases ! 设定为快照模式单点潮流然后求解 Set modesnapshot Solve ! 输出结果汇总、线路损耗、母线电压到 csv Show Summary Export Losses Export Voltages逐段说明。Clear是后悔药先把残留对象扫干净避免上一轮实验的元件悄悄影响这一轮。New Circuit是唯一一个必须存在的元件它携带基准电压basekv和标幺基准pu后面所有标幺换算都以它为准。LineCode定义了R1/X1/C1注意unitskm决定了length的单位这个字段漏写会让阻抗差三个数量级。New Line用linecodeLC1引用类型bus1/bus2后面跟.1.2.3明确指定三相节点。负荷的connwye和kV7.2是相电压kW是三相总功率这几个字段配合错了不会报错只会给你一个看起来合理的错误答案。Calc VoltageBases那行是最容易被删掉的。删掉它直接Solve很多时候也能跑出数但那是运气——一旦元件里有变压器或者混合电压等级基准电压没建立标幺换算就是错的。4. COM 接口为什么一个仿真内核要把自己降级成 DLL4.1 Text 接口最短路径的字符串通道手册对 COM 接口的定位说得很直白开发者无法预测使用者的所有需求所以留一个口子让 DSS 作为 DLL 被别的程序调用。而在这个口子里最底层、最万能、也最不优雅的一层是 Text 接口。它的形态简单到近乎粗暴外部程序把一个命令字符串交给 DSS 的命令处理器效果和在 GUI 主窗口里敲下这行字、按 Ctrl-D 完全一致。没有强类型的对象模型没有编译期检查参数是字符串错了就运行时出错。常见的实现思路是DSS 对外暴露一个默认接口其中有个属性专门接收命令文本赋值即执行。为什么保留这么“原始”的一层因为它是稳定性的下限。GUI 能做的事Text 接口都能做未来加了新元件、新命令Text 接口不用改一行代码就自动支持。上层那些强类型的封装反而容易过期。所以你会看到一个有意思的分层Text 接口负责表达“做什么”Circuit 和 Solution 接口负责表达“查什么、取什么”。4.2 Circuit 接口与 Solution 接口的分工手册的目录里把这两个接口分开讲分工其实对应了模型和算法两个层面。Circuit 接口面向电路本身设置活动元件set active element、按类别枚举元件集合负荷、线路、变压器等容器、读取元件属性。它是“模型态”的入口。你在脚本里写Edit Line.L1 R10.1等价于先SetActiveElement(Line.L1)再改属性。区别在于脚本里你写元件全名让解析器去查接口里你拿到的可能是一个元件句柄绕过字符串解析速度更快也更容易批量遍历。Solution 接口面向求解过程触发求解、读取当前仿真模式、负荷倍率、频率、迭代次数、是否收敛。它是“运行态”的入口。凡是跟“这一次解出来是什么”相关的问题答案都从这里取。这个分层带来的一个硬性约束是避坑章节要重点讲的必须先 Solve再取结果。模型态的数据元件参数随时可读运行态的数据电压、电流、功率是上一次求解的产物。没解就取拿到的是零或者上一轮的残值而且不报错。4.3 跨语言调用VB、MATLAB、Python 各自在做什么手册给了三个例子覆盖了三种典型的宿主环境。它们的语法不同但骨子里做的是同一件事拿到 DSS 对象 → 传命令建模型 → 调用求解 → 取结果。Python 的写法大致是这样# 通过 COM 拿到 DSS 引擎对象ProgID 形如 OpenDSSEngine.DSS import win32com.client dss win32com.client.Dispatch(OpenDSSEngine.DSS) # Text 接口把建模命令当字符串喂进去等价于在 GUI 里逐行执行 dss.Text.Command Clear dss.Text.Command New Circuit.Demo basekv12.47 pu1.0 phases3 dss.Text.Command New LineCode.LC1 nphases3 R10.058 X10.12 unitskm # 也可以一次性编译整个脚本文件省掉逐行拼接 dss.Text.Command rCompile C:\cases\demo\master.dss # Solution 接口设定模式并求解 dss.Solution.Mode 0 # 0 通常对应快照模式具体取值以当前版本帮助为准 dss.Solution.Solve() # 求解之后再取运行态数据顺序不能反 converged dss.Solution.Converged iters dss.Solution.Iterations print(converged:, converged, iterations:, iters)几个参数值得点出来。dss.Text.Command是写属性赋值即执行没有返回值所以出错只能靠后续状态判断这是它不如强类型接口舒服的地方。dss.Solution.Mode用整数枚举具体数值和模式的对应关系一定要查当前版本的帮助不同版本可能有增补硬编码一个数字然后疑惑“为什么模式不对”是常见翻车点。Converged和Iterations是判断求解质量的唯一依据尤其是带控制的场景Converged为真不代表控制收敛还得看控制迭代有没有撞上限。MATLAB 那边的形态几乎一样只是对象获取和属性访问语法不同本质仍是“字符串进数据出”。VB 的例子则更贴近 COM 的原生形态能直接看到接口方法的调用签名。三者的差别只在宿主语言的胶水层模型和算法一行没变——这正是把内核做成 DLL 的价值它不绑定任何一门语言的生态。4.4 求解模式与时间尺度从快照到一年 8760 点手册列出的内嵌仿真模式包括帧计算snapshot、天计算daily、年计算yearly、谐波分析harmonic、动态分析dynamic、故障短路分析fault、Monte Carlo 故障分析M1、M2、M3等等并说明这些模式是开发者在不同研究项目中需要而先后加入的。把这些模式排一下能看出一条清晰的时间尺度梯度模式时间跨度本质在做什么snapshot单点一次稳态潮流等价于传统潮流计算daily24 小时按步长推进每步套用 LoadShapeyearly8760 小时同上跨度拉满一年harmonic频域在基波解上叠加各次谐波频谱dynamic短时间尺度引入状态量逐时步推进fault事件在指定位置施加故障扫描故障阻抗或位置Monte Carlo M1/M2/M3统计逐级增加随机化维度的三档变体这里最值得琢磨的是“同一套模型能横跨这么多尺度”这件事。之所以能是因为底层统一成“注入电流 迭代求解 时间步推进”的框架不同模式只是换了外层的驱动器snapshot 的驱动器跑一圈就停daily 的驱动器跑 24 圈并且每圈改一次负荷倍率harmonic 的驱动器换一个频率再解一遍。手册说这个软件“设计有良好的可扩充性可进行修改升级以适应未来需求”落地到代码层面就是这个意思——加一种新模式主要是写一个新的外层驱动核心求解器不用动。Monte Carlo 那三个档位M1、M2、M3在手册里只列了名字没有展开我一般会这么理解它们是把随机性分层次引入从单一参数的随机抽样到多参数组合抽样再到拓扑或元件状态的随机化逐级增加复杂度。具体每档随机化哪些量得以手册正文和帮助文件为准别凭名字猜。5. 避坑与排查那些让脚本跑出“玄学结果”的地方5.1 现象电压全是零或者标幺值离谱现象脚本跑完Solve没报错Export Voltages出来的电压要么全 0要么量级差了三四倍但潮流看起来“收敛”了。原因跳过了Calc VoltageBases。母线是动态生成的节点列表和基本电压要等这一步才算出来。在这之前标幺换算没有基准元件提交的导纳和注入电流都建立在错误的基准上。元件里只要有一个变压器或者混合电压等级错误就会被放大。解决把Calc VoltageBases固定放在所有元件定义之后、Solve之前。养成肌肉记忆只要模型里出现了第二个电压等级就必须有这一行。排查时可以先Show buses看母线节点列表和基准电压是否合理再看电压结果。5.2 现象改了参数结果一点没变现象Edit了一行把某个线路的R1从 0.058 改成 0.2重跑损耗曲线跟之前一模一样。原因有三种按概率排序。第一活动元件上下文不对那行Edit用了短属性名实际改到了另一个元件上。第二对象名写错或者大小写不匹配虽然语言本身不区分大小写但你自己写的引用链上可能有个拼写错误Edit找不到目标被当成默认动词静默处理。第三改了参数但没有重新Solve读到的是上一轮结果。解决跨段落编辑一律写全名ElementClass.ElementName.Property改完立刻Show对应元件确认属性已生效把Solve和取结果的顺序固定成模板不要在中途插读取语句。5.3 现象数组参数只生效了第一个值现象给某个元件传一组数值比如三相的负荷功率或者一组时间点结果只有第一个值起作用后面的像是被吞了。原因分隔符和包裹符没配好。参数之间用逗号或空白分隔数组要用小括号或中括号包住字符串要加引号。少一层括号解析器就把后面几个值当成了新的参数名去匹配匹配不上就丢掉。解决凡是多值参数一律用括号包起来写成Param(1 2 3)这种形式凡是带空格或特殊符号的字符串值一律加引号。写完先Show一下元件看属性回显是不是你以为的那几个值。这一步花十秒能省掉半小时的怀疑人生。5.4 现象daily 模式跑出来是一条直线现象Set modedaily跑完发现 24 个小时的功率曲线完全平直LoadShape明明定义了。原因曲线定义了但没绑定。LoadShape只是一个独立对象负荷要显式引用它才会生效另外Set mode之后如果没有重新Solve拿到的还是上一次 snapshot 的结果。还有一种情况是时间步长和曲线的点数对不上采样时被插值或者截断成了常数。解决检查负荷对象上有没有指向LoadShape的引用字段确认Set modedaily之后确实执行了Solve把LoadShape的点数和步长换算一遍确保覆盖 24 小时。排查时先Export一条形状曲线出来看原始数据再对比仿真结果两头一对就知道断在哪。5.5 现象COM 调用取回来的全是零现象Python 或 MATLAB 里建完模型、调了求解、取电压拿到的数组全是 0也没有异常抛出。原因求解没有真正执行或者取数的时机在求解之前。COM 是字符串和属性驱动的没有编译期检查调用失败往往不抛异常只是安静地什么都不做。另一种可能是Compile拉起脚本时路径没对模型根本没建起来求解器面对一个空电路也能返回“成功”。解决每次求解后强制检查收敛标志和迭代次数不收敛就打印日志取数前打印一次元件数量确认模型真的存在把Text.Command的每一行都打日志出问题时能一眼看出断在第几行。这套检查看着啰嗦但它是唯一的黑匣子。6. 设计取舍把“母线中心”换成“元件中心”代价到底落在谁头上这套模型的取舍可以用一句话概括牺牲了全局索引的确定性换来了建模的自由度。母线中心的好处是简单。所有母线先建好编号固定矩阵规模已知元件只是在预分配的格子里填数。调试的时候母线编号就是矩阵下标看到第 7 号母线电压异常直接去第 7 行找原因。这种确定性对教科书式的算例非常友好。元件中心的代价则分散在三个地方。第一是顺序依赖脚本从上往下执行元件必须先生成后引用这让模型文件不能随便重排。第二是名字即身份改名等于新建删对象要显式做跨文件复用时命名冲突极难排查。第三是延迟计算节点列表和基准电压要到Calc VoltageBases才固化跳过它就得到一个静默的错误答案。但换来的东西也很硬。能描述任意相数、任意接线的变压器能把负荷挂成一个随频率变化的函数能让同一份模型从单点潮流一路跑到一年 8760 点、再跑到谐波和短路扫描。这些能力在母线中心的框架里不是不能做是每加一种能力都要动核心数据结构动一次就要回归测试一遍。我更愿意把这套设计理解成一种“把复杂性推到边界”的策略。核心求解器只认两件事导纳矩阵和电流注入向量。所有建模的复杂性——相数、接线、控制、时序——都被推到元件和辅助元件那一层去消化核心不感知。代价是边界层变厚用户要理解的东西变多收益是核心足够小小到可以二十年不断加新能力而不推翻重来。验证这套理解的方法很朴素拿一个三相不平衡的配网算例故意把某条线路的两个节点写反看结果是报错还是给出一个“看起来合理”的错误答案。如果它能安静地跑完并给你一条电压曲线说明节点语义确实是由元件而非母线决定的——这正是元件中心模型的性格。从那以后我每次接手一个陌生的 dss 工程都强制走一遍固定动作先Clear再按引入链顺序确认元件定义跑Calc VoltageBasesShow buses对一遍节点数和基准电压然后才允许Solve。这五步没有任何技术含量但它把最容易翻车的地方全部前置了。希望帮到你。本文还有配套的精品资源点击获取