OPT — QSOL Optimization Catalog

Reusable, provenance-linked optimization patterns extracted from QSOL projects.

The point of this repository is simple: when a future project needs to go faster, use less memory, avoid redundant work, or shorten CI without weakening correctness, point the implementing agent here first.

Rules of the vault

1. Correctness outranks speed. An optimization must preserve the contract it claims to preserve.
2. Measured and proposed work are different things. Records say which is which.
3. Keep the reference path. Optimized/native/parallel paths should have a deterministic reference or conformance gate whenever practical.
4. Do not cargo-cult constants. Trial counts, worker caps, cache keys, tolerances, hashes, and block sizes belong to their source environment until re-measured.
5. Provenance matters. Every promoted optimization links back to the code, release, PR, or evidence that established it.

Catalog

ID	Optimization	Status	Source	Evidence snapshot
OPT-PY-001	Deterministic test execution	Verified mechanism; benchmark context incomplete	QEC v68.2.0–v68.4.1	~126 s → ~46 s in v68.4.0 release; ~40 s after v68.4.1; original runner/toolchain/repetition context not preserved, so re-benchmark before transfer
OPT-INV-001	Invariant-driven computation reuse	Verified mechanism; benchmark context incomplete	QEC v68.4.1 cycle	Eliminated a redundant benchmark at a proven-equivalent baseline point; ~43% source-reported hot-test improvement, with original environment/timing samples unavailable
OPT-LEAN-001	Trust-preserving Lean dependency reuse	Verified on source PR; timings environment-scoped	QSOL-GEO-REASON PR #3	2501.52 s cold dependency reconstruction and 8.47 s verified-cache project rebuild are different-scope single observations on four-CPU Ubuntu lanes; see record
OPT-PAR-001	Bounded deterministic parallel execution	Verified, environment-specific	QEC v170.2.1 / NEXUS evidence	qBraid / AMD EPYC 7763 observation: 69.694063 ns/eval scalar median → 18.310215 ns/eval at 7 workers; re-benchmark before transfer
OPT-DSP-001	Control-rate + sparse + vectorized DSP	Implemented reference; approximation/native ideas proposed	SPECTRAL commit 5265b7f… + power_module.md	Control-rate decimation, sparse E8 coupling, shared phase computation and NumPy vectorization are implemented; whole-block audition approximation and native SIMD/zero-copy/lock-free claims are not promoted

See CATALOG.md for the decision map and README4AI.md for machine-oriented usage.

Provenance correction: the QEC links

The originally supplied QEC v170.2.0/v170.2.1 links are useful, but they are not the origin of the large pytest/CI test-speed optimization. The primary deterministic test optimization lineage is:

• QEC v68.2.0 — Deterministic Execution Engine
• QEC v68.4.0 — Deterministic Runtime Optimization
• QEC v68.4.1 — Invariant Hardening & Repository Cleanup

The v170.2.x releases remain relevant here because v170.2.1 contains independently validated multicore benchmark evidence used by OPT-PAR-001.

Existing source material

• power_module.md contains the E8/qutrit DSP architecture that motivated OPT-DSP-001.
• suxen.zip is retained as an opaque source archive. It is not yet promoted as optimization evidence. See sources/SUXEN.md and run the bounded recursive scripts/inventory_zip.py scanner in a normal checkout before promoting claims from its nested payloads.

Add the next optimization

Copy templates/OPTIMIZATION-RECORD.md, assign the next ID, record before/after evidence, and state exactly what correctness property was preserved.