SPH onto a Grid

Overview

The functions sph4grid2D and sph4grid3D compute Smooth Particle Hydrodynamics (SPH) estimates of either:

  • density fields (if f is None)

  • scalar fields (if f is provided)

on a regular Cartesian grid.

They are built on top of the SPH2D and SPH3D KDTree-based SPH implementations and use nearest-neighbour smoothing with a cubic kernel.

sph4grid2D

Description

Estimates SPH density or field values on a 2D Cartesian grid.

Algorithm

  1. Build KDTree using SPH2D

  2. Assign particle masses

  3. Construct regular grid

  4. Define subsampling offsets within each pixel

  5. For each offset: - shift grid positions - compute SPH estimate

  6. Average over all subsamples

  7. Reshape into (nxgrid, nygrid)

Example

# To compute the density field
dgrid = fiesta.sph.sph4grid2D(x, y, boxsize=100, ngrid=256)

# To compute the field
fgrid = fiesta.sph.sph4grid2D(x, y, boxsize=100, ngrid=256, f=f)

# Compute the field and output the x and y grid
fgrid, xg, yg = fiesta.sph.sph4grid2D(
    x, y,
    boxsize=100,
    ngrid=256,
    outputgrid=True
)

sph4grid3D

Same as sph4grid2D but extended to 3D SPH grid estimation.

Algorithm

  1. Build KDTree using SPH3D

  2. Assign masses

  3. Create 3D grid

  4. Generate subsampling offsets inside each voxel

  5. For each offset: - shift grid positions - evaluate SPH density or field

  6. Average over subsamples

  7. Reshape into (nxgrid, nygrid, nzgrid)

Performance Notes

  • Computational cost scales as: - O(Ngrid × subsampling^d)

  • 3D is significantly more expensive than 2D

  • Nearest-neighbour search dominates runtime

  • Recommended: - keep k modest (20–50) - avoid large subsampling unless necessary

Example

# To compute the density field
dgrid = fiesta.sph.sph4grid3D(x, y, z, boxsize=100, ngrid=128)

# To compute the field
fgrid = fiesta.sph.sph4grid3D(x, y, z, boxsize=100, ngrid=128, f=f)

# Compute the field and output the x and y grid
fgrid, xg, yg, zg = fiesta.sph.sph4grid3D(
    x, y, z,
    boxsize=100,
    ngrid=128,
    outputgrid=True
)

Notes

  • If mass is not provided, all particles are assumed to have unit mass.

  • Periodic boundaries are handled internally in the KDTree construction.

  • Subsampling improves accuracy by reducing pixel-center bias.

API Reference

fiesta.sph.sph4grid2D(x: ndarray, y: ndarray, boxsize: float | List[float], ngrid: int | List[int], f: ndarray | None = None, origin: float | List[float] = 0.0, mass: ndarray | None = None, k: int = 20, periodic: bool = True, subsampling: int = 1, outputgrid: bool = False) → ndarray | Tuple[ndarray, ndarray, ndarray]

Estimates a field on a regular grid based on SPH k neighbours.

Parameters:

  • x (array) – Cartesian coordinates of the input points.

  • y (array) – Cartesian coordinates of the input points.

  • boxsize (float or list of float) – Size of the box in each dimension.

  • ngrid (int or list of int) – Number of grid points in each dimension.

  • f (array, optional) – Field values at the input points.

  • origin (float or list of float, optional) – Origin of the grid.

  • mass (array, optional) – Mass of the input points. If not provided, it is assumed to be 1 for all points.

  • k (int, optional) – Number of nearest neighbors to consider.

  • periodic (bool or list of bool, optional) – Whether to use periodic boundary conditions.

  • subsampling (int, optional) – Subsampling factor for the output grid.

  • outputgrid (bool, optional) – Whether to output the grid coordinates.

Returns:

  • dgrid (array) – Density field on the regular grid, if f is None.

  • fgrid (array) – Estimated field on the regular grid, if f is provided.

  • x2d, y2d (array) – Grid coordinates, if outputgrid is True.

fiesta.sph.sph4grid3D(x: ndarray, y: ndarray, z: ndarray, boxsize: float | List[float], ngrid: int | List[int], f: ndarray | None = None, origin: float | List[float] = 0.0, mass: ndarray | None = None, k: int = 32, periodic: bool = True, subsampling: int = 1, outputgrid: bool = False) → ndarray | Tuple[ndarray, ndarray, ndarray]

Estimates a field on a regular grid based on SPH k neighbours.

Parameters:

  • x (array) – Cartesian coordinates of the input points.

  • y (array) – Cartesian coordinates of the input points.

  • z (array) – Cartesian coordinates of the input points.

  • boxsize (float or list of float) – Size of the box in each dimension.

  • ngrid (int or list of int) – Number of grid points in each dimension.

  • f (array, optional) – Field values at the input points.

  • origin (float or list of float, optional) – Origin of the grid.

  • mass (array, optional) – Mass of the input points. If not provided, it is assumed to be 1 for all points.

  • k (int, optional) – Number of nearest neighbors to consider.

  • periodic (bool or list of bool, optional) – Whether to use periodic boundary conditions.

  • subsampling (int, optional) – Subsampling factor for the output grid.

  • outputgrid (bool, optional) – Whether to output the grid coordinates.

Returns:

  • dgrid (array) – Density field on the regular grid, if f is None.

  • fgrid (array) – Estimated field on the regular grid, if f is provided.

  • x3d, y3d, z3d (array) – Grid coordinates, if outputgrid is True.