xtremax Design Doc

Extreme value modeling with JAX and NumPyro.

Structure¶

xtremax/
├── design_overview.md          # This file
├── vision.md              # Motivation, user stories, design principles, identity
├── architecture.md        # Layer stack, package layout, dependencies
├── boundaries.md          # Ownership, ecosystem, scope, testing, roadmap
├── api/
│   ├── api_overview.md    # Surface inventory, conventions, notation
│   ├── api_primitives.md  # Layer 0 — pure JAX functions (GEV, GPD, point process, max-stable math)
│   ├── api_components.md  # Layer 1 — NumPyro distributions, xarray utilities, plotting, simulations, datasets
│   └── api_models.md      # Layer 2 — model zoo (stationary/nonstationary/spatial GEV, POT, PP)
├── examples/
│   ├── examples_overview.md    # Index and reading order
│   ├── examples_primitives.md  # Layer 0 — pure JAX functions, return levels, gradients
│   ├── examples_components.md  # Layer 1 — NumPyro distributions, xarray extraction, plotting
│   ├── examples_models.md      # Layer 2 — model zoo workflows (MCMC, SVI)
│   └── examples_integration.md # Layer 3 — geo_toolz, ecosystem composition
└── decisions.md           # Design decisions with rationale

Reading Order¶

Vision — understand the why
Architecture — understand the layer stack
Boundaries and Ecosystem — understand the scope
API Overview — scan the surface
Layer 0 — Primitives → api_components.md → api_models.md — drill into detail
examples/ — see it in action
Design Decisions — understand the tradeoffs