Документация Engee

Метаданные языка физического моделирования Engee

Страница в процессе разработки.

Смотрите также:
Physical Modeling
Конструкции языка физического моделирования Engee
Переменные языка физического моделирования Engee

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

Они не влияют на математические уравнения напрямую, но определяют:

  • Единицы измерения;

  • Текстовые описания;

  • Правила отображения в интерфейсе;

  • Группировку в окне настроек блока;

  • Приоритеты;

  • Доступ.

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

Синтаксис метаданных

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

@parameters [group = "Parameters"] begin
    R = 1.0, [unit = "Ohm", description = "Resistance"]
    v = 5.0, [unit = "V", description = "Voltage"]
end

В этом примере:

  • [group = "Parameters"] — метаданные для всей конструкции @parameters. Они определяют, что все параметры внутри этой конструкции будут сгруппированы в интерфейсе под названием Parameters.

  • [unit = "Ohm", description = "Resistance"] — метаданные для конкретного параметра R. Здесь указана единица измерения (Ohm) и описание (Resistance).

  • [unit = "V", description = "Voltage"] — метаданные для конкретного параметра v. Здесь указаны единица измерения (V) и описание (Voltage).

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

Единицы измерения

Единицы измерения задаются как метаданные unit и одинаково применяются к @parameters и @variables.

@parameters begin
    R = 1.0, [unit = "Ohm"]
end
@variables begin
    i = 0.0, [unit = "A"]
    v = 0.0, [unit = "V"]
end

Здесь:

  • R задан в омах;

  • v — в вольтах;

  • i — в амперах.

Ключи метаданных и их назначение

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

Ключ Назначение Допустимые значения Пример

unit

Единицы измерения.

Поддерживаемые конструкции:

  • @parameters

  • @structural_parameters

  • @variables

  • @intermediates

Строка с обозначением единицы измерения (например, "Ohm", "V", "A", "N*m").

 
R = 1.0, [unit = "Ohm"]

description

Текстовое описание элемента.

Поддерживаемые конструкции:

  • @parameters

  • @structural_parameters

  • @variables

Строка.

 
i = 0.0, [unit = "A", description = "Current through element"]

group

Объединение параметров/переменных в группы в интерфейсе.

Поддерживаемые конструкции:

  • @parameters

  • @structural_parameters

  • @variables

Строка. По умолчанию:

  • "Parameters" — для параметров;

  • "Initial Targets" — для начальных значений переменных.

 
@parameters [group = "Model parameters"] begin
    a = 1.0
end

tab

Размещение элемента на отдельной вкладке в интерфейсе.

Поддерживаемые конструкции:

  • @parameters

  • @structural_parameters

  • @variables

Строка. По умолчанию "Main".

 
R = 1.0, [tab = "Main"]

priority

Приоритет переменной, используемый при инициализации.

Поддерживаемые конструкции:

  • @variables

"high", "low", "none" (по умолчанию).

 
v_C = 0.0, [unit = "V", priority = "high"]

gui

Управление видимостью и редактированием в интерфейсе.

Поддерживаемые конструкции:

  • @nodes

  • @inputs

  • @outputs

  • @components

  • @parameters

  • @structural_parameters

  • @variables

  • @intermediates

  • Modify (по умолчанию) — можно задавать значение и отображается при записи;

  • Observe — можно увидеть записанное signal logging 1 значение после того, как модель отработала;

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

Для access = Public по умолчанию gui = Modify, для access = Private по умолчанию gui = Observe.

 
debug_var = 0.0, [gui = Observe]

access

Уровень доступа (определяет доступна ли переменная извне).

Поддерживаемые конструкции:

  • @nodes

  • @inputs

  • @outputs

  • @components

  • @parameters

  • @structural_parameters

  • @variables

  • @intermediates

Если конструкция объявляется внутри условий if/elseif/else, то по умолчанию будет Private без возможности изменить на Public. В противном случае по умолчанию применяется Public.

 
internal = 0.0, [access = Private]

event

Пометка переменной как дискретной событийной.

Поддерживаемые конструкции:

  • @variables

true или false. По умолчанию false.

 
counter = 0, [event = true]

connect

Определяет роль переменной в соединениях портов.

Поддерживаемые конструкции:

  • @variables внутри @engeeconnector

  • Flow — потоковая переменная (сумма = 0 во всех соединённых портах).

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

 
@engeeconnector Pin2 begin
    @variables begin
        v = 2.0                    # потенциал (потенциальная переменная)
        i = 0.0, [connect = Flow]  # ток (потоковая переменная)
    end
end

view

Внешний вид порта.

Поддерживаемые конструкции:

  • @nodes

  • @inputs

  • @outputs

Tuple с двумя строками, например ("А", "left"):

  • Подписью порта на блоке

  • Положение подписи "left" / "right" / "top" / "bottom".

По умолчанию ("", "top"), при этом порты располагаются на каждой стороне равноудаленно.

Также можно задать визуальное отображение порта более детально:

  • label — подпись порта (строка);

  • side — положение подписи ("left" / "right"/ "top" /"bottom");

  • position — положение порта вдоль границы блока (относительное число от 0 до 1);

  • offset — смещение подписи вдоль границы блока (число);

  • sub_offset — смещение подписи от границы блока (число).

 
pin, [view = ("A","left")]
port = EngeePhysicalFoundation.Electrical.Pin, [
    label="n4",
    side="left",
    position=0.15,
    offset=-3,
    sub_offset=2,
]

Особенности работы с метаданными

  • Метаданные можно задавать как для всей конструкции, так и для отдельных элементов. Индивидуальные метаданные имеют приоритет. Например:

    @parameters [group = "Main", gui = Modify] begin
    R = 1.0, [unit = "Ohm", group = "Electrical"]
    debug_param = 0.0, [gui = Observe]
end

    Здесь для параметра R будет использоваться группа "Electrical" вместо унаследованной "Main", а для debug_param — режим отображения Observe вместо унаследованного Modify.

  • Метаданные priority и unit можно передавать при создании подкомпонента:

    @components begin
    custom = CustomComponent(a = (value = 10, unit = "kg/s", priority = "high"), c = 20)
end

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

  • Метаданные gui можно изменять условно, используя конструкцию @annotations:

    @parameters begin
    a::Bool = true
    b = 1, [gui = None]
end

if a
    @annotations begin
        b, [gui = Modify]
    end
end

    В этом примере поведение метаданных зависит от значения параметра a:

    • Если a = false, то параметр b скрывается в интерфейсе (gui = None),

    • Если a = true, то параметр b отображается (gui = Modify).

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

  1. Создание физического компонента

  2. Синтаксис языка физического моделирования Engee

  3. Переменные языка физического моделирования Engee

  4. Порты языка физического моделирования Engee

  5. Настройка физических блоков с помощью целевых значений