pemf/README_PEMF.md

# Pre‑Emergence Mechanics Framework (PEMF) — ARC‑AGI

Short summary  
The Pre‑Emergence Mechanics Framework (PEMF) frames ARC tasks as a boundary‑constrained field problem solved by minimizing irreducible residue (o) under writability gates. PEMF implements four core primitives — **Scalar Potential (+)**, **Gradient Ordering (V)**, **Residue (o)**, and **Boundary Charge (p_q)** — and composes atomic transforms (tile, shifted tile, fill_enclosed, rotate, reflect, etc.) in a beam search to drain residue and produce stable outputs.

Why this matters  
PEMF shows how ARC tasks can be solved mechanically (o‑minimization + gates) rather than by symbolic heuristics. The approach maps CTS/ITT primitives to executable operators (potential fields, gradients, Dirichlet masks, complex projections) and yields a reproducible solver recipe.

Key concepts (one line each)
- **Scalar Potential (+):** represent grid as numeric potential field (initialize_potential).  
- **Gradient Ordering (V):** discrete gradients direct admissible edits.  
- **Residue (o):** L1 misalignment after quantize+tile; objective to minimize.  
- **Boundary Charge (p_q):** Dirichlet boundary mask that enforces writability gates.  
- **Layer‑1 diagnostics:** complex projection (FFT imag component) to find latent edit zones when real signal is weak.

Files and examples
- **Skill artifacts:** `SKILLS/pre_emergence_mechanics_framework/` — howto, runnable example `references/examples/verify_pemf.py`, and README for the skill.  
- **Postprocess logs:** `experiments/postprocess_logs.py` — coerce gate booleans and attach candidate snapshots for offline inspection.  
- **Headless entry:** `scripts/entrypoint.py` — run experiments from CLI; `--use_wandb` flag is optional and defaults to off.

Quick verification (headless)
1. Run the PEMF example to verify primitives and a tiny compositional loop:
```bash
python SKILLS/pre_emergence_mechanics_framework/references/examples/verify_pemf.py
```
2. Run a single experiment (example):
```bash
python scripts/entrypoint.py --task example1 --out_dir experiments
```
3. Postprocess logs to attach candidate snapshot and coerce gates:
```bash
python experiments/postprocess_logs.py
```

Acceptance checks
- `verify_pemf.py` prints a residue trace and reports at least one admissible edit zone from the complex projection.  
- `experiments/*_phi_best.npy` and `experiments/*_logs.fixed.json` exist after a run and contain candidate snapshot and boolean gates for inspection.

References and provenance
This README summarizes the executable PEMF recipe derived from the ARC‑AGI exposition (PEMF / CTS / ITT). See `SKILLS/pre_emergence_mechanics_framework/references/` for runnable examples and a step‑by‑step how‑to.