Add MuJoCo model authoring helpers

Expose typed builder-first helpers for MuJoCo-specific entities.

Remap heterogeneous actuator targets during builder composition.

Author: eric-heiden

changelog/+mujoco-authoring-helpers-a4c7e2d9.added.md

@@ -0,0 +1 @@
+Add `newton.solvers.mujoco` helpers for programmatically authoring MuJoCo actuators, contact pairs, tendons, and equality constraints.

docs/api/newton_solvers.rst

@@ -21,11 +21,13 @@ https://newton-physics.github.io/newton/stable/solvers/index.html.
    :hidden:
 
    newton_solvers_experimental
+   newton_solvers_mujoco
    newton_solvers_style3d
 
 .. rubric:: Submodules
 
 - :doc:`newton.solvers.experimental <newton_solvers_experimental>`
+- :doc:`newton.solvers.mujoco <newton_solvers_mujoco>`
 - :doc:`newton.solvers.style3d <newton_solvers_style3d>`
 
 .. rubric:: Classes

docs/api/newton_solvers_mujoco.rst

@@ -0,0 +1,66 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+.. SPDX-License-Identifier: CC-BY-4.0
+
+newton.solvers.mujoco
+=====================
+
+MuJoCo solver and programmatic model-authoring helpers.
+
+Use :class:`~newton.solvers.SolverMuJoCo` as the solver class. The module-level
+helpers create MuJoCo-specific actuators, tendons, contact pairs, and equality
+constraints on a :class:`~newton.ModelBuilder` without exposing custom-frequency
+storage details.
+
+Example::
+
+    from newton.solvers import mujoco
+
+    actuator = mujoco.add_actuator_dcmotor(
+        builder,
+        target=mujoco.ActuatorTarget.joint(joint),
+        motorconst=(0.05, 0.05),
+        resistance=2.0,
+    )
+
+.. note::
+
+   This page documents helper functions exposed through the ``newton.solvers.mujoco`` attribute.
+   Because ``newton.solvers`` is a module rather than a package, use
+   ``from newton.solvers import mujoco`` instead of ``import newton.solvers.mujoco``.
+
+.. currentmodule:: newton._src.solvers.mujoco
+
+.. rubric:: Classes
+
+.. autoclass:: ActuatorTarget
+
+.. autoclass:: TendonWrapGeom
+
+.. autoclass:: TendonWrapPulley
+
+.. autoclass:: TendonWrapSite
+
+
+.. rubric:: Functions
+
+.. autofunction:: add_actuator_dcmotor
+
+.. autofunction:: add_actuator_general
+
+.. autofunction:: add_actuator_motor
+
+.. autofunction:: add_actuator_position
+
+.. autofunction:: add_actuator_velocity
+
+.. autofunction:: add_contact_pair
+
+.. autofunction:: add_equality_connect
+
+.. autofunction:: add_equality_joint
+
+.. autofunction:: add_equality_weld
+
+.. autofunction:: add_tendon_fixed
+
+.. autofunction:: add_tendon_spatial

newton/_src/sim/builder.py

@@ -896,6 +896,15 @@ class CustomAttribute:
         urdf_value_transformer: Callable[[str, dict[str, Any] | None], Any] | None = None
         """Transformer function that converts a URDF attribute value string to a valid Warp dtype. If undefined, the generic converter from :func:`newton.utils.parse_warp_value_from_string` is used. Receives an optional context dict with parsing-time information."""
 
+        reference_value_transformer: Callable[[Any, dict[str, Any]], Any] | None = None
+        """Transformer for entity references copied by :meth:`ModelBuilder.add_builder`.
+
+        Use this instead of :attr:`references` when the referenced entity type depends on
+        other values in the same row. The callback receives the value and a context with
+        ``builder`` (the source builder), ``destination_builder``, ``entity_offsets``,
+        ``custom_frequency_offsets``, ``row_index``, ``world``, and ``label_prefix``.
+        """
+
         def __post_init__(self):
             """Initialize default values and validate dtype compatibility."""
             # Allow str dtype for string attributes (stored as Python lists, not warp arrays)
@@ -1707,6 +1716,7 @@ def _custom_attribute_specs_match(existing: CustomAttribute, incoming: CustomAtt
             and existing.assignment == incoming.assignment
             and existing.namespace == incoming.namespace
             and existing.references == incoming.references
+            and existing.reference_value_transformer is incoming.reference_value_transformer
         )
 
     @staticmethod
@@ -4033,8 +4043,13 @@ def get_offset(entity_or_key: str | None) -> int:
             value_offset = 0 if use_current_world else get_offset(attr.references)
             is_equality_target_attr = full_key == "mujoco:equality_constraint_target"
             is_collision_mask_domain_attr = full_key == collision_mask_domain_key and bool(collision_mask_domain_remap)
+            has_reference_value_transformer = attr.reference_value_transformer is not None
             needs_remap = (
-                value_offset != 0 or use_current_world or is_equality_target_attr or is_collision_mask_domain_attr
+                value_offset != 0
+                or use_current_world
+                or is_equality_target_attr
+                or is_collision_mask_domain_attr
+                or has_reference_value_transformer
             )
 
             if needs_remap:
@@ -4092,7 +4107,22 @@ def transform_enum_value(
                     value: Any,
                     is_equality_target: bool = is_equality_target_attr,
                     is_collision_mask_domain: bool = is_collision_mask_domain_attr,
+                    reference_value_transformer: Callable[[Any, dict[str, Any]], Any]
+                    | None = attr.reference_value_transformer,
                 ) -> Any:
+                    if reference_value_transformer is not None:
+                        return reference_value_transformer(
+                            value,
+                            {
+                                "builder": builder,
+                                "destination_builder": self,
+                                "entity_offsets": entity_offsets,
+                                "custom_frequency_offsets": custom_frequency_offsets,
+                                "row_index": entity_idx,
+                                "world": world,
+                                "label_prefix": label_prefix,
+                            },
+                        )
                     if is_equality_target:
                         return transform_equality_target_value(entity_idx, value)
                     if is_collision_mask_domain:

newton/_src/solvers/__init__.py

@@ -5,7 +5,7 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from . import style3d
+    from . import mujoco, style3d
     from .featherstone import SolverFeatherstone
     from .implicit_mpm import SolverImplicitMPM
     from .kamino import SolverKamino
@@ -26,6 +26,7 @@
     "SolverStyle3D",
     "SolverVBD",
     "SolverXPBD",
+    "mujoco",
     "style3d",
 ]
 
@@ -43,6 +44,7 @@
     "SolverStyle3D": (".style3d.solver_style3d", "SolverStyle3D"),
     "SolverVBD": (".vbd", "SolverVBD"),
     "SolverXPBD": (".xpbd", "SolverXPBD"),
+    "mujoco": (".mujoco", None),
     "style3d": (".style3d", None),
 }
 

newton/_src/solvers/mujoco/__init__.py

@@ -1,8 +1,59 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 The Newton Developers
 # SPDX-License-Identifier: Apache-2.0
 
+"""MuJoCo solver and programmatic model-authoring helpers.
+
+Use :class:`~newton.solvers.SolverMuJoCo` as the solver class. The module-level
+helpers create MuJoCo-specific actuators, tendons, contact pairs, and equality
+constraints on a :class:`~newton.ModelBuilder` without exposing custom-frequency
+storage details.
+
+Example::
+
+    from newton.solvers import mujoco
+
+    actuator = mujoco.add_actuator_dcmotor(
+        builder,
+        target=mujoco.ActuatorTarget.joint(joint),
+        motorconst=(0.05, 0.05),
+        resistance=2.0,
+    )
+"""
+
+from .actuators import (
+    ActuatorTarget,
+    add_actuator_dcmotor,
+    add_actuator_general,
+    add_actuator_motor,
+    add_actuator_position,
+    add_actuator_velocity,
+)
+from .contacts import add_contact_pair
+from .equality import add_equality_connect, add_equality_joint, add_equality_weld
 from .solver_mujoco import SolverMuJoCo
+from .tendons import (
+    TendonWrapGeom,
+    TendonWrapPulley,
+    TendonWrapSite,
+    add_tendon_fixed,
+    add_tendon_spatial,
+)
 
 __all__ = [
+    "ActuatorTarget",
     "SolverMuJoCo",
+    "TendonWrapGeom",
+    "TendonWrapPulley",
+    "TendonWrapSite",
+    "add_actuator_dcmotor",
+    "add_actuator_general",
+    "add_actuator_motor",
+    "add_actuator_position",
+    "add_actuator_velocity",
+    "add_contact_pair",
+    "add_equality_connect",
+    "add_equality_joint",
+    "add_equality_weld",
+    "add_tendon_fixed",
+    "add_tendon_spatial",
 ]

newton/_src/solvers/mujoco/_authoring.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared implementation helpers for MuJoCo model authoring."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...sim import ModelBuilder
+
+
+def _ensure_mujoco_attributes(builder: ModelBuilder, sentinel: str) -> None:
+    """Register the MuJoCo schema when the requested domain is unavailable."""
+    if builder.has_custom_attribute(sentinel):
+        return
+
+    from .solver_mujoco import SolverMuJoCo  # noqa: PLC0415
+
+    SolverMuJoCo.register_custom_attributes(builder)
+
+
+def _prepare_custom_frequency_row(
+    builder: ModelBuilder,
+    frequency: str,
+    values: dict[str, Any],
+    custom_attributes: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Validate and combine one solver-owned custom-frequency row."""
+    extras = custom_attributes or {}
+    overlap = values.keys() & extras.keys()
+    if overlap:
+        names = ", ".join(sorted(overlap))
+        raise ValueError(f"custom_attributes cannot override MuJoCo-managed values: {names}")
+
+    row = {**values, **extras}
+    for key in row:
+        attribute = builder.custom_attributes.get(key)
+        if attribute is None:
+            raise AttributeError(
+                f"Custom attribute '{key}' is not registered. Register it before adding a {frequency} row."
+            )
+        if attribute.frequency != frequency:
+            raise ValueError(
+                f"Custom attribute '{key}' uses frequency {attribute.frequency!r}, expected {frequency!r}."
+            )
+    return row
+
+
+def _add_custom_frequency_row(
+    builder: ModelBuilder,
+    frequency: str,
+    values: dict[str, Any],
+    *,
+    index_key: str,
+    custom_attributes: dict[str, Any] | None = None,
+) -> int:
+    """Append one validated custom-frequency row and return its index."""
+    row = _prepare_custom_frequency_row(builder, frequency, values, custom_attributes)
+    return builder.add_custom_values(**row)[index_key]
+
+
+__all__ = []