Compiling API Models to Libraries

A Third-party compiler allows you to compile C++ code to a library (.dll in Windows or .so in Linux).

EDEM does not support any specific compiler. However, Microsoft Visual Studio is commonly used and the Visual Studio Community 2017 is shown in this example along with Linux GCC.

The following example assumes you have already written the code to be compiled. The code used in this example is the Hertz-Mindlin model available on the EDEM Simulation Forum and the EDEM API Contact Model Tutorial. User written API files are as follows:

Windows

When installing Visual Studio, it is important to choose to install the C++ tool set (Universal Windows Platform development and Desktop development with C++), depending on the install these may be installed by default or additional options in the installer.

1. Create a new project.
   1. Open Visual C++ For Windows Desktop and Go to File > New Project...
   2. Select Win32 Console Application.
      

   3. Specify a project name and location and click OK.

   4. On the next window, go to Application Settings and select DLL in Application Type.

   5. Select Empty Project and then click Finish.
      
      

   6. Copy your written .cpp and .h files to the newly created project folder.
      EDEM header files are also needed before the model with compile. The additional header files can be found in the EDEM install folder > src > API.

   7. Copy the following files from Core and ContactModels to your project folder:

      IPluginContactModel.h

      IPluginContactModelV3_3_0.h

      PluginContactModelCore.h

      ApiIds.h

      ApiTypes.h

      IApi.h

      IApiManager_1_0.h

      ICustomPropertyDataApi_1_0.h

      ICustomPropertyManagerApi_1_0.h

      PluginConstants.h

   8. Right-click Header files and Source files to add the file to the Visual Studio Project.
      
      

2. To compile the Contact Model:

   1. Go to Visual Studio Build > Configuration Manager.

      From Win32, select ‘new’ > x64.

      The Configuration Manager window is displayed.
      

   2. Select Release or Debug and build the solution from Build > Build Solution.
      
      This creates a .dll file which can be loaded into EDEM.

Linux

Although some basic commands are covered, the following is not intended to be an in-depth guide for new users of Linux.

The GNU Compiler Collection, more commonly referred to as GCC, is typically included with Linux installations and, as the name suggests, is a collection of different compilers. EDEM’s API is based on C++, meaning a compiler that is compatible with C++ is required. We recommend using either the gcc or g++ command, both of which are common ways of invoking a C++ compiler. There are differences between the two commands, which we will not outline here, but you should be able to use either when compiling your EDEM API plugin.

EDEM uses functionality from the C++11 standard, so you will require a compatible version of gcc in order to compile plugins using EDEM’s API. gcc 4.8.1 was the first version to be fully compliant with the C++11 standard.  If you have Red Hat / CentOS 7 or later, you should be able to use the default version of gcc. You can check which version of gcc you have by entering “gcc --version” in a terminal:

To compile the Hertz-Mindlin example from the command line with an output file of HertzMindlinAPI.so, use the following command:

gcc -std=c++11 -O2 -shared -fPIC

-I/home/<user>/2022.3/altair/src/Api/ContactModels/

-I/home/<user>/2022.3/altair/src/Api/Core/

-I/home/<user>/2022.3/altair/src/Misc/

CHertzMindlin.cpp HertzMindlin.cpp -o HertzMindlinAPI.so

If you modify the install path during the installation, you must update the file locations to the appropriate directory. <user> should be updated to the appropriate account depending on the folder EDEM is installed in:

1. -std=c++11 informs gcc to expect functionality from the C++11 standard and use the appropriate libraries when compiling.
2. -O2 specifies the use of optimization method 2. Adding an optimization method flag allows gcc to attempt to improve the performance of the resulting output file, though potentially increases compilation time. Generally speaking, an EDEM API plugin should compile within seconds, so it is usually worth including this optimization option.
3. -shared -fPIC creates a shared object file as an output. The default output of gcc is an executable program. Adding these flags means gcc produces a shared library instead.
4. -I/<directory> adds the directory to the included path. This allows you to use headers from a particular directory, without having to copy them to the directory where your source code is. In addition to those mentioned above, when creating EDEM API plugins,you may also need to include the following:
   /home/<user>/2022.3/altair/src/Api/Factories
   /home/<user>/2022.3/altair/src/Api/ParticleBodyForce

Alternatively, you can choose to copy the relevant header files to your working directory if you do not wish to use this flag to include any directories.

-o specifies the output file name. This is not mandatory, but is required if you would like the created shared library to have a particular name. You can always rename the file after compilation if you do not use this flag.

This is a single command, and only spaces between the arguments and not new lines is allowed. The arguments are shown on new lines for easier readability.

Enter the following command (script):

It is recommended to specify the compile flags appropriate to their model and requirements, though the above flags are commonly used and found to work when compiling EDEM API plugins. For more detail on flags for gcc, visit https://gcc.gnu.org/ or check out gcc’s man entry (man gcc).

Making a Compilation Script (Recommended)

Although this step is not mandatory, if you are compiling API plugins regularly, you may wish to consider putting together a script that does the compilation automatically, to save you from having to type out a long command every time.

1. Using a text editor such as Emacs, Vim or Gedit, create a new text file with your command similar to that written above (edited for your particular filenames and included directories) and save it to a file name of your choice such as compileScript, in the same folder as your source code. Here we are using Vim, which should be available to all Linux distributions, though the text editors available to you might mean it is easier to use something else.
   
   

2. Navigate to the directory where you have saved your script, using cd, and then make the script an executable using chmod 755 compileScript. Now when you list the contents of the directory, using the ls command, the compileScript has executable permissions (it now shows in green).
   
   

3. Run the compile script using ./compileScript and your .so file will be created.
   
   

4. When compiling another model, you need to change is the included directories and filenames in this one script, or modify the script to accept arguments instead.

(c) 2023 Altair Engineering Inc. All Rights Reserved.

Intellectual Property Rights Notice | Technical Support