Welcome to the Mrsimulator documentation


PyPI version PyPI - Python Version

Build Status

GitHub Workflow Status Documentation Status




Language grade: Python https://codecov.io/gh/deepanshs/mrsimulator/branch/master/graph/badge.svg Total alerts CodeFactor


GitHub contributors GitHub issues GitHub stars GitHub forks


mrsimulator is an open-source Python package for fast computation/analysis of nuclear magnetic resonance (NMR) spectra in fluid and solid phases.

See our example galleries

Why use mrsimulator?

  • It is open-source and free.

  • It is a fast and versatile multi-dimensional solid-state NMR spectra simulator, including MAS and VAS spectra of nuclei experiencing chemical shift (nuclear shielding) and quadrupolar coupling interactions.

  • It includes simulation of weakly coupled nuclei experiencing J and dipolar couplings.

  • It is fully documented with a stable and simple API and is easily incorporated into Python scripts and web apps.

  • It is compatible with modern Python packages, such as Scikit-learn, Keras, etc.

  • Packages using mrsimulator -

A brief example

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"})

(png, hires.png, pdf)


Figure 1 Simulation of static and MAS solid-state NMR spectra


Throughout the web version of this documentation, you can copy code blocks into your clipboard by hovering over the top right corner of each gray code block and clicking the copy-to-clipboard icon. This is useful for copying code examples into your Python scripts and Jupyter notebooks.


The mrsimulator package offers the following

  • Fast simulation of one and two-dimensional solid-state NMR spectra.

  • Simulation of coupled and uncoupled spin system
    • for spin \(I=\frac{1}{2}\), and quadrupole \(I \ge \frac{1}{2}\) nuclei

    • at arbitrary macroscopic magnetic flux density

    • at arbitrary rotor angles

    • at arbitrary spinning frequency

  • A library of pre-built NMR methods,
    • 1D Bloch decay spectrum

    • 1D Bloch decay central transition spectrum

    • 2D Multi-Quantum Variable Angle Spinning (MQ-VAS)

    • 2D Satellite-Transition Variable Angle Spinning (ST-VAS)

    • 2D isotropic/anisotropic sideband correlation spectrum (e.g. PASS and MAT)

    • 2D Magic-Angle Flipping (MAF)

    • 2D Dynamic-Angle Spinning (DAS)

    • Custom user-defined methods (Method)

  • Models for tensor parameter distribution in amorphous materials.
    • Czjzek

    • Extended Czjzek

    • Custom user-defined models


User Guide



API and references

Project details

Reporting Bugs

Submit bug reports or feature requests on the Github issue tracker.

Discussions are welcome on the Github discussion page.

How to cite

If you use mrsimulator in your publication, please consider citing the following.

  • Deepansh J. Srivastava, Matthew Giammar, Maxwell C. Venetos, Shyam Dwaraknath, Philip J. Grandinetti, & Alexis McCarthy. (2021). mrsimulator: v0.6.1. Zenodo. https://doi.org/10.5281/zenodo.5559730

  • Srivastava DJ, Vosegaard T, Massiot D, Grandinetti PJ (2020) Core Scientific Dataset Model: A lightweight and portable model and file format for multi-dimensional scientific dataset. PLOS ONE 15(1): e0225953. https://doi.org/10.1371/journal.pone.0225953

Additionally, if you use lmfit for least-squares fitting, consider citing the lmfit package.

  • Matt Newville; Renee Otten; Andrew Nelson; Antonino Ingargiola; Till Stensitzki; Dan Allan; Austin Fox; Faustin Carter; Michał; Dima Pustakhod; lneuhaus; Sebastian Weigand; Ray Osborn; Glenn; Christoph Deil; Mark; Allan L. R. Hansen; Gustavo Pasquevich; Leon Foks; Nicholas Zobrist; Oliver Frost; Alexandre Beelen; Stuermer; kwertyops; Anthony Polloreno; Shane Caldwell; Anthony Almarza; Arun Persaud; Ben Gamari; Benjamin F. Maier. (2021, February 7). lmfit/lmfit-py 1.0.2 (Version 1.0.2). Zenodo. https://doi.org/10.5281/zenodo.4516651