Introduction

The HQS NMR Tool is the first package in the HQStage module HQS Spectrum Tools. With the HQS NMR Tool you can calculate and analyze NMR spectra for molecules or other spin systems. Given the NMR parameters of a molecule, HQS Spectrum Tools provides a set of solvers via a python API to calculate the NMR spectrum. RUST and C++ components are used internally to achieve remarkable speed and accuracy, even for complex, large molecules.

Fastest NMR Spectrum Solver

“One of the fastest Hilbert-space NMR simulation tools I have ever seen, with a remarkably efficient frequency-domain implementation.” - Ilya Kuprov, Professor of Physics, University of Southampton

The HQS NMR Tool is also an integral part of HQSpectrum, our end-to-end solution for NMR Spectra analysis. If you are interested in using this cloud service please request access by sending an email to hqspectrum@quantumsimulations.de.

NMR spectra prediction is also a very promising use case for the quantum computer. To explore this possibility, we invite you to take a look at the HQS Qorrelator App.

If you are interested in the theory behind NMR or the math of how to calculate NMR spectra, take a look at the background chapter.

Applications

Nuclear magnetic resonance (NMR) spectroscopy is a key analytical tool in chemistry and related disciplines. Its broad application not only facilitates the identification of molecules, but also provides intricate details about their structure, dynamics, and chemical environment. The ability to compare an experimental NMR spectrum with theoretical predictions for various compounds is crucial for the accurate identification and characterization of chemical entities. T

Our NMR spectrum solvers are designed for both speed and precision. They are based on a very efficient implementation in the frequency domain. With a variety of solver strategies at your disposal, you can leverage symmetries and clustering techniques either fully automated or customized according to your specifications. This flexibility allows you to tailor your approach based on the specific characteristics of your system, optimizing performance without sacrificing accuracy.

Getting started

To use HQS NMR Tool you need a running version of HQStage. You can check here how to set it up. Once you have HQStage correctly configured you can install the HQS NMR Tool using the command:

hqstage install hqs-nmr

For some of the functionalities of the HQS NMR Tool (especially the provided example NMR parameters), the RDKit cheminformatics package is required. It is strongly recommended to install it via the conda-forge channel to ensure the access to its latest version. Additionally it is highly recommended to install the Intel oneAPI Math-Kernel-Library (MKL) as otherwise performance will be critically impaired. However, these packages have to be installed manually. The easiest way to install these libraries is running the following command in an active conda environment:

conda install rdkit mkl

Alternative ways to install the required libraries

If you do not have conda available you can also install RDKit via pip. This is not recommended as currently only an older version of RDKit is supported via pip and could cause issues in the future. Also it requires a numpy version smaller numpy 2.0:

pip install "numpy<2.0"
pip install rdkit

To install the MKL you basically have three options:

You can use HQStage to install the MKL into the currently active virtual environment.
```
hqstage install mkl
```
You can manually provide a version of the MKL by making sure that the file libmkl_rt.so is found by the dynamic linker. That means, that a system-wide installation should be found automatically.

You can install the MKL via pip. However, you need to create a symlink for the file libmkl_rt.so. The commands below perform the necessary steps.

pip install mkl
PLATLIB_DIR="$(python -c "import sysconfig; print(sysconfig.get_path('platlib'))")"
ln -fs libmkl_rt.so.2 "${PLATLIB_DIR}/../../libmkl_rt.so"

The following code snippet can be used to create your first program in HQS NMR Tool.For an expanded collection of examples please see the examples section.

from hqs_nmr.calculate import calculate_spectrum
from hqs_nmr.datatypes import NMRCalculationParameters
from hqs_nmr_parameters.examples import molecules

import numpy as np
import matplotlib.pyplot as plt

# Obtain example molecule of datatype NMRParameters.
molecule_parameters = molecules["C3H8"].spin_system()

# Define the calculation parameters. The only required field is the magnetic
# field in Tesla
calculation_parameters = NMRCalculationParameters(field_T=11.7433)

# Calculate the individual spin contributions of the spectrum.
nmr_result = calculate_spectrum(
    molecule_parameters,
    calculation_parameters
)

# Sum up the individual spin contributions.
spectrum = np.sum(nmr_result.spectrum.spin_contributions, axis=0)

# Plot the spectrum.
plt.plot(nmr_result.spectrum.omegas_ppm, spectrum, linewidth=0.3)
plt.title("500 MHz, Propane")
plt.xlabel("$\\delta$ [ppm]")
plt.ylabel("$Intensity \\, [a. u.]$")
plt.savefig("propane_500MHz_NMR_spectrum.png", dpi=2000)
plt.show()

Executing the code snippet using python should result in the following plot:

Please note that HQS Spectrum Tools is currently only supported on Linux.

Features

Frequency domain-based fast and precise NMR spectra calculation.
Automatic implementation to compute accurate 1D NMR spectra with minimal truncation errors for large numbers of spins, featuring linear scaling with system size.
NMR example parameters (chemical shifts and J-couplings) for molecules of different sizes, accessible via data classes containing structural information.
Custom NMR parameters can be specified conveniently for NMR spectrum simulation.
Easy construction of an NMR Spin Hamiltonian from provided or custom parameters using the struqture-py package.
Extensive customization options of the NMR solver for expert users.
Postprocessing methods to analyze simulated spectra and compare them to experiment.