跳到主要内容

Python 控制元件

本文档介绍自定义 Python 元件的创建和调用方法,并通过 3 个案例介绍自定义 Python 元件的使用方法。阅读该文档,用户需熟悉 Python 的基本语法。该功能仅支持在 EMTLab 平台使用。

功能定义

该功能支持使用 Python 语言构建自定义电磁暂态仿真元件。公网试用平台暂不支持自定义 Python 元件

功能说明

创建元件

方法1 直接创建 Python 元件

在 EMTLab 工作台中,点击新建按钮,在弹出的向导窗口中选择空白 Python 元件模板,点击新建按钮,新建元件,如下图所示。

直接创建 Python 元件
直接创建 Python 元件

方法2 从已有算例修改为 Python 元件

在已有算例中,选择总览标签页,将模型类型切换为元件

切换模型类型
切换模型类型

此时,在实现标签页中将出现拓扑、电磁暂态等子标签页。选中电磁暂态子标签页,点击创建电磁暂态 - Python 实现按钮,即可创建 Python 用户自定义控制元件。

创建电磁暂态 - Python 实现
创建电磁暂态 - Python 实现

创建成功后,在电磁暂态子标签下将会出现 Python 代码编辑器。

Python 代码编辑器
Python 代码编辑器

参数、引脚设置

自定义 Python 元件的参数、引脚设置与其它用户自定义元件类似,在接口标签页中进行配置。参数、引脚的类型和定义可以参考 定义模块参数列表定义模块引脚列表 文档。

参数、引脚定义后,将在代码编辑中作为变量被调用。

Python 参数引脚设置
Python 参数引脚设置

代码编辑

切换到实现标签页,选择电磁暂态子标签,跳转到电磁暂态元件代码编辑窗口。

此时,如果已定义好元件的参数和引脚,它们的键名会自动识别并列出。同时,EMTLab 已提供了三个内置变量,分别是 init(当前是否为第一个时步)、time(仿真进行时间)和 deltaT(仿真步长),用户可以直接使用这三个变量参与控制逻辑实现。

用户可以在代码编辑器中以 args["键名"] 的形式调用自定义的元件参数,也可以通过 global 的方式定义全局变量,用于在时步之间传递数据。

代码编写时,使用 return 语句返回要输出的值,返回值为列表类型,列表中元素的数量需要与输出引脚数量一致。

代码编辑窗口
代码编辑窗口

调用方式

自定义 Python 元件根据触发方式的不同可分为 3 种,分别是:每时步触发、固定频率触发和外部触发。

  • 每时步触发
    即仿真运行的每个时步都会调用 Python 元件,与其它常规元件的调用方式一致。

  • 固定频率触发
    当需要以某一固定频率调用 Python 元件时,可以使用 EMTLab 提供的内置参数 Trigger,参数类型为实数,含义为触发频率。该参数需要用户在参数列表手动添加后才能修改,否则默认为每时步触发。

    接口标签页的参数列表定义栏,新建一个参数,设置其键名为 Trigger,详细描述为“触发频率”,类型为实数,如下图所示。

    设置固定触发频率
    设置固定触发频率

    在元件参数面板修改 Trigger 的值后,Python 元件将按所设置的触发频率被调用。

  • 外部触发:当需要用一个外部信号触发来调用 Python 元件时,可以将 EMTLab 提供的内置参数 Trigger 的参数类型需设为虚拟引脚,虚拟引脚的连接类型为输入,含义为外部触发信号输入端口,需要注意,这个信号为上升沿触发。该参数需要用户在参数列表手动添加后才能生效,否则默认为每时步触发。

    接口标签页的参数列表定义栏,新建一个参数,设置其键名为 Trigger,详细描述为“外部触发信号输入端口(上升沿触发)”,类型为虚拟引脚,连接类型为输入,如下图所示。

    设置外部触发信号输入端口
    设置外部触发信号输入端口

    在元件参数面板的 Trigger 栏填入 @前缀的控制信号,Python 元件将按该信号的上升沿触发被调用。

案例

本文档提供 3 个案例:

  • 案例 1:每时步触发的简单 Python 控制元件;
  • 案例 2:固定频率触发的并带有全局变量的 Python 控制元件;
  • 案例 3:外部触发的含多维输入、多维输出的 Python 控制元件。

简单控制元件,每时步触发

本案例以一个可调斜率和分段点的分段函数,展示 Python 元件的创建和使用方法。

  • 新建 Python 元件

    在 SimStudio 工作台,点击左上角的新建,在弹出的窗口中,选择项目模板下的空白 Python 元件。点击窗口右下角的新建按钮,即可完成新建。

    新建 Python 元件
    新建 Python 元件
  • 参数与引脚定义

    接口标签页的参数列表定义栏新建一个参数组,并新建参数。本例中需要添加的参数有:第一段函数斜率 k1、第二段函数斜率 k2、分段点横坐标 a 和分段点纵坐标 b。可如下图所示新建参数。

    新建参数组并新建参数
    新建参数组并新建参数

    接口标签页的引脚列表栏新建引脚。本例中需要添加的引脚有:输入引脚 input 和输出引脚 output 。可如下图所示新建引脚。

    新建引脚
    新建引脚
  • 元件图形设计

    接口标签页的元件图形设计窗口绘制元件图标,并添加两个引脚,分别与 input 和 output 绑定。

    绘制元件图形并绑定引脚
    绘制元件图形并绑定引脚
  • 代码编辑

    切换到实现标签页,选择电磁暂态子标签,跳转到 Python 元件代码编辑窗口。此时,由于已经定义好元件的参数和引脚,它们的键名会自动识别并列出。

    编辑 Python 元件
    编辑 Python 元件

    在代码编辑窗口编写可调斜率和分段点的分段函数代码:

        if input < args["a"]:
    output = args["k1"] * input + args["b"] - args["k1"] * args["a"]
    else:
    output = args["k2"] * input + args["b"] - args["k2"] * args["a"]

    return[output]

    注意代码的缩进,注意变量名称为 args["键名"] 的形式。

    分段函数的 Python 实现
    分段函数的 Python 实现
  • 元件名称与权限设置

    切换到总览标签页,输入元件的名称,并设置元件的权限元件标签

    元件名称与权限设置
    元件名称与权限设置

    保存的元件可以在设置的元件标签中查找,也可通过搜索查找。

至此,一个使用自定义 Python 功能的分段函数元件构建完成。可以新建一个普通项目,在对应的元件标签中找到该元件,验证其控制效果。

  • 控制效果验证

    新建一个普通项目,调用 Python 分段函数元件。在其输入引脚连接一个时间输入元件,在其输出引脚连接一个输出通道观测输出结果。

    调用 Python 分段函数
    调用 Python 分段函数
    配置电磁暂态仿真方案
    配置电磁暂态仿真方案

    配置电磁暂态仿真方案和输出通道,运行电磁暂态仿真,得到如下图所示结果。曲线的分段点和斜率与设置参数一致。

    Python 分段函数输出结果
    Python 分段函数输出结果

案例 1 算例文件下载:model_admin_Python_Test_Case1.zip。文件密码:cloudpss123

注意

公网试用平台暂不支持自定义 Python 元件。

常见问题

仿真运行报错:"compile python code failed"

请检查 Python 代码是否存在语法错误。需要注意代码的缩进,并注意变量名称为 args["键名"] 的形式。

仿真运行报错:"python module return type error"

请检查 return 语句是否存在语法错误,return 返回的值应为列表类型,用 [] 表示。

若存在多个需要返回的值,使用逗号分隔,例如:return [output1, output2, output3],需注意列表中元素的数量应与输出引脚的数量一致。

当存在多维的输出引脚时,使用列表嵌套返回一个多维的值,例如:return [[output1A, output1B, output1C], output2, output3],需注意列表中元素的数量应与输出引脚的维数以及数量对应。

仿真运行报错:"execute python module failed"

请根据详细报错信息检查 Python 代码是否存在错误。

为什么使用 print( ) 函数没有效果?

目前暂不支持直接输出 print( ) 的结果。用户可通过添加输出引脚,使用 return 语句输出 Python 元件中需要观测的结果。