simscape.multibody.Multibody Class

R2026b

Namespace: 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.

example

Properties

expand all

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

Methods

expand all

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
`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 connectors, components, and connections in the top level of the simscape.multibody.Multibody object.

Examples

collapse all

Double Pendulum

Open Live Script

This example shows how to assemble instances of a modularly designed link into a double pendulum. This double pendulum moves in the x-y plane of the world frame.

To avoid typing the namespace name for the classes, you can use the import function.

import simscape.Value simscape.op.* simscape.multibody.*;

Construct a Double Pendulum

Create a simscape.multibody.Multibody object to construct the double pendulum. By default, a newly created Multibody object is empty.

doublePendulum = Multibody

doublePendulum = 
  Multibody:

  No connectors.

  No components.

  No connections.

  Multibody with properties:

     ComponentNames: [0×1 string]
    FrameConnectors: [0×1 string]

Create two links by using the custom function described in the Link Creation Function section. To add the links to the doublePendulum object, you can use the addComponent method. The upper link has a length of 12 cm and the red color. The lower link has a length of 8 cm and the blue color. The two links have rectangular shapes with the default density.

upperLength = Value(12,"cm");
lowerLength = Value(8,"cm");
addComponent(doublePendulum,"Upper_Link",link(upperLength,[1 0 0]));
addComponent(doublePendulum,"Lower_Link",link(lowerLength,[0 0 1]));

Create two revolute joints by using the simscape.multibody.RevoluteJoint class. You can use these joints to connect the upper and lower links.

joint = RevoluteJoint;
addComponent(doublePendulum,"World_Upper_Joint",joint);
addComponent(doublePendulum,"Upper_Lower_Joint",joint);

Add the world frame to the doublePendulum object and connect the positive end of the upper link to the world frame via the revolute joint named World_Upper_Joint. To make the connection, you can use the connectVia function.

addComponent(doublePendulum,"World",WorldFrame);
connectVia(doublePendulum,"World_Upper_Joint","World/W","Upper_Link/pos_end");

Connect the positive end of the lower link to the negative end of the upper link via the revolute joint named Upper_Lower_Joint.

connectVia(doublePendulum,"Upper_Lower_Joint","Upper_Link/neg_end","Lower_Link/pos_end");

To specify the initial position for the upper link, you can use a simscape.op.OperatingPoint object and a simscape.op.Target.

op = OperatingPoint;
op("World_Upper_Joint/Rz/q") = Target(60,"deg","High");

To see the components in the doublePendulum object, you can type:

doublePendulum

doublePendulum = 
  Multibody:

  No connectors.

  Components:

  Name                 Type          
  ___________________  ______________

  "Lower_Link"         Rigid Body    
  "Upper_Link"         Rigid Body    
  "Upper_Lower_Joint"  Revolute Joint
  "World"              World Frame   
  "World_Upper_Joint"  Revolute Joint

  Connections:

  Connector 1           Connector 2          
  ____________________  _____________________

  "Lower_Link/pos_end"  "Upper_Lower_Joint/F"
  "Upper_Link/neg_end"  "Upper_Lower_Joint/B"
  "Upper_Link/pos_end"  "World_Upper_Joint/F"
  "World/W"             "World_Upper_Joint/B"

  Multibody with properties:

     ComponentNames: [5×1 string]
    FrameConnectors: [0×1 string]

Link Creation Function

You can use this function to create a link with specific length and color. Frames at the ends of the link are always exposed as connectors for connections to joints. See more information about creating a link, see Simple Link.

function link = link(length,color)

    import simscape.Value simscape.multibody.*;

    link = RigidBody;
    offset = length/2;
    addFrame(link,"neg_end","reference",RigidTransform(StandardAxisTranslation(offset,"-X")));
    addFrame(link,"pos_end","reference",RigidTransform(StandardAxisTranslation(offset,"+X")));

    % Add component
    genExtrusion_geom_cs = roundedRect(length,Value(2,"cm"));
    genExtrusion_geom_length = Value(1,"cm");
    genExtrusion_viz = SurfaceGraphic(SimpleVisualProperties(color));
    solid = UniformSolid(GeneralExtrusion(genExtrusion_geom_cs, genExtrusion_geom_length, genExtrusion_viz),...
                Value(1000, 'kg/m^3'));
    addComponent(link,"Body","reference",solid);

    % Connectors
    addConnector(link,"neg_end");
    addConnector(link,"pos_end");

end

function xs = roundedRect(length,width)
% Return the cross section of a rectangle with rounded ends
    angles = (-90:10:+90)'*pi/180;
    semi = width/2*[cos(angles) sin(angles)]+repmat([length/2 0],size(angles));
    xs = [semi;-semi];
end

More About

expand all

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.

Multibody System Illustration

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.

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

simscape.multibody.Multibody Class

Description

Class Attributes

Creation

Description

Properties

`ComponentNames` — Names of top-level component objects in multibody system
[ ] (default) | string array

Attributes:

Methods

Public Methods

Specialized Operators and Functions

Examples

Double Pendulum

More About

Construction of a Mechanical System

Compilation

Creating Simulink Models

Version History

See Also

Topics

simscape.multibody.Multibody Class

Description

Class Attributes

Creation

Description

Properties

ComponentNames — Names of top-level component objects in multibody system [ ] (default) | string array

Attributes:

Methods

Public Methods

Specialized Operators and Functions

Examples

Double Pendulum

More About

Construction of a Mechanical System

Compilation

Creating Simulink Models

Version History

See Also

Topics

`ComponentNames` — Names of top-level component objects in multibody system
[ ] (default) | string array