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-10-08
- Stars
- ★ 11
- Forks
- 3
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 资源文件 3
- 参考文档references/api-reference.md7.4 KB
- 参考文档references/compatibility.md5.0 KB
- 参考文档references/troubleshooting.md8.9 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
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.