Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -75,16 +75,12 @@ src/unilab/assets/motions/g1/**/*.npz
src/unilab/assets/motions/g1/**/*.csv
src/unilab/assets/motions/g1/flip
src/unilab/assets/motions/g1/flip_npz
src/unilab/assets/motions/x2/*.npz
src/unilab/assets/motions/x2/*.csv

# Robot mesh assets (downloaded from HF at runtime)
src/unilab/assets/bots/
src/unilab/assets/robots/x2/meshes/*.STL
src/unilab/assets/robots/g1/assets/
src/unilab/assets/robots/g1/textures/
src/unilab/assets/robots/go2/assets/
src/unilab/assets/robots/allegro_hand/assets/
src/unilab/assets/robots/sharpa_wave/meshes/

# Grasp cache assets (downloaded from HF at runtime)
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ rewriting the task's environment lifecycle.
becoming a CUDA-resident simulator. The learner can run on CUDA, ROCm, MPS,
or XPU; the [support matrix](https://unilabsim.github.io/UniLab-doc/en/5-reference/5-support_matrix.html)
records the evidence level of each backend/task combination.
- **Accelerate replay-based off-policy training.** FastSAC/FlashSAC/WarpSAC lets
- **Accelerate replay-based off-policy training.** FastSAC/FlashSAC lets
simulation data collection overlap with learner updates. The paper reports
3–10× end-to-end gains on representative configurations; see [Why UniLab](https://unilabsim.github.io/UniLab-doc/en/why_unilab.html)
for scope and measurements.
Expand Down
2 changes: 1 addition & 1 deletion README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ learner,而无需重写任务的 environment 生命周期。
不必先变成 CUDA-resident simulator,也可以向 accelerator learner 提供数据;learner
可以运行在 CUDA、ROCm、MPS 或 XPU 上。每个 backend/task 组合的证据等级请查看
[支持矩阵](https://unilabsim.github.io/UniLab-doc/zh_CN/5-reference/5-support_matrix.html)。
- **加速 replay-based off-policy 训练。** FastSAC/FlashSAC/WarpSAC 让仿真数据采集与 learner
- **加速 replay-based off-policy 训练。** FastSAC/FlashSAC 让仿真数据采集与 learner
update 重叠。论文在代表性配置上报告了 3–10 倍端到端收益;测量范围和限制见
[为什么选择 UniLab](https://unilabsim.github.io/UniLab-doc/zh_CN/why_unilab.html)。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ orphan: true
## Context

[Discussion #1541](https://github.com/Motphys/UniLab/discussions/1541)
指出,legacy domain-randomization provider 与 SimToolReal 大量工具模型瓶颈有共同根因:
指出,legacy domain-randomization provider 与大量工具模型瓶颈有共同根因:
backend 缺少 per-env model identity / model-field indirection。因此 task 曾被迫在
UniLab 侧编译多个 engine model,或在 reset 协议中扩展模型变更语义。

Expand Down Expand Up @@ -94,7 +94,7 @@ backend 名称、可选 package import、executor introspection 或异常降级

- 让 task config 直接持有或返回 `MjSpec`。拒绝原因:task YAML 变成 MuJoCo-specific,
UniSim 难以保持 MJWarp 兼容,且 public plan 不再 pickle-safe。
- 在 UniLab 为每个 env 编译完整 model。拒绝原因:这正是 SimToolReal 内存和冷启动
- 在 UniLab 为每个 env 编译完整 model。拒绝原因:这正是大量工具模型内存和冷启动
瓶颈,并把 engine realization 上移到错误 owner。
- 在 reset provider 中切换 model identity。拒绝原因:破坏派生常量、CUDA graph 和
playback 的生命周期假设,也会延长 legacy DR 协议共存。
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ fail closed,也没有可审计的 runtime evidence。
- 新增共享 off-policy owner 设置
`training.cuda_process_sharing: null | mps`,默认 `null` 保持现状。
- 初始有效范围限定为 Linux、NVIDIA CUDA、`training.sim_backend=mjwarp`、单主机、
`world_size=1` 的 SAC/FastSAC/FlashSAC/WarpSAC 共享路径。
`world_size=1` 的 SAC/FastSAC/FlashSAC 共享路径。
- `mps` 是显式请求:所有前置条件在 env probe、learner construction 与 collector
spawn 之前验证,失败时给出第一个未满足条件和启动既有 daemon 的命令,不 fallback。
- rank-local 物理一致性按 GPU UUID 判断,而不是 CUDA ordinal。
Expand Down Expand Up @@ -69,7 +69,6 @@ fail closed,也没有可审计的 runtime evidence。
- `src/unilab/scripts/train_offpolicy.py`
- `src/unilab/conf/sac/config.yaml`
- `src/unilab/conf/flashsac/config.yaml`
- `src/unilab/conf/warpsac/config.yaml`
- `tests/training/test_cuda_process_sharing.py`
- `tests/algos/test_offpolicy_double_buffer_runner.py`
- `docs/sphinx/source/en/2-user_guide/1-training/7-tensor_runtime_production.md`
Expand Down
4 changes: 1 addition & 3 deletions docs/sphinx/source/api_reference/tasks/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
Concrete RL tasks split by family:

- **locomotion** — Go2 and Unitree G1 reference owners
- **manipulation** — Allegro in-hand cube and Stewart balance
- **motion_tracking** — G1 and X2 whole-body motion tracking
- **motion_tracking** — G1 whole-body motion tracking

Every task is registered into the task `Registry` so it can be selected via
`uv run train --algo <algo> --task <name> --sim <backend>`.
Expand All @@ -14,7 +13,6 @@ Unitree production variants are documented in `unitree_rl_unilab`.
:maxdepth: 2

locomotion
manipulation
motion_tracking
```

Expand Down
11 changes: 0 additions & 11 deletions docs/sphinx/source/api_reference/tasks/manipulation.md

This file was deleted.

3 changes: 1 addition & 2 deletions docs/sphinx/source/api_reference/tasks/motion_tracking.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `unilab.tasks.motion_tracking`

Whole-body motion-tracking tasks for G1 and X2 robots.
Whole-body motion-tracking tasks for G1 robots.

```{eval-rst}
.. autosummary::
Expand All @@ -10,5 +10,4 @@ Whole-body motion-tracking tasks for G1 and X2 robots.

unilab.tasks.motion_tracking.common
unilab.tasks.motion_tracking.g1
unilab.tasks.motion_tracking.x2
```
1 change: 0 additions & 1 deletion docs/sphinx/source/en/0-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,6 @@ committed benchmark manifest or separate recommendation metadata.
| --- | --- | --- |
| Go2 joystick | PPO, FlashSAC | PPO has tested MuJoCo and Motrix rows. FlashSAC has MuJoCo owner YAMLs for `go2_joystick_flat`. |
| G1 reference locomotion / tracking | PPO, APPO, SAC | PPO, APPO, and SAC include committed MuJoCo and Motrix owner YAMLs for retained G1 tasks. |
| Allegro in-hand | PPO, APPO | PPO and APPO have committed MuJoCo and Motrix owner YAMLs for Allegro in-hand tasks. |

Unitree production task families are maintained in `unitree_rl_unilab` and are
not counted as core repository evidence.
Expand Down
13 changes: 2 additions & 11 deletions docs/sphinx/source/en/1-getting_started/1-quick_demo.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,8 @@ Run a pre-trained policy before changing any task configuration:
uv run demo dance
```

Available demo names are `teaser`, `dance`, `wallflip`, `boxtracking`,
and `inhandgrasp`. Use `uv run demo --help` for device and refresh
options.
Available demo names are `teaser` and `dance`. Use `uv run demo --help` for
device and refresh options.

## Train A Task

Expand Down Expand Up @@ -75,14 +74,6 @@ community mirror before running training, eval, or demo commands:
export HF_ENDPOINT=https://hf-mirror.com
```

X2 robot meshes auto-download from Hugging Face (`unilabsim/unilab-robots`) into
`src/unilab/assets/robots/x2/meshes/` on first run; no manual step is needed. To
pre-fetch them:

```bash
uv run unilab-pull-assets --robot x2
```

On macOS, the CLI routes Motrix interactive playback through `mxpython` when
needed. Use `--render-mode record` for headless video export or
`--render-mode none` to skip rendering.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ keeps the lower-level scripts available for debugging Hydra composition.
| APPO | `uv run train --algo appo --task <task> --sim <backend>` | `src/unilab/scripts/train_appo.py` |
| SAC | `uv run train --algo sac --task <task> --sim <backend>` | `src/unilab/scripts/train_sac.py` |
| FlashSAC | `uv run train --algo flashsac --task <task> --sim <backend>` | `src/unilab/scripts/train_flashsac.py` |
| WarpSAC | `uv run train --algo warpsac --task <task> --sim <backend>` | `src/unilab/scripts/train_warpsac.py` |

Examples:

Expand Down Expand Up @@ -109,13 +108,10 @@ dependency; the `viser.*` config group (`viser.port`, `viser.max_envs`,

```bash
uv run demo dance
uv run demo wallflip
uv run demo boxtracking
uv run demo inhandgrasp
uv run demo dance --refresh --device cpu
```

Available demos: `teaser`, `dance`, `wallflip`, `boxtracking`, `inhandgrasp`.
Available demos: `teaser`, `dance`.
Each demo fetches a pre-trained checkpoint from the
`unilabsim/unilab-checkpoints` Hugging Face dataset on first run and caches it
under `src/unilab/assets/checkpoints/<demo>/model_0.pt`. Pass `--refresh` to
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ persistent backend, which keeps each unsmoothed iteration value.

This page first covers the log directory shared by all algorithms and the
Manager-Based reward metric contract, then documents the off-policy terminal used by
SAC / FlashSAC / WarpSAC and APPO. Persisted backend tags follow the canonical schema
SAC / FlashSAC and APPO. Persisted backend tags follow the canonical schema
owned by `uni_rl.logging.metric_schema`: millisecond timing fields end in `_ms`,
while `Perf/learning_time`, `Perf/collection_time`, and `Perf/iteration_time` are
seconds. A few terminal fields (`Other`, phase percentages, collector cycle total,
Expand All @@ -31,7 +31,6 @@ stack overrides `training.log_root` or `training.log_dir`:
| APPO | `logs/appo/<task>/` | `src/unilab/conf/appo/config.yaml` |
| SAC | `logs/fast_sac/<task>/` | `src/unilab/conf/sac/config.yaml` |
| FlashSAC | `logs/flash_sac/<task>/` | `src/unilab/conf/flashsac/config.yaml` |
| WarpSAC | `logs/warp_sac/<task>/` | `src/unilab/conf/warpsac/config.yaml` |

A run directory is named `YYYY-MM-DD_HH-MM-SS_<sim_backend>`, for example
`2026-03-09_18-30-00_mujoco`. Common artifacts include `run_config.json`,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Tensor runtime

SAC, FlashSAC, and WarpSAC resolve their spawn-facing tensor-runtime settings
SAC and FlashSAC resolve their spawn-facing tensor-runtime settings
before probing the environment or constructing a learner. The owner YAML values
are collected into one bounded `TensorRuntimeSettings` object and passed to the
off-policy runner. Invalid values, unsupported bounds, and impossible memory
Expand Down
2 changes: 0 additions & 2 deletions docs/sphinx/source/en/2-user_guide/2-algorithms/0-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ lives, and which command shape selects it. For general flags, see
| APPO | async on-policy | `src/unilab/scripts/train_appo.py` | `src/unilab/conf/appo/config.yaml` |
| SAC | off-policy | `src/unilab/scripts/train_sac.py` | `src/unilab/conf/sac/config.yaml` |
| FlashSAC | off-policy | `src/unilab/scripts/train_flashsac.py` | `src/unilab/conf/flashsac/config.yaml` |
| WarpSAC | off-policy | `src/unilab/scripts/train_warpsac.py` | `src/unilab/conf/warpsac/config.yaml` |

```{toctree}
:hidden:
Expand All @@ -19,5 +18,4 @@ lives, and which command shape selects it. For general flags, see
2-appo
3-sac
4-flash_sac
5-warpsac
```
27 changes: 0 additions & 27 deletions docs/sphinx/source/en/2-user_guide/2-algorithms/5-warpsac.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/sphinx/source/en/2-user_guide/3-backends/0-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ provided.
FlashSAC `g1_motion_tracking`.
- SuperDex requires the `superdex` extra on CPython 3.12/3.13 Linux x86_64 and
provides a CPU-authoritative packed HOST_BRIDGE; the current scope is the
configured Go2 and FR3 research owners.
configured Go2 research owner.
- Drake requires the locally built DrakeUni batch extension. Its scoped PPO
`go2_joystick_flat` owner uses CPU physics and the packed HOST_BRIDGE
lifecycle; floating-root and reset-randomization events remain disabled until
Expand Down
56 changes: 6 additions & 50 deletions docs/sphinx/source/en/2-user_guide/3-backends/8-superdex.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,22 @@
# SuperDex Backend

> SuperDex participates in the tensor-only Manager runtime as a packed CPU
> `HOST_BRIDGE` backend. Its Go2 and FR3 owners remain **Configured** research
> `HOST_BRIDGE` backend. Its Go2 owner remains a **Configured** research
> profiles, not full-training or cross-platform production claims.


SuperDex is an optional CPU physics adapter owned by `unisim.backend.superdex`.
The initial UniLab owner is the fixed-base `FR3JointTarget` task:
`src/unilab/conf/ppo/task/fr3_joint_target/superdex.yaml`. It uses seven torque
actions, 21 observation values, selected tensor joint-state resets, and
`TorchEnv`. Its support level is **Configured**; bounded rollout or short
training checks do not establish full-training performance or platform support.
The implementation is tracked in [#1534](https://github.com/Motphys/UniLab/issues/1534)
under [roadmap #1533](https://github.com/Motphys/UniLab/issues/1533).
The checked-in owner is `go2_joystick_flat/superdex`. Its support level is
**Configured**; bounded rollout or short training checks do not establish
full-training performance or platform support.

## Installation

SuperDex Physics/Robotics 1.0.0 is published as Python wheels and is an
optional UniLab extra; no native source build is required. The wheels carry
the native batch executor and support CPython 3.12/3.13 on Linux x86_64 only;
on other platforms the extra is empty and the CLI reports a targeted runtime
diagnostic. CPU physics does not require CUDA. The FR3 owner has no record
(video) playback — the `.superdex_bot` asset carries no MJCF visual model — so
play defaults to the native interactive viewer (`play_render_mode=interactive`
with `play_env_num=1`); use `training.play_render_mode=none` for headless runs.
diagnostic. CPU physics does not require CUDA.

```bash
# Source checkout (default Python 3.13; wheels support CPython 3.12/3.13):
Expand All @@ -42,19 +35,7 @@ are a temporary unilabsim build (`superdex-physics-uni` /
the `superdex-physics` / `superdex-robotics` wheels, UniSim switches the
package names and UniLab needs no change.

Native FR3 assets are hosted on Hugging Face
([unilabsim/unilab-robots](https://huggingface.co/datasets/unilabsim/unilab-robots)),
like the other robot mesh assets; the wheels do not carry robot binaries. The
asset hub registers `bots/arms/fr3_v2/fr3_v2.superdex_bot` and downloads the
snapshot into `src/unilab/assets/` on first use, checking its collision SDF,
render files, `LICENSE` and `NOTICE` before constructing physics. To pre-fetch
the assets (e.g. for CI or offline prep):

```bash
uv run unilab-pull-assets --robot fr3_v2
```

To audit a local `project_superdex` checkout instead, set
To audit a local `project_superdex` checkout, set
`SUPERDEX_ASSETS_PATH=/absolute/path/to/project_superdex/assets`, or set
`env.superdex_assets_root=/absolute/path/to/project_superdex/assets` to
override it for a specific owner invocation. An explicit root takes precedence
Expand All @@ -65,20 +46,6 @@ A local source build is only needed when changing the SuperDex engine itself:
builds the native extensions and links the local UniSim/UniLab checkouts
editable. Regular use does not need it.

## Run the FR3 Task

```bash
uv run --no-sync train --algo ppo --task fr3_joint_target --sim superdex \
algo.max_iterations=2 algo.num_steps_per_env=16 \
algo.algorithm.num_learning_epochs=1
```

The target joint positions, rewards, reset ranges and action scales live in the
task's `base.yaml`. The torque bounds `[20,20,20,20,5,5,5]` Nm are an explicit
research profile, not rated hardware limits. `superdex_effort_limits` declares
the same bounds at the native backend boundary. The SDK remains single-threaded;
the native scene executor below owns all supported CPU parallelism.

## Run the Go2 Task

The `go2_joystick_flat/superdex` owner trains and evaluates the Go2 quadruped
Expand Down Expand Up @@ -213,17 +180,6 @@ through the production playback session and executes 64 SuperDex control steps
without a renderer. It checks finite values and interface compatibility; a
two-iteration checkpoint is not expected to walk reliably.

```bash
uv run --no-sync pytest tests/assets/test_superdex_assets.py \
tests/envs/test_fr3_superdex.py tests/test_cli_runtime_requirements.py -q
```

The optional native tests require the SDK and the FR3 assets (downloaded from
Hugging Face on demand, or provided through `SUPERDEX_ASSETS_PATH`); they cover
finite rollout data, selected reset isolation, immediate observation refresh
and a spawned `EnvFactory`. Missing runtime/assets produce an explicit skip;
such a run is not native validation. The base asset/config tests need no native
asset checkout.

Engine conversion and physics live in UniSim; asset registration, Hydra and task
terms remain in UniLab. See
Expand Down
9 changes: 1 addition & 8 deletions docs/sphinx/source/en/2-user_guide/4-tasks/0-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,7 @@ Go2 and G1 core reference owners; Unitree production variants are downstream.
:::{grid-item-card} Motion tracking
:link: 2-motion_tracking
:link-type: doc
G1/X2 motion-tracking reference profiles.
:::

:::{grid-item-card} Manipulation
:link: 3-manipulation
:link-type: doc
Allegro in-hand rotation and grasp generation.
G1 motion-tracking reference profiles.
:::

::::
Expand All @@ -31,5 +25,4 @@ Allegro in-hand rotation and grasp generation.

1-locomotion
2-motion_tracking
3-manipulation
```
Loading
Loading