[PERF] Share static-geometry raycast BVH across envs (N trees, not B)

[Kashu7100]

Summary

The raycast BVH (Raycaster / DepthCamera) is allocated per env — nodes, aabbs, morton_codes, and the radix-sort scratch are all shape=(n_envs, …). For a high-poly static terrain this per-env replication is the dominant GPU-memory cost and OOMs at a few thousand envs — even though the per-env trees are identical (or fall into a handful of distinct variants), and the cast already reads batch 0 once #2867's runtime check finds them identical (that saves cast work, not memory).

This adds RigidOptions.shared_static_raycast_bvh (default False). When True, the static (fully-fixed) collision BVH is allocated per distinct geometry rather than per env — envs that share geometry share one tree:

• homogeneous scene → 1 shared tree
• N variants across n_envs (N ≪ n_envs, e.g. a terrain curriculum) → N trees

Mechanism

Two routing arrays unify all three layouts: env_bvh_idx[n_env] (which tree each env casts against — arange per-env, 0 shared, group id grouped) and batch_repr_env[n_batches] (which env's geometry builds each tree). The cast kernels index env_bvh_idx; update_aabbs builds each tree slot from its representative env. Groups are derived from the per-env active-geom-range signature in batched links_info (the data Genesis already populates for heterogeneous envs), so N variants yield N groups automatically. The per-env path is env_bvh_idx=arange (unchanged); #2867's runtime shared detection becomes env_bvh_idx=0.

Why opt-in

Env-identity is a runtime property — a per-env set_pos on a fixed body diverges geometry after build (exercised by test_lidar_bvh_parallel_env), and detecting it requires the per-env trees we're eliminating. The flag is a caller guarantee the static geometry stays as built. Default False preserves current behavior + the runtime detection exactly.

Benchmark

Raycast DepthCamera over static eden_dwbp terrain (RTX 3080), total GPU memory (mem_get_info — BVH lives in Quadrants fields invisible to torch.cuda.max_memory_allocated):

scene	envs	per-env (off)	shared/grouped (on)	reduction
1 terrain (8087 faces)	256	775 MB	154 MB	5.0×
1 terrain	1024	2884 MB	366 MB	7.9×
1 terrain	4096	OOM	runs	—
4 terrains	1024	7300 MB	530 MB	13.8×

Depth is bit-identical to the per-env path (homogeneous and N-variant); cast speed unchanged (each env already read its tree; build is one-time).

Tests

• test_raycaster_shared_static_bvh: homogeneous → 1 tree, shared, distances identical across envs.
• test_raycaster_grouped_static_bvh: 3 variants × 12 envs → 3 trees, env_bvh_idx == [0,0,0,0,1,1,1,1,2,2,2,2], grouped distances bit-identical to per-env reference.
• Default + per-env set_pos divergence covered by test_lidar_bvh_parallel_env; heterogeneous fall-back by test_raycaster_heterogeneous_object. Full raycaster/lidar suite passes.

Notes

• Composes with the per-sensor distances-only mode ([PERF] Add distances-only mode to raycaster (return_points=False) #2908) — orthogonal memory levers.
• For a solver mixing static terrain with a moving entity (e.g. a robot), maybe_static is solver-wide so the flag has no effect there yet; it composes with a static/dynamic BVH split to extend the benefit to those scenes.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a530b7776c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[github-actions]

⚠️ Abnormal Benchmark Result Detected ➡️ Report