[jtravs]

Native CPU FFT optimisation. ADR-075 is proposed for the maintainer.

Closes #584
Closes #587
Closes #595

What changes

• Transforms thread by shape (Native CPU: transforms' width by rows and row length, not element count #587). A batch of transforms took its width from its element count. Now, from fft_threshold, it takes a thread per fft_thread_elements samples, at most one per row, or up to the medium width when its rows are at least fft_long_row long. fft_full is a backstop.
  • Linux and Windows: 8192, 4096 and 16384. macOS: 32768, 32768 and 65536, a sixteenth of those on a spinning top tier.
  • These values come from timing batched real transforms alone at 1–36 threads on an Intel Xeon Gold 6240, 16 cores of an AMD EPYC 7763 and an Apple M5 Max (table in benchmarks.md).
  • The sizing record now carries each batch's row length.
• One forward pack on a host (Native CPU: a stage's forward transforms as one batched region (#560 item 4) #584). A modal stage's forward rows go through one batched plan, as on a device: the projection's fine and coarse rows, the in-stage absorber's, and the held plasma currents'.
  • The host puts the coarse rows after the fine ones, so a deferred quadrature's stages transform the fine block alone and its finish takes the coarse block in one call.
  • Compact (one-column) problems keep their separate transforms.
  • SOLPROP_NATIVE_FORWARD_PACK=0 turns the pack off (documented in the tuning guide).
• The FFT grain is calibrated again. "fft" is back in grain.TIMED, last in the order, with its threshold and fft_thread_elements halved and doubled.
• Calibration: why measured and patient FFT plans chosen alone rarely win in the step #595, plans alone against in the step. Each captured plan is timed alone (_core.time_fft_plan) and its ratio is stored beside its verdict.
  • A candidate no faster alone is no longer timed in the step, and the thorough level no longer plans at patient.
  • The levels now take 30 s, 2 min and 7 min (from 20 s, 90 s and 5 min), by the maintainer's decision.
  • The calibration version is now 2.

Results

Against main: 5 % windows, three rounds, fields within 1e-12, with SOLPROP_CALIBRATION=off on both arms.

case	Xeon Gold 6240, 18	36	EPYC 7763, 16	M5 Max, 6 (contended)
argon_blueshift	0.87	0.80	0.86	0.92
ctc	0.89	0.91	0.92	0.98
rdw	0.91	0.95	0.95	0.95
line	0.93	0.87	0.88	1.00
others (8 cases)	0.94–1.04	0.93–1.04	0.98–1.01	0.99–1.01
geometric mean, including the one-thread rows	0.977		0.981	0.993

On #595, measured plans for threaded rows (SOLPROP_FFTW_PLAN=measure) win in the step:

• Xeon: 0.94 (kerr_beam_192 0.54–0.79).
• EPYC: 0.96 (grin_nonlinear 0.83).
• M5 Max: 0.97.

But planning them adds up to 12 s of construction (ctc on the EPYC: 13.8 s against 1.6 s), so the default stays at estimate.

The calibration's planning candidates "rarely won" because they were rarely timed. On all three machines the patient capture never finished, and the timing in the step ran out of rounds before a verdict. main does the same on the EPYC: no verdict at thorough, and nothing planned at standard.

With the pruning and the new budgets, the stage reaches a verdict on the EPYC 7763. Estimate's serial rows and planes were pruned (2.11 and 1.26 alone), and threaded_rows measure scored 0.99 on the calibration's problems but tied a round, so the policy held.

The thorough and standard calibrations on the EPYC 7763 conclude as on main, admitting the copy threshold. The transforms' thread grain kept 4096 (2048: 0.976, not admitted; 8192: 1.13).

Not done here

• Run-measured FFTW wisdom kept by default, so that admitted measured plans cost each shape one planning only (a separate, stacked PR).
• A socket-aware cap: on the two-socket Xeon at 36 threads a 28-row batch takes 28 threads across sockets.
• gnlse_raman_shock scales poorly with threads: slower at 16 than at 1 on an EPYC 9B45, and varies between processes #81's per-process modes, which still dominate the one-column cases on the Xeon.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 solprop | 🛠️ Build #35762714 | 📁 Comparing ef7ee5a against latest (0901bf6)

  🔍 Preview build  

17 files changed · ± 17 modified

± Modified

• genindex.html
• dev/backends.html
• dev/benchmarks.html
• dev/cpu-performance.html
• dev/decisions.html
• _modules/solprop/exceptions.html
• api/generated/solprop.calibration.controller.html
• api/generated/solprop.calibration.first_use.html
• api/generated/solprop.calibration.grain.html
• api/generated/solprop.exceptions.html
• and 7 more...

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-09T16:52:42.439000Z	7fed8b5	Draft marked ready
🔒 Security Review	✅ Completed 2026-11-09T16:53:19.975277Z	7fed8b5	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7fed8b5ed1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".