Skip to main content

ctrl_freeq/
lib.rs

1//! # ctrl-freeq
2//!
3//! Quantum gate and pulse design by optimal control.  A Rust port of the Python
4//! [ctrl-freeq](https://pypi.org/project/ctrl-freeq/) package.
5//!
6//! A control pulse is expanded in a small basis (Chebyshev, Legendre, Fourier, ...), propagated through a batch of
7//! drift Hamiltonians that sample the uncertainty in offsets, couplings and field strength, and scored by the mean
8//! fidelity to a target state, or by the average gate fidelity to a target gate.  The optimiser adjusts the basis
9//! coefficients; gradients and Hessians come from the crate's own reverse-mode automatic differentiation.
10//!
11//! [`analyse()`] then gives the data the plots need: the pulses, the state dynamics, the excitation profile, and
12//! the population outside the computational subspace.  A run also reports each qubit's peak amplitude as a fraction
13//! of its maximum Rabi frequency, which the cost penalises rather than enforces.
14//!
15//! ## Quick start
16//!
17//! ```
18//! use ctrl_freeq::config::{Config, examples};
19//! use ctrl_freeq::optim::NoProgress;
20//!
21//! # fn main() -> ctrl_freeq::Result<()> {
22//! // One of the Python package's bundled configurations: three initial states on one qubit.
23//! let json = examples().iter().find(|e| e.0 == "single_qubit_parameters_multiple_initial_targ").unwrap().1;
24//! let mut cfg = Config::from_json(json)?;
25//! cfg.seed = Some(7); // reproducible
26//! cfg.optimization.max_iter = 20;
27//! let result = ctrl_freeq::run(&cfg, &mut NoProgress)?;
28//! assert!(result.fidelity > 0.5);
29//! let plots = ctrl_freeq::analyse(&cfg, &result)?;
30//! assert_eq!(plots.pulses.len(), 1);
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! ## Where to look
36//!
37//! * [`config`]: the configuration, in the Python package's JSON schema.
38//! * [`run()`] and [`analyse()`]: optimise, then get the data for plots.
39//! * [`optim`]: the optimisers and the interface a new one implements.
40//! * [`hamiltonian`] and [`basis`]: the physical platforms and waveform bases, and how to add one.
41//! * [`objective`] and [`autodiff`]: the cost function and the differentiation underneath it.
42//!
43//! ## Threads
44//!
45//! With the `parallel` feature, on by default, the batch elements and the Hessian's columns are evaluated on
46//! [rayon](https://docs.rs/rayon)'s thread pool.  Results are bit-for-bit the same on one thread as on many.
47//! `wasm32` has no threads and always runs sequentially.
48#![deny(missing_docs)]
49
50pub mod analysis;
51pub mod autodiff;
52pub mod basis;
53pub mod config;
54pub mod error;
55pub mod hamiltonian;
56pub mod linalg;
57pub mod objective;
58pub mod optim;
59mod parallel;
60pub mod run;
61pub mod setup;
62pub mod time;
63
64pub use analysis::{Analysis, analyse};
65pub use config::Config;
66pub use error::{Error, Result};
67pub use run::{RunResult, run};