Troubleshooting A Failing Dymola Model

There are lots of reasons why a model can fail and sometimes it feels like an endless battle just keeping models running. But what do you do if there is a model that used to run and for some unknown reason it just doesn’t any more? Or a model that theoretically should run but just doesn’t? Here’s a quick set of troubleshooting guidelines to help try and get your models back to a gloriously, error free, simulating state. For this blog post we are assuming that Licensing is not an issue and we are using a full version of Dymola.

Let’s break it down into 3 common stages of a model simulation failure, in order of which to check first:

  1. Model Check
  2. Initialisation
  3. Simulation

It is fairly easy to identify which stage your model is failing and once done it can help home in on what kind of issues to look for. Through all of these steps the Dialog Box is your best friend to help identify what and where your issue lies; but part of the terminology can be misleading or difficult to understand.

We will be troubleshooting a Suspensions Double Wishbone Half Car Multibody experiment but the principals can be applied widely to other situations too. Troubleshooting

Model Check

Check Button

Check the model using the button highlighted above. There are two main types of messages that arise from a model check; warnings and errors. Troubleshooting

Warnings don’t stop the model from running but can help identify weaknesses in the model. Errors will stop a model from running; these are the things to take note of. If you have neither of these then you can move onto Compilation and Initialisation. Here are some common errors to look for and some reasons why they can occur:

Double Wishbone Missing Connection - Troubleshooting

Errors or Failure to handle Overdetermined Connectors

This means that there are some variables that cannot be computed; the common issue is that there is a connection missing. Use the location given as a starting point to check that everything is connected and everything has the correct amount of freedom. In our double wishbone example we could be missing the anti roll bar connection as shown on the right; this causes the ARB to be unattached to the suspension and therefore is not constrained.

2 Double Wishbone ARB Connections

The problem is Structurally Singular

This means that there are variables that are over constrained; the common issue is that there are multiple connections defining the same variable. For more simple models the Dialog Box can normally direct you to the issue; for more complex issues it can be difficult for Dymola to isolate what should and shouldn’t be connected so a little bit of detective work may be required. Breaking the model into isolated component experiments can be very helpful in identifying the culprit. In the linkage it could have the anti roll bar connected to both the upper and lower control arm, shown on the left; this constrains too many degrees of freedom for the linkage.

There are more obvious issues such as parameters missing values or type inconsistencies which Dymola is good at pointing out. But Dymola can get confused when checking external functions as it cannot check if it is functioning/interacting as it should; this can give you a false answer and lead you in the wrong direction.


Let’s think of Initialisation as several steps Dymola takes just before starting the simulation. You can identify that it is failing at this stage by attempting to simulate and not reaching a point where time is increasing. You can see this by looking at the Variable Browser in the simulation tab; if there is a list of Initial Values instead of results then it has not passed initialisation. The Simulation tab of the Dymola Message will also end with Error: Failed to start model. The error messages in this tab can be confusing but they usually give a location to look. Common causes of this kind of failure are:

Bad Parameter Values

When a model is connected correctly but the values populating the parameters are incorrect or impossible to create a working model from. This is very easy to do; a typo, incorrect unit selection, model variant choice, changes to supporting libraries… this list is very long. The Simulation tab normally gives you the location of the failing system. The best direction to go is to break up complex models and simulate individual subsystems to make sure they run with the same parameters. For a double wishbone suspension system that could be simulating a 500m long damper in a space fit for one 500mm long.

Bad Initialisation Settings

Revolute Initialisation control - Troubleshooting

A subtle difference to Bad Parameter Values is the initialisation settings of systems; these are initial positions, temperatures, speeds, etc that allow a model to start within sensible/possible limits. Initialisation Parameters and settings can be overlooked as they are not required to be modified for the model to run; but they can really help you get a model starting happily and help simulation speed.

When looking at a revolute joint the initialisation settings can control the angle, speed and acceleration of the rotation. The settings highlighted in blue can allow a user to force the simulation to use the value given; otherwise the value is just used as a guess value. Be careful though, over constraint of the model at initialisation also causes models to fail; for example if we are forcing identical initial values of two adjacent rotating bodies. You can use the Warnings section of the Model Check, mentioned above, to identify potential undefined initial parameters.


Failure during simulation is easy to spot; does the simulation start and then fail? Unfortunately troubleshooting can be a little more difficult. There are many reasons why a simulation could fail, and don’t rule out the issues mentioned in Initialisation; a simulation could initialise but when subjected to experiment, conditions fail due to incorrect parameterisation.

Primary reason that a simulation fails is because a calculated variable value is mathematically impossible; for example the distance between two joints is driven larger than fixed translation holding them together. A good starting point is to look at the key variables to see if they are within sensible limits. If you find a suspect variable, look at the parameters surrounding it and check if they are reasonable. The Simulation tab of Dymola Messages can be helpful in pointing towards a problem system.

Lack of continuous derivatives of variables also cause failure; if the position of mass is moved in infinitely fast steps then the acceleration and force cannot be calculated. An area that can highlight this type of fluctuation is looking at events and seeing what is changing leading up to the failure. This is done in the Simulation Setup, Debug tab by enabling Events during simulation. This provides a list of events that show changing states of the model which highlight what could upset the model.

There are lots of ways to try and find the issue causing a failure; I have the luxury of working primarily with multibody models so including visualisation can sometimes highlight the issue.

Best Practice to aid Troubleshooting

Keep libraries up to date; The newest version of a library invariably has the most bug fixes and therefore should have the most stable versions of models.

Read Release Notes; When updating to a newer version of libraries there are changes, some could be crucial to your model. Release notes let you know what has changed since the last release, improvements, new features, bug fixes and dependant library versions; Most importantly it contains information about pre-requisite model modifications that update scripts are unable to change, to ensure your models carry on working. Reading through it could save you a lot of hassle both in new features improving your models and in getting your models working correctly.

Keep Subsystems and Components Independently Correct; Build each component and subsystem so that it can be separate from the rest of a system without failing a check; this means it makes it a lot easier creating component tests and can make the task of troubleshooting a lot easier if something does go wrong.

Name and describe EVERYTHING; Reiterating a previous blog post suggestion, looking at a Dirty Code Layer, keep everything named, described and neat; Time spent when you build a model will be paid back 10 times over if you need to come back to it later to troubleshoot it.

Written by: David Briant – Project Engineer







Log in with your credentials

Forgot your details?