Seedless Technical Manual and Pulse Creation Guide
Theory, pulse design, input syntax, optimisation, and validation
Version 1.3

Contents

1 Introduction

Seedless rapidly calculates GRAPE pulses, primarily for NMR spectroscopy, and is fast enough to generate pulses matched to particular hardware and sample conditions [?, ?, ?]. Properly designed pulses can significantly improve experimental sensitivity. Its speed comes from combining established and newer optimisation ideas [?, ?]. In addition to bespoke GRAPE calculations, the program can construct and analyse traditional shapes such as BURP and CHIRP pulses, optimise smooth Fourier or power-series descriptions, import existing shapes, and perform specialised evolution and diagnostic analyses.

Pulse design is an engineering problem with competing constraints. Bandwidth, selectivity, pulse duration, maximum B1, RF inhomogeneity, finite-element duration, transition width, and required transformation all affect the attainable performance. The program makes it inexpensive to explore these compromises, but a low numerical score does not remove the need to check the full simulated profile and validate the result experimentally.

Seedless is written in C++ and controlled by a text input file. The companion GUI constructs the same file from graphical controls. This manual introduces each concept in terms of the underlying script, then retains a complete syntax reference in Section x1-570001010. The companion GUI manual focuses more on getting up and running quickly.

Seedless focuses on isolated spin-1/2 systems. When only one spin is pulsed at a time and evolution is controlled appropriately, such pulses will exactly control weakly coupled systems and to higher-spin nuclei whose anisotropic interactions are motionally averaged [?].

The recommended default is constant-amplitude, phase-only optimisation [?]. In our experience it is fast, robust, and usually performs at least as well as a comparable simultaneous amplitude-and-phase optimisation. Amplitude-only and combined modes remain available when the hardware or application requires them, as do conversions between phase-only and amplitude-modulated forms.

Otherwise, enjoy using Seedless. Please email us if you have any problems.

Andy Baldwin and Jonathan Jones

andrew.baldwin@chem.ox.ac.uk

jonathan.jones@physics.ox.ac.uk

© University of Oxford

Thanks to Team Seedless: Charles Bunchanan, Gaurav Bhole, Jack Bercovici, Bowen Guo, Suzanne Lim, Abi Turner, Gogulan Karunanithy, Virginia Casablancas-Antras, Adeline Poh, Ben Davis, Eiso Ab.

2 Quick start

1.

Work through the setup and installation instructions (Section x1-400033);

2.

Run the test HNCO carbon input without modification;

3.

Confirm that a pulse file and summary PDF are produced;

4.

Copy the input file and change one parameter at a time to see what they do;

5.

Use a nearby demo or the GUI templates to explore a range of cases; and

6.

Then use these principles to make whatever pulses you need!

The full demonstration suite provides a useful regression test once the initial example is working. It should create 36 pulses of a wide range of pulse types. You can run this from the command line, or clicking Run pulse collections in the Templates tab in the GUI.

If you can run the demonstration and you can generate the output files, the installation was successful and you are good to go.

3 Setup and installation

The downloaded distribution should contain the following folders. For the initial tests, keep this directory structure unchanged, as many of the demonstration scripts locate the executable using relative paths.

3.1 Required components

A complete installation requires:

• a working platform-specific Seedless binary;
• Python 3 and the seedlessRun wrapper;
• gnuplot and pdflatex available for PDF reports; and
• Python 3 with wxPython and matplotlib for the GUI.

Adding the bin folder to the system path is convenient but not required. This directory contains all binaries and supporting libraries required to run Seedless. For first tests, an explicit or relative path to the executable files is often easier to diagnose.

Installation of gnuplot and pdflatex depends on the operating system. Instructions for macOS, Linux and Windows are given.

3.2 Platform binaries

seedless_Darwin_arm 
seedless_Windows_x86_64.exe 
seedless_Linux_x86_64

====================================
 Welcome to Seedless version 1.3
====================================
 Fast optimal control pulses.
------------------------------------
                    C.Buchanan
                    G.Bhole
                    J.Jones
                    A.Baldwin
      (c) University of Oxford
------------------------------------
 Special thanks to G.Buo and S. Lim
------------------------------------

You have identified the correct binary if running it from a terminal produces the banner shown above. If you see an error, there is a compatibility problem. Work through the troubleshooting steps below and get in touch if the problem persists.

3.3 macOS

Homebrew can install reporting dependencies:

brew install gnuplot 
brew install basictex

If you intend to use LaTeX, you may prefer a more complete distribution (ca. 7 Gb) rather than the basic (130 Mb) using

brew install mactex

Open a new terminal after installation, then test gnuplot and pdflatex. If you get a message from the programs, the installation was successful. Run one of the supplied demonstrations using the wrapper or an explicit binary path, for example:

python3 ../../bin/seedlessRun 
../../bin/seedless_Darwin_arm seedless.C

3.4 Linux

Install gnuplot and a LaTeX distribution using the system package manager. On Ubuntu or Debian-derived systems, a typical starting point is:

sudo apt-get update 
sudo apt-get install gnuplot texlive-latex-base texlive-latex-extra

Open a new terminal after installation, then test gnuplot and pdflatex. If you get a message from the programs, the installation was successful. Then run the Seedless wrapper or binary explicitly:

python3 ../../bin/seedlessRun 
../../bin/seedless_Linux_x86_64 seedless.C

If you want to run Seedless from any folder, add the Seedless bin directory to your shell path. For example, in bash you would add a line like this to ~/.bashrc, replacing the path with the actual location of your Seedless folder:

export PATH="PATH:/path/to/Seedless/bin"

Then open a new terminal or reload the file with source ~/.bashrc.

Older Linux distributions might fail to run seedless_Linux_x86_64, reporting that libmvec is not present. We have included an additional binary seedless_Linux_x86_64_OLD. If you encounter this error, go to the bin folder and run

cp ./seedless_Linux_x86_64_OLD ./seedless_Linux_x86_64

This replaces the default binary with one compiled without libmvec. Thanks to Eiso Ab for figuring this out.

3.5 Windows setup

On Windows, install Seedless, Gnuplot, and a LaTeX distribution that provides pdflatex.

Install Gnuplot from SourceForge: https://sourceforge.net/projects/gnuplot/files/gnuplot/

Install pdfLaTeX using either TeXLive or MiKTeX.

After installation, check that the following folders are on your Windows Path. The exact locations will depend on where you installed each program:

• the Gnuplot binary folder, for example C:\Program Files\gnuplot\bin;
• the pdfLaTeX binary folder, for example C:\texlive\2025\bin\Windows;
• the Seedless bin folder, for example C:\path\to\Seedless\bin.

To edit your user path on Windows:

1.

Open the Windows Start menu and search for Edit environment variables for your account.

2.

Under User variables, select Path and click Edit. If Path does not exist, create it.

3.

Add the Gnuplot bin folder, the LaTeX bin folder, and the Seedless bin folder.

4.

Save the changes and open a new terminal window.

5.

Test the setup by typing gnuplot and pdflatex.

There are two Windows environment-variable editors: one for your user account and one for system-wide variables. Editing the user account path is sufficient, which usually does not require administrator access.

Open a new terminal after installation, then test gnuplot and pdflatex. If you get a message from the programs, the installation and setting of the path was successful. To run Seedless directly on Windows, open a terminal in the folder containing the input file and use:

seedless_Windows_x86_64.exe seedless.C

if the Seedless bin folder is on the path. Otherwise, call it using the full or relative path to the executable.

To use seedlessRun on Windows, Python must also be installed and visible on the path. Then run:

python seedlessRun

from a suitable folder, or call seedlessRun using its full path.

3.6 Installing the GUI

Install the GUI dependencies into the same Python environment that launches seedless_gui. This is the same on all platforms:

python3 -m pip install --upgrade pip 
python3 -m pip install --upgrade matplotlib wxPython 
python3 -c "mport wx; import matplotlib; print(wx.version())"/span>

If the final step gives an error, then wxPython has not installed correctly. The companion GUI manual begins after this import test and the platform binary test succeed. Launch the GUI with

seedless_gui

Or supply the path if the bin folder is not in the path.

4 Running Seedless

There are three options. The following examples assume that the bin directory is on your system path. If it isn’t, you will need to type in the path before the commands.

seedlessRun

recursively locates inputs whose names begin with seedless, runs them in their home folders, and writes a consolidated report. It is convenient for demo suites and batches.

For development and debugging, it is often preferable to invoke the binary directly. This gives the clearest terminal diagnostics while developing a new pulse:

seedless_Platform_Chipset inputfile

Chosen from the list

seedless_Darwin_arm 
seedless_Windows_x86_64.exe 
seedless_Linux_x86_64

Alternatively, launch the GUI using

seedless_gui

seedlessRun and seedless_gui are executable python scripts. You may need to make them executable with e.g. chmod +x seedlessRun (macOS and Linux). You can also launch them with

python3 seedlessRun
python3 seedless_gui

4.1 Summary reports

The header command MakeSummary enables a PDF report. Report generation requires gnuplot and pdflatex. Test both from the same terminal or environment used to run Seedless before changing the pulse input.

4.2 First-run checklist

1.

Are you in the directory containing the intended input, or have you supplied its path?

2.

Does the selected binary match the operating system and processor?

3.

Is the binary executable and permitted by the operating system?

4.

If using the wrapper, does the same Python interpreter run it?

5.

If using MakeSummary, can the same environment run gnuplot and pdflatex?

6.

If using the GUI, can the same Python import wx and matplotlib?

If you run into trouble, the most likely cause is the installation. Find a friendly local IT person, ask Mr. Google or your favourite AI for help.

5 Your first Seedless pulse: an HNCO carbon excitation

The quickest way to learn Seedless is not to begin with a blank input file, but with a calculation that is already known to work. Throughout both the GUI and technical manuals we therefore use the same canonical example: an 80 μs ¹³C excitation pulse for an HNCO experiment. The pulse performs three different tasks simultaneously:

• Excite CO magnetisation (I_z →−I_y).
• Leave Cα magnetisation unchanged (I_z → I_z).
• Leave Cβ magnetisation unchanged (I_z → I_z).

Although relatively simple, this example illustrates nearly every important idea in Seedless: multiple chemical-shift bands, different restraints in different regions, RF inhomogeneity, finite-element optimisation and validation with a summary report.

5.1 Before looking at the input file

Before writing a single line of syntax, it is helpful to think like a pulse designer. Ask four questions.

1.

What experiment is this pulse for?

2.

Which chemical-shift regions matter?

3.

What transformation is required in each region?

4.

What RF field and duration are experimentally realistic?

For this HNCO example the answers are straightforward.

The pulse belongs to a triple-resonance experiment. Only three carbon bands are important (CO, Cα, and Cβ). CO must be excited, whereas the remaining two bands should behave as spectators. A pulse duration of 80 μs and a maximum RF field of 17.6 kHz are realistic on many modern probes and provide an excellent demonstration problem.

Only after these experimental decisions have been made do we describe them using Seedless syntax.

5.2 The complete input file

ncpus 8 
frq 150 
outPath ./HNCO/C/ 
maxIter 5000 
MakeSummary 
Bruker 
RF: 
  0.93 0.25 
  1.00 0.50 
  1.05 0.25 
Plot: 
  P 0 200 360 
SpinSystem: 
  CO 165 185 96 
  CA 40 78 96 
  CB 8 40 96 
Carriers: 
  176 
wmH: 
  17605 
Durations: 
  80E-6 80 
Targets: 
  Iz -Iy , Iz Iz , Iz Iz

Rather than trying to memorise the individual keywords, read the file from top to bottom as a description of the experiment.

Header:

defines the spectrometer, output files and optimisation.

RF:

specifies the RF inhomogeneity distribution.

Plot:

defines the dense validation grid used after optimisation.

SpinSystem:

defines the three chemical-shift bands.

Carriers:

places the RF carrier at 176 ppm.

wmH:

sets the maximum RF field.

Durations:

specifies the pulse duration and number of finite elements.

Targets:

specifies the desired transformation in each band.

Notice that the input file never tells Seedless how to produce the pulse. Instead it describes what the pulse should achieve. The optimiser is responsible for finding a pulse that satisfies those constraints.

5.3 Running the calculation

While learning Seedless, we recommend running the platform binary directly, for example

../../bin/seedless_Darwin_arm seedless.C

or the corresponding Linux or Windows executable. The GUI writes exactly the same input file before launching the calculation. Understanding this relationship between the GUI and the underlying input file makes it much easier to move confidently between the two interfaces.

5.4 What should you expect?

The exact pulse phases differ slightly between computers because the optimisation begins from random initial conditions. Do not expect the pulse shape itself neccessarily to be identical. Instead check that

• the pulse duration is 80 μs;
• the carrier is 176 ppm;
• the three bands are CO, CA and CB;
• the requested targets are reproduced;
• the final infidelity is approximately 2.7 × 10⁻³.

If these points agree with the supplied example then your installation is working correctly. The next section explains how to interpret the summary report and assess whether a pulse is suitable for experimental use.

6 Evaluating a pulse: how to read a Seedless report

If MakeSummary is included in the input file, and both gnuplot and pdflatex are available, Seedless produces a PDF report summarising both the optimisation and the behaviour of the final pulse. The report is much more than a record of the calculation. It is the primary tool for deciding whether a pulse is ready for experimental use. An experienced pulse designer rarely studies the report from top to bottom. Instead, it is best viewed as a sequence of diagnostic questions.

A systematic way to inspect a report

Whenever you calculate a new pulse, work through the following checklist.

1.

Did I calculate the pulse I intended?

2.

Does the pulse perform the requested transformation?

3.

Does it work between optimisation points?

4.

Did the optimiser genuinely converge?

5.

Would I use this pulse on my spectrometer?

Working through the report in this order usually identifies problems much more quickly than looking only at the final infidelity.

6.1 Step 1: Check the calculation

Begin with the summary at the top of the report. Confirm that

• the spectrometer frequency is correct;
• the carrier frequency is correct;
• the maximum RF field is correct;
• the pulse duration and number of finite elements are correct;
• the chemical-shift bands match the intended experiment;
• the requested targets are listed correctly.

Many apparently poor optimisations are simply the result of calculations performed using incorrect input parameters.

6.2 Step 2: Examine the rotation plots

The rotation plots are the most important part of the report. Each panel begins with magnetisation aligned along one of the Cartesian axes (I_x, I_y or I_z) and shows where that magnetisation finishes as a function of chemical shift. Remember that only restrained transformations are expected to look simple. For the HNCO example the targets are

Therefore the I_z plot is the principal figure of merit. The behaviour of magnetisation that starts along I_x or I_y was never restrained and may appear complicated. This is entirely normal for a state-to-state pulse. By contrast, a universal 90_x pulse should show the expected behaviour for all three starting axes.

6.3 Step 3: Look between optimisation points

Seedless optimises only the frequencies supplied in the SpinSystem: section. The plotted report is evaluated on a denser plotting grid to make sure performance is good for all frequencies within the band. Inspect the Rotation plots carefully.

• Are they smooth?
• Are there oscillations?
• Are there narrow failures between optimisation points?
• Are the transition regions reasonable?

If not, increase the optimisation sampling, perhaps make the pulse duration longer, and repeat the calculation.

Why this matters: A pulse that performs perfectly at optimisation points can still perform poorly between them.

6.4 Step 4: Read the convergence plot

The convergence plot shows the infidelity and gradient as a function of iteration. In this case, the pulse met its ‘true’ convergence after 1080 iterations. Reaching this point required 1130 calls to the expensive ‘compute infidelity and gradients’ function.

During the first few hundred iterations the infidelity typically decreases rapidly. Thereafter the curve begins to plateau. The optimiser, however, continues refining the pulse, often smoothing the waveform while making progressively smaller improvements to the cost function. The gradient norm, |g|, typically decreases approximately exponentially throughout the optimisation.

A convergence curve that has the infidelity still falling steeply usually indicates that the optimisation was stopped too early. A flat infidelity curve may indicate

• successful convergence;
• a difficult local minimum;
• a pulse limited by duration or RF power.

6.5 Step 5: Decide whether the pulse is practical

Finally, ask whether you would actually use this pulse. Consider

• Is the RF field realistic?
• Is the duration acceptable?
• Does the duty cycle satisfy the probe limits?
• Is the output format correct for the spectrometer?
• Does the pulse solve the experimental problem?

Only after answering these questions does it become meaningful to compare infidelity values between different pulses.

When is a pulse good enough?

There is no universal numerical threshold. For many applications when considering the infidelity

These values are only guidelines. Transition bands are intrinsically difficult. If two different restraints are required close together in frequency compared with the inverse pulse length then the behaviour at the boundary will be hard to control. A relatively high overall infidelity may simply reflect a difficult transition region, the pulse may still perform well in the bands that matter experimentally. Similarly, water-miss pulses often produce larger infidelities while still giving reasonable experimental performance reflecting the challenge of reconciling conflicting restraints.

Ultimately, the experiment is the final judge. In the words of Lewis Kay,

The spectrometer never lies.

If you get increased sensitivity or better selectivity in a spectrum, you have a good pulse.

The next chapter describes how to improve a pulse systematically once the report has identified its strengths and weaknesses.

7 Designing a new pulse

Designing a pulse is fundamentally an engineering problem. Before writing a Seedless input file, you need to decide exactly what the pulse must do, which compromises are acceptable, and what limitations are imposed by the spectrometer. Every successful Seedless calculation begins by answering four questions:

1.

Which chemical-shift region(s) matter?

2.

What transformation is required in each region?

3.

What RF power and pulse duration are experimentally realistic?

4.

How densely should the optimisation and validation grids sample the problem?

Once these questions have been answered, the Seedless syntax simply becomes a way of describing those decisions. The detailed syntax is collected later in Section x1-570001010.

A practical workflow

When designing a new pulse we recommend the following order:

1.

Decide where the pulse sits within the pulse sequence.

2.

Decide which chemical-shift bands require control.

3.

Decide the simplest transformation required in each band.

4.

Set realistic RF limits from the spectrometer.

5.

Choose an initial pulse duration.

6.

Optimise using the default phase-only settings.

7.

Inspect the report and refine the design.

A useful principle is to change only one design variable at a time. If the pulse is too long, reduce the duration. If the quality is poor, increase the duration and B₁. If the pulse is still unsatisfactory, reconsider whether the requested restraints are stricter than the experiment actually requires.

7.1 Setting up the virtual spectrometer

The virtual spectrometer describes the experimental environment in which the pulse will operate. The aim is not to reproduce every detail of the hardware, but to capture the quantities that determine pulse performance. Modern NMR spectrometers generally reproduce these in silico simulations remarkably well, particularly when the finite-element duration is several hundred nanoseconds or longer.

7.1.1 Central RF field strength

The most important experimental parameter is the calibrated RF field. Measure the 90^∘ pulse length t₉₀ for the nucleus of interest and calculate

Use the highest RF field that your probe can safely sustain for the intended pulse duration. Modern probes are often capable of operating at their maximum calibrated field for several hundred microseconds. If the desired pulse requires a substantially longer duration, reduce the RF field so that the duty cycle remains within the manufacturer’s recommendations.

Corresponding syntax: wmH: (Section x1-8100010.4.510.4.5).

7.1.2 RF field inhomogeneity

Real samples experience a distribution of RF fields rather than a single value. Seedless therefore optimises the average performance across a distribution of relative RF amplitudes.

A simple three-point model is usually an excellent starting point. It improves robustness without making the optimisation unnecessarily expensive. The B₁ inhomogeneity can be measured by Fourier transforming the nutation curve or visualised using an imaging experiment [?].

Corresponding syntax: RF: (Section x1-7700010.4.110.4.1).

7.1.3 Pulse duration and finite elements

A shaped pulse is represented as many short hard pulses (finite elements). Increasing the number of finite elements allows increasingly complex pulse shapes, but also increases optimisation time and makes the pulse more sensitive to hardware transients. For most liquid-state applications, element lengths of roughly 1–2 μs provide an excellent starting point.

To estimate the total duration (T), the product B₁T provides a useful guide. Pulses created with the same restraints will often have a similar infidelity for a range of durations provided the product stays constant. As a useful rule of thumb, B₁T >10 usually gives the optimiser sufficient freedom to satisfy the required controls.

Corresponding syntax: Durations: (Section x1-8200010.4.610.4.6).

7.1.4 Validation grid

The optimisation grid defines the frequencies used while designing the pulse. The plotting grid is different: it is a validation grid used to test the finished pulse between optimisation points.

Always validate on a denser grid than was used for optimisation.

Corresponding syntax: Plot: (Section x1-7800010.4.210.4.2).

7.2 Choosing the pulse restraints

The most important design decision is not the optimiser, but the restraint. Always ask: what does the experiment actually require?

If only one initial state is ever present experimentally, there is usually no advantage in demanding a full unitary rotation and a state-to-state pulse can be used instead. As this is a less demanding pulse, it can be shorter.

Universal: should be reserved for pulses that must handle many different coherence pathways and starting states.

State-to-state: if the pulse sequence only needs a single transform. Requires less time/power than universal.

XYcite: a special case of state-to-state transfer. They move magnetisation into the transverse plane with uncontrolled phase. These pulses are often very short, but the phase is not ordered. These can be used in symmetric pairs to compensate for variable evolution with frequency (ppm).

Evolution: these control the duration for which chemical shift and scalar coupling are active in a pre and post evolution periods that flank a ‘zero time’ central rotation[?]. There are state-to-state and unitary versions of these pulses, which are relatively demanding.

The following table gives some typical situations, and examples can be found in the demo.

As a worked example, here is the pulse selection logic for a sensitivity enhanced HSQC.

7.2.1 Evolution-controlled pulse creation

Some experiments need the pulse to do more than produce the right final state; they also need the pulse to control how much chemical-shift and weak-scalar coupling evolution takes place during the pulse[?]. In Seedless these are evolution-controlled or schematic pulses, and they sit naturally alongside the universal and state-to-state restraints above. The pre- and post- fractional evolution periods need to be specified.

There are two main forms.

• Unitary evolution-controlled pulses specify a full rotation together with an effective pre-evolution and post-evolution. Common examples are a90xb where the fractional pre and post evolution delays are set with evAlpha and evBeta, and using 180x with the REBURP flag, an evolution controlled refocusing 180 can be created where evAlpha sets the evolution fraction, and evBeta should be set to zero (section Section x1-520009.59.5).
• State-to-state evolution-controlled pulses specify a transfer together with a chosen amount of effective evolution, for example Iz -0.5OIy (section 9.5). Here the ‘pre’ evolution delay is uncontrolled, but the ‘post’ fractional evolution delay is explicitly fixed to 0.5.

When using these modes, the later schematic-analysis keywords, EVOLVE and HALF can be used to verify if the pulse behaves as required.

Corresponding syntax: Targets: (Section x1-8300010.4.710.4.7), and the schematic-analysis keywords in Section x1-7000010.2.1110.2.11. These include a detailed custom syntax for supplying restraints both state-to-state and universal with and without evolution control in a very general form.

7.3 Optimisation

For all routine calculations we recommend constant-amplitude, phase-only optimisation. The default settings for the optimiser are typically excellent. If performance is poor, re-consider your design. Instead, first reconsider the

• pulse duration,
• RF field,
• restraint type,
• chemical-shift sampling.

It is helpful to set maxIter to something relatively small, ca. 10³ that gives a quick computation, letting you get close to the smallest possible infidelity, so you can inspect the results. A setting of 10⁵ is typically required to get to the default convergence (difference in infidelity between iterations of 𝜖 = 10⁻¹⁰). This is not often necessary, and simply a low infidelity is sufficient for excellent performance on the spectrometer.

We have included modes to convert phase-only to amplitude/phase modulated pulses which can lower the overall integrated B₁ (section Section x1-550009.89.8) [?].

7.4 When is a pulse good enough?

Do not judge a pulse from the final infidelity alone. Instead work through the report in the following order:

1.

Are the requested inputs correct?

2.

Do the rotation plots behave correctly?

3.

Is the interpolation smooth?

4.

Has the optimisation converged?

5.

Is the pulse practical on the spectrometer?

6.

Does the experiment produce the desired sensitivity?

An infidelity near 10⁻⁴ is excellent for many applications, while 10⁻³ is often entirely satisfactory. Ultimately the experimental result is the final judge. Remember the words of Lewis Kay:

“The spectrometer never lies.”

8 Learning Seedless: a recommended pathway

Once you have calculated the first demonstration pulse successfully, the next objective is not to learn every Seedless keyword. Instead, the goal is to develop an intuition for pulse design. The supplied demonstrations are arranged so that each introduces one or two new ideas while reinforcing concepts encountered earlier.

This chapter suggests a progression that has worked well for new users. By changing only one aspect of a calculation at a time, it becomes much easier to understand why a pulse improves or deteriorates.

8.1 Stage 1: Reproduce a known pulse

Begin by calculating the canonical HNCO pulse described in Section x1-1400055. Do not modify the input file. Your objective is simply to confirm that

• the program runs successfully;
• the pulse and PDF report are produced;
• the calculated infidelity is similar to the supplied example;
• you can interpret the report using the workflow in Section x1-1900066.

8.2 Stage 2: Change one parameter

Copy the example input and modify a single quantity. Useful first experiments include

• increasing the pulse duration;
• decreasing the pulse duration;
• changing the carrier frequency;
• increasing the maximum RF field;
• reducing the number of finite elements.

After each change, inspect the report and ask why the pulse improved or performed worse. The objective is to build intuition rather than to produce an optimal pulse.

8.3 Stage 3: Modify the restraints

Once you are comfortable changing experimental parameters, begin changing what the pulse is actually asked to do. For example

• replace a state-to-state restraint with a universal rotation;
• alter the bandwidth of one spin-system region;
• add or remove a chemical-shift band;
• compare state-to-state and XYcite targets.

These exercises quickly demonstrate that the requested transformation often has a much greater influence on pulse quality than optimiser settings.

8.4 Stage 4: Design a pulse from scratch

After working through several supplied examples you should begin creating your own pulses.

A useful checklist is

1.

Identify the experiment.

2.

Identify the important chemical-shift bands.

3.

Choose the simplest suitable restraint.

4.

Set realistic RF limits.

5.

Choose an initial duration.

6.

Optimise using the default settings.

7.

Evaluate the report.

8.

Refine the design.

This is the same design philosophy discussed in Section x1-2800077.

8.5 Stage 5: Explore advanced features

Only after the basic workflow has become familiar is it worth exploring the advanced optimisation modes described later in this manual.

Examples include

• Horserace mode for choosing favourable random seeds;
• Grid searches for selecting RF field and duration;
• Evolution-controlled pulses;
• Fourier and power-series optimisation;
• Amplitude optimisation.

These tools are extremely useful, but they are intended to address specific design problems rather than replace good pulse-design practice.

The supplied demonstrations

The demonstration directory provides examples covering a wide range of applications.

Rather than working through these in numerical order, follow the learning stages described above. Each example introduces a new design concept while reinforcing the previous ones.

After the first example works, run the full supplied demo suite as a regression test. To do this, go to the demo folder and run RunMe.sh. This will loop over all examples creating 36 pulses, and generate a report summarising details and timings.

Calculation times vary strongly with hardware, compiler, CPU count, and program version, so compare the expected files and broad score ranges rather than exact timings.

Key ideas

Before moving on to the advanced chapters, you should be comfortable with the following principles.

• Start from a working example.
• Change one variable at a time.
• Design the pulse before adjusting the optimiser.
• Judge a pulse from its report, not its infidelity alone.
• Always validate the pulse experimentally.

Once these ideas become familiar, the advanced optimisation modes in the following chapters become much easier to understand because they solve specific design problems rather than introducing entirely new concepts.

9 Advanced optimisation and analysis modes

This section brings together features that become useful once the basic input-file workflow is familiar. Some are routine pulse-design tools, others are primarily diagnostic, and several occupy the space between. The boundaries are not rigid: a single calculation may move naturally from pulse design to analysis, conversion, and back again. Table 1 provides a practical guide to when each feature is most useful.

9.1 Horserace mode: choosing a good random seed

In some examples, changing the random seed can produce slightly different pulses. The spread between the best and worst final infidelities is usually modest, often around a factor of three. This mostly occurs for pulses with already low infidelities, below about 10⁻³, where the differences are unlikely to create visible sensitivity differences in spectra. Even so, it is undesirable for the result to depend noticeably on the seed.

A practical test is to run with Horsey set to 100, with HorseyIter set to 1000 or some other large number sufficient to come close to convergence. This will start 100 independent calculations that proceed for the specified number of iterations, with each starting from a different random seed. A histogram is produced in the report that shows the distribution of solutions. If there is a spread of values, the optimiser has a risk of finding false minima, and the problem needs a horserace. Here, only the seed that led to the best performance is retained and run to completion. Add the following lines to the header of the input file:

Horsey 50
HorseyIter 100
HorseyBins 10

The report adds a plot of infidelity versus iteration for the different seeds, together with a histogram showing the spread of final infidelity values from the race.

This makes the optimisation extremely robust. For example, if 4 out of 100 random seeds are poor, the probability that all H horses are poor is approximately (0.04)^H. With H = 50, this is astronomically small with a failure rate of 1 computation in 10⁷. In practice, Horsey 10 with HorseyIter 20 is often enough; Horsey 50 with HorseyIter 100 is a more conservative setting.

The BIP example illustrates the output. The left plot shows that the early trajectories for different seeds follow different paths, and the best seed may not be obvious until convergence begins to stabilise. In this example, seed 39 was best, but that was not apparent until about iteration 50. The right plot shows the distribution of final infidelities. For this pulse, omitting horserace mode can lead to final infidelities that vary by about a factor of three. The best pulses for this problem have time symmetry. By formally imposing this symmetry with the SYM flag in the header, the false positive rate is dramatically reduced.

The BIP demonstration includes an example of horserace mode.

9.2 Grid search: choosing B₁, duration, and finite-element length

When designing a new pulse, a common first question is: what RF field strength, pulse duration, and finite-element length are needed to reach the desired infidelity? Grid search is intended to answer this practical question before investing time in a full optimisation.

A grid search is enabled in the header of the input file. For example:

Grid Iter 1000
Grid Show 5
Grid T 5 50E-6 3E-3
Grid dt list  500E-9 1E-6 2E-6
Grid B1 list 20000  10000 5000

The three-number form, such as Grid T 5 50E-6 3E-3, is interpreted as the number of points, the minimum value, and the maximum value. The keyword list means that all following values are read literally as the set to test.

The summary report shows optimisation trajectories and summary plots, including infidelity versus duration and infidelity versus B₁T. RF field is indicated by colour, while finite-element length is indicated by marker type. If the trajectories are still decreasing strongly at the end of the grid run, the grid calculation has not converged and Grid Iter should be increased.

A useful rule of thumb is that performance often begins to improve much more slowly once B₁T is greater than about 10. In many examples, the final infidelity follows an approximately linear trend in log–log space:

log(final infidelity) = a log (B1.T) + b
final infidelity = c (B1.T)^a

The constants are application dependent. The practical implication is that decreasing B₁ can often be compensated by increasing the duration T, provided the product B₁T remains similar. This is useful when the maximum RF field is limited by the probe or by sample heating.

The BIP demonstration below tests five durations between 50 μs and 3 ms, three finite-element durations, and three B₁ values.

The left plot shows that higher B₁ and longer duration improve the pulse. The right plot shows that, for the 10 and 20 kHz fields, the points largely fall on a line when B₁T is plotted against infidelity in log–log space. If the target is an infidelity below 10⁻⁴, the example suggests that B₁T ≈ 10 is sufficient: approximately 500 μs at 20 kHz, 1 ms at 10 kHz, or 2 ms at 5 kHz. In this case, finite-element durations of 500 ns, 1 μs, and 2 μs give similar results.

A second type of grid search explores B₁T and finite-element flip angle directly:

Grid Iter 1000
Grid Show 5
Grid Nmax 50000
Grid B1 list 10 100 1000 10000
Grid B1T log 20 3 100
Grid flip 1 5 10

Here, Grid Nmax sets an upper limit on the number of finite elements. Grid points exceeding that limit are skipped. The Grid B1T and Grid flip commands make the grid search loop over specified values of B₁T and finite-element flip angle. This often gives intuitive plots of pulse performance.

The example below is for a universal 180_x pulse with time-reversal symmetry, designed over ±10 ppm for protons at a 1 GHz Larmor frequency. It compares finite-element flip angles of 1^∘, 5^∘, and 10^∘, RF fields of 10, 100, 1000, and 10,000 Hz, and B₁T values from 3 to 50.

For B₁ = 10 kHz, the pulses are good from B₁T = 3 upwards. At 1 kHz, the pulses are good provided B₁T >30. At 100 Hz, excellent pulses can still be made if the flip angle is small, for example 1^∘. At 10 Hz, the pulses are poor.

To design a final pulse with infidelity below 10⁻³, this grid suggests B₁T ≈ 30 for fields below 10 kHz, or about 8 at 10 kHz. Thus, a 1 kHz pulse with B₁T = 30 requires a 30 ms duration, whereas a 10 kHz pulse with B₁T = 4 requires 400 μs. The finite-element duration can be estimated from the finite-element flip angle:

(1)

For a 10^∘ finite-element flip angle, this gives approximately 27 μs at 1 kHz and 2.7 μs at 10 kHz. The number of finite elements is

(2)

which gives 1080 and 144 elements for the 1 and 10 kHz pulses respectively. These grid calculations are run only to 1000 iterations, so the final full optimisation is expected to improve on these values.

The interpretation of a plot like this is straightforward. Choose a target infidelity, read off the approximate B₁T value required at the available RF field, and then convert that into a pulse duration. The grid.bip demo contains an example of grid search. Run it with:

seedless_{Platform}_{Chipset} grid.bip

For example, on an Apple silicon Mac:

seedless_Darwin_arm grid.bip

This calculation is fairly lengthy, typically on the order of 10 minutes. In normal use, we usually try a condition, inspect the result, and then adjust duration and B₁ to tune the pulse.

9.3 Jiggle mode: basin hopping after optimisation

Jiggle mode is a basin-hopping strategy intended to help difficult optimisations escape local minima. In our experience, this mode is rarely necessary, particularly for phase-only optimisation. It is retained for completeness rather than as a routine pulse-design tool. It is not included in the GUI and is usually not the first feature to try.

Enable it with commands such as:

JIGGLE                # engage jiggling mode after BFGS
JiggleHeatMax 0.01    # starting perturbation size
JiggleHeatMin 0.0005  # final perturbation size
JiggleHeatFac 2       # factor used to reduce the perturbation size
JigglePrint 50        # number of jiggles between reports
JiggleMax 500         # number of unsuccessful jiggles before reducing heat
JiggleIter 500        # optimisation iterations for each jiggle

A normal optimisation is performed first, optionally including a horserace. The pulse parameters are then perturbed by multiplying them by random numbers drawn from a Gaussian distribution. The perturbed pulse is optimised, and the new solution is kept only if the infidelity is lower than the previous best value. When JiggleMax attempts have passed without improvement, the perturbation size is reduced by JiggleHeatFac. The process stops when the perturbation size falls below JiggleHeatMin.

A summary.pdf report is generated every JigglePrint jiggle runs. This allows a long calculation to be interrupted while preserving and characterising the best solution found so far.

9.4 Amplitude and simultaneous amplitude/phase optimisation

We recommend phase-only pulses for most routine work. Seedless can also optimise amplitude-only pulses and simultaneous amplitude/phase-modulated pulses, but these calculations are generally less robust. We have not found an NMR example where a fully amplitude/phase-optimised pulse beats a phase-only pulse at the same peak B₁ in a way that justifies the extra complexity.

Amplitude-only optimisation allows positive and negative amplitudes, equivalent to phases of 0^∘ and 180^∘, similar in spirit to BURP and Q pulses. Simultaneous amplitude/phase optimisation optimises amplitudes and phases simultaneously. In practice, both are more sensitive to the initial conditions than phase-only optimisation.

At the same average B₁, amplitude-only and phase-only pulses often have similar infidelities, while an amplitude/phase-optimised pulse can be better. However, a phase-only pulse running at constant maximum amplitude will usually match or outperform an amplitude/phase pulse that only reaches peak B₁ for part of its duration. On modern NMR hardware, running the amplifier at its maximum value for a few milliseconds is typically acceptable.

For amplitude-only optimisation use the following commands:

NoOptPha
OptAmp
initAmp rand
initPha zero

Use OptAmp without NoOptPha for simultaneous amplitude and phase optimisation.

For amplitude optimisation, it is often helpful to reduce the memory in the lBFGS optimiser:

hessianM 6

The default value is 300, which works well for phase-only pulses. A smaller value, such as 6, is often better when amplitudes are being optimised.

For amplitude optimisation it is often necessary to impose penalty functions to prevent the amplitude rising above the maximum value selected, and it is sometimes desirable to make the amplitudes vary smoothly.

The amplitude cutoff penalty has the form α(|Amp|− 1)² for normalised amplitudes whose absolute value is greater than 1. The smoothing penalty is based on a spectral differential method. In the final report, Seedless tabulates the contribution from the pulse infidelity, the amplitude cutoff penalty, and the smoothing penalty. This is important: a pulse can be physically good, but receive a poor overall score if the smoothing penalty dominates. For this reason, it is usually better to make alphaS extremely small unless smoothing is specifically required.

Amplitude optimisations are less robust than phase-only optimisations and benefit from a larger horserace.

The algebra behind the miss-restraint speedup is useful for implementation, but it is not essential for routine pulse design. The derivation is retained in Appendix 10.4.9. The practical message is simply that the backwards accumulation of partial sums makes the miss-restraint calculations much faster.

9.5 Evolution-controlled pulses and schematic evolution analysis

Evolution-controlled pulses are analysed using the schematic description introduced in the recent work on evolution-controlled shaped pulses [?]. The key idea is that, at each frequency of interest, the net effect of a shaped pulse can be decomposed into three parts, an effective pre-evolution delay, a central “zero-time” unitary rotation, and an effective post-evolution delay. In this notation, the pulse is not treated simply as a finite-duration black box. Instead, Seedless asks how much chemical-shift evolution the pulse behaves as if it has placed before and after the central rotation.

These pulse types are best understood first as a design choice and only then as an analysis tool. In practice, the created pulses fall into two broad groups: unitary evolution-controlled pulses such as a90xb, and 180x used with the REBURP flag, and state-to-state evolution-controlled pulses such as Iz -0.5OIy.

The REBURP mode applies an a90xb restraint at the halfway point of the pulse with pre and post fractional evolution parameters set by evAlpha and evBeta. A further 180x restraint is applied at the full time of the pulse. In this way, an evolution controlled 180^∘ pulse can be created where scalar coupling and chemical shift evolve in the front and back halves of the pulse. This mode behaves much like the original REBURP pulse [?].

The schematic-analysis keywords EVOLVE (and HALF for 180^o pulses) show whether a created pulse really behaves in the intended way.

This analysis is useful when the timing of evolution during the pulse matters. A conventional shaped pulse may give a good final rotation or state-to-state transfer, but still introduce frequency-dependent effective delays (particularly when the pulse duration is long enough to allow scalar coupling to significantly evolve). Those delays can be important in pulse sequences that rely on accurate refocusing or controlled J evolution. The EVOLVE report helps diagnose this behaviour by showing whether the effective pre-evolution delay, zero-time rotation, and post-evolution delay are stable across the frequency band.

A practical way to read the output is:

• Check the central unitary rotation first. This should match the intended operation, such as a 90^∘ or 180^∘ rotation.
• Check whether the effective pre- and post-evolution delays are approximately constant across the useful bandwidth.
• For refocusing pulses, check the halfway analysis using HALF, because the full-pulse Euler-angle description can become poorly conditioned for 180^∘ rotations.
• If the delays vary strongly with offset, the pulse may still work as a simple rotation, but may be unsuitable in experiments where evolution during the pulse must be controlled.

The same idea also underlies the more specialised modes below. REBURP adds midpoint restraints designed to improve evolution control in refocusing pulses. State-to-state evolution-control targets, such as Iz -0.5OIy, use related notation described below to ask for a transfer that includes a specified effective evolution period.

An example EVOLVE output for a recently created a90x (evAlpha=0.95, evBeta=0, target a90xb) pulse is

The first plot shows the “pre” evolution delay inside the optimised band is the required 0.95 of the total duration. The “post” evolution delay, as required is zero. The second plot shows the central zero-time rotation versus frequency. During the optimised band the pulse is doing a perfect 90x. Outside of the optimised band, performance is uncontrolled.

When analysing 180^∘ pulses, use the HALF flag. The analysis splits the pulse into two, and shows the pre, post and central evolution periods, and the central-zero-time unitary rotation of the front and back halves. For a good refocusing 180^∘ pulse you want the middle delay to be zero, and the central unitaries to be 90^∘ rotations around the same axis.

9.6 Optimisations in Fourier or power-series representations

Seedless can optimise pulses whose amplitudes or phases are represented by a series, similar to the original BURP pulses. This feature was added following requests from Alex Hansen. In our tests, phase-only GRAPE pulses usually outperform these lower-dimensional series descriptions, but the option is useful for exploring smooth pulse forms and for comparison with traditional shaped pulses.

For a Fourier representation, the phase can be written as:

(3)

To use this mode, define the number of parameters to optimise in the Fourier series. For F Fourier terms, the number of parameters is P = 2F + 1:

SERIES FOURIER 5

Assuming no transient response, the derivatives are:

(4)

where P_j is the relevant Fourier coefficient. With k numbered from 0 to N − 1:

(5)

Seedless already contains the values of 2Tr(B_iC_k), so the implementation pre-computes the derivative factors and adds a loop over the Fourier coefficients.

Two useful modifiers are available. If amplitudes are being optimised, SERIES_ZEROEDGES forces the pulse amplitude to start and end at zero by constraining a₀ to be related to the other constants a_k. This removes one parameter from the fit. The command FOURIER_COSONLY ignores all sine coefficients, b_j.

A power-series representation is also available, although there is no obvious physical reason to prefer it. The expansion is taken about the centre of the pulse:

(6)

It is enabled with:

SERIES POWER 10

The number specifies the number of parameters. As for the Fourier series, SERIES_ZEROEDGES can be used during amplitude optimisation to force the pulse to start and finish at zero. In tests, power-series pulses are close to, but slightly worse than, Fourier-series pulses with a similar number of parameters.

Overall, the results from series optimisation are not especially encouraging. Phase-only constant-amplitude pulses generally give better fidelity, often by an order of magnitude or more. Series optimisation can also be tricky, and horserace mode may be needed to find a reasonable minimum. Smooth series pulses may still be useful on hardware with a limiting response function, but for most Seedless applications, allowing the optimiser to control all finite elements directly is more effective. In the demo, there is an example where we compute a pulse that looks identical to the EBURP from scratch using this mode.

9.7 Hessian characterisation

The command HESSIANPLOT adds Hessian characterisation to the report. Seedless computes a numerical Hessian matrix from central differences of gradients:

(7)

where g_i(x) is the gradient with respect to parameter i at parameter vector x. The eigenvalues of the real symmetric hessian are then computed and ranked. If all eigenvalues are positive, the point is a true local minimum. If the eigenvalues contain a mixture of positive and negative values, the solution is a saddle point.

The following example is a phase-only pulse designed to perform a band-selective state-to-state transformation I_z →−I_y while preserving I_z → I_z outside the band, similar to an EBURP1. For random initial phases, the hessian contains a mixture of positive and negative eigenvalues:

After optimisation with near-default settings, 𝜖 = 10⁻¹⁰, the pulse converges in about 40,000 steps:

Driving the optimisation harder, using 𝜖 = 10⁻¹⁴, gives convergence in about 200,000 steps:

The final Hessian is positive definite. This analysis can therefore distinguish a true minimum from a saddle point. In this example, the difference in pulse shape and infidelity between the last two cases is tiny.

For phase-only optimisation, Seedless usually gets close to, or reaches, a true minimum. There are exceptions, especially for difficult problems where a small probability of a local minimum remains; horserace mode is useful in those cases. For amplitude and phase optimisation, the solutions often appear to be saddle points. This fits the intuition that the optimiser has multiple similar descent directions involving changes in either amplitude or phase. We therefore recommend phase-only optimisation, followed by conversion to an amplitude/phase pulse only if reduced integrated B₁ is genuinely required. In practice, it does not seem to matter whether the solution is a true minimum or a saddle point, provided the cost function (infidelity) is sufficiently small.

9.8 Amplitude-to-phase and phase-to-amplitude conversion

As part of the phase-only pulse work, Seedless includes two conversion modes that explore the equivalence between phase-only and amplitude/phase pulses. These may be useful when integrated B₁ power must be minimised.

Add AMPtoPHASE to the header to create an additional phase-only version of an amplitude-modulated pulse. This works well with Make mode for traditional pulses such as EBURP, REBURP, and CHIRP. Seedless uses a Trotter–Suzuki mapping that increases the number of finite elements by a factor of 4, following the practical pulse-engineering approach used to avoid unnecessary matrix exponentiation.[?] Each new element uses the maximum supplied amplitude, while preserving the same total pulse duration.

The infidelities of the original amplitude/phase pulse and the converted phase-only pulse are usually similar. If desired, the converted pulse can be read back into Seedless for further optimisation.

The reverse conversion is less direct. When reading in a phase-only pulse, specify PHASEtoAMP, optionally followed by an integer smoothing window. Seedless computes the complex value associated with each finite element, ω₁e^iϕ_i, and applies binomial smoothing. The smoothing window should be odd. A value of 5 gives weights proportional to 1:4:6:4:1.

After conversion, the pulse is read in and a phase-only optimisation is performed with fixed amplitudes. This can reduce the amplitude requirement. The process can be repeated until the B₁ requirement is reduced without significantly compromising infidelity.

For routine NMR work, we have generally not needed to reduce B₁: running at maximum field for a few milliseconds is usually acceptable on modern hardware. In other fields, such as MRI, this may be less true. These conversion modes provide a compromise when lower integrated power is important.

9.9 Multiple optimisers

The original Seedless implementation used liblBFGS from Naoaki Okazaki (link), a faithful C++ implementation based on the original LBFGS algorithm by Jorge Nocedal. LBFGS, BFGS, SR1, and Newton methods are all related quasi-Newton or Newton-type optimisers that use, approximate, or build information about the hessian.

We highly recommend the default but the other optimisers can be selected with:

optimiser liblBFGS # default
optimiser lBFGS
optimiser BFGS
optimiser Newton
optimiser SR1
optimiser Hybrid 15

In our tests, there is usually no reason to use anything other than liblBFGS. BFGS and SR1 tend to take longer and are less able to find good minima. Newton’s method can descend rapidly for favourable initial seeds and may find a good pulse in roughly 10 fewer iterations, but each function call can be more than 100 times slower. Overall, liblBFGS and Newton find similar minima, with liblBFGS being much faster in wall-clock time.

All these methods also require a line search. The optimiser defines a search direction, but a separate decision is needed about how far to move in that direction. Different implementations handle this step differently, and this can affect performance. In our testing, it is hard to beat the behaviour of liblBFGS and the original lBFGS line-search strategy.

10 Detailed syntax reference

This section serves as a reference for editing Seedless input files. It is deliberately more detailed than the introductory examples and is intended for consultation rather than sequential reading. Use it when you want to modify the behaviour of a calculation, add restraints, change the output format, or simulate an existing pulse.

10.1 General input-file rules

• Lines beginning with # are comments and are ignored.
• If a command has several entries on one line, Seedless stops reading that line at #. This lets you add comments after commands.
• Keywords are case sensitive. For example, Bruker and bruker are not the same.
• Seedless currently skips unknown or misspelled keywords without warning. Check spelling carefully if an option appears to have no effect.
• Boolean options default to false. If the keyword is present, it is normally treated as true. Options like NoOptPha handle cases where the default behaviour is the wrong way round.
• In target lines with multiple bands, commas separate the bands. Leave spaces around commas, for example Iz -Iz , Iz Iz , Iz Iz.

A typical input file has this overall structure:

# Header commands first
frq 150
pulseName my_pulse
Bruker
MakeSummary
# Then named sections
RF:
  1.0 1.0
Plot:
  P 0 200 120
SpinSystem:
  CO 165 185 96
Carriers:
  176
wmH:
  17605
Durations:
  130E-6 130
Targets:
  Iz -Iz

10.2 Header commands

Header commands control the global behaviour of the calculation: where output files go, how pulses are named, whether Bruker, Varian or Jeol pulse files are written, how much optimisation is performed, and which optional analysis modes are switched on.

10.2.1 Basic calculation and output settings

10.2.2 Output format and pulse-writing options

10.2.3 Bruker, Varian and Jeol spectrometer formats

Seedless can read and write both Bruker and Varian-style pulse files. The differences are primarily formatting conventions, although there is also an important difference in phase convention. If you are working on a Bruker spectrometer, include the following keyword in the header:

Bruker

This switches Seedless to Bruker conventions for both reading and writing pulses (do not use this if you want Varian and Jeol pulses!). It also sets the Bruker read-in defaults automatically. Use MakeSummary if you want the report plots, and use Bruker shapetool to check how the pulse will be perceived by the spectrometer. If the Seedless report and shapetool disagree, treat shapetool as the hardware-facing reference.

For example, a Bruker-style file has amplitude first and phase second:

100, 0
100, 180
100, 0
100, 180
...

A Varian-style file has phase first and amplitude second:

0,   1023
180, 1023
0,   1023
80,  1023
...

A Jeol-style file has phase second and amplitude third (we do not use the 1st and 4th columns):

1, 0,   100, 0
1, 180, 100, 0
1, 0,   100, 0
1, 180, 100, 0
...

Varian-style input is the default, by virtue of Lewis Kay’s NMR centre being Varian until relatively recently. To write a pulse for direct use on a spectrometer, specify writeVarian, writeBruker or writeJeol. The Bruker keyword sets Bruker read/write conventions and reverses the relevant phase convention for read-in and written pulses.

Seedless uses the following RF Hamiltonian internally, which is also the Varian and Jeol convention:

(8)

The Bruker convention is effectively:

(9)

Here ω is the applied B₁ field in radians per second, and I_x and I_y have their standard meanings. Seedless always performs its internal calculations using Equation 8. When Bruker is set, phases are inverted at read-in and write-out so that Seedless, Bruker hardware, and shapetool behave consistently.

This convention affects the relative sense of rotation in the xy plane compared with intrinsic spin evolution such as chemical shift and J coupling. In experiments such as TROSY, getting these relative signs correct can be crucial. If a sequence does not behave as expected, useful tests are to reverse the target rotation direction and/or add 180^∘ phase-cycle changes at the relevant points in the pulse sequence.

10.2.4 Coarse optimiser settings

The default optimiser settings should be reliable. Increase ncpus to make use of all available processor cores. For final polishing, setting maxIter to a larger number ensures the optimisation continues until convergence.

10.2.5 Fine optimiser settings

These settings control the optimiser used for both the main optimisation and, where relevant, the horserace stage. The default optimiser is libLBFGS, which is recommended. For more information on these see the liblBFGS documentation.

The optimiser is selected with one of the following lines:

optimiser liblBFGS
optimiser Newton
optimiser BFGS
optimiser SR1
optimiser lBFGS
optimiser Hybrid 15

optimiser Hybrid 15 runs 15 iterations of Newton–Raphson optimisation, followed by lBFGS. In our tests, libLBFGS and lBFGS significantly out-perform all the other optimisers. But they are there if you want to play with them. Analytical Hessians are efficiently computed when using the Newton–Raphson scheme.

10.2.6 Printing optimisation progress

10.2.7 Initial conditions and amplitude optimisation

10.2.8 Pulse symmetries and transforms

Formal symmetries can be imposed on the pulse phases. These can help in some cases, but they can also make a pulse worse if the best solution does not have the imposed symmetry.

Broadband inversion pulses (BIPs) often benefit from SYM. If the best solution has a symmetry, the optimiser finds it naturally. If imposing symmetry gives worse performance, remove the symmetry constraint.

10.2.9 Horserace settings

The horserace tests several random seeds for a short optimisation and then continues with the best one. This is useful when the optimisation is sensitive to the initial random phases; see Section x1-480009.19.1.

10.2.10 Grid-search settings

Grid search lets you scan over pulse parameters such as field strength, total duration, or finite-element duration. This mode runs the grid search and then quits; it does not currently run a horserace or random-seed testing as part of the same calculation.

10.2.11 Schematic evolution analysis and pulse creation

For each frequency, Seedless can analyse a pulse as a pre-evolution delay, a central zero-time unitary rotation, and a post-evolution delay.[?] This is the analysis mode used for the evolution-controlled pulses created with the targets discussed in Section x1-520009.59.5. A good evolution-controlled pulse should have these factors roughly constant across the chemical-shift range.

Use HALF when analysing 180^∘ refocusing pulses. The Euler description has a gimbal-locking singularity for 180^∘ pulses, and analysing the pulse halfway through avoids this problem.

10.3 Reading, making, and transforming pulses

10.3.1 Reading an existing pulse

Use Read to read in an existing pulse. This is most often used with NoOpt, so that Seedless simulates the pulse without changing it. If NoOpt is omitted, Seedless will use the read-in pulse as the initial condition for optimisation; this often gives a local minimum, and starting from random phases is usually better.

Before reading a pulse, make sure the amplitude and phase columns are specified correctly. If Bruker is set in the header, the Bruker read-in defaults are set automatically. Otherwise, Seedless defaults to Varian-style input.

The simplest Read command is

Read Gaus1.1000

Options can be added on the same line:

For example, this reads Hello.RF, sets the total duration to 2 ms, and simulates it at a peak B₁ field of 20 kHz:

Read Hello.RF duration 2000 field 20000

Special pulse names are also available. Free inserts a period of free precession for the specified duration. A name of the form HardXXX creates a rectangular pulse with a flip angle of XXX degrees on resonance. You can concatenate as many Read lines as needed.

To convert a phase-only pulse into an amplitude/phase approximation, use:

PHASEtoAMP 5

This applies binomial smoothing. It is useful when you want to approximate a phase-only pulse by an amplitude/phase pulse and then reoptimise. Repeated cycles often give similar infidelity while reducing the integrated B₁ requirement.

10.3.2 Making standard and adiabatic pulses

Seedless can create Q3, Q5, SEDUCE, REBURP1, EBURP1, BURP1, HARD, and adiabatic pulses such as CHIRP, TANH, CHORUS, and WURST. A pulse file can also be supplied ,and the following B₁ optimisation will be performed on an arbitrary waveform.

A simple example is:

Make Q5 1000 1000 Opt Iz Iy -1

This creates a Q5 pulse with 1000 elements and a total duration of 1 ms. In Make commands, the duration is given in μs. The Opt Iz Iy -1 part asks Seedless to optimise the field so that, on resonance, the pulse transfers I_z to −I_y. After making a pulse, Seedless produces the report and quits, so Make overrides other calculation instructions.

You can also read in a pulse, fix its duration, and determine the optimal on-resonance field. For example:

Make make/pulse_Q5_1.RF 1000 1000 Opt Iz Iy -1

This reads a Q5 pulse of duration 1 ms and finds the B₁ field required for a 90^∘ rotation, which is 4546 Hz in this example. If the input file uses Bruker format, put Bruker in the header so that ReadColPhi, ReadColAmp, and ReadMaxAmp are set correctly.

The first plot follows pulse performance versus B₁ and runs a simple optimiser to find the field with peak performance. The second estimates the 0.99, 0.95, and 0.90 points of the excitation window. This is convenient for quick calibration of standard pulses.

Additional Make options include:

For an adiabatic example:

Make CHIRP 1000 2000 sweep 20000 n 5 SetB1 4060 Opt Iz Iz -1 wHmax 10000

Here, sweep sets the frequency-sweep width and n sets the amplitude-profile shape. Additional adiabatic options are:

The calibrate demo project contains useful examples. Remove the initial # in that demo file to execute a line . Note if you have multiple Make lines, Seedless will treat this literally and concatenate multiple pulses. This probably isn’t what you want.

Make Q5 1000 1000 Opt Iz Iy -1
Make Q3 1000 1000 Opt Iz Iz -1
Make SEDUCE 1000 1000 Opt Iz Iz -1
Make REBURP1 1000 1000 Opt Iz Iz -1
Make EBURP1 1000 1000 Opt Iz Iy -1
Make HARD 1000 500 Opt Iz Iy -1
Make CHIRP 1000 2000 phase 2 sweep 20000 n 5 SetB1 4060 Opt Iz Iz -1 wHmax 10000
Make CHIRP 1000 2000 sweep 20000 n 5 SetB1 1060 Opt Iz Iy -1
Make TANH 1000 2000 sweep 20000 kappa 0.005 n 5 SetB1 1060 Opt Iz Iz -1 wHmax 5000
Make CHORUS 2000 2000 sweep 300000 n 5 SetB1 15500 Profile Iz Ix 1 wHmax 20000

10.3.3 Series representations

As described in Section x1-530009.69.6, amplitudes and/or phases can be represented by either a Fourier series or a power series.

SERIES FOURIER 5
SERIES POWER 10
FOURIER_COSONLY
SERIES_ZEROEDGES

Do not specify both series types in the same calculation. Fourier/power-series modes are useful for reproducing some older BURP-style computations[?], but for most modern Seedless calculations a phase-only pulse is usually more effective.

10.3.4 Hessian and gradient checks

As described in section 9.7 for diagnostic calculations, use:

HESSIANPLOT
TESTGRADS

HESSIANPLOT computes the Hessian and its eigenvalues for the final report; see Section x1-540009.79.7. TESTGRADS compares analytical and numerical gradients and reports the absolute gradients at the point where the calculation stops.

10.4 Named input sections

Named sections come after the header. They can appear in any order, and each section can contain as many lines as needed. Once Seedless reaches a named section, it no longer treats subsequent lines as header commands.

10.4.1 RF:

Use RF: to describe the B₁ homogeneity distribution. Always include this section. If you do not want B₁ compensation, include a single line with 1.0 1.0.

RF: (B1/weight)   # one row per B1 homogeneity value
0.93 0.25
1.00 0.50
1.05 0.25

10.4.2 Plot:

Use Plot: to choose the offsets shown in the final report. The plotting grid should not exactly match the optimisation grid in SpinSystem:; otherwise you only see performance at the points used during optimisation. Always include this section, even if you use only a small number of plotting points.

Plot: (Min/Max/Num)  # for showing final profiles
P 0 200 120

You can also apply different relative B₁ values in different ppm ranges:

Plot: (Min/Max/Num)
P 0 5 60 B1 0.5
P 5 14 60 B1 1.0

List ppm ranges from low to high so that output plots are continuous.

10.4.3 SpinSystem:

Use SpinSystem: to specify the chemical-shift bands included in the optimisation. The first entry is an arbitrary band name. For a simple pulse with one chemical-shift range, use one line. For selective pulses with several bands, use one line per band.

SpinSystem: (Min/Max/Num) # one row per group of spins
CO 165 185 96
CA 40 78 96
CB 8 40 96

10.4.4 Carriers:

Use Carriers: to specify the carrier frequency, in ppm. This is the centre of the pulse.

Carriers: (ppm)
176

10.4.5 wmH:

Use wmH: to specify the calibrated peak B₁ field in Hz. This value is important: it should be measured for your probe, sample, and amplifier settings.

For a direct-dimension calibration, measure a nutation curve. If the 360^∘ rotation time is t₃₆₀, the corresponding B₁ field in Hz is 1∕t₃₆₀. For example, a 14.2 μs 90^∘ pulse corresponds to a field of 17605 Hz. For a heteronucleus, a practical approach is to use an HSQC-based calibration in which a test pulse is inserted after the first INEPT on the insensitive spin.

For low-γ nuclei, the field generated by the amplifier is often relatively sample independent. This is less true for protons. For maximum sensitivity, calibrate the relevant B₁ values and use those values in the Seedless calculation.

wmH: (Hz)
17605 # 14.2 us 90-degree pulse time

10.4.6 Durations:

Use Durations: to specify the total pulse duration and the number of finite elements. If you want duration rows to correspond one-to-one with target rows, rather than forming an independent grid, use LINK in the header.

Durations:
130E-6 130

10.4.7 Targets:

Use Targets: to start the section showing which transformation the pulse should perform. You can provide as many target rows as needed. Each row must contain one target instruction for each chemical-shift band in SpinSystem:. Separate band instructions with commas and leave spaces around the commas. Targets should be provided in the same order as the bands.

Some common examples for excitation (taking the spin from longitudinal, moving into the XY plane. Difficulty (and hence relative pulse duration) increases down the table. EV indicates evolution control[?].

For 180^o rotations,

You are free to mix and match state-to-state and universal restraints for different bands.

State-to-state

For state-to-state targets, give the starting state and final state separated by a space. Choices for states are Iz, Iy, Ix, -Iz, -Iy, -Ix and Iex. State-to-state restraints can also be supplied as a single string (no spaces) as linear combinations, for example 0.5Ix+0.5Iy. For a problem with three bands the targets should look like this

Targets:
Iz -Iz , Iz Iz , Iz Iz

Universal

For universal targets, give a single operator such as id for an identity restraint (the state at the end has to exactly match the state at the beginning), 90x (90^o rotation about the x axis), 180x (180^o rotation about the x axis) or a90xb (90^o flanked by fractional pre and post evolution periods specified by evAlpha and evBeta in the header), for example

Targets:
90x , id , id

A more general syntax is available for universal restraints. The unitary operators have the form e^−iA, where

Here, B sets the flip angle, P sets the phase in units of π, and O sets evolution about Z for a fraction of the total duration for evolution control. For example, 0.25B is a 90_x restraint, and 0.35B+0.5P is a 126_y-type restraint. Multiple propagators can be concatenated with semicolons:

0.25B+0.5P;0.5B;0.25B+0.5P

This creates a 90_y pulse, followed by a 180_x pulse, followed by another 90_y pulse, and

0.3O;0.25B;0.6O

This creates a schematic pulse with a ‘pre’ delay of 0.3 times the pulse length, and a ‘post’ evolution delay equal to 0.6 times the pulse length, flanking a 90x central rotation. This is equivalent to specifying a90xb, and setting evAlpha 0.3 and evBeta 0.6.

Generalised XYcite

The XYcite restraint was modified, with thanks to Jesse Shelfhout, to support laser-excitation work. The original XYcite pulse selected for “not Z”. The command

XYciteTarg 0.707

can be set in the header to set the desired amount of Z remaining in the final state. If this value is omitted or set to zero, Seedless selects for “not Z”. If it is set to 1.0, the pulse tries to end with only Z. A value of 0.707 gives approximately equal excitation and remaining Z magnetisation. This is useful when transverse relaxation is fast and only a small fraction of the total magnetisation should be tipped into the transverse plane, allowing a faster repetition delay.

This determines the angle 𝜃 of the final magnetisation relative to the Z axis, with XYciteTarg = sin(𝜃). Different bands can be used to specify specific XYcite target excitation values. For example:

Targets:
Iz 0.5Iex ,  Iz 0.1Iex , Iz 0.2Iex ....

sets different excitation amounts for each band.

State-to-state evolution control

A state-to-state evolution-controlled target can be created using syntax such as:

Targets:
Iz -0.5OIy

The capital letter O before Iy triggers this mode, and note that the minus sign applies to the I_y rather than to the 0.5. The target starts from I_z and ends at the appropriate point in the transverse plane, taking into account the chemical shift of the spin and half of the pulse length. In the ‘schematic picture’ this will create a pulse with uncontrolled ‘pre’ evolution, and have a controlled ‘post’ evolution equal to half of the pulse duration[?].

This mode can also use XYciteTarg when small flip-angle excitation is desired. If 𝜃 is the angle to the z axis and XYciteTarg is sin(𝜃), then the target -0.5OIy creates the reduced density matrix:

(10)

In this expression, XYciteTarg sets the angle to the z axis, while the offset-dependent command rotates the final transverse state by the desired amount of chemical-shift evolution. This syntax can therefore be used to make small-flip-angle, state-to-state, evolution-controlled pulses.

In terms of difficulty, a fully evolution-controlled unitary pulse is usually the most demanding. A unitary 90^∘ pulse is typically easier because it does not control evolution. A state-to-state evolution-controlled pulse is probably comparable in difficulty to a normal state-to-state pulse, and XYcite is easier again.

10.4.8 BandWeight:

Use BandWeight: to change the relative applied B₁ weighting in different bands. Each line must contain one entry per band, matching the order used in Targets:. Add multiple lines to test multiple combinations.

For example, with two bands, this applies 50% of the maximum relative B₁ to the first band and 100% to the second:

BandWeight:
0.5 , 1.0

10.4.9 Miss:

Use Miss: to add a miss restraint, commonly used for water suppression or for protecting a region while optimising another region.

Miss: (Min/Max/Num/Target) # one row per group of spins
Wat 4.65 4.85 10 Iz Iz stride 2 weight 1

This applies the Iz Iz start/finish restraint to 10 ppm values spaced linearly between 4.65 and 4.85 ppm. stride controls how often the restraint is applied: stride 1 means every finite element, stride 2 means every other element, and so on. weight controls the relative importance of the miss restraint. Increase it if the calculation should pay more attention to this region. We are very grateful to Steffen Glaser for helping revise how we compute the miss restraint (section 10.4.9)

Appendix: refined optimal tracking derivation

The derivation below is retained for readers who want the implementation detail behind the miss-restraint speedup. It is not needed for routine pulse design.

Following discussion with Prof. Steffen Glaser, it was pointed out that our water-miss pulses are identical in formulation to previously published optimal-tracking pulses. The original Seedless implementation evaluated gradients using a triangular sum. For a cost function with N finite elements, where the effect of the pulse is recorded at every element, the original expression was:

This can be rearranged as:

	= ∑ n=jNTr	(11)
	= ∑ n=jN2ReTr.

(12)

and simplified to:

(13)

Taking C_n = ρ_sX_n^†ρ_fX_n and B_j = X_j^†X_j−1 gives:

(14)

Glaser’s observation was that the triangular sum can be collapsed. First write:

(15)

If the derivatives are computed from j = N backwards, define D_N = C_N and update recursively with D_j = D_j+1 + C_j. The derivative then becomes:

(16)

Seedless uses this backwards loop, updating D_j only at finite elements where the restraint should be sampled. This replaces a triangular sum with a single loop over N involving matrix products and sums. In one water-miss example, the evaluation time dropped from 16 seconds to 6 seconds, a speedup of about 2.7.

11 Project history and contributors

For those that find the background interesting, Seedless began as a collaboration between chemistry and quantum information theory, and a discussion about quantum similarity [?]. Jonathan Jones has been producing pulses for quantum information purposes for many years. We sought to implement these ideas for NMR pulse sequences. The initial project involved C. Buchanan, G. Bhole, G. Karunanithy, J. A. Jones, and A. Baldwin. We are very grateful to members of the Baldwin group, particularly V. Casablancas-Antras and J. Eaton, for support with protein NMR tests. We are also grateful to A. W. J. Poh and B. G. Davis for support with fluorinated organic molecules, which helped us test the ideas behind the program[?]. The Seedless program came from this work, where we demonstrated that pulses created by Seedless can be used in pulse sequences for significant sensitivity gains. We argue that “one size does not fit all” and that in general, it is beneficial to tailor pulses to specific hardware/sample combinations. The program is fast and robust enough to make this viable.

We then considered how limiting was the assumption of making pulses for isolated spin-1/2 systems. We use this in Seedless as we can exploit symmetries in the form of the density matrices to make a highly efficient algorithm. But is this a good idea? We were able to prove that provided a pulse acts on one spin at a time, ensembles of weakly coupled spins can be treated exactly using isolated spin- pulses[?]. This also covers the case of non-spin- nuclei when quadrupolar interactions have averaged to zero. If you have strong coupling, or you have the pulse on multiple nuclei at once, then make the pulse short. These ideas lead to the “schematic pulse” description of pulses, and “evolution controlled” pulses that exactly control both scalar coupling and chemical shift evolution times in pulse sequences. These ideas are described in a paper with by S. Lim, B. Guo, A. Turner, C. Buchanan, J. A. Jones, and A. Baldwin. The experimental demonstration of these ideas was performed by Suzanne Lim as part of her Masters year research project.

Seedless deliberately emphasises phase-only pulses. Although the program includes amplitude-only and simultaneous amplitude/phase optimisation modes, our NMR tests have usually found phase-only pulses to be faster, more robust, and at least as good experimentally when peak B₁ is the relevant limit. As part of ongoing work on this question, Seedless now includes modes for converting between phase-only and amplitude/phase modulation. These modes are included both as practical tools and as a way to demonstrate the close relationship between the two descriptions. Further development is planned.

Seedless has benefited from many conversations, tests, bug reports, and contributions of code and effort. The list below is deliberately detailed so that changes can be traced between versions. Please get in touch if you would like to collaborate, test new features, report a problem, or help extend the software.

11.1 Version 1.0, 8th January 2025

The starting point was a MATLAB algorithm written by G. Bhole and J. A. Jones for optimising square-root universal restraints using MATLAB’s BFGS optimiser. The approach built on methods used and developed by J. A. Jones in quantum information studies. The optimisation instructions and smoothing penalties drew directly from code in the excellent Spinach project by I. Kuprov and co-workers.

The code was then ported to C++ and generalised to accept a broader range of restraints, including state-to-state, universal, and water-miss restraints. This implementation was developed by A. Baldwin, with J. A. Jones and C. Buchanan, and was optimised to exploit symmetries specific to isolated spin- calculations. The implementation is deliberately low-level, written by someone who likes pointers, and parallelised using OpenMP.

The practical NMR rules for deciding which pulse type should be used in which part of an experiment came from a large number of pulse-design tests by C. Buchanan and A. Baldwin. The final results from this phase of the work are presented in the Seedless paper.

Compilation was set up for Linux by A. Baldwin, Intel Macs by A. Baldwin, Apple M1 Macs by C. Buchanan, and Windows by J. Schelfhout, S. Lim, A. Turner, and A. Baldwin.

11.2 Version 1.1, 25th January 2025

Following discussions with N. Karschin, M. Mayzel, and P. Wurm at Bruker, we noted that the final infidelity can depend on the random seed. The variation is typically around a factor of three and is most noticeable when the overall infidelity is already very low. It is not yet clear how often such small numerical differences are visible experimentally, but it is undesirable for a calculation to depend strongly on a single random seed.

To address this, the HorseRace mode was added. This mode tests a set of random initial conditions, runs a short optimisation trajectory for each, selects the best early performer, and then carries that pulse through to the final optimisation. Examples and usage notes are given earlier in this manual.

Following discussions with users including J. Bercovici, A. Turner, and H. Mackenzie, a Grid mode was added. This mode lets users scan over B₁ values, total durations, and finite-element lengths while monitoring the resulting infidelity. For a new application, grid search helps develop an intuitive sense of the RF field and pulse duration needed to reach a useful infidelity.

Binaries were produced for Linux by A. Baldwin, Intel Mac by A. Baldwin, Apple M1 Mac by A. Turner, and Windows by S. Lim, together with timing reports.

11.3 Version 1.11, 19th February 2025

This release contained minor bug fixes and added a mode to enforce time-reflection symmetry in pulse phases using SYM. For a unitary restraint, this guarantees a frequency-symmetric pulse. A related time-reflection plus phase-inversion option, SYMPR, was also added, although it is probably of limited practical use.

Binaries were produced for Linux by A. Baldwin, Intel Mac by A. Baldwin, Apple M1 Mac by M. Wright, and Windows by S. Lim, together with timing reports.

11.4 Version 1.2, 10th February 2026

Version 1.2 was released to coincide with the multi-spin paper [?]. It added several new modes, described in the release notes and in the advanced-functionality sections above.

Amplitude and simultaneous amplitude/phase optimisation routines were improved. A basin-hopping stimulated-annealing mode, the Jiggler, was added for difficult cases where the ordinary optimiser may not reach the global minimum. We have not generally found this necessary for routine phase-only NMR pulses, but it remains available for difficult optimisation problems.

The Make mode was extended so that an arbitrary shape can be read in, run for a specified duration, and used to optimise the on-resonance field. The number of supported standard pulse shapes was also increased.

Prof. Steffen Glaser pointed out that the original miss-restraint formulation was inefficient and that a more efficient implementation could be built from the ideas in his optimal-tracking work. The miss-pulse calculations are now considerably faster.

Alex Hansen and Jesse Schelfhout, working with Jonathan Jones, were both interested in extensions of the XYcite pulse that do not attempt to place all magnetisation in the transverse plane. Related state-to-state evolution-control pulses were also requested. Both capabilities were implemented for this version and are described in the relevant sections of this manual.

The major update in version 1.2 was enhanced support for schematic pulses that control scalar-coupling and chemical-shift evolution across coupled spin ensembles. See the multi-spin paper for the full description.

Binaries were produced for Linux by A. Baldwin, Apple M1 Mac by A. Baldwin, and Windows by S. Lim. Timings were supplied by J. Bercovici for Linux and by S. Lim for Windows.

11.5 Version 1.3, 4th July 2026

Version 1.3 added modes for Hessian analysis and an expanded set of optimiser options. In practice, we do not yet think the additional optimisers are usually useful for routine Seedless calculations, but they are included for testing and comparison.

More importantly, this release added amplitude-to-phase and phase-to-amplitude conversion modes. These were added to accompany work led by J. A. Jones on the relationship between phase-only and amplitude/phase descriptions of shaped pulses. Thanks to Eiso Ab for pointing out an issue with our Linux binary: older distributions of Linux are missing a more modern vectorisation library. We have included an extra linux binary that can be substituted for the main one should this beomce an issue.

The wonderful Seedless logo was hand drawn by Suzanne Lim.