Программное управление моделированием

Создавайте модели, добавляйте блоки, соединяйте их сигнальными линиями, устанавливайте параметры и свойства, а также выполняйте другие базовые операции при помощи специализированных команд, встроенных в программную среду Engee.

В этой статье мы опишем программное управление моделированием в Engee.

Для написания команд используется язык Julia, который прост для использования и позволяет сосредоточиться на решении вашей инженерной задачи, не тратя времени на овладение языком.

Основные направления в программном управлении моделированием Engee:

  • Создание, сохранение, удаление модели, открытие из файла, добавление/удаление блоков, линий и подсистем.

  • Управления симуляцией модели (установка параметров решателя, запуск, прерывание, остановка симуляции, получение результатов).

  • Управление параметрами блоков и подсистем.

  • Подготовка автоматизированных сценариев (например, автоматизация тестирования, подбор параметров, генерация тестов, генерация кода и т.д.).

Работа с моделями

Публичные методы

Вызвать все доступные в Engee публичные методы можно с помощью команды engee. и нажатия клавиши Tab в командной строке:

example prog modeling 2

Редактор скриптов выполнит команду engee., но не выведет доступные методы.

Если у вас возникли вопросы по конкретному методу, вы можете сменить режим командной строки с engee на help? и вывести справку по интересующему методу.

Получение справки в командной строке

Для получения справки введите знак вопроса ? в командную строку и с помощью команды engee.method_name (где method_name — интересующий публичный метод) обратитесь к справке.

example prog modeling 4

Все публичные методы в Engee представлены в таблице:

Таблица публичных методов
Метод Аргументы Краткое описание

add_block

lib_block_path::String — полный путь до блока в библиотеке.

tgt_block_path::String — путь до системы и ожидаемое имя.

Формат: path/to/system/new block name (если имя не указано, то задается автоматически).

Добавляет блок из библиотеки.

add_line

system::String|System — путь до системы или обьект типа ET.System.

src_port::String — полный путь до out порта блока.

tgt_port::String — полный путь до in порта блока.

В качестве названия порта используется его порядковый номер. Формат: system_name/block_name/idx

Добавляет связь (поток данных) между блоками.

close

src_block_path::String — полный путь до блока в системе.

Закрывает модель.

close_all

-

Закрывает все модели.

copy_block

src_block_path::String — полный путь до блока в системе

tgt_block_path::String — путь до системы и ожидаемое имя. Формат: path/to/system/newblockname (если имя не указано, то задается автоматически).

Копирует блок из системы.

create

engee.create(model_name::String)::Model

Создает новую модель с параметрами по-умолчанию

delete_block

block_path::String — путь до блока.

Удаляет блок, все связанные линии и логируемые порты из системы.

delete_line

system::String|System — путь до системы или объект типа ET.System.

src_port::String — полный путь до out порта блока.

tgt_port::String — полный путь до in порта блока.

В качестве названия порта используется его порядковый номер. Формат: system_name/block_name/idx

Удаляет связь (поток данных) между блоками.

eval

-

Вычисляет выражение, представленное в виде строки (текста).

gcm

engee.get_current_model()::Model

engee.gcm()::Model

Возвращает текущую (активную) модель.

gcs

engee.get_current_system()::System

engee.gcs()::System

Возвращает текущую систему.

generate_code

Создает код на языке C для файла модели с расширением .engee, расположенного по пути engee_file_path, в директории ccode_dir_path. Пути считаются относительно папки пользователя.

Создает код на языке C для файла модели с расширением .engee.

get_all_models

-

Возвращает список открытых в текущей сессии моделей.

get_current_model

engee.get_current_model()::Model

engee.gcm()::Model

Возвращает текущую модель.

get_current_system

engee.get_current_system()::System

engee.gcs()::System

Возвращает текущую систему.

get_logs

m::Model — модель, относительно которой выполняется операция, по-умолчанию, текущая модель.

Получает сообщения из журнала, связанные с моделью.

get_param

engee.get_param(model::Model)::ModelParameters

engee.get_param(path::String,param::Union{Symbol,String})::Any

Возвращает все параметры.

get_results

m::Model — модель, относительно которой выполняется операция, по-умолчанию, текущая модель.

Возвращает результаты последней симуляции модели в виде словаря Dict{String, DataFrame}, где ключ — имя отслеживаемого порта.

get_status

engee.get_status()::SimulationStatus

Возвращает статус симуляции как SimulationStatus.

include

-

Включает содержимое файла из другого сеанса в текущий.

is_dirty

engee.is_dirty(model::Model)::Bool

Проверяет, есть ли несохраненные изменения модели.

load

engee.load(file_path::String;

name::Maybe{\String\}=nothing, force::Bool = false)::Model

Загружает модель из файла с расширением .engee.

open

engee.open(path::String)::System

engee.open(model::Model)::System

engee.open(system::System)::System

Возвращает открытую систему System.

pause

pause()

Приостанавливает запущенную симуляцию.

resume

verbose::Bool = false: — включает вывод сообщений о ходе выполнения симуляции

Возобновляет приостановленную симуляцию.

run

verbose — выводить ли прогресс на печать (по-умолчанию verbose=false).

m::Model — модель, относительно которой выполняется операция (по-умолчанию текущая модель).

Запускает исполнение модели.

save

engee.save(model_name::String, file_path::String; force::Bool = false)

engee.save(model::Model, file_path::String; force::Bool = false)

Сохраняет модель с именем model_name по пути file_path в файл с расширением .engee.

script

-

Функция.

set_param!

block_path::String — путь до блока.

block::ET.Block — структа ET.Block, которая хранит в себе данные, идентифицирующие блок.

block_params::ET.BlockParameters — структура всех настроек блока.

params::Pari{\String\}…​)::Nothing — параметры блока в виде "name" ⇒ value

Обновляет выбранные параметры блока.

stop

stop()

Останавливает запущенную симуляцию.

version

version()

Возвращает короткую версию Engee.

Создание новой модели

Для создания модели в Engee используйте следующий код:

model = "model_name"
engee.create(model)

В коде инициализируется переменная model со значением "model_name", после обращения к которой через engee.create возвращается объект Model и создается модель. Создать модель можно и другим способом:

engee.create("model_name")

Здесь название для модели сразу передается строкой (тип данных String) и не требует предварительной инициализации переменной.

Таким образом, на основе вышеупомянутого кода:

  • Создается модель с именем model_name и параметрами по умолчанию.

  • Модель становится текущей моделью. Ее корневая система становится текущей системой.

    Имя модели (model_name) не должно содержать символ /.
Ошибки
  • Если модель с таким именем уже существует, выводит исключение ModelAlreadyExistsException.

Вывод

example prog modeling 1

Загрузка модели из файла

engee.load(file_path::String; force = false)::Model
  • Загружает модель из файла с расширением .engee, расположенного в пути file_path.

  • Возвращает объект Model.

  • Модель становится текущей моделью. Ее корневая система становится текущей системой.

Ошибки
  • Если модель с таким именем уже существует и параметр force = true, то перезагружает ее и все не сохраненные ранее изменения будут утеряны, если же force = false, то выводит исключение ModelAlreadyExistsException. По умолчанию force = false.

  • Если у файла некорректное расширение, выводит исключение InvalidFileExtension.

  • Если такого файла не существует, выводит исключение FileNotFound.

Вывод
engee> engee.load("NewModel.engee"; force = true)
Model(NewModel)

Открытие ранее используемой модели

engee.open(model_name::String)::System
engee.open(path::String)::System
engee.open(model::Model)::System
engee.open(system::System)::System
  • Если в параметре указано название model_name открытой ранее модели, она становится текущей моделью. Ее корневая система становится текущей системой. Возвращает объект Model.

  • Возвращает открытую систему System.

  • Если в параметре указан путь до существующей системы system_path, содержащая ее модель становится текущей моделью, а сама система — текущей системой, которая отображается в визуальном редакторе. Возвращает объект System.

  • Также вместо пути можно передать непосредственно экземпляр Model или System.

Ошибки
  • Если модели не существует, выводит исключение ModelDoesntExistException.

  • Если системы не существует, выводит исключение SystemIsNotExistException.

Вывод
engee> # open model:
engee> m1 = engee.open("NewModel")
Model(NewModel)
engee> engee.gcm(), engee.gcs()
(Model(NewModel), System(root))
engee> # open system:
engee> engee.open("AnotherModel/Subsystem-1")
System(Subsystem-1)
engee> engee.gcm(), engee.gcs()
(Model(AnotherModel), System(Subsystem-1))

Открытие текущей модели

engee.get_current_model()::Model
engee.gcm()::Model
  • Возвращает текущую активную модель.

Ошибки
  • Если текущей модели нет, выводит исключение NoModelOpened.

Открытие текущей системы

engee.get_current_system()::System
engee.gcs()::System
  • Возвращает текущую активную систему.

Ошибки
  • Если текущей системы нет, выводит исключение NoModelOpenedException.

Просмотр списка открытых моделей

engee.get_all_models(; sorted=true)::Vector{Model}
  • Возвращает список открытых в текущей сессии моделей, как Vector{Model}.

  • Если параметр sorted=true, то сортирует модели по имени, при sorted=false модели выводятся в порядке открытия. По умолчанию sorted=true.

Завершение работы с моделью

Проверка на несохраненные изменения

engee.is_dirty(model::Model)::Bool
  • Проверяет, есть ли несохраненные изменения модели. Возвращает true при наличии несохраненных изменений, иначе — false.

  • Если модель уже закрыта, возвращает false.

Сохранение модели в файл

engee.save(model_name::String, file_path::String; force::Bool = false)
engee.save(model::Model, file_path::String; force::Bool = false)
  • Сохраняет модель с именем model_name по пути file_path в файл с расширением .engee.

  • Если необходимо, создаются промежуточные директории.

  • Возвращает nothing.

Ошибки
  • Если файл уже существует и параметр force = true, перезаписывает его, если же force = false, то завершается ошибкой FileAlreadyExists. По умолчанию, force = false.

Закрытие модели

engee.close(model_name::String; force::Bool = false)::Model
engee.close(model::Model; force::Bool = false)::Model
engee.close(; force::Bool = false)::Model
  • Закрывает модель с именем model_name в визуальном редакторе (удаляет ее из сессии).

  • Текущей становится модель, открытая во вкладке визуального редактора левее.

  • Возвращает Model.

  • Если модель не указана, закрывает текущую модель. Если текущая модель не задана, ничего не делает.

  • Если модели уже не существует, ничего не делает.

Ошибки
  • Если есть несохраненные изменения и параметр force=false, завершается ошибкой UnsavedModelException, если же force=true, то несохраненные изменения будут потеряны.

Управление параметрами моделирования

Получение настроек симуляции

engee.get_param(model::Model)::ModelParameters
engee.get_param(path::String, param::Union{Symbol, String})::Any
  • Если указано имя модели, но не указано имя параметра, возвращает настройки симуляции для выбранной модели в виде структуры ModelParameters.

  • Если же имя параметра указано, возвращает значение параметра.

Изменение настроек симуляции модели

engee.set_param!(model_name::String, param::Pair...)
engee.set_param!(model_name::String, param::ModelParameters)
engee.set_param!(model::Model, param::Pair...)
engee.set_param!(model::Model, param::ModelParameters)
  • Обновляет выбранные параметры модели Model с именем model_name.

  • Возвращает nothing.

  • Если в param передана структура настроек симуляции, настройки из нее будут скопированы.

  • Если параметры некорректны, завершается соответствующей ошибкой.

  • Структура настроек симуляции привязывается к конкретной модели - можно изменять настройки модели непосредственно через задание полей структуры.

Вывод
engee> engee.set_param!("model_1", "solver"=>"ode45", "stop_time"=>10)
engee> param_1 = engee.get_param("model_1")::ModelParameters
engee> engee.set_param!("model_2", param_1)

Обновление параметров блоков

engee.set_param!(block_path::String,params::Pair{String}...)
engee.set_param!(block::ET.Block, params::Pair{String}...)
engee.set_param!(block::ET.Block, block_params::ET.BlockParameters)
engee.set_param!(block_path::String, block_params::ET.BlockParameters)
  • Обновляет выбранные параметры блока.

  • Если изменяется параметр, который влечет за собой изменения количества портов, или состояния, то количество портов и состояние изменяются согласно переданным значениям параметра.

  • Возвращает nothing.

  • Если в качестве второго параметра передана структура настроек блока, параметры из нее будут скопированы. Если параметры некорректны, завершается соответствующей ошибкой.

Изменение настроек симуляции модели с помощью структуры

  • Структура настроек симуляции привязывается к конкретной модели — можно изменять настройки модели непосредственно через задание полей структуры.

Вывод
engee> params = engee.get_param(model::Model)::ModelParameters
engee> # структура params привязана к конкретной model
engee> params.step_time = 0.01
0.01
engee> # аналогично `engee.set_param!(model::Model, "step_time" => 0.01)

Редактирование моделей

Добавление блока

engee.add_block(lib_block_path::String, tgt_block_path::String)
  • Добавляет копию блока из lib_block_path в tgt_block_path.

  • lib_block_path — полный путь до блока в модели или библиотеке.

  • tgt_block_path — путь до системы и ожидаемое имя. Если имя не указано, то задается автоматически.

  • Если путь до существующего блока модели совпадает с путем до блока из библиотеки из-за совпадения имен модели и ее систем с названиями разделов библиотеки, выбирается блок из модели.

  • Если в tgt_block_path последним содержится название будущего блока, пробует добавить блок под этим названием.

  • Если tgt_path не содержит название будущего блока, название формируется по образцу <block_type>-<index>, например Sin-1, где индекс является количеством блоков данного типа после добавления.

  • Добавляет в подсистему дополнительный порт при добавлении блок-порта, например, Inport.

Ошибки
  • Если название занято, завершается ошибкой IncorrectBlockNameException.

  • Если путь до блока библиотеки некорректный, то завершается ошибкой InvalidBlockPathException.

  • Если система, в которую добавляется блок не существует, то завершается ошибкой SystemIsNotExistException.

Удаление блока

engee.delete_block(block_path::String)
  • Удаляет блок по указанному пути.

  • block_path — абсолютный путь до блока в модели.

  • Также удаляет все связанные с блоком линии и логируемые порты.

Копирование блока

engee> engee.copy_block("newmodel_1/Add-3", "newmodel_2/")
engee> # добавить блок из модели `newmodel_1` с именем "Test_name" в модель `nemodel_2`
engee> engee.copy_block("newmodel_1/Custom Block Name", "newmodel_2/Test_name")
  • Добавляет блок из модели newmodel_1 и присваивает ему имя в модели newmodel_2.

  • src_block_path::String — полный путь до блока в системе

  • tgt_block_path::String — путь до системы и ожидаемое имя. Формат: path/to/system/newblockname (если имя не указано то задается автоматически).

Ошибки
  • IncorrectBlockNameException — некорректное имя для нового блока.

  • InvalidBlockPathException — копируемого блока не существует по указанному пути.

  • SystemIsNotExistException — система, в которую добавляем блок, не существует.

Добавление/удаление сигнала

# добавляет линии между портами
engee.add_line(src_port, dst_port) = engee.add_line(engee.gcs(), src_port_path, dst_port_path)
engee.add_line(system::String|System, src_port :: String, dst_port :: String)

# удаляет линии между портами
engee.delete_line(src_port, dst_port) = delete_line(gcs(), src_port, dst_port)
engee.delete_line(system, src_port :: String, dst_port :: String)
  • Добавляет/удаляет линию между портами src_port_path и dst_port_path, где src_port::String: — полный путь до выходгого порта блока, tgt_port::String: — полный путь до входного порта блока.

  • Если путь указывает на блок-порт подсистемы, то соединяет/отсоединяет саму подсистему по соответствующему порту.

  • В остальных случаях блоки соответствующих портов должны находиться в одной системе.

  • В качестве названия порта используется его порядковый номер.

Ошибки
  • SourceEdgeIsNotOutputPort — если порт по пути src_port_path не out порт

  • TargetEgdeIsNotInputPort — если порт по пути tgt_port_path не входной порт.

  • TargetEdgeAlreadyConnected — если tgt порт уже соединён.

  • NotAcausalPort — при ненаправленном соединении, если один из портов имеет тип не acausal.

  • LineCannotBeAdded — если некорректный тип порта или направление линии.

Запись/чтение параметров блока и сигнала

engee.set_param!(blockPath::String, paramName::String => paramValue::Any)
engee.get_param(blockPath::String, paramName::String)::Any
engee.get_param(blockPath::String) :: BlockParameters
engee.set_param!(blockPath::String, blockParams::BlockParameters)
  • Аналогично get_param и set_param! для параметров модели.

Примеры

engee.add_block("Basic/Mathematics/Add", "model_name/Add1") #вставляет блок Add из библиотеки Basic/Mathematics и присваивает ему заданное имя Add1 (если имя с этим блоком есть, выдает ошибку)
engee.add_block("Basic/Continuous/Integrator", "model_name/") #вставляет блок Integrator из библиотеки base/continuous и присваивает имя автоматически (например Integrator2 если блок с именем Integrator1 уже есть)
engee.add_line("model_name", "Add1/1", "Integrator/1")  #устанавливает сигнал между выходным портом №1 у блока Add1 и входным портом №1 блока Integrator2
engee.add_line("model_name", "Add1/1", "SubSystem/1") #устанавливает сигнал между выходным портом №1 у блока Add1 и входным портом подсистемы `Subsystem`, с которым связан блок `Inport_1`.
params = engee.get_param("model_name/Integrator-1") #возвращает все параметры блока Integrator-1 в структуру params
engee.set_param!("model_name/Integrator-1", params)#присваиваются параметры блоку Integrator-1 из структуры params

Управление симуляцией модели

Запуск симуляции

engee.run(model_name::String; verbose=false)
engee.run(model::Model; verbose=false)
engee.run(; verbose=false)
  • Запускает симуляцию модели. Возвращает результаты симуляции.

  • Если модель не указана, запускает симуляцию текущей модели.

  • Если симуляция была остановлена, возвращает NoModelOpenedException.

  • При verbose=true, выводится прогресс симуляции. По умолчанию verbose=false.

Приостановка запущенной симуляции

engee.pause(model_name::String)
engee.pause(model::Model)
engee.pause()
  • Приостанавливает запущенную симуляцию модели. Возвращает nothing.

Возобновление приостановленной симуляции

engee.resume(model_name::String)
engee.resume(model::Model)
engee.resume()
  • Возобновляет приостановленную симуляцию модели. Возвращает результаты симуляции.

Прерывание симуляции

engee.stop(model_name::String)
engee.stop(model::Model)
engee.stop()
  • Останавливает запущенную симуляцию модели. Возвращает nothing.

Просмотр результатов симуляции

engee.get_results(model_name::String)
engee.get_results(model::Model)
engee.get_results()
  • Возвращает результаты симуляции указанной модели в виде словаря Dict{String, DataFrame}, где ключ – имя отслеживаемого порта.

  • Если модель не указана, возвращает результаты последней симуляции.

Ошибки
  • Если модель не открыта, то бросается исключение NoModelOpenedException.

  • Если симуляция не запущена, то бросается исключение ModelIsNotRunningException.

Просмотр статуса симуляции модели

engee.get_status(model_name::String)::SimulationStatus
engee.get_status(model::Model)::SimulationStatus
engee.get_status()::SimulationStatus
  • Возвращает статус симуляции как SimulationStatus.

Просмотр событий симуляции

engee.get_logs(model_name::String)
engee.get_logs(model::Model)
engee.get_logs()
  • Получает сообщения из журнала, связанные с моделью.

  • Возвращает массив с сообщениями из журнала, связанные с указанной моделью.

Ошибки
  • Если модель не открыта, то бросается исключение NoModelOpenedException.

Генерация кода

generate_code(
      engee_file_path::String,
      ccode_dir_path::String,
      subsystem_name::Union{Nothing, String} = nothing)
  • Создает код на языке C для файла модели с расширением .engee, расположенного по пути engee_file_path, в директории ccode_dir_path.

  • Пути считаются относительно папки пользователя. По-умолчанию, если имя подсистемы subsystem_name не указано, то создает код для корневой подсистемы.

Вывод
engee> engee.generate_code("models/example_model.engee", "dir_for_c_code_of_example_model")
"Created directory - dir_for_c_code_of_example_model"

Вывод версии продукта

engee.version()