Metadata-Version: 2.4
Name: thermoc-erasure
Version: 0.2.0
Summary: ThermoC `erasure`: reversibility analysis, Landauer erased-bit accounting, Bennett scheduling, and adiabatic execution planning for computation graphs
Author-email: David Johnson <sportsmedicineuae@gmail.com>
License: Proprietary
Project-URL: Repository, https://github.com/dmjdxb/thermoc-erasure
Project-URL: Documentation, https://github.com/dmjdxb/thermoc-erasure/blob/main/MANUAL.md
Keywords: thermodynamic-computing,landauer,reversible-computing,energy,compiler,p-bit,entropy-production
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: torch
Requires-Dist: torch<2.7,>=2.4; extra == "torch"
Requires-Dist: transformers<4.60,>=4.50; extra == "torch"
Provides-Extra: pro
Requires-Dist: cryptography>=42; extra == "pro"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: scipy>=1.12; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Dynamic: license-file

# thermoc-erasure

**ThermoC `erasure`** — reversibility analysis, Landauer erased-bit
accounting, erasure-minimizing graph rewrites (uncomputation + Bennett
pebble scheduling), and adiabatic execution planning for computation
graphs. Part of the EnergyIR compiler suite.

Every logically irreversible operation has a hard physical minimum energy
cost of k_B·T·ln2 per erased bit (Landauer, 1961). This compiler:

- **Phase A — measure & certify:** counts the erased bits of every op in a
  PyTorch or ThermoIR graph, attributes a certified joule floor per op,
  ranks irreversibility hotspots, and emits signed physics certificates
  (distribution-free reversibility claims + ensemble-bound floor claims).
- **Phase B — restructure & plan:** removes erasures via reversible
  substitutions, autodiff-style uncomputation, and exact Bennett pebble
  scheduling under user memory/latency budgets, then emits adiabatic
  execution plans with provably optimal per-op time allocation
  (τ\* ∝ √a, Sivak–Crooks-compatible shared engine). Non-adiabatic
  backends are refused, with the physics explanation — no false savings
  claims.

## Install

```sh
pip install .                 # numpy-only core: worstcase mode, ThermoIR, planner
pip install ".[torch]"        # + PyTorch fx frontend (ResNet/GPT-style models)
pip install ".[dev]"          # + pytest, hypothesis, scipy (test suite)
```

## Quickstart

```sh
thermoc erasure profile resnet50 --mode empirical --out out/   # needs [torch]
thermoc erasure certify out/erasure_report.json
thermoc erasure plan coupling_mlp --latency 10 --mem 8x        # numpy-only
thermoc erasure taxonomy --list
```

```python
from thermoc.erasure import profile, rewrite, plan, Budget

rep = profile(model, example_inputs, mode="empirical")   # Landauer floor + hotspots
g2, rw = rewrite(rep.graph, Budget(mem="4x", latency="2x"))
xp = plan(g2, "phal:pb64", latency_budget_s=1.0)         # adiabatic execution plan
```

See **[MANUAL.md](MANUAL.md)** for the complete end-to-end guide and the
physics reference card (every formula is mapped to the function that
implements it and the test that pins it).

## Guarantees enforced by the test suite (150 tests)

- Glauber entropy-production ledger is exact: telescoping identity to
  machine precision, and the **integral fluctuation theorem**
  ⟨e^(−Δs_tot)⟩ = 1 verified against an exactly-enumerated 4×4 ensemble.
- Bennett pebbling drops chain erasure **N·b → b** at the exactly
  predicted time/space cost (property-based).
- Planner prediction matches an independent simulated adiabatic backend
  within 2%; reversible-heavy benchmarks reach ≥5× dissipation reduction
  at 2× latency.
- Certificates are only ever marked valid in distribution-sound modes.

## Licensing & PRO tier

OSS-first, fail-open: **profiling, reports, taxonomy, and unsigned
certificates are free** and never require a license. The enterprise
surfaces are PRO-gated with the same offline ed25519 license the EnergyIR
suite uses (`ENERGYIR_LICENSE` env var or `~/.energyir/license`; no
network, no phone-home):

| Surface | Tier |
|---|---|
| `profile` (worstcase + empirical), reports, HTML, headroom | free |
| certificates (emitted, unsigned) | free |
| **signed** certificates | PRO |
| `rewrite()` — R1 substitutions / R2 uncompute / R3 Bennett pebbling | PRO |
| `plan()` — adiabatic execution planning | PRO |

A PRO license minted by the EnergyIR portal for ThermoIR unlocks erasure
too — same token, same entitlement. When the `energyir` package is
installed alongside, license verification delegates to it
(`energy.intelligence.licensing`) so there is exactly one code path.
See `integration/ENERGYIR_INTEGRATION.md` for the (tiny) suite-side hookup.

## Provenance

This project is standalone: ThermoIR (the EnergyIR item-4 prototype) is
vendored as a frozen snapshot under `src/thermoc/_vendor/thermoir/`; no
production EnergyIR code paths are imported or modified.

License: proprietary — see [LICENSE](LICENSE).
