Метаданные языка физического моделирования 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` — можно увидеть записанное значение после того, как модель отработала; `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, ]`

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 — можно увидеть записанное значение после того, как модель отработала;
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).

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

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

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

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

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

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