C++ & Python API to Aspherix®

This section describes how to build and use Aspherix® via a C++ or Python interface.

C++ API

The C++ API is in an early development phase, may change in future versions, and is evolving toward a stable Aspherix®-style interface. Please note that the API usage is currently restricted to the CPU-based version of Aspherix®.

The basic workflow is that, during compilation, your C++ program uses the API header files included with your Aspherix® installation and then links against the Aspherix® dynamic library. The C++ header files are located in the include/aspherix/api directory of your installation, while the dynamic library libaspherix.so / aspherix.lib can be found in the lib/aspherix folder. All API functions are contained within the Aspherix_API namespace.

You can find several API examples in the examples/API/C++ folder. Among them, the demo example illustrates a variety of API concepts, while hertz_history_benchmark compares the performance of the native contact model—combining normal Hertz and tangential history—with an equivalent implementation using the API.

At the beginning of every API program you need to initialize an aspherix instance which can be done by

Aspherix asx(command_line_arguments);

where command_line_arguments is a string containing all command line arguments being passed to Aspherix, this could even be with an input script (-in).

Compilation

To compile API code, cmake with version 3.9 or greater is required.

Compilation on Linux

In the simplest case, a compilation can be done using the following commands:

First, create a separate build directory:

mkdir build && cd build

Then, run cmake to generate the build files:

cmake -DCMAKE_PREFIX_PATH=path/to/aspherix/install/share/aspherix path/to/source

Your Aspherix® installation directory contains a subdir share/aspherix, which you need to provide to cmake. Additionally, the path to the sources containing your API code is required. If you wish to install the compiled binary to a certain location, you can add -DCMAKE_INSTALL_PREFIX=desired/install/path to the cmake call.

Finally, perform the actual compilation by calling:

make
make install (optional)

Compilation on Windows

As a prerequisite, the Microsoft MPI SDK needs to be installed. Download it from Microsoft. Windows compilation was only tested with Microsoft Visual Studio 2017.

As on Linux, create a build directory with

mkdir build
cd build

then run the configuration step with

cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_PREFIX_PATH=path\to\aspherix\install\share\aspherix path/to/source

and the actual compilation with

cmake --build . --config Release

The executable is then located in buildReleaseexecutableName.exe

Warning

On Windows, the –config Release switch is mandatory. Aspherix® API programs can not be built with debug symbols on Windows.

Basic interaction

At its simplest, the API supports interactive input scripts. Two key functions are provided for this purpose:

// execute a full input file
asx.executeInputFile("some_input_file.asx");
// execute only a single command
asx.executeCommand("enable_gravity magnitude 3.72");

Note

All commands can be wrapped using try and catch as the API will throw a runtime exception if it fails. Using the what() function of std::exception can be used to get more information about the error.

Advanced interaction

In the following the different API header files are listed and linked to the respective explanations. Each header file contains exactly one class with the same name as the file minus the leading aspherix.

Python API

Besides our C++ API we provide a Python wrapper of our C++ API. Thus all remarks concerning the backward compatibility of C++ API apply to the Python API also.

To use the Python API the preferred way is to append the lib/aspherix folder to the environment variable PYTHONPATH. If not done otherwise, you can simply source our prepared shell script by:

$ source path/to/aspherix/install/share/aspherix/shell_variables.sh

This allows to use the Python API within a Python script simply by importing the API module.

from Aspherix_API import Aspherix
asx = Aspherix(command_line_arguments)

This is already sufficient for a basic interaction with the Python API , e.g.

# execute a full input file
asx.executeInputFile("some_input_file.asx");
# execute only a single command
asx.executeCommand("enable_gravity magnitude 3.72");

For more details please have a look at the Basic interaction section or the Advanced interaction section of the C++ API.

Note

For more advanced usage extend the “from Aspherix_API import Aspherix ,…” command accordingly.