Engee documentation

Constructions of the Engee physical Modeling language

Page in progress.

See also:
Creating a physical component
Physical Modeling

In the physical modeling language Engee component is described by a set of block structures of the form @…​ begin … end. Constructs define parameters, variables, equations, ports, branches, annotations, and other structure of the future component. Below is an overview of the main language constructs and the key methods used within them.

Basic constructions

Construction Appointment Example

@parameters

The parameters of the component that are set before launch.

 
@parameters begin
    R = 1.0, [unit = "Ohm"]
end

@variables

Variables calculated during the simulation.

 
@variables begin
    v = 0.0, [unit = "V"]
end

@equations

Equations describing behavior.

 
@equations begin
    v ~ R * i
end

@nodes

Connection ports to physical domains.

 
@nodes begin
    p = EngeePhysicalFoundation.Electrical.Pin
    n = EngeePhysicalFoundation.Electrical.Pin
end

@branches

Binds the stream(s) of multiple ports to a common variable.

 
@branches begin
    i:(p.i, n.i)
end

@components

Sub-components (hierarchy within the model).

 
@components begin
    cap = EngeePhysicalFoundation.Electrical.Elements.Capacitor()
end

@structural_parameters

Non-symbolic parameters. They are usually used for indexes and dimensions of arrays.

 
@structural_parameters begin
    N::Int = 3
end

@intermediates

Intermediate variables that simplify expressions in equations.

 
@intermediates begin
    power = v*i
end

@inputs

Input variables.

 
@inputs begin
    u_in = 0.0
end

@outputs

Output variables.

 
@outputs begin
    y_out = 0.0
end

@annotations

Changing metadata of parameters, variables, ports, and sub-components.

 
@annotations begin
    (v, i), [gui = None]
end

@icon

The appearance of the block icon.

 
@icon begin
    "icon.svg"
end

@extend

Inheritance from an existing component.

 
@engeemodel MyResistor begin
    @extend Resistor
end

Metadata

Using metadata, you can set units of measurement, groups, priorities, visibility in the interface, etc. For more information, see the article Metadata of the Engee Physical Modeling Language.

Special functions for constructions with equations

  • assert(condition [, message [, action]]) — checks.

    @equations begin
    assert(R >= 0.0)
end

  • connect(a, b, …​) — connection of ports and sub-components.

    connect(R1.p, R2.n)

  • domain_connect(a, b) — synchronization of environment parameters between ports within the same component (port variables are not connected).

    @equations begin
    domain_connect(n, p)
end

Rules of operation of structures

  • All designs are designed as @name begin …​ end.

  • The order of the structures inside the physical component (in the code after @engeemodel) it doesn’t matter — the language is declarative.

    For example, a variable can be used in an equation even before it is explicitly declared.:

    @engeemodel Example begin
    @equations begin
        y ~ x^2 +1 # we use x, although it is declared below
    end
    @variables begin
        x = 0
        y = 0
    end
end

  • There may be several structures of the same type in one physical component (for example, several blocks @equations).

  • Constructions can be provided with metadata (for example, group = "Parameters"), which apply to all objects declared in this construct. For example:

    @parameters [group = "Electrical Parameters"] begin
    R = 1.0, [unit = "Ohm", description = "Resistance"]
    v_nom = 230.0, [unit = "V", description = "Nominal voltage"]
end

    In this example, both parameters will be displayed in the group. "Electrical Parameters".

  • The visibility of parameters, variables, ports, and sub-components can be changed depending on the parameter values inside the conditions using the block @annotations. For example:

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

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

    In this example, the behavior of metadata depends on the value of the parameter. a:

    • If a = false, then the parameter b hidden in the interface (gui = None),

    • If a = true, then the parameter b displayed (gui = Modify).

  1. Syntax of the Engee Physical Modeling language

  2. Creating a physical component