---

name: "model-editing-kinematics" description: "Transform MuJoCo model specs safely and solve site-pose inverse kinematics with MyoSuite's CPU APIs, while preserving robot/model contracts and cleaning temporary artifacts." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Model editing and kinematics

Use this sub-skill when a task changes a MuJoCo model before compilation, needs a site pose converted to joint coordinates, or needs quaternion/vector utility semantics. It is an operating guide, not an environment lifecycle, renderer, reference-motion, or MJX-parity guide.

Route the request

1. Identify the input model, the intended edit, the compile target, and the expected cleanup behavior before touching the model.
2. For a one-off XML edit, use ModelEditor(model_path) and keep the edit in a callable edit_fn(spec) -> None. For a reusable pure XML transformation, use the XML helpers described in API reference.
3. For inverse kinematics, name the target site and state whether position, orientation, or both are constrained. Validate target shapes before calling the solver.
4. Prefer a bounded, non-rendering CPU smoke test. Use scripts/ik_smoke.py when a minimal proof is enough.

Core contracts

Model editing

• ModelEditor loads a file into mujoco.MjSpec; it does not return a compiled model from edit_model.
• edit_model(edit_fn=None) mutates the in-memory spec. None is a deliberate no-op and should preserve the serialized spec.
• An edit function should inspect names and properties before deleting, preserve required poses/mesh names, add replacement bodies/geoms/sites, and leave compilation to the caller.
• create_edited_xml() compiles the spec, serializes it, writes a timestamped XML artifact, and returns its path. Compile or write failures happen before a usable artifact is guaranteed.
• Always use try/finally: delete the returned artifact only when it exists, and also clean a partially created path on write/compile failure when the caller owns that path. Never delete the source model.

Kinematics

• qpos_from_site_pose(physics, site_name, target_pos=None, target_quat=None, ...) returns IKResult(qpos, err_norm, steps, success).
• Supply at least one target. Position is shape (3,), orientation is shape (4,) in MuJoCo (w, x, y, z) order; reject malformed or non-finite values.
• joint_names is None, a list, tuple, or NumPy array. Use it to limit degrees of freedom; do not assume joint IDs equal DOF indices.
• Treat success as the gate, not a small-looking qpos change. Inspect err_norm and steps; a failure is diagnostic data, not a valid pose.
• Use inplace=False by default so the caller's state is restored. Use inplace=True only when the caller explicitly wants the data mutated.

Solver controls

Start with defaults and lower the scope before increasing iterations. The important controls are tol, rot_weight, regularization_threshold, regularization_strength, max_update_norm, progress_thresh, and max_steps. Regularization is active while the weighted residual exceeds its threshold; the update is capped by max_update_norm; the progress heuristic can stop a stalled local solve early. The implementation does not enforce joint limits, so validate or clamp the resulting configuration against the model's policy before applying it.

For a failed solve, record the site name, target shapes, selected joints, initial state policy, err_norm, steps, and whether the target is reachable. Retry only with a justified initial state, joint subset, damping/regularization, or iteration bound. Do not silently convert an unreachable target into a success.

Utility routing

• Quaternion composition/difference: mulQuat, negQuat, diffQuat, quatDiff2Vel, quat2Vel.
• Representations: euler2mat, mat2euler, euler2quat, quat2mat, mat2quat, quat2euler, and the intrinsic Euler pair.
• Vector rotation: rotVecMat, rotVecMatT, rotVecQuat.
• Vector alignment: calculate_cosine; equal shapes are required, and zero norms need an explicit interpretation by the caller.
• Tensor packing is shape-preserving bookkeeping: use flatten/unflatten for parameter blocks and stack/concat helpers only when leading dimensions match. These helpers do not change MuJoCo coordinate conventions.

See kinematics workflows for concrete edit, compile, IK, and cleanup sequences. See troubleshooting for failure-specific recovery.

Robot/model relationship

A compiled mujoco.MjModel is the shared boundary between editing and a robot: editing produces an MjSpec, compilation produces the model, and Robot can construct its MjData from either a model path or an already compiled model. Forward the data before reading site/body transforms. Environment code may apply an edit_fn while building its spec and compile afterward; this sub-skill does not own reset, stepping, rewards, or observation lifecycle.

Runtime and safety boundaries

The documented path is base MuJoCo plus NumPy on CPU. MJX/JAX and CUDA are optional acceleration paths and are not required for these APIs; do not claim parity or import them as a fallback. The bundled smoke is non-rendering and uses a generated temporary model. Viewer/Mink workflows remain optional and are not needed to validate the solver contract.

Before handoff, verify:

• imports and internal links resolve without checkout-specific paths;
• edit functions compile a model and preserve intended names/properties;
• every created artifact is removed on success and on forced failure;
• valid and invalid IK targets exercise both return and validation paths; and
• the smoke reports success, residual, and iteration count rather than only printing a final configuration.