robotenv 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. robotenv-0.2.1/.agent/future_ideas.md +10 -0
  2. robotenv-0.2.1/.agent/memory.md +138 -0
  3. robotenv-0.2.1/.agent/quotient_space.md +3 -0
  4. robotenv-0.2.1/.github/workflows/ci.yml +55 -0
  5. robotenv-0.2.1/.github/workflows/workflow.yml +41 -0
  6. robotenv-0.2.1/.gitignore +163 -0
  7. robotenv-0.2.1/.python-version +1 -0
  8. robotenv-0.2.1/AGENTS.md +9 -0
  9. robotenv-0.2.1/LICENSE +339 -0
  10. robotenv-0.2.1/PKG-INFO +136 -0
  11. robotenv-0.2.1/README.md +93 -0
  12. robotenv-0.2.1/benchmarks/bench_warp.py +250 -0
  13. robotenv-0.2.1/benchmarks/menagerie_options.py +63 -0
  14. robotenv-0.2.1/docs/README.md +76 -0
  15. robotenv-0.2.1/docs/cluster.md +67 -0
  16. robotenv-0.2.1/docs/configs/base-env.md +174 -0
  17. robotenv-0.2.1/docs/configs/control.md +107 -0
  18. robotenv-0.2.1/docs/configs/env.md +84 -0
  19. robotenv-0.2.1/docs/configs/robot.md +226 -0
  20. robotenv-0.2.1/docs/configs/sim.md +96 -0
  21. robotenv-0.2.1/docs/configs/task.md +126 -0
  22. robotenv-0.2.1/docs/design.md +87 -0
  23. robotenv-0.2.1/docs/development.md +97 -0
  24. robotenv-0.2.1/docs/getting-started.md +135 -0
  25. robotenv-0.2.1/docs/robots/menagerie.md +143 -0
  26. robotenv-0.2.1/docs/robots/writing-a-robot-provider.md +121 -0
  27. robotenv-0.2.1/docs/simulators.md +244 -0
  28. robotenv-0.2.1/docs/tasks/empty.md +29 -0
  29. robotenv-0.2.1/docs/tasks/robosuite.md +134 -0
  30. robotenv-0.2.1/docs/tasks/writing-a-provider.md +207 -0
  31. robotenv-0.2.1/docs/viz.md +112 -0
  32. robotenv-0.2.1/examples/embodiment_sweep.ipynb +224 -0
  33. robotenv-0.2.1/examples/menagerie_robots.ipynb +286 -0
  34. robotenv-0.2.1/examples/mount.ipynb +175 -0
  35. robotenv-0.2.1/examples/quickstart_cpu_mujoco.ipynb +208 -0
  36. robotenv-0.2.1/examples/quickstart_gpu_warp.ipynb +244 -0
  37. robotenv-0.2.1/examples/scene_viz.ipynb +493 -0
  38. robotenv-0.2.1/examples/scene_walkthrough.ipynb +575 -0
  39. robotenv-0.2.1/pizza_robot/.agent/memory.md +49 -0
  40. robotenv-0.2.1/pizza_robot/assets/elrobot/Gripper_Base_v1_1.stl +0 -0
  41. robotenv-0.2.1/pizza_robot/assets/elrobot/Gripper_Gear_v1_1.stl +0 -0
  42. robotenv-0.2.1/pizza_robot/assets/elrobot/Gripper_Jaw_01_v1_1.stl +0 -0
  43. robotenv-0.2.1/pizza_robot/assets/elrobot/Gripper_Jaw_02_v1_1.stl +0 -0
  44. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_01_1.stl +0 -0
  45. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_02_1.stl +0 -0
  46. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_03_v1_1.stl +0 -0
  47. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_04_v1_1.stl +0 -0
  48. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_05_v1_1.stl +0 -0
  49. robotenv-0.2.1/pizza_robot/assets/elrobot/Joint_06_v1_1.stl +0 -0
  50. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_1_v1_1.stl +0 -0
  51. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_2_v1_1.stl +0 -0
  52. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_3_v1_1.stl +0 -0
  53. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_4_v1_1.stl +0 -0
  54. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_5_v1_1.stl +0 -0
  55. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_6_v1_1.stl +0 -0
  56. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_7_v1_1.stl +0 -0
  57. robotenv-0.2.1/pizza_robot/assets/elrobot/ST3215_8_v1_1.stl +0 -0
  58. robotenv-0.2.1/pizza_robot/assets/elrobot/base_link.stl +0 -0
  59. robotenv-0.2.1/pizza_robot/elrobot_table.xml +615 -0
  60. robotenv-0.2.1/pizza_robot/run_elrobot_table.py +10 -0
  61. robotenv-0.2.1/pyproject.toml +40 -0
  62. robotenv-0.2.1/src/robotenv/__init__.py +21 -0
  63. robotenv-0.2.1/src/robotenv/_canon.py +136 -0
  64. robotenv-0.2.1/src/robotenv/config/__init__.py +93 -0
  65. robotenv-0.2.1/src/robotenv/config/base_env.py +557 -0
  66. robotenv-0.2.1/src/robotenv/config/control.py +161 -0
  67. robotenv-0.2.1/src/robotenv/config/defaults.py +29 -0
  68. robotenv-0.2.1/src/robotenv/config/env.py +107 -0
  69. robotenv-0.2.1/src/robotenv/config/kinematics.py +121 -0
  70. robotenv-0.2.1/src/robotenv/config/mount.py +172 -0
  71. robotenv-0.2.1/src/robotenv/config/providers.py +171 -0
  72. robotenv-0.2.1/src/robotenv/config/robot_providers.py +140 -0
  73. robotenv-0.2.1/src/robotenv/config/sim.py +152 -0
  74. robotenv-0.2.1/src/robotenv/config/specs.py +111 -0
  75. robotenv-0.2.1/src/robotenv/config/sweep.py +100 -0
  76. robotenv-0.2.1/src/robotenv/config/task.py +183 -0
  77. robotenv-0.2.1/src/robotenv/envs/__init__.py +34 -0
  78. robotenv-0.2.1/src/robotenv/envs/spaces.py +38 -0
  79. robotenv-0.2.1/src/robotenv/errors.py +35 -0
  80. robotenv-0.2.1/src/robotenv/robot/__init__.py +30 -0
  81. robotenv-0.2.1/src/robotenv/robot/arm.py +319 -0
  82. robotenv-0.2.1/src/robotenv/robot/external.py +234 -0
  83. robotenv-0.2.1/src/robotenv/robot/generators.py +138 -0
  84. robotenv-0.2.1/src/robotenv/robot/gripper.py +82 -0
  85. robotenv-0.2.1/src/robotenv/robot/pose.py +49 -0
  86. robotenv-0.2.1/src/robotenv/robot/providers/__init__.py +5 -0
  87. robotenv-0.2.1/src/robotenv/robot/providers/menagerie/__init__.py +127 -0
  88. robotenv-0.2.1/src/robotenv/robot/providers/menagerie/_describe.py +130 -0
  89. robotenv-0.2.1/src/robotenv/robot/providers/menagerie/cards.json +37 -0
  90. robotenv-0.2.1/src/robotenv/simulators/__init__.py +51 -0
  91. robotenv-0.2.1/src/robotenv/simulators/base.py +70 -0
  92. robotenv-0.2.1/src/robotenv/simulators/mujoco/__init__.py +38 -0
  93. robotenv-0.2.1/src/robotenv/simulators/mujoco/arm_spec.py +137 -0
  94. robotenv-0.2.1/src/robotenv/simulators/mujoco/compile.py +242 -0
  95. robotenv-0.2.1/src/robotenv/simulators/mujoco/env.py +257 -0
  96. robotenv-0.2.1/src/robotenv/simulators/mujoco/external.py +443 -0
  97. robotenv-0.2.1/src/robotenv/simulators/mujoco/mount.py +65 -0
  98. robotenv-0.2.1/src/robotenv/simulators/mujoco/render.py +158 -0
  99. robotenv-0.2.1/src/robotenv/simulators/mujoco/scenes.py +35 -0
  100. robotenv-0.2.1/src/robotenv/simulators/mujoco/sim.py +174 -0
  101. robotenv-0.2.1/src/robotenv/simulators/warp/__init__.py +100 -0
  102. robotenv-0.2.1/src/robotenv/simulators/warp/env.py +235 -0
  103. robotenv-0.2.1/src/robotenv/simulators/warp/sim.py +332 -0
  104. robotenv-0.2.1/src/robotenv/tasks/__init__.py +10 -0
  105. robotenv-0.2.1/src/robotenv/tasks/base.py +147 -0
  106. robotenv-0.2.1/src/robotenv/tasks/empty/__init__.py +42 -0
  107. robotenv-0.2.1/src/robotenv/tasks/empty/params.py +33 -0
  108. robotenv-0.2.1/src/robotenv/tasks/empty/task.py +27 -0
  109. robotenv-0.2.1/src/robotenv/tasks/robosuite/__init__.py +133 -0
  110. robotenv-0.2.1/src/robotenv/tasks/robosuite/_compat.py +165 -0
  111. robotenv-0.2.1/src/robotenv/tasks/robosuite/_introspect.py +65 -0
  112. robotenv-0.2.1/src/robotenv/tasks/robosuite/params.py +152 -0
  113. robotenv-0.2.1/src/robotenv/tasks/robosuite/scene.py +140 -0
  114. robotenv-0.2.1/src/robotenv/tasks/robosuite/task.py +145 -0
  115. robotenv-0.2.1/src/robotenv/viz/__init__.py +22 -0
  116. robotenv-0.2.1/src/robotenv/viz/_deps.py +16 -0
  117. robotenv-0.2.1/src/robotenv/viz/camera.py +98 -0
  118. robotenv-0.2.1/src/robotenv/viz/clip.py +180 -0
  119. robotenv-0.2.1/src/robotenv/viz/frames.py +93 -0
  120. robotenv-0.2.1/src/robotenv/viz/record.py +141 -0
  121. robotenv-0.2.1/tests/__init__.py +0 -0
  122. robotenv-0.2.1/tests/conftest.py +9 -0
  123. robotenv-0.2.1/tests/golden_hashes.json +30 -0
  124. robotenv-0.2.1/tests/menagerie_expected.json +43 -0
  125. robotenv-0.2.1/tests/nbrun.py +26 -0
  126. robotenv-0.2.1/tests/parity.py +71 -0
  127. robotenv-0.2.1/tests/test_base_env_config.py +493 -0
  128. robotenv-0.2.1/tests/test_bench_warp.py +60 -0
  129. robotenv-0.2.1/tests/test_chain_kinematics.py +79 -0
  130. robotenv-0.2.1/tests/test_control_modes.py +95 -0
  131. robotenv-0.2.1/tests/test_docs.py +60 -0
  132. robotenv-0.2.1/tests/test_empty_task.py +64 -0
  133. robotenv-0.2.1/tests/test_env_config.py +213 -0
  134. robotenv-0.2.1/tests/test_external_robot.py +377 -0
  135. robotenv-0.2.1/tests/test_golden_hashes.py +93 -0
  136. robotenv-0.2.1/tests/test_gripper.py +56 -0
  137. robotenv-0.2.1/tests/test_menagerie_docs.py +20 -0
  138. robotenv-0.2.1/tests/test_menagerie_provider.py +223 -0
  139. robotenv-0.2.1/tests/test_menagerie_reactuation.py +61 -0
  140. robotenv-0.2.1/tests/test_menagerie_smoke.py +13 -0
  141. robotenv-0.2.1/tests/test_menagerie_tasks.py +235 -0
  142. robotenv-0.2.1/tests/test_menagerie_warp.py +87 -0
  143. robotenv-0.2.1/tests/test_mount.py +167 -0
  144. robotenv-0.2.1/tests/test_mujoco_compile.py +132 -0
  145. robotenv-0.2.1/tests/test_mujoco_env.py +193 -0
  146. robotenv-0.2.1/tests/test_mujoco_external.py +480 -0
  147. robotenv-0.2.1/tests/test_mujoco_gripper.py +73 -0
  148. robotenv-0.2.1/tests/test_mujoco_mount.py +143 -0
  149. robotenv-0.2.1/tests/test_mujoco_sim.py +70 -0
  150. robotenv-0.2.1/tests/test_no_hardcoded_robots.py +52 -0
  151. robotenv-0.2.1/tests/test_no_hardcoded_tasks.py +70 -0
  152. robotenv-0.2.1/tests/test_notebooks.py +127 -0
  153. robotenv-0.2.1/tests/test_packaging.py +63 -0
  154. robotenv-0.2.1/tests/test_render.py +191 -0
  155. robotenv-0.2.1/tests/test_robosuite_compat.py +118 -0
  156. robotenv-0.2.1/tests/test_robosuite_params.py +80 -0
  157. robotenv-0.2.1/tests/test_robosuite_task.py +345 -0
  158. robotenv-0.2.1/tests/test_robot_config.py +113 -0
  159. robotenv-0.2.1/tests/test_simulators.py +173 -0
  160. robotenv-0.2.1/tests/test_simview.py +101 -0
  161. robotenv-0.2.1/tests/test_task_registry.py +161 -0
  162. robotenv-0.2.1/tests/test_viz.py +308 -0
  163. robotenv-0.2.1/tests/test_warp_config.py +77 -0
  164. robotenv-0.2.1/tests/test_warp_env.py +202 -0
  165. robotenv-0.2.1/tests/test_warp_external.py +163 -0
  166. robotenv-0.2.1/tests/test_warp_parity.py +112 -0
  167. robotenv-0.2.1/tests/test_warp_robosuite.py +110 -0
  168. robotenv-0.2.1/tests/test_warp_sim.py +177 -0
  169. robotenv-0.2.1/tests/toy_provider/__init__.py +55 -0
  170. robotenv-0.2.1/tests/toy_provider/framed.py +48 -0
  171. robotenv-0.2.1/tests/toy_provider/framed_engine.py +23 -0
  172. robotenv-0.2.1/tests/toy_provider/params.py +34 -0
  173. robotenv-0.2.1/tests/toy_provider/reach.py +114 -0
  174. robotenv-0.2.1/tests/toy_robot_provider/__init__.py +214 -0
  175. robotenv-0.2.1/uv.lock +2723 -0
@@ -0,0 +1,10 @@
1
+ Future Ideas, DONT CONSIDER THIS AS A ROADMAP, JUST IDEAS
2
+
3
+ 1. Connection to FreeCAD.
4
+ 2. Mjx-Jax and differentiability.
5
+ 3. Standardize interface with Mujoco-Warp using Newton.
6
+ 4. TorchRL's own render stack (`torchrl.render` / `rlrender` CLI) as an optional adapter, mainly to render trained policies from checkpoints (formats mp4, gif, ipynb, frames, npz; backends env / pixels / mujoco). It would now find `env.render()`, and `MujocoStateReader` could read the MuJoCo state. Its MP4 writer needs `torchcodec>=0.10` plus FFmpeg libraries, which are not in the robotenv venv. Only the source was read, nothing was run. Not adopted for now: the in-repo `robotenv.viz` covers recording and saving without a checkpoint or policy factory.
7
+ 5. Add molvospaces env as another backend for another library.
8
+ 6. in robot field, add ExternalRobot() to load library robot and DualRobot() can contain two robots.
9
+ 7. training_cfgs type .yaml file workflow for Config management.
10
+
@@ -0,0 +1,138 @@
1
+ # robotenv: agent memory
2
+
3
+ Start with `AGENTS.md` (what the package is), `docs/README.md` (reference index) and `docs/design.md` (principles, boundaries, vocabulary; the older dated decision log is in git history); `docs/tasks/writing-a-provider.md` shows how to add a task source. This file keeps what those do not: working rules, environment facts, pitfalls, open decisions.
4
+ Last updated: 2026-10-30. Work happens on `devel` (merged locally; the user pushes). The older history of this file is in git.
5
+
6
+ ## Goal
7
+ A framework to load different robot configs into an RL env, reused in other projects to study relationships between embodiments in
8
+ control (downstream project: "Quotient"). The user's own note is `.agent/quotient_space.md`: an n-DoF arm in an RL env with `n` as a
9
+ parameter, the robot config kept separate from the env. Do not overwrite the user's notes (`quotient_space.md`, `future_ideas.md`).
10
+
11
+ ## Working rules
12
+ - Commit and merge only when the user asks. Never push. Cut work on a branch in its own worktree (`<repo>-wt/<name>`) and leave the user's
13
+ checkout alone. Fast-forward `devel` only when it has not moved and the user's checkout has no uncommitted changes; if it has, ask what
14
+ to do with them (stash is reversible, discarding needs an explicit yes, and a yes covers that one case only).
15
+ - The repo is public: no cluster paths, user names, job ids, host names or tool / model names in tracked files, issues, notebook outputs
16
+ or commit messages (stored notebook output has the venv path replaced by `<site-packages>`).
17
+ - Do not delete repo files without asking. No trainer (RLlib or other) shapes the design.
18
+ - Do not hardcode a task or env in the core unless the user says so (the one exception is the `empty` placeholder, decided 2026-10-30): `tests/test_no_hardcoded_tasks.py` enforces it.
19
+ - Docs are tested (`tests/test_docs.py`): every ```python block in `docs/configs`, `docs/tasks` and `docs/README.md` is executed (numpy only,
20
+ no simulator; fence a block as ```python no-run to skip it) and every relative link and anchor must resolve. Change a config's fields,
21
+ rules or hashing and you change its page.
22
+ - The user works in the repo concurrently: check `git status` before editing shared files. Tell the user what a long step is doing before
23
+ it starts; they ask "is it done?" when a run is silent.
24
+ - After a rename or removal, grep for leftovers in code, docs, images (`docs/` diagrams), notebook outputs and this file.
25
+
26
+ ## Terminology (the user's, 2026-10-30)
27
+ - **simulator**: a physics engine realized as code, `robotenv.simulators.<name>`, named by `sim.simulator` (`mujoco`, `warp`).
28
+ Git history, closed issues and old text say "backend": read it as "simulator". `build-backend` in `pyproject.toml` is packaging vocabulary.
29
+ - **task provider**: owner of a task-id namespace (`robosuite`); **task**: `<namespace>/<name>`; **options**: the settings of one simulator,
30
+ in `sim.options`. **config side / engine side**: numpy-only classes vs the code that needs torch and MuJoCo ("engine" = those libraries).
31
+ - **embodiment**: a robot config (`ParametricArm`, or an `ExternalRobot`). **robot provider**: owner of a robot namespace (`config/robot_providers.py`, mirrors task providers);
32
+ **external robot**: a reference to a model of a robot provider (numbers only on the config side); `NativeGains` drives it with its own actuators. **scene**: `sim.scene` is a preset of the simulator (`empty`, `plain_floor`); a
33
+ robosuite scene is an arena plus objects brought by a task.
34
+
35
+ ## Why the project looks like this
36
+ - Same control task, varying embodiment: the task is a first-class object that does not mention `n` or link lengths. A fixed target is
37
+ unreachable for small `n` and trivial for large `n`, so targets are drawn per arm (`OwnReachable`) or from a box in the base frame.
38
+ - `n` confounds reach, mass and inertia: hold total length and mass fixed and split them over `n` (`chain(total_length=, total_mass=)`).
39
+ - Equal gains on every joint make control differences partly gain mismatch: gains are an explicit recorded choice, `InertiaScaledGains`.
40
+ - Every rollout must trace to an embodiment: configs are frozen, validated, hashable (`robot_hash`, `env_hash`); a task draws from its own
41
+ seeded stream, so the same seed gives every embodiment the same scene.
42
+ - Observation and action dimensions vary with `n`; a cross-embodiment view (padding, masks, per-embodiment heads) is not built.
43
+
44
+ ## Decisions (dated; reasons in the spec decision log)
45
+ - 2026-10-27 user: JAX shelved, GPU = MuJoCo Warp driven from torch; env contract = TorchRL `EnvBase`. Agent, under "do what is right": python
46
+ >= 3.10, extras `env`, `warp`, `robosuite`, `viz`, `dev`, nested observations.
47
+ - 2026-10-28 agent, accepted: robosuite's MuJoCo incompatibility is patched at run time (`apply_compat`), not by capping MuJoCo.
48
+ - 2026-10-29 user: `env = make_env(cfg)`; robosuite is a source of assets, never a simulator (success and reward are ours); no hardcoded tasks.
49
+ - 2026-10-30 user: the `native` provider and its reach task are purged (the tests keep a test-only provider, `tests/toy_provider`, namespace
50
+ `toy`); "backend" becomes "simulator" everywhere and the options move into `SimConfig`. Agent: the task gets its own random stream.
51
+ - 2026-10-30 user (roadmap #32, issue #33 done): the params object is the task (`TaskConfig(params, horizon, success_tolerance, target_region)`; params classes have `provider` and `name`; `task.id` is derived); every `env_hash` changed once. `provider_for` is removed (`get_task_provider(cfg.task.params.provider)`). Issue #34 done: `base_pose` left the robot, `TaskConfig.mount` (required `Pose`) and a name-only default-mount hint on the provider replace it (since #43 that is `TaskProvider.mount_frame(params)` and `TaskConfig.mount` is `Mount | MobileMount`, relative to the scene's frame); `kin.forward(arm, q, base=None)`; hashes changed again. Issue #35 done: `robotenv.tasks.empty` (`empty/idle`, `EmptyParams`), the one task the core may name; the no-hardcoded test exempts namespace `empty`. Issue #36 done: `BaseEnvConfig` (`config/base_env.py`), `Chain`/`NOT_SET` (`specs.py`), `DEFAULTS` (`defaults.py`, version 1); numbers chosen there (one z joint 0.5 m 1 kg, kp 60 kd 6, dt 0.002, 50 Hz, 1 env, scene `empty`, horizon 200), for the user's review; defaults change hashes, store `resolve().to_dict()`. Issue #37 done: `with_overrides`, `to_dict`/`from_dict`/`dump`/`load` (JSON; YAML via extra `yaml`, also in `dev`). Issue #38 done: `sweep`/`Family` (`config/sweep.py`), `examples/embodiment_sweep.ipynb`. Roadmap #32 is complete (#33 to #38), merged as PR #39. Issue #40: `horizon` -> `max_episode_steps` (loaders read `horizon` with a DeprecationWarning; hashes changed again). Issue #41: `env.action_space` / `env.observation_space` as shapes (`envs/spaces.py`) in order, one issue at a time, wait for the user between issues.
52
+ - GitHub issues: roadmap #10; M1 #11 to #14 and #16; M2 #15 and #17 to #20 (all closed, implemented).
53
+
54
+ ## Environment and workflow
55
+ - HPC: CPU jobs on partition `c23ms` (8 CPUs), GPU on `c23g`; not the `devel` partition. The user's venv is the one to use (do not build another):
56
+ Python 3.13, mujoco 3.17.0, robosuite 1.5.1, torch 2.14.1, torchrl 0.14.1, tensordict 0.14.3, numpy 2.5.4, pytest 9.1.1, imageio and ffmpeg, Pillow,
57
+ ipykernel and jupyter_client (no nbclient / nbformat). It is an editable install of the main checkout; to run a worktree: `unset PYTHONPATH`,
58
+ then `PYTHONPATH=<worktree>/src`.
59
+ - Tests: `pytest -m "not render"` (163 tests, about 1 min on c23ms); `-m render` (12 tests) needs EGL: `MUJOCO_GL=egl`, and on a multi-GPU login
60
+ node pin an idle device with `MUJOCO_EGL_DEVICE_ID` (osmesa and glfw did not work). Run heavy work as jobs, not on the login node.
61
+ - Slurm submission can fail with "Socket timed out" (nothing is queued): retry. SSH access once failed for hours: ask the user to restore it.
62
+ - A pytest run from the repo root writes `MUJOCO_LOG.TXT` (git-ignored now). Read repo files with `git show` or `cat`.
63
+ - Moving files to the cluster: one tar bundle of the changed files is far faster than file by file.
64
+ - Notebooks (`examples/*.ipynb`) are stored with outputs, executed in a fresh kernel with `jupyter_client` on a login node; rerun them when an
65
+ API they use changes. Examples are notebooks ONLY (user rule, 2026-11-02): no `.py` scripts in `examples/` (`tests/test_notebooks.py` checks it).
66
+ `tests/nbrun.py` executes a notebook's code cells in-process for the smoke tests (`-m robosuite`, `-m gpu` for the Warp one, `-m render` for
67
+ `scene_viz`). The runner that stores outputs needs no nbclient: `jupyter_client` start_new_kernel, execute each code cell, collect iopub
68
+ stream / display_data / execute_result / error messages. The Warp notebook sets `wp.config.log_level = wp.LOG_WARNING` (Warp >= 1.18; `wp.config.quiet` no longer exists there and assigning it is silently ignored) to keep the banner and compile lines out of the outputs. Quiet robosuite's per-scene INFO line with `logging.getLogger("robosuite_logs").setLevel(logging.WARNING)`.
69
+ - Only the tip of a branch is tested; intermediate commits are topic splits and may not pass alone.
70
+
71
+ ## robosuite facts and pitfalls (1.5.1 unless stated)
72
+ - 1.5.x as released fails on MuJoCo >= 3.10 (joint-address enum comparison; mass-matrix call). `apply_compat()` probes and patches only what fails;
73
+ tested on MuJoCo 3.3.1 to 3.17. Absolute dynamics differ across MuJoCo versions (a 60-step trajectory differs by up to 4e-3 rad between 3.9 and
74
+ 3.17): fix the version per study.
75
+ - The provider builds the environment once with a stock Panda, keeps `ManipulationTask(arena, [], objects).get_xml()`, strips `<option>`, `<size>`,
76
+ `<visual>` and the IK mocap bodies `*_eef_target`, and attaches it with `MjSpec.attach` under the prefix `rs_` (must be non-empty). `sim.scene`
77
+ must be `empty`: the arena brings its floor.
78
+ - Object sizes (the `Lift` cube) and the placement samplers draw from the GLOBAL numpy stream: seed and restore it. 1.5.2 uses sampler generators
79
+ (path written, unrun). 1.5.1 `Lift` has no `seed` argument. Do not hand robosuite the env's own generator; derive an integer seed.
80
+ - Objects without a free joint (the `Door` door, the `PickPlace` bins) are fixtures: baked once, since the envs of a batch share one model.
81
+ `obj_type == "visual"` objects are not observed. 12 of 15 single-arm environments build; `*Single` refused (observation keys change per
82
+ episode); `Wipe` has no object; two-arm refused. Introspecting a constructor must follow `**kwargs` forwarding.
83
+ - `Lift`: table top z = 0.8; stock Panda mount `(-0.56, 0, 0.912)`; cube half-size about 0.021, placed within +-3 cm of the table centre.
84
+ - Pitfalls: `MjSpec` reads angles as degrees unless `compiler.degree = False` (the compile sets it; a test guards it); `xpos` is stale until the
85
+ next forward; robosuite's own delta input settles at about 17 % of the commanded rate, so delta mode accumulates the target in our env.
86
+
87
+ ## MuJoCo Warp (built; verified only on Warp's CPU device)
88
+ mujoco-warp 3.17.0 and warp-lang 1.18.0. Built: `WarpOptions` (config/sim.py, capacities per world), `simulators/warp` (`WarpSimulator`, `WarpBatchedSim`
89
+ in sim.py, `WarpEnv` in env.py, `check_model_supported`, `CapacityError`), `SimView` in `tasks/base.py` (tasks are written against it; `BatchedSim`
90
+ implements it too), `task_seed` in `simulators/base.py`. Warp runs on its CPU device, so everything except CUDA specifics is testable here: tests build
91
+ `WarpEnv` directly with `device="cpu"` (`make_env` refuses it: capabilities say `cuda`); the `gpu` marker covers the same tests on `cuda:0`.
92
+ - Facts found: `naconmax = nconmax * nworld`; `overflow` is a per-world bitmask (`OverflowType`), counters are clipped, so `check_overflow` reads
93
+ `overflow`; after a step the derived state (`xpos`, `site_xpos`) is the pre-integration one, as on the CPU, so `mj_forward` on a host copy matches only
94
+ after a reset; `reset_data(m, d, reset=mask)` is a masked partial reset; the CPU-versus-Warp errors (float32) are in the docstring of
95
+ `tests/test_warp_parity.py` (all four control modes and integrators match); `NutAssembly*` need `WarpOptions(njmax=512, nconmax=128)`.
96
+ - Not verified (no GPU in the dev container): CUDA graph capture, stream sharing with torch, solver determinism, the parity tolerances on CUDA, the
97
+ Warp render test (needs OpenGL too), the throughput (`benchmarks/bench_warp.py` is written and was smoke-run on Warp's CPU device; its timings there mean nothing). `WarpOptions.default()` = 128 / 32 / graph off, from the device-independent per-world counts (Lift 32/8, Stack 52/13, NutAssemblySquare 374/63); turn the graph on after validating on a GPU.
98
+ - Pitfall: a second `mujoco.Renderer` probe after a failed one aborts the process (glfw); import `needs_gl` from `tests/test_render.py` instead.
99
+ - Open: per-world model fields (family batching, exploratory), a shared env base class for `MujocoEnv` and `WarpEnv`.
100
+
101
+ ## TorchRL conventions
102
+ Subclass `_reset`, `_step`, `_set_seed` and the specs; never override `reset` / `step`. `td["_reset"]` is bool `[B, 1]` (absent = reset all); the env
103
+ never autoresets; done, terminated, truncated and reward carry a trailing dim of 1; `check_env_specs` is the conformance check. torchrl 0.14.1 pins
104
+ tensordict < 0.15, tensordict 0.15.3 needs torch >= 2.11: widen the pins only after CI passes on the newer line.
105
+
106
+ ## Open decisions
107
+ 1. Family batching on the GPU: one simulation per topology group, lazy stacking, or padding.
108
+ 2. The smallest `n` that can physically solve `Lift`; infeasibility must be separable from failures of learning. The MuJoCo simulator builds no
109
+ gripper (`robot.tool` is ignored), so grasping tasks are out of reach.
110
+ 3. Reward shaping of the robosuite objectives is basic (negative distance); `Wipe` needs an objective of its own.
111
+ 4. An `ExternalRobot` baseline (the stock Panda) through the same contract: config side (#49) and the CPU MuJoCo compile (#50) exist; the menagerie provider (#51, `robot/providers/menagerie`, cards in `cards.json`, status in `tests/menagerie_expected.json`) exists; re-actuation (#52: `FixedGains` / `InertiaScaledGains` replace the model's actuators on the driven joints) exists; Warp runs external robots too (#53), verified on Warp's CPU device only: **CUDA is not verified for external robots** (the `gpu` tests skip here; mismatches are in #57). Existing tasks run on Menagerie robots unchanged (#54); the model's solver options are not carried over (the scene's win); the `render` test for external robots is written but cannot run without an OpenGL context.
112
+ 5. robosuite 1.5.2 placement path, robosuite throughput with many envs, and the `robosuite` CI job are unchecked.
113
+ 6. The user's idea list item "molvospaces": with the terms above that is a task provider (assets) or a simulator (physics): decide which.
114
+
115
+ ## Lessons
116
+ - A number or claim in the docs goes stale silently (the spec said 13 of 15 environments after the design changed to 12): recheck claims
117
+ against code and tests whenever a design changes.
118
+ - After the reach task was purged a diagram still listed it: images and notebook outputs need the same grep as code.
119
+ - A user's uncommitted change in their checkout is theirs: ask, and prefer a reversible step.
120
+ - External robots (the Menagerie work, #48 to #57), pitfalls found:
121
+ - `MjSpec.attach` into a frame of the *world* body keeps a free root joint legal (MuJoCo allows a free joint only on a direct child of the world); a welded body such as `base` would not. The compile therefore keeps an empty `base` for `SimView` and attaches into a separate frame at the same pose.
122
+ - Names are not reliable: free joints, many actuators and some keyframes are unnamed, so the compile maps the attached model's joints and actuators by position (they come last), not by name. `mj_id2name` returns `None`.
123
+ - Compare MuJoCo enums with `int(...)`: a numpy integer does not equal or hash like the pybind enum (a membership test and a dict lookup both failed silently).
124
+ - A model's joint actuators can include a finger or gripper (seven arms), and a gripper can be a tendon actuator: `controlled` in the card says which joints are driven, the others are held at the keyframe's `ctrl`. Some models have no force limits (`describe` needs `effort_limit`); some have unnamed or no `home` keyframe.
125
+ - Deleting an actuator from a spec breaks the keyframes' `ctrl` size: delete the keyframes first (re-actuation reads the keyframe from a standalone compile instead).
126
+ - `check_env_specs` draws from the task's random stream: build a fresh env after it before comparing placements.
127
+ - Parity with the Warp simulator needs a model that is not marginally stable (no armature or damping amplifies float32 rounding); contacts and stiff native servos are where it differs (#57).
128
+ - Rendering found two bugs the other tests did not (a camera framing that needs an end effector, a test task that read capsule radii): run the `render` tests with software GL (`apt-get install libosmesa6 libegl1 libgl1-mesa-dri`, then `MUJOCO_GL=egl`).
129
+ - The notebooks' stored outputs carried a user name and a cluster path: `tests/test_notebooks.py` now fails on an absolute path in a stored output.
130
+ - `docs/spec_robotconfig_env.md` and `docs/architecture.png`, which the roadmap issues name, are not in the repository; the decision log is the end of `docs/design.md`.
131
+
132
+
133
+ ## Mount (roadmap #42; #43 config done on branch issue-43-mount-config)
134
+ - The scene owns the mount frame (`TaskProvider.mount_frame(params)`, a world pose); `TaskConfig.mount` is `Mount(offset)` (fixed-base arm) or `MobileMount(spawn, heading)` (floating base; `spawn` (x, y[, z]), `z` added to the home height, `heading` a yaw in rad), in `config/mount.py`. `world_mount(cfg)` is the only composition: `T_frame @ T_mount`. the old name-only hint is gone (no alias); a `Pose` at `task.mount` raises with the replacement.
135
+ - A floating base is an `ExternalRobot` with `home_root`; `Mount` on it, or `MobileMount` on a fixed-base robot, raises at `task.mount` (in `EnvConfig`). A planar base made of slide joints (TidyBot) is not detected and takes a `Mount`.
136
+ - `Lift`: the frame is `(-0.56, 0, 0.912)`, identity orientation, as the stock Panda's root; the pedestal is not recreated.
137
+ - #44 (branch issue-44-mount-simulator, on top of #43): `TaskImpl.mount_site()`; `simulators/mujoco/mount.py` reads the marker (scene-only compile + `mj_forward`), checks it against `mount_frame` (1e-6), `base = marker @ mount`; both compile paths (ParametricArm and ExternalRobot) use it; `env.world_mount`. Test providers `framed` / `framed_bad` in `tests/toy_provider/framed*.py` (conftest registers them).
138
+ - #45 (branch issue-45-mount-robosuite, on top of #44): `SceneAssets.mount` is the stock Panda's root `Pose`; marker site `rs_mount`; `RobosuiteTasks.mount_frame(params)` memoised in `_FRAMES` by (name, canonical env_kwargs), seed-free. `Lift` frame `(-0.56, 0, 0.912)`, identity. The pedestal (RethinkMount) is not recreated: the base floats in renders.
@@ -0,0 +1,3 @@
1
+ In a RL env, for example a robosuite env. I want to have a n-dof arm in there, where n is a parameter that I can set. I want to be able to specify the number of degrees of freedom (n-dof) for the robotic arm in the environment. This will allow me to test different configurations and see how the arm performs with varying levels of complexity.
2
+
3
+ I think robotconfig should be maintained separate from the env. in robotconfig, i can define dof, length of links, joint types, axes, etc. Then in the env, I can instantiate the robot using the configuration from robotconfig.
@@ -0,0 +1,55 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, devel, feat/quotient]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ python-version: ["3.10", "3.12", "3.13"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Install uv
20
+ uses: astral-sh/setup-uv@v4
21
+
22
+ - name: Run tests
23
+ run: uv run --python ${{ matrix.python-version }} --extra env --extra viz --extra dev pytest -v -m "not gpu and not robosuite and not render and not menagerie"
24
+
25
+ robosuite:
26
+ # robosuite 1.5.x needs the compat layer on current MuJoCo; these tests notice when either side changes.
27
+ runs-on: ubuntu-latest
28
+ steps:
29
+ - uses: actions/checkout@v4
30
+
31
+ - name: Install uv
32
+ uses: astral-sh/setup-uv@v4
33
+
34
+ - name: Run robosuite tests
35
+ # The runner has no display and no GPU: the render and gpu tests (also marked robosuite) are not selected here, as in the test job.
36
+ run: uv run --python 3.12 --extra robosuite --extra dev pytest -v -m "robosuite and not gpu and not render"
37
+
38
+ menagerie:
39
+ # Robots from MuJoCo Menagerie: the model archives are downloaded on first use and cached between runs.
40
+ runs-on: ubuntu-latest
41
+ steps:
42
+ - uses: actions/checkout@v4
43
+
44
+ - name: Install uv
45
+ uses: astral-sh/setup-uv@v4
46
+
47
+ - name: Cache menagerie models
48
+ uses: actions/cache@v4
49
+ with:
50
+ path: ~/.cache/mujoco_menagerie # the library's default cache directory on Linux
51
+ # Keep in step with the pin in pyproject.toml (extra "menagerie").
52
+ key: menagerie-2026.9.0
53
+
54
+ - name: Run menagerie tests
55
+ run: uv run --python 3.12 --extra menagerie --extra dev pytest -v -m menagerie
@@ -0,0 +1,41 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build:
10
+ name: Build distribution
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - uses: actions/setup-python@v5
15
+ with:
16
+ python-version: "3.12"
17
+ - name: Build sdist and wheel
18
+ run: |
19
+ python -m pip install --upgrade build twine
20
+ python -m build
21
+ twine check dist/*
22
+ - uses: actions/upload-artifact@v4
23
+ with:
24
+ name: dist
25
+ path: dist/
26
+
27
+ publish:
28
+ name: Publish robotenv to PyPI
29
+ needs: build
30
+ runs-on: ubuntu-latest
31
+ environment:
32
+ name: pypi
33
+ url: https://pypi.org/project/robotenv/
34
+ permissions:
35
+ id-token: write # required for PyPI trusted publishing
36
+ steps:
37
+ - uses: actions/download-artifact@v4
38
+ with:
39
+ name: dist
40
+ path: dist/
41
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,163 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py,cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ #Pipfile.lock
96
+
97
+ # poetry
98
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
102
+ #poetry.lock
103
+
104
+ # pdm
105
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
106
+ #pdm.lock
107
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
108
+ # in version control.
109
+ # https://pdm.fming.dev/#use-with-ide
110
+ .pdm.toml
111
+
112
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
113
+ __pypackages__/
114
+
115
+ # Celery stuff
116
+ celerybeat-schedule
117
+ celerybeat.pid
118
+
119
+ # SageMath parsed files
120
+ *.sage.py
121
+
122
+ # Environments
123
+ .env
124
+ .venv
125
+ env/
126
+ venv/
127
+ ENV/
128
+ env.bak/
129
+ venv.bak/
130
+
131
+ # Spyder project settings
132
+ .spyderproject
133
+ .spyproject
134
+
135
+ # Rope project settings
136
+ .ropeproject
137
+
138
+ # mkdocs documentation
139
+ /site
140
+
141
+ # mypy
142
+ .mypy_cache/
143
+ .dmypy.json
144
+ dmypy.json
145
+
146
+ # Pyre type checker
147
+ .pyre/
148
+
149
+ # pytype static type analyzer
150
+ .pytype/
151
+
152
+ # Cython debug symbols
153
+ cython_debug/
154
+
155
+ # PyCharm
156
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
157
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
159
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
160
+ #.idea/
161
+ .vscode/settings.json
162
+ .claude/skills/mujoco_xml_skill/SKILL.md
163
+ MUJOCO_LOG.TXT
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,9 @@
1
+ This package provides robot embodiments as validated, hashable data and batched TorchRL environments:
2
+
3
+ 1. `robotenv.robot`: the robot embodiments, numpy only (`ParametricArm`, `TwoFingerGripper`, `Pose`, the `chain()` generator). `robotenv.config`: numpy-only configs (`ControlConfig`, `TaskConfig`, `SimConfig`, `EnvConfig`, ...; it re-exports the robot classes) and a kinematics oracle.
4
+ 2. `robotenv.simulators` / `robotenv.envs`: simulator registry and `make_env(cfg)`, the one way from an `EnvConfig` to an environment. The CPU MuJoCo simulator (`simulators/mujoco`) has one generic env (`MujocoEnv`) that runs any task; the GPU simulator (`simulators/warp`: `WarpBatchedSim`, `WarpEnv`) is its twin on MuJoCo Warp. Tasks are written against the engine-neutral `SimView` (`tasks/base.py`), so one task runs on both.
5
+ 3. `robotenv.tasks`: task providers, one subpackage per namespace (`<namespace>/<name>` ids), each with a numpy-only config side (params classes) and an engine side (a `TaskImpl`, contract in `tasks/base.py`). The core names no task: providers are discovered from the registry (`config/providers.py`), and `tests/test_no_hardcoded_tasks.py` enforces it. robosuite is a provider that supplies assets (arena, objects); it is never a simulator.
6
+ 4. `robotenv.robot.providers` (registry: `config/robot_providers.py`): robot providers, one subpackage per namespace, each turning a source of robot models (MuJoCo Menagerie: `menagerie`) into `ExternalRobot`s, a numpy-only reference to a model (`robot/external.py`) that the CPU and Warp simulators attach to the scene and drive with the model's own actuators (`NativeGains`) or with ours. Config side numpy only, engine side (`describe`, `spec`, `kinematics`) needs MuJoCo; the core names no robot provider (`tests/test_no_hardcoded_robots.py`) and no model file is copied into the repository.
7
+ 5. `robotenv.viz`: clips, frame recorder and camera framing for rendered rollouts (guide: `docs/viz.md`).
8
+
9
+ Documentation: `docs/README.md` indexes the pages: the config reference (`docs/configs/*.md`), `docs/simulators.md` (the environment contract), `docs/tasks/*.md` (providers; `writing-a-provider.md` shows how to add a task source), `docs/robots/*.md` (robots from a library; `writing-a-robot-provider.md` shows how to add a robot source), `docs/viz.md`, `docs/cluster.md`, `docs/design.md` (principles, boundaries and vocabulary) and `docs/development.md` (layout, tests, adding a simulator). The Python examples in the pages are executed by `tests/test_docs.py` (blocks fenced `python no-run` are not) and links are checked: when you change a config's fields, validation rules, defaults or hashing, update its page. Working notes: `.agent/memory.md`.