Skip to content

Fix fractal FFT centering for odd and singleton extents - #934

Merged
agianno merged 2 commits into
gprMax:masterfrom
fallenmi:codex/gprmax-fractal-dc-center-oct23-v1
Oct 25, 2026
Merged

agianno merged 2 commits into
gprMax:masterfrom
fallenmi:codex/gprmax-fractal-dc-center-oct23-v1

Conversation

@fallenmi

Copy link
Copy Markdown
Contributor

Summary

Centre the fractal volume and surface filters on the actual FFT DC position for odd and single-cell extents.

The existing kernels map an index i to (i + n // 2) % n, so the DC position is n // 2. The callers currently pass a reference at n / 2. For an odd extent this introduces a half-cell offset: conjugate frequency pairs receive different multipliers. Taking the real part of the inverse FFT then changes the intended spectrum. A single-cell axis also incorrectly contributes a nonzero distance to every coefficient.

This changes the reference vectors in the volume and surface callers, including their MPI counterparts. The kernels, exponent, output shape, binning and surface-range logic are unchanged.

Regression coverage

  • Odd volume extents (5, 6, 7) and (7, 7, 7), and a single-cell extent (8, 8, 1).
  • Odd surface extents (5, 6) and (7, 7), and a single-cell extent (1, 8).
  • The tests exercise the real caller and kernel, checking the DC reference, conjugate-pair symmetry and the single-cell-axis distance.

Verification

Using the normal source build and pytest configuration on Python 3.12:

  • On the unchanged base, the seven new regression cases fail; the other 93 project cases pass.
  • With the final patch, all 100 cases in test_fractal_volume.py, test_fractal_surface.py and test_fractals_generate.py pass.
  • Ten additional local verification-only cases pass. Four seeded even-extent volume/surface arrays are exactly equal before and after; six odd/single-cell outputs remain finite and in range and change as expected.
  • Scoped native pre-commit checks pass, including Black and isort with the repository's configured arguments.

This is not a full-repository, MPI, GPU or hardware test claim. MPI reference-vector changes were checked statically; MPI execution was not available.

Compatibility

Seeded results for odd or single-cell extents change because their spectral distances are corrected. The tested even-extent cases retain exactly the same arrays.

AI assistance

Claude Code prepared the patch and regression tests. Codex independently reproduced the defect, ran the normal-build and paired regression checks, and prepared this PR. No human maintainer approval is implied.

@agianno

agianno commented Oct 23, 2026

Copy link
Copy Markdown
Member

Thanks—the correction looks appropriate. Please add a release note stating that regenerated fractal volumes and rough surfaces with odd-sized or single-cell dimensions may differ for the same seed after this fix. All-even cases and previously exported geometry remain unchanged. This concerns the fractal-generation dimensions, not necessarily the overall domain. Once documented, I’m happy to merge.

Please add this compatibility warning to docs/source/release_notes.rst under “Unreleased / next release”, as part of this PR—not only in the PR description.

@agianno
agianno merged commit 41a604e into gprMax:master Oct 25, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants