### Installing IMPETUS on Linux

IMPETUS can run on both Windows and Linux. In this blog post I will guide you through the steps required to get IMPETUS running on Linux. First we look at the recommended steps to install the software and license. At the end of the post I will list some issues and solutions that we have experienced in the past.

### Installing the software

From our download page you can download an installer for Ubuntu 18.04 LTS and CentOS 7. You should pick the version that is closest to your distribution. If you are using for instance Red Hat Enterprise Linux you should choose the CentOS version as those distributions are very closely related. Also note that it is usually not a problem if you are using a newer distribution than the ones we build for, for instance Ubuntu 22.04 LTS. Only if you are using an older distribution is there likely to be problems. This is the reason we build for quite old distributions – we want to cover all distributions used by our customers. If you still experience any incompatibilities with your distribution, please let us know and we will find a solution.

One important point is that IMPETUS requires to run in a window manager. It will not be possible to install the software on a server without a gui or through SSH.

When setting up IMPETUS for the first time on Linux, the first thing you should do is to download and run the installer. Download the .run file from the download page, make it executable and run it.

chmod +x ImpetusAfeaSolver_official_offline_ubuntu_amd64_engine-7.0.1_gui-7.0.3.run
sudo ./ImpetusAfeaSolver_official_offline_ubuntu_amd64_engine-7.0.1_gui-7.0.3.run

The installer will open and a wizard will guide you through the steps. We recommend to install for all users and keep the default settings. The software will in that case be installed in /opt/impetus/solver. This is the reason the installer must be run as su.

Immediately after the installer finishes, the Impetus GUI will open and you will see something like this:

However, before you set up the IMPETUS server you need to install the license. You should therefore click Cancel and then close the Impetus GUI. Then download the license file, if you have not already done so.

The license file is an .ilic file with a file name like IMPETUS_Afea_Solver_00338_License.ilic, where the number is your dongle ID. This file is not executable, you need to run a tool bundled with the IMPETUS software suite to install the license.

sudo /opt/impetus/solver/gui/implic --install IMPETUS_Afea_Solver_00338_License.ilic 

If this is successful, you should see this message:

License for IMPETUS Afea Solver has been installed successfully.

The implic tool extracts a .lic file into /opt/impetus/license and sets up the driver for the USB dongle. It also sets up an environment variable pointing to the location of the license.

### Setting up IMPETUS server

Now you are ready to set up the IMPETUS server. Open the Impetus GUI by clicking the icon or run

/opt/impetus/solver/gui/solvergui

You will see the same windows as above. Click the Install button and the following dialog opens.

The IMPETUS server runs as two systemd services, one for managing the job queue and license management, the other for starting simulations. The services can be managed by standard systemd Linux commands, but IMPETUS bundles a couple of tools to make this easier.

The services must run with the privileges of a named user account. This user account should of course not be root, but the account must have read and write access to the folders you plan to use for simulations. Specify the name of this user account and click Install.

If all goes well, you will see that both services are running and you can click on Connect.

If you see a green circle next to localhost it means that the server services are up and running. If you see a green checkbox over the key icon, you also know that the license is properly installed and valid.

You have now successfully installed IMPETUS on Linux and are ready to set up and run your simulations.

### Updating to a new version

When we release new versions of the software, there are a couple of steps you must perform to update the software. You should wait until all running simulations have finished. First, you must stop the services. To do this, click on localhost and then Stop. Then you must uninstall the previous version of the software before installing the new. To do this, open the Maintain IMPETUS Afea Solver tool:

sudo /opt/impetus/solver/MaintainSolver

and click Remove all components.

This will completely remove the previous version and you are ready to install the new version, following the same steps as above.

### Troubleshooting

For various reasons, the installation process may not always be as straightforward as described above. In the following I will list the most common problems users have had when installing on Linux.

#### implic fails to install license

implic will both extract the license and set up the driver for the USB dongle. The USB dongle is set up as a udev device, and implic will fail if udev is not installed on the system. The solution is to install udev.

sudo apt install udev

#### Missing dependencies

Some distribution may miss some dependencies required by the IMPETUS software. In particular, on AlmaLinux (based on RHEL8) the following libraries are missing:

ldd solvergui | grep not
libsnappy.so.1 => not found

This command install the missing dependencies on RHEL/Centos/AlmaLinux:

sudo yum install nss libXcomposite libXdamage libXrandr libXtst alsa-lib snappy

Even the Engine may fail due to missing dependencies:

ldd impetus | grep not
libquadmath.so.0 => not found

This can be resolved by installing the missing dependencies:

sudo yum install libgomp libquadmath

Various other distribution may miss other libraries. The solution is to detect the missing dependencies with ldd and then to install what is missing.

#### Incompatible dependencies

If you are using SUSE Linux Enterprise and downloaded the Centos version, you might get the following error during execution:

ImportError: /usr/lib/python3.6/lib-dynload/math.cpython-36m-x86_64-linux-gnu.so: undefined symbol...

The provided líbpython3.6m.so.1.0 in the engine directory might not be compatible with your system. Try removing this file from /opt/impetus/solver/engine and install a compatible one from the package manager:

sudo zypper install python3

#### Failure to install services

If the Install service operation fails in the GUI, it is possible to perform the same operation from the command line:

sudo ./impsrvctrl --install --node-install --server localhost --run-as impetus --password …

Installing impserver daemon...
SUCCEEDED
Installing impnode daemon...
SUCCEEDED

You should include both the –install and –node-install options to install both services. You can also run with only the –help option to list all available options.

If you still have problems with the services, you can run

journalctl -f -t impservice

and

journalctl -f -t impnode

to see the systemd logs for the two services. This may list relevant error messages that can help in detecting the problem.

#### Server refuses to start

After installing the service, if the IMPETUS Afea Server does not start but IMPETUS Afea Compute Nodes does, then the problem is probably that the license has not been installed. The server will not start without a license. The solution in this case is to install the license and reboot the machine. The IMPETUS Afea Server should start as expected after the reboot.

#### Connection error

The IMPETUS GUI connects to the server over TCP port 8860. If you try to connect to a server on another machine but get a connection error, make sure that port 8860 is open in the firewall.

#### 3D graphics windows are black

The Impetus GUI uses OpenGL for 3D graphics and thus requires a graphics driver installed. We recommend using the proprietary NVIDIA drivers for best performance, but the Mesa 3D software drivers can be used if necessary.

If you have problems with the 3D windows, go to File->Help->Hardware capabilities and scroll down to the OpenGL section. Here you can see the driver details that are available to the GUI. To get the full functionality of the GUI, you must have at least OpenGL 4.0.

To install graphics drivers you should look up the documentation for your Linux distribution. If you want to force the GUI to use Mesa, you can set some environment variables like this

export LIBGL_ALWAYS_SOFTWARE=1; export MESA_GL_VERSION_OVERRIDE=4.5; /opt/impetus/solver/gui/solvergui

#### Unable to detect serial number: The USB device could not be opened

If you see this error message when running a simulation:

/opt/impetus/solver/engine/impetus i= main.k

Failed to initialize:Unable to detect serial number: The USB device could not be opened.

the problem is that the driver cannot get access to the USB device. Sometimes it works again after unplugging the USB dongle and putting it back in, but generally a reboot is required to solve this problem.

#### No Qt platform plugin could be initialized

If you see this error message when trying to start the GUI:

This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, webgl, xcb.

then the problem can be that xcb is not installed on the system. (You will also see this error message if you log in through SSH or other non-GUI terminals, but that is to be expected.) In particular, the required xcb libraries might be missing from Gnome on CentOS. To add the missing libraries, run

sudo yum install libxcb*
sudo yum install xcb-util-renderutil
sudo yum install xcb-util-wm

### Summary

I hope this will make it easier to resolve the subtle problems that sometimes arise when installing on Linux. If other problems arise, let us know and we can update the list of known issues and solutions.