Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| ceca51b0d8 | |||
| d5e9004f6c |
@@ -5,22 +5,16 @@ description: Translate a built bundle's manual.en.json into Chinese as manual.zh
|
||||
|
||||
# The bundle's manual, in Chinese
|
||||
|
||||
`scripts/deploy.py` writes `manual.en.json` (`kk-bundle-manual/1`) into every
|
||||
bundle: each pad control and each key the bundle reads, what it does in each
|
||||
mode, how each mode is reached and left, and every mode switch. It is generated
|
||||
from the controller's own account of its controls (`padGuide`), so it cannot
|
||||
disagree with the bindings. The pad and the keyboard are two paths since
|
||||
2026-09-29 and the manual lists them apart: in each mode `controls` is the pad
|
||||
and `keys` the keyboard, and each switch says which `device` it is on. The
|
||||
Chinese version is a translation of it, and this skill is how it is made: the
|
||||
build cannot write natural Chinese, and a person or an agent can.
|
||||
Translate the generated English manual of the actual native or legacy bundle.
|
||||
Keep keyboard, pad and mode switches distinct; translate only the entries this
|
||||
build supplies.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Find the bundle directory. `deploy.py` prints it
|
||||
(`[deploy] bundled <commit> -> …/out/bundle_<ts>/<name>`) and then prints the
|
||||
`--translate` command with that path already filled in. It holds
|
||||
`manual.en.json` and `bundle.json`.
|
||||
1. Find the bundle directory. `deploy.py` writes `<bundle_parent>/<robot_id>`
|
||||
(alongside `<robot_id>.app`) and prints the `--translate` command with that
|
||||
path already filled in. The directory holds `manual.en.json` and
|
||||
`bundle.json`.
|
||||
2. Read `manual.en.json` in full.
|
||||
3. Write `manual.zh.json` somewhere outside the bundle (a scratch file):
|
||||
- the same JSON, field for field, in the same order;
|
||||
@@ -34,22 +28,21 @@ build cannot write natural Chinese, and a person or an agent can.
|
||||
entry in a mode's `keys` (`W`, `;`, `Space`, `↑`), and the `keys`
|
||||
lists of `switches` (`Space`, `Ctrl + 1`, `Num 1`). They are identifiers,
|
||||
and the check below refuses a translation that changes one.
|
||||
4. Add it to the bundle, which checks it and packs the `.app` again:
|
||||
4. Add it to the bundle, which checks it and packs the `.app` archive again:
|
||||
|
||||
```bash
|
||||
python scripts/deploy.py --translate out/bundle_<ts>/<name> --language zh --manual <scratch file>
|
||||
python scripts/deploy.py --translate <bundle-dir> --language zh --manual <scratch file>
|
||||
```
|
||||
|
||||
It refuses a file whose non-text fields differ from the English one, and
|
||||
holds the result to `deploy/app.schema`. Fix what it names and run it again.
|
||||
5. If the `.app` is going to be committed (bundles are committed under
|
||||
`out/bundle_<ts>/<name>.app`), commit it after this step, not before: the
|
||||
translation changes the archive.
|
||||
validates the result against the bundle's schema (`rl/mjrl/platform/app.schema`
|
||||
for native apps or `deploy/app.schema` for legacy bundles). Fix what it names
|
||||
and run it again.
|
||||
|
||||
## How to write it
|
||||
|
||||
For someone holding a gamepad or sitting at a keyboard, in plain Chinese. Keep
|
||||
mode names as identifiers where they name a mode (`进入 jump`), and say what the
|
||||
mode names as identifiers where they name a mode (`进入 locomotion`), and say what the
|
||||
mode is in the sentence when the English does. The manual lists each mode's
|
||||
keys on their own; say what a key does, never which pad control it is -- the
|
||||
English never says that either.
|
||||
@@ -79,22 +72,12 @@ English never says that either.
|
||||
| let go of everything: every control back to rest | 全部松开:所有操作回到静止 |
|
||||
| switch to X; press again to switch back | 进入 X;再按一次退出 |
|
||||
| (from X, Y only) | (仅在 X、Y 中有效) |
|
||||
| leave X, Y -- whichever is on -- back to locomotion | 退出 X、Y 中正在进行的那一个,回到 locomotion |
|
||||
| leave X, Y -- whichever is on -- back to default | 退出 X、Y 中正在进行的那一个,回到默认模式 |
|
||||
| click A once / double-click A / triple-click A | 单击 A / 双击 A / 三连击 A |
|
||||
| click A four times / click A five times | 四连击 A / 五连击 A |
|
||||
| switch to X; double-click again to switch back | 进入 X;再双击一次退出 |
|
||||
|
||||
A task's own words -- `closes the left claw as far as it is held`, from its
|
||||
`controls.yaml` -- are translated like any other text: `按多深,左爪就夹多紧`;
|
||||
`holds the carried arm straight out, thumb up, while held` is
|
||||
`按住时手臂向前伸直,拇指朝上`, and thumb-web up is `虎口朝上`. A claw mode lists
|
||||
only its own side's claw (the left claw's lists `LT` and Space, not `RT`), so
|
||||
A mode's custom control descriptions from its `controls.yaml` are translated
|
||||
like any other text (for example, `drives the elbow joint target` becomes
|
||||
`驱动肘关节目标位置`). Each mode lists only the controls bound in that mode, so
|
||||
translate what is there and add nothing.
|
||||
|
||||
## Why a separate step
|
||||
|
||||
The English is the build's and the Chinese is a translation of it, never the
|
||||
other way round: a manual written in Chinese first would have no generator to
|
||||
hold it to the bindings. `--translate` is what keeps the two the same manual in
|
||||
two languages -- it compares every identifier -- and it is also why a bundle
|
||||
built without an agent still ships the English one.
|
||||
|
||||
@@ -1,34 +1,35 @@
|
||||
---
|
||||
name: controls
|
||||
description: Configure operator keys, pad bindings, releases, or legacy FSM mode switches using the shared control vocabulary and schema.
|
||||
description: Configure and verify operator inputs, releases and mode bindings against a controller's supported physical commands.
|
||||
---
|
||||
|
||||
# Bind operator input
|
||||
# Bind physical commands to inputs
|
||||
|
||||
Read [Controls](../../../docs/CONTROLS.md). Use
|
||||
`python -m controller --vocabulary` as the source of device names.
|
||||
|
||||
For the locked locomotion templates, generate the ordered body-frame
|
||||
velocity binding in the robot's asset directory:
|
||||
|
||||
```bash
|
||||
python .claude/skills/controls/scripts/write_controls.py --task <robot_id>
|
||||
```
|
||||
|
||||
Use `--profile differential` for `wheeled_biped`. W/S drive forward and
|
||||
backward and A/D turn left and right. The keyboard leaves lateral motion
|
||||
unbound. The required Lx pad channel stays in the layout and has zero range.
|
||||
The default `omni` profile keeps A/D for lateral motion and J/L for turning.
|
||||
Use `--out` to specify another destination file. Keep all three velocity
|
||||
channels in order. Use `--bind AXIS=SOURCE+` or `--bind AXIS=SOURCE-` for
|
||||
named changes and `--release BUTTON` when specified. Point `robot_spec.py`
|
||||
at this file.
|
||||
For deterministic modes, generate the binding with `onboard.py setup-tier2`.
|
||||
|
||||
Validate the final YAML with `controller.controls.load_controls`. Exercise
|
||||
both ends of the active axes and release on the selected model. Repeat native
|
||||
verification after changing bindings that a portable app will package.
|
||||
|
||||
A legacy FSM mode switch belongs in the deployment manifest. Check it against
|
||||
the mode's operator bindings and validate the legacy bundle. Native app mode
|
||||
selection uses `--app-mode`.
|
||||
1. Identify the named command, frame, unit, order, sign, rest value and release
|
||||
behavior for each supported input. Choose the profile from actual kinematics;
|
||||
preserve disabled channels if required by the target schema. The
|
||||
[controls reference](../../../docs/CONTROLS.md) owns device vocabulary,
|
||||
keyboard layouts, generators and schema validation.
|
||||
For humanoid walking, bind W/S to forward/reverse body velocity and A/D to
|
||||
left/right yaw. Verify signed translation and rotation independently and
|
||||
check forward plus turn. For an arm with IK, exercise the viewer drag on
|
||||
the tool target, measure the achieved tool point, and check where it holds
|
||||
when the mouse is released.
|
||||
2. Set each input's extrema from measured deployment capability. A held key
|
||||
can reach the full configured value; a positive-direction test does not
|
||||
validate a symmetric range. Preserve training ranges separately if supplied.
|
||||
3. Validate the bindings and exercise held input, required signs, idle/release
|
||||
and promised combinations on the actual controller. Measure physical motion
|
||||
as well as input values. Compare the complete return-to-rest transition with
|
||||
its settled endpoint. An abrupt release can reach the effort limit even when
|
||||
the final position and steady effort pass. Sample applied effort on every physics
|
||||
step, including the first step after the target changes. Record peak, time at
|
||||
the bound and time to settle from both endpoints. If the jump causes
|
||||
clipping, test a named slider `target_rate_limits` entry on the affected
|
||||
axis with the same gains, effort limits and commands. Verify that one
|
||||
release tick followed by idle reaches rest as reliably as holding release.
|
||||
For legacy mode-switch conflicts follow the
|
||||
[bundler's diagnostic](../deploy/SKILL.md#input-conflicts).
|
||||
4. Hand the exact bindings, supported range and probe results to
|
||||
[deploy](../deploy/SKILL.md). If a binding changes, repeat the affected
|
||||
responses before releasing the changed archive.
|
||||
|
||||
@@ -8,6 +8,8 @@ import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
REPO = Path(__file__).resolve().parents[4]
|
||||
sys.path.insert(0, str(REPO))
|
||||
|
||||
@@ -35,17 +37,7 @@ DEFAULT_BINDING = {
|
||||
"ang_vel_z": ("Rx", -1),
|
||||
}
|
||||
|
||||
#: The keyboard: command axis -> (the keys towards its positive direction, the
|
||||
#: keys away from it). W S and the arrows walk forward and back, A D and the
|
||||
#: arrows step left and right (the arrows asked for on 2026-09-28), J L turn --
|
||||
#: the layout as the
|
||||
#: user decided it on 2026-09-29. Two keys on one direction are summed while
|
||||
#: both are held. Letting go of the keys is taking your hands off; there is no
|
||||
#: key for it (`centre`, retired 2026-09-27).
|
||||
#:
|
||||
#: Every letter is also one of MuJoCo's viewer shortcuts -- W flips the scene to
|
||||
#: wireframe -- and that was accepted for a keyboard laid out for the hands; the
|
||||
#: dictionary's `_keys_note` has the table.
|
||||
# Explicit omnidirectional layout, retained for existing operator profiles.
|
||||
KEYS_FOR = {
|
||||
"lin_vel_x": (("key_w", "key_up"), ("key_s", "key_down")),
|
||||
"lin_vel_y": (("key_a", "key_left"), ("key_d", "key_right")),
|
||||
@@ -61,8 +53,8 @@ DIFFERENTIAL_KEYS = {
|
||||
KeyDirections = tuple[tuple[str, ...], tuple[str, ...]]
|
||||
|
||||
#: The keys that let go of everything, as the pad's release button does: Esc.
|
||||
#: The keyboard's own, whatever button `--release` gives the pad. It was B until
|
||||
#: Control-agent 3.1 put the right claw there (2026-09-29).
|
||||
#: The keyboard's own release key, independent of whichever button `--release`
|
||||
#: binds on the gamepad.
|
||||
RELEASE_KEYS = ("key_escape",)
|
||||
|
||||
#: Seconds a key is held for its direction to reach full deflection; it is back
|
||||
@@ -91,15 +83,20 @@ def check(name: str, kind: str, allowed) -> None:
|
||||
absent = vocabulary.absent()
|
||||
extra = f"\n {absent[name]}" if name in absent else ""
|
||||
raise SystemExit(
|
||||
f"[controls] {name!r} is not {kind} the robot's pad service publishes.\n"
|
||||
f" It publishes: {' '.join(allowed)}{extra}\n"
|
||||
f"[controls] {name!r} is not {kind} in the shared gamepad vocabulary.\n"
|
||||
f" Allowed: {' '.join(allowed)}{extra}\n"
|
||||
f" python -m controller --vocabulary"
|
||||
)
|
||||
|
||||
|
||||
def keyboard_for(axes: list[str], profile: str) -> dict[str, KeyDirections | None]:
|
||||
"""Check each selected keystroke against the dictionary."""
|
||||
mapping = DIFFERENTIAL_KEYS if profile == "differential" else KEYS_FOR
|
||||
if profile == "walking":
|
||||
preset = REPO / "rl/mjrl/controllers/walking.yaml"
|
||||
bindings = yaml.safe_load(preset.read_text(encoding="utf-8"))["devices"]["keyboard"]["axes"]
|
||||
mapping = {axis: (tuple(keys["+"]), tuple(keys["-"])) for axis, keys in bindings.items()}
|
||||
else:
|
||||
mapping = DIFFERENTIAL_KEYS if profile == "differential" else KEYS_FOR
|
||||
out = {}
|
||||
for axis in axes:
|
||||
directions = mapping[axis]
|
||||
@@ -177,13 +174,11 @@ def render(task: str, axes: list[str], bind: dict[str, tuple[str, int]],
|
||||
out.append(" # The wheeled template scales this required pad channel to zero.")
|
||||
out.append(f" {axis}: {{ source: {source}, sign: {sign} }}")
|
||||
out += [
|
||||
" # MEASURED: the signs are not measured against the robot's pad service.",
|
||||
" # `controller/xbox.py` states the same evdev convention -- ABS_Y positive",
|
||||
" # is **down**, ABS_X positive is **right** -- and the service passes both",
|
||||
" # through unchanged, negating `dpad_y` and not `Ly`. Pushing the stick on",
|
||||
" # the robot is what would settle it.",
|
||||
" # `controller/xbox.py` uses the evdev convention -- ABS_Y positive is",
|
||||
" # **down**, ABS_X positive is **right**. Confirm stick signs on the intended",
|
||||
" # input device during verification.",
|
||||
" #",
|
||||
" # The service applies a 0.15 deadband and **rescales**, so full deflection",
|
||||
" # The input layer applies a 0.15 deadband and **rescales**, so full deflection",
|
||||
" # still reaches ±1. A consumer that applies its own on top narrows the",
|
||||
" # range a person can ask for and cannot tell that it has.",
|
||||
" deadzone: device_reported_rescaled",
|
||||
@@ -222,8 +217,8 @@ def main() -> int:
|
||||
ap = argparse.ArgumentParser(prog="write_controls.py", description=__doc__.splitlines()[0])
|
||||
ap.add_argument("--task", required=True, help="robot id, e.g. sample_biped")
|
||||
ap.add_argument(
|
||||
"--profile", choices=("omni", "differential"), default="omni",
|
||||
help="keyboard profile. Use differential for the wheeled-biped template",
|
||||
"--profile", choices=("walking", "omni", "differential"),
|
||||
help="keyboard profile (defaults to the registered family, or walking for a new task)",
|
||||
)
|
||||
ap.add_argument("--axes", default=",".join(AXIS_MEANING),
|
||||
help="command axes in order (default: all three)")
|
||||
@@ -239,6 +234,12 @@ def main() -> int:
|
||||
if re.fullmatch(r"[a-z][a-z0-9_]*", args.task) is None:
|
||||
ap.error("--task must be a lowercase robot id")
|
||||
|
||||
if args.profile is None:
|
||||
from tasks.robot_spec import read_robot_spec
|
||||
|
||||
registered = REPO / "tasks" / args.task / "robot_spec.py"
|
||||
family = read_robot_spec(registered).family if registered.is_file() else "biped"
|
||||
args.profile = {"biped": "walking", "wheeled_biped": "differential"}.get(family, "omni")
|
||||
axes = [a.strip() for a in args.axes.split(",") if a.strip()]
|
||||
if args.profile == "differential" and axes != list(AXIS_MEANING):
|
||||
ap.error("the differential profile requires all three command axes in template order")
|
||||
|
||||
@@ -1,66 +1,64 @@
|
||||
---
|
||||
name: deploy
|
||||
description: Export, verify and package a robot controller as a native MuJoCo .app or a supported legacy board/web bundle. Use for deployment contracts, ONNX/RKNN conversion, runtime parity, bundle creation, or an explicitly requested hardware deployment.
|
||||
description: Verify and package a native MuJoCo application or a supported legacy board/web bundle; diagnose runtime fidelity and final archive failures.
|
||||
---
|
||||
|
||||
# Verified application packaging
|
||||
# Package the verified capability
|
||||
|
||||
Read [deploy/README.md](../../../deploy/README.md) and
|
||||
[deploy/BUNDLE.md](../../../deploy/BUNDLE.md). A directory containing an ONNX file
|
||||
is an export, not an accepted application.
|
||||
Use the [acceptance procedure](../../../docs/ROBOT_ONBOARDING_LESSONS.md) for
|
||||
claim status and the [deploy guide](../../../deploy/README.md) and
|
||||
[bundle format](../../../deploy/BUNDLE.md) for build commands and contracts.
|
||||
|
||||
## Native application
|
||||
|
||||
1. Identify the robot ID, normalized MJCF and control mode. Use the onboarding
|
||||
skill for source assets. Do not infer a home pose or motor mapping from order.
|
||||
2. For a trained or adapted policy, inspect its `layout.json`, numerical parity
|
||||
report and source provenance. Preserve wire/observation/action named orders,
|
||||
term histories, transforms, rates and gain semantics.
|
||||
3. Write explicit native physical-response probes and run `onboard.py verify`.
|
||||
Require both physics and control acceptance for a controlled capability.
|
||||
Changing tolerances solely to turn a failure green is not acceptance.
|
||||
4. Run `deploy.py --robot <id> --model <normalized.xml> --control
|
||||
<controller.json> --controls <controls.yaml> --verification <report.json>
|
||||
--bundle <output-parent>`. Add `--policy <export>` for an ONNX mode.
|
||||
Geometry-only display omits controller/verification and claims `model_viewer`.
|
||||
5. Replay the emitted app and run `deploy.py --check-reference <app>`. Record
|
||||
actual measured results and supported runtime, including missing capabilities.
|
||||
6. Follow [bundle-manual](../bundle-manual/SKILL.md) to add the Chinese manual
|
||||
through `deploy.py --translate`; report the resulting archive path.
|
||||
1. Select the declared host and mode. A native app needs host Python and its
|
||||
declared dependencies. A geometry-only app claims `model_viewer`; a
|
||||
controlled app needs passing native physics and command probes for its exact
|
||||
model, controller and [bindings](../controls/SKILL.md). For a policy include
|
||||
the actor, layout, parity evidence and provenance. Carry any requested
|
||||
[motion-quality result](../train/SKILL.md) forward separately.
|
||||
2. If source replay works but export diverges, compare the first differing
|
||||
state: observations/history, action, target and effort, then next model
|
||||
state. Check runtime versions and serialized geometry/physics. Preserve
|
||||
suitable numeric assets; repeated serialization can change contact
|
||||
trajectories. Different mesh frames can represent the same transformed
|
||||
geometry: compare the quantities the claim actually requires.
|
||||
If compiled mass, inertia or center of mass changes, locate the first
|
||||
affected body and trace which geoms contribute under its inherited defaults.
|
||||
An omitted zero mass or density can make a collision mesh contribute inertia.
|
||||
Compare compiled values before and after relocation, including fixed links.
|
||||
3. Build using the verified inputs. Include imported licenses and distinguish
|
||||
synthetic fixtures in the robot ID and attribution. Add the
|
||||
[translated manual](../bundle-manual/SKILL.md) before final validation.
|
||||
4. Run the **final archive** outside the source checkout with the declared
|
||||
dependencies, check its reference trajectories (`deploy.py --check-reference`)
|
||||
and replay the claimed inputs for a finite duration. For a multi-stage task,
|
||||
include a reference at a discriminating intermediate state, such as the
|
||||
object's position during an unsupported hold. Replay the complete default
|
||||
mode and any operator mode used to demonstrate the task. Record the archive hash,
|
||||
host, measured response and limitations. If those bytes change, reassess
|
||||
affected checks and identify the artifact actually delivered.
|
||||
|
||||
The portable native runtime needs host Python and declared dependencies. It is
|
||||
not a browser or board executable. Do not mark an unsupported host as available.
|
||||
## Legacy board or web target
|
||||
|
||||
## Legacy Rust board/web application
|
||||
|
||||
1. Export the checkpoint through `scripts/export.py`. Refuse contracts the target
|
||||
reader does not implement; native hybrid position/velocity contracts are not
|
||||
legacy scalar-action contracts.
|
||||
2. Choose explicit export paths, cascade and switches in `deploy/manifests.json`
|
||||
or repeated `--mode` arguments. The generic repository defines no default robot.
|
||||
Use the [controls skill](../controls/SKILL.md) for binding changes.
|
||||
3. For a real board, run the read-only preflight script with the explicitly supplied
|
||||
`--host` and machine configuration. Check software ABI, DDS/QoS and named motor
|
||||
order before a build or transfer. No address is inferred.
|
||||
4. Build through `scripts/deploy.py`. Its default legacy path performs RKNN
|
||||
conversion, cross-builds, contract checks and reference generation. Follow
|
||||
`deploy/convert/README.md` and `deploy/fsm/README.md` for toolchains.
|
||||
5. `--allow-incomplete` is a development build with recorded omissions. Do not
|
||||
describe one as board-ready. Add its Chinese manual before handoff too.
|
||||
6. Hardware operation is separate from building. When explicitly authorized,
|
||||
run the board controller's `--dry-run` then `--check-reference` before the
|
||||
operational command with the machine's configuration. Stop on mismatch.
|
||||
Use only contracts the target reader implements; a native hybrid position and
|
||||
velocity layout cannot be assumed to work with a scalar-action reader. Supply
|
||||
the export paths, modes and switches explicitly. For a board, use the
|
||||
[read-only preflight](scripts/check_board.py) with the supplied host and machine
|
||||
configuration; check ABI, DDS/QoS and named motor order. A skipped preflight
|
||||
check is not a pass. Cross-build and check the references for the selected target.
|
||||
Include the translated manual; an `--allow-incomplete` build is developmental.
|
||||
Operating hardware requires separate authorization and a passing board dry run
|
||||
and reference check.
|
||||
|
||||
## Input conflicts
|
||||
|
||||
A mode's controls and the FSM's switches share a vocabulary and must not consume
|
||||
one input twice. The legacy reader reports:
|
||||
The legacy bundler checks the combination of mode inputs and FSM switches. On
|
||||
|
||||
```
|
||||
switches on the pad's ... controls use too: one press would do both.
|
||||
Pick another control, or say with `from` that the switch is not pressed in
|
||||
```
|
||||
|
||||
Change the binding or explicitly restrict the switch's source modes. Do not remove
|
||||
validation or widen a contract to hide the conflict. Unknown observation terms,
|
||||
joint names, unsupported versions and missing trajectory companions fail closed.
|
||||
change the binding or restrict the switch's source modes, then validate the
|
||||
bundle again. Do not widen the schema or suppress the collision.
|
||||
|
||||
@@ -5,29 +5,31 @@ description: Register a new legged robot for training by generating a data-only
|
||||
|
||||
# Register a robot
|
||||
|
||||
Read [Usage](../../../docs/USAGE.md#robot-specification) for the schema.
|
||||
Select `biped`, `quadruped`, `wheeled_biped`, or `multipod` using inspected
|
||||
model facts and control intent. Reuse the exact model that passed the
|
||||
stance checks. Keep robot assets and optional controls outside `tasks/`.
|
||||
Apply the [diagnosis and closeout loop](../../../docs/ROBOT_ONBOARDING_LESSONS.md).
|
||||
Read the [robot specification schema](../../../docs/USAGE.md#robot-specification).
|
||||
|
||||
```bash
|
||||
python scripts/onboard.py scaffold-tier3 --config robot.json --calibration calibration.json
|
||||
python scripts/train.py --list
|
||||
python scripts/train.py --task <robot_id> --dry-run
|
||||
python -m pytest tests/test_registry.py tests/test_template_lock.py -q
|
||||
```
|
||||
1. Select a supported family from inspected physical topology and intended
|
||||
control using the specification schema. Reuse the exact
|
||||
model and dependencies that passed stance checks. Automatic family guesses
|
||||
require review; a missing family is a template design issue, not a reason to
|
||||
mislabel the robot.
|
||||
2. Prepare only physical data: model/controls paths, named home values and base
|
||||
height, gains, effort limits, action scales, supports and any wheel joints.
|
||||
Keep assets and controls outside `tasks/`. Record source evidence or measured
|
||||
calibration for values; do not infer missing policy semantics from this data.
|
||||
3. Include [operator bindings](../controls/SKILL.md) for humanoid walking by
|
||||
default. Resolve a custom controls path relative to its configuration.
|
||||
4. Write one literal `tasks/<robot_id>/robot_spec.py`. Routine onboarding must
|
||||
not modify the registry, entry points, template files or lock. New behavior,
|
||||
rewards or a new family requires an explicit shared-template revision with
|
||||
its own justification and validation. Do not hide behavior in the spec.
|
||||
5. Verify discovery, resolved configuration and template integrity, then hand
|
||||
off to [train](../train/SKILL.md) for a backend smoke. Discovery establishes
|
||||
registration only.
|
||||
|
||||
The scaffold writes `tasks/<robot_id>/robot_spec.py`. It carries the model and
|
||||
controls paths, home joint values and base height, gains and effort limits,
|
||||
action scales, and contact names. With `--calibration`, the JSON supplies the
|
||||
robot ID, family, model path, action scales, and any optional contacts,
|
||||
controls, or wheel joint specifications not supplied by the report.
|
||||
## Execution aids
|
||||
|
||||
For operator input, apply the [controls skill](../controls/SKILL.md) before
|
||||
scaffolding and set `controls_path` in the scaffold JSON relative to that
|
||||
file. Use `--profile differential` when generating bindings for
|
||||
`wheeled_biped`.
|
||||
Onboarding must not modify the template files, the registry source, the
|
||||
entry points, or the lock. The only generated Python file is the literal
|
||||
robot specification. If the asset requires a new family or behavior, treat
|
||||
it as an explicit template revision.
|
||||
`onboard.py scaffold-tier3 --config <config> --calibration <report>` writes the
|
||||
specification. Review its output instead of relying on generation alone.
|
||||
`train.py --list` and `--task <id> --dry-run` check discovery and resolution;
|
||||
`tests/test_registry.py` and `tests/test_template_lock.py` check their contracts.
|
||||
|
||||
@@ -1,30 +1,42 @@
|
||||
---
|
||||
name: onboard-asset
|
||||
description: Inspect a new robot URDF, MJCF, mesh, or project directory, normalize it for MuJoCo, and select a viewer, existing policy, deterministic control, or legged training route.
|
||||
description: Inspect a robot model and its dependencies, establish supported capabilities, and route an intake to viewing, policy adaptation, deterministic control or training.
|
||||
---
|
||||
|
||||
# Onboard a robot asset
|
||||
# Inspect and route an asset
|
||||
|
||||
Read [Workflow](../../../docs/WORKFLOWS.md) and [Hardware](../../../docs/HARDWARE.md).
|
||||
Use the [common acceptance and closeout procedure](../../../docs/ROBOT_ONBOARDING_LESSONS.md).
|
||||
The intake output is a selected model, an inventory of evidence and a supported
|
||||
next step, including any blocker.
|
||||
|
||||
1. Run `python scripts/onboard.py inspect <source> --report <new-report.json>`.
|
||||
Pass `--profile`, `--mesh-root`, `--policy`, or `--metadata` when supplied.
|
||||
Review the selected model, missing dependencies, model checks, declared
|
||||
control intent, and recommended tier. Resolve ambiguous inputs explicitly.
|
||||
Keep candidate training configs associated with the actor that used them.
|
||||
A Tier 1 recommendation with `needs_metadata` goes to
|
||||
[tier1-adapt](../tier1-adapt/SKILL.md) for extraction and review.
|
||||
2. Preserve the source and record the exact model selected. For URDF, MJCF,
|
||||
or a standalone mesh, run `build-mjcf` with a new `--output` path. A
|
||||
directory works when it contains one model, or one mesh if there is no model. Add
|
||||
`--floating-base` only when the robot requires a free root. If generating
|
||||
visual fallback collisions, record the approximation and inspect the result.
|
||||
3. Check compilation and inspect joint names, units, axes, limits, inertias,
|
||||
collision geometry, and frames. For a viewer use `scripts/deploy.py --robot
|
||||
<id> --model <xml>` and run a finite headless replay.
|
||||
4. Route an existing policy to [tier1-adapt](../tier1-adapt/SKILL.md),
|
||||
deterministic control to [tier2-control](../tier2-control/SKILL.md), and
|
||||
explicit legged training to [tier3-train](../tier3-train/SKILL.md).
|
||||
1. Inventory the supplied assets, dependencies, licenses, actor, configurations
|
||||
and reference results. Identify which belong together. A keyframe, gain or
|
||||
physics timestep is model evidence; none establishes a policy's home, order,
|
||||
action scales or decision rate. Label a synthetic actor as a test fixture.
|
||||
2. Trace model includes to find the scene, articulated root, ground and contact
|
||||
definitions. When several unnamed collision shapes make up one sole, identify
|
||||
the supporting body and aggregate its floor contacts. Count physical feet
|
||||
and measure their loads after settling. Explicit contact pairs can remain active with zero collision
|
||||
masks. Review physical chains rather than counting mesh names or trusting
|
||||
an automatic family guess. In manipulation scenes, an independent payload
|
||||
adds another top-level body. Inspect the arm on its own to establish its
|
||||
capabilities, then verify the complete scene with the robot root and scene
|
||||
reset key selected explicitly. Check the free object's initial pose as well
|
||||
as the robot pose. Inspect units, frames, inertias, axes and limits
|
||||
using the [model requirements](../../../docs/HARDWARE.md).
|
||||
3. Preserve the source. Reuse suitable compiled MJCF; convert to a separate
|
||||
asset only if needed. Declare approximated collisions and add a floating
|
||||
root only if the intended mechanism requires one.
|
||||
4. Choose the [intake route](../../../docs/WORKFLOWS.md) justified by user
|
||||
intent and available evidence. A working viewer can be delivered as such.
|
||||
Default a humanoid intake to command-following walking. Reuse a matching
|
||||
walking policy via [adaptation](../tier1-adapt/SKILL.md) or prepare the
|
||||
floating-base biped for [training](../tier3-train/SKILL.md). Keep walking
|
||||
open until measured gait passes. Honor an explicit narrower request. For
|
||||
an arm, inspect the controllable chain and tool point for interactive
|
||||
[end-effector control](../tier2-control/SKILL.md).
|
||||
If the requested capability is blocked, record the missing prerequisite
|
||||
and close out that claim; a different capability is a separate result.
|
||||
|
||||
A viewer pass establishes that the model loads. Carry separate measured
|
||||
physics and command evidence into every controlled mode.
|
||||
See [Onboard](../../../docs/USAGE.md#onboard) for inspection and conversion
|
||||
tools. Model-only inspection does not require policy extraction.
|
||||
|
||||
@@ -1,160 +1,29 @@
|
||||
---
|
||||
name: setup-env
|
||||
description: Set up, verify or repair the mjrl-lab development environment on Linux, Windows or macOS, with or without an NVIDIA GPU -- the Python environment and the Rust toolchain the controller (deploy/fsm) builds with. Detects the machine, picks the right torch build, finds which of cargo, the wasm target, wasm-bindgen and CycloneDDS are missing, installs, and verifies Python and optional legacy targets. Use this whenever someone is getting this repository running on a new machine, onboarding, or hitting environment trouble: "ModuleNotFoundError: No module named 'mjlab'", torch not seeing the GPU, warp reporting only ['cpu'], a registered robot missing from `--list`, mujoco version conflicts, `cargo` not found, `idlc not found`, a wasm-bindgen version mismatch, the controller's tests skipping, or a suspicion that the wrong Python or the wrong checkout is being used. Reach for it before hand-rolling pip or cargo commands, because the failures here are quiet -- an environment that imports everything and trains happily can still be running another checkout's code or ignoring the GPU entirely, and a test suite on a machine without cargo is green because it skipped the controller.
|
||||
description: Establish or diagnose this checkout's Python environment, simulation backend or optional legacy controller build toolchain.
|
||||
---
|
||||
|
||||
# Setting up mjrl-lab
|
||||
# Verify the environment used by the task
|
||||
|
||||
The reference procedure is [`docs/AGENT_SETUP.md`](../../../docs/AGENT_SETUP.md) — about 600 lines,
|
||||
written to be read by an agent, with the full platform tables and a catalogue of known failures.
|
||||
**This skill does not restate it.** It sequences it, automates the two parts worth automating,
|
||||
and knows when to stop and read.
|
||||
Use [docs/AGENT_SETUP.md](../../../docs/AGENT_SETUP.md) for platform-specific
|
||||
installation, versions and failure remedies.
|
||||
|
||||
Two scripts carry the weight. Both are plain standard-library Python and run without this skill,
|
||||
so an agent that cannot load skills can still use them:
|
||||
1. Identify the interpreter, checkout, OS, device and intended target. Verify an
|
||||
existing isolated environment before replacing it. Install this repository
|
||||
editable in the intended interpreter; confirm that vendored libraries import
|
||||
from this checkout. A different checkout can import and run successfully.
|
||||
Keep incompatible simulator environments separate.
|
||||
2. Test the capability that will actually run: device enumeration for Warp,
|
||||
the batch rollout interface for native MuJoCo, or registry discovery for a
|
||||
missing task. A GPU banner, version string or successful import alone can
|
||||
pass when the intended capability is unusable.
|
||||
3. Only for the corresponding legacy target, verify the Rust target builds,
|
||||
the wasm tool matches the lockfile, or the device binary links and loads
|
||||
with the target ABI. Skipped controller tests do not establish readiness.
|
||||
4. Smoke-test the selected path with a registered task, or a viewer example
|
||||
for a model-only request. Report the measured result and untested targets.
|
||||
|
||||
| Script | Interpreter | Answers |
|
||||
|---|---|---|
|
||||
| `scripts/detect.py` | whatever the machine already has | what this machine is, and the exact commands that follow from it |
|
||||
| `scripts/gates.py` | the environment's own | whether the environment actually works, and what to fix |
|
||||
|
||||
## The shape of the problem
|
||||
|
||||
Almost everything here fails **quietly**. Installing a cu126 torch on a Blackwell card succeeds
|
||||
and dies later inside CUDA. An editable install pointing at a stale checkout imports cleanly and
|
||||
runs somebody else's code. A `pip` into the wrong interpreter reports success and changes
|
||||
nothing. A machine without cargo runs the test suite green, because the tests that build the
|
||||
controller skip. None of these announce themselves, and all of them surface much later as
|
||||
something that looks unrelated.
|
||||
|
||||
That is why this measures before deciding and verifies after acting, rather than running a
|
||||
sequence of commands and trusting that silence means success.
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. Measure, before deciding anything
|
||||
|
||||
```bash
|
||||
python3 .claude/skills/setup-env/scripts/detect.py
|
||||
```
|
||||
|
||||
Run it with the machine's existing interpreter — establishing whether that interpreter is usable
|
||||
at all is part of what it answers. It reports OS, architecture, Python version, GPU and compute
|
||||
capability, any environment that already exists, which parts of the controller's toolchain are
|
||||
already here, and it ends with the exact command sequence for this machine.
|
||||
|
||||
Read its output before continuing. In particular:
|
||||
|
||||
- **Python out of range** (needs 3.10–3.13): install a compliant interpreter *first*. Installing
|
||||
dependencies on an old one produces failures much later that read as unrelated.
|
||||
- **An environment already exists**: go to step 3 and verify it. The common case after the first
|
||||
run is not a bare machine but a broken environment, and building a second one hides the fault
|
||||
rather than fixing it.
|
||||
|
||||
### 2. Install
|
||||
|
||||
Follow the commands `detect.py` printed. They are section 1 of the reference doc with the
|
||||
branches already resolved for this machine; consult the doc when something does not match — the
|
||||
Debian `ensurepip` split, the Windows execution policy, and the MSVC prerequisite each have a
|
||||
paragraph there.
|
||||
|
||||
Only one step genuinely branches: **which torch wheel**. `detect.py` chose it from the measured
|
||||
compute capability, and its reasoning is on the `torch_plan` function if you need to check it.
|
||||
|
||||
Before any `pip`, confirm the interpreter is the intended one:
|
||||
|
||||
```bash
|
||||
python -c "import sys; print(sys.prefix)"
|
||||
```
|
||||
|
||||
It must be the environment you just made. Pip reports success regardless of where it installs, so
|
||||
this is the cheapest place to catch a mistake that otherwise surfaces three steps later.
|
||||
|
||||
`pip install -e .` is not optional and is not a convenience: the vendored `mjlab` and `rsl_rl`
|
||||
live under `rl/`, which is not on `sys.path`. That editable install *is* the mechanism that makes
|
||||
them importable.
|
||||
|
||||
**The legacy controller toolchain is required for its browser and board targets** — sections 2.1 and 2.2
|
||||
of the reference doc. It is additive rather than per-checkout, so `detect.py` prints only the
|
||||
steps this machine is missing, and "nothing missing" is a normal answer on a second checkout.
|
||||
Two of its parts are easy to get subtly wrong:
|
||||
|
||||
- **wasm-bindgen's version comes from `deploy/fsm/Cargo.lock`**, exactly — not from
|
||||
`Cargo.toml`'s `"0.2"`, a range every 0.2.x satisfies and `cargo install --version` refuses.
|
||||
Take the command `detect.py` printed; `scripts/deploy.py` refuses any other version.
|
||||
- **CycloneDDS is a source build** (11.0.1, the soname the board carries) and needs
|
||||
`sudo ldconfig` after installing into `/usr/local`. It is not needed for `deploy.py`, but once
|
||||
cargo exists `tests/test_deploy_sources.py` stops skipping and fails without it.
|
||||
- **Rockchip's NPU header is per checkout, not per machine.** `bash
|
||||
deploy/fsm/vendor/rknpu2/fetch.sh` puts it in the repository, git-ignored because its licence
|
||||
is Rockchip's. `detect.py` prints that step whenever it is missing, a second checkout included.
|
||||
|
||||
### 3. Verify
|
||||
|
||||
```bash
|
||||
.venv/bin/python .claude/skills/setup-env/scripts/gates.py --python-only
|
||||
```
|
||||
|
||||
Use `--python-only` for Python onboarding, training, and native apps. Omit it to verify the legacy controller toolchain as well. The exit code counts failures. Each prints what it measured and, on failure, the
|
||||
remedy and where the long form lives:
|
||||
|
||||
- **A — warp device enumeration.** On a GPU machine `cuda:0` must appear in the device list.
|
||||
`wp.init()` also prints a banner naming the card; that banner appears even when CUDA is
|
||||
unusable, so the list is the criterion and the banner is not.
|
||||
- **B — native MuJoCo's batch interface.** `native:cpu` is built on `mujoco.rollout`, so
|
||||
importing `mujoco` is not sufficient evidence.
|
||||
- **C — the vendored copies are this checkout's.** Stricter than the doc's version, which only
|
||||
rules out `site-packages`. An editable install left pointing at an older copy of the repository
|
||||
satisfies that and still executes another checkout's code — measured on a training machine on
|
||||
2026-09-04, where `tasks` came from the current repository and `mjlab` from a snapshot three
|
||||
days stale. Everything imported; the seam being edited simply was not the seam being run.
|
||||
- **D — the task registry.** Loads no simulation dependencies, so it passes even where the GPU is
|
||||
broken. A failure here is a packaging problem, not a simulation one — which is worth knowing
|
||||
before looking in the wrong place.
|
||||
- **E — the Rust toolchain builds the controller's host targets.** `cargo check` of the browser's
|
||||
wasm and of `play --app`'s extension, and the wasm-bindgen CLI against `Cargo.lock`. It builds
|
||||
rather than reading versions, because a missing target or linker passes `cargo --version`.
|
||||
- **F — the device build links and loads.** `cargo test --lib -- --list` with the default
|
||||
features: CycloneDDS, libclang, Rockchip's NPU header and a `libddsc` the loader finds. `--list` runs the binary
|
||||
without running a test, so a failing crate test is not reported as an environment fault.
|
||||
|
||||
E and F take about 30 s together, cold, on the i9-14900KF with the crates already downloaded; a
|
||||
first run also downloads them.
|
||||
|
||||
Do not proceed past a failure. Each remedy is printed; the long forms are section 6 of the
|
||||
reference doc.
|
||||
|
||||
### 4. Smoke test
|
||||
|
||||
With the relevant gates green, smoke-test the backend you intend to use.
|
||||
Choose a registered robot from `scripts/train.py --list`. If the registry is
|
||||
empty, use the model viewer example in the root README.
|
||||
|
||||
```bash
|
||||
python scripts/train.py --task <robot_id> --backend warp --device cuda --num_envs 4 --max-iterations 1 --headless
|
||||
python scripts/train.py --task <robot_id> --backend native --device cpu --num_envs 4 --max-iterations 1 --headless
|
||||
```
|
||||
|
||||
Check the backend in the run banner and confirm the PPO update completes.
|
||||
|
||||
## When something fails
|
||||
|
||||
Work from the measurement, not from the symptom. `detect.py` and `gates.py` both print what they
|
||||
observed, and the reference doc's section 6 is indexed by the exact error text — search it for the
|
||||
message rather than reasoning from the traceback, because several of these have causes that the
|
||||
traceback does not mention (the `njmax` overflow, the wandb `start_method` rejection, and
|
||||
`select_gpus` raising `IndexError` are all in that class).
|
||||
|
||||
Two rules survive every platform, and both are in section 7 of the doc:
|
||||
|
||||
- **Never `pip install mjlab` or `rsl-rl-lib`.** They exist as modifiable copies under `rl/`.
|
||||
A PyPI copy in the same environment shadows them ambiguously and is very hard to notice.
|
||||
- **Never install into an existing Isaac Lab environment.** mjlab needs `mujoco~=3.11`, Isaac Lab
|
||||
ships 3.10, and they break each other.
|
||||
|
||||
## Reporting back
|
||||
|
||||
Say which branch the machine took, which gates passed, and what the smoke test measured. If a
|
||||
gate was skipped or a step was worked around, say so plainly — an environment reported as ready
|
||||
when one gate was quietly skipped is worse than one reported as broken, because the next failure
|
||||
will be attributed to the code instead of the setup.
|
||||
[Host detection](scripts/detect.py) and [environment checks](scripts/gates.py)
|
||||
automate these measurements; run checks with the target interpreter. Use
|
||||
`--python-only` for Python/native work. On failure use the measured mismatch
|
||||
to select the remedy, then repeat the failed check.
|
||||
|
||||
@@ -122,7 +122,7 @@ def find_repo():
|
||||
"""The repository root, if we are standing in it.
|
||||
|
||||
Identified by pyproject naming this project rather than by the directory
|
||||
name, which is routinely different (kk-rl-mjlab, mjrl-lab, a worktree path).
|
||||
name, which is routinely different (mjrl-lab, a custom clone name, or a worktree path).
|
||||
"""
|
||||
here = os.path.abspath(os.getcwd())
|
||||
while True:
|
||||
@@ -437,7 +437,8 @@ def main():
|
||||
"" if steps else ": nothing missing"))
|
||||
for step in steps:
|
||||
print(" %s" % step)
|
||||
print("\n Then verify: python <skill>/scripts/gates.py")
|
||||
print("\n Then verify: python <skill>/scripts/gates.py --python-only")
|
||||
print(" (omit --python-only to also check legacy Rust targets)")
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@@ -94,9 +94,9 @@ def locked_version(repo: Path, package: str) -> str | None:
|
||||
def find_repo(start: Path | None = None) -> Path | None:
|
||||
"""The repository root, identified by pyproject rather than directory name.
|
||||
|
||||
The directory is routinely named something else -- kk-rl-mjlab, a git
|
||||
worktree path -- so matching on the name would fail on the machines this is
|
||||
most needed on.
|
||||
The directory is routinely named something else -- mjrl-lab, a custom clone
|
||||
name, or a git worktree path -- so matching on the name would fail on the
|
||||
machines this is most needed on.
|
||||
"""
|
||||
here = (start or Path.cwd()).resolve()
|
||||
for candidate in [here, *here.parents]:
|
||||
|
||||
@@ -5,43 +5,45 @@ description: Recover explicit policy semantics from upstream training configs or
|
||||
|
||||
# Adapt an existing policy
|
||||
|
||||
1. Use [onboard-asset](../onboard-asset/SKILL.md) to identify the matching
|
||||
model, actor and training configs. Treat a Tier 1 recommendation with
|
||||
`needs_metadata` as a request to recover policy semantics.
|
||||
2. If the source supplies a complete `mjrl-policy-adapter/1` document, use it
|
||||
directly. Otherwise extract evidence from the matched config files.
|
||||
Apply the [diagnosis and closeout loop](../../../docs/ROBOT_ONBOARDING_LESSONS.md).
|
||||
An adapter graph match, source-policy quality and deployed motion are separate
|
||||
claims with separate evidence.
|
||||
|
||||
```bash
|
||||
python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model robot.xml \
|
||||
--output metadata-draft
|
||||
```
|
||||
1. Identify the matching actor, model and source runtime/configuration. Without
|
||||
the actor, original-policy adaptation is blocked; continue supported asset
|
||||
work through [onboarding](../onboard-asset/SKILL.md). Config filenames are not
|
||||
a contract: recover semantics from matching declarative data, source code or
|
||||
the live source managers. Static extraction cannot resolve arbitrary imports,
|
||||
inheritance or expressions. Record unresolved fields instead of guessing.
|
||||
2. Establish the complete named contract: observation terms, units, frames,
|
||||
ordering, normalization, clipping and history; actor inputs/outputs; raw
|
||||
action order, physical target scales, home, limits, gains and control rate.
|
||||
Joint inventories, default-angle dictionaries, compiled order and tensor
|
||||
widths each establish different facts. Verify actual interpreter, module
|
||||
paths, dependency versions and physics settings when replaying a reference.
|
||||
3. Review extracted provenance, conflicts and missing fields against that
|
||||
evidence. Keep model facts distinct from learned-policy semantics. A complete
|
||||
`mjrl-policy-adapter/1` document can be used directly; extraction drafts need
|
||||
reviewed overrides and a ready manifest before automatic adaptation.
|
||||
4. Choose only a transformation the target runtime supports. For zero-scale
|
||||
held channels with raw previous-action observations, baking scales into actor
|
||||
outputs loses history. Preserve the full raw output/history and explicit
|
||||
per-channel scales when supported; never divide by zero or invent history.
|
||||
A zero residual scale can still command a powered position hold.
|
||||
5. Verify observation construction and history over multiple steps and resets,
|
||||
then actor/normalizer outputs, physical target and servo response, and native
|
||||
trajectories. Match the source order of target transforms and effort limits;
|
||||
use out-of-range actions to distinguish clipping orders. Prove any version compatibility rewrite by semantic
|
||||
and response comparisons. Refuse unsupported contracts or unresolved fields.
|
||||
6. Measure requested command responses on the adapted model. Hand the exact
|
||||
actor, layout, provenance, parity results and measured limitations to
|
||||
[deploy](../deploy/SKILL.md) if packaging is requested.
|
||||
|
||||
Review `metadata.json` and the provenance, conflicts, `missing_fields` and
|
||||
`unresolved` entries in `manifest.json`. An incomplete extraction writes
|
||||
the draft and exits 1. Python inputs are read as static syntax only.
|
||||
Resolve unknown imports, inheritance or expressions from source evidence
|
||||
and record the confirmed values in a JSON or YAML overrides file. The
|
||||
actor's observation and action definitions establish channel order.
|
||||
A joint-name inventory, a dictionary of default angles, MuJoCo joint order
|
||||
and graph widths each establish different facts.
|
||||
3. Rerun extraction with `--overrides reviewed.json --output metadata-ready`.
|
||||
Require `ready: true` in the manifest. Review ordered observation terms,
|
||||
history, joint and action order, home pose, scaling, gains, limits and rate.
|
||||
Run the adapter with the exact model.
|
||||
## Execution aids
|
||||
|
||||
```bash
|
||||
python scripts/onboard.py adapt-tier1 actor.onnx --metadata metadata-ready/metadata.json \
|
||||
--model robot.xml --output policy --report adapter-report.json
|
||||
```
|
||||
|
||||
After review, `--config env.yaml --config agent.yaml --overrides reviewed.json`
|
||||
can replace `--metadata` and run the same extraction during adaptation.
|
||||
4. Review the adapter parity result and layout against the supplied semantics.
|
||||
Build a verification config for the ONNX controller with `kind: rl_onnx`,
|
||||
its relative `policy` and `layout` paths, and the robot root when needed.
|
||||
Run native command probes with meaningful expected motion and tolerances.
|
||||
5. Package a compatible controlled mode only with passing verification for
|
||||
those files. Use [deploy](../deploy/SKILL.md) and replay the resulting app.
|
||||
|
||||
A graph comparison verifies the transformation. Native command response
|
||||
establishes how the adapted controller moves that model.
|
||||
Use `onboard.py extract-tier1` for supported config formats, reviewed overrides
|
||||
for source-confirmed values, and `adapt-tier1` for implemented transformations.
|
||||
An incomplete extraction writes a draft and exits 1. See [extraction](../../../docs/CONTROLLER_SETUP.md#extract-metadata-from-upstream-configs)
|
||||
and [Usage](../../../docs/USAGE.md) for syntax. A source contract outside the
|
||||
helper's scope needs an explicitly supported runtime route, not a fabricated
|
||||
ready manifest.
|
||||
|
||||
@@ -5,27 +5,61 @@ description: Set up a deterministic native MuJoCo controller for a complete robo
|
||||
|
||||
# Set up deterministic control
|
||||
|
||||
1. Inspect the model with [onboard-asset](../onboard-asset/SKILL.md).
|
||||
Choose a controller from the actual kinematics and intended motion.
|
||||
Confirm joint axes and limits, actuator semantics, effort, and rates.
|
||||
2. Declare a JSON controller config with its `kind`. Use
|
||||
`joint_sliders` for named position joints, `ik` for a
|
||||
named chain and end-effector site or body, `differential` or `omni` for
|
||||
measured wheel geometry, and `trajectory` or `cpg` for explicit motions.
|
||||
The `direct` API can inspect authored actuator inputs, but a packaged
|
||||
`model_viewer` must have `actuators: []` and carries no control claim. Choose
|
||||
one of the verified control kinds above for a controlled application.
|
||||
3. Run setup to a fresh path.
|
||||
Apply the [diagnosis and closeout loop](../../../docs/ROBOT_ONBOARDING_LESSONS.md)
|
||||
after [asset inspection](../onboard-asset/SKILL.md).
|
||||
|
||||
```bash
|
||||
python scripts/onboard.py setup-tier2 --model robot.xml --config setup.json --output control
|
||||
```
|
||||
1. Define the intended motion, conditions and expected physical response. Choose
|
||||
control from inspected kinematics: named position joints, an IK chain and
|
||||
end-effector, measured wheel geometry, or an explicit trajectory/CPG. For
|
||||
an interactive arm, offer a draggable Cartesian target at a verified tool
|
||||
point. Establish its reachable workspace, keep the gripper independent and
|
||||
exercise mouse selection, translation and release in the packaged viewer.
|
||||
Verify that a click from the startup view selects the target when a payload
|
||||
or the tool overlaps it. A scripted Cartesian command bypasses picking. A model
|
||||
viewer carries no control claim and must have `actuators: []`; the direct API
|
||||
can inspect authored inputs but does not make a packaged viewer controlled.
|
||||
2. Establish named joint/actuator mapping, axis signs, units, target semantics,
|
||||
limits, effort and rate. Distinguish authored parameters from newly chosen
|
||||
controller values. Passive joint damping and servo `kd` are separate; avoid
|
||||
adding the same damping twice. When normalizing a position servo, compare
|
||||
its compiled target-limited flag, target range and effort range before and
|
||||
after. A continuous hinge can have a bounded servo input. Convert that
|
||||
interval through the transmission and intersect applicable joint travel.
|
||||
Set the joint near each target edge and command just beyond it. Compare
|
||||
applied effort below the force cap, where a lost clamp is observable.
|
||||
Record the initial state and the selected keyframe if one is available.
|
||||
3. Preserve the intended mounting, gravity and contacts. Probe the initial
|
||||
state, joint margins, drift and effort headroom before increasing amplitude;
|
||||
check a grounded stance only if the task depends on it.
|
||||
A plausible keyframe or stable hold does not establish dynamic capability.
|
||||
If an authored rest pose fails a limit-margin check, measure the margin in
|
||||
joint units and as a fraction of travel. When the task allows an interior
|
||||
rest, test it on the source model, then use it for both reset and operator
|
||||
release. For tasks that require an end stop, test that contact explicitly.
|
||||
Diagnose insufficient authority, clipping, sign errors or contact problems
|
||||
before changing gains; do not invent physical parameters to pass a probe.
|
||||
4. Write the supported controller configuration and
|
||||
[operator bindings](../controls/SKILL.md). Declare the command envelope as a
|
||||
controller choice, with evidence for its usable range. Keep generated assets
|
||||
separate from source files.
|
||||
5. Compare commanded and measured motion in task coordinates. If the direction
|
||||
is wrong, bypass the binding with a named target to distinguish input mapping
|
||||
from transmission or frame errors. For an operation on an object, measure the
|
||||
object outcome as well as actuator travel. For a load test, record the compiled
|
||||
payload mass, free degrees of freedom and initial support. During a hold,
|
||||
measure object clearance, contact forces on the intended gripper surfaces,
|
||||
absence of external support and object drift in the gripper frame across the
|
||||
full interval. After opening, check that support transfers back and the
|
||||
gripper can withdraw. Repeat the same arm motion with the grasp disabled to
|
||||
distinguish carrying from incidental support. Review physics and
|
||||
control results separately and repeat affected probes after edits.
|
||||
6. If packaging is requested, hand the tested model, controller, bindings
|
||||
and native probe results to [deploy](../deploy/SKILL.md).
|
||||
|
||||
Use the resulting `robot.xml` and `controller.json`. Inspect the optional
|
||||
`controls.yaml` with the [controls skill](../controls/SKILL.md).
|
||||
4. Run `onboard.py verify` with a probe JSON that references the generated
|
||||
controller and controls and declares expected measured responses. Use
|
||||
[Tutorial](../../../docs/TUTORIAL.md) for a runnable joint-slider example.
|
||||
Read both the physics and control stages and repeat after any relevant edit.
|
||||
5. Package with the exact evidence and replay the app with finite steps.
|
||||
Report observed responses, limits, and any failing probe.
|
||||
## Execution aids
|
||||
|
||||
Use `onboard.py setup-tier2` to generate a supported controller and `verify` to
|
||||
measure it. Inspect model parameters directly or through `model_evidence` when
|
||||
useful; policy extraction is not required. Schemas and a runnable joint-slider
|
||||
example are in [Usage](../../../docs/USAGE.md) and
|
||||
[Tutorial](../../../docs/TUTORIAL.md).
|
||||
|
||||
@@ -3,26 +3,35 @@ name: tier3-train
|
||||
description: Calibrate a floating-base biped, quadruped, wheeled biped, or multipod for locked-template locomotion training, then scaffold and run measured replay.
|
||||
---
|
||||
|
||||
# Calibrate and train a legged robot
|
||||
# Calibrate and prepare locomotion training
|
||||
|
||||
1. Run [onboard-asset](../onboard-asset/SKILL.md). Establish the family, named
|
||||
supports, single floating root, explicit locomotion intent, and joint
|
||||
control semantics. Wheeled bipeds require named unlimited wheel hinges.
|
||||
2. Prepare stance JSON with the seed pose, named supports, optional height
|
||||
adjustments, and measured effort limits. Run
|
||||
`python scripts/onboard.py calibrate --model robot.xml --config stance.json
|
||||
--report calibration.json`. Inspect the measured contact loads, drift,
|
||||
limits, effort headroom, and complete report before using it.
|
||||
3. Follow [new-task](../new-task/SKILL.md) to generate the literal robot spec.
|
||||
Supply explicit action scales and reuse the passing report for the same
|
||||
XML and compiled dependencies. If operator input is requested, generate
|
||||
bindings before scaffolding and set `controls_path` in the scaffold JSON.
|
||||
Use `--profile differential` for a wheeled biped so A/D command yaw.
|
||||
Keep robot-specific changes in data.
|
||||
4. Follow [train](../train/SKILL.md). Verify discovery and a backend smoke
|
||||
before allocating a learning run. Measure the selected checkpoint on
|
||||
trained ranges with the required command and observation-noise setting.
|
||||
5. If packaging is requested, export with `--native-layout` and verify the
|
||||
exported model, controller and bindings. The native layout supports the
|
||||
wheeled-biped template's hybrid position and velocity targets. Follow
|
||||
[deploy](../deploy/SKILL.md) for the selected runtime.
|
||||
Apply the [diagnosis and closeout loop](../../../docs/ROBOT_ONBOARDING_LESSONS.md).
|
||||
Walking is the default training objective for humanoid intake. Include forward
|
||||
and reverse speeds, turns in both directions, and a stop in the command
|
||||
envelope. Select usable magnitudes from measured gait and tracking results.
|
||||
|
||||
1. Establish the inspected family, named supports, single floating root and joint
|
||||
control semantics through [onboarding](../onboard-asset/SKILL.md). Wheeled
|
||||
bipeds require named unlimited wheel hinges. Confirm that a supported locked
|
||||
template represents the intended motion before creating a task.
|
||||
2. Prepare a separate training asset only as needed. The template owns terrain
|
||||
and calibrated reset state: remove source ground, source reset keyframes and
|
||||
any `size.nkey` allocation hint together. Review terrain collision masks and
|
||||
replacement floor pairs while retaining intended self-contact pairs. Check
|
||||
that new ground does not inherit disabled robot collision defaults.
|
||||
3. Calibrate a grounded stance using measured contact loads, drift, joint limits
|
||||
and effort headroom. Separate passive damping from servo damping and preserve
|
||||
source-backed physical limits. Test the chosen pose rather than treating an
|
||||
authored keyframe or a successful static hold as a dynamic gait solution.
|
||||
4. Establish physical action authority by named channel: raw actor value to
|
||||
target, target clipping, applied effort and achievable excursion. Choose
|
||||
scales with physical units and record their origin. Zero position residual
|
||||
scale retains powered home hold; velocity scales must be positive and some
|
||||
locomotion authority must remain active. Do not copy another robot's gains,
|
||||
posture or action scales merely because its training worked.
|
||||
5. Pass the matching calibration evidence, exact model and scales to
|
||||
[task registration](../new-task/SKILL.md), then the registered task to
|
||||
[training and measured replay](../train/SKILL.md).
|
||||
|
||||
Use `onboard.py calibrate` to record stance evidence. See
|
||||
[Usage](../../../docs/USAGE.md#onboard) for the calibration inputs.
|
||||
|
||||
@@ -1,38 +1,47 @@
|
||||
---
|
||||
name: train
|
||||
description: Train or resume a locomotion policy through a locked template, validate backend and run size, replay the checkpoint, and report measured results.
|
||||
description: Train or resume a locomotion task, diagnose stationary or poor-quality motion, and select a checkpoint using measured replay.
|
||||
---
|
||||
|
||||
# Train and measure
|
||||
# Train and evaluate locomotion
|
||||
|
||||
1. Confirm the robot appears in `scripts/train.py --list`. Use
|
||||
[new-task](../new-task/SKILL.md) when the robot still needs registration.
|
||||
Run `.claude/skills/setup-env/scripts/detect.py` and verify the environment
|
||||
with the [setup skill](../setup-env/SKILL.md) when needed.
|
||||
2. Resolve with `--dry-run`. Use `native:cpu` for the CPU path or `warp:cuda`
|
||||
for a supported CUDA installation. A small environment count and one
|
||||
iteration exercise the path. Choose the learning run size from the
|
||||
backend's available memory and measured throughput. If Warp reports an
|
||||
overflow, raise `--warp-max-constraints N` for per-world constraints or
|
||||
`--warp-max-contacts N` for the shared contact pool and rerun the smoke.
|
||||
Use positive integers. Training saves the selected and effective capacities
|
||||
in `warp-allocation.json` beside the checkpoints. Warp resume, replay, and
|
||||
export use that record with the current task or scene capacity floor.
|
||||
Explicit flags override the saved setting and floor.
|
||||
3. Run `scripts/train.py --task <robot_id>` with the chosen backend, device
|
||||
and environment count. Use `--headless` for unattended runs. Watch
|
||||
tracking rewards, episode lengths, termination counts, action spread,
|
||||
and curriculum level. Use `--resume` for the latest run or
|
||||
`--checkpoint <path>` for a specific one. On resume, an iteration override
|
||||
counts additional iterations.
|
||||
4. Run `scripts/play.py --task <robot_id> --checkpoint <path> --headless
|
||||
--steps <count> --speed 0 --measure`. Use `--checkpoint-command-ranges`
|
||||
for the saved curriculum range. For a fixed command inside that range,
|
||||
add `--command <vx> <vy> <yaw_rate> --evaluation-out <json>`. Match replay
|
||||
physics to training and report the observation noise setting.
|
||||
5. Report the checkpoint, backend, environment count, iteration count,
|
||||
evaluation command and duration, measured tracking, and resets. Describe
|
||||
a one-iteration smoke as an execution check. Record when replay was not
|
||||
run or results are unavailable.
|
||||
Start with a [registered, calibrated task](../new-task/SKILL.md) and the
|
||||
[claim and evidence to collect](../../../docs/ROBOT_ONBOARDING_LESSONS.md).
|
||||
Use [Train and replay](../../../docs/USAGE.md#train-and-replay) for commands,
|
||||
checkpoint selection and backend capacity settings.
|
||||
|
||||
See the [tutorial](../../../docs/TUTORIAL.md) for the end-to-end sequence.
|
||||
1. **Establish a comparable baseline.** Record the task, checkpoint, backend,
|
||||
physics/control rates, noise setting, evaluation commands and duration.
|
||||
Check that the named observations, history, normalization, home and action
|
||||
mapping still mean the same thing before resuming. If incompatible, keep
|
||||
the old recipe and treat the new one as a separate experiment. Attribute a
|
||||
reference adaptation, warm start or from-scratch run accurately.
|
||||
2. **Run a bounded pilot.** Resolve the task, smoke-test the selected backend
|
||||
and size the run from available memory and throughput. An overflow needs a
|
||||
corrected allocation and a new smoke. A completed update proves execution.
|
||||
Use headless measurement for unattended replay; plotting must not open a GUI.
|
||||
3. **If commands produce little movement**, trace a named channel from raw
|
||||
action through the target transform, limits and applied effort to measured
|
||||
joint and body motion. Scale is in target units per policy unit, not a
|
||||
clipping bound. Check contact/reset feasibility before attributing the
|
||||
result to learning. Compare held and active channels separately.
|
||||
4. **If the task pays for the wrong behavior**, compare reward per unit time
|
||||
for the failure and an attempted improvement at the same command. Include
|
||||
per-event terms, timestep, unused axes and penalties on channels without
|
||||
physical authority. A partial budget suggests an experiment; it does not
|
||||
establish a cause. Test the predicted improvement in a bounded ablation
|
||||
before spending more iterations. If using a frozen teacher, verify matched
|
||||
pre-action observations and masks across resets, frozen normalization, and
|
||||
learner-only replay.
|
||||
5. **Select by measured behavior.** Compare commanded and actual responses,
|
||||
resets and effort across the claimed conditions. For stepping gaits, measure
|
||||
complete swings per limb and environment, timing, clearance, coordination
|
||||
and joint excursions. Exclude events crossing a reset or window boundary;
|
||||
retain chatter. Measure slip at the contact point and effort fast enough to
|
||||
observe clipping, or label a proxy and its limits. Use appropriate measures
|
||||
for rolling or other motion. Derive thresholds from the task and a comparable
|
||||
reference, never from a different robot's accepted checkpoint.
|
||||
|
||||
Report whether to continue, reject or hand off the selected checkpoint, with
|
||||
the measurements behind that decision. If export is requested, pass the recipe,
|
||||
contract, tested envelope and open quality issues to [deploy](../deploy/SKILL.md).
|
||||
|
||||
+4
-3
@@ -3,20 +3,21 @@ __pycache__/
|
||||
*.py[cod]
|
||||
*.egg-info/
|
||||
.pytest_cache/
|
||||
.ruff_cache/
|
||||
.venv/
|
||||
venv/
|
||||
build/
|
||||
dist/
|
||||
|
||||
# Training artefacts
|
||||
# Training and packaging artefacts
|
||||
logs/
|
||||
runs/
|
||||
outputs/
|
||||
# scripts/export.py's default output directory
|
||||
# Default output directory for scripts/deploy.py and onboarding reports
|
||||
out/
|
||||
*.pt
|
||||
*.onnx
|
||||
# deploy/onnx2rknn.py's output, and the record of what built it
|
||||
# deploy/convert/onnx2rknn.py's output, and the record of what built it
|
||||
*.rknn
|
||||
*.rknn.json
|
||||
wandb/
|
||||
|
||||
@@ -32,10 +32,16 @@ Read an applicable `SKILL.md` in full before starting the work.
|
||||
| [new-task](.claude/skills/new-task/SKILL.md) | Create the data-only robot specification and verify discovery. |
|
||||
| [train](.claude/skills/train/SKILL.md) | Run or resume training and report measured replay results. |
|
||||
| [controls](.claude/skills/controls/SKILL.md) | Bind keys and pad controls using the shared vocabulary. |
|
||||
| [deploy](.claude/skills/deploy/SKILL.md) | Export and package policies for the supported host. |
|
||||
| [deploy](.claude/skills/deploy/SKILL.md) | Verify and package a viewer, deterministic controller or policy for the supported host. |
|
||||
| [bundle-manual](.claude/skills/bundle-manual/SKILL.md) | Translate the built application's operator manual. |
|
||||
|
||||
Every new skill belongs in this table. The template directories carry their own
|
||||
lock instructions. Onboarding writes one literal `robot_spec.py` per robot and
|
||||
lock instructions. Tier 3 registration writes one literal `robot_spec.py` per robot and
|
||||
keeps the calibrated asset, controller, reports, and controls outside the locked
|
||||
templates.
|
||||
|
||||
## Maintain skills after every robot intake
|
||||
|
||||
Every new intake, including failed or blocked work, ends with the
|
||||
[case report and skill review](docs/ROBOT_ONBOARDING_LESSONS.md#required-closeout-for-every-new-robot).
|
||||
Apply any transferable correction to the owning skill before handoff.
|
||||
|
||||
@@ -4,6 +4,9 @@ The project is a generic robotics onboarding, simulation, and training platform.
|
||||
Choose an intake route in [Workflow](docs/WORKFLOWS.md). Use
|
||||
[Usage](docs/USAGE.md) for commands and [Contributing](CONTRIBUTING.md) for layout.
|
||||
|
||||
Apply the mandatory [per-robot skill maintenance rule](AGENTS.md#maintain-skills-after-every-robot-intake)
|
||||
to every intake.
|
||||
|
||||
## Checks
|
||||
|
||||
Run from the repository root with the editable install active.
|
||||
|
||||
+4
-1
@@ -24,6 +24,7 @@ mjrl-lab/
|
||||
│ ├── dds/ # legacy wire interface
|
||||
│ └── fsm/ # legacy Rust controller
|
||||
├── docs/ # manuals and design notes
|
||||
├── notebooks/ # Colab GPU training notebook and guides
|
||||
├── rl/
|
||||
│ ├── mjlab/ # vendored simulator and manager library
|
||||
│ ├── mjrl/
|
||||
@@ -31,7 +32,9 @@ mjrl-lab/
|
||||
│ │ ├── controllers/ # deterministic controller models
|
||||
│ │ ├── onboarding/ # inspect, build, calibrate, verify
|
||||
│ │ ├── platform/ # native app assembly and runtime
|
||||
│ │ └── tasks/ # reusable MDP and curriculum code
|
||||
│ │ ├── sensor/ # native camera and raycast sensors
|
||||
│ │ ├── tasks/ # reusable MDP and curriculum code
|
||||
│ │ └── viewer/ # live viewer, telemetry, and video recording
|
||||
│ └── rsl_rl/ # vendored learning algorithms
|
||||
├── scenes/ # built-in world configurations
|
||||
├── scripts/ # onboard, train, play, export, deploy
|
||||
|
||||
@@ -14,6 +14,22 @@ on native MuJoCo CPU or MuJoCo Warp GPU.
|
||||
| 2 | Complete robot model and known kinematics | Deterministic controller and native verification report |
|
||||
| 3 | Legged robot with a calibrated stance and explicit control intent | Robot specification and training through a locked morphology template |
|
||||
|
||||
## Train with an AI Agent (Recommended)
|
||||
|
||||
We recommend opening this repository folder directly in an AI coding agent
|
||||
(such as Claude Code, Antigravity, Cursor, or Codex) and instructing the AI in
|
||||
natural language to onboard and train your robot.
|
||||
|
||||
The repository includes [AGENTS.md](AGENTS.md), [CLAUDE.md](CLAUDE.md), and
|
||||
specialized workflow skills under `.claude/skills/` (`setup-env`,
|
||||
`onboard-asset`, `tier1-adapt`, `tier2-control`, `tier3-train`, `new-task`,
|
||||
`train`, `controls`, `deploy`, and `bundle-manual`). When opened at the
|
||||
repository root, the agent automatically follows these rules and verification
|
||||
gates—you can simply point it at your URDF, MJCF, or mesh directory and ask it
|
||||
to set up the environment, inspect and calibrate the model, generate
|
||||
`tasks/<robot_id>/robot_spec.py`, launch or resume PPO training, run measured
|
||||
replay probes, and package a native `.app` bundle.
|
||||
|
||||
## Run the model viewer
|
||||
|
||||
From the checkout, with Python 3.10–3.13:
|
||||
@@ -76,5 +92,5 @@ and unsuccessful trials, with their measured reasons.
|
||||
- [Tutorial](docs/TUTORIAL.md) for verification, training, and measured replay.
|
||||
- [Colab](docs/COLAB.md) for GPU training with your own registered robot.
|
||||
- [Hardware and model facts](docs/HARDWARE.md) for calibration and actuator inputs.
|
||||
- [Deployment format](deploy/BUNDLE.md) for application contents and runtime contracts.
|
||||
- [Deploy guide](deploy/README.md) and [deployment format](deploy/BUNDLE.md) for application contents and runtime contracts.
|
||||
- [Contributing](CONTRIBUTING.md) for repository layout and checks.
|
||||
|
||||
+13
-7
@@ -1,6 +1,6 @@
|
||||
# MJRL 机器人平台
|
||||
|
||||
<!-- tracks: README.md @ sha256:5e58614ff2c467bd -->
|
||||
<!-- tracks: README.md @ sha256:124d41b6e17eb69c -->
|
||||
|
||||
[English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md)
|
||||
|
||||
@@ -15,6 +15,12 @@ MuJoCo Warp GPU 上训练运动策略。
|
||||
| 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 |
|
||||
| 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 |
|
||||
|
||||
## 使用 AI Agent 进行接入与训练(推荐)
|
||||
|
||||
建议使用 AI Agent(如 Claude Code、Antigravity、Cursor、Codex 等)直接打开本仓库根目录文件夹,并通过自然语言指挥 AI 进行机器人接入、训练与打包。
|
||||
|
||||
仓库内置了 [AGENTS.md](AGENTS.md)、[CLAUDE.md](CLAUDE.md) 以及位于 `.claude/skills/` 下的专用工作流技能(`setup-env`、`onboard-asset`、`tier1-adapt`、`tier2-control`、`tier3-train`、`new-task`、`train`、`controls`、`deploy`、`bundle-manual`)。在仓库根目录下打开后,AI Agent 会自动读取工作规则与验证门禁——你只需告知 URDF、MJCF 或网格模型路径,即可指挥 AI 自动完成环境配置、模型检查与站姿标定、生成 `tasks/<robot_id>/robot_spec.py`、启动或恢复 PPO 训练、执行量化回放评测以及打包原生 `.app` 应用。
|
||||
|
||||
## 运行模型查看应用
|
||||
|
||||
在代码库根目录中使用 Python 3.10–3.13:
|
||||
@@ -65,9 +71,9 @@ Python 和所列依赖。现有 Rust 浏览器与板端走独立的旧版包格
|
||||
|
||||
## 参考
|
||||
|
||||
- [项目指南](docs/PROJECT_GUIDE.zh.md)
|
||||
- [教程](docs/TUTORIAL.zh.md)
|
||||
- [Colab](docs/COLAB.zh.md) 用于在 GPU 上训练自己注册的机器人
|
||||
- [硬件与模型参数](docs/HARDWARE.zh.md)
|
||||
- [部署包格式](deploy/BUNDLE.md)
|
||||
- [贡献指南](CONTRIBUTING.md)
|
||||
- [项目指南](docs/PROJECT_GUIDE.zh.md):导航与支持边界说明。
|
||||
- [教程](docs/TUTORIAL.zh.md):验证、训练与量化回放流程。
|
||||
- [Colab](docs/COLAB.zh.md):在 GPU 上训练已注册的机器人。
|
||||
- [硬件与模型参数](docs/HARDWARE.zh.md):标定要求与执行器输入规范。
|
||||
- [部署指南](deploy/README.zh.md)与[部署包格式](deploy/BUNDLE.md):应用结构与运行时契约。
|
||||
- [贡献指南](CONTRIBUTING.md):目录结构与仓库检查项。
|
||||
|
||||
@@ -84,10 +84,12 @@ and settled after Escape.
|
||||
The packaged runtime reproduced seven 12-second probes, including sampled
|
||||
joint state and per-axis body-frame tracking metrics. The app includes the
|
||||
asset license and provenance along with English and Chinese operator manuals.
|
||||
After building the app, use the repository's native reference checker.
|
||||
Build the app and run the repository's native reference checker:
|
||||
|
||||
```bash
|
||||
python scripts/deploy.py --check-reference out/platform_release_20261104/go1_example.app
|
||||
python scripts/play.py --app out/platform_release_20261104/go1_example.app --headless \
|
||||
python scripts/deploy.py --robot go1_example --checkpoint <checkpoint.pt> \
|
||||
--output out/go1_example_bundle
|
||||
python scripts/deploy.py --check-reference out/go1_example_bundle/go1_example.app
|
||||
python scripts/play.py --app out/go1_example_bundle/go1_example.app --headless \
|
||||
--steps 200 --command 0.4 0 0
|
||||
```
|
||||
|
||||
@@ -20,7 +20,7 @@ python scripts/onboard.py calibrate --model assets/multipod_example/multipod.xml
|
||||
python scripts/onboard.py scaffold-tier3 --config assets/multipod_example/robot.json \
|
||||
--calibration out/multipod-calibration.json --tasks-root out/multipod-scaffold
|
||||
python scripts/train.py --task multipod_example --backend native --device cpu \
|
||||
--num_envs 4 --max-iterations 1 --headless --no-tensorboard
|
||||
--num-envs 4 --max-iterations 1 --headless --no-tensorboard
|
||||
```
|
||||
|
||||
The checked-in robot specification is the calibrated task used by the
|
||||
|
||||
@@ -138,7 +138,7 @@ whether the reader pairs at all -- and a mismatch does not raise, it leaves
|
||||
|
||||
The 2026-09-29 refresh is that case again. The `ImuData` fields reached mbus master
|
||||
only in the 2026-09-28 merge, mbus's CHANGELOG has no release entry for them yet, and
|
||||
the board last read (`deploy/README.md`) ran libmbus 2.4.0, from 2026-09-02. A
|
||||
the board last read ran libmbus 2.4.0, from 2026-09-02. A
|
||||
controller built from this tree pairs with an `mc_ctrl_driver` / `mc_forwarder` rebuilt
|
||||
against `d9875988f065` or later, and with nothing older. `check_board.py` compares the
|
||||
board's `idl_motor_control.h` with the one generated here and says which it is.
|
||||
|
||||
@@ -261,7 +261,7 @@ operator fresh either way, so sending it every frame is harmless.
|
||||
a page that wants to say which keys do something: `controls` is each mode's own
|
||||
account of its bindings -- the lines the robot's controller prints before it
|
||||
enables the motors -- on one line, the modes that read the pad alike named
|
||||
together: `claw_left, claw_right: … | locomotion: …`. Show it as given;
|
||||
together: `stand: … | locomotion: …`. Show it as given;
|
||||
describing the bundle yourself would be a second copy of its bindings.
|
||||
|
||||
`fsm.bindings()` returns `[{name, pad, key, on, with, from, leaves}]` -- the mode
|
||||
|
||||
+11
-11
@@ -13,8 +13,8 @@ places they have to run:
|
||||
|
||||
| | observation from | inference on | execution to |
|
||||
|---|---|---|---|
|
||||
| `kk-rl-mjlab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators |
|
||||
| BEUNLIMITED's web sim | MuJoCo WASM | ONNX, in the browser | the same actuators |
|
||||
| `mjrl-lab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators |
|
||||
| the browser web sim | MuJoCo WASM | ONNX, in the browser | the same actuators |
|
||||
| the robot | servos and IMU | RKNN, on the NPU | DDS to the motor controller |
|
||||
|
||||
That logic existed **three times**: this crate in Rust, `rl-wbc-fsm` in C++,
|
||||
@@ -162,7 +162,7 @@ locomotion on `device`:
|
||||
```
|
||||
|
||||
**That list is the sim2real gap, enumerated.** Nobody can see it today. It costs
|
||||
one field per term in the exported contract — every term kk-rl-mjlab exports is
|
||||
one field per term in the exported contract — every term `mjrl-lab` exports is
|
||||
`Simulated`, so producing it is nearly free, and the value is entirely on the
|
||||
consuming side.
|
||||
|
||||
@@ -292,8 +292,8 @@ So transitions become an **ordered rule list**, first match wins:
|
||||
[[fsm.rule]] when = "in_state:safe" enter = "@initial"
|
||||
[[fsm.rule]] when = "warm_start_reached" enter = "@warm_start_ref"
|
||||
[[fsm.rule]] when = "in_state:warmstart" enter = "@stay"
|
||||
[[fsm.rule]] when = "button:jump" enter = "jump"
|
||||
[[fsm.rule]] when = "button:claw_left" enter = "claw_left"
|
||||
[[fsm.rule]] when = "button:stand" enter = "stand"
|
||||
[[fsm.rule]] when = "button:motion" enter = "motion"
|
||||
[[fsm.rule]] when = "always" enter = "locomotion"
|
||||
```
|
||||
|
||||
@@ -466,7 +466,7 @@ Built as of this document:
|
||||
| the two-phase tick, four regimes, per-mode runtimes | `src/control.rs` |
|
||||
| each mode's reading of the pad and keys, command shaping | `src/operator.rs` |
|
||||
| the pad's manual as data (`pad_guide`) | `src/guide.rs` |
|
||||
| a task's deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` |
|
||||
| an optional task deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` |
|
||||
| the recorded motion a reference-guided mode is driven by | `src/trajectory.rs` |
|
||||
| a recorded run replayed, and where a host differs | `src/reference.rs` |
|
||||
| the bundle format, one reader for every host with a filesystem | `src/bundle.rs` |
|
||||
@@ -475,11 +475,11 @@ Built as of this document:
|
||||
| `play`'s host: the pyo3 `Fsm` | `src/py.rs` |
|
||||
| the robot's program: the loop, the two clocks, the shutdown path | `src/bin/controller.rs` |
|
||||
|
||||
156 tests. Two of them are control groups, because both of these modules replace
|
||||
162 tests in the generic controller core. Two of them are control groups, because both of these modules replace
|
||||
something that was previously written into code and would pass every obvious
|
||||
assertion while ignoring the file: `the_cascade_is_the_file_s_rather_than_agreeing_with_it`
|
||||
moves the tilt rule below the operator's button and requires a tilted robot to
|
||||
jump, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains
|
||||
switch modes, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains
|
||||
a term as reconstructed and requires simulation to be reported as the divergence.
|
||||
|
||||
`control.rs` earned a third test the hard way. Its first `publish` used
|
||||
@@ -507,8 +507,8 @@ into a `button:<name>` the rules can match. `pump` is compiled against the real
|
||||
|
||||
`[[fsm.button]]` names one thing the operator can ask for and which control asks
|
||||
it: a pad button or a keyboard key, one device per entry, and two entries with
|
||||
one name share its latch -- the pad's A and the keyboard's Space are both the
|
||||
jump. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click
|
||||
one name share its latch -- the pad's A and the keyboard's Space can both drive
|
||||
the same mode switch. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click
|
||||
count `single` … `quintuple` counted inside `[fsm] click_window_ms`), an optional
|
||||
`with` modifier (a pad button, or `ctrl` / `shift` / `alt` for a key), `from`
|
||||
(the states it may be pressed in) and `leaves` (latches it lets go of). Pad
|
||||
@@ -598,6 +598,6 @@ second shutdown behaviour. None of it can be tested off the board.
|
||||
## Open
|
||||
|
||||
- **Provenance in the exported contract.** Needs a field per observation term in
|
||||
kk-rl-mjlab's exporter. Cheap to produce, and the whole value of the divergence
|
||||
`mjrl-lab`'s exporter. Cheap to produce, and the whole value of the divergence
|
||||
list depends on it.
|
||||
- **Per-mode command vocabulary**, above.
|
||||
|
||||
@@ -77,7 +77,7 @@ and one `.app` of it that somebody with none of this repository can use, on any
|
||||
of the three hosts:
|
||||
|
||||
```bash
|
||||
python scripts/deploy.py
|
||||
python scripts/deploy.py --manifest <bundle-id>
|
||||
```
|
||||
|
||||
It runs the cross build above first, every time, so the board's binary in the
|
||||
@@ -94,7 +94,7 @@ removed rather than left for someone to upload. Then it is held to
|
||||
For the wasm, a cargo build and wasm-bindgen are what it runs. Run it rather
|
||||
than them: it reads the commit **after** looking at the tree, suffixes it `-dirty`
|
||||
when the controller's source has uncommitted changes -- the crate, and every file
|
||||
outside it the build reads, each task's hook among them (`SOURCES` in the script)
|
||||
outside it the build reads (`SOURCES` in the script)
|
||||
-- and holds the wasm-bindgen CLI
|
||||
against the version the crate compiles with. The hand procedure lasted one day
|
||||
before it recorded a commit whose source would have built a different controller
|
||||
@@ -165,9 +165,9 @@ the policy `(0, 0)`.
|
||||
**This is not cosmetic, and the C++ controller does not do it.** The policy is
|
||||
trained that way — zero magnitude is a value no phase can produce, i.e. an
|
||||
unambiguous "hold still". A free-running unit-magnitude clock was measured during
|
||||
training to make the robot step in place while commanded to stand: roll-rate
|
||||
autocorrelation peaked at the clock frequency, and 5.17 of 6 feet were on the
|
||||
ground.
|
||||
training to make the robot step in place while commanded to stand, with roll-rate
|
||||
autocorrelation peaking at the clock frequency instead of holding all supports on
|
||||
the ground.
|
||||
|
||||
The failure is invisible to every dimension check: gated or not, `gait_phase` is
|
||||
2 wide and the observation is the same length. Only the values differ, and only
|
||||
|
||||
Vendored
+2
-2
@@ -32,8 +32,8 @@ not free to float:
|
||||
|
||||
- `deploy/convert/requirements.txt` pins `rknn-toolkit2==2.3.2`, and a `.rknn`
|
||||
does not load under a `librknnrt` older than the toolkit that produced it;
|
||||
- the board carries `librknnrt` 2.3.2 (`deploy/README.md`, *Verified against the
|
||||
board*), and `.claude/skills/deploy/scripts/check_board.py` checks it.
|
||||
- the board carries `librknnrt` 2.3.2, and
|
||||
`.claude/skills/deploy/scripts/check_board.py` checks it.
|
||||
|
||||
Moving to another release means changing all three together, and the two sha256
|
||||
values in `fetch.sh` with them.
|
||||
|
||||
+21
-15
@@ -215,17 +215,18 @@ If this environment ever had them, uninstall first (this does not remove their d
|
||||
pip uninstall -y mjlab rsl-rl-lib
|
||||
```
|
||||
|
||||
### 2.1 The controller's toolchain: Rust
|
||||
### 2.1 The legacy controller's toolchain: Rust
|
||||
|
||||
The controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds two of
|
||||
them on this machine with cargo — the browser's wasm and `play --app`'s extension — and
|
||||
The legacy controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds
|
||||
two of them on this machine with cargo — the browser's wasm and the legacy `play --app` extension — and
|
||||
cross-builds the board's binary and the Windows extension in Docker, which brings its own
|
||||
toolchain. **Every row of section 0's decision table needs this subsection**; it does not branch
|
||||
on the GPU.
|
||||
toolchain. Native platform `.app` bundles (`mjrl-robot-app/1`) run in pure Python without this
|
||||
toolchain; install this subsection when building or testing legacy `kk-policy-bundle/1` browser,
|
||||
board, or extension targets.
|
||||
|
||||
> ⚠️ **Without cargo the test suite does not fail, it skips.** `tests/test_fsm_extension.py` and
|
||||
> ⚠️ **Without cargo the legacy controller tests do not fail, they skip.** `tests/test_fsm_extension.py` and
|
||||
> `tests/test_deploy_sources.py` skip when there is no cargo, so `pytest tests/` is green on a
|
||||
> machine that has never built the controller.
|
||||
> machine that has never built the legacy controller.
|
||||
|
||||
Four pieces. `detect.py` prints only the ones this machine lacks:
|
||||
|
||||
@@ -307,7 +308,7 @@ export PATH=$CYCLONEDDS_HOME/bin:$PATH
|
||||
```
|
||||
|
||||
bindgen finds libclang in Xcode's command-line tools. Measured on an M3 Max (Darwin 25.5,
|
||||
cargo 1.95.0) on 2026-10-08: the build takes about two minutes, gate F lists 195 tests, and
|
||||
cargo 1.95.0): the build takes about two minutes, gate F lists 162 tests, and
|
||||
`cargo test --lib` in `deploy/fsm` passes all of them. A test binary built before
|
||||
`CYCLONEDDS_HOME` was exported carries no rpath and aborts with
|
||||
`Library not loaded: @rpath/libddsc.11.dylib`; rebuild it (`cargo clean -p mjrl-fsm`) rather
|
||||
@@ -394,9 +395,11 @@ A `ModuleNotFoundError` here means `pip install -e .` was not run or did not suc
|
||||
python scripts/train.py --list
|
||||
```
|
||||
|
||||
Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID. A fresh
|
||||
checkout reports an empty registry. This command loads no simulation
|
||||
dependencies. Check the editable install and literal robot specs if it fails.
|
||||
Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID (on a fresh
|
||||
checkout: `g1_example`, `go1_example`, `multipod_example`, and
|
||||
`wheeled_biped_example`), followed by the built-in scenes. This command loads no
|
||||
simulation dependencies. Check the editable install and literal robot specs if
|
||||
it fails.
|
||||
|
||||
### Gate E — The Rust toolchain builds the controller's host targets
|
||||
|
||||
@@ -420,7 +423,7 @@ a new machine also downloads them.
|
||||
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
|
||||
```
|
||||
|
||||
Expected: a list of lines ending in `: test` (179 of them on 2026-09-29). `--list` runs the test
|
||||
Expected: a list of lines ending in `: test` (162 in the generic controller core). `--list` runs the test
|
||||
binary without running a test, so it proves `libddsc` is found at load time — which a
|
||||
`cargo check` never would — and a failing crate test cannot pass itself off as an environment
|
||||
fault. 9 s cold on the same machine. A checkout without Rockchip's NPU header fails here, in
|
||||
@@ -516,9 +519,12 @@ wandb also works, but tensorboard is less trouble.)
|
||||
infers defaults from the `mjData` of a resting pose, and a moving robot has many more contacts
|
||||
than a resting one.
|
||||
|
||||
Inspect the model's contact geometry and measure contact load. A capacity change
|
||||
to the shared simulator recipe requires an explicit template revision and
|
||||
updated lock validation.
|
||||
**Remedy**: pass `--warp-max-constraints N` and/or `--warp-max-contacts N` on the command line
|
||||
(for example, `g1_example` uses `--warp-max-constraints 300`). Warp runs record these capacities in
|
||||
`warp-allocation.json` beside their checkpoints for resume, replay, and export. Also inspect the
|
||||
model's collision geometry (`onboard.py build-mjcf` or `tools/hull_collision.py`) if contact load is
|
||||
unreasonably high. A default capacity change inside the shared simulator recipe requires an explicit
|
||||
template revision and updated lock validation.
|
||||
|
||||
### `"cuda" device requested but this build of Warp does not support CUDA`
|
||||
|
||||
|
||||
+20
-15
@@ -1,9 +1,9 @@
|
||||
<!-- tracks: AGENT_SETUP.md @ sha256:62621d9b01a77c30 -->
|
||||
<!-- tracks: AGENT_SETUP.md @ sha256:076262f3d4d73ae1 -->
|
||||
|
||||
# 环境搭建说明(写给 AI agent)
|
||||
|
||||
本文档写给**在一台全新机器上把 mjrl-lab 跑起来的 AI agent**。
|
||||
人类读者请从 [`../README.md`](../README.md) 开始。
|
||||
人类读者请从 [`../README.zh.md`](../README.zh.md) 开始。
|
||||
|
||||
## 机械的部分由两个脚本完成
|
||||
|
||||
@@ -203,15 +203,15 @@ pip install -e .
|
||||
pip uninstall -y mjlab rsl-rl-lib
|
||||
```
|
||||
|
||||
### 2.1 控制器的工具链:Rust
|
||||
### 2.1 旧版控制器的工具链:Rust
|
||||
|
||||
控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用
|
||||
cargo 构建其中两种 —— 浏览器的 wasm 和 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在
|
||||
Docker 里交叉编译,镜像自带工具链。**第 0 节决策表的每一行都需要本小节**;它不按有没有 GPU
|
||||
分叉。
|
||||
旧版控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用
|
||||
cargo 构建其中两种 —— 浏览器的 wasm 和旧版 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在
|
||||
Docker 里交叉编译,镜像自带工具链。原生平台 `.app` 应用(`mjrl-robot-app/1`)使用纯 Python 运行,
|
||||
不需要此工具链;仅当需要构建或测试旧版 `kk-policy-bundle/1` 的浏览器、板端或扩展目标时才需安装本小节。
|
||||
|
||||
> ⚠️ **没有 cargo 时测试集不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和
|
||||
> `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过控制器的机器上,
|
||||
> ⚠️ **没有 cargo 时旧版控制器测试不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和
|
||||
> `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过旧版控制器的机器上,
|
||||
> `pytest tests/` 也是绿的。
|
||||
|
||||
一共四样。`detect.py` 只打印这台机器缺的那几样:
|
||||
@@ -290,8 +290,8 @@ export CYCLONEDDS_HOME=$HOME/.local/opt/cyclonedds-11.0.1
|
||||
export PATH=$CYCLONEDDS_HOME/bin:$PATH
|
||||
```
|
||||
|
||||
bindgen 从 Xcode 命令行工具里找 libclang。2026-10-08 在一台 M3 Max(Darwin 25.5,cargo
|
||||
1.95.0)上实测:构建约两分钟,gate F 列出 195 个测试,`deploy/fsm` 里 `cargo test --lib` 全部
|
||||
bindgen 从 Xcode 命令行工具里找 libclang。在一台 M3 Max(Darwin 25.5,cargo
|
||||
1.95.0)上实测:构建约两分钟,gate F 列出 162 个测试,`deploy/fsm` 里 `cargo test --lib` 全部
|
||||
通过。在 `export CYCLONEDDS_HOME` 之前构建出来的测试二进制没有 rpath,会以
|
||||
`Library not loaded: @rpath/libddsc.11.dylib` 中止;重新构建它(`cargo clean -p mjrl-fsm`),
|
||||
不必重装 CycloneDDS。
|
||||
@@ -373,8 +373,9 @@ python -c "import mjlab, rsl_rl, os; print(os.path.dirname(mjlab.__file__)); pri
|
||||
python scripts/train.py --list
|
||||
```
|
||||
|
||||
预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出。新检出报告空注册表。
|
||||
该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。
|
||||
预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出(新检出包含
|
||||
`g1_example`、`go1_example`、`multipod_example` 和 `wheeled_biped_example`),
|
||||
随后列出内置场景。该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。
|
||||
|
||||
### Gate E —— Rust 工具链能构建控制器的宿主目标
|
||||
|
||||
@@ -397,7 +398,7 @@ wasm-bindgen --version
|
||||
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
|
||||
```
|
||||
|
||||
预期:一串以 `: test` 结尾的行(2026-09-29 时是 179 行)。`--list` 会运行测试二进制但不执行
|
||||
预期:一串以 `: test` 结尾的行(通用控制器核心包含 162 个测试)。`--list` 会运行测试二进制但不执行
|
||||
任何测试,所以它能证明加载时找得到 `libddsc` —— 这是 `cargo check` 永远证明不了的 —— 同时
|
||||
crate 自己的测试失败也没法冒充成环境故障。同一台机器上冷构建 9 s。缺 Rockchip NPU 头文件的
|
||||
checkout 会在这里、在 `build.rs` 中失败;解决办法是 `fetch.sh`(2.2 节)。
|
||||
@@ -485,7 +486,11 @@ tensorboard 省事。)
|
||||
`njmax` / `nconmax` 是每个 world 上约束行数和接触数的上限。mujoco_warp 从静止姿态的
|
||||
`mjData` 推断默认值,而运动中的机器人接触数比静止时多得多。
|
||||
|
||||
检查碰撞几何并测量接触负载。若需调整共享仿真容量,应明确修订模板并重新验证锁定规则。
|
||||
**补救**:在命令行传入 `--warp-max-constraints N` 和/或 `--warp-max-contacts N`(例如
|
||||
`g1_example` 使用 `--warp-max-constraints 300`)。Warp 训练会在检查点旁的
|
||||
`warp-allocation.json` 中保存该容量供续训、回放和导出使用。若接触负载过高,也应检查碰撞几何
|
||||
(`onboard.py build-mjcf` 或 `tools/hull_collision.py`)。若需调整共享仿真配方的默认容量,
|
||||
应明确修订模板并重新验证锁定规则。
|
||||
|
||||
### `"cuda" device requested but this build of Warp does not support CUDA`
|
||||
|
||||
|
||||
@@ -34,6 +34,23 @@ the number of substeps. Set gains and effort limits for your model. The bench
|
||||
defaults are `kp: 40`, `kd: 4`, and `effort_limit: 30` for position and CPG
|
||||
controllers, or `kv: 5` and `effort_limit: 30` for velocity actuators.
|
||||
|
||||
|
||||
For `ik`, `joint_sliders`, `trajectory`, and `cpg`, each of `kp`, `kd`, and
|
||||
`effort_limit` accepts either one scalar or a map covering every name in `joints`
|
||||
exactly. Maps are resolved by name, independently of actuator order. Values must
|
||||
be finite; `kp` and `effort_limit` must be positive and `kd` nonnegative. For
|
||||
example, `"kp": {"hip": 70, "shoulder": 30}` gives those two controlled joints
|
||||
different stiffnesses. Missing or extra names and positional arrays are rejected.
|
||||
|
||||
Normalization intersects the requested effort with the source actuator force
|
||||
limits, pure motor input limits, and joint actuator-force limits. Source force
|
||||
and motor input bounds are converted through the authored gear before creating
|
||||
unit-gear actuators. Position and velocity target ranges are not effort limits.
|
||||
The resulting model retains the effective bounds even when the configuration
|
||||
requests a larger effort. Each joint must retain effort authority in both
|
||||
directions. CPG clips its computed effort to the smaller magnitude of the two
|
||||
effective bounds; position servos retain the asymmetric bounds when present.
|
||||
|
||||
| `kind` | Required inputs | Output |
|
||||
|---|---|---|
|
||||
| `ik` | `joints`. Provide `site`, or select `end_effector_body` and optional `end_effector_offset` in its local frame | Position targets from damped least-squares IK |
|
||||
@@ -51,9 +68,12 @@ of the other verified kinds. A viewer never advances robot dynamics.
|
||||
A new IK site defaults to `mjrl_ee`. If `end_effector_body` is omitted, setup follows
|
||||
the chain from the last named joint to its unique leaf. A branching chain needs an
|
||||
explicit endpoint. Setup places a collision-free target sphere on a `mocap=true`
|
||||
body named `mjrl_target` unless a different `mocap_body` is configured. Drag that
|
||||
sphere in the MuJoCo viewer, or send `target_x`, `target_y`, and `target_z` as
|
||||
world-space offsets from its starting position. IK solves for the site position.
|
||||
body named `mjrl_target` unless a different `mocap_body` is configured. A generated
|
||||
marker starts at the tool point in the verified reset pose. An existing mocap
|
||||
target keeps its authored origin unless `start_target_at_site` is set. Use
|
||||
the [viewer drag controls](CONTROLS.md#deterministic-controller-controls), or
|
||||
send `target_x`, `target_y`, and `target_z` as world-space offsets from the
|
||||
starting position. Both paths use the configured axis bounds. IK solves for the site position.
|
||||
The solver leaves other joints and the simulated position untouched.
|
||||
|
||||
Joint sliders accept a partial map of joint names to targets and hold other
|
||||
@@ -61,6 +81,25 @@ targets. The MuJoCo viewer's Control panel can also set these targets directly.
|
||||
The generated controls bind the first four axes unless `operator_axes` selects
|
||||
another subset. `command_ranges` can narrow command travel per axis.
|
||||
|
||||
Set `"target_rate_limits": {"elbow": 0.5}` to limit the speed of selected
|
||||
slider targets. Give a positive finite maximum in rad/s for each hinge or m/s
|
||||
for each slide. Unlisted joints take the requested target immediately. At each
|
||||
controller tick a limited target moves toward the requested position by at most
|
||||
the configured rate times elapsed simulation time. A single named command,
|
||||
viewer slider edit, or release-button tap latches the destination until it is
|
||||
reached or replaced. Reset starts from the actual joint positions. Measure the
|
||||
resulting effort and settling time under the intended load when choosing rates.
|
||||
|
||||
For a calibrated slider pose, supply `home` as a finite map covering exactly
|
||||
`joints`, with each value inside both its physical limits and declared command
|
||||
range. Without `home`, the operator rest uses the model reference pose, clipped
|
||||
to the joint limits. `home` sets the operator rest and release targets; it does
|
||||
not move the simulated robot on reset. Reset holds the actual supplied joint
|
||||
positions. Supply the calibrated initial `pose` and base position to verification
|
||||
so the packaged application starts from that verified state. Escape or the pad's
|
||||
release button restores only operator-bound joints to `home`, preserving targets
|
||||
on unbound joints such as supporting legs.
|
||||
|
||||
Trajectory files use `schema: "mjrl-trajectory/1"`, `joint_order`, strictly
|
||||
increasing `time_s` from zero, and one `q` row per timestamp. Positions interpolate
|
||||
linearly in time and hold at the last keyframe. Set `loop: true` for a loop whose
|
||||
@@ -301,3 +340,34 @@ and 0.00304 rad/s in final joint velocities. The policy failed separate forward
|
||||
and yaw tracking probes. It finished at −0.00148 m/s for a 0.08 m/s request
|
||||
and 0.02854 rad/s for a 0.15 rad/s request. This smoke establishes execution
|
||||
and export parity on the fixture.
|
||||
|
||||
### Explicit sensor frames and calibrated motors
|
||||
|
||||
The default base observations use the authored root body frame. An upstream
|
||||
policy may instead observe an IMU site's angular velocity while keeping gravity
|
||||
in the root frame. Declare only the overridden terms in `observation.frames`:
|
||||
|
||||
```json
|
||||
{"observation": {
|
||||
"terms": [{"name": "base_ang_vel"}, {"name": "projected_gravity"}],
|
||||
"frames": {"base_ang_vel": {"kind": "site", "name": "imu"}}
|
||||
}}
|
||||
```
|
||||
|
||||
Frames apply to `base_ang_vel`, `base_lin_vel` and `projected_gravity`; each must
|
||||
name an observed term and an existing `body` or `site`. Local velocities use that
|
||||
frame's origin. These contracts use `mjrl-native-layout/1` to prevent a legacy
|
||||
reader from silently applying different sensor semantics.
|
||||
|
||||
For an actor trained with a calibrated BAM motor, install the optional `bam`
|
||||
extra under Python 3.12. In the top-level `motor_model` block, set `kind` to
|
||||
`bam` and provide the calibrated `motor_name`, `model`, firmware gain `kp`,
|
||||
supply voltage `vin`, current limit `max_current`, supply resistance
|
||||
`vin_drop_resistance` and minimum voltage `vin_min` from the training setup.
|
||||
This opt-in law requires position targets and replaces the ordinary PD effort
|
||||
calculation. `motor_model.kp` is a firmware gain, distinct from the export's
|
||||
`control.kp`. The declared effort limit still bounds output. BAM updates
|
||||
load-dependent friction and damping at every physics tick, resets independently
|
||||
for each probe, and updates passive friction with actuation disabled for the
|
||||
counterfactual. Native bundles pin `better-actuator-models==1.0.2` and declare its
|
||||
Python `>=3.12,<3.13` requirement. The original actor is not retrained.
|
||||
|
||||
+16
-7
@@ -18,13 +18,18 @@ The generated command is `twist` feeding `velocity_commands`. Its axes are
|
||||
`lin_vel_x`, `lin_vel_y`, and `ang_vel_z`, in that order. Pad deflections
|
||||
scale to the command range, with separate positive and negative ends.
|
||||
Keyboard keys bind directly to an axis direction and ramp while held.
|
||||
The default `omni` profile uses W/S for forward and backward, A/D for
|
||||
lateral movement, and J/L for turning. Use `--profile differential` for
|
||||
the wheeled-biped template. W/S still drive forward and backward, A/D turn,
|
||||
and the arrow keys mirror WASD. On the pad, Ly drives forward and backward
|
||||
and Rx turns. The lateral channel stays in the three-axis layout. It is
|
||||
unbound on the keyboard, and the template gives the required Lx pad
|
||||
binding a zero command range.
|
||||
For a registered task the generator selects a layout by family. Bipeds and
|
||||
as-yet unregistered robots default to `walking`; other legged families use
|
||||
`omni`, except wheeled bipeds which use `differential`. An explicit
|
||||
`--profile` overrides that choice.
|
||||
|
||||
The `walking` layout uses W/S for forward/reverse and A/D for
|
||||
left/right yaw. The arrow keys mirror WASD. J/L request left/right lateral
|
||||
motion on policies that support it. The pad uses Ly for forward speed, Lx
|
||||
for lateral speed and Rx for yaw. Holding W+A combines forward and left turn.
|
||||
The explicit `omni` layout keeps A/D for lateral motion and J/L for yaw.
|
||||
Use `--profile differential` for a wheeled biped; its lateral axis is
|
||||
unbound on the keyboard and has a zero command range in the template.
|
||||
|
||||
Use `--bind AXIS=SOURCE+` or `--bind AXIS=SOURCE-` for explicit signs and
|
||||
`--release BUTTON` for the pad release. Review the direction of motion and
|
||||
@@ -39,6 +44,10 @@ joint sliders or targets can be addressed through the programmatic controller.
|
||||
Run native verification with the exact controller and controls paths. After
|
||||
changing bindings, generate a fresh report before packaging.
|
||||
|
||||
For end-effector IK, double-click the tool target marker, then hold Ctrl
|
||||
and drag with the right mouse button. Add Shift to change the translation
|
||||
plane. Release the button to hold the selected target.
|
||||
|
||||
## Shared schema
|
||||
|
||||
The schema describes a list of command terms and the bindings for both
|
||||
|
||||
+12
-6
@@ -1,6 +1,6 @@
|
||||
# 操作控制
|
||||
|
||||
<!-- tracks: CONTROLS.md @ sha256:bc51703abef90b63 -->
|
||||
<!-- tracks: CONTROLS.md @ sha256:42ec9ffccdd8a735 -->
|
||||
|
||||
`controller/vocabulary.json` 定义键盘和手柄的控制名称。
|
||||
`python -m controller --vocabulary` 可显示词表。
|
||||
@@ -17,11 +17,14 @@ python .claude/skills/controls/scripts/write_controls.py --task my_robot \
|
||||
|
||||
命令 `twist` 送到 `velocity_commands`,轴顺序为 `lin_vel_x`、
|
||||
`lin_vel_y`、`ang_vel_z`。摇杆的正负两侧分别按命令范围缩放。
|
||||
键盘直接绑定方向,按住时逐渐增大。默认 `omni` 配置用 W/S 控制前后、
|
||||
A/D 控制横移、J/L 控制转向。轮足双足模板使用 `--profile differential`。
|
||||
此时 W/S 仍控制前后,A/D 控制转向,方向键与 WASD 对应。
|
||||
手柄的 Ly 控制前后,Rx 控制转向。三轴布局仍保留横向通道,键盘不绑定此轴,
|
||||
模板将格式要求的手柄 Lx 绑定的命令范围设为零。
|
||||
已注册任务按形态选择布局。双足人形和暂未注册的机器人默认用 `walking`,轮足
|
||||
双足用 `differential`,其余足式任务用 `omni`。可用 `--profile` 显式指定。
|
||||
|
||||
按键按住时,命令逐渐增大。`walking` 布局用 W/S 控制前进和后退,
|
||||
A/D 控制左转和右转,方向键与 WASD 对应。支持侧移的策略还可以用 J/L 左右侧移。
|
||||
手柄的 Ly、Lx 和 Rx 分别控制前后、侧移和转向。按住 W+A 可边前进边左转。
|
||||
显式选择 `omni` 可使用 A/D 侧移、J/L 转向的布局。轮足双足使用
|
||||
`--profile differential`,其横向轴无键盘绑定,模板中的横向速度范围为零。
|
||||
|
||||
用 `--bind AXIS=SOURCE+` 或 `--bind AXIS=SOURCE-` 指定符号,
|
||||
用 `--release BUTTON` 设置手柄释放键。在仿真检查方向和释放动作,
|
||||
@@ -33,6 +36,9 @@ A/D 控制横移、J/L 控制转向。轮足双足模板使用 `--profile differ
|
||||
`operator_axes` 最多选四个轴,其余关节滑块或目标可通过程序接口控制。
|
||||
打包前验证实际使用的控制器和绑定。修改后重新生成报告。
|
||||
|
||||
在末端控制模式下,双击末端的目标标记,按住 Ctrl 并用鼠标右键拖动。
|
||||
同时按住 Shift 可切换拖动平面,松开鼠标后保持当前位置目标。
|
||||
|
||||
## 共享格式
|
||||
|
||||
命令列表声明名称、输出位置、坐标系、有序的轴和满幅缩放规则。每个轴有单位与
|
||||
|
||||
@@ -16,7 +16,7 @@ platform. Use [Agent setup](AGENT_SETUP.md) to establish the environment and
|
||||
| Extend the platform | [Contributing](../CONTRIBUTING.md) |
|
||||
|
||||
The checkout includes calibrated Go1, G1, six-legged and wheeled-biped examples,
|
||||
covering all four locked families. G1 also has a separate compliant-gain variant.
|
||||
covering all four locked families.
|
||||
Their asset READMEs distinguish execution checks, measured
|
||||
learning and accepted policies; registration alone is not a performance or
|
||||
hardware qualification. Add another robot with the onboarding tools to give it
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 项目指南
|
||||
|
||||
<!-- tracks: PROJECT_GUIDE.md @ sha256:ed077c5edd6cf510 -->
|
||||
<!-- tracks: PROJECT_GUIDE.md @ sha256:1db03214fd026c6f -->
|
||||
|
||||
接入资产或策略时先读[接入流程](WORKFLOWS.md)。用[环境准备](AGENT_SETUP.zh.md)
|
||||
建立环境,用[命令手册](USAGE.zh.md)查询命令和配置。
|
||||
@@ -12,12 +12,11 @@
|
||||
| 配置键盘或手柄 | [操作控制](CONTROLS.zh.md) |
|
||||
| 训练和测量足式策略 | [教程](TUTORIAL.zh.md) |
|
||||
| 在 Colab GPU 上训练 | [Colab](COLAB.zh.md) |
|
||||
| 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.md)与[包格式](../deploy/BUNDLE.md) |
|
||||
| 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.zh.md)与[包格式](../deploy/BUNDLE.md) |
|
||||
| 理解双后端与模板锁定 | [平台设计](DESIGN.md)与[上游依赖](VENDOR.md) |
|
||||
| 扩展平台 | [贡献指南](../CONTRIBUTING.md) |
|
||||
|
||||
本仓库包含经过标定的 Go1、G1、六足和轮足双足样例,覆盖四个锁定模板。
|
||||
G1 另有一个独立的柔顺增益变体。
|
||||
各资产的 README 区分执行检查、实际学习效果与验收通过的策略;注册本身不代表
|
||||
性能达标或硬件认证。用接入工具为新机器人生成任务 ID,再运行
|
||||
`python scripts/train.py --list` 查看本地注册项。
|
||||
|
||||
@@ -14,7 +14,8 @@ instructions.
|
||||
third-party notices. The legacy Rockchip runtime has separate provenance
|
||||
and terms described in its [runtime notes](../deploy/fsm/vendor/rknpu2/README.md).
|
||||
- Inspect tracked configuration, generated packages, and archives for private
|
||||
content. Shared defaults are in `.env`. Keep `.env.local` out of the snapshot.
|
||||
content. Shared option keys are documented in `.env.example`. Keep `.env` and
|
||||
`.env.local` out of the snapshot.
|
||||
- Choose the commit identity, confirm the target remote and branch, and
|
||||
review changes already present there before publishing.
|
||||
- Keep release downloads and provenance tied to actual artifacts. Record
|
||||
|
||||
@@ -39,10 +39,9 @@ on 2026-11-04. All training runs started for this snapshot have finished.
|
||||
Bundling fingerprints inputs, rejects missing gates, and reruns the packaged
|
||||
response before publication. The reader uses its own trusted schema.
|
||||
- Original exclusive robot assets/tasks were removed after shared mechanisms were
|
||||
extracted. Historical ignored exports were initially preserved, then removed
|
||||
during workspace cleanup: `out/pre_platform_exports_20261104/` and
|
||||
`out/bundle_example/jumper/`. Training logs, failure reports and other user
|
||||
applications were retained. Scene dimensions are explicit nominal parameters.
|
||||
extracted. Historical ignored exports under `out/` were removed during
|
||||
workspace cleanup, while training logs, failure reports and user applications
|
||||
were retained. Scene dimensions are explicit nominal parameters.
|
||||
|
||||
## Measured evidence
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Robot onboarding: diagnosis and skill maintenance
|
||||
|
||||
Start with the requested capability and operating conditions. Use the
|
||||
[route table](WORKFLOWS.md) to select the applicable [stage skills](../AGENTS.md#skills).
|
||||
A route recommendation is provisional until its required inputs are confirmed.
|
||||
|
||||
## Establish the claim before choosing tools
|
||||
|
||||
Derive observable pass criteria from the request and available evidence before
|
||||
choosing a candidate. Use the rows relevant to the request:
|
||||
|
||||
| Claim | Evidence |
|
||||
|---|---|
|
||||
| The model loads | Resolve dependencies; inspect the compiled topology, units and frames. |
|
||||
| The physical model supports the task | Check the intended initial state, constraints, joint margins and loads. Measure ground contact and stance only where relevant. |
|
||||
| Commands work | Compare requested and measured physical responses across the claimed range, including rest or transitions where meaningful. |
|
||||
| Motion has the requested quality | Pick measures suited to the mechanism and task; inspect individual components as well as the aggregate. Retain representative replay. |
|
||||
| An export is faithful | Compare source and target behavior at matched inputs and states, then compare trajectories on the declared runtime. |
|
||||
| The package works | Run the final archive with its actual dependencies and controls on its supported host. |
|
||||
| Motion meets a subjective requirement | Present representative evidence and record the user's verdict separately. |
|
||||
|
||||
Record each relevant claim as **passed, failed or untested**; mark a potentially
|
||||
confusing but inapplicable check **not applicable** and say why. Keep partial
|
||||
passes when the overall request fails. A missing required probe is a coverage
|
||||
gap; it is not a measured failure of that probe.
|
||||
|
||||
## Diagnose one layer at a time
|
||||
|
||||
1. Reproduce the first failing claim. Identify the exact inputs, runtime,
|
||||
conditions and measurement; distinguish source facts, chosen values and
|
||||
unknowns. Preserve the baseline and source provenance.
|
||||
2. Trace the relevant path from input to outcome. For example, if a control
|
||||
moves the wrong way, compare device input, commanded target and measured
|
||||
movement before tuning gains. If only an export fails, compare it against
|
||||
the working source at the first step where they differ. Skip stages the
|
||||
route does not use.
|
||||
3. State a possible cause, a check that distinguishes it from an alternative,
|
||||
the predicted result and what decision each outcome would support. Prefer
|
||||
a shared instrument when it measures the right quantity; otherwise inspect
|
||||
source data or design a bounded probe. No robot-specific helper is required.
|
||||
4. Change the smallest justified factor. Repeat the failed check under the
|
||||
same conditions and check previously working behavior affected by the edit.
|
||||
Tie results to the applicable artifacts and settings (hashes where available).
|
||||
Report the margin for borderline passes. Leave the cause open if the evidence
|
||||
does not distinguish it; do not relax a criterion after seeing the result.
|
||||
|
||||
## Required closeout for every new robot
|
||||
|
||||
Put one review in the robot's case report at completion or when blocked:
|
||||
|
||||
| Record | What to enter |
|
||||
|---|---|
|
||||
| Scope and evidence | Requested capability, source and missing inputs, applicable gate outcomes, artifacts, conditions and limits. |
|
||||
| Diagnosis | Symptom → measurement → cause or uncertainty → change → retest result, or the next distinguishing test. |
|
||||
| Skill decision | Name the owning skill. Add or correct the reusable decision there; if covered, identify the existing rule the case confirmed. Keep robot names, values, paths and experiments in the case report. |
|
||||
| Validation | Record what was checked. For a changed decision, try a different mechanism or missing-input case without relying on the original helper. Verify links and skill metadata. |
|
||||
|
||||
Review even if no candidate passed. This review does not authorize additional
|
||||
training, deployment or hardware operation.
|
||||
+2
-2
@@ -92,7 +92,7 @@ python scripts/play.py --task my_robot --checkpoint <model_N.pt> --headless \
|
||||
--evaluation-out evaluation.json
|
||||
```
|
||||
|
||||
报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。
|
||||
报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。仅当评测包含与无噪声回放的对比时,才额外使用干净观测回放进行比较。
|
||||
|
||||
## 导出到原生仿真
|
||||
|
||||
@@ -112,4 +112,4 @@ python scripts/onboard.py verify --model out/native_policy/robot.xml \
|
||||
|
||||
使用通过的报告及其对应导出文件构建原生应用。详见
|
||||
[控制器设置](CONTROLLER_SETUP.md#native-hybrid-policy-export)和
|
||||
[部署指南](../deploy/README.md)。
|
||||
[部署指南](../deploy/README.zh.md)。
|
||||
|
||||
+30
-8
@@ -77,9 +77,12 @@ and provenance fields written by the CLI.
|
||||
|
||||
The calibrated scaffold config names `robot_id`, `family`, `model_path`, and
|
||||
`action_scales` keyed by calibrated position-joint name. It can also name
|
||||
`controls_path`, `velocity_joints`, `penalized_contact_geoms`, and
|
||||
`controls_path`, `velocity_joints`, `foot_sites`, `penalized_contact_geoms`, and
|
||||
`termination_contact_geoms`. Model and controls paths resolve relative to the
|
||||
input JSON. The calibration must match the model XML and compiled dependencies.
|
||||
Optional `posture_stds` is an exact-name map covering every calibrated position
|
||||
joint with a positive finite value. Scaffolding writes these values into each
|
||||
joint's `posture_std` and consumes the top-level map; omitting it uses `0.35`.
|
||||
|
||||
Without `--calibration`, give a full `RobotSpec` from verified model facts.
|
||||
This example shows the file shape:
|
||||
@@ -110,14 +113,27 @@ for quadruped, and five for multipod. A wheeled biped also needs at least two
|
||||
named unlimited wheel hinges in `velocity_joints`, with `kp: 0`, positive
|
||||
`kd`, an effort limit, and a velocity action scale.
|
||||
|
||||
|
||||
Optional `posture_std` on each joint is its positive finite posture allowance
|
||||
in radians, defaulting to `0.35`. It supplies calibration data for the template's
|
||||
speed-dependent pose term, not a reward weight. Different joints can declare
|
||||
different allowances without adding robot-specific logic to the template.
|
||||
|
||||
Optional `foot_sites` lists one unique, nonempty, unqualified MuJoCo site name
|
||||
per named foot support, in the same order as `foot_geoms` or `foot_bodies`.
|
||||
These sites provide authored measurement locations for foot-clearance terms.
|
||||
The default empty list preserves existing specifications without sites. A
|
||||
nonempty list must match the support count; use actual sites in the robot model.
|
||||
Full `RobotSpec` input and literal scaffolding preserve both fields.
|
||||
|
||||
Scaffolding writes only `tasks/<robot_id>/robot_spec.py` in the task tree.
|
||||
The robot ID is the task ID. Family values are `biped`, `quadruped`,
|
||||
`wheeled_biped`, and `multipod`. The controls file for a locomotion policy
|
||||
uses the body-frame `twist` term feeding `velocity_commands`, with
|
||||
`lin_vel_x`, `lin_vel_y`, and `ang_vel_z` in that order. For operator input,
|
||||
generate the [bindings](CONTROLS.md#training-template-controls) before
|
||||
scaffolding and set `controls_path` in the input JSON. Choose
|
||||
`--profile differential` for a wheeled biped to use A/D for yaw.
|
||||
`lin_vel_x`, `lin_vel_y`, and `ang_vel_z` in that order. A new biped defaults to W/S for forward/reverse and A/D for left/right
|
||||
yaw. To supply a custom layout, set `controls_path` in the input JSON. See
|
||||
the [control profiles](CONTROLS.md#training-template-controls) for wheeled
|
||||
and omnidirectional layouts.
|
||||
|
||||
## Train and replay
|
||||
|
||||
@@ -141,6 +157,12 @@ and the environment count. A Warp buffer overflow stops the run before it
|
||||
uses the affected observations. For example, the G1 flat setup uses
|
||||
`--warp-max-constraints 300`.
|
||||
|
||||
EPA horizon overflow is a separate convex-collision scratch-buffer limit;
|
||||
increasing contact or constraint pools does not enlarge it. The checked Warp
|
||||
backend reserves at least 128 horizon entries before capturing simulation graphs
|
||||
(MuJoCo Warp 3.11 defaults to 24), preserves larger upstream buffers, and records
|
||||
the effective size. It still stops on every reported overflow.
|
||||
|
||||
A Warp run saves selected and effective capacities in `warp-allocation.json`
|
||||
beside its checkpoints. Warp resume, replay, and export read this file when
|
||||
present. Explicit flags take precedence. Otherwise, the larger of the saved
|
||||
@@ -197,9 +219,9 @@ The legacy target flags build the separate Rust bundle format.
|
||||
## Defaults
|
||||
|
||||
Precedence is command line, shell environment, `.env.local`, `.env`, then the
|
||||
argument default. A blank task means a task is required on task entry points.
|
||||
A blank model selects the robot's registered model. The committed defaults
|
||||
are:
|
||||
argument default. Copy `.env.example` to `.env` to set local defaults. A blank
|
||||
task means a task is required on task entry points. A blank model selects the
|
||||
robot's registered model. The effective defaults are:
|
||||
|
||||
```dotenv
|
||||
MJRL_TASK=
|
||||
|
||||
+49
-13
@@ -1,6 +1,6 @@
|
||||
# 命令手册
|
||||
|
||||
<!-- tracks: USAGE.md @ sha256:5d4ada2976459092 -->
|
||||
<!-- tracks: USAGE.md @ sha256:39a53b186c3a2171 -->
|
||||
|
||||
用 Python 3.10–3.13 建立环境并执行 `python -m pip install -e ".[dev]"`。
|
||||
平台配置见[环境准备](AGENT_SETUP.zh.md)。可编辑安装负责连接两个包根目录。
|
||||
@@ -69,24 +69,54 @@ extraction = extract_policy_metadata(
|
||||
### 机器人规格
|
||||
|
||||
使用标定时,配置提供 `robot_id`、`family`、`model_path` 和按位置关节名称
|
||||
索引的 `action_scales`。可选 `controls_path`、`velocity_joints`、
|
||||
索引的 `action_scales`。可选 `controls_path`、`velocity_joints`、`foot_sites`、
|
||||
`penalized_contact_geoms` 和 `termination_contact_geoms`。模型及控制路径
|
||||
相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。
|
||||
可选 `posture_stds` 须按名称精确覆盖所有标定的位置关节,每个值均为有限正数。
|
||||
生成规格时,数值写入各关节的 `posture_std`,顶层映射随之移除;省略时使用 `0.35`。
|
||||
|
||||
也可提供完整的已验证规格。完整字段包括 `base_body`、`base_height`、
|
||||
`foot_geoms` 或 `foot_bodies`,以及 `position_joints`。每个位置关节提供
|
||||
`name`、`kp`、`kd`、`effort_limit`、`action_scale`、`home`,
|
||||
可选 `armature`。站立根高度是 `base_height`,各关节默认位置是 `home`。
|
||||
支撑物体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
|
||||
多足至少五个。轮足双足还需至少两个不限位转动关节,设置 `kp: 0`、
|
||||
不传 `--calibration` 时,可根据已验证的模型参数提供完整 `RobotSpec`,格式示例如下:
|
||||
|
||||
```json
|
||||
{
|
||||
"robot_id": "sample_biped",
|
||||
"family": "biped",
|
||||
"model_path": "assets/sample_biped/robot.xml",
|
||||
"base_body": "base",
|
||||
"base_height": 0.32,
|
||||
"foot_geoms": ["left_foot", "right_foot"],
|
||||
"penalized_contact_geoms": ["left_shin", "right_shin"],
|
||||
"termination_contact_geoms": ["torso"],
|
||||
"position_joints": [
|
||||
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
|
||||
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
请使用针对该机器人标定的数值。站立根高度是 `base_height`,各关节默认位置是 `home`,
|
||||
可选 `armature` 为该关节的附加转动惯量。提供 `foot_geoms` 或 `foot_bodies`;
|
||||
每个支撑刚体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
|
||||
多足至少五个。轮足双足还需在 `velocity_joints` 中提供至少两个不限位转动关节,设置 `kp: 0`、
|
||||
正 `kd`、力矩上限和轮速动作尺度。
|
||||
|
||||
|
||||
每个关节可选 `posture_std`,表示以弧度为单位的姿态容许尺度,须为有限正数,默认
|
||||
`0.35`。它为模板中随速度变化的姿态项提供标定数据,不是奖励权重。各关节可设置
|
||||
不同尺度,无需在模板中加入特定机器人的判断逻辑。
|
||||
|
||||
可选 `foot_sites` 为每个命名足部支撑指定一个 MuJoCo site,顺序须与 `foot_geoms`
|
||||
或 `foot_bodies` 一致。名称须唯一、非空且不带实体路径前缀。这些 site 提供抬脚净空项
|
||||
的模型测量位置。默认空列表兼容不含 site 的现有规格;非空列表的长度须等于支撑数量,
|
||||
且应引用机器人模型中实际存在的 site。完整 `RobotSpec` 输入及生成的字面量规格都会
|
||||
保留这两个字段。
|
||||
|
||||
仅生成 `tasks/<robot_id>/robot_spec.py`,任务 ID 等于机器人 ID。
|
||||
形态取值为 `biped`、`quadruped`、`wheeled_biped`、`multipod`。
|
||||
运动策略的控制文件按顺序提供 `lin_vel_x`、`lin_vel_y`、`ang_vel_z`,
|
||||
由机体系 `twist` 命令送入 `velocity_commands`。若需要操作输入,在生成规格前先生成
|
||||
[操作绑定](CONTROLS.zh.md#训练模板),并在输入 JSON 中设置 `controls_path`。
|
||||
轮足双足应选择 `--profile differential`,让 A/D 控制转向。
|
||||
由机体系 `twist` 命令送入 `velocity_commands`。新接入的双足人形默认用 W/S 前进和后退,
|
||||
A/D 左转和右转。可在输入 JSON 的 `controls_path` 指定自定义布局。轮足与全向布局见
|
||||
[操作绑定](CONTROLS.zh.md#训练模板)。
|
||||
|
||||
## 训练与回放
|
||||
|
||||
@@ -106,6 +136,11 @@ Warp 的约束和接触容量可用正整数参数 `--warp-max-constraints N`
|
||||
总容量由每环境设置和环境数决定。缓冲区溢出时,程序会在使用受影响的观测前停止。
|
||||
例如,G1 平地任务使用 `--warp-max-constraints 300`。
|
||||
|
||||
EPA horizon 溢出属于凸体碰撞求解的独立临时缓冲区限制,增加接触或约束容量
|
||||
不会扩大这个缓冲区。平台的 Warp 后端在捕获仿真执行图前,至少分配 128 个
|
||||
horizon 条目(MuJoCo Warp 3.11 默认是 24),保留上游更大的容量,并记录
|
||||
实际大小。所有溢出仍会使运行停止。
|
||||
|
||||
Warp 训练会在检查点旁的 `warp-allocation.json` 中记录所选容量和实际容量。
|
||||
使用 Warp 续训、回放或导出时会读取该文件(如存在)。命令行参数优先,其次取已记录
|
||||
容量与任务或场景要求中的较大值。若没有运行记录且未配置容量,则由 Warp 自动分配。
|
||||
@@ -148,8 +183,9 @@ python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 1
|
||||
|
||||
## 默认值
|
||||
|
||||
优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。
|
||||
空任务要求显式指定,空模型选择已注册模型。
|
||||
优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。可将
|
||||
`.env.example` 复制为 `.env` 自定义本地默认值。空任务要求显式指定,空模型选择
|
||||
已注册模型。有效默认值为:
|
||||
|
||||
```dotenv
|
||||
MJRL_TASK=
|
||||
|
||||
+35
-2
@@ -4,6 +4,17 @@ The intake tier describes what the supplied inputs support. A robot can use a
|
||||
lower tier for visualization or deterministic control even if it also qualifies
|
||||
for policy adaptation or training.
|
||||
|
||||
For a humanoid, the default delivery goal is walking under operator control.
|
||||
Use a compatible walking policy when available or calibrate and train the
|
||||
biped. A standing or upper-body demonstration can verify an intermediate
|
||||
capability. Accept walking after measuring forward and reverse travel, left
|
||||
and right turns, stopping, and alternating support on the final policy.
|
||||
For an interactive arm, use a measured end-effector point and a draggable
|
||||
IK target. An explicit task request takes precedence over these defaults.
|
||||
|
||||
Use the [common diagnosis, verification and closeout procedure](ROBOT_ONBOARDING_LESSONS.md)
|
||||
throughout the selected route.
|
||||
|
||||
| Route | Required inputs | Verification and output |
|
||||
|---|---|---|
|
||||
| Tier 0 · Model viewing | Mesh, URDF, or MJCF and its dependencies | Compiled MJCF and viewer app |
|
||||
@@ -31,8 +42,10 @@ build) can recommend Tier 3 with `status: needs_profile` and
|
||||
Review the candidates, declare the profile and control intent, resolve the
|
||||
reported `prerequisites`, then calibrate. Missing URDF actuation/effort data
|
||||
remains an explicit prerequisite, not an inferred motor specification. An
|
||||
explicit profile takes precedence over automatic routing; policy adaptation
|
||||
retains its existing priority. No directory watcher or automatic training is
|
||||
explicit control intent takes precedence over the humanoid default. For the
|
||||
default walking route, check that the candidate policy accepts both signs of
|
||||
forward speed and yaw before choosing adaptation. A scene that includes a
|
||||
floor may need its robot-only model before calibration. No directory watcher or automatic training is
|
||||
started by inspection.
|
||||
|
||||
Select `--policy` and `--metadata` when the directory
|
||||
@@ -47,6 +60,26 @@ once the model, actor selection and metadata have passed intake checks.
|
||||
Resolve missing meshes and inertias, ambiguous model selection, incompatible
|
||||
actuator semantics, and unresolved metadata before building an application.
|
||||
|
||||
## Assets without weights or training configs
|
||||
|
||||
A robot description can provide geometry, contact pairs, servo parameters and
|
||||
keyframes without a learned controller. Select the scene wrapper explicitly
|
||||
when it supplies the floor and contact pairs. For a reviewable evidence-only
|
||||
extraction, run:
|
||||
|
||||
```bash
|
||||
python scripts/onboard.py extract-tier1 --model scene.xml --output out/model-draft
|
||||
```
|
||||
|
||||
This writes `metadata.json` and `manifest.json` and exits 1 because policy
|
||||
semantics remain unknown. The manifest's `model_evidence` includes the compiled
|
||||
model fingerprint, named joints, actuator parameters and keyframes; it never
|
||||
fills policy channel orders, scales, observation history or rate from these
|
||||
physical facts. Supply matching configs and an actor to resume Tier 1.
|
||||
Meanwhile, Tier 0 or a measured Tier 2 controller can produce an application.
|
||||
Synthetic actors are separate adapter test fixtures, never recovered weights
|
||||
or evidence of learned locomotion.
|
||||
|
||||
## Normalize the model
|
||||
|
||||
Use MJCF directly when it compiles and has the required geometry, frames,
|
||||
|
||||
+8
-7
@@ -60,6 +60,8 @@ dependencies = [
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = ["pytest", "ruff"]
|
||||
# BAM 1.0.2 requires Python 3.12; requesting this extra on other hosts fails explicitly.
|
||||
bam = ["better-actuator-models==1.0.2"]
|
||||
|
||||
[build-system]
|
||||
requires = ["setuptools>=64"]
|
||||
@@ -85,7 +87,7 @@ include = ["tasks*", "scenes*", "controller*", "mjrl*", "mjlab*", "rsl_rl*"]
|
||||
# never hit it, which is exactly what makes it easy to ship.
|
||||
[tool.setuptools.package-data]
|
||||
scenes = ["assets/*/*.png"]
|
||||
tasks = ["templates/**/*.json", "templates/**/AGENTS.md"]
|
||||
tasks = ["templates/**/AGENTS.md"]
|
||||
# The gamepad dictionary is data, read at run time by `controller.vocabulary`
|
||||
# and at compile time by `deploy/fsm`. Same reason as the scene textures: a
|
||||
# wheel with the module and not the file fails on first use, not on build.
|
||||
@@ -93,6 +95,7 @@ controller = ["vocabulary.json"]
|
||||
# Native app builders and validators use these trusted resources in wheels.
|
||||
# tests/test_app_schema.py checks them against the published files.
|
||||
"mjrl.platform" = ["app.schema", "LICENSE"]
|
||||
"mjrl.controllers" = ["walking.yaml"]
|
||||
|
||||
[tool.ruff]
|
||||
line-length = 100
|
||||
@@ -118,13 +121,11 @@ select = ["E4", "E7", "E9", "F"]
|
||||
# A notebook cell imports where it first needs a name, after the form fields
|
||||
# Colab reads off the top of the cell; ruff 0.16 lints notebooks by default.
|
||||
"notebooks/*.ipynb" = ["E402"]
|
||||
# One-off checks and asset tools are written dense -- several statements to a
|
||||
# line, an import where it is first needed -- on purpose: each is read once,
|
||||
# beside the measurement it produced. Only the layout is exempt; a dead import
|
||||
# or an empty f-string is still a finding there.
|
||||
# One-off checks are written dense -- several statements to a line, an import
|
||||
# where it is first needed -- on purpose: each is read once, beside the
|
||||
# measurement it produced. Only the layout is exempt; a dead import or an empty
|
||||
# f-string is still a finding there.
|
||||
"tools/checks/*" = ["E401", "E402", "E701", "E702"]
|
||||
"assets/*/tools/*" = ["E401", "E402", "E701", "E702"]
|
||||
"tasks/*/tools/*" = ["E701"]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
# Asset Zoo
|
||||
|
||||
| Robot | Image |
|
||||
|-------|-------|
|
||||
| **Unitree G1** | <img src="../../../docs/source/_static/content/g1.png" width="200" height="150" alt="Unitree G1 Humanoid"> |
|
||||
| **Unitree Go1** | <img src="../../../docs/source/_static/content/go1.png" width="200" height="150" alt="Unitree Go1 Quadruped"> |
|
||||
| **i2rt YAM** | <img src="../../../docs/source/_static/content/yam.png" width="200" height="150" alt="i2rt YAM Robot Arm"> |
|
||||
| Robot | Description |
|
||||
|-------|-------------|
|
||||
| **Unitree G1** | Unitree G1 Humanoid (`rl/mjlab/asset_zoo/robots/unitree_g1`) |
|
||||
| **Unitree Go1** | Unitree Go1 Quadruped (`rl/mjlab/asset_zoo/robots/unitree_go1`) |
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
# Terrains
|
||||
|
||||
Procedurally generate terrains using primitive geometries and heightfields.
|
||||
|
||||
<img src="../../../docs/source/_static/content/rough_terrain.png" alt="Rough Terrain">
|
||||
|
||||
+43
-12
@@ -20,7 +20,7 @@ import yaml
|
||||
|
||||
from controller.controls import controller_contract, load_controls
|
||||
|
||||
from .controllers.bindings import velocity_controls
|
||||
from .controllers.bindings import velocity_controls, walking_controls
|
||||
from .controllers.model import finite, joint_ids, vector
|
||||
from .platform.graph import TORCHSCRIPT_SUFFIXES, read_embedded_onnx
|
||||
from .platform.layout import COMMAND_ORDER, JOINT_TERMS, NATIVE_LAYOUT_SCHEMA, STANDARD_TERMS
|
||||
@@ -102,6 +102,7 @@ def _metadata(source: Mapping | Path) -> Mapping:
|
||||
"use_default_offset",
|
||||
"controller",
|
||||
"root_body",
|
||||
"motor_model",
|
||||
},
|
||||
"policy metadata",
|
||||
)
|
||||
@@ -396,6 +397,7 @@ def _observations(
|
||||
"normalization",
|
||||
"inputs",
|
||||
"command_order",
|
||||
"frames",
|
||||
},
|
||||
"observation",
|
||||
)
|
||||
@@ -473,6 +475,15 @@ def _observations(
|
||||
denominator = (std + epsilon).astype(np.float32)
|
||||
elif normalization not in ("baked_into_onnx", "none"):
|
||||
raise ValueError("Unknown observation.normalization")
|
||||
frames = _object(doc.get("frames", {}), "observation.frames")
|
||||
for name, frame in frames.items():
|
||||
if name not in {"base_ang_vel", "base_lin_vel", "projected_gravity"} or name not in terms:
|
||||
raise ValueError("Observation frames require a corresponding base vector term")
|
||||
frame = _object(frame, f"observation.frames.{name}")
|
||||
if set(frame) != {"kind", "name"} or frame["kind"] not in {"body", "site"}:
|
||||
raise ValueError("Observation frames must name a body or site")
|
||||
if not isinstance(frame["name"], str) or not frame["name"]:
|
||||
raise ValueError("Observation frame name must be nonempty")
|
||||
inputs = []
|
||||
if "inputs" in doc:
|
||||
for item in doc["inputs"]:
|
||||
@@ -512,6 +523,7 @@ def _observations(
|
||||
"history_order": "oldest_first",
|
||||
"normalization": "baked_into_onnx",
|
||||
"command_order": command_order,
|
||||
**({"frames": dict(frames)} if frames else {}),
|
||||
}, transform
|
||||
|
||||
|
||||
@@ -570,7 +582,9 @@ def _prepare(metadata: Mapping | Path, model=None) -> tuple[dict, _Transform]:
|
||||
raise ValueError(f"{term['name']}.joint_order must be a subset of obs_joint_order")
|
||||
names = {term["name"] for term in terms}
|
||||
native = (
|
||||
"targets" in doc.get("action", {})
|
||||
"motor_model" in doc
|
||||
or bool(observation.get("frames"))
|
||||
or "targets" in doc.get("action", {})
|
||||
or bool(passive)
|
||||
or any(default_vel.values())
|
||||
or any(isinstance(gain, dict) for gain in control.values())
|
||||
@@ -619,6 +633,18 @@ def _prepare(metadata: Mapping | Path, model=None) -> tuple[dict, _Transform]:
|
||||
if not lo <= 0 <= hi:
|
||||
raise ValueError(f"command_ranges.twist.{axis} must contain zero")
|
||||
layout["command_ranges"]["twist"][axis] = [float(lo), float(hi)]
|
||||
if "motor_model" in doc:
|
||||
from .platform.motors import validate_motor_model
|
||||
|
||||
if velocity:
|
||||
raise ValueError("BAM motor model requires position targets")
|
||||
layout["motor_model"] = validate_motor_model(doc["motor_model"])
|
||||
if model is not None:
|
||||
for frame in observation.get("frames", {}).values():
|
||||
kind = mujoco.mjtObj.mjOBJ_SITE if frame["kind"] == "site" else mujoco.mjtObj.mjOBJ_BODY
|
||||
index = mujoco.mj_name2id(model, kind, frame["name"])
|
||||
if index < 0 or (frame["kind"] == "body" and index == 0):
|
||||
raise ValueError(f"Model has no observation frame {frame['name']!r}")
|
||||
if "controller" in doc:
|
||||
layout["controller"] = dict(_object(doc["controller"], "controller"))
|
||||
return layout, transform
|
||||
@@ -886,17 +912,22 @@ def adapt_policy(
|
||||
layout["_adapter_validation"] = {"max_abs_error": error, "probes": 10}
|
||||
if active_axes:
|
||||
tmp_controls = temporary / controls_path.name
|
||||
tmp_controls.write_text(
|
||||
yaml.safe_dump(velocity_controls(active_axes), sort_keys=False), "utf-8"
|
||||
)
|
||||
generated = controller_contract(load_controls(tmp_controls), None)
|
||||
supplied = layout.get("controller", generated)
|
||||
if any(
|
||||
supplied.get(key) != generated[key]
|
||||
for key in ("schema", "command", "task", "devices")
|
||||
):
|
||||
supplied = layout.get("controller")
|
||||
# Prefer the walking layout for new exports. Existing actor metadata
|
||||
# may explicitly contract the earlier, equally valid velocity keys.
|
||||
for make_controls in (walking_controls, velocity_controls):
|
||||
tmp_controls.write_text(
|
||||
yaml.safe_dump(make_controls(active_axes), sort_keys=False), "utf-8"
|
||||
)
|
||||
generated = controller_contract(load_controls(tmp_controls), None)
|
||||
if supplied is None or all(
|
||||
supplied.get(key) == generated[key]
|
||||
for key in ("schema", "command", "task", "devices")
|
||||
):
|
||||
layout["controller"] = generated
|
||||
break
|
||||
else:
|
||||
raise ValueError("Supplied controller metadata differs from generated controls")
|
||||
layout["controller"] = generated
|
||||
for path, value in ((layout_path, layout), (config_path, config)):
|
||||
(temporary / path.name).write_text(
|
||||
json.dumps(value, indent=2, allow_nan=False) + "\n", "utf-8"
|
||||
|
||||
+1
-1
@@ -50,7 +50,7 @@ from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from mjrl.viewer.keys import ViewerKeys as ViewerKeys
|
||||
from mjrl.viewer.keys import ViewerKeys
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
|
||||
@@ -232,8 +232,17 @@ class _NativeData:
|
||||
|
||||
def __init__(self, buffers: dict[str, np.ndarray], num_envs: int) -> None:
|
||||
object.__setattr__(self, "_np", buffers)
|
||||
tensors = {k: torch.from_numpy(v) for k, v in buffers.items()}
|
||||
# mjwarp exposes mat33 fields with two trailing matrix dimensions.
|
||||
# Keep MuJoCo's flat NumPy buffers for gather/scatter, but give entity
|
||||
# pose readers the same matrix layout as Warp. Reshape shares memory:
|
||||
# future native forward calls still update already-held tensor views.
|
||||
for name in ("xmat", "site_xmat", "geom_xmat"):
|
||||
if name in tensors:
|
||||
value = tensors[name]
|
||||
tensors[name] = value.reshape(*value.shape[:-1], 3, 3)
|
||||
object.__setattr__(
|
||||
self, "_t", {k: torch.from_numpy(v) for k, v in buffers.items()}
|
||||
self, "_t", tensors
|
||||
)
|
||||
# mjwarp's Data has nworld (the world count) and mjlab's entity, sensor
|
||||
# and offscreen_renderer all read it. Native MjData has no such concept, so
|
||||
@@ -950,7 +959,7 @@ class NativeSimulation:
|
||||
|
||||
**Putting each environment's control and warm start back costs** one
|
||||
`mj_setState` and two small copies per environment, under the GIL. Measured
|
||||
on the i9-14900KF (2026-09-26), example_robot.tripod on 8 threads, medians of 5
|
||||
on the i9-14900KF (2026-09-26), a 6-legged locomotion task on 8 threads, medians of 5
|
||||
runs interleaved with the code before it, before -> after:
|
||||
|
||||
| envs | `sim.step` ms | `env.step` ms | this function ms |
|
||||
|
||||
@@ -67,4 +67,6 @@ def write_warp_allocation(run_dir: Path, sim) -> None:
|
||||
"allocation": {field: getattr(sim.cfg, field) for field, _ in _FLAGS},
|
||||
"effective": {"njmax": data.njmax, "naconmax": data.naconmax, "nworld": data.nworld},
|
||||
}
|
||||
if hasattr(sim, "epa_horizon_capacity"):
|
||||
record["effective"]["epa_horizon"] = sim.epa_horizon_capacity
|
||||
(run_dir / FILENAME).write_text(json.dumps(record, indent=2) + "\n")
|
||||
|
||||
@@ -7,6 +7,31 @@ from mjlab.sim import Simulation
|
||||
from mujoco_warp._src.types import OverflowType
|
||||
|
||||
|
||||
# EPA stores its temporary horizon per convex pair, independently of the
|
||||
# contact/constraint pools. MuJoCo Warp 3.11's 24 entries can exhaust during
|
||||
# otherwise valid deep mesh contacts. The kernels bound writes by array shape.
|
||||
EPA_HORIZON_CAPACITY = 128
|
||||
|
||||
|
||||
def _ensure_epa_horizon_capacity() -> int:
|
||||
"""Raise host scratch allocation before initialization and graph capture.
|
||||
|
||||
These module globals size host allocations, not Warp compile-time constants.
|
||||
Leave installed files and collision algorithms untouched, and never reduce a
|
||||
newer upstream capacity. Apply to rigid and flexible collision paths alike.
|
||||
"""
|
||||
from mujoco_warp._src import collision_convex, collision_flex
|
||||
|
||||
modules = (collision_convex, collision_flex)
|
||||
capacities = [getattr(module, "MJ_MAX_EPAHORIZON", None) for module in modules]
|
||||
if any(type(value) is not int or value <= 0 for value in capacities):
|
||||
raise RuntimeError("Unsupported MuJoCo Warp EPA scratch allocator; update the platform compatibility shim.")
|
||||
capacity = max(EPA_HORIZON_CAPACITY, *capacities)
|
||||
for module in modules:
|
||||
module.MJ_MAX_EPAHORIZON = capacity
|
||||
return capacity
|
||||
|
||||
|
||||
@wp.kernel(enable_backward=False)
|
||||
def _collect_overflow(
|
||||
flags: wp.array(dtype=int),
|
||||
@@ -32,6 +57,7 @@ class CheckedWarpSimulation(Simulation):
|
||||
"""Preserve sticky flags across resets and check once per observation."""
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
self.epa_horizon_capacity = _ensure_epa_horizon_capacity()
|
||||
super().__init__(*args, **kwargs)
|
||||
self._overflow_report = wp.zeros(3, dtype=int, device=self.wp_device)
|
||||
|
||||
@@ -58,10 +84,20 @@ class CheckedWarpSimulation(Simulation):
|
||||
if flags or constraints or contacts:
|
||||
data = self.wp_data
|
||||
kinds = OverflowType(flags).name if flags else "capacity counters"
|
||||
advice = []
|
||||
if flags & OverflowType.EPA_HORIZON:
|
||||
advice.append(
|
||||
f"EPA horizon scratch capacity: {self.epa_horizon_capacity} entries per convex pair. "
|
||||
"This is independent of contact and constraint pools; increase the platform EPA horizon "
|
||||
"capacity before graph capture and replay the failing collision."
|
||||
)
|
||||
if constraints or flags & (OverflowType.NEFC | OverflowType.NJMAX_NNZ):
|
||||
advice.append("For constraint overflow increase --warp-max-constraints.")
|
||||
if contacts or flags & (OverflowType.BROADPHASE | OverflowType.NARROWPHASE):
|
||||
advice.append("For broadphase or narrowphase overflow increase --warp-max-contacts.")
|
||||
raise RuntimeError(
|
||||
f"Warp buffer overflow ({kinds}). "
|
||||
f"Constraint capacity per world: {data.njmax}, demand above capacity: {constraints}. "
|
||||
f"Shared contact capacity: {data.naconmax}, demand above capacity: {contacts}. "
|
||||
"For constraint overflow increase --warp-max-constraints. "
|
||||
"For broadphase or narrowphase overflow increase --warp-max-contacts."
|
||||
+ " ".join(advice)
|
||||
)
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
"""Generate operator documents for named native command axes."""
|
||||
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
WALKING_CONTROLS = Path(__file__).with_name("walking.yaml")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -20,6 +25,17 @@ _VELOCITY = {
|
||||
}
|
||||
|
||||
|
||||
def walking_controls(axes) -> dict:
|
||||
"""Bind exactly the body-velocity axes the policy can observe."""
|
||||
layout = yaml.safe_load(WALKING_CONTROLS.read_text(encoding="utf-8"))
|
||||
term = layout["command"][0]
|
||||
by_name = {axis["name"]: axis for axis in term["axes"]}
|
||||
term["axes"] = [by_name[name] for name in axes]
|
||||
for device in layout["devices"].values():
|
||||
device["axes"] = {name: device["axes"][name] for name in axes}
|
||||
return layout
|
||||
|
||||
|
||||
def velocity_controls(axes, *, differential: bool = False) -> dict:
|
||||
bindings = {axis: _VELOCITY[axis] for axis in axes}
|
||||
if differential and "ang_vel_z" in bindings:
|
||||
|
||||
+118
-10
@@ -2,6 +2,7 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass
|
||||
from numbers import Real
|
||||
|
||||
@@ -34,8 +35,10 @@ def joint_ids(model: mujoco.MjModel, names: list[str]) -> np.ndarray:
|
||||
|
||||
|
||||
def joint_actuators(model: mujoco.MjModel, ids: np.ndarray) -> list[np.ndarray]:
|
||||
# Both joint transmissions have the same length law for hinges and slides.
|
||||
direct = np.isin(model.actuator_trntype, [_JOINT, mujoco.mjtTrn.mjTRN_JOINTINPARENT])
|
||||
return [
|
||||
np.flatnonzero((model.actuator_trntype == _JOINT) & (model.actuator_trnid[:, 0] == joint))
|
||||
np.flatnonzero(direct & (model.actuator_trnid[:, 0] == joint))
|
||||
for joint in ids
|
||||
]
|
||||
|
||||
@@ -54,6 +57,60 @@ def vector(value, size: int, field: str) -> np.ndarray:
|
||||
return np.array([finite(v, field) for v in value], dtype=np.float64)
|
||||
|
||||
|
||||
def joint_values(value, names, field: str, *, positive=False, nonnegative=False) -> np.ndarray:
|
||||
"""Expand a scalar or exact named map in controller joint order."""
|
||||
if not isinstance(names, (list, tuple)) or not names or not all(
|
||||
isinstance(name, str) and name for name in names
|
||||
) or len(set(names)) != len(names):
|
||||
raise ValueError("joints must be a nonempty list of unique names")
|
||||
if isinstance(value, Mapping):
|
||||
if set(value) != set(names):
|
||||
raise ValueError(f"{field} must cover controlled joints exactly")
|
||||
values = [finite(value[name], f"{field}.{name}", positive=positive) for name in names]
|
||||
else:
|
||||
values = [finite(value, field, positive=positive)] * len(names)
|
||||
values = np.asarray(values, dtype=np.float64)
|
||||
if nonnegative and np.any(values < 0):
|
||||
raise ValueError(f"{field} must be nonnegative")
|
||||
return values
|
||||
|
||||
|
||||
def joint_effort_bounds(model, ids, effort) -> np.ndarray:
|
||||
"""Intersect requested joint effort with authored actuator and joint bounds.
|
||||
|
||||
MuJoCo actuator force is before gear transmission; normalize it to joint
|
||||
effort before replacing an actuator with a unit-gear servo.
|
||||
"""
|
||||
bounds = np.column_stack((-effort, effort))
|
||||
for i, (joint, actuators) in enumerate(zip(ids, joint_actuators(model, ids), strict=True)):
|
||||
if len(actuators) > 1:
|
||||
raise ValueError("A controlled joint has multiple actuators")
|
||||
if len(actuators):
|
||||
aid = int(actuators[0])
|
||||
gear = model.actuator_gear[aid]
|
||||
if not np.isfinite(gear).all() or gear[0] == 0 or np.any(gear[1:] != 0):
|
||||
raise ValueError("Cannot normalize a non-scalar or zero actuator gear")
|
||||
if model.actuator_forcelimited[aid]:
|
||||
low, high = np.sort(model.actuator_forcerange[aid] * gear[0])
|
||||
bounds[i] = [max(bounds[i, 0], low), min(bounds[i, 1], high)]
|
||||
# A motor's input is effort, whereas a position/velocity servo's
|
||||
# ctrlrange is a target range and must never be treated as force.
|
||||
if (model.actuator_ctrllimited[aid]
|
||||
and model.actuator_dyntype[aid] == mujoco.mjtDyn.mjDYN_NONE
|
||||
and model.actuator_gaintype[aid] == mujoco.mjtGain.mjGAIN_FIXED
|
||||
and model.actuator_biastype[aid] == mujoco.mjtBias.mjBIAS_NONE):
|
||||
low, high = np.sort(
|
||||
model.actuator_ctrlrange[aid] * model.actuator_gainprm[aid, 0] * gear[0]
|
||||
)
|
||||
bounds[i] = [max(bounds[i, 0], low), min(bounds[i, 1], high)]
|
||||
if model.jnt_actfrclimited[joint]:
|
||||
low, high = model.jnt_actfrcrange[joint]
|
||||
bounds[i] = [max(bounds[i, 0], low), min(bounds[i, 1], high)]
|
||||
if not bounds[i, 0] < 0 < bounds[i, 1]:
|
||||
raise ValueError("Controlled joint effort must permit both directions")
|
||||
return bounds
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class JointControl:
|
||||
names: tuple[str, ...]
|
||||
@@ -115,19 +172,70 @@ class JointControl:
|
||||
return cls(tuple(names), ctrl, model.jnt_qposadr[ids], model.jnt_dofadr[ids], lo, hi)
|
||||
|
||||
|
||||
def _position_limits(model, joint, actuators):
|
||||
"""Return unit-gear joint targets, respecting the source servo's length units."""
|
||||
limits = model.jnt_range[joint] if model.jnt_limited[joint] else None
|
||||
if not len(actuators):
|
||||
return limits
|
||||
aid = actuators[0]
|
||||
if not (model.actuator_ctrllimited[aid] or model.actuator_actlimited[aid]):
|
||||
return limits
|
||||
|
||||
bias_type = model.actuator_biastype[aid]
|
||||
bias = model.actuator_biasprm[aid]
|
||||
# Motors and velocity servos do not take position targets.
|
||||
if bias_type == mujoco.mjtBias.mjBIAS_NONE or (
|
||||
bias_type == mujoco.mjtBias.mjBIAS_AFFINE and bias[1] == 0
|
||||
):
|
||||
return limits
|
||||
|
||||
name = model.joint(joint).name
|
||||
gain = model.actuator_gainprm[aid, 0]
|
||||
if not (
|
||||
model.actuator_gaintype[aid] == mujoco.mjtGain.mjGAIN_FIXED
|
||||
and bias_type == mujoco.mjtBias.mjBIAS_AFFINE
|
||||
and gain > 0 and bias[0] == 0 and bias[1] == -gain and bias[2] <= 0
|
||||
and model.actuator_dyntype[aid] in (
|
||||
mujoco.mjtDyn.mjDYN_NONE, mujoco.mjtDyn.mjDYN_FILTER, mujoco.mjtDyn.mjDYN_FILTEREXACT,
|
||||
)
|
||||
and not model.actuator_actlimited[aid]
|
||||
):
|
||||
raise ValueError(
|
||||
f"Cannot infer position target bounds for joint {name!r} "
|
||||
"from its actuator law or activation limits"
|
||||
)
|
||||
|
||||
# For a scalar joint the actuator length is gear * qpos. Sorting handles
|
||||
# a reversed transmission, and works for both hinge and slide coordinates.
|
||||
source = np.sort(model.actuator_ctrlrange[aid] / model.actuator_gear[aid, 0])
|
||||
if not np.isfinite(source).all():
|
||||
raise ValueError(f"Nonfinite position target bounds for joint {name!r}")
|
||||
if limits is not None:
|
||||
source = [max(limits[0], source[0]), min(limits[1], source[1])]
|
||||
if source[0] >= source[1]:
|
||||
raise ValueError(f"Actuator and joint position ranges do not overlap for {name!r}")
|
||||
return source
|
||||
|
||||
|
||||
def normalize_actuators(
|
||||
spec: mujoco.MjSpec,
|
||||
model: mujoco.MjModel,
|
||||
names: list[str],
|
||||
kind: str,
|
||||
*,
|
||||
kp: float,
|
||||
kd: float,
|
||||
effort: float,
|
||||
kp: float | Mapping[str, float],
|
||||
kd: float | Mapping[str, float],
|
||||
effort: float | Mapping[str, float],
|
||||
speed: float,
|
||||
) -> None:
|
||||
ids = joint_ids(model, names)
|
||||
for joint, name, existing in zip(ids, names, joint_actuators(model, ids), strict=True):
|
||||
gains = joint_values(kp, names, "kp", positive=kind == "position", nonnegative=True)
|
||||
damping = joint_values(kd, names, "kd", positive=kind == "velocity", nonnegative=True)
|
||||
efforts = joint_values(effort, names, "effort_limit", positive=True)
|
||||
bounds = joint_effort_bounds(model, ids, efforts)
|
||||
for index, (joint, name, existing) in enumerate(
|
||||
zip(ids, names, joint_actuators(model, ids), strict=True)
|
||||
):
|
||||
if len(existing) > 1:
|
||||
raise ValueError(f"Joint {name!r} has multiple actuators")
|
||||
if len(existing):
|
||||
@@ -140,14 +248,14 @@ def normalize_actuators(
|
||||
actuator.delay = 0
|
||||
if kind == "motor":
|
||||
actuator.set_to_motor()
|
||||
limits = [-effort, effort]
|
||||
limits = bounds[index]
|
||||
elif kind == "velocity":
|
||||
actuator.set_to_velocity(kd)
|
||||
actuator.set_to_velocity(damping[index])
|
||||
limits = [-speed, speed]
|
||||
else:
|
||||
actuator.set_to_position(kp, kv=kd)
|
||||
limits = model.jnt_range[joint] if model.jnt_limited[joint] else None
|
||||
actuator.set_to_position(gains[index], kv=damping[index], timeconst=0)
|
||||
limits = _position_limits(model, joint, existing)
|
||||
actuator.ctrllimited = int(limits is not None)
|
||||
actuator.ctrlrange = limits if limits is not None else [0, 0]
|
||||
actuator.forcelimited = 1
|
||||
actuator.forcerange = [-effort, effort]
|
||||
actuator.forcerange = bounds[index]
|
||||
|
||||
@@ -12,7 +12,7 @@ import numpy as np
|
||||
from controller.controls import Controls, load_controls
|
||||
|
||||
from .input import OperatorInput
|
||||
from .model import JointControl, finite, object_id, vector
|
||||
from .model import JointControl, finite, joint_effort_bounds, joint_values, object_id, vector
|
||||
from .motion import DampedLeastSquaresIK, Trajectory
|
||||
from .wheels import WHEEL_AXES, mix_velocity, wheel_mixer
|
||||
|
||||
@@ -52,6 +52,9 @@ class Controller:
|
||||
raise ValueError("control_hz must correspond to a whole number of physics steps")
|
||||
self.command_axes: tuple[str, ...]
|
||||
self.joints: JointControl | None = None
|
||||
self._target_rates: np.ndarray | None = None
|
||||
if "target_rate_limits" in config and self.kind != "joint_sliders":
|
||||
raise ValueError("target_rate_limits requires joint_sliders")
|
||||
self.controls: Controls | None = None
|
||||
self.operator: OperatorInput | None = None
|
||||
|
||||
@@ -128,6 +131,9 @@ class Controller:
|
||||
assert joints is not None
|
||||
if self.kind == "ik":
|
||||
self.ik = DampedLeastSquaresIK(self.model, joints, config)
|
||||
self._start_at_site = config.get("start_target_at_site", False)
|
||||
if type(self._start_at_site) is not bool:
|
||||
raise ValueError("start_target_at_site must be boolean")
|
||||
self.command_axes = IK_AXES
|
||||
self._spans = [(-np.inf, np.inf, 0)] * 3
|
||||
self._origin = self.model.body_pos[
|
||||
@@ -136,6 +142,20 @@ class Controller:
|
||||
elif self.kind == "joint_sliders":
|
||||
self.command_axes = joints.names
|
||||
self._home = np.clip(self.model.qpos0[joints.pos], joints.lo, joints.hi)
|
||||
if "home" in config:
|
||||
if not isinstance(config["home"], Mapping):
|
||||
raise ValueError("home must map every controlled joint by name")
|
||||
self._home = joint_values(config["home"], joints.names, "home")
|
||||
if np.any(self._home < joints.lo) or np.any(self._home > joints.hi):
|
||||
raise ValueError("home lies outside a controlled joint's position limits")
|
||||
rates = config.get("target_rate_limits", {})
|
||||
if not isinstance(rates, Mapping) or set(rates) - set(joints.names):
|
||||
raise ValueError("target_rate_limits must map controlled joint names to rates")
|
||||
if rates:
|
||||
self._target_rates = np.array([
|
||||
finite(rates[name], f"target_rate_limits.{name}", positive=True)
|
||||
if name in rates else np.inf for name in joints.names
|
||||
])
|
||||
self._spans = list(zip(joints.lo, joints.hi, self._home, strict=True))
|
||||
elif self.kind == "trajectory":
|
||||
trajectory = config.get("trajectory")
|
||||
@@ -168,11 +188,12 @@ class Controller:
|
||||
self._centre + self._amplitude > joints.hi
|
||||
):
|
||||
raise ValueError("CPG excursion lies outside a joint's position limits")
|
||||
self._kp = finite(config.get("kp", 40), "kp", positive=True)
|
||||
self._kd = finite(config.get("kd", 4), "kd")
|
||||
if self._kd < 0:
|
||||
raise ValueError("kd must be nonnegative")
|
||||
self._effort = finite(config.get("effort_limit", 30), "effort_limit", positive=True)
|
||||
self._kp = joint_values(config.get("kp", 40), joints.names, "kp", positive=True)
|
||||
self._kd = joint_values(config.get("kd", 4), joints.names, "kd", nonnegative=True)
|
||||
requested = joint_values(config.get("effort_limit", 30), joints.names, "effort_limit", positive=True)
|
||||
ids = self.model.dof_jntid[joints.vel]
|
||||
bounds = joint_effort_bounds(self.model, ids, requested)
|
||||
self._effort = np.minimum(-bounds[:, 0], bounds[:, 1])
|
||||
self.command_axes = ("amplitude_scale",)
|
||||
self._spans = [(0, 1, 1)]
|
||||
|
||||
@@ -188,11 +209,21 @@ class Controller:
|
||||
self._time = float(data.time)
|
||||
self._motion_time = 0.0
|
||||
if self.kind == "ik":
|
||||
self._origin = data.mocap_pos[self.ik.mocap].copy()
|
||||
target = data.mocap_pos[self.ik.mocap]
|
||||
if self._start_at_site:
|
||||
mujoco.mj_kinematics(self.model, data)
|
||||
target[:] = data.site_xpos[self.ik.site]
|
||||
self._origin = target.copy()
|
||||
spans = np.array([self.command_spans[axis][:2] for axis in IK_AXES])
|
||||
self._target_low = self._origin + spans[:, 0]
|
||||
self._target_high = self._origin + spans[:, 1]
|
||||
elif self.kind == "joint_sliders":
|
||||
data.ctrl[self.ctrl_ids] = np.clip(
|
||||
data.qpos[self.joints.pos], self.joints.lo, self.joints.hi
|
||||
)
|
||||
if self._target_rates is not None:
|
||||
self._applied = data.ctrl[self.ctrl_ids].copy()
|
||||
self._requested = self._applied.copy()
|
||||
if self.operator is not None:
|
||||
self.operator.reset()
|
||||
|
||||
@@ -230,7 +261,13 @@ class Controller:
|
||||
if self.kind in {"direct", "joint_sliders"}:
|
||||
# The passive viewer's Control panel writes data.ctrl. Keep its
|
||||
# slider values when there is no new keyboard, pad, or API target.
|
||||
previous = dict(zip(self.command_axes, data.ctrl[self.ctrl_ids], strict=True))
|
||||
previous_targets = data.ctrl[self.ctrl_ids]
|
||||
if self._target_rates is not None:
|
||||
# Viewer edits replace the pending goal only on the axes it changed.
|
||||
previous_targets = np.where(
|
||||
previous_targets != self._applied, previous_targets, self._requested
|
||||
)
|
||||
previous = dict(zip(self.command_axes, previous_targets, strict=True))
|
||||
if use_operator and self.operator.releasing:
|
||||
command = {
|
||||
name: self.command_spans[name][2] for name in self.operator.controls.bindings
|
||||
@@ -249,7 +286,10 @@ class Controller:
|
||||
use_operator and (np.any(values) or self.operator.releasing)
|
||||
):
|
||||
data.mocap_pos[self.ik.mocap] = self._origin + values
|
||||
output = self.ik.solve(data, data.mocap_pos[self.ik.mocap])
|
||||
target = data.mocap_pos[self.ik.mocap]
|
||||
# Native viewer drags write directly to mocap_pos, in world metres.
|
||||
np.clip(target, self._target_low, self._target_high, out=target)
|
||||
output = self.ik.solve(data, target)
|
||||
elif self.kind == "trajectory":
|
||||
self._motion_time += dt * values[0]
|
||||
t = self._motion_time
|
||||
@@ -266,6 +306,15 @@ class Controller:
|
||||
effort = self._kp * (target - data.qpos[joints.pos])
|
||||
effort += self._kd * (rate - data.qvel[joints.vel])
|
||||
output = np.clip(effort, -self._effort, self._effort)
|
||||
elif self._target_rates is not None:
|
||||
self._requested = values
|
||||
limited = np.isfinite(self._target_rates)
|
||||
delta = self._target_rates[limited] * dt
|
||||
output = values.copy()
|
||||
output[limited] = np.clip(
|
||||
values[limited], self._applied[limited] - delta, self._applied[limited] + delta
|
||||
)
|
||||
self._applied = output.copy()
|
||||
else:
|
||||
output = values
|
||||
data.ctrl[self.ctrl_ids] = output
|
||||
|
||||
@@ -18,7 +18,7 @@ from mjrl.onboarding._xml import checked_mjcf
|
||||
from mjrl.onboarding.build import write_mjcf
|
||||
|
||||
from .bindings import AxisBinding, controls_document, velocity_controls
|
||||
from .model import finite, normalize_actuators, object_id, vector
|
||||
from .model import finite, joint_values, normalize_actuators, object_id, vector
|
||||
from .runtime import WHEEL_KINDS, Controller, read_config
|
||||
from .wheels import wheel_mixer
|
||||
|
||||
@@ -30,12 +30,12 @@ class ControllerSetup:
|
||||
controls: Path | None
|
||||
|
||||
|
||||
def _gains(config: Mapping) -> tuple[float, float, float]:
|
||||
kp = finite(config.get("kp", 40), "kp", positive=True)
|
||||
kd = finite(config.get("kd", 4), "kd")
|
||||
if kd < 0:
|
||||
raise ValueError("kd must be nonnegative")
|
||||
effort = finite(config.get("effort_limit", 30), "effort_limit", positive=True)
|
||||
def _gains(config: Mapping) -> tuple:
|
||||
names = config.get("joints")
|
||||
kp, kd, effort = config.get("kp", 40), config.get("kd", 4), config.get("effort_limit", 30)
|
||||
joint_values(kp, names, "kp", positive=True)
|
||||
joint_values(kd, names, "kd", nonnegative=True)
|
||||
joint_values(effort, names, "effort_limit", positive=True)
|
||||
return kp, kd, effort
|
||||
|
||||
|
||||
@@ -64,6 +64,7 @@ def _prepare_ik(spec: mujoco.MjSpec, model: mujoco.MjModel, config: dict) -> Non
|
||||
body.add_site(name=site, pos=offset, size=[0.012, 0, 0], rgba=[0.1, 0.8, 1, 1])
|
||||
mocap = config.setdefault("mocap_body", "mjrl_target")
|
||||
if spec.body(mocap) is None:
|
||||
config.setdefault("start_target_at_site", True)
|
||||
model = _compile_with_named_links(spec)
|
||||
data = mujoco.MjData(model)
|
||||
mujoco.mj_kinematics(model, data)
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
schema_version: 2
|
||||
command:
|
||||
- term: twist
|
||||
feeds: velocity_commands
|
||||
frame: body
|
||||
axes:
|
||||
- {name: lin_vel_x, unit: m/s, positive: forward}
|
||||
- {name: lin_vel_y, unit: m/s, positive: left}
|
||||
- {name: ang_vel_z, unit: rad/s, positive: counter-clockwise}
|
||||
scaling: {rule: full_deflection_is_range_edge}
|
||||
devices:
|
||||
gamepad:
|
||||
scheme: absolute
|
||||
layout: xbox
|
||||
deadzone: device_reported_rescaled
|
||||
release_button: B
|
||||
axes:
|
||||
lin_vel_x: {source: Ly, sign: -1}
|
||||
lin_vel_y: {source: Lx, sign: -1}
|
||||
ang_vel_z: {source: Rx, sign: -1}
|
||||
keyboard:
|
||||
scheme: keys
|
||||
full_after_s: 2.0
|
||||
release: [key_escape]
|
||||
axes:
|
||||
lin_vel_x: {"+": [key_w, key_up], "-": [key_s, key_down]}
|
||||
lin_vel_y: {"+": [key_j], "-": [key_l]}
|
||||
ang_vel_z: {"+": [key_a, key_left], "-": [key_d, key_right]}
|
||||
@@ -12,6 +12,8 @@ import numpy as np
|
||||
from mjlab.utils.spec import non_default_option_fields
|
||||
from mjlab.utils.xml import fix_spec_xml, strip_buffer_textures
|
||||
|
||||
from .platform._serialization import spec_xml
|
||||
|
||||
|
||||
def _asset_bytes(spec: mujoco.MjSpec, filename: str, tag: str) -> bytes:
|
||||
directory = Path(spec.texturedir if tag == "texture" else spec.meshdir)
|
||||
@@ -60,7 +62,7 @@ def write_native_model(env, output: Path, layout: dict) -> None:
|
||||
setattr(spec.option, field, getattr(live.opt, field))
|
||||
strip_buffer_textures(spec)
|
||||
spec.compile()
|
||||
xml = ET.fromstring(fix_spec_xml(spec.to_xml()))
|
||||
xml = ET.fromstring(fix_spec_xml(spec_xml(spec)))
|
||||
sources = {name: entity.spec for name, entity in env.scene.entities.items()}
|
||||
_localize_assets(xml, spec, sources, output)
|
||||
ET.indent(xml, space=" ")
|
||||
@@ -87,7 +89,8 @@ def write_native_model(env, output: Path, layout: dict) -> None:
|
||||
"geom_quat",
|
||||
"actuator_forcerange",
|
||||
):
|
||||
# MjSpec's MJCF writer uses six significant digits.
|
||||
# Preserve the existing contract checks even if high precision native
|
||||
# serialization is unavailable. Lossy or reordered models must fail.
|
||||
if not np.allclose(getattr(model, name), getattr(live, name), rtol=5e-6, atol=1e-9):
|
||||
raise ValueError(f"Native model export changed {name}")
|
||||
if not np.isclose(model.opt.timestep, layout["control"]["sim_dt"], rtol=0, atol=1e-12):
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
"""Discover project inputs without scanning installed dependencies and caches."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
_IGNORED_DIRECTORIES = {
|
||||
".git", ".hg", ".svn", ".venv", "venv", ".tox", ".nox",
|
||||
"__pycache__", ".cache", ".mypy_cache", ".pytest_cache", ".ruff_cache",
|
||||
"node_modules", "site-packages", "dist-packages",
|
||||
}
|
||||
|
||||
|
||||
def project_files(source: Path) -> list[Path]:
|
||||
"""Prune incidental directories, retaining training logs and exported assets.
|
||||
|
||||
The explicitly selected root is always searched. A virtual environment with
|
||||
a custom name is recognized by its marker rather than by guessing names
|
||||
such as ``env`` that may hold real robot configuration.
|
||||
"""
|
||||
files = []
|
||||
for directory, children, names in os.walk(source, followlinks=False):
|
||||
parent = Path(directory)
|
||||
children[:] = [
|
||||
name for name in children
|
||||
if name not in _IGNORED_DIRECTORIES
|
||||
and not (parent / name / "pyvenv.cfg").is_file()
|
||||
]
|
||||
files.extend(parent / name for name in names if (parent / name).is_file())
|
||||
return sorted(files)
|
||||
@@ -152,16 +152,25 @@ def joint_margins(
|
||||
return result
|
||||
|
||||
|
||||
def collision_geom_ids(model: mujoco.MjModel) -> set[int]:
|
||||
"""Include explicitly paired geoms even when their automatic masks are zero."""
|
||||
enabled = set(np.flatnonzero(model.geom_contype | model.geom_conaffinity).tolist())
|
||||
enabled.update(int(gid) for gid in model.pair_geom1)
|
||||
enabled.update(int(gid) for gid in model.pair_geom2)
|
||||
return enabled
|
||||
|
||||
|
||||
def foot_geoms(model: mujoco.MjModel, raw: Any, bid: int) -> dict[str, int]:
|
||||
if not isinstance(raw, list) or not raw or any(not isinstance(name, str) for name in raw):
|
||||
raise ValueError("foot_geoms must be a nonempty list of named collision geoms")
|
||||
if len(raw) != len(set(raw)):
|
||||
raise ValueError("foot_geoms contains duplicate names")
|
||||
result = {name: object_id(model, OBJ.mjOBJ_GEOM, name) for name in raw}
|
||||
colliding = collision_geom_ids(model)
|
||||
for name, gid in result.items():
|
||||
if model.body_rootid[model.geom_bodyid[gid]] != bid:
|
||||
raise ValueError(f"foot geom {name!r} is outside the robot root")
|
||||
if not (model.geom_contype[gid] or model.geom_conaffinity[gid]):
|
||||
if gid not in colliding:
|
||||
raise ValueError(f"foot geom {name!r} is collision-disabled")
|
||||
return result
|
||||
|
||||
@@ -181,6 +190,7 @@ def contact_groups(
|
||||
if len(raw) != len(set(raw)):
|
||||
raise ValueError("foot_bodies contains duplicate names")
|
||||
result = {}
|
||||
colliding = collision_geom_ids(model)
|
||||
for name in raw:
|
||||
body = object_id(model, OBJ.mjOBJ_BODY, name)
|
||||
if model.body_rootid[body] != bid:
|
||||
@@ -188,7 +198,7 @@ def contact_groups(
|
||||
geoms = tuple(
|
||||
gid
|
||||
for gid in np.flatnonzero(model.geom_bodyid == body)
|
||||
if model.geom_contype[gid] or model.geom_conaffinity[gid]
|
||||
if gid in colliding
|
||||
)
|
||||
if not geoms:
|
||||
raise ValueError(f"foot body {name!r} has no direct collision geometry")
|
||||
@@ -234,7 +244,10 @@ def attach_calibration_ground(spec: mujoco.MjSpec, ground_geom: str | None) -> s
|
||||
name = "onboarding_ground"
|
||||
if spec.geom(name) is not None:
|
||||
raise ValueError(f"{name!r} is already used")
|
||||
spec.worldbody.add_geom(name=name, type=GEOM.mjGEOM_PLANE, size=[0.0, 0.0, 0.05])
|
||||
spec.worldbody.add_geom(
|
||||
name=name, type=GEOM.mjGEOM_PLANE, size=[0.0, 0.0, 0.05],
|
||||
contype=1, conaffinity=1,
|
||||
)
|
||||
return name
|
||||
|
||||
|
||||
|
||||
@@ -9,6 +9,7 @@ from pathlib import Path
|
||||
from tempfile import NamedTemporaryFile
|
||||
from typing import Any
|
||||
|
||||
from ._discovery import project_files
|
||||
from ._report import atomic_write
|
||||
from ._xml import _MODEL_EXTENSIONS, is_model_candidate, load_intake_mjcf, mesh_path, read_xml
|
||||
|
||||
@@ -173,9 +174,7 @@ def _select_source(source: Path, output: Path) -> Path:
|
||||
if not source.is_dir():
|
||||
return source
|
||||
output = output.resolve()
|
||||
files = sorted(
|
||||
path for path in source.rglob("*") if path.is_file() and path.resolve() != output
|
||||
)
|
||||
files = [path for path in project_files(source) if path.resolve() != output]
|
||||
candidates = [path for path in files if is_model_candidate(path)]
|
||||
kind = "model"
|
||||
if not candidates:
|
||||
@@ -308,16 +307,19 @@ def write_mjcf(spec: Any, source: Path | str, output: Path | str, *, replace: bo
|
||||
if source == output.resolve():
|
||||
raise ValueError("output must differ from the source")
|
||||
serializable = spec.copy()
|
||||
from mjrl.platform._serialization import named_spec_tree, temporary_object_names
|
||||
|
||||
temporary_names = temporary_object_names(serializable)
|
||||
# Compile a copy with fusion off for serialization. Otherwise the native
|
||||
# writer can omit a fused child's original transform from the new XML.
|
||||
fused = serializable.compiler.fusestatic
|
||||
if fused:
|
||||
original = spec.copy().compile()
|
||||
original = serializable.copy().compile()
|
||||
serializable.compiler.fusestatic = False
|
||||
serializable.compile()
|
||||
else:
|
||||
original = serializable.compile()
|
||||
xml = ET.fromstring(serializable.to_xml())
|
||||
xml = named_spec_tree(serializable)
|
||||
model_directory = Path(spec.modelfiledir or source.parent)
|
||||
compiler = xml.find("compiler")
|
||||
if compiler is None:
|
||||
@@ -351,8 +353,25 @@ def write_mjcf(spec: Any, source: Path | str, output: Path | str, *, replace: bo
|
||||
for field in ("nq", "nv", "nu", "nbody", "njnt", "ngeom"):
|
||||
if getattr(original, field) != getattr(model, field):
|
||||
raise ValueError(f"generated MJCF round-trip changed {field}")
|
||||
geom_order = [model.geom(original.geom(gid).name).id for gid in range(original.ngeom)]
|
||||
for field in ("body_mass", "body_inertia", "qpos0", "jnt_range", "geom_pos", "geom_quat"):
|
||||
if not np.allclose(getattr(original, field), getattr(model, field), atol=1e-9, rtol=1e-5):
|
||||
actual = getattr(model, field)
|
||||
if field.startswith("geom_"):
|
||||
actual = actual[geom_order]
|
||||
if not np.allclose(getattr(original, field), actual, atol=1e-9, rtol=1e-5):
|
||||
raise ValueError(f"generated MJCF round-trip changed {field}")
|
||||
if temporary_names:
|
||||
for element in xml.iter():
|
||||
if element.tag in {"body", "geom"} and element.get("name") in temporary_names:
|
||||
del element.attrib["name"]
|
||||
result = ET.tostring(xml, encoding="unicode") + "\n"
|
||||
# Removing unused temporary labels cannot change geometry or dynamics.
|
||||
with NamedTemporaryFile(suffix=".xml", dir=output.parent, delete=False) as stream:
|
||||
staging = Path(stream.name)
|
||||
stream.write(result.encode("utf-8"))
|
||||
try:
|
||||
model = mujoco.MjModel.from_xml_path(str(staging))
|
||||
finally:
|
||||
staging.unlink(missing_ok=True)
|
||||
atomic_write(output, result, replace=replace)
|
||||
return model
|
||||
|
||||
@@ -10,6 +10,7 @@ import yaml
|
||||
|
||||
from mjrl.platform.graph import SUPPORTED_POLICY_SUFFIXES
|
||||
|
||||
from ._discovery import project_files
|
||||
from ._report import check, read_object
|
||||
from ._xml import (
|
||||
_MESH_EXTENSIONS,
|
||||
@@ -19,7 +20,7 @@ from ._xml import (
|
||||
read_xml,
|
||||
)
|
||||
from .build import urdf_spec
|
||||
from .morphology import infer_morphology
|
||||
from .morphology import infer_morphology, robot_root_ids
|
||||
|
||||
_POLICY_EXTENSIONS = SUPPORTED_POLICY_SUFFIXES | {".pth", ".ckpt", ".safetensors", ".tflite"}
|
||||
_LEGGED_FAMILIES = {"biped", "quadruped", "wheeled_biped", "multipod"}
|
||||
@@ -44,11 +45,7 @@ def _training_config_name(path: Path) -> bool:
|
||||
|
||||
|
||||
def _inventory(source: Path) -> tuple[list[Path], list[Path], list[Path], list[Path], list[Path]]:
|
||||
files = (
|
||||
sorted(path for path in source.rglob("*") if path.is_file())
|
||||
if source.is_dir()
|
||||
else [source]
|
||||
)
|
||||
files = project_files(source) if source.is_dir() else [source]
|
||||
models, weights, meshes, metadata, training_configs = [], [], [], [], []
|
||||
for path in files:
|
||||
extension = path.suffix.lower()
|
||||
@@ -142,13 +139,16 @@ def _model_inventory(model: Any) -> dict[str, Any]:
|
||||
}
|
||||
for aid in range(model.nu)
|
||||
]
|
||||
from ._physics import collision_geom_ids
|
||||
|
||||
colliding = collision_geom_ids(model)
|
||||
geoms = [
|
||||
{
|
||||
"name": model.geom(gid).name or None,
|
||||
"id": gid,
|
||||
"body_id": int(model.geom_bodyid[gid]),
|
||||
"type": mujoco.mjtGeom(int(model.geom_type[gid])).name.removeprefix("mjGEOM_").lower(),
|
||||
"collision_enabled": bool(model.geom_contype[gid] or model.geom_conaffinity[gid]),
|
||||
"collision_enabled": gid in colliding,
|
||||
}
|
||||
for gid in range(model.ngeom)
|
||||
]
|
||||
@@ -259,7 +259,7 @@ def _completeness(
|
||||
nonscalar = [
|
||||
joint["name"] for joint in joints if joint["type"] not in {"free", "hinge", "slide"}
|
||||
]
|
||||
roots = [bid for bid in model["root_body_ids"] if not bodies[bid]["mocap"]]
|
||||
roots = robot_root_ids(model)
|
||||
return [
|
||||
check("dynamic_dofs", model["dimensions"]["nv"] > 0, count=model["dimensions"]["nv"]),
|
||||
check(
|
||||
@@ -320,9 +320,10 @@ def _legged_evidence(model: dict[str, Any], profile: Mapping[str, Any]) -> dict[
|
||||
and all(isinstance(name, str) and name in contacts for name in feet)
|
||||
and len({contacts[name] for name in feet}) == len(feet) >= minimum
|
||||
)
|
||||
robot_only = model["root_body_ids"] == [root_id] and not model["world_geom_ids"]
|
||||
roots = robot_root_ids(model)
|
||||
robot_only = roots == [root_id] and not model["world_geom_ids"]
|
||||
intent = profile.get("control_intent")
|
||||
requested = intent in ("learned", "wasd", "retrain")
|
||||
requested = intent in ("learned", "wasd", "retrain") or (family == "biped" and intent is None)
|
||||
articulated = [joint for joint in model["joints"] if joint["type"] != "free"]
|
||||
supported = bool(articulated) and all(
|
||||
joint["type"] in {"hinge", "slide"} and joint["name"] for joint in articulated
|
||||
@@ -349,6 +350,7 @@ def _legged_evidence(model: dict[str, Any], profile: Mapping[str, Any]) -> dict[
|
||||
"explicit_core_legged_profile",
|
||||
free_base and valid_feet and robot_only and supported and wheel_mapping and requested,
|
||||
family=family,
|
||||
base_body_is_root=root_id in roots,
|
||||
floating_base=free_base,
|
||||
valid_foot_contacts=valid_feet,
|
||||
robot_only=robot_only,
|
||||
@@ -391,6 +393,7 @@ def inspect_asset(
|
||||
complete = False
|
||||
legged = False
|
||||
morphology = None
|
||||
legged_check = {}
|
||||
if len(models) == 1:
|
||||
path = models[0]
|
||||
try:
|
||||
@@ -437,6 +440,7 @@ def inspect_asset(
|
||||
metadata_extraction = extract_policy_metadata(sources, model=model)
|
||||
metadata_doc = metadata_extraction["metadata"]
|
||||
metadata_valid = False
|
||||
walking_commands = False
|
||||
metadata_issue = None
|
||||
if metadata_extraction is not None and not metadata_extraction["ready"]:
|
||||
metadata_issue = "upstream metadata needs review; see metadata_extraction"
|
||||
@@ -447,11 +451,17 @@ def inspect_asset(
|
||||
from mjrl.adapter import build_layout
|
||||
|
||||
try:
|
||||
build_layout(metadata_doc, model=model)
|
||||
layout = build_layout(metadata_doc, model=model)
|
||||
except (TypeError, ValueError) as exc:
|
||||
metadata_issue = str(exc)
|
||||
else:
|
||||
metadata_valid = True
|
||||
twist = layout.get("command_ranges", {}).get("twist", {})
|
||||
walking_commands = all(
|
||||
lo < 0 < hi for lo, hi in (
|
||||
twist.get("lin_vel_x", (0, 0)), twist.get("ang_vel_z", (0, 0))
|
||||
)
|
||||
)
|
||||
checks.append(
|
||||
check(
|
||||
"policy_metadata_evidence",
|
||||
@@ -487,7 +497,15 @@ def inspect_asset(
|
||||
and intent in (None, "learned", "wasd", "retrain")
|
||||
and (morphology["floating_base"] or evidence["format"] == "urdf")
|
||||
)
|
||||
if (3 in eligible or tier3_pending) and intent == "retrain":
|
||||
# A humanoid's default objective survives a partial profile or a scene
|
||||
# wrapper. Readiness still depends on the reviewed root, feet and model.
|
||||
family = profile.get("family", morphology["family"] if morphology else None)
|
||||
walking = family == "biped" and intent in (None, "learned", "wasd", "retrain")
|
||||
if complete and intent == "deterministic":
|
||||
tier = 2
|
||||
elif complete and walking:
|
||||
tier = 1 if 1 in eligible and walking_commands and intent != "retrain" else 3
|
||||
elif (3 in eligible or tier3_pending) and intent == "retrain":
|
||||
tier = 3
|
||||
elif 1 in eligible or tier1_pending:
|
||||
tier = 1
|
||||
@@ -499,19 +517,28 @@ def inspect_asset(
|
||||
tier = 0
|
||||
route = {0: "build-mjcf", 1: "adapt-tier1", 2: "setup-tier2", 3: "scaffold-tier3"}[tier]
|
||||
status = "ready"
|
||||
if tier == 1 and (len(weights) != 1 or len(metadata) > 1):
|
||||
if len(models) > 1:
|
||||
status = "needs_selection"
|
||||
elif tier == 1 and (len(weights) != 1 or len(metadata) > 1):
|
||||
status = "needs_selection"
|
||||
elif tier == 1 and not metadata_valid:
|
||||
status = "needs_metadata"
|
||||
elif tier == 3 and tier3_pending:
|
||||
status = "needs_profile"
|
||||
elif tier == 3 and not legged:
|
||||
profile_ready = all(legged_check.get(key) for key in (
|
||||
"base_body_is_root", "valid_foot_contacts", "supported_articulation",
|
||||
"wheel_mapping", "learned_control_requested",
|
||||
))
|
||||
status = "needs_model" if profile_ready else "needs_profile"
|
||||
prerequisites = []
|
||||
if len(models) > 1:
|
||||
prerequisites.append("select_model")
|
||||
if tier == 3:
|
||||
if tier3_pending:
|
||||
prerequisites.append("confirm_morphology_and_control_intent")
|
||||
if status == "needs_profile":
|
||||
prerequisites.append("confirm_morphology_and_supports" if walking
|
||||
else "confirm_morphology_and_control_intent")
|
||||
if not morphology["floating_base"]:
|
||||
prerequisites.append("build_floating_base_mjcf")
|
||||
if evidence["world_geom_ids"]:
|
||||
if evidence["world_geom_ids"] or len(robot_root_ids(evidence)) != 1:
|
||||
prerequisites.append("extract_robot_only_model")
|
||||
if not next(item["passed"] for item in checks if item["name"] == "actuation_coverage"):
|
||||
prerequisites.append("supply_actuation_and_effort_limits")
|
||||
@@ -531,11 +558,14 @@ def inspect_asset(
|
||||
"morphology_candidates": morphology,
|
||||
"checks": checks,
|
||||
"recommendation": {
|
||||
**({"objective": "walking"} if walking else {}),
|
||||
"tier": tier,
|
||||
"route": route,
|
||||
"status": status,
|
||||
"next_step": (
|
||||
"review-profile" if tier == 3 and tier3_pending
|
||||
"select-model" if len(models) > 1
|
||||
else "review-profile" if status == "needs_profile"
|
||||
else "prepare-training-model" if status == "needs_model"
|
||||
else "extract-tier1" if tier == 1 and not metadata_valid else route
|
||||
),
|
||||
"prerequisites": prerequisites,
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
"""Compiled MJCF facts kept separate from unknown actor semantics."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import mujoco
|
||||
|
||||
from ._physics import compiled_model_sha256
|
||||
|
||||
|
||||
def model_evidence(model: mujoco.MjModel) -> dict:
|
||||
"""Record named physical facts without inventing a policy contract.
|
||||
|
||||
Keyframes are authored poses, not evidence of a policy's default pose.
|
||||
Physics timestep is not policy frequency; joint damping is not policy kd.
|
||||
Raw actuator parameters retain transmission and force conventions.
|
||||
"""
|
||||
joints = []
|
||||
for jid in range(model.njnt):
|
||||
kind = mujoco.mjtJoint(int(model.jnt_type[jid]))
|
||||
nq = {mujoco.mjtJoint.mjJNT_FREE: 7, mujoco.mjtJoint.mjJNT_BALL: 4}.get(kind, 1)
|
||||
nv = {mujoco.mjtJoint.mjJNT_FREE: 6, mujoco.mjtJoint.mjJNT_BALL: 3}.get(kind, 1)
|
||||
qadr, dadr = int(model.jnt_qposadr[jid]), int(model.jnt_dofadr[jid])
|
||||
joints.append({
|
||||
"name": model.joint(jid).name or None,
|
||||
"type": kind.name.removeprefix("mjJNT_").lower(),
|
||||
"body": model.body(int(model.jnt_bodyid[jid])).name,
|
||||
"qpos_address": qadr, "dof_address": dadr,
|
||||
"reference_qpos": model.qpos0[qadr:qadr + nq].tolist(),
|
||||
"range": model.jnt_range[jid].tolist() if model.jnt_limited[jid] else None,
|
||||
"damping": model.dof_damping[dadr:dadr + nv].tolist(),
|
||||
"armature": model.dof_armature[dadr:dadr + nv].tolist(),
|
||||
"actuator_force_range": (
|
||||
model.jnt_actfrcrange[jid].tolist() if model.jnt_actfrclimited[jid] else None
|
||||
),
|
||||
})
|
||||
actuators = []
|
||||
for aid in range(model.nu):
|
||||
transmission = mujoco.mjtTrn(int(model.actuator_trntype[aid]))
|
||||
joint = None
|
||||
if transmission in {mujoco.mjtTrn.mjTRN_JOINT, mujoco.mjtTrn.mjTRN_JOINTINPARENT}:
|
||||
joint = model.joint(int(model.actuator_trnid[aid, 0])).name
|
||||
actuators.append({
|
||||
"name": model.actuator(aid).name or None,
|
||||
"joint": joint,
|
||||
"transmission": transmission.name.removeprefix("mjTRN_").lower(),
|
||||
"target_ids": model.actuator_trnid[aid].tolist(),
|
||||
"gear": model.actuator_gear[aid].tolist(),
|
||||
"gain_type": mujoco.mjtGain(int(model.actuator_gaintype[aid])).name,
|
||||
"bias_type": mujoco.mjtBias(int(model.actuator_biastype[aid])).name,
|
||||
"dynamics_type": mujoco.mjtDyn(int(model.actuator_dyntype[aid])).name,
|
||||
"gain_parameters": model.actuator_gainprm[aid].tolist(),
|
||||
"bias_parameters": model.actuator_biasprm[aid].tolist(),
|
||||
"dynamics_parameters": model.actuator_dynprm[aid].tolist(),
|
||||
"control_range": (
|
||||
model.actuator_ctrlrange[aid].tolist() if model.actuator_ctrllimited[aid] else None
|
||||
),
|
||||
"force_range": (
|
||||
model.actuator_forcerange[aid].tolist() if model.actuator_forcelimited[aid] else None
|
||||
),
|
||||
})
|
||||
return {
|
||||
"schema": "mjrl.onboarding.model-evidence/1",
|
||||
"compiled_model_sha256": compiled_model_sha256(model),
|
||||
"dimensions": {"nq": model.nq, "nv": model.nv, "nu": model.nu},
|
||||
"physics_timestep_s": float(model.opt.timestep),
|
||||
"gravity_world_m_s2": model.opt.gravity.tolist(),
|
||||
"joints": joints,
|
||||
"actuators": actuators,
|
||||
"keyframes": [{
|
||||
"name": model.key(kid).name or None,
|
||||
"qpos": model.key_qpos[kid].tolist(),
|
||||
"qvel": model.key_qvel[kid].tolist(),
|
||||
"ctrl": model.key_ctrl[kid].tolist(),
|
||||
} for kid in range(model.nkey)],
|
||||
"explicit_contact_pairs": [{
|
||||
"geoms": [model.geom(int(gid)).name for gid in
|
||||
(model.pair_geom1[pid], model.pair_geom2[pid])],
|
||||
"condim": int(model.pair_dim[pid]),
|
||||
"friction": model.pair_friction[pid].tolist(),
|
||||
} for pid in range(model.npair)],
|
||||
"limitations": [
|
||||
"Compiled order does not establish actor observation or action order.",
|
||||
"Keyframes and reference positions do not establish policy default_joint_pos.",
|
||||
"Physics timestep does not establish policy control_hz or decimation.",
|
||||
"Joint damping and actuator gains do not establish policy control gains.",
|
||||
"No actor weights, observation history, normalization or action scale are recovered.",
|
||||
],
|
||||
}
|
||||
@@ -14,9 +14,63 @@ def _named(value: str | None, words: str) -> bool:
|
||||
return bool(re.search(rf"(^|[^a-z])({words})([^a-z]|$)", text))
|
||||
|
||||
|
||||
def _support_branches(
|
||||
paths: dict[int, list[int]], by_body: dict[int, list],
|
||||
) -> dict[int, int]:
|
||||
"""Separate limbs below shared bodies without splitting a foot's contacts.
|
||||
|
||||
Start with root branches, then examine each support group's lowest common
|
||||
ancestor. A deeper split requires at least two scalar joints on every
|
||||
resulting distal chain: fixed contact bodies and single-joint toes do not
|
||||
establish independent legs. Ambiguous short chains remain one candidate.
|
||||
"""
|
||||
result = {}
|
||||
|
||||
def partition(group: dict[int, list[int]], branch: int) -> None:
|
||||
common = 0
|
||||
for nodes in zip(*group.values()):
|
||||
if len(set(nodes)) != 1:
|
||||
break
|
||||
common += 1
|
||||
distal = {bid: path[common:] for bid, path in group.items()}
|
||||
if len(group) == 1 or any(
|
||||
sum(len(by_body.get(node, [])) for node in path) < 2
|
||||
for path in distal.values()
|
||||
):
|
||||
result.update({bid: branch for bid in group})
|
||||
return
|
||||
children: dict[int, dict[int, list[int]]] = {}
|
||||
for bid, path in distal.items():
|
||||
children.setdefault(path[0], {})[bid] = group[bid]
|
||||
for child, members in children.items():
|
||||
partition(members, child)
|
||||
|
||||
roots: dict[int, dict[int, list[int]]] = {}
|
||||
for bid, path in paths.items():
|
||||
roots.setdefault(path[0], {})[bid] = path
|
||||
for root, group in roots.items():
|
||||
partition(group, root)
|
||||
return result
|
||||
|
||||
|
||||
def robot_root_ids(model: dict[str, Any]) -> list[int]:
|
||||
"""Ignore empty static frame trees without hiding physical scene bodies."""
|
||||
bodies = {body["id"]: body for body in model["bodies"]}
|
||||
occupied = {joint["body_id"] for joint in model["joints"]}
|
||||
occupied.update(geom["body_id"] for geom in model["geoms"])
|
||||
occupied.update(body["id"] for body in bodies.values() if body["mass_kg"] > 0)
|
||||
meaningful = set()
|
||||
for bid in occupied:
|
||||
while bid in bodies:
|
||||
meaningful.add(bid)
|
||||
bid = bodies[bid]["parent_id"]
|
||||
return [bid for bid in model["root_body_ids"]
|
||||
if bid in meaningful and not bodies[bid]["mocap"]]
|
||||
|
||||
|
||||
def infer_morphology(model: dict[str, Any]) -> dict[str, Any]:
|
||||
bodies = {body["id"]: body for body in model["bodies"]}
|
||||
roots = [bid for bid in model["root_body_ids"] if not bodies[bid]["mocap"]]
|
||||
roots = robot_root_ids(model)
|
||||
base = roots[0] if len(roots) == 1 else None
|
||||
joints = model["joints"]
|
||||
scalar = [joint for joint in joints if joint["type"] in {"hinge", "slide"}]
|
||||
@@ -32,6 +86,7 @@ def infer_morphology(model: dict[str, Any]) -> dict[str, Any]:
|
||||
wheel_bodies = {joint["body_id"] for joint in wheels}
|
||||
children = {body["parent_id"] for body in bodies.values()}
|
||||
supports = []
|
||||
support_paths = {}
|
||||
terminal_chains = []
|
||||
for bid, body in bodies.items():
|
||||
if bid == base or bid in children:
|
||||
@@ -61,6 +116,7 @@ def infer_morphology(model: dict[str, Any]) -> dict[str, Any]:
|
||||
"velocity_dofs": sum(joint["velocity_dofs"] for joint in chain_joints),
|
||||
})
|
||||
if geoms and (foot or (leg and len(chain_joints) >= 2)):
|
||||
support_paths[bid] = list(reversed(chain))
|
||||
# Prefer explicitly named contact surfaces over wheel hubs/shells.
|
||||
preferred = [geom for geom in geoms
|
||||
if _named(geom["name"], "foot|feet|toe|sole|tire|wheel")]
|
||||
@@ -69,7 +125,10 @@ def infer_morphology(model: dict[str, Any]) -> dict[str, Any]:
|
||||
"geoms": [geom["name"] for geom in preferred or geoms if geom["name"]],
|
||||
"wheel": wheel, "evidence": "named_support" if foot else "leg_chain",
|
||||
})
|
||||
# Multiple toes on one branch must not count as multiple legs.
|
||||
# Limbs may share an articulated waist; distal contacts may share a foot.
|
||||
support_branches = _support_branches(support_paths, by_body)
|
||||
for support in supports:
|
||||
support["branch_id"] = support_branches[support["body_id"]]
|
||||
branches = {support["branch_id"] for support in supports}
|
||||
count = len(branches)
|
||||
wheel_count = sum(support["wheel"] for support in supports)
|
||||
|
||||
@@ -70,6 +70,13 @@ def calibrated_spec_config(
|
||||
action_scales = number_map(config.get("action_scales"), "action_scales")
|
||||
if set(action_scales) != set(position_names):
|
||||
raise ValueError("action_scales must cover exactly the calibrated position joints")
|
||||
posture_stds = dict.fromkeys(position_names, 0.35)
|
||||
if "posture_stds" in config:
|
||||
posture_stds = number_map(config["posture_stds"], "posture_stds")
|
||||
if set(posture_stds) != set(position_names):
|
||||
raise ValueError("posture_stds must cover exactly the calibrated position joints")
|
||||
if any(value <= 0 for value in posture_stds.values()):
|
||||
raise ValueError("posture_stds must contain positive values")
|
||||
values = []
|
||||
for name in position_names:
|
||||
measurement = measurements[name]
|
||||
@@ -81,10 +88,11 @@ def calibrated_spec_config(
|
||||
"name": name,
|
||||
**{key: measurement[key] for key in fields},
|
||||
"action_scale": action_scales[name],
|
||||
"posture_std": posture_stds[name],
|
||||
}
|
||||
)
|
||||
return {
|
||||
**{key: value for key, value in config.items() if key != "action_scales"},
|
||||
**{key: value for key, value in config.items() if key not in {"action_scales", "posture_stds"}},
|
||||
"model_path": str(model_path),
|
||||
"base_body": report.get("root_body"),
|
||||
"base_height": float(position[2]),
|
||||
@@ -106,6 +114,7 @@ def scaffold_task(
|
||||
report supplies measured stance fields and must match the exact model.
|
||||
The task directory defaults to the active `tasks` package.
|
||||
"""
|
||||
from mjrl.controllers.bindings import WALKING_CONTROLS
|
||||
from tasks.robot_spec import RobotSpec, scaffold_robot_spec
|
||||
from tasks.templates._locomotion import validate_robot_model
|
||||
|
||||
@@ -115,6 +124,8 @@ def scaffold_task(
|
||||
if calibration is not None
|
||||
else dict(config)
|
||||
)
|
||||
if data.get("family") == "biped":
|
||||
data.setdefault("controls_path", str(WALKING_CONTROLS))
|
||||
spec = RobotSpec.from_dict(data, base_dir=base)
|
||||
checked_mjcf(spec.model_path)
|
||||
validate_robot_model(spec)
|
||||
|
||||
@@ -51,12 +51,12 @@ _TOP_FIELDS = {
|
||||
"wire_joint_order", "obs_joint_order", "action_joint_order", "default_joint_pos",
|
||||
"source_action_joint_order", "default_joint_vel", "passive_joints", "joint_limits",
|
||||
"action_scale", "action", "command_ranges", "raw_action_clip", "use_default_offset",
|
||||
"controller", "root_body",
|
||||
"controller", "root_body", "motor_model",
|
||||
}
|
||||
_CONTROL_FIELDS = {"kp", "kd", "effort_limit", "control_hz"}
|
||||
_OBSERVATION_FIELDS = {
|
||||
"terms", "dim", "history_length", "source_term_order", "source_order",
|
||||
"source_history_order", "normalization", "inputs", "command_order",
|
||||
"source_history_order", "normalization", "inputs", "command_order", "frames",
|
||||
}
|
||||
_GAIN_FIELDS = {"control.kp", "control.kd", "control.effort_limit"}
|
||||
_CONTROL_SECTIONS = {"control", "controller", "actuation", "actuator", "actuators", "gains"}
|
||||
@@ -388,8 +388,8 @@ def extract_policy_metadata(
|
||||
sources: Sequence[Path | str], *, overrides: Mapping | None = None, model=None
|
||||
) -> dict:
|
||||
"""Extract a canonical draft, with unresolved fields visible and provenance."""
|
||||
if isinstance(sources, (str, Path)) or not sources:
|
||||
raise ValueError("sources must be a nonempty sequence of config paths")
|
||||
if isinstance(sources, (str, Path)) or (not sources and model is None):
|
||||
raise ValueError("provide config paths or a model for an evidence-only draft")
|
||||
if overrides is not None and not isinstance(overrides, Mapping):
|
||||
raise ValueError("overrides must be a canonical metadata object")
|
||||
|
||||
@@ -655,8 +655,14 @@ def extract_policy_metadata(
|
||||
except (AttributeError, KeyError, OverflowError, TypeError, ValueError) as error:
|
||||
problem("metadata", {"source": "adapter", "path": ""}, str(error))
|
||||
ready = False
|
||||
evidence = None
|
||||
if model is not None:
|
||||
from .model_evidence import model_evidence
|
||||
|
||||
evidence = model_evidence(model)
|
||||
return {
|
||||
"schema": REPORT_SCHEMA,
|
||||
"model_evidence": evidence,
|
||||
"metadata": metadata,
|
||||
"ready": ready,
|
||||
"missing_fields": missing,
|
||||
|
||||
@@ -24,6 +24,7 @@ from ._physics import (
|
||||
OBJ,
|
||||
base_frames,
|
||||
compiled_model_sha256 as compiled_model_sha256,
|
||||
collision_geom_ids,
|
||||
contact_groups,
|
||||
contact_loads,
|
||||
finite,
|
||||
@@ -504,8 +505,16 @@ def _run_probe(
|
||||
disabled = model.opt.disableflags
|
||||
try:
|
||||
model.opt.disableflags |= mujoco.mjtDisableBit.mjDSBL_ACTUATION
|
||||
# Dynamic motor friction belongs to this passive rollout, not to the
|
||||
# last active sample. Reset only controller state, preserving baseline.
|
||||
reset_passive = getattr(controller, "reset_passive", None)
|
||||
apply_passive = getattr(controller, "apply_passive", None)
|
||||
if reset_passive is not None:
|
||||
reset_passive(baseline)
|
||||
mujoco.mj_forward(model, baseline)
|
||||
for index in range(steps):
|
||||
if apply_passive is not None:
|
||||
apply_passive(baseline)
|
||||
mujoco.mj_step(model, baseline)
|
||||
mujoco.mj_forward(model, baseline)
|
||||
if (
|
||||
@@ -637,8 +646,7 @@ def verify(
|
||||
mass = float(mj.body_subtreemass[root])
|
||||
has_collision = any(
|
||||
mj.body_rootid[mj.geom_bodyid[gid]] == root
|
||||
and (mj.geom_contype[gid] or mj.geom_conaffinity[gid])
|
||||
for gid in range(mj.ngeom)
|
||||
for gid in collision_geom_ids(mj)
|
||||
)
|
||||
physics.append(
|
||||
check(
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
"""Preserve floating point precision when the native XML writer supports it."""
|
||||
from __future__ import annotations
|
||||
|
||||
import ctypes
|
||||
import xml.etree.ElementTree as ET
|
||||
from threading import RLock
|
||||
|
||||
_XML_LOCK = RLock()
|
||||
|
||||
|
||||
def _precision_api():
|
||||
import mujoco
|
||||
|
||||
# MuJoCo exposes these private hooks through its shared library, but not
|
||||
# through Python. Keep the optional dependency isolated: older builds use
|
||||
# their ordinary writer and callers' unchanged round-trip checks still apply.
|
||||
try:
|
||||
library = ctypes.CDLL(mujoco._specs.__file__)
|
||||
get = library._mjPRIVATE__get_xml_precision
|
||||
set_ = library._mjPRIVATE__set_xml_precision
|
||||
except (OSError, AttributeError):
|
||||
return None
|
||||
get.argtypes, get.restype = [], ctypes.c_int
|
||||
set_.argtypes, set_.restype = [ctypes.c_int], None
|
||||
return get, set_
|
||||
|
||||
|
||||
def spec_xml(spec) -> str:
|
||||
"""Use double precision XML and restore native writer state even on error."""
|
||||
api = _precision_api()
|
||||
if api is None:
|
||||
return spec.to_xml()
|
||||
get, set_ = api
|
||||
with _XML_LOCK:
|
||||
previous = get()
|
||||
try:
|
||||
set_(17)
|
||||
return spec.to_xml()
|
||||
finally:
|
||||
set_(previous)
|
||||
|
||||
|
||||
def temporary_object_names(spec) -> set[str]:
|
||||
"""Give anonymous bodies/geoms stable identities for round-trip checks."""
|
||||
temporary_names = set()
|
||||
used_names = {item.name for item in [*spec.bodies, *spec.geoms]}
|
||||
for index, item in enumerate([*spec.bodies, *spec.geoms]):
|
||||
if item is spec.worldbody or item.name:
|
||||
continue
|
||||
name = f"__mjrl_roundtrip_{index}"
|
||||
while name in used_names:
|
||||
name += "_"
|
||||
item.name = name
|
||||
temporary_names.add(name)
|
||||
used_names.add(name)
|
||||
return temporary_names
|
||||
|
||||
|
||||
def named_spec_tree(spec) -> ET.Element:
|
||||
"""Serialize a spec whose geoms have stable names for round-trip checks."""
|
||||
root = ET.fromstring(spec_xml(spec))
|
||||
# MuJoCo can elide both mass and density for a zero-mass geom when its
|
||||
# class supplies both as zero. On reload it then acquires the built-in
|
||||
# density. Use the effective spec mass, including class inheritance.
|
||||
massless = {geom.name for geom in spec.geoms if geom.mass == 0}
|
||||
if massless:
|
||||
for element in root.iterfind("./worldbody//geom"):
|
||||
if element.get("name") in massless:
|
||||
element.set("mass", "0")
|
||||
return root
|
||||
@@ -17,6 +17,13 @@ MODES = {"rl_onnx", "ik_mocap", "wheeled_velocity", "cpg_keyframe", "model_viewe
|
||||
KIND_MODE = {"ik": "ik_mocap", "joint_sliders": "ik_mocap", "trajectory": "cpg_keyframe",
|
||||
"cpg": "cpg_keyframe", "differential": "wheeled_velocity", "omni": "wheeled_velocity",
|
||||
"direct": "model_viewer", "rl_onnx": "rl_onnx"}
|
||||
IK_MOUSE_HELP = (
|
||||
"Double-click the end-effector target marker to select it. Hold Ctrl and drag "
|
||||
"with the right mouse button to move it. Hold Shift as well to change the "
|
||||
"translation plane. Release the mouse to hold the target."
|
||||
)
|
||||
|
||||
|
||||
def _trusted_schema_bytes() -> bytes:
|
||||
# The application also ships a published schema for readers. Validation
|
||||
# always uses the copy shipped with this installed or portable runtime.
|
||||
@@ -105,9 +112,11 @@ def _manual(root: Path, robot_id: str, modes: dict, default: str) -> dict:
|
||||
"leave": "Close the viewer or stop replay.",
|
||||
"keyboard": "This mode has no keyboard bindings.",
|
||||
"controls": [], "keys": []}
|
||||
contract = json.loads((root / mode["contract"]).read_text())
|
||||
if contract.get("kind") == "ik":
|
||||
item["summary"] = IK_MOUSE_HELP
|
||||
if mode.get("controls"):
|
||||
controls = load_controls(root / mode["controls"])
|
||||
contract = json.loads((root / mode["contract"]).read_text())
|
||||
if mode["control_mode"] == "rl_onnx":
|
||||
layout = json.loads((root / mode["layout"]).read_text())
|
||||
ranges = layout.get("command_ranges", {}).get("twist", {})
|
||||
@@ -338,8 +347,19 @@ def _build_bundle(model: Path, output: Path, *, robot_id: str, modes: dict[str,
|
||||
write_json(root / "manual.en.json", _manual(root, robot_id, mode_records, default_mode))
|
||||
(root / "runtime").mkdir()
|
||||
_runtime(root / "runtime/controller.pyz")
|
||||
(root / "runtime/requirements.txt").write_text(
|
||||
"mujoco~=3.11.0\nnumpy\nPyYAML\njsonschema\nonnx\nonnxruntime>=1.17\nimageio-ffmpeg\n")
|
||||
requirements = "mujoco~=3.11.0\nnumpy\nPyYAML\njsonschema\nonnx\nonnxruntime>=1.17\nimageio-ffmpeg\n"
|
||||
python_requirement = ">=3.10,<3.14"
|
||||
for record in mode_records.values():
|
||||
if record.get("layout"):
|
||||
layout = json.loads((root / record["layout"]).read_text())
|
||||
if "motor_model" in layout:
|
||||
from .motors import BAM_PYTHON_REQUIREMENT, BAM_REQUIREMENT, validate_motor_model
|
||||
|
||||
validate_motor_model(layout["motor_model"])
|
||||
requirements += BAM_REQUIREMENT + "\n"
|
||||
python_requirement = BAM_PYTHON_REQUIREMENT
|
||||
break
|
||||
(root / "runtime/requirements.txt").write_text(requirements)
|
||||
(root / "app.schema").write_bytes(_trusted_schema_bytes())
|
||||
(root / "LICENSE").write_bytes(files(__package__).joinpath("LICENSE").read_bytes())
|
||||
license_files = ["LICENSE"]
|
||||
@@ -361,7 +381,7 @@ def _build_bundle(model: Path, output: Path, *, robot_id: str, modes: dict[str,
|
||||
"controller": "controller.toml", "manuals": {"en": "manual.en.json"},
|
||||
"reference": "reference.json", "verification": "verification.json" if reports else None,
|
||||
"runtimes": {"native": {"file": "runtime/controller.pyz", "language": "python",
|
||||
"python": ">=3.10,<3.14", "dependencies": "runtime/requirements.txt",
|
||||
"python": python_requirement, "dependencies": "runtime/requirements.txt",
|
||||
"platforms": ["linux", "windows", "macos"]}},
|
||||
"capabilities": sorted({x["control_mode"] for x in mode_records.values()}),
|
||||
"source": {"model_sha256": digest(model)}, "files": {}}
|
||||
|
||||
+44
-11
@@ -16,16 +16,36 @@ def copy_model(source: Path, output: Path) -> dict[str, str]:
|
||||
from mjrl.onboarding._xml import checked_mjcf
|
||||
|
||||
source, output = Path(source).resolve(), Path(output)
|
||||
checked_mjcf(source)
|
||||
before = mujoco.MjModel.from_xml_path(str(source))
|
||||
authored = checked_mjcf(source)
|
||||
from ._serialization import named_spec_tree, temporary_object_names
|
||||
|
||||
spec = mujoco.MjSpec.from_file(str(source))
|
||||
# Compiling a fused spec mutates fixed-child geometry before serialization.
|
||||
# Serialize the unfused tree and let the relocated model apply the original
|
||||
# compiler setting, preserving both transforms and authored semantics.
|
||||
fuse_static = spec.compiler.fusestatic
|
||||
spec.compiler.fusestatic = False
|
||||
spec.compile()
|
||||
root = ET.fromstring(spec.to_xml())
|
||||
authored_compiler = authored.find("compiler")
|
||||
# An already flattened export needs only dependency relocation. Feeding it
|
||||
# through MjSpec's writer recomposes mesh frames and renormalizes rotations,
|
||||
# changing a few ulps that can split long contact-rich reference rollouts.
|
||||
# Preserve its exact numeric attribute text, including inherited defaults.
|
||||
direct = not any(element.tag in {"include", "model", "attach"}
|
||||
for element in authored.iter()) and (
|
||||
authored_compiler is None or not any(
|
||||
authored_compiler.get(key) for key in ("assetdir", "meshdir", "texturedir", "strippath")
|
||||
)
|
||||
)
|
||||
temporary_names = set()
|
||||
if direct:
|
||||
before = mujoco.MjModel.from_xml_path(str(source))
|
||||
root = authored
|
||||
fuse_static = spec.compiler.fusestatic
|
||||
else:
|
||||
temporary_names = temporary_object_names(spec)
|
||||
before = spec.copy().compile()
|
||||
# Compiling a fused spec mutates fixed-child geometry before serialization.
|
||||
# Serialize the unfused tree and let the relocated model apply the original
|
||||
# compiler setting, preserving both transforms and authored semantics.
|
||||
fuse_static = spec.compiler.fusestatic
|
||||
spec.compiler.fusestatic = False
|
||||
spec.compile()
|
||||
root = named_spec_tree(spec)
|
||||
if root.find("extension") is not None:
|
||||
raise ValueError("plugin models require an explicit packaged plugin runtime")
|
||||
compiler = root.find("compiler")
|
||||
@@ -57,7 +77,8 @@ def copy_model(source: Path, output: Path) -> dict[str, str]:
|
||||
dependencies[str(path)] = relative
|
||||
for key in ("assetdir", "meshdir", "texturedir"):
|
||||
compiler.attrib.pop(key, None)
|
||||
compiler.set("fusestatic", "true" if fuse_static else "false")
|
||||
if not direct:
|
||||
compiler.set("fusestatic", "true" if fuse_static else "false")
|
||||
ET.indent(root)
|
||||
ET.ElementTree(root).write(output, encoding="utf-8", xml_declaration=True)
|
||||
after = mujoco.MjModel.from_xml_path(str(output))
|
||||
@@ -65,6 +86,8 @@ def copy_model(source: Path, output: Path) -> dict[str, str]:
|
||||
for field in ("nq", "nv", "nu", "nbody", "ngeom", "njnt"):
|
||||
if getattr(before, field) != getattr(after, field):
|
||||
raise ValueError(f"relocating model changed {field}")
|
||||
geom_order = (list(range(before.ngeom)) if direct else
|
||||
[after.geom(before.geom(gid).name).id for gid in range(before.ngeom)])
|
||||
for field in (
|
||||
"body_mass", "body_inertia", "body_pos", "body_quat", "body_ipos", "body_iquat",
|
||||
"jnt_range", "jnt_pos", "jnt_axis", "jnt_stiffness", "qpos0",
|
||||
@@ -74,8 +97,18 @@ def copy_model(source: Path, output: Path) -> dict[str, str]:
|
||||
"actuator_gainprm", "actuator_biasprm", "actuator_dynprm",
|
||||
"actuator_ctrlrange", "actuator_forcerange",
|
||||
):
|
||||
if not np.allclose(getattr(before, field), getattr(after, field), rtol=1e-7, atol=1e-10):
|
||||
actual = getattr(after, field)
|
||||
if field.startswith("geom_"):
|
||||
actual = actual[geom_order]
|
||||
if not np.allclose(getattr(before, field), actual, rtol=1e-7, atol=1e-10):
|
||||
raise ValueError(f"relocating model changed {field}")
|
||||
if direct and not np.array_equal(getattr(before, field), actual):
|
||||
raise ValueError(f"relocating flattened model changed exact {field}")
|
||||
if temporary_names:
|
||||
for element in root.iter():
|
||||
if element.tag in {"body", "geom"} and element.get("name") in temporary_names:
|
||||
del element.attrib["name"]
|
||||
ET.ElementTree(root).write(output, encoding="utf-8", xml_declaration=True)
|
||||
return dependencies
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
"""Optional calibrated motor laws for native policy playback.
|
||||
|
||||
BAM owns the electrical and friction equations. Its constructor receives scratch
|
||||
MuJoCo data because mj_setConst resets qpos; no live world is passed to it.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from importlib.metadata import version
|
||||
import re
|
||||
import sys
|
||||
|
||||
import mujoco
|
||||
import numpy as np
|
||||
|
||||
from mjrl.controllers.model import finite
|
||||
|
||||
BAM_VERSION = "1.0.2"
|
||||
BAM_REQUIREMENT = f"better-actuator-models=={BAM_VERSION}"
|
||||
BAM_PYTHON_REQUIREMENT = ">=3.12,<3.13"
|
||||
|
||||
|
||||
def validate_motor_model(config: Mapping) -> dict:
|
||||
fields = {
|
||||
"kind", "motor_name", "model", "kp", "vin", "max_current",
|
||||
"vin_drop_resistance", "vin_min",
|
||||
}
|
||||
if not isinstance(config, Mapping) or set(config) != fields or config.get("kind") != "bam":
|
||||
raise ValueError(f"motor_model requires BAM fields {sorted(fields)}")
|
||||
result = dict(config)
|
||||
for field in ("motor_name", "model"):
|
||||
if not isinstance(result[field], str) or not re.fullmatch(r"[a-zA-Z0-9_-]+", result[field]):
|
||||
raise ValueError(f"motor_model.{field} must name a built-in BAM model")
|
||||
for field in ("kp", "vin", "max_current", "vin_min"):
|
||||
result[field] = finite(result[field], f"motor_model.{field}", positive=True)
|
||||
result["vin_drop_resistance"] = finite(
|
||||
result["vin_drop_resistance"], "motor_model.vin_drop_resistance"
|
||||
)
|
||||
if result["vin_drop_resistance"] < 0 or result["vin_min"] > result["vin"]:
|
||||
raise ValueError("motor_model requires nonnegative resistance and vin_min <= vin")
|
||||
return result
|
||||
|
||||
|
||||
class BamMotorModel:
|
||||
"""Apply a named BAM model once per physics tick, reset independently per run."""
|
||||
|
||||
def __init__(self, model, actuator_ids, effort, config):
|
||||
config = validate_motor_model(config)
|
||||
if sys.version_info[:2] != (3, 12):
|
||||
raise ValueError(f"Native BAM playback requires Python {BAM_PYTHON_REQUIREMENT}")
|
||||
if version("better-actuator-models") != BAM_VERSION:
|
||||
raise ValueError(f"Native BAM playback requires {BAM_REQUIREMENT}")
|
||||
from bam.model import load_model
|
||||
from bam.mujoco import MujocoController
|
||||
|
||||
self.model = model
|
||||
self.actuator_ids = np.asarray(actuator_ids)
|
||||
self.effort = np.asarray(effort).copy()
|
||||
self.dofs = model.jnt_dofadr[model.actuator_trnid[self.actuator_ids, 0]]
|
||||
self.initial_friction = model.dof_frictionloss[self.dofs].copy()
|
||||
self.initial_damping = model.dof_damping[self.dofs].copy()
|
||||
motor = load_model(motor_name=config["motor_name"], model=config["model"])
|
||||
for key in ("kp", "vin", "max_current"):
|
||||
setattr(motor.actuator, key, config[key])
|
||||
names = [model.actuator(int(index)).name for index in self.actuator_ids]
|
||||
if any(not name for name in names):
|
||||
raise ValueError("BAM requires named actuators")
|
||||
self.controller = MujocoController(
|
||||
motor, names, model, mujoco.MjData(model),
|
||||
vin_drop_resistance=config["vin_drop_resistance"], vin_min=config["vin_min"],
|
||||
)
|
||||
self._applied_time = None
|
||||
self._torque = np.zeros(len(names))
|
||||
|
||||
def reset(self, data, targets):
|
||||
self.model.dof_frictionloss[self.dofs] = self.initial_friction
|
||||
self.model.dof_damping[self.dofs] = self.initial_damping
|
||||
controller = self.controller
|
||||
controller.mujoco_data = data
|
||||
controller.model.reset()
|
||||
controller.last_ts = float(data.time)
|
||||
controller.q_target = np.asarray(targets).copy()
|
||||
self._applied_time = None
|
||||
self._torque[:] = 0
|
||||
data.ctrl[self.actuator_ids] = 0
|
||||
|
||||
def apply(self, data, targets):
|
||||
# step() and the physics loop both call apply(). Evaluating BAM twice
|
||||
# would update its state/friction twice for one physical sample.
|
||||
if self._applied_time != float(data.time):
|
||||
self.controller.mujoco_data = data
|
||||
self.controller.q_target = np.asarray(targets).copy()
|
||||
self.controller.update()
|
||||
self._torque = np.clip(data.ctrl[self.actuator_ids], -self.effort, self.effort)
|
||||
self._applied_time = float(data.time)
|
||||
data.ctrl[self.actuator_ids] = self._torque
|
||||
return data.ctrl.copy()
|
||||
@@ -9,7 +9,7 @@ import math
|
||||
from pathlib import Path
|
||||
import time
|
||||
|
||||
from .bundle import open_bundle, safe_path, write_json
|
||||
from .bundle import IK_MOUSE_HELP, open_bundle, safe_path, write_json
|
||||
|
||||
|
||||
class RobotApplication:
|
||||
@@ -270,11 +270,16 @@ def play(
|
||||
if headless:
|
||||
viewer = None
|
||||
else:
|
||||
mouse_ik = app.config.get("kind") == "ik" and command is None
|
||||
if mouse_ik:
|
||||
print(f"[play] {IK_MOUSE_HELP}", flush=True)
|
||||
viewer_keys.register(keys.report)
|
||||
stack.callback(viewer_keys.unregister, keys.report)
|
||||
viewer = stack.enter_context(
|
||||
mujoco.viewer.launch_passive(
|
||||
app.model, app.data, key_callback=viewer_keys.from_viewer
|
||||
app.model, app.data, key_callback=viewer_keys.from_viewer,
|
||||
# Keep the draggable marker visible in a narrow viewport.
|
||||
show_left_ui=not mouse_ik, show_right_ui=not mouse_ik,
|
||||
)
|
||||
)
|
||||
frames = []
|
||||
|
||||
@@ -142,6 +142,32 @@ class OnnxController:
|
||||
self.targets = self.home.copy()
|
||||
self.velocity_targets = np.zeros_like(self.home)
|
||||
self._configure_actuators(model)
|
||||
self.motor_model = None
|
||||
if "motor_model" in layout:
|
||||
from .motors import BamMotorModel
|
||||
|
||||
if not self.native or np.any(self.velocity_axes):
|
||||
raise ValueError("BAM requires native position actions")
|
||||
self.motor_model = BamMotorModel(
|
||||
model, self.actuators, self.effort[self.driven_idx], layout["motor_model"]
|
||||
)
|
||||
self.observation_frames = {}
|
||||
frames = observation.get("frames", {})
|
||||
if not isinstance(frames, Mapping) or set(frames) - names:
|
||||
raise ValueError("Observation frames must name observed vector terms")
|
||||
for term, frame in frames.items():
|
||||
if term not in {"base_ang_vel", "base_lin_vel", "projected_gravity"}:
|
||||
raise ValueError(f"{term} cannot declare an observation frame")
|
||||
if not isinstance(frame, Mapping) or set(frame) != {"kind", "name"}:
|
||||
raise ValueError("Observation frame requires kind and name")
|
||||
kind = frame["kind"]
|
||||
if kind not in {"body", "site"}:
|
||||
raise ValueError("Observation frame kind must be body or site")
|
||||
obj = mujoco.mjtObj.mjOBJ_BODY if kind == "body" else mujoco.mjtObj.mjOBJ_SITE
|
||||
index = object_id(model, obj, frame["name"])
|
||||
if kind == "body" and index == 0:
|
||||
raise ValueError("Observation body frame must identify a robot body")
|
||||
self.observation_frames[term] = (kind, index)
|
||||
|
||||
@staticmethod
|
||||
def _tensor_name(tensor, width: int, which: str) -> str:
|
||||
@@ -360,9 +386,28 @@ class OnnxController:
|
||||
self.operator.reset()
|
||||
for *_, history in self.terms:
|
||||
history.clear()
|
||||
self.apply(data)
|
||||
if self.motor_model is None:
|
||||
self.apply(data)
|
||||
else:
|
||||
self.motor_model.reset(data, self.targets[self.driven_idx])
|
||||
mujoco.mj_forward(self.model, data)
|
||||
|
||||
def reset_passive(self, data) -> None:
|
||||
"""Reset dynamic friction for an actuation-disabled counterfactual.
|
||||
|
||||
Preserve the supplied world state; policy state and targets from the
|
||||
active rollout must not influence the passive comparison.
|
||||
"""
|
||||
if self.motor_model is not None:
|
||||
self.motor_model.reset(data, data.qpos[self.qadr[self.driven_idx]])
|
||||
|
||||
def apply_passive(self, data) -> None:
|
||||
if self.motor_model is not None:
|
||||
if not self.model.opt.disableflags & mujoco.mjtDisableBit.mjDSBL_ACTUATION:
|
||||
raise ValueError("Passive motor update requires disabled actuation")
|
||||
self.motor_model.apply(data, data.qpos[self.qadr[self.driven_idx]])
|
||||
data.ctrl[self.actuators] = 0
|
||||
|
||||
def observation(self, data, command):
|
||||
mujoco.mj_forward(self.model, data)
|
||||
values = {
|
||||
@@ -383,6 +428,15 @@ class OnnxController:
|
||||
values["projected_gravity"] = data.xmat[self.root_body].reshape(3, 3).T @ np.asarray(
|
||||
[0.0, 0.0, -1.0]
|
||||
)
|
||||
for term, (kind, index) in self.observation_frames.items():
|
||||
if term == "projected_gravity":
|
||||
matrix = data.xmat[index] if kind == "body" else data.site_xmat[index]
|
||||
values[term] = matrix.reshape(3, 3).T @ np.asarray([0.0, 0.0, -1.0])
|
||||
else:
|
||||
velocity = np.zeros(6)
|
||||
obj = mujoco.mjtObj.mjOBJ_XBODY if kind == "body" else mujoco.mjtObj.mjOBJ_SITE
|
||||
mujoco.mj_objectVelocity(self.model, data, obj, index, velocity, 1)
|
||||
values[term] = velocity[:3] if term == "base_ang_vel" else velocity[3:]
|
||||
parts = []
|
||||
for name, indices, scale, clip, count, stride, history in self.terms:
|
||||
frame = values[name]
|
||||
@@ -446,6 +500,8 @@ class OnnxController:
|
||||
|
||||
def apply(self, data):
|
||||
i = self.driven_idx
|
||||
if self.motor_model is not None:
|
||||
return self.motor_model.apply(data, self.targets[i])
|
||||
torque = self.kp[i] * (self.targets[i] - data.qpos[self.qadr[i]])
|
||||
torque += self.kd[i] * (self.velocity_targets[i] - data.qvel[self.vadr[i]])
|
||||
data.ctrl[self.actuators] = np.clip(torque, -self.effort[i], self.effort[i])
|
||||
|
||||
+9
-30
@@ -31,8 +31,8 @@ __all__ = [
|
||||
def load_command_script(spec: str):
|
||||
"""`FILE[:NAME]` -> the callable `NAME` (default `script`) defined in `FILE`.
|
||||
|
||||
The file is loaded by path, not imported by name: a clip's script lives next
|
||||
to whatever draws the clip (`tools/readme_media.py`), which is not a package.
|
||||
The file is loaded by path, not imported by name, so standalone evaluation
|
||||
or video-capture scripts outside the package tree can be passed directly.
|
||||
"""
|
||||
path, sep, name = spec.rpartition(":")
|
||||
if not sep or not name.isidentifier():
|
||||
@@ -55,15 +55,10 @@ def script_commands(env, script) -> list[str]:
|
||||
"""Have command terms hold what `script` says, from each term's own `compute` on.
|
||||
|
||||
`script(t)` returns `{term name: values}` for `t` seconds since this was
|
||||
installed; it is written into each named term **after** the term's own
|
||||
`compute`, which is where the operator writes -- so a pad that is plugged in
|
||||
and nudged does not drive a scripted term, and the term's own bookkeeping
|
||||
(metrics, resample timers, the posture term's walking band) still runs.
|
||||
|
||||
Two kinds of term are understood: a velocity command (`vel_command_b`,
|
||||
three values) and a posture command (`posture_command`, four). A posture's
|
||||
height may be NaN, the term's own
|
||||
neutral height, or `(height, share)`, that share of the way there from it.
|
||||
installed; it is written into each named velocity command term (`vel_command_b`,
|
||||
three values) **after** the term's own `compute`, which is where the operator
|
||||
writes -- so a pad that is plugged in and nudged does not drive a scripted
|
||||
term, and the term's own bookkeeping (metrics, resample timers) still runs.
|
||||
"""
|
||||
import torch
|
||||
|
||||
@@ -79,8 +74,8 @@ def script_commands(env, script) -> list[str]:
|
||||
term = env.command_manager.get_term(name)
|
||||
except KeyError:
|
||||
raise ValueError(f"the task has no command term {name!r} to script") from None
|
||||
if not hasattr(term, "posture_command") and not hasattr(term, "vel_command_b"):
|
||||
raise ValueError(f"command term {name!r} is neither a velocity nor a posture "
|
||||
if not hasattr(term, "vel_command_b"):
|
||||
raise ValueError(f"command term {name!r} is not a velocity "
|
||||
"command; a script cannot drive it")
|
||||
_install(term, name, script, env, origin, step_dt, torch)
|
||||
return names
|
||||
@@ -93,18 +88,6 @@ def _install(term, name, script, env, origin, step_dt, torch) -> None:
|
||||
compute(dt, env_ids)
|
||||
t = (env.common_step_counter - origin) * step_dt
|
||||
values = list(script(t)[name])
|
||||
if hasattr(term, "posture_command"):
|
||||
rest = term.cfg.neutral_height
|
||||
height = values[3]
|
||||
if isinstance(height, tuple):
|
||||
values[3] = rest + (height[0] - rest) * height[1]
|
||||
elif math.isnan(height):
|
||||
values[3] = rest
|
||||
term.posture_command[:] = torch.tensor(
|
||||
values, device=term.device, dtype=torch.float32
|
||||
)
|
||||
term.hold_to_band()
|
||||
return
|
||||
columns = term.command.shape[1]
|
||||
if len(values) != columns:
|
||||
raise ValueError(f"a script of {len(values)} values for {name!r}, a command of "
|
||||
@@ -140,8 +123,7 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
|
||||
if ladder is not None:
|
||||
params = ladder.params or {}
|
||||
fractions, ceilings = params.get("fractions"), params.get("ceilings")
|
||||
levels, angles = params.get("levels"), params.get("ang_levels")
|
||||
level_count = len(fractions) if fractions else len(levels or ())
|
||||
level_count = len(fractions) if fractions else 0
|
||||
infos = checkpoint.get("infos") or {}
|
||||
curriculum = infos.get("curriculum") or {}
|
||||
saved = curriculum.get("command") or {}
|
||||
@@ -150,9 +132,6 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
|
||||
raise ValueError("checkpoint has no valid saved command curriculum level")
|
||||
if fractions and ceilings and len(ceilings) == 3:
|
||||
x, y, yaw = (float(value) * float(fractions[level]) for value in ceilings)
|
||||
elif levels and angles and len(levels) == len(angles):
|
||||
x = y = float(levels[level])
|
||||
yaw = float(angles[level])
|
||||
else:
|
||||
raise ValueError("unsupported command curriculum: no valid command range ladder")
|
||||
if not all(math.isfinite(value) for value in (x, y, yaw)) or x <= 0 or y < 0 or yaw <= 0:
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
"""Robot-independent stepping rewards for the biped recipe."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import torch
|
||||
from mjlab.tasks.velocity.mdp.rewards import feet_swing_height
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from mjlab.envs import ManagerBasedRlEnv
|
||||
|
||||
|
||||
class ActiveActionRate:
|
||||
"""Smooth policy channels that actually change physical targets.
|
||||
|
||||
Resolve the mask from each action term's runtime order, not RobotSpec
|
||||
order. Zero-scale channels still exist in observations and retain their PD
|
||||
home hold, but their raw policy variations cannot move a joint.
|
||||
"""
|
||||
|
||||
def __init__(self, cfg, env: ManagerBasedRlEnv):
|
||||
masks = []
|
||||
for name in env.action_manager.active_terms:
|
||||
term = env.action_manager.get_term(name)
|
||||
scale = torch.as_tensor(term.scale, device=env.device)
|
||||
if not torch.isfinite(scale).all():
|
||||
raise ValueError("Action scales must be finite")
|
||||
masks.append(torch.broadcast_to(scale != 0, term.raw_action.shape))
|
||||
self.active = torch.cat(masks, dim=-1)
|
||||
if self.active.shape != env.action_manager.action.shape:
|
||||
raise ValueError("Physical action mask must match the policy action layout")
|
||||
|
||||
def __call__(self, env: ManagerBasedRlEnv) -> torch.Tensor:
|
||||
delta = env.action_manager.action - env.action_manager.prev_action
|
||||
return (delta.square() * self.active).sum(dim=-1)
|
||||
|
||||
|
||||
def bounded_single_support(
|
||||
env: ManagerBasedRlEnv, sensor_name: str, command_name: str,
|
||||
) -> torch.Tensor:
|
||||
"""Credit one-foot support during a commanded, bounded-duration swing.
|
||||
|
||||
Contact slots belong to a foot, not separate supports. Both feet in stance,
|
||||
flight, and a foot held aloft beyond 0.4 seconds earn no credit. This is a
|
||||
running reward rate; the reward manager supplies the control timestep.
|
||||
"""
|
||||
sensor = env.scene[sensor_name]
|
||||
found = sensor.data.found
|
||||
air_time = sensor.data.current_air_time
|
||||
assert found is not None and air_time is not None
|
||||
if air_time.ndim != 2 or found.shape[:2] != air_time.shape:
|
||||
raise ValueError("support contact and airtime must share [environment, foot] axes")
|
||||
touching = (found > 0).reshape(*air_time.shape, -1).any(dim=-1)
|
||||
command = env.command_manager.get_command(command_name)
|
||||
assert command is not None
|
||||
moving = command[:, :2].norm(dim=-1) + command[:, 2].abs() > 0.05
|
||||
one_support = touching.sum(dim=-1) == 1
|
||||
swing = ((air_time > 0.05) & (air_time < 0.4)).any(dim=-1)
|
||||
return (moving & one_support & swing).float()
|
||||
|
||||
|
||||
class ResettableSwingHeight(feet_swing_height):
|
||||
"""Keep the reference landing cost while clearing peaks on episode reset.
|
||||
|
||||
The vendored reward retains per-foot peaks but has no reset hook. Without
|
||||
clearing selected rows, a terminated episode can affect its successor's
|
||||
first landing. The inherited landing formula and timestep scaling stay
|
||||
unchanged.
|
||||
"""
|
||||
|
||||
def reset(self, env_ids: torch.Tensor | slice | None = None) -> None:
|
||||
self.peak_heights[slice(None) if env_ids is None else env_ids] = 0.0
|
||||
|
||||
|
||||
def command_relative_linear_tracking(
|
||||
env: ManagerBasedRlEnv, command_name: str,
|
||||
minimum_width: float = 0.1,
|
||||
) -> torch.Tensor:
|
||||
"""Keep low-speed tracking meaningful while allowing wider high-speed error."""
|
||||
command = env.command_manager.get_command(command_name)
|
||||
assert command is not None
|
||||
actual = env.scene["robot"].data.root_link_lin_vel_b
|
||||
speed = command[:, :2].norm(dim=-1)
|
||||
width = (0.1 + 0.5 * speed).clamp(max=0.5)
|
||||
width = torch.where(speed > 0.05, width.clamp(min=minimum_width), width)
|
||||
error = (command[:, :2] - actual[:, :2]).square().sum(dim=-1) + actual[:, 2].square()
|
||||
return torch.exp(-error / width.square())
|
||||
|
||||
|
||||
def command_relative_angular_tracking(
|
||||
env: ManagerBasedRlEnv, command_name: str,
|
||||
minimum_width: float = 0.15,
|
||||
) -> torch.Tensor:
|
||||
"""Scale moving yaw tolerance while preserving the stationary noise floor."""
|
||||
command = env.command_manager.get_command(command_name)
|
||||
assert command is not None
|
||||
actual = env.scene["robot"].data.root_link_ang_vel_b
|
||||
# An additive floor made small nonzero turns too tolerant of undertracking.
|
||||
# Clamping preserves the zero-yaw floor without adding it to moving turns.
|
||||
width = (0.5 * command[:, 2].abs()).clamp(min=minimum_width, max=math.sqrt(0.5))
|
||||
yaw_error = (command[:, 2] - actual[:, 2]).square() / width.square()
|
||||
roll_pitch_error = actual[:, :2].square().sum(dim=-1) / 0.5
|
||||
return torch.exp(-yaw_error - roll_pitch_error)
|
||||
|
||||
|
||||
def translation_aware_angular_tracking(
|
||||
env: ManagerBasedRlEnv, command_name: str,
|
||||
linear_minimum_width: float = 0.1, translating_yaw_width: float = 0.15,
|
||||
) -> torch.Tensor:
|
||||
"""Reward the requested twist jointly when translation is commanded.
|
||||
|
||||
A robot standing still used to collect the entire heading reward while
|
||||
ignoring forward commands. Retain a small heading floor during exploration,
|
||||
and award the remainder in proportion to linear tracking. Pure turns and
|
||||
idle commands retain their original yaw objective and noise tolerance.
|
||||
"""
|
||||
command = env.command_manager.get_command(command_name)
|
||||
assert command is not None
|
||||
turning = command_relative_angular_tracking(env, command_name)
|
||||
translating = command[:, :2].norm(dim=-1) > 0.05
|
||||
if translating_yaw_width != 0.15:
|
||||
# Normal walking includes instantaneous pelvis heading oscillations.
|
||||
# Relax only translating commands; pure-turn and idle accuracy retain
|
||||
# their existing objective and still have separate native probes.
|
||||
translating_heading = command_relative_angular_tracking(
|
||||
env, command_name, minimum_width=translating_yaw_width,
|
||||
)
|
||||
turning = torch.where(translating, translating_heading, turning)
|
||||
linear = command_relative_linear_tracking(env, command_name, minimum_width=linear_minimum_width)
|
||||
multiplier = torch.where(translating, 0.2 + 0.8 * linear, torch.ones_like(linear))
|
||||
return turning * multiplier
|
||||
|
||||
|
||||
class CompletedSwingQuality:
|
||||
"""Bounded height/duration cost for a swing observed from takeoff to landing.
|
||||
|
||||
Each foot must first be observed grounded after reset. Contact events that
|
||||
never include an observed airborne sample, including reset-truncated swings,
|
||||
incur no cost. Each completed event is divided by control dt so the reward
|
||||
manager's integration leaves its magnitude independent of control rate.
|
||||
"""
|
||||
|
||||
def __init__(self, cfg, env: ManagerBasedRlEnv):
|
||||
for name in ("target_height", "target_swing_s"):
|
||||
value = cfg.params[name]
|
||||
if not math.isfinite(value) or value <= 0:
|
||||
raise ValueError(f"{name} must be finite and positive")
|
||||
minimum = cfg.params.get("minimum_motion_fraction", 1.0)
|
||||
if not math.isfinite(minimum) or not 0 < minimum <= 1:
|
||||
raise ValueError("minimum_motion_fraction must lie in (0, 1]")
|
||||
count = env.scene[cfg.params["height_sensor_name"]].num_frames
|
||||
self.peak_heights = torch.zeros((env.num_envs, count), device=env.device)
|
||||
self.armed = torch.zeros_like(self.peak_heights, dtype=torch.bool)
|
||||
self.in_swing = torch.zeros_like(self.armed)
|
||||
|
||||
def __call__(
|
||||
self, env: ManagerBasedRlEnv, sensor_name: str, height_sensor_name: str,
|
||||
target_height: float, target_swing_s: float, command_name: str,
|
||||
command_threshold: float = 0.05,
|
||||
minimum_motion_fraction: float = 1.0,
|
||||
) -> torch.Tensor:
|
||||
sensor = env.scene[sensor_name]
|
||||
found, duration = sensor.data.found, sensor.data.last_air_time
|
||||
assert found is not None and duration is not None
|
||||
heights = env.scene[height_sensor_name].data.heights
|
||||
if (heights.shape != self.peak_heights.shape or duration.shape != heights.shape
|
||||
or found.shape[:2] != heights.shape):
|
||||
raise ValueError("swing heights, airtime and contacts must share [environment, foot] axes")
|
||||
touching = (found > 0).reshape(*heights.shape, -1).any(dim=-1)
|
||||
taking_off = self.armed & ~touching & ~self.in_swing
|
||||
self.in_swing |= taking_off
|
||||
self.peak_heights = torch.where(taking_off, torch.zeros_like(heights), self.peak_heights)
|
||||
self.peak_heights = torch.where(
|
||||
self.in_swing & ~touching, torch.maximum(self.peak_heights, heights), self.peak_heights,
|
||||
)
|
||||
landed = self.in_swing & touching
|
||||
height_cost = (self.peak_heights / target_height - 1).square().clamp(max=4.0)
|
||||
duration_cost = (duration / target_swing_s - 1).square().clamp(max=4.0)
|
||||
command = env.command_manager.get_command(command_name)
|
||||
assert command is not None
|
||||
moving = command[:, :2].norm(dim=-1) + command[:, 2].abs() > command_threshold
|
||||
cost = ((height_cost + duration_cost) * landed).sum(dim=-1) / env.step_dt
|
||||
if minimum_motion_fraction < 1.0:
|
||||
# Preserve the small exploration cost while standing or initially
|
||||
# moving. Apply the full quality cost once command progress exists.
|
||||
# This adds no positive landing credit or cadence bonus.
|
||||
data = env.scene["robot"].data
|
||||
speed2 = command[:, :2].square().sum(dim=-1)
|
||||
linear = (data.root_link_lin_vel_b[:, :2] * command[:, :2]).sum(dim=-1)
|
||||
linear = linear / speed2.clamp(min=command_threshold ** 2)
|
||||
angular = data.root_link_ang_vel_b[:, 2] * command[:, 2]
|
||||
angular = angular / command[:, 2].square().clamp(min=command_threshold ** 2)
|
||||
progress = torch.where(speed2 > command_threshold ** 2, linear, angular).clamp(0, 1)
|
||||
cost *= minimum_motion_fraction + (1 - minimum_motion_fraction) * progress
|
||||
self.peak_heights = torch.where(touching, torch.zeros_like(heights), self.peak_heights)
|
||||
self.in_swing &= ~touching
|
||||
self.armed |= touching
|
||||
return cost * moving
|
||||
|
||||
def reset(self, env_ids: torch.Tensor | slice | None = None) -> None:
|
||||
selection = slice(None) if env_ids is None else env_ids
|
||||
self.peak_heights[selection] = 0.0
|
||||
self.armed[selection] = False
|
||||
self.in_swing[selection] = False
|
||||
@@ -0,0 +1,67 @@
|
||||
"""Training command distributions with explicit coverage of isolated axes."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
from dataclasses import dataclass
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import torch
|
||||
from mjlab.tasks.velocity.mdp.velocity_command import UniformVelocityCommand, UniformVelocityCommandCfg
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from mjlab.envs import ManagerBasedRlEnv
|
||||
|
||||
|
||||
@dataclass(kw_only=True)
|
||||
class AxisBalancedVelocityCommandCfg(UniformVelocityCommandCfg):
|
||||
"""Reserve a fraction of nonstanding commands for uniformly selected axes.
|
||||
|
||||
The remainder retains independent uniform sampling of all three axes.
|
||||
Standing probability is inherited and independent of this conditional
|
||||
fraction. Use this distribution for training, keeping replay's operator
|
||||
command unchanged.
|
||||
"""
|
||||
|
||||
isolated_axis_fraction: float = .3
|
||||
|
||||
def __post_init__(self):
|
||||
super().__post_init__()
|
||||
for name in ("isolated_axis_fraction", "rel_standing_envs", "init_velocity_prob"):
|
||||
value = getattr(self, name)
|
||||
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or not 0 <= value <= 1:
|
||||
raise ValueError(f"{name} must be a finite fraction in [0, 1]")
|
||||
if self.heading_command or self.ranges.heading is not None or self.rel_world_envs != 0 or self.rel_forward_envs != 0:
|
||||
raise ValueError("Axis-balanced commands require body-frame sampling without heading, world, or forward modes")
|
||||
for axis in ("lin_vel_x", "lin_vel_y", "ang_vel_z"):
|
||||
bounds = getattr(self.ranges, axis)
|
||||
if len(bounds) != 2 or any(isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) for v in bounds) or not bounds[0] <= 0 <= bounds[1]:
|
||||
raise ValueError(f"{axis} range must contain finite ordered bounds including zero")
|
||||
|
||||
def build(self, env: ManagerBasedRlEnv) -> AxisBalancedVelocityCommand:
|
||||
return AxisBalancedVelocityCommand(self, env)
|
||||
|
||||
|
||||
class AxisBalancedVelocityCommand(UniformVelocityCommand):
|
||||
cfg: AxisBalancedVelocityCommandCfg
|
||||
|
||||
def __init__(self, cfg: AxisBalancedVelocityCommandCfg, env: ManagerBasedRlEnv):
|
||||
cfg.__post_init__() # Also reject incompatible mutations made after config creation.
|
||||
super().__init__(cfg, env)
|
||||
|
||||
def _resample_command(self, env_ids: torch.Tensor) -> None:
|
||||
count = len(env_ids)
|
||||
values = torch.empty((count, 3), device=self.device)
|
||||
for column, axis in enumerate(("lin_vel_x", "lin_vel_y", "ang_vel_z")):
|
||||
values[:, column].uniform_(*getattr(self.cfg.ranges, axis))
|
||||
standing = torch.rand(count, device=self.device) < self.cfg.rel_standing_envs
|
||||
isolated = (torch.rand(count, device=self.device) < self.cfg.isolated_axis_fraction) & ~standing
|
||||
axes = torch.randint(3, (count,), device=self.device)
|
||||
keep = ~isolated[:, None] | (torch.arange(3, device=self.device)[None, :] == axes[:, None])
|
||||
values *= keep
|
||||
self.vel_command_b[env_ids] = values
|
||||
self.vel_command_w[env_ids] = values
|
||||
self.is_standing_env[env_ids] = standing
|
||||
self.is_heading_env[env_ids] = False
|
||||
self.is_world_env[env_ids] = False
|
||||
self.is_forward_env[env_ids] = False
|
||||
+20
-14
@@ -44,7 +44,8 @@ Nothing here is task-specific or robot-specific: the names come from the entity.
|
||||
|
||||
A live window is the right answer and is not always available: matplotlib needs
|
||||
an interactive backend, which needs a GUI toolkit, and a training box reached
|
||||
over SSH often has none. So this picks in order:
|
||||
over SSH often has none. When an interactive view is explicitly requested,
|
||||
this picks in order:
|
||||
|
||||
1. **a matplotlib window**, if an interactive backend imports -- three stacked
|
||||
panels, one line per joint, a rolling window;
|
||||
@@ -112,7 +113,7 @@ _BACKENDS = (
|
||||
#: not enough to find out whether a window can open.
|
||||
_PROBE = (
|
||||
"import matplotlib;matplotlib.use({backend!r});"
|
||||
"import matplotlib.pyplot as p;p.figure();p.close('all')"
|
||||
"import matplotlib.pyplot as p;p.ioff();p.figure();p.close('all')"
|
||||
)
|
||||
|
||||
|
||||
@@ -157,7 +158,8 @@ class JointMonitor:
|
||||
"""Collects and displays joint telemetry for one environment.
|
||||
|
||||
`update` is called once per control step from `play._loop`; `close` writes the
|
||||
artifacts. Construction decides the display, so a failure to open a window
|
||||
artifacts. An explicit `interactive=True` enables the live window.
|
||||
Construction decides the display, so a failure to open a window
|
||||
happens before the replay starts rather than a minute into it.
|
||||
"""
|
||||
|
||||
@@ -171,6 +173,8 @@ class JointMonitor:
|
||||
foot_names: "tuple[str, ...] | None" = None,
|
||||
window_s: float = WINDOW_S,
|
||||
refresh_hz: float = REFRESH_HZ,
|
||||
*,
|
||||
interactive: bool = False,
|
||||
) -> None:
|
||||
self.entity = entity
|
||||
self.index = index
|
||||
@@ -200,11 +204,11 @@ class JointMonitor:
|
||||
|
||||
self._fig = None
|
||||
self._lines: dict[str, list] = {}
|
||||
chosen = _interactive_backend()
|
||||
chosen = _interactive_backend() if interactive else None
|
||||
self._backend = None if chosen is None else chosen[0]
|
||||
if chosen is not None:
|
||||
self._open_window(*chosen)
|
||||
else:
|
||||
elif interactive:
|
||||
print(
|
||||
"[measure] no toolkit here can open a window, so the live view is "
|
||||
"a table (`pip install PyQt5` in the venv is usually enough). The "
|
||||
@@ -442,14 +446,13 @@ class JointMonitor:
|
||||
|
||||
def _write_png(self, path: Path) -> None:
|
||||
"""The whole run, not the rolling window -- this is the artifact."""
|
||||
import matplotlib
|
||||
|
||||
if self._fig is None:
|
||||
matplotlib.use("Agg")
|
||||
import matplotlib.pyplot as plt
|
||||
from matplotlib.backends.backend_agg import FigureCanvasAgg
|
||||
from matplotlib.figure import Figure
|
||||
|
||||
count = 4 if self.foot_names else 3
|
||||
fig, axes = plt.subplots(count, 1, sharex=True, figsize=(12, 3 * count))
|
||||
fig = Figure(figsize=(12, 3 * count))
|
||||
FigureCanvasAgg(fig)
|
||||
axes = fig.subplots(count, 1, sharex=True)
|
||||
panels = [
|
||||
(axes[0], self._pos, "position [rad]", self.joint_names),
|
||||
(axes[1], self._vel, "velocity [rad/s]", self.joint_names),
|
||||
@@ -474,10 +477,12 @@ class JointMonitor:
|
||||
fig.suptitle(title)
|
||||
fig.tight_layout()
|
||||
fig.savefig(path, dpi=120)
|
||||
plt.close(fig)
|
||||
|
||||
|
||||
def make_monitor(entity: Any, index: int, env, out_dir: Path) -> "JointMonitor | None":
|
||||
|
||||
def make_monitor(
|
||||
entity: Any, index: int, env, out_dir: Path, *, interactive: bool = False,
|
||||
) -> "JointMonitor | None":
|
||||
"""Build a monitor for an entity, or None if it has no joints to measure.
|
||||
|
||||
The entity is passed in rather than found here: `play.py` already picks the
|
||||
@@ -493,7 +498,8 @@ def make_monitor(entity: Any, index: int, env, out_dir: Path) -> "JointMonitor |
|
||||
return None
|
||||
unwrapped = getattr(env, "unwrapped", env)
|
||||
sensor, names = _find_foot_sensor(unwrapped)
|
||||
return JointMonitor(entity, index, unwrapped.step_dt, out_dir, sensor, names)
|
||||
return JointMonitor(entity, index, unwrapped.step_dt, out_dir, sensor, names,
|
||||
interactive=interactive)
|
||||
|
||||
|
||||
def _find_foot_sensor(env) -> "tuple[Any, tuple[str, ...]]":
|
||||
|
||||
+5
-5
@@ -14,8 +14,8 @@ file runs during `import scenes`, and `--list` has to stay usable on a machine
|
||||
without the simulation dependencies. `registry.load` imports the module.
|
||||
|
||||
`--scene` also takes a **path** to an imported `kk-scene-package/1` or `/2` --
|
||||
a directory, a `.zip` or a `.map` that scene-generator, kingkong_design's map
|
||||
library or this repository's own `scenes/tools/export_web_scene.py` wrote.
|
||||
a directory, a `.zip` or a `.map` written by an external scene generator or this
|
||||
repository's own `scenes/tools/export_web_scene.py`.
|
||||
`scripts/play.py` accepts one and `scripts/train.py` refuses it;
|
||||
`scenes/package.py` says why.
|
||||
|
||||
@@ -129,9 +129,9 @@ register(
|
||||
description="**changes the ground**: generated slopes, stairs and rough surface",
|
||||
tags=("terrain",),
|
||||
# A 10 x 7 grid of difficulty tiles with a flat control column, sized from
|
||||
# this robot's foot-lift height. An instrument for the curriculum to move
|
||||
# a robot through, not a place. Stairs worth walking on for fun would be a
|
||||
# new scene, not this one with its levels shipped.
|
||||
# explicit nominal terrain parameters. An instrument for the curriculum to
|
||||
# move a robot through, not a place. Stairs worth walking on for fun would
|
||||
# be a new scene, not this one with its levels shipped.
|
||||
use="training",
|
||||
)
|
||||
|
||||
|
||||
+1
-1
@@ -29,7 +29,7 @@ The sky is a **cube map** rather than a builtin gradient, because a builtin one
|
||||
runs from zenith to horizon and nothing else -- it cannot be warm on one side of
|
||||
the compass and cold on the other, which is most of what makes a low sun read as
|
||||
a low sun rather than as an orange filter over the whole world. The six faces are
|
||||
generated by `assets/scenes/beach/tools/make_skybox.py`, which draws the
|
||||
generated by `tools/make_skybox.py`, which draws the
|
||||
sun's disc into them as well, so the sun is where the light says it is rather
|
||||
than merely implied. That file holds the sun direction and **it has to stay the
|
||||
negation of the light's `dir` below**: disagreeing puts the bright part of the sky
|
||||
|
||||
+9
-10
@@ -5,11 +5,11 @@ another simulator can import, this one reads one somebody else wrote. The format
|
||||
is the same in both directions, which is the point -- a room exported by
|
||||
scene-generator and a pitch exported from here are the same kind of file.
|
||||
|
||||
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene
|
||||
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene.zip
|
||||
python scripts/play.py --task example_robot.flat --scene library/maps/bedroom.map
|
||||
python scripts/play.py --task go1_example --scene out/bedroom.scene
|
||||
python scripts/play.py --task go1_example --scene out/bedroom.scene.zip
|
||||
python scripts/play.py --task go1_example --scene library/maps/bedroom.map
|
||||
|
||||
`/2` is what kingkong_design's map library is written in: the `/1` world, plus
|
||||
`/2` is what the map library format is written in: the `/1` world, plus
|
||||
the robot the map was authored around (`robot/`) and a thumbnail (`preview/`).
|
||||
Both are verified like every other file and neither is loaded -- the robot here
|
||||
is the task's own, the one the policy was trained on -- and `spawn` becomes
|
||||
@@ -56,7 +56,7 @@ heading in **degrees** -- while the robot here starts where its task puts it, at
|
||||
the environment origin facing +X. So the world is attached in a frame that moves
|
||||
the spawn point to the origin and turns its heading onto +X, and the robot's
|
||||
initial state is left alone. Ignoring `spawn` is not a small offset: measured on
|
||||
kingkong_design's 13 maps (c655914), 6 put it away from the origin, and a robot at
|
||||
13 reference maps (c655914), 6 put it away from the origin, and a robot at
|
||||
the origin instead stands in a shelf (shelf-maze: 0.82 m of shelf within 0.25 m
|
||||
of it), on a 0.7 m ramp (switchback-slopes) or in bedroom furniture (0.45 m).
|
||||
|
||||
@@ -70,8 +70,7 @@ and shelf-maze (-0.03 m, 60%) are buried the same way.
|
||||
|
||||
It is not enough to delete the task's plane. Every robot task's
|
||||
`feet_ground_contact` sensor counts contacts with the **body** named `terrain`,
|
||||
so a foot on anything that lives elsewhere reads as a foot in the air -- and
|
||||
`example_robot.ref_free_jump` decides take-off and landing from that sensor. So every
|
||||
so a foot on anything that lives elsewhere reads as a foot in the air. So every
|
||||
geom of the package that collides and does not move -- the ground, and equally
|
||||
a start platform, a bridge deck, a ramp or a table top -- is rebuilt inside that
|
||||
body (`_Terrain`), the ground under the name `terrain` so that everything that
|
||||
@@ -96,7 +95,7 @@ from .registry import Scene
|
||||
__all__ = ["PackageError", "ScenePackage", "is_package_path", "load_package", "read_package"]
|
||||
|
||||
#: The versions this importer reads. An unknown one is refused rather than read
|
||||
#: as the nearest known one: kingkong_design's contract says a consumer that
|
||||
#: as the nearest known one: the package contract says a consumer that
|
||||
#: does not know a version must reject it.
|
||||
SCHEMAS = ("kk-scene-package/1", "kk-scene-package/2")
|
||||
MANIFEST = "scene-package.json"
|
||||
@@ -109,7 +108,7 @@ SUFFIX = ".map"
|
||||
#: collide on base names, and MuJoCo's asset lookup falls back to the base name.
|
||||
PLATFORM_DIR = "platforms/"
|
||||
#: What `/2` adds beside the world, kept out of the shared section for the same
|
||||
#: reason as `PLATFORM_DIR`: every map in kingkong_design's library carries both
|
||||
#: reason as `PLATFORM_DIR`: every `/2` map carries both
|
||||
#: `preview/preview.png` and `robot/preview/preview.png`, and the robot's meshes
|
||||
#: are free to share a base name with the world's. Only for `/2`, where the
|
||||
#: names mean this -- in a `/1` package `robot/` would be an ordinary directory.
|
||||
@@ -762,7 +761,7 @@ def _entities(package: ScenePackage) -> dict[str, Any]:
|
||||
"""The props that are their own file, as mjlab entities.
|
||||
|
||||
A prop carrying a `file` is the exporter saying it belongs **beside a robot**
|
||||
rather than in the room: kk-rl-mjlab writes its football that way because it
|
||||
rather than in the room: `mjrl-lab` writes its football that way because it
|
||||
places one per environment at that environment's origin. Rebuilding it as an
|
||||
entity is what makes the round trip a round trip -- exported from here,
|
||||
imported back, and placed the same way.
|
||||
|
||||
+1
-2
@@ -199,8 +199,7 @@ def scene(*, foot_bodies=()) -> Scene:
|
||||
variable, and if it also changed the lighting then "the robot walks
|
||||
differently here" would have two candidate explanations and no way to
|
||||
separate them by looking. Sharing the look makes `--scene soft` against no
|
||||
scene at all a one-variable comparison, in the same way `example_robot.flat` is a
|
||||
one-variable control for two of the gait tasks.
|
||||
scene at all a clean one-variable comparison.
|
||||
|
||||
The consequence to keep in mind: **the two are indistinguishable in a
|
||||
screenshot.** A frame from this scene and a frame from `default` differ only
|
||||
|
||||
+8
-11
@@ -213,11 +213,10 @@ FEATURES = "web"
|
||||
#:
|
||||
#: **Not only the crate's directory, either.** This was `Cargo.toml`,
|
||||
#: `Cargo.lock` and `src/` until 2026-09-28, and the controller was also built
|
||||
#: from files outside them: `build.rs`, which compiles in every task's deploy
|
||||
#: hook -- so a commit that changed only `tasks/example_robot/deploy/lib.rs`
|
||||
#: shipped a different arm under the previous commit's name, and an uncommitted
|
||||
#: one without `-dirty` -- the dictionary `src/vocabulary.rs` includes, the IDL
|
||||
#: the board's bus is generated from, and the NPU header `vendor/` holds.
|
||||
#: from files outside them: `build.rs`, which compiles in optional task deploy
|
||||
#: hooks (`tasks/**/deploy/lib.rs`), the dictionary `src/vocabulary.rs`
|
||||
#: includes, the IDL the board's bus is generated from, and the NPU header
|
||||
#: `vendor/` holds.
|
||||
#: `tests/test_bundle.py` holds this list to what rustc and `build.rs` actually
|
||||
#: read.
|
||||
SOURCES = (
|
||||
@@ -963,9 +962,8 @@ def write_reference(out: Path, extension: Path | None,
|
||||
|
||||
# The mode the cascade runs with nobody touching anything -- the one these
|
||||
# frames converge on and infer in -- rather than the first mode by name,
|
||||
# whose home may be another policy's entirely: `robot`'s `claw_left` sorts
|
||||
# first and carries an arm 1.6 rad from the walking stance, so the frames
|
||||
# converged on a pose the warm start never reaches and not one inferred.
|
||||
# whose home pose may belong to another policy entirely, so the frames
|
||||
# would converge on a pose the warm start never reaches.
|
||||
import tomllib
|
||||
|
||||
cfg = tomllib.loads((out / "controller.toml").read_text("utf-8")).get("fsm", {})
|
||||
@@ -1507,8 +1505,7 @@ def assemble(out: Path, modes: dict[str, Path], fsm_path: Path | None, meta: dic
|
||||
if name.endswith(f"/{BOARD_BINARY}"):
|
||||
(out / name).chmod(0o755)
|
||||
|
||||
# One copy of a model per export directory. `claw_left` and `claw_right`
|
||||
# are one export carried on two sides, and shipped them twice.
|
||||
# One copy of a model per export directory when two modes share an export.
|
||||
stored: dict[Path, dict[str, str]] = {}
|
||||
listed: dict[str, dict] = {}
|
||||
unconverted: list[str] = []
|
||||
@@ -2074,7 +2071,7 @@ def validate_app(out: Path) -> None:
|
||||
#: be held against the one shipped last week.
|
||||
ZIP_EPOCH = (1980, 1, 1, 0, 0, 0)
|
||||
|
||||
#: What a bundle's archive is called: `robot/` travels as `example_robot.app`.
|
||||
#: What a bundle's archive is called: `<bundle_id>/` travels as `<bundle_id>.app`.
|
||||
#:
|
||||
#: The bytes are an ordinary zip, and any zip reader opens one. The name says
|
||||
#: what the file is rather than how it is packed, as `.jar` does for a zip of
|
||||
|
||||
+2
-1
@@ -58,7 +58,8 @@ def _parser() -> argparse.ArgumentParser:
|
||||
setup.add_argument("--output", "--out", required=True, type=Path, help="output directory")
|
||||
|
||||
extract = commands.add_parser("extract-tier1", help="extract and review upstream policy metadata")
|
||||
extract.add_argument("configs", nargs="+", type=Path, help="YAML, JSON or Python training configs")
|
||||
extract.add_argument("configs", nargs="*", type=Path,
|
||||
help="YAML, JSON or Python training configs; omit with --model for facts only")
|
||||
extract.add_argument("--output", "--out", required=True, type=Path, help="new draft directory")
|
||||
extract.add_argument("--model", type=Path, help="MJCF model for metadata validation")
|
||||
extract.add_argument("--overrides", type=Path, help="reviewed JSON/YAML field overrides")
|
||||
|
||||
+13
-13
@@ -11,10 +11,10 @@ choices for both. The backend comes from `--backend` / `--device`, or is
|
||||
auto-detected, exactly as in train.
|
||||
|
||||
The environment is built in **replay mode** (`play=True`): external disturbances
|
||||
are off and episodes run on rather than timing out (the one-shot jumps keep
|
||||
theirs, so a replay loops whole attempts), so what you see is the policy rather
|
||||
than the randomisation. Observation noise is the exception: `--obs-noise`, on by
|
||||
default, puts training's back, because a clean replay flatters the policy.
|
||||
are off and episodes run on rather than timing out, so what you see is the
|
||||
policy rather than the randomisation. Observation noise is the exception:
|
||||
`--obs-noise`, on by default, puts training's back, because a clean replay
|
||||
flatters the policy.
|
||||
|
||||
A replay is **one environment** unless `--num_envs` or `MJRL_PLAY_NUM_ENVS` says
|
||||
otherwise. `MJRL_NUM_ENVS` is training's batch size, and play does not read it.
|
||||
@@ -43,14 +43,13 @@ without a display needs ``MUJOCO_GL=egl`` set before Python starts):
|
||||
python scripts/play.py --checkpoint <path>/model_N.pt --headless \
|
||||
--steps 500 --video replay.mp4 --video-fps 30
|
||||
|
||||
**It is the one MP4 recorder** (`mjrl/viewer/video.py`): the README clips, the
|
||||
dance export and the Colab notebook all run this command rather than drawing for
|
||||
themselves. The camera is placed from the robot's first frame (`--video-azimuth`,
|
||||
`--video-elevation`, `--no-video-follow`), `--stop-on-done` records one attempt
|
||||
of a one-shot motion rather than looping it, and `--command-script` hands the
|
||||
command terms a script of time where the README clips need a walk that starts and
|
||||
a posture that changes -- written where the operator writes, so the pad does not
|
||||
drive a scripted term.
|
||||
**It is the one MP4 recorder** (`mjrl/viewer/video.py`): evaluation clips and
|
||||
the Colab notebook all run this command rather than drawing for themselves. The
|
||||
camera is placed from the robot's first frame (`--video-azimuth`,
|
||||
`--video-elevation`, `--no-video-follow`), `--stop-on-done` stops when an
|
||||
episode terminates, and `--command-script` hands the command terms a script of
|
||||
time -- written where the operator writes, so a connected pad does not drive a
|
||||
scripted term.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -512,7 +511,8 @@ def _run(spec, res, asset: Path | None, args) -> None:
|
||||
from mjrl.viewer.monitor import make_monitor
|
||||
|
||||
out = (ckpt.parent if trained else Path.cwd()) / "measure"
|
||||
monitor = make_monitor(*_watched(wrapped), wrapped, out)
|
||||
monitor = make_monitor(*_watched(wrapped), wrapped, out,
|
||||
interactive=not args.headless)
|
||||
if monitor is None:
|
||||
print("[measure] this scene has no entity with joints; nothing to measure")
|
||||
|
||||
|
||||
+1
-2
@@ -13,8 +13,7 @@ from pathlib import Path
|
||||
#: The repository root. This file lives in `tasks/`, hence one level up.
|
||||
REPO_ROOT: Path = Path(__file__).resolve().parents[1]
|
||||
|
||||
#: The model asset root. One subdirectory per asset, each with its own `tools/`
|
||||
#: for generation and calibration scripts.
|
||||
#: The model asset root. One subdirectory per robot asset.
|
||||
ASSETS_DIR: Path = REPO_ROOT / "assets"
|
||||
|
||||
#: The training log root directory name. Relative to the **current working
|
||||
|
||||
+17
-6
@@ -42,18 +42,22 @@ class JointSpec:
|
||||
kp: float
|
||||
kd: float
|
||||
effort_limit: float
|
||||
action_scale: float
|
||||
action_scale: float # Zero holds a position actuator at its calibrated home.
|
||||
home: float = 0.0
|
||||
armature: float = 0.0
|
||||
posture_std: float = 0.35
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
_names("joint", (self.name,))
|
||||
_number(f"{self.name}.kp", self.kp, minimum=0.0)
|
||||
_number(f"{self.name}.kd", self.kd, minimum=0.0)
|
||||
_number(f"{self.name}.effort_limit", self.effort_limit, minimum=1e-12)
|
||||
_number(f"{self.name}.action_scale", self.action_scale, minimum=1e-12)
|
||||
_number(f"{self.name}.action_scale", self.action_scale, minimum=0.0)
|
||||
_number(f"{self.name}.home", self.home)
|
||||
_number(f"{self.name}.armature", self.armature, minimum=0.0)
|
||||
_number(f"{self.name}.posture_std", self.posture_std, minimum=0.0)
|
||||
if self.posture_std <= 0:
|
||||
raise ValueError(f"{self.name}.posture_std must be positive")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -72,6 +76,7 @@ class RobotSpec:
|
||||
foot_bodies: tuple[str, ...] = ()
|
||||
penalized_contact_geoms: tuple[str, ...] = ()
|
||||
termination_contact_geoms: tuple[str, ...] = ()
|
||||
foot_sites: tuple[str, ...] = ()
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if (
|
||||
@@ -89,10 +94,14 @@ class RobotSpec:
|
||||
raise ValueError("controls_path must be a Path or None")
|
||||
_names("base_body", (self.base_body,))
|
||||
_number("base_height", self.base_height, minimum=1e-12)
|
||||
for key in ("foot_geoms", "foot_bodies", "penalized_contact_geoms", "termination_contact_geoms"):
|
||||
if not isinstance(self.foot_sites, (list, tuple)):
|
||||
raise ValueError("foot_sites must be a list or tuple of names")
|
||||
for key in ("foot_geoms", "foot_bodies", "foot_sites", "penalized_contact_geoms", "termination_contact_geoms"):
|
||||
_names(key, getattr(self, key))
|
||||
if bool(self.foot_geoms) == bool(self.foot_bodies):
|
||||
raise ValueError("declare either foot_geoms or foot_bodies")
|
||||
if self.foot_sites and len(self.foot_sites) != len(self.foot_geoms or self.foot_bodies):
|
||||
raise ValueError("foot_sites must have one site per named foot support")
|
||||
min_contacts = {"biped": 2, "quadruped": 4, "wheeled_biped": 2, "multipod": 5}
|
||||
if len(self.foot_geoms or self.foot_bodies) < min_contacts[self.family]:
|
||||
raise ValueError(f"{self.family} requires at least {min_contacts[self.family]} supports")
|
||||
@@ -102,11 +111,13 @@ class RobotSpec:
|
||||
_names("position_joints and velocity_joints", tuple(j.name for j in self.joints))
|
||||
if not self.position_joints or any(j.kp <= 0 for j in self.position_joints):
|
||||
raise ValueError("position_joints must contain joints with kp > 0")
|
||||
if not any(j.action_scale > 0 for j in self.joints):
|
||||
raise ValueError("at least one joint must have a positive action_scale")
|
||||
if self.family == "wheeled_biped":
|
||||
if len(self.velocity_joints) < 2 or any(
|
||||
j.kp != 0 or j.kd <= 0 for j in self.velocity_joints
|
||||
j.kp != 0 or j.kd <= 0 or j.action_scale <= 0 for j in self.velocity_joints
|
||||
):
|
||||
raise ValueError("wheeled_biped requires at least two velocity joints with kp=0, kd>0")
|
||||
raise ValueError("wheeled_biped requires at least two velocity joints with kp=0, kd>0, action_scale>0")
|
||||
elif self.velocity_joints:
|
||||
raise ValueError("velocity_joints are supported by wheeled_biped only")
|
||||
|
||||
@@ -121,7 +132,7 @@ class RobotSpec:
|
||||
for key in ("model_path", "controls_path"):
|
||||
if key in data and data[key] is not None:
|
||||
data[key] = (base_dir / Path(data[key])).resolve()
|
||||
for key in ("foot_geoms", "foot_bodies", "penalized_contact_geoms", "termination_contact_geoms"):
|
||||
for key in ("foot_geoms", "foot_bodies", "foot_sites", "penalized_contact_geoms", "termination_contact_geoms"):
|
||||
if key in data:
|
||||
if not isinstance(data[key], (tuple, list)):
|
||||
raise ValueError(f"{key} must be a list or tuple of names")
|
||||
|
||||
@@ -7,7 +7,10 @@ _RECIPE = LocomotionRecipe(
|
||||
command_ceiling=(0.7, 0.35, 0.8),
|
||||
fall_angle_deg=55.0,
|
||||
upright_weight=1.4,
|
||||
air_time_weight=0.2,
|
||||
air_time_weight=0.0,
|
||||
# With posture and clearance costs, tiny commands favor standing. Train
|
||||
# the full velocity range from the start.
|
||||
command_fractions=(1.0,),
|
||||
)
|
||||
|
||||
|
||||
|
||||
+142
-14
@@ -25,7 +25,7 @@ from mjlab.managers import (
|
||||
from mjlab.managers.scene_entity_config import SceneEntityCfg
|
||||
from mjlab.rl import RslRlModelCfg, RslRlOnPolicyRunnerCfg
|
||||
from mjlab.scene import SceneCfg
|
||||
from mjlab.sensor import ContactMatch, ContactSensorCfg
|
||||
from mjlab.sensor import ContactMatch, ContactSensorCfg, ObjRef, RingPatternCfg, TerrainHeightSensorCfg
|
||||
from mjlab.sim import MujocoCfg, SimulationCfg
|
||||
from mjlab.tasks.velocity import mdp as velocity_mdp
|
||||
from mjlab.terrains import TerrainEntityCfg
|
||||
@@ -34,6 +34,14 @@ from mjlab.viewer import ViewerConfig
|
||||
|
||||
from controller.controls import controller_contract, load_controls
|
||||
from mjrl.tasks.curriculum import CommandRangeCurriculum
|
||||
from mjrl.tasks.biped import (
|
||||
ActiveActionRate,
|
||||
CompletedSwingQuality,
|
||||
bounded_single_support,
|
||||
command_relative_linear_tracking,
|
||||
translation_aware_angular_tracking,
|
||||
)
|
||||
from mjrl.tasks.commands import AxisBalancedVelocityCommandCfg
|
||||
from mjrl.tasks.mdp import (
|
||||
actuator_force,
|
||||
base_roll_pitch_velocity,
|
||||
@@ -63,6 +71,7 @@ class LocomotionRecipe:
|
||||
fall_angle_deg: float
|
||||
upright_weight: float
|
||||
air_time_weight: float
|
||||
command_fractions: tuple[float, ...] = _FRACTIONS
|
||||
|
||||
|
||||
def _load_model(
|
||||
@@ -91,9 +100,9 @@ def _load_model(
|
||||
# The robot supplies geometry and dynamics. The calibrated spec supplies
|
||||
# actuator gains and the home state, so remove the authored copies first.
|
||||
for actuator in list(spec.actuators):
|
||||
actuator.delete()
|
||||
spec.delete(actuator)
|
||||
for key in list(spec.keys):
|
||||
key.delete()
|
||||
spec.delete(key)
|
||||
model = spec.compile()
|
||||
|
||||
joints = {joint.name: joint for joint in robot.joints}
|
||||
@@ -118,7 +127,28 @@ def _load_model(
|
||||
if missing := joints.keys() - homes.keys():
|
||||
raise ValueError(f"{path}: missing calibrated joints {sorted(missing)}")
|
||||
|
||||
return spec, _contact_geoms(model, path, robot), homes
|
||||
support_geoms = _contact_geoms(model, path, robot)
|
||||
_ordered_foot_sites(model, robot)
|
||||
return spec, support_geoms, homes
|
||||
|
||||
|
||||
def _ordered_foot_sites(model: mujoco.MjModel, robot: RobotSpec) -> tuple[str, ...]:
|
||||
"""Align sole markers to contact slots, which follow compiled model order."""
|
||||
if not robot.foot_sites:
|
||||
return ()
|
||||
mode = mujoco.mjtObj.mjOBJ_BODY if robot.foot_bodies else mujoco.mjtObj.mjOBJ_GEOM
|
||||
supports = robot.foot_bodies or robot.foot_geoms
|
||||
ordered = []
|
||||
for support, site_name in zip(supports, robot.foot_sites, strict=True):
|
||||
support_id = mujoco.mj_name2id(model, mode, support)
|
||||
site_id = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_SITE, site_name)
|
||||
if site_id < 0:
|
||||
raise ValueError(f"missing foot site {site_name!r}")
|
||||
body_id = support_id if robot.foot_bodies else int(model.geom_bodyid[support_id])
|
||||
if int(model.site_bodyid[site_id]) != body_id:
|
||||
raise ValueError(f"foot site {site_name!r} must be on its support {support!r}")
|
||||
ordered.append((support_id, site_name))
|
||||
return tuple(name for _, name in sorted(ordered))
|
||||
|
||||
|
||||
def _contact_geoms(model: mujoco.MjModel, path: Path, robot: RobotSpec) -> tuple[str, ...]:
|
||||
@@ -155,7 +185,20 @@ def validate_robot_model(robot: RobotSpec, asset: Path | None = None) -> None:
|
||||
|
||||
|
||||
def _entity_spec(path: Path, robot: RobotSpec) -> mujoco.MjSpec:
|
||||
return _load_model(path, robot)[0]
|
||||
spec = _load_model(path, robot)[0]
|
||||
if robot.family == "biped" and robot.foot_sites:
|
||||
# Terrain scans select group 0. Rendering groups do not alter contact
|
||||
# masks; keep robot colliders out of terrain-only height measurements.
|
||||
for geom in spec.geoms:
|
||||
if geom.contype or geom.conaffinity:
|
||||
geom.group = 3
|
||||
elif geom.group == 0:
|
||||
geom.group = 1
|
||||
spec.add_sensor(
|
||||
name="mjrl_root_angmom", type=mujoco.mjtSensor.mjSENS_SUBTREEANGMOM,
|
||||
objtype=mujoco.mjtObj.mjOBJ_BODY, objname=robot.base_body,
|
||||
)
|
||||
return spec
|
||||
|
||||
|
||||
def _patterns(names) -> tuple[str, ...]:
|
||||
@@ -254,8 +297,11 @@ def _observations(robot: RobotSpec, play: bool):
|
||||
|
||||
|
||||
def _commands(robot: RobotSpec, recipe: LocomotionRecipe, play: bool):
|
||||
command_cls = velocity_mdp.UniformVelocityCommandCfg
|
||||
fraction = 1.0 if play else _FRACTIONS[0]
|
||||
command_cls = (
|
||||
AxisBalancedVelocityCommandCfg if robot.family == "biped" and not play
|
||||
else velocity_mdp.UniformVelocityCommandCfg
|
||||
)
|
||||
fraction = 1.0 if play else recipe.command_fractions[0]
|
||||
x, y, yaw = (value * fraction for value in recipe.command_ceiling)
|
||||
kwargs = {
|
||||
"entity_name": "robot",
|
||||
@@ -358,18 +404,21 @@ def _contact_penalty(env, sensor_name: str | None) -> torch.Tensor:
|
||||
return _contact_hit(env, sensor_name).float()
|
||||
|
||||
|
||||
def _contact_sensor(name: str, mode: str, patterns: tuple[str, ...], air_time: bool = False):
|
||||
def _contact_sensor(
|
||||
name: str, mode: str, patterns: tuple[str, ...], air_time: bool = False,
|
||||
forces: bool = False,
|
||||
):
|
||||
return ContactSensorCfg(
|
||||
name=name,
|
||||
primary=ContactMatch(mode=mode, pattern=_patterns(patterns), entity="robot"),
|
||||
secondary=ContactMatch(mode="body", pattern="terrain"),
|
||||
fields=("found",),
|
||||
fields=("found", "force") if forces else ("found",),
|
||||
track_air_time=air_time,
|
||||
reduce="maxforce",
|
||||
reduce="netforce" if forces else "maxforce",
|
||||
)
|
||||
|
||||
|
||||
def _rewards(robot: RobotSpec, recipe: LocomotionRecipe):
|
||||
def _rewards(robot: RobotSpec, recipe: LocomotionRecipe, foot_sites: tuple[str, ...] = ()):
|
||||
leg_joints = _joint_selection(robot.position_joints)
|
||||
rewards = {
|
||||
"track_linear_velocity": RewardTermCfg(
|
||||
@@ -422,6 +471,76 @@ def _rewards(robot: RobotSpec, recipe: LocomotionRecipe):
|
||||
"command_name": _COMMAND, "command_threshold": 0.08,
|
||||
},
|
||||
)
|
||||
if robot.family == "biped":
|
||||
# Keep robot-specific homes and named posture tolerances in RobotSpec.
|
||||
rewards["track_linear_velocity"].weight = 3.0
|
||||
rewards["track_linear_velocity"].func = command_relative_linear_tracking
|
||||
rewards["track_linear_velocity"].params = {"command_name": _COMMAND, "minimum_width": 0.35}
|
||||
rewards["track_angular_velocity"] = RewardTermCfg(
|
||||
# Keep pure-turn incentive, but do not award full heading credit
|
||||
# to a stationary robot ignoring a simultaneous translation.
|
||||
func=translation_aware_angular_tracking, weight=3.0,
|
||||
params={"command_name": _COMMAND, "linear_minimum_width": 0.35,
|
||||
"translating_yaw_width": 0.5},
|
||||
)
|
||||
rewards.pop("joint_home")
|
||||
moving_std = {re.escape(joint.name): joint.posture_std for joint in robot.position_joints}
|
||||
rewards["pose"] = RewardTermCfg(
|
||||
func=velocity_mdp.variable_posture, weight=0.5,
|
||||
params={
|
||||
"asset_cfg": leg_joints, "command_name": _COMMAND,
|
||||
"std_standing": {".*": 0.1},
|
||||
"std_walking": moving_std, "std_running": moving_std.copy(),
|
||||
"walking_threshold": 0.05, "running_threshold": 1.5,
|
||||
},
|
||||
)
|
||||
# Smooth physical action channels; held joints must not dominate this
|
||||
# budget while rapid hip/knee targets are filtered by passive damping.
|
||||
rewards["action_rate"] = RewardTermCfg(func=ActiveActionRate, weight=-0.03)
|
||||
# Natural-gait revision: raw squared torque disproportionately taxes
|
||||
# high-effort hip/knee swing compared with low-effort ankle rocking.
|
||||
# Preserve effort limits and native saturation gates; reduce this cost.
|
||||
rewards["leg_torque"].weight = -1.0e-6
|
||||
rewards.pop("swing_air_time", None)
|
||||
rewards["single_support"] = RewardTermCfg(
|
||||
func=bounded_single_support, weight=0.5,
|
||||
params={"sensor_name": _SUPPORT_SENSOR, "command_name": _COMMAND},
|
||||
)
|
||||
if foot_sites:
|
||||
# Sole height is relative to the actual terrain ray hit, not world Z.
|
||||
sole_selection = SceneEntityCfg("robot", site_names=_patterns(foot_sites), preserve_order=True)
|
||||
height = min(0.08, 0.1 * robot.base_height)
|
||||
rewards.pop("support_slip")
|
||||
rewards["foot_clearance"] = RewardTermCfg(
|
||||
func=velocity_mdp.feet_clearance, weight=-2.0,
|
||||
params={"target_height": height, "height_sensor_name": "sole_height",
|
||||
"command_name": _COMMAND, "command_threshold": 0.05,
|
||||
"asset_cfg": sole_selection},
|
||||
)
|
||||
rewards["swing_quality"] = RewardTermCfg(
|
||||
# Integrated landing cost. Keep the initial exploration budget
|
||||
# at .005, then strengthen quality with actual command progress.
|
||||
func=CompletedSwingQuality, weight=-0.03,
|
||||
params={"target_height": height, "height_sensor_name": "sole_height",
|
||||
"sensor_name": _SUPPORT_SENSOR, "command_name": _COMMAND,
|
||||
"command_threshold": 0.05,
|
||||
"target_swing_s": 0.24 * math.sqrt(robot.base_height / 0.68),
|
||||
"minimum_motion_fraction": 1.0 / 6.0},
|
||||
)
|
||||
rewards["foot_slip"] = RewardTermCfg(
|
||||
func=velocity_mdp.feet_slip, weight=-0.1,
|
||||
params={"sensor_name": _SUPPORT_SENSOR, "command_name": _COMMAND,
|
||||
"command_threshold": 0.05, "asset_cfg": sole_selection},
|
||||
)
|
||||
rewards["soft_landing"] = RewardTermCfg(
|
||||
func=velocity_mdp.soft_landing, weight=-1e-5,
|
||||
params={"sensor_name": _SUPPORT_SENSOR, "command_name": _COMMAND,
|
||||
"command_threshold": 0.05},
|
||||
)
|
||||
rewards["angular_momentum"] = RewardTermCfg(
|
||||
func=velocity_mdp.angular_momentum_penalty, weight=-0.01,
|
||||
params={"sensor_name": "robot/mjrl_root_angmom"},
|
||||
)
|
||||
return rewards
|
||||
|
||||
|
||||
@@ -431,7 +550,8 @@ def env_cfg(
|
||||
if robot.family != recipe.family:
|
||||
raise ValueError(f"{recipe.family} template cannot use a {robot.family} robot spec")
|
||||
path = asset or robot.model_path
|
||||
_, support_geoms, homes = _load_model(path, robot)
|
||||
spec, support_geoms, homes = _load_model(path, robot)
|
||||
foot_sites = _ordered_foot_sites(spec.compile(), robot) if robot.family == "biped" else ()
|
||||
commands, controls = _commands(robot, recipe, play)
|
||||
sensors = [
|
||||
_contact_sensor(
|
||||
@@ -439,8 +559,16 @@ def env_cfg(
|
||||
"body" if robot.foot_bodies else "geom",
|
||||
robot.foot_bodies or robot.foot_geoms,
|
||||
air_time=True,
|
||||
forces=bool(foot_sites),
|
||||
)
|
||||
]
|
||||
if foot_sites:
|
||||
sensors.append(TerrainHeightSensorCfg(
|
||||
name="sole_height",
|
||||
frame=tuple(ObjRef(type="site", name=name, entity="robot") for name in foot_sites),
|
||||
pattern=RingPatternCfg.single_ring(radius=0.025, num_samples=4),
|
||||
max_distance=1.0, include_geom_groups=(0,), exclude_parent_body=True,
|
||||
))
|
||||
for name, geoms in (
|
||||
(_PENALIZED_SENSOR, robot.penalized_contact_geoms),
|
||||
(_TERMINATION_SENSOR, robot.termination_contact_geoms),
|
||||
@@ -459,7 +587,7 @@ def env_cfg(
|
||||
actions=_actions(robot),
|
||||
commands=commands,
|
||||
events=_events(robot, play, support_geoms),
|
||||
rewards=_rewards(robot, recipe),
|
||||
rewards=_rewards(robot, recipe, foot_sites),
|
||||
terminations={
|
||||
"time_out": TerminationTermCfg(func=mdp.time_out, time_out=True),
|
||||
"undesired_contact": TerminationTermCfg(
|
||||
@@ -476,7 +604,7 @@ def env_cfg(
|
||||
"command": CurriculumTermCfg(
|
||||
func=CommandRangeCurriculum,
|
||||
params={
|
||||
"fractions": _FRACTIONS, "ceilings": recipe.command_ceiling,
|
||||
"fractions": recipe.command_fractions, "ceilings": recipe.command_ceiling,
|
||||
"command_name": _COMMAND, "dwell_steps": 2400,
|
||||
"min_steps": 200, "min_samples": 16, "gate_ratio": 0.4, "ema_alpha": 0.15,
|
||||
},
|
||||
|
||||
@@ -177,6 +177,26 @@ def test_adapter_writes_valid_bindings_only_for_supported_command_ranges(tmp_pat
|
||||
"layout": "layout.json",
|
||||
}
|
||||
|
||||
# New metadata defaults to A/D yaw. An explicit pre-WASD contract
|
||||
# regenerates its original keys and file bytes, including its ramp rate.
|
||||
import yaml
|
||||
from controller.controls import controller_contract
|
||||
from mjrl.controllers.bindings import velocity_controls
|
||||
|
||||
assert "key_a" in controls.key_axes["ang_vel_z"].plus
|
||||
previous = tmp_path / "controls.yaml"
|
||||
previous.write_text(yaml.safe_dump(velocity_controls(tuple(controls.bindings)), sort_keys=False))
|
||||
meta["controller"] = controller_contract(load_controls(previous), None)
|
||||
restored = adapt_policy(source, meta, tmp_path / "previous")
|
||||
assert restored.controls.read_bytes() == previous.read_bytes()
|
||||
assert json.loads(restored.layout.read_text())["controller"] == meta["controller"]
|
||||
assert load_controls(restored.controls).key_axes["ang_vel_z"].plus == ("key_j",)
|
||||
meta["controller"]["devices"]["keyboard"]["full_after_s"] = 3.75
|
||||
rejected = tmp_path / "mismatch"
|
||||
with pytest.raises(ValueError, match="differs from generated controls"):
|
||||
adapt_policy(source, meta, rejected)
|
||||
assert not rejected.exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("observes_commands", [False, True])
|
||||
def test_adapted_fixed_jit_runs_verified_native_application(tmp_path, observes_commands):
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
"""Calibrated actuator and sensor semantics survive metadata review/export."""
|
||||
import copy
|
||||
import json
|
||||
|
||||
import mujoco
|
||||
import pytest
|
||||
|
||||
from mjrl.adapter import build_layout
|
||||
from mjrl.onboarding.upstream import extract_policy_metadata
|
||||
|
||||
|
||||
def metadata():
|
||||
return {
|
||||
"schema": "mjrl-policy-adapter/1",
|
||||
"wire_joint_order": ["joint"], "obs_joint_order": ["joint"],
|
||||
"action_joint_order": ["joint"], "default_joint_pos": {"joint": 0},
|
||||
"joint_limits": {"joint": [-1, 1]}, "action_scale": 1,
|
||||
"control": {"kp": 1, "kd": 0, "effort_limit": 0.64, "control_hz": 50},
|
||||
"observation": {
|
||||
"terms": [{"name": "base_ang_vel"}, {"name": "joint_pos"}],
|
||||
"frames": {"base_ang_vel": {"kind": "site", "name": "imu"}},
|
||||
},
|
||||
"motor_model": {
|
||||
"kind": "bam", "motor_name": "xl330", "model": "m6", "kp": 100,
|
||||
"vin": 7.0, "max_current": 1.5, "vin_drop_resistance": 0.1, "vin_min": 6,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def test_calibrated_metadata_roundtrip(tmp_path):
|
||||
doc = metadata()
|
||||
source = tmp_path / "reviewed.json"
|
||||
source.write_text(json.dumps(doc))
|
||||
report = extract_policy_metadata([source])
|
||||
assert report["ready"], report
|
||||
assert report["metadata"] == doc
|
||||
layout = build_layout(report["metadata"])
|
||||
assert layout["_schema"] == "mjrl-native-layout/1"
|
||||
assert layout["motor_model"] == doc["motor_model"]
|
||||
assert layout["observation"]["frames"] == doc["observation"]["frames"]
|
||||
assert layout["control"]["kp"] == 1 # BAM firmware gain stays separate.
|
||||
assert layout["motor_model"]["kp"] == 100
|
||||
|
||||
|
||||
@pytest.mark.parametrize("frames", [
|
||||
{"actions": {"kind": "site", "name": "imu"}},
|
||||
{"projected_gravity": {"kind": "site", "name": "imu"}},
|
||||
{"base_ang_vel": {"kind": "sensor", "name": "imu"}},
|
||||
{"base_ang_vel": {"kind": "site", "name": ""}},
|
||||
{"base_ang_vel": {"kind": "site", "name": "imu", "ignored": 1}},
|
||||
])
|
||||
def test_unknown_or_unobserved_frames_fail_closed(frames):
|
||||
doc = metadata()
|
||||
doc["observation"]["frames"] = frames
|
||||
with pytest.raises(ValueError, match="[Ff]rame"):
|
||||
build_layout(doc)
|
||||
|
||||
|
||||
def test_frame_must_exist_in_exact_model():
|
||||
model = mujoco.MjModel.from_xml_string('''<mujoco><compiler angle="radian"/>
|
||||
<worldbody><body><joint name="joint" range="-1 1"/>
|
||||
<geom size=".1"/><site name="actual_imu"/></body></worldbody>
|
||||
<actuator><motor joint="joint"/></actuator></mujoco>''')
|
||||
doc = metadata()
|
||||
with pytest.raises(ValueError, match="no observation frame"):
|
||||
build_layout(doc, model=model)
|
||||
doc["observation"]["frames"]["base_ang_vel"]["name"] = "actual_imu"
|
||||
assert build_layout(doc, model=model)["observation"]["frames"]
|
||||
|
||||
|
||||
def test_motor_metadata_rejects_unknown_keys_and_velocity_targets():
|
||||
doc = metadata()
|
||||
invalid = copy.deepcopy(doc)
|
||||
invalid["motor_model"]["typo"] = 1
|
||||
with pytest.raises(ValueError, match="BAM fields"):
|
||||
build_layout(invalid)
|
||||
doc["action"] = {"targets": {"joint": {"kind": "velocity", "offset": 0}}}
|
||||
doc["control"]["kp"], doc["control"]["kd"] = 0, 1
|
||||
with pytest.raises(ValueError, match="requires position targets"):
|
||||
build_layout(doc)
|
||||
@@ -0,0 +1,122 @@
|
||||
"""Measure command populations and exercise inherited partial-reset lifecycle."""
|
||||
|
||||
from types import SimpleNamespace
|
||||
|
||||
import pytest
|
||||
import torch
|
||||
|
||||
from mjrl.tasks.commands import AxisBalancedVelocityCommand, AxisBalancedVelocityCommandCfg
|
||||
|
||||
|
||||
def _config(**kwargs):
|
||||
return AxisBalancedVelocityCommandCfg(
|
||||
entity_name="robot", resampling_time_range=(3., 7.),
|
||||
ranges=AxisBalancedVelocityCommandCfg.Ranges((-.7, .7), (-.35, .35), (-.8, .8)),
|
||||
**{"rel_standing_envs": .1, **kwargs},
|
||||
)
|
||||
|
||||
|
||||
def _term(count=30000, **kwargs):
|
||||
zeros = torch.zeros(count, 3)
|
||||
robot = SimpleNamespace(data=SimpleNamespace(root_link_lin_vel_b=zeros, root_link_ang_vel_b=zeros))
|
||||
env = SimpleNamespace(num_envs=count, device="cpu", step_dt=.02, scene={"robot": robot})
|
||||
return _config(**kwargs).build(env)
|
||||
|
||||
|
||||
def test_population_has_balanced_isolated_axes_both_signs_standing_and_mixed_commands():
|
||||
torch.manual_seed(1027)
|
||||
term = _term()
|
||||
assert isinstance(term, AxisBalancedVelocityCommand)
|
||||
term.reset(torch.arange(term.num_envs))
|
||||
term.compute(0.)
|
||||
values = term.command
|
||||
standing = term.is_standing_env
|
||||
moving = ~standing
|
||||
assert standing.float().mean().item() == pytest.approx(.1, abs=.012)
|
||||
assert torch.count_nonzero(values[standing]) == 0
|
||||
active_axes = (values != 0).sum(dim=1)
|
||||
isolated = moving & (active_axes == 1)
|
||||
assert isolated.sum().item() / moving.sum().item() == pytest.approx(.3, abs=.015)
|
||||
assert ((active_axes[moving] == 1) | (active_axes[moving] == 3)).all()
|
||||
assert (active_axes == 3).float().mean().item() == pytest.approx(.63, abs=.02)
|
||||
for axis, maximum in enumerate((.7, .35, .8)):
|
||||
assert (values[:, axis].abs() <= maximum).all()
|
||||
chosen = isolated & (values[:, axis] != 0)
|
||||
assert chosen.sum().item() / isolated.sum().item() == pytest.approx(1/3, abs=.025)
|
||||
assert (values[chosen, axis] > 0).float().mean().item() == pytest.approx(.5, abs=.04)
|
||||
assert values[chosen, axis].min() < -.9 * maximum
|
||||
assert values[chosen, axis].max() > .9 * maximum
|
||||
original = values.clone()
|
||||
term.compute(.01)
|
||||
torch.testing.assert_close(values, original, atol=0, rtol=0)
|
||||
|
||||
|
||||
def test_isolation_keeps_original_sampled_axis_and_partial_reset_keeps_other_envs():
|
||||
def sampled(fraction):
|
||||
torch.manual_seed(29)
|
||||
term = _term(256, isolated_axis_fraction=fraction, rel_standing_envs=0.)
|
||||
term.reset(torch.arange(256))
|
||||
term.compute(0.)
|
||||
return term
|
||||
|
||||
mixed, isolated = sampled(0.), sampled(1.)
|
||||
mask = isolated.command != 0
|
||||
assert (mask.sum(dim=1) == 1).all()
|
||||
assert (mixed.command != 0).all() # The control actually includes all axes.
|
||||
torch.testing.assert_close(isolated.command[mask], mixed.command[mask], atol=0, rtol=0)
|
||||
before = {name: getattr(isolated, name).clone() for name in
|
||||
("vel_command_b", "vel_command_w", "time_left", "command_counter", "is_standing_env")}
|
||||
ids = torch.tensor([1, 7, 19, 97])
|
||||
untouched = torch.ones(256, dtype=torch.bool)
|
||||
untouched[ids] = False
|
||||
isolated.reset(ids)
|
||||
isolated.compute(0., env_ids=ids)
|
||||
for name, old in before.items():
|
||||
torch.testing.assert_close(getattr(isolated, name)[untouched], old[untouched], atol=0, rtol=0)
|
||||
assert not torch.equal(isolated.command[ids], before["vel_command_b"][ids])
|
||||
assert (isolated.command_counter[ids] == 1).all()
|
||||
assert ((isolated.time_left[ids] >= 3) & (isolated.time_left[ids] <= 7)).all()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("field", ["isolated_axis_fraction", "rel_standing_envs", "init_velocity_prob"])
|
||||
@pytest.mark.parametrize("value", [-.1, 1.1, float("nan"), float("inf"), True, "0.3"])
|
||||
def test_invalid_probabilities_fail(field, value):
|
||||
with pytest.raises(ValueError, match=field):
|
||||
_config(**{field: value})
|
||||
|
||||
|
||||
@pytest.mark.parametrize("kwargs", [
|
||||
{"heading_command": True}, {"rel_world_envs": .1}, {"rel_forward_envs": .1},
|
||||
{"rel_world_envs": float("nan")},
|
||||
])
|
||||
def test_modes_that_overwrite_axes_are_rejected(kwargs):
|
||||
with pytest.raises(ValueError):
|
||||
_config(**kwargs)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("bounds", [(.1, .5), (-.5, -.1), (.5, -.5), (float("nan"), .5)])
|
||||
def test_ranges_must_allow_zero_masking(bounds):
|
||||
cfg = _config()
|
||||
cfg.ranges.lin_vel_x = bounds
|
||||
with pytest.raises(ValueError, match="lin_vel_x"):
|
||||
cfg.build(None) # Validation precedes environment access.
|
||||
|
||||
|
||||
def test_heading_range_and_mutated_mode_are_rejected():
|
||||
cfg = _config()
|
||||
cfg.ranges.heading = (-1., 1.)
|
||||
with pytest.raises(ValueError, match="without heading"):
|
||||
cfg.build(None)
|
||||
cfg = _config()
|
||||
cfg.rel_world_envs = .2
|
||||
with pytest.raises(ValueError, match="body-frame"):
|
||||
cfg.build(None)
|
||||
|
||||
|
||||
def test_all_standing_stays_zero_with_isolation_enabled():
|
||||
term = _term(16, rel_standing_envs=1., isolated_axis_fraction=1.)
|
||||
term.reset(torch.arange(16))
|
||||
term.compute(0.)
|
||||
assert term.is_standing_env.all()
|
||||
assert torch.count_nonzero(term.command) == 0
|
||||
assert torch.count_nonzero(term.vel_command_w) == 0
|
||||
@@ -0,0 +1,471 @@
|
||||
"""Behavioral checks for biped support credit and episode-local swing peaks."""
|
||||
|
||||
from types import SimpleNamespace as NS
|
||||
|
||||
import pytest
|
||||
import torch
|
||||
from mjlab.sensor.terrain_height_sensor import TerrainHeightSensor
|
||||
from mjlab.tasks.velocity.mdp.rewards import feet_swing_height
|
||||
|
||||
from mjrl.tasks.biped import (
|
||||
ActiveActionRate,
|
||||
CompletedSwingQuality,
|
||||
ResettableSwingHeight,
|
||||
bounded_single_support,
|
||||
command_relative_angular_tracking,
|
||||
command_relative_linear_tracking,
|
||||
)
|
||||
|
||||
|
||||
def test_action_smoothing_follows_runtime_scale_order_and_ignores_held_channels():
|
||||
action = torch.tensor([[2., 999., 3.], [4., -999., 1.]])
|
||||
previous = torch.tensor([[1., -999., 1.], [2., 999., -1.]])
|
||||
terms = {'position': NS(scale=torch.tensor([[.2, 0.], [.2, 0.]]),
|
||||
raw_action=action[:, :2]),
|
||||
'velocity': NS(scale=.5, raw_action=action[:, 2:])}
|
||||
manager = NS(active_terms=list(terms), get_term=terms.__getitem__,
|
||||
action=action, prev_action=previous)
|
||||
env = NS(action_manager=manager, device='cpu')
|
||||
reward = ActiveActionRate(NS(), env)
|
||||
torch.testing.assert_close(reward(env), torch.tensor([5., 8.]))
|
||||
action[:, 0] += 2 # A real change on an active channel increases its cost.
|
||||
torch.testing.assert_close(reward(env), torch.tensor([13., 20.]))
|
||||
# Runtime history and the 3D action contract are unchanged by the reward.
|
||||
assert previous[:, 1].tolist() == [-999., 999.]
|
||||
assert action.shape == (2, 3)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("slots", [False, True])
|
||||
def test_single_support_rejects_stance_flight_idle_and_unbounded_swing(slots):
|
||||
found = torch.tensor([
|
||||
[1, 1], [0, 0], [1, 0], [0, 1], [1, 0], [1, 0], [1, 0], [1, 0],
|
||||
])
|
||||
air = torch.tensor([
|
||||
[0., 0.], [.2, .2], [0., .2], [.2, 0.], [0., .6], [0., .2],
|
||||
[0., .05], [0., .4],
|
||||
])
|
||||
command = torch.tensor([[.2, 0., 0.]] * len(found))
|
||||
command[3] = torch.tensor([0., 0., -.2]) # Turning also commands stepping.
|
||||
command[5] = 0.
|
||||
if slots:
|
||||
# Two contact points on one foot must still count as one support.
|
||||
found = torch.stack((found, found * 2), dim=-1)
|
||||
env = NS(scene={"feet": NS(data=NS(found=found, current_air_time=air))},
|
||||
command_manager=NS(get_command=lambda _: command))
|
||||
assert bounded_single_support(env, "feet", "twist").tolist() == [
|
||||
0., 0., 1., 1., 0., 0., 0., 0.,
|
||||
]
|
||||
command[:] = torch.tensor([.05, 0., 0.])
|
||||
assert not bounded_single_support(env, "feet", "twist").any()
|
||||
|
||||
|
||||
def test_single_support_rejects_mismatched_sensor_axes():
|
||||
sensor = NS(data=NS(found=torch.ones(2, 3), current_air_time=torch.zeros(2, 2)))
|
||||
with pytest.raises(ValueError, match="share"):
|
||||
bounded_single_support(NS(scene={"feet": sensor}), "feet", "twist")
|
||||
|
||||
|
||||
class _HeightSensor(TerrainHeightSensor):
|
||||
"""Supply controlled terrain samples while exercising the real reward."""
|
||||
|
||||
def __init__(self, heights):
|
||||
self.heights = heights
|
||||
|
||||
@property
|
||||
def num_frames(self):
|
||||
return self.heights.shape[1]
|
||||
|
||||
@property
|
||||
def data(self):
|
||||
return NS(heights=self.heights)
|
||||
|
||||
|
||||
def _swing_env():
|
||||
height = _HeightSensor(torch.tensor([[.12, .03], [.09, .06], [.06, .12]]))
|
||||
contact = NS(data=NS(found=torch.zeros(3, 2)),
|
||||
landed=torch.zeros(3, 2, dtype=torch.bool))
|
||||
contact.compute_first_contact = lambda dt: contact.landed
|
||||
env = NS(scene={"height": height, "feet": contact}, num_envs=3, device="cpu",
|
||||
step_dt=.02, extras={"log": {}},
|
||||
command_manager=NS(get_command=lambda _: torch.tensor([[.2, 0., 0.]] * 3)))
|
||||
params = dict(sensor_name="feet", height_sensor_name="height", target_height=.06,
|
||||
command_name="twist", command_threshold=.05)
|
||||
return env, NS(params=params), params
|
||||
|
||||
|
||||
def test_reset_discards_only_terminated_episode_peaks_and_changes_next_landing():
|
||||
env, cfg, params = _swing_env()
|
||||
reward = ResettableSwingHeight(cfg, env)
|
||||
reference = feet_swing_height(cfg, env)
|
||||
assert not reward(env, **params).any() # Flight accumulates, never pays a landing cost.
|
||||
reference(env, **params)
|
||||
before = reward.peak_heights.clone()
|
||||
assert torch.all(before > 0)
|
||||
reward.reset(torch.tensor([0, 2]))
|
||||
torch.testing.assert_close(reward.peak_heights[1], before[1])
|
||||
assert not reward.peak_heights[[0, 2]].any()
|
||||
|
||||
# The next episode swings to exactly the desired height. Unreset episodes
|
||||
# keep their previous maximum; the reference control retains stale peaks.
|
||||
env.scene["height"].heights[:] = .06
|
||||
reward(env, **params)
|
||||
reference(env, **params)
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
env.scene["feet"].landed[:] = True
|
||||
actual = reward(env, **params)
|
||||
stale = reference(env, **params)
|
||||
torch.testing.assert_close(actual, torch.tensor([0., .25, 0.]))
|
||||
torch.testing.assert_close(stale, torch.tensor([1., .25, 1.]))
|
||||
assert not reward.peak_heights.any() # Actual landings clear their feet.
|
||||
|
||||
|
||||
@pytest.mark.parametrize("env_ids", [None, slice(None)])
|
||||
@pytest.mark.parametrize("step_dt", [.01, .02])
|
||||
def test_swing_height_full_reset_and_reference_rate_semantics(env_ids, step_dt):
|
||||
env, cfg, params = _swing_env()
|
||||
env.step_dt = step_dt
|
||||
reward = ResettableSwingHeight(cfg, env)
|
||||
reference = feet_swing_height(cfg, env)
|
||||
reward(env, **params)
|
||||
reference(env, **params)
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
env.scene["feet"].landed[:] = True
|
||||
actual = reward(env, **params)
|
||||
torch.testing.assert_close(actual, reference(env, **params))
|
||||
torch.testing.assert_close(actual, torch.tensor([1.25, .25, 1.]))
|
||||
# The unscaled reference event cost is retained (no division by step_dt).
|
||||
env.scene["feet"].data.found[:] = 0
|
||||
env.scene["feet"].landed[:] = False
|
||||
reward(env, **params)
|
||||
assert reward.peak_heights.any()
|
||||
reward.reset(env_ids)
|
||||
assert not reward.peak_heights.any()
|
||||
|
||||
|
||||
def _quality_env():
|
||||
env, cfg, params = _swing_env()
|
||||
params["target_swing_s"] = .18
|
||||
env.scene["feet"].data.last_air_time = torch.full((3, 2), .18)
|
||||
return env, CompletedSwingQuality(cfg, env), params
|
||||
|
||||
|
||||
@pytest.mark.parametrize("step_dt", [.01, .02])
|
||||
@pytest.mark.parametrize("slots", [False, True])
|
||||
def test_completed_swing_cost_distinguishes_desired_short_and_outlier_events(step_dt, slots):
|
||||
env, reward, params = _quality_env()
|
||||
env.step_dt = step_dt
|
||||
sensor = env.scene["feet"]
|
||||
if slots:
|
||||
sensor.data.found = sensor.data.found.unsqueeze(-1).repeat(1, 1, 2)
|
||||
sensor.data.found[:] = 1
|
||||
assert not reward(env, **params).any() # Initial stance arms every foot.
|
||||
sensor.data.found[:, 0] = 0
|
||||
env.scene["height"].heights[:, 0] = torch.tensor([.06, .012, .6])
|
||||
assert not reward(env, **params).any()
|
||||
sensor.data.last_air_time[:, 0] = torch.tensor([.18, .06, 1.8])
|
||||
sensor.data.found[:] = 1
|
||||
integrated = reward(env, **params) * step_dt
|
||||
torch.testing.assert_close(integrated, torch.tensor([0., .8 ** 2 + (2 / 3) ** 2, 8.]))
|
||||
assert not reward.peak_heights.any()
|
||||
assert not reward.in_swing.any()
|
||||
assert not reward(env, **params).any() # The event is never charged twice.
|
||||
|
||||
|
||||
def test_initial_truncated_swing_and_unobserved_contact_chatter_are_ignored():
|
||||
env, reward, params = _quality_env()
|
||||
env.scene["height"].heights[:] = .6
|
||||
assert not reward(env, **params).any() # Starts in flight; no observed takeoff.
|
||||
assert not reward.peak_heights.any()
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
env.scene["feet"].data.last_air_time[:] = .01
|
||||
assert not reward(env, **params).any()
|
||||
env.scene["feet"].landed[:] = True # Timer chatter without observed air.
|
||||
assert not reward(env, **params).any()
|
||||
assert reward.armed.all()
|
||||
env.scene["feet"].data.found[:, 0] = 0
|
||||
reward(env, **params)
|
||||
env.scene["feet"].data.found[:, 0] = 1
|
||||
assert (reward(env, **params) > 0).all() # A genuinely observed swing is detected.
|
||||
|
||||
|
||||
@pytest.mark.parametrize('turn', [False, True])
|
||||
def test_swing_quality_strengthens_with_command_progress_without_positive_bonus(turn):
|
||||
env, reward, params = _quality_env()
|
||||
params['minimum_motion_fraction'] = 1 / 6
|
||||
linear, angular = torch.zeros(3, 3), torch.zeros(3, 3)
|
||||
command = torch.zeros(3, 3)
|
||||
command[:, 2 if turn else 0] = .2
|
||||
(angular if turn else linear)[:, 2 if turn else 0] = torch.tensor([0., .1, .2])
|
||||
env.scene['robot'] = NS(data=NS(root_link_lin_vel_b=linear, root_link_ang_vel_b=angular))
|
||||
env.command_manager.get_command = lambda _: command
|
||||
env.scene['feet'].data.found[:] = 1
|
||||
assert not reward(env, **params).any()
|
||||
env.scene['feet'].data.found[:, 0] = 0
|
||||
env.scene['height'].heights[:, 0] = .012
|
||||
assert not reward(env, **params).any()
|
||||
env.scene['feet'].data.last_air_time[:, 0] = .06
|
||||
env.scene['feet'].data.found[:] = 1
|
||||
cost = reward(env, **params) * env.step_dt
|
||||
full = .8 ** 2 + (2 / 3) ** 2
|
||||
torch.testing.assert_close(cost, full * torch.tensor([1/6, 7/12, 1.]))
|
||||
assert not reward(env, **params).any() # No repeated payment while grounded.
|
||||
|
||||
|
||||
def test_completed_swing_idle_gate_does_not_leave_stale_event_state():
|
||||
env, reward, params = _quality_env()
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
reward(env, **params)
|
||||
env.scene["feet"].data.found[:, 0] = 0
|
||||
reward(env, **params)
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
env.command_manager.get_command = lambda _: torch.zeros(3, 3)
|
||||
assert not reward(env, **params).any()
|
||||
assert not reward.in_swing.any()
|
||||
env.command_manager.get_command = lambda _: torch.tensor([[0., 0., -.2]] * 3)
|
||||
assert not reward(env, **params).any()
|
||||
|
||||
|
||||
def test_completed_swing_reset_isolates_one_environment():
|
||||
env, reward, params = _quality_env()
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
reward(env, **params)
|
||||
env.scene["height"].heights[:] = .012
|
||||
env.scene["feet"].data.found[:, 0] = 0
|
||||
reward(env, **params)
|
||||
assert reward.in_swing[:, 0].all() and (reward.peak_heights[:, 0] > 0).all()
|
||||
reward.reset(torch.tensor([1]))
|
||||
assert not reward.armed[1].any() and not reward.in_swing[1].any()
|
||||
assert not reward.peak_heights[1].any()
|
||||
assert reward.in_swing[[0, 2], 0].all()
|
||||
env.scene["feet"].data.found[:] = 1
|
||||
torch.testing.assert_close(reward(env, **params) * env.step_dt, torch.tensor([.64, 0., .64]))
|
||||
reward.reset()
|
||||
assert not reward.armed.any() and not reward.in_swing.any() and not reward.peak_heights.any()
|
||||
|
||||
|
||||
def test_low_command_tracking_has_material_gain_over_stationary_control(neutral_robot):
|
||||
data = NS(root_link_lin_vel_b=torch.tensor([[0., 0., 0.], [0., .1, 0.], [0., .1, .1]]))
|
||||
env = NS(scene={"robot": NS(data=data)},
|
||||
command_manager=NS(get_command=lambda _: torch.tensor([[0., .1, 0.]] * 3)))
|
||||
result = command_relative_linear_tracking(env, "twist")
|
||||
expected = torch.exp(torch.tensor(-.1 ** 2 / .15 ** 2))
|
||||
torch.testing.assert_close(result, torch.tensor([expected, 1., expected]))
|
||||
assert 3 * (result[1] - result[0]) > .47
|
||||
data.root_link_ang_vel_b = torch.tensor([[0., 0., 0.], [0., 0., .25], [0., 0., .25]])
|
||||
env.command_manager.get_command = lambda _: torch.tensor([[0., 0., .25]] * 3)
|
||||
result = command_relative_angular_tracking(env, "twist")
|
||||
assert result[0].item() == pytest.approx(torch.exp(torch.tensor(-.25 ** 2 / .15 ** 2)).item())
|
||||
assert result[1] == result[2] == 1.
|
||||
from tasks.templates.Biped_Template.env_cfg import env_cfg
|
||||
|
||||
weight = env_cfg(neutral_robot).rewards["track_angular_velocity"].weight
|
||||
# Reserve a material return margin for initiating a turn. The former
|
||||
# weight fails this control, matching the measured low-yaw standing trap.
|
||||
assert weight * (result[1] - result[0]) > 1.5
|
||||
assert 1.5 * (result[1] - result[0]) < 1.5
|
||||
|
||||
|
||||
def test_undertracking_turn_retains_incentive_without_tightening_idle_noise_floor():
|
||||
command = torch.tensor([[0., 0., 0.], [0., 0., .25]])
|
||||
actual = torch.tensor([[0., 0., .05], [0., 0., .14]])
|
||||
env = NS(scene={"robot": NS(data=NS(root_link_ang_vel_b=actual))},
|
||||
command_manager=NS(get_command=lambda _: command))
|
||||
result = command_relative_angular_tracking(env, "twist")
|
||||
assert result[0].item() == pytest.approx(torch.exp(torch.tensor(-(.05 / .15) ** 2)).item())
|
||||
assert 3 * (1 - result[1]) > 1.2
|
||||
additive_floor = torch.exp(torch.tensor(-((.25 - .14) / .275) ** 2))
|
||||
assert 3 * (1 - additive_floor) < .5 # Former low-turn undertracking trap.
|
||||
|
||||
|
||||
def test_roll_pitch_penalty_is_independent_of_yaw_command_and_tolerance_is_capped():
|
||||
command = torch.tensor([[0., 0., 0.], [0., 0., .25], [0., 0., 2.]])
|
||||
actual = torch.tensor([[.2, .3, 0.], [.2, .3, .25], [.2, .3, 2.]])
|
||||
data = NS(root_link_ang_vel_b=actual, root_link_lin_vel_b=torch.zeros(3, 3))
|
||||
env = NS(scene={"robot": NS(data=data)}, command_manager=NS(get_command=lambda _: command))
|
||||
torch.testing.assert_close(command_relative_angular_tracking(env, "twist"),
|
||||
torch.full((3,), torch.exp(torch.tensor(-.13 / .5))))
|
||||
actual[2, 2] = 1.
|
||||
assert command_relative_angular_tracking(env, "twist")[2].item() == pytest.approx(
|
||||
torch.exp(torch.tensor(-1. / .5 - .13 / .5)).item(),
|
||||
)
|
||||
command[:] = torch.tensor([2., 0., 0.])
|
||||
data.root_link_lin_vel_b[:] = torch.tensor([1.5, 0., 0.])
|
||||
torch.testing.assert_close(command_relative_linear_tracking(env, "twist"),
|
||||
torch.full((3,), torch.exp(torch.tensor(-1.))))
|
||||
|
||||
|
||||
def test_biped_pilot_weights_leave_other_families_unchanged(neutral_robot):
|
||||
from dataclasses import asdict
|
||||
from importlib import import_module
|
||||
from tasks.templates._locomotion import _rewards
|
||||
from tasks.templates.Biped_Template.env_cfg import _RECIPE
|
||||
|
||||
rewards = _rewards(neutral_robot, _RECIPE, ('left_sole', 'right_sole'))
|
||||
assert rewards['swing_quality'].func is CompletedSwingQuality
|
||||
assert rewards['swing_quality'].weight == -.03
|
||||
assert rewards['action_rate'].func is ActiveActionRate
|
||||
assert rewards['action_rate'].weight == -.03
|
||||
assert rewards['leg_torque'].weight == -1e-6
|
||||
assert rewards['single_support'].weight == .5
|
||||
for family, template in [('quadruped', 'Quadruped_Template'),
|
||||
('multipod', 'Multipod_Template'),
|
||||
('wheeled_biped', 'Wheeled_Biped_Template')]:
|
||||
recipe = import_module(f'tasks.templates.{template}.env_cfg')._RECIPE
|
||||
other_robot = NS(**{**asdict(neutral_robot), "family": family})
|
||||
other_robot.position_joints = neutral_robot.position_joints
|
||||
other = _rewards(other_robot, recipe)
|
||||
assert other['action_rate'].weight == -.02
|
||||
assert other['leg_torque'].weight == -1e-5
|
||||
assert 'single_support' not in other
|
||||
assert 'swing_quality' not in other
|
||||
assert other['track_linear_velocity'].weight == 2.
|
||||
assert other['joint_home'].weight == -.5
|
||||
|
||||
|
||||
@pytest.mark.parametrize('step_dt', [.01, .02])
|
||||
def test_small_completed_steps_do_not_consume_initial_forward_tracking_gain(
|
||||
neutral_robot, step_dt,
|
||||
):
|
||||
"""Four imperfect real events must not erase the first tracking improvement.
|
||||
|
||||
This is a local reward-budget check, not a claim that a complete gait is
|
||||
profitable: posture, action changes, effort, and impacts still carry their
|
||||
configured costs and must be measured in native replay.
|
||||
"""
|
||||
from dataclasses import replace
|
||||
from tasks.templates._locomotion import _rewards
|
||||
from tasks.templates.Biped_Template.env_cfg import _RECIPE
|
||||
|
||||
# Use a synthetic tall biped to exercise height-dependent terms.
|
||||
robot = replace(neutral_robot, base_height=1.0203419882368219)
|
||||
rewards = _rewards(robot, _RECIPE, ('left_sole', 'right_sole'))
|
||||
params = rewards['swing_quality'].params
|
||||
found = torch.ones(1, 2)
|
||||
air = torch.zeros(1, 2)
|
||||
last_air = torch.zeros(1, 2)
|
||||
height = NS(num_frames=2, data=NS(heights=torch.zeros(1, 2)))
|
||||
sensor = NS(data=NS(found=found, current_air_time=air, last_air_time=last_air))
|
||||
command = torch.tensor([[.7, 0., 0.]])
|
||||
data = NS(root_link_lin_vel_b=torch.zeros(1, 3), root_link_ang_vel_b=torch.zeros(1, 3))
|
||||
env = NS(scene={params['sensor_name']: sensor,
|
||||
params['height_sensor_name']: height, 'robot': NS(data=data)},
|
||||
command_manager=NS(get_command=lambda _: command),
|
||||
num_envs=1, device='cpu', step_dt=step_dt)
|
||||
quality = CompletedSwingQuality(rewards['swing_quality'], env)
|
||||
assert quality(env, **params).item() == 0. # Observe stance before takeoff.
|
||||
tracking = rewards['track_linear_velocity']
|
||||
standing = tracking.func(env, **tracking.params).item()
|
||||
data.root_link_lin_vel_b[:, 0] = .02
|
||||
tracking_gain = tracking.weight * (tracking.func(env, **tracking.params).item() - standing)
|
||||
assert tracking_gain == pytest.approx(.038963, abs=2e-6)
|
||||
|
||||
integrated_quality = 0.
|
||||
integrated_support = 0.
|
||||
nonzero_events = 0
|
||||
starts = [round(t / step_dt) for t in [0., .24, .5, .74]]
|
||||
swing_samples = round(.06 / step_dt)
|
||||
for step in range(round(1. / step_dt)):
|
||||
found[:] = 1
|
||||
air[:] = 0
|
||||
for event, start in enumerate(starts):
|
||||
foot = event % 2
|
||||
if start <= step < start + swing_samples:
|
||||
found[:, foot] = 0
|
||||
air[:, foot] = (step - start + 1) * step_dt
|
||||
height.data.heights[:, foot] = .012
|
||||
elif step == start + swing_samples:
|
||||
last_air[:, foot] = .06
|
||||
height.data.heights[:, foot] = 0.
|
||||
cost = quality(env, **params).item() * step_dt
|
||||
nonzero_events += int(cost > 0)
|
||||
integrated_quality += cost
|
||||
support = rewards['single_support']
|
||||
integrated_support += support.func(env, **support.params).item() * step_dt
|
||||
|
||||
assert nonzero_events == 4 # Reject vacuous success from missing takeoffs.
|
||||
expected_error = (.012 / params['target_height'] - 1) ** 2 \
|
||||
+ (.06 / params['target_swing_s'] - 1) ** 2
|
||||
fraction = params['minimum_motion_fraction'] + (1 - params['minimum_motion_fraction']) * .02 / .7
|
||||
assert integrated_quality == pytest.approx(4 * expected_error * fraction, rel=1e-6)
|
||||
new_cost = -rewards['swing_quality'].weight * integrated_quality
|
||||
assert new_cost < tracking_gain
|
||||
assert tracking_gain + rewards['single_support'].weight * integrated_support - new_cost > 0
|
||||
# The previous recipe must fail the same budget on these same events.
|
||||
assert tracking_gain + .3 * integrated_support - .05 * 4 * expected_error < 0
|
||||
|
||||
|
||||
def test_translation_coupling_removes_standing_heading_credit_but_keeps_optimum(neutral_robot):
|
||||
from mjrl.tasks.biped import translation_aware_angular_tracking
|
||||
from tasks.templates.Biped_Template.env_cfg import env_cfg
|
||||
|
||||
command = torch.tensor([[.3, 0., 0.], [.3, 0., .25]])
|
||||
data = NS(root_link_lin_vel_b=torch.tensor([[0., 0., 0.], [.3, 0., 0.]]),
|
||||
root_link_ang_vel_b=torch.tensor([[0., 0., 0.], [0., 0., .25]]))
|
||||
env = NS(scene={'robot': NS(data=data)}, command_manager=NS(get_command=lambda _: command))
|
||||
angular = command_relative_angular_tracking(env, 'twist')
|
||||
coupled = translation_aware_angular_tracking(env, 'twist')
|
||||
assert 3 * angular[0].item() == pytest.approx(3.) # Previous standing windfall.
|
||||
assert 3 * coupled[0].item() == pytest.approx(1.16862662, abs=1e-6)
|
||||
assert coupled[1].item() == pytest.approx(1.) # Perfect full twist still earns 3/s.
|
||||
term = env_cfg(neutral_robot).rewards['track_angular_velocity']
|
||||
assert term.func is translation_aware_angular_tracking
|
||||
|
||||
|
||||
def test_walking_tolerance_allows_pelvis_oscillation_but_keeps_pure_turn_and_idle(neutral_robot):
|
||||
from tasks.templates.Biped_Template.env_cfg import env_cfg
|
||||
|
||||
cfg = env_cfg(neutral_robot)
|
||||
command = torch.tensor([[.3, 0., 0.], [.3, 0., 0.], [0., 0., .4], [0., 0., 0.]])
|
||||
data = NS(root_link_lin_vel_b=torch.tensor([[.3, 0., 0.], [0., 0., 0.],
|
||||
[0., 0., 0.], [0., 0., 0.]]),
|
||||
root_link_ang_vel_b=torch.tensor([[0., 0., .12], [0., 0., 0.],
|
||||
[0., 0., 0.], [0., 0., .12]]))
|
||||
env = NS(scene={'robot': NS(data=data)}, command_manager=NS(get_command=lambda _: command))
|
||||
term = cfg.rewards['track_angular_velocity']
|
||||
value = term.func(env, **term.params)
|
||||
assert value[0].item() == pytest.approx(torch.exp(torch.tensor(-.12**2/.5**2)).item())
|
||||
assert value[1].item() < .6 # Standing still does not receive full heading credit.
|
||||
original = command_relative_angular_tracking(env, 'twist')
|
||||
torch.testing.assert_close(value[2:], original[2:])
|
||||
assert value[2].item() < .02 # Ignoring a pure .4 rad/s turn still loses nearly all credit.
|
||||
data.root_link_lin_vel_b[2:, 0] = .1
|
||||
linear = cfg.rewards['track_linear_velocity']
|
||||
torch.testing.assert_close(linear.func(env, **linear.params)[2:],
|
||||
command_relative_linear_tracking(env, 'twist')[2:])
|
||||
assert term.weight == 3.
|
||||
|
||||
|
||||
def test_translation_coupling_keeps_pure_turn_idle_and_threshold_behavior():
|
||||
from mjrl.tasks.biped import translation_aware_angular_tracking
|
||||
|
||||
command = torch.tensor([[0., 0., .25], [0., 0., 0.], [.05, 0., .25]])
|
||||
data = NS(root_link_lin_vel_b=torch.tensor([[.1, .1, .1]] * 3),
|
||||
root_link_ang_vel_b=torch.tensor([[.02, .03, .14], [.02, .03, .05],
|
||||
[.02, .03, .14]]))
|
||||
env = NS(scene={'robot': NS(data=data)}, command_manager=NS(get_command=lambda _: command))
|
||||
torch.testing.assert_close(translation_aware_angular_tracking(env, 'twist'),
|
||||
command_relative_angular_tracking(env, 'twist'))
|
||||
# Crossing the explicit translation threshold engages the joint objective.
|
||||
command[2, 0] = .051
|
||||
assert translation_aware_angular_tracking(env, 'twist')[2] \
|
||||
< command_relative_angular_tracking(env, 'twist')[2]
|
||||
|
||||
|
||||
def test_translation_coupling_rejects_wrong_yaw_lateral_backwards_and_vertical_motion():
|
||||
from mjrl.tasks.biped import translation_aware_angular_tracking
|
||||
|
||||
command = torch.tensor([[.3, 0., .25]] * 6)
|
||||
data = NS(root_link_lin_vel_b=torch.tensor([[.3, 0., 0.], [.3, 0., 0.],
|
||||
[0., .3, 0.], [-.3, 0., 0.],
|
||||
[.3, 0., .1], [0., 0., 0.]]),
|
||||
root_link_ang_vel_b=torch.tensor([[0., 0., .25], [0., 0., 0.],
|
||||
[0., 0., .25], [0., 0., .25],
|
||||
[0., 0., .25], [0., 0., .25]]))
|
||||
env = NS(scene={'robot': NS(data=data)}, command_manager=NS(get_command=lambda _: command))
|
||||
result = translation_aware_angular_tracking(env, 'twist')
|
||||
assert result[0].item() == pytest.approx(1.)
|
||||
assert ((result[1:] > 0) & (result[1:] < 1)).all()
|
||||
assert result[2] < result[5] # Matching speed in the wrong direction is worse than stillness.
|
||||
assert result[3] < result[5]
|
||||
torch.testing.assert_close(result, command_relative_angular_tracking(env, 'twist')
|
||||
* (.2 + .8 * command_relative_linear_tracking(env, 'twist')))
|
||||
@@ -35,11 +35,18 @@ def test_training_range_matches_replay_at_each_checkpoint_level(neutral_robot):
|
||||
def test_the_operator_reaches_each_trained_limit(neutral_robot):
|
||||
train = env_cfg(neutral_robot)
|
||||
replay = env_cfg(neutral_robot, play=True)
|
||||
checkpoint = {"infos": {"curriculum": {"command": {"level": 1}}}}
|
||||
params = train.curriculum["command"].params
|
||||
level = len(params["fractions"]) - 1
|
||||
checkpoint = {"infos": {"curriculum": {"command": {"level": level}}}}
|
||||
report = configure_velocity_replay(replay, train, checkpoint)
|
||||
command = replay.commands["twist"]
|
||||
controls = command.controls
|
||||
edges = spans(controls.command("twist"), command)
|
||||
for axis, ceiling in zip(("lin_vel_x", "lin_vel_y", "ang_vel_z"), params["ceilings"], strict=True):
|
||||
low, high = report["ranges"][axis]
|
||||
cap = ceiling * params["fractions"][level]
|
||||
assert (low, high) == pytest.approx((-cap, cap))
|
||||
assert -ceiling <= low < high <= ceiling
|
||||
for axis, (binding,) in controls.bindings.items():
|
||||
values = dict.fromkeys(("Lx", "Ly", "Rx", "Ry", "LT", "RT"), 0.0)
|
||||
values[binding.source] = binding.sign
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
"""Named heterogeneous servos retain physical limits and calibrated operator rest."""
|
||||
|
||||
import json
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
mujoco = pytest.importorskip("mujoco")
|
||||
|
||||
from mjrl.controllers import load_controller, setup_controller
|
||||
|
||||
XML = """<mujoco>
|
||||
<compiler angle="radian"/>
|
||||
<option timestep=".002" gravity="0 0 0" integrator="implicitfast"/>
|
||||
<worldbody><body name="leg_body">
|
||||
<joint name="leg" type="slide" axis="1 0 0" range="-.2 .2" actuatorfrcrange="-5 4"/>
|
||||
<geom size=".02" mass="1" contype="0" conaffinity="0"/>
|
||||
<body name="arm_body"><joint name="arm" type="slide" axis="0 1 0" range="-.2 .2" actuatorfrcrange="-3 5"/>
|
||||
<geom size=".02" mass="1" contype="0" conaffinity="0"/>
|
||||
</body></body></worldbody>
|
||||
<actuator>
|
||||
<motor name="arm_motor" joint="arm" gear="-2" forcerange="-4 3" ctrlrange="-1 2"/>
|
||||
<position name="leg_servo" joint="leg" kp="10" ctrlrange="-.2 .2" forcerange="-8 12"/>
|
||||
</actuator></mujoco>"""
|
||||
GAINS = {"kp": {"arm": 30, "leg": 70}, "kd": {"arm": 3, "leg": 2},
|
||||
"effort_limit": {"arm": 100, "leg": 6}}
|
||||
|
||||
|
||||
def setup(tmp_path, **extra):
|
||||
source = tmp_path / "source.xml"
|
||||
source.write_text(XML)
|
||||
config = {"kind": "joint_sliders", "joints": ["leg", "arm"], **GAINS, **extra}
|
||||
result = setup_controller(source, config, tmp_path / "controller")
|
||||
model = mujoco.MjModel.from_xml_path(str(result.model))
|
||||
controller = load_controller(model, result.config, result.controls)
|
||||
return result, model, controller
|
||||
|
||||
|
||||
def test_named_servos_apply_gains_by_joint_and_do_not_enlarge_authored_effort(tmp_path):
|
||||
result, model, controller = setup(tmp_path)
|
||||
config = json.loads(result.config.read_text())
|
||||
assert config["kp"] == GAINS["kp"]
|
||||
assert config["kd"] == GAINS["kd"]
|
||||
assert config["effort_limit"] == GAINS["effort_limit"]
|
||||
# Actuator order arm,leg differs from controller order leg,arm.
|
||||
np.testing.assert_array_equal(model.actuator_gainprm[:, 0], [30, 70])
|
||||
np.testing.assert_array_equal(model.actuator_biasprm[:, 2], [-3, -2])
|
||||
np.testing.assert_array_equal(model.actuator_gear[:, 0], [1, 1])
|
||||
# Arm: motor control [-1,2] * gear -2, intersect joint [-3,5].
|
||||
# Leg: requested +-6, source force [-8,12], intersect joint [-5,4].
|
||||
np.testing.assert_array_equal(model.actuator_forcerange, [[-3, 2], [-5, 4]])
|
||||
data = mujoco.MjData(model)
|
||||
controller.reset(data)
|
||||
controller.step(data, {"arm": .2, "leg": .2})
|
||||
mujoco.mj_forward(model, data)
|
||||
np.testing.assert_array_equal(data.actuator_force, [2, 4])
|
||||
controller.step(data, {"arm": -.2, "leg": -.2})
|
||||
mujoco.mj_forward(model, data)
|
||||
np.testing.assert_array_equal(data.actuator_force, [-3, -5])
|
||||
|
||||
|
||||
def test_cpg_uses_named_pd_gains_and_clips_to_preserved_effort(tmp_path):
|
||||
_, model, controller = setup(
|
||||
tmp_path, kind="cpg", frequency_hz=1, amplitude=[.1, .1], phase=[np.pi / 2] * 2,
|
||||
)
|
||||
data = mujoco.MjData(model)
|
||||
controller.reset(data)
|
||||
data.qpos[:] = [.09, .09]
|
||||
data.qvel[:] = [.2, .1]
|
||||
# leg: 70*.01 - 2*.2=.3; arm: 30*.01 - 3*.1=0.
|
||||
np.testing.assert_allclose(controller.step(data), [0, .3], atol=1e-14)
|
||||
data.qpos[:] = [-.1, -.1]
|
||||
np.testing.assert_allclose(controller.step(data), [2, 4], atol=1e-14)
|
||||
data.qpos[:] = [.2, .2]
|
||||
np.testing.assert_allclose(controller.step(data), [-2, -4], atol=1e-14)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("release", [{"keys": {"key_escape"}}, {"pad": {"B": True}}])
|
||||
def test_calibrated_home_releases_bound_arm_and_preserves_unbound_leg(tmp_path, release):
|
||||
_, model, controller = setup(
|
||||
tmp_path, home={"arm": -.08, "leg": .1}, operator_axes=["arm"],
|
||||
command_ranges={"arm": [-.12, .04], "leg": [-.15, .15]},
|
||||
)
|
||||
data = mujoco.MjData(model)
|
||||
data.qpos[:] = [.11, -.07]
|
||||
controller.reset(data)
|
||||
# Reset holds actual calibrated pose, rather than teleporting qpos to home.
|
||||
np.testing.assert_array_equal(data.qpos, [.11, -.07])
|
||||
np.testing.assert_array_equal(data.ctrl, [-.07, .11])
|
||||
controller.step(data, {"arm": .03, "leg": .13})
|
||||
controller.step(data, **release)
|
||||
np.testing.assert_array_equal(data.ctrl, [-.08, .13])
|
||||
assert controller.command_spans["arm"][2] == -.08
|
||||
assert controller.command_spans["leg"][2] == .1
|
||||
|
||||
|
||||
@pytest.mark.parametrize("field,value", [
|
||||
("kp", {"arm": 30}), ("kp", {"arm": 30, "leg": 70, "extra": 1}),
|
||||
("kd", {"arm": -1, "leg": 2}), ("kp", {"arm": 0, "leg": 2}),
|
||||
("effort_limit", {"arm": float("nan"), "leg": 2}),
|
||||
("effort_limit", {"arm": 0, "leg": 2}), ("kp", [30, 70]),
|
||||
("home", {"arm": 0}), ("home", {"arm": 0, "leg": .3}),
|
||||
("home", {"arm": float("inf"), "leg": .1}), ("home", [0, .1]),
|
||||
])
|
||||
def test_named_parameters_reject_missing_extra_invalid_or_positional_values(tmp_path, field, value):
|
||||
with pytest.raises(ValueError):
|
||||
setup(tmp_path, **{field: value})
|
||||
assert not (tmp_path / "controller").exists()
|
||||
|
||||
|
||||
def test_home_must_lie_in_declared_command_range(tmp_path):
|
||||
with pytest.raises(ValueError, match="exceeds limits or excludes the rest"):
|
||||
setup(tmp_path, home={"arm": -.08, "leg": .1}, command_ranges={"arm": [0, .1]})
|
||||
@@ -91,32 +91,62 @@ def test_mocap_ik_solves_named_site_and_tracks_without_editing_qpos(tmp_path):
|
||||
assert setup.controls.is_file()
|
||||
|
||||
|
||||
def test_application_idle_keyboard_preserves_mocap_drag(tmp_path):
|
||||
def test_application_native_mouse_drag_tracks_and_respects_workspace(tmp_path):
|
||||
from mjrl.platform.bundle import IK_MOUSE_HELP, _manual
|
||||
from mjrl.platform.play import RobotApplication
|
||||
|
||||
setup, _, _, _ = _setup(tmp_path, _ARM, kind="ik", joints=["x", "y"])
|
||||
app = RobotApplication(
|
||||
setup.model.parent,
|
||||
{
|
||||
"model": "robot.xml",
|
||||
"default_mode": "ik",
|
||||
"modes": {
|
||||
"ik": {
|
||||
"control_mode": "ik_mocap",
|
||||
"contract": "controller.json",
|
||||
"controls": "controls.yaml",
|
||||
}
|
||||
},
|
||||
},
|
||||
setup, _, _, _ = _setup(
|
||||
tmp_path, _ARM, kind="ik", joints=["x", "y"],
|
||||
command_ranges={"target_x": [-0.02, 0.02], "target_y": [-0.03, 0.03]},
|
||||
)
|
||||
app.data.mocap_pos[0] = [0.08, -0.05, 0]
|
||||
manifest = {
|
||||
"model": "robot.xml",
|
||||
"default_mode": "ik",
|
||||
"modes": {"ik": {
|
||||
"control_mode": "ik_mocap", "contract": "controller.json", "controls": "controls.yaml",
|
||||
}},
|
||||
}
|
||||
app = RobotApplication(setup.model.parent, manifest)
|
||||
manual = _manual(setup.model.parent, "arm", manifest["modes"], "ik")
|
||||
assert manual["modes"][0]["summary"] == IK_MOUSE_HELP
|
||||
|
||||
model, data, ik = app.model, app.data, app.controller.ik
|
||||
# A calibrated starting pose can differ from the model reference position.
|
||||
data.qpos[:] = [0.03, 0.04]
|
||||
app.controller.reset(data)
|
||||
mujoco.mj_forward(model, data)
|
||||
origin = data.site_xpos[ik.site].copy()
|
||||
np.testing.assert_allclose(data.mocap_pos[ik.mocap], origin)
|
||||
camera, opt = mujoco.MjvCamera(), mujoco.MjvOption()
|
||||
camera.lookat, camera.distance = origin, 0.5
|
||||
camera.azimuth, camera.elevation = 90, -90
|
||||
scene = mujoco.MjvScene(model, maxgeom=32)
|
||||
perturb = mujoco.MjvPerturb()
|
||||
mujoco.mjv_updateScene(model, data, opt, perturb, camera, mujoco.mjtCatBit.mjCAT_ALL, scene)
|
||||
|
||||
# The same picking, right-drag and pose application calls as MuJoCo's
|
||||
# passive viewer. Aim at the marker rim, clear of the tool geometry.
|
||||
point = np.zeros(3)
|
||||
ids = [np.full(1, -1, dtype=np.int32) for _ in range(3)]
|
||||
body = mujoco.mjv_select(model, data, opt, 1.0, 0.555, 0.5, scene, point, *ids)
|
||||
assert body == model.body("mjrl_target").id
|
||||
perturb.select = body
|
||||
perturb.localpos[:] = data.xmat[body].reshape(3, 3).T @ (point - data.xpos[body])
|
||||
mujoco.mjv_initPerturb(model, data, scene, perturb)
|
||||
perturb.active = mujoco.mjtPertBit.mjPERT_TRANSLATE
|
||||
mujoco.mjv_movePerturb(
|
||||
model, data, mujoco.mjtMouse.mjMOUSE_MOVE_H, 0.4, 0.15, scene, perturb
|
||||
)
|
||||
mujoco.mjv_applyPerturbPose(model, data, perturb, 0)
|
||||
raw_offset = data.mocap_pos[ik.mocap] - origin
|
||||
assert abs(raw_offset[0]) > 0.02
|
||||
expected = origin + np.clip(raw_offset, [-0.02, -0.03, -0.2], [0.02, 0.03, 0.2])
|
||||
for _ in range(55):
|
||||
app.step(keys=())
|
||||
np.testing.assert_allclose(
|
||||
app.data.site_xpos[app.controller.ik.site], [0.08, -0.05, 0], atol=1e-4
|
||||
)
|
||||
np.testing.assert_allclose(data.mocap_pos[ik.mocap], expected)
|
||||
np.testing.assert_allclose(data.site_xpos[ik.site], expected, atol=1e-4)
|
||||
app.step(keys={"key_escape"})
|
||||
np.testing.assert_equal(app.data.mocap_pos[0], [0, 0, 0])
|
||||
np.testing.assert_allclose(data.mocap_pos[ik.mocap], origin)
|
||||
|
||||
|
||||
def test_sliders_and_trajectory_apply_joint_limits_and_interpolate_by_name(tmp_path):
|
||||
@@ -317,3 +347,121 @@ def test_omni_geometry_lateral_motion_and_uniform_saturation(tmp_path):
|
||||
np.testing.assert_allclose(
|
||||
controller.step(data, {"ang_vel_z": 1}), [1.3, -1.3, -1.3], atol=1e-10
|
||||
)
|
||||
|
||||
|
||||
def test_slider_rate_limit_persists_partial_targets_and_accepts_viewer_edits(tmp_path):
|
||||
_, model, data, sliders = _setup(
|
||||
tmp_path, _ARM, kind="joint_sliders", joints=["x", "y"], target_rate_limits={"x": 0.5}
|
||||
)
|
||||
# The model actuators are ordered y,x. An unlisted joint moves immediately.
|
||||
np.testing.assert_allclose(sliders.step(data, {"x": 1, "y": -.06}), [-.06, 0])
|
||||
data.time = .1
|
||||
np.testing.assert_allclose(sliders.step(data, {"y": .1}), [.1, .05])
|
||||
np.testing.assert_allclose(sliders.step(data), [.1, .05])
|
||||
data.time = .2
|
||||
np.testing.assert_allclose(sliders.step(data, keys=()), [.1, .1])
|
||||
data.time = .5
|
||||
np.testing.assert_allclose(sliders.step(data), [.1, .2])
|
||||
data.ctrl[1] = -.1
|
||||
data.time = .6
|
||||
np.testing.assert_allclose(sliders.step(data, keys=()), [.1, .15])
|
||||
data.time = 1.2
|
||||
np.testing.assert_allclose(sliders.step(data), [.1, -.1])
|
||||
|
||||
mujoco.mj_resetData(model, data)
|
||||
data.qpos[0] = -.02
|
||||
np.testing.assert_allclose(sliders.step(data), [0, -.02])
|
||||
data.time = .1
|
||||
np.testing.assert_allclose(sliders.step(data), [0, -.02])
|
||||
|
||||
|
||||
@pytest.mark.parametrize("release", [{"keys": {"key_escape"}}, {"pad": {"B": True}}])
|
||||
@pytest.mark.parametrize("hold_release", [True, False])
|
||||
def test_slider_rate_limited_operator_return_completes_after_tap_or_hold(
|
||||
tmp_path, release, hold_release
|
||||
):
|
||||
_, _, data, sliders = _setup(
|
||||
tmp_path, _ARM, kind="joint_sliders", joints=["x", "y"], home={"x": -.1, "y": 0},
|
||||
operator_axes=["x"], target_rate_limits={"x": 0.5},
|
||||
)
|
||||
data.time = .5
|
||||
np.testing.assert_allclose(sliders.step(data, pad={"Ly": -1}), [0, .2])
|
||||
data.time = .52
|
||||
np.testing.assert_allclose(sliders.step(data, **release), [0, .19])
|
||||
data.time = .54
|
||||
following = release if hold_release else {"keys": ()}
|
||||
np.testing.assert_allclose(sliders.step(data, **following), [0, .18])
|
||||
data.time = 1.2
|
||||
np.testing.assert_allclose(sliders.step(data, **following), [0, -.1])
|
||||
|
||||
|
||||
@pytest.mark.parametrize("limits", [None, 0.5, {"other": 1}, {"x": 0}, {"x": -1},
|
||||
{"y": float("nan")}, {"y": True}])
|
||||
def test_slider_rate_limits_validate_names_and_positive_finite_rates(tmp_path, limits):
|
||||
with pytest.raises(ValueError, match="target_rate_limits"):
|
||||
_setup(tmp_path, _ARM, kind="joint_sliders", joints=["x", "y"], target_rate_limits=limits)
|
||||
|
||||
|
||||
def _servo_fixture(actuator, joint_range="", transmission="joint"):
|
||||
return f"""<mujoco><compiler angle="radian"/><worldbody><body>
|
||||
<joint name="axis" {joint_range}/><geom size=".02"/>
|
||||
</body></worldbody><actuator><{actuator} {transmission}="axis"/></actuator></mujoco>"""
|
||||
|
||||
|
||||
@pytest.mark.parametrize("actuator,joint_range,expected", [
|
||||
('position ctrlrange="-3.141592 3.141592"', "", [-3.141592, 3.141592]),
|
||||
('position gear="-2" ctrlrange="-.5 1.5"', "", [-.75, .25]),
|
||||
('general gear="2" gainprm="3" biastype="affine" biasprm="0 -3 -1" ctrlrange="-.5 1.5"',
|
||||
'range="-.5 .5"', [-.25, .5]),
|
||||
('position timeconst=".02" ctrlrange="-.1 .2"', "", [-.1, .2]),
|
||||
('position kp="10" inheritrange=".5"', 'range="-1 1"', [-.5, .5]),
|
||||
])
|
||||
def test_normalized_servo_preserves_length_target_in_joint_units(
|
||||
tmp_path, actuator, joint_range, expected
|
||||
):
|
||||
_, model, data, controller = _setup(
|
||||
tmp_path, _servo_fixture(actuator, joint_range), kind="joint_sliders", joints=["axis"]
|
||||
)
|
||||
assert model.actuator_ctrllimited[0]
|
||||
np.testing.assert_array_equal(model.actuator_ctrlrange[0], expected)
|
||||
for command, bound in zip([-10, 10], expected, strict=True):
|
||||
np.testing.assert_array_equal(controller.step(data, {"axis": command}), [bound])
|
||||
# A raw MuJoCo user can bypass the controller. At the target boundary
|
||||
# the servo must also hold zero force for an out-of-range native input.
|
||||
data.qpos[0] = bound
|
||||
data.ctrl[0] = command
|
||||
mujoco.mj_forward(model, data)
|
||||
assert data.actuator_force[0] == pytest.approx(0, abs=1e-12)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("actuator", [
|
||||
'motor ctrlrange="-.1 .1"', 'velocity ctrlrange="-.1 .1"',
|
||||
'position ctrllimited="false" ctrlrange="-.1 .1"',
|
||||
])
|
||||
def test_non_position_inputs_and_disabled_limits_do_not_restrict_joint_targets(tmp_path, actuator):
|
||||
_, model, data, controller = _setup(
|
||||
tmp_path, _servo_fixture(actuator), kind="joint_sliders", joints=["axis"]
|
||||
)
|
||||
assert not model.actuator_ctrllimited[0]
|
||||
np.testing.assert_array_equal(controller.step(data, {"axis": .5}), [.5])
|
||||
|
||||
|
||||
@pytest.mark.parametrize("actuator,joint_range,error", [
|
||||
('position gear="-2" ctrlrange="2 4"', 'range="0 1"', "do not overlap"),
|
||||
('general biastype="affine" biasprm=".1 -3 -1" gainprm="3" ctrlrange="-1 1"', "",
|
||||
"Cannot infer position target bounds"),
|
||||
('intvelocity kp="3" actrange="-2 2" ctrlrange="-1 1"', "",
|
||||
"Cannot infer position target bounds"),
|
||||
])
|
||||
def test_normalization_rejects_incompatible_position_bounds(tmp_path, actuator, joint_range, error):
|
||||
with pytest.raises(ValueError, match=error):
|
||||
_setup(tmp_path, _servo_fixture(actuator, joint_range), kind="joint_sliders", joints=["axis"])
|
||||
assert not (tmp_path / "joint_sliders").exists()
|
||||
|
||||
|
||||
def test_parent_frame_scalar_transmission_reuses_the_source_servo(tmp_path):
|
||||
xml = _servo_fixture('position gear="-2" ctrlrange="-.2 .8"', transmission="jointinparent")
|
||||
_, model, data, controller = _setup(tmp_path, xml, kind="joint_sliders", joints=["axis"])
|
||||
assert model.nu == 1
|
||||
np.testing.assert_array_equal(model.actuator_ctrlrange[0], [-.4, .1])
|
||||
np.testing.assert_array_equal(controller.step(data, {"axis": 1}), [.1])
|
||||
|
||||
+37
-2
@@ -111,8 +111,43 @@ def _generate_controls(path: Path, *options: str):
|
||||
return load_controls(path)
|
||||
|
||||
|
||||
def test_controls_writer_defaults_to_omni(tmp_path) -> None:
|
||||
controls = _generate_controls(tmp_path / "omni.yaml")
|
||||
def test_default_walking_controls_drive_training_and_native_policy(tmp_path) -> None:
|
||||
import yaml
|
||||
from mjrl.controllers.bindings import WALKING_CONTROLS, walking_controls
|
||||
from mjrl.controllers.input import OperatorInput
|
||||
from mjrl.tasks.operator import Operator, spans
|
||||
|
||||
full = load_controls(WALKING_CONTROLS)
|
||||
names = [axis.name for axis in full.command("twist").axes]
|
||||
edges = spans(full.command("twist"), _env_cfg().commands["twist"])
|
||||
native_path = tmp_path / "adapted.yaml"
|
||||
native_path.write_text(yaml.safe_dump(walking_controls(names)))
|
||||
for controls in (full, _generate_controls(tmp_path / "generated.yaml"), load_controls(native_path)):
|
||||
for keys, target in [
|
||||
(("key_w",), [.6, 0, 0]), (("key_s",), [-.3, 0, 0]),
|
||||
(("key_a",), [0, 0, .7]), (("key_d",), [0, 0, -.7]),
|
||||
(("key_w", "key_a"), [.6, 0, .7]), (("key_w", "key_s"), [0, 0, 0]),
|
||||
]:
|
||||
clock = _Clock()
|
||||
op = Operator(controls, listen=False, clock=clock)
|
||||
op.attach("twist", edges)
|
||||
for key in keys:
|
||||
op.key(key, True)
|
||||
native = OperatorInput(controls, edges)
|
||||
native.read({}, keys, 0, 0)
|
||||
clock.t = controls.full_after_s
|
||||
assert op.command("twist") == pytest.approx(target)
|
||||
values = native.read({}, keys, clock.t, clock.t)
|
||||
assert [values[name] for name in names] == pytest.approx(target)
|
||||
for key in keys:
|
||||
op.key(key, False)
|
||||
assert op.command("twist") == pytest.approx([0, 0, 0])
|
||||
assert all(value == 0 for value in native.read({}, (), clock.t, 0).values())
|
||||
|
||||
|
||||
@pytest.mark.parametrize("options", [("--profile", "omni"), ("--task", "multipod_example")])
|
||||
def test_omni_controls_preserve_lateral_keys(tmp_path, options) -> None:
|
||||
controls = _generate_controls(tmp_path / "omni.yaml", *options)
|
||||
assert "key_a" in controls.key_axes["lin_vel_y"].plus
|
||||
assert "key_d" in controls.key_axes["lin_vel_y"].minus
|
||||
assert controls.key_axes["ang_vel_z"].plus == ("key_j",)
|
||||
|
||||
@@ -111,6 +111,9 @@ def built(neutral_robot):
|
||||
with pytest.MonkeyPatch.context() as mp:
|
||||
mp.delenv(LEVEL_ENV, raising=False)
|
||||
cfg = env_cfg(neutral_robot)
|
||||
# This fixture tests generic multi-rung resume, independently of the
|
||||
# biped recipe's intentional full-range, single-rung training policy.
|
||||
cfg.curriculum["command"].params["fractions"] = (.4, .7, 1.)
|
||||
cfg.scene.num_envs = N_ENVS
|
||||
env = ManagerBasedRlEnv(cfg, device="cpu")
|
||||
wrapped = RslRlVecEnvWrapper(env)
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
"""A zero residual scale retains position control while removing policy authority."""
|
||||
from dataclasses import replace
|
||||
|
||||
import pytest
|
||||
import torch
|
||||
|
||||
|
||||
def test_zero_scale_holds_home_without_disabling_the_actuator(neutral_robot):
|
||||
from mjlab.envs import ManagerBasedRlEnv
|
||||
from mjlab.sim import get_simulation_cls, set_simulation_cls
|
||||
from mjrl.backend import native_sim
|
||||
from mjrl.backend.resolve import resolve
|
||||
from mjrl.backend.select import use_backend
|
||||
from tasks.templates.Biped_Template.env_cfg import env_cfg
|
||||
|
||||
held = replace(neutral_robot.position_joints[0], action_scale=0.0)
|
||||
robot = replace(neutral_robot, position_joints=(held, *neutral_robot.position_joints[1:]))
|
||||
previous, threads = get_simulation_cls(), native_sim._DEFAULT_NTHREAD
|
||||
env = None
|
||||
try:
|
||||
use_backend(resolve(backend='native', device='cpu', num_envs=1))
|
||||
env = ManagerBasedRlEnv(env_cfg(robot, play=True), device='cpu')
|
||||
action = env.action_manager.get_term('joint_pos')
|
||||
action.process_actions(torch.tensor([[100.0, 1.0]]))
|
||||
assert action._processed_actions[0, 0].item() == pytest.approx(held.home)
|
||||
moving = robot.position_joints[1]
|
||||
assert action._processed_actions[0, 1].item() == pytest.approx(moving.home + moving.action_scale)
|
||||
# A held action is still a powered PD joint, not an omitted/passive DOF.
|
||||
actuator = env.scene['robot'].actuators[0]
|
||||
assert actuator.stiffness[0, 0].item() == pytest.approx(held.kp)
|
||||
assert actuator.force_limit[0, 0].item() == pytest.approx(held.effort_limit)
|
||||
action.process_actions(torch.tensor([[-100.0, -1.0]]))
|
||||
assert action._processed_actions[0, 0].item() == pytest.approx(held.home)
|
||||
assert action._processed_actions[0, 1].item() == pytest.approx(moving.home - moving.action_scale)
|
||||
finally:
|
||||
if env is not None:
|
||||
env.close()
|
||||
set_simulation_cls(previous)
|
||||
native_sim._DEFAULT_NTHREAD = threads
|
||||
|
||||
|
||||
def test_negative_and_entirely_held_locomotion_actions_are_rejected(neutral_robot):
|
||||
with pytest.raises(ValueError, match='action_scale'):
|
||||
replace(neutral_robot.position_joints[0], action_scale=-.1)
|
||||
with pytest.raises(ValueError, match='at least one joint'):
|
||||
replace(neutral_robot, position_joints=tuple(
|
||||
replace(joint, action_scale=0.0) for joint in neutral_robot.position_joints))
|
||||
|
||||
|
||||
def test_velocity_actuator_still_requires_nonzero_scale():
|
||||
from pathlib import Path
|
||||
from tasks.robot_spec import read_robot_spec
|
||||
|
||||
robot = read_robot_spec(Path(__file__).resolve().parents[1] / 'tasks/wheeled_biped_example/robot_spec.py')
|
||||
with pytest.raises(ValueError, match='action_scale>0'):
|
||||
replace(robot, velocity_joints=tuple(replace(joint, action_scale=0.0) for joint in robot.velocity_joints))
|
||||
@@ -283,12 +283,12 @@ def test_usage_doc_matches_the_code() -> None:
|
||||
for name in ("def register(", "def load_env_cfg(", "def load_agent_cfg("):
|
||||
assert name in registry, f"{name}, mentioned in USAGE, is not in the registry"
|
||||
|
||||
# The .env keys in the manual must match the repository's .env
|
||||
# The .env keys in the manual must match the repository's .env.example
|
||||
import re
|
||||
|
||||
doc_keys = set(re.findall(r"^(MJRL_[A-Z_]+)=", usage, re.M))
|
||||
env_keys = set(
|
||||
re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env").read_text(encoding="utf-8"), re.M)
|
||||
re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env.example").read_text(encoding="utf-8"), re.M)
|
||||
)
|
||||
assert doc_keys == env_keys, (
|
||||
f"USAGE and .env keys disagree.\nExtra in the document: "
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
"""Reset discontinuities and contact chatter must remain visible in diagnostics."""
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
from tools.checks.diagnose_locomotion_policy import contact_events, summarize_samples
|
||||
|
||||
|
||||
def _samples():
|
||||
target = np.array([0., 0., 100., 0., 2., 2.]).reshape(6, 1, 1)
|
||||
done = np.zeros((6, 1), dtype=bool)
|
||||
done[2] = True
|
||||
velocity = np.full((6, 1, 3), .2)
|
||||
velocity[2] = 999.
|
||||
reward = np.full((6, 1, 1), 1.)
|
||||
reward[2] = 999.
|
||||
root = np.zeros((6, 1, 3))
|
||||
root[..., 2] = 1.1
|
||||
root[2, :, 2] = .2
|
||||
return dict(action=target.copy(), target=target, qpos=target.copy(), torque=target.copy(),
|
||||
dones=done, contacts=np.ones((6, 1, 2), dtype=bool),
|
||||
height=np.zeros((6, 1, 2)), velocity=velocity, rewards=reward,
|
||||
root_height=root[..., 2], root_link_pos_w=root)
|
||||
|
||||
|
||||
def test_reset_frames_are_excluded_but_real_target_jumps_remain():
|
||||
sample = _samples()
|
||||
sample['angular_velocity'] = np.full((6, 1, 3), .3)
|
||||
sample['angular_velocity'][2] = 999.
|
||||
result = summarize_samples(sample, .02, ['joint'], np.array([10.]), ['reward'],
|
||||
np.array([.2, .2, 0.]))
|
||||
assert result['valid_samples'] == 5 and result['excluded_reset_samples'] == 1
|
||||
assert result['valid_target_difference_samples'] == 3
|
||||
# The real 0->2 rad action transition remains; 0->100->0 reset edges vanish.
|
||||
assert result['joints']['joint']['target_speed_rms_rad_s'] == pytest.approx(100 / np.sqrt(3))
|
||||
assert result['joints']['joint']['qpos']['max'] == 2.
|
||||
assert result['joints']['joint']['torque_saturation_fraction'] == 0.
|
||||
assert result['reward_rate']['reward'] == 1.
|
||||
assert result['mean_velocity'] == pytest.approx([.2, .2, .2])
|
||||
assert result['mean_velocity_axes'] == ['vx', 'vy', 'vz']
|
||||
assert result['mean_angular_velocity'] == pytest.approx([.3, .3, .3])
|
||||
assert result['mean_yaw_tracking_error'] == pytest.approx(.3)
|
||||
assert result['mean_height'] == pytest.approx(1.1)
|
||||
assert result['root_height_m']['min'] == pytest.approx(1.1)
|
||||
# A control without resets must detect the large real jump, not suppress it.
|
||||
sample['dones'][:] = False
|
||||
control = summarize_samples(sample, .02, ['joint'], np.array([10.]), ['reward'],
|
||||
np.array([.2, .2, 0.]))
|
||||
assert control['joints']['joint']['target_speed_rms_rad_s'] > 3000.
|
||||
assert control['joints']['joint']['qpos']['max'] == 100.
|
||||
assert control['joints']['joint']['torque_saturation_fraction'] > 0.
|
||||
|
||||
|
||||
def test_stance_slip_ignores_swing_and_reset_samples():
|
||||
sample = _samples()
|
||||
sample['sole_velocity_w'] = np.zeros((6, 1, 2, 3))
|
||||
sample['sole_velocity_w'][..., 0] = .03
|
||||
sample['sole_velocity_w'][2] = 999. # Reset frame.
|
||||
sample['contacts'][3, 0, 1] = False
|
||||
sample['sole_velocity_w'][3, 0, 1] = 100. # Airborne foot.
|
||||
result = summarize_samples(sample, .02, ['joint'], np.array([10.]), ['reward'],
|
||||
np.array([.2, .2, 0.]))
|
||||
assert result['stance_sole_horizontal_speed_m_s']['max'] == pytest.approx(.03)
|
||||
assert result['joints']['joint']['qpos']['per_env_p95_p05_excursion_rad'] == [2.]
|
||||
|
||||
|
||||
def test_reset_aborts_swings_and_same_foot_periods_do_not_bridge_episodes():
|
||||
contacts = np.ones((14, 1, 2), dtype=bool)
|
||||
contacts[[1, 2, 4, 5, 7, 8, 11, 12], 0, 0] = False
|
||||
dones = np.zeros((14, 1), dtype=bool)
|
||||
dones[5] = True
|
||||
height = np.where(contacts, 0., .03)
|
||||
result = contact_events(contacts, height, dones, .02)
|
||||
assert result['completed_swings_per_env_foot'] == [[3, 0]]
|
||||
summary = result['contact_event_summary']
|
||||
assert summary['complete_event_count'] == 3
|
||||
assert summary['airtime_s']['median'] == pytest.approx(.04)
|
||||
assert summary['same_foot_landing_period_s']['min'] == pytest.approx(.08)
|
||||
assert summary['same_foot_landing_period_s']['max'] == pytest.approx(.08)
|
||||
assert summary['events_airtime_ge_0_1s_and_height_ge_0_02m'] == 0
|
||||
|
||||
|
||||
@pytest.mark.parametrize('dt', [.01, .02])
|
||||
def test_descriptive_threshold_does_not_change_existing_40ms_count(dt):
|
||||
# One 40ms shallow event and one 120ms higher event; include leading and
|
||||
# trailing truncated air phases, neither of which is a complete swing.
|
||||
states = [False, True] + [False] * round(.04 / dt) + [True, True] \
|
||||
+ [False] * round(.12 / dt) + [True, True, False]
|
||||
contacts = np.ones((len(states), 1, 2), dtype=bool)
|
||||
contacts[:, 0, 0] = states
|
||||
heights = np.where(contacts, 0., .01)
|
||||
start = 4 + round(.04 / dt)
|
||||
heights[start:start + round(.12 / dt), 0, 0] = .03
|
||||
result = contact_events(contacts, heights, np.zeros((len(states), 1), dtype=bool), dt)
|
||||
assert result['completed_swings_per_env_foot'] == [[2, 0]]
|
||||
summary = result['contact_event_summary']
|
||||
assert summary['complete_event_count'] == 2
|
||||
assert summary['airtime_s']['min'] == pytest.approx(.04)
|
||||
assert summary['airtime_s']['max'] == pytest.approx(.12)
|
||||
assert summary['events_airtime_ge_0_1s_and_height_ge_0_02m'] == 1
|
||||
|
||||
|
||||
def test_one_frame_chatter_is_described_but_not_counted_as_40ms_swing():
|
||||
contacts = np.ones((3, 1, 2), dtype=bool)
|
||||
contacts[1, 0, 0] = False
|
||||
result = contact_events(contacts, np.where(contacts, 0., .005),
|
||||
np.zeros((3, 1), dtype=bool), .02)
|
||||
assert result['completed_swings_per_env_foot'] == [[0, 0]]
|
||||
assert result['contact_event_summary']['complete_event_count'] == 1
|
||||
assert result['contact_event_summary']['airtime_s']['median'] == .02
|
||||
assert result['contact_event_summary']['same_foot_landing_period_s'] is None
|
||||
|
||||
|
||||
def test_no_usable_samples_fails_explicitly():
|
||||
sample = _samples()
|
||||
sample['dones'][:] = True
|
||||
with pytest.raises(ValueError, match='No non-reset samples'):
|
||||
summarize_samples(sample, .02, ['joint'], [10.], ['reward'], np.zeros(3))
|
||||
@@ -81,7 +81,7 @@ def test_training_only_randomization_and_wheel_exclusion(neutral_robot):
|
||||
|
||||
cfg = env_cfg(neutral_robot)
|
||||
assert cfg.observations["actor"].history_length == 4
|
||||
assert {"joint_home", "lin_vel_z", "ang_vel_xy", "support_slip", "missing_support"} <= cfg.rewards.keys()
|
||||
assert {"pose", "single_support", "lin_vel_z", "ang_vel_xy", "support_slip", "missing_support"} <= cfg.rewards.keys()
|
||||
assert {"base_density", "base_com", "pd_gains", "support_friction"} <= cfg.events.keys()
|
||||
play = env_cfg(neutral_robot, play=True)
|
||||
assert play.observations["actor"].history_length == 4
|
||||
|
||||
+47
-3
@@ -116,9 +116,6 @@ def test_the_csv_header_still_describes_its_rows(tmp_path: Path) -> None:
|
||||
monitor = JointMonitor(
|
||||
_Entity(), 0, 0.01, tmp_path, sensor=_Feet(), foot_names=feet
|
||||
)
|
||||
# The window may or may not have opened depending on the machine; the csv is
|
||||
# what this is about.
|
||||
monitor._fig = None
|
||||
for _ in range(4):
|
||||
monitor.update()
|
||||
monitor.close()
|
||||
@@ -170,3 +167,50 @@ def test_a_bundle_is_a_directory_checkpoint_can_be_pointed_at(tmp_path) -> None:
|
||||
(bare / "actor.onnx").write_bytes(b"")
|
||||
with pytest.raises(FileNotFoundError):
|
||||
find_checkpoint(str(bare), tmp_path)
|
||||
|
||||
|
||||
def test_measurement_only_probes_gui_when_explicitly_interactive(tmp_path, monkeypatch):
|
||||
from types import SimpleNamespace
|
||||
from mjrl.viewer import monitor as module
|
||||
|
||||
events = []
|
||||
|
||||
def probe():
|
||||
events.append('probe')
|
||||
return 'QtAgg', {'QT_API': 'pyqt5'}
|
||||
|
||||
def open_window(self, backend, env):
|
||||
events.append((backend, env))
|
||||
|
||||
monkeypatch.setattr(module, '_interactive_backend', probe)
|
||||
monkeypatch.setattr(module.JointMonitor, '_open_window', open_window)
|
||||
entity = SimpleNamespace(joint_names=('hip',), actuator_names=('hip',))
|
||||
env = SimpleNamespace(step_dt=.01)
|
||||
measurement = module.make_monitor(entity, 0, env, tmp_path)
|
||||
assert measurement._fig is None
|
||||
assert events == []
|
||||
# Control proves the explicitly requested live view still probes and opens.
|
||||
module.make_monitor(entity, 0, env, tmp_path, interactive=True)
|
||||
assert events == ['probe', ('QtAgg', {'QT_API': 'pyqt5'})]
|
||||
|
||||
|
||||
def test_saved_plot_uses_no_interactive_figure_even_with_live_window(tmp_path, monkeypatch):
|
||||
from types import SimpleNamespace
|
||||
from matplotlib import pyplot
|
||||
from mjrl.viewer.monitor import JointMonitor
|
||||
|
||||
def unexpected(*args, **kwargs):
|
||||
raise AssertionError('artifact export opened an interactive figure')
|
||||
|
||||
monkeypatch.setattr(pyplot, 'figure', unexpected)
|
||||
monkeypatch.setattr(pyplot, 'subplots', unexpected)
|
||||
measurement = JointMonitor(SimpleNamespace(joint_names=('hip',), actuator_names=('hip',)),
|
||||
0, .01, tmp_path)
|
||||
measurement._fig = object() # Existing live monitor must not affect export.
|
||||
measurement._t = [0., .01]
|
||||
measurement._pos = [[0.], [.1]]
|
||||
measurement._vel = [[0.], [1.]]
|
||||
measurement._tau = [[0.], [.5]]
|
||||
png = tmp_path / 'measure.png'
|
||||
measurement._write_png(png)
|
||||
assert png.read_bytes().startswith(b'\x89PNG\r\n\x1a\n')
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
"""Fusion can reorder geoms; serialization must preserve poses at full precision."""
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
mujoco = pytest.importorskip('mujoco')
|
||||
|
||||
from mjrl.onboarding.build import write_mjcf
|
||||
|
||||
|
||||
def _source(tmp_path):
|
||||
(tmp_path / 'shape.obj').write_text('''v 0 0 0
|
||||
v .1 0 0
|
||||
v 0 .2 0
|
||||
v 0 0 .3
|
||||
f 1 3 2
|
||||
f 1 2 4
|
||||
f 1 4 3
|
||||
f 2 3 4
|
||||
''')
|
||||
path = tmp_path / 'robot.xml'
|
||||
path.write_text('''<mujoco><compiler fusestatic="true"/>
|
||||
<asset><mesh name="shape" file="shape.obj"/></asset><worldbody>
|
||||
<body name="base"><joint name="axis"/><geom size=".1"/>
|
||||
<body name="fixed_a" pos=".1234567890123 .032123456789 .2"
|
||||
quat=".998412345 .00123456789 .0423456789 .03123456789">
|
||||
<geom name="first" type="mesh" mesh="shape"/>
|
||||
<geom name="second" size=".03" pos=".01 .02 .03"/>
|
||||
<body name="nested" pos=".0123456789 .02345678901 .03456789012">
|
||||
<geom name="nested_geom" type="mesh" mesh="shape"/>
|
||||
</body>
|
||||
</body>
|
||||
<body name="fixed_b" pos=".2 0 0"><geom name="last" size=".02"/></body>
|
||||
</body></worldbody></mujoco>''')
|
||||
return path
|
||||
|
||||
|
||||
def test_fusion_order_and_mesh_poses_preserved(tmp_path, monkeypatch):
|
||||
from mjrl.platform import _serialization
|
||||
|
||||
serialize = _serialization.spec_xml
|
||||
|
||||
def reordered(spec):
|
||||
root = ET.fromstring(serialize(spec))
|
||||
parent = root.find(".//body[@name='fixed_a']")
|
||||
geoms = parent.findall('geom')
|
||||
for geom in geoms:
|
||||
parent.remove(geom)
|
||||
for index, geom in enumerate(reversed(geoms)):
|
||||
parent.insert(index, geom)
|
||||
return ET.tostring(root, encoding='unicode')
|
||||
|
||||
monkeypatch.setattr(_serialization, 'spec_xml', reordered)
|
||||
source = _source(tmp_path)
|
||||
spec = mujoco.MjSpec.from_file(str(source))
|
||||
original = mujoco.MjModel.from_xml_path(str(source))
|
||||
copied = write_mjcf(spec, source, tmp_path / 'output' / 'robot.xml')
|
||||
assert original.nbody == copied.nbody == 2
|
||||
assert copied.geom(0).name == ''
|
||||
assert '__mjrl_roundtrip_' not in (tmp_path / 'output' / 'robot.xml').read_text()
|
||||
# Native fusion changes IDs after canonicalization; prove the test has a
|
||||
# reordered geom and then verify each object by its actual identity.
|
||||
assert original.geom('first').id != copied.geom('first').id
|
||||
for name in ['first', 'nested_geom', 'last']:
|
||||
a, b = original.geom(name).id, copied.geom(name).id
|
||||
np.testing.assert_allclose(original.geom_pos[a], copied.geom_pos[b], atol=1e-12, rtol=0)
|
||||
np.testing.assert_allclose(original.geom_quat[a], copied.geom_quat[b], atol=1e-12, rtol=0)
|
||||
np.testing.assert_allclose(original.body_inertia, copied.body_inertia, atol=1e-9)
|
||||
|
||||
|
||||
def test_roundtrip_still_rejects_transform_corruption(tmp_path, monkeypatch):
|
||||
source = _source(tmp_path)
|
||||
load = mujoco.MjModel.from_xml_path
|
||||
|
||||
def corrupted(path):
|
||||
model = load(path)
|
||||
model.geom_pos[model.geom('first').id, 0] += .01
|
||||
return model
|
||||
|
||||
monkeypatch.setattr(mujoco.MjModel, 'from_xml_path', corrupted)
|
||||
output = tmp_path / 'output' / 'robot.xml'
|
||||
with pytest.raises(ValueError, match='round-trip changed geom_pos'):
|
||||
write_mjcf(mujoco.MjSpec.from_file(str(source)), source, output)
|
||||
assert not output.exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize('raises', [False, True])
|
||||
def test_precision_restored_on_success_and_error(raises):
|
||||
from mjrl.platform._serialization import _precision_api, spec_xml
|
||||
|
||||
api = _precision_api()
|
||||
if api is None:
|
||||
pytest.skip('native writer precision hooks unavailable')
|
||||
get, set_ = api
|
||||
previous = get()
|
||||
|
||||
class Writer:
|
||||
def to_xml(self):
|
||||
assert get() == 17
|
||||
if raises:
|
||||
raise ValueError('writer error')
|
||||
return '<mujoco/>'
|
||||
|
||||
try:
|
||||
set_(9)
|
||||
if raises:
|
||||
with pytest.raises(ValueError, match='writer error'):
|
||||
spec_xml(Writer())
|
||||
else:
|
||||
assert spec_xml(Writer()) == '<mujoco/>'
|
||||
assert get() == 9
|
||||
finally:
|
||||
set_(previous)
|
||||
|
||||
|
||||
def test_precision_fallback_without_native_hooks(monkeypatch):
|
||||
from mjrl.platform import _serialization
|
||||
|
||||
monkeypatch.setattr(_serialization, '_precision_api', lambda: None)
|
||||
|
||||
class Writer:
|
||||
def to_xml(self):
|
||||
return '<mujoco/>'
|
||||
|
||||
assert _serialization.spec_xml(Writer()) == '<mujoco/>'
|
||||
|
||||
|
||||
def test_packaged_copy_preserves_precision(tmp_path):
|
||||
from mjrl.platform.model import copy_model
|
||||
|
||||
source = _source(tmp_path)
|
||||
before = mujoco.MjModel.from_xml_path(str(source))
|
||||
output = tmp_path / 'app' / 'robot.xml'
|
||||
copy_model(source, output)
|
||||
after = mujoco.MjModel.from_xml_path(str(output))
|
||||
assert '__mjrl_roundtrip_' not in output.read_text()
|
||||
for name in ['first', 'nested_geom', 'last']:
|
||||
a, b = before.geom(name).id, after.geom(name).id
|
||||
np.testing.assert_allclose(before.geom_pos[a], after.geom_pos[b], atol=1e-12, rtol=0)
|
||||
np.testing.assert_allclose(before.geom_quat[a], after.geom_quat[b], atol=1e-12, rtol=0)
|
||||
|
||||
|
||||
@pytest.mark.parametrize('packaged', [False, True])
|
||||
def test_temporary_names_do_not_strip_other_object_names(tmp_path, packaged):
|
||||
from mjrl.platform.model import copy_model
|
||||
|
||||
source = tmp_path / 'source.xml'
|
||||
source.write_text('''<mujoco><worldbody><body><joint name="j"/>
|
||||
<geom size=".1"/><site name="__mjrl_roundtrip_1" size=".01"/>
|
||||
</body></worldbody><sensor><framepos name="p" objtype="site"
|
||||
objname="__mjrl_roundtrip_1"/></sensor></mujoco>''')
|
||||
output = tmp_path / 'result.xml'
|
||||
if packaged:
|
||||
copy_model(source, output)
|
||||
else:
|
||||
write_mjcf(mujoco.MjSpec.from_file(str(source)), source, output)
|
||||
model = mujoco.MjModel.from_xml_path(str(output))
|
||||
assert model.site('__mjrl_roundtrip_1').id == 0
|
||||
assert model.body(1).name == ''
|
||||
assert model.geom(0).name == ''
|
||||
|
||||
|
||||
@pytest.mark.parametrize('packaged', [False, True])
|
||||
def test_massless_collision_defaults_preserve_inferred_inertia(tmp_path, packaged):
|
||||
from mjrl.platform.model import copy_model
|
||||
|
||||
# Include the body so packaging must flatten the spec. Both zero settings
|
||||
# together trigger the native writer's elision of the collision default.
|
||||
(tmp_path / 'body.xml').write_text('''<mujoco><body name="link">
|
||||
<joint name="hinge"/><geom size=".1" mass="1.25"/>
|
||||
<geom class="pad" size=".2" pos="0 .25 0"/>
|
||||
<geom class="pad" size=".15" pos=".25 0 0" mass=".5"/>
|
||||
</body></mujoco>''')
|
||||
source = tmp_path / 'scene.xml'
|
||||
source.write_text('''<mujoco><default><default class="collision">
|
||||
<geom density="0" mass="0"/><default class="pad"/>
|
||||
</default></default><worldbody><include file="body.xml"/></worldbody></mujoco>''')
|
||||
before = mujoco.MjModel.from_xml_path(str(source))
|
||||
assert before.body('link').mass.item() == 1.75
|
||||
output = tmp_path / 'output' / 'robot.xml'
|
||||
if packaged:
|
||||
copy_model(source, output)
|
||||
else:
|
||||
write_mjcf(mujoco.MjSpec.from_file(str(source)), source, output)
|
||||
after = mujoco.MjModel.from_xml_path(str(output))
|
||||
for field in ('body_mass', 'body_inertia', 'body_ipos', 'body_iquat'):
|
||||
np.testing.assert_array_equal(getattr(after, field), getattr(before, field))
|
||||
assert all(after.geom(gid).name == '' for gid in range(after.ngeom))
|
||||
@@ -0,0 +1,110 @@
|
||||
"""Relocating flattened MJCF must preserve exact compiled dynamics and defaults."""
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
mujoco = pytest.importorskip('mujoco')
|
||||
|
||||
from mjrl.platform.model import copy_model, validate_contained_model
|
||||
|
||||
|
||||
def _model(tmp_path):
|
||||
(tmp_path / 'shape.obj').write_text('''v 0 0 0
|
||||
v .1 0 0
|
||||
v 0 .2 0
|
||||
v 0 0 .3
|
||||
f 1 3 2
|
||||
f 1 2 4
|
||||
f 1 4 3
|
||||
f 2 3 4
|
||||
''')
|
||||
source = tmp_path / 'source.xml'
|
||||
source.write_text('''<mujoco><compiler angle="radian"/>
|
||||
<option timestep=".0025" integrator="implicitfast"/>
|
||||
<default><default class="part"><geom friction=".812345678901234 .01 .001"/>
|
||||
<joint damping=".123456789012345"/></default></default>
|
||||
<asset><mesh name="shape" file="shape.obj"/></asset><worldbody>
|
||||
<geom type="plane" size="2 2 .1"/>
|
||||
<body name="robot" pos="0 0 .3" quat=".998412345 .00123456789 .0423456789 .03123456789">
|
||||
<freejoint/><geom type="sphere" size=".1"/>
|
||||
<geom name="visual" type="mesh" mesh="shape" contype="0" conaffinity="0"
|
||||
quat=".912345678901 .001234567891 .234567891234 .123456789123"/>
|
||||
<body name="arm" pos=".1234567890123 0 .05" childclass="part">
|
||||
<joint name="hinge"/><geom name="hand" size=".04"/></body></body>
|
||||
</worldbody><actuator><position joint="hinge" kp="10.1234567890123" kv="1"/>
|
||||
</actuator></mujoco>''')
|
||||
return source
|
||||
|
||||
|
||||
def test_flattened_copy_keeps_exact_compiled_arrays_and_rollout(tmp_path, monkeypatch):
|
||||
from mjrl.platform import _serialization
|
||||
|
||||
def unexpected(spec):
|
||||
raise AssertionError('Flattened XML was unnecessarily reserialized')
|
||||
|
||||
monkeypatch.setattr(_serialization, 'spec_xml', unexpected)
|
||||
source = _model(tmp_path)
|
||||
output = tmp_path / 'app' / 'robot.xml'
|
||||
copy_model(source, output)
|
||||
before = mujoco.MjModel.from_xml_path(str(source))
|
||||
after = mujoco.MjModel.from_xml_path(str(output))
|
||||
for field in dir(before):
|
||||
a, b = getattr(before, field), getattr(after, field)
|
||||
# _sizes includes storage allocated for relocated path strings.
|
||||
if field != "_sizes" and isinstance(a, np.ndarray) and np.issubdtype(a.dtype, np.number):
|
||||
np.testing.assert_array_equal(a, b, err_msg=field)
|
||||
# Numeric defaults and original anonymous objects survive, not just named geoms.
|
||||
assert ET.parse(output).find('.//default[@class="part"]/geom').get('friction') \
|
||||
== '.812345678901234 .01 .001'
|
||||
assert before.geom(0).name == after.geom(0).name == ''
|
||||
(tmp_path / 'shape.obj').unlink()
|
||||
validate_contained_model(output.parent, output)
|
||||
a, b = mujoco.MjData(before), mujoco.MjData(after)
|
||||
for step in range(1000):
|
||||
a.ctrl[:] = b.ctrl[:] = .2 * np.sin(step * .01)
|
||||
mujoco.mj_step(before, a)
|
||||
mujoco.mj_step(after, b)
|
||||
np.testing.assert_array_equal(a.qpos, b.qpos)
|
||||
np.testing.assert_array_equal(a.qvel, b.qvel)
|
||||
|
||||
|
||||
def test_flattened_copy_still_rejects_sub_tolerance_geometry_change(tmp_path, monkeypatch):
|
||||
source = _model(tmp_path)
|
||||
output = tmp_path / 'app' / 'robot.xml'
|
||||
load = mujoco.MjModel.from_xml_path
|
||||
|
||||
def changed(path):
|
||||
model = load(path)
|
||||
if str(path) == str(output):
|
||||
model.geom_pos[0, 0] += 1e-12
|
||||
return model
|
||||
|
||||
monkeypatch.setattr(mujoco.MjModel, 'from_xml_path', changed)
|
||||
with pytest.raises(ValueError, match='flattened model changed exact geom_pos'):
|
||||
copy_model(source, output)
|
||||
|
||||
|
||||
def test_include_and_asset_directory_still_use_normalization(tmp_path):
|
||||
source = _model(tmp_path)
|
||||
xml = ET.parse(source)
|
||||
asset = xml.find('./asset/mesh')
|
||||
(tmp_path / 'assets').mkdir()
|
||||
(tmp_path / 'shape.obj').rename(tmp_path / 'assets/shape.obj')
|
||||
xml.find('compiler').set('meshdir', 'assets')
|
||||
body = xml.find('./worldbody/body')
|
||||
xml.find('worldbody').remove(body)
|
||||
fragment = ET.Element('mujoco')
|
||||
fragment.append(body)
|
||||
ET.ElementTree(fragment).write(tmp_path / 'body.xml')
|
||||
ET.SubElement(xml.find('worldbody'), 'include', file='body.xml')
|
||||
xml.write(source)
|
||||
assert asset.get('file') == 'shape.obj'
|
||||
output = tmp_path / 'app' / 'robot.xml'
|
||||
copy_model(source, output)
|
||||
result = ET.parse(output)
|
||||
assert result.find('.//include') is None
|
||||
assert result.find('compiler').get('meshdir') is None
|
||||
validate_contained_model(output.parent, output)
|
||||
assert mujoco.MjModel.from_xml_path(str(source)).nq \
|
||||
== mujoco.MjModel.from_xml_path(str(output)).nq
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user