Machine Environment

Mechanical simulation parameters of a machine


First Generation/Bodies



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

The Machine Environment block allows you to view and change the mechanical environment settings for one machine in your model.


A Simscape Multibody model consists of one or more machines. A machine is a complete, connected diagram of Simscape Multibody blocks topologically distinct from other complete Simscape Multibody block diagrams. Each machine must have one or more Ground blocks.

A machine can be a composite of submachines connected by Shared Environment blocks. Each submachine must have one or more Ground blocks.

Exactly one Ground per machine, simple or composite, must be connected to a Machine Environment block for your Simscape Multibody model to be valid.

This block determines the following settings for the machine:

  • How to simulate the machine

  • How to interpret mechanical constraints

  • How to linearize the simulation

  • Whether and how to display the machine in visualization

The Machine Environment Port and Connecting the Block

You connect this block to a Ground by enabling that Ground's Machine Environment port from the Ground dialog.

Gravity as a Simulink Signal

This block also allows you to input gravity as a variable Simulink® signal. If you choose to do this, a Simulink inport > also appears on the block for connection to a three-component Simulink signal line.

Opening the Simulink Configuration Parameters Dialog

You can open the Simulink Configuration Parameters dialog for viewing and editing by clicking the Configuration Parameters button on the lower left of the block dialog.

Dialog Box and Parameters

In the lower half of its dialog, the Machine Environment block has four active tabs that you can view and modify after selecting the corresponding tabs. You can apply your settings at any time by clicking Apply or OK.

 Restricted Parameters

Configuring the Dynamics

In this tab, you configure settings that control the mechanical dynamics.

Gravity vector

The value of this parameter is a MATLAB® vector that specifies the magnitude and direction of gravitational acceleration in the model's world coordinate system. It must be a three-component vector. The default vector is [0 -9.81 0]. This field is disabled if you choose to input gravity as a signal.

The default units are m/s2 (meters per square second). Use the pull-down menu to the right if you want to reset the units.

Input gravity as signal

Select this check box if you want to disable the Gravity vector field and instead input gravity as a variable Simulink signal. The default is not selected.

If you select this check box, a Simulink inport appears on the block in addition to the existing Machine Environment port. You input the gravity vector as a three-component Simulink signal to this port. The components are, respectively, x, y, and z.

Machine dimensionality

In the pull-down menu, select in how many dimensions you want to simulate your machine: in 3D Only or 2D Only, or let the Simscape Multibody simulation choose for you with Auto. The default is 3D Only.

You must take care, if you choose 2D Only, that the machine actually moves in only two dimensions. If it does not, the simulation stops with an error.

Analysis mode

Specifies the type of analysis to be performed during the simulation. Choose one from the pull-down menu.

Analysis ModeDescription
Forward dynamicsComputes the positions and velocities of the system's bodies, given forces, torques, and initial conditions. This is the default mode.
Inverse dynamicsComputes the forces and torques required to produce the specified motions of an open machine.
KinematicsComputes the forces and torques required to produce the specified motions of a closed-loop machine.

Variant of Forward Dynamics mode to be used with the Simulink trim command. Determines steady-state or other points in system state space.

Linear assembly tolerance

Maximum position error allowed between bodies connected by prismatic joints. The default is 1e-3 m. Use the menu on the right to set the units.

Angular assembly tolerance

Maximum angular error allowed between bodies connected by revolute joints. Default is 1e-3 rad. Use the menu on the right to set the units.

 Tunable Parameters

Implementing Constraints

In this tab, you tell the Simscape Multibody simulation how to interpret mechanical constraints in machines that contain blocks from the Constraints & Drivers library; cut Joint, Constraint, and Driver blocks in closed loops; or both.

Constraint solver type

Type of solver used to solve constraints on the mechanical system's states. Choose one from the pull-down menu.

Solver TypeDescription
StabilizingAdds a self-correcting term to the dynamics that stabilizes the numerical solution so that it drifts toward the constraint manifold. This is the default.
TolerancingSolves the constraints on the system's states to a specified degree of accuracy.
Machine precision Solves the constraints to the numerical precision of the computer on which the simulation is running.
Relative tolerance

The relative tolerance used by the tolerancing constraint solver to determine when to stop refining a solution. Default is 1e-4.

Enabled only if Constraint solver type is set to Tolerancing.

Absolute tolerance

The absolute tolerance used by the tolerancing constraint solver to determine when to stop refining the solution of a machine state. Default is 1e-4.

Enabled only if Constraint solver type is set to Tolerancing.

Use robust singularity handling

Select this check box if you want Simulink to take extra steps to handle singularities in a system's equations of motion. The default is not selected.

This option increases the computational cost of solving a system's equations of motion, regardless of whether they have singularities. Select this option only as a last resort, i.e., only if the Simulink solvers cannot otherwise solve the system's equations of motion or require an excessively long time to do so.

Redundant constraint tolerancing

Select Specify tolerance in this pull-down menu if you want to control how precisely the Simscape Multibody simulation distinguishes constraints. The default is Automatically select tolerance.

This option is important if you have two or more constraints that impose almost identical restrictions on the motion of your machine. More constraints means fewer degrees of freedom.

  • If two or more constraints are almost the same, the simulation eliminates one or more of them as redundant.

  • If the constraints are dissimilar enough, the simulation treats them as independent constraints.

Selecting Specify tolerance enables the Relative tolerance field.

Relative tolerance

The relative tolerance of redundant constraint analysis that the simulation implements. This field is enabled only if you select Specify tolerance in the Redundant constraint tolerancing pull-down menu. The default is 1e-14.

  • Making this tolerance larger means the simulation treats similar constraints as the same, i.e., redundant.

  • Making this tolerance smaller means the simulation treats similar constraints as distinct, i.e., not redundant.

Configuring Linearization

In this tab, you tell the simulation how to linearize your machine.

State perturbation type

Specifies the type of state perturbation used by linmod to linearize a machine. The default is Fixed.

  • Adaptive recomputes the size of the perturbation used at each step in the linearization process to ensure accurate computation of the linearization coefficients. It starts with the entry in the Perturbation size field as an initial guess.

  • Fixed uses the perturbation size specified in the Perturbation size field for every step.

Perturbation size

Specifies the relative size of the perturbation used by the Fixed perturbation option. Specifies the relative size of the initial guess perturbation used by the Adaptive perturbation type. The perturbation size is relative to the size of the state being perturbed. The default is 1e-5.

Configuring Machine Visualization

In this tab, you determine whether Simscape Multibody visualization displays this machine and choose the default body geometry (surface shape) and color for all the Bodies within the connected machine.

The machine inherits the model-wide defaults for body geometry and color. But you can change these machine-wide defaults to differ from the model-wide defaults.

Visualize machine

Select this check box if you want the machine to which this block is connected to appear in the visualization window. The default is selected.

Default body geometries

From the pull-down menu, select a machine-wide default body geometry.

  • Use model default body geometries (the default)

  • Convex hull from Body CS locations for convex hulls

  • Equivalent ellipsoid from mass properties for equivalent ellipsoids

Body color selection mode

From the pull-down menu, choose whether to use the model-wide default for the color of all Bodies in this machine (the default), or to specify a machine-wide default different from the model-wide default.

Default body color (RGB)

If you select Specify in the Body color selection mode pull-down menu, you can specify the machine-wide default body color in the field. You specify RGB values according to the MATLAB Graphics ColorSpec.

The default is [1 0 0].

See Also

Body, Ground, Shared Environment

See the relevant entries in the Glossary: constraint, dynamics, ground, kinematics, machine, machine precision constraint, stabilizing constraint, and tolerancing constraint.

Setting Up, Configuring, and Running Machines and Models

For more about Simscape Multibody models and machines, see Representing Machines with Models. For more about using Grounds and creating valid Simscape Multibody models, see Modeling Grounds and Bodies and Validating Mechanical Models. For more about modeling constraints, see Constraining and Driving Degrees of Freedom.

Visualizing Machines and Models

For more about configuring visualization for simulation, see Starting Visualization and Simulation.

Working Together with Simulink

For more about running Simscape Multibody software with Simulink, see Configuring Simscape Multibody Models in Simulink, Machine Settings via the Machine Environment Block, and Configuring Methods of Solution.

For more about configuring simulations in Simulink, consult the section on the Configuration Parameters dialog in the Simulink documentation.

Introduced before R2006a

Was this topic helpful?