Local balance

[HansOlsson]

I believe this handles all of the case, but there might be some remaining issue.

[HansOlsson]

I believe the updated handling of overdetermined connectors works, and to me is short and fairly intuitive.
I understand it can be formulated in different ways, but I don't see any alternative that will be as easy to handle.

For the perfect matching I believe it is best discussed in #3763 - and some restriction added later.

[HansOlsson]

As far as I can see this improves the situation for:

• overdetermined connectors (when doing a local check and there are sub-components with overdetermined connectors).
• expandable connectors

With fairly small changes. It would be possible to formulate in various other ways, but I believe they will be equivalent - and I don't see any alternative that is clearly easier to understand.

Note that we have improved the local check for these cases for Dymola 2026x (in particular when checking models with partial components which requires a local check, the usual balancing-error-pin-pointing is primarily an inclusive check according to the terminology in
#3750 (comment) ); so I'm fairly confident that it actually works.

[qlambert-pro]

This is overly abstract and as I explained before the only way I am signing off on it is if other people prefer this formulation to what I proposed.

[HansOlsson]

So that others can find that alternative (which responded to a previous variant of this text):

An alternative to the count here is:

• For over-determined variables and equations, where the cardinality of the type is c and the size of the residual is n:
  • Over-determined connector variables are counted as n variables.
  • Declaration and equality equation of over-determined type are counted as c.
  • Connections.root and Connections.branch are counted as adding n - c equations.
  • Connections.potentialRoot is counted as adding n - c if the root is selected and 0 otherwise.
  • Generated potential equations are counted as adding n equations.

Originally posted by @qlambert-pro in #3750 (comment)

I have a hard time understanding how that description really works, as Connections.root and Connections.potentialRoot don't directly contribute to the global equation count (for potentialRoot there is normally an if-equation based on whether it is selected as root or not).

However, I can understand that this problem is abstract and complicated to get right.

The following are four cases that seem to covert this:

• A root-less component with one over-determined connector, like Modelica.Mechanics.MultiBody.Forces.WorldForce
• A component with a root and one over-determined connector, like a simplified Modelica.Mechanics.MultiBody.Parts.Body
• A (root-less) component with a pair of over-determined connectors connected to similar ones in a sub-component, like Modelica.Mechanics.MultiBody.Forces.Spring
• A (root-less) component with a pair of over-determined connectors connected to similar ones in two sub-component (like a parallel Spring and Damper variant built by components).

[HansOlsson]

After some additional thinking:

I still don't think that describing local variable and equation sizes in that way for the local check would be good, as it creates a different way of counting even for a simple model with overdetermined connectors and without sub-components.

However, it indicates that it is locally and globally possible to check balancing without generating the spanning tree and the corresponding equations, and that seems seems like something that could be documented in general. I would slightly rewrite it as (and view that as a separate pull-request):

-Start-

For checking the number of variables and equations for overdetermined connectors an alternative to generating equations from the spanning tree is the following (note that this often generates fewer variables and equations, but both counts are decreased by the same amount):

For over-determined variables and equations, where the cardinality of the type is c and the size of the residual is n (where c>=n):

• Over-determined connector variables are counted as n variables.
• Declaration and equality equation of over-determined type are counted as c.
• Connections.root and Connections.branch are counted as adding c-n variables.
• Connections.potentialRoot is counted as adding c-n variables if the root is selected and 0 otherwise.
• Generated potential equations (from connections) are counted as adding n equations.

The balance should hold for all legal selections of potential roots, and also for all possibilities for Connections.isRooted. For local check only the local Connections.root etc are considered.

The addition of c-n variables effectively mean that roots (and one of the arguments to branch) are counted as having the cardinality of its type, c.

-End-

Notes:

• The over-determined connector variables counted as c correspond to branches being in parallel with equations for the entire over-determined connector (i.e., of size c) and roots having equations for the entire over-determined connector, i.e., c equations, not only equations for the residual.
• The statement that it should hold for all selections adds something, both locally and globally.
• It is still necessary to process connections, due to the possibility of redundancy in the connection sets (both for over-determined connectors and for normal ones).
• I prefer to add positive variables instead of subtracting equations (or as above adding a negative number), since negative number of equations are generally quite confusing for users; and in this case the added variables isn't just a number, but it corresponds to actual variables as explained above (or specifically it change the count to an actual variable).
• It indirectly uses the spanning tree as explained below.

For simulation models this is consistent with the equation count in for the spanning tree since:

• Nodes will add c-n variables (unless already done), and based on the spanning tree a corresponding number of equations:
  • If there's incoming edge to the node and it is an optional spanning tree edge it means we generate normal equations for the connection, of size c, i.e., adding c-n equations.
  • Otherwise it must be a root (potential or otherwise), or have a required edge as incoming (based on Connection.branch), and in those cases we already added c-n variables.
• If an optional spanning tree isn't such an incoming edge it has been removed from the spanning tree, and generate n residual equations.

An alternative that is more intuitive, except for one minor issue, would be to reduce the changes to:

• Over-determined connector variables are counted as c variables, if they are (locally) selected as root (potential or otherwise) or the target of Connections.branch; in all other cases as n variables.
• Generated potential equations (from connections) are counted as adding n equations (regardless of whether the branch is broken or not).

The only issue is that the Connections.branch "target" must be a non-root to avoid double-counting. So, if you have two potential roots and a branch between them you may have to adjust the target depending on the root-selection (both cannot be selected). Trivial, but that is sort of looking at the spanning tree).

That model is an issue also for the proposal above, that is hidden in the "all legal selection of roots", so if someone has such a model and writes if Connections.isRoot(f_a.o) then ... else if Connections.isRoot(f_b.o) then else ... end if based on the understanding that only one of them will be a root we need to use the spanning tree information to rule out both being selected as roots, since otherwise it will be unbalanced in that case.

[HansOlsson]

For the cases above with an over-constrained connector, Frame, with n flows and c variables in the over-determined type. To me one major benefit of this way of thinking is that one can adjust this to not only have a local balance in terms of number of variables and equations, but also construct structurally non-singular equations based on this, which may find structurally singular sub-components even if they are balanced.

Modelica.Mechanics.MultiBody.Parts.Body (with potential root we also cover Modelica.Mechanics.MultiBody.Forces.WorldForce). The thing that makes it complicated is the quaternions which are due to the same underlying issue with over-determined types, so I thought it best to include that as well in a general setting:

model SimpleBody
   constant Integer nQ=4;
   constant Real dummyQ[nQ]=...;
   Real Q[nQ];
   Frame frame_a;
equation
   Connections.potentialRoot(frame_a.R);
   if Connections.isRoot(frame_a.R) then
      frame_a.R=from_Q(Q);
      zeros(nQ-n)=orientationConstraint(Q);
   else
      Q=dummyQ;
   end if;
end SimpleBody;

It has if nQ+n+c variables and the same number of equations:

• Actual equations if isRoot(frame_a.R) then c+(nQ-n) else nQ
• Equations for flow-variables in outside connectors n
• Possibly root-less spanning tree if isRoot(frame_a.R) then 0 else c-n

Note: This works both if the over-determined type describe rotation as rotation matrix (c=9) or as quaternion(c=4).

Connection from a sub-component (half of Modelica.Mechanics.MultiBody.Forces.Spring - it would be straightforward to add the other half):

model HalfSpring
  Frame frame_a;
  HalfLineForce halfLine;
equation
  connect(frame_a, halfLine.frame_a);
end HalfSpring;

It has n+c+n variables (we only consider flow-variables for connectors in sub-components) and the same number of equations:

• Actual equations with just equality for connect: n+c equations.
• Equations for flow-variables in outside connectors n
• No root-less spanning tree: 0

Connection from a sub-component (half of spring-damper built in the same way`):

model HalfSpringDamper
  Frame frame_a;
  HalfLineForce lineSpring;
  HalfLineForce lineDamper;
equation
  connect(frame_a, lineSpring.frame_a);
  connect(frame_a, lineDamper.frame_a);
end HalfSpringDamper;

Since both of the inside over-determined connectors are seen as roots it has to break of the connections.

It has n+c+n*2 variables (we only consider flow-variables for connectors in sub-components), and the same number of equations:

• Flows summing to zero: n
• One connect generating normal potential equations: c equations
• One connect being over-determined: n residual equations
• Equations for flow-variables in outside connectors n
• No root-less spanning tree: 0

However, even if I could include that in the specification as examples (with both halves) I now think it would be too much.