# quantr
[](https://crates.io/crates/quantr)
[](https://releases.rs/)
[](https://github.com/a-barlow/quantr/actions/workflows/rust.yml)
[&color=%2349881B)](https://github.com/a-barlow/quantr/actions/workflows/rust_dev.yml)
[](https://crates.io/crates/quantr)
[](https://crates.io/crates/quantr)
[](https://joinup.ec.europa.eu/collection/eupl)
> 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](#other-quantum-computer-simulators) 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
For a brief example of using quantr, see the
[quick start guide](QUICK_START.md) 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. For the number of qubits in a circuit, `n`, the
estimated memory that is required for quantr to simulate the circuit
when `n >= 16` is approximately the size of the state vector itself in
Rust, `2**(n-6) KiB`. For `n < 16`, the memory required is less than
`1 MiB`.
- Can simulate circuits up to ~18 qubits within a reasonable time.
- Only safe Rust code is used, and the only dependency is the
[fastrand](https://crates.io/crates/fastrand) crate and its
sub-dependencies.
### Usage
An example of simulating and printing a two qubit circuit:
```rust
use quantr::{Circuit, Gate, Printer, Measurement::Observable};
fn main() {
let mut quantum_circuit: Circuit = Circuit::new(2).unwrap();
quantum_circuit
.add_gates(&[Gate::H, Gate::Y]).unwrap()
.add_gate(Gate::CNot(0), 1).unwrap();
let mut printer = Printer::new(&quantum_circuit);
printer.print_diagram();
// The above prints the following:
// ┏━━━┓
// ┨ H ┠──█──
// ┗━━━┛ │
// │
// ┏━━━┓┏━┷━┓
// ┨ Y ┠┨ X ┠
// ┗━━━┛┗━━━┛
quantum_circuit.simulate();
// Below prints the number of times that each state was observered
// over 500 measurements of superpositions.
if let Ok(Observable(bin_count)) = quantum_circuit.repeat_measurement(500) {
println!("[Observable] Bin count of observed states.");
for (state, count) in bin_count {
println!("|{}> observed {} times", state.to_string(), count);
}
}
}
```
A more detailed example of using quantr is given in the [quick start
guide](QUICK_START.md).
### Limitations (currently)
- **No noise** consideration, or ability to introduce noise.
- **No parallelisation** option.
- **No ability to add classical wires** nor gates that measure a
single wire of a quantum circuit.
### Conventions
The ordering of the wires labelling the product states in the
computational basis is defined as:
``` text
|a⟩ ────
⋮ ⋮
```
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](https://a-barlow.github.io/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](https://crates.io/crates/quantr). 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](https://arewequantumyet.github.io)
(checked 24/10/23) lists all things quantum computing in Rust.
A useful and very practical simulator for learning quantum computing is
[Quirk](https://algassert.com/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](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](COPYRIGHT.txt).