# $\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 psi::{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

`psi` is a single crate. the library lives under `src/`:

- **`core`**: quantum gates, circuits, registers, and runtimes
- **`maths`**: complex numbers, vectors, matrices, simd operations
- **`visualizer`**: circuit visualisation (ascii horizontal/vertical)

the comprehensive test suite and benchmarks live in **`examples/tester`**.

## quick start

```rust
use psi::{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 psi::{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 psi::{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 --release --example tester           # All tests
cargo run --release --example tester -- clifford
cargo run --release --example tester -- non-clifford
cargo run --release --example tester -- kernels
cargo run --release --example tester -- simd
cargo run --release --example tester -- bench
cargo run --release --example tester -- 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).