The objective of this tutorial is to replace several entities in a MotionView model with Python user subroutines. You will run a model initially, and then edit the file to incorporate Python scripts in place of MotionView entities and compare the results from each simulation.

In this tutorial, you will learn how:

You must be familiar with the MotionView user interface and entities panel, as well as have some experience defining and modifying entities.  Some experience with the Python programming language is necessary to fully understand the topics covered.

Exercise One - Introduction to User Subroutines

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.

Copy the model file required for this exercise, engine_baseline.mdl, along with all of the H3D files located in the mbd_modeling\motionsolve\python_usersub folder to your <working directory>.

The single cylinder engine model

The model we are using is a single cylinder engine, and uses a curve, an output, a force, and a motion entity.  The system also uses default damping.

The following is a list of the entities and usersubs we will be using in this tutorial, along with a brief description of their usage:

Step 1: Running the model.

This will give you result files to compare with your usrsub results.

Exercise Two - Adding User Subroutines

Notes on using XML syntax in Python

Python can use many MotionSolve functions and inputs when certain syntax rules are followed. When using a MotionSolve function such as AKISPL or SYSFNC, the string “py_” must be added to the beginning.  For example, “py_sysfnc(…” would be the correct usage of SYSFNC in Python.  When defining a usersub function in Python, the name of the function and the inputs must match those outlined in the MotionSolve online help pages exactly.  When accessing model data in python through a function such as SYSFNC, use the exact property name in quotations as the “id” input.  Model properties that are passed into Python in the function definition can be accessed throughout the script, and do not need additional defining to use.  An example of these syntax rules being used is shown below:

def REQSUB(id, time, par, npar, iflag):

   [A, errflg] = py_sysfnc(“DX”,[par[0],par[1]])

return A

Step 1: Using SPLINE_READ to Replace the Curve Entity.

The first user-subroutine we will implement uses the SPLINE_READ function to return the curve from the included pressure_curve.csv file. SPLINE_READ is the usersub that corresponds to the curve entity in MotionView.  It uses data points in an external file to create a curve, which can then be used by other entities.

Writing the Python script:

Your nonlin_spline.py Python script should resemble the following:

def SPLINE_READ(id, file_name, block_name):

 

import csv

ifile= open('pressure_curve.csv','r')  ## opens data file as readable variable

curv = csv.reader(ifile)               ## reads csv data, stores as useable var.

 

L = []              ## creates empty list

for item in curv:

L.append(item)  ## separates file values into list

 

L = L[1:]           ## removes block names from list

 

i=0                        ## creates counter

x = 16*[0.0]

y = 16*[0.0]               ## splits list into x and y lists

while i < (len(L)-1):

x[i] = float(L[i][0])  ## changes values from str to float

y[i] = float(L[i][1])

i+=1                   ## counter increment

 

z = 0.0                           ## defines z value

ifile.close()                     ## closes data file

errflg = py_put_spline(id,x,y,z)  ## var to create MotionSolve spline

 

return errflg                     ## returns var

Implementing the Python script:

The curve panel using the SPLINE_READ usersub

Step 2: Using REQSUB to Request an Output.

The second user-subroutine will use Python to specify which values to return.  In this tutorial, the returned values will be the magnitude of displacement for the piston.

Writing the Python script:

Your req_nonlin.py Python script should resemble the following:

def REQSUB(id, time, par, npar, iflag):

 

[D, errflg] = py_sysfnc("DM",[par[0],par[1]])  ## sets "D" as piston displacement mag

result = [0,D,0,0,0,0,0,0]         ## lists results for output return

 

return result         ## sends list with results to motionsolve as output

Implementing the Python script:

The Outputs panel is displayed.

Expression Builder dialog

Outputs panel using REQSUB

Step 3: Using GFOSUB to Replace the Force Entity.

The GFOSUB user subroutine replaces a force with a user defined Python script.  The GFOSUB used here will take the curve data defined with SPLINE_READ, and change depending on the Conrod angle according to the curve.

Writing the Python script:

Your gfo_nonlin.py Python script should resemble the following:

def GFOSUB(id, time, par, npar, dflag, iflag):

 

from math import pi

 

[A, errflg] = py_sysfnc("AZ",[par[1],par[2]])  ## retreives conrod angle

B = ((-1)*A*180)/pi                            ## converts radians to degrees

 

[C, errflg] = py_akispl(B,0,par[0],0)  ## interpolates data to fit curve

 

return [0,C[0],0]  ## returns C data as force values

Implementing the Python script:

Step 4: Using MOTSUB to Define a Motion.

Writing the Python script:

Your mot_nonlin.py Python script should resemble the following:

def MOTSUB(id, time, par, npar, iord, iflag):

 

if iord==0:         ## function

A = 10.0461*time

elif iord==1:       ## first derivative

A = 10.0461

else:               ## second derivative

A = 0.0

return A       ## returns function based on iord input

Implementing the Python script:

The Motions panel is displayed.

Because we defined the function in the Python script, we do not need to modify USER() text field.

Motions panel using MOTSUB

Step 5: Using DMPSUB to Add Custom Flexbody Damping.

Writing the Python script:

nmode is the number of modes in the flexbody.

Your dmp_nonlin.py Python script should resemble the following:

def DMPSUB(id, time, par, npar, freq, nmode, h):

 

cratios = nmode*[0.0]    ## makes preallocated list for markers

 

for i in xrange(nmode):

cratios[i] = 1.0     ## sets marker damping to 1

 

return cratios           ## returns damping values

Implementing the Python script:

Because we defined the damping in our dmp_nonlin.py script, we do not need to change the USER() expression.

is_user_damp        = "TRUE"

usrsub_param_string = "USER()"

interpreter         = "Python"

script_name         = "dmp_nonlin.py"

usrsub_fnc_name     = "DMPSUB"

Your flexbody definition should look like below:

<Body_Flexible

id                  = "30104"

lprf_id             = "30104002"

mass                = "7.424574879203591E-02"

inertia_xx          = "1.471824534365642E+02"

inertia_yy          = "4.505004745855096E+00"

inertia_zz          = "1.501914135052064E+02"

inertia_xy          = "-5.546373592613223E-03"

inertia_yz          = "-1.984540442733755E-03"

inertia_xz          = "1.557626595859531E-03"

cm_x                = "1.191728011928773E-03"

cm_y                = "-2.225471002399553E+01"

cm_z                = "5.469513396916666E-05"

h3d_file            = "conrod.h3d"

is_user_damp        = "TRUE"

usrsub_param_string = "USER()"

interpreter         = "Python"

script_name         = "dmp_nonlin.py"

usrsub_fnc_name     = "DMPSUB"

flexdata_id         = "30104"

animation_scale     = "1."

/>

Exercise Three - Running Your Simulation with Usersubs

Now that all the user subroutines have been implemented, run your model, and compare your results to those from your initial test.

Step 1: Using the Run Solver Panel to Run Your Model.

Exercise Four - Comparing Your Results

Now that we have results for both the initial model and the model using user subroutines, we will compare the data to ensure accuracy.  We will do this using HyperGraph and Hyperview to compare the outputs and deformations of the system.

Step 1: Using HyperGraph to Plot the Displacement Magnitudes.

Using the outputs from both simulations, we will compare the displacement magnitude of the piston.  A correct result from the usersub run will match the results from the initial run.

Comparison of output results from both model simulations

Step 2: Using HyperView to Compare Flexbody Stresses.

Using HyperView, you can view the stresses and deformations on the flexbody.  The results between the two simulations should be the same.

Only the flexbody component should be displayed.

The Contour panel is displayed.

Comparison of flexbody deformation in HyperView