feat: per-body compile-time BodyModel on SimModel

[wlgys8]

Summary

Implements #43: SimModel gains a per-body compile-time static model container, so manager-based terms stop re-deriving the same compile-time facts (default joint angles, actuator order checks, key-pose FK references).

Closes #43 (core + backend + contract part; humanoid walk manager migration follows separately).

Design decisions

Discussed at length in #43 and during implementation:

• bodies: Mapping[str, BodyModel] keyed by SceneObjsCfg field name — the key is a cfg-side fact, identical across backends for the same scene. Base-file-only content stays out (no cfg anchor).
• joint_names = the body's named joints in backend joint-DOF order (floating base excluded) — joint identity, not actuator order. Consumers resolve by name, never hard-coded index, since ordering is per-backend. All joint-aligned arrays (joint_pos_limits, init_joint_pos) follow this axis; FK arrays follow link_names.
• Init-only snapshot: the container carries exactly one baked snapshot — joint angles from the key pose designated by RobotCfg.init_key_pose (env-level choice via scene-composition override; asset default "default"), base placement split into init_base_position (3,) / init_base_quat (4,), and link poses from one FK evaluation at the default placement (world frame, (x, y, z, w) quaternions — cross-validated against engine rotation matrices). Non-init key poses stay in the cfg.
• Key poses must exactly cover the body's joints; permutation into body order and all validation (unknown joints, coverage, missing init pose) happen once at build time in core.
• actuators on BodyModel is the body-scoped view of SimModel.actuators (specs targeting the body's joints, scene-wide order) — derived by core, backends never filter.
• SimModelQueryCompiler → SimModelCompiler.compile(scene, queries): both inputs that meet in SimModel are now contract-level, making bodies an abstract obligation instead of a convention. SimBackend.compile_model(queries) keeps its env-facing signature by retaining the scene; backends must call super().__init__().
• Core owns semantics, backends supply facts: assemble_body_model / resolved_key_pose own permutation/validation/derivation; a plugin implements a SceneCompiler, a SimModelCompiler subclass, and the existing abstract members — nothing else.
• Model-surface types (ActuatorSpec, GeomSpec, BodyModel, SimModel) moved to sim/model.py next to the queries, removing the TYPE_CHECKING cycles in both directions.

Implementation notes

• MotrixSim adapter evaluates one batch-1 FK for all bodies at once (each body's key-pose overrides touch disjoint joints, so they compose into a single init configuration) and uses the engine Body object APIs (get_dof_pos_indices, link.index, get_pose) instead of manual lookups.
• Zero-joint bodies verified end-to-end (free-floating ball: joint_pos_limits=None, empty actuators, (0,) init joints).
• Two-robot scene verified: shared FK composes without cross-body interference; body-scoped actuator views are disjoint.

Test plan

• Core contract tests: permutation, designated init pose, prefix resolution, coverage/unknown-joint rejection, shape alignment, actuator subset derivation (11 tests)
• MotrixSim integration: init snapshot contents, engine-order alignment, unit quaternions, empty-bodies scene
• Humanoid walk incomplete-preset test now expects the build-time error
• Full suite: 492 passed, ruff clean

Follow-ups (not in this PR)

• Humanoid walk manager migration to model.bodies (issue acceptance item)
• Design write-up back to feat: SimModel 按 BodyCfg 构建编译期 BodyModel（body 级静态模型数据容器） #43
• Separate issue: numba generated-kernel cache fallback hardening (retry with cache=False)

[Copilot]

🟡 Changes recommended

A test backend still implements the old compiler compile(queries) signature, which will raise a TypeError if compile_model() is invoked under the new compile(scene, queries) contract.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR implements per-body compile-time BodyModel data on SimModel, shifting repeated “compile-time facts” (init key pose joint angles, per-body actuator views, and init FK snapshots) into a backend-neutral model surface assembled once during model compilation.

Changes:

• Introduces BodyModel and adds SimModel.bodies to hold per-body static model data baked at compile time.
• Replaces SimModelQueryCompiler with SimModelCompiler.compile(scene, queries) and updates backends/callers to use SimBackend.compile_model(...).
• Adds/updates tests to cover BodyModel assembly, init snapshot baking, and the updated compile API.

File summaries

File	Description
wiki/design/manager/sim-backend.md	Updates design doc to reflect model_compiler and the new compile contract.
motrix_envs/tests/test_scene_cfg.py	Migrates test env setup to sim.compile_model(...).
motrix_envs/tests/test_quadruped_walk.py	Updates ActuatorType import to sim.model.
motrix_envs/tests/test_humanoid_walk.py	Updates expected exception semantics for compile-time key-pose validation.
motrix_envs/tests/test_action_space.py	Updates ActuatorType import to sim.model.
motrix_envs/src/motrix_envs/locomotion/wbt/mdp/action.py	Updates actuator model-surface imports to sim.model.
motrix_envs/src/motrix_envs/locomotion/quadruped/walk_np.py	Updates ActuatorType import to sim.model.
motrix_envs/src/motrix_envs/locomotion/humanoid/walk_np.py	Updates ActuatorType import to sim.model.
motrix_envs/src/motrix_envs/locomotion/action_space.py	Updates ActuatorType import to sim.model.
motrix_env_mujoco/src/motrix_env_mujoco/backend.py	Updates backend API to call SimBackend base init and expose model_compiler.
motrix_env_motrixsim/tests/test_sim_data_provider.py	Renames model_query_compiler → model_compiler in test backend scaffold.
motrix_env_motrixsim/tests/test_motrixsim_backend.py	Updates tests to use model_compiler.compile(scene, queries) and adds init snapshot coverage.
motrix_env_motrixsim/src/motrix_env_motrixsim/runtime.py	Implements MotrixSimModelCompiler and assembles SimModel.bodies via one FK pass.
motrix_env_core/tests/test_registry.py	Updates registry test backend to new model_compiler/compile signature.
motrix_env_core/tests/test_model_query_dispatch.py	Updates dispatch test to new compiler name/signature and SimModel import location.
motrix_env_core/tests/test_manager_sim_backend.py	Updates fake backend compile signature and model imports.
motrix_env_core/tests/test_direct_env_sim_backend.py	Updates fake backend compile signature and model imports.
motrix_env_core/tests/test_body_model.py	Adds contract tests for assemble_body_model (permutation, validation, init snapshot).
motrix_env_core/src/motrix_env_core/sim/model.py	Defines BodyModel/SimModel surface and replaces query compiler with SimModelCompiler.
motrix_env_core/src/motrix_env_core/sim/body.py	Adds core-owned BodyModel assembly logic (validation, permutation, actuator view derivation).
motrix_env_core/src/motrix_env_core/sim/backend.py	Moves model-surface types out; adds model_compiler + compile_model() with stored scene.
motrix_env_core/src/motrix_env_core/sim/init.py	Re-exports model-surface types/compiler from sim.model and adds body assembly export.
motrix_env_core/src/motrix_env_core/numba/manager/env.py	Updates ActuatorSpec import location.
motrix_env_core/src/motrix_env_core/numba/manager/actions.py	Updates ActuatorSpec type-checking import location.
motrix_env_core/src/motrix_env_core/config/scene/base.py	Adds RobotCfg.init_key_pose and validates it against declared key poses.

Review details

Suppressed comments (2)

motrix_env_motrixsim/tests/test_sim_data_provider.py:363

• _FrameworkTestBackend.model_compiler returns self, but the compiler interface now expects compile(scene, queries). With the current compile(self, queries) signature, calling SimBackend.compile_model will raise a TypeError (extra positional arg), even before the "not exercised" assertion.

    def model_compiler(self):
        return self

    def compile(self, queries: Mapping[str, ModelQuery]) -> object:
        raise AssertionError("not exercised")

motrix_env_core/src/motrix_env_core/sim/body.py:99

• Spelling/grammar: “Permutates” should be “Permutes” in the assemble_body_model docstring.

    """Assemble a :class:`BodyModel` from backend-extracted engine facts.

    Permutates each declared key pose from ``KeyPoseCfg.joint_names`` order
    into the body joint order — every declared joint must exist on the body
    and every body joint must be covered — and bakes the init snapshot from
    the configured ``init_key_pose``. The body-scoped actuator view is

• Files reviewed: 25/25 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.