toroidal-noise 0.2.0

# toroidal-noise

A small Rust crate for single-qubit quantum noise channels and 2×2
density-matrix simulation, including a phenomenological dephasing
parameterization driven by the spectral gap of an `n × n` discrete-torus
Laplacian.

## Channels

| Function | Parameters | Kraus operators |
|----------|-----------|-----------------|
| `dephasing(gamma)` | `gamma ∈ [0, 1]` | 2 |
| `amplitude_damping(gamma)` | `gamma ∈ [0, 1]` | 2 |
| `depolarizing(p)` | `p ∈ [0, 1]` | 4 (I, X, Y, Z) |
| `toroidal_dephasing(gamma, n, alpha)` | `gamma ∈ [0, 1]`, `n >= 2`, `alpha > 0` | 2 |

Plus utility functions:

- `spectral_gap(n)` — `λ₁(n) = 2 − 2cos(2π/n)`, the smallest non-zero
  eigenvalue of the cycle-graph Laplacian (also the spectral gap of the
  `n × n` torus).
- `effective_gamma(gamma, grid_n, alpha)` — the phenomenological mapping
  `γ · λ₁ / (λ₁ + α)`.

## Status

**`toroidal_dephasing` is a phenomenological model, not a derivation from
physical first principles.** It is a thin wrapper that delegates to
`dephasing(effective_gamma(γ, n, α))`. The mapping is offered as a tunable
parameterization for studying lattice-geometry-dependent dephasing in
simulations; `alpha` is a knob, not a physically calibrated coupling.
Treat results as exploratory unless you have an independent physical
justification.

The other channels (`dephasing`, `amplitude_damping`, `depolarizing`) are
standard textbook noise channels and have no such caveat.

## Usage

```rust
use toroidal_noise::{
    apply_channel, apply_unitary, dephasing, effective_gamma,
    toroidal_dephasing, HADAMARD, RHO_ZERO,
};

// Start with |+⟩
let rho = apply_unitary(&RHO_ZERO, &HADAMARD);

// Two equivalent ways to apply toroidal-parameterized dephasing:

// 1. Named wrapper
let rho_a = apply_channel(&rho, &toroidal_dephasing(0.5, 12, 1.0));

// 2. Explicit composition (preferred when readers should see the parameterization)
let rho_b = apply_channel(&rho, &dephasing(effective_gamma(0.5, 12, 1.0)));

// Off-diagonal coherence comparable in both
assert!((rho_a[0][1].re - rho_b[0][1].re).abs() < 1e-12);
```

## Math

The discrete `n × n` torus is the graph product `Cₙ □ Cₙ` of two cycle
graphs. Eigenvalues of its Laplacian are pairwise sums of cycle-graph
eigenvalues:

```text
λ_{j,k}(n) = (2 − 2cos(2πj/n)) + (2 − 2cos(2πk/n)),  0 ≤ j, k < n
```

The smallest non-zero eigenvalue, attained at `(1, 0)` or `(0, 1)`, is

```text
λ₁(n) = 2 − 2cos(2π/n)
```

The library uses this in the saturation:

```text
γ_eff(γ, n, α) = γ · λ₁(n) / (λ₁(n) + α)
```

| `grid_n` | `λ₁(n)` | `γ_eff/γ` (α=1) |
|----------|---------|------------------|
| 4        | 2.000   | 0.667            |
| 6        | 1.000   | 0.500            |
| 8        | 0.586   | 0.369            |
| 12       | 0.268   | 0.211            |
| 32       | 0.0383  | 0.0369           |
| 64       | 0.00964 | 0.00955          |

## Limitations and caveats

- **Phenomenological direction.** `γ_eff = γ · λ₁ / (λ₁ + α)` reduces
  dephasing as `λ₁ → 0`. This direction does not correspond to any
  particular standard physical mechanism — typical "spectral-gap
  protection" arguments in many-body physics suppress noise as the gap
  *increases*, not as it shrinks. Do not interpret results from this
  parameterization as a physical prediction without independent
  justification.
- **No T₂ / hardware claim.** This crate does not derive or claim any
  hardware T₂-extension figure. If you need such numbers, they must come
  from a calibrated device model, not from this parameterization.
- **Single-qubit channels only.** The spectral-gap calculation references
  an `n × n` lattice geometry, but every channel here acts on a single
  qubit. There is no multi-qubit lattice noise correlation.

## Related

- A PennyLane-compatible Python sibling is published as
  [`pennylane-toroidal-noise`](https://pypi.org/project/pennylane-toroidal-noise/),
  which delegates to `qml.PhaseDamping`.

## License

MIT.