Public methods of programme management
See also: Application of Programme Model Control. |
All public methods of the engee
programme control are presented here. For engee.script
methods, please refer to the article Software script management.
engee
methods
#
engee.add_block
— Function
engee.add_block(block_identity::String, tgt_block_path::String)
Adds a block from the library.
Arguments
-
lib_block_path::String
: the full path to the block in the library. The path starts from/
. -
tgt_block_path::String
: the path to the target system and the expected name of the new block. If only the system name is specified (for example,"newmodel_1/"
), then the block name will be automatically generated. If the full path with the block name is specified (for example,"newmodel_1/Sum1"
), then the block will receive the specified name.
Examples
# Adding a block from the library without assigning a name
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/")
# Adding a block with a name
engee.add_block("/Basic/Math Operations/Add", "newmodel_1/Add_block_new")
#
engee.add_line
— Function
engee.add_line(src_port::String, dst_port::String) = engee.add_line(engee.gcs(), src_port::String, dst_port::String)
engee.add_line(system::String|System, src_port::String, dst_port::String)
engee.add_line(system_id::UUID, src_port::String, dst_port::String)
Adds a connection (data flow) between blocks.
Arguments
-
system::System
: path to the system or object typeSystem
. -
src_port::String
: full path toout
the (output) port of the block. The port name is its serial number. Recording format —"system_name/block_name/idx"
. -
tgt_port::String
: full path toin
the (input) port of the block. The name and format of the record are similar to the input port.
Examples
# Connects the first input port of the Sine Wave block and the first output port of the Terminator block in the current model
engee.add_line("Sine Wave/1", "Terminator/1")
# The first parameter can be a System object
system = engee.gcs()
# The call is equivalent to the previous one
engee.add_line(system, "Sine Wave-1/1", "Terminator-1/1")
#
engee.addpath
— Function
engee.addpath(path::Vararg{String})
Adds one or more paths to a system variable LOAD_PATH
. LOAD_PATH
— this is a system variable that Engee uses to find the necessary executable objects (for example, .engee
, .ngscript
), as well as any other paths used in commands.
Arguments
path::Vararg{String}
: one or more paths in the file system.
Examples
engee.addpath("/user/models")
engee.load("model.engee") # loading the model
#
engee.clear
— Function
engee.clear()
Clears all variables in the current workspace. clear()
deletes all data stored in variables to free up memory for new calculations and data streams. Returns nothing
.
#
engee.clear_all
— Function
engee.clear_all()
Clears all variables, functions, and defined modules from the current workspace. clear_all()
returns the current workspace to its original state. Returns nothing
.
#
engee.close
— Function
engee.close(model_name::String; force::Bool = false)
engee.close(model::Model; force::Bool = false)
engee.close(; force::Bool = false)
Closes the model with the name model_name
. The current model becomes the one that is open to the left in the navigation panel for models. If the model is not specified, it closes the current model. If the current model is not set, it does nothing. If the model doesn’t exist anymore, it doesn’t do anything.
Arguments
-
model_name::String
: the name of the model that will be closed. -
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. -
force::Bool
: by default is equal tofalse
. If there are unsaved changes and the parameter is equal tofalse
, then exits with an error. If equal totrue
then unsaved changes will be lost.
Examples
# Unloads the newmodel_1 model from memory
engee.close("newmodel_1")
# Unloads the newmodel_1 model from memory without saving the latest changes
engee.close("newmodel_1", force=true)
# Closes the newmodel_1 model (unloads and removes it from the canvas)
engee.close("newmodel_1", force=true)
#
engee.close_all
— Function
engee.close_all()
Closes all models.
Examples
# Unloads all open models from memory
engee.close_all()
#
engee.compare_models
— Function
engee.compare_models(model_path_1::String, model_path_2::String; subsystem_id_a=UUID_YOU_SUBSYSTEM_IN_MODEL_m)
Compares a pair of models, and returns a list of differences.
Arguments
-
model_path_1::String
: the path to the first model to be compared. -
model_path_2::String
: the path to the second model for comparison with the first. -
subsystem_id_a
: subsystem identifier, which is used to compare only a specific part of the model (in the subsystem). A specific UUID is used for the call. This parameter can be useful if you need to compare a specific subsystem within the model.
Examples
# Absolute path (specifying the full path to the model file)
m1 = "/user/modelname_1.engee"
# Relative path (specifying the relative path to the model file)
m2 = "modelname_2.engee"
# Returns the result of comparing m1 and m2
engee.compare_models(m1, m2)
#
engee.convert_model
— Function
engee.convert_model(model_path::String,[out_path::String])
Generates a program management script in the Julia language for the specified model. If a path is specified out_path
, then the script is saved to a file with the specified name (the extension can be set arbitrarily, but it is recommended to use .jl for subsequent launch in Julia). If no path is specified, the result is returned as a string.
Arguments
-
model_path::String
: the path to the source model in the format.engee
or.slx
which needs to be converted. -
out_path::String
: the path to save the generated script. If this argument is not specified, the script can be saved in the default folder (/user
).
Examples
# Getting an absolute path and outputting an Engee script
model_path = "/user/newmodel_1.engee"
engee.convert_model(model_path)
# Getting the relative path and outputting the Engee script
m_abs_path = "newmodel_2.engee"
engee.convert_model(m_abs_path)
#
engee.copy_block
— Function
engee.copy_block(src_block_path::String, tgt_block_path::String)
Copies the block from the system.
Arguments
-
src_block_path::String
: the full path to the block in the system. -
tgt_block_path::String
: the path to the system and the expected name. Recording format —path/to/system/new_block_name
. If the name is not specified, it is set automatically.
Examples
# Adds the Add-3 block from the newmodel_1 model and automatically assigns it a name in the newmodel_2 model.
engee.copy_block("newmodel_1/Add-3", "newmodel_2/")
# Adds a block from the newmodel_1 model named Custom Block Name to the nemodel_2 model named Test_name
engee.copy_block("newmodel_1/Custom Block Name", "newmodel_2/Test_name")
#
engee.copy_contents
— Function
engee.copy_contents(src_system_path::String, tgt_system_path::String)
engee.copy_contents(src_system_id::UUID, tgt_system_id::UUID)
Copies the contents of one system to another. The target system must be empty. Recursive copying is prohibited.
Arguments
-
src_system_path::String
: the path to the system from which the copy is being made. -
tgt_system_path::String
: the path to the system to which the copy is being made. -
src_system_id::UUID
: ID of the system that is being copied from. -
src_system_id::UUID
: ID of the system that is being copied from.
Examples
# Copying content from the newmodel_1 root system to the newmodel_2 root system
engee.copy_contents("newmodel_1", "newmodel_2")
# Copying content from subsystem "newmodel_1/Subsystem" to 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
— Function
engee.create(model_name::String)::Model
Creates a new model with the name model_name
and the default settings. Returns Model
. The model becomes the current model. Its root system becomes the current system. If a model with that name already exists, it fails. EngeeException
.
Arguments
model_name::String
: the desired model name in the system. The model name must not contain the symbol /
.
Examples
engee.create("NewModel")
Model(
name: NewModel
id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
#
engee.delete_block
— Function
engee.delete_block(block_path::String)
Deletes the block, all associated lines, and writable ports from the system.
Arguments
block_path::String
: the path to the block.
Examples
# Removes the Sine Wave block and all associated lines and blocks from the system
engee.delete_block("newmodel_1/Sine Wave")
#
engee.delete_contents
— Function
engee.delete_contents(system_path::String)
engee.delete_contents(system_id::UUID)
Deletes the contents of the system.
Arguments
-
system_path::String
: the path to the system whose content will be deleted. -
system_id::UUID
: ID of the system whose content will be deleted.
Examples
# Removing all blocks from Subsystem-1 in the newmodel_1 model
engee.delete_contents("newmodel_1/Subsystem-1")
#
engee.delete_line
— Function
engee.delete_line(src_port::String, dst_port::String) = delete_line(gcs(), src_port::String, dst_port::String)
engee.delete_line(system::System, src_port::String, dst_port::String)
Deletes the connection (data flow) between the blocks.
Arguments
-
system::String||System
: path to the system or object typeSystem
. -
src_port::String
: full path toout
the (output) port of the block. The port name is its serial number. Recording format —"system_name/block_name/idx"
. -
tgt_port::String
: full path toin
the (input) port of the block. The name and format of the record are similar toout
the port.
Examples
# Deletes the connection between the first input port of the Sine Wave block and the first output port of the Terminator block in the newmodel_1 model
engee.delete_line("newmodel_1", "Sine Wave/1", "Terminator/1")
system = engee.gcs()
engee.delete_line(system, "Sine Wave-1/1", "Terminator-1/1")
# Removal without specifying the system. It is called By default for the current system
engee.delete_line("Sine Wave-2/1", "Terminator-2/1")
#
engee.find_system
— Function
engee.find_system(; blocktype::Maybe{String}=nothing, depth::Maybe{Int}=nothing, blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())
Searches for entities (models/systems/blocks) in all available models. Returns the paths to the found entities.
Arguments
-
blocktype::Maybe{String}=nothing
: the type of block to search for. Only blocks with the specified type will be returned. -
depth::Maybe{Int}=nothing
: the maximum search depth (inclusive). To search without restrictions, you need to passnothing
. The enumeration starts from 0. By defaultnothing
. -
blockparams::Vector
: only blocks with the specified parameters will be returned.
Examples
# List of all entities
engee.find_system(;)
# List of model entities without going into subsystems
engee.find_system(; depth=0)
# List of all Sin type blocks
engee.find_system(; blocktype="Sin")
# A list of all blocks with the Value field equal to 1.0
engee.find_system(; blockparams=["Value"=>1.0])
engee.find_system(path::String; blocktype::Maybe{String}=nothing, depth::Maybe{Int}=nothing, blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())
Searches for entities (models/systems/blocks) along the specified path. Returns the paths to the found entities.
Arguments:
-
path::String
: path to the entity to be searched for -
blocktype::Maybe{String}=nothing
: the type of block to search for. Only blocks with the specified type will be returned. -
depth::Maybe{Int}=nothing
: the maximum search depth (inclusive). To search without restrictions, you need to pass nothing. The enumeration begins with0
. By default, nothing. -
blockparams::Vector
: only blocks with the specified parameters will be returned.
Examples
# The list of entities that make up the model named newmodel_1 (subsystems, blocks)
engee.find_system("newmodel_1")
# List of entities of the newmodel_1 model without entering the subsystems
engee.find_system("newmodel_1"; depth=0)
# List of all Sin type blocks in the newmodel_1 model
engee.find_system("newmodel_1"; blocktype="Sin")
# A list of all blocks with the Value field equal to 1.0 in the `newmodel_1` model
engee.find_system("newmodel_1"; blockparams=["Value"=>1.0])
engee.find_system(system::System; blocktype::Maybe{String}=nothing, depth::Maybe{Int}=nothing, blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())
Searches for entities (models/systems/blocks) in the specified system, passed as an object of the type System
. Returns the paths to the found entities.
Arguments:
-
system::System
: the system in which the search will be conducted. -
blocktype::Maybe{String}=nothing
: the type of block to search for. Only blocks with the specified type will be returned. -
depth::Maybe{Int}=nothing
: the maximum search depth (inclusive). To search without restrictions, you need to passnothing
. The enumeration begins with0
. By defaultnothing
. -
blockparams::Vector
: only blocks with the specified parameters will be returned.
Examples
# The list of entities that make up the system (subsystems, blocks)
engee.find_system(system)
# A list of system entities without going into the subsystems
engee.find_system(system; depth=0)
# A list of all Sin type blocks in the system system
engee.find_system(system; blocktype="Sin")
# A list of all blocks with the Value field equal to 1.0 in the system system
engee.find_system(system; blockparams=["Value"=>1.0])
engee.find_system(model::Model; blocktype::Maybe{String}=nothing, depth::Maybe{Int}=nothing, blockparams::Vector{<:Pair{<:AbstractString,<:Any}}=Vector{Pair{String, Any}}())
Searches for entities (models/systems/blocks) in the specified model passed as an object of the type Model
. Returns the paths to the found entities.
Arguments:
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. The search will be conducted in this model. -
blocktype::Maybe{String}=nothing
: the type of block to search for. Only blocks with the specified type will be returned. -
depth::Maybe{Int}=nothing
: the maximum search depth (inclusive). To search without restrictions, you need to passnothing
. The enumeration begins with0
. By defaultnothing
. -
blockparams::Vector
: only blocks with the specified parameters will be returned.
Examples
# The list of entities that make up the model (subsystems, blocks)
engee.find_system(model)
# List of entities model model without going into subsystems
engee.find_system(model; depth=0)
# A list of all Sin type blocks in the model
engee.find_system(model; blocktype="Sin")
# A list of all blocks with the Value field equal to 1.0 in the model
engee.find_system(model; blockparams=["Value"=>1.0])
#
engee.gcb
— Function
engee.get_current_block()::String
engee.gcb()::String
Returns the path to the current (selected) block. If the block is not selected, it returns nothing
.
#
engee.gcm
— Function
engee.get_current_model()::Model
engee.gcm()::Model
Returns the current (active) model (returns an object with the type Model
). If there is no current model, it throws an exception EngeeException
.
Examples
engee.get_current_model()
Model(
name: ssc_bridge_rectifier_modified
id: c390ed60-d2c4-4e17-85df-07129aca8ba4
)
#
engee.gcs
— Function
engee.get_current_system()::System
engee.gcs()::System
Returns the current system as an object of the type System
. If the current model is missing, it causes an error. EngeeException
.
Examples
engee.get_current_system()
System(
name: root
id: 4db18dce-1bca-46ca-8441-6f4802a78c6f
)
#
engee.generate_code
— Function
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)
Generates code in the specified language for models and/or subsystems. Supports the use of templates to customize the output code (including the function main
).
For models
-
Generation is performed for the entire model, set by an absolute or relative path to the model file.
.engee
. -
The target code generation can be specified via the parameter
target
, as well as the path to the custom template viatemplate_path
.
Arguments
-
model_path::String
: the absolute or relative path to the model from which the code is generated. A model object (an object of the type) can be used as an argument.model
received by the functionengee.gcm
). -
output_dir::String
: the absolute or relative path to the directory where the generated code will be saved. If the directoriesoutput_dir
if it does not exist, it will be created automatically. -
target::String
: specifying the language for code generation. Supported languages —Си
(by default) orVerilog
. -
template_path::String
: the path to.jl
-a template file (for example, a function templatemain
).
Examples
# Generating the C code for the model
engee.generate_code("newmodel_1.engee", "newmodel_1/codegen_output")
# Verilog code generation, the newmodel_1 file will be created.v with Verilog code
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_output", target="verilog")
# Code generation with a template containing the main function
engee.generate_code("codegen_model.engee", "codegen_dir", template_path="/user/main_template.jl")
# Getting the current open model and generating code from it
m = engee.gcm()
engee.generate_code(m, "/user/newmodel_1/codegen_output")
For subsystems
-
Generation is performed only for the atomic subsystem specified by name (
subsystem_name
) or by ID (subsystem_id
). -
The remaining parameters are similar to the generation for the full model.
Arguments
-
subsystem_name::String
: the full path to the atomic subsystem from which the code is generated. -
subsystem_id::String
: a unique identifier of the atomic subsystem from which the code is generated (alternativesubsystem_name
). -
target::String
: specifying the language for code generation. Supported languages —Си
(by default) orVerilog
.
Examples
# Generating C code for a subsystem by name
engee.generate_code("newmodel_1.engee", "newmodel_1/Subsystem", subsystem_name="Subsystem")
# Code generation for an atomic subsystem by its id
engee.generate_code("/user/newmodel_1.engee", "/user/newmodel_1/Subsystem"; subsystem_id = "88275e0b-a049-4bb5-b8c7-057badd1b536")
# Verilog code generation for the subsystem, the newmodel_1 file will be created.v with the subsystem's Verilog code
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_pid", subsystem_name="SubSystem", target="verilog")
#
engee.get_all_models
— Function
engee.get_all_models(; sorted=true)::Vector{Model}
Retrieves a list of all models opened in the current session, in the format Vector{Model}
. If the parameter sorted=true
, then returns a list of models sorted by name.
Arguments
sorted::Bool
: by default true
. Determines whether the list of models will be sorted by name.
Examples
# A list with a list of all open models
models_list = engee.get_all_models()
# A list with the names of all open models
model_names = [m.name for m in engee.get_all_models()]
#
engee.get_current_block
— Function
engee.get_current_block()::String
engee.gcb()::String
Returns the path to the current (selected) block. If the block is not selected, it returns nothing
.
#
engee.get_current_model
— Function
engee.get_current_model()::Model
engee.gcm()::Model
Returns the current (active) model (returns an object with the type Model
). If there is no current model, it throws an exception EngeeException
.
Examples
engee.get_current_model()
Model(
name: ssc_bridge_rectifier_modified
id: c390ed60-d2c4-4e17-85df-07129aca8ba4
)
#
engee.get_current_system
— Function
engee.get_current_system()::System
engee.gcs()::System
Returns the current system as an object of the type System
. If the current model is missing, it causes an error. EngeeException
.
Examples
engee.get_current_system()
System(
name: root
id: 4db18dce-1bca-46ca-8441-6f4802a78c6f
)
#
engee.get_logs
— Function
engee.get_logs([m::Model])
Retrieves log messages related to the model. Returns an array with messages.
Arguments
m::Model
: the default model for which the operation is performed is the current model. If the model is not open, it outputs an error. NoModelOpenedException
.
#
engee.get_param
— Function
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
For models
-
If the model name is specified but the parameter name is not specified, it returns the simulation settings for the selected model as a dictionary.
-
If the parameter name is specified, it returns the parameter value.
Arguments
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. The parameters will be extracted from this model. -
path::String
: a string path to the model if a path is used instead of the model object. -
param::Union{Symbol, String}
: the name of the parameter to extract. It can be a string or a character.
For blocks
-
On the way to the block, it returns either the parameter value (if specified) or a dictionary with parameters.
-
If the parameter name is specified, it returns the parameter value.
Arguments
-
block::Block
: the object of the block to extract the parameters for. -
path::String
: a string path to the block if a path is used instead of the block object. -
param::Union{Symbol, String}
: the name of the block parameter to be extracted. It can be a string or a character.
Examples
# Getting a dictionary of all model parameters
m = engee.gcm()
params = engee.get_param(m)
#
engee.get_results
— Function
engee.get_results(model_name::String)
engee.get_results(model::Model)
engee.get_results()
Returns the results of the last simulation of the model as a dictionary Dict{String, DataFrame}
, where the key is the name of the monitored port. If the model is not open, it outputs an error. NoModelOpenedException
. If the simulation is not running, it outputs an error. ModelIsNotRunningException
.
Arguments
model::Model
: a model object that can be loaded into memory using the function engee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. The operation of returning the results of the last simulation will be performed relative to this model.
Examples
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
— Function
engee.get_status()::SimulationStatus
Returns the simulation status as an object of the type SimulationStatus
. Returns one of the five simulation statuses of the model:
-
BUILDING
: the model is being built. -
READY
Questioner: the model is ready. -
NOT_READY
Questioner: the model is not ready. -
RUNNING
: the model is in progress. -
PAUSED
: the execution of the model has been suspended.
Examples
engee.get_status()
READY
#
engee.is_dirty
— Function
engee.is_dirty(model::Model)::Bool
engee.is_dirty(model_path::String)
Checks if there are unsaved model changes. Returns true
if there are unsaved changes, otherwise — false
. If the model is already closed, it returns false
.
Arguments
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. -
model_path::String
: the path to the model.
#
engee.load
— Function
engee.load(file_path::String; name::Maybe{String}=nothing, force::Bool = false)::Model
Loads the model from a file with the extension .engee
, located in file_path
. Returns Model
. The model becomes the current model. Its root system becomes the current system. Features:
-
If a model with the same name already exists and the parameter is equal to
true
, then restarts it and all previously unsaved changes will be lost if equal tofalse
, then throws an exception. By default, it is equal tofalse
. -
The model can be loaded with a different name if it is specified in the parameter
name
. If the parameter is omitted, it leaves the model name saved in the file. -
If the file has a different extension or it does not exist, it throws an exception.
Arguments
-
file_path::String
: the path to the file from which the model or data will be loaded. -
name::Maybe{String}
: used to specify the name of the loaded model or data. -
force::Bool
: by default is equal tofalse
. If equal totrue
, then the download will be performed if the file has already been previously uploaded.
Examples
engee.load("NewModel.engee"; force = true)
Model(
name: NewModel
id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
#
engee.open
— Function
engee.open(path::String)::System
engee.open(model::Model)::System
engee.open(system::System)::System
Returns an open system System
. If the model or system does not exist, it fails. EngeeException
. The behavior of the method changes if:
-
The name is specified in the parameter
model_name
a previously opened model, then it becomes the current model. Its root system becomes the current system.; -
The parameter specifies the path to the existing system.
system_path
, then the model containing it becomes the current model, and the system itself becomes the current system, which is displayed in the visual editor. ReturnsSystem
. You can also pass an instance directly instead of the path.Model
orSystem
.
Arguments
-
path::String
: the path to the model. -
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. The default is the current model. -
system::System
: the path to the system or a System type object.
Examples
# 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.resume
— Function
engee.resume(; verbose::Bool = false)
Resumes the suspended simulation.
Arguments
verbose::Bool = false
: enables the output of simulation progress messages.
#
engee.rmpath
— Function
engee.rmpath(path::String)
Removes a path from a system variable LOAD_PATH
. LOAD_PATH
— this is a system variable that Engee uses to find the necessary executable objects (for example, .engee
, .ngscript
), as well as any other paths used in commands.
Arguments
path::String
: the path in the file system to be deleted from LOAD_PATH
.
Examples
engee.addpath("/user/models")
# Loading the model
engee.load("model.engee")
engee.rmpath("/user/models")
# Loading the model will return an error.
engee.load("model.engee")
#
engee.run
— Function
engee.run([m::Model]; verbose=false)
Starts the execution of the model. If no model is specified, it starts a simulation of the current model. If the model is not open, an exception is thrown. NoModelOpenedException
.
Arguments
-
verbose
: clarifying the need to print the progress of the model execution (by default, it is equal tofalse
— not displayed). -
m::Model
: the model relative to which the operation is performed. The default is the current model.
Examples
m = engee.load("/user/start/examples/power_systems/power_line_apv/power_line_apv.engee")
engee.run(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…
# An example of asynchronous, infinite simulation
m = engee.load("/user/start/examples/controls/PID_controller/pid_controls_tf_stable.engee")
engee.set_param!(m, "end_time" => Inf)
ch = Channel(c -> put!(c, engee.run(m)))
sleep(10)
engee.stop()
take!(ch)
#
engee.save
— Function
engee.save(model_name::String, file_path::String; force::Bool = false)
engee.save(model::Model, file_path::String; force::Bool = false)
Saves the model with the name model_name
on the way file_path
to a file with the extension .engee
. If necessary, intermediate directories are created. Returns nothing
.
Arguments
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. -
model_name::String
: the desired model name in the system. -
file_path::String
: the directory of the saved model. -
force::Bool
: by default is equal tofalse
. If the file already exists and the parameter is equal totrue
, then overwrites the file. If equal tofalse
, then ends with an errorFileAlreadyExists
.
Examples
# Saves the newmodel_1 model to a new newmodel_1.engee file
engee.save("newmodel_1", "newmodel_1.engee")
# Saves the newmodel_1 model to the newmodel_1.engee file (overwrites the file)
engee.save("newmodel_1", "newmodel_1.engee", force = true)
#
engee.screenshot
— Function
engee.screenshot(to_print::Union{Model, String, System}, save_path::String; position_mode::String="auto")
Saves a screenshot of the model/system to a file along the path save_path
. Supported formats: PNG, SVG. In other cases, an error is displayed. ErrorException("unsuported picture format: <format>")
. Positioning: "auto", "tiled", in other cases "auto" will be applied.
Arguments
-
to_print::Union{Model, String, System}
: the name of the model that the screenshot will be taken from. -
save_path::String
: the path to save the screenshot. -
position_mode::String
: positioning of the screenshot. The following modes are used:"auto"
— automatically determine the optimal block location (standard mode);"tiled"
— Arrange the blocks in a grid to avoid overlaps and make the structure more readable. Any other value is perceived as"auto"
.
Examples
engee.screenshot(loaded_model, "/user/saved.png"[; position_mode="tiled"])
#
engee.set_log
— Function
engee.set_log(system_path::String, port_path::String)
engee.set_log(system::System, port_path::String)
engee.set_log(port_path::String)
Sets the port for writing.
Arguments
-
system_path::String
: the system where the port is located. -
system::System
: the system where the port is located. -
port_path::String
: the relative path to the port. If the system is not provided as the first parameter, then the default open system is used.
Examples
engee.set_log("Sine Wave/1")
# The port of the Sine Wave block in the current system is set to write
engee.set_log("newmodel_1/Subsystem","Sine Wave/1")
# The port of the Sine Wave block in the newmodel_1/Subsystem system is set to write
system = engee.gcs()
engee.set_log(system, "Sine Wave/1")
# The port of the Sine Wave block in the system is set to write
engee.run()
Dict{String, DataFrames.DataFrame} with 1 entry:
"Sine Wave.1" => 1001×2 DataFrame…
#
engee.set_param!
— Function
engee.set_param!(model::Model | model_name::String, param::Pair...)
Updates the parameters of the models. Returns nothing
. If the parameters are incorrect, an error occurs.
Arguments
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. The parameters will be updated for this model. -
model_name::String
: string path or model name. -
param::Pair...
: one or more parameters in the format"name" => value
.
Examples
engee.set_param!("model_1", "SolverName" => "ode45", "StopTime" => "10")
# We get the parameters of the model_1 model
param_1 = engee.get_param("model_1")
# Copy the parameters from model_1 to model_2
engee.set_param!("model_2", param_1)
The example shows how you can use get_param
and set_param!
together to copy parameters between models.
The structure of the simulation settings is tied to a specific model. You can change the model settings directly by setting the structure fields, then:
params = engee.get_param("newmodel_1")
# The params structure is tied to a specific model, similar to engee.set_param!("newmodel_1", "FixedStep" => "0.05")
params["FixedStep"] = "0.05"
0.05
Changing the values in the dictionary params
it does not update the model parameters automatically — it is a local copy. For the changes to take effect, you need to send the dictionary back using 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"])
Each parameter must be represented as a pair consisting of the parameter name and its value (for example, "StartTime" => 0.0
). For the parameter param
:
Simulation Parameters
-
StartTime::String
: the start time of the simulation (Float64). -
StopTime::String
: the end time of the simulation (Float64). To set an infinite simulation time, pass the string"Inf"
or"inf"
(engee.set_param!("model_name", "StopTime" => "Inf")
) -
SolverType::String
: type of solver (fixed-step
orvariable-step
). -
SolverName::String
: the name of the solver (depends on the selected type).
Parameters for fixed-step
FixedStep::String
: simulation step (Float64).
Parameters for variable-step
-
AbsTol::String
: absolute precision (Float64 or 'auto'). -
RelTol::String
: relative precision (Float64 or 'auto'). -
InitialStep::String
: initial step (Float64 or 'auto'). -
MaxStep::String
: maximum step (Float64 or 'auto'). -
MinStep::String
: minimum step (Float64 or 'auto'). -
OutputTimes::String
: output interval (Float64 or 'auto'). -
DenseOutput::Bool
: dense output of results.
engee.set_param!(block::Block | block_path::String, params::Pair{String}...)
Updates the block parameters.
Arguments
-
block::Block
: the block object. -
block_path::String
: the string path to the block. -
params::Pair{String}...
: block parameters in the format"name" => value
.
Examples
engee.set_param!("newmodel_1/Генератор синусоиды", "Phase" => 1.0, "Amplitude" => 3.0, "Frequency" => 4.0)
#
engee.unset_log
— Function
engee.unset_log(system_path::String, port_path::String)
engee.unset_log(system::System, port_path::String)
engee.unset_log(port_path::String)
Removes the port from recording.
Arguments
-
system_path::String
: the system where the port is located. -
system::System
: the system where the port is located. -
port_path::String
: the relative path to the port. If the system is not provided as the first parameter, then the default open system is used.
Examples
engee.set_log("Sine Wave/1")
# The port of the Sine Wave block in the current system is set to write
engee.run()
Dict{String, DataFrames.DataFrame} with 1 entry:
"Sine Wave.1" => 1001×2 DataFrame…
# We ran the simulation and got the results
engee.unset_log("Sine Wave/1")
# The port of the Sine Wave block in the current system has been de-recorded
engee.run()
Dict{String, DataFrames.DataFrame}()
#
engee.update_params
— Function
engee.update_params()
engee.update_params(model::Model)
engee.update_params(model_name::String)
Updates the parameters of a running simulation by rereading their current values from the workspace.
The function allows you to dynamically apply parameter changes in the workspace to an already running simulation without having to stop and restart it. If there is no working simulation, then the function does nothing.
It can take as an optional argument the name of the model or the object of the model for which the parameter update should be applied. This functionality is equivalent to clicking the "Compile Model" button during the simulation.
Arguments
-
model::Model
: a model object that can be loaded into memory using the functionengee.gcm
. This model can be active in the workspace, but not necessarily open in the GUI. -
model_name::String
: the name of the model whose parameters need to be recalculated.
Examples
# Updates the parameters of all blocks in the current simulation
engee.update_params()
# Updates the parameters of the specified model
model = engee.gcm()
engee.update_params(model)
# Updates model parameters by name
engee.update_params("newmodel_1")
#
engee.version
— Function
engee.version()
Returns the short version of Engee.
Examples
engee.version()
"24.10.0"