# Tutorial: Co-Simulation with MotionSolve

Learn how to build a Multi-Body System Model (MBS) of an inverted pendulum, combine it with a controls system model, and co-simulate the models.

## Files for This Tutorial

Inverted_Pendulum_Tutorial.scm; Inverted_Pendulum_Tutorial.mdl

A finished version of the models you build in the tutorials along with any files required to complete the tutorials are available at this location: <installation_directory>/tutorial_models/

## Overview of Co-Simulation and Prerequisites

Co-simulation enables MotionSolve Multi-Body Dynamics (MBS) models and Activate models to communicate with each other during simulation.

An ideal use case for co-simulation is the development of a control system for an MBS model. This tutorial shows you how to develop such a control system for an inverted pendulum.

An inverted pendulum is a pendulum that has its center of mass above its pivot point, such as a pendulum moving horizontally with its pivot point mounted on a moving railroad cart. Whereas a normal pendulum is stable when hanging downward, an inverted pendulum is inherently unstable, and must be actively balanced in order to remain upright either by applying a torque at the pivot point or by moving the pivot point horizontally as part of a feedback system.

This tutorial shows you how to design a control force acting horizontally on a cart to keep a pendulum upright, much like a child balancing a stick on his hand. The inverted pendulum is a classic problem in dynamics and control theory and is used as a benchmark for testing control strategies. Some real-world examples of inverted pendulum problems include attitude control of a rocket at launch, and the balance and movement of a Segway motorized vehicle.

### Prerequisites

The installation of HyperWorks MotionSolve software is required for co-simulation. MotionSolve offers powerful modeling, analysis, visualization and optimization capabilities for multi-disciplinary simulations that include kinematics and dynamics, statics and quasi-statics, linear and vibration studies, stress and durability, loads extraction, co-simulation, effort estimation, and packaging synthesis.

## Defining the Software Path Settings

Defining the paths to MotionSolve and other software that is required for local and remote co-simulation methods.

1. From the File menu, select the Preferences button.
The Preferences dialog appears.
2. On the left column of the dialog, select the category, Activate Paths.
3. For each preference, enter an installation path, and click Apply.
Preference Path
MotionView <HyperWorks_install_path>/hwdesktop/hw/bin/platform
MotionSolve <HyperWorks_install_path>/hwsolvers/motionsolve/bin/platform
Python

(For HyperWorks 2021): <HyperWorks_install_path>/common/python/python3.5/platform

(For HyperWorks 2020): <HyperWorks install_dir>/hwdesktop/common/python/python3.5/platform

## Building an Inverted Pendulum

Build a Multi-Body System (MBD) model of an inverted pendulum on a cart.

Building this model requires basic knowledge of MotionView. Alternatively, you can load the completed model, Inverted_Pendulum_Tutorial.mdl, located in the tutorial_models directory of the Activate installation files, and skip this section of the tutorial.

### Entities in the MBS Model

• Pendulum
• Cart
• Rod to connect the pendulum to the cart
• Rail on which the cart is constrained to move horizontally
• Pivot which is located on the cart, between the pendulum and cart

### Building the Geometry

With MotionView software, create the geometry for the inverted pendulum.

1. Launch MotionView and create a new model.
2. Add three points of geometry to the model with the following names and locations:
Point X Y Z
PivotCenter 300 0 0
PendulumCenter 350 0 300
Z-Direction 400 0 600
3. Save your model as Inverted_Pendulum.mdl.

The rod connecting the pendulum to the cart is a massless body that you include as a graphic.
1. Insert a body entity and label it Cart.
2. For the Cart, set the CM Coordinates to the point PivotCenter.
3. Insert a second body entity and label it Pendulum.
4. For the Pendulum, set the CM Coordinates to the point PendulumCenter, and the Z-axis to the direction of point ZDirection.
5. Enter the following inertial properties for the bodies:
Body ID Mass (kg) Ixx(kg-mm^2) Iyy(kg-mm^2) Izz(kg-mm^2)
Cart b_0 0.45 100 100 100
Pendulum b_1 0.2 32 32 32

Add a revolute and translational joint to the model.

1. Insert a revolute joint, label it PendulumPivot, and set the Connectivity parameters as follows:
2. Set the Initial Conditions as follows:
3. Insert a translational joint, label it CartTranslation, and set the Connectivity parameters as follows:
4. Set the Initial Conditions as follows:

Graphics are essential for understanding the model behavior in an animation.

1. Insert a cylinder graphic and label it Rail.
2. For the Connectivity parameters, set the parent body to Ground Body; origin to Global Origin; and direction to vector Global X.
3. Set the Properties as follows:
4. Insert a sphere graphic, and label it Pendulum.
5. For Connectivity parameters, set the parent body to Pendulum, and set the origin to PendulumCenter.
6. For Properties, set the radius to 20.
7. Insert a cylinder graphic, and label it Rod.
8. For Connectivity parameters, set the parent body to Pendulum; set the origin to PendulumCenter; set the direction to the point PivotCenter.
9. Set the Properties as follows:
10. Insert a box graphic, and label it Cart.
11. For Connectivity parameters, set the Type to Center; set the Parent Body to Cart; set the Origin Point to PivotCenter; set the Z axis direction to Vector Global Z; set the ZX plane direction to Vector Global X.
12. Set the Properties as follows:

Apply translational forces to the Cart.

1. On the Connectivity tab, add the force, frc_0, label it Control Force, and set the Connectivity properties as follows:
2. On the Connectivity tab, add a second force, frc_1, label it PivotTorque, and set the Connectivity properties as follows:
3. Select File > Save As Model, and save your model with the name: Inverted_Pendulum_Tutorial.mdl.

## Modifying the MBS Model for Co-Simulation

Modify the basic MBS model for co-simulation by adding MotionView entities including solver arrays and solver variables.

The solver variables contain the individual plant input and output values. The solver arrays define the plant input and output to communicate with Activate.

1. Create two solver variables: ControlForce (varname: sv_0) and PivotTorque (varname: sv_1) as follows:
2. Connect the two solver variables to the forces you created in the previous section, Adding Forces.
As you see in the following figure, on the Trans Properties tab for ControlForce, for Fx, select Expression, and for f, enter: VARVAL({sv_0.id}). This expression specifies the ControlForce to be the first solver variable, sv_0. This variable sets the control signal sent from Activate to be the control force acting on the translational joint of the Cart.
3. Verify that the varnames match (sv_0): From the Expression Builder, select the solver variable by name and enter its ID as you see in the following figure:
4. On the Rot Properties tab for PivotTorque, for Ty, select Expression, and then for f, enter:VARVAL({sv_1.id}). This expression sets the PivotTorque as the second solver variable, sv_1, which specifies the control signal sent from Activate as the torque acting on the rotation of the pendulum.
5. Insert three additional solver variables: AngularDeviation, AngularRate and CartPosition.
6. For AngularDeviation, enter sv_2. For Type, select Expression, and enter: RTOD(AY({b_1.cm.idstring})), where b1 is the ID of the Pendulum body. Note that the AY function returns the Angle about the Y axis of the marker specified as the argument. The units of the angle are in radians, therefore, apply the RTOD function to convert Radians TO Degrees.
7. For Angular Rate, enter sv_3. For Type, select Expression, and enter:RTOD(WY({b_1.cm.idstring})), where b2 is the ID of the Pendulum body.
8. For Car Position, enter, sv_4. For Type, select Expression, and enter: DX({b_0.cm.idstring})-300, where b1 is the ID of the cart body.
9. Insert two solver arrays. Label them ControlInput and PlantOutput.
10. The ControlInput solver array includes both the PivotTorque and ControlForce solver variables. Set the properties as follows:
11. The PlantOutput solver array includes the following solver variables: AngularDeviation, AngularRate and CartPosition. Set the Plant Output properties as follows:
12. To help you select the proper solver variable names, click and a panel appears:
13. Save your model as Inverted_Pendulum_Tutorial.mdl.

### Validating the Inverted Pendulum Model

Simulate the MBS model in MotionSolve and validate that it performs as required.

1. From the Run panel, select: Save and run current model.
2. Select the folder icon, and enter a path and name for saving the MotionSolve model (XML file). The name is your choice, but a good practice is to use the same root name as your MotionView model. The solver run requires the XML file. When entering the path, note that the default directory of the tutorial may not be writable, and you may need to specify a different directory or change the write permissions on the directory.
3. From the Run panel, save your model as an XML file. This file is used for the solver run as well as the Activate model. Alternatively, you can run the MotionView .mdl file, and name it Inverted_Pendulum_Tutorial.xml.
4. Animate the results from the simulation and confirm that the model works as intended before continuing to the next steps. The controller is not yet connected to the model, therefore the input force and torque are zero.

## Building the Controls System Model

Build a controls system model with Activate.

Alternatively, you can load the completed model, Inverted_Pendulum_Tutorial.scm, located in the tutorial_models directory of the Activate installation files. If you load the model, skip the steps to Create the Diagram of the Activate Model, and move ahead to Simulating the Diagram.

The controls system model requires these blocks:

Block Description
MotionSolve Enables the embedding of a MotionSolve model into an Activate model.
Mux Reads multiple signals into one signal.
Demux Reads a signal which contains multiple components and splits the signal into individual components.
OMLCustomBlock
Scope Plots data as defined.
Constant Generates a command signal.
PID Serves as the controller block, the brain of the model.
Sum Calculates the error from reference signals and feedback.

### Creating the Diagram of the Activate Model

1. On the ribbon, select File > New.
2. From the Palette Browser, select Activate > CoSimulation, then drag and drop one MotionSolve block into the current diagram.
3. In the diagram, on the MotionSolve block, double-click. From the dialog that appears, define the following block properties:
For this property Do this
XML or MDL input file name Copy and paste the path to your MotionView .mdl model or MotionSolve .xml file.
Output MRF file name Enter a path to an output multi-body results file.
Direct feedthrough Clear the check box for this option.

Direct feedthrough defines if the outputs of a block are directly affected by the inputs. An example is a gain block where y = K*u, which causes algebraic loops. If this result is not desired, clear the check box to break the loops.

Note: The following parameters are populated automatically after you load the input model, *.mdl or *.xml:
This parameter Is defined with this value
Input Row Size The value 2 indicates that two signals from the Activate model are supplied to the MotionSolve model. These signals correspond to the solver array PlantInput, with variables PivotTorque and ControlForce.
Output Row Size The value 3 indicates that the MotionSolve model sends out three signals from one port, which is why the Demux block is added to separate the signals. The signals correspond to the solver array ControlOutput with variables AngularRate, AngularDeviation and CartPosition.
4. In the Palette Browser from Activate > MathOperations, drag and drop one Sum block into the diagram.
5. In the Palette Browser, from Activate > Routing, drag and drop one Demux and one Mux block into the diagram.
6. On the DeMux block, double-click, and in the block dialog, for Number of outputs, enter 3.
7. In the Palette Browser, from Activate > CustomBlocks, drag and drop one OmlCustomBlock into the diagram.
8. On the OmlCustomBlock, double-click.
9. In the block dialog, select the tab SimFunction, and for the Function Code, enter or copy and paste the following code:

function OmlBlockFunction(block,flag)
angle=vssGetInPortData(block,1);
if flag==vssBlockOutputUpdateFlag
x= mod(angle(1),360);
if(x>180)
x=-360+x;
end
vssSetOutPortData(block,1,x,vssGetOutputDataType(block,1));
end
end

This code wraps the measurement for the pendulum angle between 180 and -180 degrees.

10. In the Palette Browser, from Activate > SignalViewers, drag and drop three Scope blocks into the diagram.
The Scope blocks correspond to the responses of AngularDeviation, AngularRate and CartPosition. Define the scope block parameters for axis and curve properties for these responses.
11. In the Palette Browser, from Activate > Dynamical, drag and drop two PID blocks into the diagram.
12. Select the first PID block. From the Property Editor, select General > Name, and enter the name PID1_AngularDeviation.
13. Select the second PID block. From the Property Editor, select General > Name, and enter the name: PID2_CartPosition
14. On the block, PID1_AngularDeviation, double-click, and enter these values for the parameters:
Note:
• Proportional Gain multiplies the error signal by a constant gain Kp.
• Integral Gain multiplies the sum history of error with integral gain Ki.
• Derivative Gain multiplies the rate of change of error with gain Kd.
15. On the block, PID2_CartPosition, double-click. In the dialog, define the parameters:
16. In the Palette Browser, from Activate > SignalGenerators, drag and drop one Constant block into the diagram.
17. On the Constant block, double-click. In the dialog, for Constant, enter 0.
18. Select the Constant block, and copy and paste it into your diagram so that you have a duplicate.
19. All of the required blocks are now present. Assemble and link the blocks in the diagram as follows:
20. Experiment with the diagram and try to modify the PID gain parameters to see their effect on the simulation.

## Simulating the Diagram

1. On the ribbon, select Setup.
2. On the dialog that appears, select the tab, Simulation Time.
3. For Final Time, enter 7, indicating that the simulation will run for 7 seconds.