User Subroutines and MotionSolve

The relationship between the user-written subroutines that reside in a script or a DLL/SO, the modeling access subroutines provided by MotionSolve, the MotionSolve subroutine interface and MotionSolve itself is shown in Figure-1 below.

Figure 1. The data flow between a user created DLL/SO or script and MotionSolve


Figure 1 may be interpreted as follows:
  • MotionSolve is invoked and an input XML file containing the model is provided to it.
  • The input XML file may contain several modeling statements whose behavior is defined in a user-defined DLL/SO or script. An example of a modeling element whose behavior is defined in a user-written DLL or script is shown below.
    As a User-defined DLL As a User-defined Script 
    <Force_Scalar_TwoBody 
  Id = "30101"
  Type = "Force" 
  I_Marker_Id = "30103031" 
  J_Marker_Id = "30104041" 
  Usrsub_Param_String = "USER(50,1000)"   
  Usrsub_Dll_Name = "./Myfunction.dll" 
  Usersub_Fnc_Name = "Friction_Lugre"
/>
    		 
    <Force_Scalar_TwoBody 
  Id = "30102" 
  Type = "Force" 
  I_Marker_Id = "30103032"
  J_Marker_Id = "30104042" 
  Usrsub_Param_String = "USER(50,1000)" 
  Script_Name = "./Myfunction.pyc" 
  Usersub_Fnc_Name = "Friction_Lugre" 
  Interpreter = "Python" 
/>

    This example tells MotionSolve that the behavior of modeling element Force_Scalar_TwoBody with ID=30101 is defined by the function Friction_LuGre in the file ./MyFunction.dll. It also tells MotionSolve that the behavior of modeling element Force_Scalar_TwoBody with ID=30102 is defined by the function Friction_LuGre in the file ./MyFunction.pyc, which is written in Python.

  • The input XML file may also contain several commands that ask MotionSolve to be driven by a user subroutine. An example of such a command whose behavior is defined in a user-written DLL or script is shown below.
    As a User-defined DLL As a User-defined Script 
    <UserProgramControl 
  Usrsub_Param_String = "USER(0,-9810,0)" 
  Usersub_Fnc_Name = "Lane_Change" 
  Usrsub_Dll_Name = "./Myfunction.Dll" 
/>
    		 
    <UserProgramControl 
  Usrsub_Param_String = "USER(0,-9810,0)" 
  Usersub_Fnc_Name = "Lane_Change" 
  Script_Name = "./Myfunction .py" 
  Interpreter = "Python" 
/>

    This example tells MotionSolve that once MotionSolve has read the model, it should pass execution control to the function Lane_Change in the file ./MyFunction.dll. The function could also have been written in Python as shown in the column on the right. This tells MotionSolve that once MotionSolve has read the model, it should pass execution control to the function Lane_Change in the file ./MyFunction.py, which was written in Python. (Python scripts may be compiled, *.pyc, or not compiled, *.py)

  • Once the input file has been read in and processed, MotionSolve is ready for simulation. It executes the commands in the XML input file, which can either be standard commands or defined in a user subroutine. When a standard MotionSolve analysis command is encountered, for example: 
    <Simulate
    analysis_type = "Transient"
    end_time = "2."
    print_interval = "0.01"
 />

    MotionSolve performs the requested analysis. Alternatively, if it encounters a UserProgramControl command it loads the specified DLL/SO (if the Driver subroutine is compiled) or accesses the file specified in Script_Name. Then it invokes the function specified by Usersub_Fnc_Name and executes the instructions in the driver user subroutine.

  • During the course of an analysis, MotionSolve is required to evaluate all of the modeling elements. When modeling elements referencing user-written subroutines are encountered, MotionSolve loads the user-written subroutine and executes the instructions in the subroutine to get its required data. The path to the user-written subroutine library or script can either be specified directly by the modeling statement via usrsub_dll_name or script_name, or via environment variables. For more details, see the MotionSolve Environment Variables topic in the MotionSolve User's Guide.