163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
# 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.
|