Documentation

Configuring Methods of Solution

Warning

This content is specific to Simscape™ Multibody™ First Generation software. First-generation features are slated to be deprecated and should be avoided.

In this section, you choose and configure the settings necessary to simulate mechanical motion with a Simscape Multibody model.

To gain a better understanding of how Simscape Multibody software solves for mechanical motion, see How Simscape Multibody Software Works and Improving Performance.

Defining Gravity

The most basic aspect of a machine's environment is the gravitational acceleration it experiences. You control a machine's gravity in the Parameters tab of its Machine Environment dialog.

Setting a Constant Gravitational Acceleration

A uniform gravity field is applied to the motion of every machine. The default is a constant vector of `[0 -9.81 0]` with units of meters/seconds2 and x-, y-, and z-components, respectively.

You can change this value to a different constant vector by modifying the entry in the Gravity vector field of the Parameters tab. You can change the units by using the units pull-down menu.

Introducing Gravity as an External Simulink Signal

In addition to constant gravity, you can apply a time-varying, spatially uniform, gravity vector through a Simulink® signal. You enable this option by selecting the Input gravity as signal check box in the Parameters tab.

Once you make this selection, the Machine Environment block acquires a Simulink inport to accept this Simulink signal. The signal must be a three-component vector. You can still change the units through the pull-down menu.

In general, you simulate machine motion in all three spatial dimensions. If a machine can move in only two dimensions, however, ignoring the third dimension makes the simulation more efficient. By default, the simulation automatically determines whether your machine moves in all three or only two dimensions and optimizes the simulation accordingly.

You can override this default by requiring simulation in either three or two dimensions. You choose the simulation dimension of a machine in the Machine dimensionality pull-down menu of the Parameters tab of the Machine Environment dialog. If you attempt to simulate a three-dimensional machine in two dimensions, the simulation stops with an error.

Requirements for Two-Dimensional Simulation

Your machine must meet certain criteria before you can require simulation in two dimensions:

• The prismatic primitives must define a set of parallel planes.

• The revolute primitives must rotate about axes perpendicular to the prismatic planes.

The bodies of a two-dimensional machine do not all have to lie in a single plane, but they should slide and rotate only in parallel planes.

Code Generated from Two-Dimensional Models

Code generated from simulations restricted to two-dimensional motion is also restricted to two-dimensional motion. See Restrictions on Two-Dimensional Simulation.

Blocks That Require Three-Dimensional Simulation

The Simscape Multibody library contains certain blocks that, if you use them in a machine, require you to simulate in three dimensions.

• Any Joint block with more than two prismatic primitives, more than one revolute primitive, or any spherical primitives

• Disassembled Joints

• Massless connectors

Choosing an Analysis Mode

You can analyze motion in a Simscape Multibody model with these analysis types.

Analysis ResultAnalysis Type
Motion that results from applying forcesForward dynamics
Effect of slightly perturbing the motionLinearization
Forces required to produce a specified motionInverse dynamics

The Parameters tab of the Machine Environment dialog allows you to choose the analysis mode you want to simulate in. You make this choice via the Analysis mode pull-down menu. In the case of linearization, use the Linearization tab to set the size of the small perturbations.

By choosing one of these analysis modes, you implement the type of motion analysis you want.

Analysis TypeAnalysis ModeDescription
Forward dynamicsForward DynamicsComputes the positions and velocities of a system's bodies at each time step, given the initial positions and velocities of its bodies and any forces applied to the system.
LinearizationForward DynamicsComputes the effect of small perturbations on system motion through the Simulink `linmod` command.
TrimmingTrimmingEnables the Simulink `trim` command to compute steady-state solutions of system motion.
Inverse dynamics (open-loop)Inverse DynamicsComputes the forces required to produce a specified velocity for each body of an open-loop system.
Inverse dynamics (closed-loop)KinematicsComputes the forces required to produce a specified velocity for each body of a closed-loop machine.

Forward Dynamics Mode

Use this mode to simulate a model that represents the initial positions and velocities of the system's bodies and the forces on those bodies.

Run these examples in the Forward Dynamics mode:

Trimming Mode

Use this mode to allow you to run the Simulink `trim` command on your model. The `trim` command allows you to find steady-state solutions for your model.

Trimming mode inserts a subsystem and an output port at the top level of your model. These blocks output signals corresponding to the constraints on the system represented by your model. Configure the `trim` command to find equilibrium points where the constraint signals are zero. This ensures that the equilibrium points found by the `trim` command satisfy the constraints on the modeled system.

See Trimming Mechanical Models for examples of using this mode to find the equilibrium points of a mechanical system.

To Linearize a Machine's Motion

You can determine the effect of small perturbations on system motion by linearizing your machine. To linearize, set the analysis mode to Forward Dynamics and run the Simulink `linmod` command on your model.

You can fix the size of the perturbation or let the simulation find an optimal perturbation for you. Enter these settings in the Linearization tab of the Machine Environment dialog.

See Linearizing Mechanical Models for examples of using this mode to find the effect of small perturbations on mechanical motion.

Inverse Dynamics Mode

Use this mode to simulate an open-loop system whose model specifies the velocity of every degree of freedom of every body at every time step.

See Inverse Dynamics Mode with a Double Pendulum for an example of using this mode to find the forces on an open-loop system.

Kinematics Mode

Use this mode to simulate a closed-loop machine whose model specifies the velocity of every independent degree of freedom at every time step. The tolerancing constraint solver is recommended in this mode. (See Maintaining Constraints.)

See Kinematics Mode with a Four Bar Machine for an example of using this mode to find the forces on a closed-loop machine.

Hierarchy of Solvers and Tolerances

Simulating your Simscape Multibody model is a cooperative effort between Simscape Multibody software and Simulink. A Simscape Multibody simulation interprets your machine's purely mechanical aspects through machine assembly and a constraint solver. Simulink controls the purely mathematical aspects of the simulation through your chosen Simulink solver. Together, they try to harmonize your choices of Simulink solver and solver tolerances, constraint solver and solver tolerances, and assembly tolerances in this dynamic hierarchy:

Controlling Machine Assembly

The linear and angular assembly tolerances specify the precision with which

• A model must specify the initial locations and angles of a machine's joints.

• A simulation must solve the initial positions and angles of a machine's unassembled joints.

The Parameters tab of a machine's Machine Environment dialog allows you to change the default assembly tolerances in the Linear assembly tolerance and Angular assembly tolerance fields. You can also adjust the linear and angular units in the respective pull-down menus.

For more about machine assembly and assembly tolerances, see the sections Modeling Degrees of Freedom and Modeling Disassembled Joints.

How Assembly Tolerances Work

A Simscape Multibody simulation checks the locations and angles of a machine's assembled joints when it initializes the model and later in the simulation. If any of the joint locations or angles fails to meet the corresponding assembly tolerances, Simulink halts the simulation and displays an error message. If this happens, you should check your machine to ensure that it specifies the locations and angles of its assembled joints to the precision specified in the Parameters tab. If not, either change the locations and angles that fail to meet the assembly tolerances or increase the tolerances themselves.

Assembly tolerances can also be violated during the course of a simulation by insufficiently accurate constraint and motion solvers. See Maintaining Constraints and Configuring a Simulink Solver.

Maintaining Constraints

If your model contains implicit or explicit constraints on a machine's motion, the Simscape Multibody simulation uses a constraint solver to find a solution for the motion that satisfies those constraints.

This section describes how the constraint solvers work and what you need to decide to make proper use of them. These constraint choices and settings for a machine are found on the Constraints tab of its Machine Environment dialog.

The simulation imposes constraints when it initializes the model, then later checks if the constraints remain satisfied during the simulation. If any of the degrees of freedom (DoFs) fail to satisfy the constraint tolerances, Simulink halts the simulation and displays an error message. If this happens, you should either switch to a looser constraint solver or increase the constraint tolerances (if you have manual control of the constraint tolerance).

Constraints can also be violated during the course of a simulation by an insufficiently accurate Simulink solver. See Configuring a Simulink Solver.

Origins of Mechanical Constraints

The need to impose constraints on a machine's motion arises in two ways, explicit or implicit. In either case, motion is restricted to a subspace of DoFs.

• Imposing a time-independent or time-dependent mechanical constraint on a system's DoFs. This requires you to insert a Constraint or Driver block that restricts the motion represented by a Joint.

• Cutting closed loops in a Simscape Multibody block diagram. Each closed loop is cut at one Joint, Constraint, or Driver block. The simulation internally replaces the cut block with an implicit constraint equivalent to the original closed loop.

Marking Automatically Cut Joints.  Selecting the Mark automatically cut joints check box in the Simscape Multibody 1G node of your model's Configuration Parameters dialog causes Simulink to mark the icons of any Joint blocks in closed loops that it cuts during simulation of the model. By default, the check box is not selected.

Cut Joint X Mark

Projecting the Motion on to the Constraint Manifold

The space of motion allowed to the DoFs by the constraints, or constraint manifold K, is a subspace of the full space Q of DoFs. (Q includes both coordinates and their velocities.) A Simscape Multibody simulation initializes your model by projecting the initial state of its machines on to K. During simulation, the constraints ensure that the motion remains on K, and Simulink solves for the motion only in the constrained subspace.

The projection cannot be done with infinite precision, but only within the constraint tolerance. Your constraint settings determine the method and precision of projection.

Constraint Manifold as a Subspace of DoFs

Identifying and Eliminating Redundant Constraints

It is possible for you or the simulation to overspecify constraints. Simulation proceeds if the extra or redundant constraints are consistent with the others, but having redundant constraints always runs the risk of inconsistency, which leads to the simulation halting with errors.

Several checks identify and eliminate redundant constraints, both at the start of and during the simulation.

• You can enable a warning to indicate if a small perturbation to the model initial state changes the number of constraints.

• You can enable a warning to indicate if your model is subject to redundant constraints, whether they conflict or not.

• You can specify how similar constraints have to be before they are treated as redundant, or you can let the simulation decide for you.

See Configuring Simscape Multibody Simulation Diagnostics and the Constraints tab of the Machine Environment block.

Comparing and Choosing Constraint Solvers

Each constraint solver has advantages and disadvantages relative to the others, subject to the fundamental tradeoff of accuracy and speed.

Constraint SolverToleranceComputational CostAccuracySimulation Speed
StabilizingDynamic attractorLowestLowestFastest
Machine PrecisionTolerance ~ `eps`HighestHighestSlowest

Stabilizing Constraint Solver

This solver adds a self-correcting term to the equations of motion that stabilizes the solution by causing it to evolve toward, rather than drift away from, the constraint manifold K. It is the least accurate of the constraint solvers.

Simscape Multibody simulations use this solver by default. It is typically faster than the other solvers, but it can settle into a solution that exceeds the machine's assembly tolerances. If assembly tolerance errors occur during the simulation, use one of the other constraint solvers instead.

Tolerancing Constraint Solver

This solver finds the system's motion while imposing the constraints to the tolerance that you specify. Specifically, the solver stops refining the solution when the difference between two successive solutions satisfies the condition

|error| < max(|rtol * x|, atol)

where error is the difference between successive solutions, rtol is the relative constraint tolerance, x is the motion to be solved, and atol is the absolute constraint tolerance.

Use this solver you plan to run the simulation in Kinematics mode. It is more accurate than the stabilizing solver, but less accurate than the machine precision solver, with a computational cost between the two.

Setting Constraint Tolerances.  If you use the tolerancing solver, the constraint tolerances maintained during simulation are under your control. You can view and change the constraint tolerances in the Constraints tab of the Machine Environment dialog.

Machine-Precision Constraint Solver

This solver imposes the constraints to the numerical precision of the computer on which the simulation is running. Select this solver if you want to obtain the most accurate simulation permitted by the computer, regardless of simulation time or computational cost. It is the most accurate of the solvers and typically the slowest.

A Simscape Multibody model uses one of the ordinary differential equation (ODE) solvers of Simulink to solve a system's equations of motion, typically in tandem with a constraint solver (see Maintaining Constraints).

Simulink provides an extensive suite of ODE solvers that represent the most advanced numerical techniques available for solving differential equations in general and equations of motion in particular. The Solver node of your model's Configuration Parameters dialog allows you to select any of these solvers for use by Simulink in solving the model's dynamics. See the Simulink documentation for more details about choosing a Simulink solver.

• By default, Simulink uses a variable-step solver, whose accuracy is controlled by setting its absolute and relative tolerances.

• You can also use a fixed-step solver, whose accuracy is controlled by setting the time step.

See Improving Performance for further details on variable- versus fixed-step solvers.

By default, Simulink automatically determines the absolute tolerance used by ODE solvers. The resulting tolerance might not be small enough for a mechanical system, particularly a nonlinear or chaotic system. Try running a simulation with the relative tolerance set to `1e-3` (the default) and the absolute tolerance set to `1e-4`. Then increase the tolerances if the simulation takes too long or decrease them if the solution is not sufficiently accurate.

Solver Tolerances and Stiction

If your model contains one or more Joint Stiction Actuator blocks, you must also take into account the velocity thresholds of these blocks when setting the absolute tolerance of the ODE solver. If the absolute tolerance of the solver is greater than a joint's velocity threshold, the simulation might never detect the locking or unlocking of a joint. To prevent this from happening, set the absolute tolerance to be no more than 10% of the size of the smallest stiction velocity threshold in your model.

Avoiding Simulation Failures

You can anticipate and avoid many types of simulation failure by the following adjustments. You make them in the Simscape Multibody 1G subnode of your model's Configuration Parameters dialog and the Constraints tab of a machine's Machine Environment dialog.

See How Simscape Multibody Software Works and Troubleshooting Simulation Errors for further information about identifying and recovering from simulation errors. See Maintaining Constraints for more about constraints.

Configuring Simscape Multibody Simulation Diagnostics

Certain Simscape Multibody diagnostics help you understand and, if necessary, troubleshoot simulation problems. You can adjust these diagnostics in the Diagnostics area of the Simscape Multibody 1G node.

Warning on Redundant Constraints.  Selecting the Warn if machine contains redundant constraints check box triggers a warning if there are more constraints than necessary in your model. This situation by itself does not cause simulation errors. But in certain configurations, too many constraints might lead to conflicts and thus to errors during the course of the simulation.

By default, the check box is selected.

Warning on Unstable Constraints in Initial State.  Selecting the Warn if number of initial constraints is unstable check box triggers a warning if small changes to your model's initial state leads to changes in the number of constraints. In certain configurations, this instability can lead to too few or too many (conflicting) constraints on your system and prevent the simulation from finding a solution for the motion.

By default, the check box is not selected.

Handling Motion Singularities

At certain simulation times, one or more degrees of freedom in a mechanical system might change quickly compared to the others. If these sudden, quick motions are too fast compared to the slower motions, the Simulink solver has difficulty finding an accurate solution in a reasonable simulation time. Imposing constraints on the motion often exacerbates this problem. In extreme cases, the simulation can stop with an error.

You can alleviate these motion singularities by selecting the Use robust singularity handling on the Constraints tab of the Machine Environment dialog. This option requires extra computation whether or not singularities exist. Select it only if you cannot find a Simulink solver that solves your model in a reasonable amount of time without it.

See Maintaining Constraints and Configuring a Simulink Solver for more discussion of motion singularities and their relationship to the Simulink solvers.