Engee documentation

Creating a physical component

The structure of the physical component

The declaration of any physical component always begins with a construction @engeemodel, followed by the component name. The entire content of the component is described inside the structure begin …​ end:

@engeemodel component_name begin
end

The code above creates an empty physical component with no parameters or behavior description. In order for the component to perform useful functions, other language constructs are placed inside the structure, each of which is also formed into a block. begin …​ end. For example:

  • @parameters — sets the parameters that are configured before the model is launched:

    @parameters begin
    a = 1.0
end

  • @variables — introduces variables that change during the simulation:

    @variables begin
    x = 1.0
end

It should be noted that this is only a basic set of constructs. In the Engee physical modeling language, there are significantly more of them: ports, branches, structural parameters, subcomponents, annotations, and much more. For a complete list, see Syntax of the Engee Physical Modeling language.

Component Creation: capacitor

Now let’s look at what creating a real physical component looks like in practice. As an example, let’s take an electric capacitor, an illustrative element that shows how ports, parameters, variables, branches, and equations are combined within a single physical component.

  1. Create a folder in file browser Engee file browser 7.

  2. Add the created folder to path.

  3. Create a format file in the folder .ngpc and the initial template:

    @engeemodel Capacitor begin
end
    Construction @engeemodel_name of the begin …​ end component required to create any physical component.

In one `.ngpc`A file can have several physical components, but to avoid confusion, it is better to store each component in a separate file (1 .ngpc file = 1 physical component).

Adding Ports

The ports determine how the component connects to the rest of the model and what values are exchanged through it. Here we will announce two electrical outputs — positive p and negative n, which will be used in the component equations. Two electrical outputs (p and n), through which the capacitor is connected to the circuit.

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

Adding parameters

Parameters are configurable constants that are set before launching the model. For a capacitor, this is the capacitance C with a faraday unit of measurement and a brief description for the interface.

@parameters begin
    C = 1e-6, [unit = "F", description = "Capacitance"]
end

C — capacitor capacity; in the future, this value can be changed in the unit settings.

Adding variables

Variables are quantities that are calculated during simulation. The capacitor needs: voltage v between the terminals and the current i through the element; we will indicate the units of measurement and understandable signatures to them:

@variables begin
    v = 0.0, [unit = "V", description = "Voltage"]
    i = 0.0, [unit = "A", description = "Current"]
end

Here v — voltage on the element; i — current through the element.

Adding a branch

Branches associate physical component variables with port flow variables and define the flow topology within the model. By linking i with p.i and n.i, ensures that the current balance is correctly accounted for when connecting physical components to each other.

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

The branch defines how the variable i connected to the ports of the component: current i It represents the total amount that flows through the ports. p.i and n.i. The flow balance is taken into account automatically when connecting physical components.

Writing the equation

Equations are physical relations that describe the behavior of a component. For the capacitor, we set the voltage drop as the potential difference of the ports, and write down the basic ratio i = C * du/dt and synchronize the port parameters between the ports.

@equations begin
    v ~ p.v - n.v         # voltage between ports
    i ~ C * der(v)        # the basic equation of the capacitor
    domain_connect(n, p)  # negotiation of environment parameters between ports
end

The first equation defines the voltage as the potential difference of the ports, and the second equation defines the current dynamics. domain_connect transfers parameters between ports. For information about matching port parameters, see the article Equations of the physical modeling language.

The final code of the physical component

Below, all the parts of the physical component are put together, from ports and parameters to branches and equations. This completed fragment can be saved in .ngpc and immediately use it as a full-fledged Capacitor unit in Engee models.:

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

    @parameters begin
        C = 1e-6, [unit = "F", description = "Capacitance"]
    end

    @variables begin
        v = 0.0, [unit = "V", description = "Voltage"]
        i = 0.0, [unit = "A", description = "Current"]
    end

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

    @equations begin
        v ~ p.v - n.v
        i ~ C * der(v)
        domain_connect(n, p)
    end
end

Connecting a physical component to the Engee model

  • Add the Physical Component block to the canvas.

  • In its settings (settings window debug article icon 1) specify the path to the file .ngpc or the name Capacitor.

  • Now the Capacitor block can be used in any model along with the typical blocks of the Engee physical library.

For the model to work correctly with a physical component (and any other block from Physical Modeling) add a block to the model Solver Configuration.

Thus, in the Engee language of physical modeling, we have described the physical component Capacitor that models the behavior of a capacitor.

Recommendations

  • Use informative names and ask questions. units of measurement for parameters and variables.

  • Check the physical correctness of the equations and the boundary cases (for example, using assert you can set the acceptable range of parameter values, etc.). For more information, see the article Checks.

  1. Physical Modeling

  2. Syntax of the Engee Physical Modeling language