Files
2026-11-03 19:46:08 +08:00

163 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Environment setup
The simulation/learning sources are **vendored in this repository**:
`rl/mjlab` and `rl/rsl_rl`. G1 and T1 models required by the registered examples are also bundled,
with their licenses. No external mjlab checkout, personal directory layout or asset download is
needed for these examples. See [VENDOR.md](VENDOR.md) for exact origins and retained modifications.
## Supported reference target
The locked training target is **Linux x86-64, Python 3.11–3.13, NVIDIA CUDA 13.0 PyTorch**.
Python 3.13 is the tested interpreter. A compatible NVIDIA driver is required; the Python lock
cannot install a driver or guarantee support for every GPU. EGL is the default offscreen renderer.
Other OS/architectures and CUDA builds need a separately validated lock; there is no native-CPU
training fallback.
Before installing, the standard-library detector works without simulation packages:
```bash
python3 .agents/skills/setup-env/scripts/detect.py
```
## Recommended: locked installation in a new environment
Install `uv`, then run from the repository root:
```bash
uv sync --locked --extra dev --python 3.13
./scripts/uh doctor
./scripts/uh verify-vendor
./scripts/check
```
`uv.lock` pins transitive dependencies and artifact hashes, including the PyTorch CUDA index and
NVIDIA Warp index. `--locked` refuses to silently resolve a changed project. `uv sync` installs
this project as editable and creates `.venv`; it does not reuse another project's environment.
Large CUDA wheels may take time to download. Do not interpret a partial download as an installed
runtime.
## Standard pip editable installation
The same packaging layout supports `pip install -e .`, as in Jumper. **mjlab and rsl_rl are included
in this distribution**, not separately installed PyPI packages. Always use a fresh virtual environment:
```bash
python3.13 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
```
This convenient command resolves the declared dependencies but does not enforce the entire
transitive lock. For the locked pip alternative, install the exported requirements first:
```bash
.venv/bin/python -m pip install --require-hashes -r requirements-linux-cu130.lock \
--extra-index-url https://download.pytorch.org/whl/cu130 \
--extra-index-url https://pypi.nvidia.com/
.venv/bin/python -m pip install --no-deps -e .
```
The exported file contains exact versions and hashes. It targets the same Linux CUDA environment,
not all platforms. Regenerate it from `uv.lock`, never edit it by hand:
```bash
uv export --locked --extra dev --no-emit-project --format requirements-txt \
--output-file requirements-linux-cu130.lock
```
Do not install `mjlab` or `rsl-rl-lib` separately. `doctor` checks package origins and detects
conflicting distributions. Repair a polluted environment by creating a new one, not by uninstalling
packages from another project's shared runtime. Installed wheels include the same model resources
and licenses; the source inventory check itself requires a repository checkout.
## Lightweight CI environment
`.github/workflows/check.yml` checks locks, licenses/layout, source inventory, wheel resource
parity, lint/format and core tests on hosted Linux/Python 3.13. Actions use immutable revisions;
the resolver is version-pinned. No GPU runtime is installed by this job, so backend-dependent
tests skip rather than claiming a simulator pass. The GPU gates below remain separate.
The `ci` dependency group is locked in `uv.lock`. Its small hashed pip export is
`requirements-ci.lock`; regenerate it with:
```bash
uv export --locked --only-group ci --no-emit-project --format requirements-txt \
--output-file requirements-ci.lock
```
CI regenerates both exports and rejects Git diffs. To reproduce its environment without replacing
your training `.venv`, use another directory:
```bash
UV_PROJECT_ENVIRONMENT=.venv-ci uv sync --locked --only-group ci --python 3.13
uv pip install --python .venv-ci/bin/python --no-deps --no-build-isolation -e .
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv-ci/bin/python -m pytest -q
```
The wheel is built with `--no-isolation`, using the locked build tools, rather than downloading
an unpinned build environment. CI is triggered by pushes, pull requests and manual dispatch after
this repository is hosted on GitHub; a local Git commit does not itself execute GitHub Actions.
## Run the setup gates
```bash
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/g1_smoke.json --output runs/setup-g1
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/t1_smoke.json --output runs/setup-t1
```
The script runs vendor inventory, backend/CUDA/version checks, dependency consistency,
`check-robot`, and a bounded GPU smoke. It preserves a log for every gate and a JSON summary;
any failed gate gives a nonzero exit. It does not install packages, change gains, repair assets
or weaken checks. Use a new output directory each time.
`check-robot` validates declared interfaces AND measured contact response; it does not prove
locomotion or physical safety. See [NEW_ROBOT.md](NEW_ROBOT.md).
## Interpreter and optional asset configuration
`scripts/uh` chooses an explicit executable `UH_PYTHON`, otherwise the project `.venv/bin/python`,
otherwise `python3` from PATH. The project must be installed in that interpreter. A bad explicit
path fails; it never falls back to another project's environment. The launcher clears inherited
`PYTHONPATH`/user-site leakage and does not inject source directories. An installed `uh` entry
point also works from outside the repository.
`scripts/uh` rejects legacy `MJLAB_ROOT` and `UH_EXTRA_PYTHONPATH` overrides. Unset them when migrating.
The installed Python entry point also enforces vendored import origins; those old variables cannot select a backend.
Use `UH_PYTHON` only to select another **installed, compatible** environment.
Optional external asset discovery/override:
```bash
export UNITREE_ROBOTS_ROOT=/path/to/unitree_ros/robots
./scripts/uh assets
./scripts/uh inspect-asset "$UNITREE_ROBOTS_ROOT/g1_description/g1_29dof.xml"
# Optional T1 replacement, not required for the bundled example:
export BOOSTER_ASSETS_ROOT=/path/to/booster_assets
```
An explicit Booster override expects `robots/T1/T1_23dof.xml` and referenced meshes. An invalid
override fails rather than silently using the bundled asset. G1 training uses the bundled adapted
G1 model, not Unitree ROS XML. External model changes require a new conformance report and source/
asset provenance; an inventory entry is not a registered task.
## Lightweight configuration inspection
`list` and `plan` do not import the simulation stack. If intentionally inspecting source without
an install, `PYTHONPATH=src python -m universal_humanoid list` remains a metadata-only convenience;
it is **not** a supported way to select a training backend.
## Troubleshooting
- **Backend shadowing:** inspect `doctor` origins. Both backends must resolve to this checkout's
`rl/` (editable install), or the packages installed by the same built wheel.
- **Core version mismatch:** restore the documented lock in a new environment.
- **No CUDA:** check driver compatibility and GPU access; CPU discovery is not a training pass.
- **Vendor mismatch:** inspect the diff against `rl/VENDOR.json` / `rl/upstream/import.json`;
do not regenerate the inventory just to hide an unexplained change.
- **Robot gate failed:** read the failed check IDs and actual/declared values. Do not widen a
tolerance or remove a foot/sensor requirement merely to turn the report green.
- **Historical run rejected:** restore its trusted recorded source/assets/dependencies separately;
vendoring intentionally changes provenance. Do not rewrite old hashes.