Import upstream snapshot c19f713c415a699a79d71cd96aa13c3104a05047

Upstream: https://github.com/michaelgillett/mjlab
Upstream-Commit: c19f713c415a699a79d71cd96aa13c3104a05047
Upstream-Branch: main

docs/source/terminations.rst

@@ -0,0 +1,70 @@
+.. _terminations:
+
+Terminations
+============
+
+Termination terms define when an episode ends. Each term is a function
+that returns a boolean per-environment tensor every step. The
+termination manager aggregates all terms and reports the result to the
+training framework as either a terminal failure or a truncation.
+
+Each term is registered by name with a ``TerminationTermCfg``. Setting
+``time_out=True`` marks the condition as a truncation rather than a
+terminal failure. Truncations map to the ``truncated`` signal in the
+Gym interface; failures map to ``terminated``. This distinction matters
+for value bootstrapping: the agent should estimate future value beyond
+a truncation but not beyond a failure.
+
+.. code-block:: python
+
+    from mjlab.envs.mdp import terminations
+    from mjlab.managers.termination_manager import TerminationTermCfg
+
+    terminations_cfg = {
+        "time_out": TerminationTermCfg(
+            func=terminations.time_out, time_out=True,
+        ),
+        "fallen": TerminationTermCfg(
+            func=terminations.bad_orientation,
+            params={"limit_angle": 1.0},
+        ),
+    }
+
+
+Built-in termination functions
+-------------------------------
+
+The functions below are available in ``mjlab.envs.mdp.terminations`` and
+are shared across tasks. Individual tasks may define additional
+termination functions specific to their objective. All termination
+functions return a boolean tensor of shape ``[num_envs]``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 72
+
+   * - Function
+     - Description
+   * - ``time_out``
+     - Returns ``True`` when the episode length reaches
+       ``env.max_episode_length``. Register with ``time_out=True`` so
+       the manager treats it as a truncation.
+   * - ``bad_orientation``
+     - Returns ``True`` when the angle between the asset's up axis and
+       world up exceeds ``limit_angle`` (radians).
+   * - ``root_height_below_minimum``
+     - Returns ``True`` when the asset's root link height is below
+       ``minimum_height`` (meters).
+   * - ``nan_detection``
+     - Returns ``True`` when NaN or Inf values appear anywhere in the
+       physics state. A safety net to terminate diverged simulations
+       cleanly.
+
+
+Writing custom termination functions
+-------------------------------------
+
+Custom termination functions follow the same patterns as reward
+functions. A plain function accepts ``env`` and returns a boolean
+``[num_envs]`` tensor. See :ref:`env-config-term-pattern` for the
+general pattern.