View page source

warp.HashGrid#

class warp.HashGrid(*args, **kwargs)[source]#

Hash-based spatial grid for accelerated neighbor queries on point data.

Supports float16, float32, and float64 precision via the dtype parameter.

Concept of Grouped HashGrid:

A grouped hash grid partitions point buckets by a user-provided integer group id. This is useful for storing particles from many independent environments in a single grid while keeping neighbor queries local to one environment.

In a standard hash grid, all points sharing a spatial cell are stored together, so kernels that need environment isolation must query all candidates and filter out points from other environments. Grouped hash grids keep each cell’s points sorted by group id, and warp.hash_grid_query() accepts an optional group id that restricts traversal to that group’s points only. This avoids cross-group candidate iteration while preserving the ungrouped query path when no group is passed.

Unlike grouped BVH queries, grouped hash-grid queries do not require a separate root lookup. Pass the same group id used at build time directly to warp.hash_grid_query().

Class representing a hash grid object for accelerated point queries.

id#

Unique identifier for this hash grid object, can be passed to kernels.

device#

Device this object lives on, all buffers must live on the same device.

dtype#

Scalar data type (float16, float32, or float64).

Note

float16 grids have limited precision (~3.3 decimal digits, max ~65504). Large coordinates or small cell widths may cause incorrect cell assignments.

Parameters:

  • dim_x (int) – Number of cells in x-axis

  • dim_y (int) – Number of cells in y-axis

  • dim_z (int) – Number of cells in z-axis

  • device – Device to create the hash grid on

  • dtype – Scalar data type for point coordinates (default: float32)

Methods

build(points, radius[, groups])

Update the hash grid data structure.

reserve(num_points[, with_groups])

Reserve enough memory to build the grid for the given number of points.
build(points, radius, groups=None)[source]#

Update the hash grid data structure.

This method rebuilds the underlying datastructure and should be called any time the set of points changes.

Parameters:

  • points (warp.array) – Array of points matching the grid’s dtype (vec3h for float16, vec3/vec3f for float32, vec3d for float64)

  • radius (float) – The cell size to use for bucketing points, cells are cubes with edges of this width. For best performance the radius used to construct the grid should match closely to the radius used when performing queries.

  • groups – Optional array of point group indices of data type warp.int32. When provided, the grid is partitioned by group so grouped queries only visit points with the requested group id. This is intended for independent environments or worlds whose particles should not interact, even when their coordinates overlap. Omitting the group argument in warp.hash_grid_query() preserves the all-points traversal behavior. Group ids may be arbitrary int32 values and are consumed on-device, so group assignments may change between rebuilds, including during CUDA graph replay.

reserve(num_points, with_groups=False)[source]#

Reserve enough memory to build the grid for the given number of points.

Reserving ahead of CUDA graph capture makes subsequent build() calls of up to num_points points allocation-free, without requiring a warm-up build before capture.

Parameters:

  • num_points (int) – Number of points the grid should accommodate.

  • with_groups (bool) – Also reserve the buffers used by grouped builds, so that a grouped build() (with groups) is allocation-free as well.