Skip to content

Installation instructions

Jump to bottom Edit New page
Tom Schoonjans edited this page Aug 10, 2024 · 42 revisions

Compiling from source

XMI-MSIM has been successfully built on Linux (Debian/Ubuntu and RHEL/CentOS/Fedora), macOS (High Sierra and up) and Windows 7 (with the 64-bit MinGW-w64 compilers installed using MSYS2). Obtain the source code from the releases section.

The following dependencies are required to build XMI-MSIM:

  • fortran 2003 compiler (gfortran >= 4.4, Intel Fortran are known to work)
  • C compiler with OpenMP support (gcc and clang). The native Mac OS X version requires that the compiler supports Objective-C as well. When compiling the GUI, a C++ compiler becomes an additional requirement.
  • HDF5
  • libxml2
  • libxslt
  • Fortran GSL bindings (FGSL) or easyRNG
  • xraylib 4.0.0+ (including Fortran bindings)
  • glib2
  • GTKMM3, Gtkmm-PLplot and libpeas (1.22.0+) for the graphical user interface (optional though highly recommended)
  • optional for the GUI: json-glib, libsoup
  • MPI (OpenMPI or Intel MPI): optional. Recommended for those that want to perform brute-force simulations with a very high number of simulated photons

All dependencies should be easy to obtain, with the exception of those projects I manage personally:

Windows users will have to compile most of these dependencies themselves, which will require them to install a bash shell with all basic UNIX utilities. Our 64-bit version was built with MSYS2 and its GCC packages.

It is absolutely critical that all Fortran packages are compiled with the exact same compiler, and this same compiler also needs to be used when building XMI-MSIM.

Compilation stages

Unpack the tarball:

tar xvfz xmimsim-x.y.tar.gz
cd xmimsim-x.y

Configure the source tree by examining the capabilities of the host system:

./configure

The configure command has a long list of options. You can have a look at them by executing:

./configure --help

A commonly used option is to change the installation destination: this can be accomplished by using the --prefix option. If your Fortran compiler does not have a standard name, you may have to specify it as an option to configure such as FC=gfortran-9. Packages that are not installed in default locations, may not be detected by the configure script and could result in the configure script aborting prematurely. This is particularly likely for packages like xraylib and/or fgsl that are installed in /usr/local. Such a problem can be avoided by setting the PKG_CONFIG_PATH environment variable manually:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

If the configure script terminates without error, try building the code by running:

make

It is not recommended to invoke make with the -j option, as it may confuse the fortran compiler.

After compilation, install the program using:

make install

This may have to be executed with root privileges.

Preparing the precompiled dataset

XMI-MSIM loads, before running a simulation, datasets of precomputed physical data into memory, depending on the exact parameters in the input file. These datasets are mostly inverse cumulative distribution functions of scattering cross-sections, which would be very computationally expensive to calculate during the simulation itself based on the corresponding probability density functions.

This file is generated using the xmimsim-db executable, which produces a file called xmimsimdata.h5 in the current working directory. After this file is created, which can take up to half an hour on slower machines, copy it to the data folder of your XMI-MSIM installation. Assuming the default installation destination was not altered, this would be /usr/local/share/xmimsim.

Note on the random number generators

XMI-MSIMs random number generators are seeded on Mac OS X and Linux using high quality noise produced by /dev/urandom. The seeds can be collected in two ways:

  1. The user launches the xmimsim-harvester daemon, which will collect seeds at frequent intervals and pass them along to XMI-MSIM when requested. The daemon is ideally started at boottime (using some initd script), or on Mac OS X, by copying the be.ugent.xmi.harvester.plist file from its installation location (prefix/Library/LaunchDaemons) to /Library/LaunchDaemons and subsequently invoking sudo launchctl load /Library/LaunchDaemons/be.ugent.xmi.harvester.plist. It should be noted that the daemon is buggy, and it is generally not recommended to use this solution.
  2. If the daemon is not running, then a separate thread is launched in XMI-MSIM at runtime which takes care of harvesting the seeds (a bit slower, but reliable).

Linux

You will need to compile XMI-MSIM from source: due to a lack of time, I am unable to produce builds for Debian, Ubuntu and Redhat based distros.

Windows

Installers containing the 64-bit binaries of XMI-MSIM for the Windows platform can be found in the Releases section. It will download and install xraylib if necessary.

The Windows releases ship with the OpenCL plug-in for XMI-MSIM. In order for this plug-in to function, you need 1) to have a videocard that supports OpenCL 1.1 and 2) have the OpenCL drivers installed as provided by your videocard's manufacturer. To confirm that this is indeed the case, try running XMI-MSIM with GPU support enabled: if it fails, an error message will be shown in the log box in red, followed by a fallback to the default Fortran implementation.

macOS

A dmg an application bundle which integrates nicely within macOS, through the use of some dedicated API's. The provided app will run on macOS Yosemite and newer (all 64-bit Intel only). After downloading, mount the dmg file and drag the XMI-MSIM app to the Applications folder.

I have been informed that this app no longer works on modern versions of macOS, and definitely not on Silicon CPUs. You will need to install with Homebrew!

Homebrew can also be used to install a more UNIX-like version of XMI-MSIM, allowing you to run the GUI and other executables from the command-line, and is required when installing XRMC with its XMI-MSIM plug-in.

In order to install XMI-MSIM using Homebrew type in a terminal:

brew install tschoonj/tap/xmi-msim

To install XRMC with XMI-MSIM support (in this case the previous command does not have to be executed since XMI-MSIM will be installed first as a dependency):

brew install tschoonj/tap/xrmc --with-xmi-msim

Add a custom footer
Add a custom sidebar
Clone this wiki locally