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

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

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

Смотрите также:
Physical Modeling
Обзор конструкций декларативного языка Engee

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

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

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

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

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

  • Группировку элементов;

  • Приоритеты, доступ и видимость.

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

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

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

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

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

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

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

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

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

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

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

unit

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

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

 
R = 1.0, [unit = "Ohm"]

description

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

Любая строка.

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

group

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

Строка. Часто используются:

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

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

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

tab

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

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

 
R = 1.0, [tab = "Main"]

priority

Приоритет отображения и использования значений. Может влиять на то, какое значение используется при инициализации.

"high", "low", "none". (В старых версиях — целое число).

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

gui

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

  • Modify — можно задавать значение;

  • Observe — только наблюдать;

  • none — скрыть из GUI.

Если access = Private, то по умолчанию gui = Observe.

 
debug_var = 0.0, [gui = Observe]

access

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

Public, Protected, Private.

 
internal = 0.0, [access = Private]

event

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

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

 
counter = 0, [event = true]

connect

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

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

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

 
@engeeconnector Pin begin
    v                     # потенциал
    i, [connect = Flow]   # ток
end

view

Настройка отображения переменной в GUI. Можно использовать простые строки или детальные Tuple.

Строка ("left", "right", "top", "bottom") или Tuple с параметрами.

 
gain = 1.0, [view = "slider"]

pin, [view = ("A","left")]

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

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

    @parameters [key1 = value1, key2 = value2] begin
    a = b, [key1 = value3]
    c = d, [key2 = value4]
end

    Здесь для a будет использоваться key1 = value3, а для c — key2 = value4, даже несмотря на то, что у конструкции заданы другие значения.

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

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

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

  • Метаданные gui можно изменять условно:

    @parameters begin
    a::Bool = true
    b = 1
end

if a
    @annotations begin
        b, [gui = none]
    end
else
    @annotations begin
        b, [gui = Observe]
    end
end

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

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

  • Если a = false, то параметр b отображается для наблюдения (gui = Observe).

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

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

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