simscape.multibody.Multibody class

Package: simscape.multibody
Superclasses: simscape.multibody.Component

Specify structure of multibody system

Since R2022a

Description

Use an object of the simscape.multibody.Multibody class to construct a multibody system. A Multibody object is a hierarchical container that can have any type of component object, and each component object represents a part or a subsystem of the multibody system. See simscape.multibody.Component for more information about different component objects.

By default, a newly created Multibody object is empty. You can use the methods of the Multibody object to construct a multibody system, prepare the Multibody object for analyses, or create a corresponding Simulink^® model. See the More About section for more information about the Multibody class.

The simscape.multibody.Multibody class is a handle class.

Class Attributes

Sealed	true
ConstructOnLoad	true
HandleCompatible	true
RestrictsSubclassing	true

For information on class attributes, see Class Attributes.

Creation

Description

mb = simscape.multibody.Multibody creates an empty simscape.multibody.Multibody object.

Properties

ComponentNames — Names of top-level component objects in multibody system

[ ] (default) | string array

Names of the component objects at the top level of the simscape.multibody.Multibody object, returned as a string array.

Example: "Base_Bar"

Attributes:

GetAccess	public
SetAccess	Restricts access
NonCopyable	true
Transient	true

Gravity — Gravitational acceleration

[0 0 -9.80655]' : m/s^2 (default) | simscape.Value object

Gravitational acceleration in the multibody system, specified as a simscape.Value object that represents a 3-by-1 or 1-by-3 vector with a unit of linear acceleration. The elements of the vector specify the gravity in the x, y, and z directions of the world frame. In a hierarchical simscape.multibody.Multibody object, the Gravity property of the higher-level Multibody object overrides the Gravity property of its contained Multibody objects.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true
Transient	true

Methods

Public Methods

addComponent	Add component object to Multibody object
addConnector	Add connector to Multibody object
compile	Compile Multibody object
component	Extract component object from Multibody object
componentPaths	Return paths of component objects in Multibody object
connect	Link two connectors in Multibody object
connectVia	Link two connectors in Multibody object via intermediate object
jointPrimitivePaths	Return paths of joint primitives in Multibody object at all hierarchical levels
makeBlockDiagram	Create Simulink model from Multibody object
removeConnector	Remove existing connector from Multibody object

Specialized Operators and Functions

These methods specialize standard MATLAB^® operators and functions for objects in this class.

disp	Prints the name and type of the connectors and components in the top level of the simscape.multibody.Multibody object.

More About

Construction of a Mechanical System

By default, a newly created simscape.multibody.Multibody object is empty and has zero connectors. To construct a multibody system, use the addComponent method to add objects to the Multibody object, then connect the objects using the connect or connectVia method. Each object represents a part or a subsystem of the multibody system.

To manage the complexity of a large multibody system, you can use several Multibody objects to model the subsystems of a system. The image shows an example of a large multibody system, Robot.

Note that you must completely construct a Multibody object before adding it to a system. For example, in this example, you need to add the connectors hand and body to the Left_Arm object before adding it to the Robot object. To add the connectors, use the addConnector method.

To establish mechanical relationships between the three subsystems in the Robot system, connect the Body, Left_Arm, Right_Arm objects, as shown in the image, by using the connect or connectVia method.

Compilation

To analyze a multibody system, you need to successfully compile the simscape.multibody.Multibody object of the system by using the compile method. The compilation performs a thorough error checking for a Multibody object. If any error occurs, the compile method shows the problem. For example, if a Multibody object contains joint objects or simscape.multibody.RigidTransform objects that do not connect to the main structure of the Multibody object, the compilation fails. See compile and simscape.multibody.CompiledMultibody for more information about compilation and analysis methods.

Creating Simulink Models

To use the capabilities in Simscape Multibody that you cannot do programmatically, such as simulating a multibody system, create a Simulink model from a simscape.multibody.Multibody object by using the makeBlockDiagram method.

When you construct a multibody system programmatically, Simscape Multibody has a different approach to specify the state of the joint primitives in the system. Instead of specifying the state through joint targets in joint blocks, the programmatic way uses the simscape.op.OperatingPoint object to specify state targets for joint primitives. Therefore, when you create a Simulink model from a Multibody object, the makeBlockDiagram method must have both the OperatingPoint object that specifies the joint states of the system and the Multibody object that defines the structure of the system. The makeBlockDiagram method uses the data in the OperatingPoint object to populate the joint target parameters for the joint blocks of the created Simulink model. Note that if the OperatingPoint object targets some joint primitives that do not exist in the Multibody object, those targets are ignored.

Tip

When setting up the targets of joint primitives, use the jointPrimitivePaths method to display the paths of primitives in Multibody object.

After you create the Simulink model from a Multibody object, the model can be modified just like general Simulink models. However, a best practice is to avoid making changes in the Simulink model that you can make in the Multibody object. Make the changes in the code that generates the Multibody object, re-generate the object, and then re-create the Simulink model. This process allows you to keep the code as the main source for the model. However, some capabilities are not supported in the programmatic way, and so must be done in Simulink model. For example, you can specify input signals only in the Simulink model.

Version History

Introduced in R2022a