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