Engee Physics Modeling Language Equations

Page in progress.

Declaring Equations

The equations the physical component is declared using the construct @equations. The tilde is used as the equality symbol. ~.

@equations begin
    x ~ y * z
    y ~ 2 * t
end

Here t — this is a time variable, always measured in seconds.

All numbers used in explicit equations are considered dimensionless (in the SI system).

For more information about complex cases, including conditional equations and branching, see the article Enumerations, branches, loops, and modules of the Engee Physics Modeling language.

Vector equations

The equations can also be set in vector form, when entire arrays are equated at once. For more information, see the article Enumerations, branches, loops, and modules of the Engee Physics Modeling language.

Time derivatives

To set time derivatives, the function is used der(…). For example:

@equations begin
    der(x) ~ y
end

Here der(x) denotes the derivative of a variable x by time t.

Interpolation and extrapolation

For tabular interpolation and extrapolation, the function is used tablelookup with multiple methods:

tablelookup(x_vector::Vector, y_vector::Vector, x, interpolation, extrapolation) — 1D interpolation;
tablelookup(x1_vector::Vector, x2_vector::Vector, y_matrix::Matrix, x1, x2, interpolation, extrapolation) — 2D interpolation;
tablelookup(x1_vector::Vector, x2_vector::Vector, x3_vector::Vector, y_3d_array::Array, x1, x2, x3, interpolation, extrapolation) — 3D interpolation.

Supported modes:

interpolation:
- "linear" — piecewise linear;
- "smooth" — piecewise cubic modified interpolation of Akim.
extrapolation:
- "linear" — linear (at the two extreme points for "linear", tangent to the extreme polynomial for "smooth");
- "nearest" — at the nearest extreme value.

Arguments other than interpolation and extrapolation they can be either symbolic or non-symbolic. It is acceptable to set the first group as non-symbolic (with array arguments x_vector, …, y_3d_array), and the second one in characters (x, x1, x2, x3).

Checks

Condition checks are performed by the function assert(condition, message, action) inside the structure @equations:

@parameters begin
    a = 1
    assert_action::AssertAction = AssertAction.error
end
@equations begin
    assert(a>0, "This is error.", assert_action)
end

Usage formats:

assert(x>0) — a routine check, in case of violation, the calculation will stop;
assert(x>0, "Error") — with the specified error message;
assert(x>0, "", AssertAction.none) — no text, only the action is set.

action it can be a symbolic parameter and take values:

AssertAction.none — do nothing;
AssertAction.error — stop the calculation (by default).

Features:

If the check contains only numbers and parameters, it is performed once when the simulation is started.;
If there is at least one variable, it is checked at each step of the simulation (with the Run—time assertions option enabled in the block Solver Configuration).

For compound conditions, the operators || and && they only work without ports and variables. If there are any, you should use | and &.

Connections

To connect sub-components and ports the function is used connect, which , with symbolic transformations , is conditionally equivalent to two groups of equations:

Equating potential variables of connected ports;
The sum of the stream variables of the connected ports is equal to zero.

@components begin
    resistor = EngeePhysicalFoundation.Electrical.Elements.Resistor()
    capacitor = EngeePhysicalFoundation.Electrical.Elements.Capacitor()
    reference = EngeePhysicalFoundation.Electrical.Elements.Reference()
end

@equations begin
    connect(resistor.p, capacitor.n)
    connect(capacitor.p, resistor.n, reference.pin)
end

If you use the function connect with an argument *, then the potential variables in the port will be 0.

@engeemodel ground begin
    @nodes begin
        pin = EngeePhysicalFoundation.Electrical.Pin
    end
    @equations begin
        connect(pin, *)
    end
end

In addition to the equations, the parameters of the connected ports are also equated.

Using * in branches

Branches defined in the construction @branches, associate the variables of the physical component with the stream variables of the ports and define the topology of the streams within the model. Symbol * it is used to indicate that the stream variable does not connect to other ports. Example:

@engeemodel FloatingReference begin
    @nodes begin
        p = EngeePhysicalFoundation.Electrical.Pin
        n = EngeePhysicalFoundation.Electrical.Pin
        out = EngeePhysicalFoundation.Electrical.Pin
    end
    @variables [access = Private] begin
        i_input = 0, [unit = "A", description = "Input current"]
    end
    @variables begin
        i_output = 0, [unit = "A", description = "Current into output node"]
    end
    @branches begin
        i_input:(p.i, n.i) # the i_input current flows between ports p and n
        i_output:(out.i, *) # the i_output current flows into the out port without connecting anywhere on the other side
    end
end

Here:

i_input:(p.i, n.i) — indicates that the variable i_input corresponds to the flow from the port p to the port n;
i_output:(out.i, *) — indicates that the current i_output flowing into the port out, but it does not have a paired short-circuit port.

Distribution of port parameters

To distribute the parameters between the ports inside the component, the function is used domain_connect:

@equations begin
    domain_connect(port_a, port_b)
end

This function equates parameters between ports, but does not affect port variables (unlike connect). If neither connect, neither domain_connect If they are not set, the parameters in the ports will remain different.