mujoco-mojo 2.3.7__tar.gz → 2.3.9__tar.gz

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mujoco-mojo
-Version: 2.3.7
+Version: 2.3.9
 Summary: A complete MJCF lifecycle and trial orchestration suite for MuJoCo, powered by Pydantic v2.
 Project-URL: Homepage, https://github.com/Hydrowelder/mujoco-mojo
 Project-URL: Documentation, https://hydrowelder.github.io/mujoco-mojo/
@@ -103,13 +103,14 @@ A **complete MJCF lifecycle and trial orchestration suite** for MuJoCo, powered
 
 **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.
+- **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
@@ -124,34 +125,41 @@ pip install mujoco-mojo
 
 ---
 
-
 ## Features
 
 ### MJCF Tools
 
-* **Strongly-Typed Elements:** MJCF components backed by Pydantic v2 for immediate validation.
-* **Semantic Validation:** Early detection of structural errors and attribute mismatches before the engine starts.
-* **MuJoCo Alignment:** Designed to mirror MuJoCo’s XML schema closely (no magic abstractions)
-* **Object Enumerations:** Embedded MuJoCo object mappings to simplify retrieving `mjOBJ` IDs.
-* **Asset Sharing:** Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models
+- **Strongly-Typed Elements:** MJCF components backed by Pydantic v2 for immediate validation.
+- **Semantic Validation:** Early detection of structural errors and attribute mismatches before the engine starts.
+- **MuJoCo Alignment:** Designed to mirror MuJoCo’s XML schema closely (no magic abstractions)
+- **Object Enumerations:** Embedded MuJoCo object mappings to simplify retrieving `mjOBJ` IDs.
+- **Asset Sharing:** Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models
+
+### Runtime Toolkit
+
+- **Forcing Functions:** A library of typed `Load` definitions (spring-dampers, point-to-point forces, friction, and more) that apply themselves including reaction forces.
+- **Proximity Sensing:** Built-in distance and closest-point tracking between sites and bodies, exposed as both telemetry signals and live overlays with no extra instrumentation. Works on concave geometry meshes.
+- **Structured Telemetry:** A single `post`/`track` call records any value into a hierarchical namespace during simulations. This include prebuilt `request` calls for commonly desired values.
+- **Video Recording:** Multi-camera MP4/WebM/GIF capture synced to simulation time, with playback-speed control, force/proximity overlays, on-frame labels, and single-frame snapshots.
 
 ### Job Utilities
 
 #### Campaign Orchestration
 
-* **Multi-Threaded Execution:** Single or multi-threaded trial execution
-* **Environment Snapshotting:** Automatically record installed Python packages to `requirements.txt` for job recreation (works with `uv` or `pip`)
-* **Resume Logic:** Resume a previously started job without rerunning previous cases
-* **Robust Logging:** Built in Rich logging for terminal and a rotating file handler for persistent logs and status files for insight on trial progress
-* **Global Overrides:** Force specific values onto distributions via CLI or JSON overrides to test "golden" cases.
+- **Multi-Threaded Execution:** Single or multi-threaded trial execution
+- **Environment Snapshotting:** Automatically record installed Python packages to `requirements.txt` for job recreation (works with `uv` or `pip`)
+- **Resume Logic:** Resume a previously started job without rerunning previous cases
+- **Robust Logging:** Built in Rich logging for terminal and a rotating file handler for persistent logs and status files for insight on trial progress
+- **Global Overrides:** Force specific values onto distributions via CLI or JSON overrides to test "golden" cases.
 
 #### Monte Carlo
 
-* **Reproducible Sampling:** Random draw tools for Monte Carlo or rerun with global variable override
-* End of run summary with metric to help perform a state of health check
-* Support for running jobs with SLURM for distributed compute
+- **Reproducible Sampling:** Random draw tools for Monte Carlo or rerun with global variable override
+- End of run summary with metric to help perform a state of health check
+- Support for running jobs with SLURM for distributed compute
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo run monte-carlo \
 >     --generator monte_carlo_test.Experiment.generate \
@@ -166,12 +174,13 @@ pip install mujoco-mojo
 
 #### Optimization
 
-* **Bayesian Search:** Intelligent design space navigation powered by Optuna integration.
-* **Design Variables:** Continuous (`DesignFloat`) and discrete (`DesignCategorical`) parameters evolved by the solver.
-* **Adaptive Refinement:** "Zoom" into promising neighborhoods by aggressively shrinking search bounds on resume.
-* **Stochastic Robustness:** Multi-evaluation trials that average scores over different seeds to filter out noisy physics outliers.
+- **Bayesian Search:** Intelligent design space navigation powered by Optuna integration.
+- **Design Variables:** Continuous (`DesignFloat`) and discrete (`DesignCategorical`) parameters evolved by the solver.
+- **Adaptive Refinement:** "Zoom" into promising neighborhoods by aggressively shrinking search bounds on resume.
+- **Stochastic Robustness:** Multi-evaluation trials that average scores over different seeds to filter out noisy physics outliers.
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo run optimiztion \
 >     -g sim.generate \
@@ -190,30 +199,33 @@ A zero-dependency, offline-first web suite for monitoring and analyzing your sim
 
 #### 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.
+- **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.
+- **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.
 
 ### Reloaded
 
 A rapid prototyping loop that allows you to modify physics logic and model architecture on the fly without ever closing the visualizer.
 
-* **Module Hot-Reloading:** Recursively reloads local Python modules and MJCF logic, allowing code changes to propagate instantly to the active simulation.
-* **Unified Visualizer Bridge:** Synchronized visualization of custom force and torque vectors across native OpenGL, Viser web interfaces, and video recordings.
-* **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, or trigger "generation-only" mode for rapid MJCF debugging.
-* **Asset Persistence:** Automatically dumps current MJCF snapshots and model configurations to a workspace directory for post-hoc analysis or version tracking.
+- **Module Hot-Reloading:** Recursively reloads local Python modules and MJCF logic, allowing code changes to propagate instantly to the active simulation.
+- **Unified Visualizer Bridge:** Synchronized visualization of custom force and torque vectors across native OpenGL, Viser web interfaces, and video recordings.
+- **Multiple Viewer Backends:** Drive the same reload/sync pipeline through either the native MuJoCo OpenGL viewer or a Viser web viewer.
+- **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, watch for file changes and auto-reload, switch telemetry recording on or off mid-session, or trigger "generation-only" mode for rapid MJCF debugging.
+- **Live Session Controls:** Adjust the seed and trial number on the fly with `seed <N>` and `trial <N>`, without restarting the loop.
+- **Asset Persistence:** Automatically dumps current MJCF snapshots and model configurations to a workspace directory for post-hoc analysis or version tracking.
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo reloaded \
 >     --generator monte_carlo_test.Experiment.generate \

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/README.md

@@ -38,13 +38,14 @@ A **complete MJCF lifecycle and trial orchestration suite** for MuJoCo, powered
 
 **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.
+- **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
@@ -59,34 +60,41 @@ pip install mujoco-mojo
 
 ---
 
-
 ## Features
 
 ### MJCF Tools
 
-* **Strongly-Typed Elements:** MJCF components backed by Pydantic v2 for immediate validation.
-* **Semantic Validation:** Early detection of structural errors and attribute mismatches before the engine starts.
-* **MuJoCo Alignment:** Designed to mirror MuJoCo’s XML schema closely (no magic abstractions)
-* **Object Enumerations:** Embedded MuJoCo object mappings to simplify retrieving `mjOBJ` IDs.
-* **Asset Sharing:** Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models
+- **Strongly-Typed Elements:** MJCF components backed by Pydantic v2 for immediate validation.
+- **Semantic Validation:** Early detection of structural errors and attribute mismatches before the engine starts.
+- **MuJoCo Alignment:** Designed to mirror MuJoCo’s XML schema closely (no magic abstractions)
+- **Object Enumerations:** Embedded MuJoCo object mappings to simplify retrieving `mjOBJ` IDs.
+- **Asset Sharing:** Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models
+
+### Runtime Toolkit
+
+- **Forcing Functions:** A library of typed `Load` definitions (spring-dampers, point-to-point forces, friction, and more) that apply themselves including reaction forces.
+- **Proximity Sensing:** Built-in distance and closest-point tracking between sites and bodies, exposed as both telemetry signals and live overlays with no extra instrumentation. Works on concave geometry meshes.
+- **Structured Telemetry:** A single `post`/`track` call records any value into a hierarchical namespace during simulations. This include prebuilt `request` calls for commonly desired values.
+- **Video Recording:** Multi-camera MP4/WebM/GIF capture synced to simulation time, with playback-speed control, force/proximity overlays, on-frame labels, and single-frame snapshots.
 
 ### Job Utilities
 
 #### Campaign Orchestration
 
-* **Multi-Threaded Execution:** Single or multi-threaded trial execution
-* **Environment Snapshotting:** Automatically record installed Python packages to `requirements.txt` for job recreation (works with `uv` or `pip`)
-* **Resume Logic:** Resume a previously started job without rerunning previous cases
-* **Robust Logging:** Built in Rich logging for terminal and a rotating file handler for persistent logs and status files for insight on trial progress
-* **Global Overrides:** Force specific values onto distributions via CLI or JSON overrides to test "golden" cases.
+- **Multi-Threaded Execution:** Single or multi-threaded trial execution
+- **Environment Snapshotting:** Automatically record installed Python packages to `requirements.txt` for job recreation (works with `uv` or `pip`)
+- **Resume Logic:** Resume a previously started job without rerunning previous cases
+- **Robust Logging:** Built in Rich logging for terminal and a rotating file handler for persistent logs and status files for insight on trial progress
+- **Global Overrides:** Force specific values onto distributions via CLI or JSON overrides to test "golden" cases.
 
 #### Monte Carlo
 
-* **Reproducible Sampling:** Random draw tools for Monte Carlo or rerun with global variable override
-* End of run summary with metric to help perform a state of health check
-* Support for running jobs with SLURM for distributed compute
+- **Reproducible Sampling:** Random draw tools for Monte Carlo or rerun with global variable override
+- End of run summary with metric to help perform a state of health check
+- Support for running jobs with SLURM for distributed compute
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo run monte-carlo \
 >     --generator monte_carlo_test.Experiment.generate \
@@ -101,12 +109,13 @@ pip install mujoco-mojo
 
 #### Optimization
 
-* **Bayesian Search:** Intelligent design space navigation powered by Optuna integration.
-* **Design Variables:** Continuous (`DesignFloat`) and discrete (`DesignCategorical`) parameters evolved by the solver.
-* **Adaptive Refinement:** "Zoom" into promising neighborhoods by aggressively shrinking search bounds on resume.
-* **Stochastic Robustness:** Multi-evaluation trials that average scores over different seeds to filter out noisy physics outliers.
+- **Bayesian Search:** Intelligent design space navigation powered by Optuna integration.
+- **Design Variables:** Continuous (`DesignFloat`) and discrete (`DesignCategorical`) parameters evolved by the solver.
+- **Adaptive Refinement:** "Zoom" into promising neighborhoods by aggressively shrinking search bounds on resume.
+- **Stochastic Robustness:** Multi-evaluation trials that average scores over different seeds to filter out noisy physics outliers.
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo run optimiztion \
 >     -g sim.generate \
@@ -125,30 +134,33 @@ A zero-dependency, offline-first web suite for monitoring and analyzing your sim
 
 #### 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.
+- **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.
+- **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.
 
 ### Reloaded
 
 A rapid prototyping loop that allows you to modify physics logic and model architecture on the fly without ever closing the visualizer.
 
-* **Module Hot-Reloading:** Recursively reloads local Python modules and MJCF logic, allowing code changes to propagate instantly to the active simulation.
-* **Unified Visualizer Bridge:** Synchronized visualization of custom force and torque vectors across native OpenGL, Viser web interfaces, and video recordings.
-* **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, or trigger "generation-only" mode for rapid MJCF debugging.
-* **Asset Persistence:** Automatically dumps current MJCF snapshots and model configurations to a workspace directory for post-hoc analysis or version tracking.
+- **Module Hot-Reloading:** Recursively reloads local Python modules and MJCF logic, allowing code changes to propagate instantly to the active simulation.
+- **Unified Visualizer Bridge:** Synchronized visualization of custom force and torque vectors across native OpenGL, Viser web interfaces, and video recordings.
+- **Multiple Viewer Backends:** Drive the same reload/sync pipeline through either the native MuJoCo OpenGL viewer or a Viser web viewer.
+- **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, watch for file changes and auto-reload, switch telemetry recording on or off mid-session, or trigger "generation-only" mode for rapid MJCF debugging.
+- **Live Session Controls:** Adjust the seed and trial number on the fly with `seed <N>` and `trial <N>`, without restarting the loop.
+- **Asset Persistence:** Automatically dumps current MJCF snapshots and model configurations to a workspace directory for post-hoc analysis or version tracking.
 
 > [!TIP]
+>
 > ```bash
 > mujoco-mojo reloaded \
 >     --generator monte_carlo_test.Experiment.generate \

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/index.md

@@ -87,6 +87,13 @@ Install `mujoco-mojo` in your project using the following:
 - **Object Enumerations:** Embedded MuJoCo object mappings to simplify retrieving `mjOBJ` IDs.
 - **Asset Sharing:** Specialized handling of dependency by remapping assets to become shared allows for space efficient execution of complex models
 
+### Runtime Toolkit
+
+- **Forcing Functions:** A library of typed `Load` definitions (spring-dampers, point-to-point forces, friction, and more) that apply themselves including reaction forces.
+- **Proximity Sensing:** Built-in distance and closest-point tracking between sites and bodies, exposed as both telemetry signals and live overlays with no extra instrumentation. Works on concave geometry meshes.
+- **Structured Telemetry:** A single `post`/`track` call records any value into a hierarchical namespace during simulations. This include prebuilt `request` calls for commonly desired values.
+- **Video Recording:** Multi-camera MP4/WebM/GIF capture synced to simulation time, with playback-speed control, force/proximity overlays, on-frame labels, and single-frame snapshots.
+
 ### Job Utilities
 
 #### Campaign Orchestration
@@ -164,7 +171,9 @@ A rapid prototyping loop that allows you to modify physics logic and model archi
 
 - **Module Hot-Reloading:** Recursively reloads local Python modules and MJCF logic, allowing code changes to propagate instantly to the active simulation.
 - **Unified Visualizer Bridge:** Synchronized visualization of custom force and torque vectors across native OpenGL, Viser web interfaces, and video recordings.
-- **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, or trigger "generation-only" mode for rapid MJCF debugging.
+- **Multiple Viewer Backends:** Drive the same reload/sync pipeline through either the native MuJoCo OpenGL viewer or a Viser web viewer.
+- **Interactive Prototyping:** A developer-centric command loop to toggle playback speeds, repeat last commands, watch for file changes and auto-reload, switch telemetry recording on or off mid-session, or trigger "generation-only" mode for rapid MJCF debugging.
+- **Live Session Controls:** Adjust the seed and trial number on the fly with `seed <N>` and `trial <N>`, without restarting the loop.
 - **Asset Persistence:** Automatically dumps current MJCF snapshots and model configurations to a workspace directory for post-hoc analysis or version tracking.
 
 ??? example

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/stylesheets/extra.css

@@ -77,6 +77,19 @@ h1,
     text-transform: uppercase;
 }
 
+/* Figure captions are often wrapped in a glightbox <a> link and would otherwise
+   inherit the cyan link color and underline, which is hard to read at caption size.
+   text-decoration is drawn by the anchor itself, so it must be cleared there too. */
+.md-typeset figure > a {
+    text-decoration: none;
+}
+
+.md-typeset figure figcaption {
+    color: var(--md-default-fg-color);
+    font-style: normal;
+    text-decoration: none;
+}
+
 code,
 kbd,
 pre {

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/user-guides/generate-script.md

@@ -3,8 +3,8 @@
 !!! abstract
     The **Generate Script** is the heartbeat of your simulation pipeline. Its job is to programmatically assemble the MuJoCo MJCF model and perform all stochastic (random) draws. By the time this function returns, the simulation should be "frozen" in its initial state, ready for the physics engine to take over.
 
-    <figure align="center" class="fade-in">
-        <img src="../../assets/user-guides/generate-result.jpg" alt="Generate final result" style="width: 50%; height: auto;">
+    <figure markdown="span">
+        ![Mosaic dashboard view](../../assets/user-guides/generate-result.jpg){ width="50%" height="auto" }
         <figcaption>The visual result of the completed generator script: two translucent boxes with freejoints, spring attachment sites (red and blue spheres), and a central tracking site (fuchsia sphere), all set against a starry skybox.</figcaption>
     </figure>
 

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/user-guides/monitor.md

@@ -5,12 +5,13 @@
 
 ---
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-monitor-view.jpg#only-light" alt="Mosaic dashboard view" style="width: 85%; height: auto;">
-    <img src="../../assets/user-guides/dark-monitor-view.jpg#only-dark" alt="Mosaic dashboard view" style="width: 85%; height: auto;">
+<figure markdown="span">
+    ![Mosaic dashboard view](../../assets/user-guides/light-monitor-view.jpg#only-light){ width="85%" height="auto" }
+    ![Mosaic dashboard view](../../assets/user-guides/dark-monitor-view.jpg#only-dark){ width="85%" height="auto" }
     <figcaption>A preview of the <b>Monitor</b> page showing a completed progress bar, job statistics, and links to <b>Mosaic</b> to assess individual trials.</figcaption>
 </figure>
 
+
 ## Real-Time Oversight
 
 The Monitor acts as a nexus for overseeing your `mujoco-mojo run` jobs. It works by monitoring the trial status files in your workspace and reflecting the global state of the simulation.

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/user-guides/mosaic.md

@@ -5,9 +5,9 @@
 
 ---
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-mosaic-view.jpg#only-light" alt="Mosaic dashboard view" style="width: 85%; height: auto;">
-    <img src="../../assets/user-guides/dark-mosaic-view.jpg#only-dark" alt="Mosaic dashboard view" style="width: 85%; height: auto;">
+<figure markdown="span">
+    ![Mosaic dashboard view](../../assets/user-guides/light-mosaic-view.jpg#only-light){ width="85%" height="auto" }
+    ![Mosaic dashboard view](../../assets/user-guides/dark-mosaic-view.jpg#only-dark){ width="85%" height="auto" }
     <figcaption>A preview of the <b>Mosaic</b> page showing run results for <code>trial_00</code>. Annotations indicate key moments in the simulations. Two telemetry signals per trial are shown with 9 additional trials displayed for comparison.</figcaption>
 </figure>
 
@@ -30,9 +30,9 @@ Trial Navigation
 !!! tip "Pro Tip: Regex Filtering"
     The dropdowns aren't just lists; they are Regex-aware. You can use the segment buttons (like quat, ctrl, or sens) to quickly filter down hundreds of signals to just the ones you need.
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-selector-bar.jpg#only-light" alt="Selector" style="width: 85%; height: auto;">
-    <img src="../../assets/user-guides/dark-selector-bar.jpg#only-dark" alt="Selector bar" style="width: 85%; height: auto;">
+<figure markdown="span">
+    ![Selector bar](../../assets/user-guides/light-selector-bar.jpg#only-light){ width="85%" height="auto" }
+    ![Selector bar](../../assets/user-guides/dark-selector-bar.jpg#only-dark){ width="85%" height="auto" }
     <figcaption>The dropdown for <b>Y-Axes</b> is active with the Bodies and box1 quick filters active. Two telemetry signals are selected showing the rotational and total kinetic energy.</figcaption>
 </figure>
 
@@ -50,9 +50,9 @@ This button compacts your current plot view (trial, selected data, plot appearan
 
 Adjust the visual style. Switch between Lines, Markers, or both. Change interpolation (Spline vs. Linear) or toggle Logarithmic scales for high-dynamic-range data.
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-plot-editor.jpg#only-light" alt="Plot editor menu" style="width: 40%; height: auto;">
-    <img src="../../assets/user-guides/dark-plot-editor.jpg#only-dark" alt="Plot editor menu" style="width: 40%; height: auto;">
+<figure markdown="span">
+    ![Plot editor menu](../../assets/user-guides/light-plot-editor.jpg#only-light){ width="40%" height="auto" }
+    ![Plot editor menu](../../assets/user-guides/dark-plot-editor.jpg#only-dark){ width="40%" height="auto" }
     <figcaption>The menu for <b>plot editor</b> is active. It shows the many dropdown options available to configure the layout of the plot area as well as the interaction behavior when hover over data.</figcaption>
 </figure>
 
@@ -63,9 +63,9 @@ Adjust the visual style. Switch between Lines, Markers, or both. Change interpol
 ???+ tip "Tip: Clickable Buttons"
     You can click on a note in the editor to "focus" on the note!
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-notes-editor.jpg#only-light" alt="Notes editor menu" style="width: 60%; height: auto;">
-    <img src="../../assets/user-guides/dark-notes-editor.jpg#only-dark" alt="Notes editor menu" style="width: 60%; height: auto;">
+<figure markdown="span">
+    ![Notes editor menu](../../assets/user-guides/light-notes-editor.jpg#only-light){ width="60%" height="auto" }
+    ![Notes editor menu](../../assets/user-guides/dark-notes-editor.jpg#only-dark){ width="60%" height="auto" }
     <figcaption>The menu for <b>notes editor</b> is active and in editing mode. A note is being edited. The plot area shows the two notes shown in the menu.</figcaption>
 </figure>
 
@@ -79,9 +79,9 @@ Add various shapes to the plot. After selecting an option in the menu, your mous
 
 Each new shape is automatically assigned the next color in the preset palette so overlapping shapes remain visually distinct. The shape editor includes a full color picker (identical to the signal color picker) for precise color control.
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-shapes-editor.jpg#only-light" alt="Shapes editor menu" style="width: 60%; height: auto;">
-    <img src="../../assets/user-guides/dark-shapes-editor.jpg#only-dark" alt="Shapes editor menu" style="width: 60%; height: auto;">
+<figure markdown="span">
+    ![Shapes editor menu](../../assets/user-guides/light-shapes-editor.jpg#only-light){ width="60%" height="auto" }
+    ![Shapes editor menu](../../assets/user-guides/dark-shapes-editor.jpg#only-dark){ width="60%" height="auto" }
     <figcaption>The menu for <b>shapes editor</b> is active and in editing mode. A shape's label and color is being edited. The plot area shows a vertical (yellow) and horizontal (red) line and a rectangle (purple).</figcaption>
 </figure>
 
@@ -115,9 +115,9 @@ Dojo provides a few basic export options to capture an image of the plot or save
 - **Filtered CSV:** A CSV file containing the data currently being plotted can be downloaded for a look at the raw data.
 - **Config JSON:** The current page configuration can be downloaded as a JSON so it can be reloaded at a later time.
 
-<figure align="center">
-    <img src="../../assets/user-guides/light-export-options.jpg#only-light" alt="Export options menu" style="width: 60%; height: auto;">
-    <img src="../../assets/user-guides/dark-export-options.jpg#only-dark" alt="Export options menu" style="width: 60%; height: auto;">
+<figure markdown="span">
+    ![Export options menu](../../assets/user-guides/light-export-options.jpg#only-light){ width="60%" height="auto" }
+    ![Export options menu](../../assets/user-guides/dark-export-options.jpg#only-dark){ width="60%" height="auto" }
     <figcaption>The menu for <b>export options</b> is active. </figcaption>
 </figure>
 

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/user-guides/optimization.md

@@ -15,7 +15,7 @@ In a standard Monte Carlo script, you use `mojo_model.sample_dist()` to represen
 Mojo supports two primary types of design variables within your generate script:
 
 - `DesignFloat`: For continuous parameters like spring stiffness, mass, or damping ratios.
-- `DesignCategorical`: For discrete choices like material types (['steel', 'aluminum']) or solver methods.
+- `DesignCategorical`: For discrete choices like material types (`['steel', 'aluminum']`) or solver methods.
 
 ???+ example "Example: Defining Design Variables"
 

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/docs/user-guides/runtime-script.md

@@ -5,8 +5,8 @@
 
     The beauty of Mojo is that you don't need to manage the low-level MuJoCo physics state manually; the `RuntimeManager` handles the heavy lifting, ensuring your simulation is stable and your telemetry is perfectly synchronized.
 
-    <figure align="center" class="fade-in">
-        <img src="../../assets/user-guides/runtime-anim.gif" alt="Runtime final result" style="width: 50%; height: auto;">
+    <figure markdown="span">
+        ![Runtime final result](../../assets/user-guides/runtime-anim.gif){ width="50%" height="auto" }
         <figcaption>The visual result of the completed runtime script: Two spring forces act between the sphere site pairs defined in the generate step. The action-reaction forces are displayed. The boxes translate away from one another while rotating due to mismatched the unequal spring force.</figcaption>
     </figure>
 

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/mkdocs.yml

@@ -145,7 +145,6 @@ plugins:
             - https://mkdocstrings.github.io/griffe/objects.inv
             - https://docs.pydantic.dev/latest/objects.inv
             - https://numpy.org/doc/stable/objects.inv
-  - glightbox
 
 markdown_extensions:
   - abbr
@@ -187,10 +186,15 @@ markdown_extensions:
   - pymdownx.keys
   - pymdownx.mark
   - pymdownx.tilde
+  - zensical.extensions.glightbox:
+      auto_themed: true
 
 extra:
   generator: false
   social:
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/mujoco-mojo/
+      name: PyPI
     - icon: fontawesome/brands/github
       link: https://github.com/Hydrowelder
       name: My GitHub

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/pyproject.toml

@@ -92,7 +92,7 @@ dev = [
     "ruff>=0.14.14",
     "tabulate>=0.9.0",
     "watchfiles>=1.1.1",
-    "zensical>=0.0.31",
+    "zensical>=0.0.36",
 ]
 
 [project.scripts]

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/src/mujoco_mojo/mjcf/mujoco_attr/asset_attr/mesh.py

@@ -139,7 +139,11 @@ class MeshBase(XMLModel):
     @model_validator(mode="after")
     def validate_file(self) -> Self:
         # make the file extension lowercase
-        if self.file is not None and self.file.suffix not in [".stl", ".msh", ".obj"]:
+        if self.file is not None and self.file.suffix.lower() not in [
+            ".stl",
+            ".msh",
+            ".obj",
+        ]:
             msg = f'Mesh {self.name}: Invalid file suffix ({self.file.suffix}). Must be ".stl", ".msh", or ".obj".'
             logger.error(msg)
             raise ValueError(msg)

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/src/mujoco_mojo/mjcf/mujoco_attr/body_attr/inertial.py

@@ -211,7 +211,16 @@ class Inertial(XMLModel):
         eigvals = np.linalg.eigvalsh(M)
 
         if np.any(eigvals <= 0):
-            msg = (f"Inertia matrix must be positive definite. Eigenvalues: {eigvals}",)
+            msg = f"Inertia matrix must be positive definite. Eigenvalues: {eigvals}"
+            logger.error(msg)
+            raise ValueError(msg)
+
+        # triangle inequality check
+        # eigvalsh returns eigenvalues in ascending order, so e1 + e3 >= e2 and
+        # e2 + e3 >= e1 always hold; only the largest-vs-sum-of-others case can fail
+        e1, e2, e3 = eigvals
+        if e1 + e2 < e3:
+            msg = f"Inertia tensor violates the triangle inequality: the largest principal moment of inertia ({e3:.6e}) exceeds the sum of the other two ({e1:.6e} + {e2:.6e} = {e1 + e2:.6e})."
             logger.error(msg)
             raise ValueError(msg)
 
@@ -429,6 +438,28 @@ class Inertial(XMLModel):
             logger.exception(msg)
             raise ValueError(msg)
 
+        def _seed_dist(input_val: Any) -> None:
+            """Update the seed and trial number for the distribution."""
+            if isinstance(input_val, (list, tuple)):
+                for item in input_val:
+                    if isinstance(item, Distribution):
+                        item.with_seed(mojo_model.seed).with_trial_num(
+                            mojo_model.trial_num
+                        )
+            elif isinstance(input_val, Distribution):
+                input_val.with_seed(mojo_model.seed).with_trial_num(
+                    mojo_model.trial_num
+                )
+
+        _seed_dist(mass)
+        _seed_dist(pos)
+        if diaginertia is not None:
+            _seed_dist(diaginertia)
+        if fullinertia is not None:
+            _seed_dist(fullinertia)
+        if isinstance(orientation, tuple):
+            _seed_dist(orientation[1])
+
         def _resolve_and_track(input_val: Any) -> tuple[np.ndarray, list[NamedValue]]:
             """Samples distributions and prepares NamedValues for registration."""
             resolved_values = []
@@ -439,9 +470,6 @@ class Inertial(XMLModel):
                 for item in input_val:
                     if isinstance(item, Distribution):
                         # sample raw, but create the NamedValue container
-                        item.with_seed(mojo_model.seed).with_trial_num(
-                            mojo_model.trial_num
-                        )
                         nv = item.sample_to_named_value()
                         resolved_values.append(nv.squeeze())
                         pending_named_values.append(nv)
@@ -451,9 +479,6 @@ class Inertial(XMLModel):
 
             # case 2: single vector-level distribution
             if isinstance(input_val, Distribution):
-                input_val.with_seed(mojo_model.seed).with_trial_num(
-                    mojo_model.trial_num
-                )
                 nv = input_val.sample_to_named_value()
                 return nv.value.squeeze(), [nv]
 

{mujoco_mojo-2.3.7 → mujoco_mojo-2.3.9}/src/mujoco_mojo/mojo_model.py

@@ -64,3 +64,20 @@ class MojoModel(MojoBaseModel, StochasBase):
             self.user_data = cls.model_validate(data)
 
         return self.user_data
+
+    def clear_unpickleable_data(self) -> None:
+        """
+        Clear unpickleable objects from the model tree before serialization.
+
+        This walks through all geoms in the MJCF tree and clears cached collision managers and proximity queries that contain Cython objects which cannot be pickled for multiprocessing.
+        """
+        from mujoco_mojo.utils.proximity_mixin import ProximityMixin
+
+        if self.mjcf.worldbody is None:
+            return
+
+        bodies = self.mjcf.worldbody.walk_bodies(include_self=True)
+        for body in bodies:
+            for geom in body.geoms:
+                if isinstance(geom, ProximityMixin):
+                    geom.clear_unpickleable()