Installing MuSpinSim

In this tutorial we'll go through the best ways to install MuSpinSim on any system of your interest. The first step is, of course, procuring Python itself. If you have not already done this, see the tutorial here.

Installing with pip or conda

Using either pip or conda will take care of installing all of the dependencies (other packages that muspinsim needs to run). Assuming you already have Python and pip installed on your system, then installing muspinsim from the command line is easy using

pip install muspinsim --user
or if you are using Anaconda, you may also use

conda install muspinsim

and you'll be ready to go.

You do not need to worry about the details on the reset of this page unless the above failed, or you wish to install from the source.

Installing from source

To install from source you first need to ensure you have a suitable C++ compiler on your system. If you are on Linux or macOS, this is likely already the case, but for Windows you will likely need to install one such as MSCV.

After this you should obtain the source from GitHub in one of two ways. If you have git installed and are familiar with its use you can simply clone the repository:

git clone https://github.com/muon-spectroscopy-computational-project/muspinsim.git

Otherwise, you can download it as a zip file and unzip it in a folder of your choice.

To install the downloaded source, navigate to the parent directory in your terminal. If you don't know how to do it, here's a handy guide for Linux and MacOS and here's one for Windows, which has a different syntax.

Once you are in the directory above the unzipped/cloned package, you can run:

pip install ./{package} --user

where {package} represents the name of the directory where you unzipped/cloned the package. In your case, if you didn't rename the unzipped directory, it should be:

pip install ./muspinsim --user
Compiling with OpenMP

If installing using pip or conda, then parallelisation with OpenMP will be enabled. If compiling from source, to allow parallelisation you can assign the environment variable MUSPINSIM_WITH_OPENMP prior to installation. To do this on Linux and macOS you may use

export MUSPINSIM_WITH_OPENMP=1

and for Windows

set MUSPINSIM_WITH_OPENMP=1

Important

While the default compiler on Linux and most Windows compilers support OpenMP, the default compiler on macOS does not. As a result you should install a compatible compiler first. We recommend using clang from homebrew's llvm package which can be installed via

brew install llvm

Then you need to add the following environment variables to point to the the new compilers instead of the default. The paths may differ for your system but are usually

export CC="/usr/local/opt/llvm/bin/clang"
export CXX="/usr/local/opt/llvm/bin/clang++"

With these set, you can now install the downloaded source with

pip install ./muspinsim --user

For developers: You may also use python setup.py --with-openmp build_ext --inplace to compile the source with OpenMP while developing.