Tips and tricks

User models

Instead of assigning parameter in the code, parameters values can be introduced via “User Model” in MBsysPad.

Back to the spring-pendulum example

The goal is to store the parameters of the model in the “User Model” and retrieving them in the user function.


Step 4 and 5 are not impacted by theses function. See the Bodies and joints part for more information

Step 1: Draw your multibody system

  • In MBsysPad, click on “User Model” (under the joint button)

  • Click the upper “Add” button to add a new user model

  • Give a name to the user model

  • Add 3 parameters for the spring (K, C, L0)

    • Click the lower “Add” button to add a parameter

    • In the right part of the window, give a name and a value to the parameter

Steps to add user model in MBsysPad

User model gui illustration


Press enter when modifying a parameter value to ensure that the change is correctly taken into account.


User model only serves for storing data. If nothing else is done, they do not modify the behaviour of the system. They must be accessed in user functions to be taken into account.

Step 2: Generate your multibody equations

It is not necessary to regenerate the multibody equations after a modification or a creation of user models since the symbolic files are not affected by user models. However, you may need to re-generate the project with CMake to take into account the newly generated user model files.


When modifying a user model parameter in MBsysPad, you must save the model in MBsysPad and reload the model in your code so that the modification take effect.

Step 3: Write your user function

The parameters defined in MBsysPad can then be accessed via the mbs data structure in the code.

  • Edit the user_JointForces function (open the file from the userfctR subfolder of your project);

  • Modify the spring-damper law to get the parameter values from the user model:

    • K, C and L0 are stored in the dictionary MbsData.user_model with the name and values defined in MBsysPad.

def user_JointForces(mbs_data, tsim):

   # set the joint force in joint 2
   id_J = 2
   K  = mbs_data.user_model['Spring']['K']
   C  = mbs_data.user_model['Spring']['C']
   L0 = mbs_data.user_model['Spring']['L0']
   mbs_data.Qq[id_J] = - ( K*(mbs_data.q[id]-L0) + C*mbs_data.qd[id_J] )


Initial conditions

The initial condition previously defined in MBsysPad can also be defined in the code after project loading.


Step 1, 2, 3 and 5 are not impacted by theses modifications.

Back to the spring-pendulum example

The goal is to modify in the main script the initial rotation and rotationnal speed of the pendulum.

Step 4: Run your simulation

  • Open the file and add the following command

    • After the project loading (load() function)

    • Before the coordinate partitioning and time integration (run() function for both but they are called on different python class)


# Define the initial condition of the joint 1 (rotation of the pendulum)
Joint_ID = 1

mbs_data.q[Joint_ID] = 0.2
# The initial rotation of the pendulum is set to 0.2 rad

mbs_data.qd[Joint_ID] = 0.01
# The initial angular velocity of the pendulum is set to 0.01 rad/s



The initial conditions are stored in the q0, qd0 and qdd0 vectors at the loading of the .mbs file. If you need to access to q0 (or qd0 or qdd0) during the computation you need to update these values aswell.

The function MbsData.reset() reset the coordinates values to the initial one. The considered initial value are the one stored in q0, qd0 and qdd0.


If you change the value of an independent joint involved in a kinematic loop, you can fail to close the loop (max Newton-Raphson iteration reached).

If you change the value of a dependent joint, you only change the initial configuration of the Newton-Raphson iteration.

MBsysPad 2D diagram manipulation

Moving several elements at once

Press the SHIFT key to move a component and all its descendence. Moving the base while pressing SHIFT will move all the drawing.

Press the SHIFT key to move a component and all its descendence

Moving a component and all its descendence

Modifying the attach point of a body, joint, anchor point, sensor…

Select the element (body, joint, anchor point, sensor…) you want to modify. A small grey square appears next to the attach point of your element. Click on it (and keep the button pressed) and move the the mouse to the desired attach point.

Use the small grey square to modify the attach point

Modifying the attach point of a body, joint, anchor point, sensor


The attach point is colored in red while moving the mouse. Check that you have reached the desired location.

Saving a custom quantity

It is often useful to get the time history of a custom variable which is not contained by default in the result structure returned by the direct dynamics module. The variables contained by default are:

  • The position, velocity and acceleration of each joint at each time step

  • The state vectors at each time step (see User derivatives if you don’t know what are state vectors)

The way to save custom quantity highly differs between the codes (Matlab, python, C).

In Python and MbsysC, in the opposite of Matlab version, also save the following value by default:

  • All values of links forces (z, zd, force value)

  • All joints force/torque value

  • All force/torque required in the driven joints

Python offers to save several type of value (with mbs_data being a MBsysPy.MbsData instance):

  • A single value: mbs_data.set_output(value, name)

  • A vector of values:

    • In user_dirdyn_init function, declare the vector size and name with the function: mbs_data.define_output_vector(name, size)

    • Fill the vector in any of your user function or in the user_dirdyn_loop function with:

      • A specific vector: mbs_data.set_output_vector(vector, name) (the size of the defined and provided vector must match).

      • Multiple values composing the vector: mbs_data.set_output_value(value, index, name) (the index start at 1 and its maximal value is the defined size)

By default we allow the user to save up to 12 single value, if you need more output value update the option max_save_user with the function MbsDirdyn.set_options().

Back to the spring-pendulum example

The goal is to store the spring force and the damper force of the link.


Step 1, 2, 4 and 5 are not impacted by theses modifications.

Step 3: Write your user function

  • Edit the file from the userfctR subfolder of your project

def user_LinkForces(Z, Zd, mbs_data, tsim, identity):

   Flink = K*(Z-Z0)+C*Zd

   # Save the spring and damper forces
   mbs_data.set_output(K*(Z-Z0), 'Fspring')
   mbs_data.set_output(C*Zd, 'Fdamper')

The saved value will be accessible in the results (MbsDirdyn.results) instance in the dictionary outputs.


Integrator type

With the Python implementation of Robotran, you can use different integrator by setting the field integrator of the class MbsDirdyn. The available integrator are listed in the documentation of MbsDirdyn.set_options() function (import MBsysPy and write print(MBsysPy.MbsDirdyn.set_options.__doc__)). Please refer to the MbsysC documentation for full details about the integrators.

Force the integrator to pass at specific time value

With the Python implementation of Robotran, you can force the integrator to return the results at fixed time step. do to so, activate the flag_waypoint options of MbsDirdyn and set the step size in the option delta_t_wp. More details in the documentation of the MbsDirdyn.set_options() function Please refer to the MbsysPy documentation or write import MBsysPy and write print(MBsysPy.MbsDirdyn.set_options.__doc__)).