Engee для профессионалов

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

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

Программное управление скриптами

Рассмотрим методы программного управления скриптами engee.script:

• engee.script.edit
• engee.script.run
• engee.script.@include

Метод engee.script.edit

engee.script.edit(path::String)

Открывает в редакторе интерактивный скрипт, расположенный по пути path (включая имя и расширение). Если такого файла нет, то по указанному пути создается и открывается в редакторе пустой файл скрипта. Если указанное в path расширение отличается от .ngscript, то функция вернет ошибку.

Например, следующая строка кода открывает скрипт file.ngscript в Редакторе скриптов Engee. Если в текущей папке такого файла не существует, то файл будет создан и открыт для редактирования:

✏️Задание 1

С помощью метода engee.script.edit откройте скрипт Построение графика.ngscript, расположенный в папке данного курса. Этот скрипт строит график функции на отрезке от 0 до 1 с шагом 0.01.

Решение

Метод engee.script.run

engee.script.run(path::String; isolate::Bool = false)

Запускает скрипт по указанному пути. Возвращает результат последнего верхнеуровневого выражения в скрипте.

Аргументы:

• path — абсолютный путь до скрипта.
• Если isolate = true, то скрипт выполняется во временном изолированном окружении. Все переменные, созданные во время исполнения, не сохраняются после завершения скрипта. Если isolate = false, то скрипт выполняется в основном пользовательском окружении. Все переменные, объявленные глобально или на верхнем уровне, сохраняются после выполнения. Этот аргумент необязателен. Если его не указать, то по умолчанию принимается isolate = false.

✏️Задание 2

С помощью метода engee.script.run запустите выполнение скрипта Построение графика.ngscript, расположенного в папке данного курса. В результате будет построен график функции на отрезке от 0 до 1 с шагом 0.01.

Решение

Метод engee.script.@include

engee.script.@include(path::String)

Вставляет содержимое указанного скрипта на место вызова макроса. В отличие от engee.script.run, который исполняет скрипт отдельно, макрос @include лексически подставляет код скрипта на место вызова.

Аргументы:

path — абсолютный путь до скрипта.

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

В Engee реализованы следующие направления в программном управлении моделированием:

• Создание, сохранение, удаление модели, открытие модели из файла.
• Добавление/удаление блоков, линий и подсистем, управление параметрами блоков и подсистем.
• Управление параметрами моделирования (получение настроек симуляции, их изменение, обновление параметров блоков и изменение настроек симуляции модели с помощью структуры).
• Управления симуляцией модели (установка параметров решателя, запуск, прерывание, остановка симуляции, получение результатов).
• Генерация кода.

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

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

Используется метод create:

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

Создать модель можно и другим способом:

На основе приведенного выше кода:

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

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

Для загрузки модели из файла используется метод load:

engee.load(file_path; force = false)

Эта команда:

• Загружает модель из файла с расширением .engee, расположенного в пути file_path.
• Возвращает объект типа Model.
• Модель становится текущей моделью. Ее корневая система становится текущей системой.

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

Используется метод open:

engee.open(model_name)
engee.open(path)
engee.open(model)
engee.open(system)

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

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

Используется метод gcm:

engee.get_current_model()
engee.gcm()

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

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

Используется метод get_all_models.

engee.get_all_models(; sorted=true)

• Возвращает список открытых в текущей сессии моделей как Vector{Model}.
• Если параметр sorted=true, то сортирует модели по имени, при sorted=false модели выводятся в порядке открытия. По умолчанию sorted=true.

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

Используется метод save:

engee.save(model_name, file_path; force = false)
engee.save(model, file_path; force = false)

• Сохраняет модель с именем model_name по пути file_path в файл с расширением .engee. Расширение .engee нужно обязательно указывать!
• Если необходимо, создаются промежуточные директории.
• Возвращает nothing.
• Если файл уже существует и параметр force = true, то файл перезаписывается. Если же force = false (по умолчанию), то появится сообщение об ошибке FileAlreadyExists.

Пример:

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

Используется метод close:

engee.close(model_name; force = false)
engee.close(model; force = false)
engee.close(; force = false)

• Закрывает модель с именем model_name в визуальном редакторе (удаляет ее из сессии).
• Текущей становится модель, открытая во вкладке визуального редактора левее.
• Возвращает Model.
• Если модель не указана, закрывает текущую модель. Если текущая модель не задана, ничего не делает.

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

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

Для запуска симуляции модели используется метод run (перед запуском симуляции модель нужно загрузить с помощью метода load).

engee.run(model_name; verbose=false)
engee.run(model; verbose=false)
engee.run(; verbose=false)

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

Пример. Загрузим модель Синусоида.engee, находящуюся в папке данного курса, и запустим ее симуляцию:

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

Используется метод pause:

engee.pause(model_name)
engee.pause(model)
engee.pause()

Если симуляция не запущена, то появится сообщение об ошибке Engee.Exceptions.SimulationError("Only running simulation may be paused").

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

Используется метод resume:

engee.resume(model_name)
engee.resume(model)
engee.resume()

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

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

Используется публичный метод stop:

engee.stop(model_name)
engee.stop(model)
engee.stop()

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

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

Используется публичный метод get_results:

engee.get_results(model_name)
engee.get_results(model)
engee.get_results()

• Возвращает результаты симуляции указанной модели в виде словаря Dict, где ключ — имя отслеживаемого порта.
• Если модель не указана, возвращает результаты последней симуляции.
• Метод напрямую связан с переменной simout, хранящей результаты симуляции модели.

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

Перед редактированием модели откройте ее с помощью метода open. После редактирования не забудьте сохранить результаты с помощью save.

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

Для добавления блока используется метод add_block:

engee.add_block(lib_block_path, tgt_block_path)

• Добавляет копию блока из lib_block_path в tgt_block_path.
• lib_block_path — полный путь до блока в модели или библиотеке. Путь lib_block_path можно увидеть при двойном нажатии по свободной области рабочего пространства и набрав имя нужного блока, а также в окне настроек блока во вкладке Информация.
• tgt_block_path — путь до системы и ожидаемое имя. Если имя не указано, то задается автоматически.
• Если в tgt_block_path последним содержится название будущего блока, пробует добавить блок под этим названием.
• Если tgt_path не содержит название будущего блока, то название формируется по образцу <block_type>-<index>, например Sin-1, где индекс является количеством блоков данного типа после добавления, а Sin — это block_type блока.

Пример. Добавим в текущую модель new_model два блока: Линейный сигнал и Квадратный корень:

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

Используется метод delete_block:

engee.delete_block(block_path)

• Удаляет блок по указанному пути.
• block_path — абсолютный путь до блока в модели по типу "new_model/Sine Wave", где new_model — имя модели, а Sine Wave — имя блока.
• Также удаляет все связанные с блоком линии и порты.

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

Используется метод copy_block:

engee.copy_block(src_block_path::String, tgt_block_path::String)

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

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

Используются методы add_line и delete_line:

# добавляет линии между портами
engee.add_line(src_port, dst_port)
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 — полный путь до выходного порта блока, tgt_port — полный путь до входного порта блока.
• Если путь указывает на блок-порт подсистемы, то соединяет/отсоединяет саму подсистему по соответствующему порту.
• В остальных случаях блоки соответствующих портов должны находиться в одной системе.
• В качестве названия порта используется его порядковый номер.

Пример. В текущей модели new_model соединим линией блоки Линейный сигнал и Квадратный корень:

Здесь /1 после имени блока — номер порта.

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

Используются методы set_param! и get_param:

engee.set_param!(blockPath, paramName => paramValue)
engee.get_param(blockPath, paramName)
engee.get_param(blockPath)
engee.set_param!(blockPath, blockParams)

Аналогично методы set_param! и get_param используются для параметров модели.

✏️Задание 3

С помощью средств программного управления создайте модель и сохраните ее в текущей папке:

1. Создайте модель с именем model с помощью метода create.
2. Сохраните модель с помощью метода save.

Решение

✏️Задание 4

Добавьте в модель блоки Линейный сигнал и Заглушка и создайте линию между ними:

1. Добавьте в модель блок Линейный сигнал с помощью метода add_block.
2. Добавьте в модель блок Заглушка с помощью метода add_block.
3. Соедините эти блоки линией с помощью метода add_line.
4. Сохраните изменения в модели с помощью метода save. Для того чтобы перезаписать файл, задайте второй аргумент в виде force = true.

Решение

✏️Задание 5

Запустите симуляцию модели и постройте график выходного сигнала:

1. Найдите в файловом браузере файл model.engee и откройте построенную модель.
2. Включите запись выходного сигнала блока Линейный сигнал.
3. Программно запустите симуляцию модели с помощью метода run.
4. Перейдите в модель и постройте график результатов симуляции.

Решение

График результатов симуляции:

Программная обработка результатов симуляции в Engee

Рассмотрим, как сохранять результаты симуляций с помощью переменной simout.

Примечание

По умолчанию переменная simout не создается после завершения симуляции модели. Для ее появления поставьте галочку Сохранять результаты симуляции в рабочую область в окне настроек модели (вкладка Отладка):

✏️Задание 6

1. Откройте модель Синусоида.engee, которая находится в папке данного курса:

2. Запустите симуляцию модели. После окончания симуляции переменная simout будет автоматически создана в рабочей области Engee:

3. Переменная simout формирует DataFrame — структуру данных, представленную в виде таблицы. Ячейки этой таблицы автоматически заполняются данными результатов симуляции. К переменной simout можно обратиться через команду collect. Команда собирает данные с переменной simout и сохраняет их в новую переменную. Для выполнения команды создайте переменную result и сохраните результаты симуляции, введя следующий код в командную строку:

result = collect(simout["Синусоида/Генератор синусоиды.1"])

Здесь:

• result — имя переменной, в которую сохраняются данные о симуляции (может быть переименована).
• Синусоида — имя текущей модели.
• Генератор синусоиды — имя блока, который выдает данные.
• 1 — номер порта, с выхода которого считываются значения для переменной simout и к которому добавлена запись сигнала.

Полученный результат будет отображен в виде таблицы в командной строке.

4. Запишите данные о проведенной симуляции в файл формата CSV. Сохраните переменную result в файл result.csv с помощью следующих команд:

using CSV
CSV.write("result.csv", result)

5. Убедитесь в корректности сохранения данных в переменной simout визуально, отобразив график результатов симуляции в командной строке или редакторе скриптов:

using Plots
plot(result.time, result.value)

Полезные ссылки

Программное управление скриптами

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

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

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

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

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

Тест для получения сертификата

Пройти тест по разделу >>