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 gate.  The optimiser adjusts the basis coefficients; gradients and Hessians come
9//! from the crate's own reverse-mode automatic differentiation.
10//!
11//! ## Quick start
12//!
13//! ```
14//! use ctrl_freeq::config::{Config, examples};
15//! use ctrl_freeq::optim::NoProgress;
16//!
17//! # fn main() -> ctrl_freeq::Result<()> {
18//! // One of the Python package's bundled configurations: three initial states on one qubit.
19//! let json = examples().iter().find(|e| e.0 == "single_qubit_parameters_multiple_initial_targ").unwrap().1;
20//! let mut cfg = Config::from_json(json)?;
21//! cfg.seed = Some(7); // reproducible
22//! cfg.optimization.max_iter = 20;
23//! let result = ctrl_freeq::run(&cfg, &mut NoProgress)?;
24//! assert!(result.fidelity > 0.5);
25//! let plots = ctrl_freeq::analyse(&cfg, &result)?;
26//! assert_eq!(plots.pulses.len(), 1);
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! ## Where to look
32//!
33//! * [`config`]: the configuration, in the Python package's JSON schema.
34//! * [`run()`] and [`analyse()`]: optimise, then get the data for plots.
35//! * [`optim`]: the optimisers and the interface a new one implements.
36//! * [`hamiltonian`] and [`basis`]: the physical platforms and waveform bases, and how to add one.
37//! * [`objective`] and [`autodiff`]: the cost function and the differentiation underneath it.
38//!
39//! ## Threads
40//!
41//! With the `parallel` feature, on by default, the batch elements and the Hessian's columns are evaluated on
42//! [rayon](https://docs.rs/rayon)'s thread pool.  Results are bit-for-bit the same on one thread as on many.
43//! `wasm32` has no threads and always runs sequentially.
44#![deny(missing_docs)]
45
46pub mod analysis;
47pub mod autodiff;
48pub mod basis;
49pub mod config;
50pub mod error;
51pub mod hamiltonian;
52pub mod linalg;
53pub mod objective;
54pub mod optim;
55mod parallel;
56pub mod run;
57pub mod setup;
58pub mod time;
59
60pub use analysis::{Analysis, analyse};
61pub use config::Config;
62pub use error::{Error, Result};
63pub use run::{RunResult, run};