Metadata-Version: 2.4
Name: mujoco-mojo
Version: 1.6.0
Summary: A complete MJCF lifecycle and trial orchestration suite for MuJoCo, powered by Pydantic v2.
Author-email: David Gable <dave.a.gable@gmail.com>
Maintainer-email: David Gable <dave.a.gable@gmail.com>
License: Apache-2.0
Project-URL: Documentation, https://hydrowelder.github.io/mujoco-mojo/
Project-URL: Repository, https://github.com/Hydrowelder/mujoco-mojo
Project-URL: Issues, https://github.com/Hydrowelder/mujoco-mojo/issues
Keywords: mujoco,robotics,simulation,monte-carlo,physics,pydantic,orchestration,mjcf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: coacd>=1.0.7
Requires-Dist: duckdb>=1.5.0
Requires-Dist: fastapi>=0.134.0
Requires-Dist: fastparquet>=2025.12.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mediapy>=1.2.6
Requires-Dist: mujoco>=3.4.0
Requires-Dist: numpy>=2.4.1
Requires-Dist: numpydantic>=1.7.0
Requires-Dist: pandas>=3.0.0
Requires-Dist: pillow>=12.1.1
Requires-Dist: polars>=1.39.0
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: pybind11-stubgen>=2.5.5
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.3.3
Requires-Dist: scipy>=1.17.0
Requires-Dist: scipy-stubs[scipy]>=1.17.0.2
Requires-Dist: stochas>=1.0.0
Requires-Dist: sse-starlette>=3.3.4
Requires-Dist: tabulate>=0.9.0
Requires-Dist: trimesh>=4.11.2
Requires-Dist: typer>=0.24.1
Requires-Dist: uvicorn>=0.41.0
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dark-hero-logo.svg">
    <img alt="MuJoCo Mojo" src="docs/assets/light-hero-logo.svg" style="height: 10.0em">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/mujoco-mojo/">
    <img src="https://img.shields.io/pypi/v/mujoco-mojo.svg" alt="PyPI version">
  </a>
  <a href="https://pypi.org/project/mujoco-mojo/">
    <img src="https://img.shields.io/pypi/pyversions/mujoco-mojo.svg" alt="Python versions">
  </a>
  <a href="https://github.com/Hydrowelder/mujoco-mojo/actions/workflows/release.yml">
    <img src="https://github.com/Hydrowelder/mujoco-mojo/actions/workflows/release.yml/badge.svg" alt="Tests & Release Status">
  </a>
  <a href="https://docs.pydantic.dev/latest/">
    <img src="https://img.shields.io/badge/Pydantic-v2-FF43A1?logo=pydantic&logoColor=white" alt="Pydantic v2">
  </a>
  <a href="https://opensource.org/licenses/Apache-2.0">
    <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License">
  </a>
  <a href="https://hydrowelder.github.io/mujoco-mojo/">
    <img src="https://img.shields.io/badge/docs-GitHub_Pages-blue.svg" alt="Documentation">
  </a>
  <a href="https://pypistats.org/packages/mujoco-mojo">
    <img src="https://img.shields.io/pypi/dm/mujoco-mojo.svg" alt="Downloads">
  </a>
</p>

---

A **complete MJCF lifecycle and trial orchestration suite** for MuJoCo, powered by **Pydantic v2**.

**MuJoCo Mojo** bridges the gap between static XML modeling and large-scale simulation research. It provides a strongly-typed bridge for building models and a robust execution engine for running them at scale.

* **Model:** Build MJCFs via **validated Python objects** allowing for programatic generation.
* **Scale:** Execute **multi-threaded Monte Carlo trials** with built-in resume logic.
* **Monitor:** Track progress via a **zero-dependency web dashboard** and persistent logs.
* **Assess:** Quickly view **interactive results** of a trial in context of others.
* **Reproduce:** Automatic **environment snapshotting** (`requirements.txt`) for every job.

## Installation
Install using `uv` (recommended):

```bash
uv add mujoco-mojo
```

or with `pip`:

```bash
pip install mujoco-mojo
```

> [!WARNING]
> At the time of writing, MuJoCo supports up to Python 3.13

## Features

### MJCF Tools

* Strongly-typed MJCF elements backed by Pydantic v2
* Early validation of MJCF structure and attribute semantics
* Pythonic composition of assets, bodies, sensors, and plugins
* Designed to mirror MuJoCo’s XML schema closely (no magic abstractions)
* Suitable for code generation, tooling, and large model pipelines
* Embedded MuJoCo object enumerations to make getting `mjOBJ` IDs simple
* Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models

### Job Utilities

* Single or multi-threaded trial execution
* Random draw tools for Monte Carlo or rerun with global variable override
* Detailed status files for insight on trial progress
* Resume a previously started job without rerunning previous cases
* Automatically record installed Python packages to `requirements.txt` for job recreation (works with `uv` or `pip`)
* End of run summary with metric to help perform a state of health check
* Flexible command line utilities to run jobs

> [!TIP]
> ```bash
> mujoco-mojo run monte-carlo \
>     --generator monte_carlo_test.Experiment.generate \
>     --runtime monte_carlo_test.runtime \
>     --workdir ./mc_test/ \
>     --no-resume \
>     --gen-arg 123 \
>     --gen-kwarg 'test=1234' \
>     --n-trial 10 \
>     --n-proc 1
> ```

* Support for running jobs with SLURM for distributed compute
* Built in Rich logging for terminal and a rotating file handler for persistent logs

### Dojo Dashboard

A zero-dependency, offline-first web suite for monitoring and analyzing your simulation jobs in real-time.

#### Monitor: Real-Time Oversight

* Live Progress Tracking: Dynamic progress bars and color-coded status cards provide a high-level view of your Monte Carlo runs.
* Success/Failure Analytics: Automatic categorization of trials with built-in data integrity checks to identify "empty" vs. "failed" runs.
* Sensory Feedback: Optional audio cues and visual celebrations let you know exactly when a multi-hour job hits 100%.
* Deep-Linked Navigation: Jump straight from the monitor to any individual trial in the viewer with one click.

#### Mosaic: Advanced Telemetry Analysis

* High-Fidelity Plotting: Hardware-accelerated visualization using Plotly.js for seamless zooming and panning through millions of data points.
* Dynamic Versus Mode: Overlay current telemetry against previous trials using an intuitive range-selection slider for instant regression testing.
* Regex-Powered Filtering: Navigate high-dimensional datasets using a "folder-style" signal selector with suffix and regex support.
* State Persistence & Sharing: Every view is captured in a shareable, compressed URL by pasting a link to share your exact configuration.
* Pro-Grade Tooling: Built-in JSON configuration editor, drag-and-drop config restoration, and multi-format exports (SVG, PNG, CSV).
* Keyboard-First Design: Full hotkey support for warping between trials and managing views without leaving the home row.

---

> [!NOTE]
> **MuJoCo Mojo** is an independently developed open-source toolbox. It is **not** affiliated with, sponsored by, or endorsed by **Google DeepMind** or the official **MuJoCo** development team.
> MuJoCo® is a registered trademark of Google LLC. All MJCF schemas and MuJoCo-related terminology used within this project are for compatibility and documentation purposes only.
