Skip to main content

Crate qoala

Crate qoala 

Source
Expand description

§QOALA - Quantum Optimal control by Adaptive Low-cost Algorithm

A Rust port of the QOALA MATLAB package (M. Foroozandeh, D. L. Goodwin, P. Singh). QOALA is a GRAPE optimal-control package for coupled two-level systems whose central idea is that a pulse optimisation does not need an accurate propagator until it is close to the optimum: it splits the Hamiltonian into a single-spin part with a closed form and an interaction part handled by a few precomputed propagators, then picks the splitting order and Trotter number on the fly.

The method is described in D. L. Goodwin, P. Singh and M. Foroozandeh, “Adaptive optimal control of entangled qubits”, Science Advances 8(49), eabq4244 (2022), https://doi.org/10.1126/sciadv.abq4244. The single-spin method it extends, ported here as escalade, is M. Foroozandeh and P. Singh, “Optimal control of spins by analytical Lie algebraic derivatives”, Automatica 129, 109611 (2021), https://doi.org/10.1016/j.automatica.2021.109611.

§Where to start

  • drivers - state2state_xy and universal_gate_xy wrap the whole pipeline for a chain of coupled two-level systems with an x and a y control on each.
  • config - ControlOptions in, ControlSystem out, for anything the drivers do not cover.
  • optim::newton::fmaxnewton - the optimiser itself.
  • spinops - the spin operators, states, couplings and gates the examples are built from.
  • gates - turn any Hilbert-space unitary into the Liouville-space superoperator a gate optimisation targets, plus a library of the usual one- and two-qubit gates.
  • escalade - ESCALADE, the uncoupled single-spin method QOALA extends: one pulse for a band of offsets and a spread of field strengths, optimised on the exact Hessian.

§The numerical layers

  • objfun - the objective functions: objfun::qoala for the adaptive split-operator method, objfun::auxmat for the exact auxiliary-matrix reference.
  • rodrigues - closed-form single-spin propagators and their control derivatives.
  • splittings - operator splittings of orders 0, 1, 2, 3, 4 and 6, with Trotterisation.
  • propagate - Pade, Taylor and Krylov matrix exponentials.
  • penalty - waveform penalty terms with gradients and Hessians.
  • linalg - the dense/sparse complex matrix type everything is built on.

§Threads

With the parallel feature, on by default, ESCALADE evaluates each spin at each field - one work item - on rayon’s thread pool: one thread per core, fewer with RAYON_NUM_THREADS or inside a pool of the caller’s own. The sums are grouped by the size of the problem, never by the thread count, so a run gives bit-for-bit the same pulse on one thread as on many, and the same as with the feature turned off. wasm32 has no threads and always runs sequentially.

Differences from the MATLAB original are listed in DEVIATIONS.md.

Modules§

config
Control-system configuration: options in, a parsed system out.
drivers
High-level drivers: describe the problem, get an optimised pulse back.
error
Error type for the QOALA crate.
escalade
ESCALADE
examples_io
CSV writers the examples use; not available on wasm32, which has no filesystem. Small helpers the examples use to get results out of the process.
gates
Hilbert-space gates and their Liouville-space superoperators.
linalg
Dense/sparse complex matrix plumbing.
objfun
GRAPE objective functions.
optim
Optimisation: the cost-function interface, the diagnostics record and the objective wrapper.
penalty
Waveform penalty terms and their derivatives.
prop_index
Sparse index tables for propagator elements.
propagate
Matrix exponentials and single-step propagation.
report
Console reporting.
rodrigues
Euler-Rodrigues propagator elements and their control derivatives.
spinops
Spin-1/2 operators in the spherical tensor Liouville basis.
splittings
Operator splittings for the interaction Hamiltonian.
time
Clock shim.
types
Typed replacements for QOALA’s MATLAB “magic string” options.
waveform
Independent fidelity check by direct propagation.

Macros§

bad
Shorthand for building a QoalaError::BadValue.
missing
Shorthand for building a QoalaError::MissingField.
nyi
Shorthand for building a QoalaError::NotImplemented.