Metadata-Version: 2.4
Name: pennylane-toroidal-noise
Version: 0.2.0
Summary: Phenomenological spectral-gap dephasing parameterization for PennyLane (delegates to qml.PhaseDamping)
Author-email: Sylvain Cormier <sylvain@paraxiom.org>
License: MIT
Project-URL: Homepage, https://github.com/Paraxiom/pennylane-toroidal-noise
Project-URL: Documentation, https://github.com/Paraxiom/pennylane-toroidal-noise#readme
Project-URL: Repository, https://github.com/Paraxiom/pennylane-toroidal-noise
Keywords: quantum,noise-channels,pennylane,toroidal,spectral-gap,dephasing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pennylane>=0.35.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# pennylane-toroidal-noise

A phenomenological dephasing parameterization for [PennyLane](https://pennylane.ai/),
where the effective dephasing rate is modulated by the spectral gap of an
`n × n` discrete-torus Laplacian.

This package is a thin wrapper over `qml.PhaseDamping`. It exposes:

- `spectral_gap(n)` — the smallest non-zero eigenvalue of the cycle-graph
  Laplacian, `λ₁(n) = 2 − 2cos(2π/n)`.
- `effective_gamma(gamma, grid_n, alpha)` — a one-parameter saturation of
  `gamma` against `λ₁`, returning `γ · λ₁ / (λ₁ + α)`.
- `ToroidalDephasing(gamma, grid_n, alpha, wires)` — a named channel whose
  Kraus operators are delegated to `qml.PhaseDamping.compute_kraus_matrices`
  with `effective_gamma(...)` as the rate.

## Status

**Phenomenological model, not a derivation from physical first principles.**
The spectral-gap-to-dephasing mapping `γ_eff = γ · λ₁ / (λ₁ + α)` is offered
as a tunable parameterization for studying lattice-geometry-dependent
dephasing in PennyLane simulations. `alpha` is a knob, not a physically
calibrated coupling. Treat results as exploratory unless you have an
independent physical justification for this mapping in your specific setting.

## Installation

```bash
pip install pennylane-toroidal-noise
```

Or from source:

```bash
git clone https://github.com/Paraxiom/pennylane-toroidal-noise
cd pennylane-toroidal-noise
pip install -e .[dev]
pytest
```

## Usage

### Recommended pattern — explicit composition

The cleanest way to use this library is to compose the spectral-gap
calculation with `qml.PhaseDamping` at the call site:

```python
import pennylane as qml
from pennylane_toroidal_noise import effective_gamma

dev = qml.device("default.mixed", wires=1)

@qml.qnode(dev)
def circuit(gamma):
    qml.Hadamard(wires=0)
    qml.PhaseDamping(effective_gamma(gamma, grid_n=12, alpha=1.0), wires=0)
    return qml.expval(qml.PauliX(0))
```

This makes the parameterization visible to anyone reading the circuit and
keeps the noise model standard (a `PhaseDamping` channel).

### Alternative — named operator

If you prefer a named operator for circuit-diagram readability or for
reusing `grid_n`/`alpha` across many call sites, use `ToroidalDephasing`:

```python
import pennylane as qml
from pennylane_toroidal_noise import ToroidalDephasing

dev = qml.device("default.mixed", wires=1)

@qml.qnode(dev)
def circuit(gamma):
    qml.Hadamard(wires=0)
    ToroidalDephasing(gamma, grid_n=12, alpha=1.0, wires=0)
    return qml.expval(qml.PauliX(0))
```

`ToroidalDephasing.compute_kraus_matrices` delegates to
`qml.PhaseDamping.compute_kraus_matrices`; `decomposition()` returns a
single `qml.PhaseDamping(effective_gamma(...))`.

## Math

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

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

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

```
λ_1(n) = 2 − 2cos(2π/n)
```

This is also the spectral gap of the cycle graph `C_n`. The library uses
this as the geometry parameter in the saturation:

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

| `grid_n` | `λ_1(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.** The mapping `γ_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. Users should not interpret results from
  this parameterization as a physical prediction without independent
  justification.
- **No T₂ / hardware claim.** This package does not derive or claim a
  hardware T₂-extension figure. Earlier framings that quoted specific
  microsecond-to-millisecond figures have been removed; if you need those
  numbers, they must come from a calibrated device model, not from this
  parameterization.
- **Single-qubit channel only.** The spectral-gap calculation references
  an `n × n` lattice geometry, but the channel itself acts on a single
  wire. There is no multi-qubit lattice noise correlation in this
  implementation.

## Related

- A pure-Rust companion crate is published as
  [`toroidal-noise`](https://crates.io/crates/toroidal-noise) for
  non-PennyLane use cases.

## License

MIT.
