Skip to main content

A python toolbox for simulating fast real-time solid-state NMR spectra.

Project description

The MRSimulator project

Deployment PyPI version PyPI - Python Version
Build Status CI Read the Docs
License License
Metrics codecov CodeFactor

MRSimulator is an open-source Python package designed for fast and comprehensive analysis of NMR (Nuclear Magnetic Resonance) spectra in fluid and solid phases. It introduces a new approach to spectral simulation in the frequency domain based on approximations valid for most commonly used solid-state NMR methodologies, significantly improving numerical efficiency.

Key Features

  • Open-Source and Free: MRSimulator is fully documented, freely available, and open-source.
  • Versatile Simulations: Capable of simulating one- and two-dimensional static, MAS (Magic Angle Spinning), and VAS (Variable Angle Spinning) spectra from a variety of NMR multiple-pulse sequences for nuclei experiencing chemical shift (nuclear shielding) and quadrupolar coupling interactions, as well as weak J and dipolar couplings. Furthermore, it includes the ability to create customized methods for modeling spectra from more sophisticated one and two-dimensional NMR methodologies.
  • Efficiency: Achieves high benchmarks by assuming no degeneracies in energy eigenstates and no rotational resonances during evolution periods. It further restricts coherence transfer among transitions to pure rotations about an axis in the rotating frame or through an artificial total mixing operation between selected transitions of adjacent free evolution periods.
  • Ease of Use: Simple-to-use, versatile, and extendable package with a stable and straightforward API.
  • Integration: Easily incorporated into Python scripts and web apps and compatible with modern Python packages such as scikit-learn and Keras.
  • FAIR Principles: Helps researchers follow FAIR (Findability, Accessibility, Interoperability, and Reusability) data practices.

MRSimulator is not intended as a general magnetic resonance simulation package for exploring complicated spin dynamics. Other software packages can handle these more demanding simulations, albeit at a more significant cost in computational time. Instead, MRSimulator focuses on the more tractable applications of solid-state NMR spectroscopy in the chemical and materials sciences. It is the ideal tool for users who want to model and fit experimental spectra to understand site populations and interaction parameters of multiple spin systems, as commonly found in disordered or heterogeneous materials.

Packages Using MRSimulator

Install

pip install mrsimulator

Please refer to our installation documentation for details.

A 1D static and MAS 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])
sim.run()

# 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[0].set_title("Static")
ax[1].plot(sim.methods[1].simulation.real, color="black", linewidth=1)
ax[1].set_title("MAS")
plt.tight_layout()
plt.show()

This should produce the following figure.


Check out our extensive documentation and more example.

Simulation Fitting


Features

The MRSimulator package currently offers the following

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

  • Simulation of coupled and uncoupled spin system

    • for spin I=1/2, and quadrupole I>1/2 nuclei
    • at arbitrary macroscopic magnetic flux density
    • at arbitrary rotor angles
    • at arbitrary spinning frequency
  • A library of 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 (MQ-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

For more information, refer to the documentation.

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 work implemented in MRSimulator.

  • Please use the GitHub citation tool to cite this repository. The tool in located in the About section under the Cite this repository category.

  • Srivastava D.J. and Grandinetti P.J. (2024) Simulating multipulse NMR spectra of polycrystalline solids in the frequency domain. J. Chem. Phys. 160, 234110, https://doi.org/10.1063/5.0209887

  • Srivastava D.J., Baltisberger J.H and Grandinetti P.J. (2024) Rapid simulation of two-dimensional spectra with correlated anisotropic dimension. J. Chem. Phys. 160, 134104, https://doi.org/10.1063/5.0200042

  • Srivastava D.J., Vosegaard T, Massiot D, Grandinetti P.J. (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. Zenodo. https://doi.org/10.5281/zenodo.4516651

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mrsimulator-1.0.0.tar.gz (518.8 kB view details)

Uploaded Source

Built Distributions

mrsimulator-1.0.0-cp313-cp313-win_amd64.whl (8.5 MB view details)

Uploaded CPython 3.13Windows x86-64

mrsimulator-1.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.8 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

mrsimulator-1.0.0-cp313-cp313-macosx_14_0_arm64.whl (10.0 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

mrsimulator-1.0.0-cp313-cp313-macosx_12_0_x86_64.whl (13.9 MB view details)

Uploaded CPython 3.13macOS 12.0+ x86-64

mrsimulator-1.0.0-cp312-cp312-win_amd64.whl (8.5 MB view details)

Uploaded CPython 3.12Windows x86-64

mrsimulator-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.8 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

mrsimulator-1.0.0-cp312-cp312-macosx_14_0_arm64.whl (10.0 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

mrsimulator-1.0.0-cp312-cp312-macosx_12_0_x86_64.whl (13.9 MB view details)

Uploaded CPython 3.12macOS 12.0+ x86-64

mrsimulator-1.0.0-cp311-cp311-win_amd64.whl (8.5 MB view details)

Uploaded CPython 3.11Windows x86-64

mrsimulator-1.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

mrsimulator-1.0.0-cp311-cp311-macosx_14_0_arm64.whl (10.0 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

mrsimulator-1.0.0-cp311-cp311-macosx_12_0_x86_64.whl (13.9 MB view details)

Uploaded CPython 3.11macOS 12.0+ x86-64

mrsimulator-1.0.0-cp310-cp310-win_amd64.whl (8.5 MB view details)

Uploaded CPython 3.10Windows x86-64

mrsimulator-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

mrsimulator-1.0.0-cp310-cp310-macosx_14_0_arm64.whl (10.0 MB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

mrsimulator-1.0.0-cp310-cp310-macosx_12_0_x86_64.whl (13.9 MB view details)

Uploaded CPython 3.10macOS 12.0+ x86-64

File details

Details for the file mrsimulator-1.0.0.tar.gz.

File metadata

  • Download URL: mrsimulator-1.0.0.tar.gz
  • Upload date:
  • Size: 518.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for mrsimulator-1.0.0.tar.gz
Algorithm Hash digest
SHA256 21e170522da0ba3760deb59f4d5bc1b183268f038aa5324118eded5576271d02
MD5 61852aacd5f8bbcbd38e36f50d7c9276
BLAKE2b-256 0053b01a9ae62dc538d0ba156bc657174da886927692f6b9960186b5af9f98ce

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 76cb68d3a37f0295a98035876d7bf7df611e0a0266d708bc9b90e6881c0cc265
MD5 919cf686ea3da3746659900a583c389e
BLAKE2b-256 f37b38f61d5dfb28e2338e79c8f2581e17238183025394f0b222118410f5dc0e

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2c9bc6b47acc46e4f90aaa80c79259931b89623cae982ae318664a8066727ec9
MD5 3b33503520bc5ec2f7c5cb741138877b
BLAKE2b-256 eb06450911c089c7974134e10f01965442fe795ef4418cfeb5c46e4811dbc49d

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 3884cc724503a701a7eda84400c6e1b92ed6fe9145ffd49dfcf1449dc53148b6
MD5 5b188680c3172ad6604e230975d7d5ac
BLAKE2b-256 818f7a22c53788ac63cc27cd67add3d4b4e6d014d36b911ef27b92a077d7aad7

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp313-cp313-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp313-cp313-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 bcc8903675fb602468bdec33a2716aeb7352b4913e66e08ae759f6d8ba57b27e
MD5 b3ea3439312f3807448bc74fbca9949f
BLAKE2b-256 22a61850593c1fbde1a314bf1bb52a51c04a7a8794203110f11dc3dc6986c5ab

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 02c39498071202d5387f73488af5cbac48d8810dd2fc84835d1fa36070297eba
MD5 c0746b4a7371b88d9113f236f56a6bcb
BLAKE2b-256 a93055533e2206e7ce6cfdf923369d06587615289b51d545624c7d6c91dfd7a7

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8e46903682c505d1beaf30b6ac3890029f5c04b20b177e2144e2d1645142cd69
MD5 9c258dd99db3b2bb7f92f36047681cb4
BLAKE2b-256 abb3b42713b807ece4f780c98e1864af56c456c12a2977082e3fbe7e088809b3

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 ec721ccdb8495b077089e65c9e1bad24afae2d460f12fa1b919240aadb13c529
MD5 322130c2d4a921230e869e7a8789e2d4
BLAKE2b-256 d506bb98f9f4f35bf1374a4a4cef6fb921f5fb72df13b84c635d5c7623bad1ba

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp312-cp312-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp312-cp312-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 bb89d0ff654976a22bdf1b5734ffb622e34c45152b776bb566e9c0ea54ee0054
MD5 1655cbdfc48634496d84fd63eb7a2d70
BLAKE2b-256 5a8eed05c40d1840838a4cf3041a322d6194e7737f6171e3d45136e8e421ece0

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 2ac7b9cfcc1b024e99c68ecf167fc885df3798d040482aacc832797b8ce0e8d2
MD5 3ccc58d199f04deb0801311168a1b517
BLAKE2b-256 0cc457a4431dfbc2b300a26c9b83e9f97f82b3a2ab15131a297fb094ce46a38c

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8a95bf60b9932447355c6a5d926e8a43d0bd94d3fd1f995f49cb536307d13523
MD5 c248cbb38c843a23cff62828a6f1096b
BLAKE2b-256 97c14ea19d67ae4f59e51e64cdb6e9224d450e04514cb007fa38b80c7069f0cb

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 7e66cb53d90d3f3ee71b96507699d90e275a791b0ae6a967bd540a66360e5b4c
MD5 94107f11c8240f525ad643e96c077c34
BLAKE2b-256 f2e09afdd94551c988be5abb61b6377f9216a57c0c7828d76f1b148cd1a0ca57

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp311-cp311-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp311-cp311-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 275c2134d1564f78517c67cbde1a3e566ecf5f39692b299c0e64f9d97d163080
MD5 14e3f83658a54f28779316e5562ea101
BLAKE2b-256 7fe7e6d4e6e0db2120ab0fe46693a31320786f59973ce9ae3daa6e3f3c75e1b8

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 1012609fce6854bc06d570123c3867f5def869dd11f9052e235315e64cf02c1c
MD5 0e625da8d1ec0fdbaeeb164e632c12f7
BLAKE2b-256 9430347e7cfd2085e1b6d517304acb392825d22d0efdea9c4ff2211328c17755

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 020683433ac7f00ed1abcb6d1ed67149e7d1abf2899021e166711a8bca4c056e
MD5 cf0034cc3dba4a7f069d7d400a9db6ba
BLAKE2b-256 9ab0d629d6ed09155ee94c17fe973483a79ef318ba7580b603248ea08cb60464

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 4c7038cda6567a55c284c910c1f6257c5a25dc3699d679c16cdaf33b07d74661
MD5 e3926dd1211d413da96076d5671958bd
BLAKE2b-256 8df54887c77a76409ef32cdab37cbb08c3a58f8e8ced0a363e4d554f51520104

See more details on using hashes here.

File details

Details for the file mrsimulator-1.0.0-cp310-cp310-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for mrsimulator-1.0.0-cp310-cp310-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 fc30888b80c4765fc90a62a67c6926d0ac75a0174c4543e63b40b3c534c49748
MD5 a5be55ccae47a1c33b4a43a91c73e108
BLAKE2b-256 efe060a8b58c676c3ca4ff075e4ba2c68c4c93187040922c213b2c7b4fe9774e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page