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.
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
The MotionSolve Subroutine Builder dialog is displayed:
-
To launch the build tool on Linux, navigate to
<altair_root>/altair/scripts/ and issue the
command:
./motionsolve_subroutine_builder
The GUI is displayed:
Specify Source Code or Object Files
- 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.
- 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.
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.
- 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.
Build the Shared Library
-
To build your shared library, click Build.
-
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.
Upon building the source files successfully, the following dialog is displayed:
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: - 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?
- 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
- 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 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 installation directory.
- Open Microsoft Visual Studio 2005 (Express and Professional Editions will work).
- From the File menu, select .
-
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.
Make sure that the target type for the shared library matches your installation. For example, choose x64 for a 64-bit installation of the application.
-
Select
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: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.