Chapter 9 Connectors and Connections

Connections between objects are introduced by connect-equations in the equation part of a class. A connect-equation has the following syntax:

connect ”(” component-reference ”,” component-reference ”)” ”;”

The connect-equation construct takes two references to connectors [a connector is an instance of a connector class], each of which is either of the following forms:

• •

  $c_1.c_2\mathrm{\dots }{c}_n$, where $c_1$ is a connector of the class, n>=1 and $c_{i+1}$ is a connector element of $c_i$ for i=1:(n-1).

• •

  m.c, where m is a non-connector element in the class and c is a connector element of m.

There may optionally be array subscripts on any of the components; the array subscripts shall be parameter expressions or the special operator “:”. If the connect construct references array of connectors, the array dimensions must match, and each corresponding pair of elements from the arrays is connected as a pair of scalar connectors.

[Example of array usage:

]

The three main tasks are to:

• •

  Elaborate expandable connectors.

• •

  Build connection sets from connect-equations.

• •

  Generate equations for the complete model.

When generating connection equations, outer elements are resolved to the corresponding inner elements in the instance hierarchy (see instance hierarchy name lookup section 5.4). The arguments to each connect-equation are resolved to two connector elements.

For every use of the connect-equation

the primitive components of a and b form a connection set – together with an indication of whether they are from an inside or an outside connector; the primitive elements are of simple types – or of types defined as operator record (i.e. a component of an operator record type is not split into sub-components). The elements of the connection sets are tuples of primitive variables together with an indication of inside or outside; if the same tuple belongs to two connection sets those two sets are merged, until every tuple is only present in one set. Composite connector types are broken down into primitive components. The outer components are handled by mapping the objects to the corresponding inner components – and the inside indication is not influenced. The outer connectors are handled by mapping the objects to the corresponding inner connectors – and they are always treated as outside connectors.

[Rationale: The inside/outside as part of the connection sets ensure that connections from different hierarchical levels are treated separately. Connection sets are formed from the primitive elements and not from the connectors; this handles connections to parts of hierarchical connectors and also makes it easier to generate equations directly from the connection sets. All variables in one connection set will either be flow variables or non-flow variables due to restriction on connect-equations. The mapping from an outer to an inner element must occur before merging the sets in order to get one zero-sum equation, and ensures that the equations for the outer elements are all given for “one side” of the connector, and the inner element can define the other “side”.]

The following connection sets with just one member are also present (and merged):

• •

  Each primitive flow-variable as inside connector.

• •

  Each flow variable added during augmentation of expandable connectors, both as inside and as outside. [Note that the flow variable is not directly in the expandable connector, but in a connector inside the expandable connector.]

[Rationale: If these variables are not connected they will generate a set comprised only of this element, and thus they will be implicitly set to zero (see below). If connected, this set will be merged and adding this at the start has no impact.]

Each connection set is used to generate equations for potential and flow (zero-sum) variables of the form

• •

  a1 = a2 = ... = an;                // neither flow nor stream variables

• •

  z1 + z2 + (-z3) + ... + zn = 0 ; // flow-variables

The bold-face 0 represents an array or scalar zero of appropriate dimensions (i.e. the same size as z).

For an operator record type this uses the operator ’0’ – which must be defined in the operator record; and all of the flow-variables for the operator record must be of the same operator record type. This implies that in order to have flow variables of an operator record type the operator record must define addition, negation, and ’0’; and these operations should define an additive group.

In order to generate equations for flow variables [using the flow prefix], the sign used for the connector variable z_i above is +1 for inside connectors and -1 for outside connectors z₃ in the example above].

[Example (simple):

The connection sets are before merging (note that one part of the load and resistor is not connected):

{<load.p.i, inside>}

{<load.n.i, inside>}

{<ground.p.i, inside>}

{<load.resistor.p.i, inside>}

{<load.resistor.n.i, inside>}

{<resistor.p.i, inside>}

{<resistor.n.i, inside>}

{<resistor.p.i, inside>, <ground.p.i, inside>}

{<resistor.p.v, inside>, <ground.p.v, inside>}

{<load.p.i, inside>, <ground.p.i, inside>}

{<load.p.v, inside>, <ground.p.v, inside>}

{<load.p.i, outside>, <load.resistor.p.i, inside>}

{<load.p.v, outside>, <load.resistor.p.v, inside>}

{<load.n.i, outside>, <load.resistor.n.i, inside>}

{<load.n.v, outside>, <load.resistor.n.v, inside>}

After merging this gives:

{<load.p.i, outside>, <load.resistor.p.i, inside>}

{<load.p.v, outside>, <load.resistor.p.v, inside>}

{<load.n.i, outside>, <load.resistor.n.i, inside>}

{<load.n.v, outside>, <load.resistor.n.v, inside>}

{<load.p.i, inside>, <ground.p.i, inside>, <resistor.p.i, inside> }

{<load.p.v, inside>, <ground.p.v, inside>, <resistor.p.v, inside>}

{<load.n.i, inside>}

{<resistor.n.i, inside>}

And thus the equations:

load.p.v = load.resistor.p.v;

load.n.v = load.resistor.n.v;

load.p.v = ground.p.v;

load.p.v = resistor.p.v;

0 = (-load.p.i) + load.resistor.p.i;

0 = (-load.n.i) + load.resistor.n.i;

0 = load.p.i + ground.p.i + resistor.p.i;

0 = load.n.i;

0 = resistor.n.i;

Example (outer component):

The connection sets are before merging (note that one part of the load and resistor is not connected):

{<load.p.i, inside>}

{<load.n.i, inside>}

{<ground.p.i, inside>}

{<resistor.p.i, inside>}

{<resistor.n.i, inside>}

{<load.p.i, inside>, <ground.p.i, inside>}

{<load.p.v, inside>, <ground.p.v, inside>}

{<load.p.i, outside>, < resistor.p.i, inside>}

{<load.p.v, outside>, <resistor.p.v, inside>}

{<load.n.i, outside>, <resistor.n.i, inside>}

{<load.n.v, outside>, <resistor.n.v, inside>}

After merging this gives:

{<load.p.i, outside>, <resistor.p.i, inside>}

{<load.p.v, outside>, <resistor.p.v, inside>}

{<load.n.i, outside>, <resistor.n.i, inside>}

{<load.n.v, outside>, <resistor.n.v, inside>}

{<load.p.i, inside>, <ground.p.i, inside>}

{<load.p.v, inside>, <ground.p.v, inside>}

{<load.n.i, inside>}

And thus the equations:

load.p.v = resistor.p.v;

load.n.v = resistor.n.v;

load.p.v = ground.p.v;

0 = (-load.p.i) + resistor.p.i;

0 = (-load.n.i) + resistor.n.i;

0 = load.p.i + ground.p.i;

0 = load.n.i;

This corresponds to a direct connection of the resistor.

]

• •

  The connect-equations (and the special functions for overdetermined connectors) may only be used in equations and may not be used inside if-equations with non-parametric condition, or in when-equations. [For-equations always have parameter expressions for the array expression.]

• •

  A connector component may not be declared with the prefix parameter or constant. In the connect-equation the primitive components may only connect parameter variables to parameter variables and constant variables to constant variables.

• •

  The connect-equation construct only accepts forms of connector references as specified in section 9.1.

• •

  In a connect-equation the two connectors must have the same named component elements with the same dimensions; recursively down to the primitive components. The primitive components with the same name are matched and belong to the same connection set.

• •

  The matched primitive components of the two connectors must have the same primitive types, and flow-variables may only connect to other flow-variables, stream-variables only to other stream-variables, and causal variables (input/output) only to causal variables (input/output).

• •

  A connection set of causal variables (input/output) may at most contain variables from one inside output connector or one public outside input connector. [i.e., a connection set may at most contain one source of a signal.]

• •

  At least one of the following must hold for a connection set containing causal variables generated for a non-partial model or block:

  1. 1.

     the connection set includes variables from an outside public expandable connector,

  2. 2.

     the set contains variables from protected outside connectors,

  3. 3.

     it contains variables from one inside output connector, or

  4. 4.

     from one public outside input connector, or

  5. 5.

     the set is comprised solely of one variable from one inside input connector that is not part of an expandable connector.

  [i.e., a connection set must – unless the model or block is partial - contain one source of a signal (the last item (item 5) covers the case where a connector of a component is left unconnected and the source given textually).]

• •

  Variables from a protected outside connector must be part of a connection set containing at least one inside connector or one declared public outside connector (i.e. it may not be an implicitly defined part of an expandable connector). [Otherwise it would not be possible to deduce the causality for the expandable connector element.]

• •

  In a connection set all variables having non-empty quantity attribute must have the same quantity attribute.

• •

  A connect equation may not (directly or indirectly) connect two connectors of outer elements. [indirectly is similar to them being part of the same connection set – however, connections to outer elements are “moved up” before forming connection sets. Otherwise the connection sets could contain “redundant” information breaking the equation count for locally balanced models and blocks.]

• •

  Subscripts in a connector reference shall be parameter expressions or the special operator “:”.

• •

  Constants or parameters in connected components yield the appropriate assert statements to check that they have the same value; connections are not generated.

• •

  For conditional connectors, see section 4.4.5.

There is a special problem regarding equation systems resulting from loops in connection graphs where the connectors contain non-flow (i.e., potential) variables dependent on each other. When a loop structure occurs in such a graph, the resulting equation system will be overconstrained, i.e., have more equations than variables, since there are implicit constraints between certain non-flow variables in the connector in addition to the connection equations around the loop. At the current state-of-the-art, it is not possible to automatically eliminate the unneeded equations from the resulting equation system without additional information from the model designer.

This section describes a set of equation operators for such overconstrained connection-based equation systems, that makes it possible for the model designer to specify enough information in the model to allow a Modelica environment to automatically remove the superfluous equations.

[Connectors may contain redundant variables. For example, the orientation between two coordinate systems in 3 dimensions can be described by 3 independent variables. However, every description of orientation with 3 variables has at least one singularity in the region where the variables are defined. It is therefore not possible to declare only 3 variables in a connector. Instead n variables (n > 3) have to be used. These variables are no longer independent from each other and there are n-3 constraint equations that have to be fulfilled. A proper description of a redundant set of variables with constraint equations does no longer have a singularity. A model that has loops in the connection structure formed by components and connectors with redundant variables, may lead to a differential algebraic equation system that has more equations than unknown variables. The superfluous equations are usually consistent with the rest of the equations, i.e., a unique mathematical solution exists. Such models cannot be treated with the currently known symbolic transformation methods. To overcome this situation, operators are defined in order that a Modelica translator can remove the superfluous equations. This is performed by replacing the equality equations of non-flow variables from connection sets by a reduced number of equations in certain situations.

This section handles a certain class of overdetermined systems due to connectors that have a redundant set of variables. There are other causes of overdetermined systems, e.g., explicit zero-sum equations for flow variables, that are not handled by the method described below.]