Sub-components and inheritance of the Engee Physics modeling language

This article discusses how the Engee physical modeling language can be used to build more complex models by assembling them from sub-components. This mechanism allows you to organize a hierarchy of elements, make models reusable and more compact.

Inheritance of components

Sometimes a new component is very similar to an existing one, and it makes no sense to rewrite the entire component. To do this, the Engee physical modeling language uses the construction @extend, which allows you to inherit variables and equations from another physical component.

@extend Branch
@extend Branch(i = 0)

All parameters/variables/sub-components with access=Public from Branch they will be automatically visible in the inherited component.

To apply @extend it is allowed only once inside one component.

@engeemodel Branch begin
    @nodes begin
        p = EngeePhysicalFoundation.Electrical.Pin, [label="+", side="left"]
        n = EngeePhysicalFoundation.Electrical.Pin, [label="−", side="right"]
    end
    @variables begin
        i = 0, [unit="A", description="Current"]
        v = 0, [unit="V", description="Voltage"]
    end
    @branches begin
        i: (p.i, n.i)
    end
    @equations begin
        v ~ p.v - n.v
        domain_connect(n, p)
    end
end

@engeemodel Resistor begin
    @extend Branch
    @parameters begin
        R = 1, [unit="Ohm", description="Resistance"]
    end
    @intermediates begin
        power_dissipated = R * i^2
    end
    @equations begin
        assert(R > 0.0)
        v ~ R * i
    end
end

@engeemodel Capacitor begin
    @extend Branch
    @parameters begin
        C = 1e-6, [unit="F", description="Capacitance"]
    end
    @equations begin
        assert(C > 0.0)
        i ~ C * der(v)
    end
end

@engeemodel Inductor begin
    @extend Branch
    @parameters begin
        L = 1e-6, [unit="H", description="Inductance"]
    end
    @equations begin
        assert(L > 0.0)
        v ~ L * der(i)
    end
end

In the example above, the component is declared Branch with a description of ports, variables, branches, and equations, and in components Resistor, Capacitor, Inductor all content is inherited Branch using the construction @extend and they are supplemented with parameters and equations specific to each component.

Sub-components

Sub-components are common physical components that can be embedded inside other physical components. They are created using the construction @components.

@components begin
    diode     = EngeePhysicalFoundation.Electrical.Elements.PieceWiseLinearDiode(v_forward = 0.6, R_on = 0.3, G_off = 1e-8)
    capacitor = EngeePhysicalFoundation.Electrical.Elements.Capacitor(C = 1e-4)
end

Here, two sub-components have been added to the new component: a diode and a capacitor. In the arguments of the sub-component constructor, you can immediately set the parameters (v_forward, R_on, C and so on).

An example of transmitting values

You can use the parameters of the main component as the parameter values of the subcomponents, but you do not need to specify the units of measurement.

@engeemodel A begin
    @variables begin
        a = 1
        b[:] = [1, 2]
    end
    @parameters begin
        c = 3
        d[:] = [3, 4]
    end
    @equations begin
        a^2 ~ 2
        b[1] * b[2] ~ 5
        b[1]^2 ~ 12
    end
end

@engeemodel B begin
    @components begin
        a1 = A(a = 2, b = [3, 4.0], c = 1, d = [5, 6])
        a2 = A(a = e, b = f*2, c = sin(e), d = f .+ 2)
    end
    @parameters begin
        e = 3
        f[:] = [3,4]
    end
end

In this example:

For a1 values are passed directly: numbers and arrays;
For a2 the component parameters are used B: e, f;
Expressions can be used when passing values: f*2, sin(e), f .+ 2;
You do not need to specify units of measurement — Engee automatically uses units from parameter declarations in the component. A.

Arrays of sub-components

Sub-components can be set not only one at a time, but also in arrays.

@engeemodel ArrayExample begin
    @components begin
        res = [EngeePhysicalFoundation.Electrical.Elements.Resistor() for i in 1:5]
        cap = [EngeePhysicalFoundation.Electrical.Elements.Capacitor() for i in 1:3]
    end
end

Features:

The sub-components are accessed like regular Julia arrays. Example: connect(diode[1].p, capacitor[3].p).
The names of the elements for external use will look like diode_1, diode_2, … and capacitor_1, capacitor_2, …

This is convenient if you need to connect a group of identical elements at once (for example, several diodes or capacitors).

Sub-component connections

Function connect(…) solves two problems:

Connects sub-components to each other;
Connects the port of the sub-component to the port of the main component.

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

    @components begin
        r = EngeePhysicalFoundation.Electrical.Elements.Resistor(R = 1000)
        c = EngeePhysicalFoundation.Electrical.Elements.Capacitor(C = 1e-6)
    end

    @equations begin
        connect(r.n, c.p)  # (1) соединяем подкомпоненты между собой
        connect(p, r.p)    # (2) соединяем порт r.p с внешним портом p
        connect(c.n, n)    # (2) соединяем порт c.n с внешним портом n
    end
end