Exercise 1: Introduction to User Subroutines

In this exercise you will learn about user subroutines and run a model for a single cylinder engine.

Before you begin, copy the model file engine_baseline.mdl, along with all of the H3D files located in the mbd_modeling\motionsolve\python_usersub folder to your <working directory>.
User subroutines are a useful tool to customize simulations and analyses. These subroutines, or usersubs can be created using variety of programming languages like C, Ruby, TCL, and Python. Subroutines created in programming languages like C, C++ and FORTRAN etc. are compiled to create *.dll files using the MS UserSub Build Tool (located in the MotionView Tools menu). These dlls are then used by the solver. In older versions of MotionView only compiled usersubs (*.dll) were supported. Starting with MotionView version 11.0, usersubs are enabled to use Python and Matlab scripts. In this tutorial, we will be using Python to create usersubs. User subroutines can make use of external Python scripts in order to define complex simulations, which cannot be created through the MotionView GUI. With a basic knowledge of the Python programming language, a user can easily generate intricate experiments to simulate any complex mechanism. This tutorial will show you how to replace five MotionView entities with their corresponding usersubs.
Figure 1. The single cylinder engine model


The model you will use is of a single cylinder engine that uses a curve, an output, a force, and a motion entity. The system also uses default damping.
  • The curve is read from a CSV file, and gives a force value based on the angular displacement of the connecting rod.
  • The output returns the displacement magnitude of the piston.
  • The force entity uses the angle of the connecting rod and the curve to apply a variable pressure force to the piston.
  • The motion entity applies an angular motion to the Crank_Grnd revolute joint.
  • The default damping of the system is 1, however it can be changed in the Bodies panel.
Listed in Table 1 are the entities and usersubs you will be using in this tutorial, along with a brief description of their usage.
Table 1.
Entity Usrsub Description
Curve SPLINE_READ Reads the curve data file.
Request REQSUB Outputs the requested values.
Force GFOSUB Applies a force on the system.
Motion MOTSUB Applies a motion to the system.
Damping DMPSUB Defines the damping of a flexbody.

Run the Model

In this step, you will run the model to obtain the results files to compare with your usrsub results.

  1. Click the (Run) button.
  2. From the Run panel, click (Open File) to browse your <working directory>. Specify the name of the MotionSolve XML file as engine_baseline.xml.
  3. Click to check the model for errors.
  4. Click the Run button.