41 project init

.github/workflows/docs.yml

@@ -23,6 +23,8 @@ jobs:
           enable-cache: true
       - name: Install Python 3.13
         run: uv python install 3.13
+      - name: Generate API reference pages
+        run: uv run --python 3.13 --group dev python mujoco-mojo/scripts/gen_ref_pages.py
       - run: uv run --python 3.13 --group dev zensical build --clean
       - uses: actions/upload-pages-artifact@v4
         with:

.gitignore

@@ -13,6 +13,7 @@ mojo.log
 mojo.log.*
 
 site
+docs/reference/
 mojo-models
 textures
 

docs/user-guides/getting-started.md

@@ -306,5 +306,14 @@ MuJoCo does not currently ship first-party Python typing stubs. To enable proper
 
 ---
 
+!!! tip "Tip: Scaffold a New Project"
+    Before diving into the generate script, run `mujoco-mojo init` in a new directory to get a working project skeleton — `simulation.py`, `run.sh`, and `reloaded.sh` — pre-wired and ready to edit.
+
+    ```bash linenums="0"
+    mujoco-mojo init
+    ```
+
+    See the [Initializing a Project](init.md) guide for details.
+
 !!! success
     This concludes our basic overview of the core concepts to MuJoCo Mojo. The next guide will cover how to get started with assembling your first model with the [generate script](generate-script.md).

docs/user-guides/init.md

@@ -0,0 +1,65 @@
+# Initializing a New Project
+
+!!! abstract
+    The `mujoco-mojo init` command scaffolds a new project in the current directory, providing ready-to-run starter files for Monte Carlo campaigns or optimization studies.
+
+---
+
+## Usage
+
+```bash linenums="0"
+mujoco-mojo init [--optimizer]
+```
+
+With no flags, the command generates a standard Monte Carlo project. Pass `--optimizer` to include an `objective` function stub for use with `mujoco-mojo run optimization`.
+
+---
+
+## Generated Files
+
+Running `mujoco-mojo init` produces three files in the current directory:
+
+| File | Purpose |
+|---|---|
+| `simulation.py` | Simulation stubs: `UserData`, `generate`, and `runtime` |
+| `run.sh` | Pre-configured shell script to launch the campaign |
+| `reloaded.sh` | Shell script to open the interactive viewer |
+
+Both shell scripts are made executable and resolve their paths relative to their own location, so they can be invoked from any working directory.
+
+---
+
+## Monte Carlo (default)
+
+```bash linenums="0"
+mujoco-mojo init
+```
+
+`simulation.py` will contain stubs for `generate` and `runtime`. `run.sh` will call `mujoco-mojo run monte-carlo`.
+
+---
+
+## Optimization
+
+```bash linenums="0"
+mujoco-mojo init --optimizer
+```
+
+`simulation.py` will additionally contain an `objective` stub. `run.sh` will call `mujoco-mojo run optimization`.
+
+---
+
+## Next Steps
+
+After running `init`, fill in your `generate` and `runtime` functions, then launch your campaign:
+
+```bash linenums="0"
+bash run.sh
+```
+
+!!! tip
+    Use `reloaded.sh` during development to get rapid visual feedback on your model without running a full campaign.
+
+    ```bash linenums="0"
+    bash reloaded.sh
+    ```

docs/user-guides/reloaded.md

@@ -17,14 +17,20 @@ mujoco-mojo reloaded --generator my_sim.Experiment.generate
 
 The `reloaded` command is highly flexible, allowing you to specify different viewers, initial seeds, and even pass custom arguments to your scripts.
 
-| Argument           | Description                                                               |
-|:-------------------|:--------------------------------------------------------------------------|
-| `--help`           | Describes all available arguments. Used on its own.                       |
-| `--generator`      | **(Required)** Import path to your `MojoGenerate` function.               |
-| `--runtime`        | Optional import path to your `MojoRuntime` function.                      |
-| `--user-interface` | Choose your viewer: `opengl` (native), `viser`, or `mjviser` (web-based). |
-| `--seed`           | Set the global seed for stochastic draws.                                 |
-| `--port`           | Port for the web-based viewers (default: `8080`).                         |
+| Argument           | Shortcut | Description                                                                    |
+|:-------------------|:---------|:-------------------------------------------------------------------------------|
+| `--help`           |          | Describes all available arguments. Used on its own.                            |
+| `--generator`      | `-g`     | Import path to your `generate` function.                                       |
+| `--config`         | `-c`     | Path to a saved `model_config.json`. Mutually exclusive with `--generator`.    |
+| `--runtime`        | `-r`     | Optional import path to your `runtime` function.                               |
+| `--workdir`        | `-w`     | Workspace directory for output files (default: `mojo-models`).                 |
+| `--user-interface` | `-ui`    | Choose your viewer: `opengl` (native), `viser`, or `mjviser` (web-based).      |
+| `--trial-num`      | `-tn`    | Load the random state for a specific trial number (default: `0`).              |
+| `--seed`           | `-s`     | Set the global seed for stochastic draws.                                      |
+| `--overrides`      | `-o`     | Path to a NamedValue overrides JSON file. Fixes specific distribution draws.   |
+| `--gen-arg`        | `-ga`    | Positional argument forwarded to the generator. Repeatable.                    |
+| `--gen-kwarg`      | `-gk`    | Keyword argument (`key=value`) forwarded to the generator. Repeatable.         |
+| `--port`           | `-p`     | Port for the web-based viewers (default: `8080`).                              |
 
 ---
 
@@ -41,6 +47,31 @@ Once Reloaded is running, your terminal becomes an interactive command center. Y
 
 ---
 
+## Loading a Saved Model Config
+
+As an alternative to calling a generator function, Reloaded can load a previously saved `model_config.json` directly using `--config`. This is useful when you want to inspect the exact model that was used in a specific trial without running any Python generation logic.
+
+```bash linenums="0"
+mujoco-mojo reloaded --config ./results/trial_0042/model_config.json
+```
+
+This mode is mutually exclusive with `--generator`.
+
+---
+
+## Inspecting a Specific Trial
+
+When iterating on a stochastic simulation, it is often necessary to reproduce the exact random state of a particular trial. Pass `--trial-num` to seed the session with that trial's distribution draws.
+
+```bash linenums="0"
+# Open trial 42 in the viewer, using the same seed and random draws as the original campaign
+mujoco-mojo reloaded -g sim.generate -r sim.runtime --seed 123 --trial-num 42
+```
+
+Combined with `--overrides`, you can also lock specific named values to fixed quantities while keeping everything else stochastic, which helps isolate the effect of individual parameters.
+
+---
+
 ## Workflow
 
 ### MJCF Prototyping

docs/user-guides/running-jobs.md

@@ -13,25 +13,23 @@ Mojo uses a single, unified command structure for all job types. By adjusting a
 
 ### Running a Single Trial
 
-To run exactly one trial (usually trial `0`), simply set the trial count to `1` or specify a specific trial number.
+Use `mujoco-mojo run single` when you want to execute exactly one trial. It accepts the same arguments as `run monte-carlo` and is the recommended command when running a baseline or re-running an individual trial for inspection.
 
 ```bash linenums="0"
-# Run one trial using nominal values
-mujoco-mojo run monte-carlo --generator sim.generate --runtime sim.runtime --seed 123 --n-trial 1
+# Run trial 0 (nominal values)
+mujoco-mojo run single -g sim.generate -r sim.runtime --seed 123
 
-# Or run a specific trial from a previous distribution
-mujoco-mojo run monte-carlo -g sim.generate -r sim.runtime --seed 123 --trial-num 42
+# Re-run a specific trial from a previous campaign
+mujoco-mojo run single -g sim.generate -r sim.runtime --seed 123 --trial-num 42
 ```
 
 ???+ note "Note: Nominal Run"
-    For stochastic values, trial number `0` will use the distribution's `nominal_value` (if provided). This allows you to not only be able to recreate a model, but also build a "baseline" simulation.
+    Trial number `0` uses each distribution's `nominal_value` (if one was provided). This gives you a deterministic baseline that reflects design intent rather than a stochastic draw.
 
-    This helps you with defining the design intent, rather than letting chaos take over!
-
-More than one `--trial-num` argument can be passed to the command. This will make it so those select trials are run:
+You can also target specific trials within a full `run monte-carlo` campaign by passing `--trial-num` one or more times. This is useful for re-running failed trials without re-running the entire job.
 
 ```bash linenums="0"
-# This will run trials 12 and 42
+# Re-run only trials 12 and 42
 mujoco-mojo run monte-carlo -g sim.generate -r sim.runtime --seed 123 --trial-num 12 --trial-num 42
 ```
 

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
   - User Guide:
       # - user-guide.md
       - Getting Started: user-guides/getting-started.md
+      - Initializing a Project: user-guides/init.md
       - Generate Script: user-guides/generate-script.md
       - Runtime Script: user-guides/runtime-script.md
       - Running Jobs:
@@ -27,7 +28,30 @@ nav:
           - Mosaic: user-guides/mosaic.md
       - Optimization: user-guides/optimization.md
       - Reloaded: user-guides/reloaded.md
-  # - Code Reference: reference/
+  - Code Reference:
+      - reference/index.md
+      - mujoco_mojo:
+          - reference/mujoco_mojo/index.md
+          - MojoModel: reference/mujoco_mojo/mojo_model.md
+          - Base: reference/mujoco_mojo/base.md
+          - Visualization: reference/mujoco_mojo/visualization.md
+          - Typing: reference/mujoco_mojo/typing.md
+          # - Stochas: reference/mujoco_mojo/stochas.md
+          - MJCF: reference/mujoco_mojo/mjcf.md
+      - Runtime:
+          - reference/mujoco_mojo/runtime/index.md
+          - Load: reference/mujoco_mojo/runtime/load.md
+          - RuntimeManager: reference/mujoco_mojo/runtime/runtime_manager.md
+          - SignalManager: reference/mujoco_mojo/runtime/signal_manager.md
+          - VideoRecorder: reference/mujoco_mojo/runtime/video_recorder.md
+      - Utils:
+          - reference/mujoco_mojo/utils/index.md
+          - Color: reference/mujoco_mojo/utils/color.md
+          - Runner: reference/mujoco_mojo/utils/runner.md
+          - Proximity: reference/mujoco_mojo/utils/proximity.md
+          - Filters: reference/mujoco_mojo/utils/filters.md
+          - Interp: reference/mujoco_mojo/utils/interp.md
+          - Dataframe: reference/mujoco_mojo/utils/dataframe.md
   - About: about.md
 
 theme:
@@ -81,12 +105,14 @@ plugins:
   - search
   - open-in-new-tab:
       add_icon: true
+  # gen-files and literate-nav are MkDocs-only plugins; zensical ignores them.
+  # Reference pages are pre-generated by scripts/gen_ref_pages.py instead.
   # - gen-files:
   #     scripts:
   #       - scripts/gen_ref_pages.py
-  - literate-nav:
-      nav_file: SUMMARY.md
-  - section-index
+  # - literate-nav:
+  #     nav_file: SUMMARY.md
+  # - section-index
   - mkdocstrings:
       handlers:
         python:

pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=61", "wheel"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
 
 [project]
 name = "mujoco-mojo"
-version = "2.2.2"
+dynamic = ["version"]
 description = "A complete MJCF lifecycle and trial orchestration suite for MuJoCo, powered by Pydantic v2."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -94,8 +94,12 @@ dev = [
 [project.scripts]
 mujoco-mojo = "mujoco_mojo.utils.layers.cli:cli_app"
 
-[tool.setuptools.package-data]
-"*" = ["*.html", "*.js", "*.mp3", "*.svg", "*.css"]
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mujoco_mojo"]
 
 [tool.ruff]
 exclude = ["typings", "scripts/templating/sensor_template.py"]

scripts/gen_ref_pages.py

@@ -1,35 +1,87 @@
-"""Generate the code reference pages and navigation."""
+"""
+Generate API reference pages in docs/reference/.
+
+Run this script before building the docs site:
+
+    python scripts/gen_ref_pages.py
+
+The output is written to docs/reference/ and is consumed by zensical (or
+mkdocs) via the ::: autodoc directives.  The directory is gitignored; this
+script must be run as part of the CI pipeline before zensical build.
+"""
 
 from pathlib import Path
 
-import mkdocs_gen_files
+ROOT = Path(__file__).parent.parent
+DOCS_REF = ROOT / "docs" / "reference"
+
+# ---------------------------------------------------------------------------
+# Modules to document: (dotted identifier, output path relative to DOCS_REF)
+# ---------------------------------------------------------------------------
+MODULES: list[tuple[str, str]] = [
+    # top-level package
+    ("mujoco_mojo", "mujoco_mojo/index.md"),
+    ("mujoco_mojo.mojo_model", "mujoco_mojo/mojo_model.md"),
+    ("mujoco_mojo.base", "mujoco_mojo/base.md"),
+    ("mujoco_mojo.visualization", "mujoco_mojo/visualization.md"),
+    # typing — enums and type aliases (some not re-exported at top level)
+    ("mujoco_mojo.typing", "mujoco_mojo/typing.md"),
+    # stochas — distributions and named values (has items not in top-level __all__)
+    ("mujoco_mojo.stochas", "mujoco_mojo/stochas.md"),
+    # runtime
+    ("mujoco_mojo.runtime", "mujoco_mojo/runtime/index.md"),
+    ("mujoco_mojo.runtime.load", "mujoco_mojo/runtime/load.md"),
+    ("mujoco_mojo.runtime.runtime_manager", "mujoco_mojo/runtime/runtime_manager.md"),
+    ("mujoco_mojo.runtime.signal_manager", "mujoco_mojo/runtime/signal_manager.md"),
+    ("mujoco_mojo.runtime.video_recorder", "mujoco_mojo/runtime/video_recorder.md"),
+    # utils
+    ("mujoco_mojo.utils", "mujoco_mojo/utils/index.md"),
+    ("mujoco_mojo.utils.color", "mujoco_mojo/utils/color.md"),
+    ("mujoco_mojo.utils.runner", "mujoco_mojo/utils/runner.md"),
+    ("mujoco_mojo.utils.proximity", "mujoco_mojo/utils/proximity.md"),
+    ("mujoco_mojo.utils.filters", "mujoco_mojo/utils/filters.md"),
+    ("mujoco_mojo.utils.interp", "mujoco_mojo/utils/interp.md"),
+    ("mujoco_mojo.utils.dataframe", "mujoco_mojo/utils/dataframe.md"),
+]
+
+# ---------------------------------------------------------------------------
+# Hand-written stub for mujoco_mojo.mjcf (too large to autodoc)
+# ---------------------------------------------------------------------------
+MJCF_STUB = """\
+# mujoco\\_mojo.mjcf
+
+The `mujoco_mojo.mjcf` subpackage provides the complete Python object model
+for the MuJoCo XML schema.  It mirrors the official XML structure closely, so
+the best reference is the upstream documentation:
+
+[MuJoCo XML Reference :material-open-in-new:](https://mujoco.readthedocs.io/en/stable/XMLreference.html){ .md-button .md-button--primary target=_blank }
+
+All `mjcf` types are re-exported from the top-level `mujoco_mojo` namespace,
+so you rarely need to import directly from `mujoco_mojo.mjcf`.
 
-nav = mkdocs_gen_files.Nav()  # type: ignore
+```python
+import mujoco_mojo as mojo
 
-root = Path(__file__).parent.parent
-src = root / "src"
+body = mojo.Body(name=mojo.BodyName("my_body"))
+```
+"""
 
-for path in sorted(src.rglob("*.py")):
-    module_path = path.relative_to(src).with_suffix("")
-    doc_path = path.relative_to(src).with_suffix(".md")
-    full_doc_path = Path("reference", doc_path)
 
-    parts = tuple(module_path.parts)
+def main() -> None:
+    DOCS_REF.mkdir(parents=True, exist_ok=True)
 
-    if parts[-1] == "__init__":
-        parts = parts[:-1]
-        doc_path = doc_path.with_name("index.md")
-        full_doc_path = full_doc_path.with_name("index.md")
-    elif parts[-1] == "__main__":
-        continue
+    for module, rel_path in MODULES:
+        dest = DOCS_REF / rel_path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(f"::: {module}\n", encoding="utf-8")
+        print(f"  {dest.relative_to(ROOT)}")
 
-    nav[parts] = doc_path.as_posix()
+    mjcf_page = DOCS_REF / "mujoco_mojo" / "mjcf.md"
+    mjcf_page.write_text(MJCF_STUB, encoding="utf-8")
+    print(f"  {mjcf_page.relative_to(ROOT)}")
 
-    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
-        fd.write(f"::: {ident}")
+    print(f"\nWrote {len(MODULES) + 1} pages to {DOCS_REF.relative_to(ROOT)}/")
 
-    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
 
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+if __name__ == "__main__":
+    main()