{"id":49759113,"url":"https://github.com/microrobotics-simulation-framework/maddening","last_synced_at":"2026-05-30T20:00:24.625Z","repository":{"id":351416291,"uuid":"940086717","full_name":"Microrobotics-Simulation-Framework/MADDENING","owner":"Microrobotics-Simulation-Framework","description":"Modular Automatic Differentiation and Data-Enhanced Neural-network INteracting Graph (MADDENING).  A pure JAX end-to-end autodifferentiable graph based framework for multiphysics simulation.","archived":false,"fork":false,"pushed_at":"2026-05-19T15:44:01.000Z","size":1415,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-19T15:44:24.457Z","etag":null,"topics":["automatic-differentiation","differentiable-simulation","gpu-computing","jax","multiphysics","python","scientific-computing","simulation","xla"],"latest_commit_sha":null,"homepage":"https://microrobotica.org/maddening/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Microrobotics-Simulation-Framework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-27T15:39:47.000Z","updated_at":"2026-05-15T15:38:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"8d0b7dd9-dbb3-42a1-ba44-2d57377cab77","html_url":"https://github.com/Microrobotics-Simulation-Framework/MADDENING","commit_stats":null,"previous_names":["microrobotics-simulation-framework/maddening"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Microrobotics-Simulation-Framework/MADDENING","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Microrobotics-Simulation-Framework%2FMADDENING","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Microrobotics-Simulation-Framework%2FMADDENING/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Microrobotics-Simulation-Framework%2FMADDENING/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Microrobotics-Simulation-Framework%2FMADDENING/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Microrobotics-Simulation-Framework","download_url":"https://codeload.github.com/Microrobotics-Simulation-Framework/MADDENING/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Microrobotics-Simulation-Framework%2FMADDENING/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33707328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatic-differentiation","differentiable-simulation","gpu-computing","jax","multiphysics","python","scientific-computing","simulation","xla"],"created_at":"2026-05-11T02:55:01.819Z","updated_at":"2026-05-30T20:00:24.606Z","avatar_url":"https://github.com/Microrobotics-Simulation-Framework.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MADDENING\n\n**M**odular **A**utomatic **D**ifferentiation and **D**ata-**E**nhanced **N**eural-network **IN**teracting **G**raph\n\n📖 **Documentation: \u003chttps://microrobotica.org/maddening/\u003e**\n🧩 Part of the [Microrobotics Simulation Framework](https://microrobotica.org/) (MADDENING · MIME · MICROROBOTICA).\n\nA JAX-based modular simulation framework for multi-physics. Designed as the computational backbone of [MIME](https://microrobotica.org/mime/) (MIcrorobotics Multiphysics Engine).\n\n\u003e **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.\n\n## What It Does\n\nMADDENING 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.\n\n**Core capabilities:**\n- **Graph-based multi-physics** — nodes are independent JAX programs coupled by typed edges\n- **Fully differentiable** — `jax.grad` through entire coupled simulations (verified through 1000-step rollouts)\n- **Iterative coupling** — Gauss-Seidel and Jacobi with convergence acceleration (Aitken, IQN-ILS, IQN-IMVJ)\n- **Multi-rate timestepping** — each node at its own timestep, GCD-based base rate\n- **Adaptive timestepping** — Richardson extrapolation with PI controller\n- **Neural surrogates** — train MLP/DeepONet/FNO surrogates from simulation data, hot-swap into the graph\n- **Cloud deployment** — provision GPU VMs via SkyPilot, stream rendered viewports via WebRTC\n- **Multi-job** — distribute subgraphs across VMs with ZMQ-based rendezvous coordination\n\n**Package structure:**\n```\nmaddening/\n├── core/                 # Graph manager, node ABC, edge spec, schedule\n│   ├── coupling/         # Iterative coupling, convergence, acceleration, spatial mapping\n│   ├── simulation/       # Adaptive dt, checkpoint, integrators, calibration, profiler\n│   └── compliance/       # Metadata, stability, anomaly tracking, audit, UQ\n├── nodes/                # Built-in nodes (Ball, Table, Spring, Heat, LBM, HeartPump, RigidBody)\n├── surrogates/           # Neural surrogate framework (architectures, training, validation)\n├── cloud/                # Cloud orchestration (SkyPilot, providers, coordinator, streaming)\n│   └── multigpu/         # Device mesh, partitioning, sharded nodes, coordinator\n├── viz/                  # Visualization (renderer ABC, relay, runner, backends)\n├── api/                  # FastAPI server (REST + WebSocket + server-side rendering)\n└── usd/                  # OpenUSD integration (graph serialization, geometry)\n```\n\n## Installation\n\n```bash\npip install maddening                    # CPU (base)\npip install maddening[cuda12]            # GPU with CUDA 12\npip install maddening[cuda12,viz]        # GPU + matplotlib plots\npip install maddening[server,cuda12]     # GPU simulation server\npip install maddening[runpod]            # Cloud deploy to RunPod\n```\n\n| Extra | What it adds |\n|-------|-------------|\n| `cuda12` / `tpu` | GPU / TPU acceleration |\n| `viz` | Matplotlib renderers |\n| `terminal` | Rich terminal renderer |\n| `api` | FastAPI HTTP/WS server |\n| `network` | ZeroMQ remote transport |\n| `surrogates` | Neural surrogate training (equinox + optax) |\n| `runpod` / `lambda` / `aws` / `gcp` | Cloud deploy via SkyPilot |\n| `server` | Bundle: FastAPI + ZMQ + rich + matplotlib |\n| `cloud` | All supported cloud providers |\n| `all` | Everything |\n\nWorks 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.\n\n## Quick Start\n\n```python\nimport jax.numpy as jnp\nfrom maddening import GraphManager, SimulationNode\n\nclass BounceNode(SimulationNode):\n    @property\n    def requires_halo(self) -\u003e bool:\n        return False  # pointwise (no spatial neighbors)\n\n    def initial_state(self):\n        return {\"position\": jnp.array(5.0), \"velocity\": jnp.array(0.0)}\n\n    def update(self, state, boundary_inputs, dt):\n        new_vel = state[\"velocity\"] + -9.81 * dt\n        new_pos = state[\"position\"] + new_vel * dt\n        new_vel = jnp.where(new_pos \u003c 0, jnp.abs(new_vel) * 0.8, new_vel)\n        new_pos = jnp.maximum(new_pos, 0.0)\n        return {\"position\": new_pos, \"velocity\": new_vel}\n\ngm = GraphManager()\ngm.add_node(BounceNode(name=\"ball\", timestep=0.01))\ngm.compile()\nfinal_state, history = gm.run_scan_with_history(n_steps=500)\n```\n\nSee [docs/user_guide/quickstart.md](docs/user_guide/quickstart.md) for the full tutorial.\n\n## Cloud Deployment\n\nPre-built Docker image with JAX CUDA, GStreamer, and all server dependencies:\n\n```bash\npip install maddening[runpod]\n# Set up ~/.maddening/cloud_credentials.yaml (see examples/cloud/config/)\n```\n\n```python\nfrom maddening.cloud.launcher import CloudLauncher\n\nlauncher = CloudLauncher()\njob = launcher.launch(\"job_config.yaml\")  # provisions GPU VM\njob.ssh_run(\"python3 my_simulation.py\")   # run directly on GPU\njob.teardown()\n```\n\nDocker image: `ghcr.io/microrobotics-simulation-framework/maddening-cloud:latest`\n\n## For MIME Developers\n\nMADDENING is designed to be extended by MIME. See:\n- [docs/user_guide/installation.md](docs/user_guide/installation.md) — install options\n- [docs/developer_guide/node_authoring.md](docs/developer_guide/node_authoring.md) — writing custom nodes\n- [DESIGN.md](DESIGN.md) — architecture decisions\n- [CLOUD_ROADMAP.md](CLOUD_ROADMAP.md) — cloud/multi-GPU/multi-job architecture\n- [DOCUMENTATION_ARCHITECTURE.md](DOCUMENTATION_ARCHITECTURE.md) — regulatory compliance structure\n\n## License\n\nLGPL-3.0-or-later. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrorobotics-simulation-framework%2Fmaddening","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrorobotics-simulation-framework%2Fmaddening","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrorobotics-simulation-framework%2Fmaddening/lists"}