Add nested multi-resolution volume render backend by ojessop01 · Pull Request #337 · SWIFTSIM/swiftsimio

ojessop01 · 2026-06-24T17:50:17Z

Implement efficient Sparse Multi-Scale Grid algorithm (Benitez-Llambay 2025)
for 3D volume rendering of SPH data. Particles are hierarchically assigned
to grid levels based on kernel smoothing length, then scattered onto
coarse-to-fine grids and upsampled back to target resolution. This bounds
per-particle work regardless of smoothing length, providing significant
speedups for simulations with wide kernel distributions.

Features:

New nested grid backend accessible via backend="nested" parameter
Adaptive hierarchy with configurable target voxels per kernel (ntarget)
and number of levels (nlevels)
Kernel arithmetic matches scatter.py implementation (Wendland-C2)
Parallel support via Numba prange
Trilinear upsampling for hierarchy collapse
Efficient bounding-box tracking to skip empty regions

API additions:

render_voxel_grid() and render_gas() now accept backend, ntarget, nlevels
backends dict updated to include "nested" alongside "scatter"
Added validation and warnings for backend-specific parameters

Tests:

Added TestNestedVolumeRender class with serial/parallel matching tests
Tests cover periodic boundary conditions and edge cases
Comparison against single-resolution backend validates correctness

Documentation:

Updated volume_render.rst with nested backend description and examples
Added parameter documentation for ntarget and nlevels

Code quality:

Passes ruff linter
Passes numpydoc validation
All existing tests continue to pass

Implement efficient Sparse Multi-Scale Grid algorithm (Benitez-Llambay 2025) for 3D volume rendering of SPH data. Particles are hierarchically assigned to grid levels based on kernel smoothing length, then scattered onto coarse-to-fine grids and upsampled back to target resolution. This bounds per-particle work regardless of smoothing length, providing significant speedups for simulations with wide kernel distributions. Features: - New nested grid backend accessible via backend="nested" parameter - Adaptive hierarchy with configurable target voxels per kernel (ntarget) and number of levels (nlevels) - Kernel arithmetic matches scatter.py implementation (Wendland-C2) - Parallel support via Numba prange - Trilinear upsampling for hierarchy collapse - Efficient bounding-box tracking to skip empty regions API additions: - render_voxel_grid() and render_gas() now accept backend, ntarget, nlevels - backends dict updated to include "nested" alongside "scatter" - Added validation and warnings for backend-specific parameters Tests: - Added TestNestedVolumeRender class with serial/parallel matching tests - Tests cover periodic boundary conditions and edge cases - Comparison against single-resolution backend validates correctness Documentation: - Updated volume_render.rst with nested backend description and examples - Added parameter documentation for ntarget and nlevels Code quality: - Passes ruff linter - Passes numpydoc validation - All existing tests continue to pass Refs: Benitez-Llambay A., 2025, MNRAS (in prep) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

kyleaoman · 2026-06-24T21:09:45Z

Thanks Owen, looks promising. Presumably this can be trivially translated to the 2D ("project") case? And maybe slice, too? Or do you think it's not worth it because that scales as N^2 instead of N^3?

ojessop01 · 2026-06-24T21:16:20Z

Yes this could be trivially extended to 2d projection and slice and would scale much better than the current implementations. I just haven't had a chance to implement this and ensure all the formatting etc is correct and the documentation written.

kyleaoman · 2026-06-24T21:22:03Z

Great, and not a problem - marking this as draft for now if you plan to add that (if not feel free to mark ready for review).

ojessop01 · 2026-06-24T22:07:12Z

i plan to add eventually but not sure when I can get around to it. I will submit this ready for review for now.

kyleaoman

Hi Owen,

Sorry to leave this hanging for a while, for some reason I thought that you were still planning edits. Anyway some suggestions for you here, all fairly straightforward. Will want to make sure Josh is happy to merge this before we do, too.

kyleaoman · 2026-09-05T13:57:24Z

+       resolution=256,
+       project="masses",
+       parallel=True,
+       backend="scatter",


Suggested change

backend="scatter",

backend="scatter", # the default

kyleaoman · 2026-09-05T13:57:53Z

+
+   data = load("cosmo_volume_example.hdf5")
+
+   # Standard backend — identical results, familiar behaviour.


Suggested change

# Standard backend — identical results, familiar behaviour.

# Standard backend

kyleaoman · 2026-09-05T14:01:10Z

+:math:`\mathcal{O}(n_\mathrm{target}^3)` regardless of smoothing length by
+scattering large particles onto a coarser grid and trilinearly upsampling
+the result back to the finest grid afterwards. This follows the Sparse
+Multi-Scale Grid approach described in Benitez-Llambay (2025).


Suggested change

Multi-Scale Grid approach described in Benitez-Llambay (2025).

Multi-Scale Grid approach described in `Benítez-Llambay (2025)`_.

_Benítez-Llambay (2025): https://iopscience.iop.org/article/10.3847/2515-5172/addab2

kyleaoman · 2026-09-05T14:03:26Z

+received mass is upsampled at each level, so the collapse cost scales with
+the number of particles rather than the grid volume.


Suggested change

received mass is upsampled at each level, so the collapse cost scales with

the number of particles rather than the grid volume.

received mass is upsampled at each level, so the collapse cost scales

approximately with the number of particles rather than the grid volume.

kyleaoman · 2026-09-05T14:06:53Z

+   out = backends["nested"](
+       x=x, y=y, z=z, h=h, m=m, res=res,
+       ntarget=6,
+       nlevels=4,
+   )


Suggested change

out = backends["nested"](

x=x, y=y, z=z, h=h, m=m, res=res,

ntarget=6,

nlevels=4,

)

out = backends["nested"](

x=x,

y=y,

z=z,

h=h,

m=m,

res=res,

ntarget=6,

nlevels=4,

)

kyleaoman · 2026-09-05T14:42:29Z

+        Controls the accuracy/speed trade-off. Default is 6.
+
+    nlevels : int
+        Maximum number of coarsening levels in the hierarchy. Default is 4.


Suggested change

Maximum number of coarsening levels in the hierarchy. Default is 4.

Maximum number of coarsening levels in the hierarchy. Default is ``4``.

kyleaoman · 2026-09-05T14:43:26Z

+
+    Returns
+    -------
+    np.ndarray[np.float32, np.float32, np.float32]


Is content of brackets correct? Thought it was type then shape?

kyleaoman · 2026-09-05T14:44:05Z

+
+    ntarget : int
+        Target number of voxels spanned by each kernel at its assigned level.
+        Controls the accuracy/speed trade-off. Default is 6.


Suggested change

Controls the accuracy/speed trade-off. Default is 6.

Controls the accuracy/speed trade-off. Default is ``6``.

kyleaoman · 2026-09-05T14:44:15Z

+        Controls the accuracy/speed trade-off. Default is 6.
+
+    nlevels : int
+        Maximum number of coarsening levels in the hierarchy. Default is 4.


Suggested change

Maximum number of coarsening levels in the hierarchy. Default is 4.

Maximum number of coarsening levels in the hierarchy. Default is ``4``.

kyleaoman · 2026-09-05T14:44:35Z

+
+    Returns
+    -------
+    np.ndarray[np.float32, np.float32, np.float32]


Again hint on the dtype and shape is incorrectly formatted?

ojessop01 and others added 2 commits June 24, 2026 18:38

deleted .ipynb test notebook

f665092

Copilot AI review requested due to automatic review settings June 24, 2026 17:50

Copilot started reviewing on behalf of ojessop01 June 24, 2026 17:50 View session

Copilot AI reviewed Jun 24, 2026

kyleaoman marked this pull request as draft June 24, 2026 21:21

kyleaoman added enhancement New feature or request performance An issue that is impacting performance visualisation Visualisation-related issues labels Jun 24, 2026

ojessop01 marked this pull request as ready for review June 24, 2026 22:07

Fix linting issues.

f91b22d

kyleaoman self-requested a review September 5, 2026 13:56

kyleaoman requested changes Sep 5, 2026

View reviewed changes


		data = load("cosmo_volume_example.hdf5")

		# Standard backend — identical results, familiar behaviour.

	# Standard backend — identical results, familiar behaviour.
	# Standard backend

-Multi-Scale Grid approach described in Benitez-Llambay (2025).
+Multi-Scale Grid approach described in `Benítez-Llambay (2025)`_.
+_Benítez-Llambay (2025): https://iopscience.iop.org/article/10.3847/2515-5172/addab2

		received mass is upsampled at each level, so the collapse cost scales with
		the number of particles rather than the grid volume.

	Maximum number of coarsening levels in the hierarchy. Default is 4.
	Maximum number of coarsening levels in the hierarchy. Default is ``4``.

	Controls the accuracy/speed trade-off. Default is 6.
	Controls the accuracy/speed trade-off. Default is ``6``.

Uh oh!

Conversation

ojessop01 commented Jun 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

kyleaoman commented Jun 24, 2026

Uh oh!

ojessop01 commented Jun 24, 2026

Uh oh!

kyleaoman commented Jun 24, 2026

Uh oh!

ojessop01 commented Jun 24, 2026

Uh oh!

kyleaoman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants