Main Content

Troubleshooting Simulation Errors

Troubleshooting Tips and Techniques

Simscape™ simulations can stop before completion with one or more error messages. This section discusses generic error types and error-fixing strategies. You might find the previous section, How Simscape Simulation Works, useful for identifying and tracing errors.

If a simulation failed:

  • Review the model configuration. If your error message contains a list of blocks, look at these blocks first. Also look for:

    • Wrong connections — Verify that the model makes sense as a physical system. For example, look for actuators connected against each other, so that they try to move in opposite directions, or incorrect connections to reference nodes that prevent movement. In electrical circuits, verify polarity and connections to ground.

    • Wrong units — Simscape unit manager offers great flexibility in using physical units. However, you must exercise care in specifying the correct units, especially in the Simulink-PS Converter and PS-Simulink Converter blocks. Start analyzing the circuit by opening all the converter blocks and checking the correctness of specified units.

  • Try to simplify the circuit. Unnecessary circuit complexity is the most common cause of simulation errors.

  • Break the system into subsystems and test every unit until you are positive that the unit behaves as expected.

  • Build the system by gradually increasing its complexity.

It is recommended that you build, simulate, and test your model incrementally. Start with an idealized, simplified model of your system, simulate it, verify that it works the way you expected. Then incrementally make your model more realistic, factoring in effects such as friction loss, motor shaft compliance, hard stops, and the other things that describe real-world phenomena. Simulate and test your model at every incremental step. Use subsystems to capture the model hierarchy, and simulate and test your subsystems separately before testing the whole model configuration. This approach helps you keep your models well organized and makes it easier to troubleshoot them.

System Configuration Errors

Missing Solver Configuration Block

Each topologically distinct Simscape block diagram requires exactly one Solver Configuration block to be connected to it. The Solver Configuration block specifies the global environment information and provides parameters for the solver that your model needs before you can begin simulation.

If you get an error message about a missing Solver Configuration block, open the Simscape Utilities library and add the Solver Configuration block anywhere on the circuit.

Extra Fluid or Gas Properties Block

If your model contains hydraulic elements, each topologically distinct hydraulic circuit in a diagram requires a Custom Hydraulic Fluid block (or Hydraulic Fluid block, available with Simscape Fluids™ block libraries) to be connected to it. These blocks define the fluid properties that act as global parameters for all the blocks connected to the hydraulic circuit. If no hydraulic fluid block is attached to a loop, the hydraulic blocks in this loop use the default fluid. However, more than one hydraulic fluid block in a loop generates an error.

Similarly, more than one Thermal Liquid Settings (TL) block in a thermal liquid circuit, Two-Phase Fluid Properties (2P) block in a two-phase fluid circuit, or Gas Properties (G) block in a gas circuit generates an error.

If you get an error message about too many domain-specific global parameter blocks attached to the network, look for an extra Hydraulic Fluid block, Custom Hydraulic Fluid block, Thermal Liquid Settings (TL) block, Two-Phase Fluid Properties (2P) block, or Gas Properties (G) block and remove it.

Missing Reference Block

Simscape libraries contain domain-specific reference blocks, which represent reference points for the conserving ports of the appropriate type. For example, each topologically distinct electrical circuit must contain at least one Electrical Reference block, which represents connection to ground. Similarly, hydraulic conserving ports of all the blocks that are referenced to atmosphere (for example, suction ports of hydraulic pumps, or return ports of valves, cylinders, pipelines, if they are considered directly connected to atmosphere) must be connected to a Hydraulic Reference block, which represents connection to atmospheric pressure. Mechanical translational ports that are rigidly clamped to the frame (ground) must be connected to a Mechanical Translational Reference block, and so on.

If you get an error message about a missing reference block, or node, check your system configuration and add the appropriate reference block based on the rules described above. The missing reference node diagnostic messages include information about the particular block and variable that needs a reference node. This is especially helpful when multiple domains are involved in the model. For more information and examples of best modeling practices, see Grounding Rules.

Basic Errors in Physical System Representation

Physical systems are represented in the Simscape modeling environment as Physical Networks according to the Kirchhoff's generalized circuit laws. Certain model configurations violate these laws and are therefore illegal. There are two broad violations:

  • Sources of domain-specific Across variable connected in parallel (for example, voltage sources, hydraulic pressure sources, or velocity sources)

  • Sources of domain-specific Through variable connected in series (for example, electric current sources, hydraulic flow rate sources, force or torque sources)

These configurations are impossible in the real world and illegal theoretically. If your model contains such a configuration, upon simulation the solver issues an error followed by a list of blocks, as shown in the following example.

Example.  The model shown in the following illustration contains two Ideal Translational Velocity Sources connected in parallel. This produces a loop of independent velocity sources, and the solver cannot construct a consistent system of equations for the circuit.

When you try to simulate the model, the solver issues an error message with links to the Ideal Translational Velocity Source and Ideal Translational Velocity Source1 blocks. To fix the circuit, you can either replace the two velocity sources by a single Ideal Translational Velocity Source block, or add a Translational Damper block between them.

Numerical Simulation Issues

Numerical simulation issues can be either a result of certain circuit configurations or of parameter discontinuities.

Dependent Dynamic States

Certain circuit configurations can result in dependent dynamic states, or the so-called higher-index differential algebraic equations (DAEs). Simscape solver can handle dependencies among dynamic states that are linear in the states and independent of time and inputs to the system. For example, capacitors connected in parallel or inductors connected in series will not cause any problems. Other circuit configurations with dependent dynamic states, in certain cases, may slow down the simulation or lead to an error when the solver fails to initialize.

Problems may occur when dynamic states have a nonlinear algebraic relationship. An example is two inertias connected by a nonlinear gear constraint, such as an elliptical gear. In case of simulation failure, the Simscape solver may be able to identify the components involved, and provide an error message with links to the blocks and to the equations within each block.

Parameter Discontinuities

Nonlinear parameters, dependent on time or other variables, may also lead to numerical simulation issues as a result of parameter discontinuity. These issues usually manifest themselves at the transient initialization stage (see Transient Simulation Issues).

Initial Conditions Solve Failure

The initial conditions solve, which solves for all system variables (with initial conditions specified on some system variables), may fail. This has several possible causes:

  • System configuration error. In this case, the Simulation Diagnostics window usually contains additional, more specific, error messages, such as a missing reference node, or a warning about the component equations, followed by a list of components involved. See System Configuration Errors for more information.

  • Dependent dynamic state. In this case, the Simulation Diagnostics window also may contain additional, more specific, error messages, such as a warning about the component equations, followed by a list of components involved. See Dependent Dynamic States for more information.

  • The residual tolerance may be too tight to produce a consistent solution to the algebraic constraints at the beginning of simulation. You can try to increase the Consistency Tolerance parameter value (that is, relax the tolerance) in the Solver Configuration block.

If the Simulation Diagnostics window has other, more specific, error messages, address them first and try rerunning the simulation. See also Troubleshooting Tips and Techniques.

Transient Simulation Issues

Transient initialization happens at the beginning of simulation (after computing the initial conditions) or after a subsequent event, such as a discontinuity (for example, when a hard stop hits the stop). It is performed by fixing all dynamic variables and solving for algebraic variables and derivatives of dynamic variables. The goal of transient initialization is to provide a consistent set of initial conditions for the next transient solve step.

Transient Initialization Not Converging

Error messages stating that transient initialization failed to converge, or that a set of consistent initial conditions could not be generated, indicate transient initialization issues. They can be a result of parameter discontinuity. Review your model to find the possible sources of discontinuity. See also Troubleshooting Tips and Techniques.

You can also try to decrease the Consistency Tolerance parameter value (that is, tighten the tolerance) in the Solver Configuration block.

Step-Size-Related Errors — Dependent States — High Stiffness

A typical step-size-related error message may state that the system is unable to reduce the step size without violating the minimum step size for a certain number of consecutive times. This error message indicates numerical difficulties in solving the Differential Algebraic Equations (DAEs) for the model. This might be caused by dependent dynamic states (higher-index DAEs) or by the high stiffness of the system. You can try the following:

  • Tighten the solver tolerance (decrease the Relative Tolerance parameter value in the Configuration Parameters dialog box)

  • Specify a value, other than auto, for the Absolute Tolerance parameter in the Configuration Parameters dialog box. Experiment with this parameter value.

  • Tighten the residual tolerance (decrease the Consistency Tolerance parameter value in the Solver Configuration block)

  • Increase the value of the Number of consecutive min step size violations allowed parameter in the Configuration Parameters dialog box (set it to a value greater than the number of consecutive step size violations given in the error message)

  • Review the model configuration and try to simplify the circuit, or add small parasitic terms to your circuit to avoid dependent dynamic states. For more information, see Numerical Simulation Issues.