116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# Vendored dependencies
|
|
|
|
Two upstream packages live under `rl/` as **modifiable copies** (forks) rather than pip
|
|
dependencies.
|
|
|
|
| Directory | Upstream | Version | Why fork it |
|
|
|---|---|---|---|
|
|
| `rl/mjlab/` | [mujocolab/mjlab](https://github.com/mujocolab/mjlab) | 1.6.0 | We cut a seam between the manager layer and the physics engine — an invasive change |
|
|
| `rl/rsl_rl/` | [leggedrobotics/rsl_rl](https://github.com/leggedrobotics/rsl_rl) | 5.4.2 | Planned algorithm work (distillation / AMP / custom PPO variants) |
|
|
|
|
The version pairing is not arbitrary: **5.4.2 is exactly the `rsl-rl-lib` version mjlab
|
|
1.6.0 pins.** Check mjlab's constraint before changing either.
|
|
|
|
## Provenance
|
|
|
|
Both are taken unmodified from the official PyPI release artifacts:
|
|
|
|
- **mjlab 1.6.0** — unpack the wheel, take the `mjlab/` package directory
|
|
- **rsl_rl 5.4.2** — unpack the sdist, take the `rsl_rl/` package directory
|
|
|
|
Neither package directory carries its licence — that sits at the root of each upstream
|
|
repository — so each copy has a `LICENSE` added beside it, taken from the release tag:
|
|
`rl/mjlab/LICENSE` from mjlab `v1.6.0` (Apache-2.0) and `rl/rsl_rl/LICENSE` from rsl_rl
|
|
`v5.4.2` (BSD-3-Clause). Both licences require the text to travel with the code. What the
|
|
two upstreams in turn took from elsewhere — Isaac Lab in `mjlab/utils/lab_api/`, MuJoCo
|
|
Menagerie's robots in `mjlab/asset_zoo/`, pfrl in `rsl_rl/modules/normalization.py` — has
|
|
its licence in [`licenses/`](../licenses/) at the repository root, and
|
|
[`NOTICE`](../NOTICE) says which file covers what.
|
|
|
|
`rl/mjlab/asset_zoo/` is 34 MB of robot meshes (Unitree Go1 / G1 and the i2rt YAM arm). It is **kept, not pruned**:
|
|
a faithful copy makes rebasing onto upstream clean, and mjlab's own Go1 / G1 tasks are a
|
|
ready-made reference for checking that the seam did not change behaviour.
|
|
|
|
## Layout: why under `rl/`
|
|
|
|
Package locations are declared explicitly by the two package roots in `pyproject.toml`:
|
|
|
|
```toml
|
|
[tool.setuptools.packages.find]
|
|
where = [".", "rl"]
|
|
include = ["tasks*", "scenes*", "controller*", "mjrl*", "mjlab*", "rsl_rl*"]
|
|
```
|
|
|
|
`rl/` itself has **no** `__init__.py`, so `mjlab` and `rsl_rl` remain top-level packages —
|
|
upstream's own `import mjlab.envs` needs no edit.
|
|
|
|
The point of this layout is to make **which copy you get independent of which directory you
|
|
run from**. Put the copies at the repository root and the root is implicitly on `sys.path`:
|
|
running from the repo root picks up the copy, running from anywhere else picks up the pip
|
|
version, and the two behave differently in ways that are hard to notice. Under `rl/` that
|
|
implicit path does not exist.
|
|
|
|
**The cost is that installation goes from optional to mandatory.** `rl/` is not on
|
|
`sys.path`, so without `pip install -e .` an `import mjlab` simply fails — there is no
|
|
"happens to work" middle state. That is deliberate: an implicit directory dependency traded
|
|
for an explicit install dependency.
|
|
|
|
The shadowing risk from pip versions remains (a same-named package in `site-packages` still
|
|
competes with this copy), so **do not keep pip versions in the environment**:
|
|
|
|
```bash
|
|
pip uninstall -y mjlab rsl-rl-lib
|
|
```
|
|
|
|
Uninstalling them does not take their dependencies with them (mujoco-warp, warp-lang, torch,
|
|
tyro, viser and friends stay), and those dependencies are listed explicitly in
|
|
`pyproject.toml`, so `pip install -e .` in a fresh environment installs everything.
|
|
|
|
To check which copy is in use:
|
|
|
|
```bash
|
|
python -c "import mjlab, rsl_rl, os; print(os.path.dirname(mjlab.__file__)); print(os.path.dirname(rsl_rl.__file__))"
|
|
```
|
|
|
|
Both paths must point at `<repo>/rl/mjlab` and `<repo>/rl/rsl_rl`. If either points into
|
|
`site-packages`, a pip version is still installed or this repository was not installed as
|
|
editable.
|
|
|
|
## What was changed
|
|
|
|
All modifications to upstream are confined to **five files**, each carrying an `[mjrl]`
|
|
marker and the reason for the change. `rsl_rl` is untouched.
|
|
|
|
| File | Change |
|
|
|---|---|
|
|
| `mjlab/sim/__init__.py` | **New**: `set_simulation_cls` / `get_simulation_cls`, making `Simulation` replaceable. This is the seam itself |
|
|
| `mjlab/envs/manager_based_rl_env.py` | Constructing the sim goes from `Simulation(...)` to `get_simulation_cls()(...)`. With nothing registered it returns `Simulation`, byte-for-byte upstream behaviour |
|
|
| `mjlab/sensor/sensor_context.py` | Dispatch the sensor context by backend. `RenderContext` is a mjwarp thing and the native path has no `model.struct`, so buffers are allocated on the CPU in the same layout instead |
|
|
| `mjlab/sensor/raycast_sensor.py` | Same dispatch. This is the only mjwarp-bound part of the whole `RayCastSensor`; the native path goes through `mujoco.mj_ray` |
|
|
| `mjlab/rl/config.py` | **New field**: forwards rsl_rl's symmetry augmentation / mirror-loss parameter, which this wrapper dataclass did not expose. Delete it if upstream adds the same field |
|
|
|
|
To find every change:
|
|
|
|
```bash
|
|
grep -rn "\[mjrl\]" rl/mjlab/ rl/rsl_rl/
|
|
```
|
|
|
|
## Modification discipline
|
|
|
|
So that rebasing onto upstream stays possible:
|
|
|
|
1. **Keep changes concentrated.** Edits on the mjlab side belong near the seam
|
|
(`rl/mjlab/sim/` and the files in the table above), not scattered across manager / entity.
|
|
2. **Mark every edit** with `[mjrl]`, saying why it was made and against which upstream
|
|
version, e.g. `# [mjrl] reason: … (against mjlab 1.6.0)`.
|
|
3. **When upgrading upstream**: overwrite with the new official artifact, then use
|
|
`git diff` to recover your own changes and reapply them. Which makes rule 2 not decoration
|
|
but the only trail you have.
|
|
4. **The two `LICENSE` files are not in the artifact**, so an overwrite deletes them. Take
|
|
them again from the new release's tag, and check that [`NOTICE`](../NOTICE) still
|
|
describes what the new copy contains.
|
|
|
|
`tests/test_seam.py` checks that the set of files carrying the marker is exactly the one in the
|
|
table above — a marked change that spreads to a sixth file gets caught. An edit made without the
|
|
marker does not, which is why rule 2 is the one that matters.
|