Введение и базовые понятия

Комплекс программ «Среда моделирования ORPHYS 2.0» (ORPHYS) предназначен для формирования многоуровневых компьютерных моделей технических объектов и систем управления, проведения численных экспериментов, анализа динамических процессов и визуализации результатов.

Три слоя модели

В основу архитектуры ORPHYS положен принцип многослойного описания исследуемой системы. Расчетная схема разделяется на три функциональных уровня:

Интерфейс пользователя и элементы рабочего пространства

Создание и редактирование схем

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

Порядок сборки схемы

1. 1
   Выбор слоя и размещение компонентов

   Перейдите на требуемый слой модели (вкладки «C-слой» или «L-слой» над холстом). Выберите компонент в палитре слева и перетащите его на рабочее поле. В панели свойств задайте компоненту понятную функциональную метку (параметр label).
2. 2
   Прокладка соединений (коммутация)

   Наведите курсор на контактный вывод компонента, нажмите левую кнопку мыши и протяните линию связи к выводу смежного элемента. На логическом слое соединение допускается только от выхода (out) ко входу (in).
3. 3
   Установка узлов соединения (Junction)

   При разветвлении линий на физическом слое используйте специальный компонент «Узел соединения» (Junction). Простое геометрическое пересечение линий без узла не образует контакта.
4. 4
   Задание опорного узла цепи

   В обязательном порядке подключите к физической цепи элемент, фиксирующий базисный потенциал (компонент «Земля» для электротехники или «Источник среды / Сток» для гидравлики).
5. 5
   Параметризация элементов

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

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

Беспроводная передача сигналов блоками Goto и From

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

• Блок Goto: подключается к источнику сигнала и публикует его в локальном пространстве схемы под символьным именем tag (например, PID_Output).
• Блок From: настраивается на идентичное имя тега и передает значение на вход приемного компонента. Один блок Goto может обслуживать произвольное количество блоков From.

Связь физического и логического уровней (Адаптеры и отводы)

Среда ORPHYS позволяет строить замкнутые системы автоматического управления, где регуляторы логического слоя воздействуют на аппараты физического слоя, а измерительные преобразователи считывают параметры процесса.

Порты-отводы технологических аппаратов (Taps)

Для подключения физического аппарата к системе управления на его графическом корпусе формируются порты-отводы:

• Выходной отвод (Телеметрия): Снимает вычисленную величину физического состояния аппарата (температуру среды, перепад давлений, массовый расход) для передачи в измерительные датчики или индикаторы.
• Входной отвод (Управление): Принимает внешнее командное воздействие от регулятора (степень открытия регулирующего клапана opening_cmd, задание частоты вращения вентилятора АВО fan_cmd).

Порядок добавления порта-отвода:

1. 1
   Выделение аппарата

   На объектном слое выделите курсором требуемый аппарат (например, аппарат воздушного охлаждения avo).
2. 2
   Формирование отвода

   В панели свойств найдите секцию «Порты-отводы», нажмите кнопку «+ выход» (для измерения) или «+ вход» (для команды управления).
3. 3
   Выбор физической величины

   В выпадающем списке выберите регистрируемую переменную (например, T_prod_out для температуры продукта или fan_cmd для привода). На корпусе блока появится контактный порт.

Согласующий компонент l_device

Для взаимодействия логического алгоритма с физическим оборудованием на логическом слое устанавливается блок «Адаптер объекта» (l_device). В его свойствах указываются:

• target_device: метка (label) целевого физического аппарата на объектном слое (например, AVO_1).
• variable: наименование переменной, совпадающее с именем сформированного отвода (например, T_prod_out при чтении или fan_cmd при записи).

Сквозной пример: контур стабилизации температуры АВО

Запуск расчетов и режимы моделирования

Среда ORPHYS поддерживает проведение расчетов установившегося состояния, динамических переходных процессов и интерактивное моделирование в реальном времени.

Режимы расчета

Настройка параметров времени и шага интегрирования

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

• Время окончания расчета ($t_{\text{end}}$): Длительность исследуемого физического процесса в секундах (например, $100\text{ с}$).
• Базовый шаг ($h$): Временной интервал между расчетными точками.

Автоматический реактивный пересчет

После того как схема была однократно успешно рассчитана нажатием кнопки «Старт», активируется реактивный режим: любое последующее изменение параметров компонентов в панели свойств либо перемещение проводников автоматически инициирует фоновый пересчет схемы. Графики и цифровые табло обновляются без дополнительных действий со стороны пользователя.

Визуализация и анализ результатов

Для наблюдения за ходом технологического процесса и анализа результатов моделирования на визуальном слое (V) размещаются контрольно-измерительные приборы и органы управления.

Структуры данных: ряды (series) и текущие значения (last)

Вычислительное ядро среды возвращает результаты в двух форматах:

• Временной ряд (series): Полный массив пар «время — значение» за весь период расчета. Предназначен для построения непрерывных кривых переходных процессов в компоненте «График» (Chart).
• Конечное значение (last): Точечное скалярное значение переменной на последнем вычисленном шаге. Предназначено для отображения текущих показаний в компонентах «Числовое табло» (Digital Display), сигнальных индикаторах и мнемосхемах.

Настройка виртуальных приборов

Интерактивные органы управления

Для ручного воздействия на систему в режиме реального времени (Live) используются элементы ввода:

• Ползунковый задатчик (Slider): Обеспечивает плавное изменение численного параметра в заданных границах (минимум, максимум, шаг приращения).
• Переключатель (Toggle Switch): Служит для дискретной подачи логических сигналов (0/1) и переключения технологических блокировок.

Создание собственных компонентов (Генератор моделей)

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

Пошаговый алгоритм создания компонента

1. 1
   Запуск редактора компонентов и задание метаданных

   Откройте инструмент «Редактор компонентов» из панели инструментов среды. Укажите уникальное системное имя (латиницей без пробелов, например custom_valve), понятное наименование для палитры (например, «Клапан») и выберите целевой слой (физический или логический).
2. 2
   Конфигурация портов (внешних выводов)

   Добавьте контакты компонента. Для логического блока выберите направление: in (вход) или out (выход). Для физического блока выберите домен (электрика, гидравлика) и сторону размещения на корпусе. Имена портов будут использоваться в формулах.
3. 3
   Объявление параметров

   Сформируйте список настроек, которые пользователь сможет изменять через панель свойств: символьное обозначение (например, K_loss), текстовая подпись, единицы измерения и базовое значение по умолчанию.
4. 4
   Математическое описание: логика vs физика

   Воспользуйтесь редактором формул для ввода уравнений поведения компонента. Важно учитывать принципиальное различие слоев:
   • Для логического блока: Задается формула прямого расчета выхода: $$\text{out} = K \cdot (\text{in}_1 - \text{in}_2)$$ • Для физического блока: Физический закон должен быть приведен к форме Невязки (все переносится в левую часть, чтобы справа остался ноль).
   Пример (закон Ома): Вместо $U = I \cdot R$ в редактор вводится невязка: $$(V_{\text{in}} - V_{\text{out}}) - I \cdot R = 0$$
5. 5
   Оформление условного графического обозначения (УГО)

   На вкладке глифа задайте габариты блока и нарисуйте пиктограмму. Равномерно распределите порты по сторонам прямоугольника для обеспечения удобной коммутации на схеме.
6. 6
   Валидация и регистрация

   Нажмите кнопку «Проверить» (Validate) для синтаксической проверки уравнений, затем нажмите кнопку «Зарегистрировать компонент» (Register Component). Новый блок автоматически появится в палитре компонентов.

Интеграция пользовательских математических моделей в БМК

Настоящая инструкция устанавливает регламент разработки, конфигурации и внедрения внешних математических моделей в составе Библиотеки Моделей Компонентов (БМК) при использовании исполняемой (EXE) версии программного комплекса ORPHYS 2.0 в операционной системе Windows.

1. Расположение директории хранения пользовательских компонентов

В структуре исполняемой сборки ORPHYS 2.0 предусмотрена изолированная директория для хранения пользовательских компонентов. Данное хранилище обладает свойством персистентности: его содержимое не подвергается удалению или перезаписи при автоматическом обновлении программного обеспечения.

Локализация пользовательского хранилища:
%APPDATA%\Mars EM Simulator\bmk\
(Абсолютный путь, как правило, имеет вид: C:\Users\<Имя_Пользователя>\AppData\Roaming\Mars EM Simulator\bmk\)

2. Архитектура каталога компонента

Каждый разрабатываемый компонент должен быть размещен в отдельной поддиректории. Наименование поддиректории должно состоять из символов латинского алфавита и строго соответствовать идентификатору компонента.

Структура исходного кода (язык Python):

%APPDATA%\Mars EM Simulator\bmk\
  └── my_pump\
        ├── my_pump.py         # Исходный код математической модели (язык Python)
        ├── catalog.json       # Декларативное описание графического интерфейса (определение портов, параметров)
        └── helper.py          # (Опционально) Вспомогательные модули, содержащие дополнительную логику

Для интегрирования проприетарных (скомпилированных) компонентов вместо файла с расширением .py применяется бинарный модуль .pyd:

%APPDATA%\Mars EM Simulator\bmk\
  └── my_pump\
        ├── my_pump.cp313-win_amd64.pyd  # Бинарный модуль расширения (компиляция C++/Cython)
        └── catalog.json

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

3. Среда исполнения (Интерпретатор Python)

1. Выполнение кода посредством встроенного интерпретатора: В состав исполняемой версии ORPHYS 2.0 интегрирован автономный интерпретатор CPython версии 3.13 (64-битная архитектура). Системный интерпретатор Python (установленный в операционной системе пользователя) не задействуется.
2. Ограничения стандартной библиотеки Python: Вследствие компиляции бэкенда ORPHYS, модули, не задействованные в базовом функционале, исключены из сборки с целью минимизации объема дискового пространства (например, отсутствуют модули tkinter, unittest, pytest).
3. Модули, доступные в базовой конфигурации:
   • Пакет разработки (SDK) симулятора: mars_models_sdk (включающий элементы @component, ComponentSpec, Port, Param).
   • Ключевые модули стандартной библиотеки: math, json, random, re, os, sys, dataclasses, time и прочие.
   • Библиотеки для проведения математических вычислений: numpy, scipy, sympy.

4. Порядок импорта библиотек и смежных модулей

4.1 Импорт вспомогательных модулей (например, helper.py)

Симулятор осуществляет загрузку компонентов напрямую, используя механизм importlib. Следует учитывать, что директория компонента не добавляется в системный путь sys.path автоматически. Попытка прямого или относительного импорта приведет к генерации исключения ModuleNotFoundError.

Корректный синтаксис импорта смежных файлов в коде компонента:

import sys
from pathlib import Path

# Обеспечение доступности директории текущего компонента для механизма импорта:
_COMP_DIR = str(Path(__file__).parent.resolve())
if _COMP_DIR not in sys.path:
    sys.path.insert(0, _COMP_DIR)

# Выполнение импорта смежного модуля:
import helper

4.2 Использование внешних сторонних библиотек (pip)

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

• Библиотека должна быть полностью совместима с Python 3.13 (AMD64 / ОС Windows).
• Для библиотек, написанных исключительно на Python (pure-python), необходимо скопировать директорию библиотеки в каталог разрабатываемого компонента (или в поддиректорию libs/) и зарегистрировать путь в sys.path, аналогично пункту 4.1.
• Бинарные C-расширения (файлы .pyd / .dll) должны быть строго скомпилированы под среду CPython 3.13 64-bit. Все динамически подключаемые DLL-библиотеки должны располагаться в той же директории.

5. Жизненный цикл и процедура регистрации компонентов

• Автоматическое сканирование каталога: Симулятор производит сканирование директории %APPDATA%\Mars EM Simulator\bmk исключительно в момент инициализации (запуска) программы.
• Отсутствие динамической перезагрузки (Hot-Reload): При внесении изменений в файлы во время работы программы симулятор не применяет модификации в реальном времени. Вычислительное ядро использует версию модуля, загруженную в память при старте.
• Регламент обновления: После каждого сохранения изменений в файлах модели необходимо выполнить перезапуск среды моделирования. При последующей инициализации компонент будет повторно считан с диска и зарегистрирован.

6. ВАЖНО: Отсутствие двунаправленной синхронизации с утилитой "Генератор компонентов"

В состав ORPHYS входит утилита «Генератор компонентов» (визуальный конструктор). Необходимо учитывать критический принцип архитектуры:

Практические следствия:

1. Безусловная перезапись файлов: При активации функций «Сгенерировать» или «Сохранить» в интерфейсе Генератора компонентов, программа формирует исходный код на базе визуально заданных параметров и полностью перезаписывает файлы <name>.py и catalog.json в целевой директории.
2. Игнорирование ручных модификаций: Если вы модифицировали файл .py во внешнем редакторе, Генератор компонентов не выполнит импорт этих изменений. Повторное открытие компонента отобразит лишь состояние, зафиксированное в визуальных формах при последнем сохранении.
3. Риск утраты исходного кода: Если после ручного редактирования файла .py пользователь повторно нажмет «Сохранить» в Генераторе, файл будет сформирован заново, что приведет к безвозвратной утрате всех ручных модификаций кода.

Регламент организации рабочего процесса (Рекомендуемый для сложных моделей):

1. Создание каркаса компонента в Генераторе (декларация портов, параметров и УГО).
2. Генерация базовой структуры файлов.
3. Последующее прекращение использования Генератора для данного компонента (запрет на сохранение в конструкторе).
4. Дальнейшая разработка файла .py во внешней среде разработки (IDE).

7. Эталонный пример минимального компонента

Декларативное описание catalog.json:

{
  "my_resistor": {
    "kind": "Пользовательский резистор",
    "sym": "R_USR",
    "body": "R_USR",
    "folder": "Пользовательские",
    "layer": "logic",
    "render": "block",
    "nodes": [
      { "name": "in_val", "dir": "in", "side": "left" },
      { "name": "out_val", "dir": "out", "side": "right" }
    ],
    "attrs": [
      { "name": "resistance", "value": "100.0", "unit": "Ом", "type": "number" }
    ],
    "bus": "my_resistor"
  }
}

Исходный код математической модели my_resistor.py:

import sys
from pathlib import Path

# 1. Интеграция директории компонента в системный путь
_COMP_DIR = str(Path(__file__).parent.resolve())
if _COMP_DIR not in sys.path:
    sys.path.insert(0, _COMP_DIR)

# 2. Импорт SDK симулятора
from mars_models_sdk import component

# 3. Применение декоратора для регистрации функции
@component("my_resistor", inp="in_val", out="out_val")
def my_resistor_step(io):
    # Извлечение значения из входного порта
    u_in = io.read("in_val", 0.0)
    
    # Считывание конфигурационного параметра
    r = io.param("resistance", 100.0)
    
    # Внедрение защиты от деления на ноль
    if r == 0:
        r = 1e-6  
        
    # Вычисление выходной величины
    i_out = u_in / r
    
    # Трансляция вычисленного значения в выходной порт
    io.write("out_val", i_out)

8. Проверочный регламент (Чек-лист) валидации компонента

• ✓
  Путь сохранения

  Директория компонента размещена строго по пути %APPDATA%\Mars EM Simulator\bmk\<идентификатор>\.
• ✓
  Именования

  Наименование директории и основного исполняемого файла (.py или .pyd) полностью совпадают и состоят из латинских символов.
• ✓
  Каталог интерфейса

  В наличии синтаксически корректный файл catalog.json, содержащий определение интерфейсов (nodes) и параметров (attrs).
• ✓
  Импорты

  При использовании импорта смежных модулей реализована модификация sys.path в заголовочной части.
• ✓
  Перезапуск

  Процедура перезапуска среды ORPHYS выполнена после фиксации последних изменений в файлах.
• ✓
  Защита кода

  Файл исходного кода не подвергался перезаписи со стороны утилиты "Генератор компонентов" после внесения ручных модификаций.

Диагностика частых ошибок (ЧаВо / FAQ)

Сводная таблица типовых нештатных ситуаций, возникающих при формировании и расчете схем, с указанием причин и способов устранения.

Создание компонента логического уровня

Практическое руководство по разработке функциональных компонентов логического слоя (L-слоя) в среде моделирования ORPHYS 2.0 с помощью визуального «Генератора компонентов».

Расширенное практическое руководство по разработке функциональных компонентов логического слоя (L-слоя) в среде моделирования ORPHYS 2.0 с помощью визуального «Генератора компонента».

1. Принцип работы логического компонента

В отличие от физического компонента, который формирует невязку F(X, dX/dt, t) = 0, логический компонент реализует один тик (шаг) вычислений — обычную чистую функциональную программу:

выход = f(входы, параметры, состояние)

Ключевые особенности:

1. Вычисление явное, а не совместное с соседями. Логический блок не «договаривается» с ядром об общем решении — он просто получает значения входов и возвращает значения выходов.
2. Исполнение шаг за шагом по тикам временной сетки. Шаг dt фиксирован (по умолчанию согласован с шагом интегрирования объектного слоя, но может быть задан отдельно).
3. Состояние (io.state) живёт между тиками, обеспечивает храниеие и накопление значения переменной.
4. Связь направленная — out → in. В отличие от объектного слоя, нет акаузального объединения узлов; каждый провод отдает скаляр от одного выхода строго одному входу.
5. Реактивное исполнение. После успешного первичного расчёта ComponentBus реагирует на любое изменение параметра или связи в инспекторе мгновенно в фоновом режиме.

Эта особенность диктует три практических следствия для разработчика:

• Тело компонента должно быть чистым: без побочных эффектов, без print, без мутаций глобальных переменных. Шина может вызывать компонент параллельно по разным веткам графа.
• Персистентная память организуется через io.state, а не через глобальные переменные Python-модуля — иначе состояние «протекает» между экземплярами одного класса компонентов.
• Если нужен явный интегратор с фиксированным шагом, всегда используется io.integrate(name, rate, x0) — не собственная реализация метода Эйлера.

2. Архитектурный контракт: ComponentBus, io.integrate, io.state

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

2.1. Декораторы регистрации

Из архитектурного руководства (раздел «Выбор слоя и математической парадигмы»):

В генераторе эквивалент декоратора «спрятан» в служебном коде, который формируется автоматически при нажатии «Зарегистрировать». Вручную править его не нужно.

2.2. Сервис исполнения

Шина компонентов — ComponentBusService.EvaluateGraph — топологически сортирует блоки логического графа и выполняет их в нужном порядке.

В одном проекте могут сосуществовать Python- и C++-реализации одного и того же компонента. Хост автоматически выбирает более быстрый бэкенд (C++), если он доступен, иначе выполняет Python-версию — при условии идентичности формул в обоих файлах.

2.3. Хранилище памяти: io.state

io.state — это словарь персистентной памяти компонента. Он сохраняется:

• между тиками внутри одного запуска;
• между повторными пересчётами той же схемы;
• между сессиями в режиме реального времени (Live), пока не вызван явный сброс.

Поведение словаря описано в таблице IO (см. раздел 9.2 ниже):

io.state["acc"] = ...       # запись
io.state.get("acc", 0.0)   # безопасное чтение с дефолтом
io.state                    # прямой доступ к словарю

2.4. Интегрирование: io.integrate

Шина применяет явный метод Эйлера с фиксированным шагом io.dt. Метод io.integrate(name, rate, x0) извлекает значение из io.state, делает инкремент x_{n+1} = x_n + rate * dt и сохраняет результат обратно. Этот метод — единственный способ гарантированно сохранить состояние интегратора между тиками и не потерять пересчёты при изменении схемы.

2.5. Реактивность

Логический слой реактивен непрерывно: после первого расчёта любое изменение связей или параметров блока в инспекторе мгновенно пересчитывает функциональные ряды в фоновом режиме.

3. Сравнение с объектным слоем

Когда выбирать L-слой, а не C-слой

Главный критерий: если закон описывается как «преобразовать скаляр в скаляр» — это требует компонента L-слоя. Если как «связать давление и поток ветви физическим законом» — это требует компонента C-слоя. Если модель содержит уравнения непрерывности, баланса или нелинейной характеристики физической величины — это всегда C-слой.

4. Подготовка: что нужно знать до запуска генератора

Прежде чем нажимать «Запустить генератор», зафиксируйте на бумаге:

1. Машинное имя (bus id): латиница, без пробелов, уникальное в библиотеке. Используется в реестре и при сборке каталога.
2. Слой компонента: в генераторе выбирается переключателем «Логический» в правом верхнем углу генератора (см. п. 6).
3. Список входов (inp=) и выходов (out=) — направленные скалярные порты. У одного блока может быть несколько входов и несколько выходов.
4. Список параметров: имя, тип, значение по умолчанию, единица измерения, границы (min/max/step).
5. Алгоритм: формула шага выход = f(входы, параметры), или последовательность операций с использованием пресетов (read, write, integrate, state).
6. Состояния памяти (если есть): какие переменные нужно хранить между шагами расчета. Описываются как «дифференцируемые параметры» на вкладке «Параметры».
7. Строковые режимы (если есть): например, мультирежимный источник (const, ramp, sine, square, step).
8. Зависимости для кода Python: используются ли numpy, scipy, sympy, scikit-learn, pandas (встроены) или нужны сторонние пакеты (тогда потребуется .pyd).

5. Шаг 1. Запуск «Генератора компонента»

Запускаем

Запуск производится из меню «Сервис» основного интерфейса ORPHYS. После открытия генератора появляется окно с тем же набором вкладок, что и для объектного слоя, но с одним важным отличием: вкладка «Невязки» заменена на вкладку «Алгоритм», а на вкладке «Код» доступны специальные XML-теги <mars:user-*>.

Рекомендуемый порядок заполнения:

Порты → Параметры → Алгоритм → Код → Внешний вид → Документация

Именно в таком порядке поля более поздних вкладок получают автозаполненные ссылки на ранние сущности.

6. Шаг 2. Вкладка «Порты»

Заполняем порты

Что здесь задаётся: интерфейс компонента — список направленных портов (in/out), которые будут видны на холсте логического слоя для подключения проводов. С точки зрения архитектуры это поля ports= дескриптора ComponentSpec с layer="logic".

6.1. Главный переключатель слоя

В верхней части окна генератора находится переключатель «Объектный»/«Логический». Для компонента логического уровня выбирается «Логический». После этого выбора:

• во вкладке «Невязки» вкладка переименовывается в «Алгоритм»;
• становятся доступны пресеты алгоритма (read, write, integrate, state, param, text, и т.п.);
• в сгенерированном коде используется декоратор @component (а не @physical).

6.2. Минимальные поля одной записи порта

6.3. Количество портов и направление

• Минимум для функционального блока — один вход или один выход. Генератор, источник сигнала или константа могут иметь только выход; индикатор или запись — только вход.
• Компонент может иметь Несколько входов (ПИД-регулятор, например, имеет setpoint и meas, сумматор — a и b); а также может иметь несколько выходов (например, ПИД-регулятор выдаёт u и last_error, блок сравнения выдаёт gt, eq, lt).
• Соединение только out → in: связь отдает значение переменной (объект) от одного выхода ко всем присоединённым связями входам.

6.4. Конфликт имён

Если два логических выхода случайно соединены с одним входом — это ошибка топологии, регистрируемая валидатором. Маркер «нет опоры» / «соединение запрещено» — именно то, что блокирует такую конфигурацию.

6.5. Расширенные поля

7. Шаг 3. Вкладка «Параметры»

Заполняем параметры

Что здесь задаётся: коэффициенты, режимы, начальные условия и состояния памяти. В коде это поля params= дескриптора ComponentSpec и словарь io.state после регистрации.

7.1. Состав полей одной записи параметра

7.2. Поддерживаемые типы

7.3. Состояния (stateful-параметры)

Для интеграторов, фильтров и ПИД-регуляторов добавляются записи состояний: это переменные, которые хранятся в io.state и запоминаются между шагами. На вкладке «Параметры» они имеют признак «Дифференцируемый» или просто маркируются как состояние.

Пример для ПИД-регулятора:

• параметры: Kp = 0.8, Ki = 0.05, Kd = 0.1, setpoint = 50.0;
• состояния: integral = 0.0, prev_error = 0.0 (память интегратора и предыдущей ошибки).

7.4. Тепловая модель (не применимо)

В логическом слое секция «Тепловая модель» не появляется: это понятие физического уровня. Если логический блок участвует в тепловом контуре (например, ПИД управляет АВО), он работает только с числовыми значениями, а тепловое моделирование выполняется в объектном слое через блок АВО.

8. Шаг 4. Вкладка «Алгоритм» (главный шаг)

Заполняем уравнения

Центральный шаг разработки. Здесь формулируется функциональный алгоритм шага — тело будущей функции def step(io): .... Вкладка отличается от объектного слоя тем, что:

• используются пресеты команд из боковой панели (чтение входа, запись выхода, доступ к состоянию и т.п.);
• формула имеет вид присваивания (выход = …), а не невязки (F = 0);
• проверка и сборка переводит алгоритм в питоновский скелет с заглушками для всех внутренних переменных.

8.1. Пресеты команд

В правой панели вкладки доступны кнопки-вставки готовых конструкций. Наиболее употребительные:

Пресеты избавляют от опечаток в строковых литералах и обеспечивают единообразие кода: генератор сам подставляет правильное имя порта/параметра из соответствующих вкладок.

8.2. Правила записи алгоритма

1. Форма — присваивание, а не невязка. Это y = gain * x + offset, а не y - gain * x - offset == 0.
2. Финальная строка должна быть io.write("выход", value) для каждого выходного порта. Если выходов несколько, делается несколько io.write (для каждого свой).
3. Все идентификаторы должны быть объявлены либо как порт (вкладка «Порты»), либо как параметр (вкладка «Параметры»). Свободные имена не допускаются.
4. Все состояния читаются через io.state.get(..., default) на каждом тике. При первом тике io.state пуст — и без default вылетит KeyError.
5. Допускается несколько строк и if/elif/else — алгоритм логический, не обязан укладываться в одну формулу.

8.3. Конструкции алгоритма

Простое преобразование (линейная функция)

y = io.read("x", 0.0) * io.param("gain", 1.0) + io.param("offset", 0.0)
io.write("y", y)

Безусловный интегратор

u = io.read("u", 0.0)
x_prev = io.state.get("acc", 0.0)
x_next = io.integrate("acc", u, x_prev)
io.write("x", x_next)

EMA-фильтр первого порядка

x = io.read("x", 0.0)
alpha = io.param("alpha", 0.2)
y_prev = io.state.get("y", x)
y_curr = y_prev + alpha * (x - y_prev)
io.state["y"] = y_curr
io.write("y", y_curr)

Здесь io.integrate не нужен — это алгебраический фильтр, а не интегратор. Состояние запоминается через io.state явно.

Мультирежимный источник сигнала

mode = io.text("mode", "")
base = io.param("base", 25.0)
amp = io.param("amplitude", 20.0)
freq = io.param("freq", 0.1)

if mode == "sine":
    v = base + amp * math.sin(2 * math.pi * freq * io.ts)
elif mode == "step":
    v = base + (amp if io.ts >= io.param("t0", 0.0) else 0.0)
elif mode == "const":
    v = base
else:
    v = base

io.write("value", v)

Логический автомат (гистерезис)

x = io.read("x", 0.0)
hi = io.param("hi", 1.0)
lo = io.param("lo", 0.0)
state = io.state.get("tripped", False)

if state and x < lo:
    state = False
elif (not state) and x > hi:
    state = True
io.state["tripped"] = state
io.write("y", 1.0 if state else 0.0)

8.4. Проверка и сборка

После заполнения алгоритма нажмите «Проверить и собрать». Генератор:

1. Парсит текст алгоритма через встроенный парсер Python AST.
2. Проверяет, что все идентификаторы разрешены (объявлены в портах, параметрах или состояниях).
3. Подставляет default-значения и проверяет синтаксическую корректность.
4. Генерирует питоновский скелет компонента с заглушками для всех внутренних переменных.
5. Открывает доступ к редактированию сгенерированного кода на вкладке «Код».

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

9. Шаг 5. Вкладка «Код» — Python в тегах mars:user-*

Дописываем код

Вкладка «Код» для логического слоя устроена также как и для объектного. Здесь доступны три специальных XML-тега, в которые вставляется пользовательский Python-код (не доступен тег блока невязок):

Генератор сам формирует вокруг этих блоков всю обвязку:

# Автоматически сгенерированная шапка:
from mars_core.component_sdk import component
from mars_core.component_spec import ComponentSpec, Port, Param, AutomationSpec, ...

SPEC = ComponentSpec(
    name="my_pid",
    layer="logic",
    folder="Управление",
    ports=[Port("setpoint", dir="in"), Port("meas", dir="in"),
           Port("u", dir="out")],
    params=[Param("Kp", 0.8, "—"), Param("Ki", 0.05, "—"),
            Param("Kd", 0.1, "—"), Param("dt_min", 0.0, "с")],
    # ... и т.д. из вкладок Порты и Параметры
)

# <mars:user-imports>
import math                     # ← пользовательский импорт
# </mars:user-imports>

# <mars:user-helpers>
def _clamp(x, lo, hi):
    return max(lo, min(hi, x))  # ← пользовательская функция
# </mars:user-helpers>

@component("my_pid", inp="meas", out="u", spec=SPEC)
def my_pid(io):
    # <mars:user-compute>
    sp = io.read("setpoint", 0.0)
    meas = io.read("meas", 0.0)
    e = sp - meas
    Kp = io.param("Kp", 0.8)
    Ki = io.param("Ki", 0.05)
    Kd = io.param("Kd", 0.1)
    integral = io.state.get("integral", 0.0)
    de = (e - io.state.get("prev_error", 0.0))
    integral += e * io.dt
    u = Kp * e + Ki * integral + Kd * de / max(io.dt, 1e-9)
    u = _clamp(u, -100.0, 100.0)
    io.state["integral"] = integral
    io.state["prev_error"] = e
    io.write("u", u)
    # </mars:user-compute>

9.1. Когда нужно дописывать код вручную

1. Подключение сторонних пакетов: numpy.linalg, scipy.signal, pandas.read_csv, модели scikit-learn — все они разрешены «из коробки», импорт делается в <mars:user-imports>.
2. Сложные многоступенчатые алгоритмы: если алгоритм содержит вложенные for, списковые включения, генераторы табличных коэффициентов — их удобнее оформить в виде вспомогательной функции в <mars:user-helpers>.
3. Локальные физико-математические формулы: например, реализация обратной матрицы, формулы перевода единиц, уравнения состояния.
4. Использование .pyd/.so модулей — при необходимости подключения собственных скомпилированных библиотек их .pyd-файл размещается в одной папке с компонентом и импортируется обычным способом.

9.2. Таблица API io

Это полный контракт интерфейса, читаемый внутри функции шага.

9.3. Импорт сторонних модулей

Генератор автоматически разрешает импорты четырёх встроенных пакетов: scipy, numpy, sympy, scikit-learn, pandas. Все они доступны без дополнительной настройки. Иные пакеты требуют размещения скомпилированного .pyd-файла в папке компонента:

bmk/<group>/my_pid/
    ├── my_pid.py        # код компонента
    ├── my_pid.pyd       # скомпилированный собственный модуль
    └── tests/

После редактирования нажмите «Проверить код» — генератор перепарсит AST и убедится, что все импорты разрешены.

9.4. Ограничения

• Тело функции должно быть чистым: без глобальных мутаций и без print. Шина может вызывать компонент параллельно.
• Состояние хранится только в io.state. Глобальные переменные Python-модуля дают утечку между экземплярами.
• Длинные табличные коэффициенты лучше выносить в отдельный файл .npz / .csv и читать через io.array или io.table — иначе def разрастается до десятков килобайт.
• Запрещается явное использование requests, subprocess, socket — вычислительное ядро изолировано от внешних сервисов.

10. Шаг 6. Вкладка «Внешний вид»

Редактируем внешний вид

Здесь задаётся векторное обозначение компонента, отображаемое в логической палитре и на холсте логического слоя. Функциональность идентична объектному слою (см. соответствующий раздел guide_object.md), но с двумя особенностями:

1. Символ на теле блока. Для логических блоков принято использовать функциональные обозначения: треугольник для усилителей, прямоугольник с буквой S для сумматоров, прямоугольник с ∫ для интеграторов, прямоугольник с ∫ и pid для ПИД-регуляторов.
2. Стрелки направления. В отличие от объектного слоя, на логических блоках явно рисуются стрелки in / out, чтобы инженер не ошибся при подключении. Генератор рисует их автоматически, но внешний вид можно скорректировать вручную.

Рекомендации

• Длина подписей портов — не более 4–6 символов (in, out, u, y, pid_in).
• Символ тела — опознаваемый, в верхнем регистре: PID, FF, EMA, SRC.
• Точки подключения должны точно совпадать со сторонами, указанными на вкладке «Порты».

11. Шаг 7. Вкладка «Документация»

Заполняем информацию

Что здесь задаётся: паспорт компонента. Функциональность идентична объектному слою (guide_object.md).

Минимальный набор полей

• Поле "Краткое описание". Что можно писать:

• Поле "Внешние зависимости". Здесь необходимо указывать требуемые библиотеки для работы компонента.
• Поле "Связанные компоненты". Указываются компоненты, связанные с описываемым, или рабоающие с ним в связке.
• Поле "Замечания". Что можно писать:

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

Что указать обязательно

• Суть алгоритма — даже если она очевидна из кода. Формула нужна для рецензирования без запуска Python.
• Требования к шагу dt — устойчивость явного Эйлера зависит от выбора dt. Если компонент содержит интегратор с большим коэффициентом усиления, укажите минимально допустимый шаг.
• Безопасное значение safe_value — особенно для исполнительных механизмов (вентилятор, клапан). При остановке сессии шина переводит выход в safe_value (см. п. 14 «Частые сценарии»).

12. Шаг 8. Контроль готовности и место сохранения

Перед регистрацией выполните финальную проверку.

Чек-лист готовности

1. Машинное имя — латиница, без пробелов, уникальное.
2. Слой — переключатель стоит в положении «Логический».
3. Список портов соответствует логике алгоритма: каждый io.read("…") имеет одно объявление Port со стороной и направлением.
4. Список параметров покрывает все io.param(...) / io.text(...) / io.flag(...) / io.array(...) / io.pair(...) / io.table(...).
5. Состояния объявлены, если алгоритм обращается к io.state.
6. Алгоритм записан и проходит проверку.
7. Код проходит проверку синтаксиса и импортов.
8. Глиф не выходит за габариты портов.
9. Паспорт заполнен, ограничения указаны.

Выбор папки сохранения

Логические компоненты публикуются в пользовательскую папку bmk/:

poc/bmk/<group>/<component_name>/
    ├── <component_name>.py     # код компонента
    ├── <component_name>.cpp    # опционально, для C++ версии
    ├── <component_name>.tex    # документация (паспорт)
    ├── glyph.svg               # внешний вид (опционально)
    └── tests/
        └── test_<component_name>.py

13. Шаг 9. Регистрация и проверка появления в БМК

Находим компонент в БМК

По нажатию кнопки «Зарегистрировать» генератор выполняет конвейер регистрации (идентичен объектному слою):

1. Сохранение исходников в папку bmk/<group>/<component>/. Формируются:
2. <name>.py — код с ComponentSpec (где layer="logic") и декоратором @component;
3. <name>.tex — паспорт;
4. glyph.svg — глиф;
5. test_<name>.py — заготовка юнит-теста.
6. Вызов регистратора — компилирует код, импортирует модуль и регистрирует блок в реестрах REGISTRY, _RESIDUALS, _PHYSICAL_SPECS. Это возможно без перезапуска сервера (исполняемого приложения ORPHYS).
7. Генерация записи catalog.json с метаданными для палитры.
8. Сборка обновлённого клиентского каталога.
9. Пересборка production-бандла (по необходимости).

1. Запуск автотестов.
2. Визуальная проверка: новый блок появляется в палитре логического слоя в указанной папке.

Как убедиться, что регистрация прошла успешно

• В дереве палитры логического слоя отображается новая запись.
• В инспекторе свойств видны параметры с правильными единицами.
• При запуске минимальной пробной схемы Константа → мой_блок → Индикатор расчёт не падает, индикатор показывает значение.

14. Частые сценарии алгоритмов

Здесь приведены примеры логических компонентов.

14.1. Преобразователь вход → выход (датчик температуры)

Линейная функция $T = R \cdot \text{gain} + \text{offset}$:

@component("datchik_temperatury", inp="R_Ohm", out="T_C")
def datchik(io):
    x   = io.read("R_Ohm", 100.0)
    g   = io.param("gain", 2.5974)
    off = io.param("offset", -259.74)
    io.write("T_C", x * g + off)

14.2. Источник гармонического сигнала во времени

Без входа; выход строится на базе счётчика тиков io.ts:

import math
from mars_core.component_sdk import component

@component("istochnik_znacheniya", inp="p_in", out="value")
def src(io):
    base = io.param("base", 25.0)
    amp  = io.param("amplitude", 20.0)
    freq = io.param("freq", 0.1)
    val  = base + amp * math.sin(2.0 * math.pi * freq * io.ts)
    io.write("value", val)

14.3. Мультирежимный источник с переключением во время выполнения

Строковый режим io.text("mode", "") с числовым резервом mode_id:

import math
from mars_core.component_sdk import component

@component("multimod_source", inp="p_in", out="value")
def multimod_source(io):
    base  = io.param("base", 25.0)
    amp   = io.param("amplitude", 20.0)
    freq  = io.param("freq", 0.1)
    slope = io.param("slope", 1.0)
    t0    = io.param("t0", 0.0)

    modes = {"const": 0, "ramp": 1, "sine": 2, "square": 3, "step": 4}
    m = modes.get(io.text("mode", ""), int(io.param("mode_id", 2.0)))

    if   m == 0: v = base
    elif m == 1: v = base + slope * io.ts
    elif m == 3: v = base + amp * (1.0 if math.sin(2*math.pi*freq*io.ts) >= 0 else -1.0)
    elif m == 4: v = base + (amp if io.ts >= t0 else 0.0)
    else:        v = base + amp * math.sin(2 * math.pi * freq * io.ts)

    io.write("value", v)

14.4. Линейный ограничитель (Limiter)

Надёжная параметризация с безопасными дефолтами:

from mars_core.component_sdk import component

@component("limiter", inp="x", out="y")
def limiter(io):
    x  = io.read("x", 0.0)
    k  = io.param("k", 1.0)
    lo = io.param("min", 0.0)
    hi = io.param("max", 100.0)
    y  = max(lo, min(hi, x * k))
    io.write("y", y)

14.5. Составные типы данных: массивы, пары, таблицы

Полиномиальный фильтр с кусочно-линейной характеристикой:

from mars_core.component_sdk import component

@component("poly_filter", inp="x", out="y")
def poly_filter(io):
    x = io.read("x", 0.0)
    coeffs = io.array("coeffs", [0.0])
    lo, hi = io.pair("range", (-100.0, 100.0))
    table  = io.table("curve", [])

    y = 0.0
    p = 1.0
    for c in coeffs:
        y += c * p
        p *= x
    y = max(lo, min(hi, y))
    io.write("y", y)

14.6. EMA-фильтр (экспоненциальное скользящее среднее)

Демонстрация работы с io.state для алгебраических фильтров:

from mars_core.component_sdk import component

@component("ema", inp="x", out="y")
def ema(io):
    x = io.read("x", 0.0)
    alpha = io.param("alpha", 0.2)
    # При первом тике состояние инициализируется значением входа.
    y_prev = io.state.get("y", x)
    y_curr = y_prev + alpha * (x - y_prev)
    io.state["y"] = y_curr
    io.write("y", y_curr)

14.7. Интегратор с утечкой (термоаккумулятор)

Интегрирование через io.integrate с явным накоплением:

from mars_core.component_sdk import component

@component("thermal_storage", inp="Q", out="T")
def thermal_storage(io):
    q        = io.read("Q", 0.0)
    capacity = io.param("C", 1000.0)
    ambient  = io.param("Tamb", 20.0)
    loss     = io.param("k", 5.0)

    t_prev   = io.state.get("T", io.param("T0", ambient))
    dtdt     = (q - loss * (t_prev - ambient)) / capacity
    t_next   = io.integrate("T", dtdt, x0=t_prev)
    io.write("T", t_next)

14.8. Управляемый вентилятор со спецификацией автоматизации

Шаблон с AutomationSpec (команды, телеметрия, безопасное значение):

from mars_models_sdk import (
    component, ComponentSpec, Port, Param,
    AutomationSpec, AutomationCommand, AutomationTelemetry,
)

SPEC = ComponentSpec(
    name="fan_object",
    kind="Управляемый вентилятор",
    sym="FAN",
    layer="logic",
    folder="Пользовательские/Приводы",
    ports=[
        Port("cmd", dir="in",  side="left"),
        Port("rpm", dir="out", side="right"),
    ],
    params=[
        Param("rpm_nominal", 1500.0, "об/мин", type="number"),
        Param("enabled", True, type="bool"),
    ],
    automation=AutomationSpec(
        commands=(
            AutomationCommand(
                id="set_cmd", label="Команда скорости",
                target_attr="cmd", value_type="number",
                minimum=0.0, maximum=1.0, step=0.01,
                safe_value=0.0,
            ),
        ),
        telemetry=(
            AutomationTelemetry(
                id="rpm", label="Текущие обороты",
                source="rpm", unit="об/мин",
            ),
        ),
    ),
)

@component("fan_object", inp="cmd", out="rpm", spec=SPEC)
def fan_object(io):
    cmd = max(0.0, min(1.0, io.read("cmd", 0.0)))
    if not io.param("enabled", 1.0):
        cmd = 0.0
    rpm = cmd * io.param("rpm_nominal", 1500.0)
    io.write("rpm", rpm)

14.9. ПИД-регулятор с bumpless transfer

Типовая конструкция для замкнутых контуров управления:

@component("pid", inp="meas", out="u")
def pid(io):
    sp  = io.read("setpoint", 0.0)
    err = sp - io.read("meas", 0.0)
    Kp  = io.param("Kp", 0.8)
    Ki  = io.param("Ki", 0.05)
    Kd  = io.param("Kd", 0.0)
    dt  = max(io.dt, 1e-9)

    integral = io.state.get("i", 0.0) + err * dt
    de       = (err - io.state.get("prev_err", err)) / dt
    u        = Kp * err + Ki * integral + Kd * de

    io.state["i"]        = integral
    io.state["prev_err"] = err
    io.write("u", u)

14.10. Адаптер для связи с объектным слоем (l_device)

Один из самых важных компонентов: читает метрики и формирует команды для объектного аппарата:

@component("l_device", inp="cmd", out="value")
def l_device(io):
    target = io.text("device", "")
    bind   = io.text("bind", "")
    kind   = io.text("role", "out")
    bus    = io.state.get("__bus", None)

    if kind == "in":
        # Записать команду в объектный аппарат:
        cmd_value = io.read("cmd", 0.0)
        io.write("pushed_cmd", cmd_value)
        # Шина применит патч к объектному аппарату через __series.
    else:
        # Прочитать метрику аппарата через служебный узел __series.
        metric = io.state.get("__metric_" + bind, 0.0)
        io.write("value", metric)

15. Типичные ошибки и их диагностика

Этот раздел существенно отличается от таблицы ошибок объектного слоя: ошибки логики другие.

16. Приёмочные испытания после регистрации

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

16.1. Регистрация в реестре шины

import mars_core.component_host
from mars_core.dispatcher import REGISTRY

assert "my_pid" in REGISTRY

Если REGISTRY не экспортируется напрямую — посмотрите dir() на импортированном component_host.

16.2. Численное базовое тестирование шага

Подайте искусственные входы, рассчитайте ожидаемое значение и сравните:

io = make_io(setpoint=50.0, meas=55.0, Kp=0.8, Ki=0.05, Kd=0.0,
             dt=0.01, prev_err=0.0, i=0.0)
u = pid(io)
assert abs(u - (-0.8 * 5.0 + 0.05 * (-0.05))) < 1e-9

Здесь make_io — тестовая обёртка, формирующая совместимый контекст. В реальной кодовой базе такая утилита обычно лежит в tests/_harness/.

16.3. Интеграционный тест на схеме

Соберите минимальную пробную схему:

Константа (setpoint=50) → PID → Индикатор "u"
                ↑
Датчик (meas=…) ┘

Запустите расчёт и убедитесь:

• при meas = setpoint выход u стабилизируется около 0 (или значения, которое даёт интегральная составляющая);
• при ступенчатом изменении meas выход реагирует с характерной ПИД-кривой (бросок → затухание → стабилизация);
• состояние ПИД не сбрасывается при изменении связей в инспекторе (проверка bumpless transfer).

16.4. Регрессионное тестирование в pytest

Поместите тесты в tests/test_<имя_компонента>.py. Минимальный набор:

1. Регистрация: assert "<name>" in REGISTRY.
2. Аналитический баланс: при известных значениях выход равен расчётному.
3. Память: интегратор и фильтр сохраняют io.state между тиками.
4. Типовая ошибка топологии: попытка соединить два выхода должна приводить к ошибке валидатора (если хочется автоматизировать этот контроль).

17. Управление жизненным циклом

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

Изменение значений по умолчанию безопасно: влияет только на вновь размещаемые блоки. Уже размещённые экземпляры хранят свои значения в attrs каждого блока.

Переименование машинного имени порта

Изменение алгоритма

Переписывание тела функции допустимо после публикации — внутренняя логика изолирована от топологии. Однако:

• если вы изменяете список читаемых параметров — синхронно обновите вкладку «Параметры» в ComponentSpec;
• если вы добавляете новое состояние — опишите его на вкладке «Параметры» как дифференцируемый параметр;
• сохраните обратную совместимость: инспектор уже размещённых блоков не должен показывать незнакомые поля (для этого используются дефолты).

Удаление компонента

1. Удалите файлы из bmk/<group>/<component>/.
2. Запустите среду моделирования.
3. Убедитесь, что активные проекты не содержат экземпляров компонента (иначе — ошибка валидатора при загрузке).

Конкурентная запись параметров в реальном времени

Один и тот же параметр исполнительного механизма (например, cmd) не должен одновременно перезаписываться регулятором, сценарием ИСУЛ и ручным вводом из инспектора. Для разрешения конфликта используются приоритетные классы управления (priorityClass в AutomationCommand) и политики сценария в ИСУЛ.

18. Краткая шпаргалка

18.1. Минимальный обязательный набор полей в генераторе

Порты       — минимум один вход или один выход
Параметры   — минимум один числовой параметр (или пусто)
Алгоритм    — строки с read/param/state/integrate/write
Код         — пусто (генератор сам подставит декоратор и SPEC)
Внешний вид — пусто (стандартный прямоугольник)
Документация     — хотя бы краткое описание назначения

18.2. Эквивалент «вкладка ↔ код»

18.3. Сводка «когда какой слой выбирать»

Создание компонента объектного уровня

Практическое руководство по разработке физических компонентов объектного слоя (C-слоя) в среде моделирования ORPHYS 2.0 с помощью визуального «Генератора компонентов».

Расширенное практическое руководство по разработке физических компонентов объектного слоя (C-слоя) в среде моделирования ORPHYS 2.0 с помощью визуального «Генератора компонента».

1. Принцип работы объектного компонента

В отличие от логического блока, который «вычисляет выход из входа», физический компонент объектного слоя формирует уравнение физического закона в форме невязки:

F(t, X, dX/dt) = 0

Здесь:

• X = [V(узлы), I(ветви)] — общий вектор состояния, формируемый численным ядром, где V - потенциальная переменная (ток, расход, сила), I - потенциальная (напряжение, давление, скорость);
• dX/dt — производные по времени для динамических систем;
• t — текущее физическое время интегрирования.

Ядро решателя, а не компонент, вычисляет токи и потенциалы. Компонент лишь сообщает ядру, какое физическое соотношение связывает потенциалы его полюсов и поток в его ветви. Решатель синхронно находит узловые потенциалы и ветвевые потоки всей схемы методом Ньютона с LU-факторизацией разреженной матрицы Якоби (SuperLU). Поэтому вклад компонента — это одно уравнение невязки ветви для двухполюсника (плюс дополнительные уравнения для внутренних состояний и многопортовых аппаратов).

Эта особенность диктует три практических следствия:

1. Каждый физический закон записывается в инженерной форме «должно быть равно нулю», а не в форме присваивания.
2. Уравнения непрерывности потока (KCL) в узлах уже заложены в модель — их записывать не нужно, иначе система окажется переопределённой.
3. Динамика объявляется явно: при написании кода компонента для dP/dt или dU/dt указывается diff="nodes", для dG/dt или dI/dt — diff="branch". Без этого флага решатель не выделит производную. При разработке модели в генераторе это деалется автоматически.

2. Архитектурный контракт и общая схема регистрации

Полный путь от определения модели до видимости компонента в палитре библиотеки модели компонентов (БМК) состоит из двух уровней регистрации.

Цепочка регистрации выглядит так:

Генератор модели компонента
   ↓ Спецификация компонента + код вычисления невязки
Модуль регистрации
   ↓ авторегистрация в момент импорта
Реестры ядра (_RESIDUALS, _PHYSICAL_SPECS)
   ↓
Перезапуск клиента среды
   ↓
Сборка и размещение в палитре БМК

В генераторе весь этот конвейер свёрнут в одну пользовательскую операцию — кнопку «Зарегистрировать». Далее в документе описано, что именно происходит на каждой вкладке генератора.

3. Домены физики: что и почему

Объектный слой ORPHYS — акаузальный: один и тот же решатель обслуживает несколько физических доменов. Для каждого домена закреплена пара потенциальная / потоковая переменные (across/through).

Кроме того, домены oilgas и thermal дополнительно требуют тепловую модель (см. п. 8.4) — это профили flow_through или accumulation, которые автоматически генерируют уравнения переноса тепла/состава. Домен electrical и hydraulic обычно обходятся одной невязкой ветви без расширений.

4. Подготовка: что нужно знать до запуска генератора

Прежде чем нажимать «Запустить генератор», целесообразно зафиксировать на бумаге следующие позиции. Это сокращает число возвратов к редактированию вкладок и снижает риск переименования идентификаторов (см. п. 15).

1. Машинное имя (bus id): латиница, без пробелов, уникальное в пределах библиотеки. Используется решателем для сопоставления блока с функцией невязки. Не должно меняться после публикации.
2. Читаемое имя и обозначение на теле блока (sym) — то, что увидит пользователь в палитре и на корпусе компонента.
3. Список портов с указанием:
4. имени (машинное);
5. направления (in/out);
6. стороны (left, right, top, bottom);
7. физического домена.
8. Список параметров: имя, тип, значение по умолчанию, единица измерения, границы (для int/number).
9. Физический закон в инженерной форме — уравнение связи across и through для выбранного домена. Закон записывается как «разность должна быть равна нулю».
10. Признаки динамики: содержит ли модель производные по времени, и если да — к какой переменной они относятся (потенциалу узлов или потоку ветви).
11. Признак нелинейности: квадратичные потери, экспоненты, произведения неизвестных — всё это потребует nonlinear=True.
12. Признак многопортовости: только если на портах должны быть независимые through-переменные (тройник, многообмоточный трансформатор, общий коллектор).
13. Признак накоплнения среды: для нефтегазовых аппаратов потребуется выбор пресета flow_through / accumulation и входной порт для StreamProfile.
14. Признак опции V-слоя: какие из параметров нужно открыть как пользовательские настройки визуального слоя.

Если хотя бы один из пунктов остался неясным, см. раздел 14 «Частые сценарии» — там приведены эталонные шаблоны для типовых аппаратов.

5. Шаг 1. Запуск «Генератора компонента»

Запускаем

Запуск производится из меню «Сервис» - «Генератор компонента» основного интерфейса ORPHYS (см. архитектурное руководство, «Инженерный инструментарий» → «визуальный конструктор компонентов»).

После запуска откроется окно с набором вкладок:

• Порты;
• Параметры;
• Невязки;
• Код;
• Внешний вид;
• Документация.

Заполнять вкладки рекомендуется в порядке Порты → Параметры → Невязки → Код → Внешний вид → Документация — так поля более поздних вкладок получают корректные ссылки на ранние сущности.

6. Шаг 2. Вкладка «Порты»

Заполняем порты

Что здесь задаётся: интерфейс компонента, который будет виден на холсте для подключения проводов и валидации при сборке схемы. С точки зрения архитектуры это поля ports= дескриптора ComponentSpec.

Минимальные поля одной записи порта

Практические замечания

• Количество портов определяется физикой процесса. Для двухполюсной ветви (труба, клапан, резистор) порты два: вход и выход. Для ёмкости между двумя узлами давления — также два, для спепаратора - три. Тройник — три и так далее.
• Сторону подключения к сети имеет смысл выбирать так, чтобы поток среды на схеме шёл слева направо (inlet → left, outlet → right), это согласуется с автоматическим алгоритмом расчёта размера блока.
• Переименование name после публикации компонента приведёт к потере привязок в ранее сохранённых проектах, сценариях ИСУЛ и алгоритмах СГМС — это миграционно-чувствительная операция.
• Если компонент реализует наполнение материи по потоковой переменной (сепаратор с удержанием массы, ректификационная колонна, теплообменник с аккумуляцией), отметьте галочки:
• «Независимые расходы портов» — для многопортового аппарата, у которого потоки на портах не равны (накопитель имеет отдельный вход и отдельный выход).
• «Накопитель среды» — для аппаратов с гидродинамическим удержанием массы; разрешает генерацию дифференциального уравнения накопления. Эта опция автоматически расширяет размерность DAE на одно состояние.

Расширенный сценарий: «внешние переменные»

Для аппаратов, которые будут управляться из логического слоя или читаться им (например, для АВО нужны fan_speed и T_product_out для получения от регулятора целевого значения скорости вращения и передачи текущего значения температуры продукта на выходе). Таки переменные задаются как параметры с отметкой о публикации для V-слоя. Передача данных между L- и C- уровнями осуществляется на схеме с помощью компонента "Связь с аппаратом". То есть для передачи значения параметра / переменной на V- или L- уровень не требуется заводить специальный порт, достаточно завести параметр, публикуемый для передачи данных.

7. Шаг 3. Вкладка «Параметры»

Заполняем параметры

Что здесь задаётся: коэффициенты, настройки и граничные условия компонента — поля params= дескриптора ComponentSpec и атрибуты блока attrs= в сериализации схемы.

Состав полей одной записи параметра

Поддерживаемые типы параметров

Дифференцируемые параметры (внутренние состояния)

Для моделей с памятью (ёмкость с инерцией давления, термоаккумулятор, гистерезисный клапан) на этой же вкладке добавляются состояния (states):

• name — имя состояния, доступное в формулах невязок;
• default — начальное условие x(t=0);
• unit, description — для инспектора;
• publish — публикация состояния как метрики на V-слой.

Тепловая модель

Для компонентов теплогидравлического и нефтегазового доменов в нижней части вкладки присутствует секция «Тепловая модель» с пресетами геометрии: кожухотрубный, пластинчатый, спиральный, произвольный.

Параметры:

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

8. Шаг 4. Вкладка «Невязки» (главный шаг)

Заполняем уравнения

Это центральный шаг разработки компонента. Здесь формулируется математический закон, на основании которого ядро будет включать компонент в совместно решаемую DAE-систему. Ошибки в этой вкладке дают трудно диагностируемые расходимости численного решателя.

8.1. Базовая форма записи уравнения

В генераторе формула вводится как обычное математическое выражение в правой части уравнения F = 0, то есть в инженерной форме «разность, которая должна обратиться в нуль». Например, для гидравлического сопротивления:

P_in - P_out - R * G = 0

В генераторе используется математический движок MathLive / SymPy, что позволяет:

• вводить формулы визуально (WYSIWYG), в том числе с автозаменой Vdot → $\dot{V}$;
• использовать автоматическое символьное дифференцирование для построения якобиана (см. п. 8.6);
• проверять размерности в символьном виде (при наличии описаний единиц).

8.2. Доступные идентификаторы в формулах

В формулах допустимо использовать:

• Имена портов в виде P_in, P_out, V1, V2 — те читают potential соответствующего полюса;
• Имена параметров, объявленных во вкладке «Параметры»: R, tau, mu, и т.п.;
• Глобальный поток ветви G (для гидравлики/нефтегаза) или I (для электрики);
• Производные: dP_dt, dG_dt — в зависимости от установленного флага diff;
• Внутренние состояния (если объявлены): Pf, alarm — текущие значения; dPf_dt, dalarm_dt — их производные.

Идентификаторы портов, параметров и состояний подставляются генератором автоматически из соответствующих вкладок. Допускается также свободный ввод (объявленных, но не новых) имён.

8.3. Конститутивные уравнения для типовых доменов

В таблице ниже приведены канонические формы невязки для типовых компонентов.

8.4. Включение динамики: флаг «дифф. переменная»

В нижней части пресетов переменных вкладки «Невязки» находится пресеты по потоковым переменным (например, dG или dP для нефтегазового домена).

Если модель содержит собственные внутренние состояния, не сводящиеся к потенциалам полюсов или сквозному потоку (см. вкладку «Параметры», секция «Дифференцируемые параметры»), их уравнения дописываются отдельной строкой в таблицу невязок.

8.5. Включение нелинейности: флаг «Нелинейная модель»

Любой компонент, чей закон сохранения содержит квадратичные потери, модули, экспоненты или произведения неизвестных (диод, клапан с квадратичным сопротивлением, насос с кубической характеристикой), должен иметь установленный флаг Нелинейная модель. Это эквивалентно nonlinear=True в декораторе и сообщает ядру о необходимости полного пересчёта матрицы Якоби и включения адаптивного демпфирования шага Ньютона.

8.6. Аналитический якобиан (автоматическая генерация)

Если установлен флаг «Аналитический якобиан», генератор с помощью SymPy выполняет символьное дифференцирование формулы по каждой неизвестной (dF/dV_in, dF/dG, dF/dt и т.п.) и встраивает полученные выражения прямо в код невязки.

Когда это помогает: жёсткие нелинейные модели и большие схемы, где численное дифференцирование по раскраске столбцов становится узким местом. Символьный якобиан сокращает количество обращений к уравнениям в 10–30 раз.

Когда это не помогает (или вредит): модели с большим числом условных переходов (if/else, разные режимы работы в зависимости от значений переменных); в этом случае аналитический якобиан придётся дописывать вручную на вкладке «Код».

8.7. Проверка и сборка

После заполнения формулы рекомендуется нажать кнопку «Проверить и собрать». Генератор в этом режиме:

1. Парсит выражение через SymPy и строит абстрактное синтаксическое дерево.
2. Проверяет, что все идентификаторы разрешены (объявлены в портах или параметрах).
3. Подставляет символьные значения по умолчанию и проверяет отсутствие деления на ноль в формуле.
4. При включённом аналитическом якобиане — выполняет символьное дифференцирование.
5. Генерирует код Python-функции невязки и помещает его в черновик компонента.

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

9. Шаг 5. Вкладка «Код» — пользовательская логика на Python

Дописываем код

На этой вкладке формируется тело функции шага на языке Python — исполняемая часть компонента, которая будет зарегистрирована через @physical(SPEC) в реестре _RESIDUALS ядра.

Здесь доступны 4 специальных XML-тега, в которые вставляется пользовательский Python-код:

9.1. Что именно генерирует вкладка «Невязки»

По нажатию «Зарегистрировать» генератор формирует файл следующей приблизительной структуры:

from mars_core.acausal import physical
from mars_core.component_spec import ComponentSpec, Port, Param

SPEC = ComponentSpec(
    name="hydraulic_resistor",
    kind="Гидравлическое сопротивление",
    layer="object",
    folder="Гидравлика",
    domain="hydraulic",
    ports=[
        Port("inlet",  dir="in",  side="left",  domain="hydraulic"),
        Port("outlet", dir="out", side="right", domain="hydraulic"),
    ],
    params=[Param("R", 1000.0, unit="Па/(кг/с)", type="number")],
)

@physical(SPEC)
def hydraulic_resistor(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    G = I[c["id"]]
    R = float(c["attrs"].get("R", 1000.0))
    return (V[a] - V[b]) - R * G

Пользовательский код на вкладке «Код» — это тело функции между строкой def hydraulic_resistor(c, V, I, dV, dI, t, lam): и return .... Если специальной логики не требуется, генератор сам подставит сгенерированное return из вкладки «Невязки», и вкладку «Код» можно пропустить.

9.2. Когда нужно дописывать код вручную

• Сложные многоступенчатые алгоритмы (например, итерационный расчёт тепловой характеристики АВО как функции от оборотов и температуры);
• Модели с условными переходами: if P > P_critical: ...; такие модели плохо выражаются одной формулой невязки;
• Вспомогательные публикации метрик: можно дополнить словарь publish_metrics (см. ниже);
• Импорт специализированных численных функций (например, термодинамика библиотеки теплофизических свойств).

9.3. Расширенные сценарии кода

Публикация метрик на V-слой

Для возможности публикации значений переменных на V-слой необходимо на вкладке "Параметры" отметить галочкой чекбокс "Публикуемый". Это генерирует следующий код:

def publish_metrics(c, V, I, t, S):
    a, b = c["nodes"]
    return {
        "flow_kgs": float(I[c["id"]]),
        "dp_pa":    float(V[a] - V[b]),
        "T_prod_out_c": float(S.get("T_out", 0.0)) - 273.15,
    }

@physical(SPEC, publish=publish_metrics)
def hydraulic_resistor(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    G = I[c["id"]]
    R = float(c["attrs"].get("R", 1000.0))
    return (V[a] - V[b]) - R * G

Использование объектного API через Elem

Для моделей с большим числом портов удобно читать потенциалы и потоки через класс Elem:

from mars_core.comp_runtime import Elem
_PORTS = ("inlet", "outlet")
_DIRS  = ("in", "out")
_MULTI = False

def _body(elem):
    inlet, outlet = elem.port("inlet"), elem.port("outlet")
    R = elem.param("R", 1000.0)
    return (inlet.potential - outlet.potential) - R * inlet.flow

@physical(SPEC)
def hydraulic_resistor(c, V, I, dV, dI, t, lam):
    return _body(Elem(c, V, I, dV, dI, t, lam, _PORTS, _DIRS, _MULTI))

Нефтегазовый аппарат с StreamProfile

from mars_core.stream_profile import StreamProfile

SPEC_OG = ComponentSpec(
    name="oilgas_linear_resistance",
    kind="Технологическое сопротивление смеси",
    layer="object",
    folder="Нефтегазовые аппараты",
    domain="oilgas",
    supports_stream=True,
    stream_role="resistance",
    ports=[Port("inlet", dir="in"), Port("outlet", dir="out")],
    params=[Param("R", 1000.0, unit="Па/(кг/с)")],
)

@physical(
    SPEC_OG,
    stream=StreamProfile.flow_through("inlet", "outlet", allow_reverse=True),
    publish=lambda c, V, I, t, S: {
        "flow_kgs": float(I[c["id"]]),
        "dp_pa": float(V[c["nodes"][0]] - V[c["nodes"][1]]),
    },
)
def oilgas_linear_resistance(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    return (V[a] - V[b]) - float(c["attrs"].get("R", 1000.0)) * I[c["id"]]

9.4. Ограничения

• Тело функции должно быть чистым: без глобальных мутаций и без побочных эффектов. Ядро вычисляет невязки параллельно по цветам столбцов якобиана.
• Запрещается print/stdout в горячем цикле (снижает производительность).
• Любые пользовательские import должны находиться в шапке файла.

10. Шаг 6. Вкладка «Внешний вид» — глиф блока

Редактируем внешний вид

Здесь задаётся векторное обозначение компонента, которое будет отображаться в палитре и на холсте. Редактор глифов позволяет:

• загрузить готовый SVG-файл (например, из ГОСТ-обозначений);
• нарисовать блок вручную из готовых примитивов (прямоугольник, треугольник, линии, текст, точки подключения);
• установить символ на теле блока (например, R, AVO, PUMP1);
• привязать подписи портов к их сторонам.

Рекомендации по оформлению

• Длина подписей портов — не более 8 символов (например, in, out, cmd, fan). Иначе блок придётся расширять, что нарушит читаемость схемы.
• Символ на теле блока — уникальный и опознаваемый. Лучше использовать ANSI-стандартизованные обозначения для электрических компонентов (R, L, C) и единообразные сокращения для технологических (AVO, PUMP, SEP).
• Точки подключения должны точно совпадать со сторонами, указанными на вкладке «Порты». Алгоритм canvas.jsx распределяет порты по вертикали с шагом 22 px, начиная с HEAD = 22 px смещения от шапки.

11. Шаг 7. Вкладка «Документация» — паспорт компонента

Заполняем информацию

Что здесь задаётся: карточка-паспорт компонента, видимая в палитре, в инспекторе свойств и в режиме просмотра документации. Эти данные не влияют на расчёт, но критичны для повторного использования компонента в проектах, ИСУЛ-сценариях и при коллективной разработке.

Минимальный набор полей

• Поле "Краткое описание". Что можно писать:

• Поле "Внешние зависимости". Здесь необходимо указывать требуемые библиотеки для работы компонента.
• Поле "Связанные компоненты". Указываются компоненты, связанные с описываемым, или рабоающие с ним в связке.
• Поле "Замечания". Что можно писать:

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

Советы

• Заполняйте все ограничения модели — это поможет будущим пользователям избежать ошибочных применений.
• В графе «Источники» указывайте не только ГОСТ, но и конкретные формулы (см. раздел про шпаргалку нелинейных моделей в архитектурном руководстве — там приведены классические соотношения, на которые можно ссылаться).
• Длинные описания допустимо выносить в отдельный PDF/Markdown и прикладывать как адрес в интернете как ссылку на источник.

12. Шаг 8. Контроль готовности и место сохранения

Перед регистрацией выполните финальную проверку:

1. Машинное имя компонента — латиница, без пробелов, уникальное в пределах вашей библиотеки.
2. Список портов соответствует физической топологии.
3. Список параметров содержит все необходимые для формулы идентификаторы.
4. Невязка записана в форме F = 0 (а не присваивания).
5. Флаги установлены корректно: динамика, нелинейность, материальный поток.
6. Глиф не выходит за рамки портов.
7. Паспорт заполнен, ограничения модели указаны.

Выбор папки сохранения

Компоненты публикуются в вашу пользовательскую папку, обычно:

bmk/<domain>/<component_name>/
    ├── <component_name>.py     # код невязки и ComponentSpec
    ├── <component_name>.tex    # документация (паспорт)
    ├── glyph.svg               # внешний вид (опционально)
    └── tests/
        └── test_<component_name>.py  # юнит-тесты (опционально)

13. Шаг 9. Регистрация и проверка появления в БМК

Находим компонент в БМК

По нажатию кнопки «Зарегистрировать» генератор выполняет последовательность операций, описанных в архитектурном руководстве (раздел «Генератор компонентов», шаги 7–11):

1. Сохранение исходников в папку, выбранную на предыдущем шаге. Генерируются:
2. <name>.py — код компонента с ComponentSpec и декоратором @physical;
3. <name>.tex — документация паспорта;
4. glyph.svg — глиф (если был задан);
5. test_<name>.py — заготовка юнит-теста.
6. Вызов регистратора — компилирует код, импортирует модуль и регистрирует блок в реестрах REGISTRY, _RESIDUALS, _PHYSICAL_SPECS. Это возможно без перезапуска сервера (исполняемого приложения ORPHYS).
7. Генерация записи catalog.json с метаданными для палитры.
8. Сборка обновлённого клиентского каталога:
9. Пересборка production-бандла (по необходимости):

1. Запуск автотестов:
2. Визуальная проверка в браузере (ручная): компонент должен появиться в папке палитры, указанной при создании, и перетаскиваться на холст соответствующего слоя.

Как убедиться, что регистрация прошла успешно

• В дереве палитры отображается новая папка/иконка с указанным обозначением.
• В инспекторе свойств все параметры видны с правильными единицами.
• При запуске минимальной пробной схемы с этим компонентом (источник → компонент → сток) расчёт не падает с ошибкой размерности или сингулярности.

14. Частые сценарии настройки невязок

Здесь приведены примеры кода компонентов объектного уровня.

14.1. Простое гидравлическое сопротивление

Линейная потеря давления. Один скаляр невязки ветви.

SPEC = ComponentSpec(
    name="hydraulic_resistor",
    kind="Гидравлическое сопротивление",
    sym="RES",
    body="RES",
    render="block",
    layer="object",
    folder="Гидравлика",
    domain="hydraulic",
    ports=[
        Port("inlet",  dir="in",  side="left",  domain="hydraulic"),
        Port("outlet", dir="out", side="right", domain="hydraulic"),
    ],
    params=[Param("R", 1000.0, unit="Па/(кг/с)")],
)

@physical(SPEC)
def hydraulic_resistor(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    G = I[c["id"]]
    R = float(c["attrs"].get("R", 1000.0))
    return (V[a] - V[b]) - R * G

Поле «Невязки» генератора: P_in - P_out - R * G. Флаги: динамика «нет», нелинейность «нет».

14.2. Гидравлический трубопровод по Хагену — Пуазёйлю

Ламинарный режим:

$$ \Delta P = \frac{128 \mu L G}{\pi \rho d^4} $$

SPEC = ComponentSpec(
    name="laminar_pipe",
    kind="Трубопровод ламинарный",
    layer="object", folder="Гидравлика", domain="hydraulic",
    ports=[
        Port("inlet",  dir="in",  side="left"),
        Port("outlet", dir="out", side="right"),
    ],
    params=[
        Param("L", 100.0, unit="м"),
        Param("d", 0.015, unit="м"),
        Param("rho", 998.0, unit="кг/м³"),
        Param("mu", 1.0e-3, unit="Па·с"),
    ],
)

@physical(SPEC)
def laminar_pipe(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    attrs = c["attrs"]
    G   = float(I[c["id"]])
    L   = float(attrs.get("L", 100.0))
    d   = float(attrs.get("d", 0.015))
    rho = float(attrs.get("rho", 998.0))
    mu  = float(attrs.get("mu", 1.0e-3))
    dp = 128.0 * mu * L * G / (pi * rho * (d ** 4))
    return (V[a] - V[b]) - dp

Поле «Невязки»: P_in - P_out - 128 * mu * L * G / (pi * rho * d**4). Флаги: динамика «нет», нелинейность «нет».

14.3. Гидравлическая ёмкость (diff="nodes")

Ёмкость с накоплением среды; поток ветви выражается через производную давления.

SPEC_CAPACITY = ComponentSpec(
    name="hydraulic_capacity",
    kind="Гидравлическая емкость",
    layer="object", folder="Гидравлика", domain="hydraulic",
    ports=[
        Port("a", dir="in",  side="left"),
        Port("b", dir="out", side="right"),
    ],
    params=[Param("C_h", 1.0e-5, unit="кг·с²/м⁵")],
)

@physical(SPEC_CAPACITY, diff="nodes")
def hydraulic_capacity(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    G = I[c["id"]]
    C_h = float(c["attrs"].get("C_h", 1.0e-5))
    return G - C_h * (dV[a] - dV[b])

Поле «Невязки»: G - C_h * (dP_in_dt - dP_out_dt). Флаг: дифф. переменная «по узлам».

14.4. Гидравлическая инерционность (diff="branch")

Инерционность столба жидкости в трубе.

SPEC_INERTANCE = ComponentSpec(
    name="hydraulic_inertance",
    kind="Гидравлическая инерционность",
    layer="object", folder="Гидравлика", domain="hydraulic",
    ports=[
        Port("a", dir="in",  side="left"),
        Port("b", dir="out", side="right"),
    ],
    params=[Param("L_h", 100.0, unit="кг/м⁴")],
)

@physical(SPEC_INERTANCE, diff="branch")
def hydraulic_inertance(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    L_h = float(c["attrs"].get("L_h", 100.0))
    return (V[a] - V[b]) - L_h * dI[c["id"]]

Поле «Невязки»: P_in - P_out - L_h * dG_dt. Флаг: дифф. переменная «по ветви».

14.5. Аппарат с внутренним состоянием фильтрации

Ёмкость с диагностикой давления; добавляется дифференциальное состояние Pf и алгебраическое alarm.

SPEC = ComponentSpec(
    name="smart_vessel",
    kind="Ёмкость с диагностикой",
    layer="object", folder="Технологические аппараты",
    ports=[Port("a", dir="in"), Port("b", dir="out")],
    params=[
        Param("V",     2.0,    unit="м³"),
        Param("T",     300.0,  unit="К"),
        Param("Rs",    287.0,  unit="Дж/(кг·К)"),
        Param("tau",   20.0,   unit="с"),
        Param("P_set", 40000.0, unit="Па"),
    ],
)

@physical(SPEC, diff="nodes", states=[("Pf", "diff"), ("alarm", "alg")])
def smart_vessel(elem):
    a, b   = elem.port("a"), elem.port("b")
    V      = elem.param("V", 2.0)
    T      = elem.param("T", 300.0)
    Rs     = elem.param("Rs", 287.0)
    tau    = elem.param("tau", 20.0)
    P_set  = elem.param("P_set", 0.0)
    Pf     = elem.state("Pf", 0.0)
    d_Pf   = elem.d_state("Pf")
    alarm  = elem.state("alarm", 0.0)
    Ch = V / (Rs * T)
    return [
        a.flow - Ch * (a.d_potential - b.d_potential),
        d_Pf   - (a.potential - Pf) / tau,
        alarm  - (Pf - P_set),
    ]

Поле «Невязки» генератора заполняется тремя строками. Состояния объявляются на вкладке «Параметры», секция «Дифференцируемые параметры».

14.6. Нефтегазовое сопротивление (StreamProfile)

from mars_core.stream_profile import StreamProfile

SPEC_OG = ComponentSpec(
    name="oilgas_linear_resistance",
    kind="Технологическое сопротивление смеси",
    layer="object", folder="Нефтегазовые аппараты", domain="oilgas",
    supports_stream=True,
    stream_role="resistance",
    ports=[Port("inlet", dir="in"), Port("outlet", dir="out")],
    params=[Param("R", 1000.0, unit="Па/(кг/с)")],
)

@physical(
    SPEC_OG,
    stream=StreamProfile.flow_through("inlet", "outlet", allow_reverse=True),
    publish=lambda c, V, I, t, S: {
        "flow_kgs": float(I[c["id"]]),
        "dp_pa":    float(V[c["nodes"][0]] - V[c["nodes"][1]]),
    },
)
def oilgas_linear_resistance(c, V, I, dV, dI, t, lam):
    a, b = c["nodes"]
    return (V[a] - V[b]) - float(c["attrs"].get("R", 1000.0)) * I[c["id"]]

На вкладке «Параметры» в секции «Тепловая модель» выбирается пресет flow_through.

14.7. Многопортовый аппарат (тройник)

Идеальный гидравлический тройник с тремя независимыми потоками:

_PORTS = ("p1", "p2", "p3")
_DIRS  = ("in", "out", "out")
_MULTI = True

def _body(elem):
    p1, p2, p3 = elem.port("p1"), elem.port("p2"), elem.port("p3")
    return [
        p1.potential - p2.potential,
        p1.potential - p3.potential,
        p1.flow + p2.flow + p3.flow,
    ]

@physical(SPEC_TEE, ports=3)
def hydraulic_tee(c, V, I, dV, dI, t, lam):
    return _body(Elem(c, V, I, dV, dI, t, lam, _PORTS, _DIRS, _MULTI))

Поле «Невязки» генератора содержит три строки; количество уравнений = числу портов. Галочка «Независимые расходы портов» установлена.

15. Типичные ошибки и их диагностика

16. Приёмочные испытания после регистрации

После того как компонент зарегистрирован, до передачи его другим пользователям имеет смысл выполнить серию проверок. Это требование совпадает с «Методикой проверки и изолированного тестирования» из архитектурного руководства.

16.1. Проверка автоматической регистрации в реестрах ядра

import mars_core.component_host
from mars_core.acausal import _PHYSICAL_SPECS, _RESIDUALS

assert "hydraulic_resistor" in _PHYSICAL_SPECS
assert "hydraulic_resistor" in _RESIDUALS

Если одно из утверждений падает, декоратор @physical не сработал. Самая частая причина — синтаксическая ошибка в сгенерированном .py файле или отсутствие импорта модуля.

16.2. Численное базовое тестирование невязки

Подставьте искусственные словари V и I, при которых уравнение аналитически выполняется, и проверьте близость невязки к нулю:

c = {"id": "p1", "nodes": [1, 2],
     "attrs": {"L": 100.0, "d": 0.015, "rho": 998.0, "mu": 1e-3}}
V = {1: 150000.0, 2: 100000.0}  # ΔP = 50 000 Па

# Аналитическое решение для ламинарного течения:
G_exact = 50000.0 * pi * 998.0 * (0.015 ** 4) / (128 * 1e-3 * 100.0)

res = laminar_pipe(c, V, {"p1": G_exact}, {}, {}, 0.0, 1.0)
assert abs(res) < 1e-9, f"Невязка должна быть ≈ 0, получено {res}"

16.3. Интеграционный тест на схеме

Соберите минимальную проверочную схему (по образцу из архитектурного руководства):

Источник FEED → [Ваш компонент] → Приёмник SINK

Запустите расчёт в статике (DC) и убедитесь:

• расчёт завершается без ошибок;
• баланс расходов сходится с точностью не хуже относительной погрешности Ньютона (tol ≈ 1e-9 по умолчанию);
• на графике метрик отображается физически адекватная траектория (без скачков, монотонная там, где ожидается).

Затем запустите расчёт в переходном режиме (Transient) и убедитесь в отсутствии осцилляций, вызванных численной неустойчивостью.

16.4. Регрессионное тестирование в pytest

Поместите тесты в tests/test_<имя_компонента>.py для запуска в CI/CD. Тесты должны покрывать:

• успешную регистрацию (_PHYSICAL_SPECS);
• аналитический баланс при известных значениях;
• реакцию на переключение режимов (diff, nonlinear).

17. Управление жизненным циклом: обновление и удаление

Обновление значений параметров по умолчанию

Изменения значений по умолчанию безопасны: они влияют только на вновь размещаемые блоки. Уже размещённые блоки хранят свои значения в attrs каждого экземпляра.

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

Если переименование неизбежно:

1. Добавьте новое имя как алиас, оставив старое в ComponentSpec (через «совместимое имя» — поддерживается в новых версиях SDK);
2. Обновите все проекты через миграционный скрипт;
3. Только после этого удаляйте старое имя.

Изменение количества портов

Добавление нового порта — относительно безопасная операция, если:

• новый порт опционален и совместим со старой топологией;
• существующие подключения продолжают работать без правки формулы.

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

Удаление компонента из библиотеки

1. Удалите файлы из bmk/<component>/.
2. Запустите среду моделирования.
3. Убедитесь, что все активные проекты больше не содержат экземпляров компонента (иначе — ошибка валидатора при загрузке).
4. При наличии опубликованных проектов выполните миграцию на заменяющий компонент.

18. Краткая шпаргалка

18.1. Минимальный обязательный набор полей в генераторе

Порты       — минимум 1 порт (in / out)
Параметры   — минимум один числовой параметр (или без них)
Невязки     — формула в форме F = 0
Код         — пусто (генератор сам подставит return)
Внешний вид — пусто (стандартный прямоугольник)
Документация     — хотя бы краткое описание назначения

18.2. Эквивалент «вкладка ↔ код»

18.3. Соответствие «шаг генератора ↔ раздел архитектуры»

• Шаги 2–3 (порты и параметры) → раздел «Описание дескриптора ComponentSpec».
• Шаг 4 (невязки) → разделы «Прямой @physical», «Elem», register_component.
• Шаг 4 (флаги) → «Динамические компоненты», «Нелинейные физические компоненты», «Многопортовые компоненты», «Материальные потоки».
• Шаг 5 (код) → «Высокопроизводительный C++ SDK» (при необходимости расширения на C++).
• Шаги 8–9 (контроль и регистрация) → «Двухуровневая природа регистрации».
• Шаг 16 (приёмочные испытания) → «Методика проверки и изолированного тестирования» и «Сводная матрица типичных ошибок».

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

Полный каталог паспортов компонентов среды моделирования ORPHYS с описанием назначения, портов, параметров, математической модели и алгоритма работы. Поиск работает по Ctrl+K (глобальный) и по полю «Поиск компонента» (локально).