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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
# $\psi$: A Quantum Computational Toolkit
$\psi$ is a powerful quantum computing toolkit designed for simulating quantum circuits and wavefunction dynamics on classical hardware.
## Features
### Quantum Gates
**Clifford Gates:**
- Single-qubit: H, X, Y, Z, S
- Two-qubit: CNOT, CZ, SWAP
- Three-qubit: CCNOT (Toffoli), CSWAP (Fredkin)
**Non-Clifford Gates:**
- Fixed: T, $S^\dagger$, $T^\dagger$, $\sqrt{X}$, $\sqrt{X}^\dagger$
- Parametric rotations: $R_x(\theta)$, $R_y(\theta)$, $R_z(\theta)$, $P(\theta)$
- General unitaries: $U_1(\lambda)$, $U_2(\phi, \lambda)$, $U_3(\theta, \phi, \lambda)$
- Controlled parametric: $CR_x(\theta)$, $CR_y(\theta)$, $CR_z(\theta)$, $CP(\theta)$
**Custom Gates:**
- Define gates from unitary matrices
- Build composite gates from sequences of operations
### Composable Runtime System
Build custom execution pipelines by combining optimisation features:
| Feature | Description |
|---------|-------------|
| `.batched()` | Kernel batching with gate fusion |
| `.simd()` | SIMD acceleration (AVX-512/AVX2/NEON) |
| `.structure_aware()` | Commutation analysis and advanced fusion |
| `.parallel()` | Multi-threaded execution |
| `.with_threshold(n)` | Set parallel threshold (default: 8 qubits) |
**Predefined Runtimes:**
- `Runtime::BasicRT` / `BasicRTMT` — Direct state vector simulation
- `Runtime::BatchedRT` / `BatchedRTMT` — Batched kernel execution
- `Runtime::SimdRT` / `SimdRTMT` — Batched + SIMD
- `Runtime::StructureAwareRT` / `StructureAwareMT` — Structure-aware + SIMD
- `Runtime::optimal()` — Structure-aware + SIMD + parallel
### SIMD Acceleration
Automatic detection and use of platform-specific SIMD instructions:
- **AVX-512**: Modern Intel/AMD processors
- **AVX2+FMA**: Older x86_64 processors
- **NEON**: ARM processors (Apple Silicon, etc.)
- **Scalar fallback**: Universal compatibility
### Kernel Optimisations
**Batching:**
- Groups consecutive single-qubit gates on the same qubit
- Fuses gate matrices to reduce operations
- Typically achieves 30–50% kernel reduction
**Structure-Aware:**
- Gate type detection (diagonal, non-diagonal, controlled)
- Commutation analysis for reordering
- Multi-pass fusion until convergence
- Execution layer grouping for parallelism
### Noise Channels (Density Matrix)
Realistic quantum noise simulation using Kraus operators:
| Channel | Description |
|---------|-------------|
| `depolarising(p)` | Random Pauli error with probability $p$ |
| `amplitude_damping(γ)` | Energy decay ($T_1$ relaxation) |
| `phase_damping(γ)` | Phase decoherence ($T_2$ dephasing) |
| `bit_flip(p)` | $X$ error with probability $p$ |
| `phase_flip(p)` | $Z$ error with probability $p$ |
| `bit_phase_flip(p)` | $Y$ error with probability $p$ |
```rust
use libpsi_core::{DensityMatrix, NoiseChannel};
// Create density matrix from circuit state
let dm = DensityMatrix::from_state_vector(&state_vec);
// Apply noise
let noise = NoiseChannel::depolarising(0.05);
dm.apply_noise_channel(&noise, 0); // Apply to qubit 0
// Check properties
println!("Purity: {}", dm.purity()); // 1.0 = pure, <1.0 = mixed
println!("Fidelity: {}", dm.fidelity_with_pure_state(&ideal_state));
```
## Project Structure
- **`libpsi-core`**: Core quantum simulation library
- `core`: Quantum gates, circuits, registers, and runtimes
- `maths`: Complex numbers, vectors, matrices, SIMD operations
- **`libpsi-visualizer`**: Circuit visualisation (ASCII horizontal/vertical)
- **`tester`**: Comprehensive test suite and benchmarks
## Quick Start
```rust
use libpsi_core::{QuantumCircuit, Runtime};
fn main() {
let mut circuit = QuantumCircuit::new(3);
// Build a GHZ state
circuit.h(0).cnot(0, 1).cnot(0, 2);
// Execute with optimal settings
circuit.compute_with_config(Runtime::optimal());
println!("{}", circuit.state());
}
```
### Composable Runtimes
```rust
use libpsi_core::{QuantumCircuit, RuntimeConfig};
let mut circuit = QuantumCircuit::new(8);
// ... add gates ...
// Combine features as needed
let config = RuntimeConfig::new()
.structure_aware()
.simd()
.parallel();
circuit.compute_with_config(config);
```
### Parametric Gates
```rust
use std::f64::consts::PI;
circuit
.rx(0, PI / 4.0) // Rotation around X
.ry(0, PI / 3.0) // Rotation around Y
.rz(1, PI / 2.0) // Rotation around Z
.crz(0, 1, PI / 4.0); // Controlled-Rz
```
### Custom Gates
```rust
use libpsi_core::{CustomGateBuilder, CustomGate, complex, matrix};
// From operations
let bell_gate = CustomGateBuilder::new("BELL", 2)
.h(0)
.cnot(0, 1)
.build();
// From a unitary matrix
let sqrt_x_matrix = matrix!(
[complex!(0.5, 0.5), complex!(0.5, -0.5)];
[complex!(0.5, -0.5), complex!(0.5, 0.5)]
);
let sqrt_x = CustomGate::from_matrix("√X", sqrt_x_matrix);
```
## Running Tests
```bash
cargo run --package tester --release # All tests
cargo run --package tester --release -- clifford
cargo run --package tester --release -- non-clifford
cargo run --package tester --release -- kernels
cargo run --package tester --release -- simd
cargo run --package tester --release -- bench
cargo run --package tester --release -- help
```
## Disclaimer
This project is under active development. Features and APIs may change.
## License
This project is made available under the Apache License, Version 2.0, allowing free use, modification, and distribution with proper attribution. Community contributions, improvements, and research collaborations are encouraged. Full licensing terms can be found in [LICENSE](LICENSE).
|
