Crate quantr

🚧 quantr 🚧

This crate is not production ready and so should not be considered stable, nor produce correct answers. It is still under heavy development and requires many more optimisations. Hence, it’s likely that near future updates will induce breaking changes. Please always check answers with other simulations if you are intending to use quantr for projects.

A Rust library crate that builds, prints and simulates a quantum computer.

This crate allows the user to build a quantum circuit by adding columns of gates via various methods. Once the circuit has been built, then it can be simulated, which attaches the register |00..0> resulting in a superposition that can be measured.

For a brief example of using quantr, see the quick start guide which walks through an implementation of Grover’s algorithm.

Defining features

• Aimed to be accessible for beginners in Rust.
• The distinction between physical observables and non-physical observables is made clear; but the latter is still made possible to retrieve.
• Prints the circuit diagram to the terminal, or saves it to a text file, as a UTF-8 string.
• Custom gates can be implemented easily by giving their explicit linear mappings on product states. This allows the user to avoid representing the gates as matrices.
• Attempts to minimise memory consumption by not using matrices nor sparse matrices, but instead uses functions to represent the linear mapping of gates.
• Only safe Rust code is used, and the only dependency is the rand crate and its sub-dependencies.

Usage

An example of simulating and printing a two qubit circuit:

use quantr::circuit::{Circuit, StandardGate, printer::Printer, 
            Measurement::Observable};

fn main() {

    let mut quantum_circuit: Circuit = Circuit::new(2).unwrap();

    quantum_circuit 
        .add_gates(vec![StandardGate::H, StandardGate::H])
        .unwrap();
    quantum_circuit
        .add_gate(StandardGate::CNot(0), 1)
        .unwrap();
    
    let mut printer = Printer::new(&quantum_circuit);
    printer.print_diagram();
    // The above prints the following:
    // ┏━━━┓     
    // ┨ H ┠──█──
    // ┗━━━┛  │  
    //        │  
    // ┏━━━┓┏━┷━┓
    // ┨ H ┠┨ X ┠
    // ┗━━━┛┗━━━┛

    quantum_circuit.simulate();

    // Below prints the number of times that each state was observered 
    // over 500 measurements of superpositions.

    if let Observable(bin_count) = quantum_circuit.repeat_measurement(500).unwrap() {
        println!("[Observable] Bin count of observed states.");
        for (state, count) in bin_count {
            println!("|{}> observed {} times", state.as_string(), count);
        }
    }

}

A more detailed example of using quantr is given in the quick start guide.

Limitations (currently)

• There is no noise consideration, or ability to introduce noise.
• There is no ability to add classical wires.
• The circuit size has an upper bound of 50 qubits. Although, due to incomplete optimisations, it’s recommended that the circuit size should be much less.

Conventions

The ordering of the wires labelling the product states in the computational basis is defined as:

|a⟩ ──── 
|b⟩ ────  ⟺ |a,b,c,⋯⟩ ≡ |a⟩⊗|b⟩⊗|c⟩⊗⋯ 
|c⟩ ────
 ⋮    ⋮

When defining a custom function that depends on the position of control nodes to define gates (such as the CNot and Toffoli gates), it must be defined so that the most far right state of the product state, is assumed to be the gate that is ‘activated’. In general, it is better to assume that the custom function doesn’t define control nodes, but rather it extends the dimension of the function’s domain.

Documentation

The Quantr Book is planned to serve as extended documentation to quantr, such as explaining the motivations behind chosen algorithms. For now, it only contains the start guide.

For the online code documentation, please refer to crates.io. This can also be built and opened in your favourite web browser locally by cloning the project, moving into the directory, and running cargo doc --open.

Other quantum computer simulators

The website Are We Quantum Yet (checked 24/10/23) lists all things quantum computing in Rust.

A useful and very practical simulator for learning quantum computing is Quirk. It’s a real-time online simulator that interfaces via drag-and-drop gates. Note that the labelling of the states in the computational basis in Quirk is reversed when compared to quantr’s labelling of such states.

Licence

Quantr is licensed under the EUPL-1.2 or later. You may obtain a copy of the licence at https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12. A copy of the EUPL-1.2 licence in English is given in LICENCE.txt which is found in the root of this repository. Details of the licenses of third party software, and the quantr project, can be found in COPYRIGHT.txt.

Modules

• circuit
  Construct, simulate and measure quantum circuits.
• complex
  Generic complex numbers.

Macros

• complex
  Usage: complex!(real: f64, imaginary: f64) -> Complex<f64> A quick way to define a f64 complex number.
• complex_Im
  Usage: complex_Im!(imaginary: f64) -> Complex<f64> A quick way to define an imaginary f64; the real part is set to zero.
• complex_Im_array
  Usage: complex_Im_array!(input: [f64; n]) -> [Complex<f64>; n] Returns an array of complex number with zero real part, and imaginary set by input.
• complex_Im_vec
  Usage: complex_Im_vec!(input: [f64; n]) -> Vec<Complex<f64>> Returns a vector of complex numbers with zero real part, and imaginaries set by input.
• complex_Re
  Usage: complex_Re!(real: f64) -> Complex<f64> A quick way to define a real f64; the imaginary part is set to zero.
• complex_Re_array
  Usage: complex_Re_array!(input: [f64; n]) -> [Complex<f64>; n] Returns an array of complex number with zero imaginary part, and reals set by input.
• complex_Re_vec
  Usage: complex_Re_vec!(input: [f64; n]) -> Vec<Complex<f64>> Returns a vector of complex number with zero imaginary part, and reals set by input.
• complex_zero
  Shortcut for complex!(0f64, 0f64).