Update README.md

README.md

@@ -10,58 +10,79 @@ pinned: false
 license: other
 short_description: Live coherence + throughput benchmark (no precomputed result
 thumbnail: >-
-  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/Sr9bUuYsRuDtVZnb-
-
+  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/  
+ 
 ---
-# Coherent_Compute_Engine
 
-A real-time, on-machine benchmark that measures coherent state-update throughput and produces a tamper-evident receipt for every run.
+  # README.md — Coherent Compute Engine
+
+**Coherent Compute Engine** is a live benchmark Space that measures **real** compute throughput and stability for a coherent state update rule — with **no precomputed results** and **no estimates**.
 
-## What it does
-- Runs a coherent update kernel over **N oscillators** for **S steps**
-- Measures:
-  - **Throughput** (B/s = billions of items per second)
-  - **Coherence** (|C| stability proxy)
-  - **Mean Energy** (bounded mean of E)
-  - **Elapsed time**
-- Produces a **downloadable receipt** (JSON) containing inputs, environment, outputs, and a **SHA-256** hash.
+It’s designed to be understandable, verifiable, and brutally honest:
+- Everything is computed **now**, on the Space machine.
+- Baselines (Python loop + vectorised NumPy) are measured **live** on the **same machine**.
+- Results can be downloaded as a **receipt** (JSON) with a SHA-256 hash.
 
 ## What an “item” is
-**1 item = one per-oscillator coherent state update of `[Psi, E, L]` per step**, as implemented in this Space.
 
-This definition is explicit so the metric is reproducible.
+**One item = one coherent update of `[Ψ, E, L]` per oscillator per step.**
+
+So:
+
+`items/sec = (N oscillators × steps) / elapsed_seconds`
+
+We report throughput in **billions of items/sec** (“B/s”).
+
+## What this Space measures
+
+For the chosen oscillator count and step count, it reports:
+
+- **Throughput (B/s)**: billions of coherent updates per second  
+- **Coherence (|C|)**: a stability proxy computed from a normalised dot product of sampled `Ψ` before/after  
+- **Mean Energy**: bounded mean proxy from `E` in `[0, 1.5]`  
+- **Elapsed Time (s)**  
+- **Engine**: `numba` when available; otherwise `numpy`  
+- **Verification baselines (optional)**:
+  - **Baseline (Vectorised NumPy)**
+  - **Baseline (Python loop, capped)** — safety-capped and subset-based to keep the Space responsive
+  - **Speedup factors** vs those baselines
+
+## Receipts: verification you can download
+
+Each run emits a small JSON “receipt” containing:
+- input settings (N, steps)
+- engine name
+- measured metrics
+- runtime info
+- **SHA-256 hash** of the canonical JSON
 
-## Verification / receipts
-Each run writes a receipt JSON under `results/` and exposes it via the UI.
-The receipt includes:
-- timestamp (UTC)
-- app version
-- platform + python
-- logical CPU count
-- inputs (N, steps, seed, scale)
-- measured outputs
-- SHA-256 hash of the canonical receipt JSON
+This supports the “don’t trust it, verify it” approach.
 
-This makes runs easy to share and tamper-evident.
+## Why baselines exist (and why they’re not a contest)
 
-## Baselines (optional)
-If enabled, the Space also measures:
-- live **NumPy** baseline (vectorised)
-- tiny **Python loop** baseline (hard safety caps)
+Baselines are **verification anchors**:
+- They show what “normal” Python looks like (slow floor)
+- They show what vectorised NumPy looks like (standard reference)
+- They show what the engine path achieved under the same rules
 
-If `numba` is available, the primary engine automatically uses a Numba JIT kernel.
+No claims about beating GPUs or other systems. Just measured, reproducible data.
 
-## Important note about “your CPU”
-Hugging Face Spaces run on hosted hardware. The results reflect the **Space runtime**, not the visitor’s laptop CPU.
+## Running locally
 
-If you want your own machine’s numbers, run the repo locally.
+```bash
+pip install -r requirements.txt
+python app.py
+Safety rails
 
-## Files
-- `app.py` — Gradio app + benchmark + receipt writer
-- `results/` — receipts + `runs.csv` (created automatically)
+To keep the Space stable:
+	•	oscillator count is clamped to a safe max
+	•	steps are clamped
+	•	Python loop baseline is time-capped and subset-based
 
-## Licence
-Please read LICENCE, listed in repo
+That ensures the Space stays responsive while still measuring real throughput.
 
+⸻
 
+Built by RFTSystems.
+  
   Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference