AnyMath 文档

项目管理的公共方法

请参阅: 软件模型管理的应用

这里介绍了所有公共的项目管理方法。 工程师. 熟悉这些方法 恩吉。剧本 参考文章 软件脚本管理.

方法 工程师

engee.add_block(lib_block_path::String, tgt_block_path::String; kwargs...)::String

engee.add_block(
    lib_block_path::String,
    tgt_block_path::String;
    top::Union{Int, Missing} = missing,
    left::Union{Int, Missing} = missing,
    width::Union{Int, Missing} = missing,
    height::Union{Int, Missing} = missing,
    rotation::Union{Int, Missing} = missing,
    is_flipped::Union{Bool, Missing} = missing,
    colors::Union{BlockColors, Missing} = missing,
    annotation::Union{Maybe{String}, Missing} = missing,
    is_name_visible::Union{Maybe{Bool}, Missing} = missing,
)::String

从库中添加一个模块。返回所添加模块的路径。

添加模块时，可以设置其视觉属性。未指定的属性将采用默认值。

参数

  • lib_block_path::String：库中代码块的路径（以 / 开头）。

  • tgt_block_path::String：目标系统的路径以及新模块的预期名称。 如果仅指定了系统名称（例如 "newmodel_1/"），则块名称将自动生成。 如果指定了包含块名的完整路径（例如 "newmodel_1/Sum1"），则该块将采用指定的名称。

  • top::Union{Int, Missing}：块的上坐标。

  • left::Union{Int, Missing}：块的左坐标。

  • width::Union{Int, Missing}: 块的宽度.

  • height::Union{Int, Missing}: 块的高度.

  • rotation::Union{Int, Missing}：块的旋转角度。

  • is_flipped::Union{Bool, Missing}: 块的镜像标志.

  • colors::Union{BlockColors, Missing}: 块的颜色属性.

  • annotation::Union{Maybe{String}, Missing}: 块注释.

  • is_name_visible::Union{Maybe{Bool}, Missing}：显示块名称的标志。

示例

# 从库中添加块而不指定名称
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/")

# 添加块并指定名称
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/Add_block_new")

# 添加块并设置视觉属性
engee.add_block(
    "/Basic/Sinks/Terminator",
    engee.gcm().name * '/';
	# 该模块将添加到坐标 (50, 50) 处，尺寸为 (100, 100)
	top = 50,
	left = 50,
	width = 100,
	height = 100,
)
engee.add_line(src_path::AbstractString, dst_path::AbstractString)
engee.add_line(system::System, src_path::AbstractString, dst_path::AbstractString)
engee.add_line(system_path::AbstractString, src_path::AbstractString, dst_path::AbstractString)

engee.add_line(src::PortHandle{OUT}, dst::PortHandle{IN})
engee.add_line(src::PortHandle{IN}, dst::PortHandle{OUT})
engee.add_line(src::PortHandle{ACAUSAL}, dst::PortHandle{ACAUSAL})

在模块之间添加连接（数据流）。支持以下两种端口指定方式：

  • 通过指向端口的字符串路径： "block_path/idx" 或 "block_path/port_name"，其中 block_path 表示相对于所选系统的模块路径。如果未通过单独的参数指定系统，则使用当前系统；

  • 通过端口描述符（PortHandle）实现，例如通过 engee.get_ports 获取。

端口描述符（PortHandle）是一个对象，它唯一标识 内的特定模块端口 模型内的特定模块端口。它不包含信号值，但作为软件操作端口的"`句柄`"（“Handle”）----可以将其 传递给 engee.add_line、engee.delete_line、 engee.get_lines 以及其他函数中进行软件层面的端口操作。

物理建模的特点（非因果性）

在 Engee 的物理建模模块中，端口是无向的 (acausal)。 这给连接操作带来了以下特点：

  • +PortHandle{ACAUSAL}+之间的连接不指定数据流的方向，而只是将两个物理节点连接起来；

  • 一个无方向端口可以拥有多个连接（多条线路）；

  • 模块之间的连接由独立的 Line 对象表示。

因此，在进行程序分析或修改模型时，采用分阶段的方法：

  • 使用 engee.get_ports 获取模块端口；

  • 使用 engee.get_lines 获取连接到该端口的线路；

  • 从 Line 对象中获取相邻端口 （source 和 destination）；

  • 使用 engee.add_line 执行重新连接。

参数

行格式：

  • system::System：System类型的对象；

  • system_path::AbstractString：指向系统的路径；

  • src_path::AbstractString：到 out （输出）端口或块的非定向（acausal）端口的相对路径。 记录格式为 "system_name/block_name/idx" 或 "system_name/block_name/port_name"；

  • dst_path::AbstractString：指向 in （输入）端口或块的非定向（acausal）端口的相对路径。 记录格式为 "system_name/block_name/idx" 或 "system_name/block_name/port_name"。

带端口描述符的选项：

  • src::PortHandle{OUT}、dst::PortHandle{IN} — 源端口和目标端口的描述符；

  • src::PortHandle{IN}, dst::PortHandle{OUT} — 反向（当根据电路图的含义，具有输入端口的模块为源时）；

  • src::PortHandle{ACAUSAL}, dst::PortHandle{ACAUSAL} — 无方向端口的描述符。

示例

行：

# 将模块Sine Wave 的第一个输出端口与当前系统中模块Terminator 的第一个输入端口连接
engee.add_line("Sine Wave/1", "Terminator/1")

# 第一个参数可以是System对象
system = engee.gcs()

# 以下调用与前一个等效
engee.add_line(system, "Sine Wave-1/1", "Terminator-1/1")

# 可以使用端口名称代替索引
engee.add_line("model", "Resistor/p", "Resistor-1/n")

描述符：

engee.add_block("/Basic/Sources/Sine Wave",   "newmodel_1/Sine Wave")
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/Add_block")
engee.add_block("/Basic/Sinks/Terminator",    "newmodel_1/Terminator")

# 获取模块的端口
src_ports = engee.get_ports("newmodel_1/Sine Wave")
add_ports = engee.get_ports("newmodel_1/Add_block")
dst_ports = engee.get_ports("newmodel_1/Terminator")

# 将Sine Wave 的输出与Add_block的第一个输入连接
engee.add_line(src_ports.outputs[1], add_ports.inputs[1])

# 将输出端口Add_block 与输入端口Terminator连接
engee.add_line(add_ports.outputs[1], dst_ports.inputs[1])

在物理建模中（acausal），一个端口可能有多个连接， 因此不能仅直接使用 source 或 destination。 在这种情况下，应采用"`端口 → 线路 → 相邻端口`"的分步方法：

  • 使用 engee.get_ports 获取模块端口；

  • 使用 engee.get_lines; 获取连接到该端口的线路

  • 从对象 Line 中获取相邻端口 （line.source 或 line.destination）；

  • 使用 engee.add_line 执行重新连接。

以下是根据该链路执行物理模块替换并恢复连接的示例。

# 获取模块PID Controller 的输入端口，名称为 "in"。这是接收端口
pid_input_port = engee.get_ports("newmodel_1/PID Controller").inputs["in"]

# 获取与该端口对应的连接线
pid_input_line = engee.get_lines(pid_input_port)

# 获取该连接线的源端口
pid_source_port = pid_input_line[1].source

# 获取新模块PID Controller 的输入端口，名称为“in ”。这是一个接收端口
new_pid_input_port = engee.get_ports("newmodel_1/PID Controller New").inputs["in"]

# 将源端口与接收端口连接起来
engee.add_line(pid_source_port, new_pid_input_port)

# 获取输出端口PID Controller
pid_output_port = engee.get_ports("newmodel_1/PID Controller").outputs["out"]

# 获取该端口的连接线
pid_output_line = engee.get_lines(pid_output_port)

# 获取该连接线的接收端口
pid_dest_port = pid_output_line[1].destination

# 删除旧模块PID Controller
engee.delete_block("newmodel_1/PID Controller")

# 获取新模块的输出端口PID Controller
new_pid_output_port = engee.get_ports("newmodel_1/PID Controller New").outputs["out"]

# 将新模块的输出端口PID Controller 连接到旧的接收端口
engee.add_line(new_pid_output_port, pid_dest_port)

# 可选：对模型进行自动格式化
engee.arrange_system(engee.gcs())
engee.addpath(path::Vararg{String})

将一条或多条路径添加到系统变量 LOAD_PATH 中。LOAD_PATH ----这是一个系统变量，AnyMath 会利用它来查找所需的可执行对象（例如 .engee、 .ngscript），以及命令中使用的任何其他路径。

参数

path::Vararg{String}：一个或多个文件系统路径（绝对或相对）。

示例

engee.addpath("/user/models")
# 加载模型
engee.load("model.engee")
engee.arrange_system(system::System)

重新排列指定模型中块和连接的位置，自动调整元素布局，以减少线条交叉并提高模型结构的可读性。 该功能等同于AnyMath画布上的"`整理模型`"右键菜单命令。整理操作仅针对指定模型执行（不会递归修改嵌套的子系统）。

参数

system::System：需要执行自动排序的系统（模型）对象。 可通过 engee.gcs() 获取。

示例

# 对当前打开的模型进行排序
engee.arrange_system(engee.gcs())
engee.clear()

清除当前工作空间中的所有变量。clear() 会删除变量中存储的所有数据，以便为新的计算和数据流释放内存。 返回 nothing。

engee.clear_all()

清除当前工作空间中的所有变量、函数和已定义模块。clear_all() 将当前工作空间恢复到初始状态。 返回 nothing。

engee.clear_port(port_path::AbstractString)

删除与传入端口相关的所有线路。 如果使用端口索引代替名称，则会在模块的输出端口中搜索该端口。

示例

engee.clear_port("model/Sine Wave/main_out")
engee.clear_port("model/Terminator/main_in")
engee.close(model_name::String; force::Bool = false)
engee.close(model::Model; force::Bool = false)
engee.close(; force::Bool = false)

关闭名称为 model_name 的模型。导航面板中位于其左侧的模型将成为当前模型。如果未指定模型，则关闭当前模型。 如果未指定当前模型，则不执行任何操作。如果该模型已不存在，则不执行任何操作。

参数

  • model_name::String：将被关闭的模型名称。

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但未必在图形界面中打开。

  • force::Bool：默认值为 false。 如果存在未保存的更改且该参数等于 false，则操作将以错误结束。 如果该参数等于 true，则未保存的更改将被丢失。

示例

# 从内存中卸载模型newmodel_1
engee.close("newmodel_1")

# 从内存中卸载模型newmodel_1 且不保存最近的更改
engee.close("newmodel_1", force=true)

# 关闭模型newmodel_1 （卸载并从画布上移除）
engee.close("newmodel_1", force=true)
engee.close_all()

关闭所有模型。

示例

# 从内存中卸载并关闭所有已打开的模型
engee.close_all()
engee.compare_models(model_path_1::String, model_path_2::String)

对一对模型进行比较，并返回差异列表。

参数

  • model_path_1::String：要进行比较的第一个模型的绝对或相对路径。

  • model_path_2::String：用于与第一个模型进行比较的第二个模型的绝对或相对路径。

示例

# 绝对路径 （指定模型文件的完整路径）
m1 = "/user/modelname_1.engee"

# 相对路径（指定模型文件的相对路径）
m2 = "modelname_2.engee"

# 比较m1 和m2
engee.compare_models(m1, m2)
engee.convert_model(model_path::String, out_path::String="")

生成 .ngscript 文件（AnyMath 脚本），用于通过程序控制命令构建当前模型。 执行脚本时，模型将在非交互模式下创建，且不会显示在画布上。若在创建模型时发生错误，需执行命令 engee.close(...) 以重新运行脚本。

参数

  • model_path::String： 以 .engee 或 .slx 格式表示的源模型的绝对或相对路径，该模型需要进行转换。

  • out_path::String：用于保存生成的脚本的路径。

    • 如果 out_path</未指定或等于 ""，则该函数将生成的脚本作为字符串返回，且不会将其保存到文件中。

    • 如果指定了 out_path，则脚本将保存到指定的路径，且该函数返回 nothing。 若需在 Julia 中后续运行，建议使用扩展名 .jl。

示例

# 将脚本保存到文件中（绝对路径）
model_path = "/user/newmodel_1.engee"
engee.convert_model(model_path, "/user/newmodel_1.jl")

# 将脚本保存到文件（相对路径）
engee.convert_model("newmodel_2.engee", "newmodel_2.jl")

# 获取脚本字符串（不保存到文件）
script = engee.convert_model("/user/newmodel_1.engee")
engee.convert_unit(value::T, from::String, to::Maybe{String})::Real where T<:Real

将 value 转换为其他计量单位： 将 from 转换为 to。 如果 to 等于 nothing，则转换为国际单位制（SI）。

示例

engee.convert_unit(17, "km", "m")
engee.copy_block(src_path::AbstractString, dst_path::AbstractString; duplicate::Bool=false)::Nothing

从系统中复制代码块。

如果 duplicate=true 和 src_path 指向块 Inport，则该函数会创建输入端口（Inport Shadow): 副本将获得与原始对象相同的输入端口编号Inport，并允许从输入端口分路信号，而无需创建新的子系统输入端口。

参数

  • src_path::AbstractString： 在模型层次结构中到该块的路径（例如 "model/system/block" 或 "model/block" 表示根文件夹）。

  • dst_path::AbstractString：指向系统的路径及预期名称。记录格式为 path/to/system/new_block_name。若未指定名称，则系统将自动生成。

  • duplicate::Bool：用于 Inport 代码块的复制标志。 对于其他类型的代码块，设置该标志（duplicate=true）将导致错误："Duplication not allowed for this block type: only "Inport" blocks can be duplicated"。

示例

# 从模型newmodel_1 中添加块Add-3，并自动为其在模型中命名newmodel_2
engee.copy_block("newmodel_1/Add-3", "newmodel_2/")

# 将模型newmodel_1 中名为Custom Block Name 的块，以Test_name为名添加到模型nemodel_2 中
engee.copy_block("newmodel_1/Custom Block Name", "newmodel_2/Test_name")
engee.copy_contents(src_path::AbstractString, dst_path::AbstractString)

将一个系统的内容复制到另一个系统中。目标（target）系统必须为空。禁止递归复制。

参数

  • src_path::AbstractString：源系统的路径。

  • dst_path::AbstractString：目标系统的路径。

示例

# 将根系统（root ）newmodel_1 的内容复制到根系统newmodel_2中
engee.copy_contents("newmodel_1", "newmodel_2")

# 将子系统“newmodel_1/Subsystem ”中的内容复制到子系统 `newmodel_1/Subsystem-1`
engee.copy_contents("newmodel_1/Subsystem", "newmodel_1/Subsystem-1")
ERROR: "newmodel_1/Subsystem-1 must be empty. Use `engee.delete_contents`"
engee.delete_contents("newmodel_1/Subsystem-1")
engee.copy_contents("newmodel_1/Subsystem", "newmodel_1/Subsystem-1")
engee.create(model_name::String)::Model

创建一个名为 model_name 且采用默认参数的新模型。返回 Model。 该模型将成为当前模型，其根系统将成为当前系统。如果已存在同名的模型，则会因错误 EngeeException 而终止。

参数

model_name::String：在系统中期望的模型名称。 模型名称中不得包含符号 /。

示例

engee.create("NewModel")
Model(
        name: NewModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
engee.delete_block(block_path::String)

从系统中删除该模块、所有相关线路以及被记录的端口。

参数

block_path::String：模块的路径。

示例

# 从系统中删除块Sine Wave 及其所有相关线段和块
engee.delete_block("newmodel_1/Sine Wave")
engee.delete_contents(system_path::String)

删除系统内容。

参数

system_path::String：要删除其内容的系统的路径。

示例

# 从模型newmodel_1中删除子系统Subsystem-1 中的所有块
engee.delete_contents("newmodel_1/Subsystem-1")
engee.delete_line(src_path::AbstractString, dst_path::AbstractString)
engee.delete_line(system::System, src_path::AbstractString, dst_path::AbstractString)
engee.delete_line(system_path::AbstractString, src_path::AbstractString, dst_path::AbstractString)

engee.delete_line(line::Line)
engee.delete_line(src::PortHandle{OUT},     dst::PortHandle{IN})
engee.delete_line(src::PortHandle{IN},      dst::PortHandle{OUT})
engee.delete_line(src::PortHandle{ACAUSAL}, dst::PortHandle{ACAUSAL})

支持三种指定待删除连接的方式：

  • 通过指向端口的字符串路径（"system_name/block_name/idx"）；

  • 通过 Line 获取的行对象，该对象由 engee.get_lines 提供；

  • 根据端口描述符（PortHandle）， 通过 engee.get_ports 获取，或来自 Line 结构体。

Line 描述了电路图中的一条连接线，并特别包含源端口和目标端口： source::PortHandle、destination::PortHandle。

通过 Line 和 PortHandle{ACAUSAL} 删除的方法也适用于非定向（acausal，物理）连接。

参数

字符串选项：

  • system::Union{AbstractString, System}：系统路径或 System 类型的对象；

  • src_path::AbstractString：指向模块端口 out（输出）的相对路径。端口名称使用其序号。 记录格式为 — "system_name/block_name/idx";

  • dst_path::AbstractString：指向 in（输入）模块端口的相对路径。端口名称使用其序号。 记录格式为 "system_name/block_name/idx".

包含 Line 对象和端口描述符的变体：

  • line::Line：由 engee.get_lines(...) 返回的线路对象。 包含行标识符以及源端口和目标端口的描述符；

  • src::PortHandle{OUT}、dst::PortHandle{IN} — 源端口和接收端口的定向端口描述符；

  • src::PortHandle{IN}, dst::PortHandle{OUT} — 反向（当根据语境，具有输入端口的块被视为源时

的块被视为源）；

  • src::PortHandle{ACAUSAL}、dst::PortHandle{ACAUSAL} — 非定向端口的描述符。

示例

# 删除模型中模块Sine Wave 的第一个输入端口与模块Terminator 的第一个输出端口之间的连接
newmodel_1
engee.delete_line("newmodel_1", "Sine Wave/1", "Terminator/1")
system = engee.gcs()
engee.delete_line(system, "Sine Wave-1/1", "Terminator-1/1")

# 未指定系统的删除操作。默认情况下，该操作将应用于当前系统
engee.delete_line("Sine Wave-2/1", "Terminator-2/1")

# 端口描述符（PortHandle ）的使用示例，假设模块已通过engee 连接。add_line ，如add_line中的示例所示
src_ports = engee.get_ports("newmodel_1/Sine Wave")
dst_ports = engee.get_ports("newmodel_1/Terminator")

# 删除第一个输出端口Sine Wave 与第一个输入端口Terminator之间的连接线
engee.delete_line(src_ports.outputs[1], dst_ports.inputs[1])

# 删除连接到该模块的所有线的示例

# 获取连接到该模块的所有线Add_block
all_block_lines = engee.get_lines("newmodel_1/Add_block")

# 按对象删除所有这些线Line
for ln in all_block_lines
    engee.delete_line(ln)
end

# 点表示法的等效表达式
engee.delete_line.(engee.get_lines("newmodel_1/Add_block"))
engee.eval(code::AbstractString)

在当前模型上下文中执行 Julia 代码。

参数

code::AbstractString：待执行的 Julia 代码行。

示例

engee.eval(2 + 3 * 5)
17

engee.eval(sin(π/2))
1.0
engee.find_system(path::String; depth::Int=typemax(Int), blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())

根据指定路径搜索实体（模型/系统/模块）。返回找到的实体的路径。

参数

  • path::String：要进行搜索的实体的路径。

  • depth::Int=typemax(Int)：最大搜索深度（含该深度）。 若要进行无限制搜索，请使用 typemax(Int)。计数从 0 开始。默认值为 typemax(Int)。

  • blockparams::Vector：仅返回具有指定参数的代码块。

示例

# 由名为newmodel_1 的模型组成的实体列表（子系统、模块）
engee.find_system("newmodel_1")

# 不进入子系统的newmodel_1 模型的实体列表
engee.find_system("newmodel_1"; depth=0)

# newmodel_1模型中所有Value 字段值为 1.0 的模块列表
engee.find_system("newmodel_1"; blockparams=["Value"=>1.0])
engee.find_system(; depth::Int=typemax(Int), blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())

在所有可用模型中搜索实体（模型/系统/块）。返回所查找实体的路径。

参数

  • depth::Int=typemax(Int)：最大搜索深度（包含该深度）。若要进行无限制搜索，请使用 typemax(Int)。 编号从 0 开始。默认值为 typemax(Int)。

  • blockparams::Vector：仅返回具有指定参数的块。

示例

# 所有实体的列表
engee.find_system()

# 不涉及子系统的模型实体列表
engee.find_system(; depth=0)

# 所有Value 字段值为1.0的模块列表
engee.find_system(; blockparams=["Value"=>1.0])
engee.find_system(system::System; depth::Int=typemax(Int), blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())

在指定系统中搜索实体（模型/系统/块），该系统作为 System 类型的对象传递。返回所查找实体的路径。

参数

  • system::System：将进行搜索的系统。

  • depth::Int=typemax(Int)：最大搜索深度（含边界）。 若需无限制搜索，请使用 typemax(Int)。计数从 0 开始。默认值为 typemax(Int)。

  • blockparams::Vector：仅返回具有指定参数的代码块。

示例

# 构成系统system 的实体列表（子系统、模块）
engee.find_system(system)

# 不深入子系统的系统system 的实体列表
engee.find_system(system; depth=0)

# 系统system中所有Value 字段值为 1.0 的模块列表
engee.find_system(system; blockparams=["Value"=>1.0])
engee.find_system(model::Model; depth::Int=typemax(Int), blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())

在作为 Model 类型对象传递的指定模型中搜索实体（模型/系统/块）。返回所查找实体的路径。

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不必在图形界面中打开。搜索将在该模型中进行。

  • depth::Int=typemax(Int)：最大搜索深度（含边界）。 若要进行无限制搜索，请使用 typemax(Int)。计数从 0 开始。默认值为 typemax(Int)。

  • blockparams::Vector：仅返回具有指定参数的代码块。

示例

# 构成模型model 的实体列表（子系统、模块）
engee.find_system(model)

# 模型model 中不深入子系统的实体列表
engee.find_system(model; depth=0)

# 模型model中所有Value 字段值为 1.0 的模块列表
engee.find_system(model; blockparams=["Value"=>1.0])
engee.get_current_block()::String
engee.gcb()::String

返回指向当前块的路径。如果当前块或模型不存在，则返回错误 Current block is not set。

示例

# 模块Sine Wave 在画布上被高亮显示
engee.gcb()
"newmodel_1/Sine Wave"
engee.get_current_model()::Model
engee.gcm()::Model

返回当前模型。如果当前模型不存在，则报错 No opened model.

示例

engee.get_current_model()
Model(
        name: ssc_bridge_rectifier_modified
        id: c390ed60-d2c4-4e17-85df-07129aca8ba4
)
engee.get_current_system()::System
engee.gcs()::System

返回当前系统。如果不存在当前模型，则报错 No opened model。

示例

engee.gcs()
System(
    name: root,
    id: 039b7ddd-f836-4b0c-bb8d-8232344b22fb,
    path: newmodel_1
)
engee.generate_code(path/to/modelname.engee::String, path/to/output_dir::String; subsystem_name=subsystem_path::String, subsystem_id=subsystem_id::String, target::String, jl_path::String)

为模型和/或子系统生成指定语言的代码。支持使用模板来配置输出代码（包括函数 main）。

针对模型

  • 生成操作将针对整个模型进行，该模型通过绝对路径或相对路径指向模型文件 .engee。

  • 可以通过参数 target 指定代码生成的目标，也可以通过 template_path 指定用户模板的路径。

参数

  • model_path::String：生成代码所依据的模型的绝对或相对路径。 参数可以是模型对象（由函数 engee.gcm 返回的 model 类型的对象）。

  • output_dir::String：生成代码将保存到的目录的绝对或相对路径。 如果目录 output_dir 不存在，则会自动创建该目录。

  • template_path::String：指向 .jl模板文件（例如函数模板 main）。

  • target::String：代码生成的语言指定。支持的语言包括 C（默认）、 Verilog 或 Promela。

示例

# 为模型生成 C 代码
engee.generate_code("newmodel_1.engee", "newmodel_1/codegen_output")

# 生成Verilog 代码，将创建文件newmodel_1 。v 包含Verilog 代码
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_output", target="verilog")

# 使用包含main函数的模板生成代码
engee.generate_code("codegen_model.engee", "codegen_dir", template_path="/user/main_template.jl")

# 获取当前打开的模型并从中生成代码
m = engee.gcm()
engee.generate_code(m, "/user/newmodel_1/codegen_output")

针对子系统

  • 仅针对按名称（subsystem_name）或标识符 (subsystem_id) 指定的原子子系统。

  • 其余参数与完整模型的生成方式相同。

参数

  • subsystem_name::String：生成代码的原子子系统的完整路径。

  • subsystem_id::String：生成代码的原子子系统的唯一标识符（替代方案为 subsystem_name）。

  • target::String：指定代码生成的语言。支持的语言包括 Si （默认）或 Verilog。

示例

# 为指定名称的子系统生成 C 代码
engee.generate_code("newmodel_1.engee", "newmodel_1/Subsystem", subsystem_name="Subsystem")

# 根据原子子系统的id生成代码
engee.generate_code("/user/newmodel_1.engee", "/user/newmodel_1/Subsystem"; subsystem_id = "88275e0b-a049-4bb5-b8c7-057badd1b536")

# 为子系统生成Verilog 代码，将创建文件newmodel_1 。v 包含子系统的Verilog 代码
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_pid", subsystem_name="SubSystem", target="verilog")

# 为子系统“Subsystem ”生成Promela 代码，将生成文件
engee.generate_code("newmodel_1.engee", "newmodel_1/Subsystem", subsystem_name="Subsystem", target="promela")
engee.get_all_models(; sorted=true)::Vector{Model}

返回当前会话中所有已打开的模型列表，格式为 Vector{Model}。 如果参数为 sorted=true，则返回按名称排序的模型列表。

参数

sorted::Bool：默认值为 true。用于确定模型列表是否按名称排序。

示例

# 所有已打开模型的列表
models_list = engee.get_all_models()

# 所有已打开模型的名称列表
model_names = [m.name for m in engee.get_all_models()]
engee.get_current_block()::String
engee.gcb()::String

返回指向当前块的路径。如果不存在当前块或模型，则报错 Current block is not set。

示例

# 模块Sine Wave 在画布上被高亮显示
engee.gcb()
"newmodel_1/Sine Wave"
engee.get_current_model()::Model
engee.gcm()::Model

返回当前模型。如果当前模型不存在，则报错 No opened model。

示例

engee.get_current_model()
Model(
        name: ssc_bridge_rectifier_modified
        id: c390ed60-d2c4-4e17-85df-07129aca8ba4
)
engee.get_current_system()::System
engee.gcs()::System

返回当前系统。如果当前模型不存在，则报错 No opened model

示例

engee.gcs()
System(
    name: root,
    id: 039b7ddd-f836-4b0c-bb8d-8232344b22fb,
    path: newmodel_1
)
engee.get_lines(block_path::AbstractString)::Vector{Line}
engee.get_lines(block_path::AbstractString, causality::PortCausality)::Vector{Line}
engee.get_lines(port::PortHandle)::Vector{Line}

返回连接到该模块或特定端口的信号线（Line）。 返回 Vector{Line} — 一个由 Line 对象组成的向量，其中每个对象描述两个端口之间的单条连接。

线路 (Line) ---- 这是一个描述原理图中单个连接的对象：

  • id::UUID — 线路标识符；

  • source::PortHandle — 源端口；

  • destination::PortHandle — 目标端口；

例如，可以将对象 Line 传递给 engee.delete_line(line::Line) 以解除连接。

函数 engee.get_lines(...) 始终返回线向量 (Vector{Line})，即使只有一条线也是如此。 这对物理仿真中的非定向（acausal）端口尤为重要，因为一个端口可能有多个连接。

参数

  • block_path::AbstractString：模型层次结构中该模块的路径。 记录格式为 "model_name/block_name" 或 "model_name/system_name/block_name"。

  • causality::PortCausality：需要获取线路的端口类型。 支持以下枚举值 PortCausality:

    • IN — 连接到模块输入端口的线路；

    • OUT — 连接至输出端口的线路；

    • ACAUSAL — 连接至非方向性端口的线路。

  • port::PortHandle： 模块端口描述符（PortHandle{IN}, PortHandle{OUT} 或 PortHandle{ACAUSAL}）， 例如，通过 engee.get_ports 获取的。

示例

engee.add_block("/Basic/Sources/Sine Wave",   "newmodel_1/Sine Wave")
engee.add_block("/Basic/Sinks/Terminator",    "newmodel_1/Terminator")
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/Add_block")

# 连接Sine Wave -&gt;Add_block -&gt;Terminator
src_ports = engee.get_ports("newmodel_1/Sine Wave")
add_ports = engee.get_ports("newmodel_1/Add_block")
dst_ports = engee.get_ports("newmodel_1/Terminator")

engee.add_line(src_ports.outputs[1], add_ports.inputs[1])
engee.add_line(add_ports.outputs[1], dst_ports.inputs[1])

# 连接到模块的所有线路Add_block
all_add_lines = engee.get_lines("newmodel_1/Add_block")

# 仅连接到模块输出端口的线路Sine Wave
sine_out_lines = engee.get_lines("newmodel_1/Sine Wave", OUT)

# 连接到特定端口的线路
first_add_input  = add_ports.inputs[1]
lines_to_add_in1 = engee.get_lines(first_add_input)

# 删除连接到模块的所有线路Add_block
engee.delete_line.(engee.get_lines("newmodel_1/Add_block"))

通过线路获取相邻端口（端口 → 线路 → 端口）：

some_port = add_ports.inputs[1]

lines = engee.get_lines(some_port)

source_ports = getproperty.(lines, :source)
destination_ports = getproperty.(lines, :destination)
engee.get_logs(model::Model)
engee.get_logs()

从日志中获取与模型相关的消息。 如果模型未打开，则报错 No opened model。返回包含消息的数组。

参数

m::Model：默认情况下，执行操作所针对的模型为当前模型。

示例

engee.get_logs()
4-element Vector{Dict{Symbol, String}}:
 Dict(:datetime => "2025-10-27T20:18:38.465684+00:00", :type => "INFO", :content => "Подготовка симуляции завершена за 5.8178 с.")
 Dict(:datetime => "2025-10-27T20:18:39.412789+00:00", :type => "INFO", :content => "Компиляция модели завершена за 1.833 c.")
 Dict(:datetime => "2025-10-27T20:18:39.412896+00:00", :type => "INFO", :content => "Инициализация модели завершена за 0.0903 c.")
 Dict(:datetime => "2025-10-27T20:18:39.842869+00:00", :type => "INFO", :content => "Симуляция модели завершена за 0.764 c.")
engee.get_param(model::Model)
engee.get_param(path::String, param::Union{Symbol, String})::Any
engee.get_param(path::String, param::Union{Symbol, String})::Any
engee.get_param(block::Block)
engee.get_param(block::Block, param::Union{Symbol, String})::Any

针对模型

  • 如果指定了模型名称但未指定参数名称，则以字典形式返回所选模型的仿真设置。

  • 如果指定了参数名称，则返回该参数的值。

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但未必在图形界面中打开。参数将从该模型中提取。

  • path::String：指向模型的字符串路径，若使用路径而非模型对象时。

  • param::Union{Symbol, String}：要提取的参数名称。可以是字符串或单个字符。

对于块

  • 根据块的路径，返回参数值（如果指定）或包含参数的字典。

  • 如果指定了参数名称，则返回该参数的值。

参数

  • block::Block：需要从中提取参数的代码块对象。

  • path::String：块的字符串路径（如果使用路径代替块对象）。

  • param::Union{Symbol, String}：要提取的块参数的名称。可以是字符串或符号。

示例

# 获取所有模型参数的字典
m = engee.gcm()
params = engee.get_param(m)
engee.get_ports(block_path::AbstractString)::BlockPorts

返回结构 BlockPorts，其中包含指定模块的端口描述符。

端口描述符是一种特殊对象（PortHandle），用于唯一标识模型内模块的特定端口。 它包含操作端口所需的所有信息：所属模块、端口类型（输入、输出、acausal）以及在模块内的索引。

该描述符并非信号值，而是作为端口指针，可传递给其他函数，例如

  • engee.add_line(src::PortHandle, dst::PortHandle);

  • engee.delete_line(src::PortHandle, dst::PortHandle);

  • engee.get_lines(port::PortHandle).

因此，PortHandle 是 Engee 模型中用于程序化处理端口的"`句柄`"（“handle”）。

参数

block_path::AbstractString：模型层次结构中该模块的路径。 记录格式为 "model_name/system_name/block_name" 或 "model_name/block_name"（用于根系统中的模块）。

返回值

BlockPorts：包含三个端口字典的结构：

  • inputs::IntStringDict{PortHandle{IN}} — 输入端口；

  • outputs::IntStringDict{PortHandle{OUT}} — 输出端口；

  • acausal::IntStringDict{PortHandle{ACAUSAL}} — 无方向端口。

端口既可通过索引（ports.outputs[1]）访问，也可通过端口名称（ports.outputs["main_out"]）访问。

物理建模

对于物理建模模块，无向端口位于 ports.acausal 字典中。 此类端口的名称取决于具体模块（例如 "p"、"n"、 "pin"）。要查询可用的端口名称，请使用 collect(keys(ports.acausal))。

示例

engee.add_block("/Basic/Sources/Sine Wave",      "newmodel_1/Sine Wave")
engee.add_block("/Basic/Sinks/Terminator",       "newmodel_1/Terminator")
engee.add_block("/Basic/Math Operations/Add",    "newmodel_1/Add_block")

# 获取模型中的模块端口newmodel_1
src_ports = engee.get_ports("newmodel_1/Sine Wave")
dst_ports = engee.get_ports("newmodel_1/Terminator")

# 通过索引访问
first_src_out = src_ports.outputs[1]
first_dst_in  = dst_ports.inputs[1]

# 模块Add_block 的端口也可通过索引访问
add_ports = engee.get_ports("newmodel_1/Add_block")

sum_in1 = add_ports.inputs[1]
sum_in2 = add_ports.inputs[2]
sum_out = add_ports.outputs[1]

# 获取具有命名端口的模块端口（端口必须预先命名）
add_ports = engee.get_ports("newmodel_1/Add_block")

sum_in1 = add_ports.inputs["in1"]
sum_in2 = add_ports.inputs["in2"]
sum_out = add_ports.outputs["out"]

# 输出
# CommandControlTypes.PortHandle{CommandControlTypes.OUT}(Base.UUID("b99ea18d-6ffa-4366-bc4f-43ea5438c530"),Base.UUID("746c1521-0c13-465e-8d26-e4d7f8729e52"),Base.UUID("e23e6f8a-0811-4f91-a597-707c501be315"),Base.UUID("e72aa3ab-7a60-4c4b-a8f1-f2bca8985747"), 1)

获取物理模块的非定向端口：

r_ports = engee.get_ports("model/Resistor")

#  acausal 端口名称列表
collect(keys(r_ports.acausal))

p = r_ports.acausal["p"]
n = r_ports.acausal["n"]
engee.get_results(model_name::String)
engee.get_results(model::Model)
engee.get_results()

以字典形式返回模型最近一次仿真的结果 Dict{String, DataFrame}，其中键为被跟踪端口的名称。 如果模型未打开，则输出错误 NoModelOpenedException。 如果未启动仿真，则返回错误 ModelIsNotRunningException。

参数

model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不必在图形界面中打开。返回上次仿真结果的操作将针对该模型执行。

示例

m = engee.load("start/examples/powersystems/models/power_line_apv.engee")
results1 = engee.run(m);
results2 = engee.get_results(m)
Dict{String, DataFrame} with 6 entries:
  "Va" => 40001×2 DataFrame…
  "Ia" => 40001×2 DataFrame…
  "Ib" => 40001×2 DataFrame…
  "Ic" => 40001×2 DataFrame…
  "Vc" => 40001×2 DataFrame…
  "Vb" => 40001×2 DataFrame…
results1 == results2
true
engee.get_status()::SimulationStatus
engee.get_status(model_name::String)::SimulationStatus
engee.get_status(model::Model)::SimulationStatus

返回模拟状态，类型为 SimulationStatus。返回模型模拟状态之一：

  • NOT_READY;

  • READY;

  • BUILDING;

  • RUNNING;

  • PAUSED;

  • STARTED;

  • ERROR;

  • STOPPED;

  • DONE.

参数

  • model_name::String：需要获取状态的模型名称。

  • model::Model：需要获取状态的 Model 类型的模型对象。

示例

engee> engee.get_status()
READY
engee.get_view(block_path::AbstractString)::Maybe{BlockView}

返回块的视觉属性。如果块中不存在 view 字段，则该函数返回 nothing。

参数

  • block_path::AbstractString：指向代码块的字符串路径。

示例

view = engee.get_view("model/system/Myblock")
view.colors = BlockColors(;
	border = Color("#352A87")
)
view.width = 150
view.height = 90
engee.info(info_message::String)

将信息消息传递到模型诊断窗口。该函数仅在块的回调（包括掩码回调）内部调用。 在消息中，可通过 $参数名 引用工作区（变量窗口）中的参数名称。

参数

info_message::String：要传递的信息消息。

示例

# 未引用工作区参数的示例
engee.info("Модель успешно инициализирована!")

# 诊断窗口中的消息：
# 模型已成功初始化！

# 引用了工作区参数的示例
engee.info("Модель успешно инициализирована с параметрами $Kp и $Ki!")

# 诊断窗口中的消息：
# 模型已使用参数 1.4 和 1.8 成功初始化！
engee.is_dirty(model::Model)::Bool
engee.is_dirty(model_name::String)::Bool

检查模型中是否存在未保存的更改。 若存在未保存的更改，则返回 true；否则返回 false。 如果模型已关闭，则返回 false。 对于最近打开的模型，如果该模型是从旧版本的文件中打开的，则可能返回 true（模型将在保存时更新）。

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不一定被选为当前模型。

  • model_path::String：模型的路径。

示例

# 验证当前模型
model = engee.gcm()
engee.is_dirty(model)

# 按模型名称验证
engee.is_dirty("newmodel_1")
engee.load(file_path::String; name::Maybe{String}=nothing, force::Bool=false)::Model

从位于路径 file_path 的、扩展名为 .engee 的文件中加载模型。 返回对象 Model。加载的模型将成为当前模型，其根系统将成为当前系统。

特点

  • 在当前会话中，"`已加载`"模型的标识符是模型名称（无论是从文件中读取的，还是通过 name 指定的）。

  • 如果该名称的模型已加载：

    • 当 force=false （默认）情况下，该函数会从内存中加载模型，而不会重新读取指定路径下的文件（包括当 file_path指向其他文件/目录，但模型名称相同）；

    • 当遇到 force=true 时，将强制从指定路径的文件中重新加载；当前同名模型中所有未保存的更改都将丢失。

  • 若要加载多个内部模型名称相同的文件，请指定唯一的 name（否则将使用内存中已打开的模型）。

  • 对于批量处理（转换/保存多个模型），建议在每次打开时调用 engee.load(...; force=true)，或者在保存后关闭模型 （例如，engee.close(...)/engee.close()），以免在迭代之间将其保留在内存中。

  • 如果文件不存在或扩展名不同，则会抛出异常。

参数

  • file_path::String：指向扩展名为 .engee 的模型文件的绝对或相对路径。

  • name::Maybe{String}：模型在当前会话中加载时使用的名称。若未指定，则使用文件中保存的名称。

  • force::Bool：强制加载标志。

    • false — 如果已加载了同名的模型，则返回内存中的实例（不会重新读取文件）；

    • true — 强制从指定路径的文件中加载模型，即使同名模型已加载（未保存的更改将丢失）。

示例

# 常规加载（默认force =false ）
engee.load("NewModel.engee")
Model(
        name: NewModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)

# 当force=false时重新加载同一模型
# （如果名为NewModel 的模型已打开，则从内存中返回该模型）
engee.load("NewModel.engee"; force = false)
Model(
        name: NewModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)

# 强制从指定路径的文件中加载（force=true ）
# 模型将从文件中重新加载。当前模型中未保存的更改将丢失。
engee.load("NewModel.engee"; force = true)
Model(
        name: NewModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
engee.log(message::String)

将消息写入事件日志。该函数仅在块回调（包括掩码回调）内部调用。 在消息中，可通过 $参数名 引用工作区（变量窗口）中的参数名称。

参数

message::String：要写入日志的文本消息。

示例

engee.log("Условие выполнено за $time" секунд)
Условие выполнено за 6.7538 секунд
engee.model(model_name::String, phase::Symbol)
engee.model(model_name::String,
            t::Union{Float64, Nothing},
            x::Union{Vector{Float64}, Float64, Nothing},
            u::Union{Vector{Float64}, Float64, Nothing},
            phase::Symbol)

在指定的仿真阶段执行模型计算，而无需启动完整的仿真。可用于获取有关任务规模、输出以及状态导数的辅助信息，并应用于内部算法（工作点搜索、线性化）。 不适用于逐步调试，也不能替代公开方法 engee.run。

该函数仅在名为 model_name 的模型文件已打开时才有效。

参数

  • model_name::String：模型名称。

  • t::Union{Float64, Nothing}：仿真时间点。 用于 :outputs 和 :derivatives 阶段。 对于 :sizes 阶段，该值可能为 nothing，并将被忽略。

  • x::Union{Vector{Float64}, Float64, Nothing}：模型状态向量或标量。对于无状态的模型，此处可以是 nothing。 对于相位 :sizes，该参数将被忽略。

  • u::Union{Vector{Float64}, Float64, Nothing}：模型的输入信号向量或标量。如果模型不包含输入端口，则应为 nothing。 对于 :sizes 阶段，该参数将被忽略。

  • phase::Symbol：仿真阶段。支持的值：

    • :sizes：定义仿真任务的规格（状态数、输入/输出及采样频率）；

    • :outputs：根据给定的 t 计算模型输出， x、u；

    • :derivatives：在给定条件下计算连续状态的导数 t, x、u。

返回值

根据 phase 的值，该函数的行为将发生如下变化：

  • phase == :sizes

    • 返回元组：

      • sys ---- 包含模型结构信息的整数向量：

        • sys[1] — 连续状态的数量；

        • sys[2] — 离散状态的数量；

        • sys[3] — 模型的输出数量；

        • sys[4] — 模型的输入数量；

        • sys[5] — 模型中的采样时间（sample time）数量；

      • blks — 包含状态的模块名称。

      • x0 — 模型状态的初始值。 如果模型中不包含带有状态的块，则返回 nothing。

  • phase == :outputs

    • 返回：

      • y::Union{Vector{Float64}, Float64, Nothing} — 在给定 t 时模型的输出， x、u 时的输出。

      • 如果模型不包含输出端口，则返回 nothing。

      • 向量 y 的元素按输出模块的完整名称排序。

  • phase == :derivatives

    • 返回值：

      • dx::Union{Vector{Float64}, Float64, Nothing} — 在给定 t 时连续状态的导数， x、u。

      • 如果模型不包含连续状态，则返回 nothing。

      • 向量 dx 的元素按包含状态的模块全名进行排序。

限制条件

该功能支持：

  • 连续模型；

  • 离散模型；

  • 不包含状态块的模型；

  • 包含虚拟子系统（Subsystem）的模型；

  • 包含原子子系统（Atomic Subsystem）的模型；

  • 包含引用模型的模型。

该功能不支持包含以下内容的模型：

  • 条件执行子系统（enabled、triggered）；

  • 包含 Action Port 模块的子系统；

  • Engee Function模块；

  • C Function模块；

  • 代码块 Chart;

  • 代码块 Bus Creator、Bus Selector、 Bus Assignment;

  • 物理建模模块。

错误

若违反调用条件，可能会生成以下错误：

  • 模型不存在或未打开：The model "model_name" doesn’t exist;

  • 模型中存在未保存的更改：The model "model_name" has unsaved changes;

  • 模型中包含不受支持的模块：The model "model_name" contains unsupported blocks.

示例

# 确定模型参数
sys, blks, x0 = engee.model("model_name", :sizes)

# 计算模型输出
t = 0.0
x = [0.0; 0.0; 0.0]
u = 2.0

y = engee.model("model_name", t, x, u, :outputs)

# 计算状态导数
t = 0.0
x = [0.0; 1.0; 1.0]
u = [2.0]

dx = engee.model("model_name", t, x, u, :derivatives)
engee.open(path::String)::System
engee.open(model::Model)::System
engee.open(system::System)::System

返回已打开的系统 System。如果模型或系统不存在，则以错误 EngeeException 终止。

特点

  • 如果参数中指定了先前已打开的模型的名称 model_name，则该模型将成为当前模型。 其根系统将成为当前系统。

  • 如果参数中指定了现有系统 system_path 的路径，则包含该系统的模型将成为当前模型，而该系统本身将成为当前系统，并在可视化编辑器中显示。 返回 System。 此外，也可以直接传入 Model 或 System 的实例，而非路径。

参数

  • path::String：模型或系统的路径。

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不一定被选为当前模型。默认情况下为当前模型。

  • system::System：System类型的对象。

示例

# open model :
s1 = engee.open("NewModel")
System(root)
engee.gcm(), engee.gcs()
(Model(
        name: NewModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
, System(
        name: root
        id: 69f5da6f-250d-4fa7-a25f-645bac751aea
)
)
# open system :
engee.open("AnotherModel/Subsystem-1")
System(
        name: root
        id: 69f5da6f-250d-4fa7-a25f-645bac751aea
)
engee.gcm(), engee.gcs()
(Model(
        name: AnotherModel
        id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
, System(
        name: Subsystem-1
        id: 69f5da6f-250d-4fa7-a25f-645bac751aea
)
)
engee.pause()

暂停正在运行的仿真。

engee.rename_model(old_name::AbstractString, new_name::AbstractString)

重命名模型。 将模型名称从 old_name 更改为 new_name。

参数

  • old_name::AbstractString：当前模型名称。

  • new_name::AbstractString：新模型名称。

示例

# 按名称重命名模型
engee.rename_model("OldModel", "NewModel")

# 验证模型是否已重命名
engee.gcm()  # 现在显示NewModel
engee.reset()

重新启动仿真内核。

示例

engee.reset()
[ Info: Simulation kernel has been reseted.
engee.resume(; verbose::Bool = false)

恢复已暂停的模拟。

参数

verbose::Bool = false：启用模拟执行过程的进度消息输出。

engee.rmpath(path::String)

从系统变量 LOAD_PATH 中删除路径。LOAD_PATH ----这是一个系统变量，AnyMath 会利用它来查找所需的可执行对象（例如 .engee、 .ngscript），以及命令中使用的任何其他路径。

参数

path::Vararg{String}：需从 LOAD_PATH 中删除的文件系统路径。

示例

engee.addpath("/user/models")

# 加载模型
engee.load("model.engee")
engee.rmpath("/user/models")

# 加载模型将报错
engee.load("model.engee")
engee.run(; verbose::Bool=false)
engee.run(model; verbose::Bool=false) where {model <: Union{Model, System, AbstractString}}

启动模型的执行。如果未指定模型，则启动当前模型的仿真。 如果模型未打开，则抛出 NoModelOpenedException 异常。

参数

  • verbose：是否将执行进度输出到打印机的标志（默认值为 false — 不输出）.

  • m::Model：执行操作所针对的模型。默认值为当前模型。

示例

# 运行当前模型
engee.run()

# 运行并显示进度
engee.run(verbose=true)

# 运行特定模型
m = engee.load("/user/start/examples/power_systems/power_line_apv/power_line_apv.engee")
engee.run(m)

# 异步无限仿真
m = engee.load("/user/start/examples/controls/PID_controller/pid_controls_tf_stable.engee")
engee.set_param!(m, "StopTime" => Inf)
ch = Channel(c -> put!(c, engee.run(m)))
sleep(10)
engee.stop()
take!(ch)
engee.save(model_name::String, file_path::String; force::Bool = false)
engee.save(model::Model, file_path::String; force::Bool = false)

将名称为 model_name 的模型，并将其保存至路径 file_path 下的扩展名为 .engee 的文件中。如有必要，将创建中间目录。 返回 nothing.

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不必在图形界面中打开。

  • model_name::String：系统中模型的期望名称。

  • file_path::String：保存模型的目录。

  • force::Bool：默认值为 false。 如果文件已存在且该参数等于 true，则覆盖该文件。 如果该参数等于 false，则会因错误 FileAlreadyExists 而终止。

示例

# 将模型newmodel_1 保存到新文件newmodel_1 中。engee
engee.save("newmodel_1", "newmodel_1.engee")

# 将模型newmodel_1 保存到文件newmodel_1 中。engee （重新写入文件）
engee.save("newmodel_1", "newmodel_1.engee", force = true)
engee.screenshot(to_print::Union{Model, String, System}, save_path::String; position_mode::String="auto")

将模型/系统的截图保存到路径为 save_path 的文件中。支持的格式：PNG、SVG。 在其他情况下，将显示错误 ErrorException("unsuported picture format: <FORMAT>")。定位方式："auto"、"tiled"；在其他情况下将采用"auto"。

参数

  • to_print::Union{Model, String, System}：用于截图的模型名称。

  • save_path::String：保存截图的路径。

  • position_mode::String : 截图的定位。 支持以下模式："auto" — 自动确定区块的最佳布局（标准模式）； "tiled" — 采用网格布局排列代码块，以避免重叠并提高结构可读性。 任何其他值均被视为 "auto"。

示例

engee.screenshot(loaded_model, "/user/saved.png"[; position_mode="tiled"])
engee.set_log(system_path::AbstractString, port_path::AbstractString)
engee.set_log(system::System, port_path::AbstractString)
engee.set_log(port_path::AbstractString)

设置日志记录端口。

参数

  • system_path::AbstractString：包含该端口的系统的路径。

  • system::System：包含该端口的系统.

  • port_path::AbstractString：到该端口的相对路径。如果未将系统作为第一个参数提供，则使用默认的开放系统.

示例

# 当前系统中，模块Sine Wave 的端口已设置为写入模式
engee.set_log("Sine Wave/1")

# 在系统newmodel_1/Subsystem 中，模块Sine Wave 的端口设置为写入
engee.set_log("newmodel_1/Subsystem","Sine Wave/1")

# 在系统system 中，模块Sine Wave 的端口设置为写入
system = engee.gcs()
engee.set_log(system, "Sine Wave/1")

# 运行仿真并获得结果
engee.run()
Dict{String, DataFrames.DataFrame} with 1 entry:
  "Sine Wave.1" => 1001×2 DataFrame…
engee.set_param!(model::Model | model_name::String, param::Pair...)

更新模型参数。返回 nothing。如果参数不正确，则会引发错误。

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但不必在图形界面中打开。该模型的参数将被更新。

  • model_name::String：字符串路径或模型名称。

  • param::Pair...：一个或多个符合 "name" => value 格式的参数。 如果参数带有计量单位，则其值必须以字典形式传递 Dict("value" => ..., "unit" => ...)，其中 "value" 表示数值，而 "unit" 表示包含计量单位的字符串（例如 "V"、 "Hz"、"deg"、"s" 等）.

示例

engee.set_param!(
    "my_model",
    "amplitude" => Dict("value" => 5.0, "unit" => "V"),
    "frequency" => Dict("value" => 50.0, "unit" => "Hz")
)

该示例展示了如何设置带单位参数。

engee.set_param!("model_1", "SolverName" => "ode45", "StopTime" => "10")

# 获取模型参数model_1
param_1 = engee.get_param("model_1")

# 将model_1 中的参数复制到model_2
engee.set_param!("model_2", param_1)

该示例演示了如何仅修改块中的一个参数（振幅），同时保持所有其他参数不变。 当需要有针对性地修改模块设置，且不希望导致其他参数被重置时，请采用此方法。

# 获取当前参数Sine Wave
sine_params = engee.get_param("newmodel_1/Sine Wave")

# 创建所有参数的副本，并仅修改其中一项
modified_params = copy(sine_params)
modified_params["Amplitude"] = "2.5"  # 仅修改振幅

# 应用所有参数 （其余参数保持不变）
engee.set_param!("newmodel_1/Sine Wave", pairs(modified_params)...)

仿真设置结构与特定模型相关联----可以通过直接设置结构字段来修改模型设置，此时：

params = engee.get_param("newmodel_1")

# 结构params 与特定的model 相关联，类似于engee 。set_param!("newmodel_1", "FixedStep" =&gt; "0.05")
params["FixedStep"] = "0.05"
0.05

修改 params 字典中的值不会自动更新模型参数----这是本地副本。 要使更改生效，需要通过 engee.set_param! 将字典传回。

params = engee.get_param("newmodel_1")
params["FixedStep"] = "0.05"
params["SolverName"] = "Euler"
engee.set_param!("newmodel_1", "FixedStep" => params["FixedStep"], "SolverName" => params["SolverName"])

每个参数都应以"`参数名-值`"的形式表示（例如 "StartTime" => 0.0）。 对于参数 param：

仿真参数

  • StartTime::String: 模拟开始时间（Float64）。

  • StopTime::String：模拟结束时间（Float64）。 若要设置无限模拟时间，请传递字符串 "Inf" 或 "inf" (engee.set_param!("model_name", "StopTime" => "Inf"))。

  • SolverType::String： 求解器类型（fixed-step 或 variable-step）。

  • SolverName::String：求解器名称（取决于所选类型）。

固定步长参数

FixedStep::String：模拟步长（Float64）。

可变步长参数

  • AbsTol::String：绝对精度（Float64 或 'auto'）。

  • RelTol::String：相对精度（Float64 或 'auto'）。

  • InitialStep::String：初始步长（Float64 或 'auto'）。

  • MaxStep::String：最大步长（Float64 或 'auto'）。

  • MinStep::String：最小步长（Float64 或 'auto'）。

  • OutputTimes::String：输出间隔（Float64 或 'auto'）。

  • DenseOutput::Bool：紧凑输出结果。

engee.set_view!(block_path::AbstractString, view::BlockView)
engee.set_view!(block_path::AbstractString; kwargs...)

engee.set_view!(
    block_path::AbstractString,
    top::Union{Int, Missing} = missing,
    left::Union{Int, Missing} = missing,
    width::Union{Int, Missing} = missing,
    height::Union{Int, Missing} = missing,
    rotation::Union{Int, Missing} = missing,
    is_flipped::Union{Bool, Missing} = missing,
    colors::Union{BlockColors, Missing} = missing,
    annotation::Union{Maybe{String}, Missing} = missing,
    is_name_visible::Union{Maybe{Bool}, Missing} = missing,
)::String

设置或更改块的视觉属性。

参数

  • block_path::AbstractString：指向该块的字符串路径。

  • view::BlockView：块的视觉属性对象.

  • top::Union{Int, Missing}: 块的顶部坐标.

  • left::Union{Int, Missing}：块的左坐标.

  • width::Union{Int, Missing}: 块的宽度.

  • height::Union{Int, Missing}: 块的高度.

  • rotation::Union{Int, Missing}：块的旋转角度.

  • is_flipped::Union{Bool, Missing}: 块的镜像标志.

  • colors::Union{BlockColors, Missing}: 块的颜色属性.

  • annotation::Union{Maybe{String}, Missing}: 块注释.

  • is_name_visible::Union{Maybe{Bool}, Missing}：显示块名称的标志。

示例

view = engee.get_view("model/system/Myblock")
view.colors = BlockColors(;
	border = Color("#352A87")
)
view.width = 150
view.height = 90

engee.set_view!("model/system/Myblock", view)
engee.set_view!("model/system/Myblock"; rotate = 90)
engee.stop()

停止正在运行的仿真。

engee.unset_log(system_path::String, port_path::String)
engee.unset_log(system::System, port_path::String)
engee.unset_log(port_path::String)

将端口从记录中移除。

参数

  • system_path::String：端口所在的系统。

  • system::System：端口所在的系统.

  • port_path::String：到该端口的相对路径。如果未将系统作为第一个参数提供，则使用默认的开放系统.

示例

# 当前系统中，模块Sine Wave 的端口设置为写入模式
engee.set_log("Sine Wave/1")

# 运行仿真并获取结果
engee.run()
Dict{String, DataFrames.DataFrame} with 1 entry:
  "Sine Wave.1" => 1001×2 DataFrame…

# 当前系统中，模块Sine Wave 的端口已取消写入
engee.unset_log("Sine Wave/1")

engee.run()
Dict{String, DataFrames.DataFrame}()
engee.update_params()
engee.update_params(model::Model)
engee.update_params(model_name::String)

更新正在运行的仿真参数，并从工作空间重新计算其当前值。

该函数允许将工作空间中参数的更改动态应用到已运行的仿真中，而无需停止并重新启动仿真。如果不存在正在运行的仿真，则该函数不执行任何操作。

可接受模型名称或模型对象作为可选参数，以指定需要应用参数更新的对象。 此功能相当于在模拟运行期间点击"`编译模型`"按钮。

参数

  • model::Model：可通过函数 engee.gcm 加载到内存中的模型对象。 该模型可在工作空间中处于活动状态，但未必在图形界面中打开。

  • model_name::String：需要重新计算其参数的模型名称。

示例

# 更新当前仿真中所有模块的参数
engee.update_params()

# 更新指定模型的参数
model = engee.gcm()
engee.update_params(model)

# 按名称更新模型参数
engee.update_params("newmodel_1")
engee.version()

返回 AnyMath 的简写形式。

示例

engee.version()
"25.11.2"
engee.warning(warning_message::String)

将警告消息传递到模型诊断窗口。该函数仅在块的回调中调用（包括隐藏的回调）。 在消息中，可通过 $参数名 引用工作区（变量窗口）中的参数名称。

参数

warning_message::String：要传递的警告消息。

示例

# 未引用工作区参数的示例
engee.warning("Параметры округлены, результаты могут быть неточными!")

# 诊断窗口中的提示：
# 参数已四舍五入，结果可能不准确！

# 包含工作区参数引用示例
engee.warning("Параметры округлены до $Nd и $Ns, результаты могут быть неточными!")

# 诊断窗口中的提示信息：
# 参数已四舍五入为 1.7 和 1.3，结果可能不准确！












有限状态机方法


















engee.sm.add_data(chart_path, scope, name; value, idx)::Nothing








向 Chart 模块（有限自动机）添加变量或事件。






参数






    

  • 

    chart_path::String ：指向 Chart 模块的路径。
    

    • 

  • 

    scope::Symbol ：事件/数据类型。可取值：:input 、:output 、:local 、:event 。
    

    • 

  • 

    name::String ：变量名称。
    

    • 

  • 

    value::Any ：变量值。默认情况下为空。
    

    • 

  • 

    idx::Int ：端口序号。适用于:input 和:output 类型的变量。
    

    • 


















engee.sm.add_junction(path; type)::Tuple{UUID, String, String}








在Chart（有限自动机）块内创建节点和内存节点。嵌套层级由参数path 确定。 返回Tuple ，其中包含节点UUID 、节点类型及其路径。






参数






    

  • 

    path::String ：状态路径或要添加新节点的Chart块路径。
    

    • 

  • 

    type::String ：节点类型："history" （用于内存节点）、nothing 。
    

    • 







示例








# 在Chart中创建普通节点
junction_id, junction_type, junction_path = engee.sm.add_junction("newmodel_1/Chart")

# 创建内存节点
junction_id, junction_type, junction_path = engee.sm.add_junction(
    "newmodel_1/Chart",
    type="history"



















engee.sm.add_state(path, name; content)::Tuple{UUID, String, String}








在Chart（有限自动机）块内部创建状态。 嵌套层级由参数path 确定。返回Tuple ，其中包含状态的UUID 、状态名称及其路径。






参数






    

  • 

    path::String ：通往父状态或要添加新状态的Chart块的路径。
    

    • 

  • 

    name::String ：新状态的名称。
    

    • 

  • 

    content::String: 状态的全部代码，代码中可包含以下部分：
    

    

      

    • 

      entry: 用于entry 部分的代码，在进入该状态时执行；
      

      • 

    • 

      during: 用于during 部分的代码，在该状态处于活动状态时执行；
      

      • 

    • 

      exit: 用于exit 节的代码，在状态退出时执行。
      

      • 

    

    

    • 







示例








# 在Chart中创建简单状态
state_id, state_name, state_path = engee.sm.add_state("newmodel_1/Chart", "State1")
(Base.UUID("a511fb4d-44cc-45dc-bfb0-74f6f9791239"), "State1", "newmodel_1/Chart/State1")

# 使用代码创建状态
state_id, state_name, state_path = engee.sm.add_state(
     "newmodel_1/Chart",
     "ActiveState",
     content="""
     entry:
         disp('Вход в активное состояние');
     during:
         counter = counter + 1;
     exit:
         disp('Выход из активного состояния');
     """
)
(Base.UUID("6c8d02d4-da4a-4393-9458-ac381a627520"), "ActiveState", "newmodel_1/Chart/ActiveState")



















engee.sm.add_transition(chart_path, source, destination)::Tuple{UUID, String}








在 Chart 块（有限自动机）内部创建一个转换。返回包含转换的UUID 以及指向包含该转换的系统的路径的Tuple 。






参数






    

  • 

    chart_path::String: 指向 Chart 块的路径。
    

    • 

  • 

    source::Maybe{String} ：源对象状态的路径。
    

    • 

  • 

    destination_id::UUID ：目标状态/节点的 UUID。
    

    • 

  • 

    trigger::Maybe{String} ：用于执行代码的触发器。
    

    • 

  • 

    action::Maybe{String} ：当condition 中的条件满足时执行的代码。
    

    • 

  • 

    condition::Maybe{String} ：执行代码的条件。
    

    • 

  • 

    content::Maybe{String}: 整个跳转代码（包括条件 - condition、触发器 - trigger、动作 - action）。
    

    • 

  • 

    origin::Maybe{String}: 默认跳转起点的所属关系（起点属于某个状态，还是属于全局状态）。
    

    • 















有用的连结






    

  1. 

    命令行
    

    2. 

  2. 

    软件控制建模
    

    3. 

  3. 

    脚本编辑器
    

    4.