Metadata of the Engee Physical Modeling Language

Page in progress.

Metadata in the Engee physical modeling language is used to describe the properties of parameters, variables, nodes, and other entities within physical component.

They do not directly affect mathematical equations, but they determine:

Units of measurement;
Text descriptions;
Display rules in the interface;
Grouping in the block settings window;
Priorities;
Access.

Therefore, metadata helps to make the component understandable and user-friendly in Engee.

Metadata syntax

Metadata is specified in square brackets after the name of a parameter, variable, or other construct. You can specify multiple fields at the same time.

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

In this example:

[group = "Parameters"] — metadata for the entire structure @parameters. They define that all the parameters inside this construct will be grouped in an interface called Parameters.
[unit = "Ohm", description = "Resistance"] — metadata for a specific parameter R. The unit of measurement is indicated here (Ohm) and the description (Resistance).
[unit = "V", description = "Voltage"] — metadata for a specific parameter v. The unit of measurement is indicated here (V) and the description (Voltage).

Thus, metadata can be set both at the level of the entire structure and for individual elements.

Units of measurement

Units of measurement are set as metadata unit and apply equally to @parameters and @variables.

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

Here:

R set in ohms;
v — in volts;
i — in amperes.

Metadata keys and their purpose

The table below provides a list of supported metadata keys, their purpose, acceptable values, and usage examples.

Key Appointment Acceptable values Example

Key	Appointment	Acceptable values	Example
`unit`	Units of measurement. Supported designs: `@parameters` `@structural_parameters` `@variables` `@intermediates`	A string indicating the unit of measurement (for example, `"Ohm"`, `"V"`, `"A"`, `"N*m"`).	`R = 1.0, [unit = "Ohm"]`
`description`	The text description of the element. Supported designs: `@parameters` `@structural_parameters` `@variables`	Line.	`i = 0.0, [unit = "A", description = "Current through element"]`
`group`	Grouping parameters/variables in the interface. Supported designs: `@parameters` `@structural_parameters` `@variables`	Line. By default: `"Parameters"` — for parameters; `"Initial Targets"` — for the initial values of the variables.	`@parameters [group = "Model parameters"] begin a = 1.0 end`
`tab`	Placing the item on a separate tab in the interface. Supported designs: `@parameters` `@structural_parameters` `@variables`	Line. By default `"Main"`.	`R = 1.0, [tab = "Main"]`
`priority`	The priority of the variable used during initialization. Supported designs: `@variables`	`"high"`, `"low"`, `"none"` (by default).	`v_C = 0.0, [unit = "V", priority = "high"]`
`gui`	Manage visibility and editing in the interface. Supported designs: `@nodes` `@inputs` `@outputs` `@components` `@parameters` `@structural_parameters` `@variables` `@intermediates`	`Modify` (default) — the value can be set and is displayed when recording; `Observe` — you can see recorded the value after the model has worked; `None` — hide any mention in the interface. For `access = Public` by default `gui = Modify`, for `access = Private` by default `gui = Observe`.	`debug_var = 0.0, [gui = Observe]`
`access`	Access level (determines whether a variable is accessible from the outside). Supported designs: `@nodes` `@inputs` `@outputs` `@components` `@parameters` `@structural_parameters` `@variables` `@intermediates`	If the construction is declared inside the conditions `if/elseif/else`, then the default will be `Private` without the ability to change to `Public`. Otherwise, the default is applied `Public`.	`internal = 0.0, [access = Private]`
`event`	Marking a variable as discrete event-driven. Supported designs: `@variables`	`true` or `false`. By default `false`.	`counter = 0, [event = true]`
`connect`	Defines the role of a variable in port connections. Supported designs: `@variables` inside `@engeeconnector`	`Flow` — stream variable (sum = 0 in all connected ports). If not specified, the variable is considered potential (the values are equal in all connected ports).	`@engeeconnector Pin2 begin @variables begin v = 2.0 # potential (potential variable) i = 0.0, [connect = Flow] # current (flow variable) end end`
`view`	The appearance of the port. Supported designs: `@nodes` `@inputs` `@outputs`	`Tuple` with two lines, for example `("A", "left")`: By signing the port on the block Signature position `"left"` / `"right"` / `"top"` / `"bottom"`. By default `("", "top")` in this case, the ports are located equidistant on each side. You can also set the visual representation of the port in more detail.: `label` — port signature (string); `side` — position of the signature (`"left"` / `"right"`/ `"top"` /`"bottom"`); `position` — the position of the port along the border of the block (relative number from 0 to 1); `offset` — offset of the signature along the block boundary (number); `sub_offset` — offset of the signature from the block boundary (number).	`pin, [view = ("A","left")]` `port = EngeePhysicalFoundation.Electrical.Pin, [ label="n4", side="left", position=0.15, offset=-3, sub_offset=2, ]`

unit

Units of measurement.

Supported designs:

@parameters
@structural_parameters
@variables
@intermediates

A string indicating the unit of measurement (for example, "Ohm", "V", "A", "N*m").

R = 1.0, [unit = "Ohm"]

description

The text description of the element.

Supported designs:

@parameters
@structural_parameters
@variables

Line.

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

group

Grouping parameters/variables in the interface.

Supported designs:

@parameters
@structural_parameters
@variables

Line. By default:

"Parameters" — for parameters;
"Initial Targets" — for the initial values of the variables.

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

tab

Placing the item on a separate tab in the interface.

Supported designs:

@parameters
@structural_parameters
@variables

Line. By default "Main".

R = 1.0, [tab = "Main"]

priority

The priority of the variable used during initialization.

Supported designs:

@variables

"high", "low", "none" (by default).

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

gui

Manage visibility and editing in the interface.

Supported designs:

@nodes
@inputs
@outputs
@components
@parameters
@structural_parameters
@variables
@intermediates

Modify (default) — the value can be set and is displayed when recording;
Observe — you can see recorded the value after the model has worked;
None — hide any mention in the interface.

For access = Public by default gui = Modify, for access = Private by default gui = Observe.

debug_var = 0.0, [gui = Observe]

access

Access level (determines whether a variable is accessible from the outside).

Supported designs:

@nodes
@inputs
@outputs
@components
@parameters
@structural_parameters
@variables
@intermediates

If the construction is declared inside the conditions if/elseif/else, then the default will be Private without the ability to change to Public. Otherwise, the default is applied Public.

internal = 0.0, [access = Private]

event

Marking a variable as discrete event-driven.

Supported designs:

@variables

true or false. By default false.

counter = 0, [event = true]

connect

Defines the role of a variable in port connections.

Supported designs:

@variables inside @engeeconnector

Flow — stream variable (sum = 0 in all connected ports).
If not specified, the variable is considered potential (the values are equal in all connected ports).

@engeeconnector Pin2 begin
    @variables begin
        v = 2.0 # potential (potential variable)
        i = 0.0, [connect = Flow]  # current (flow variable)
    end
end

view

The appearance of the port.

Supported designs:

@nodes
@inputs
@outputs

Tuple with two lines, for example ("A", "left"):

By signing the port on the block
Signature position "left" / "right" / "top" / "bottom".

By default ("", "top") in this case, the ports are located equidistant on each side.

You can also set the visual representation of the port in more detail.:

label — port signature (string);
side — position of the signature ("left" / "right"/ "top" /"bottom");
position — the position of the port along the border of the block (relative number from 0 to 1);
offset — offset of the signature along the block boundary (number);
sub_offset — offset of the signature from the block boundary (number).

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

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

Features of working with metadata

Metadata can be set for the entire structure, as well as for individual elements. Individual metadata takes precedence. For example:
```
@parameters [group = "Main", gui = Modify] begin
    R = 1.0, [unit = "Ohm", group = "Electrical"]
    debug_param = 0.0, [gui = Observe]
end
```
Here for the parameter R the group will be used "Electrical" instead of inherited "Main", and for debug_param — display mode Observe instead of inherited Modify.

Metadata priority and unit can be passed when creating a sub-component:

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

If the metadata is not explicitly specified, the default values specified in the component are applied.
Metadata gui you can change it conditionally using the construction @annotations:
```
@parameters begin
    a::Bool = true
    b = 1, [gui = None]
end

if a
    @annotations begin
        b, [gui = Modify]
    end
end
```
In this example, the metadata behavior depends on the parameter value. a:
- If a = false, then the parameter b hidden in the interface (gui = None),
- If a = true, then the parameter b displayed (gui = Modify).

Metadata of the Engee Physical Modeling Language

Metadata syntax

Units of measurement

Metadata keys and their purpose

Features of working with metadata

Useful links