thermoc-erasure 0.2.0__tar.gz

thermoc_erasure-0.2.0/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 David Johnson / EnergyIR. All rights reserved.
+
+This software and its accompanying documentation are proprietary.
+No permission is granted to use, copy, modify, distribute, or create
+derivative works of this software, in whole or in part, without prior
+written agreement from the copyright holder.
+
+The vendored ThermoIR snapshot under src/thermoc/_vendor/thermoir/ is a
+frozen copy of the author's own EnergyIR research-stack prototype and is
+covered by the same terms.

thermoc_erasure-0.2.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include MANUAL.md
+include pytest.ini
+recursive-include integration *.md
+recursive-include tests *.py
+recursive-include examples *.py

thermoc_erasure-0.2.0/MANUAL.md

@@ -0,0 +1,546 @@
+# ThermoC `erasure` — User Manual
+
+**Version 0.1.0 · July 2026 · EnergyIR**
+Reversibility analysis, Landauer erased-bit accounting, erasure-minimizing
+graph rewrites, and adiabatic execution planning for computation graphs.
+
+This manual covers the complete end-to-end workflow: profile a model →
+read the report → certify the floor → rewrite the graph → emit and
+simulate an adiabatic execution plan.
+
+---
+
+## 1. What this compiler does, in one page
+
+Every logically **irreversible** operation — every bit overwritten, rounded
+away, or discarded — has a hard physical minimum energy cost:
+
+> **Landauer bound.** Erasing ΔS bits into a bath at temperature T
+> dissipates heat Q ≥ k_B·T·ln2·ΔS.
+> At 300 K that is **2.87098 × 10⁻²¹ joules per bit** — a law of physics,
+> not an engineering estimate.
+
+Every logically **reversible** operation has no such floor: on
+adiabatic-capable hardware its dissipation can be driven toward zero by
+running it more slowly (E ≈ a/τ).
+
+`thermoc.erasure` is the compiler subsystem that exploits this:
+
+| Phase | What it does | Command |
+|---|---|---|
+| **A — Measure** | Counts the erased bits of every op in your graph, attributes a certified joule floor per op, ranks hotspots | `erasure profile` |
+| **A — Certify** | Emits a signed physics certificate of the floor | `erasure certify` |
+| **B — Restructure** | Removes erasures via substitutions, uncomputation, and Bennett pebble scheduling, under your memory/latency budgets | `rewrite()` |
+| **B — Plan** | Emits an adiabatic execution plan with provably optimal per-op time allocation; refuses non-adiabatic backends | `erasure plan` |
+
+**The honest line (PRD P4/N1), stated up front:** floors and headroom are
+physics *reference lines*. Actual joule savings are realized **only** on
+adiabatic-capable hardware via Phase B plans. The tool never claims energy
+savings on GPUs or conventional CMOS — it refuses, with an explanation.
+
+---
+
+## 2. Installation & environment
+
+The project is self-contained at:
+
+```
+/Users/davidjohnson/Desktop/Spectral/EnergyIR/thermoc_erasure/
+```
+
+It lives inside the production EnergyIR repository **without touching it**
+(vendored ThermoIR snapshot, read-only borrows only).
+
+**Requirements:** Python ≥ 3.11 with numpy. Optional: `torch` +
+`transformers` (for the PyTorch frontend and neural-net demos),
+`hypothesis` + `scipy` (dev/tests). On this machine everything is already
+present in `/opt/anaconda3/bin/python`.
+
+**No install needed** — run from the project folder:
+
+```sh
+cd "/Users/davidjohnson/Desktop/Spectral/EnergyIR/thermoc_erasure"
+
+# full test suite (150 tests, ~75 s; the physics gates live here)
+/opt/anaconda3/bin/python -m pytest
+
+# CLI without installing
+PYTHONPATH=src /opt/anaconda3/bin/python -m thermoc --help
+```
+
+Optionally, in your own venv: `pip install -e .` gives you the `thermoc`
+console command directly.
+
+Throughout this manual, `thermoc` means
+`PYTHONPATH=src /opt/anaconda3/bin/python -m thermoc` run from the project
+folder.
+
+---
+
+## 3. Quickstart: profile a model in 60 seconds
+
+### 3.1 Builtin demo targets
+
+```sh
+thermoc erasure profile resnet50   --mode empirical --out out_resnet
+thermoc erasure profile gpt2-block --mode worstcase --out out_gpt2
+thermoc erasure profile item2-chain --out out_item2
+```
+
+Example output (GPT-2 block, worstcase):
+
+```
+graph: GPT2Block  ops: 27  mode: worstcase
+Landauer floor: 8.1470e-14 J   erased bits: 2.8377e+07   sigma_env: 0 nats
+top hotspots:
+  3.613e-14 J   44.3%  gelu           torch_fx:0025:act
+  2.709e-14 J   33.3%  linear         torch_fx:0026:mlp_proj
+  1.411e-16 J    0.2%  softmax        torch_fx:0016:softmax
+  ...
+wrote json: out_gpt2/erasure_report.json
+wrote html: out_gpt2/erasure_report.html
+```
+
+Open `erasure_report.html` in any browser — it is fully self-contained
+(no CDNs): headline cards, hotspot chart, sortable per-op table,
+warnings, unclassified-op panel.
+
+### 3.2 Your own PyTorch model
+
+```sh
+thermoc erasure profile path/to/my_model.py --mode empirical --out out/
+```
+
+`my_model.py` must expose:
+
+```python
+def get_model():            # returns an nn.Module (eval mode recommended)
+    ...
+def get_example_inputs():   # returns a tensor / tuple of tensors
+    ...
+```
+
+or pass inputs from a file: `--inputs batch.npz` (first array is used).
+
+### 3.3 Modes: `worstcase` vs `empirical`
+
+- **`worstcase`** — no execution. Distribution-free preimage arithmetic:
+  an *upper* attribution per op ("at most this many bits"), plus the
+  uniform-ensemble column used for certificates. This is the only mode
+  whose certificate is a valid bound.
+- **`empirical`** — runs your model on the example inputs, streams
+  activation histograms (never stores raw activations), and estimates the
+  bits actually erased *on your workload*, with bootstrap confidence
+  intervals. Deterministic for a fixed `--seed` (bin edges are frozen on
+  the first batch). Never certifiable; always ≤ the worstcase column.
+
+Useful flags:
+
+```
+--temperature 300      bath temperature in K (floor scales linearly)
+--seed 0 --bins 64     empirical estimator settings
+--top-k 10             hotspot count
+--measured-json m.json attach measured energy => headroom column
+--no-html              JSON only
+```
+
+`m.json` schema: `{"total_J": 12.3, "per_op": {...}?, "source": "nvml"}` —
+any measurement source works; v1 deliberately does not bind NVML/RAPL.
+
+---
+
+## 4. Reading the report
+
+Every op row carries **three erased-bit columns** — they answer different
+questions and are deliberately kept separate:
+
+| Column | Meaning | Use |
+|---|---|---|
+| `delta_S_worstcase_bits` | max over inputs of log₂\|preimage\| — an upper bound for **every** input distribution. **= 0 ⇔ op is logically reversible.** | reversibility certification, rewrite targeting |
+| `delta_S_uniform_bits` | erased bits under a uniform ensemble over the dtype domain | the certified floor (Form B) |
+| `delta_S_empirical_bits` | erased bits measured on your traced workload (± CI) | profiling truth |
+
+Ordering is always `empirical ≤ uniform ≤ worstcase` (tested).
+
+**Classes:**
+- `REV` — reversible (ΔS_wc = 0). Examples: transpose/reshape, XOR,
+  integer add, LeakyReLU(α≠0), coupling layers, RevNet blocks, RoPE, FFT,
+  *numerically full-rank square* linear (checked at runtime via SVD — a
+  singular or ill-conditioned weight is demoted with its σ-spectrum
+  recorded; condition number literally becomes a bit count).
+- `IRREV` — information-destroying, with a derived formula. E.g. ReLU
+  erases exactly p(x≤0)·H(x|x≤0); softmax erases exactly one scalar (the
+  mean logit) per row; quantization erases bits_in − bits_out per element.
+- `STOCH` — sampling ops. Accounted by **entropy production σ** (nats),
+  not deterministic erasure: heat ≥ k_B·T·σ. For Gibbs/Glauber sweeps σ is
+  computed exactly from the trajectory ledger.
+- `UNKNOWN` — unclassified kind. **Soundness rule:** treated as full-input
+  erasure (worstcase), logged, and listed in the report's
+  `unclassified ops` panel. If you see UNKNOWN inflating your floor, add a
+  spec (§9).
+
+**Headroom** = measured_J / floor_J. Expect 10⁵–10⁶× on today's hardware —
+that gap is the industry's total remaining prize, not a promise this tool
+saves it on your GPU.
+
+**Sanity anchors** (what a healthy report looks like): ResNet-50 —
+conv/relu/pool dominate; GPT-2 block — GELU and the non-square MLP
+projection dominate, softmax is tiny (exactly b bits per attention row);
+item-2 chain — the first stage dissipates (+σ), later noising stages
+absorb heat (−σ, zero floor).
+
+---
+
+## 5. Certification
+
+```sh
+thermoc erasure certify out_gpt2/erasure_report.json --out cert.json
+```
+
+The certificate contains **two claim forms** (this is a deliberate,
+documented soundness correction to the PRD's original FR6 wording — flag
+for legal review):
+
+- **Form A — reversibility (distribution-free, fully sound).** Lists the
+  ops with ΔS_wc = 0: *"these contribute no Landauer floor under any input
+  distribution."* Valid because worstcase preimage counting upper-bounds
+  the erased entropy for every distribution.
+- **Form B — floor (ensemble-bound).** *"Under the declared input ensemble
+  (default: uniform over the dtype domain), the **average** dissipation of
+  any physical device executing this exact graph at T is ≥ X J."*
+  A distribution-free nonzero floor does not exist (a point-mass input
+  erases nothing), so the ensemble must be declared — and is.
+
+Guard rails baked into the artifact:
+- empirical-mode reports always produce `claim_valid: false` and a
+  `[NOT A BOUND — empirical mode]` prefix;
+- the claim binds to *this graph's semantics* — a different algorithm for
+  the same task may have a lower floor;
+- Landauer is an ensemble-average bound (single-shot fluctuations can
+  undershoot it — Jarzynski); the wording says "average".
+
+**Signing:** set `THERMOC_SIGNING_KEY` (and optionally
+`THERMOC_SIGNING_KEY_ID`) in the environment → HMAC-SHA256 over canonical
+JSON. Unset → `alg: none` with an explicit warning. Verify in Python:
+
+```python
+import json
+from thermoc.erasure.certify import verify
+assert verify(json.load(open("cert.json")))
+```
+
+---
+
+## 6. Python API (end-to-end)
+
+```python
+import sys
+sys.path.insert(0, "/Users/davidjohnson/Desktop/Spectral/EnergyIR/thermoc_erasure/src")
+
+from thermoc.erasure import profile, rewrite, plan, Budget
+
+# ---- Phase A: profile -------------------------------------------------
+import torch
+model = MyModel().eval()
+x = torch.randn(8, 128)
+
+rep = profile(model, x, mode="empirical", temperature_K=300.0, seed=0)
+print(rep.total_floor_J)         # graph Landauer floor, joules
+print(rep.hotspots[:5])          # ranked irreversibility hotspots
+rep.save("out/")                 # erasure_report.json + .html
+
+# ---- Phase B: rewrite under budgets ------------------------------------
+g = rep.graph                    # the live erasure-IR graph
+g2, rw = rewrite(g, Budget(mem="4x", latency="2x"))
+print(rw.erased_bits_before, "->", rw.erased_bits_after)
+for cert in rw.certificates:     # every rewrite carries a certificate
+    print(cert.rule, cert.delta_bits, cert.equivalence)
+
+# ---- Phase B: plan + simulate ------------------------------------------
+xp = plan(g2, "phal:pb64", latency_budget_s=1.0)
+xp.save("execution_plan.json")
+
+from thermoc.erasure.backends.simulated_adiabatic import SimulatedAdiabaticBackend
+sim = SimulatedAdiabaticBackend("phal:pb64").run(xp)
+print(xp.E_total_pred_J, sim.E_total_J)   # agree within 2% (M3 gate)
+```
+
+`profile()` accepts an `nn.Module` (+ example inputs), an
+`fx.GraphModule`, a ThermoIR `Program`, or an `EGraph`.
+
+### 6.1 ThermoIR / p-bit programs and σ accounting
+
+```python
+from thermoc.erasure.demos import item2_chain
+prog, _ = item2_chain(T=6, L=16)         # item-2 DTM forward chain
+rep = profile(prog, mode="empirical", seed=0)
+```
+
+Empirical mode executes the chain with the **σ ledger**: per Glauber
+update, the exact pathwise entropy flow Δs_env = β·f_i·(Δs_i) = β·Q. Per
+stage you get `sigma_env_nats` and a stage floor
+kT·max(σ,0). The cheap production estimator
+(σ̂ = β·Σ f·(tanh(βf) − s), the Rao-Blackwellized conditional expectation)
+is validated ≤ 5% against the exact ledger, and the whole machinery passes
+an integral-fluctuation-theorem test (⟨e^(−Δs_tot)⟩ = 1) against an
+exactly-enumerated 4×4 ensemble.
+
+To instrument your own program:
+
+```python
+from thermoc.erasure.trace import run_program_logged
+import numpy as np
+s, ledger = run_program_logged(prog, np.random.default_rng(0))
+print(ledger.sigma_env, ledger.sigma_rb)   # nats; per-op in ledger.per_op
+```
+
+Trajectories are bit-identical to the vendored ThermoIR backend at equal
+seeds — logging adds zero RNG draws.
+
+---
+
+## 7. The rewrite engine (Phase B, part 1)
+
+`rewrite(graph, budget, opt_in=None)` runs three passes in order — R1
+creates the reversible regions that R2/R3 then exploit:
+
+**R1 — substitutions**
+- `relu → leaky_relu` fold-back. *Exact* when every consumer is another
+  relu-family op (relu∘leaky = relu); otherwise requires
+  `opt_in={"relu_leaky": {"alpha": 0.01}}` and the certificate is marked
+  `approx`.
+- `quantize-later`: sinks a quantize past exactly-commuting relabelings
+  (transpose/reshape/flip/roll), growing the upstream REV region.
+- `inplace → out-of-place`: overwrites stop erasing H(old|new), charged
+  against the memory budget by erased-bits-per-byte density.
+
+**R2 — uncomputation.** Explicit `erase` nodes whose value was produced by
+an invertible cone are replaced by the cone's **inverse chain** (generated
+from the taxonomy's registered inverses, the way autodiff generates
+gradients from a tape). Cost: ~2× that region's time + pinned anchor
+memory. A copy of a still-live source (e.g. a graph input) is cancelled
+reversibly (retained-operand convention). Selection is greedy by erased
+bits per extra time, until your latency budget is spent.
+
+**R3 — Bennett pebble scheduling.** For long reversible chains where
+memory can't hold every checkpoint: the exact checkpoint/uncompute
+recursion with branching factor k. Erasure drops **N·b → b** (only the
+forced final erasure survives) at time × (2−1/k)ⁿ = N^ε and
+n(k−1)+1 checkpoints. The scheduler generates and *simulates* the exact
+move list (game invariant asserted); k is chosen under your budgets, and
+infeasible budgets raise `BudgetInfeasible` carrying the exact
+(k, time×, space, erasure) Pareto frontier so you can pick a point.
+
+**Budgets.** `Budget(mem="2x", latency="1.5x")` — multipliers over the
+baseline graph's peak liveness / total time, or absolute values
+(bytes / time units). Rough guide: `mem="8x", latency="3x"` lets the full
+pipeline strip a reversible-heavy graph to its forced erasures.
+
+**Certificates.** Every application emits
+`{rule, nodes, delta_bits, equivalence: tested|by-construction|approx}`.
+Semantic equivalence is checked by executing before/after graphs on
+identical inputs (bit-equal for integers).
+
+---
+
+## 8. The adiabatic planner (Phase B, part 2)
+
+```sh
+thermoc erasure plan coupling_mlp --latency 10 --mem 8x --out plan.json
+```
+
+```
+rewrite: 1.188e+05 -> 4160 erased bits (7 certificates)
+plan: 30 stages on phal:pb64, T = 10.0 s
+E_pred = 5.7743e-17 J  (landauer residue 1.194e-17 J, sigma heat 0.000e+00 J)
+simulated = 5.7743e-17 J  (pred error 0.00%)
+```
+
+**The physics the planner implements:**
+- Per-op adiabatic energy E(τ) = a/τ + c·τ (RC-ramp dissipation +
+  leakage). With leakage, "slower is always better" is false — each op
+  has an optimum τ* = √(a/c), and the planner will deliberately *not*
+  spend your whole latency budget past it.
+- Optimal allocation (P6): τ_i\* ∝ √a_i, E\* = (Σ√a_i)²/T. The gain over
+  uniform allocation is exactly the heterogeneity of the a_i
+  (Cauchy–Schwarz), reported as `gain_vs_uniform`.
+- Total prediction: driving dissipation + kT·ln2·(residual erased bits) +
+  kT·(Σσ for sampling stages).
+- The same `thermoc.allocate_time` engine will drive the geodesic
+  (thermodynamic-length) scheduler: a stage of thermodynamic length L is
+  just a_i = kT·L_i², giving constant thermodynamic speed.
+
+**Backends.** Builtins: `phal:pb64` (simulated adiabatic p-bit fabric,
+projected constants) and `phal:cmos-ref` (refusal reference). Describe
+real hardware in JSON and pass `BackendCapability.from_json(path)`:
+
+```json
+{"name": "my-adiabatic-chip", "adiabatic": true,
+ "a_per_unit": {"*": 2e-21}, "leak_per_unit": {"*": 1e-21},
+ "tau_min_s": 1e-8, "ramp_granularity_s": 1e-6}
+```
+
+**Refusal path (P4/N1).** Planning onto a non-adiabatic backend raises
+`NonAdiabaticBackendError` with the full physics explanation and emits
+**no plan and no savings claim**:
+
+```
+Backend 'phal:cmos-ref' declares adiabatic=false: it dissipates a fixed
+switching energy (~1/2 C V^2) per operation irrespective of logical
+reversibility ... the residual Landauer floor remains a physics reference
+line only.
+```
+
+**Plan format (v1)** reserves the pb64 hardware-integration fields per
+stage (FR7): `ramp_profile`, `erase_sites`, `telemetry.q_channel` — the
+simulated backend fills telemetry; real hardware will.
+
+**Simulated backend.** `SimulatedAdiabaticBackend(cap).run(plan,
+jitter=0.05)` is an independent code path (own snapping, own capability
+read); the M3 gate holds predicted-vs-simulated ≤ 2% across the benchmark
+suite, and the reversible-heavy benchmarks achieve **≥ 5× dissipation
+reduction at 2× latency** (rev_chain 6.5×, inplace_accum 20.7×,
+fft_pipeline 11.2×).
+
+---
+
+## 9. Extending the taxonomy
+
+63+ op specs ship in `src/thermoc/erasure/taxonomy/seed_{rev,irrev,stoch}.py`.
+Inspect them:
+
+```sh
+thermoc erasure taxonomy --list
+thermoc erasure taxonomy --show softmax
+```
+
+To add an op, register an `OpSpec`:
+
+```python
+from thermoc.erasure.taxonomy import default_registry
+from thermoc.erasure.taxonomy.registry import OpSpec
+from thermoc.erasure.ir import OpClass
+
+default_registry().register(OpSpec(
+    name="my_op", klass=OpClass.IRREV,
+    matches=("my_op", "aten.my_op*"),          # exact names or globs
+    worstcase_bits=lambda node: node.numel_in() * 8.0,
+    unif_bits=lambda node: node.numel_in() * 4.0,
+    inverse=None,                              # or "my_op_inv" to enable R2
+    reference_impl=lambda x, **a: ...,         # numpy semantics (equiv tests)
+    notes="what the formula means and why it is sound"))
+```
+
+Rules of the game:
+- `worstcase_bits` must upper-bound H(X|f(X)) for *every* distribution;
+- `unif_bits` must not exceed the true uniform-ensemble value (floors must
+  never overstate); when unsure, use `n·b − log2|image|` or 0;
+- unregistered kinds are safe by construction: UNKNOWN ⇒ full-input
+  erasure, logged and surfaced in the report;
+- registering `inverse` + `reference_impl` is what makes an op eligible
+  for uncomputation and equivalence testing.
+
+Fine-precision helpers you can reuse in formulas
+(`estimators/worstcase.py`): `smooth_monotone_bits` (elasticity formula
+for sigmoid-like saturation), `spectral_erasure_bits`
+(Σ log₂(1/σᵢ) over singular values < 1), `linear_rank_bits`.
+
+---
+
+## 10. Physics reference card
+
+| Law | Statement | Where implemented |
+|---|---|---|
+| Landauer (F1) | Q ≥ kT·ln2·ΔS, ensemble-average | `constants.kT_ln2` |
+| Erased info (F2) | ΔS(p) = H(X\|f(X)); ΔS_wc ≥ ΔS(p) ∀p; wc=0 ⇔ reversible | `estimators/worstcase.py` |
+| Finite precision (F3) | alphabet = dtype; δ(x) ≈ max(0, −log₂\|x f′/f\|) | `smooth_monotone_bits` |
+| Spectral erasure (F4) | ΔS_num = Σ_{σ<1} log₂(1/σ) | `spectral_erasure_bits` |
+| Entropy production (F5) | Δs_env = ln[P(s→s′)/P(s′→s)] = βQ, exact pathwise | `trace.SigmaLedger` |
+| IFT gate (F5) | ⟨e^(−Δs_tot)⟩ = 1 (exact 4×4 ensemble) | `estimators/glauber.py` |
+| Estimator stats (F6) | frozen quantile bins, Miller–Madow, bootstrap CI | `estimators/empirical.py` |
+| Bennett (F7) | N·b → b at time N^ε, ε = ln(2−1/k)/ln k, space n(k−1)+1 | `pebble.py` |
+| Uncompute (F8) | inverse-mode transformation over the taxonomy tape | `rewrite/uncompute.py` |
+| Time allocation (F9) | τ\* ∝ √a; E(τ)=a/τ+cτ, τ_opt=√(a/c); geodesic a=kT·L² | `thermoc/allocate_time.py` |
+| Certificates (F10) | Form A distribution-free; Form B ensemble-bound | `certify.py` |
+| Plan total (F11) | Σa/τ + cτ + kT·ln2·bits + kT·σ; refuse non-adiabatic | `planner.py` |
+| TUR hook (F12) | σ ≥ 2/ε² reserved (`precision_certificate: null`) | report/plan schemas |
+
+---
+
+## 11. Honest limits (read before quoting numbers externally)
+
+1. **No savings on today's GPUs.** Phase A is measurement/certification;
+   Phase B savings are demonstrated in simulation against declared E(τ)
+   curves. `phal:pb64` constants are projections.
+2. **Empirical estimates are workload-conditional** and carry binning
+   bias (documented per-op in `notes`); they never enter certificates.
+3. **Worstcase attributions can be loose** (that is their job — they are
+   upper bounds). Use the uniform column for floors, empirical for
+   profiling.
+4. **Certificates bind to the graph, not the task.** A different
+   algorithm may have a lower floor. The wording enforces this.
+5. **fx tracing limits:** dynamic control flow won't trace; shapes are
+   concretized at the example inputs and recorded in the report; the HF
+   GPT-2 tracer is incompatible with this torch/transformers pairing
+   (the demo uses a structure-identical hand-written block).
+6. **UNKNOWN ops inflate floors by design** (soundness). Check the
+   report's unclassified panel and add specs.
+
+## 12. Licensing & the PRO tier
+
+thermoc-erasure is OSS-first and **fails open to the free tier**: with no
+license (or an invalid/expired one) everything in §3–§5 keeps working
+except signing. The enterprise surfaces are PRO-gated using the same
+offline license mechanism as the rest of the EnergyIR suite:
+
+- **Free:** `profile` (both modes), JSON/HTML reports, headroom,
+  taxonomy inspection, certificates *emitted but unsigned*.
+- **PRO:** `rewrite()` (R1/R2/R3), `plan()` (adiabatic planner), and
+  signed certificates. Calling a PRO surface without a license raises
+  `PermissionError` (CLI exit code 4) with an upgrade hint.
+
+**How to activate:** obtain the license token from the EnergyIR portal
+(the same token that activates ThermoIR — one entitlement covers both),
+then either
+
+```sh
+export ENERGYIR_LICENSE="<token>"            # token literal
+export ENERGYIR_LICENSE="@/path/to/license"  # or a file reference
+# or place the token at ~/.energyir/license
+export ENERGYIR_LICENSE_PUBKEY="<publicKeyHex from the portal>"  # if instructed
+```
+
+Verification is offline ed25519 (`cryptography` package — installed with
+`pip install "thermoc-erasure[pro]"`); there is no phone-home. If the
+`energyir` suite is installed, verification delegates to
+`energy.intelligence.licensing` so one license serves the whole suite.
+
+## 13. Test map (where each guarantee is enforced)
+
+```
+test_constants.py        kT ln2 pinned; T scaling
+test_vendor.py           vendored ThermoIR ≡ upstream snapshot
+test_ir_frontends.py     graph hash, fx/thermoir mapping, in-place detection
+test_taxonomy.py         ≥60 specs, normative seeds, UNKNOWN path
+test_worstcase.py        every F4 formula; emp ≤ unif ≤ wc; SVD demotion
+test_empirical.py        ReLU closed form; frozen bins; CI; determinism
+test_glauber_sigma.py    bit-exact mirror; telescoping <1e-9; σ̂ ≤5%; IFT=1
+test_report_certify.py   schema; headroom; Form A/B; HMAC tamper detection
+test_acceptance_fr1.py   ResNet-50 / GPT-2 / item-2: <5 s, all resolve, <1%
+test_allocate_time.py    P6 closed form; Cauchy–Schwarz; leakage √(a/c)
+test_budget.py           budgets + liveness baselines
+test_substitutions.py    R1a/b/c with certificates
+test_uncompute.py        R2 legality, inverse synthesis, equivalence
+test_pebble.py           N·b → b property test (hypothesis); Pareto
+test_planner.py          plan schema; FR7 fields; refusal wording; σ heat
+test_m3_end_to_end.py    ≤2% pred-vs-sim; ≥5× @ 2× latency
+test_licensing.py        offline verifier; fail-open OSS; PRO gates; unsigned certs
+```
+
+Run any single gate: `/opt/anaconda3/bin/python -m pytest tests/test_glauber_sigma.py -v`
+
+---
+
+*Generated as part of the M0–M3 build of PRD_thermoc_erasure.md
+(physics-deep edition). The compiler's objective function is a physical
+quantity — and the certificate says exactly when that quantity is a law.*

thermoc_erasure-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+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).