Repository navigation
Deprecate *_tiled tile query aliases #1885
Description
Background
Warp exposes two names for each tiled BVH and mesh query operation:
| Keep | Deprecate |
|---|---|
tile_bvh_query_aabb |
bvh_query_aabb_tiled |
tile_bvh_query_ray |
bvh_query_ray_tiled |
tile_bvh_query_next |
bvh_query_next_tiled |
tile_mesh_query_aabb |
mesh_query_aabb_tiled |
tile_mesh_query_aabb_next |
mesh_query_aabb_next_tiled |
Both naming forms were introduced together in 430a9fb. The implementation describes the tile_* names as backward-compatibility aliases and treats the *_tiled names as primary, but this does not match the API's release history.
The tile_* convention makes the cooperative, block-synchronous behavior explicit and is consistent with the naming of other tile primitives. Keeping both forms permanently adds API, documentation, stub, and test surface without providing different behavior.
A targeted downstream check found:
- Newton uses
wp.tile_mesh_query_aabb()andwp.tile_mesh_query_aabb_next()in its enabled tiled query path. - MuJoCo Warp uses neither naming form.
- Neither repository uses any of the
*_tilednames.
Proposed change
Make the tile_* names canonical and deprecate the five *_tiled aliases.
This would not change query behavior. During the deprecation window, the aliases would continue to work while directing users to the corresponding tile_* names.
Tasks
- Audit broader public and internal usage before introducing deprecation warnings.
- Add deprecation warnings for the five
*_tiledfunctions, including their replacements. - Update the API documentation, generated stubs, tests, and examples to use
tile_*. - Replace comments that incorrectly describe
tile_*as backward-compatibility aliases. - Add the deprecated aliases to the Pending Removal table in
design/deprecations.md, following its column conventions and recording the replacement APIs and planned removal version. - Add a changelog fragment and select a removal release consistent with Warp's deprecation policy.
- File a follow-up GitHub issue for removing the aliases and assign it to the milestone for the intended removal release.
Activity
christophercrouzet commentedon Sep 16, 2026
Addressed in commit 6098a5e.
Deprecate the *_tiled query aliases (NVIDIAGH-1885)
shi-eric commentedon Sep 17, 2026
This is addressed by 6098a5e, with supporting documentation updates in 52176a2.
Public API behavior
Warp 1.18 deprecates
wp.bvh_query_aabb_tiled(),wp.bvh_query_ray_tiled(),wp.bvh_query_next_tiled(),wp.mesh_query_aabb_tiled(), andwp.mesh_query_aabb_next_tiled(). Each alias remains functional during the deprecation window and directs users to its correspondingwp.tile_*name.The warnings are emitted during kernel code generation. A cached kernel may therefore defer the warning until the module is recompiled.
The canonical
tile_*functions retain the existing query behavior and are now the primary documentation and example locations. The Warp call sites and named downstream checks recorded in this issue did not require migrations.Removal of the deprecated aliases in Warp 1.22.0 is tracked in #1967.
Test coverage
warp/tests/geometry/test_bvh.pyandwarp/tests/geometry/test_mesh_query_aabb.pywere relabeled as compatibility coverage. No dedicated warning assertions were added.Behavioral verification
Compilation probes confirmed that all five deprecated aliases emit
DeprecationWarningwith the correct replacement, while the canonical names compile without deprecation warnings. BVH AABB, BVH ray, and mesh AABB query results remained unchanged.