PSCAD自定义模型核心接口：DSDYN与DSOUT从翻译到实操完整解读

做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工具先转成可编辑文本。注意表格和代码块要单独整理，避免排版混乱。

第二步：构建术语表。从说明书里挑出高频词汇，先自己定一遍翻译映射。我当时的术语表大致是这样：

术语表在每次翻译任务前都随提示词一起给模型，保证同一个词全程译法一致。

第三步：分段翻译。说明书一个章节太长，一次喂进去容易让模型注意力分散、前后术语漂移。我按小节为单位拆，每段控制在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(NEXC+1) = 0.0 ENDIF

这里的STOR(NEXC)代表第一个状态变量，STOR(NEXC+1)就是第二个，依次类推。但要注意，NEXC的值并不是从0开始，而是EMTDC根据整个工程所有控制系统状态统一分配后的当前偏移量。你只管在这个基址上叠加自己的变量序号。

STORL则是用来保存上一个时间步旧值的数组。经典的一阶欧拉积分在$DSDYN里就是这样实现的：

C--- 一阶欧拉法更新状态 --- STOR(NEXC) = STORL(NEXC) + DELT * DERIVATIVE

DELT是当前仿真步长，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那一段的状态计算里。这说明两个段落的主次关系很明确：核心逻辑在DSDYN，DSOUT只是一个忠实的数据搬运工。

6. 常见问题与避坑速查表

6.1 高频问题速查

以下这些问题是翻译完说明书后，结合我自己及身边朋友在实际使用中遇到的典型情况整理出来的速查表：

每个条目都是真实出现过的场景。特别是输出通道索引错乱那一条，当自定义元件引脚特别多时几乎必踩，一定要养成"重新生成骨架"的习惯。

6.2 翻译和建模时的个人经验补充

最后再说三个翻译和使用说明书时很难从文档里学到的点。

第一个点是翻译时不要只翻正文，代码注释和示例脚注同样重要。PSCAD官方文档里很多关键的工程细节其实藏在Fortran代码的注释行里，比如"这里必须使用前向欧拉以匹配插值机制""此变量必须在零点初始化"。这些注释如果不翻译，你很容易只理解到书面层，错过真正的实现提示。我翻译时专门要求模型把代码注释也翻译成中文并保留在代码行上方，效果比只看正文好得多。

第二个点是理解"接口变量"比背代码更重要。两份子段落的代码格式在不同PSCAD版本里会有些微差异，比如索引变量的名字可能从NEXC变成其他命名，但本质都是"系统给当前模型分配的存储位置指针"。只要理解了这个机制，换版本时改起来一点都不费劲；不理解的话，只能靠记忆硬凑，很容易在新版本里寸步难行。

第三个点是用好模型的Debug输出通道。我在开发自定义模型时，会在元件内部临时多建几个输出通道，专门把中间计算量（比如导数、误差、标志位状态）全部丢到$DSOUT里。平时用不上，一旦仿真出问题，就能像看示波器一样看到模型内部到底哪一步出了问题。调试完再把多余通道删掉，成本几乎为零但收益非常大。

我自己在阅读、翻译和验证这全套流程走下来，最大的体会是：PSCAD自定义模型的文档说难也不难，真正的门槛在于把英文术语和Fortran代码机制映射到实际工程行为上。DeepSeek这类工具恰恰把"术语映射"和"代码保护"这两件事做得很顺手，再配合PSCAD自带例程的交叉验证，完全能把官方文档变成一本可靠的中文操作手册。如果你最近也在被某个自定义模型的DSDYN段折磨，不妨按这个思路试试。