Tutorial on basic Python API usage

Description

This test shows you how to set up a first simulation using the Aspherix(R) Python API.

Introduction

The idea of the API is to allow the interaction with Aspherix(R) by not just using an input script but by using a Python script written by the user. This allows the same type of interaction as with an input script plus an additional layer of access to internal data of Aspherix(R) which can, for example, be used for advanced post-processing.

In this first tutorial you are going to create a very basic script to read in an input script and then execute another command at the end of this simulation. While not extremely useful in itself it will teach you how to import the Aspherix(R) API and run the script.

Prerequisites

The advantage of the Python API is that it is platform independent. Therefore, we have the same prerequisites for both platforms:

• Python 3.8.6

• Aspherix(R)

Python can be simply installed alongside with the Aspherix(R) installer. Check the installation instructions for more details.

The basic API example explained

The basic API example can be found in your Aspherix(R) installation folder in subdirectory examples/API/Python/basic_api_usage. There, the following three files should be present:

basic.asx
meshes/plate.stl
basic.py

The basic.asx is a standard Aspherix(R) input script that uses the STL mesh meshes/plate.stl and our goal is to run this case from within our Python script which can be found in basic.py. The contents of the first two should be no surprise for you as they contain standard Aspherix(R) notation and data. The contents of basic.py will be explained in detail below.

The basic.py file:

Let us now go through this Python script line by line. If you are not familiar with the language you can go to www.python.org for an introduction.

from Aspherix_API import Aspherix
import sys

As usual the Python script start with importing some modules. The first line imports the main class Aspherix from the Aspherix(R) Python API. The second line is a standard Python module and is used for the interaction with the system.

asx = Aspherix()

This is the first call towards Aspherix(R). We create a new Aspherix object, without any arguments (command line options). You could pass an input script directly to Aspherix using "-in script.asx".

// Run an input script in a try/catch block to detect any errors during the run
try:
    # run the file with name "basic.asx"
    asx.executeInputFile("basic.asx")
except Exception as inst:
    # if there was an error we output the corresponding error message and
    print("Exception when running Aspherix: " + inst, file=sys.stderr)
    # exit the program
    sys.exit(1)

The gist of these lines is that we want to execute an input file with Aspherix(R) using the executeInputFile function. This function takes one argument and that is the filename of the script we want to execute. Note, the filename is relative to the path where the executable is executed in, something that will be important later.

The rest of the code is for exception handling. Basically, should anything go wrong when executing the input file the code will abort gracefully by going into the except block and executing the code inside. In this case it will output a message to stderr and tell you what exactly went wrong using the exception object inst.

# Let's output some information to the terminal
print("Completed execution of input script. Next, we execute a single command.")

This line just writes some output to the terminal (stdout).

# finally we simulate an additional 1e-2 seconds
asx.executeCommand("simulate time 1e-2");

After executing the input script above Aspherix(R) will not complete the simulation. Instead it is waiting for further input, just as if you were adding another line to the input script.

Using the Aspherix object we can instruct Aspherix(R) to execute another command using the executeCommand function. In this case we continue the simulation for another 0.01 seconds.

# And we tell the user that we are done
print("Completed execution of single command. Goodbye")

Finally, after the second simulation step is done we write some output to the terminal. Python will exit the script successfully.

Running the API example

As long as the environment variable PYTHONPATH is set correctly (see) we can simply run the Python script by

$ python-3.8.6/bin/python3 basic.py

and watch the simulation output:

Aspherix (Version Aspherix 7.1.0, compiled 2026-03-12-13:20:23 by vagrant, git commit 3efa378ae0fe305d4e235e2e5c66d2244884a712)
Checkout of asx_solver OK.
Created orthogonal box = (-0.1 -0.1 -1) to (1 1 1)

[... more output from the Aspherix(R) simulation ...]

Completed execution of input script. Next, we execute a single command.

[... more output from the second Aspherix(R) simulation step ...]

Completed execution of single command. Goodbye

Note, in the basic.py file above we specified the input script as basic.asx so if we run the script we must ensure that it is located where the script file is (you can verify this by using ls).