5.9 KiB
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 | 1.6.0 | We cut a seam between the manager layer and the physics engine — an invasive change |
rl/rsl_rl/ |
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/ at the repository root, and
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:
[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:
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:
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:
grep -rn "\[mjrl\]" rl/mjlab/ rl/rsl_rl/
Modification discipline
So that rebasing onto upstream stays possible:
- 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. - Mark every edit with
[mjrl], saying why it was made and against which upstream version, e.g.# [mjrl] reason: … (against mjlab 1.6.0). - When upgrading upstream: overwrite with the new official artifact, then use
git diffto recover your own changes and reapply them. Which makes rule 2 not decoration but the only trail you have. - The two
LICENSEfiles are not in the artifact, so an overwrite deletes them. Take them again from the new release's tag, and check thatNOTICEstill 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.