做PSCAD自定义模型Custom Model的人早晚都会撞上dsdyn和dsout这两个名字。它们藏在PSCAD自动生成的Fortran文件里是打通自定义模型与EMTDC仿真内核的两道关卡。前段时间我在搭MMC自定义模型啃官方《EMTDC User Guide》啃到这两段子程序时被大段英文技术描述折腾得够呛后来干脆用DeepSeek把相关说明书章节翻译出来再对着PSCAD自带例程一行行验证总算是把这两个接口彻底搞明白了。这篇就把翻译成果和实操解读一起整理出来给同样在做PSCAD自定义模型的朋友做个参考。1. 为什么要啃这份说明书PSCAD自定义模型的地基1.1 一个实际场景把我推到文档面前PSCAD自带的Master Library库里元件已经相当丰富电机、变压器、输电线路、HVDC换流器都有现成模块。但真到了做研究的时候几乎每个人都会撞到同一个天花板需要建模的对象在库里找不到直接能用的元件。我做MMC模块化多电平换流器的电磁暂态仿真时就遇到这个问题。MMC每个桥臂动辄几十上百个子模块如果用库里的IGBT阀组元胞去逐个搭仿真会慢到让人怀疑人生。可行的路就是把整个桥臂或者子模块的等效逻辑封装成自定义元件把电容电压均衡、桥臂聚合、触发脉冲生成这些计算都写进自定义模型里。这个时候你避不开的就是PSCAD自定义模型背后的Fortran代码而代码里最关键的两段就是DSDYN和DSOUT。PSCAD官方手册里对这两段子程序的说明分散在《EMTDC User Guide》的Custom Model章节里写得其实挺细但英文原文加上大量Fortran代码片段阅读门槛不低。我一开始尝试直接对着英文写结果状态数组的存取方式、输出通道的映射规则这些关键细节反复看几遍都容易搞混。后来决定用DeepSeek分批翻译再人工对照例程验证这才把文档里的坑一条条理顺。1.2 DSDYN和DSOUT在自定义模型里到底是什么角色先给不熟悉PSCAD自定义模型结构的读者打个底。PSCAD里面新建一个自定义元件后会自动生成一份Fortran代码骨架里面预留了若干段落Section最常见的是$DSDYN和$DSOUT。这两个名字其实是EMTDC仿真内核和用户模型之间的接口约定。$DSDYN段落承载的是模型每个时间步内的动态行为和状态更新。换句话说仿真时钟每走一步EMTDC都会调用一次$DSDYN里的代码让模型根据当前输入、前一步的状态、以及计算出的网络变量去更新自己的内部状态。所有需要积分记忆迭代的东西基本都放在这一段。$DSOUT段落则负责把模型算出来的关键信号交出去。PSCAD中的Output Channel、Online Plot、RMS表计、FFT分析等后处理工具都要靠$DSOUT把数值上传到输出数组里才能被上层界面采集和绘制。用一个生活化的类比$DSDYN是发动机负责在每个仿真步长里把状态往前推$DSOUT是仪表盘把发动机的状态亮给驾驶员看。两个角色相互配合但功能和分工完全不同。搞反了、混用了轻则输出信号乱跳重则编译报错或者仿真发散。2. 翻译方案怎么选为什么最后落在DeepSeek上2.1 试过的几条路网页翻译、术语表、DeepSeek API既然决定要把说明书啃下来摆在我面前的有几条路。第一条是最省事的把PDF英文原文贴进网页翻译工具。结果很直观——英文日常句子翻得还行但一到技术环节就露馅。比如dead band被翻成死带state variable被翻成状态改变量更麻烦的是Fortran代码被强行改动变量名、函数调用都被翻译了这种结果根本没法用来指导写代码。网页翻译工具没有电力系统领域的上下文碰到专业术语基本靠猜。第二条路是自己逐段硬翻。效果固然最准确但那份说明文档内容上百页人工逐句翻译耗时太长。我当时的核心目标其实是快速理解接口机制不是做学术翻译投入产出比太低。第三条路就是用DeepSeek这类大模型来做专业领域辅助翻译。我选择它的理由很直接一是上下文理解能力强给它喂一段带Fortran代码的说明文字它能区分哪些是代码、哪些是注释、哪些是自然语言描述二是可控性好可以在提示词里强制要求术语保留英文原文、代码原样输出三是API可以批量处理多个章节长文档翻完能汇总成一个还算一致的Result文件。实际用下来大模型翻译最大的价值不在词汇查得好而在保持术语一致和保留代码结构这两点上。只要提示词约束到位它能很稳定地把SUBROUTINE、STOR(NEXC)、IOUT(1)这些代码元素原封不动地保留下来只翻译解释性文字。2.2 面向说明书的提示词与处理流程翻译不是把文字丢进去就完事。我整理出来一套适合PSCAD官方文档的处理流程大致五步第一步提取文本。PDF里的文字如果能直接复制最好复制不了就用OCR工具先转成可编辑文本。注意表格和代码块要单独整理避免排版混乱。第二步构建术语表。从说明书里挑出高频词汇先自己定一遍翻译映射。我当时的术语表大致是这样英文术语中文译法备注state variable状态变量不译成状态改变量time step / DELT仿真步长单位秒dead band死区控制环节的滞回区间interface variable接口变量用户模型与EMTDC交互的量interpolation插值电磁暂态中的数值插值shunt并联支路也指分流电路flag标志位布尔型控制标记lookup table查表分段函数查值output channel输出通道与DSOUT映射相关dynamic state动态状态需要在DSDYN中更新的状态术语表在每次翻译任务前都随提示词一起给模型保证同一个词全程译法一致。第三步分段翻译。说明书一个章节太长一次喂进去容易让模型注意力分散、前后术语漂移。我按小节为单位拆每段控制在2000字以内并且让相邻段落之间保留一小段重叠内容比如上一段末尾的代码块在下一段开头也出现这样模型能回忆起上文语境。第四步代码保护。这一条极其重要。我使用的提示词明确要求Fortran代码、变量名、函数名、数字常量一律原样保留禁止翻译、重命名、格式化。只翻译自然语言句子和注释文字。实测下来只要加了这句约束代码块的完整性基本有保障。第五步汇总校对。把翻译结果按原文顺序拼接逐条与英文原文对照。重点检查三段内容新出现的术语是否与术语表一致、代码块是否被意外改动、数学公式和单位是否正确。下面是我反复使用的提示词模板供参考你是一名电力系统仿真领域的资深工程师。请把下面这段PSCAD/EMTDC官方说明文档翻译成中文。 要求 1. Fortran代码、变量名、函数名、数字常量原样保留禁止翻译或重命名。 2. 专业术语第一次出现时在括号中标注英文原文。 3. 只翻译自然语言句子和代码注释不额外添加解释。 4. 保持原文的段落结构代码块用markdown代码块包好。 5. 术语表如下state variable状态变量time step仿真步长dead band死区…… 文档内容 [粘贴原文]这套流程跑下来整个Custom Model章节花了一个多晚上就翻译完后面再对着英文原文校对的时候基本只需要关注专业术语和描述性句子省了大量时间。2.3 翻译中的术语保护与代码校验翻译只是第一步关键还是看翻译结果能不能指导实际建模。我当时给自己定了一个校验方法拿PSCAD自带例程来反译验证。PSCAD安装目录的Examples里有很多现成工程其中一部分自定义元件比如一些教学用的控制器、电机模型内部就有$DSDYN和$DSOUT段落。我会把翻译文档里的规则描述和这些真实代码对照文档说状态变量应在TIME等于0时初始化那就去例程里看是不是真有IF (TIME .EQ. 0.0)开头的初始化语句文档说DSOUT里只能对输出通道赋值不应做重计算那就去看例程的DSOUT段落是不是只有赋值语句。这样交叉验证过翻译内容的可信度就高很多。也正因为如此后面对这两段的拆解我基本可以确定是贴合PSCAD实际行为的。3. dsdyn子程序原文核心内容拆解3.1 dsdyn在EMTDC求解流程中的位置EMTDC采用的是时域逐时间步的仿真方式。一个仿真时间步里EMTDC要完成交流系统的网络求解、控制系统的更新、插值事件处理等多件事。自定义元件的$DSDYN就插在控制系统更新这一环里。更具体一点说$DSDYN的调用位置在整个求解顺序中比较靠前它负责在步长开始阶段根据上一已知量计算出当前步的驱动量这些驱动量随后会被用于更新网络解和输出。因此我在阅读说明书后有一个重要的理解$DSDYN里的代码执行顺序和模型在电路中的连接顺序无关它更依赖于你内部逻辑的正确性。这个位置关系决定了我们写代码时的两个习惯一是不要把复杂迭代放在$DSDYN里。网络求解本身是EMTDC通过节点导纳矩阵完成的$DSDYN中做太多牛顿迭代或者循环逼近会拖慢每步仿真而且可能和EMTDC的插值机制产生冲突。二是$DSDYN依赖前一步状态。这意味着处理好状态存储是正确仿真的前提——你需要的所有记忆量必须显式地存进状态数组而不是依赖局部变量。因为每次调用结束后这些局部变量就丢了。3.2 关键调用STORE、STORL与状态初始化$DSDYN里最常打交道的是几个以STOR开头的存储机制。说明书里的核心概念是状态数组。EMTDC为每个自定义模型分配了一段连续的存储空间通过索引来访问。索引本身由系统通过变量比如NEXC传递过来用户代码不需要关心具体地址只要按照系统给的位置去读写就行。初始化通常这样写$DSDYN C--- 状态变量初始化 --- IF (TIME .EQ. 0.0) THEN STOR(NEXC) 0.0 STOR(NEXC1) 0.0 ENDIF这里的STOR(NEXC)代表第一个状态变量STOR(NEXC1)就是第二个依次类推。但要注意NEXC的值并不是从0开始而是EMTDC根据整个工程所有控制系统状态统一分配后的当前偏移量。你只管在这个基址上叠加自己的变量序号。STORL则是用来保存上一个时间步旧值的数组。经典的一阶欧拉积分在$DSDYN里就是这样实现的C--- 一阶欧拉法更新状态 --- STOR(NEXC) STORL(NEXC) DELT * DERIVATIVEDELT是当前仿真步长DERIVATIVE是你由输入量和当前状态计算出的导数。这种写法逻辑清晰状态在存储数组里自然迭代和说明书里强调的动态状态概念完全吻合。这里需要特别注意状态变量必须初始化。如果某个状态量初始化条件没覆盖到比如只在TIME .EQ. 0.0时赋初值但第一次调用时TIME因为仿真起止时间设置的原因不是0而是0.0001那初始化就会被跳过后续仿真就直接放飞自我了。稳妥的做法是用TIME .LE. 0.0或者显式判断IF (TIME .LT. DELT)。3.3 从翻译文档中提炼的dsdyn编写要点结合翻译内容和实际调试经验我提炼出以下几个$DSDYN的编写要点第一保证纯计算逻辑。$DSDYN里只做数值计算和状态更新。不要在段落里写文件输入输出、调用外部命令、声明大规模临时数组这些都会在每次仿真步长被反复调用时拖垮性能有些甚至导致编译失败。第二用系统变量而不是自定义全局变量。不同自定义模型之间的数据共享应该通过PSCAD提供的通道或公共变量机制实现不要在Fortran里自行开COMMON块去跨模型传数据否则工程移植很容易出问题。第三注意时间判断的写法。说明书里的例程经常用TIME .EQ. 0.0来定位初始时刻。实际仿真中如果初始时间不是0或者数值精度导致判断失败初始化代码可能不执行。我的经验是用一个标志位或更宽松的时间判断C--- 更稳妥的初始化写法 --- IF (.NOT. INITDONE) THEN STOR(NEXC) 0.0 INITDONE .TRUE. ENDIF把标志位作为自定义元件的参数或公共变量保存。第四处理好与输入量的关系。如果$DSDYN里需要用到从外部电路采样的电压电流值确认这些采样变量在自定义模型的定义中已经声明为Input类型。漏声明的话Fortran编译阶段就会报未定义变量。4. dsout子程序原文核心内容拆解4.1 输出通道与信号命名规则$DSOUT段落做的事情比$DSDYN简单得多但重要性一点都不低。它的核心任务是把模型内部数值上传到PSCAD的输出系统里让用户能在面板上看到波形、控件或者参与后续的逻辑判断。PSCAD自定义模型的输出通道Output Channel在定义界面里就确定了。你一定先添加了输出变量生成了对应的输出通道并给符号命名。$DSOUT里的代码就是给这些通道赋值。赋值方式最常用的是给ROUT、IOUT、LOUT这些输出数组写入数值。比如你在模型定义里建了两个输出一个要输出有功功率一个要输出状态变量状态值那在$DSOUT里就会看到类似这样的代码$DSOUT C--- 输出映射 --- ROUT(1) P_MEASURED ROUT(2) STOR(NEXC)这里的ROUT(1)对应定义界面里的第一个输出通道ROUT(2)对应第二个单纯按顺序映射。IOUT用于整数信号LOUT用于逻辑信号。不必在$DSOUT里面做大计算量处理因为这是纯赋值环节。如果需要在输出前做滤波、缩放、单位转换之类应当在$DSDYN里完成然后把准备输出的值传递过来。这一点说明书里虽然没有明令禁止但从性能和逻辑清晰度考虑都是最佳做法。4.2 典型IOUT配置案例我实际在做MMC控制模型时用过一个很典型的$DSOUT配置。模型内部计算出了如下关键量桥臂电流的瞬时值子模块电容电压聚合值触发脉冲状态一个用于调试的故障标志位这些量在自定义元件定义界面分别建立了4个输出通道。那么在$DSOUT里对应的写法是$DSOUT C--- 输出桥臂电流和电容电压 --- ROUT(1) I_ARM ROUT(2) VC_SUM C--- 输出触发脉冲状态0/1 --- IOUT(1) INT(PULSE_STATE) C--- 输出故障标志 --- LOUT(1) FAULT_FLAG这里能看出PSCAD输出机制的几个特点第一不同数据类型的输出通道是分开管理的不能用ROUT去传逻辑量也不能用IOUT传浮点量否则类型不匹配会把编译搞挂。第二输出通道的顺序一定要和元件引脚定义时建立的顺序一一对应。如果在元件定义界面里调整过输出顺序回代码里改ROUT索引时很容易混乱最稳妥的方式是重新生成代码骨架再填入逻辑而不是手动去猜第几个输出对应哪个引脚。第三如果某个输出通道没有在$DSOUT里被赋值PSCAD运行时通常不会报错但波形通道会显示常值或零值。排查输出异常时优先检查是不是漏了映射。4.3 与dsdyn协同时的常见误区翻译完说明书的最大收获是搞清楚了$DSDYN和$DSOUT的分工边界。我见过不少刚上手的朋友在这两个段落之间踩坑最常见的有三类误区一在DSOUT里更新状态。有人觉得反正每个时间步两个段落都会执行顺手在$DSOUT里改一下STOR(NEXC)行不行答案是不行。EMTDC对状态数组的更新逻辑和输出阶段是有区分的。在输出阶段修改状态会产生不可预计的顺序问题不同PSCAD版本里的执行顺序可能还不一样结果就是同一模型换个版本仿真结果就飘了。状态更新一律放在DSDYN。误区二只建输出通道不处理状态。有些模型其实不需要动态状态比如一个纯代数变换的模块。但如果不小心给元件定义了内部状态变量却在$DSDYN里完全没初始化、没更新那么$DSOUT里读到的就是一个永远不会被更新的值。这种情况表面看不出编译错误但波形对不上排查起来很隐蔽。误区三输出映射顺序混乱。当你反复增删输出通道时很容易在多个自定义模型之间复制粘贴代码导致ROUT索引和实际引脚定义对不上。最直白的排查方法在$DSOUT里加一个临时赋值语句比如ROUT(1) 100.0然后跑一小段仿真看第1个输出通道是不是显示100。如果是说明映射正确如果第1个通道显示别的值那引脚和索引的对应关系已经乱了。5. 实操用一个最小模型走通整个流程5.1 在PSCAD中新建自定义模型的步骤拿一个最简单的RL动态元件为例我带你走一遍完整流程。这个元件输入是端口电压内部有一个电感的动态状态需要积分更新输出是电流和电感磁链。第一步在PSCAD工程里右键选择新建自定义元件或者在Master Library里新建一个Custom Model定义。填入元件名称比如RL_DYN设置状态变量数量这里是1、输入量数量电压、输出量数量电流和磁链。第二步在元件定义界面里画好元件符号添加输入的电压端口和输出的信号引脚。每个信号引脚都对应一个输出通道后面$DSOUT里的ROUT索引顺序就是按照这里定义的引脚顺序来排的。第三步打开元件对应的Fortran文件。PSCAD会生成一个初始骨架里面有变量声明区和各段落。你要做的就是往$DSDYN和$DSOUT里填代码。5.2 Fortran代码实现我写的代码大致如下$DSDYN C--- RL动态元件状态更新 --- C--- 状态变量电感电流 IL --- IF (TIME .LE. 0.0) THEN C--- 初始电流为0 --- STOR(NEXC) 0.0 ENDIF C--- 微分方程: dIL/dt (V_IN - R*IL) / L --- DERIV (V_IN - R_PARAM * STOR(NEXC)) / L_PARAM C--- 使用前向欧拉进行积分更新 --- STOR(NEXC) STORL(NEXC) DELT * DERIV这里的V_IN是元件输入端口测得的电压R_PARAM和L_PARAM是元件参数需要在定义界面里配置成可调参数。$DSOUT C--- 输出电流和磁链 --- ROUT(1) STOR(NEXC) ROUT(2) L_PARAM * STOR(NEXC)第1个输出通道是电感电流第2个输出通道是磁链。写完之后在元件定义界面点击编译。如果一切正常Fortran编译器会将自定义模型链接进工程随后就能在仿真主电路中拖入RL_DYN元件进行测试。5.3 编译报错排查实录第一次编译这个模型时我遇到过两个报错这里记录一下排查过程。第一个报错是STOR未定义。当时我写的代码里直接用了STOR(NEXC)但生成的骨架代码里状态数组被封装在EMTDC提供的公共块中通常需要通过INCLUDE引入相关头文件或者使用系统生成接口来访问。报错信息指向未声明变量。解决方案是不要手动声明STOR而是确认代码骨架自带的变量声明部分没被误删如果误删了就从备份骨架或者新生成一个元件对比恢复。第二个报错提示是NEXC没有定义。这类索引变量通常是在EMTDC调用自定义模型时自动传入的均位于PSCAD自动生成的代码段中。我在编辑代码时复制粘贴别人的代码把骨架中的公共块声明覆盖掉了导致索引变量失去定义。教训是不要大范围删除骨架自带的声明区只往段落里填逻辑。5.4 仿真结果验证编译通过后把RL_DYN元件接在一个交流电压源后面负载接地。跑一小段暂态仿真再用Online Plot把输出电流通道拉出来看到的电流波形应该符合RL电路指数上升特征。我用这个极小模型把两个接口都验证过一遍发现只要$DSDYN的状态更新正确$DSOUT的波形读取自然就正常。反过来如果波形异常排查路径也基本锁定在$DSDYN那一段的状态计算里。这说明两个段落的主次关系很明确核心逻辑在DSDYNDSOUT只是一个忠实的数据搬运工。6. 常见问题与避坑速查表6.1 高频问题速查以下这些问题是翻译完说明书后结合我自己及身边朋友在实际使用中遇到的典型情况整理出来的速查表现象可能原因排查与解决方法编译报错STOR或NEXC未定义骨架声明区被误删或覆盖新生成一个空自定义模型对比恢复声明区仿真一开始状态就发散状态变量未初始化或初始化条件没触发用TIME .LE. 0.0或标志位初始化波形一直是0但模型明明有输出$DSOUT漏了赋值或输出通道索引顺序错乱临时赋固定值测试通道映射确认ROUT索引输出波形正常但数值偏大单位换算或参数缩放没做检查参数定义界面的单位倍率设置修改输出引脚顺序后波形乱ROUT索引和引脚定义顺序不对应重新生成代码骨架或逐个通道调试DSDYN内使用文件读写后仿真变慢每步都执行I/O操作移出DSDYN改用PSCAD事件机制一次性处理与其它自定义模型之间数据不同步用了局部临时变量跨模型传数据改用PSCAD的公共变量或Index引用机制每个条目都是真实出现过的场景。特别是输出通道索引错乱那一条当自定义元件引脚特别多时几乎必踩一定要养成重新生成骨架的习惯。6.2 翻译和建模时的个人经验补充最后再说三个翻译和使用说明书时很难从文档里学到的点。第一个点是翻译时不要只翻正文代码注释和示例脚注同样重要。PSCAD官方文档里很多关键的工程细节其实藏在Fortran代码的注释行里比如这里必须使用前向欧拉以匹配插值机制此变量必须在零点初始化。这些注释如果不翻译你很容易只理解到书面层错过真正的实现提示。我翻译时专门要求模型把代码注释也翻译成中文并保留在代码行上方效果比只看正文好得多。第二个点是理解接口变量比背代码更重要。两份子段落的代码格式在不同PSCAD版本里会有些微差异比如索引变量的名字可能从NEXC变成其他命名但本质都是系统给当前模型分配的存储位置指针。只要理解了这个机制换版本时改起来一点都不费劲不理解的话只能靠记忆硬凑很容易在新版本里寸步难行。第三个点是用好模型的Debug输出通道。我在开发自定义模型时会在元件内部临时多建几个输出通道专门把中间计算量比如导数、误差、标志位状态全部丢到$DSOUT里。平时用不上一旦仿真出问题就能像看示波器一样看到模型内部到底哪一步出了问题。调试完再把多余通道删掉成本几乎为零但收益非常大。我自己在阅读、翻译和验证这全套流程走下来最大的体会是PSCAD自定义模型的文档说难也不难真正的门槛在于把英文术语和Fortran代码机制映射到实际工程行为上。DeepSeek这类工具恰恰把术语映射和代码保护这两件事做得很顺手再配合PSCAD自带例程的交叉验证完全能把官方文档变成一本可靠的中文操作手册。如果你最近也在被某个自定义模型的DSDYN段折磨不妨按这个思路试试。