Metadata-Version: 2.4
Name: coheroncompute
Version: 1.0.0
Summary: Coheron Computing: a computational framework built on coherence rephasing in inhomogeneous media
Author-email: CETQAC <info@coheroncomputing.com>
License: MIT
Project-URL: Homepage, https://www.coheroncomputing.com
Project-URL: Documentation, https://www.coheroncomputing.com
Project-URL: Source, https://www.coheroncomputing.com
Keywords: coheron computing,photon echo,phonon echo,analog computing,reservoir computing,fourier transform,matched filter,quantum,physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: viz
Requires-Dist: matplotlib>=3.3; extra == "viz"
Dynamic: license-file

# Coheron Computing

### A Computational Framework Built on Coherence Rephasing in Inhomogeneous Media

[![PyPI](https://img.shields.io/badge/pip-coheroncompute-blue)]()
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()

**`coheroncompute`** is the reference Python stack for **Coheron Computing** — a
programmable computational paradigm whose physical substrate is the spontaneous
rephasing of coherence in an inhomogeneously broadened ensemble of two-level systems
(a real, replicated physical effect first measured in 1976). It is to Coheron
Computing what Qiskit is to quantum computing: a simulator core, a gate library, a
circuit model, an algorithm library, a backend interface, and a benchmarking suite —
everything needed to write, run, and verify Coheron programs on a laptop today, and on
real hardware when it exists.

## The three pillars of Coheron

Coheron is built in three layers, each named under one brand:

- **Coheron Physics** — the foundational description. The coherence-rephasing effect
  in an inhomogeneously broadened ensemble of two-level systems, the physical
  phenomenon first measured in 1976, and the substrates that host it (rare-earth
  crystals, spins).
- **Coheron Mechanics** — the mathematical formalism. The state `ψ(Δ) ∈ ℂ^N` over `N`
  *coherons* (the fundamental unit), the generating gate set `{ E(t), Π, R }`, the
  readout `M`, the **Coheron Transform Theorem**, and the complexity classes
  (`CoheronP`, `CoheronBQP`).
- **Coheron Computing** — the computational process. Circuits, algorithms, backends,
  and benchmarks. This package, `coheroncompute`, implements this layer.

> Coheron Computing does **not** claim to exceed quantum computing in complexity
> class. In the linear regime its native problems lie in classical **P**; its
> advantage there is constant-time transforms, analog precision, and built-in
> cancellation of static disorder. The nonlinear (reservoir) regime is a universal
> approximator of temporal maps whose exact complexity is an open problem. This
> library is honest about that boundary everywhere.

---

## Install

```bash
pip install coheroncompute
# optional pulse-schedule plots:
pip install coheroncompute[viz]
```

Requires only NumPy (matplotlib optional for visualization).

## 60-second quickstart

```python
import numpy as np
from coheroncompute import CoheronCircuit, coheron_fft, coheron_correlate

# 1) Native Fourier transform — the readout *is* the transform
x = np.random.randn(1024) + 1j*np.random.randn(1024)
spectrum = coheron_fft(x)                   # == np.fft.fft(x, norm="ortho")

# 2) Build a two-pulse rephasing circuit by hand
c = CoheronCircuit(N=1024, bandwidth=1e9, T2=1e-3, snr_db=30)
c.write(x).evolve(50e-6).conjugate().evolve(50e-6)
result = c.read()
print(result.fidelity, result.peak())

# 3) RESONANCE matched filter — locate a template in a signal in one coheron cycle
template = np.random.randn(64) + 1j*np.random.randn(64)
signal = np.zeros(2048, complex); signal[900:964] = template
y = coheron_correlate(signal, template, N=2048)
print("template found at index", int(np.argmax(np.abs(y))))
```

## The state model (Coheron Mechanics)

Coheron Computing has two regimes, so the simulator has two state representations:

- **Level A — coherence-vector model (linear regime).** The state is `psi ∈ ℂ^N`, one
  complex amplitude per *coheron* (spectral cell). Exact, fast, FFT-based; the working
  model for all transform-class programs. Classically simulable, consistent with
  `CoheronP ⊆ P`.
- **Level B — Bloch-ensemble model (nonlinear regime).** Per-cell two-level states,
  required for saturation, higher-order rephasing terms, and the reservoir regime.

The detuning grid spans the band `B = [−W/2, W/2]` with `N = W/δ` resolvable cells,
where `W` is the inhomogeneous bandwidth and `δ` the homogeneous linewidth.

## The gate set

Everything derives from the generating set `{ E(t), Π, R }` plus the readout `M`.

| Gate | API | Action on state | Class |
|------|-----|-----------------|-------|
| INIT | `.reset()` | `ψ ← 0` | preparation |
| WRITE | `.write(a)` | `ψ ← a` | preparation (π/2 pulse) |
| E(τ) | `.evolve(tau)` | `ψ_k ↦ ψ_k e^{iΔ_k τ}` | diagonal unitary |
| Π | `.conjugate(phase)` | `ψ_k ↦ e^{iϕ} ψ*_k` | **antiunitary** |
| R | `.rotate(k, θ, ϕ)` | SU(2) rotation on coheron k | unitary |
| P | `.phase_mask(φ⃗)` | `ψ_k ↦ e^{iφ_k} ψ_k` | diagonal unitary |
| A | `.amp_mask(m⃗)` | `ψ_k ↦ m_k ψ_k` | attenuating |
| M | `.read()` | `s = F(g·ψ)` | measurement (Fourier) |
| REFOCUS | `.refocus(tau)` | `E(τ/2)·Π·E(τ/2)` | control |
| CPMG | `.cpmg(t, n)` | n-pulse decoupling train | control |

`Π` and time-reversal apply **complex conjugation**, not a matrix product — they are
antilinear. The readout `M` applies an N-point Fourier transform *for free* (it is the
measurement boundary, not a synthesized circuit).

## The algorithm library (Coheron Computing)

The "hello-world" programs of Coheron Computing:

```python
from coheroncompute import (coheron_fft, coheron_convolve, coheron_correlate,
                            coheron_time_reverse, coheron_reservoir, train_reservoir)

coheron_fft(signal)                    # native Fourier transform (one coheron cycle)
coheron_convolve(signal, kernel)       # circular convolution (two-pulse rephasing)
coheron_correlate(signal, template)    # matched filter / RESONANCE (three-pulse rephasing)
coheron_time_reverse(signal)           # time-reversal / phase conjugation (Π in time)
W = train_reservoir(signals, labels)   # train a nonlinear-regime classifier
coheron_reservoir(signal, W)           # run it
```

## Backends — write once, run anywhere

The circuit is independent of where it runs, exactly as in Qiskit:

```python
circuit.run(backend="simulator")   # classical simulation (default, available now)
circuit.run(backend="hardware")    # AWG + heterodyne detector (Stage-1 roadmap)
```

The hardware contract is fixed now so nothing changes when a device is connected:
compile `circuit.schedule` into an AWG pulse program, fire it at a cryogenic
rare-earth substrate (e.g. Eu³⁺:Y₂SiO₅), and return the heterodyne-detected rephased
signal as a `CoheronResult`.

## Benchmarks — verify the simulator matches theory

```python
from coheroncompute import benchmarks
benchmarks.run_all()
```

- **FFT fidelity** — the readout reproduces the exact DFT.
- **Static cancellation** — the framework's falsifiable prediction, made runnable:
  under increasing static detuning disorder, the refocused fidelity stays flat
  (static disorder cancels exactly at `t = 2τ`), while a no-refocus control collapses.
- **Coherence decay** — recover `T₂` from the rephasing amplitude vs. delay.
- **RESONANCE throughput** — matched-filter correlations per second.

A correct implementation keeps the static-cancellation fidelity at ≈1.0 across all
disorder levels — the signature property that distinguishes Coheron Computing from a
naive "rephasing as lossy memory" picture.

## What is honest scope, and what is not claimed

- The **mathematics** (the Coheron Transform Theorem) is unconditional given the
  Maxwell–Bloch equations.
- The **linear regime** is provably in **P**; the advantage is physical-time and
  energy, not a complexity-class separation.
- The **nonlinear regime's** computational power is an **open problem**; this library
  implements it but attaches no complexity claim to it.
- The **hardware backend** is not yet available — it is Stage 1 of the experimental
  roadmap. The simulator is exact and runs today.

## Citation

```
Coheron Computing: A Computational Framework Built on Coherence
Rephasing in Inhomogeneous Media. Founding Document v1.0, 2026. Software:
coheroncompute v1.0.
```

## License

MIT. © CETQAC. See `LICENSE`.

---

*Coheron — a phenomenon made formal (Coheron Physics), a mathematics made precise
(Coheron Mechanics), and a machine made programmable (Coheron Computing).*
