Installation#

Base Install#

MADDENING requires Python 3.10+ and installs with CPU-based JAX by default:

pip install maddening

This gives you the full simulation engine (JAX + NumPy) running on CPU. All core features work: graph construction, compilation, stepping, coupling, adaptive timestepping, parameter sweeps, and checkpoint/restore.

GPU Acceleration#

For GPU acceleration, add the hardware extra matching your CUDA version:

# CUDA 12 (most common)
pip install maddening[cuda12]

# TPU (Google Cloud)
pip install maddening[tpu]

You can combine hardware extras with any other extra:

pip install maddening[cuda12,viz]         # GPU + matplotlib plots
pip install maddening[cuda12,server]      # GPU + FastAPI server
pip install maddening[cuda12,runpod]      # GPU + RunPod cloud deploy

Note: The cuda12 extra upgrades the base JAX installation to the CUDA 12 variant. You must have CUDA 12 drivers installed on your system. Check with nvidia-smi.

Feature Extras#

Install only what you need. Each extra adds one capability:

Extra	What it adds	Install command
`viz`	Matplotlib 2D renderers	`pip install maddening[viz]`
`terminal`	Rich terminal renderer (works over SSH)	`pip install maddening[terminal]`
`network`	ZeroMQ remote transport	`pip install maddening[network]`
`api`	FastAPI HTTP/WebSocket server	`pip install maddening[api]`
`surrogates`	Neural surrogate training (equinox + optax)	`pip install maddening[surrogates]`
`viz3d`	PyVista 3D server-side rendering	`pip install maddening[viz3d]`
`gpu-viz`	pygfx GPU-accelerated 3D viewer	`pip install maddening[gpu-viz]`
`usd`	OpenUSD graph serialization	`pip install maddening[usd]`
`streaming`	GStreamer WebRTC streaming	`pip install maddening[streaming]`

Mix and match freely:

pip install maddening[viz,surrogates]           # plots + neural surrogates
pip install maddening[cuda12,api,network]       # GPU server with ZMQ

Cloud Deployment#

Deploy simulations to cloud GPU providers via SkyPilot. Each provider has its own extra that bundles SkyPilot with the provider’s SDK:

Extra	Provider	Install command
`runpod`	RunPod	`pip install maddening[runpod]`
`lambda`	Lambda Labs	`pip install maddening[lambda]`
`aws`	Amazon Web Services	`pip install maddening[aws]`
`gcp`	Google Cloud Platform	`pip install maddening[gcp]`
`cloud`	All supported providers (RunPod + Lambda)	`pip install maddening[cloud]`
`cloud-all`	Every SkyPilot provider	`pip install maddening[cloud-all]`

After installing, set up your credentials file:

mkdir -p ~/.maddening
cp src/maddening/examples/cloud/cloud_credentials.example.yaml ~/.maddening/cloud_credentials.yaml
# Edit ~/.maddening/cloud_credentials.yaml and fill in your API key(s)
# ~/.maddening/cloud_credentials.yaml is the default path. For a different location, use:
# CloudLauncher(credentials_path='path/to/cloud_credentials.yaml')

The credentials file holds keys for all providers in one place:

runpod:
  api_key: "rp_xxxxxxxxxxxx"

lambda_labs:
  api_key: "llxxxxxxxxxxxxxxxxxx"

CloudLauncher reads only the block matching the provider: field in your job config. See src/maddening/examples/cloud/ for complete examples.

Task Bundles#

For common workflows, use a task bundle instead of listing individual extras:

Bundle	What it includes	Use case
`server`	FastAPI + uvicorn + websockets + ZMQ + rich + matplotlib	Running a simulation server (Docker image, GPU workstation)
`client`	ZMQ + rich	Thin client viewing a remote simulation

# Cloud GPU Docker image
pip install maddening[server,cuda12]

# Thin client on your laptop
pip install maddening[client,viz]

Everything#

pip install maddening[all]       # all features + supported cloud providers
pip install maddening[dev]       # all + pytest (for development)

Using uv#

All install commands work identically with uv:

uv pip install maddening[cuda12,runpod]
uv add maddening[server]

Verifying Your Installation#

import maddening
import jax

# Check JAX backend
print(f"JAX backend: {jax.devices()[0].platform}")  # 'cpu', 'gpu', or 'tpu'

# Check available features
try:
    from maddening.viz.backends import MatplotlibRenderer
    print("matplotlib: available")
except ImportError:
    print("matplotlib: not installed (pip install maddening[viz])")

try:
    from maddening.cloud import CloudLauncher
    print("cloud: available")
except ImportError:
    print("cloud: not installed (pip install maddening[runpod])")

Missing Dependency Errors#

MADDENING uses lazy imports — optional features only fail when you try to use them, not at import time. When a dependency is missing, you’ll see a clear error with the exact install command:

ImportError: 'SurrogateTrainer' requires equinox and/or optax.
Install with:  pip install maddening[surrogates]

ImportError: TerminalRenderer requires 'rich'.
Install with:  pip install maddening[terminal]

Follow the suggested command to install the missing extra.