Add power-of-two FFT323161 lead caching

Author: cherubrock-seb

MANIFEST_NATIVE_PFA.json

@@ -1,8 +1,8 @@
 {
-  "root": "PrMers-v99.73-Aevum-PFA9-Force-Adaptive-exp11",
-  "version": "4.20.67-alpha-v99.73-aevum-pfa9-force-adaptive-exp11",
-  "feature": "force-adaptive explicit type-4 PFA9 requests with full-path diagnostic escape",
-  "file_count": 422,
+  "root": "PrMers-v99.74-Aevum-Pow2-Type4-LeadCache-exp12",
+  "version": "4.20.68-alpha-v99.74-aevum-pow2-type4-lead-cache-exp12",
+  "feature": "explicit power-of-two FFT323161 with deferred LEAD_WIDTH/carryFused register squaring",
+  "file_count": 432,
   "files": [
     ".github/workflows/build_linux.yml",
     ".github/workflows/build_mac_os.yml",
@@ -14,12 +14,15 @@
     "LICENSES/PrMers-MIT.txt",
     "LICENSES/README.md",
     "MANIFEST_NATIVE_PFA.json",
+    "MODIFICATIONS.md",
     "Makefile",
     "NOTICE.md",
     "README.md",
     "README_AEVUM_REG.md",
     "README_NATIVE_AEVUM_PFA.md",
+    "README_POW2_TYPE4_LEAD_CACHE.md",
     "README_TYPE4_PFA9.md",
+    "RELEASE_EXP12.md",
     "build_and_test_native_pfa_ubuntu.sh",
     "chainpm1.sh",
     "chainpm1old.sh",
@@ -91,6 +94,7 @@
     "kernels/marin.cl",
     "kernels/prmers.cl",
     "prmers.ipynb",
+    "scripts/bench_pow2_type4_ubuntu.sh",
     "scripts/benchmark_aevum_vs_marin.sh",
     "scripts/build_native_pfa.sh",
     "scripts/build_native_pfa_ubuntu.sh",
@@ -154,6 +158,7 @@
     "tests/aevum_apple_fused_tailsquare_test.py",
     "tests/aevum_fake_engine.cpp",
     "tests/aevum_pm1_small_factor_policy_test.py",
+    "tests/aevum_pow2_type4_source_test.py",
     "tests/aevum_vtrace_prepared_cache_test.py",
     "tests/apple_strict_smoke_source_test.py",
     "tests/macos_default_marin_policy_test.py",
@@ -199,6 +204,7 @@
     "third_party/aevum/README_GPUOWL.md",
     "third_party/aevum/README_GPUOWL_LEGACY.txt",
     "third_party/aevum/README_NATIVE_PFA.md",
+    "third_party/aevum/README_POW2_TYPE4_LEAD_CACHE.md",
     "third_party/aevum/README_TYPE4_PFA9.md",
     "third_party/aevum/SP/Gpu.cpp",
     "third_party/aevum/SP/Gpu.h",
@@ -226,6 +232,7 @@
     "third_party/aevum/scripts/check_macos_minos.sh",
     "third_party/aevum/scripts/install_ubuntu_dependencies.sh",
     "third_party/aevum/scripts/test_native_pfa_gpu.sh",
+    "third_party/aevum/scripts/test_pow2_type4_lead_cache_ubuntu.sh",
     "third_party/aevum/scripts/test_type4_pfa9_ubuntu.sh",
     "third_party/aevum/src/AllocTrac.cpp",
     "third_party/aevum/src/AllocTrac.h",
@@ -391,6 +398,7 @@
     "third_party/aevum/tests/apple_readchecked_double_sync_test.py",
     "third_party/aevum/tests/check_macos_minos.sh",
     "third_party/aevum/tests/engine_api_load_test.cpp",
+    "third_party/aevum/tests/engine_lead_cache_test.py",
     "third_party/aevum/tests/engine_small_factor_gpu_test.cpp",
     "third_party/aevum/tests/fft3161_exact_plan_test.py",
     "third_party/aevum/tests/gpu_init_order_test.py",
@@ -401,6 +409,8 @@
     "third_party/aevum/tests/opencl12_syntax_test.sh",
     "third_party/aevum/tests/opencl_monolithic_source_test.cpp",
     "third_party/aevum/tests/opencl_standard_test.cpp",
+    "third_party/aevum/tests/pow2_type4_lead_cache_compare.cpp",
+    "third_party/aevum/tests/pow2_type4_opencl_syntax.sh",
     "third_party/aevum/tests/run_aevum_apple_plane_isolation_v5.sh",
     "third_party/aevum/tests/run_aevum_apple_stage_trace_v4.sh",
     "third_party/aevum/tests/source_audit.sh",

MODIFICATIONS.md

@@ -0,0 +1,9 @@
+## v99.74 power-of-two FFT323161 + PRPLL-style lead cache
+
+- accepts explicit non-PFA FFT323161 plans, including `4:512:8:512:202`;
+- embeds Aevum v0.3.67;
+- preserves consecutive PRP squarings in `LEAD_WIDTH` state through the register adapter;
+- flushes the one pending final square before every externally visible register operation;
+- keeps PFA and Apple on their validated canonical paths;
+- adds exact cached-versus-canonical GPU comparison and benchmark scripts.
+

Makefile

@@ -118,6 +118,7 @@ test-gui-state:
 	bash tests/test_web_gui_backend_state.sh
 
 test-aevum-source:
+	python3 tests/aevum_pow2_type4_source_test.py
 	bash tests/source_aevum_engine_audit.sh
 
 test-backend-compat: all

README.md

@@ -1175,3 +1175,11 @@ PrMers is developed by cherubrock-seb, with feedback and contributions from user
 - A forced Aevum request falls back to Marin only when no admissible FFT3161 plan exists, and the log states the reason explicitly.
 - The one-register P-1 ultra-low-memory algorithm is the sole Marin-only path because it depends on Marin `fast3`; Auto selects Marin and forced Aevum exits cleanly before GPU allocation.
 - PRP/LL checkpoints now include backend and mode metadata. Legacy untagged checkpoints are not loaded into Aevum, and LL-safe, LL-safe2 and LL-unsafe use distinct filenames.
+
+### Power-of-two FFT323161 lead cache in v99.74
+
+The exact plan `4:512:8:512:202` is now accepted by Aevum.  Consecutive
+`engine::square_mul(reg, 1)` calls use a one-square pending scheduler so the
+GPU retains `LEAD_WIDTH` and upstream `carryFused` between iterations.  See
+`README_POW2_TYPE4_LEAD_CACHE.md` for validation and A/B commands.
+

README_POW2_TYPE4_LEAD_CACHE.md

@@ -0,0 +1,45 @@
+# PrMers v99.74 — power-of-two FFT323161 + register lead cache
+
+This release enables the exact upstream-style power-of-two plan:
+
+```text
+4:512:8:512:202
+```
+
+for `M175000039`.  It is the same 4M-word FFT323161 family used by PRPLL:
+FP32 + GF31 + GF61, variant 202.  Previous PrMers/Aevum builds rejected this
+non-PFA type-4 plan and therefore compared an 8M FFT3161 plan against PRPLL's
+4M FFT323161 plan.
+
+The register adapter now also preserves upstream PRPLL's hot squaring chain.
+One logical `square_mul(reg,1)` is held pending; consecutive calls execute the
+previous square with `LEAD_WIDTH`, and a read/copy/checkpoint/sync emits the
+final square with a canonical boundary.  This restores `carryFused` between
+ordinary PRP iterations without changing the public engine API.
+
+Safety rules:
+
+- enabled only for non-PFA, short-carry plans;
+- disabled on Apple, retaining the validated canonical path;
+- PFA3/PFA9 remain canonical because native-PFA fused carry is not implemented;
+- `AEVUM_REG_LEAD_CACHE=0` restores the previous per-iteration canonical path;
+- `AEVUM_TYPE4_MULTI_Q=0` disables type-4 plane overlap for A/B measurement.
+
+Recommended RTX 3080 test:
+
+```bash
+./prmers 175000039 -d 1 \
+  -aevum-fft 4:512:8:512:202 \
+  -proof 0 -f bench-pow2-type4
+```
+
+Expected startup lines include:
+
+```text
+FFT: 4M 4:512:8:512:202 (41.72 bpw)
+Aevum register lead cache enabled
+```
+
+Use `AEVUM_REG_LEAD_CACHE=0` with the same command for the exact canonical
+baseline.  The package test script also performs a word-exact GPU differential
+between the cached and canonical paths before benchmarking.

RELEASE_EXP12.md

@@ -0,0 +1,82 @@
+# exp12 publication commands
+
+## Aevum standalone
+
+```bash
+cd /Users/fricadev/dev/aevum-engine
+git switch main
+git pull --ff-only origin main
+git status --short
+
+rsync -av --delete \
+  --exclude='.git/' --exclude='.DS_Store' \
+  --exclude='.aevum-kernel-cache/' \
+  --exclude='build/' --exclude='build-engine/' --exclude='build-tests/' \
+  --exclude='build-release/' --exclude='build-debug/' --exclude='build-cuda/' \
+  --exclude='*.o' --exclude='*.d' --exclude='*.so' --exclude='*.dylib' \
+  /Users/fricadev/Downloads/aevum-engine-v0.3.67-pow2-type4-lead-cache-exp12/ \
+  /Users/fricadev/dev/aevum-engine/
+
+git status --short
+git diff --check
+git diff --stat
+make test-host
+bash tests/native_pfa_opencl_syntax.sh
+python3 tests/engine_lead_cache_test.py
+
+git add -A
+git diff --cached --check
+git diff --cached --stat
+git commit -m "Enable power-of-two FFT323161 lead caching"
+git push origin main
+
+AEVUM_TAG='v0.3.67-pow2-type4-lead-cache-exp12'
+git tag -a "$AEVUM_TAG" -m "Aevum v0.3.67 power-of-two FFT323161 lead-cache release"
+git push origin "$AEVUM_TAG"
+```
+
+## PrMers
+
+```bash
+cd /Users/fricadev/prmerscopy/PrMers
+git switch main
+git pull --ff-only origin main
+git status --short
+
+rsync -av --delete \
+  --exclude='.git/' --exclude='.DS_Store' \
+  --exclude='.aevum-kernel-cache/' --exclude='prmers' \
+  --exclude='build/' --exclude='build-engine/' --exclude='build-tests/' \
+  --exclude='build-release/' --exclude='package/' \
+  --exclude='*.o' --exclude='*.d' --exclude='*.so' --exclude='*.dylib' \
+  /Users/fricadev/Downloads/PrMers-v99.74-Aevum-Pow2-Type4-LeadCache-exp12/ \
+  /Users/fricadev/prmerscopy/PrMers/
+
+git status --short
+git diff --check
+git diff --stat
+python3 tests/native_pfa_cli_source_test.py
+python3 tests/aevum_pow2_type4_source_test.py
+make test-aevum-host
+make test-aevum-source
+make test-aevum-auto
+make test-aevum-default
+
+git add -A
+git diff --cached --check
+git diff --cached --stat
+git commit -m "Add power-of-two FFT323161 lead caching"
+git push origin main
+
+TAG='v4.20.68-alpha-v99.74-aevum-pow2-type4-lead-cache-exp12'
+git fetch --tags --force
+if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+  echo "ERREUR: le tag existe deja" >&2
+  exit 1
+fi
+git tag -a "$TAG" -m "PrMers v99.74 power-of-two FFT323161 lead-cache release"
+git push origin "$TAG"
+
+gh run list --limit 10
+gh run watch
+```

include/core/Version.hpp

@@ -4,7 +4,7 @@
 #include <string>
 
 namespace core {
-    const std::string PRMERS_VERSION = "4.20.67-alpha-v99.73-aevum-pfa9-force-adaptive-exp11";
+    const std::string PRMERS_VERSION = "4.20.68-alpha-v99.74-aevum-pow2-type4-lead-cache-exp12";
 } // namespace core
 
 #endif // VERSION_HPP

scripts/bench_pow2_type4_ubuntu.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+DEVICE="${1:-1}"
+DURATION="${2:-180}"
+EXPONENT="${3:-175000039}"
+
+run_bench() {
+  local name="$1"; shift
+  local dir="$ROOT/bench-$name"
+  rm -rf "$dir"; mkdir -p "$dir"
+  printf '\n===== %s =====\n' "$name"
+  set +e
+  timeout -s INT "${DURATION}s" "$@" -f "$dir" 2>&1 | tee "$dir/run.log"
+  local rc=${PIPESTATUS[0]}
+  set -e
+  if [[ $rc -ne 0 && $rc -ne 124 && $rc -ne 130 ]]; then return "$rc"; fi
+}
+
+run_bench pow2-type4-lead \
+  env AEVUM_REG_LEAD_CACHE=1 AEVUM_TYPE4_MULTI_Q=1 \
+  ./prmers "$EXPONENT" -d "$DEVICE" -aevum-fft 4:512:8:512:202 -proof 0
+
+run_bench pow2-type4-canonical \
+  env AEVUM_REG_LEAD_CACHE=0 AEVUM_TYPE4_MULTI_Q=1 \
+  ./prmers "$EXPONENT" -d "$DEVICE" -aevum-fft 4:512:8:512:202 -proof 0
+
+run_bench pow2-type4-singleq \
+  env AEVUM_REG_LEAD_CACHE=1 AEVUM_TYPE4_MULTI_Q=0 \
+  ./prmers "$EXPONENT" -d "$DEVICE" -aevum-fft 4:512:8:512:202 -proof 0
+
+run_bench pfa9-type1 \
+  ./prmers "$EXPONENT" -d "$DEVICE" -aevum-fft pfa9:1:512:9:512:202 -proof 0
+
+run_bench pow2-type1 \
+  ./prmers "$EXPONENT" -d "$DEVICE" -pfa-off -proof 0
+
+run_bench marin \
+  ./prmers "$EXPONENT" -d "$DEVICE" -engine-marin -proof 0
+
+printf '\n===== SUMMARY =====\n'
+for log in bench-*/run.log; do
+  echo "--- $log"
+  grep -E 'version=|register lead cache|multi-queue|FFT:|Progress:' "$log" | tail -12 || true
+done
+
+PRPLL_BIN="${PRPLL_BIN:-$HOME/mgpu/gpuowl/build-release/prpll}"
+if [[ -x "$PRPLL_BIN" ]]; then
+  echo
+  echo "PRPLL reference command:"
+  echo "$PRPLL_BIN -device $DEVICE -prp $EXPONENT -fft 4:512:8:512:202"
+fi

src/aevum/EngineAevum.cpp

@@ -264,7 +264,7 @@ class engine_aevum final : public engine {
             handle_ = nullptr;
             throw std::runtime_error("Aevum plugin returned an invalid transform");
         }
-        std::cout << "[Backend Aevum] engine::Reg adapter active, GF(M31^2) x GF(M61^2)"
+        std::cout << "[Backend Aevum] engine::Reg adapter active, FFT3161/FFT323161"
                   << " | transform=" << transform_size_
                   << " | regs=" << register_count_
                   << " | plugin=" << api_.path
@@ -525,9 +525,6 @@ std::size_t transform_size_from_spec(const std::string& spec) {
                                 (fields[offset] == "1" || fields[offset] == "4");
     if (!supported_type)
         throw std::runtime_error("invalid Aevum FFT3161/FFT323161 spec");
-    const bool explicit_pfa9 = spec.rfind("pfa9:", 0) == 0 || spec.rfind("pfa9fast:", 0) == 0 || spec.rfind("pfa9full:", 0) == 0;
-    if (fields[offset] == "4" && !explicit_pfa9)
-        throw std::runtime_error("Aevum FFT323161 requires explicit pfa9, pfa9fast, or pfa9full plan");
     const std::size_t width = parse_fft_dimension(fields[offset + 1]);
     const std::size_t middle = parse_fft_dimension(fields[offset + 2]);
     const std::size_t height = parse_fft_dimension(fields[offset + 3]);

tests/aevum_pow2_type4_source_test.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+from pathlib import Path
+root = Path(__file__).resolve().parents[1]
+adapter = (root / "src/aevum/EngineAevum.cpp").read_text()
+engine = (root / "third_party/aevum/src/EngineApi.cpp").read_text()
+gpu = (root / "third_party/aevum/src/Gpu.cpp").read_text()
+fft = (root / "third_party/aevum/src/FFTConfig.cpp").read_text()
+version = (root / "include/core/Version.hpp").read_text()
+
+assert 'fields[offset] == "1" || fields[offset] == "4"' in adapter
+assert 'requires explicit pfa9' not in adapter
+assert 'pending_reg_ = index;' in engine
+assert 'AEVUM_REG_LEAD_CACHE' in engine
+assert 'gpu_->regSquareStep(reg(index), pending_lead_width_, true);' in engine
+assert 'gpu_->regSquareStep(reg(index), lead_in, false);' in engine
+assert '!fft.isPfa() && !useLongCarry' in gpu
+assert 'fft.shape.fft_type == FFT323161;' in fft
+assert '4.20.68-alpha-v99.74-aevum-pow2-type4-lead-cache-exp12' in version
+print('PrMers Aevum power-of-two type-4 lead-cache source test passed')