MV-7001: Building User Subroutines in MotionSolve

In this tutorial, you will learn how to compile and build a MotionSolve user subroutine.

The user subroutine can be implemented as C/C++ or FORTRAN source code, C/C++ or FORTRAN object files, or a combination of these.

For your convenience, MotionSolve contains a subroutine build tool for Windows and Linux that can build the subroutine for you. Using this subroutine requires no programming knowledge.

You can also build your user subroutine using an integrated development environment like Microsoft® Visual Studio® on Windows. This is explained in this tutorial.

Table 1. Minimum Software Requirements to Compile and Build MotionSolve User Subroutine DLLs
Windows	Linux
Microsoft Visual Studio version 2005, both Express and Professional	GCC, version 4.1.2
Intel Visual FORTRAN Compiler 10

Use the MotionSolve Subroutine Build Tool to Create Shared Libraries

The Altair Subroutine Builder is included in the MotionSolve installation for both Windows and Linux.

Follow these steps to build a MotionSolve-compatible shared library using available source code.

Launch the build tool on Windows by clicking Start > All Programs > HyperWorks (64-bit) > Tools > MotionSolve Subroutine Builder
The MotionSolve Subroutine Builder dialog is displayed:

Figure 1.
To launch the build tool on Linux, navigate to <altair_root>/altair/scripts/ and issue the command:
```
./motionsolve_subroutine_builder
```
The GUI is displayed:

Figure 2.

Specify Source Code or Object Files

The next step is to specify the source code or the object files that you will be using to build the shared library. The following are valid source file types and can be used to build a shared library:

C/C++ source code (*.c, *.cpp, *.cxx)
FORTRAN source code (*.f, *.f90)
FORTRAN or C/C++ object files (*.obj in Windows, *.o in Linux)
A combination of the above.
Note: The remainder of this section demonstrates using the build tool on Windows. The steps for using the tool on Linux are identical.

Important: The source code or object files must all be located in the same directory. You must have write-to-disk permissions for this directory. If you do not have write-to-disk permissions for this directory, please copy the source code to a location where you do have write-to-disk permissions.
Also, if your source/object code is located in different folders on your disk, please copy all source/object code, along with any relevant files (like headers, for example) to one common directory. Use this as your working directory in the following steps.

To specify the source/object files, click next to the Source File(s) field.

Figure 3.
Navigate to your working directory and choose the source files as required. You can choose multiple files by holding down the CTRL button while clicking the file names, or by clicking and dragging your mouse pointer.
Click Open to select these files.

Figure 4.

Specify the Output Directory

Next, you will specify the output directory where you would like the shared library to be built. Again, you must have write-to-disk permissions for this directory.

Click Open next to the Output Name field.

Figure 5.
Navigate to the directory where you want the shared library to be built. Click Select Folder to choose the current folder as the output directory.
Before building the shared library, you need to specify a name for the shared library. To do this, simply type in the name (without the extension) into the Output Name field.

Note: The shared library name must contain only alphanumeric characters (A-Z, a-z, 0-9) with the exception of the underscore ("_") character.

Figure 6.

Build the Shared Library

To build your shared library, click Build.

Figure 7.
For the Windows platform, if you have multiple compilers installed on your computer, you can choose which compiler to use while building your shared library.

Figure 8.
Upon building the source files successfully, the following dialog is displayed:

Figure 9.

Additionally, you will see the shared library built by the tool in your working directory (C:\Test in this case). You can use this library in a MotionSolve simulation.

The tool also creates a temporary directory inside your working directory while building the shared library. The contents of this temporary directory can be used for debugging and informational purposes.
Note: The temporary directory created inside of your working directory contains some useful information:
- build.bat: a batch file that contains the compiler and linker commands used to build the shared library.
- build_output.log: a log file that contains messages from the compiler and linker. The contents of this file are useful when debugging an unsuccessful build.
  For a successful build, this directory also contains compiled objects, the linked library and other temporary files. If you specified only C/C++ source files and/or object files, the tool also creates a Microsoft® Visual Studio® solution file in this directory.
If, however, your build is unsuccessful, the following dialog is displayed:

Figure 10.
To investigate the cause of build failure, look at the build_output.log file at the location stated in the dialog above. This file typically contains compiler/link time errors or warnings that may help you debug your source code.
After you have finished using the tool, you can exit by clicking Quit. If you built a shared library before quitting, you are given the option to remove the temporary folder created by the tool.

Frequently Asked Questions

Can the tool build a shared library when both Fortran and C/C++ source code is specified?

Yes, the tool can handle mixed source code as well as object files.

What platform does the tool build my library for?

The supported platforms are 64-bit Windows and 64-bit Linux.

Is my shared library a debug or release version?

The shared library created is a release version library.

Where can I get sample templates for the syntax of the C/C++/Fortran code?

Sample user subroutine code is provided in the HyperWorks installation in the following locations:

For C/C++ source code: <install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_src
For Fortran source code: <install>\Altair\<version>\hwsolvers\motionsolve\usersub\f_src

Note: For MotionSolve to use the functions defined in the source code, these functions must be exported on the Windows platform (on Linux, all functions are automatically exported). The syntax to do this for C/C++ and Fortran is described below.

C/C++

Include the header file msolvsub_c_include.h (located in <install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_src\include) in your code. To export a function, use the keywords CLINKAGE, DLLFUNC, and STDCALL.

#include " msolvsub_c_include.h"
#include "stdlib.h"
CLINKAGE 
DLLFUNC
void
STDCALL
ARYSUB (int *id, double *time, double *par,int *npar, int *dflag, int *iflag, int *nvalue, double *value)
{
}

Fortran

In Fortran syntax, the same function above can be exported as shown below:

SUBROUTINE
ARYSUB (ID, TIME, PAR, NPAR, DFLAG,
     &  IFLAG, NVALUE, VALUE)
!DEC$ ATTRIBUTES DLLEXPORT ::
ARYSUB

Does the order in which I choose the source files matter?

Yes, this can matter in certain cases. For example, when building Fortran source code and defining MODULES, you may want to include the source file that contains the definition of any defined modules before the source files that refer to these modules.

I am not able to compile Fortran files even though I have a supported Intel Fortran compiler installed. What's wrong?

The build tool relies on an environment variable to detect the version of the Intel Fortran compiler and its location on your machine. Make sure you have the environment variable IFORT_COMPILERxx (where xx is the version of the compiler - 10, 11 or 12) defined correctly on your system and pointing to the installed version.

Use the Microsoft® Developer Studio to Build a Shared Library

To successfully build a shared library using the steps below, you will need to have write-to-disk permissions for your HyperWorks installation directory.

Building a C++ User Subroutine DLL using Microsoft® Visual Studio®

To successfully build a shared library using the steps below, you will need to have write-to-disk permissions for your HyperWorks installation directory.

Open Microsoft Visual Studio 2005 (Express and Professional Editions will work).
From the File menu, select Open > Project/Solution.
Browse to <install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_project, select the file ms_csubdll.vcproj and click Open.

Note: If you are using a version newer than Visual Studio 2005, you will be prompted to convert the project file. Please proceed with the default options for the conversion. Once converted, the new project file is loaded to your workspace.

In the Solution Explorer, the CPP subroutines that are part of the solution are listed.
Double-click any of the CPP files that you want to modify/view and make the required changes.
Click Save to save the changes made to the file.
Choose the configuration for your shared library.

Figure 11.

Make sure that the target type for the shared library matches your HyperWorks installation. For example, choose x64 for a 64-bit installation of HyperWorks.
Select Build > Build Solution to build the DLL. You will be prompted to save the solution. Save the solution in a directory of your choice.
After successfully completing the build, Visual Studio displays a message as shown below:

Figure 12.
The DLL ms_csubdll.dll is located in <install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_project\<platform>\<config>\ms_csubdll.dll.

Building a FORTRAN User Subroutine DLL using Microsoft® Visual Studio®

The same steps can be repeated to build a FORTRAN user subroutine DLL for MotionSolve. The only difference is that the Visual Studio project file to be opened is ms_fsubdll.vfproj. All the other steps remain the same.