跳到主要内容

Matlab / Octave 控制元件

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

功能定义​

该功能支持使用 MATLAB/Octave 语言构建自定义电磁暂态仿真元件。

功能说明​

创建元件​

方法1 直接创建 Octave 元件​

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

直接创建 Octave 元件
直接创建 Octave 元件

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

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

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

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

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

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

Octave 代码编辑器
Octave 代码编辑器

参数、引脚设置​

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

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

Octave 参数引脚设置
Octave 参数引脚设置

代码编辑​

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

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

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

代码编写时需要给所有输出引脚赋值。

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

调用方式​

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

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

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

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

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

    用户也可以在创建 Octave 元件时，选择新建空白 Octave 元件（固定频率触发式），直接打开一个带有 Trigger 参数的 Octave 元件模板，并在其基础上修改。

    新建固定频率触发式 Octave 元件
    新建固定频率触发式 Octave 元件

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

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

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

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

    用户也可以在创建 Octave 元件时，选择新建空白 Octave 元件（外部触发式），直接打开一个带有 Trigger 虚拟引脚输入参数的 Octave 元件模板，并在其基础上修改。

    新建外部触发式 Octave 元件
    新建外部触发式 Octave 元件

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

案例​

本文档提供 3 个案例：

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

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

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

  • 新建 Octave 元件

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

    新建 Octave 元件
    新建 Octave 元件

  • 参数与引脚定义

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

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

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

    新建引脚
    新建引脚

  • 元件图形设计

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

    绘制元件图形并绑定引脚
    绘制元件图形并绑定引脚

  • 代码编辑

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

    编辑 Octave 元件
    编辑 Octave 元件

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

    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;
    end

    注意变量名称为 args.键名的形式。

    分段函数的 Octave 实现
    分段函数的 Octave 实现

  • 元件名称与权限设置

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

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

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

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

  • 控制效果验证

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

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

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

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

案例 1 算例文件下载：model_admin_Octave_Test_Case1.zip

常见问题​

同时设置了一个元件的“拓扑”和“电磁暂态”的两种实现方法，为什么“拓扑”中的内容没有正确地生效？

需要注意的是，在存在电磁暂态标签页的具体实现时，拓扑的实现方法将会失效。用户可以右键选择电磁暂态的子标签，并点击删除按钮，删除 Octave 的元件实现方法，保留拓扑实现方法，如下图所示。当然，也可以根据需要，自行选择需要保留的实现方法类型。

删除一个实现方法
删除一个实现方法
为什么带有 Octave 元件的算例运行很慢？

对于含有 Octave 元件的算例，在仿真的过程中需要根据 Octave 元件的触发频率调用 Octave 的解释器，导致仿真速度较慢。用户可以根据需求，选用拓扑模块封装等速度更快的方式进行模块构建。

仿真运行报错："The function belongs to the image package from Octave Forge which seems to not be installed in your system."

该报错原因为在代码中存在未识别的函数，目前暂不支持调用外部函数。

为什么使用 disp( ) 函数没有效果？

目前暂不支持直接输出 disp( ) 的结果。用户可通过添加输出引脚，输出 Octave 元件中需要观测的结果。