mujoco-truss-gen

mujoco-truss-gen is a Python package for generating MuJoCo models and Gymnasium-style environments for triangle-based isoperimetric truss robots.

Browse the rendered preset catalog, ranked by initial worst-case rigidity index.

The package is intended for members of the isoperimetric robot research workflow who need a shared, installable source of MuJoCo robot models instead of copying model-generation code between reinforcement learning, planning, simulation, and optimization projects.

Status

This repository is an internal lab prototype. It has a working installable package, built-in structure presets, a small public API, and tests that verify basic model generation and environment stepping. The API may still change before the package is treated as stable research infrastructure.

Supported workflows include:

• Generate MuJoCo MjSpec models for triangle-based truss structures.
• Use built-in "octahedron", "icosahedron", "solar_array", "tetrahedron", Usevitch et al. triangle-decomposable graph presets, and Henneberg routed continuous-tendon graph presets.
• Build abstract slide-joint models or realistic triangle-body models.
• Save generated MuJoCo XML.
• Wrap generated models in Gymnasium-compatible environments.
• Generate configurable flat, sloped, stair, wave, and rough height-field terrain.
• Convert STL meshes into experimental routed-tube shape dictionaries.

Installation

After a release has been published to PyPI:

python -m pip install mujoco-truss-gen

The optional MJX-Warp backend requires an NVIDIA CUDA GPU and is installed separately so ordinary MuJoCo/MJX-JAX users do not pull in Warp:

python -m pip install "mujoco-truss-gen[warp]"

For local development from a clone:

git clone https://github.com/isaa-sudweeks/mujoco-truss-gen.git
cd mujoco-truss-gen
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

The package requires Python 3.10 or newer and installs these runtime dependencies:

• gymnasium
• mujoco
• networkx
• numpy
• scipy

Install the optional interactive terrain figures with:

python -m pip install "mujoco-truss-gen[terrain]"

Quick Start

Generate the built-in octahedron model:

from mujoco_truss_gen import get_mujoco_spec

spec = get_mujoco_spec("octahedron", realistic=False)
model = spec.compile()

Generate the same robot on deterministic rough terrain:

from mujoco_truss_gen import TerrainConfig, get_mujoco_spec

spec = get_mujoco_spec(
    "octahedron",
    realistic=False,
    terrain=TerrainConfig(
        kind="rough",
        amplitude=0.15,
        feature_size=0.8,
        seed=7,
    ),
)

Save generated XML:

from mujoco_truss_gen import get_mujoco_spec, save_xml

spec = get_mujoco_spec("octahedron", realistic=False)
xml_path = save_xml(spec, "octahedron.xml")

Run one Gymnasium step:

import numpy as np

from mujoco_truss_gen import MujocoRelativeObsEnv, TrussEnvConfig, get_mujoco_spec

spec = get_mujoco_spec("octahedron", realistic=False)
env = MujocoRelativeObsEnv(
    TrussEnvConfig(
        model_source=spec,
        max_steps=1_000,
        nsubsteps=4,
        speed=0.01,
    )
)

obs, info = env.reset(seed=0)
action = np.zeros(env.action_space.shape, dtype=np.float32)
obs, reward, terminated, truncated, info = env.step(action)
env.close()

Open the built-in octahedron model from the command line:

python -m mujoco_truss_gen.generate_mujoco_model

On macOS, MuJoCo's passive viewer may require running viewer scripts with mjpython instead of the standard python executable.

Render a searchable catalog of every distinct registered preset, ranked by its initial worst-case rigidity index:

.venv/bin/mjpython tools/render_preset_catalog.py

The command writes the files deployed to the public preset catalog: preset_catalog/index.html, full-resolution PNGs, and a JSON manifest. It checkpoints after every preset, so rerunning the command resumes an interrupted first-time build. Use --realistic for realistic connector geometry, --overwrite to rebuild existing entries, or --include-aliases to include the unsuffixed Henneberg names that alias variant _1.

The same site includes an interactive terrain explorer that previews every height-field family and produces a copyable TerrainConfig.

Routed continuous-tube presets such as tetrahedron are all-edge-actuated models whose route tendons softly constrain each tube to its initial total length. They also support realistic=True, which clones shared routed node occurrences and connects them through in-plane bisector rods. Use MujocoNodeVelocityCommandEnv for node-level scalar velocity commands that are mapped through the route incidence matrix to edge actuator commands. For manual testing, view_node_velocity_terminal(spec) opens the MuJoCo viewer and accepts terminal commands such as set node_2 0.01, show, zero, and quit. Henneberg routed graph presets such as henneberg_n8_2tube_1 are generated from H1/H2 minimally rigid graph candidates, decomposed into continuous routed tendons, and accepted only after a deterministic 3D embedding passes an infinitesimal-rigidity check. The unsuffixed names, such as henneberg_n8_2tube, are aliases for variant _1.

Documentation

• Model generation: custom trusses, routed shape dictionaries, model modes, and generation helper contracts.
• Environments: environment constructors, actions, observations, rewards, rendering, and TrussEnvConfig.
• STL import: optional STL-to-routed-tube conversion and preview behavior.
• GNN utilities: extracting graph features and edge indices for PyTorch Geometric workflows.
• Height-field terrain: terrain families, physical parameters, safe spawning, native/MJX behavior, and interactive figures.
• Development: local setup, tests, linting, formatting, and package builds.
• MJX-Warp benchmark: compatibility gates, reproducible ORC benchmark commands, and the pending adoption decision.
• Releasing: automated and manual PyPI release steps.
• Roadmap: known limitations and planned work.

Example

Start from the included custom-truss example:

python examples/custom_truss.py

Citation

There is no formal citation for this package yet.

The Usevitch graph presets are based on:

Nathan Usevitch, Isaac Weaver, and James Usevitch. "Triangle-Decomposable Graphs for Isoperimetric Robots." arXiv:2505.01624, 2025. https://arxiv.org/abs/2505.01624

License

This project is distributed under the BSD-3-Clause license. See LICENSE for the full license text.