Structurally singular system🔗

Background🔗

A model is considered to be a structurally singular system if the number of variables is not equal to the number of equations.

Examples🔗

The simplest example is a model with two variables and one equation. Consider model A below:

model A "Example of a structurally singular system."
    Real x;
    Real y;
equation
    der(x) = -x;
end A;

An attempt to simulate model A above fails with the error:

Error in flattened model:
    The system is structurally singular. The following variable(s) could not be matched to any equation:
     y

Model A is by definition structurally singular since there is no equal number of variables to the number of equations. The error message informs that y cannot be matched to any equation. This is because compared to x, there is no equation describing y.

Below let us modify model A to show another failing example:

model B "Example of a structurally singular system."
    Real x;
    Real y;
equation
    der(x) = -x-y;
end B;

Model B fails with the same error as A.

Error in flattened model:
    The system is structurally singular. The following variable(s) could not be matched to any equation:
     y

The reason is that the equation der(x) = -x-y is again not enough to calculate both x and y. The model still has two variables but only one equation.

Now we start from B and create model C. We add an arbitrary equation for y which results in a model that simulates without errors:

model C "Model that is not structurally singular."
    Real x;
    Real y;
equation
    der(x) = -x-y;
    der(y) = y + 1;
end C;

In the same manner, we can have a structurally singular system that has too many equations. We add an arbitrary equation that includes both x and y and call the model D:

model D "Structurally singular system, too many equations."
    Real x;
    Real y;
equation
    der(x) = -x-y;
    der(y) = y + 1;
    x * x + sin(y) = 3;
end D;

Compiling model D will generate the expected error below:

Error in flattened model:
  The system is structurally singular. The following equation(s) could not be matched to any variable:
    x * x + sin(y) = 3

Usually, a model is more complex than the cases above, but when a system is structurally singular, all the unmatched variables and equations will be displayed in the error message.

How to investigate the issue🔗

Local balancing check🔗

It is recommended to debug errors related to structurally singular systems by first checking the local balancing. This initiates a check per model that counts the number of variables and equations. For example, if model A (from the earlier example) is in our workspace, then a local balance check will display:

Balance check returned errors:
Class Workspace.A is not locally balanced:
    Local number of unknowns: 2
    Local equation size:      1

From the error above, it is straightforward to identify that there is an issue in model A in the workspace and can check if we have missed equations or added too many variables.

Too many connectors🔗

Another common scenario that leads to the same error is too many connections. As an example, create a workspace with a model Test and add the following components: - Add two of Modelica.Blocks.Sources.Constant, set the value k on each of the sources to different positive values. - Add one Modelica.Mechanics.Rotational.Sources.Position - Connect each output from the two constant sources to the input of the source position.

Compiling the model now generates the error:

Compilation failed for Workspace.Test
The system is structurally singular. The following equation(s) could not be matched to any variable:
    const.y = const2.k

Performing a local balancing check will also display an error, informing that there are only 2 variables but 3 equations.

Initialization Failure