qoala 1.3.0

Quantum Optimal control by Adaptive Low-cost Algorithm: GRAPE pulse optimisation for coupled two-level systems, with adaptive operator splitting
Documentation

qoala

CI Crates.io Documentation License: MIT

Quantum Optimal control by Adaptive Low-cost Algorithm — a Rust port of the QOALA MATLAB package by M. Foroozandeh, D. L. Goodwin and P. Singh.

Try Rusty-QOALA in your browser: https://rusty-qoala.pages.dev - QOALA and ESCALADE with presets and live plots, nothing to install. Everything runs on your machine; nothing is uploaded.

QOALA is a GRAPE optimal-control package for coupled two-level systems. Its idea is that most of the work in a pulse optimisation is wasted: early iterations are nowhere near the optimum, so propagating the system to machine precision to evaluate them is pointless. QOALA splits the Hamiltonian into a single-spin part, which has a closed form and needs no matrix exponential at all, and an interaction part handled by a small set of precomputed propagators — then chooses the splitting order and Trotter number on the fly, so the propagator is only ever as accurate as the optimiser currently needs.

On the paper's own two-spin benchmark this port reaches an infidelity of 3e-8 in 0.11 s of objective time, against 2.3 s for the exact auxiliary-matrix method: a 21x speed-up at the same accuracy.

The crate also ports ESCALADE, by M. Foroozandeh and P. Singh: the uncoupled, single-spin method QOALA extends to coupled spins. With nothing coupling the spins, the closed-form propagators are all there is, so ESCALADE can afford the exact Hessian. It designs one pulse for a whole band of resonance offsets, and optionally for a spread of field strengths as well, which is how a pulse is made robust to B1 inhomogeneity. See ESCALADE.

Installation

[dependencies]
qoala = "1.3"

There is also a graphical front end: open it at https://rusty-qoala.pages.dev, or run it as a desktop application. See The application.

Or the development version from git:

[dependencies]
qoala = { git = "https://github.com/mforoozandeh/Rusty-QOALA" }

Quick start

use qoala::drivers::{state2state_xy, StateTransfer, Tuning};
use qoala::spinops;
use num_complex::Complex64;

// Two spins, weakly coupled at 140 Hz, with an x/y control pair on each.
let interaction = spinops::zz_coupling(2, 0, 1)?
    .scale(Complex64::new(2.0 * std::f64::consts::PI * 140.0, 0.0));

let optimised = state2state_xy(StateTransfer {
    omega: vec![0.0, 0.0],                       // offsets, Hz
    initial: spinops::z_state(2, 0),             // z-magnetisation on spin 1
    target:  spinops::z_state(2, 1),             // ... moved onto spin 2
    amplitudes: vec![1000.0, 1000.0],            // maximum control power, Hz
    duration: 0.01,                              // seconds
    increments: 50,                              // time slices
    interaction,
    cartops: spinops::one_pair_per_spin(2),
    init_pulse: None,                            // random start
    seed: Some(1),
    tuning: Tuning::default(),
})?;

println!("{:?}", optimised.waveform.shape());    // (50, 4)
# Ok::<(), qoala::error::QoalaError>(())

For anything the drivers do not cover, build a ControlOptions, run it through optimconset, and hand the result to fmaxnewton — the same two steps as the MATLAB.

Examples

cargo run --release --example z2z_2spin_1        # z-to-z transfer, weak coupling
cargo run --release --example z2z_2spin_2        # strong coupling, one shared control pair
cargo run --release --example z2z_3spin_1        # three-spin chain
cargo run --release --example swap_2spin_1       # SWAP gate
cargo run --release --example swap_3spin_1       # SWAP across a three-spin chain
cargo run --release --example paper_benchmarks -- state-2spin-hetero
cargo run --release --example escalade_grad_vs_hess   # ESCALADE, see below

Each writes its optimised pulse to CSV and prints a fidelity computed by an independent exact propagation of the pulse it produced — not by the objective function that produced it. Current results, on a random starting pulse:

example fidelity (independently checked)
z2z_2spin_1 99.999999 %
z2z_2spin_2 99.999981 %
z2z_3spin_1 99.999989 %
swap_2spin_1 99.617 % (100-iteration budget, as in the MATLAB)
swap_3spin_1 99.986 %

paper_benchmarks covers all six scripts in the MATLAB's examples/qoala_paper_results/, which differ only in the spin system and target. Pass state-2spin-hetero, state-2spin-homo, state-3spin-hetero, state-4spin-mixed, gate-2spin-hetero or gate-3spin-hetero, plus optional --runs, --steps and --iters.

ESCALADE

use qoala::escalade::{escalade, magnetisation, Escalade, States};

// z to -y across 20 kHz, with a 17 kHz field, in 100 microseconds.
let optimised = escalade(&Escalade {
    nspins: 51,                                  // spins spread across the band
    sw: 20000.0,                                 // bandwidth, Hz
    rf: vec![17000.0],                           // field, Hz; several values for B1 robustness
    tau_p: 100e-6,                               // seconds
    np_pulse: 50,                                // pulse points
    initial: States::Single(magnetisation(0.0, 0.0, 1.0)),
    target: States::Single(magnetisation(0.0, -1.0, 0.0)),
    use_hessian: true,                           // Newton trust region on the exact Hessian
    seed: Some(1),
    ..Default::default()
})?;

println!("{:.4} after {} iterations", optimised.fidelity, optimised.counters.iter);
# Ok::<(), qoala::error::QoalaError>(())
cargo run --release --example escalade_grad_vs_hess   # Hessian against gradient only
cargo run --release --example escalade_b1             # B1-sensitive against B1-compensated
cargo run --release --example escalade_parallel       # one thread against every core

These port the two scripts in the MATLAB's test_runs/. On the first, both optimisers reach 99 % in under a tenth of a second. The second writes the pulse, the excitation profile, the map of Iy over offset and field, and the dphi/dB1 curve as CSV; optimising over 0.8 to 1.2 times the field lifts the worst-case fidelity across that range from 0.84 to 0.95.

escalade::profile computes the offset profile, the B1 map and the phase sensitivity of any pulse, from the same propagators the optimiser uses.

Threads. One spin at one field - a work item - is a time-ordered product over the pulse, but the work items are independent of each other. The parallel feature, on by default, spreads them over rayon's thread pool - one thread per core, or RAYON_NUM_THREADS. Where that applies:

  • Library and command line, native - on every core by default. default-features = false in a dependency, or --no-default-features in this repository, drops rayon and runs on one core.
  • Desktop application (cargo run -p qoala-gui --release) - on every core.
  • Browser application - on one core, even when the page is cross-origin isolated. The WebAssembly build has no threads.

Only ESCALADE is spread over cores; QOALA's coupled-spin optimisation runs on one core everywhere. The sums are grouped by the size of the problem and never by the thread count, so a run returns the same pulse to the last bit on one core or many. That fixed grouping has a small cost on one core: a single field of 51 spins runs about 5% slower there than a plain loop, since each spin becomes a piece with its own Hessian accumulator.

escalade_parallel times the B1-compensated problem both ways. On an idle 12-core Apple M2 Max (8 performance, 4 efficiency), a Hessian evaluation of its 1581 work items (51 spins × 31 fields) drops from 41 ms to 4.8 ms, and 200 Newton iterations from 7.1 s to 0.9 s, with identical pulses. escalade_b1 falls from 38 s with the original sequential code to 4.8 s.

MATLAB Rust
main/ESCALADE.m escalade/solve.rs
main/readDefaults.m, main/readSettings.m escalade/settings.rs
main/gradhess_vectorized_B1_parallel.m, main/gradhess_vectorized.m escalade/objective.rs
main/derivatives_vectorized.m, main/LL_vectorized.m escalade/propagators.rs
visualisation/ESCALADE_pulse_sim.m, visualisation/ESCALADE_Bloch_B1.m escalade/profile.rs

Two things work differently, both described in DEVIATIONS.md. fmincon is replaced by argmin: a trust region on the Hessian, or L-BFGS on the gradient. And the amplitude limit is on the field itself, sqrt(x^2 + y^2) <= rf, kept by a penalty, where the MATLAB bounds each quadrature separately.

Repository layout

src/
  config.rs       parser: ControlOptions -> ControlSystem
  drivers.rs      state2state_xy, universal_gate_xy, the GRAPE cost function
  objfun/         the objective functions
    qoala.rs        adaptive split-operator method
    auxmat.rs       exact auxiliary-matrix reference
  optim/          optimiser
    newton.rs       LBFGS and Newton-Raphson
    linesearch.rs   Wolfe-condition line search
  escalade/       ESCALADE: uncoupled spins across a band
    solve.rs        the driver, and argmin's trust region and L-BFGS
    objective.rs    fidelity, gradient and Hessian over offsets and fields
    propagators.rs  SU(2) propagators and their first and second derivatives
    profile.rs      offset profiles, B1 maps, phase sensitivity
  rodrigues.rs    closed-form single-spin propagators and derivatives
  splittings.rs   operator splittings, orders 0-6, with Trotterisation
  propagate.rs    Pade, Taylor and Krylov matrix exponentials
  penalty.rs      waveform penalties
  prop_index.rs   sparse propagator index tables
  spinops.rs      spin operators, states, couplings, gates
  gates.rs        Hilbert unitaries -> Liouville superoperators, gate library
  linalg.rs       dense/sparse complex matrix type
  time.rs         clock shim, so the crate builds for wasm32
  types.rs        typed options; report.rs, error.rs, waveform.rs
examples/         the MATLAB example scripts, plus the benchmark harness
tests/            gradients, accuracy, end-to-end optimisation
gui/              the application: desktop and browser, same source
  src/setup.rs      the QOALA problem description, serde-serialisable
  src/escalade.rs   the ESCALADE problem description, and its analysis
  src/problem.rs    either of the two, as stored, shared and run
  src/presets.rs    the examples above, as one-click setups
  src/run.rs        the optimisation, and the message stream out of it
  src/app.rs        panels and plots
  src/export.rs     CSV and JSON export
  src/runner_*.rs   background thread natively, Web Worker in the browser
deploy/           cross-origin isolation headers, one file per host

The application

Rusty-QOALA, in gui/, is a front end over the same library: describe a qubit system, pick a target, watch it converge, take the pulse away as a file. It runs two ways from one source.

In the browser: https://rusty-qoala.pages.dev. Nothing to install. Everything runs in your browser - there is no server, no account and no upload - on one core.

On the desktop. Faster for large ESCALADE runs, which it spreads over every core, and the only way to run four-spin QOALA systems:

cargo run -p qoala-gui --release

Building the web version yourself. Only needed to try out changes to the application, or to host a copy of your own. trunk serve builds it and serves it at http://localhost:8080:

cargo install --locked trunk
trunk serve --config gui/Trunk.toml

trunk build --release --config gui/Trunk.toml writes the static files to gui/dist, which any file server can host - including python3 -m http.server. See deploy/README.md. The copy at rusty-qoala.pages.dev is built and published that way by .github/workflows/deploy.yml on every push to main.

What it gives you:

  • Both problems behind one switch, named for what they optimise rather than for the method. Single-qubit runs ESCALADE: it edits a band, a field (with an optional B1 spread) and a pulse. Multi-qubit runs QOALA: it edits a system of coupled qubits.
  • Every quantity in SI units - seconds and Hz - entered and shown in scientific notation where that reads better: type 2e6 for 2000000, and 0.000003 shows as 3e-6. Values of ordinary size, from 0.001 to 99999, are written out in full. Nanosecond and millisecond pulses are equally easy to set, and dragging a value moves it by a fixed fraction of itself.
  • A visual editor for the multi-qubit control map - which channel drives which qubit - which is the least obvious part of the library's API.
  • Presets for the five QOALA examples and the two ESCALADE runs of test_escalade_visual.m; the two-qubit transfer is loaded on startup, so the first click gives a converged pulse in about a second.
  • For a single-qubit pulse, a choice of three views under the convergence plot: the waveform, the excitation profile across offsets, and B1 robustness - a map of Iy over offset and field, beside the dphi/dB1 curve.
  • Infidelity against iteration on a log axis, the waveform as stairs in Hz, and the splitting order and Trotter number live, climbing as the fidelity improves.
  • A runtime estimate on the Run button, and a Cancel that works.
  • Exports: the waveform as CSV in Hz against seconds, and the whole setup as JSON.
  • The whole setup encoded in the URL fragment, so a link reproduces it exactly and can be sent to somebody else. Nothing is stored anywhere but the link and the visitor's own browser.

Three limits worth knowing. The browser build runs on one core, cross-origin isolated or not, while the desktop build spreads single-qubit optimisation over every core - several times faster for a B1-compensated pulse. Multi-qubit optimisation runs on one core in both. Four-qubit systems are dimension 256 with dense 256x256 propagators per slice; the browser build refuses them and points at the desktop one. And cancelling in the browser terminates the Web Worker, so the convergence curve is kept but the partial waveform is not - natively, cancellation is cooperative and the waveform comes back.

How the code maps to the MATLAB

MATLAB Rust
kernel/optimconset.m config.rs — ControlOptions in, ControlSystem out
kernel/fmaxnewton.m optim/newton.rs
kernel/fmaxlinesearch.m optim/linesearch.rs
kernel/objective.m optim/mod.rs — objective, OptData
kernel/penalty_fun.m penalty.rs
kernel/propagate.m propagate.rs
kernel/obj_fun/grape_{state,ugate}_qoala.m objfun/qoala.rs
kernel/obj_fun/grape_{state,ugate}_auxmat.m objfun/auxmat.rs
utilities/rodrigues.m rodrigues.rs
utilities/operator_splittings.m splittings.rs
utilities/propagator_ind.m prop_index.rs
utilities/waveform_fidelity.m waveform.rs
utilities/{state2state,universal_gate}_xy.m drivers.rs
operator construction in the example scripts spinops.rs
— types.rs, error.rs, linalg.rs, report.rs

The two grape_state_* / grape_ugate_* pairs are the same algorithm with different fidelity functionals, so each is one module parameterised by FidelityKind rather than two near-identical files.

Design notes

Options are typed. MATLAB's magic strings become enums, so 'lbgfs' is a compile error rather than a run-time surprise, and ctrl_param becomes a struct. The parser still prints the same banner, the same resolved settings and the same WARNING/RESOLVE commentary.

Sparsity is explicit. CMat is dense or CSR, and densify_if reproduces the "more than sparsity * dim^2 non-zeros means go dense" rule the objective functions apply to every propagator.

Propagator derivatives stay factored. The MATLAB builds dP{k} as an nsteps x dim^2 array — 65536 columns wide for four spins. ControlDerivative keeps the D block and the operators and forms the dim x dim matrix on demand. Same arithmetic, much less memory.

nargout becomes an argument. EvalOrder::{Value, Gradient} and PenaltyOrder::{Value, Gradient, Hessian} say what the caller wants.

Verification

cargo test runs 142 tests. There is no MATLAB in the loop; every check is self-contained and tests the mathematics rather than a stored output.

  • Gradients against finite differences. Every objective function's analytic gradient is checked against a central difference of its own fidelity — split-operator and auxiliary-matrix, state transfer and gate synthesis, at splitting orders 0, 1, 2, 3, 4 and 6 with Trotter numbers 1 and 2, with and without penalties. Every penalty's gradient and Hessian likewise.
  • Propagators against expm. The Euler-Rodrigues elements are checked against an independently computed matrix exponential of the same generator, and its derivative against a finite difference of that exponential. Padé, Taylor and Krylov are checked against each other and against closed-form Pauli rotations.
  • Splittings against their order conditions. Each splitting is assembled and compared with the exact exponential at two step sizes; the observed convergence rate must match the advertised order for orders 1, 2, 3, 4 and 6. Trotterisation must improve second-order accuracy quadratically.
  • Operators against the MATLAB literals. The zz and isotropic coupling superoperators built by spinops are compared entry by entry with the 16x16 matrices written out longhand in z2z_2spin_1.m and z2z_2spin_2.m. The SWAP gate is checked by confirming it actually swaps z-magnetisation — which caught a real ordering bug that a fidelity number alone would have hidden.
  • Convergence to the exact answer. Raising the splitting order, the Trotter number or the time resolution must monotonically close the gap to the auxiliary-matrix result; a well-resolved sixth-order splitting must agree to 1e-10 in fidelity and 1e-7 in gradient.
  • End to end. Optimisations must converge above 99.9 %, the adaptive ladder must climb as the infidelity falls, and adaptive and fixed fourth-order runs must land within 1 % of each other.
  • ESCALADE. The SU(2) propagators are checked against expm, their first and second control derivatives against finite differences on both sides of the zero-field series switch, and the full Hessian of the objective against a finite difference of its gradient over several spins and two weighted fields. Runs with and without the Hessian must reach 99 %, with a fidelity that matches an independent measurement of the magnetisation to 1e-9; a pulse started at twice the amplitude limit must be brought back to it; and optimising over a field spread must improve the worst case across it.

Differences from the MATLAB

Five corrections (an inexact backward pass for asymmetric splittings, an unreachable Lie-Trotter branch, a stale variable in the line search, a transposed penalty layout, and a gate-construction ordering), plus the features the MATLAB parses but never implements. All of them are listed, with reasons, in DEVIATIONS.md.

References

Relationship to the original package

This is an independent reimplementation, not a wrapper: there is no MATLAB in the loop at build time or run time. It follows the original's structure closely enough that a change made to one can be found in the other, and every place it departs is recorded in DEVIATIONS.md.

If you use this for published work, please cite the QOALA and ESCALADE papers and the underlying methods listed above, not just this port:

Licence

MIT, following the original package. See LICENSE — the original copyright is retained alongside the port's.