burn_quantum 0.4.0

Differentiable qubit and qudit simulation with Burn's native tensor and module APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# burn_quantum

Differentiable qubit and qudit simulation using Burn 0.22's native tensors,
devices, modules, parameters, optimizers and weight records. Rust 1.95+.

`QuantumBackend` describes quantum execution; `DenseSimulator` implements it
using supported Burn devices. The public API accepts native `Tensor<D>` and
`Device` values. It does not require a separate tensor backend or a Burn fork.

## Quick start

```toml
[dependencies]
burn_quantum = "0.4.0"
burn = { version = "~0.22.1", default-features = false, features = ["std", "flex"] }
```

```rust
use burn::tensor::Device;
use burn_quantum::{Circuit, DenseSimulator, QuantumBackend, Register, Unitary};

fn main() -> burn_quantum::Result<()> {
    let mut circuit = Circuit::new(Register::qubits(2)?, 0, 0);
    circuit.unitary(vec![0], Unitary::h())?;
    circuit.unitary(vec![0, 1], Unitary::cnot())?;
    let state = DenseSimulator::default()
        .execute(&circuit, None, None, 1, &Device::flex())?;
    state.validate(1e-5)?;
    // [0.5, 0.0, 0.0, 0.5] in |00>, |01>, |10>, |11> order.
    println!("{}", state.probabilities());
    Ok(())
}
```

## Capabilities

- Batched qubit, qudit and mixed-dimensional pure states and density matrices.
- Validated local unitaries, differentiable rotations, observables, partial
  traces, Kraus channels and seeded terminal measurement.
- Serializable circuits, native autodiff, qudit-aware parameter-shift
  references, and `QuantumLayer` integration with Burn modules and records.
- Reusable encodings, circuit templates, probability losses and fidelity kernels.
- Quantum natural SPSA with a regularized Fubini–Study metric and checkpoints.
- Boolean CNF/DIMACS SAT search with reversible oracles and verified witnesses.
- `photonic` adds dual-rail/vacuum encoding, loss,
  Fock optics, calibrated fusions, physical circuit compilation, finite fabric
  scheduling, Clifford/frame simulation, encoded resources, QEC memories,
  finite boundaries, logical/magic-state references and bounded event/process execution.
  A separate `tensor_network` module supplies mixed-qudit MPS and distributed
  entangled-state ownership, with explicit approximation and host-SVD limits. See the
  [implemented models and remaining gates](https://github.com/mosure/burn_quantum/blob/main/docs/photonic-status.md).

Default features are `flex` and `autodiff`. Optional `wgpu`, `cuda` and `fusion`
features select accelerator capabilities; callers supply the execution device.
F32/F64 availability depends on the device. GPU qualification uses F32.

Dense simulation uses exponential state storage: for batch B and Hilbert
dimension N, pure states store 2BN real scalars and density matrices store 2BN².
Allocation limits are preflight checks, not a total memory cap. SAT search may
return `Inconclusive` when its budget is exhausted. QN-SPSA's dense host metric
uses O(d²) storage and an O(d³) solve for d parameters. These implementations do
not establish quantum advantage or efficient simulation of arbitrary circuits.

## Canonical algorithms and dynamic protocols

`algorithms` supplies reusable QFT/inverse QFT, phase estimation, Deutsch–Jozsa
parity oracles, single-target Grover, generalized Toffoli, graph MaxCut QAOA,
teleportation and coherent odd-repetition recovery. Builders retain the ordinary
`Circuit`, symbolic bindings and operation labels. `append_qft` composes with an
existing circuit; all wires follow the register's big-endian convention.

`protocol::Protocol` references ordinary circuit operations and explicitly adds
projective measurements and initialized classical conditions. `BranchExecution`
executes a supplied outcome branch incrementally, reports its cumulative
probability, and normalizes the actually collapsed state. Impossible branches are
errors. This is explicit branch execution, not random shot sampling or a claim
that requested measurement outcomes occur deterministically.

## Package and repository

This package owns `src/`, integration `tests/`, simulator `examples/`, and the
executable-only `support/device.rs` helper. From a repository checkout:

```sh
cargo run --locked -p burn_quantum --example bell
cargo test --locked -p burn_quantum
cargo check --locked -p burn_quantum --no-default-features
cargo run --locked -p burn_quantum --features wgpu --example wgpu_smoke
```

The unpublished sibling `burn_quantum_example` package contains single-file
applications, including canonical circuits, VQE, QAOA, classifiers, a Born
machine, hybrid regression, Grover SAT, QN-SPSA VQE, physical photonic optimization,
finite-boundary QEC studies, magic-state distillation and distributed MPS workloads.
Run it from a repository checkout:

```sh
cargo run --locked -p burn_quantum_example --bin qnspsa_vqe
cargo run --locked -p burn_quantum_example --bin fbqc_bell_swap
```

See the [API documentation](https://docs.rs/burn_quantum),
[example suite](https://github.com/mosure/burn_quantum/tree/main/crates/burn_quantum_example),
[guides and validation records](https://github.com/mosure/burn_quantum/tree/main/docs),
and [changelog](https://github.com/mosure/burn_quantum/blob/main/CHANGELOG.md).

The separate [`burn_quantum_visualization`](https://crates.io/crates/burn_quantum_visualization)
crate provides a native and browser explorer for these experiments, with Bloch
spheres, probability/phase disks, circuit diagrams and photonic timelines.
It requires Rust 1.97.1; the core crate remains usable with Rust 1.95.
Try the [interactive gallery](https://mosure.github.io/burn_quantum/).

## License

MIT OR Apache-2.0. Both license texts are included in this package.