Local balance, connect equations and over-determined connectors.

[qlambert-pro]

Consider the two following models.

model Balance9
  connector Pin
    Real v;
    flow Real i;
  end Pin;

  model Ground
    Pin p;
  equation
    p.v = 0;
  end Ground;

  model Nand
    Pin x1;
    Pin y;
  equation
    x1.v = y.v;
    0 = x1.i + y.i;
  end Nand;

  Ground Gnd4;
  Nand nand;
equation
  connect(Gnd4.p, nand.x1);
end Balance9;

and

model Balance12
  connector Frame
    Orientation R;
    flow Real f;
  end Frame;

  record Orientation
    Real w[2];

    function equalityConstraint
      input Orientation R1;
      input Orientation R2;
      output Real residue[1];
    algorithm
      residue := {0};
    end equalityConstraint;
  end Orientation;

  model M
    Frame f;
  equation
    Connections.root(f.R);
    f.R = Orientation(w = zeros(2));
  end M;

  model A
    Frame frame_a;
    Frame frame_b;
  equation
    Connections.branch(frame_a.R, frame_b.R);
    frame_b.R = frame_a.R;
    0 = frame_a.f + frame_b.f;
  end A;

  M m;
  A a;

equation
  connect(m.f, a.frame_a);
end Balance12;

Both models have the same structure, the difference is that one of the connectors is overdetermined.

As a result, I would expect both models to have the same number of variables at the top level.
But the number of equations generated by the connectors, at the top level is:
for Balance9

• from Gnd4.p and nand.x1
1 flow equation and 1 potential equation
• from nand.y
1 flow equation

for Balance12

• from m.f and a.frame_a
1 flow equation and 2 potential equations
• from a.frame_b
1 flow equation

Which would make Balance9 locally balanced and Balance12 locally imbalanced, although I would expect both to be balanced since they are simpler versions of models present in the MSL.

What am I missing?

[HansOlsson]

Well, the connector is larger so one would have two more variables in Balance12 (two connectors).

https://specification.modelica.org/master/class-predefined-types-and-declarations.html#local-equation-size has one additional rule:

For over-determined connectors, section 9.4, each spanning tree without any root node adds the difference between the size of the over-determined type or record and the size of the output of equalityConstraint.

So, if you consider Balance12 you don't have a root, and there's thus one spanning tree without a root, so you should add 2-1=1. So, two more equations matching the two extra variables.

[HansOlsson]

Similarly for A you have 3 connectors variables, and 2 equations inside the model and 1 for the unconnected flow.
And for M you have 2*3 connector variables, 3 equations inside the model, 2 for the unconnected flow, and 1 for a root-less tree.

Note that this rule was added in #3442

[qlambert-pro]

I am counting 3 variables in Balance12 one for each flow variable of each public inside connector.
The following seems to be the only rule that applies since Balance12 only has components of the model kind.

For each declared component of specialized class block or model, it is the sum of the number of
inputs and flow variables in the (top level) public connector components of these components (and
counting the elements after expanding all records and arrays to a set of scalars of primitive types)

I would have thought that in Balance12, there are no spanning trees without a root since there is a single spanning tree and it has a root in m. If that's not the case the non-normative text should REALLY be adjusted.

[By definition this term is zero in simulation models, but relevant for checking component models.
There are no other changes in the variable and equation count for models – but a restriction on the
size of the output of equalityConstraint, section 9.3.1.]

[HansOlsson]

I am counting 3 variables in Balance12 one for each flow variable of each public inside connector. The following seems to be the only rule that applies since Balance12 only has components of the model kind.

For each declared component of specialized class block or model, it is the sum of the number of
inputs and flow variables in the (top level) public connector components of these components (and
counting the elements after expanding all records and arrays to a set of scalars of primitive types)

I would have thought that in Balance12, there are no spanning trees without a root since there is a single spanning tree and it has a root in m. If that's not the case the non-normative text should REALLY be adjusted.

Ah, I assume that it could be clearer that the local equation count only considers a root in the spanning tree, if the root is among the local equations. Would that clarify it enough?

Thus if you consider Balance12 without the contents of its sub-components, then there is no root in the single spanning tree as above.

If you consider the Balance12 with sub-components there are 3*3 connectors variables. 2+1 equations in A, 2 equations in M, A connection giving 3 equations, and one unconnected connector giving 1 flow-equation equal to zero.

[qlambert-pro]

Ah, I assume that it could be clearer that the local equation count only considers a root in the spanning tree, if the root is among the local equations. Would that clarify it enough?

Then Modelica.Mechanics.MultiBody.Examples.Elementary.FreeBody which is a simulation model, would have a non zero term which is the opposite of what the non-normative text says.

If you consider the Balance12 with sub-components there are 3*3 connectors variables.

What part of the local variable counting rules justifies you doing that?

[qlambert-pro]

It looks to me like the specs is missing the fact that the rank of potential equation over over-determined types should be the size of the residual.

[HansOlsson]

Ah, I assume that it could be clearer that the local equation count only considers a root in the spanning tree, if the root is among the local equations. Would that clarify it enough?

Then Modelica.Mechanics.MultiBody.Examples.Elementary.FreeBody which is a simulation model, would have a non zero term which is the opposite of what the non-normative text says.

True, it would only apply to a simulation model without any sub-components.

If you consider the Balance12 with sub-components there are 3*3 connectors variables.

What part of the local variable counting rules justifies you doing that?

Sorry for being unclear: That's not the local count, but the global.

[qlambert-pro]

Sorry for being unclear: That's not the local count, but the global.

Right, what about the local count then ...

[HansOlsson]

Sorry for being unclear: That's not the local count, but the global.

Right, what about the local count then ...

So, for the local equations the previous statement should be updated to something like:

For over-determined connectors, section 9.4, each spanning tree without any root node when only considering the local equations adds the difference between the size of the over-determined type or record and the size of the output of equalityConstraint.

By definition this term is zero in simulation models without sub-components having overdetermined connectors,
but relevant for checking component models. There are no other changes in the variable and equation count for models – but a restriction on the size of the output of equalityConstraint, section 9.3.1.

Note: Local and global equation size is a bit too simple, there are in fact three different possibilities:

• Global equation size for the entire model
• Local equation size for just this model
• Local equation size for this model and all sub-components (not discussed in the specification)

For potential roots it is a bit messy, but ideally the model should work regardless of root selection (so either select a root and corresponding equations in the local model, or don't select and add the number above).

Regarding,

It looks to me like the specs is missing the fact that the rank of potential equation over over-determined types should be the size of the residual.

Doesn't that rank implicitly follow from the above, and the restriction on the rank of equalityConstraint in 9.3.1? Note that the equations may not always be split as nicely as "potential equations".

[qlambert-pro]

So, for the local equations the previous statement should be updated to something like:

For over-determined connectors, section 9.4, each spanning tree without any root node when only considering the local equations adds the difference between the size of the over-determined type or record and the size of the output of equalityConstraint.
By definition this term is zero in simulation models without sub-components having overdetermined connectors,
but relevant for checking component models. There are no other changes in the variable and equation count for models – but a restriction on the size of the output of equalityConstraint, section 9.3.1.

This suggestion would add to the local count of equations to a model that is already in surplus according to how the specs talk about counting variables. I think the text as it is written is fine, we could add that for the purpose of determining if the spanning tree is rooted all sub-component should be considered. Which would indeed make Balance12 a simulation model meet the non-normative text.

Note: Local and global equation size is a bit too simple, there are in fact three different possibilities:

* Global equation size for the entire model

* Local equation size for just this model

* Local equation size for this model and all sub-components (not discussed in the specification)

I have only ever talked about the "Local equation size for just this model" as described in the specs, in this issue.

For potential roots it is a bit messy, but ideally the model should work regardless of root selection (so either select a root and corresponding equations in the local model, or don't select and add the number above).

I understand.

Regarding,

It looks to me like the specs is missing the fact that the rank of potential equation over over-determined types should be the size of the residual.

Doesn't that rank implicitly follow from the above, and the restriction on the rank of equalityConstraint in 9.3.1? Note that the equations may not always be split as nicely as "potential equations".

I don't understand how it does.

Either, following is true:

The number of variables of an overdetermined type or record class (see section 9.4.1) is the size of the output argument of the corresponding equalityConstraint() function.

and the following is unbalanced

  model A
    Frame frame_a; // (1 flow + 2 potentials with residual of 1) =  2 variables
    Frame frame_b; // (1 flow + 2 potentials with residual of 1) =  2 variables

   //that's 4 variables and 2 equations (one for each flow)
  equation
    Connections.branch(frame_a.R, frame_b.R); // 2 - 1 = 1 for the unrooted spanning tree
    frame_b.R = frame_a.R; (residual = 1 equation)
    0 = frame_a.f + frame_b.f; (rank1)
  end A;

 // that's 4 variables and 5 equations

Scrapping the rule about unrooted spanning tree would make it work here.

or it isn't and the following is unbalanced as said above:

model Balance12
  connector Frame
    Orientation R;
    flow Real f;
  end Frame;

  record Orientation
    Real w[2];

    function equalityConstraint
      input Orientation R1;
      input Orientation R2;
      output Real residue[1];
    algorithm
      residue := {0};
    end equalityConstraint;
  end Orientation;

  model M
    Frame f;
  equation
    Connections.root(f.R);
    f.R = Orientation(w = zeros(2));
  end M;

  model A
    Frame frame_a;
    Frame frame_b;
  equation
    Connections.branch(frame_a.R, frame_b.R);
    frame_b.R = frame_a.R;
    0 = frame_a.f + frame_b.f;
  end A;

  M m; // 1 flow variable
  A a; // 2 flow variables

equation
  connect(m.f, a.frame_a); // 2 potential equations + 1 flow
 // 1 flow for the unconnected  `a.frame_b`
end Balance12;
// that's 3 variables and 4 equations
// and that's 3 variables and 5 equations if you consider the single spanning tree to be unrooted despite the root in `m`.

Considering the potential equations resulting from the connect set as being of rank 1 would make Balance12 balanced.

[qlambert-pro]

The following model would only work without the unrooted spanning tree number, but with the strict "overdetermined types have a number of variables equal to the size of their residual" interpretation.

model Balance13
  record Orientation
    Real w[3];

    function equalityConstraint
      input Orientation R1;
      input Orientation R2;
      output Real residue[1];
    algorithm
      residue := {0};
    end equalityConstraint;
  end Orientation;

  connector Frame
    Orientation R;
    flow Real f[1];
  end Frame;

  model Body
    Frame frame_a;
  protected
    Real[2] Q;

    function f
      input Real i[2];
      output Real o[1] = {1};
    end f;
  equation
    Connections.root(frame_a.R);
    frame_a.R = Orientation(zeros(3));
    {0} = f(Q);
    frame_a.f = zeros(1);
  end Body;

  Frame frame_a;
  Body body;
equation
  connect(frame_a, body.frame_a);
end Balance13;

It is minimized from Modelica.Mechanics.MultiBody.Parts.BodyShape.

[HansOlsson]

Regarding,

It looks to me like the specs is missing the fact that the rank of potential equation over over-determined types should be the size of the residual.

Doesn't that rank implicitly follow from the above, and the restriction on the rank of equalityConstraint in 9.3.1? Note that the equations may not always be split as nicely as "potential equations".

I don't understand how it does.

Either, following is true:

The number of variables of an overdetermined type or record class (see section 9.4.1) is the size of the output argument of the corresponding equalityConstraint() function.

Oh, I realize that is bad naming.

That should be called the number of potential variables (or similarly), and shouldn't directly impact the balancing count for the model, but is just a restriction on all connectors.

Calling it "number of variables" while excluding flow and causal causal variables is bad naming, and thus directly using it for balancing for models would be problematic (but see below).
(Note that the balancing doesn't use the same name, but it should still be cleaned up.)

It is indirectly used because the balancing uses "flow variables" when it could have used "potential variables".

and the following is unbalanced

  model A
    Frame frame_a; // (1 flow + 2 potentials with residual of 1) =  2 variables
    Frame frame_b; // (1 flow + 2 potentials with residual of 1) =  2 variables

   //that's 4 variables and 2 equations (one for each flow)
  equation
    Connections.branch(frame_a.R, frame_b.R); // 2 - 1 = 1 for the unrooted spanning tree
    frame_b.R = frame_a.R; (residual = 1 equation)
    0 = frame_a.f + frame_b.f; (rank1)
  end A;

 // that's 4 variables and 5 equations

To me: there are 2*3=6 scalar variables and 6 scalar equations:

• 2 from flow variables
• 2-1 for unrooted spanning tree
• 2 from frame_b.R = frame_a.R
• 1 from flow equation

Similarly for M there are 3 scalar variables and 3 scalar equations:

• 1 from flow variables
• 2 from frame.R=....

BTW: There are multiple ways to count inputs in connectors and causal connectors (flow vs residual) that view the same models as balanced, but give different matching counts for unknowns and equations. I find the current approach somewhat easy to understand (just count all variables), and it avoids negative counts for incorrect models that can be quite confusing.

But it should be explained better.