mjx-acceleration
Route optional MyoSuite JAX/MJX acceleration work: probe dependencies and devices, construct MJX environments, use JAX quaternion, fatigue, and reference-motion helpers, and keep CPU substitution and CUDA claims explicit.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- mjx-acceleration
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Route optional MyoSuite JAX/MJX acceleration work: probe dependencies and devices, construct MJX environments, use JAX quaternion, fatigue, and reference-motion helpers, and keep CPU substitution and CUDA claims explicit.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/api-reference.md7.4 KB
- 参考文档references/compatibility.md5.0 KB
- 参考文档references/troubleshooting.md8.9 KB
- 脚本scripts/mjx_probe.py8.3 KB
03 SKILL.md 正文
MJX acceleration
Use this sub-skill only when the user explicitly asks for the optional JAX/MJX or MJWarp route, JAX math parity, JAX fatigue/reference-motion helpers, or backend/device diagnostics. For ordinary MyoSuite environments and MuJoCo CPU workflows, route to the environments sub-skill instead. For policy training recipes, route to training-integration.
Non-negotiable boundary
- Base MyoSuite is a CPU-capable MuJoCo/Gymnasium package.
- MJX is optional; it is not proof that a CPU-only installation can provide acceleration.
- CUDA is a separate optional route. Never report a CUDA speedup without a CUDA-backed JAX device probe and a workload measurement.
- A CPU JAX probe can validate imports, shapes, transforms, and semantics, but it cannot validate CUDA kernels, GPU throughput, or a speedup claim.
- Do not install packages, initialize assets, download data, or run training from the bundled probe. Installation is an explicit user decision.
Read compatibility.md before choosing an installation or device route. Read api-reference.md for signatures and data contracts. Read troubleshooting.md when a probe, parity check, or environment construction fails.
Route selection
-
Run the safe, import-only probe from this directory:
python scripts/mjx_probe.py -
If JAX/MJX is absent, choose one of these honest outcomes:
- stay on the base CPU route and state that MJX is optional and unverified;
- ask permission to install the
mjxextra, then rerun the probe; - ask for a CUDA-capable environment and permission to install
mjx-cudawhen GPU acceleration is required.
-
If MJX is present, probe an environment without training:
python scripts/mjx_probe.py --env-name MjxElbowPoseRandom-v0 --steps 1 -
For a CUDA claim, require both the optional dependencies and a device whose JAX platform is GPU/CUDA. Use
--require-cuda; a CPU result is a backend block, not a substitute:python scripts/mjx_probe.py --require-cuda --env-name MjxElbowPoseRandom-v0
The probe returns JSON only with --json, exits nonzero for a requested
required backend that is unavailable, and otherwise leaves optional absence
as a clearly labelled result.
Minimal MJX environment contract
The public constructor is myosuite.envs.myo.mjx.make(name, config_overrides=None). A normal JAX lifecycle is:
import jax
import jax.numpy as jnp
from myosuite.envs.myo import mjx
env = mjx.make("MjxElbowPoseRandom-v0", config_overrides={"num_envs": 1})
state = env.reset(jax.random.PRNGKey(0))
next_state = env.step(state, jnp.zeros((env.action_size,), dtype=jnp.float32))
reset consumes a JAX PRNG key and returns a MuJoCo Playground-style State.
step returns a new state rather than mutating the old state. The state carries
MJX data, a dictionary observation, scalar reward/done values, metrics, and
information such as the RNG, target, and step count. Confirm action size and
observation keys from the concrete environment; do not assume Gymnasium's
five-value step contract here.
Supported factory names in the inspected implementation are
MjxElbowPoseFixed-v0, MjxElbowPoseRandom-v0, MjxFingerPoseFixed-v0,
MjxFingerPoseRandom-v0, MjxHandReachFixed-v0, and
MjxHandReachRandom-v0. Registering a base environment also exposes fatigue
variants with the MjxFati prefix. Registration is lazy through make; call
make before relying on a name being present in the local registry.
JAX helper routes
- Quaternion/math parity: compare the NumPy helpers in
myosuite.utils.quat_mathwith the JAX helpers inmyosuite.utils.quat_math_jax. Check shape, finite values, rotation-matrix equivalence, and dtype before comparing numerical values. - Fatigue: use
CumulativeFatigue.reset(key, ...)to obtain a state dict withMA,MR, andMF, then pass that state tocompute_act(target_load, state).get_effortreturns the norm of active-minus-target activation. - Fatigue wrapper: configure
fatigue_configwithfatigue_reset_vec,fatigue_reset_random, and allowed observation keysMA,MR,MF. The wrapper stores fatigue state in MJXuserdataand applies fatigue to muscle activations before stepping. - Reference motion: use
ReferenceMotionwith a dict or a supported.npz/ pickle input. It classifies one-frame, two-bound, and multi-frame data as fixed, random, and track references, respectively;get_reference(time)returns aReferenceStruct.
CPU substitution and evidence
CPU substitution is full for base MuJoCo environments and only partial for
this sub-skill. It can validate helper semantics and a CPU JAX execution, but
not GPU placement or acceleration. Preserve an explicit optional-unverified
status when the extra is not installed. Treat benchmark figures as context
only: throughput depends on model contacts, batch size, JAX implementation,
hardware, and compilation/warm-up costs.
Handoff checklist
Before claiming success, record:
- package and optional-extra availability;
jax.devices()and the selected platform;- model/environment name, implementation, action shape, and one-step result;
- parity tolerance, dtype, and quaternion sign handling;
- whether fatigue/reference-motion helpers were actually exercised;
- whether the result is CPU semantic validation, CUDA execution, or an unverified optional route.
The bundled script is deliberately a probe, not a benchmark or installer. Keep long API notes, compatibility rules, and recovery steps in the linked references.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).