Metadata-Version: 2.4
Name: maddening
Version: 0.1.0
Summary: Modular Automatic Differentiation and Data-Enhanced Neural-network INteracting Graph
Project-URL: Homepage, https://microrobotica.org/maddening/
Project-URL: Documentation, https://microrobotica.org/maddening/
Project-URL: Repository, https://github.com/Microrobotics-Simulation-Framework/MADDENING
Project-URL: Issues, https://github.com/Microrobotics-Simulation-Framework/MADDENING/issues
Author: Nicholas Ehsan Roy
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: jax<0.6,>=0.4
Requires-Dist: jaxlib<0.6,>=0.4
Requires-Dist: numpy>=1.24
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: equinox>=0.11; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: glfw>=2.0; extra == 'all'
Requires-Dist: matplotlib>=3.5; extra == 'all'
Requires-Dist: optax>=0.1; extra == 'all'
Requires-Dist: pillow>=9.0; extra == 'all'
Requires-Dist: pygfx>=0.16; extra == 'all'
Requires-Dist: pygobject>=3.42; extra == 'all'
Requires-Dist: pyvista>=0.42; extra == 'all'
Requires-Dist: pyzmq>=25.0; extra == 'all'
Requires-Dist: rendercanvas>=2.0; extra == 'all'
Requires-Dist: rich>=12.0; extra == 'all'
Requires-Dist: scikit-image>=0.20; extra == 'all'
Requires-Dist: skypilot[lambda,runpod]>=0.11; extra == 'all'
Requires-Dist: uvicorn>=0.20; extra == 'all'
Requires-Dist: websockets>=11.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: uvicorn>=0.20; extra == 'api'
Requires-Dist: websockets>=11.0; extra == 'api'
Provides-Extra: aws
Requires-Dist: skypilot[aws]>=0.11; extra == 'aws'
Provides-Extra: ci
Requires-Dist: equinox>=0.11; extra == 'ci'
Requires-Dist: fastapi>=0.100; extra == 'ci'
Requires-Dist: httpx>=0.24; extra == 'ci'
Requires-Dist: matplotlib>=3.5; extra == 'ci'
Requires-Dist: optax>=0.1; extra == 'ci'
Requires-Dist: pytest>=7.0; extra == 'ci'
Requires-Dist: pyzmq>=25.0; extra == 'ci'
Requires-Dist: rich>=12.0; extra == 'ci'
Requires-Dist: skypilot[runpod]>=0.11; extra == 'ci'
Requires-Dist: uvicorn>=0.20; extra == 'ci'
Requires-Dist: websockets>=11.0; extra == 'ci'
Provides-Extra: client
Requires-Dist: pyzmq>=25.0; extra == 'client'
Requires-Dist: rich>=12.0; extra == 'client'
Provides-Extra: cloud
Requires-Dist: skypilot[lambda,runpod]>=0.11; extra == 'cloud'
Provides-Extra: cloud-all
Requires-Dist: skypilot[all]>=0.11; extra == 'cloud-all'
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]<0.6,>=0.4; extra == 'cuda12'
Provides-Extra: dev
Requires-Dist: equinox>=0.11; extra == 'dev'
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: glfw>=2.0; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: matplotlib>=3.5; extra == 'dev'
Requires-Dist: optax>=0.1; extra == 'dev'
Requires-Dist: pillow>=9.0; extra == 'dev'
Requires-Dist: pygfx>=0.16; extra == 'dev'
Requires-Dist: pygobject>=3.42; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyvista>=0.42; extra == 'dev'
Requires-Dist: pyzmq>=25.0; extra == 'dev'
Requires-Dist: rendercanvas>=2.0; extra == 'dev'
Requires-Dist: rich>=12.0; extra == 'dev'
Requires-Dist: scikit-image>=0.20; extra == 'dev'
Requires-Dist: skypilot[lambda,runpod]>=0.11; extra == 'dev'
Requires-Dist: uvicorn>=0.20; extra == 'dev'
Requires-Dist: websockets>=11.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: skypilot[gcp]>=0.11; extra == 'gcp'
Provides-Extra: gpu-viz
Requires-Dist: glfw>=2.0; extra == 'gpu-viz'
Requires-Dist: pygfx>=0.16; extra == 'gpu-viz'
Requires-Dist: rendercanvas>=2.0; extra == 'gpu-viz'
Requires-Dist: scikit-image>=0.20; extra == 'gpu-viz'
Provides-Extra: lambda
Requires-Dist: skypilot[lambda]>=0.11; extra == 'lambda'
Provides-Extra: network
Requires-Dist: pyzmq>=25.0; extra == 'network'
Provides-Extra: runpod
Requires-Dist: skypilot[runpod]>=0.11; extra == 'runpod'
Provides-Extra: sbom
Requires-Dist: cyclonedx-bom>=4.0; extra == 'sbom'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: matplotlib>=3.5; extra == 'server'
Requires-Dist: pyzmq>=25.0; extra == 'server'
Requires-Dist: rich>=12.0; extra == 'server'
Requires-Dist: uvicorn>=0.20; extra == 'server'
Requires-Dist: websockets>=11.0; extra == 'server'
Provides-Extra: streaming
Requires-Dist: pygobject>=3.42; extra == 'streaming'
Requires-Dist: websockets>=11.0; extra == 'streaming'
Provides-Extra: surrogates
Requires-Dist: equinox>=0.11; extra == 'surrogates'
Requires-Dist: optax>=0.1; extra == 'surrogates'
Provides-Extra: terminal
Requires-Dist: rich>=12.0; extra == 'terminal'
Provides-Extra: tpu
Requires-Dist: jax[tpu]<0.6,>=0.4; extra == 'tpu'
Provides-Extra: usd
Requires-Dist: usd-core>=21.8; extra == 'usd'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == 'viz'
Provides-Extra: viz3d
Requires-Dist: pillow>=9.0; extra == 'viz3d'
Requires-Dist: pyvista>=0.42; extra == 'viz3d'
Description-Content-Type: text/markdown

# MADDENING

**M**odular **A**utomatic **D**ifferentiation and **D**ata-**E**nhanced **N**eural-network **IN**teracting **G**raph

📖 **Documentation: <https://microrobotica.org/maddening/>**
🧩 Part of the [Microrobotics Simulation Framework](https://microrobotica.org/) (MADDENING · MIME · MICROROBOTICA).

A JAX-based modular simulation framework for multi-physics. Designed as the computational backbone of [MIME](https://microrobotica.org/mime/) (MIcrorobotics Multiphysics Engine).

> **Regulatory disclaimer**: MADDENING is research software. It is not a medical device as defined by EU MDR (EU 2017/745) and is not intended for clinical use. When used in a regulated product, MADDENING is classified as SOUP (Software of Unknown Provenance) under IEC 62304. See `docs/regulatory/` for details.

## What It Does

MADDENING manages a **simulation graph** where each node simulates one aspect of a physical system (fluid dynamics, rigid body mechanics, heat transfer, etc.) and edges represent coupling between them. The entire graph step is JIT-compiled into a single XLA computation via JAX, making the simulation fully differentiable and GPU-accelerated.

**Core capabilities:**
- **Graph-based multi-physics** — nodes are independent JAX programs coupled by typed edges
- **Fully differentiable** — `jax.grad` through entire coupled simulations (verified through 1000-step rollouts)
- **Iterative coupling** — Gauss-Seidel and Jacobi with convergence acceleration (Aitken, IQN-ILS, IQN-IMVJ)
- **Multi-rate timestepping** — each node at its own timestep, GCD-based base rate
- **Adaptive timestepping** — Richardson extrapolation with PI controller
- **Neural surrogates** — train MLP/DeepONet/FNO surrogates from simulation data, hot-swap into the graph
- **Cloud deployment** — provision GPU VMs via SkyPilot, stream rendered viewports via WebRTC
- **Multi-job** — distribute subgraphs across VMs with ZMQ-based rendezvous coordination

**Package structure:**
```
maddening/
├── core/                 # Graph manager, node ABC, edge spec, schedule
│   ├── coupling/         # Iterative coupling, convergence, acceleration, spatial mapping
│   ├── simulation/       # Adaptive dt, checkpoint, integrators, calibration, profiler
│   └── compliance/       # Metadata, stability, anomaly tracking, audit, UQ
├── nodes/                # Built-in nodes (Ball, Table, Spring, Heat, LBM, HeartPump, RigidBody)
├── surrogates/           # Neural surrogate framework (architectures, training, validation)
├── cloud/                # Cloud orchestration (SkyPilot, providers, coordinator, streaming)
│   └── multigpu/         # Device mesh, partitioning, sharded nodes, coordinator
├── viz/                  # Visualization (renderer ABC, relay, runner, backends)
├── api/                  # FastAPI server (REST + WebSocket + server-side rendering)
└── usd/                  # OpenUSD integration (graph serialization, geometry)
```

## Installation

```bash
pip install maddening                    # CPU (base)
pip install maddening[cuda12]            # GPU with CUDA 12
pip install maddening[cuda12,viz]        # GPU + matplotlib plots
pip install maddening[server,cuda12]     # GPU simulation server
pip install maddening[runpod]            # Cloud deploy to RunPod
```

| Extra | What it adds |
|-------|-------------|
| `cuda12` / `tpu` | GPU / TPU acceleration |
| `viz` | Matplotlib renderers |
| `terminal` | Rich terminal renderer |
| `api` | FastAPI HTTP/WS server |
| `network` | ZeroMQ remote transport |
| `surrogates` | Neural surrogate training (equinox + optax) |
| `runpod` / `lambda` / `aws` / `gcp` | Cloud deploy via SkyPilot |
| `server` | Bundle: FastAPI + ZMQ + rich + matplotlib |
| `cloud` | All supported cloud providers |
| `all` | Everything |

Works with both pip and [uv](https://docs.astral.sh/uv/). See [docs/user_guide/installation.md](docs/user_guide/installation.md) for the full guide.

## Quick Start

```python
import jax.numpy as jnp
from maddening import GraphManager, SimulationNode

class BounceNode(SimulationNode):
    @property
    def requires_halo(self) -> bool:
        return False  # pointwise (no spatial neighbors)

    def initial_state(self):
        return {"position": jnp.array(5.0), "velocity": jnp.array(0.0)}

    def update(self, state, boundary_inputs, dt):
        new_vel = state["velocity"] + -9.81 * dt
        new_pos = state["position"] + new_vel * dt
        new_vel = jnp.where(new_pos < 0, jnp.abs(new_vel) * 0.8, new_vel)
        new_pos = jnp.maximum(new_pos, 0.0)
        return {"position": new_pos, "velocity": new_vel}

gm = GraphManager()
gm.add_node(BounceNode(name="ball", timestep=0.01))
gm.compile()
final_state, history = gm.run_scan_with_history(n_steps=500)
```

See [docs/user_guide/quickstart.md](docs/user_guide/quickstart.md) for the full tutorial.

## Cloud Deployment

Pre-built Docker image with JAX CUDA, GStreamer, and all server dependencies:

```bash
pip install maddening[runpod]
# Set up ~/.maddening/cloud_credentials.yaml (see examples/cloud/config/)
```

```python
from maddening.cloud.launcher import CloudLauncher

launcher = CloudLauncher()
job = launcher.launch("job_config.yaml")  # provisions GPU VM
job.ssh_run("python3 my_simulation.py")   # run directly on GPU
job.teardown()
```

Docker image: `ghcr.io/microrobotics-simulation-framework/maddening-cloud:latest`

## For MIME Developers

MADDENING is designed to be extended by MIME. See:
- [docs/user_guide/installation.md](docs/user_guide/installation.md) — install options
- [docs/developer_guide/node_authoring.md](docs/developer_guide/node_authoring.md) — writing custom nodes
- [DESIGN.md](DESIGN.md) — architecture decisions
- [CLOUD_ROADMAP.md](CLOUD_ROADMAP.md) — cloud/multi-GPU/multi-job architecture
- [DOCUMENTATION_ARCHITECTURE.md](DOCUMENTATION_ARCHITECTURE.md) — regulatory compliance structure

## License

LGPL-3.0-or-later. See [LICENSE](LICENSE).
