MV-7001: Building User Subroutines in Altair 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.

Minimum Software Requirements to Compile and Build MotionSolve User Subroutine DLLs

Windows

•	Microsoft Visual Studio version 2005, both Express and Professional.

•	Intel Visual FORTRAN Compiler 10.

Linux

•	GCC, version 4.1.2

Using 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.

Launching the Build Tool on Windows

The build tool may be launched via the Start menu:

Start > All Programs > Altair HyperWorks (64-bit) > Tools > MotionSolve Subroutine Builder

The MotionSolve Subroutine Builder dialog is displayed:

mv-7001_usersub_tool

Launching the Build Tool on Linux

You can launch the build tool from the desktop icon or from the command line by navigating to:

<altair_root>/altair/scripts/

and issuing the following command

./motionsolve_subroutine_builder

This displays the tool’s GUI:

mv-7001_motionsolve_subroutine_builderl

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.

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

mv-7001_usersub_tool_img2

2.	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.

3.	Click Open to select these files.

mv-7001_open_dialog

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.

1.	Click Open, , next to the Output Name text box.

mv-7001_usersub_tool_img3

2.	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.

mv-7001_select_folder

Specify the name of the shared library

1.	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 text box.

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

mv-7001_shared_library_name

Build the shared library

1.	To build your shared library, click Build.

mv-7001_build_shared_library

2.	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:

mv-7001_compiler_setting

3.	Upon building the source files successfully, the following dialog box is displayed:

mv-7001_build_successful

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.

4.	If, however, your build is unsuccessful, the following dialog box is displayed:

mv-7001_build_failed

5.	To investigate the cause of build failure, you may want to look at the build_output.log file at the location stated in the dialog box above. This file typically contains compiler/link time errors or warnings that may help you debug your source code.

Exit the tool

1.	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.

mv-7001_clean_files

FAQs

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

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

Q. What platform does the tool build my library for?

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

Q. Is my shared library a debug or release version?

A. The shared library created is a release version library.

Q. Where can I get sample templates for the syntax of the C/C++/FORTRAN code?

A. 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

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

A. 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.

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

A. 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.

Using the Microsoft® Developer Studio to Build a Shared Library

Note:

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

Build a C++ user subroutine DLL using Microsoft® Visual Studio®

1.	Open Microsoft Visual Studio 2005 (Express and Professional Editions will work).

2.	From the File menu, select Open > Project/Solution.

mv-7001_open_project_solution

3.	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.

4.	In the Solution Explorer, the CPP subroutines that are part of the solution are listed.

5.	Double-click any of the CPP files that you want to modify/view and make the required changes.

6.	Click Save to save the changes made to the file.

7.	Choose the configuration for your shared library.

mv-7001_config_selection_menu

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.

8.	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.

9.	After successfully completing the build, Visual Studio displays a message as shown below:

mv-7001_vs_msg

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

Build 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.