Setting up `musrfit` on Different Platforms¶

Supported Operating Systems and Software Requirements¶

This page is intended to demonstrate for the interested user which steps are necessary to set up the free software μSR data analysis framework musrfit. While the preferred way is to run the software on GNU/Linux or MacOS X/macOS, with some restrictions it can also be set up under MS Windows (cygwin, only for the very brave, probably it is easier for most MS Windows users to install a Virtual Machine running Linux).

Note

In case musrfit should be installed according to the description found on this page, the user is strongly encouraged to read completely each section dealing with the present installation step before starting the installation process!

Apart from GCC, the GNU Compiler Collection (gcc, g++), the build tool cmake is needed. Furthermore the helper tool pkg-config needs to be in place, and musrfit requires the installation of a few open-source libraries and programs including their header packages:

boost C++ libraries: The powerful Spirit parser framework used by musrfit is included in that collection of libraries. Required version ≥ 1.33 (see boost C++ libraries).

GNU Scientific Library: A numerical C and C++ library which provides efficient implementations of various mathematical routines. Required version ≥ 1.9 (see GNU Scientific Library).

FFTW: A C implementation for the fast computation of discrete Fourier transforms. Required version ≥ 3.1 (see FFTW).

ROOT: A C++ data analysis framework developed at CERN. Required version ≥ 5.22 (see ROOT).

libxml2: The XML C parser and toolkit of gnome. Required version ≥ 2.0 (see libxml2).

Additionally, only if musrfit should support reading of data files in the NeXus format the following libraries are needed:

HDF4: A library and multi-object file format for storing and managing data (see HDF4). HDF4 is “outdated” and its support will soon be dropped. The single only reason why it is still required is that ISIS is not able to cope to implement HDF5 V2 of the NeXus muon instrument specification which has been agreed in 2012!

HDF5: A data model, library, and file format for storing and managing data (see HDF5).

minixml: A small XML library that can be used to read and write XML and XML-like data files. Required version ≥ 2.2 (see minixml). Currently the MXML support in NeXus is broken and hence you will not need to install minixml for the time being.

NeXus: A common data format for neutron, x-ray, and muon science. Required version ≥ 4.4 (see NeXus).

If optionally the editor and graphical user interface musrgui / musredit is going to be installed there is one further requirement:

Qt: A cross-platform application and user interface framework. Required version ≥ 4.6 (musredit) (see Qt). Currently the Qt5 is still supported since some older distributions are not yet supporting Qt6. Qt6 is the main development part. Should be available on all new major distributions.

Each of the following sections focusing on the installation of musrfit on the different operating systems will also give a brief introduction on the installation of the requirements before the actual musrfit installation is described.

OS Restrictions¶

Before the installation procedure will be described, please note the following restrictions:

GNU/Linux

No serious problems are currently known. Tested distributions: RHEL (also Alma, Rocky), Fedora, Debian, Ubuntu, Mint, openSUSE, and Manjaro.

Mac OS X/macOS

No serious problems are currently known for macOS ≥ 10.6. musrfit is Apple Silicon ready.

MS Windows

Native MS Windows support is currently not available. Potential ways to get musrfit running are:

via installation of Linux via the Microsoft App store for Windows 10/11 (see Install Linux on Windows with WSL).
via installation of the virtual machine on which you install Linux (probably the easiest for most Windows users).

GNU/Linux¶

Requirements¶

Everything but ROOT and NeXus¶

Depending on the GNU/Linux distribution chosen, the above mentioned software – except ROOT/CERN and NeXus – should be available from the distributor and could be easily installed in the form of binary packages. If done in this way there should be taken care of installing both, the libraries and the header (dev, devel) files.

On a Red Hat Linux (or other RPM-package base Linux distributions) system the following command executed as superuser from the shell will do the trick (never type the ‘$’ it is the shell prompt of your system):

For Qt4 (deprecated):

$ yum install git cmake boost-devel gsl-devel fftw-devel libxml2-devel qt-devel qtwebkit-devel

For Qt5/Qt6:

$ yum install epel-release
$ yum install git cmake boost-devel gsl-devel fftw-devel libxml2-devel qt6-qtbase-devel qt6-qtsvg-devel

If using Qt5, since e.g. Qt6 is not available, replace qt6-qtbase-devel qt6-qtsvg-devel by qt5-qtbase-devel qt5-qtsvg-devel

When dealing with a distribution that uses the dpkg/apt package manager like Debian or Ubuntu the installation would look like:

For Qt4 (deprecated):

$ apt-get install git cmake libboost-dev libboost-filesystem-dev libboost-system-dev libgsl-dev libfftw3-dev libxml2-dev libqt4-dev libqtwebkit-dev

For Qt5/Qt6:

$ apt-get install git cmake libboost-dev libboost-filesystem-dev libboost-system-dev libgsl-dev libfftw3-dev libxml2-dev qt6-base-dev qt6-svg-dev

If using Qt5, since e.g. Qt6 is not available, replace qt6-base-dev qt6-svg-dev by qtbase5-dev libqt5svg5-dev

Everyone should know best himself which is the way to install distribution software on the chosen distribution.

In case the distribution does not include the required software it has to be compiled from the source files. This means either to download the source code from the corresponding website, or to clone the git repo. If you need to follow this line, please check the install details of the corresponding package.

For any further information on the standard installation of software, please refer to the web search engine of choice and ask for “install software on linux”…

Installation of NeXus requirements (optional)¶

Only if musrfit should support reading/writing data files in the NeXus format the further required software has to be set up. The required libraries and header files could either be available through the user’s GNU/Linux distribution or if this is not the case, the packages can be installed from the source code. In principle NeXus should support MXML, HDF4, and HDF5. At the time of this writing, the MXML support in the NeXus project is broken, and HDF4 is outdated on most platforms, yet since ISIS/RAL is still not up-to-date HDF4 still needs to be dragged on (comment: if you are a ISIS user, please complain about HDF4). Hence, the necessary packages to build NeXus are HDF4 and HDF5. This means, for a rpm-package based distro try something like:

$ yum install hdf-devel hdf5-devel

and on a deb-package based distro try something like:

$ apt-get install libhdf4-dev libhdf5-dev

Only NeXus Version ≥ 4.4 is support!

Even though there might exist binary packages for the NeXus library, it is best to build and install it directly from the source code which can be found here.

A brief instruction how to get NeXus compiled from source (lines starting with ‘#’ are comments only):

$ cd Downloads
$ # create a directory for the NeXus source code
$ mkdir nexus
$ cd nexus
$ # get the source code from the master repository
$ git clone https://github.com/nexusformat/code.git
$ # next we will build NeXus out-of-source
$ mkdir build
$ cd build
$ cmake -DENABLE_HDF5=1 -DENABLE_HDF4=1 -DENABLE_MXML=0 ../code
$ cmake --build ./ --clean-first
$ # install needs either to be carried out as root or sudo depending on your linux flavour.
$ sudo cmake --install ./

ROOT¶

The ROOT framework may or may not be part of the GNU/Linux distribution. Some distributions are packing ROOT in a manner incompatible with the way it is needed by musrfit, though the situation is improving. If you are experienced enough you can try the packed ROOT version. Often ROOT is split in many sub-packages. Install the necessary ones (guess from the description below). One Warning: if the ROOT packages are upgraded after a yum update (apt-get update; apt-get upgrade) you might need to recompile musrfit. If you are not sure about all this: install ROOT from source. Before installing ROOT from source you will need to install some additional header packages.

For RPM based systems (RedHat, Fedora, etc) this will likely to be libX11-devel, libXft-devel, libXpm-devel, and libXext-devel:

$ yum install libX11-devel libXft-devel libXpm-devel libXext-devel

For a dpkg/apt based system (Debian, Ubuntu, etc) this will likely to be libx11-dev, libxft-dev, libxpm-dev, and libxext-dev:

$ apt-get install libx11-dev libxft-dev libxpm-dev libxext-dev

Also make sure that you have installed all required packages listed under Required Software (e.g. fftw, gsl, etc).

In the following it is assumed that ROOT shall be installed under $HOME/Apps. If you want to install it somewhere else, just systematically replace the related terms of the following description. For the following list of commands the ‘$’ will be given, the command prompt. Do not enter it! Also some comments will be added starting with a ‘#’ which can be omitted. They are only there to explain what is going on.

$ cd $HOME
$ # creat the Apps directory if not already present
$ mkdir Apps
$ cd Apps
$ git clone http://github.com/root-project/root.git
$ cd root
$ git tag -l
$ # git tag -l will list all available tags. In the next command choose the tag v6-xx-yy
$ # where xx is the highest listed number, e.g. v6-32-08.
$ # use only even numbers of xx
$ git checkout -b v6-32-08 v6-32-08
$ # now ROOT is ready to be configured. Below you will find the minimal ROOT configuration needed.
$ # since we are using cmake build now, first we will need to create the build directory.
$ mkdir root_build
$ cd root_build
$ cmake ../ -Dgminimal=1 -Dasimage=1 -Dmathmore=1 -Dxml=1 -DCMAKE_INSTALL_PREFIX=../root_exec
$ # next will be the make called via cmake. If running on a multicore CPU you can speed up tremendously by
$ # calling it with the option -j <number>, where <number> is the number of threads which you want to give,
$ # e.g. cmake --build ./ --clean-first -- -j8
$ cmake --build ./ --clean-first
$ # as a last step of the ROOT build process we need to install it
$ cmake --install ./

What is still missing is that the system should be told where to find the ROOT installation, therefore the following is suggested:

As superuser create a file /etc/ld.so.conf.d/cern-root.conf where the path to the lib directory of ROOT is added and call /sbin/ldconfig afterwards. In the example mentioned above one way of doing this is (<home> has to be the path to your home, e.g. /home/luke_skywalker):
```
$ echo "<home>/Apps/root/root_exec/lib" >> /etc/ld.so.conf.d/cern-root.conf
$ /sbin/ldconfig
```
Additionally, as normal user one should append the following lines to the ~/.bashrc and/or ~/.bash_profile (~./profile on Debian like systems, and then either restart the shell or call the same commands once more from the shell) in order to change some path-setting environment variables:
```
$ export ROOTSYS=$HOME/Apps/root/root_exec
$ export PATH=$ROOTSYS/bin:$PATH
```

If an update of ROOT is needed, simple do the following:

$ cd $HOME/Apps/root
$ git pull
$ cd root_build
$ cmake --build ./ --clean-first

musrfit¶

When all required software has been set up you can proceed with the musrfit installatio. First, the most recent source code should be downloaded. The preferred way of doing so is to clone the musrfit repository via git. Assuming the code should be located in $HOME/Apps this is achieved most easily calling from the terminal

$ cd $HOME/Apps
$ git clone https://bitbucket.org/muonspin/musrfit.git
$ cd musrfit

or

$ cd $HOME/Apps
$ git clone git://gitlab.psi.ch/nemu/musrfit.git
$ cd musrfit

Note

after cloning the musrfit repo you will automatically be on the root6 branch. If you want to get legacy ROOT 5.34.xx support, you will needed to switch branches first.

Update: If a local repository clone is already present (it needs to be newer than Dec. 2016), one can update it using:

$ cd $HOME/Apps/musrfit
$ git pull
$ cd build
$ xargs rm < install_manifest.txt
$ cmake --build ./ --clean-first
$ cmake --install ./

As an alternative (if git is not available), the source code can also be downloaded from the following web-page: musrfit at bitbucket

musrfit build with cmake¶

Currently the following configuration switches for musrfit are available:

-DCMAKE_INSTALL_PREFIX=<prefix-path>: Specify the installation prefix, i.e. the place where musrfit shall be installed, e.g. $ROOTSYS if already defined (by default: /usr/local).
-Dnexus=<value>: enable/disable the support of NeXus data files (requires the HDF4, HDF5 and NeXus libraries to be installed). <value>=1 enables NeXus, <value>=0 disables NeXus. The default setting, i.e. the switch is not provided is NeXus support is disabled.
-DASlibs=<value>: enable/disable the ASlibs. <value>=1 enables the ASlibs, <value>=0 disables the ASlibs. The default setting, i.e. the switch is not provided is ASlibs support is disabled. For details see Documentation of user libs.
-DBMWlibs=<value>: enable/disable the BMWlibs. <value>=1 enables the BMWlibs, <value>=0 disables the BMWlibs. The default setting, i.e. the switch is not provided is BMWlibs support is disabled. For details see Documentation of user libs.
-DBNMRlibs=<value>: enable/disable the BNMRlibs. <value>=1 enables the BNMRlibs, <value>=0 disables the BNMRlibs. The default setting, i.e. the switch is not provided is BNMRlibs support is disabled.
-Dqt_based_tools=<value>: Will try to get musredit, musrWiz, musrStep, and mupp installed, if Qt is found. By default this is enabled. Again <value>=0 means disabled, <value>=1 enabled.
-Dqt_version=<value>: Allows to specify which Qt version shall be tried. <value> can take the values: AUTO, 3, 4, 5, 6. If the value is set to AUTO, this highest installed version is chosen, otherwise the specified version is used.
-Dtry_OpenMP=<value>: Will check if OpenMP support is possible, and if yes use it. The default is enabled

Normally it should not be necessary to make use of any of the options except for specifying the installation path with -DCMAKE_INSTALL_PREFIX. musrfit build with cmake takes the out-of-source approach. Therefore a typical configuration / make / install process including NeXus support would look like

$ cd $HOME/Apps/musrfit
$ mkdir build
$ cd build
$ cmake ../ -DCMAKE_INSTALL_PREFIX=$ROOTSYS -Dnexus=1
# below it is assumed that multiple cores are present, hence the -j8 option
$ cmake --build ./ --clean-first -- -j8
$ cmake --install ./
$ /sbin/ldconfig                                  # (as superuser)

musrfit last step of the installation¶

In order to finish the installation of musrfit two more things should be done:

Define the MUSRFITPATH environment variable containing the path to the musrfit executables and XML files. E.g. if the location of the example above is used append the following line to the ~/.bashrc and ~/.bash_profile (and then either restart the shell, source the file, or call the same commands once more from the shell):
export MUSRFITPATH=$ROOTSYS/bin
Adjust the paths where musrfit will search for data files in the installed musrfit_startup.xml. For detailed information on this XML file refer to the manual.

musredit¶

In the latest version of musrfit the configure script tries to determine automatically the highest available Qt version. In case this is found, the editor musredit is built already together with musrfit.

musrgui (deprecated)¶

If Qt4.6 or higher is not available but Qt3 is set up musrgui can be installed. For this please follow the instructions for the musredit installation where simply every musredit occurrence has to be replaced by musrgui. If there are problems during the qmake step, e.g. “uic: File generated with too old version of Qt Designer”, this most probably means the Qt4 version of qmake is being used. In order to use the Qt3 version it should be enough to specify the full path to its location when calling it. Within the most GNU/Linux distributions this location will be something like /usr/lib/qt-3.3/bin/qmake.

Check the installation¶

In order to perform a quick test for finding out if the installation has been completed successfully, a few msr files together with the corresponding data files can be found in the musrfit source tree at doc/examples/. If musrgui has been installed, just open one of the test-*.msr files in the editor and test the musrfit functionalities. Otherwise, if only the terminal should be used, as an initial test for instance the following could be done:

$ cd $HOME/Apps/musrfit/doc/examples
$ musrview test-histo-ROOT-NPP.msr

MS Windows¶

Note

For adventurous guys using Windows 10/11, there is the possibility to activate the built in Ubuntu bash-shell. It allows to install musrfit as described in the Linux section. For details to setup the Linux sub-system for MS Windows see Install Linux on Windows with WSL.

Note

Another possibility is to setup linux as a virtual machine with VirtualBox are other alike tools. This way you separate Linux / ROOT / musrfit from the default MS Windows system.

Note

One more advice: Please never try to install either ROOT or musrfit from or to a directory containing spaces in the absolute path or in case you do, do not wonder if some errors occur! msr files, however, might be saved in such directories like ...\My Documents\...

Mac OS X / macOS¶

Note

macOS 15 alias Sequoia: musrfit is ready for Sequoia on Intel and Apple Silicon based macs, both running natively. The DKS version of musrfit for macOS Sequoia is ready as well. This is true for the Homebrew, MacPorts still has some issues (as of 23.09.24). Typically this should be fixed in a month.

Note

Starting from macOS Catalina some acpects are slightly different compared to older macOS versions, so if it happens that you have installed one of these last versions, please first check Notes on macOS Catalina and newer before you proceed.

With Mac OS X / macOS the situation is up to some extent similar like on MS Windows but still different since Mac OS X is a UNIX system. The similarity is that also on OS X a helping framework — either MacPorts or Homebrew — which provides open-source software is employed to fulfill the basic software requirements of musrfit. In the following, both possibilities (using MacPorts or Homebrew) are described but it is emphasized here that it should be followed only one of the possible routes .

Warning

If you decide to upgrade your macOS, e.g. from High Sierra to Mojave, you will typically need to unistall musrfit, ROOT, and MacPorts / Homebrew first, do the upgrade of the macOS and start the installation of MacPorts / Homebrew , ROOT, and musrfit from scratch!

Requirements (MacPorts)¶

Before proceeding with the usage of the MacPorts system first a few useful tools provided by Apple together with OS X (on the installation DVD/CDs) should be installed:

Xcode
Useful developer tools including for instance the GNU compiler collection. It can be installed via the Apple App store. Starting from XCode ≥ 4.3 the command line tools need to be installed manually. The necessary command line tools can be installed via the following commands entered in the terminal
$ xcode-select --install
$ sudo xcodebuild -license

X11: The X-window system is automatically installed on 10.5 Leopard and 10.6 Snow Leopard. For some other versions you also will need to install XQuartz. If ROOT runs without XQuartz do not install it.

After installing the Xcode tools go to the MacPorts install page, download the installer for your system and follow the installation instructions on the page. By default the MacPorts system will be installed in /opt/local. To be sure that the newest version of the software is used a MacPorts upgrade should be performed by typing in a terminal:

$ sudo port -v selfupdate

Remark: MacPorts uses rsync in order to synchronize the list of available packages. It frequently happens that this service is blocked by firewalls. In this case it should be possible to download a local version of the package repository and do the synchronization. If this step becomes necessary (and only then) it can be done in the following way:

Get a local version of the repository:

$ svn co http://svn.macports.org/repository/macports/trunk/dports ~/dports

Edit the file /opt/local/etc/macports/sources.conf: At the end of the file, comment the line beginning with rsync:// and add a new line pointing to your local copy, e.g.
```
file:///Users/username/dports
```
Synchronize the packages:
```
$ sudo port -v -d sync
```

Then the MacPorts system should be set up and can be used to install additional software.

The installation of the software mentioned above is then done in the terminal:

$ sudo port -v install pkgconfig autoconf automake libtool cmake libomp fftw-3 fftw-3-single gsl boost libxml2 qt6 qt6-qtsvg

With Qt6, musredit will be installed. If it happens that you used musrgui in the past, please change over to musredit since there will be no further development for musrgui anymore!

Installation of NeXus requirements (optional)¶

Only if musrfit should support reading data files in the NeXus format the further required packages are set up:

$ sudo port -v install hdf4 hdf5

hdf4 is likely not available anymore.

Only NeXus Version ≥ 4.4 is support!

To get things compiled do:

$ # get and install NeXus
$ cd $HOME/Applications
$ # get the source code from the master repository
$ git clone https://github.com/nexusformat/code.git nexus/code
$ # next we will build NeXus out-of-source
$ cd nexus
$ mkdir build
$ cd build
$ # in case hdf4 is present
$ cmake -DENABLE_HDF5=1 -DENABLE_HDF4=1 -DENABLE_MXML=0 ../code
$ # in case hdf4 is **not** present
$ cmake -DENABLE_HDF5=1 -DENABLE_HDF4=0 -DENABLE_MXML=0 ../code
$ cmake --build ./
$ sudo cmake --install ./

ROOT¶

The default ROOT version is based on ROOT 6.xx/yy!

ROOT installed via package installer¶

The lazy way to get ROOT installed is via package installer. If your macOS is directly supported by the ROOT people you can download the package installer from the ROOT download page. Choose the latest ROOT release and download you macOS version dmg-file, e.g. for macOS 10.13 (High Sierra) it is at the time of writting root_v6.16.00.macosx64-10.13-clang91.dmg. After the installation ROOT will be installed under /Application as owner root. In order to ease your life for the steps to follow and assuming you are the only guy working on your Mac, you could change the owner and group of the ROOT directory:

$ cd /Applications
$ sudo chown -R <username> root_v6.22.00
$ sudo chgrp -R staff root_v6.22.00
$ sudo ln -s root_v6.22.00 root

ROOT installed from source¶

The best way to get ROOT exactly the way needed for musrfit is to install it from source. Before describing it, please make sure that you have installed all required packages listed under Requested Software (e.g. fftw, gsl, etc).

For the following it is assumed that ROOT shall be installed under $HOME/Applications. If you want to install it somewhere else, just systematically replace the related terms of the following description. For the following list of commands the ‘$’ will be given, the command prompt. Do not enter it! Also some comments will be added starting with a ‘#’ which can be omitted. They are only there to explain what is going on.

$ cd $HOME/Applications
$ git clone http://github.com/root-project/root.git
$ cd root
$ git tag -l
$ # git tag -l will list all available tags. In the next command choose the tag v6-xx-yy
$ # where xx is the highest listed number, e.g. v6-32-08.
$ # use only even numbers of xx
$ git checkout -b v6-32-08 v6-32-08
$ # now ROOT is ready to be configured. Below you will find the minimal ROOT configuration needed.
$ # We will use the cmake out-of-source approach here.
$ mkdir root_build
$ cd root_build
$ cmake ../ -Dgminimal=1 -Dasimage=1 -Dmathmore=1 -Dxml=1 -Dopengl=1 -Dbuiltin_glew=1 -Ddataframe=1 -DCMAKE_INSTALL_PREFIX=$HOME/Applications/root/root_exec
$ # next will be the make. If running on a multicore CPU you can speed up tremendously by calling
$ # make with the option -j <number>, where <number> is the number of threads which you want to give,
$ # e.g. make -j8
$ cmake --build ./ --clean-first -- -j8
$ # make will take quite a while
$ cmake --install ./

For further details see Installing ROOT from Source.

Setting up Environment Variables for ROOT and musrfit¶

Since Apple in its wisdom decided that programs started from a shell are treated differently than Apps if it is coming to system variables, we need to work harder compared to a Linux system.

For Mac OS X < 10.8:

In order to finalize the ROOT installation and to prepare already the installation of musrfit and musredit this is a good time for setting necessary environment variables for the use in Mac OS X. Here it assumed that you installed ROOT from source. If you downloaded the binary package, you will need to adopt the paths accordingly. Put the following lines (without the comments in parentheses and with the paths adjusted to your local installation) into the file ~/.MacOSX/environment.plist and re-login:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
      <key>MUSRFITPATH</key>
      <string>$HOME/Applications/root/root_exec/bin</string> (where to find the musrfit executables)
      <key>QTDIR</key>
      <string>/opt/local/lib/qt3mac</string>                 (where to find Qt3 (for musrgui) or Qt4 (for musredit))
      <key>ROOTSYS</key>
      <string>$HOME/Applications/root/root_exec</string>     (where to find the ROOT system)
</dict>
</plist>

For Mac OS X ≥ 10.8:

One needs to add some system variables in ~/.zprofile:

export ROOTSYS=$HOME/Applications/root/root_exec
export MUSRFITPATH=$ROOTSYS/bin
export PATH=$ROOTSYS/bin:$QTDIR/bin:$PATH
export DYLD_LIBRARY_PATH=$ROOTSYS/lib:/usr/local/lib:$DYLD_LIBRARY_PATH

launchctl setenv ROOTSYS $ROOTSYS
launchctl setenv MUSRFITPATH $MUSRFITPATH
launchctl setenv PATH $PATH
launchctl setenv DYLD_LIBRARY_PATH $DYLD_LIBRARY_PATH

After this you will need to “execute” .zprofile or .profile before proceeding:

$ source $HOME/.profile

Notes on macOS Catalina and newer¶

Apple introduced a couple of changes starting from macOS Catalina compared to its previous versions of macOS which might be a stumble block. Here I very briefly try to add some notes in order to get a smooth installation for musrfit.

You should switch from the bash to the zsh. Please check, e.g. Moving to zsh.
Instead of .profile you will need to setup a .zprofile.
macports: currently there is a little nuisance with the fftw-3 port. My bug report is already out since a while but no proper fix is available. The workaround to get it right is to install the port from source which is done by
```
$ port -s install fftw-3
```
If you fail to do so, you might trigger a crash in the Fourier transform for 2^N, N=12.

Requirements (Homebrew)¶

Before proceeding with the usage of Homebrew, first a few useful tools provided by Apple together with OS X (on the installation DVD/CDs) should be installed:

Xcode

Useful developer tools including for instance the GNU compiler collection. It can be installed via the Apple App store. Starting from XCode ≥ 4.3 the command line tools need to be installed manually. The necessary command line tools can be installed via the following commands entered in the terminal

$ xcode-select --install
$ sudo xcodebuild -license

X11

The X-window system is automatically installed on 10.5 Leopard and 10.6 Snow Leopard. For some other versions you also will need to install XQuartz. If ROOT runs without XQuartz do not install it.

After installing the Xcode tools go to the Homebrew page, and follow the installation instructions there.

The essential packages (called formulae) which you will need to install are

cmake libomp boost gsl fftw qt6 (root)

The preferred installation of root would be from source (see below), hence it is set here in parenthesis. For example to install cmake this is done the following way:

$ brew install cmake

Installation of NeXus requirements (optional)¶

Only if musrfit should support reading data files in the NeXus format the further required packages can be installed through Homebrew (Note: hdf4 is not supported anymore):

$ brew install hdf5

Unfortunately, the NeXus libraries have to be compiled and installed directly from the source code. Given the respective version number 4.4 (which are subject to change with time) this can be achieved for example by:

$ # build NeXus
$ cd ..
$ git clone https://github.com/nexusformat/code.git nexus/code
$ cd nexus
$ # build NeXus out-of-source
$ mkdir build
$ cd build
$ cmake ../code -DENABLE_HDF5=1 -DENABLE_HDF4=0 -DENABLE_MXML=0
$ cmake --build ./ --clean-first -- -j8
$ sudo cmake --install ./

ROOT¶

The default ROOT version is based on ROOT 6.xx/yy!

ROOT installed via Homebrew¶

If you have installed ROOT via the Homebrew formula, you are done with the ROOT part here and can go straight the the musrfit setup below.

ROOT installed from source¶

The best way to get ROOT exactly the way needed for musrfit is to install it from source. Before describing it, please make sure that you have installed all required packages listed under Requested Software (e.g. fftw, gsl, etc).

For the following it is assumed that ROOT shall be installed under $HOME/Applications. If you want to install it somewhere else, just systematically replace the related terms of the following description. For the following list of commands the ‘$’ will be given, the command prompt. Do not enter it! Also some comments will be added starting with a ‘#’ which can be omitted. They are only there to explain what is going on.

$ cd $HOME/Applications
$ git clone http://github.com/root-project/root.git
$ cd root
$ git tag -l
$ # git tag -l will list all available tags. In the next command choose the tag v6-xx-yy
$ # where xx is the highest listed number, e.g. v6-32-08.
$ # use only even numbers of xx
$ git checkout -b v6-32 v6-32-08
$ # now ROOT is ready to be configured. Below you will find the minimal ROOT configuration needed.
$ # We will use the cmake out-of-source approach here.
$ mkdir root_build
$ cd root_build
$ cmake ../ -Dgminimal=1 -Dasimage=1 -Dmathmore=1 -Dxml=1 -Dopengl=1 -Dbuiltin_glew=1 -Ddataframe=1 -DCMAKE_INSTALL_PREFIX=$HOME/Applications/root/root_exec
$ # next will be the make. If running on a multicore CPU you can speed up tremendously by calling
$ # make with the option -j <number>, where <number> is the number of threads which you want to give,
$ # e.g. make -j8
$ cmake --build ./ --clean-first -- -j8
$ # make will take quite a while
$ cmake --install ./

For further details see Installing ROOT from Source.

Setting up Environment Variables for ROOT and musrfit¶

Since Apple in its wisdom decided that programs started from a shell are treated differently than Apps if it is coming to system variables, we need to work harder compared to a Linux system.

For Mac OS X < 10.8:

In order to finalize the ROOT installation and to prepare already the installation of musrfit and musredit this is a good time for setting necessary environment variables for the use in Mac OS X. Here it assumed that you installed ROOT from source. If you downloaded the binary package, you will need to adopt the paths accordingly. Put the following lines (without the comments in parentheses and with the paths adjusted to your local installation) into the file ~/.MacOSX/environment.plist and re-login:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
      <key>MUSRFITPATH</key>
      <string>$HOME/Applications/root/root_exec/bin</string> (where to find the musrfit executables)
      <key>QTDIR</key>
      <string>/opt/local/lib/qt3mac</string>                 (where to find Qt3 (for musrgui) or Qt4 (for musredit))
      <key>ROOTSYS</key>
      <string>$HOME/Applications/root/root_exec</string>     (where to find the ROOT system)
</dict>
</plist>

For Mac OS X ≥ 10.8:

One needs to add some system variables in ~/.zprofile:

If ROOT has been installed via Homebrew:

export ROOTSYS=/usr/local
export MUSRFITPATH=$ROOTSYS/bin
export PATH=$ROOTSYS/bin:$QTDIR/bin:$PATH
export DYLD_LIBRARY_PATH=$ROOTSYS/lib/root:/usr/local/lib:$DYLD_LIBRARY_PATH

launchctl setenv ROOTSYS $ROOTSYS
launchctl setenv MUSRFITPATH $MUSRFITPATH
launchctl setenv PATH $PATH
launchctl setenv DYLD_LIBRARY_PATH $DYLD_LIBRARY_PATH

If ROOT has been installed via source/compilation:

export ROOTSYS=$HOME/Applications/root/root_exec
export MUSRFITPATH=$ROOTSYS/bin
export PATH=$ROOTSYS/bin:$QTDIR/bin:$PATH
export LD_LIBRARY_PATH=$ROOTSYS/lib:/usr/local/lib:$LD_LIBRARY_PATH

launchctl setenv ROOTSYS $ROOTSYS
launchctl setenv MUSRFITPATH $MUSRFITPATH
launchctl setenv PATH $PATH
launchctl setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH

After this you will need to “execute” .zprofile before proceeding:

$ source $HOME/.zprofile

musrfit¶

First, the most recent source code should be downloaded. First, the most recent source code should be downloaded. The preferred way of doing so is to clone the musrfit repository via git. Assuming the code should be located in ~/Applications/musrfit this is achieved most easily calling from the termin

$ cd ~/Applications
$ git clone https://bitbucket.org/muonspin/musrfit.git
$ cd musrfit

or

$ cd ~/Applications
$ git clone git://gitlab.psi.ch/nemu/musrfit.git
$ cd musrfit

If a local repository clone is already present, one can update it using:

$ cd ~/Applications/musrfit
$ git pull

As an alternative (if git is not available), the source code can also be downloaded from the following web-page: musrfit at bitbucket.

musrfit build with cmake¶

Currently the following configuration switches for musrfit are available:

-DCMAKE_INSTALL_PREFIX=<prefix-path>: Specify the installation prefix, i.e. the place where musrfit shall be installed, e.g. $ROOTSYS if already defined (by default: /usr/local).
-Dnexus=<value>: enable/disable the support of NeXus data files (requires the HDF4, HDF5 and NeXus libraries to be installed). <value>=1 enables NeXus, <value>=0 disables NeXus. The default setting, i.e. the switch is not provided is NeXus support is disabled.
-DASlibs=<value>: enable/disable the ASlibs. <value>=1 enables the ASlibs, <value>=0 disables the ASlibs. The default setting, i.e. the switch is not provided is ASlibs support is disabled. For details see Documentation of user libs.
-DBMWlibs=<value>: enable/disable the BMWlibs. <value>=1 enables the BMWlibs, <value>=0 disables the BMWlibs. The default setting, i.e. the switch is not provided is BMWlibs support is disabled. For details see Documentation of user libs.
-DBNMRlibs=<value>: enable/disable the BNMRlibs. <value>=1 enables the BNMRlibs, <value>=0 disables the BNMRlibs. The default setting, i.e. the switch is not provided is BNMRlibs support is disabled.
-Dqt_based_tools=<value>: Will try to get musredit, musrWiz, musrStep, and mupp installed, if Qt is found. By default this is enabled. Again <value>=0 means disabled, <value>=1 enabled.
-Dqt_version=<value>: Allows to specify which Qt version shall be tried. <value> can take the values: AUTO, 3, 4, 5, 6. If the value is set to AUTO, this highest installed version is chosen, otherwise the specified version is used.
-Dtry_OpenMP=<value>: Will check if OpenMP support is possible, and if yes use it. The default is enabled

Normally it should not be necessary to make use of any of the options except for specifying the installation path with -DCMAKE_INSTALL_PREFIX. musrfit build with cmake takes the out-of-source approach.

In order to have OpenMP available, which allows parallel processing of the fitter, you will need to guide cmake to where it can find it. For a Homebrew installation, this would be

$ export OpenMP_ROOT=$(brew --prefix)/opt/libomp

and for a MacPorts installation, something like

$ export OpenMP_ROOT=/opt/local/lib/libomp

Therefore a typical configuration / make / install process including NeXus support would look like

$ cd $HOME/Apps/musrfit
$ mkdir build
$ cd build
$ cmake ../ -DCMAKE_INSTALL_PREFIX=$ROOTSYS -Dnexus=1
# below it is assumed that multiple cores are present, hence the -j8 option
$ cmake --build ./ --clean-first -- -j8
$ cmake --install ./
$ /sbin/ldconfig                                  # (as superuser)

Note

If you use MacPorts you will likely need to guide cmake where to find qt6. You will need to provide the path to the necessary cmake files. This is done from the command line via the switch CMAKE_PREFIX_PATH. The configuration, build, and install process might look like this:

$ cd $HOME/Apps/musrfit
$ mkdir build
$ cd build
$ cmake ../ -DCMAKE_INSTALL_PREFIX=$ROOTSYS -Dnexus=1 -DCMAKE_PREFIX_PATH="/opt/local/libexec/qt6/lib/cmake;/opt/local/include/libomp"
# below it is assumed that multiple cores are present, hence the -j8 option
$ cmake --build ./ --clean-first -- -j8
$ cmake --install ./
$ /sbin/ldconfig                                  # (as superuser)

musrfit last step of the installation¶

In order to finish the installation of musrfit two more things should be done:

Define the MUSRFITPATH environment variable containing the path to the musrfit executables and XML files. E.g. if the location of the example above is used append the following line to the ~/.bashrc and ~/.bash_profile (and then either restart the shell or call the same commands once more from the shell):

export MUSRFITPATH=$ROOTSYS/bin

Adjust the paths where musrfit will search for data files in the installed musrfit_startup.xml. For detailed information on this XML file refer to the manual.

musredit¶

In the latest version of musrfit the configure script tries to determine automatically the highest available Qt version. In case this is found, the editor musredit is built already together with musrfit.

musrgui (obsolete)¶

If Qt3 is set up the installation of the musrfit editor can be done as follows from within the shell:

$ cd ~/Applications/musrfit/src/musrgui
$ qmake musrgui.pro
$ make
$ make install

The last command copies musrgui.app to the standard program directory /Applications.

Under some circumstances it might happen, that if musrgui was called from Finder the necessary libraries for executing musrfit could not be found. In that case, the only workaround for the moment is to export the environment variable DYLD_LIBRARY_PATH in the shell and call musrgui from a terminal! In order to accomplish that, add the following lines to ~/.profile and call musrgui with the specified command:

export DYLD_LIBRARY_PATH=/opt/root-system/lib:/sw/lib:$DYLD_LIBRARY_PATH
alias mgui='/Applications/musrgui.app/Contents/MacOS/musrgui'

Check the installation¶

In order to perform a quick test for finding out if the installation has been completed successfully, a few msr files together with the corresponding data files can be found in the musrfit source tree at doc/examples/. If musrgui has been installed, just open one of the test-*.msr files in the editor and test the musrfit functionalities. Otherwise, if only the terminal should be used, as an initial test for instance the following could be done:

$ cd ~/Applications/musrfit/doc/examples
$ musrview test-histo-ROOT-NPP.msr

Setting up musrfit on Different Platforms¶

Supported Operating Systems and Software Requirements¶

OS Restrictions¶

GNU/Linux¶

Requirements¶

Everything but ROOT and NeXus¶

Installation of NeXus requirements (optional)¶

ROOT¶

musrfit¶

musrfit build with cmake¶

musrfit last step of the installation¶

musredit¶

musrgui (deprecated)¶

Check the installation¶

MS Windows¶

Mac OS X / macOS¶

Requirements (MacPorts)¶

Installation of NeXus requirements (optional)¶

ROOT¶

ROOT installed via package installer¶

ROOT installed from source¶

Setting up Environment Variables for ROOT and musrfit¶

Notes on macOS Catalina and newer¶

Requirements (Homebrew)¶

Installation of NeXus requirements (optional)¶

ROOT¶

ROOT installed via Homebrew¶

ROOT installed from source¶

Setting up Environment Variables for ROOT and musrfit¶

musrfit¶

musrfit build with cmake¶

musrfit last step of the installation¶

musredit¶

musrgui (obsolete)¶

Check the installation¶

Setting up `musrfit` on Different Platforms¶