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.

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.

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/seconds^{2} 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.

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.

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 simulations restricted to two-dimensional motion is also restricted to two-dimensional motion. See Restrictions on Two-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

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

Analysis Result | Analysis Type |
---|---|

Motion that results from applying forces | Forward dynamics |

Steady-state motion | Trimming |

Effect of slightly perturbing the motion | Linearization |

Forces required to produce a specified motion | Inverse 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 Type | Analysis Mode | Description |
---|---|---|

Forward dynamics | Forward Dynamics | Computes 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. |

Linearization | Forward Dynamics | Computes the effect of small perturbations on system motion
through the Simulink `linmod` command. |

Trimming | Trimming | Enables the Simulink `trim` command
to compute steady-state solutions of system motion. |

Inverse dynamics (open-loop) | Inverse Dynamics | Computes the forces required to produce a specified velocity for each body of an open-loop system. |

Inverse dynamics (closed-loop) | Kinematics | Computes the forces required to produce a specified velocity for each body of a closed-loop machine. |

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:

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.

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.

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.

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.

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:

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.

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.

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.

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**

The space of motion allowed to the DoFs by the constraints,
or *constraint manifold* ** K**, is
a subspace of the full space

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**

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.

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

Constraint Solver | Tolerance | Computational Cost | Accuracy | Simulation Speed |
---|---|---|---|---|

Stabilizing | Dynamic attractor | Lowest | Lowest | Fastest |

Tolerancing | Open to your control | Intermediate | Intermediate | Intermediate |

Machine Precision | Tolerance ~ `eps` | Highest | Highest | Slowest |

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.

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.

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.

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.

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.

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.

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.

Was this topic helpful?