Metadata-Version: 2.4
Name: rephon
Version: 1.0.0
Summary: Rephon Computing — Simulate the Physics of Rephasing Computation
Author-email: "Dr. Zuhair Ahmed" <info@cetqac.org>
Maintainer: CETQAC — Centre of Excellence for Technology, Quantum and AI
License: MIT
Project-URL: Homepage, https://www.cetqac.org
Project-URL: Documentation, https://www.cetqac.org/rephon
Project-URL: Repository, https://github.com/cetqac/rephon
Keywords: quantum,rephasing,photon-echo,phonon-echo,spin-echo,coherence,fourier,signal-processing,reservoir-computing,maxwell-bloch,analog-computing,rephon,CETQAC
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Provides-Extra: viz
Requires-Dist: matplotlib>=3.4; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.4; extra == "dev"
Dynamic: license-file

# Rephon Computing

### Simulate the Physics of Rephasing Computation

[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue)](https://pypi.org/project/rephon/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)

**A product by CETQAC — The Centre of Excellence for Technology, Quantum and AI (Canada).**
**Founded by Dr. Zuhair Ahmed · 2026.**

---

## Install

```bash
pip install rephon
```

That's it. The only dependencies are NumPy and SciPy.

---

## What is Rephon Computing?

**Rephon Computing** is a computational paradigm whose physical substrate is the
spontaneous **rephasing** of an inhomogeneously broadened ensemble of two-level
systems — the phenomenon behind the **phonon echo**, **photon echo**, and **spin
echo**. The phonon echo was first measured at Bell Laboratories in 1976 (Golding
& Graebner) and has been reproduced for fifty years.

This package, **`rephon`**, is the **Rephon Computing Simulator (RCS)**: a
classical, state-vector emulator of the Rephon machine. It implements all
**fifteen Rephon gates**, every one derived directly from the optical
**Maxwell–Bloch equations** — no pseudocode, no hand-waving. You can build
circuits, run the flagship algorithms, add realistic noise, and develop your own
rephasing-based algorithms today, before physical hardware exists.

### The core idea in one paragraph

Drive an ensemble of oscillators that each have a slightly different frequency.
They start in step, then dephase until the signal vanishes — but the phase of
every oscillator still records the input. Apply a conjugating pulse and they
**rephase**, spontaneously reconstructing the signal. The state of the machine is
a complex function over a frequency band, **ψ(Δ)**, discretized into **N = W/δ**
spectral cells called **rephons** (W = inhomogeneous bandwidth, δ = single-emitter
linewidth). The machine natively computes **Fourier transforms, correlations,
convolutions and time-reversals**, each in a single physical operation.

### Why use it?

- **Constant-time transforms** — an N-point DFT or correlation in *one* rephon
  cycle (O(1) physical depth), versus O(N log N) digital operations.
- **Analog precision** — the state lives in continuous phase, not fixed-width bits.
- **Built-in static-error cancellation** — static disorder (manufacturing spread,
  fixed offsets) is cancelled *exactly* by the rephasing. Only dynamic noise needs
  correction.
- **A real, buildable physics** — the substrate (rare-earth-doped crystals,
  spin ensembles) already exists in laboratories worldwide.

### Honest scope

In the **linear regime**, native problems lie in classical **P**; the advantage is
throughput, energy, and error-immunity — *not* a complexity-class speedup over
quantum computing. In the **nonlinear (reservoir) regime**, the system is a
universal approximator of temporal maps; its exact computational power is an open
research problem. This package lets you explore both.

---

## Quick start — your first Rephon circuit

```python
import numpy as np
from rephon import RephonState

# 1) Build a machine: N spectral cells (rephons), bandwidth W = 1 GHz
rcs = RephonState(N=128, W=1e9, T2=1e-3, T1=100e-3)

# 2) Make an input signal (a Gaussian-modulated tone)
k = np.arange(128)
f = np.exp(-((k - 64) ** 2) / (2 * 12 ** 2)) * np.exp(2j * np.pi * k * 5 / 128)

# 3) Run the canonical rephasing circuit:  W -> E -> Pi -> E -> M
#    (write, evolve, conjugate, evolve, read)
signal = (rcs
          .W(f)          # Gate 6  — write the input into the rephon state
          .E(50e-6)      # Gate 1  — free evolution (dephasing) for 50 us
          .Pi()          # Gate 3  — broadband conjugation (the rephasing pulse)
          .E(50e-6)      # Gate 1  — free evolution (rephasing) for 50 us
          .M())          # Gate 15 — heterodyne readout (returns s(t))

print("Output peaks at sample:", np.argmax(np.abs(signal)))
```

### Compute a DFT in one cycle

```python
from rephon import rephon_dft
spectrum = rephon_dft(f)                 # forward DFT, fidelity 1.0 vs numpy
```

### Single-shot matched filtering (the RESONANCE algorithm)

```python
from rephon import RESONANCE
template = f
signal   = f * np.exp(2j * np.pi * k * 20 / 128)   # template shifted by lag 20
xcorr    = RESONANCE(template, signal)             # one rephon cycle
print("Detected lag near:", np.argmax(np.abs(xcorr)))
```

---

## The fifteen gates — what each does and where you use it

Every program is a sequence of gates ending in a readout. Use this table to pick
the right gate. Gates are grouped into five families.

### Family 1 — Evolution

| Gate | Call | What it does | When you use it |
|------|------|--------------|-----------------|
| **E** | `rcs.E(t)` | Free evolution: each cell precesses at its detuning, `ψk → ψk·e^{iΔk t}`. Includes T2 decay. | Build delays; the dephasing/rephasing intervals; the DFT kernel. |
| **Φ** | `rcs.Phi(phi)` | Global phase: `ψk → ψk·e^{iφ}`. | Set a reference phase before readout; phase-keyed encoding. |

### Family 2 — Refocusing

| Gate | Call | What it does | When you use it |
|------|------|--------------|-----------------|
| **Π** | `rcs.Pi()` | **The core gate.** Broadband conjugation `ψk → ψk*` (antiunitary). Inverts every cell. | The rephasing pulse — turns dephasing into rephasing. Every echo uses it. |
| **Π(B)** | `rcs.PiB(lo, hi)` | Conjugates only cells in the band `[lo, hi]`. | Multi-band protocols; selective recall of a sub-band. |

### Family 3 — Rotation & Write

| Gate | Call | What it does | When you use it |
|------|------|--------------|-----------------|
| **R** | `rcs.R(k, theta, phi)` | Frequency-selective Bloch rotation of a single cell `k`. | Fine state preparation; addressing one rephon. |
| **W** | `rcs.W(f)` | **The input gate.** Encodes spectral profile `f` into the state. | Start of *every* program — write your data here. |

### Family 4 — Spectral Shaping

| Gate | Call | What it does | When you use it |
|------|------|--------------|-----------------|
| **S** | `rcs.S(h)` | Pure-phase spectral mask `ψk → ψk·h(Δk)`, `|h|=1`. | Dispersion compensation; fractional-Fourier; chirp filters. |
| **A** | `rcs.A(a)` | Amplitude window `ψk → ψk·a(Δk)`, `0≤a≤1`. | Reduce spectral leakage before readout (e.g. Hann window). |
| **CHIRP** | `rcs.CHIRP(alpha, Omega_peak)` | Adiabatic broadband inversion (Landau–Zener). Robust alternative to Π. | Wide-bandwidth refocusing when Π fidelity is limited. |

### Family 5 — Multi-Pulse, Nonlinear & Readout

| Gate | Call | What it does | When you use it |
|------|------|--------------|-----------------|
| **STIM** | `rcs.STIM(h, x, t1, Tw, t2)` | Three-pulse stimulated echo → cross-correlation of `h` and `x` via a long-lived grating. | Single-shot matched filtering (radar, comms, transient search). |
| **CPMG** | `rcs.CPMG(n, tau)` | `n` π-pulses `[E(τ)·Π]ⁿ·E(τ)`; extends coherence vs slow noise. | Protect a computation against low-frequency dephasing. |
| **XY16** | `rcs.XY16(tau)` | 16-pulse phase-cycled decoupling, robust to pulse-area errors. | Decoupling when π-pulse fidelity is below ~99%. |
| **GRAPE_OC** | `rcs.GRAPE_OC(U_target, T)` | Gradient-ascent optimal-control pulse for a target transformation. | Compile an arbitrary target operation to a physical pulse. |
| **NL** | `rcs.NL(Omega_t, dt)` | Full nonlinear Maxwell–Bloch (RK4); returns a reservoir feature trajectory. | Reservoir computing: temporal classification, sequence tasks. |
| **M** | `rcs.M(g, SNR_dB)` | **Terminal readout.** Returns `s(t) = 𝓕[g·ψ](t)`. Optional SNR noise. | End of every program — get your classical output. |

> **Rule of thumb:** start with **W** (write your data), shape with **E / S / A /
> Π**, refocus/decouple with **Π / CPMG / XY16 / CHIRP**, and finish with **M**
> (or use **STIM** for one-shot correlation). For learning tasks, use **NL** then
> train a linear readout on the returned trajectory.

You can print the catalogue any time:

```python
import rephon
for name, doc in rephon.GATES.items():
    print(f"{name:9s} — {doc}")
```

---

## The fluent circuit builder

```python
from rephon import RephonCircuit
import numpy as np

f = np.exp(-np.linspace(-3, 3, 256) ** 2).astype(complex)

out = (RephonCircuit(N=256, W=1e9)
       .W(f)
       .CPMG(4, 1e-6)     # decouple while we hold the state
       .E(50e-6)
       .Pi()
       .E(50e-6)
       .M(SNR_dB=30))     # read out with a 30 dB heterodyne SNR
```

---

## Realistic noise

```python
from rephon import RephonState, RephonNoiseModel

rcs   = RephonState(N=128, W=1e9)
noise = RephonNoiseModel(
    T2_noise_frac=0.05,             # 5% cell-to-cell T2 spread
    spectral_diffusion_sigma=1e5,   # 100 kHz rms spectral diffusion
    readout_SNR_dB=25,              # 25 dB readout SNR
    seed=42,
)

rcs.W(f)
noise.apply_spectral_diffusion(rcs, dt=1e-7)   # apply during storage
s = rcs.M()
s = noise.apply_readout_noise(s)               # add detector noise
```

---

## Standard algorithms included

| Function | What it computes |
|----------|------------------|
| `rephon_dft(f)` | N-point DFT of `f` in one rephon cycle (fidelity 1.0 vs NumPy). |
| `RESONANCE(h, x)` | Single-shot cross-correlation / matched filtering of `x` against template `h`. |
| `rephon_convolve(a, b)` | Circular convolution of `a` and `b` via the rephasing correlator. |

---

## The physics, briefly

The state is the off-diagonal density-matrix element **ψk = ρ̃eg(Δk)** of spectral
cell *k*. In the weak-drive (linear) regime each cell obeys

```
dψk/dt = i·Δk·ψk − ψk/T2 + i·Ω(t)/2
```

and in the strong-drive (nonlinear) regime the full Bloch equations for the vector
(u, v, w) apply — exactly what the **NL** gate integrates by 4th-order Runge–Kutta.
The **Rephon Transform Theorem** states that the write→evolve→conjugate→read
sequence computes the DFT, correlation, convolution and time-reversal each in a
single physical operation. Machine size is **N = W/δ** — for rare-earth crystals
(e.g. Eu³⁺:Y₂SiO₅ at 2 K) this reaches **N ≈ 10⁶–10⁷**.

---

## Citation

If you use Rephon Computing in your work, please cite:

> Ahmed, Z. (2026). *Rephon Computing: A Computational Framework Built on
> Coherence Rephasing in Inhomogeneous Media.* CETQAC — The Centre of Excellence
> for Technology, Quantum and AI (Canada).

```bibtex
@software{rephon2026,
  author    = {Ahmed, Zuhair},
  title     = {Rephon Computing: Simulate the Physics of Rephasing Computation},
  year       = {2026},
  version   = {1.0.0},
  publisher = {CETQAC},
  note      = {Centre of Excellence for Technology, Quantum and AI, Canada}
}
```

---

## License

MIT © 2026 Dr. Zuhair Ahmed — CETQAC (The Centre of Excellence for Technology,
Quantum and AI, Canada).
