HomeInstallation & License management
This document will walk you through the installation process of Aspherix® GUI and Solver on Microsoft Windows and Linux.
Prerequisites
Aspherix® Solver is supported for the following operating systems:
Windows: Windows 10
Linux: CentOS / Red Hat 7 or newer, Ubuntu 16.04 or newer, Suse Enterprise 12 or newer; Most other modern Linux systems with glibc version 2.12 or higher can be used as well, but without warranty.
Aspherix® GUI is supported for the following operating systems:
Windows: Windows 10; OpenGL 3.2 or higher is required.
Linux: CentOS / Red Hat 7 or newer, Ubuntu 16.04 or newer, Suse Enterprise 12 or newer; Most other modern Linux systems with glibc version 2.17 or higher can be used as well, but without warranty. OpenGL 3.2 or higher is required.
Recommended minimal configurations: Dual or Quad Core processor, 4GB RAM, Video Card 512 MB, screen resolution 1280 x 720.
On Linux systems make sure that MPI is installed on the machine you want to run Aspherix® on. The installed version has to support MPI-3 standard (e.g., OpenMPI 1.8 or MPICH v3.0). Under Ubuntu, MPI can be installed by the following command:
sudo apt install openmpi-bin
On CentOS/Red Hat, the following command can be used:
sudo yum install openmpi
Note that both commands require administrator privileges.
On Windows systems, Microsoft MPI will be installed during the Aspherix® installation procedure. If a more recent version of Microsoft MPI is found during the installation, it will not be changed, older versions can be updated.
During the installation process on Windows also Microsoft Visual C++ Redistributables are installed automatically. In case they have been installed before, please select the option “Repair”.
For using the API of Aspherix® Solver cmake is required (minimal version: cmake 3.0).
The operating system has to be up to date and a 64 bit architecture is required.
When using an online license server, port 5053 and a second port, which is mentioned in the license file, needs to be open. For the correct installation of an inhouse license server please follow the instructions shipped with the server application or contact your IT department.
Screencasts
Screencasts for the installation and getting started can be found here:
Installation Windows: https://www.aspherix-dem.com/tutorials-windows/#installation
Installation Linux: https://www.aspherix-dem.com/tutorials-linux/#installation
Getting started on Windows: https://www.aspherix-dem.com/tutorials-windows/#gettingstarted
Getting started on Linux: https://www.aspherix-dem.com/tutorials-linux/#gettingstarted
Installation
The installation can be launched from a file browser or from a shell.
Note
Under Linux, it may be necessary to change the file permissions
of the installer to make it executable. This can be achieved by the
shell command chmod a+x path/to/installer/file
Under Windows, a security warning might pop up - click “run” to continue installation. This starting page is displayed, click “Next” to continue:
Next, you are asked to specify the installation folder for Aspherix®.
Under Windows, a location in your user directory is proposed.
Under Linux, the installer proposes a destination in your home directory if started as user, and a location in /opt if started with root privileges.
After choosing a destination folder, the installer options dialogue appears.
A license file is required to install Aspherix®, you should have received one. For demo versions, also a password is required. If you lack any of these, please contact your IT or mail to aspherix@dcs-computing.com. Next, choose if you wish to install Aspherix® for all users on the system (requires root privileges) just for this user, or (particularly interesting for the installation on clusters) “relative to installation”. For a system-wide installation it is recommended to check the “Link Aspherix into /usr” (Linux) or “Add binary to user PATH” (Windows) tickbox, so a system-wide symlink becomes available. When chosing the install option “relative to installation” the user does not need access to any particular paths as for example /etc, the configuration file is written to the share/aspherix folder, relative to the local installation.
Note that the “Unpack documentation” checkbox only becomes available once you enter a valid license file.
Please do not uncheck the option “Unpack documentation”, otherwise it will not be automatically available after the installation.
Note
If you do not have a valid license file available during installation, or if the license cannot connect to the license server you can unpack the documentation any time running aspherix -re from the command line.
Note
When chosing the bashrc option in the Availability section under Linux a new entry is added to the bashrc file. When uninstalling Aspherix® at a later time the bashrc file is reset to its state before the Aspherix® installation. Changes that are made after this time might be lost!
If none of the options in the Availability section is selected in Linux, the following block of variables can be added to your bashrc in Linux:
export PATH=$PATH:INSTALLATION_PATH/Aspherix-6.0/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:INSTALLATION_PATH/Aspherix-6.0/lib
export LIBRARY_PATH=$LIBRARY_PATH:INSTALLATION_PATH/Aspherix-6.0/lib
export C_INCLUDE_PATH=$C_INCLUDE_PATH:INSTALLATION_PATH/Aspherix-6.0/include/aspherix
export CXX_INCLUDE_PATH=$CXX_INCLUDE_PATH:INSTALLATION_PATH/Aspherix-6.0/include/aspherix
where INSTALLATION_PATH has to be replaced by your installation path.
Both in Windows and Linux, Aspherix® Solver can be launched from within the installation folder (INSTALLATION_PATH/Aspherix-6.0/bin) at any time.
Next, you can choose which components to install. Please note that all components can be installed, but only those for which a valid license is found can be used. With a pure Aspherix® Solver / HPC license it is possible to install GUI and Calibration as well but neither of the components will be functional. The Windows installer offers the possibility to install Microsoft MPI, on Linux MPI must be installed by the user. Other offered third party components are ParaView and the ParaView macros. The latter can be used with the distributed ParaView or a custom ParaView installation (ParaView 5.8.0 or newer is required) and they help with the automated visulization of the simulation results (please see tutorials for postprocessing in Aspherix® Solver documentation).
To continue with the installation, it is necessary to accept the Open Source License Agreement and the End User License Agreement:
Under Windows, it is possible to create a start menu entry:
Now everything is set up and the installation will be performed when clicking the “Install” button.
Under Windows, it is possible that a firewall warning appears during the installation process. This is because Aspherix® establishes contact with the license server to check the validity of the provided license file.
Under Windows Microsoft MPI is installed at that time as well. In case an older version is already installed, you will be asked to update to the delivered one, in case a later version is found an error message will pop up:
Now the installation is complete and Aspherix® is ready to go.
Uninstallation
To uninstall Aspherix®, launch the Aspherix_InstallManager (Aspherix_InstallManager.exe on Windows) in the Aspherix® installation folder. The following window appears:
Click “Uninstall” to perform the uninstallation.
Installation of Salome
Salome is open source software and can be used for the generation of CAD geometries and meshes for numerical simulations. It can be downloaded and used for free:
https://www.salome-platform.org/downloads/current-version
There are installers for Windows and many Linux distributions. For making Salome usable from within Aspherix® GUI please set the correct path in File/Options:
Text based installation
Aspherix® solver can also be installed without the graphical user interface using the provided installation script. This is useful on systems where no desktop environment is installed (eg. clusters). To perform the installation in interactive mode, run
$ ./AspherixInstallScript_6.0.sh -i
Alternatively, the necessary information can be provided to the script using command line options. Run
$ ./AspherixInstallScript_6.0.sh -h
to see a list of available options.
Note
The Aspherix® solver installer needs to be in the same directory as the installation script
Note
You may have to modify the permissions of the file to make it executable. Run
chmod a+x AspherixInstallScript_6.0.sh
to do so.
Description of the command line options
$ AspherixInstallScript_6.0.sh
Script for text-based installation of Aspherix-6.0
flags:
-i enable interactive mode, flag, default false
-d PATH installation Directory, path, default $HOME/DCS-Computing/Aspherix-6.0.0/
-c also install the calibration modules, default false
-g also install the GUI modules, default false
-l LICFILE path of license file ending with .lic
-p DEMOPW demo password, string, default
-s install system wide, requres sudo privileges, flag,
invokes -r , default no
-r disable use default paths relative to the installation directory instead of config files,
flag, default false
-u link to /usr/local directory, flag, default no
-U PATH usr library directory, path, default /usr/local/lib/
-D enable documentation and example extraction, flag, default false
-e set environment in .profile and .bashrc, flag, default no
-Y accept all license agreements of all selected packages, default false
-h display this text
The options are described in greater detail below. Please also refer to the graphical installation above for further details and for comparison.
-i: Interactive mode which queries the user on each option via text based input.
-d PATH: Path into which Aspherix will be installed in.
-c: If present, Aspherix Calibration will be installed and its templates will be unpacked. Note, the latter requires the correct license files and demo password (if applicable).
-g: If present, Aspherix GUI will be installed.
-l LICENSE: Path to a license file ending with .lic that was provided to you by DCS Computing.
-p DEMOPW: The demo password that you should have received from DCS Computing.
-s: Install the package configuration system wide, so that it is available for all users. Note, this requires running this script with root privileges.
-r: Install the package configuration for the current user (if -s is not set). If this flag is not set the configuration will be written into a subfolder of PATH specified by -d and will be accessible for all users of that installation.
-u: Link Aspherix executable to /usr/local/bin and place libraries into either /usr/local/lib or the path provided by -U.
-U PATH: If -u is set, Aspherix libraries will be linked to the specified PATH.
-D: If set, the installer will extract the documentation for the Aspherix toolbox and the examples. Note, this requires the correct license files and demo password (if applicable). If this is not yet available this can be performed after the installation by running aspherix -re.
-e: Set environment variables into the current users .profile and .bashrc files so that the installation information is passed to the corresponding environment variables like $PATH.
-Y: Accept, without further prompt, the license agreements and EULAs of all selected packages.
-h: Display the help text that is shown in the box above.
If you wish to review the installation or resolve an error then check the InstallationLog.txt file that is in your Aspherix installation folder. This file lists in detail any errors and provides some verbose output of the performed installation procedures.
Dependencies of the installer
Even though the installer can work without without a graphical user interface, it still has dependencies to some graphics-related libraries. If an error similar to
./Installer-Aspherix_Linux_6.0.0: error while loading shared libraries: libxcb-glx.so.0: cannot open shared object file: No such file or directory
appears during installation, some of these libraries might be missing. The full list of dependencies is
libxcb-glx.so.0
libX11-xcb.so.1
libXrender.so.1
libXext.so.6
libX11.so.6
libxkbcommon-x11.so.0
libGL.so.1
On an Ubuntu system, these dependencies can be installed via
sudo apt-get install libx11-6 libx11-xcb1 libxcb-glx0 libxrender1 libxkbcommon-x11-0 libxext6 libgl1
On CentOS, the installation command looks like
yum install fontconfig libx11 libxcb mesa-libGL libxkbcommon libxkbcommon-x11
Depending on the exact version of the system, the package names can also slightly differ.
Testing your installation
After completing the installation you might want to test your installation. To check the version of your fresh install you can run
aspherix -version
which should show an Output similar to
Aspherix (Version Aspherix 6.0.0, compiled 2022-03-12-13:20:23 by vagrant, git commit 3efa378ae0fe305d4e235e2e5c66d2244884a712)
Note
Note, if the executable is not in you PATH environment variable you might need to explictily call it using
cd /path/to/Aspherix/Installation
bin/aspherix -version
Please verify the version number and that it corresponds to the one of the installer.
Since the previous command does not use a license manager the next step is a test that does test for a valid license. To do so start Aspherix without any arguments, i.e.
aspherix
which should show an Output similar to
Aspherix (Version Aspherix 6.0.0, compiled 2022-03-12-13:20:23 by vagrant, git commit 3efa378ae0fe305d4e235e2e5c66d2244884a712)
RLM license checkout path for feature 'asx_solver' called from 'Aspherix(R) solver': /path/to/Aspherix/Installation/share/aspherix/license.lic
the program will then wait for your input and to test it you can enter
print "test"
which should be followed by test appearing on the next line. The program can be exited by entering the quit command. The full output then would look similar to the following:
Aspherix (Version Aspherix 6.0.0, compiled 2022-03-12-13:20:23 by vagrant, git commit 3efa378ae0fe305d4e235e2e5c66d2244884a712)
RLM license checkout path for feature 'asx_solver' called from 'Aspherix(R) solver': /path/to/Aspherix/Installation/share/aspherix/license.lic
print "hi"
hi
quit
If this works your installation is ready for your first simulation. To get started try out the example found in examples/solver/basic/chute_wear. You can run it with
# Linux:
mpirun -np 4 aspherix -in chute_wear.asx
# Windows:
mpiexec -np 4 aspherix.exe -in chute_wear.asx
And the output at the end should resemble the following
1 100000 811 0.044424213 0.0081736165 1658682
Loop time of 12.1986 on 4 procs for 99999 steps with 811 atoms, finish time Fri Mar 12 13:20:23 2022
Pair time (%) = 0.345505 (2.83235)
Neigh time (%) = 1.35206 (11.0837)
Comm time (%) = 0.450405 (3.69228)
Outpt time (%) = 2.72746 (22.3588)
Wall time (%) = 1.64436 (13.48)
Coupl time (%) = 0 (0)
Other time (%) = 5.67878 (46.5528)
Nlocal: 202.75 ave 330 max 0 min
Histogram: 1 0 0 0 0 0 0 2 0 1
Nghost: 18 ave 38 max 0 min
Histogram: 1 0 1 0 0 0 1 0 0 1
Neighs: 126.5 ave 235 max 0 min
Histogram: 1 0 1 0 0 0 0 0 1 1
Total # of neighbors = 506
Ave neighs/atom = 0.623921
Neighbor list builds = 2121
Dangerous builds = 0
Note, due to performance differences the numbers shown above might differ to the ones you might obtain. At this point we can confidently say that your installation was successful.
Upgrading to a newer version of Aspherix®
Currently only one version of Aspherix® can be installed on a system at once. If you want to upgrade to a newer version, please uninstall the old version (see section Uninstallation) and install the new version (see section Installation).
License management
Independently of the purchased number of coins Aspherix® can be installed on an arbitrary number of machines. The coins only restrict the number of parallel usage of the products. A continuous contact to a license server is required. The connection is checked every 100 seconds, and if 4 connection checks fail, Aspherix® shuts down automatically. Depending on the product you are using, the license server has to be reached via the internet or within your companies intranet.
Online license server
For running Aspherix® with an online license server, the user only requires a license file and in some cases a password.
The license server is hosted at an online server. For a successful connection both port 5053 and a second, server depended port have to be accessible at server ls61.rlmcloud.com (please have a look at the troubleshooting section regarding connectivity checks). A constant, stable internet connection is required througout the usage of any Aspherix® product. Short interruptions may be tolerated, but they must not exceed 400 seconds.
In-house license server
For running Aspherix® with an in-house license server, the user has to install a license server on a local machine which requires a setting and a license file. The license file also needs to be used when activating the local installations of the Aspherix® products within the network.
The in-house server needs to be hosted on a machine that is accessible by any device on which an installation of Aspherix® is installed. The connection to the license server has to be stable. Ports used for communication with the license server can be changed by the IT and must be set accordingly in the license file. For further informations check the instructions shipped with the server application. Short interruptions may be tolerated, but they must not exceed 400 seconds.
Note
Usually an in-house server uses three ports. One is for the optional web-service, the other two are essential for the communication between Aspherix® and the license server.
Troubleshooting
In this section we have collected a few situations that can occur during installation and usage and their resolution. If you are experiencing any other issues please to not hesitate to contact us (e.g., via aspherix@dcs-computing.com). In case the issues are experienced during the installation, please always attach the installation log file (InstallationLog.txt in your installation folder).
Testing connectivity to the license server
Aspherix® needs to be able to connect to the license server. To test connectivity, the following commands might be useful:
Linux:
ping my-server.address
nmap -sS my-server.address -p 5053
telnet my-server.address 5053
Windows Powershell:
ping my-server.address
Test-NetConnection my-server.address -Port 5053
The license server address and the used ports can be found in the license file.
License activation fails
Problem description: The installation process starts normally but is interrupted by an error-message that reports an issue with the license (E.g., “Could not check out XXX license as communication with the license server failed. Make sure that both RLM ports can be reached from your machine.” or “License server does not support this product” or “Error during checkout of license”).
Cause: connection to the license server could not be established due to lacking internet connection or closed ports.
Measures:
Reading the output:
Should you get the error message: “Could not check out XXX license as communication with the license server failed. Make sure that both RLM ports can be reached from your machine.”. Then, Aspherix will automatically attempt to verify that the required ports are available.
You should see at least one status line saying “Detecting ports in XXX.” followed by the server designation of that license file.
Aspherix will find at least one of the two RLM ports and you will see a line starting with “Testing Port: YYYY”.
If this is followed by the word “Success” then the corresponding port is available.
If this is followed by “Error: Could not connect after 3 attempts” this port is closed and you or your IT department must open it up.
If Aspherix can only detect one of the two ports you will see a message stating: “Could not detect both ports in this file.” In this case you must test the second port manually as demonstrated below.
For online licenses:
Make sure that the computer is connected to the internet.
Check if the online license server can be reached through port 5053. Use the following command: - on Windows: in the PowerShell type
Test-NetConnection ls61.rlmcloud.com -Port 5053
on Linux: depending on the availability of the tools on your system, type either
nmap -sS ls61.rlmcloud.com -p 5053or
telnet ls61.rlmcloud.com 5053to a terminal.
For inhouse-license servers:
Please contact your IT department and make sure that the required ports (per default 5053, 5054 and a third random port) are open. Keep in mind that the ports can be changed by the IT and must be set accordingly in the license file.
For the network connectivity tests the name/address of the internal license server has to be used.
Installer does not start (Windows)
Problem description: double-clicking on the installer does not launch the installation process.
Cause: On “fresh” Windows systems it is likely that redistributables are still missing.
Measures: Please install both 32 and 64 bis redistributables for visual studio 2015-2022:
Installation error – Execution fails with aspherix -re
Problem description: The installation process starts normally but is interrupted by an error message stating “Error during installation process (com.dcscomputing.aspherix): Execution failed (Unexpected exit code 1): “[some path]/aspherix.exe -re”
Cause: the documentation could not be unpacked, Aspherix® Solver (and if included also Aspherix®GUI) were installed correctly.
Measures: please carry on with the installation process and once completed, open a PowerShell. Run aspherix with the flag -re (e.g., by typing the command displayed between the two commas in the error message.
Installation error – Execution fails with msmpisetup.exe (on Windows)
Problem description: The installation process starts normally but is interrupted by an error message stating “Error during installation process (com.dcscomputing.aspherix): Execution failed (Unexpected exit code [some number]): “[some path]/msmpisetup.exe”
Cause: some anti-virus software tools block the execution of the Microsoft installer of MS MPI.
Measures: if possible, please switch off the anti-virus software, un- and re-install Aspherix®.
Installation error - Unpacking of Aspherix Calibration templates fails
Problem description: The following error message pops up during the installation: “Error during installation process (…): …/aspherix_calibration extract_templates -license_path …”
Cause: No Aspherix Calibration license is available but Aspherix Calibration is selected for installation (default setting).
Measures: if Aspherix Calibration has not been purchased, this error message can be ignored. If Aspherix Calibration should be available please contact DCS Computing.
Aspherix® GUI starts but the simulation cannot be launched (Aspherix® GUI only)
Cause 1: Aspherix® GUI finds the license file correctly but Aspherix® Solver does not. Measures: Please open a terminal (Linux) or a PowerShell (Windows) and configure aspherix with the following command:
aspherix -configuration user -lp [path to the license file] -dp [demo password]
Please note that the option -dp is only required when
using a demo version. Customers with the own online license server or
inhouse server do not need it.
Cause 2: There are no Aspheri® Solver coins left because they are all currently in use. Measures: Please check if you or another user in your institution is running simulations. If the number of running processes is equal to the available number of Aspherix®Solver coins you will have to wait until coins are available. This case is indicated by a coin-checkout error message in the simulation log window.
Cause 3: The license for Aspherix® Solver is expired while the license for Aspherix®GUI is still valid. Measures: In this case please contact us (e.g., via aspherix@dcs-computing.com).
Aspherix® GUI cannot be launched with OpenGL errors
On Linux make sure an OpenGL library (version 3.2 or higher) is installed on the system.
Debian variants: libopengl0
RHEL/CentOS variants: libglvnd-opengl
On systems without hardware acceleration and proper drivers, as on virtual machines, the following startup command might be useful to ensure proper rendering:
LIBGL_ALWAYS_SOFTWARE=1 MESA_GL_VERSION_OVERRIDE=3.2 ./aspherix-gui
Windows needs adequate graphics acceleration, since it natively only supports very old OpenGL versions.
Graphics preview in Aspherix® GUI does not show anything
On Linux make sure an OpenGL library (version 3.2 or higher) is installed on the system.
Debian variants: libopengl0
RHEL/CentOS variants: libglvnd-opengl
On systems without hardware acceleration and proper drivers, as on virtual machines, the following startup command might be useful to ensure proper rendering:
LIBGL_ALWAYS_SOFTWARE=1 MESA_GL_VERSION_OVERRIDE=3.2 ./aspherix-gui
Windows needs adequate graphics acceleration, since it natively only supports very old OpenGL versions.
Aspherix® GUI cannot be launched on multi-gpu systems
On multi-gpu systems Aspherix® GUI may crash due to conflicts between different GLX versions.
For instance, you may get error messages like
qt.glx: qglx_findConfig: Failed to finding matching FBConfig for QSurfaceFormat(version 2.0, options QFlags<QSurfaceFormat::FormatOption>(), depthBufferSize -1, redBufferSize 1, greenBufferSize 1, blueBufferSize 1, alphaBufferSize -1, stencilBufferSize -1, samples -1, swapBehavior QSurfaceFormat::SingleBuffer, swapInterval 1, colorSpace QSurfaceFormat::DefaultColorSpace, profile QSurfaceFormat::NoProfile) Could not initialize GLX
To resolve this problem the following startup command tries to enforce the correct environment
QT_OPENGL=software LIBGL_ALWAYS_SOFTWARE=1 MESA_GL_VERSION_OVERRIDE=3.2 QT_XCB_GL_INTEGRATION=xcb_egl ./aspherix-gui
Paraview cannot be launched from within the GUI (Aspherix® GUI only)
Problem description: The simulation could be launched successfully, and output data should have been written to the drive already. Nevertheless, the “Start Paraview” button in the visualiuation section remains inactive.
Cause: The path to the Paraview executable is unknown to Aspherix® GUI or Paraview has not been installed.
Measure: If paraview is installed on the machine, please open the Options dialogue (File/Options) and set the correct path. Once saved, the “Start Paraview” button will become active if simulation data is available. If paraview is not yet installed, please install it (this can also be done during the installation of Aspherix®).
Paraview cannot be launched
Problem description: The simulation could be launched successfully, and output data should have been written to the drive already. The “Start Paraview” button in the visualiuation section is active but Paraview does not launch. (Mainly for Ubuntu 20.04, but can happen at other Linux OS as well).
Cause: libOpenGL.so(.0) is not available on the system.
Measure: Please go to the installation path of Paraview and check if it can launched via the terminal from there. If the library is missing, a correct error message will be displayed. Please install the missing library then.
Paraview cannot be launched
Problem description: The simulation could be launched successfully, and output data should have been written to the drive already. The “Start Paraview” button in the visualiuation section is active but Paraview does not launch. (Mainly for Ubuntu 18.04 and Paraview 5.10.1, but can happen at other Linux OS as well).
Cause: libcurl.so(.4) is not available on the system.
Measure: Please go to the installation path of Paraview and check if it can launched via the terminal from there. If the library is missing, a correct error message will be displayed. Please install the missing library (on ubuntu: libcurl4) then.
Aspherix® GUI does not run stable in virtual machine (VM)
Problem description: Aspherix® GUI shuts down unexpectedly in VM.
Cause: The VM itself can trigger this behaviour when the option “Accelerate 3D Graphics” is activated.
Measure: Swtich off “Accelerate 3D Graphics” option in settings of VM.
Aspherix® does not find libmpi* (OpenSUSE)
Problem description: Aspherix® does not find libmpi* on OpenSUSE.
Cause: OpenMPI is not added to the path automatically when installed.
Measure: Add OpenMPI to path manually.