Add standalone physics settle check over pooled layouts (#769)

## Summary
When a solver returns a pooled layouts, there are 2 types of
validations. One is analytical, fast, does not require SimApp, e.g.
check no overlapping & on relation (existing). The other involves
stepping physics, slow but more closely reflects how end user consumes,
e.g. physics stability.
In an ideal world, placement_enev shall only use valid layout everytime
thru `env.reset()`

## Detailed description
### Why
Agentic Env Gen requires a post-validation step to rule out envs with
unstable physics, and re-trigger generation if nothing valid. It has to
be automatic.

### How
`python isaaclab_arena/scripts/run_placement_pool_validation.py (--viz
kit --render) --num_envs 10 pick_and_place_maple_table`
The standalone script checks if physics settled by advancing physics
only, over the pool of layouts returned by the solver, and report
results.

### What
1. Refactored existing validation: 
- added a `PlacementValidationChecklist` data class to contain each
individual validation check results;
- included a required/optional validation failures to let user decide
which optimized layouts shall be selected as the best-ranked.
2. Added `physics_settle.py` to execute physics stepping without
rendering, and check linear_vel, and ang_vel if below thresholds.
3. Added `placement_pool_validation.py` orchestras how many episodes
over how many envs needed for the fixed pool of layouts
4. Added user-interface `run_placement_pool_validation.py` to execute
the check

## Next
Add integration with Pool filling and lookup table.
Ideal pipeline:
Each time pool is filled (after solver, before placement event) ->
[Optional] run physics check for all env's pool unvalidated layouts &
log it down -> Select (valid) one to load in placement events

---------

Signed-off-by: Xinjie Yao <xyao@nvidia.com>

Author: xyao-nv

isaaclab_arena/environments/arena_env_builder.py

@@ -30,6 +30,7 @@
 from isaaclab_arena.metrics.metric_base import MetricBase
 from isaaclab_arena.metrics.metric_term_cfg import MetricTermCfg
 from isaaclab_arena.metrics.recorder_manager_utils import metrics_to_recorder_manager_cfg
+from isaaclab_arena.relations.placement_events import PLACEMENT_RESET_EVENT_NAME
 from isaaclab_arena.tasks.no_task import NoTask
 from isaaclab_arena.utils.configclass import combine_configclass_instances, make_configclass
 from isaaclab_arena.utils.isaaclab_utils.simulation_app import reapply_viewer_cfg
@@ -189,7 +190,7 @@ def compose_manager_cfg(self) -> IsaacLabArenaManagerBasedRLEnvCfg:
         if self._placement_event_cfg is not None:
             PlacementEventCfg = make_configclass(
                 "PlacementEventCfg",
-                [("placement_reset", EventTermCfg, self._placement_event_cfg)],
+                [(PLACEMENT_RESET_EVENT_NAME, EventTermCfg, self._placement_event_cfg)],
             )
             placement_event_cfg = PlacementEventCfg()
         variations_event_cfg = self._compose_variations_event_cfg()

isaaclab_arena/relations/object_placer.py

@@ -12,6 +12,7 @@
 from isaaclab_arena.relations.bounding_box_helpers import assign_variants_for_envs, build_per_env_bounding_boxes
 from isaaclab_arena.relations.object_placer_params import ObjectPlacerParams
 from isaaclab_arena.relations.placement_result import MultiEnvPlacementResult, PlacementResult
+from isaaclab_arena.relations.placement_validation import PlacementCheck, PlacementValidationResults
 from isaaclab_arena.relations.relation_solver import RelationSolver
 from isaaclab_arena.relations.relations import (
     IsAnchor,
@@ -38,12 +39,17 @@ class PlacementCandidate:
     positions: dict[ObjectBase, tuple[float, float, float]]
     """Solved positions for each object."""
 
-    is_valid: bool
-    """Whether the placement passed validation checks."""
+    validation_results: PlacementValidationResults
+    """Per-check validation results for this candidate's layout."""
 
     orientations: dict[ObjectBase, float] = field(default_factory=dict)
     """Per-object yaw (radians about Z) sampled for this candidate. Empty when unrotated."""
 
+    @property
+    def is_valid(self) -> bool:
+        """True when all validation checks pass."""
+        return self.validation_results.do_all_required_validation_checks_pass()
+
 
 class ObjectPlacer:
     """High-level API for placing objects according to their spatial relations.
@@ -102,6 +108,16 @@ def place(
         )
         results_per_env = [env_results[0] for env_results in ranked_results_per_env]
 
+        if self.params.verbose:
+            # If no valid layout is found, print the failed checks for the lowest-loss fallback
+            # So we can debug the placement problem and it still produces some layouts for the envs
+            for env_idx, result in enumerate(results_per_env):
+                if not result.success:
+                    print(
+                        f"  env {env_idx}: no valid layout; using lowest-loss fallback "
+                        f"(failed: {result.validation_results.get_failed_validation_check_names})"
+                    )
+
         if self.params.apply_positions_to_objects:
             positions_per_env = [r.positions for r in results_per_env]
             orientations_per_env = [r.orientations for r in results_per_env]
@@ -235,7 +251,7 @@ def _place_ranked(
         ranked_results = [
             [
                 PlacementResult(
-                    success=candidate.is_valid,
+                    validation_results=candidate.validation_results,
                     positions=candidate.positions,
                     final_loss=candidate.loss,
                     attempts=attempts_per_result,
@@ -257,13 +273,19 @@ def _rank_candidates(
         num_envs: int,
         candidates_per_env: int,
     ) -> list[list[PlacementCandidate]]:
-        """Return one loss-sorted candidate slice per env (valid candidates first)."""
+        """Return one ranked candidate slice per env: most validation checks passed first, then lowest loss."""
         ranked_candidate_slices: list[list[PlacementCandidate]] = []
         for cur_env in range(num_envs):
             start = cur_env * candidates_per_env
             env_candidates = candidates[start : start + candidates_per_env]
             ranked_candidate_slices.append(
-                sorted(env_candidates, key=lambda candidate: (not candidate.is_valid, candidate.loss))
+                sorted(
+                    env_candidates,
+                    key=lambda candidate: (
+                        *candidate.validation_results.get_number_of_required_and_optional_failures,
+                        candidate.loss,
+                    ),
+                )
             )
         return ranked_candidate_slices
 
@@ -602,17 +624,26 @@ def _validate_placement(
         self,
         positions: dict[ObjectBase, tuple[float, float, float]],
         env_bboxes: dict[ObjectBase, AxisAlignedBoundingBox],
-    ) -> bool:
+    ) -> PlacementValidationResults:
         """Validate that no two objects overlap in 3D and On relations are satisfied.
 
         Args:
             positions: Dictionary mapping objects to their solved (x, y, z) positions.
             env_bboxes: Per-object bboxes for the current env, each with shape (1, 3).
 
         Returns:
-            True if no overlaps exist and On relations hold, False otherwise.
+            PlacementValidationResults containing the validation results.
         """
-        return self._validate_no_overlap(positions, env_bboxes) and self._validate_on_relations(positions, env_bboxes)
+        no_overlap = self._validate_no_overlap(positions, env_bboxes)
+        on_relation = self._validate_on_relations(positions, env_bboxes)
+
+        return PlacementValidationResults(
+            validation_results={
+                PlacementCheck.NO_OVERLAP: no_overlap,
+                PlacementCheck.ON_RELATION: on_relation,
+            },
+            required_checks={PlacementCheck.NO_OVERLAP, PlacementCheck.ON_RELATION},
+        )
 
     def _apply_poses(
         self,

isaaclab_arena/relations/physics_settle_params.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2025-2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PhysicsSettleParams:
+    """Configuration for the in-sim physics settle check."""
+
+    num_steps: int = 5
+    """Number of env steps to advance before reading back object state in the settle check. The settle
+    check converts this to ``num_steps * decimation`` physics substeps internally."""
+
+    lin_vel_thresh: float = 0.1
+    """Max per-object linear speed (m/s) after settling. Above this the layout is considered unsettled."""
+
+    ang_vel_thresh: float = 0.1
+    """Max per-object angular speed (rad/s) after settling. Above this the layout is considered unsettled."""

isaaclab_arena/relations/placement_events.py

@@ -13,19 +13,86 @@
 from isaaclab_arena.relations.pooled_object_placer import PooledObjectPlacer
 from isaaclab_arena.relations.relations import RotateAroundSolution, get_anchor_objects
 from isaaclab_arena.utils.pose import Pose, rotate_quat_by_yaw
+from isaaclab_arena.utils.velocity import Velocity
 
 if TYPE_CHECKING:
     from isaaclab_arena.assets.object_base import ObjectBase
+    from isaaclab_arena.relations.placement_result import PlacementResult
 
 IDENTITY_ROTATION_XYZW = (0.0, 0.0, 0.0, 1.0)
 
+# Name of the reset event term that owns the pooled object placer
+PLACEMENT_RESET_EVENT_NAME = "placement_reset"
+
+
+def get_placement_pool(env) -> PooledObjectPlacer | None:
+    """Return the pooled placer registered on the env, or ``None`` when the env has no pooled placement.
+
+    Lets a runtime caller reach the pool (e.g. to run the post-reset settle check) from the env alone,
+    without holding the builder. The pool is reached through the env's event manager.
+
+    Args:
+        env: The gym-wrapped Isaac Lab env; the base env is reached via ``env.unwrapped``.
+    """
+    try:
+        term_cfg = env.unwrapped.event_manager.get_term_cfg(PLACEMENT_RESET_EVENT_NAME)
+    except ValueError:
+        return None
+    return term_cfg.params.get("placement_pool")
+
 
 def get_rotation_xyzw(obj: ObjectBase) -> tuple[float, float, float, float]:
     """Return the RotateAroundSolution rotation for *obj*, or identity if none."""
     rotate_marker = next((r for r in obj.get_relations() if isinstance(r, RotateAroundSolution)), None)
     return rotate_marker.get_rotation_xyzw() if rotate_marker else IDENTITY_ROTATION_XYZW
 
 
+def get_base_rotation_per_object(objects: list[ObjectBase]) -> dict[ObjectBase, tuple[float, float, float, float]]:
+    """Return the base rotation for each object."""
+    return {obj: get_rotation_xyzw(obj) for obj in objects}
+
+
+def get_movable_object_names(
+    objects: list[ObjectBase],
+    anchor_objects_set: set[ObjectBase],
+) -> list[str]:
+    """Return the names of non-anchor objects."""
+    return [obj.name for obj in objects if obj not in anchor_objects_set]
+
+
+def write_layout_to_sim(
+    env: ManagerBasedEnv,
+    env_id: int,
+    result: PlacementResult,
+    anchor_objects_set: set[ObjectBase],
+    base_rotations: dict[ObjectBase, tuple[float, float, float, float]],
+) -> None:
+    """Write one env's solved layout into the sim.
+
+    Even writing zero velocity, the sim will still apply gravity and other forces from collisions,
+    so collided objects will still be subject to move.
+
+    Args:
+        env: The Isaac Lab ManagerBasedEnv environment.
+        env_id: The environment index.
+        result: The placement result to write to the sim.
+        anchor_objects_set: The set of anchor objects.
+        base_rotations: The base rotations for all objects.
+    """
+    env_id_tensor = torch.tensor([env_id], device=env.device)
+    zero_velocity = Velocity.zero().to_tensor(device=env.device).unsqueeze(0)
+    for obj, pos in result.positions.items():
+        if obj in anchor_objects_set:
+            continue
+        asset = env.scene[obj.name]
+        rotation_xyzw = rotate_quat_by_yaw(base_rotations[obj], result.orientations.get(obj, 0.0))
+        pose = Pose(position_xyz=pos, rotation_xyzw=rotation_xyzw)
+        pose_t_xyz_q_xyzw = pose.to_tensor(device=env.device).unsqueeze(0)
+        pose_t_xyz_q_xyzw[0, :3] += env.scene.env_origins[env_id, :]
+        asset.write_root_pose_to_sim(pose_t_xyz_q_xyzw, env_ids=env_id_tensor)
+        asset.write_root_velocity_to_sim(zero_velocity, env_ids=env_id_tensor)
+
+
 def solve_and_place_objects(
     env: ManagerBasedEnv,
     env_ids: torch.Tensor | None,
@@ -61,24 +128,14 @@ def solve_and_place_objects(
         results_by_env = dict(zip(reset_env_ids, reset_results))
 
     anchor_objects_set = set(get_anchor_objects(objects))
-    base_rotations = {obj: get_rotation_xyzw(obj) for obj in objects if obj not in anchor_objects_set}
+    base_rotations = get_base_rotation_per_object(objects)
 
-    zero_velocity = torch.zeros(1, 6, device=env.device)
     for cur_env in reset_env_ids:
-        env_id_tensor = torch.tensor([cur_env], device=env.device)
         result = results_by_env[cur_env]
         if not result.success:
             print(
                 "Warning: Writing best-loss fallback placement for "
                 f"env {cur_env}; layout failed strict placement validation."
             )
-        for obj, pos in result.positions.items():
-            if obj in anchor_objects_set:
-                continue
-            asset = env.scene[obj.name]
-            rotation_xyzw = rotate_quat_by_yaw(base_rotations[obj], result.orientations.get(obj, 0.0))
-            pose = Pose(position_xyz=pos, rotation_xyzw=rotation_xyzw)
-            pose_t_xyz_q_xyzw = pose.to_tensor(device=env.device).unsqueeze(0)
-            pose_t_xyz_q_xyzw[0, :3] += env.scene.env_origins[cur_env, :]
-            asset.write_root_pose_to_sim(pose_t_xyz_q_xyzw, env_ids=env_id_tensor)
-            asset.write_root_velocity_to_sim(zero_velocity, env_ids=env_id_tensor)
+        # only write the non-anchor objects to the sim
+        write_layout_to_sim(env, cur_env, result, anchor_objects_set, base_rotations)