Learn more about SimMechanics

Machine Environment - Set up mechanical environment for machine

Library

Bodies

Description

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

Caution A SimMechanics model consists of one or more machines. A machine is a complete, connected diagram of SimMechanics blocks topologically distinct from other complete SimMechanics 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 SimMechanics 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/s² (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 SimMechanics 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 Mode	Description
`Forward dynamics`	Computes the positions and velocities of the system's bodies, given forces, torques, and initial conditions. This is the default mode.
`Inverse dynamics`	Computes the forces and torques required to produce the specified motions of an open machine.
`Kinematics`	Computes the forces and torques required to produce the specified motions of a closed-loop machine.
`Trimming`	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 SimMechanics 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 Type	Description
`Stabilizing`	Adds a self-correcting term to the dynamics that stabilizes the numerical solution so that it drifts toward the constraint manifold. This is the default.
`Tolerancing`	Solves 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 SimMechanics 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 SimMechanics 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].