Prepare v0.3.0 counter-calibrated mapping artifact

CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable repository and research-artifact changes are recorded here.
 
+## Unreleased
+
+## 0.3.0 - 2026-08-02
+
+### Added
+
+- An orthogonal 184-case V100 length/batch suite and generated manifest for
+  FFT, NTT, FWHT, and XOR-zeta.
+- Scaling summaries that identify timing quality, throughput saturation, and
+  mapping crossovers without using sub-0.020-ms rows as stable claims.
+- Targeted NCU collection for the FFT saturation gaps and FWHT processing-unit
+  crossover.
+- A V100-calibrated mapping selector with held-out-shape evaluation and
+  explicit separation of mapping family from processing unit.
+- A matching-protocol 120-sample Dao FHT and GPU-NTT baseline refresh.
+- Targeted NCU attribution over 22 FFT/FWHT implementation-shape pairs and 37
+  kernels, plus one command that regenerates all derived V100 analyses.
+- An FP64 prefix address-path experiment that separately reproduces scalar,
+  table, recurrence, XOR-swizzled, and cuFFT timing under one protocol.
+- FP64 online cuFFTDx segment specializations at logN 7/8/9, a 648-point
+  neighboring-length mapping scan, and an interleaved 35-shape batch matrix.
+
+### Changed
+
+- Reworked the root, design, documentation-index, and experiment narratives
+  around the two logical dimensions and their four spatial/temporal unfolding
+  factors, with an explicit mapping from graph work to GPU services.
+- Replaced the high-level concept figure with a hardware-mapping diagram that
+  connects `Ud/Td/Us/Ts`, residence and transport, replaceable processing units,
+  online reordering, and counter-calibrated selection.
+- Updated paper-facing experiment summaries to include the expanded FP64
+  length/batch robustness matrix and fixed-mapping NCU attribution.
+- Regenerated checked-in V100 summaries with the current `shared_layout` and
+  `fp64_thread_instructions` schemas; existing measurement values are unchanged.
+- The comprehensive runner now supports exact case selection, validates batch
+  consistency within comparison groups, and caches identical correctness
+  preflights.
+- The next release is scoped around counter-calibrated mapping selection and
+  refreshed same-protocol external baselines.
+- Cross-GPU validation is deferred until the repository moves to a host with a
+  second GPU generation; it is not a `v0.3.0` release gate.
+- FP64 online staging now hoists invariant global addresses and advances
+  same-period shared permutations by compile-time strides.
+- FP64 online composition now covers total `logN=14..18`; each length selects
+  its split and two physical mappings independently.
+
+### Current Evidence Boundary
+
+- The new scaling evidence remains V100-only.
+- FP32 FFT matches or exceeds cuFFT at selected saturated shapes, but cuFFT has
+  a higher large-batch ceiling at `logN=18` and remains ahead at `logN=20`.
+- The profiled FP64 `logN=16`, batch-64 mapping reaches cuFFT parity at 1.002x.
+  Its updated counter capture attributes this to 26.8% fewer prefix warp
+  instructions and 8.3% lower prefix replay than the prior XOR kernel.
+- In the expanded FP64 matrix, 20/25 stable shapes have higher median
+  throughput than cuFFT and all 13 stable `logN=17/18` shapes are faster.
+- Cross-GPU portability and selector accuracy have not yet been measured.
+
 ## 0.2.0 - 2026-07-24
 
 ### Added

CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - name: "TruNcat3"
 repository-code: "https://github.com/TruNcat3/cuButterfly"
 url: "https://github.com/TruNcat3/cuButterfly"
-version: 0.2.0
-date-released: 2026-07-24
+version: 0.3.0
+date-released: 2026-08-02
 keywords:
   - butterfly computation
   - GPU

ROADMAP.md

@@ -3,24 +3,55 @@
 This roadmap separates implementation goals from evidence required for the
 research claim. Ordering may change after profiling or access to new hardware.
 
-## Near Term
-
-- Run an orthogonal `(logN, batch)` sweep instead of coupling all comparisons
-  through constant total points; identify launch-limited, saturation, and
-  throughput regions for every operator.
-- Refresh Dao-AILab FHT and GPU-NTT under the comprehensive-suite clock,
-  correctness, modulus, output-order, and trial protocol.
-- Profile the remaining FP32 `logN=20` and FP64 `logN=16` FFT gaps against
-  cuFFT, separating local-core, permutation, coefficient, and launch costs.
-- Convert the measured architecture space into a calibrated selector and
-  evaluate top-k prediction accuracy before exhaustive timing.
+## v0.3.0 Target: Counter-Calibrated Mapping Selection
+
+Status: the three V100 work packages, vectorized FFT physical unit, FFT
+leave-one-batch-out selector evaluation, and matching-protocol long-FFT refresh
+are complete. The post-vector fixed-mapping NCU capture attributes the gain to
+19.6% fewer warp instructions with unchanged DRAM write volume. Cross-GPU
+validation is deferred until the repository moves to a host with another GPU
+generation.
+
+The next release turns the measured design space into a reproducible mapping
+method rather than adding another isolated kernel. Its primary question is:
+
+> Given an operator contract, transform length, batch, and GPU service profile,
+> which mapping family and processing unit should be selected, and why?
+
+The release is complete when all of the following are true:
+
+1. NCU counters explain the FFT `logN=14` concurrency threshold, the
+   `logN=18/20` throughput ceilings, and the FWHT `logN=15` mapping crossover.
+2. A selector consumes workload and hardware descriptors, returns a ranked
+   top-k candidate set, and reports the resource or service constraints behind
+   the ranking.
+3. Leave-one-shape-out validation records top-1/top-k accuracy and performance
+   regret against the exhaustive V100 measurements.
+4. Dao-AILab FHT and GPU-NTT are refreshed under the same correctness, clock,
+   trial, and semantic protocol as the internal candidates.
+5. One release command regenerates the scaling manifest, summaries, selector
+   evaluation, and the paper-facing tables without modifying raw measurements.
+
+See [Next Phase: v0.3.0](docs/next_phase_v0.3.md) for the execution order,
+artifacts, and decision gates.
+
+## Near Term Backlog
+
+- Extend the measured orthogonal `(logN, batch)` sweep across additional
+  precision, direction, stride, and normalization contracts, then train the
+  selector on the observed saturation and mapping-crossover boundaries.
+- Reduce the remaining saturated FP32 `logN=20` exchange cost and the five
+  FP64 `logN=14..16` crossover deficits, preserving fixed-mapping NCU evidence.
 - Add a device-pointer and CUDA-stream execution API without weakening the
   current typed semantic contract.
 - Reduce template warning volume and record compiled resource envelopes as
   generated metadata.
 - Add focused sanitizer jobs on an available self-hosted GPU runner.
 
-## Cross-GPU Validation
+## Future: Cross-GPU Validation
+
+This work starts only after the repository is migrated to a machine with a
+second GPU generation. It is not a `v0.3.0` release gate.
 
 - Capture A100/H100/RTX 4090 hardware service profiles using the checked-in
   schema.