For the users

Strict Requirements

mrsimulator has the following strict requirements:

See Package dependencies for a full list of requirements.

Make sure you have the required version of python by typing the following in the terminal,


You may also click the copy-button located at the top-right corner of the code cell area in the HTML docs, to copy the code lines without the prompts and then paste it as usual. Thanks to Sphinx-copybutton

$ python --version

For Mac users, python version 3 is installed under the name python3. You may replace python for python3 in the above command and all subsequent python statements.

For Windows users, we recommend the Anaconda or miniconda distribution of python>3.6. Anaconda distribution for python comes with popular python packages that are frequently used in scientific computing. Miniconda is a minimal installer for conda. It is a smaller version of Anaconda that includes conda, Python, and the packages they depend on, along with other useful packages such as pip.

See also

If you do not have python or have an older version of python, you may visit the Python downloads or Anaconda websites and follow their instructions on how to install python.

Installing mrsimulator using pip

On Google Colab Notebook

Colaboratory is a Google research project. It is a Jupyter notebook environment that runs entirely in the cloud. Launch a new notebook on Colab. To install the mrsimulator package, type

!pip install mrsimulator

in the first cell, and execute. All done! You may now start using the library, or proceed to section Introduction to Spin Systems to continue the tutorial.

On Local machine (Using pip)

PIP is a package manager for Python packages and is included with python version 3.4 and higher. PIP is the easiest way to install python packages.

For Linux users, we provide the binary distributions of the mrsimulator package for python versions 3.6-3.9. Install the package using pip as follows,

$ pip install mrsimulator

If you get a PermissionError, it usually means that you do not have the required administrative access to install new packages to your Python installation. In this case, you may consider adding the --user option at the end of the statement to install the package into your home directory. You can read more about how to do this in the pip documentation.

Upgrading to a newer version

If you are upgrading to a newer version of mrsimulator, you have all the prerequisites installed on your system. In this case, type the following in the terminal/Prompt

$ pip install mrsimulator -U

All done! You may now start using the library, or proceed to section Introduction to Spin Systems to continue the tutorial.

Building mrsimulator from the source


You will need a C-compiler suite and the development headers for the BLAS and FFTW libraries, along with development headers from Python and Numpy, to build the mrsimulator library from source. The mrsimulator package utilizes the BLAS and FFTW routines for numerical computation. To leverage the best performance, we recommend installing the BLAS and FFTW libraries, which are optimized and tuned for your system. In the following, we list recommendations on how to install the c-compiler (if applicable), BLAS, FFTW, and building the mrsimulator libraries.

Obtaining the Source Packages

Stable packages

The latest stable source package for mrsimulator is available on PyPI and Github release. Download and extract the .tar.gz file.

OS-dependent prerequisites


Installing OS-dependent prerequisites is a one-time process. If you are upgrading to a newer version of mrsimulator, skip to Building and Installing section.

OpenBLAS and FFTW libraries

On Linux, the package manager for your distribution is usually the easiest route to ensure you have the prerequisites to building the mrsimulator library. To build from source, you will need the OpenBLAS and FFTW development headers for your Linux distribution. Type the following command in the terminal, based on your Linux distribution.

For (Debian/Ubuntu):

$ sudo apt-get install libopenblas-dev libfftw3-dev

For (Fedora/RHEL):

$ sudo yum install openblas-devel fftw-devel

Install a C/C++ compiler

The C-compiler comes with your Linux distribution. No further action is required.

Building and Installing

Use the terminal/Prompt to navigate into the directory containing the package (usually, the folder is named mrsimulator),

$ cd mrsimulator

From within the source code folder, type the following in the terminal to install the library.

$ pip install .

If you get an error that you don’t have the permission to install the package into the default site-packages directory, you may try installing with the --user options as,

$ pip install . --user

Test your build

If the installation is successful, you should be able to run the following test file in your terminal. Download the test file here.

$ python

The above statement should produce the following figure.

(png, hires.png, pdf)


Figure 1 A test example simulation of solid-state NMR spectrum.