MRSimulator: Fast Frequency-Domain Solid-State NMR Simulation with a Narrow Scope

What MRSimulator Solves and Who It Is For

MRSimulator addresses a specific pain point: the computational cost of solid-state NMR spectral simulation. Traditional simulation packages that solve the full spin dynamics are accurate but slow, making iterative fitting of experimental spectra impractical. MRSimulator instead uses frequency-domain approximations valid for common solid-state NMR methods, yielding fast simulations. The intended user is a chemist or materials scientist who wants to model and fit spectra to understand site populations and interaction parameters in multiple spin systems, as found in disordered or heterogeneous materials. It is not a general magnetic resonance package. The README is explicit: it is not intended for exploring complicated spin dynamics. That narrow scope is the core of its value proposition.

The Mechanism: Frequency-Domain Approximations

The speed comes from three documented assumptions. First, MRSimulator assumes no degeneracies in energy eigenstates. Second, it assumes no rotational resonances during evolution periods. Third, it 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. These assumptions let the simulator work in the frequency domain rather than time-domain propagation, which is where the computational savings arise. The documentation states this approach is valid for most commonly used solid-state NMR methodologies. That is a trade-off: you gain speed, but you must know whether your experiment violates any of these assumptions. If it does, the result will be wrong, and the library gives you no warning.

Getting Started: Install and a Minimal Example

Installation is a single pip command: pip install mrsimulator. The README provides a compact example that shows the core object model. You create a Site object with an isotope and a shielding tensor, here for 1H with zeta 13.89 and eta 0.25. You wrap it in a SpinSystem. Then you define Method objects, such as BlochDecaySpectrum, with channels and optionally a rotor_frequency for MAS. You pass a list of spin systems and a list of methods to a Simulator object, call run(), and plot the result. The example produces a 1D static and a 1D MAS spectrum in a few lines. This pattern is consistent across the library: sites, spin systems, methods, simulator. The API is straightforward, which lowers the barrier for users who are not simulation experts.

Capabilities: Methods and Models Beyond the Basics

The library includes a library of NMR methods beyond the simple Bloch decay. It can simulate 1D Bloch decay central transition spectra, 2D Multi-Quantum Variable Angle Spinning (MQ-VAS), 2D Satellite-transition Variable Angle Spinning (which the README also labels MQ-VAS, a typo), 2D isotropic/anisotropic sideband correlation spectra such as PASS and MAT, 2D Magic Angle Flipping (MAF), and 2D Dynamic Angle Spinning (DAS). It also supports custom user-defined methods via a Method class. For amorphous materials, it offers models for tensor parameter distributions, specifically Czjzek and Extended Czjzek, plus custom models. This breadth is notable for a package that claims speed over generality. The 2D methods and distribution models make it suitable for realistic materials science problems, not just simple isolated spins.

Integration and Ecosystem: Python-First Design

MRSimulator is designed to fit into modern Python workflows. The README mentions compatibility with scikit-learn and Keras, which suggests it can be used in machine learning pipelines for spectral analysis or parameter estimation. It also has a companion package, mrinversion, which builds on MRSimulator for inversion problems. The object-oriented design, with Site, SpinSystem, Method, and Simulator classes, makes it easy to script and automate. For researchers who want to follow FAIR data practices, the package is open source with a BSD-3-Clause license, which permits reuse with minimal restrictions. The documentation is hosted on Read the Docs, and the repository has a continuous integration pipeline. This Python-first approach contrasts with older NMR simulation tools that may require proprietary environments or complex input files.

Limitations and When It Is the Wrong Tool

The most significant limitation is the scope of the approximations. If your spin system has degenerate energy eigenstates or you are simulating experiments with rotational resonances during evolution, MRSimulator will produce incorrect results. The README does not quantify the error or provide a validity checker. You must know your experiment well enough to judge. Also, the library is not designed for complicated spin dynamics, such as strong dipolar couplings in multi-spin systems or advanced pulse sequences that rely on coherence transfer beyond pure rotations. For those cases, you need a general-purpose package, which will be slower but accurate. Another practical limitation: the release history shows a long gap between v0.7.0 in 2022 and v1.0 in 2024. That gap suggests the API may have changed, and you should check the v1.0 release notes for breaking changes before upgrading.

Alternatives and How They Differ

The README does not name competitors, but it implies their existence: 'Other software packages can handle these more demanding simulations, albeit at a more significant cost in computational time.' In the solid-state NMR simulation field, SIMPSON and GAMMA are well-known general-purpose packages. SIMPSON, for example, performs time-domain simulations of spin dynamics under arbitrary pulse sequences, including strong couplings and complex coherence transfer pathways. It does not make the same frequency-domain approximations, so it is slower but applicable to a wider range of experiments. GAMMA is a C++ library for spin dynamics simulations, also general-purpose. The key difference is approach: MRSimulator sacrifices generality for speed by restricting the physics, while SIMPSON and GAMMA solve the full spin Hamiltonian. If you need to simulate a standard MAS or static experiment with quadrupolar nuclei, MRSimulator is likely faster. If you need to explore exotic pulse sequences, you must use a general-purpose tool.

Maintenance, License, and Upgrade Cost

The repository is not archived, and the last push was on 2024-12-02, the same day as the v1.0 release. That indicates active maintenance, at least as of that date. The license is BSD-3-Clause, which is permissive and allows commercial use with attribution, but this is not legal advice. The upgrade cost from v0.7.0 to v1.0 is unknown from the README alone; the project does not provide a changelog in the supplied material. You should review the release notes on GitHub before upgrading. The documentation is extensive, with a stable URL, which helps mitigate upgrade friction. The dependency on modern Python packages like scikit-learn and Keras is optional, but the core library likely has minimal dependencies. Overall, the maintenance appears healthy, but the release gap and lack of a visible changelog in the README mean you should verify compatibility with your existing scripts before adopting v1.0.

Editorial conclusion

Adopt MRSimulator if you work in solid-state NMR and need to fit experimental spectra to extract site populations and interaction parameters for disordered or heterogeneous materials, especially with quadrupolar nuclei or MAS. Skip it if you must simulate complex spin dynamics, strong couplings, or rotational resonances, where general-purpose packages like SIMPSON or GAMMA are required despite higher computational cost. Before adopting, verify that your pulse sequences and interaction regimes fit within the documented approximations: no degenerate eigenstates, no rotational resonances during evolution, and coherence transfer limited to pure rotations or total mixing. Check the v1.0 release notes for any breaking API changes from v0.7.0, and test your specific nucleus and method against a known experimental or reference spectrum.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes