# google-deepmind/mujoco_warp architecture

> Architecture diagram of the GitHub repository google-deepmind/mujoco_warp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/mujoco_warp
- Repository: https://github.com/google-deepmind/mujoco_warp

## Overview

MJWarp is a GPU-accelerated MuJoCo physics simulator for batched robotics simulation and rendering. The principal workflow is to create model/data from MuJoCo inputs, invoke the public simulation API, and obtain updated state; separate API capabilities include inverse dynamics, sensors, ray queries, and batch rendering. The graph follows documented exports and SOURCE INDEX references. Several internals are unsampled, so their detailed call order is not inferred; the edges show only relationships evidenced by those references or the README.

Main entry points: [`mujoco_warp/__init__.py`](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/__init__.py) (MJWarp API), [`mujoco_warp/_src/forward.py`](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/forward.py) (Forward simulation), [`mujoco_warp/_src/derivative.py`](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/derivative.py) (Dynamics derivatives), [`mujoco_warp/_src/solver.py`](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/solver.py) (Constraint solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["MJWarp API<br/>[__init__.py]"]
  node_cli["Simulation CLI<br/>[cli.py]"]
end

subgraph group_simulation["Simulation"]
  node_forward["Forward simulation<br/>[forward.py]"]
  node_smooth["Smooth dynamics<br/>[smooth.py]"]
  node_passive["Passive forces<br/>[passive.py]"]
  node_derivative["Dynamics derivatives<br/>[derivative.py]"]
  node_solver["Constraint solver<br/>[solver.py]"]
  node_constraint["Constraint generation<br/>[constraint.py]"]
  node_island["Simulation islands<br/>[island.py]"]
  node_history["State history<br/>[history.py]"]
  node_sensor["Sensors<br/>[sensor.py]"]
end

subgraph group_collision["Collision"]
  node_collision_driver["Collision pipeline"]
  node_collision_core["Collision primitives<br/>[collision_core.py]"]
  node_collision_sdf["SDF collision<br/>[collision_sdf.py]"]
end

subgraph group_rendering["Rendering"]
  node_render["Batch renderer<br/>[render.py]"]
  node_ray["Ray queries<br/>[ray.py]"]
end

subgraph group_support["Model and utilities"]
  node_io["Model and data I/O<br/>[io.py]"]
  node_types["Model and state types<br/>[types.py]"]
  node_math["Physics math<br/>[math.py]"]
  node_support["Dynamics support<br/>[support.py]"]
  node_misc["Physics helpers<br/>[util_misc.py]"]
  node_warp_util["Warp utilities<br/>[warp_util.py]"]
end

node_user(("Simulation user"))
node_gpu(("NVIDIA GPU"))

node_user -->|"uses"| node_api
node_api -->|"exports"| node_io
node_api -->|"exports"| node_forward
node_api -->|"exports"| node_collision_driver
node_api -->|"exports"| node_constraint
node_api -->|"exports"| node_derivative
node_api -->|"exports"| node_history
node_api -->|"exports"| node_island
node_api -->|"exports"| node_passive
node_api -->|"exports"| node_ray
node_api -->|"exports"| node_render
node_api -->|"exports"| node_sensor
node_api -->|"returns simulation API"| node_user
node_io -->|"constructs"| node_types
node_forward -->|"calls"| node_collision_driver
node_forward -->|"calls"| node_constraint
node_forward -->|"calls"| node_derivative
node_forward -->|"uses"| node_history
node_forward -->|"uses"| node_island
node_forward -->|"calls"| node_passive
node_forward -->|"calls"| node_sensor
node_forward -->|"calls"| node_smooth
node_forward -->|"calls"| node_solver
node_collision_driver -->|"uses"| node_collision_core
node_collision_driver -->|"dispatches"| node_collision_sdf
node_constraint -->|"uses"| node_support
node_derivative -->|"uses"| node_smooth
node_derivative -->|"uses"| node_history
node_solver -->|"uses"| node_derivative
node_solver -->|"uses"| node_island
node_solver -->|"uses"| node_smooth
node_smooth -->|"uses"| node_support
node_passive -->|"uses"| node_support
node_render -->|"uses"| node_ray
node_render -->|"renders on"| node_gpu
node_cli -->|"uses"| node_io
node_cli -->|"uses"| node_warp_util
node_support -->|"uses"| node_math
node_misc -->|"uses"| node_math
node_forward -->|"uses"| node_misc

click node_api "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/__init__.py"
click node_io "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/io.py"
click node_types "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/types.py"
click node_forward "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/forward.py"
click node_smooth "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/smooth.py"
click node_passive "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/passive.py"
click node_derivative "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/derivative.py"
click node_solver "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/solver.py"
click node_constraint "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/constraint.py"
click node_island "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/island.py"
click node_history "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/history.py"
click node_collision_driver "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_driver.py"
click node_collision_core "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_core.py"
click node_collision_sdf "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_sdf.py"
click node_render "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/render.py"
click node_ray "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/ray.py"
click node_sensor "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/sensor.py"
click node_cli "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/cli.py"
click node_math "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/math.py"
click node_support "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/support.py"
click node_misc "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/util_misc.py"
click node_warp_util "https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/warp_util.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cli,node_user toneBlue
class node_forward,node_smooth,node_passive,node_derivative,node_solver,node_constraint,node_island,node_history,node_sensor toneAmber
class node_collision_driver,node_collision_core,node_collision_sdf toneMint
class node_render,node_ray toneRose
class node_io,node_types,node_math,node_support,node_misc,node_warp_util,node_gpu toneIndigo
```

## Components

### Public API

- [MJWarp API](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/__init__.py): `mujoco_warp/__init__.py`
- [Simulation CLI](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/cli.py): `mujoco_warp/_src/cli.py`

### Simulation

- [Forward simulation](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/forward.py): `mujoco_warp/_src/forward.py`
- [Smooth dynamics](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/smooth.py): `mujoco_warp/_src/smooth.py`
- [Passive forces](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/passive.py): `mujoco_warp/_src/passive.py`
- [Dynamics derivatives](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/derivative.py): `mujoco_warp/_src/derivative.py`
- [Constraint solver](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/solver.py): `mujoco_warp/_src/solver.py`
- [Constraint generation](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/constraint.py): `mujoco_warp/_src/constraint.py`
- [Simulation islands](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/island.py): `mujoco_warp/_src/island.py`
- [State history](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/history.py): `mujoco_warp/_src/history.py`
- [Sensors](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/sensor.py): `mujoco_warp/_src/sensor.py`

### Collision

- [Collision pipeline](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_driver.py): `mujoco_warp/_src/collision_driver.py`
- [Collision primitives](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_core.py): `mujoco_warp/_src/collision_core.py`
- [SDF collision](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/collision_sdf.py): `mujoco_warp/_src/collision_sdf.py`

### Rendering

- [Batch renderer](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/render.py): `mujoco_warp/_src/render.py`
- [Ray queries](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/ray.py): `mujoco_warp/_src/ray.py`

### Model and utilities

- [Model and data I/O](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/io.py): `mujoco_warp/_src/io.py`
- [Model and state types](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/types.py): `mujoco_warp/_src/types.py`
- [Physics math](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/math.py): `mujoco_warp/_src/math.py`
- [Dynamics support](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/support.py): `mujoco_warp/_src/support.py`
- [Physics helpers](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/util_misc.py): `mujoco_warp/_src/util_misc.py`
- [Warp utilities](https://github.com/google-deepmind/mujoco_warp/blob/main/mujoco_warp/_src/warp_util.py): `mujoco_warp/_src/warp_util.py`

### Other components

- **Simulation user**
- **NVIDIA GPU**

## Connections

- Simulation user → MJWarp API: uses (evidence: `README.md`)
- MJWarp API → Model and data I/O: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Forward simulation: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Collision pipeline: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Constraint generation: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Dynamics derivatives: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → State history: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Simulation islands: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Passive forces: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Ray queries: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Batch renderer: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Sensors: exports (evidence: `mujoco_warp/__init__.py`)
- MJWarp API → Simulation user: returns simulation API (evidence: `README.md`)
- Model and data I/O → Model and state types: constructs (evidence: `mujoco_warp/_src/io.py`)
- Forward simulation → Collision pipeline: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Constraint generation: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Dynamics derivatives: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → State history: uses (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Simulation islands: uses (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Passive forces: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Sensors: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Smooth dynamics: calls (evidence: `mujoco_warp/_src/forward.py`)
- Forward simulation → Constraint solver: calls (evidence: `mujoco_warp/_src/forward.py`)
- Collision pipeline → Collision primitives: uses (evidence: `mujoco_warp/_src/collision_driver.py`)
- Collision pipeline → SDF collision: dispatches (evidence: `mujoco_warp/_src/collision_driver.py`)
- Constraint generation → Dynamics support: uses (evidence: `mujoco_warp/_src/constraint.py`)
- Dynamics derivatives → Smooth dynamics: uses (evidence: `mujoco_warp/_src/derivative.py`)
- Dynamics derivatives → State history: uses (evidence: `mujoco_warp/_src/derivative.py`)
- Constraint solver → Dynamics derivatives: uses (evidence: `mujoco_warp/_src/solver.py`)
- Constraint solver → Simulation islands: uses (evidence: `mujoco_warp/_src/solver.py`)
- Constraint solver → Smooth dynamics: uses (evidence: `mujoco_warp/_src/solver.py`)
- Smooth dynamics → Dynamics support: uses (evidence: `mujoco_warp/_src/smooth.py`)
- Passive forces → Dynamics support: uses (evidence: `mujoco_warp/_src/passive.py`)
- Batch renderer → Ray queries: uses (evidence: `mujoco_warp/_src/render.py`)
- Batch renderer → NVIDIA GPU: renders on (evidence: `README.md`)
- Simulation CLI → Model and data I/O: uses (evidence: `mujoco_warp/_src/cli.py`)
- Simulation CLI → Warp utilities: uses (evidence: `mujoco_warp/_src/cli.py`)
- Dynamics support → Physics math: uses (evidence: `mujoco_warp/_src/support.py`)
- Physics helpers → Physics math: uses (evidence: `mujoco_warp/_src/util_misc.py`)
- Forward simulation → Physics helpers: uses (evidence: `mujoco_warp/_src/forward.py`)
