PSS/E自定义模型接口层解析：标志位、STRTIN与USRMDL

简介《PSSE自定义模型学习资料》面向电力系统动态仿真学习者及需在PSS/E中开发用户自定义模型的工程人员聚焦Fortran模型子程序编写、编译调用与调试中的常见问题帮助读者理解自定义模型从逻辑设计到接入主程序的实现路径。压缩包仅含1个doc文件约27KB内容围绕动态仿真中的MODE等标志位展开说明TBLCNC、CONEC等连接子程序如何依据标志量调用模型语句并涉及动态数据输入记录格式的识读。文中还整理了与机组相关模型的子程序书写格式、STRTIN数组位置表入口含义、调用实参对应关系以及发电机、电流补偿器、励磁稳定器、励磁、汽轮机/调速器和混合模型的调用顺序。已有680人学习适合初学到进阶阶段查阅作为梳理PSS/E自定义模型接口、调用关系与排错思路的参考。1. 知识地图PSS/E 自定义模型的关键在接口层不在算法层PSS/E 自定义模型这件事第一反应往往是用 Fortran 写控制框图真写起来才发现难的并不是方程而是三张表能不能对得上。一张是标志位表MODE、KPAUSE、MSTATE、MIDTRM它们留在 PSS/E 的 COMMON 内存里框架靠这些取值决定这次调用子程序该做哪件事。一张是地址表子程序头必须写成SUBROUTINE modelname(MC, ISLOT)NC、NS、NV、NI 四个计数通过 STRTIN 换成数组首地址。还有一张是数据表动态数据输入文件里那条 USRMDL 记录字段错一个模型要么被当成内置模型读走要么根本挂不上去。三张表对齐模型才会被 TBLCNC 自动联进主框架按发电机到调速器的固定次序被调用。这张地图适合两类人已经跑通潮流、开始碰动态仿真、需要自己造模型的以及编译能过、一跑就不对想回头补接口层的。2. 标志位与行为链MODE、KPAUSE、MSTATE、MIDTRM 各自管什么这一章要解决的是模型子程序为什么长成那个样子。如果只把子程序当成一个从上往下执行的函数写出来的东西一定会在某个行为上翻车。PSS/E 的框架是事件驱动的一次动态仿真被拆成一串行为每个行为对应一个标志量取值模型子程序的任务是在不同的取值下做不同的事。把这条想通后面地址和数据文件才有地方落。2.1 四个标志位住在同一块 COMMON 内存里原始资料里那句话很轻MODE、KPAUSE、MSTATE 及 MIDTRM 留在 PSS/E 的 COMMON 内存中。这句话的分量在于共享两个字。模型子程序不是通过形参拿到这几个值而是通过 COMMON 直接读写这意味着两件事第一子程序开头不需要、也没法为它们准备实参第二任何一个分支里对它们的修改对同一进程内后续被调用的模型都是可见的。实习的时候最容易犯的错就是把 MODE 当成我传进来什么就是什么的局部变量来推理结果在一个分支里动了它下一个行为进来时读到的是被污染过的值。逐个看这四个量。MODE 是行为代码框架每次决定现在该做哪件事时把它写进去子程序按它的取值分流原文明确给出的一条对应是 STRT 行为与 MODE1 内联也就是初始化。KPAUSE 从命名和它在行为链里的位置看是和暂停、中断相关的标志用于在仿真推进过程中插入一个可干预的节点。MSTATE 与状态量STATE的处理时机相关什么时候更新、什么时候保持靠它来区分。MIDTRM 是中途处理标志处理那些不属于开头也不属于结尾、但每个阶段都要过一遍的动作。标志位大致管什么模型里通常对应什么动作漏写或写错的典型表现MODE当前行为代码按值分流初始化、进入仿真、输出等初始化能过一进仿真就发散或曲线不动KPAUSE暂停/中断节点在推进中放行或挂起卡住不动或者该停的地方直接冲过去MSTATE状态量处理时机STATE 的更新与保持初值漂移稳态点对不上MIDTRM中途处理阶段性附加计算没有报错但曲线形状对不上需要说清楚的一点原始资料只给了这四个名字和留在 COMMON 内存这一条位置信息具体取值的语义随版本和模型类型会有差别复习时以手头版本的模型说明为准别凭记忆硬编码。但有一条是硬约束——它们不属于模型的私有状态谁读谁写都要按框架的时序来不能当成自己的局部缓存。2.2 一次动态仿真是一串行为不是一个函数PSS/E 主体框架里动态仿真是以一个一个的行为串联起来的而这些行为又和内置的标志量相联系。模型子程序的写法因此被规定死了对应不同标志量的值写不同的实现语句。框架实现每个行为的过程就是根据该行为相应的标志量值通过连接子程序TBLCNC、CONEC、CONET 等去调用模型子程序里对应该值的那段语句。换句话说子程序是一次性写好的但会被反复进入很多次每次只走其中一小段。原文给的例子是 STRT进行初始化时STRT 行为与 MODE1 内联框架通过连接子程序调用模型子程序里对应 MODE1 的初始化语句。这条对应关系是整套机制的样板——行为名、标志量取值、子程序里的分支三者是一一绑定的。理解了 STRT剩下的行为只是把同样的绑定再做一遍。SUBROUTINE MYMODEL(MC, ISLOT) C MC : 本模型所连机组的 PSS/E 内部机组码 C ISLOT : 本模型在内部数组位置表中的槽位指针 INTEGER MC, ISLOT C 标志位与内部数组通过 COMMON 进入不作为形参传递 C IF (MODE .EQ. 1) THEN C STRT 行为读入 CON给 STATE 赋初值 ELSE IF (MODE .EQ. 2) THEN C 仿真推进按步长计算更新 STATE ELSE IF (MODE .EQ. 3) THEN C 输出/记录把关心的量写出去 ELSE C 兜底分支打标记便于发现没预料到的行为 END IF C IF (KPAUSE .EQ. 1) THEN C 暂停点处理 END IF RETURN END这段是结构示意不是可以直接编译的完整模型重点在骨架。第一MODE的每个分支对应一个行为分支的判断值必须和框架实际传进来的值对齐原文只明确了 MODE1 对应 STRT其余取值不要凭印象写先把框架真正传进来的值打出来对一遍。第二ELSE兜底分支不是可有可无的装饰它是你发现框架还调了一个我没考虑的行为的唯一线索。第三MC和ISLOT在子程序体里通常不直接参与运算它们是拿去查 STRTIN 的钥匙这一点下一章展开。提示调试阶段在每个分支入口加一行带计数的输出跑一个最小算例看每个分支是否至少被进入过一次。比对着代码猜要快得多。2.3 自己建一张标志位—分支对照表真正复习的时候代码本身反而没那么重要值钱的是一张自己整理的对照表。做法很简单每遇到一个行为就在表里加一行四列——行为名、触发它的标志量及取值、模型里该做的事、漏写的症状。这张表写满之后你对这个模型的理解就不再是我记得好像有这么一段而是我知道它什么时候被进、进去干什么。行为触发标志模型里要做的事用到的数组漏写的症状初始化MODE1对应 STRT读 CON给 STATE 赋初值CON、STATE初值不对稳态点偏移仿真推进MODE 的推进取值每个步长算微分、更新 STATESTATE、VAR曲线发散或不变化输出记录MODE 的输出取值把关心的量写到输出通道VAR曲线缺失或全零暂停处理KPAUSE放行或挂起无卡住或直接冲过中途处理MIDTRM阶段性附加计算VAR形状对不上但无报错这张表还有一个隐藏用途它逼你把用到的数组这一列填满。填不满说明你还没搞清楚模型到底吃哪些数据填错了后面 STRTIN 的入口一定对不上。梳理下来会发现大部分跑不通的问题在这张表上就已经暴露了根本轮不到编译器报错。3. 调用契约SUBROUTINE modelname(MC, ISLOT) 的形参与地址表接口层的第一条硬规则在这里。与机组相关的自定义模型子程序形式必须写成SUBROUTINE modelname(MC, ISLOT)这是契约不是命名风格。形参名字可以按你的习惯调整但位置、类型、含义不能变顺序颠倒或者少写一个编译可能照样过运行时拿到的机组码和槽位指针就全错位了。3.1 MC 与 ISLOT两个整型形参一个都不能改名换序按原文的定义MC 是该模型相连机组的 PSS/E 内部机组码ISLOT 是该模型调用的内部数组位置表指针。相应地与机组相关的自定义模型调用语句是CALL modelname(X, Y)其中 X 是对应 MC 的实参Y 是对应 ISLOT 的实参。也就是说框架在调用你的时候第一个位置永远放机组码第二个位置永远放槽位指针。理解这两个参数的分工比记住它们的名字更重要。MC 回答的是我是谁家的模型——同一条母线上挂多台机组时同一个模型子程序会被不同机组各调用一次靠 MC 区分。ISLOT 回答的是我的数据在哪儿——每个模型实例在内部数组里占一段位置ISLOT 就是这段位置的入口编号所有数组访问都要从它出发。C 正确形参顺序与含义符合契约 SUBROUTINE MYMODEL(MC, ISLOT) INTEGER MC, ISLOT C 错误示范形参顺序颠倒编译能过运行时全错位 C SUBROUTINE MYMODEL(ISLOT, MC) C 错误示范少写一个形参框架传进来的第二个实参被丢弃 C SUBROUTINE MYMODEL(MC)上面这段只是对照说明为什么这两行不能随手改。真正的模型体里MC 一般用于取本机组的量转速、机端电压之类ISLOT 用于取本模型自己的 CON、STATE、VAR、ICON 段。两个参数都声明成整型别写成REAL隐式类型转换在这类老式 Fortran 代码里不会报错只会让你查半天。3.2 STRTIN 四个入口NC、NS、NV、NI 到地址的映射在 DYRE 活动结束时与机组相关的每一个模型都会被分配好数组位置表的入口具体落在 STRTIN 这个二维数组里。四个入口的含义是固定的入口含义计数为 0 时STRTIN(1, ISLOT)模型使用的第一个 CON 的指针NC 为 0 时为 0STRTIN(2, ISLOT)模型使用的第一个 STATE 的指针NS 为 0 时为 0STRTIN(3, ISLOT)模型使用的第一个 VAR 的指针NV 为 0 时为 0STRTIN(4, ISLOT)模型使用的第一个 ICON 的指针NI 为 0 时为 0这张表最值得记的不是1 是 CON、2 是 STATE而是计数为 0 时指针为 0这一列。它意味着如果你的模型声明 NC0那么STRTIN(1, ISLOT)拿到的就是 0后面任何基于它做的下标运算都会把数据写到不该写的地方去。这类错误不会在编译期暴露运行时的表现可能是别的模型数据被莫名其妙改写查起来非常难受。拿到首地址之后的用法是标准的偏移寻址。假设模型要用第 k 个 CON写法就是首地址加 k-1C 取本模型的第一个 CON 段首地址NC0 时该值为 0不可用 ICON1 STRTIN(1, ISLOT) C 第 1 个 CON VAL1 CON(ICON1) C 第 k 个 CON首地址 k - 1 VALK CON(ICON1 K - 1) C 同理STATE 用 STRTIN(2, ISLOT)VAR 用 STRTIN(3, ISLOT) C ICON 用 STRTIN(4, ISLOT)参数说明就三句话偏移量从 0 开始算所以第 k 个元素是首地址加 k-1访问前必须先确认对应计数大于 0不同类别的数组不能互相借用入口CON 的入口拿去索引 STATE结果一定是脏数据。3.3 自动调用TBLCNC 对用户不可见意味着什么这一条是最省事、也最容易被想多了的一条。与机组相关的自定义模型在动态稳定计算时由子程序 TBLCNC 联入 PSS/E 主模块而 TBLCNC 对用户不可见。因此这类模型按规则写完之后编译通过就由 PSS/E 自动调用相应地址也由 PSS/E 自动分配用户不用手工在连接子程序里写调用语句也不用指定地址。对比一下就清楚了。与机组相关的模型走的是 TBLCNC 这条自动路径原文同时点明它不是通过 CONEC 调用的。反过来说非机组类、需要自己接进框架的自定义模型才需要在 CONEC、CONET 这类连接子程序里写明调用。两条路径的差别可以归成这样一张表对比项与机组相关的自定义模型需要手工连接的自定义模型调用入口TBLCNC对用户不可见CONEC、CONET 等连接子程序地址分配PSS/E 自动分配用户自己指定是否写 CALL 语句不需要需要写完之后的动作编译通过即可编译 连接子程序中登记很多人第一次写机组模型习惯性地去连接子程序里补一句CALL结果是同一份逻辑被调用两次输出翻倍或者状态量被算两遍症状诡异且很难往重复调用上想。判断方法很直接先确认自己的模型是不是与机组相关是的话连接子程序里就不该有它的名字。3.4 模型库的调用顺序与依赖PSS/E 模型库里模型的调用顺序是固定的发电机模型、电流补偿器模型、励磁稳定器模型、励磁模型、汽轮机/调速器模型、混合模型。这个次序不是随手排的它反映的是量的依赖——先有发电机给出的机端与内电势电流补偿器才能在其后处理电流相关的量励磁稳定器给励磁提供附加信号励磁再反过来作用于发电机汽轮机/调速器管的是机械功率侧混合模型放在最后收口。对写自定义模型的人来说这条次序的实际意义是你要先回答我这个模型属于哪一层。属于励磁环节的模型放到调速器之后的位置去考虑读到的量就是过期的属于混合模型的指望它在励磁之前被调用也不现实。梳理下来会发现调用顺序和标志位分支是一体两面顺序决定什么时候轮到我标志位决定轮到我时做什么两者对不上模型的表现就是时好时坏很难复现。注意调用顺序是模型库层面的固定次序自定义模型插进这条链时先定位它替代或补充的是哪一类模型再去对齐标志位分支不要反过来做。4. USRMDL 记录动态数据输入文件里的字段拆解模型写完了还得让程序知道有这么个模型、挂在哪儿、吃多少数据。这件事在动态数据输入文件Dynamics Data Input File里完成一条记录对应一个模型实例。这一章把这条记录拆开看重点在字段顺序和四个计数上因为这两处是纯粹的格式问题错了一点提示都不给。4.1 一条记录的字段顺序原文给出的格式是BUSID USRMDL IM modelname IC IT NI NC NS NV data list。逐个字段对下去字段含义写错会怎样BUSID模型所挂的母线标识挂错母线模型作用在别的机组上USRMDL固定关键字声明这是用户自定义模型拼错就被当成内置模型解析整条记录读飞IM机组标识同一母线上区分多台机组多机母线时张冠李戴modelname模型名必须与 Fortran 子程序名一致找不到子程序模型不生效IC模型类别描述字段分类错可能不被对应流程调用IT调用类别描述字段同上NI NC NS NV四类内部数组的计数见 4.2最危险的一组data list模型初始化用的数据段长度不够或顺序不对初值全偏一个具体的例子某台机组上挂一个调速相关模型101 USRMDL 1 MYGOV 1 0 4 6 3 2 0.05 1.20 0.30 0.10读法母线 101机组标识 1固定关键字 USRMDL模型名 MYGOV后面依次是 IC、IT、NI4、NC6、NS3、NV2再往后是数据段。这里要说清楚原始资料没有逐条解释 IC 与 IT 的取值含义从位置上看它们排在计数之前属于描述模型类别和调用类别的字段写记录时以手头版本的模型清单为准不要照抄别人的记录——版本之间、模型类型之间这两个值都可能不同。4.2 NI、NC、NS、NV 四个计数这四个计数是模型和框架之间的内存合同你声明用多少个 CON、多少个 STATE、多少个 VAR、多少个 ICONPSS/E 就按这个数给你分配数组位置STRTIN 的四个入口就是按这个分配结果写进去的。对应关系如下计数全称对应内部数组对应 STRTIN 入口NIICON整型常数STRTIN(4, ISLOT)NCCON实型常数STRTIN(1, ISLOT)NSSTATE状态量STRTIN(2, ISLOT)NVVAR中间变量STRTIN(3, ISLOT)注意记录里的书写次序是 NI、NC、NS、NV而 STRTIN 的入口次序是 NC、NS、NV、NI。两套次序不一样这是这一块最容易背串的地方抄格式的时候尤其要盯住。次序不一致带来的后果是很实在的。假设你的模型实际用了 6 个 CON、3 个 STATE、2 个 VAR、4 个 ICON正确写法是NI NC NS NV 4 6 3 2。如果按 STRTIN 的顺序写成6 3 2 4程序会认为你有 6 个 ICON、3 个 CON、2 个 STATE、4 个 VAR分配出来的地址全乱模型读到的第一个 CON 其实是别人的 STATE。这种错编译期发现不了运行时也未必报错只表现为曲线莫名其妙。第二个容易忽略的点是计数与实际用量必须严格一致不能多也不能少。多写了白占内存还会让首地址偏移影响后续模型的入口少写了代码里访问到超出声明范围的下标写坏别人的数据。STRTIN 在计数为 0 时返回 0 这一条就是给这种情况留的最后一个信号——只要你看到 0就说明这类数组根本没申请。4.3 数据段与计数的一致性检查数据段data list是模型初始化时要读进去的初值顺序和个数必须和模型里的读语句一一对应。这一步没有任何自动校验数错了就是初值错而初值错在动态仿真里往往要跑很久才看得出来。最稳的办法是手工核对三遍先数记录里数据段的个数再数子程序里读了多少个最后对照计数看总量对不对得上。记录多了以后手工数不现实可以写个小脚本来数# 核对一条 USRMDL 记录的字段个数不做内容校验 line 101 USRMDL 1 MYGOV 1 0 4 6 3 2 0.05 1.20 0.30 0.10 # 去掉引号后按空白切分模型的引号里通常不含空格 tokens line.replace(, ).split() # 前 10 个是固定字段BUSID, USRMDL, IM, modelname, IC, IT, NI, NC, NS, NV fixed, data tokens[:10], tokens[10:] ni, nc, ns, nv map(int, tokens[6:10]) # 注意次序仍是 NI NC NS NV print(模型名:, tokens[3]) print(数据段个数:, len(data), | 计数之和:, ni nc ns nv)脚本只做计数不判断数据段该有多少个——因为不同模型的数据段构成不同有的只给 CON有的连 STATE 初值一起给。它的价值在于把我数花眼了这类人为失误挡掉把注意力留给真正需要人判断的部分数据段的排列顺序是否和读语句一致。5. 易错点复盘五处最容易翻车的地方前面四章是正向梳理这一章换个方向从错的地方往回看。以下五条是这一类模型在自查时命中率最高的每一条都按易漏点是什么、为什么会漏、怎么补写可以直接当成检查表用。5.1 只写了 MODE1 一个分支易漏点子程序里只有初始化那一段其余行为没有对应语句或者写了但都塞在同一个分支里。为什么漏因为初始化能跑通稳态潮流也对得上看起来模型已经生效了。而动态仿真真正吃的是推进阶段的分支那部分没写表现是曲线一条直线或者直接发散很容易被误判成参数问题而不是代码问题。怎么补把 2.3 那张对照表填满每个行为至少有一行在没有把握的分支里加计数输出跑一个小扰动算例确认每个分支都被进入过。只要有一个行为从没被进入说明你要么分支值写错了要么这个行为根本不需要你处理——两种情况都得弄清楚不能含糊过去。5.2 计数顺序抄反NI NC NS NV 与 NC NS NV NI易漏点记录里四个计数的书写次序和 STRTIN 四个入口的次序不一致凭印象抄一遍就错位了。为什么漏这两组数字看起来就是一回事加上编译期完全不校验错了也不报错只表现为模型读到的量不对。怎么补固定一个记忆锚点——记录按字母序 NI、NC、NS、NV 写入口按 CON、STATE、VAR、ICON 排写记录时对着 4.2 那张表逐格填不凭记忆再用 4.3 的脚本把计数打出来看一眼成本很低。另外如果某个模型跑起来后第一个 CON 的值明显不像自己设的参数优先怀疑这一条。5.3 手工在连接子程序里补 CALL 和地址易漏点以为所有自定义模型都要像以前那样在 CONEC、CONET 里登记于是给机组相关模型也补了一句调用或者手工指定了数组地址。为什么漏这是从别的模型类型带过来的习惯而且多写一句看起来是保险而不是风险。实际后果是同一份逻辑被调用两次状态量被更新两遍输出翻倍症状诡异到很难往这个方向想。怎么补先给自己的模型定性——与机组相关的由 TBLCNC 自动联入地址由 PSS/E 自动分配连接子程序里不该出现它的名字不确定的时候把连接子程序里所有 CALL 语句列一遍逐个确认是不是必要的多余的删掉再跑一次对比。5.4 子程序头写歪形参顺序、个数、类型易漏点SUBROUTINE modelname(MC, ISLOT)里的两个形参被改名、换序、少写或者声明成了实型。为什么漏编译能通过因为 Fortran 对形参名的约束很松名字随便起也合法类型不匹配在旧式写法里还可能被隐式转换糊过去。怎么补把子程序头当成不可改的一行只允许在它下面写逻辑每次接手别人的模型第一件事是核对这一行如果模型行为异常但又找不到逻辑错误用调试器在入口处把 MC 和 ISLOT 的值打出来看是否符合预期——ISLOT 出现明显不合理的值基本就能定位到这里。5.5 模型放错层调用顺序与模型类型不匹配易漏点自定义模型插进调用链时没先确认它属于哪一层结果读到的量还没被算出来或者已经被后续环节改过。为什么漏调用顺序是框架层面的固定次序平时看不到也感知不到只有模型表现异常时才会想起它。怎么补写模型之前先回答一个问题——它替代或补充的是发电机、电流补偿器、励磁稳定器、励磁、汽轮机/调速器、混合模型中的哪一类定位清楚之后再对照这个位置上上游已经算完哪些量、下游还要用什么把读写的量列出来核对。这条补起来最慢但补一次能受益很久。提示这五条里有四条的共同点是编译不报错、运行不报错、结果不对。遇到这类问题排查顺序建议从格式5.2、5.4到调用5.3、5.5再到逻辑5.1先排除不花钱的再动需要重跑的。6. 复习清单把这份笔记压缩成一张纸复习的时候不要从头读代码按下面的顺序过一遍二十分钟能把整个接口层捡回来。第一轮看三个数MC、ISLOT、四个计数。确认子程序头是SUBROUTINE modelname(MC, ISLOT)确认 ISLOT 被用来查 STRTIN确认 NI、NC、NS、NV 四个数和记录里的写法一致、和代码里实际用量一致。这一轮只看不动眼睛扫一遍就行。第二轮看四张表。标志位表MODE、KPAUSE、MSTATE、MIDTRM 各自对应哪个分支、STRTIN 入口表1 是 CON、2 是 STATE、3 是 VAR、4 是 ICON计数为 0 时返回 0、USRMDL 字段表BUSID、USRMDL、IM、modelname、IC、IT、四个计数、data list、调用顺序表发电机、电流补偿器、励磁稳定器、励磁、汽轮机/调速器、混合模型。四张表都能默出来说明结构记住了。自查项通过标准不通过时的动作子程序头形参、顺序、类型全对直接改不要试图绕过计数一致性记录与代码用量完全一致用脚本数一遍字段个数分支覆盖每个行为分支都被进入过加分计数输出跑最小算例连接方式机组模型不在连接子程序里删掉多余的 CALL层次定位能说清属于六类中的哪一类回到调用顺序重新定位第三轮做一次反向走查从输出曲线倒推。曲线不对先问是哪个行为没进、还是进了但算错算错的话是读到了 0 指针、还是下标偏移差了一位、还是计数少写了导致越界。这个顺序能把大部分玄学问题落到具体的一行上。我自己踩得最深的一次是给一个机组相关模型在连接子程序里补了调用跑出来的曲线幅值正好是应该的两倍。当时盯着公式查了两天最后是数分支进入次数时发现每个行为都被进了两遍才回头看到那句多余的 CALL。从那以后我每次新建模型都强制走一遍上面这三轮尤其是连接方式那一格先确认它该不该出现在连接子程序里再动手写别的。希望帮到你。本文还有配套的精品资源点击获取