ssNMRlib: a comprehensive library and tool box for acquisition of solid-state nuclear magnetic resonance experiments on Bruker spectrometers

We introduce ssNMRlib, a comprehensive suite of pulse sequences and jython scripts for user-friendly solid-state nuclear magnetic resonance (NMR) data acquisition, parameter optimization and storage on Bruker spectrometers. ssNMRlib allows the straightforward setup of even highly complex multi-dimensional solid-state NMR experiments with a few clicks from an intuitive graphical interface directly from the Bruker Topspin acquisition software. ssNMRlib allows the setup of experiments in a magnetic-field-independent manner and thus facilitates the workflow in a multi-spectrometer setting with a centralized library. Safety checks furthermore assist the user in experiment setup. Currently hosting more than 140 1D to 4D experiments, primarily for biomolecular solid-state NMR, the library can be easily customized and new experiments are readily added as new templates. ssNMRlib is part of the previously introduced NMRlib library, which comprises many solution-NMR pulse sequences and macros.

1 Introduction

Nuclear magnetic resonance (NMR) is arguably the most versatile spectroscopic technique, with applications ranging from studies of molecules in the solid, liquid or gas phases to complex materials and even entire organisms. The versatility of NMR spectroscopy is rooted in the countless opportunities to manipulate nuclear spins. Nowadays, the NMR spectroscopist can choose from a large number of highly specialized pulse sequences to obtain answers to specific questions related to molecular structure or dynamics. Most NMR experiments contain a number of building blocks used for transfer of coherence, for observation of chemical shifts in directly observed or incremented indirect dimensions and blocks monitoring spin evolution due to relaxation, or spin evolution under the action of (dipolar or chemical-shift anisotropy – CSA) recoupling sequences. The quality of NMR data critically depends on the precise setting of many parameters related to each of these building blocks. As a consequence, setting up an NMR experiment that yields the best possible data is often a complex time-consuming procedure even for specialists. Accordingly, valuable experiment time is often spent on optimizing parameters. Furthermore, keeping track of already optimized parameters in one experiment for use in another experiment that uses the same building blocks is an error-prone process. In facilities with multiple spectrometers, it is often a concern how the pulse sequences are centralized, how one can obtain a set of parameters that safely works for a given pulse sequence on a given spectrometer, or how to transfer an acquisition parameter set from one spectrometer to another.

Here, we introduce a library of pulse sequences, scripts and intuitive graphical-interface-based setup routines for solid-state NMR experiments on Bruker spectrometers, ssNMRlib. This library is built upon NMRlib, recently developed for biomolecular solution-state NMR (Favier and Brutscher, 2019), and has numerous solid-state NMR-specific features that greatly facilitate the key tasks of the experimentalist, from parameter optimization and storage of optimized parameters to rapid and easy setup of complex pulse sequences, centralization of pulse sequences and user-friendly storage of acquisition parameters for later use in publications or laboratory notebooks. ssNMRlib is open to many kinds of applications. We have included so far more than 140 pulse sequences for biomolecular MAS experiments, including heteronuclear multi-dimensional (1D–4D) correlation spectroscopy for resonance assignment, structure determination and dynamics studies, using ¹H, ¹³C and ¹⁵N detection; ³¹P and ¹⁹F detection is currently being added. The ssNMRlib concept is fully open to accommodating many kinds of pulse sequences and thus not limited to biological ssNMR. The possibility of the user including new experiments in the library – which then can also benefit from the automatic setup routines – is a central idea to ssNMRlib. The integration into NMRlib offers many additional scripts and macros e.g. for data processing or python-based fitting and printing. In this article we describe the key philosophy and concepts of the library and the workflow and exemplify its use with several applications.

Overview of the aims of ssNMRlib

The central design ideas behind ssNMRlib are summarized in Fig. 1a. We sought to create a tool that accesses a central library of scripts and pulse sequences, which allows setting up of experiments independently of the magnetic field strength and which takes into account the installed probe head. Parameters specific to a given machine and probe head (such as Larmor frequencies and radio-frequency (RF) power levels) are loaded by a centralized script that reads spectrometer- and probe-specific values.

Figure 1 Overview of the functionalities of ssNMRlib. (a) Main ideas considered in the design of ssNMRlib. (b) Part of the current menu structure of ssNMRlib, here focussing mainly on ¹H-detected experiments. Highlighted are routines for calibration (orange/red) and 4D backbone assignment experiments (blue, right). Helper scripts are shown in purple (bottom).

Furthermore, as many pulse sequences use common building blocks, e.g. for coherence-transfer steps, an important aim of ssNMRlib is to allow the user to optimize the relevant parameters once, ideally in an automated manner. The optimized parameters are saved without the need for additional user interference (but with the possibility of editing all parameters). These optimized parameters are then automatically read into more complex experiments, where these building blocks are needed. To facilitate the setup further, ssNMRlib proposes reasonable starting values, e.g. for cross-polarization transfers, taking into account the (automatically retrieved) MAS frequency. The transfer of parameters between different experiments (e.g. the retrieval of cross-polarization (CP) parameters to be used in complex 2D/3D/4D experiments) is facilitated by a common nomenclature of parameters, as outlined in Table S1 in the Supplement.

Pulse sequences in ssNMRlib are written such that the power levels relevant for pulse sequence elements are entered as constants (cnst) in units of Hertz or kilohertz, rather than in Watt or dB. Field strength in kilohertz is the relevant quantity for essentially all transfer steps, e.g. for Hartmann–Hahn cross-polarization conditions (Hartmann and Hahn, 1962), for many common recoupling schemes such as HORROR (Nielsen et al., 1994), DREAM (Verel et al., 1998), PAIN (Lewandowski et al., 2007), DARR (Takegoshi et al., 2001) or MIRROR (Scholz et al., 2008), as well as for decoupling. Handling power levels in kHz units rather than Watt/dB is, therefore, more convenient and intuitive. The conversion to Watt units is done internally within the pulse sequences, using the hard-pulse calibration. We find that, on temporary hardware with linearized amplifiers, one can calculate accurate power levels in Watt from a single 90^∘ pulse calibration.

In all cases where selective pulses are used, e.g. in CO-CA INEPT transfers or homonuclear ¹³C decoupling in indirect dimensions, the pulse power levels are calculated directly within the pulse sequences using the desired excitation bandwidth (in ppm); i.e. at each B₀ field strength the correct power level is calculated. The user does not need to take care of the power-level calibration of any shaped pulse.

An important further consideration when designing NMRlib is the possibility of adding new experiments to the library, which then are accessible as a button that performs the setup of the experiment. To include a novel experiment in ssNMRlib, buttons are available which create the template and setup scripts from an experiment that has been collected. The newly created setup routine is available as a button in the ssNMRlib browser window (see below). The organization of buttons within the NMRlib GUI tree structure is fully customizable.

We have, moreover, implemented a safety check routine, which verifies whether the chosen RF parameters (pulses, ramps, parameter optimizations, vdlist, delays, etc.) are within the probe-specific limits.

2 Implementation of ssNMRlib

NMRlib is an add-on in the Bruker Topspin software and has been tested currently on Topspin 3.5, 3.6 and 4, on Linux host computers, and on AVANCE III and NEO consoles. ssNMRlib is part of the NMRlib library and is installed at the same time as NMRlib. The NMRlib GUI window is launched directly from a button within the Topspin software (see Fig. 2a). NMRlib comprises a set of jython scripts, pulse sequences, selective-pulse and ramp shapes, and acquisition lists (vdlist, vclist, etc.), which can be saved either locally on one spectrometer or on a centrally mounted disk (which may be on one spectrometer) to which all spectrometers have access. The latter is very useful for ensuring that a whole facility uses the same experiments. The individual experiments (pulse programs, one jython script for acquisition, one for processing parameters and one for the security check) are organized in a directory tree structure and buttons in the GUI windows allow navigation through these directories. The organization of the experiments can be fully customized, and new experiments can be added to any location within the file structure. The library also contains all the shape files for selective pulses, amplitude ramps, etc., and decoupling sequences used by ssNMRlib, as well as a file required for safety checks (see below). On each spectrometer, the files with the correct routing need to be available, e.g. for ¹H, ¹³C or ¹⁵N detection experiments. The principal elements of the prosol table (power levels of the different channels) need to be up to date. These latter instrument-specific files, together with the general, non-instrument-specific scripts and the pulse sequence, contain everything needed to run ssNMRlib on a given instrument.

Figure 2 (a) ssNMRlib windows and example workflow. An icon with the logo “ibs” in Topspin (top) launches the main GUI window (lower left). Here the navigation to a carbon-detected 3D hCONcaCB experiment is exemplified. After clicking the corresponding experiment button, a window with the relevant parameters opens, including reasonable propositions or (if available) pre-calibrated values of the most relevant acquisition parameters (right). The buttons on the bottom of the window allow navigation within the ssNMRlib file structures, access the underlying scripts in a file browser window, or save the current experiment as a template. (b) Flow chart of the steps performed by the underlying ssNMRlib script when clicking an experiment button. The spectrometer routing files (one per detected nuclei) are a parameter set, obtained by saving (wpar) the parameter set of a high-dimensional experiment (typically 4D) with the correct routing.

Part of the current ssNMRlib experiment file tree is shown in Fig. 1b. Example screenshots of the NMRlib windows are shown in Fig. 2a. Currently, the library is organized to have in the top level branches (buttons) for setup experiments (KBr, adamantane), a main branch containing ¹H-, ¹³C- or ¹⁵N-detected experiments, as well as buttons leading to scripts, including those that allow addition/removal of templates to/from the library, saving acquisition parameters or retrieving them from a previous session. In addition, the NMRlib window also contains an “Editor” button to navigate directly to the folder structure that contains the underlying scripts and pulse sequences pertaining to a given NMRlib window (“pp” – pulse sequences, “py” – jython scripts, and “vc” and “vd” – lists). Furthermore, a “Save” button allows an experiment to be saved in order to create a template from an experiment that has been acquired (see Sect. 2.4).

The tasks performed by a typical script in ssNMRlib which sets up an experiment are shown in Fig. 2b. It starts by reading a file that contains the probe/amplifier routing. The further steps of the setup script load the pulse sequence, adjust the dimensionality, read the current MAS frequency, set pulse lengths (either from prosol or, if available, from a previous calibration), calculate acquisition parameters based on the MAS frequency and e.g. Hartmann–Hahn condition or automatically retrieve previously optimized parameters, calculate the decoupling power levels from kHz values and load processing parameters. Lastly, the script opens a GUI window that summarizes the most important parameters (Fig. 2, centre). The user may manually modify parameters at this step. Of course, all parameters can also be changed at any point in the AcquPars tab in Topspin. Another added value of the ssNMRlib software is that all the parameters of an experiment are automatically checked to ensure the probe safety before launching an experiment.

2.1 Workflow with ssNMRlib

The typical workflow with ssNMRlib can be described as follows. After setup of the sample spinning and probe tuning, possibly with adjustment of the magic angle and shims (templates for KBr acquisition (Frye and Maciel, 1982) and adamantane ¹³C observation are included in ssNMRlib), the user typically wants to calibrate 90^∘ pulses. A number of automated routines, described below, allow pulse calibration. The optimized values are stored and then used for the setup of all other experiments. In a similar manner, further calibration experiments e.g. for cross-polarization or scalar-coupling-based transfer are available with buttons in the calibration menu, and their optimized values (power levels, shape parameters, durations, etc.) are likewise stored by ssNMRlib. All optimized parameters of hard pulses and transfer parameters are stored in a dedicated text file. This file can also be re-imported into ssNMRlib at a later point; this feature is handy e.g. if one interrupts a measurement session and continues at a later time point, starting with the previously optimized acquisition parameters.

Once all the required transfers and pulses have been optimized, clicking a button for a specific experiment (e.g. a 2D, 3D or 4D correlation experiment) executes a script that automatically reads the optimized parameters used in all the transfer steps, calculates power levels and shapes, and sets up the particular experiment. These steps are described in the following sections.

2.1.1 Pulse calibration

A number of experiments for 90^∘ pulse calibrations are available, e.g. a nutation experiment with a direct hard-pulse excitation or with CP or INEPT transfer schemes. Figure 3 exemplifies a ¹H pulse calibration with a ¹H-detected hNH experiment, typically used for proteins at fast MAS. The underlying python script loads the instrument-specific parameter set (routing, power levels, pulse lengths, etc.) and pulse sequence and sets up a parameter optimization (popt in Bruker language) protocol using pre-defined spectral ranges to be observed (e.g. amide ¹H frequency range) and the range of values used for the parameter optimization, in this case ¹H pulse length. This range is based on typical values for the present probe, which are retrieved from the prosol table. At the end of the parameter optimization, the pulse duration is retrieved automatically (e.g. from finding the zero-crossing of the integrated spectral intensities). The value of the 90^∘ pulse is stored, and can be inspected and modified within the NMRlib window any time (Fig. 3).

Figure 3 Procedure for hard-pulse calibration in ssNMRlib, exemplified for the case of the ¹H pulse, detected via a ¹⁵N-filtered CP-based hNH experiment. A popup window asks whether the calibration shall be used as the basis for all later calculations (of selective pulses, CP transfers and decoupling, expressed later in kHz; button named “Before”) or whether it is a re-calibration/verification of the pulse that shall not impact the calculation of CP power levels (button named “After”). Different CP ramps are available, and reasonable values are proposed based on the MAS frequency and Hartmann–Hahn match conditions. Lastly, a popup window summarizes the most relevant acquisition parameters before the popt procedure is launched. The optimized value is automatically stored; the cogwheel symbol in the ssNMRlib window next to the button allows display (and editing) of the currently stored optimized value.

2.1.2 Automatic calculation of power levels and shapes in ssNMRlib

With calibrated 90^∘ pulse durations and power levels and a linearized amplifier, all power levels of decoupling and recoupling pulses and shapes as well as selective pulses can be calculated automatically. ssNMRlib does not require the user to do any calculation in Watt or dB units but wherever possible makes calculations from user-specified values in kilohertz units. Furthermore, selective pulses, e.g. REBURP, EBURP (Geen and Freeman, 1990) or ISNOB (Kupce et al., 1995), are directly calibrated within the pulse sequence, based on the known characteristics of a given pulse shape, as well as the desired excitation bandwidth.

Figure 4 shows pulse sequence snippets that illustrate how these calculations are done in practice. The calibrated 90^∘ hard-pulse durations and power levels can be translated to the RF field strengths (assigned to variables cnst1, cnst2, cnst3, and cnst4 for ¹³C, ¹H, ¹⁵N and ²H nuclei, respectively) that correspond to the power levels at which these pulses have been calibrated. Selective pulses are then calculated for a given shape, excitation bandwidth, spectrometer frequency and the hard-pulse calibration. The use of the spectrometer frequency ensures that the parameters are calculated correctly for any field strength. Possible frequency shifts from the carrier to the excitation band are calculated in a spectrometer-independent manner (in ppm).

Figure 4 Calculation of RF pulse parameters in ssNMRlib sequences for spectrometer-frequency independent setup. (a) The hard pulses (p21, p22, p23) are translated to RF field strengths in kilohertz (cnst1, cnst2, cnst3). (b) Calculation of selective-pulse parameters exemplified for off-resonance ISNOB2 and an on-resonance REBURP shape, using 70 ppm excitation bandwidth, at a spectrometer operating at a frequency of bf2 (in MHz). The values of cnst16 and cnst17 represent the centres of the CO and CA frequency bands, respectively, in ppm units. (c) Calculation of power levels of a cross-polarization, here for a ¹H−¹³C transfer with an amplitude ramp on the ¹H channel. The desired RF field values in kHz in the middle of the ramp are specified in cnst31 (for ¹³C) and cnst41 (¹H); the additional cnst61 corresponds to the percentage value of ramp in its centre, e.g. cnst61 =85 for a ramp that goes from 70 % to 100 %. As the power level of the ramp corresponds to the highest value of the ramp, this constant is needed for the calculation, in addition to the midpoint RF field strength. (d) Calculation of amplitude for a ramped transfer on one channel, such as DREAM or BSH-CP. The RF field strength at the midpoint of the ramp corresponds to cnst38.

The calculation of power levels for cross-polarization or other amplitude ramps is illustrated in Fig. 4c, d. The power level is specified by the user in kilohertz as constants (cnst) in Topspin and internally translated to Watt, using the 90^∘ hard-pulse durations and power levels. The use of kHz values allows the user to immediately have a reasonable set of starting values, based on Hartmann–Hahn matching conditions for CPs, HORROR conditions, etc.

Currently, the shape files are not created on the fly (which might be done with Bruker's WaveMaker library), but they are stored locally. The user can change the CP ramp file to any desired shape in the AcquPars tab. Just like these recoupling sequence elements, the decoupling power levels are calculated from desired RF field strengths (in kHz).

2.1.3 Optimization of transfer elements

The calibration of transfer steps, based on e.g. cross-polarization, of other dipolar-based transfers such as RFDR, DREAM, BSH-CP, and INEPT-based transfers, follows a similar philosophy, exemplified in Fig. 5 for the optimization of a CO-CA BSH-CP (left) and ¹H-¹³C CP transfer (right). Dedicated buttons for each of these transfers allow loading of calibration experiments, which use the previously optimized hard pulses. A ssNMRlib window summarizes the acquisition parameters, allows the ramp or the carrier position to be chosen and sets up a popt optimization protocol. The optimized parameters are stored for later use in other experiments in ssNMRlib and can be modified from the NMRlib GUI and saved to a file. In addition, a function termed “Load constants” allows retrieval at any point of a particular set of parameters, e.g. the cross-polarization power levels, shape and duration.

Figure 5 Optimization procedure of transfer steps. (a) Setup of BSH-CP CO-CA transfer optimization, found in carbon detection – calibrations – CC transfers. Several parameters (RF field, durations, trim pulses) can be optimized. The theoretical values, calculated for the frequency offset and MAS frequency, are shown in the shell console and in a popup window. The optimized acquisition parameters after optimization are automatically stored and can be inspected by clicking on the cogwheel symbol (top windows). (b) Setup of ¹H-¹³C CP optimization. A choice of optimization parameters (RF field strengths, duration), different pre-defined ramps (e.g. linear 70–100 ramps) and carrier offsets is proposed.

ssNMRlib is open to the use of different modes of detection (¹H, ¹³C, ¹⁵N) within the same session and on the same probe. For example, one may want to collect a ¹³C-detected experiment and a ¹H-detected one on the same sample and same probe. Accordingly, calibrations done in one detection mode (e.g. a N–C CP transfer optimized with a ¹³C-detected experiment) are automatically retrieved for a ¹H-detected experiment that uses this transfer (e.g. a H–N–C correlation experiment).

Of note, ssNMRlib uses a uniform naming convention for acquisition parameters. For example, a common parameter name, such as cnst41, is used for the CP power level of ¹H in all occurrences of ¹H−¹³C CPs, and it is different from e.g. the one used for the ¹H power in ¹H−¹⁵N CPs. This clear naming convention (see Table S1) additionally helps the user to retrieve parameters – although ssNMRlib is made such that the user does not need to remember those names, due to the automatic parameter retrieval. It is recommended to use the same naming convention when adding new experiments. A consistent naming convention is also very useful for safety checks (see Sect. 2.3).

2.2 Current content and organization of ssNMRlib

ssNMRlib can be fully customized, i.e. experiments can readily be added and deleted, and the organization can be modified, as described in Sect. 2.4. This section describes the current state of ssNMRlib, containing some 140 different pulse sequences, including a number of general homonuclear and heteronuclear correlation experiments and a large panel of proton-, carbon- and nitrogen-detected 1D, 2D, 3D and 4D experiments for resonance assignments, structure determination and measurements of molecular dynamics. The nomenclature used below to describe experiments employs upper-case letters for nuclei of which the chemical shift is edited and lower-case letters for nuclei which are not frequency-edited. The full list of experiments currently in ssNMRlib is shown in Listing S2 in the Supplement.

2.2.1 One- and two-dimensional experiments with ¹³C or ¹⁵N detection

¹³C- and ¹⁵N-detected experiments are most useful for samples spinning at moderate MAS frequencies, typically using 3.2 mm rotors (the use of 4 and 1.9 mm rotors can be implemented in a straightforward manner). ssNMRlib contains ¹³C-detected and ¹⁵N-detected experiments with ${}^{\mathrm{1}}\mathrm{H}{-}^{\mathrm{13}}\mathrm{C}{/}^{\mathrm{15}}\mathrm{N}$ CP or INEPT transfer or direct ¹³C∕¹⁵N excitation as well as 1D versions of double-CP hnCA and hnCO experiments. Experiments for measurement of ¹H longitudinal relaxation (saturation recovery) are useful for choosing an appropriate recycle delay; furthermore, ¹³C and ¹⁵N transverse (T₂^′) relaxation rate constants provide a rapid view of the coherence lifetimes and may be useful for optimizing decoupling parameters.

Two-dimensional ¹³C-detected experiments comprise homonuclear ¹³C−¹³C correlations with DARR (Takegoshi et al., 2001), DREAM (Verel et al., 1998), ALFRESCO (Wi and Frydman, 2020), RFDR (Bennett et al., 1992) and CHHC (Lange et al., 2003) transfer. A ¹⁵N-detected proton-driven spin diffusion (PDSD) experiment and a NHHC experiment are also available. Additionally, ¹³C−¹³C correlation experiments based on SPC5, S3 and various C and R sequences are under development. These pulse sequences are useful for a number of organic solids including biomolecules.

2.2.2 Carbon-detected resonance assignment experiments

Currently, a dozen ¹³C-detected experiments are present in ssNMRlib for high-dimensional (3D, 4D) correlation spectra. The majority of the presently available experiments are intended for protein resonance assignment, including 3D hNCACB, hNCACX, hNCOCX, hCANCO, hCONcaCB, and hCOCACB and 4D hCANCOCX, hCONCACO and hCONCACB experiments, which use cross-polarization for H–X and N–C transfers. For ¹³C−¹³C transfers, we have implemented several options, including DREAM (Verel et al., 2001), DARR (Takegoshi et al., 2001), RFDR (Bennett et al., 1992) and BSH-CP (Chevelkov et al., 2013) transfers. Figure 6 shows one backbone pulse sequence from the library, a 3D h-CO-CA-CB experiment with BSH-CP and DREAM transfer steps, which, to our knowledge, has not been proposed before, and its application to a 50 kDa protein that assembles to tube-like structures (Fraga et al., 2017).

Figure 6 (a) 3D hCOCACB correlation experiment is composed of h-CO CP, CO-CA BSH-CP and CA-CB DREAM transfer steps. Filled and open bars denote π∕2 and π pulses, respectively. Unless otherwise noted, the phase is x. The ¹³C carrier frequency is changed during the pulse sequence as denoted by elements applied to either ¹³CO or ¹³CA∕CB, respectively. (b) Experiment done on a 600 MHz spectrometer with 15 kHz MAS, 25 ^∘C, with a ¹³C, ¹⁵N labeled sample of a protein assembly from bacteriophage (Fraga et al., 2017).

2.2.3 Carbon-detected experiments for flexible systems

A suite of experiments has been implemented for application to flexible molecular systems, where CP-based transfers are inefficient, and scalar-coupling-based transfer is the better choice for correlation spectroscopy. This kind of experiment has been successfully applied, e.g. to bacterial peptidoglycan cell walls (Kern et al., 2008) or flexible tails in proteins (Gao et al., 2013). We have implemented ¹H−¹³C and ¹H−¹⁵N HETCOR experiments, hNCA, hNCO, hNcoCA, hNcaCO and hCC correlation spectra, all based on INEPT transfer steps between H–N, H–C, C–C and N–C nuclei. An additional hCC experiment with an initial H–C CP transfer followed by a C–C INEPT transfer is particularly useful for systems with some degree of flexibility that still have sufficiently large dipolar H–C couplings to make the initial H–C CP the most efficient choice. We have furthermore experiments with direct ¹³C excitation followed by C–C INEPT transfer.

2.2.4 Proton-detected protein resonance assignment experiments

The largest part of the current ssNMRlib implementation comprises ¹H-detected experiments, which are ideally used in combination with deuteration and reprotonation of e.g. amide, methyl or aromatic sites (Barbet-Massin et al., 2013; Fricke et al., 2017; Fraga et al., 2017; Gauto et al., 2019; Xiang et al., 2015; Linser et al., 2010; Zhou et al., 2007). When used at MAS frequencies above 60–100 kHz, fully protonated systems can also yield comparably good ¹H line widths (Stanek et al., 2016). The 2D experiments comprise basic ¹H−¹⁵N and ¹H−¹³C correlations and simultaneous ¹H−¹⁵N and ¹H−¹³C 2D correlation experiments, with either INEPT or CP transfers.

ssNMRlib currently comprises more than 40 different experiments for protein resonance assignment with ¹H^N or ¹H^α detection (listed in Listing S2 in the Supplement). The 3D and 4D experiments for protein resonance assignment comprise all possible correlation spectra of the amide ¹H−¹⁵N moiety with the ¹³Cα, ¹³Cβ, ¹³C^′ and ¹⁵N nuclei at both sides of the amide; 3D and 4D variants are implemented.

We have used the following general principles when designing these experiments.

• -

  Cross-polarization is used for all transfers between ¹H and either ¹⁵N or ¹³C as well as for the transfers between ¹⁵N and ¹³C (either direction). Additionally, for the case of the intra-residue ${\mathrm{H}}_{\mathrm{i}}-{\mathrm{N}}_{\mathrm{i}}-{\mathrm{CA}}_{\mathrm{i}}$ and inter-residue ${\mathrm{H}}_{\mathrm{i}}-{\mathrm{N}}_{\mathrm{i}}-{\mathrm{CA}}_{\mathrm{i}-\mathrm{1}}$ experiments, the variants with N–C TEDOR transfers are implemented.

• -

  For $\mathrm{C}\mathit{\alpha }-\mathrm{C}{}^{\prime }$ or $\mathrm{C}{}^{\prime }-\mathrm{C}\mathit{\alpha }$ transfers, we have implemented different coherence-transfer elements: (i) refocused INEPT for unidirectional experiments such as hCACONH or INEPT for out-and-back transfers such as in hcoCAcoNH; (ii) additionally, experiments with band-selective ${\mathrm{C}}^{\prime }-\mathrm{C}\mathit{\alpha }/\mathrm{C}\mathit{\alpha }-\mathrm{C}{}^{\prime }$ cross-polarization (BSH-CP) have been implemented; this transfer, based on dipolar couplings, may outcompete INEPT-based experiments when fast ¹³C coherence decay hampers the latter.

• -

  For Cα−Cβ transfers, we have implemented experiments based on scalar-coupling transfer, akin to solution-state HNCACB or HNcoCACB experiments; the setting of the transfer delay leaves the user the freedom to choose either full transfer to Cβ or only partial transfer, which results in both Cα and Cβ signals.

• -

  In experiments with INEPT-based ¹³C−¹³C transfer and chemical-shift editing of one of the two involved carbons or both of them, the chemical-shift evolution is done in a constant-time (CT) manner. CT editing comes at no cost in terms of sensitivity; i.e. the FID along this dimension does not decay. CT editing requires that the maximum evolution time is kept within the INEPT transfer delay, which is typically of the order of 6–7 ms. Additional semi-constant-time versions which do not have these limitations are also implemented.

• -

  In experiments that involve a dipolar-coupling-based ¹³C−¹³C transfer, e.g. with BSH-CP, no constant-time editing is done, because unlike the INEPT case above, the chemical shift cannot be edited during the transfer.

• -

  We have systematically implemented homonuclear (¹³C) decoupling in all indirect ¹³C dimensions, in particular CO decoupling during CA frequency editing (and vice versa), using a band-selective inversion pulse (ISNOB-2, Kupce et al., 1995). This shape is advantageous because of its good compromise of pulse duration and cleanliness of the inversion profile. To correct the Bloch–Siegert shift, a second ISNOB-2 is applied to the decoupled band and a REBURP refocusing pulse to the nucleus which is monitored. This implementation is illustrated in Fig. 7a.

• -

  In all indirect dimensions, heteronuclear decoupling is applied; when monitoring ¹³C frequencies, a ¹⁵N π pulse is applied, and vice versa. ¹H is decoupled with composite pulse decoupling (swfTPPM, Thakur et al., 2006, or WALTZ-16, Shaka et al., 1983). During ¹H acquisition, composite-pulse decoupling is applied to ¹⁵N and/or ¹³C as appropriate (generally using the WALTZ-16 scheme, Shaka et al., 1983).

  As described above, all required band-selective decoupling pulses are calculated and set within the pulse sequence, and the correct shape(s) are called by ssNMRlib's python setup routines. The decoupling field strengths $\mathit{\gamma }\cdot B_{\mathrm{1}}/\left(\mathrm{2}\mathit{\pi }\right)$ can be specified in kHz by the user, and the setup script proposes values and sets the duration of the unit element pulse accordingly.

• -

  For the majority of the assignment experiments, we have versions with additional deuterium decoupling. These experiments may be used with probes equipped for a ²H channel. The deuterium decoupling may increase coherence lifetimes of carbons in deuterated proteins (see below).

  Figure 7a shows one example pulse sequence, a 4D hCONCAHA experiment with detection of the Hα protons, which, to our knowledge, has not been published elsewhere. Figure 7b shows exemplary sensitivity comparisons of different experiments for two different protein assemblies. The data are in good qualitative agreement with reported sensitivity comparisons presented elsewhere (Barbet-Massin et al., 2013; Fraga et al., 2017). It is interesting to compare e.g. INEPT vs. BSH-CP transfer variants in experiments involving CO-CA transfers. The availability of pulse sequences with different transfer types allows the user to evaluate which experiment provides better sensitivity for a particular sample, before launching the 3D or 4D versions of these experiments.

Figure 7 (a) 4D hCONCAHA pulse sequence for Hα-detected backbone correlation, using cross-polarization transfer steps. Filled and open bars denote π∕2 and π pulses, respectively. Homonuclear ¹³C−¹³C decoupling is achieved with band-selective ISNOB2 pulses; Bloch–Siegert shift effects are compensated. Solvent suppression follows the ideas of the MISSISSIPPI scheme (Zhou and Rienstra, 2008) but unlike the original proposition uses a composite-pulse-decoupling scheme for saturating the solvent signals while storing the magnetization on the heteronucleus (+C_z). Quadrature detection is achieved with phases Φ₁, Φ₂ and Φ₄, whereby the phase is changed by either +90 or −90^∘, as indicated. (b) Sensitivity comparison of diverse pulse programs with a tube-like protein assembly formed by 50 kDa large subunits (Fraga et al., 2017) and decameric assembly of 10×21 kDa, in orange and blue, respectively. The data were obtained by integration of 1D variants of the pulse sequences.

2.2.5 Distance measurements for structure determination

Proton-detected experiments that probe ¹H−¹H distances have been successful for determining structures of deuterated, partially reprotonated samples (Zhou et al., 2007; Linser et al., 2011; Huber et al., 2011; Knight et al., 2012). When combined with ¹³C and/or ¹⁵N dimensions, such 3D or 4D experiments provide highly useful structural information. These experiments have been successful even for determining structures of very large proteins, up to 12×39 kDa (Gauto et al., 2019), and even fully protonated proteins (Agarwal et al., 2014; Andreas et al., 2016). Recoupling the ¹H−¹H dipolar interaction has been achieved primarily with RFDR (Zhou et al., 2007; Linser et al., 2011; Knight et al., 2012), DREAM (Huber et al., 2011; Agarwal et al., 2014) and rotating-frame spin diffusion (Wittmann et al., 2016; Jain et al., 2017). It has been shown that ¹H−¹H distances can be measured simultaneously for protons bound to ¹³C or ¹⁵N using simultaneous ¹H−¹³C and ¹H−¹⁵N CP steps, yielding simultaneously the connections between H^N−H^N, H^N−H^C and H^C−H^C distances (Linser et al., 2011; Gauto et al., 2019).

We have implemented RFDR and band-selective spectral spin diffusion (BASS-SD; Jain et al., 2017) experiments, with versions yielding 3D experiments with either one or two ¹H dimensions and either two or one ¹³C∕¹⁵N dimensions.

2.2.6 Experiments probing molecular dynamics

Solid-state NMR is ideally suited for investigating internal molecular motions without the limitations that arise in solution-state NMR due to the overall molecular tumbling (Krushelnitsky and Reichert, 2005; Schanda and Ernst, 2016; Lamley and Lewandowski, 2016; Rovó, 2020). ssNMRlib contains a number of experiments that measure (i) dipolar couplings, which directly report on the order parameters of bonds, and (ii) longitudinal and transverse spin-relaxation parameters of ¹³C and ¹⁵N, which are sensitive to amplitudes and timescales of motion. (iii) Slower exchange dynamics can be probed by ¹⁵N- or ¹³C-edited exchange spectroscopy (EXSY, Meier and Ernst, 1979) or a version with simultaneous ¹⁵N and ¹³C editing, which are implemented in ssNMRlib. We furthermore have implemented chemical-exchange saturation transfer (CEST, Vallurupalli et al., 2012; Rovó and Linser, 2018) experiments to probe slow motions.

The dipolar-coupling measurements are based on a time-shifted REDOR experiment (Haller and Schanda, 2013; Schanda et al., 2010) and are available with either CP or refocused-INEPT transfers. Figure 8 shows a hNH CP REDOR pulse sequence and a series of 1D REDOR experiments. Both R₁ and R_1ρ relaxation experiments are available for ¹⁵N with either 2D (hNH) or 3D (hCONH) readout and ¹³CO (with 3D hCONH readout) and ¹³C (with 2D hCH readout).

Figure 8 (a) hNH REDOR pulse sequence for measuring dipolar couplings, as implemented in ssNMRlib for ¹H−¹⁵N (shown here, reported in Haller and Schanda, 2013) and ¹H−¹³C dipolar couplings. Filled and open bars denote π∕2 and π pulses, respectively. The experiment has the possibility of shifting the central π pulse of each rotor period on the ¹H channel by setting the delay τ (d7), which scales down the dipolar-coupling evolution and therefore allows sampling of the REDOR curve with more points and thus higher precision (Gullion and Schaefer, 1988; Schanda et al., 2010). (b) Experimental series of 1D ¹H−¹⁵N REDOR spectra, collected at 55.555 kHz MAS, ¹H and ¹⁵N π pulses of 5 and 10 µs, respectively, and a delay d7 of 3 µs (i.e. 0.5 µs between the closest consecutive π pulses.

Additionally, ¹H relaxation parameters can be measured with either ¹H- or ¹³C-detected pulse sequences implemented in ssNMRlib (see also Sect. 2.2.1). ¹H relaxation is generally challenging to interpret quantitatively (Schanda and Ernst, 2016), but the knowledge of longitudinal relaxation is useful for choosing the recycle delay that yields the highest signal-to-noise ratio per unit measurement time. Furthermore, knowing the apparent ¹H coherence lifetime is useful for setting up e.g. the maximum evolution time in indirect ¹H dimensions.

2.3 Probe security handling in ssNMRlib

Ensuring that the power deposited in the probe is tolerated by the hardware is an important part of any NMR data acquisition. Topspin has a Power-Check feature, which verifies the RF peak power sent to the probe (in Watt). If Power-Check is enabled, it does not allow acquisition if the power exceeds the limit on any channel. However, when applied for too long a time, even an RF field at lower power would destroy the probe, such that the built-in Power-Check is insufficient for avoiding hardware damage. Limiting the power to strictly exclude any possible probe damage is difficult, because hardware damage may arise as a complex function of deposited RF power, its duration and the duty cycle.

We have implemented power checks in ssNMRlib which verify peak power levels and durations of pulse sequence elements, e.g. CP elements, decoupling or hard pulses. The safety check is performed automatically by ssNMRlib whenever the user clicks on a button to load an experiment. In addition, a “Security” button in Topspin, right next to the button to launch NMRlib, as well as a button in the ssNMRlib window (see Fig. 2), can be clicked at any time to control the user-modified parameters.

The safety checks in ssNMRlib access a table (which can be modified by the user) that lists the accepted durations and power levels (in kHz) for a given element. This table comes with ssNMRlib. We have decided to check RF power levels in kHz rather than in Watt, because probe specifications generally given by the manufacturer are in kHz; most spectroscopists also have a more intuitive understanding of what a probe can sustain, in kHz, rather than in Watt. In the Linux console from which Topspin was started, all the parameters that have been verified are listed, including whether they are within the limits of the probe (Fig. 9). In case a parameter exceeds the specified power limits, a popup window warns the user, and the warning is written in the Linux terminal. The user can nonetheless start the experiment by typing zg, despite a security warning. We have made this choice as we think that responsible NMR users, once warned, can make informed decisions. In the calibration experiments, which are usually launched automatically, a security check is performed, and if it fails, the acquisition is not started. The safety checks also verify the maximum power reached in RF ramps and parameter optimization (popt) arrays. The safety check is probe-specific; i.e. a separate table of tolerated RF parameters is defined for each probe head.

Figure 9 Example of security checks for the hCANH R1rho experiment. Shown is the output that ssNMRlib writes to the Linux console from which Topspin was started. All parameters used by the experiment are compared to values specified in a probe-specific table, and security warnings are issued in this console window as well as in a popup window in case a parameter exceeds the specifications.

The safety checks are currently bound to the naming convention and definitions used in a given experiment, as it will check, for example, the power level of the ¹H RF field for a H–N CP (cnst42). When a user adds new experiments (see below), care should be taken to keep this naming convention or to modify the security checks accordingly. The safety checks in ssNMRlib cannot exclude damage but serve as a useful guide. A more detailed description of the safety check is provided in the Supplement (Listing S4).

2.4 Adding new experiments to ssNMRlib

ssNMRlib allows an experiment to be integrated into the library. Once integrated, the experiment is available as a button in the GUI window, and hitting this button will launch a script that sets up the experiment (pulse sequence, calculation or setting of acquisition parameters, setting of processing parameters, etc., as described for the other experiments above). Integrating an experiment into ssNMRlib can be done by clicking the floppy disk icon in the GUI window. A popup window allows us to specify the important parameters and write a short manual for the experiment, which will appear when clicking the new button (Listing S5). The pulse program, one jython script for acquisition and one for processing parameters are automatically generated. Additional functionalities could be added inside the jython script for decoupling calculation, recall of constants or automatic security checks. By convention, we have set in the library

• -

  experiment.py: jython script containing experiment specific acquisition parameters.

• -

  p_experiment.py: jython script defining experiment specific processing parameters.

• -

  experiment_p.py: cogwheel symbol jython script used for non standard and experiment specific data analysis.

• -

  experiment_sec.py: experiment specific security jython script.

When programming new pulse sequences, we strongly advise using the naming conventions for pulses, shapes, decoupling, delays, etc., which are listed in Table S1. More information about adding new experiments is also provided in the Supplement (Listing S5).

2.5 Additional useful macros for processing and experiment setup

NMRlib comes with a number of additional useful macros and scripts for various tasks, including saving and reading acquisition parameters, processing (e.g. phasing 3D or 4D experiments or summing spectra or time-domain data) or plotting (in Matplotlib format). These tools are described in the following sections.

2.5.1 Store and retrieve acquisition parameters and pulse sequences

ssNMRlib contains many useful tools for optimizing parameters, keeping the parameters in memory, and using the optimized parameters of all the required pulse sequence blocks when setting up a complex experiment. ssNMRlib allows all the present parameters to be written in a user-friendly text file, the “recap file”. The file saves all currently stored parameters along with the date/time of their creation, which allows the user to see which parameters have been recently optimized. We have also implemented the possibility of removing all optimized parameters, thus starting “from scratch” and avoiding the use of old parameters.

The recap file contains, in addition to the optimized RF parameters, information about the identity of the installed probe, the cooling gas flow and temperature, MAS frequency, and the location where the NMR data are stored.

In our experience, the recap file is a very useful tool for keeping track of and retrieving all experimental parameters after the experiments have been concluded, in a format that is more convenient than the Bruker acquisition file (acqus).

An example recap file is shown in Listing S3.

The same button also allows us to read a previously stored “recap file”. In this way, optimizations saved during a previous NMR session can be automatically put back into the library. The user will thus be able to load any experiment from the library with the previously optimized parameters.

A “Save your pulse program” button allows us to save the current pulse program in the present acquisition directory. This button is very useful e.g. when programming/editing pulse sequences: the user can save the present state of a sequence along with the data. This allows us to more easily develop or debug pulse sequences and retrieve a previous state of a sequence.

2.5.2 Processing macros

General processing tools are part of NMRlib and have been introduced before (Favier and Brutscher, 2019). As ssNMRlib is part of this library, all previously proposed tools are also available for solid-state NMR experiments. Tools are available to add two multi-dimensional spectra (in time or frequency domain), to phase multi-dimensional (3D, 4D) spectra, or to remove (i.e. set to zero) corrupt FIDs from a multi-dimensional data set, which may arise for example as a consequence of arching in ssNMR experiments using python packages (numpy, Van Der Walt et al., 2011, nmrglue, Helmus and Jaroniec, 2013, and Matplotlib, Hunter, 2007). Another macro allows us to correct FIDs for magnetic-field drift (i.e. shearing of the spectrum), which shall be particularly useful for solid-state NMR experiments, where it is generally not possible to use a deuterium lock to stabilize the field. Other routines described earlier (Favier and Brutscher, 2019) allow nmrPipe (Delaglio et al., 1995) processing scripts to be generated or a circular shift to be performed to correct for potential missettings of the carrier frequency. Further scripts, using python/nmrglue/numpy, allow extraction of intensities, plotting spectra in Matplotlib format or fit data, as discussed e.g. for solution-state NMR experiments (DOSY, TRACT, etc.), as described (Favier and Brutscher, 2019).

3 Conclusions and perspectives

We have presented herein ssNMRlib, a comprehensive library of pulse sequences and setup scripts which markedly facilitate solid-state NMR data acquisition, security checks, tracking of parameters and data handling. We developed the library in a multi-spectrometer facility, and the fact that pulse sequences are all centralized contributes greatly to keeping data acquisition simple and reproducible. While the current ssNMRlib version has its focus on pulse programs for biomolecular applications, the library can be extended in a straightforward manner to any kind of NMR data acquisition.

We are currently implementing more experiments, such as C- and R-type (Levitt, 2002) sequences, as well as ³¹P and ¹⁹F experiments. We foresee in future versions of ssNMRlib the use of the WaveMaker library, which allows us to create shape files (ramps, selective pulses, decoupling sequences) directly from within the pulse sequence on the fly. This would allow us to perform a parameter optimization for shape files (e.g. adiabaticity), which currently requires us to change the shape file name manually.

We encourage our colleagues in the field to add their pulse sequences and hope that the platform we created will be useful for a wide range of NMR applications. While a user may simply add her/his experiments to the own local library, it also facilitates the exchange of experiments between laboratories.