Makes DataGenConfig.max_num_failures actually bound a Mimic generation run (#7433)

# Description

`DataGenConfig.max_num_failures` is documented as *"Maximum number of
failures allowed before stopping generation"* and eighteen shipped Mimic
environment configs set it to `25`. Nothing reads it.

```console
$ git grep -c max_num_failures
source/isaaclab/isaaclab/envs/mimic_env_cfg.py:1          # the definition
source/isaaclab_mimic/isaaclab_mimic/envs/*.py:18         # eighteen assignments
```

No third entry: there is no read anywhere in the repository, and the
field has been inert since Isaac Lab Mimic was introduced in #179.
`env_loop` counts `num_failures` and then never consults it; its only
termination is

```python
check_val = num_success if generation_guarantee else num_attempts
if check_val >= generation_num_trials:
```

With `generation_guarantee = True` (which those same eighteen configs
also set), a task whose success rate is low retries without any bound,
and the one knob that claims to stop that does nothing. On our own data
generation this cost 337 attempts for 10 demos before we discovered the
cap was not real.

### Reproduction, on a stock task

```bash
./isaaclab.sh -p scripts/imitation_learning/isaaclab_mimic/generate_dataset.py \
  --task Isaac-Stack-Cube-Franka-IK-Rel-Mimic-v0 \
  --input_file ./datasets/annotated_dataset.hdf5 \
  --output_file /tmp/out.hdf5 \
  --generation_num_trials 30 --num_envs 10 --headless
```

`FrankaCubeStackIKRelMimicEnvCfg` sets `max_num_failures = 25`.
Observed:

| | successes | failures | attempts |
|---|---|---|---|
| before | 30 | **50** | 80 |
| after (`max_num_failures = 25`) | 12 | **25** | 37 |

Before the change the run passed the configured cap and kept going,
ending at twice it. After, it stops on the attempt that reaches 25
failures and says so:

```
Reached 25 failures (max_num_failures=25) after 12/30 successes. Exiting.
```

### On the default

Wiring the field up exactly as written would abort the primary
documented workflow. At the ~36% success rate measured above,
`--generation_num_trials 1000` needs on the order of 1800 failures, so a
cap of 25 would end the run after roughly forty attempts. Since the
eighteen assignments were inert when they were written and no current
behaviour depends on them, they are removed here and the default becomes
`None`, meaning no limit. **Runs behave exactly as they do today unless
a limit is explicitly requested.**

If maintainers would rather the shipped configs keep an active cap, that
is a one-line change per config and I am happy to make it — it just
needs a value that suits large runs.

### Tests

`source/isaaclab_mimic/test/test_generation_failure_cap.py` drives
`env_loop` with a fake environment whose `step()` consumes scripted
attempt outcomes and refills the action queue, so the loop's own
termination logic runs unmodified with no simulator or dataset behind
it; a step-count fuse turns an unbounded loop into a failed assertion.
Six cases: the cap stops a run that never succeeds; `None` keeps the
guarantee unbounded as before; enough successes still end the run first;
a cap reached short of the target ends it; attempt-based termination
with the guarantee off is untouched (×2).

Against the unpatched loop the two cap-dependent cases fail (`'fuse' ==
'exited'`, and `(3, 4) == (2, 4)` — the loop overran the cap and
collected an extra success) and the four asserting unchanged behaviour
pass.

## Type of change

- Bug fix (non-breaking change which fixes an issue)

## Checklist

- [x] I have read and understood the contribution guidelines
- [ ] I have run the `pre-commit` checks with `./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have added a changelog fragment under
`source/<pkg>/changelog.d/` for every touched package
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01JFz91VMgmrjS4XR6f9Q9Z2

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 2047767028-lang

CONTRIBUTORS.md

@@ -123,6 +123,7 @@ Guidelines for modifications:
 * Jiwen Cai
 * Johnson Sun
 * Juana Du
+* Kai Pei
 * Kaixi Bao
 * Kourosh Darvish
 * Kousheek Chakraborty

source/isaaclab/changelog.d/mimic-max-num-failures.rst

@@ -0,0 +1,8 @@
+Fixed
+^^^^^
+
+* Fixed :attr:`~isaaclab.envs.mimic_env_cfg.DataGenConfig.max_num_failures` being ignored. The field
+  documented a cap on failed generation attempts but was never read, so a run with
+  :attr:`~isaaclab.envs.mimic_env_cfg.DataGenConfig.generation_guarantee` enabled retried without
+  bound on a task with a low success rate. Its default is now ``None`` (no limit) and setting it to
+  an integer stops generation once that many attempts have failed.

source/isaaclab/isaaclab/envs/mimic_env_cfg.py

@@ -38,8 +38,21 @@ class DataGenConfig:
     Keeping failed demonstrations is useful for visualizing and debugging low success rates.
     """
 
-    max_num_failures: int = 50
-    """Maximum number of failures allowed before stopping generation."""
+    max_num_failures: int | None = None
+    """Maximum number of failed generation attempts before stopping, or None for no limit.
+
+    Only applies together with :attr:`generation_guarantee`. With the guarantee enabled, generation
+    keeps retrying until :attr:`generation_num_trials` demos succeed, so a task whose success rate is
+    low can run for an unbounded number of attempts; this caps that. Defaults to None so the
+    guarantee keeps its usual meaning unless a limit is asked for.
+
+    With the guarantee disabled, generation already stops after :attr:`generation_num_trials`
+    attempts and this field is ignored, so setting it cannot cut a fixed-attempt run short.
+
+    The bound is read once per simulation step. Attempts that end on the step that crosses it are
+    already complete, so a run over ``num_envs`` parallel environments can record up to
+    ``num_envs - 1`` failures beyond the bound; it is exact whenever attempts end on separate steps.
+    """
 
     seed: int = 1
     """Seed for randomization to ensure reproducibility."""

source/isaaclab_mimic/changelog.d/mimic-max-num-failures.rst

@@ -0,0 +1,14 @@
+Fixed
+^^^^^
+
+* Fixed the Mimic generation loop never bounding a run by failure count. ``env_loop`` now stops when
+  ``datagen_config.max_num_failures`` failed attempts have accumulated, alongside the existing stop
+  on enough successes or attempts.
+
+Removed
+^^^^^^^
+
+* Removed the ``datagen_config.max_num_failures = 25`` assignment from the shipped Mimic environment
+  configs. The field was never read when those lines were written, so honouring it now would newly
+  cap every shipped task at 25 failed attempts and cut short any run asking for a large number of
+  demos. Set the field explicitly to opt into a cap.

source/isaaclab_mimic/isaaclab_mimic/datagen/generation.py

@@ -140,6 +140,18 @@ def env_loop(
                     print(f"Reached {generation_num_trials} successes/attempts. Exiting.")
                     break
 
+                # with the success guarantee on, nothing else bounds the run: a task that rarely
+                # succeeds retries forever. max_num_failures is the opt-in bound on that. Without the
+                # guarantee the check above already stops on generation_num_trials attempts, so the
+                # cap has nothing to add and must not cut a fixed-attempt run short.
+                max_num_failures = env.cfg.datagen_config.max_num_failures
+                if generation_guarantee and max_num_failures is not None and num_failures >= max_num_failures:
+                    print(
+                        f"Reached {num_failures} failures (max_num_failures={max_num_failures}) after"
+                        f" {num_success}/{generation_num_trials} successes. Exiting."
+                    )
+                    break
+
             # check that simulation is stopped or not
             if env.sim.is_stopped():
                 break

source/isaaclab_mimic/isaaclab_mimic/envs/agibot_place_toy2box_mimic_env_cfg.py

@@ -32,7 +32,6 @@ def __post_init__(self):
         self.datagen_config.generation_select_src_per_subtask = True
         self.datagen_config.generation_transform_first_robot_pose = False
         self.datagen_config.generation_interpolate_from_last_target_pose = True
-        self.datagen_config.max_num_failures = 25
         self.datagen_config.seed = 1
 
         # The following are the subtask configurations for the stack task.

source/isaaclab_mimic/isaaclab_mimic/envs/agibot_place_upright_mug_mimic_env_cfg.py

@@ -29,7 +29,6 @@ def __post_init__(self):
         self.datagen_config.generation_select_src_per_subtask = True
         self.datagen_config.generation_transform_first_robot_pose = False
         self.datagen_config.generation_interpolate_from_last_target_pose = True
-        self.datagen_config.max_num_failures = 25
         self.datagen_config.seed = 1
 
         # The following are the subtask configurations for the stack task.

source/isaaclab_mimic/isaaclab_mimic/envs/exhaustpipe_gr1t2_mimic_env_cfg.py

@@ -30,7 +30,6 @@ def __post_init__(self):
         self.datagen_config.generation_joint_pos = False
         self.datagen_config.generation_transform_first_robot_pose = False
         self.datagen_config.generation_interpolate_from_last_target_pose = True
-        self.datagen_config.max_num_failures = 25
         self.datagen_config.num_demo_to_render = 10
         self.datagen_config.num_fail_demo_to_render = 25
         self.datagen_config.seed = 10

source/isaaclab_mimic/isaaclab_mimic/envs/franka_bin_stack_ik_rel_mimic_env_cfg.py

@@ -28,7 +28,6 @@ def __post_init__(self):
         self.datagen_config.generation_transform_first_robot_pose = False
         self.datagen_config.generation_interpolate_from_last_target_pose = True
         self.datagen_config.generation_relative = True
-        self.datagen_config.max_num_failures = 25
         self.datagen_config.seed = 1
 
         # The following are the subtask configurations for the stack task.

source/isaaclab_mimic/isaaclab_mimic/envs/franka_stack_ik_abs_mimic_env_cfg.py

@@ -27,7 +27,6 @@ def __post_init__(self):
         self.datagen_config.generation_select_src_per_subtask = True
         self.datagen_config.generation_transform_first_robot_pose = False
         self.datagen_config.generation_interpolate_from_last_target_pose = True
-        self.datagen_config.max_num_failures = 25
         self.datagen_config.seed = 1
 
         # The following are the subtask configurations for the stack task.