Skip to content

PERF: Reuse N4 iteration buffers to cut per-iteration allocations - #7085

Merged
hjmjohnson merged 3 commits into
InsightSoftwareConsortium:mainfrom
gdevenyi:perf-n4-reuse-iteration-buffers
Nov 4, 2026
Merged

hjmjohnson merged 3 commits into
InsightSoftwareConsortium:mainfrom
gdevenyi:perf-n4-reuse-iteration-buffers

Conversation

@gdevenyi

@gdevenyi gdevenyi commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Reuse N4's per-iteration buffers, cutting allocations from 5-6 images per iteration to one. Bit-identical; full-resolution N4 is 7 % faster with #7072 and #7075. Stacked on #7075; the last two commits are new.

Details

Each N4 iteration created new images for the residual (SubtractImageFilter), the reconstructed field (B-spline output plus a VectorIndexSelectionCastImageFilter copy), the convergence difference image and the uncorrected image, and the B-spline fit allocated a full-size output that it never wrote (ANTsX/ANTs#2037, item N4-5).

  • One residual buffer, written by a parallel loop with the same float subtraction.
  • Two bias field buffers that swap: the new estimate is reconstructed into the buffer of the estimate before the previous one, because the convergence test needs both. Component 0 of the reconstructer output is copied by a parallel loop. The public ReconstructBiasField(lattice) is unchanged; a private ReconstructBiasFieldInto writes into a given image, and one helper sets up the reconstructer for both and for the lattice refinement. One reconstructer output per iteration remains.
  • The uncorrected image is updated in place by a parallel loop.
  • CalculateConvergenceMeasurement computes the difference in its loop, with the same float subtraction and the same serial summation order, so the convergence value is unchanged.
  • Separate commit: BSplineScatteredDataPointSetToImageFilter allocates its output only when GenerateOutputImage is on. When it is off, the output has its geometry but empty regions and no buffer (documented on GenerateOutputImage), so a caller cannot read an unwritten buffer and a second Update() of the unmodified filter does not re-execute.
Measurements

AMD Ryzen 9 9950X, GCC 13.3, Release, 16 threads. N4 on MNI152 2009c T1 (1 mm, no shrink), 3 levels x 15 iterations, four runs (no mask; mask; mask and confidence image; oblique direction), two repeats:

wall peak RSS
#7072 + #7075 47.3 / 46.7 s 701 / 676 MB
#7072 + #7075 + this PR 43.9 / 43.5 s 642 / 642 MB
Test results
  • ctest -R 'BSpline|N4|BiasCorrection': 34/34 pass, including the N4 GoogleTests from PERF: Build N4 B-spline fit points once instead of in each iteration #7075 (mask label, confidence image, and values from main, now also the convergence measurement) and the new B-spline output-state GoogleTest with a second Update(). The build adds no warnings.
  • Bit-identity: the raw output and control-point lattice of the four N4 runs above at shrink 2, plus a re-Update() after removing the mask, and the raw lattice and output of BSplineScatteredDataPointSetToImageFilter for spline orders 1-5, 2-D and 3-D and closed dimensions, with cmp against main: identical.
AI assistance

@gdevenyi

gdevenyi commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

@ntustison could you review this when you have a chance? It is one of the upstream items from ANTsX/ANTs#2037.

@github-actions github-actions Bot added type:Performance Improvement in terms of compilation or execution time area:Filtering Issues affecting the Filtering module labels Nov 2, 2026

@hjmjohnson hjmjohnson left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @gdevenyi. The buffer reuse in N4 looks sound, but the B-spline filter change needs to come out of this commit, and the equivalence claim needs an in-tree test before merge. These findings cover only this PR's own commit (87c3d0e); #7075 below it has a blocking release-data defect (the cached point set can be freed under GlobalReleaseDataFlag) that must be fixed first.

  • Please pin the bit-identity claim with an in-tree test: an exact-baseline GoogleTest or the committed comparison harness. Nothing in the current N4 tests would detect a value change.
  • The title overstates the change: each iteration still allocates one full-size Vector<float,1> output in the reconstructer (hxx:662), so allocations drop from about six per iteration to one, not to zero.
  • #include "itkSubtractImageFilter.h" (hxx:31) is now unused; please drop it.

Details are inline.

@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from 87c3d0e to 53324d1 Compare November 2, 2026 21:46
@github-actions github-actions Bot added type:Infrastructure Infrastructure/ecosystem related changes, such as CMake or buildbots type:Testing Ensure that the purpose of a class is met/the results on a wide set of test cases are correct labels Nov 2, 2026
@gdevenyi

gdevenyi commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @hjmjohnson. I rebased onto the revised #7075 (76f7e68) and force-pushed. There are now two commits:

  • 1dc4582 is the N4 buffer reuse, retitled "Reuse N4 iteration buffers to cut per-iteration allocations". One reconstructer output per iteration remains, as you said. The unused itkSubtractImageFilter.h include is dropped.
  • 53324d1 is the B-spline output-state change, with its own GoogleTest.

The bit-identity claim is now pinned in-tree by the N4 GoogleTests that #7075 adds. They compare a mask label with a binary mask exactly and a binary confidence image with a mask exactly, and compare a mask label plus confidence run against values generated with main. All of them pass with this branch. The out-of-tree N4 harness is also byte-identical to main, and ctest -R 'BSpline|N4|BiasCorrection' passes 34/34.

Details are inline.

@gdevenyi gdevenyi changed the title PERF: Reuse N4 iteration buffers instead of allocating new images PERF: Reuse N4 iteration buffers to cut per-iteration allocations Nov 2, 2026
@gdevenyi

gdevenyi commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

The B-spline re-Update() bug I mentioned inline now has its own PR: #7092.

@hjmjohnson

Copy link
Copy Markdown
Member

@greptileai review

@greptile-apps

greptile-apps Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable defects were found.

Summary

N4 now reuses fit points and iteration buffers instead of rebuilding them each iteration.

  • N4 reuses image buffers while correcting bias fields.
  • B-spline fitting skips the sampled image when callers turn it off.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Build fit points and allocate buffers] --> B[Sharpen current image]
  B --> C[Write residual buffer]
  C --> D[Fit control-point lattice]
  D --> E[Reconstruct into spare bias buffer]
  E --> F[Compare old and new bias fields]
  F --> G[Swap bias buffers]
  G --> H[Update corrected log image]
  H --> I{More iterations?}
  I -->|Yes| B
  I -->|No| J[Produce corrected image]
Loading

Reviews (3) · Last reviewed commit: "PERF: Skip the B-spline fit output buffe..." · Reviewed by Greptile

@hjmjohnson hjmjohnson left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. The B-spline output change is now its own commit with a doc line and a GTest that fails on main; ReconstructBiasFieldInto and MakeBiasFieldReconstructer replace the three copies; <utility> is included; the no-op DisconnectPipeline() is gone; and all buffers use one region.

Requesting changes, and the main item is my fault: the "empty buffered region, largest region = m_Size" state I suggested in round 1 lets a second Update() re-execute. Details inline.

Also, the bit-identity claim is not pinned in tree. Two of the #7075 GTests compare two runs of the same patched code, and the baseline test checks 5 pixels at relative 1e-4. All of them set ConvergenceThreshold(0.0) and never read the convergence measurement, so the rewritten CalculateConvergenceMeasurement has no test.

Non-blocking:

  • itkN4BiasFieldCorrectionImageFilter.hxx still includes itkBSplineControlPointImageFilter.h, which the header now provides.
  • testing.md names GTest files itkFooGTest.cxx; ...OutputGTest.cxx departs from that.
  • The PR body still ends with the "Generated with Claude Code" footer; the AI disclosure in <details> is enough (non-blocking).

@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from 53324d1 to 751c0ea Compare November 3, 2026 02:17
@gdevenyi

gdevenyi commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @hjmjohnson. I force-pushed 7f6f9b5 (N4) and 751c0ea (B-spline) with the inline items.

Bit identity. The convergence measurement is now asserted. On the outputs: the two exact-equality tests from #7075 compare equivalent configurations (a mask label against a binary mask, and a binary confidence image against a mask), both run on the patched code. The only comparison against main is the stored baseline at 1e-4 relative. A tighter in-tree pin against main would need stored values that hold on every platform. The N4 outputs here depend on libm (exp, log) and on the thread count through the B-spline fit, so I kept the tolerance. Out of tree, the N4 harness (MNI T1, four configurations) is byte-identical to main.

Non-blocking items:

  • The N4 .hxx no longer includes itkBSplineControlPointImageFilter.h.
  • The GTest is renamed to itkBSplineScatteredDataPointSetToImageFilterGTest.cxx. PERF: Compute B-spline fit kernel values once per axis per point #7072 adds a file with the same name, so whichever of the two merges second will need the two files combined; I'll do that rebase.
  • The PR body no longer has the footer.

ctest -R 'BSpline|N4|BiasCorrection' passes 34/34.

@gdevenyi
gdevenyi marked this pull request as ready for review November 3, 2026 02:23
Copilot AI balanced review requested due to automatic review settings November 3, 2026 02:23
@gdevenyi

gdevenyi commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main (f77bbc9) after #7072 and #7077 merged, together with #7075. The B-spline GoogleTest from this PR is now part of #7072's itkBSplineScatteredDataPointSetToImageFilterGTest.cxx, and the N4 refinement keeps #7077's skipped reconstruction. ctest -R 'BSpline|N4|BiasCorrection' passes 38/38.

@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from 751c0ea to 9c176f9 Compare November 3, 2026 02:24
@github-actions github-actions Bot removed the type:Infrastructure Infrastructure/ecosystem related changes, such as CMake or buildbots label Nov 3, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The test tolerance is smaller than the documented thread-dependent variation, so an unchanged implementation can fail when the fitting thread configuration differs from the single-thread reference.

1 open issue
What changed in this PR

This PR reduces allocation overhead in ITK’s N4 bias correction filter, building on the fit-point reuse work in #7075 while preserving the existing numerical operations.

Changes:

  • Reuse residual and bias-field buffers, update the uncorrected image in place, and compute convergence differences without a temporary image.
  • Skip sampled B-spline output allocation when output generation is disabled.
  • Add regression coverage for N4 results and B-spline output state across repeated updates.
File Description
Modules/​Filtering/​ImageGrid/​test/​itkBSplineScatteredDataPointSetToImageFilterGTest.cxx Tests unbuffered output, lattice equivalence, and repeated updates.
Modules/​Filtering/​ImageGrid/​include/​itkBSplineScatteredDataPointSetToImageFilter.hxx Allocates sampled output only when requested.
Modules/​Filtering/​ImageGrid/​include/​itkBSplineScatteredDataPointSetToImageFilter.h Documents output state when generation is disabled.
Modules/​Filtering/​BiasCorrection/​test/​itkN4BiasFieldCorrectionImageFilterGTest.cxx Adds mask, confidence, baseline, and convergence checks.
Modules/​Filtering/​BiasCorrection/​include/​itkN4BiasFieldCorrectionImageFilter.hxx Reuses fit data and iteration buffers and consolidates reconstruction setup.
Modules/​Filtering/​BiasCorrection/​include/​itkN4BiasFieldCorrectionImageFilter.h Declares reusable fit data and private reconstruction helpers.

Review effort: Balanced

@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from 9c176f9 to 848906e Compare November 3, 2026 02:56
@hjmjohnson
hjmjohnson dismissed their stale review November 3, 2026 03:14

Requested changes are addressed; dismissing my change request.

@hjmjohnson

Copy link
Copy Markdown
Member

@greptileai review

@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from 7af9818 to ef3eff1 Compare November 3, 2026 16:41
The fit points and weights depend only on the mask, the confidence
image and the input geometry. Build their containers once in
GenerateData, and in each iteration gather only the residual field
values, in parallel, into a fresh point set that shares the
containers, so releasing the fit's input cannot empty them. The
points, weights and values are unchanged, so the output is
bit-identical. GoogleTests compare a mask label with a binary mask, a
binary confidence image with a mask, and a mask label with a
confidence image against values from main.
Each N4 iteration allocated new residual, uncorrected and bias field
images through pipeline filters, plus a difference image for the
convergence test. Keep one residual buffer and two bias field buffers
that swap, and compute the subtractions and the component copy in
parallel loops with the same float arithmetic. One reconstructer output
per iteration remains. The reconstructer setup is shared by one helper.
With GenerateOutputImage off, BSplineScatteredDataPointSetToImageFilter
still allocated a full output image that it never wrote. Leave the
output with its geometry but empty regions then, so a caller cannot read
an unwritten buffer, and a later Update() of the unmodified filter does
not re-execute. N4 turns GenerateOutputImage off for each of its fits.
A GoogleTest checks the output state, a second Update(), and that the
control point lattice is unchanged.
@gdevenyi
gdevenyi force-pushed the perf-n4-reuse-iteration-buffers branch from ef3eff1 to bb504fe Compare November 4, 2026 00:39
@gdevenyi

gdevenyi commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main with #7092 merged (bb504fe, on #7075 at 3feef1f). Both PRs had added tests to itkBSplineScatteredDataPointSetToImageFilterGTest.cxx. This PR's OutputIsUnbufferedWithoutGenerateOutputImage now uses #7092's refit::MakePoints / refit::MakeFilter / refit::Values helpers instead of its own copies. The checks are unchanged, and the lattice is now read through an iterator. ctest -R "BSpline|N4|BiasCorrection" passes 41/41.

@hjmjohnson
hjmjohnson merged commit 84ce566 into InsightSoftwareConsortium:main Nov 4, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:Filtering Issues affecting the Filtering module type:Performance Improvement in terms of compilation or execution time type:Testing Ensure that the purpose of a class is met/the results on a wide set of test cases are correct

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants