For the users


If you encounter an issue during installation, see our troubleshooting section.

If that doesn’t resolve your issue, please create a bug report on our Github issue tracker.

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,

$ 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, Python is not usually installed by default. See for a list of official Python downloads and Windows installation instructions.

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

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. Install the package using pip as follows,

$ pip install mrsimulator

For Mac users, if the above statement didn’t work, you are probably using mac OS system python, in which case, use the following,

$ python3 -m pip install mrsimulator --user

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 Getting Started to continue the tutorial.

Test your build


For windows users using anaconda python 3.8 and higher, you need to set the following environment variable in the Anaconda Prompt before running mrsimulator scripts.


If the installation is successful, you should be able to run the following test file in your terminal. Download the test file here or copy and paste the following code into a python file and run the code.

from mrsimulator import Simulator, SpinSystem, Site
from mrsimulator.method.lib import BlochDecaySpectrum
import matplotlib.pyplot as plt

# Make Site and SpinSystem objects
H_site = Site(isotope="1H", shielding_symmetric={"zeta": 13.89, "eta": 0.25})
spin_system = SpinSystem(sites=[H_site])

# Make static and MAS one-pulse acquire Method objects
static = BlochDecaySpectrum(channels=["1H"])
mas = BlochDecaySpectrum(channels=["1H"], rotor_frequency=1000)  # in Hz

# Setup and run the Simulation object
sim = Simulator(spin_systems=[spin_system], methods=[static, mas])

# Plot the spectra
fig, ax = plt.subplots(1, 2, figsize=(6, 3), subplot_kw={"projection": "csdm"})
ax[0].plot(sim.methods[0].simulation.real, color="black", linewidth=1)
ax[1].plot(sim.methods[1].simulation.real, color="black", linewidth=1)

(png, hires.png, pdf)


Figure 3 An example simulating solid-state NMR spectrums of static and MAS experiments


If you encounter the following error

ValueError: numpy.ndarray size changed, may indicate binary incompatibility.
Expected 88 from C header, got 80 from PyObject

update numpy by running

$ pip install -U numpy