# 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.