Engee documentation

Public methods of program management

See also: Application of software model management

All public methods of program management are presented here. engee. To get acquainted with the methods engee.script refer to the article Software script management.

Methods engee

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,
    colours::Union{BlockColours, Missing} = missing,
    annotation::Union{Maybe{String}, Missing} = missing,
    is_name_visible::Union{Maybe{Bool}, Missing} = missing,
)::String

Adds a block from the library. Returns a path to the added block.

When adding a block, you can specify its visual properties. Properties that are not specified take their default values.

Arguments

  • lib_block_path::String: the path to the block in the library (starting with /).

  • tgt_block_path::String: path to the target system and the expected name of the new block. If only the system name is specified (for example, "newmodel_1/"), the block name will be generated automatically. If a full path including the block name is specified (e.g. "newmodel_1/Sum1"), the block will be given the specified name.

  • top::Union{Int, Missing}: the top coordinate of the block.

  • left::Union{Int, Missing}: the left coordinate of the block.

  • width::Union{Int, Missing}: the width of the block.

  • height::Union{Int, Missing}: the height of the block.

  • rotation::Union{Int, Missing}: the block’s rotation angle.

  • is_flipped::Union{Bool, Missing}: the block’s mirror flip flag.

  • colours::Union{BlockColours, Missing}: the block’s colour properties.

  • annotation::Union{Maybe{String}, Missing}: the block’s annotation.

  • is_name_visible::Union{Maybe{Bool}, Missing}: flag indicating whether the block’s name is displayed.

Examples

# Adding a block


       (50, 50)  (100, 100)


          " ".


           " ".


 ,


    (        )


  (        )


  (        )


      (  )


      (  )


      (     )


   -3


       ‘ ’    ‘ ’


     " / "  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")

# Adding a block with visual properties
engee.add_block(
    "/Basic/Sinks/Terminator",
    engee.gcm().name * '/';
  # the block will be added at point with dimensions
	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})

Adds a connection (data stream) between blocks. Two methods of specifying ports are supported:

  • Via string paths to ports: "block_path/idx" or "block_path/port_name", where block_path is the block’s path relative to the selected system. If the system is not passed as a separate argument, the current system is used.;

  • Via port handles (PortHandle), obtained, for example, using engee.get_ports.

A port handle (PortHandle) is an object that uniquely identifies a specific block port within the model. It does not contain a signal value, but serves as a ‘handle’ ‘Handle’ for programmatic interaction with ports — it can be passed to engee.add_line, engee.delete_line, engee.get_lines and other functions.

Features of physical modelling (acausal)

In Engee physical modelling blocks, ports are undirected (acausal). This imposes the following characteristics on how connections are handled:

  • A connection between PortHandle{ACAUSAL} does not specify the direction of data flow, but simply links two physical nodes;

  • A single undirected port may have multiple connections (several lines);

  • Connections between blocks are represented by separate Line objects.

Therefore, when analysing or modifying the model programmatically, a step-by-step approach is used:

  • Retrieve the block’s port using engee.get_ports;

  • Retrieve the lines connected to this port using engee.get_lines;

  • Obtain the neighbouring ports (source and destination) from the Line objects;

  • Perform the reconnection using engee.add_line.

Arguments

String options:

  • system::System: an object of type System;

  • system_path::AbstractString: the path to the system;

  • src_path::AbstractString: relative path to the out (output) port or an acausal port of the block. The record format is "system_name/block_name/idx" or "system_name/block_name/port_name";

  • dst_path::AbstractString: the relative path to the in (input) port or a non-directional (acausal) port of a block. The format is "system_name/block_name/idx" or "system_name/block_name/port_name".

Variants with port handles:

  • src::PortHandle{OUT}, dst::PortHandle{IN} — handles for the directed source and destination ports;

  • src::PortHandle{IN}, dst::PortHandle{OUT} — the reverse direction (where, according to the diagram, the source is the block with the input port);

  • src::PortHandle{ACAUSAL}, dst::PortHandle{ACAUSAL} — descriptors of acausal ports.

Examples

Strings:

# Connects the first output port of the Sine Wave block to the first input port of the Terminator block in the current system
engee.add_line("Sine Wave/1", "Terminator/1")

# The first argument can be a System object
system = engee.gcs()

# This call is equivalent to the previous one
engee.add_line(system, "Sine Wave-1/1", "Terminator-1/1")

# Port names can be used instead of indices
engee.add_line("model", "Resistor/p", "Resistor-1/n")

Descriptors:

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")

# Retrieve the block ports
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")

# Connect the output of the Sine Wave block to the first input of the Add_block
engee.add_line(src_ports.outputs[1], add_ports.inputs[1])

# Connect the output of the Add_block to the input of the Terminator
engee.add_line(add_ports.outputs[1], dst_ports.inputs[1])

In physical modelling (acausal), a port may have multiple connections, so it is not possible to use only source or destination directly. In such cases, a step-by-step approach is used along the chain: port → line → neighbouring port:

  • Retrieve the block’s port using engee.get_ports;

  • Retrieve the line or lines connected to this port using engee.get_lines;

  • From the Line object, retrieve the adjacent port (line.source or line.destination);

  • Perform the reconnection using engee.add_line.

Below is an example of replacing a physical block whilst restoring connections, carried out using this sequence.

# Retrieve the input port of the PID Controller block namedin This is the receiving port
pid_input_port = engee.get_ports("newmodel_1/PID Controller").inputs["in"]

# Retrieve the connection line corresponding to this port
pid_input_line = engee.get_lines(pid_input_port)

# Retrieve the source port for this line
pid_source_port = pid_input_line[1].source

# Retrieve the input port of the new PID Controller block namedin This is the sink port
new_pid_input_port = engee.get_ports("newmodel_1/PID Controller New").inputs["in"]

# Connect the source port to the sink port
engee.add_line(pid_source_port, new_pid_input_port)

# Retrieve the output port of the PID Controller
pid_output_port = engee.get_ports("newmodel_1/PID Controller").outputs["out"]

# Retrieve the connection line for this port
pid_output_line = engee.get_lines(pid_output_port)

# Get the destination port for this line
pid_dest_port = pid_output_line[1].destination

# Remove the old PID Controller block
engee.delete_block("newmodel_1/PID Controller")

# Get the output port of the new PID Controller block
new_pid_output_port = engee.get_ports("newmodel_1/PID Controller New").outputs["out"]

# Connect the output port of the new PID Controller to the old receiver port
engee.add_line(new_pid_output_port, pid_dest_port)

# Optionally we can automatically format the model
engee.arrange_system(engee.gcs())
engee.addpath(path::Vararg{String})

Adds one or more paths to the LOAD_PATH system variable.LOAD_PATH is a system variable that Engee uses to locate the required executable objects (e.g..engee, .ngscript), as well as any other paths used in commands.

Arguments

path::Vararg{String}: one or more paths in the file system (absolute or relative).

Examples

engee.addpath("/user/models")
# Loading a model
engee.load("model.engee")
    engee.arrange_system(system::System = engee.gcs())
    engee.arrange_system(system_path::AbstractString)
The system is organised in the same way as the ‘Organise Model’ button on the canvas. Takes a system or a path to a system.
engee.arrange_system(system::System)

Reorganises the layout of blocks and connections in the specified model, automatically arranging elements to minimise line crossings and make the model structure more readable. This function is equivalent to the ‘Reorganise Model’ context menu command on the Engee canvas. Reorganisation is performed only for the specified model (without recursively modifying nested subsystems).

Arguments

system::System: the system (model) object for which automatic reorganisation is to be performed. Can be obtained using engee.gcs().

Examples

# Organises the currently open model
engee.arrange_system(engee.gcs())
engee.clear()

Clears all variables in the current workspace.clear() removes all data stored in variables to free up memory for new computations and data streams. Returns nothing.

engee.clear_all()

Clears all variables, functions and defined modules from the current workspace.clear_all() restores the current workspace to its initial state. Returns nothing.

engee.clearport(portpath::AbstractString)

Removes all lines associated with the specified port. If a port index is used instead of a name, the port is searched for amongst the block’s output ports.

Example:

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)

Closes the model named model_name. The model opened furthest to the left in the model navigation pane becomes the current model. If no model is specified, closes the current model. If no current model is specified, does nothing. If the model no longer exists, does nothing.

Arguments

  • model_name::String: the name of the model to be closed.

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not necessarily be open in the graphical interface.

  • force::Bool: defaults to false. If there are unsaved changes and this parameter is set to false, the operation will terminate with an error. If it is set to true, any unsaved changes will be lost.

Examples

# Unloads the model newmodel_1 from memory
engee.close("newmodel_1")

# Unloads the model newmodel_1 from memory without saving the latest changes
engee.close("newmodel_1", force=true)

# Closes the model newmodel_1unloads it and removes it from the canvas
engee.close("newmodel_1", force=true)
engee.close_all()

Closes all models.

Examples

# Unloads all open models from memory
engee.close_all()
engee.compare_models(model_path_1::String, model_path_2::String)

Compares a pair of models and returns a list of differences.

Arguments

  • model_path_1::String: the absolute or relative path to the first model to be compared.

  • model_path_2::String: the absolute or relative path to the second model to be compared with the first.

Examples

# Absolute pathspecifying the full path to the model file
m1 = "/user/modelname_1.engee"

# Relative pathspecifying the relative path to the model file
m2 = "modelname_2.engee"

# Comparing m1 and m2
engee.compare_models(m1, m2)
engee.convert_model(model_path::String, out_path::String="")

Generates an .ngscript file (an Engee script) to build the current model using software control commands. When the script is executed, the model is created in non-interactive mode and is not displayed on the canvas. If an error occurs whilst creating the model, you must execute the command engee.close(...) to restart the script.

Arguments

  • model_path::String: the absolute or relative path to the source model in .engee or .slx format, which needs to be converted.

  • out_path::String: the path where the generated script is to be saved.

    • If out_path is not specified or is equal to "", the function returns the generated script as a string and does not save it to a file.

    • If out_path is specified, the script is saved to the specified path and the function returns nothing. The .jl extension is recommended for subsequent execution in Julia.

Examples

# Saving the script to a fileabsolute path
model_path = "/user/newmodel_1.engee"
engee.convert_model(model_path, "/user/newmodel_1.jl")

# Saving the script to a filerelative path
engee.convert_model("newmodel_2.engee", "newmodel_2.jl")

# Retrieving the script as a stringwithout saving to a file
script = engee.convert_model("/user/newmodel_1.engee")
    engee.convert_unit(value::T, from::String, to::Maybe{String})::Real where T<:Real
Converts value to different units of measurement: from from to to. If to is nothing,
then it converts to SI units.

Example:

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

Copies a block from the system.

If duplicate=true and src_path points to an Inport block, the function creates a duplicate of the input port (Inport Shadow): the duplicate is assigned the same input port number as the original Inport, and allows the signal from the input to be branched without creating a new subsystem input port.

Arguments

  • src_path::AbstractString: the path to the block in the model hierarchy (e.g. "model/system/block" or "model/block" for the root folder).

  • dst_path::AbstractString: path to the system and the expected name. The format is path/to/system/new_block_name. If the name is not specified, it is assigned automatically.

  • duplicate::Bool: duplication flag for Inport blocks. For other block types, setting the flag (duplicate=true) will result in an error: "Duplication not allowed for this block type: only 'Inport' blocks can be duplicated".

Examples

# Adds the Add 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 newmodel_2 model under the name Test_name
engee.copy_block("newmodel_1/Custom Block Name", "newmodel_2/Test_name")
engee.copy_contents(src_path::AbstractString, dst_path::AbstractString)

Copies the contents of one system to another. The target system must be empty. Recursive copying is not permitted.

Arguments

  • src_path::AbstractString: the path to the system from which the copy is made.

  • dst_path::AbstractString: the path to the system to which the copy is made.

Examples

# Copying the contents from the root systemnewmodel_1 to the root systemnewmodel_2
engee.copy_contents("newmodel_1", "newmodel_2")

# Copying the contents from thenewmodel_1Subsystem subsystem to the `newmodel_1/Subsystem-1` subsystem
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

Creates a new model named model_name with default parameters. Returns Model. The model becomes the current model. Its root system becomes the current system. If a model with this name already exists, an EngeeException is thrown.

Arguments

model_name::String: the desired name of the model in the system. The model name must not contain the character /.

Examples

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

Removes the block, all associated lines and recorded ports from the system.

Arguments

block_path::String: path to the block.

Examples

# Deletes the Sine Wave block and all associated lines and blocks from the system
engee.delete_block("newmodel_1/Sine Wave")
engee.delete_contents(system_path::String)

Deletes the contents of the system.

Arguments

system_path::String: the path to the system whose contents are to be deleted.

Examples

# Deleting all blocks from the Subsystem -1 subsystem in the newmodel_1 model
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})

Three methods are supported for specifying the connection to be deleted:

  • By string paths to ports ("system_name/block_name/idx");

  • By the Line object obtained via engee.get_lines;

  • Using port descriptors (PortHandle) obtained via engee.get_ports or from the Line structure.Line describes a single connection line in the diagram and contains, in particular, the source and destination ports: source::PortHandle, destination::PortHandle.

The methods for deletion via Line and PortHandle{ACAUSAL} also apply to undirected (acausal, physical) connections.

Arguments

String variants:

  • system::Union{AbstractString, System}: path to the system or an object of type System;

  • src_path::AbstractString: relative path to the out (output) port of the block. The port name is its ordinal number. The format is "system_name/block_name/idx";

  • dst_path::AbstractString: relative path to the in (input) port of the block. The port’s ordinal number is used as its name. The entry format is "system_name/block_name/idx".

Variants with Line objects and port descriptors:

  • line::Line: a line object returned by engee.get_lines(...). Contains the line identifier and the source and sink port descriptors;

  • src::PortHandle{OUT}, dst::PortHandle{IN} — descriptors for the source and destination ports;

  • src::PortHandle{IN}, dst::PortHandle{OUT} — the opposite direction (where, by definition, the source

is considered to be the block with the input port);

  • src::PortHandle{ACAUSAL}, dst::PortHandle{ACAUSAL} — descriptors for non-directed ports.

Examples

# Removes 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")

# Deletion without specifying a system . By default , this applies to the current system
engee.delete_line("Sine Wave-2/1", "Terminator-2/1")

# Example of working with port descriptors (PortHandle); we assume that the blocks are already connected via `engee.add_line`, as in the example for `add_line`
src_ports = engee.get_ports("newmodel_1/Sine Wave")
dst_ports = engee.get_ports("newmodel_1/Terminator")

# Delete the line between the first output of Sine Wave and the first input of Terminator
engee.delete_line(src_ports.outputs[1], dst_ports.inputs[1])

# Example of deleting all lines connected to the block

# Retrieve all lines connected to the Add_block block
all_block_lines = engee.get_lines("newmodel_1/Add_block")

# Delete all these lines using Line objects
for ln in all_block_lines
    engee.delete_line(ln)
end

# Equivalent notation using dot notation
engee.delete_line.(engee.get_lines("newmodel_1/Add_block"))
engee.eval(code::AbstractString)

Executes Julia code in the current model context.

Arguments

code::AbstractString: a string containing Julia code to be executed.

Examples

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}}())

Searches for entities (models/systems/blocks) along the specified path. Returns the paths to the entities found.

Arguments

  • path::String: the path to the entity in which the search will be performed.

  • depth::Int=typemax(Int): the maximum search depth (inclusive). To perform an unrestricted search, use typemax(Int). Indexing starts at 0. The default is typemax(Int).

  • blockparams::Vector: only blocks with the specified parameters will be returned.

Examples

# List of entities comprising the model named newmodel_1 (subsystems, blocks)
engee.find_system("newmodel_1")

# List of entities in the newmodel_1 model without entering subsystems
engee.find_system("newmodel_1"; depth=0)

# A list of all blocks with a `Value` field equal to 1.0 in the `newmodel_1` model
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}}())

Searches for entities (models/systems/blocks) in all available models. Returns paths to the entities found.

Arguments

  • depth::Int=typemax(Int): maximum search depth (inclusive). For an unrestricted search, use typemax(Int) is used. Indexing starts at 0. The default is typemax(Int).

  • blockparams::Vector: only blocks with the specified parameters will be returned.

Examples

# List of all entities
engee.find_system()

# List of model entities without entering subsystems
engee.find_system(; depth=0)

# List of all blocks with a `Value` field equal to 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}}())

Searches for entities (models/systems/blocks) in the specified system, passed as an object of type System. Returns the paths to the entities found.

Arguments

  • system::System: the system in which the search will be carried out.

  • depth::Int=typemax(Int): maximum search depth (inclusive). Use typemax(Int) for an unrestricted search. Indexing starts at 0. The default is typemax(Int).

  • blockparams::Vector: only blocks with the specified parameters will be returned.

Examples

# List of entities comprising the system system (subsystems, blocks)
engee.find_system(system)

# List of entities in the system system without entering subsystems
engee.find_system(system; depth=0)

# A list of all blocks with a `Value` field equal to 1.0 in the system `system`
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}}())

Searches for entities (models/systems/blocks) in the specified model, passed as an object of type Model. Returns the paths to the entities found.

Arguments

  • model::Model: a model object, which can be loaded into memory using the engee.gcm. This model may be active in the workspace, but need not be open in the graphical interface. The search will be carried out within this model.

  • depth::Int=typemax(Int): maximum search depth (inclusive). To search without restrictions, use typemax(Int). Indexing starts at 0. The default is typemax(Int).

  • blockparams::Vector: only blocks with the specified parameters will be returned.

Examples

# List of entities comprising the model (subsystems, blocks)
engee.find_system(model)

# List of entities in the model model without delving into subsystems
engee.find_system(model; depth=0)

# List of all blocks with a Value field equal to 1.0 in the model model
engee.find_system(model; blockparams=["Value"=>1.0])
engee.get_current_block()::String
engee.gcb()::String

Returns the path to the current block. If there is no current block or model, it raises the error Current block is not set.

Examples

# The Sine Wave block is highlighted on the canvas
engee.gcb()
"newmodel_1/Sine Wave"
engee.get_current_model()::Model
engee.gcm()::Model

Returns the current model. If there is no current model, it raises a No opened model error.

Examples

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

Returns the current system. If there is no current model, returns the error No opened model.

Examples

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)

Generates code in the specified language for models and/or subsystems. Supports the use of templates to customise the output code (including the main function).

For models

  • Generation is performed for the entire model, specified by an absolute or relative path to the .engee model file.

  • The code generation target can be specified via the target parameter, as well as the path to a custom template via template_path.

Arguments

  • model_path::String: the absolute or relative path to the model from which the code is generated. The argument may be a model object (an object of type model, returned by the engee.gcm function).

  • output_dir::String: the absolute or relative path to the directory in which the generated code will be saved. If the output_dir directory does not exist, it will be created automatically.

  • template_path::String: the path to a .jl template file (for example, the template for the main function).

  • target::String: Specifies the language for code generation. Supported languages are C (by default), Verilog or Promela.

Examples

# Generating C code for the model
engee.generate_code("newmodel_1.engee", "newmodel_1/codegen_output")

# Generating Verilog code ; a file named newmodel_1 .v containing Verilog code will be created
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_output", target="verilog")

# Generating code using a template containing the `main` function
engee.generate_code("codegen_model.engee", "codegen_dir", template_path="/user/main_template.jl")

# Retrieving the currently open model and generating code from it
m = engee.gcm()
engee.generate_code(m, "/user/newmodel_1/codegen_output")

For subsystems

  • Code generation is performed only for an atomic subsystem specified by name (subsystem_name) or by identifier (subsystem_id).

  • The remaining parameters are the same as for full-model generation.

Arguments

  • subsystem_name::String: the full path to the atomic subsystem from which the code is generated.

  • subsystem_id::String: the unique identifier of the atomic subsystem from which the code is generated (an alternative to subsystem_name).

  • target::String: specifies the language for code generation. Supported languages are C (default) or Verilog.

Examples

# Generating C code for a subsystem by name
engee.generate_code("newmodel_1.engee", "newmodel_1/Subsystem", subsystem_name="Subsystem")

# Generating code 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")

# Generating Verilog code for the subsystem ; a file named newmodel_1 .v containing the subsystem ’s Verilog code will be created
engee.generate_code("newmodel_1.engee", "newmodel_1/verilog_pid", subsystem_name="SubSystem", target="verilog")

# Generate Promela code for the "Subsystem" subsystem; a file will be created
engee.generate_code("newmodel_1.engee", "newmodel_1/Subsystem", subsystem_name="Subsystem", target="promela")
engee.get_all_models(; sorted=true)::Vector{Model}

Returns a list of all models open in the current session, in the format Vector{Model}. If the parameter sorted=true, it returns a list of models sorted by name.

Arguments

sorted::Bool: default true. Determines whether the list of models will be sorted by name.

Examples

# A list containing all open models
models_list = engee.get_all_models()

# A list containing the names of all open models
model_names = [m.name for m in engee.get_all_models()]
engee.get_current_block()::String
engee.gcb()::String

Returns the path to the current block. If there is no current block or model, it returns the error Current block is not set.

Examples

# The Sine Wave block is highlighted on the canvas
engee.gcb()
"newmodel_1/Sine Wave"
engee.get_current_model()::Model
engee.gcm()::Model

Returns the current model. If there is no current model, returns the error No opened model.

Examples

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

Returns the current system. If there is no current model, returns the error No opened model.

Examples

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}

Returns the signal lines (Line) connected to a block or a specific port. Returns a Vector{Line}-- a vector of Line objects, each of which describes a single connection between two ports.

A Line is an object describing a single connection in the diagram:

  • id::UUID — the line identifier;

  • source::PortHandle — the source port;

  • destination::PortHandle — the destination port.

The Line object can, for example, be passed to engee.delete_line(line::Line) to delete the connection.

The function engee.get_lines(...) always returns a vector of lines (Vector{Line}), even if there is only one line. This is important for undirected (acausal) ports in physical modelling, where a single port may have multiple connections.

Arguments

  • block_path::AbstractString: the path to the block in the model hierarchy. The format is "model_name/block_name" or "model_name/system_name/block_name".

  • causality::PortCausality: the type of ports for which lines are to be retrieved. The following values from the PortCausality enumeration are supported:

    • IN — lines connected to the block’s input ports;

    • OUT — lines connected to the output ports;

    • ACAUSAL — lines connected to undirected ports.

  • port::PortHandle: the block’s port descriptor (PortHandle{IN}, PortHandle{OUT} or PortHandle{ACAUSAL}), for example, obtained via engee.get_ports.

Examples

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")

#  Connect 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])

# All lines connected to the Add_block
all_add_lines = engee.get_lines("newmodel_1/Add_block")

# Only lines to the output ports of the Sine Wave block
sine_out_lines = engee.get_lines("newmodel_1/Sine Wave", OUT)

# Lines connected to a specific port
first_add_input  = add_ports.inputs[1]
lines_to_add_in1 = engee.get_lines(first_add_input)

# Delete all lines connected to the Add_block block
engee.delete_line.(engee.get_lines("newmodel_1/Add_block"))

Retrieving neighbouring ports via lines (port → lines → port):

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()

Retrieves messages from the log associated with the model. If no model is open, it returns the error No opened model. Returns an array of messages.

Arguments

m::Model: the model on which the operation is performed; by default, the current model.

Examples

engee.get_logs()
4-element Vector{Dict{Symbol, String}}:
 Dict(:datetime => "2025-10-27T20:18:38.465684+00:00", :type => "INFO", :content => "Simulation preparation completed in 5.8178 s.")
 Dict(:datetime => "2025-10-27T20:18:39.412789+00:00", :type => "INFO", :content => "Model compilation completed in 1.833 s.")
 Dict(:datetime => "2025-10-27T20:18:39.412896+00:00", :type => "INFO", :content => "Model initialisation completed in 0.0903 s.")
 Dict(:datetime => "2025-10-27T20:18:39.842869+00:00", :type => "INFO", :content => "Model simulation completed in 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

For models

  • If a model name is specified but no parameter name is given, returns the simulation settings for the selected model as a dictionary.

  • If a parameter name is specified, returns the parameter’s value.

Arguments

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not necessarily be open in the graphical interface. The parameters will be extracted from this model.

  • path::String: a string path to the model, if a path is used instead of a model object.

  • param::Union{Symbol, String}: the name of the parameter to be retrieved. May be a string or a symbol.

For blocks

  • Given a path to a block, returns either the parameter value (if specified) or a dictionary of parameters.

  • If a parameter name is specified, it returns the parameter value.

Arguments

  • block::Block: the block object from which the parameters are to be extracted.

  • path::String: the string path to the block, if a path is used instead of a block object.

  • param::Union{Symbol, String}: the name of the block parameter to be retrieved. May be a string or a symbol.

Examples

# Retrieving a dictionary of all model parameters
m = engee.gcm()
params = engee.get_param(m)
engee.get_ports(block_path::AbstractString)::BlockPorts

Returns a BlockPorts structure containing the port descriptors for the specified block.

A port descriptor is a special object (PortHandle) that uniquely identifies a specific port of a block within the model. It contains all the information required to work with the port: which block it belongs to, its type (input, output, acausal) and its index within the block.

The descriptor is not a signal value, but serves as a pointer to the port, which can be passed to other functions, such as

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

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

  • engee.get_lines(port::PortHandle).

Thus, PortHandle is a ‘handle’ for working with ports in Engee models via software.

Arguments

block_path::AbstractString: the path to the block within the model hierarchy. The format is "model_name/system_name/block_name" or "model_name/block_name" for a block in the root system.

Return value

BlockPorts: a structure containing three port dictionaries:

  • inputs::IntStringDict{PortHandle{IN}} — input ports;

  • outputs::IntStringDict{PortHandle{OUT}} — output ports;

  • acausal::IntStringDict{PortHandle{ACAUSAL}} — acausal ports.

Ports can be accessed either by index (ports.outputs[1]) or by port name (ports.outputs["main_out"]).

Physical modelling

For physical modelling blocks, undirected ports are located in the ports.acausal dictionary. The names of these ports depend on the specific block (for example, "p", "n", "pin"). To find out the available port names, use collect(keys(ports.acausal)).

Examples

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")

# Retrieving block ports in the newmodel_1 model
src_ports = engee.get_ports("newmodel_1/Sine Wave")
dst_ports = engee.get_ports("newmodel_1/Terminator")

# Access by index
first_src_out = src_ports.outputs[1]
first_dst_in  = dst_ports.inputs[1]

# The ports of the Add_block are also accessible by index
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]

# Retrieving block ports with named ports (ports must be named beforehand )
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"]

# Output
# 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)

Retrieving the undirected ports of a physical block:

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

# List of acausal port names
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()

Returns the results of the latest model simulation as a dictionary Dict{String, DataFrame}, where the key is the name of the monitored port. If the model is not open, a NoModelOpenedException is raised. If the simulation is not running, a ModelIsNotRunningException is raised.

Arguments

model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but does not necessarily need to be open in the graphical interface. The operation to retrieve the results of the latest simulation will be performed on 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()::SimulationStatus
engee.get_status(model_name::String)::SimulationStatus
engee.get_status(model::Model)::SimulationStatus

Returns the simulation status as an object of type SimulationStatus. Returns one of the model’s simulation statuses:

  • NOT_READY;

  • READY;

  • BUILDING;

  • RUNNING;

  • PAUSED;

  • STARTED;

  • ERROR;

  • STOPPED;

  • DONE.

Arguments

  • model_name::String: the name of the model for which you wish to retrieve the status.

  • model::Model: a model object of type Model for which you wish to retrieve the status.

Examples

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

Returns the visual properties of the block. If the block does not have a view field, the function returns nothing.

Arguments

  • block_path::AbstractString: a string path to the block.

Examples

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

Sends an information message to the model diagnostics window. The function is called only within block callbacks (including masked ones). Messages can reference parameter names in the workspace (in the variables window) using $parameter_name.

Arguments

info_message::String: the information message to be passed.

Examples

# Example without a reference to workspace parameters
engee.info("Model successfully initialised!")

# Message in the diagnostics window :
# The model has been successfully initialised !

# Example referencing workspace parameters
engee.info("The model has been successfully initialised with parameters $Kp and $Ki!")

#  Message in the diagnostics window :
# Model successfully initialised with parameters 1.4 and 1.8!
engee.is_dirty(model::Model)::Bool
engee.is_dirty(model_name::String)::Bool

Checks whether there are any unsaved changes to the model. Returns true if there are unsaved changes, otherwise false. If the model is already closed, it returns false. For a recently opened model, it may return true if the model was opened from an older version of the file (the model will be updated upon saving).

Arguments

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not be the currently selected model.

  • model_path::String: the path to the model.

Examples

# Checking the current model
model = engee.gcm()
engee.is_dirty(model)

#  Check by model name
engee.is_dirty("newmodel_1")
engee.load(file_path::String; name::Maybe{String}=nothing, force::Bool=false)::Model

Loads a model from a file with the extension .engee, located at the path file_path. Returns a Model object. The loaded model becomes the current model, and its root system becomes the current system.

Features

  • The identifier for a ‘previously loaded’ model within a session is the model’s name (either read from the file or specified via name).

  • If a model with that name has already been loaded:

    • When force=false (by default), the function returns the model from memory and does not re-read the file at the specified path (including if file_path points to a different file or directory, but the model name is the same);

    • When force=true, the model is forcibly reloaded from the file at the specified path; any unsaved changes to the current model with that name will be lost.

  • To load multiple files that contain the same model name, specify a unique name (otherwise, the model already open in memory will be used).

  • For batch processing (converting/saving multiple models), it is recommended either to call engee.load(...; force=true) each time a model is opened, or to close the model after saving (for example, engee.close(...)/engee.close()) so as not to leave it in memory between iterations.

  • If the file does not exist or has a different extension, an exception will be thrown.

Arguments

  • file_path::String: the absolute or relative path to the model file with the extension .engee.

  • name::Maybe{String}: the name under which the model will be loaded into the current session. If not specified, the name stored in the file is used.

  • force::Bool: force load flag.

    • false — if a model with this name is already loaded, an instance is returned from memory (the file is not re-read);

    • true — forces the model to be loaded from the file at the specified path, even if a model with that name is already loaded (unsaved changes will be lost).

Examples

#  Normal loading (force = false by default )
engee.load("NewModel.engee")
Model(
 name: NewModel
 id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)

# Reloading the same model with `force=false`# (if a model named `NewModel` is already open , the same one will be retrieved from memory )
engee.load("NewModel.engee"; force = false)
Model(
 name: NewModel
 id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)

# Force loading from a file at the specified path (force=true)
# The model will be reloaded from the file . Any unsaved changes to the current model will be lost .
engee.load("NewModel.engee"; force = true)
Model(
 name: NewModel
 id: 6b59d80d-8b48-419d-83e7-a90660aa1a6a
)
engee.log(message::String)

Writes a message to the event log. The function is only called within block callbacks (including masked ones). In messages, you can refer to parameter names in the workspace (in the variables window) using $parameter_name.

Arguments

message::String: a text message to be written to the log.

Examples

engee.log("Condition fulfilled in $time" seconds)
Condition fulfilled in 6.7538 seconds
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)

Performs model calculations at the specified simulation phase without running a full simulation. Allows you to obtain auxiliary information about the problem size, outputs and state derivatives, and is used in internal algorithms (operating point search, linearisation). It is not intended for step-by-step debugging and does not replace the public method engee.run.

The function only works if a model file named model_name is open.

Arguments

  • model_name::String: the model name.

  • t::Union{Float64, Nothing}: simulation time step. Used for the :outputs and :derivatives phases. For the :sizes phase, this may be nothing and is ignored.

  • x::Union{Vector{Float64}, Float64, Nothing}: a vector or scalar of model states. For models without states, this may be nothing. For the :sizes phase, this is ignored.

  • u::Union{Vector{Float64}, Float64, Nothing}: a vector or scalar of the model’s input signals. If the model contains no input ports, this must be nothing. For the :sizes phase, this is ignored.

  • phase::Symbol: simulation phase. Supported values:

    • :sizes: specification of the simulation problem dimensions (number of states, inputs/outputs and sampling frequencies);

    • :outputs: calculation of the model’s outputs for given t, x, u;

    • :derivatives: calculation of the derivatives of continuous states for given t, x, u.

Return Values

Depending on the value of phase, the behaviour of the function will vary as follows:

  • phase == :sizes

    • A tuple is returned:

  • sys — a vector of integers containing information about the model’s structure:

  • sys[1] — the number of continuous states; - sys[2] — the number of discrete states;

  • sys[3] — the number of model outputs;

  • sys[4] — the number of model inputs;

  • sys[5] — the number of sampling times in the model.

  • blks — the names of blocks containing states.

  • x0 — the initial values of the model’s states. If the model does not contain any blocks with states, nothing is returned.

  • phase == :outputs

    • Returns:

  • y::Union{Vector{Float64}, Float64, Nothing}-- the model’s outputs for the given t, x and u.

  • If the model does not contain any output ports, nothing is returned. - The elements of the vector y are ordered according to the full names of the output blocks.

  • phase == :derivatives

    • Returns:

  • dx::Union{Vector{Float64}, Float64, Nothing}-- the derivatives of continuous states at the specified t, x, u. - If the model does not contain continuous states, nothing is returned.

  • The elements of the dx vector are ordered according to the full names of the blocks containing the states.

Restrictions

The function supports:

  • Continuous models;

  • Discrete models;

  • Models without blocks containing states;

  • Models with virtual subsystems (Subsystem);

  • Models with atomic subsystems (Atomic Subsystem);

  • Models that include reference models.

The function does not support models containing:

  • Conditionally executable subsystems (enabled, triggered);

  • Subsystems with an Action Port block;

  • Engee Function blocks;

  • C Function blocks;

  • Chart blocks;

  • Bus Creator, Bus Selector and Bus Assignment blocks;

  • Physical modelling blocks.

Errors

Errors may be generated if the call conditions are not met:

  • The model does not exist or is not open: The model "model_name" doesn’t exist;

  • The model contains unsaved changes: The model "model_name" has unsaved changes;

  • The model contains unsupported blocks: The model "model_name" contains unsupported blocks.

Examples

# Defining model parameters
sys, blks, x0 = engee.model("model_name", :sizes)

# Computing the model outputs
t = 0.0
x = [0.0; 0.0; 0.0]
u = 2.0

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

# Calculating state derivatives
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

Returns an open System. If the model or system does not exist, an EngeeException is thrown.

Features

  • If the parameter specifies the name model_name of a previously opened model, it becomes the current model. Its root system becomes the current system.

  • If the parameter specifies the path to an existing system system_path, the model containing it becomes the current model, and the system itself becomes the current system, which is displayed in the visual editor. Returns System. Alternatively, instead of a path, you can pass an instance of Model or System directly.

Arguments

  • path::String: the path to the model or system.

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not be the currently selected model. The default is the current model.

  • system::System: an object of type System.

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.pause()

Pauses a running simulation.

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

Renames the model. Changes the model’s name from old_name to new_name.

Arguments

  • old_name::AbstractString: the current model name.

  • new_name::AbstractString: the new model name.

Examples

# Renaming a model by name
engee.rename_model("OldModel", "NewModel")

# Checking that the model has been renamed
engee.gcm()  # Now shows NewModel
engee.reset()

Restarts the simulation kernel.

Examples

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

Resumes a paused simulation.

Arguments

verbose::Bool = false: enables the output of messages regarding the progress of the simulation.

engee.rmpath(path::String)

Removes a path from the LOAD_PATH system variable.LOAD_PATH is a system variable that Engee uses to locate the required executable objects (e.g..engee, .ngscript), as well as any other paths used in commands.

Arguments

path::Vararg{String}: a path in the file system that needs to be removed from LOAD_PATH.

Examples

engee.addpath("/user/models")

# Loading a model
engee.load("model.engee")
engee.rmpath("/user/models")

# Loading the model will result in an error
engee.load("model.engee")
engee.run(; verbose::Bool=false)
engee.run(model; verbose::Bool=false) where {model <: Union{Model, System, AbstractString}}

Runs the model. If no model is specified, it runs a simulation of the current model. If no model is open, it throws a NoModelOpenedException.

Arguments

  • verbose: flag to print execution progress (default is false — no output).

  • m::Model: the model on which the operation is performed. By default, this is the current model.

Examples

# Run the current model
engee.run()

# Run with progress output
engee.run(verbose=true)

# Run a specific model
m = engee.load("/user/start/examples/power_systems/power_line_apv/power_line_apv.engee")
engee.run(m)

# Asynchronous infinite simulation
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)

Saves the model named model_name to the path file_path in 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 engee.gcm function. This model may be active in the workspace, but does not necessarily need to be open in the graphical interface.

  • model_name::String: the desired name of the model in the system.

  • file_path::String: the directory where the model is to be saved.

  • force::Bool: the default value is false. If the file already exists and this parameter is set to true, the file is overwritten. If it is set to false, an FileAlreadyExists error is raised.

Examples

# Saves the model `newmodel_1` to a new file named `newmodel_1.engee`
engee.save("newmodel_1", "newmodel_1.engee")

# Saves the model newmodel_1 to the file newmodel_1 .engee (overwrites the file )
engee.save("newmodel_1", "newmodel_1.engee", force = true)
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 at the path save_path. Supported formats: PNG, SVG. In other cases, an ErrorException("unsupported picture format: <FORMAT>") is thrown. Positioning: "auto", "tiled"; otherwise, "auto" is used.

Arguments

  • to_print::Union{Model, String, System}: the name of the model from which the screenshot will be taken.

  • save_path::String: the path where the screenshot will be saved.

  • position_mode::String: screenshot positioning. The following modes are available: "auto"-- automatically determine the optimal layout of blocks (default mode); "tiled"-- arrange blocks in a grid to avoid overlap and make the structure easier to read. Any other value is treated as "auto".

Examples

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)

Sets the port for logging.

Arguments

  • system_path::AbstractString: the path to the system in which the port is located.

  • system::System: the system in which the port is located.

  • port_path::AbstractString: the relative path to the port. If no system is provided as the first argument, the open system is used by default.

Examples

engee.set_log("Sine Wave/1")

# The Sine Wave block port in the current system is set to write
engee.set_log("newmodel_1/Subsystem","Sine Wave/1")

# The Sine Wave block port 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!(model::Model | model_name::String, param::Pair...)

Updates model parameters. Returns nothing. If the parameters are incorrect, an error occurs.

Arguments

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not be open in the graphical interface. The parameters will be updated for this model.

  • model_name::String: a string path or the name of the model.

  • param::Pair...: one or more parameters in the format "name" => value. If a parameter has units of measurement, its value must be passed as a dictionary Dict("value" => ..., "unit" => ...), where "value" is a numeric value and "unit" is a string containing the unit of measurement (e.g."V", "Hz", "deg", "s" and so on).

Examples

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

This example demonstrates how to set parameters with units of measurement.

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

# Retrieve the parameters for model_1
param_1 = engee.get_param("model_1")

# Copy the parameters from model_1 to model_2
engee.set_param!("model_2", param_1)

This example demonstrates how to change just one block parameter (the amplitude) whilst keeping all other parameters unchanged. Use this approach when you need to make specific adjustments to a block’s settings without the risk of resetting other parameters.

# Retrieve the current Sine Wave parameters
sine_params = engee.get_param("newmodel_1/Sine Wave")

# Create a copy of all parameters and change only one
modified_params = copy(sine_params)
modified_params["Amplitude"] = "2.5"  # change only the amplitude

# Apply all parameters (the rest remain as they were )
engee.set_param!("newmodel_1/Sine Wave", pairs(modified_params)...)

The simulation settings structure is tied to a specific model — you can change the model’s settings directly by setting the structure’s fields, in which case:

params = engee.get_param("newmodel_1")

# The `params` structure is linked to a specific model , similar to `engee.set_param!("newmodel_1", "FixedStep" => "0.05")`
params["FixedStep"] = "0.05"
0.05

Changing values in the params dictionary does not automatically update the model’s parameters — this is a local copy. For the changes to take effect, you need to pass 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 param parameter:

Simulation parameters

  • StartTime::String: simulation start time (Float64).

  • StopTime::String: simulation end time (Float64). To specify an infinite simulation duration, pass the string "Inf" or "inf" (engee.set_param!("model_name", "StopTime" => "Inf")).

  • SolverType::String: solver type (fixed-step or variable-step).

  • SolverName::String: solver name (depends on the selected type).

Parameters for fixed-step

FixedStep::String: simulation step size (Float64).

Parameters for variable-step

  • AbsTol::String: absolute tolerance (Float64 or 'auto').

  • RelTol::String: relative accuracy (Float64 or 'auto').

  • InitialStep::String: initial step (Float64 or 'auto').

  • MaxStep::String: maximum step size (Float64 or 'auto').

  • MinStep::String: minimum step size (Float64 or 'auto').

  • OutputTimes::String: output interval (Float64 or 'auto').

  • DenseOutput::Bool: dense output of results.

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

set_view!(
    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,
    colours::Union{BlockColours, Missing} = missing,
    annotation::Union{Maybe{String}, Missing} = missing,
    is_name_visible::Union{Maybe{Bool}, Missing} = missing,
)::String

Sets or changes the visual properties of a block.

Arguments

  • block_path::AbstractString: a string path to the block.

  • view::BlockView: an object representing the block’s visual properties.

  • lib_block_path::String: the path to the block in the library (starts with /).

  • 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/"), the block name will be generated automatically. If the full path including the block name is specified (for example, "newmodel_1/Sum1"), the block will be given the specified name.

  • top::Union{Int, Missing}: the top coordinate of the block.

  • left::Union{Int, Missing}: the left coordinate of the block.

  • width::Union{Int, Missing}: the block’s width.

  • height::Union{Int, Missing}: the block’s height.

  • rotation::Union{Int, Missing}: the block’s rotation angle.

  • is_flipped::Union{Bool, Missing}: the block’s mirroring flag.

  • colours::Union{BlockColours, Missing}: the block’s colour properties.

  • annotation::Union{Maybe{String}, Missing}: the block’s annotation.

  • is_name_visible::Union{Maybe{Bool}, Missing}: flag indicating whether the block’s name is displayed.

Examples

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()

Stops a running simulation.

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 logging.

Arguments

  • system_path::String: the system in which the port is located.

  • system::System: the system in which the port is located.

  • port_path::String: the relative path to the port. If no system is provided as the first argument, the default open system is used.

Examples

engee.set_log("Sine Wave/1")

# The Sine Wave block ’s port 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 obtained the results
engee.unset_log("Sine Wave/1")

# The Sine Wave block port in the current system has been unrecorded
engee.run()
Dict{String, DataFrames.DataFrame}()
engee.update_params()
engee.update_params(model::Model)
engee.update_params(model_name::String)

Updates the parameters of a running simulation by recalculating their current values from the workspace.

This function allows you to dynamically apply changes to parameters in the workspace to a simulation that is already running, without having to stop and restart it. If there is no running simulation, the function does nothing.

It may accept, as an optional argument, the name of the model or a model object to which the parameter update should be applied. This functionality is equivalent to clicking the ‘Compile Model’ button whilst the simulation is running.

Arguments

  • model::Model: a model object that can be loaded into memory using the engee.gcm function. This model may be active in the workspace, but need not be open in the graphical interface.

  • model_name::String: the name of the model whose parameters are 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 the parameters of a model by name
engee.update_params("newmodel_1")
engee.version()

Returns the short version of Engee.

Examples

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

Sends a warning message to the model diagnostics window. The function is only called within block callbacks (including masked ones). In messages, you can refer to parameter names in the workspace (in the variables window) using $parameter_name.

Arguments

warning_message::String: the warning message to be displayed.

Examples

# Example without referencing workspace parameters
engee.warning("Parameters have been rounded; results may be inaccurate!")

# Message in the diagnostics window :
# Parameters have been rounded ; results may be inaccurate !

# Example referencing workspace parameters
engee.warning("Parameters have been rounded to $Nd and $Ns; results may be inaccurate!")

# Message in the diagnostics window :
# Parameters have been rounded to 1.7 and 1.3; results may be inaccurate !












Finite state machine methods


















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








Adds a variable or event to the Chart block (state machine).






Arguments






    

  • 

    chart_path::String: the path to the Chart block.
    

    • 

  • 

    

    








    

    scope::Symbol: type of event/data. Can take values of: :input
    		

    :output
    		

    :local
    		

    :event.
    		

    
    

    

    • 

  • 

    name::String: the name of the variable.
    

    • 

  • 

    value::Any: the value of the variable. Missing by default.
    

    • 

  • 

    idx::Int: serial number of the port. Relevant for type variables :input and :output.
    

    • 


















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








Creating a node and a memory node inside the Chart block (state machine). The degree of nesting is determined by the parameter path. Returns Tuple containing UUID node, node type, and the path to it.






Arguments






    

  • 

    path::String: the path to the state or the path to the Chart block to which the new node is being added.
    

    • 

  • 

    

    






    

    type::String: node type: "history" (for the memory node)
    		

    nothing.
    		

    
    

    

    • 







Examples








# Создание обычного узла в 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}








Creates a state inside the Chart block (state machine). The degree of nesting is determined by the parameter path. Returns Tuple containing UUID states, the name of the state, and the path to it.






Arguments






    

  • 

    path::String: the path to the parent state or to the Chart block to which the new state is added.
    

    • 

  • 

    name::String: the name of the new state.
    

    • 

  • 

    content::String: the entire status code, the code may contain the following sections:
    

    

      

    • 

      entry: code for the section entry, executed at the moment of transition to the state;
      

      • 

    • 

      during: code for the section during, executed at the moment of state activity;
      

      • 

    • 

      exit: code for the section exit, executed at the moment of exiting the state.
      

      • 

    

    

    • 







Examples








# Создание простого состояния в 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}








Creates a transition inside the Chart block (state machine). Returns Tuple containing UUID the transition and the path to the system in which it is contained.






Arguments






    

  • 

    chart_path::String: the path to the Chart block.
    

    • 

  • 

    source::Maybe{String}: the path to the state of the source object.
    

    • 

  • 

    destination_id::UUID: The UUID of the target state/node.
    

    • 

  • 

    trigger::Maybe{String}: a trigger for code execution.
    

    • 

  • 

    action::Maybe{String}: the code executed when the condition is met in condition.
    

    • 

  • 

    condition::Maybe{String}: a condition for code execution.
    

    • 

  • 

    content::Maybe{String}: the entire transition code (including the condition - condition, trigger, action).
    

    • 

  • 

    origin::Maybe{String}: default position of the transition starting point (whether the starting point belongs to any state or global state).
    

    • 




















    

  1. 

    Command line
    

    2. 

  2. 

    Software control of modelling
    

    3. 

  3. 

    Script Editor
    

    4.