Altair User Subroutine Build Tool - Graphical User Interface

The Altair User Subroutine build tool has a new interface and functionality starting with version 13.0. This topic describes the process by which you may 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 even a combination of these.

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

Minimum Software Requirements for Compiling and Building 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 build tool is included 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 <version number> (64-bit) > Tools > MotionSolve Subroutine Builder

The MotionSolve Subroutine Builder GUI is displayed:

mv-7001_usersub_tool

The MotionSolve Subroutine Builder for Windows

Launching the Build Tool on Linux

The build tool may be launched 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

The MotionSolve Subroutine Builder for Linux

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++ source code (.c, .cpp, *.cxx)

•

FORTRA

•	N source code (.f, .f90)

•	FORTRAN or C/C++ object files (.obj in Windows, .o in Linux).

•	A combination of the above.

The remainder of this section demonstrates using the build tool on Windows. The steps for using the tool on Linux are identical.

Note	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 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 (such as headers) to one common directory. Use this as your working directory in the following next steps.

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

mv-7001_usersub_tool_img2

Specifying source files

2.	Navigate to your working directory and choose the source files as required. You can choose multiple files by pressing the CTRL key while clicking the file names, or by clicking and dragging your mouse pointer.

3.	Click Open to select these files.

mv-7001_open_dialog

Choosing source files

Specify the Output Directory

Next, specify the output directory and file name for the shared library. 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

Specifying the output file and location.

2.	Navigate to the directory where you would like the shared library to be built. Enter a name for your library in the File name text field. Click Save to continue.

save_subroutine_library_dialog

Specifying the output file and location.

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

Build the Shared Library

1.	To build your shared library, click Build.

build_shared_library

Build the source code.

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

Choose compilers if multiple are available

3.	Upon building the source files successfully, you should see the following dialog box:

build_succeeded_message

Build completed

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.

The temporary directory created inside 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

Build completed

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

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

SUBROUTINE ARYSUB (ID, TIME, PAR, NPAR, DFLAG,

& IFLAG, NVALUE, VALUE)

!DEC$ ATTRIBUTES DLLEXPORT :: ARYSUB

The code above exports the function ARYSUB using C/C++ and FORTRAN syntax.

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.