maddening 0.1.0__tar.gz

maddening-0.1.0/.claude/skills/commit-and-push/SKILL.md

@@ -0,0 +1,158 @@
+# Commit and Push Compliance Skill
+
+This skill enforces MADDENING's documentation architecture requirements on every commit and push. Run it before pushing to ensure all regulatory and documentation standards are met.
+
+## Trigger
+
+When the user asks to commit and push, or invokes `/commit-and-push`.
+
+## Pre-Commit Checklist
+
+Work through the following checklist systematically. Each section has a **gate** — if the gate fails, stop and fix before proceeding.
+
+### 1. Tests Pass
+
+Run the full test suite:
+
+```bash
+source ../venvs/.maddening/bin/activate
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest tests/ -v --tb=short --ignore=tests/viz
+```
+
+**Gate**: All tests must pass. If any fail, fix them before continuing.
+
+### 2. Compliance CI Scripts Pass
+
+Run all three compliance validation scripts:
+
+```bash
+python scripts/check_anomalies.py
+python scripts/check_impl_mapping.py
+python scripts/check_citations.py
+python scripts/check_transforms.py
+```
+
+**Gate**: All four must exit 0. Fix any errors before continuing.
+
+### 3. Commit Message Convention
+
+Use the correct prefix based on the nature of the change:
+
+| Prefix | When to use |
+|--------|-------------|
+| `feat:` | New feature or capability |
+| `fix:` | Bug fix |
+| `refactor:` | Code restructuring (no behavior change) |
+| `docs:` | Documentation-only changes |
+| `test:` | Test additions or changes |
+| `perf:` | Performance improvement |
+| `verify:` | Verification/validation evidence |
+| `break:` | Breaking API change |
+| `deprecate:` | Deprecation notice |
+| `security:` | Security-relevant change |
+
+The commit message body should be concise (1-2 sentences) and focus on **why** the change was made, not what was changed (the diff shows what).
+
+### 4. CHANGELOG.md Updated
+
+Check if the changes affect user-visible functionality. If yes, update `CHANGELOG.md` under `## [Unreleased]` in the appropriate section:
+
+- **Added** — new features, new nodes, new capabilities
+- **Changed** — changes to existing features or behavior
+- **Deprecated** — features marked for future removal
+- **Removed** — features removed in this change
+- **Fixed** — bug fixes
+- **Verification** — changes to V&V status, new benchmarks, benchmark results changes
+- **Security** — security-relevant changes (required by MDCG 2019-16)
+- **Known Anomalies** — changes to `known_anomalies.yaml` (required for IEC 62304 SOUP)
+
+**When to skip**: Pure internal refactors, CI config changes, and developer tooling changes that don't affect the package's external behavior don't need changelog entries.
+
+### 5. New Node Checks (if applicable)
+
+If the commit adds or modifies a `SimulationNode` subclass, verify:
+
+- [ ] `meta` ClassVar has `NodeMeta` with: `algorithm_id`, `stability`, `description`, `assumptions`, `limitations`, `hazard_hints`
+- [ ] `@stability(StabilityLevel.X)` decorator applied
+- [ ] NumPy-style docstring present
+- [ ] `update()` is JAX-traceable (uses `jnp` ops, no Python side effects)
+- [ ] Algorithm guide in `docs/algorithm_guide/nodes/` follows `_template.md`
+- [ ] Implementation Mapping table traces all equation terms to code
+- [ ] Unit tests in `tests/nodes/`
+- [ ] At least one `@verification_benchmark` in `tests/verification/`
+
+### 6. New Anomaly Checks (if applicable)
+
+If the commit introduces or discovers a known limitation:
+
+- [ ] Entry added to `docs/validation/known_anomalies.yaml` with all required fields
+- [ ] `anomaly_id` uses `MADD-ANO-XXX` format
+- [ ] `safety_relevance_rationale` is filled in (not empty)
+- [ ] Changelog updated under `### Known Anomalies`
+- [ ] `python scripts/check_anomalies.py` passes
+
+### 7. Bibliography/Citation Checks (if applicable)
+
+If the commit modifies algorithm guide documents:
+
+- [ ] All `[@Key]` citations have matching entries in `docs/bibliography.bib`
+- [ ] YAML frontmatter includes `bibliography: ../../bibliography.bib`
+- [ ] References section has human-readable inline descriptions alongside `[@Key]`
+- [ ] `python scripts/check_citations.py` passes
+
+### 8. Implementation Mapping Checks (if applicable)
+
+If the commit renames or moves any function referenced in an algorithm guide's Implementation Mapping table:
+
+- [ ] Algorithm guide updated with new qualified name
+- [ ] `python scripts/check_impl_mapping.py` passes
+
+### 8b. Transform Registry Checks (if applicable)
+
+If the commit adds or modifies edge transforms used in production examples or scenarios:
+
+- [ ] Transforms registered via `@register_transform` from `maddening.core.transforms`
+- [ ] String transform references in production code resolve in the registry
+- [ ] `python scripts/check_transforms.py` passes
+
+### 9. API Stability Checks (if applicable)
+
+If the commit changes a public API surface:
+
+- [ ] `@stability` decorator level is appropriate
+- [ ] If `STABLE`: change is backward-compatible (or this is a major version bump)
+- [ ] If `PROVISIONAL`: deprecation warning added for the old API
+- [ ] If removing a `DEPRECATED` API: verify it's a major version bump
+
+## Execution Steps
+
+After all checks pass:
+
+1. **Stage files**: Add specific files (avoid `git add -A` to prevent accidentally staging secrets or large files)
+2. **Commit**: Use the appropriate prefix and a concise message
+3. **Push**: Push to the remote
+
+```bash
+git add <specific files>
+git commit -m "prefix: concise description of why
+
+Longer explanation if needed.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+git push
+```
+
+4. **Verify CI**: After pushing, note that CI will run tests on Python 3.10/3.11/3.12 and the compliance job. If CI fails, fix and push again.
+
+## Quick Reference: What Goes Where
+
+| Change Type | CHANGELOG | Anomaly YAML | Algorithm Guide | Bibliography |
+|-------------|-----------|-------------|-----------------|--------------|
+| New node | Added | If limitations | Yes (new doc) | If citing papers |
+| Bug fix | Fixed | If it was a known anomaly | Update if affects equations | No |
+| New limitation discovered | Known Anomalies | Yes (new entry) | Update Known Limitations | No |
+| Renamed function | No | No | Update Impl Mapping | No |
+| New verification benchmark | Verification | No | Update Verification Evidence | If citing reference |
+| Documentation only | No (unless user-facing) | No | If algorithm guide | If adding citations |
+| Security fix | Security | If safety-relevant | No | No |
+| Deprecation | Deprecated | No | No | No |

maddening-0.1.0/.github/ISSUE_TEMPLATE/anomaly.md

@@ -0,0 +1,67 @@
+---
+name: Anomaly Report
+about: Report a known anomaly (incorrect results, numerical instability, unexpected behavior)
+title: "[ANOMALY] "
+labels: known-anomaly
+---
+
+## Severity
+
+<!-- Select one: critical / major / minor -->
+
+**Severity**:
+
+## Safety Relevance
+
+<!-- Select one: safety_relevant / not_safety_relevant / context_dependent -->
+
+**Safety relevance**:
+
+## Safety Relevance Rationale
+
+<!-- Explain why this is or is not safety-relevant. If context_dependent, explain what contexts would make it safety-relevant. -->
+
+
+
+## Description
+
+<!-- Precise technical description of the anomaly. -->
+
+
+
+## Affected Components
+
+<!-- Which MADDENING modules/nodes are affected? -->
+
+-
+
+## Affected Versions
+
+<!-- Which MADDENING versions exhibit this anomaly? -->
+
+
+
+## Steps to Reproduce
+
+<!-- Minimal code or steps to reproduce the anomaly. -->
+
+```python
+
+```
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+
+
+## Actual Behavior
+
+<!-- What actually happens? -->
+
+
+
+## Workaround
+
+<!-- Is there a workaround? If so, describe it. If not, state "None known." -->
+

maddening-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Pin JAX to known-good version to avoid jaxlib segfaults
+          pip install "jax==0.5.1" "jaxlib==0.5.1"
+          pip install -e ".[ci]"
+
+      - name: Run tests
+        env:
+          JAX_PLATFORMS: cpu
+          XLA_FLAGS: "--xla_gpu_autotune_level=0"
+          PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
+        run: |
+          python -m pytest tests/ -v --tb=short --ignore=tests/viz
+
+  test-usd:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies (with USD)
+        run: |
+          python -m pip install --upgrade pip
+          pip install "jax==0.5.1" "jaxlib==0.5.1"
+          pip install -e ".[ci,usd]"
+
+      - name: Run USD tests
+        env:
+          JAX_PLATFORMS: cpu
+          PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
+        run: |
+          python -m pytest tests/usd/ -v --tb=short
+
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "jax==0.5.1" "jaxlib==0.5.1"
+          pip install -e ".[ci]"
+
+      - name: Validate anomaly registry
+        run: python scripts/check_anomalies.py
+
+      - name: Check implementation mapping
+        run: python scripts/check_impl_mapping.py
+
+      - name: Check bibliography citations
+        run: python scripts/check_citations.py
+
+      - name: Check transform registry
+        run: python scripts/check_transforms.py
+
+      - name: Run compliance tests
+        env:
+          JAX_PLATFORMS: cpu
+          PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
+        run: |
+          python -m pytest tests/compliance/ tests/verification/ -v --tb=short 

maddening-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+# Publishes `maddening` to PyPI on every GitHub Release whose tag starts
+# with `v` (e.g. v0.1.0). Uses PyPI Trusted Publishing (OIDC) — no API
+# token is stored in the repo; the publisher is configured at
+# https://pypi.org/manage/account/publishing/ with:
+#   project       : maddening
+#   owner         : Microrobotics-Simulation-Framework
+#   repository    : MADDENING
+#   workflow      : publish.yml
+#   environment   : pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write   # required for Trusted Publishing OIDC
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: python -m pip install --upgrade pip build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Sanity-check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

maddening-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.claude/*
+!.claude/skills/
+*.png
+*.npz
+.venv/
+*.jsonl
+
+# For throwaway / convenience files that shouldn't be pushed
+tmp/
+
+# Cloud credentials — NEVER commit
+src/maddening/examples/cloud/config/cloud_credentials.yaml
+src/maddening/examples/cloud/config/.env

maddening-0.1.0/.skyignore

@@ -0,0 +1,14 @@
+# SkyPilot workdir sync exclusions
+# Only sync source code + config, not venvs/caches/artifacts
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.git/
+.claude/
+tmp/
+*.npz
+*.png
+*.jsonl

maddening-0.1.0/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to MADDENING will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Additional sections per release: **Verification**, **Security**, and **Known Anomalies**.
+
+## [Unreleased]
+
+### Added
+- Coupling convergence infrastructure: per-field mixed atol/rtol norm (`convergence_norm="mixed"`), convergence diagnostics (`diagnostics=True`), Aitken delta-squared acceleration (`acceleration="aitken"`), fixed under-relaxation (`acceleration="fixed"`), and Jacobi iteration mode (`iteration_mode="jacobi"`)
+- `coupling_acceleration` module with standalone JAX-traceable residual norms, state flatten/unflatten, and acceleration functions
+- `GraphManager.coupling_diagnostics()` method for retrieving iteration counts and final residuals
+- IQN-ILS quasi-Newton coupling acceleration (`acceleration="iqn-ils"`) with Aitken fallback, pre-allocated matrices for fori_loop compatibility, and automatic column management
+- Subcycling within coupling groups (`subcycling=True`) for mixed-timestep coupling with linear/constant boundary interpolation
+- Spatial interpolation map factories in `interface_mapping` module: `nearest_neighbor_1d`, `linear_interpolation_1d`, `rbf_interpolation` (4 kernels), `conservative_projection_1d`
+- `auto_couple()` and `add_coupling_group()` accept `**kwargs` forwarded to `CouplingGroup`
+- Coupling examples: acceleration comparison, Jacobi vs Gauss-Seidel, subcycling, spatial interpolation, convergence diagnostics
+- IQN-ILS/IMVJ auto interface-field detection: `flatten_coupled_state` accepts `fields` parameter to accelerate only coupling-edge fields, reducing V/W matrix size for nodes with many internal DOFs
+- IQN-IMVJ multi-timestep Jacobian reuse (`acceleration="iqn-imvj"`, `jacobian_reuse=N`): warm-starts V/W from previous timestep for faster convergence
+- Interface residual convergence norm (`convergence_norm="interface"`): checks coupling-edge values between iterations instead of full state change
+- Quadratic subcycling boundary interpolation (`boundary_interpolation="quadratic"`): Lagrange interpolation through three successive iteration values
+- Waveform relaxation for subcycled groups (`waveform_iterations=N`): repeats coupling block to improve boundary data quality
+- Flux-based coupling: `SimulationNode.compute_boundary_fluxes()` exposes derived quantities (heat flux, spring force) consumable via edges; `SimulationNode.boundary_input_spec()` declares expected inputs with `BoundaryInputSpec` descriptors
+- `EdgeSpec.additive` flag: edges with `additive=True` accumulate values instead of overwriting, enabling multi-source force/flux coupling
+- `coupling_helpers` module: `add_value_coupling`, `add_flux_coupling`, `add_dirichlet_neumann_pair`, `add_symmetric_value_coupling`, `add_robin_coupling`, `check_conservation`
+- `BoundaryInputSpec` dataclass and `boundary_input_spec()` on HeatNode, SpringDamperNode, BallNode, RigidBody2DNode
+- `compute_boundary_fluxes()` on HeatNode (left/right heat flux) and SpringDamperNode (spring force)
+- Flux coupling demo and node authoring guide sections on flux coupling patterns
+- `TransformRegistry` with `@register_transform` decorator for named, serializable edge transforms; built-in transforms (`extract_first`, `extract_last`, `negate`, `scale`, `identity`); `GraphManager.add_edge` accepts string transform names
+- `scripts/check_transforms.py` CI validation script for string transform references
+- Gradient health audit: verified `jax.grad` finite through 1000-step coupled rollouts for springs, heat rods, and multi-physics systems
+- Parameter recovery baseline: gradient-based recovery of spring stiffness and damping from trajectory data (inline physics, proving differentiability concept)
+- Interface DOF awareness: `interface_dof_indices()` and `compute_interface_correction()` on SimulationNode; coupling system re-applies interface values after node update, fixing the DD coupling "cold lock" where HeatNode's Dirichlet BC enforcement prevented heat transfer
+- Coupling iteration predictors (`predictor="linear"` or `"quadratic"` on CouplingGroup): extrapolates initial guess from previous timesteps' converged states, reducing iteration count
+- `tune_coupling_params()` utility for grid-search optimization of coupling parameters (tolerance, max_iterations, acceleration)
+- `HybridNode` wrapper: composes a physics node with an additive correction function; `generate_correction_data()` for training integration error correctors
+- `derivatives()` method on SimulationNode with implementations on BallNode, SpringDamperNode, HeatNode; `integrators` module with `euler_step`, `heun_step`, `rk4_step` and convenience `integrate_node()`
+- `calibrate()` utility for gradient-based parameter recovery from reference trajectories using `jax.grad`
+- Implicit node support: `implicit_residual()` on SimulationNode with fixed-count Newton iteration via `jax.lax.fori_loop`; implemented for SpringDamperNode and HeatNode; unconditionally stable for stiff problems
+- OpenUSD integration: codeless schemas (`MaddeningSimulationGraph`, `MaddeningNode`, `MaddeningEdge`, `MaddeningCouplingGroup`, `MaddeningExternalInput`), `USDWriter` for time-sampled state output, `save_graph_to_usd()` / `load_graph_from_usd()` for full graph serialization, late-registration guard with RuntimeError
+- HeatNode 4th-order FD stencil (`stencil_order=4`), non-uniform grid support (`grid_points` parameter)
+- 2D spatial interpolation: `nearest_neighbor_2d()`, `rbf_interpolation_2d()` in interface_mapping
+- USD geometry reader: `load_grid_from_usd()`, `create_vessel_phantom()` (Y-shaped bifurcating vessel)
+- `geometry_source` attribute on SimulationNode for USD-initialized nodes
+- Vessel bifurcation coupling example: three HeatNodes initialized from USD geometry, coupled at Y-junction
+- `HistoryViewer3D.add_curve_tube()`: render 3D centerline tubes colored by scalar fields (vessels, pipes, rods)
+- `HistoryViewer3D.add_line_plot()`: render 1D fields as 3D line plots (temperature profiles, wave solutions)
+- `viewer_from_usd()`, `viewer_from_usd_with_geometry()`, `render_usd_frame()`: bridge USD results data to the general-purpose HistoryViewer3D for interactive replay and screenshots
+- USD tests skip gracefully when `usd-core` is not installed (CI compatibility for Python 3.10/3.11)
+- `LBMNode`: general 3D Lattice Boltzmann on boolean mask domains with D3Q19/D2Q9 lattices, Zou-He pressure BCs, Guo forcing, runtime clot injection via `wall_mask_update`
+- `lbm_geometry.voxelize_vessel()`: analytical Y-bifurcation voxelizer parametric by vessel geometry
+- `RigidBodyNode`: full 6DOF rigid body (quaternion orientation, diagonal inertia, DOF constraints). `RigidBody2DNode` deprecated with thin wrapper.
+- `HeartPumpNode`: 2-element Windkessel model with pulsatile cardiac output, configurable heart rate / stroke volume / resistance / compliance, bidirectional pressure coupling
+- `PyVistaLiveRenderer`: real-time 3D visualization backend with timer callbacks, pause/resume/speed keyboard controls
+- Vessel bifurcation live example: real-time simulation + USD recording + PyVista visualization + heat pulse injection demo
+- Vessel flow server: FastAPI server with HeartPump+LBM coupling, REST endpoints for heart rate / resistance / clot injection, WebSocket live vitals streaming, browser UI with pressure waveform chart
+
+- Cloud module (`maddening.cloud`): `StreamingSession` ABC and `StreamConfig`/`StreamInfo`/`QualityPreset`/`GPUFramebuffer` data types for WebRTC viewport streaming; `MockStreamSession` for zero-dep testing; HMAC-SHA256 session token auth; `SelkiesSession` GStreamer/WebRTC implementation (requires PyGObject)
+- `CloudSession` state machine with SkyPilot VM orchestration, typed health probes (`HealthProbeError` with stage attribution), `CloudReadyResult` with per-stage pass/fail, `MockCloudSession` for testing; preemption detection with configurable policy (CHECKPOINT/FAILOVER/ABORT)
+- `SelkiesRenderer(Renderer)`: wraps inner renderer + `StreamingSession`, auto-detects GPU/CPU framebuffer path, emits `PerformanceWarning` on CPU fallback
+- Multi-GPU Jacobi coupling: `create_device_mesh()`, `assign_nodes_to_devices()` with coupling co-location, `build_sharded_jacobi_pass()` for distributed node updates; `GraphManager.enable_multigpu()` method
+- Cloud container: `docker/Dockerfile.cloud` (CUDA + GStreamer + MADDENING), `entrypoint.py` with JSON config deserialization
+- Cloud API endpoints on `SimulationServer`: `POST /cloud/launch`, `GET /cloud/status`, `POST /cloud/teardown` (unconditionally registered, returns 501 if unconfigured)
+- `CloudLauncher`: user-facing cloud job orchestration with `CloudJob` handle, `JobConfig` YAML loading, `CostPolicy` cost guards, credential context manager with cleanup, and `CloudJob.from_cluster_name()` reconnect
+- `CloudProvider` ABC with `RunPodProvider` and `LambdaLabsProvider` (stub); per-provider credential file management with write/delete lifecycle
+- Cloud examples consolidated under `src/maddening/examples/cloud/`: `01_validate.py` (dry-run), `02_runpod_launch.py` (real launch), config templates
+- Restructured package extras: per-provider cloud (`runpod`, `lambda`, `aws`, `gcp`), hardware acceleration (`cuda12`, `tpu`), task bundles (`server`, `client`), combo (`cloud`, `cloud-all`)
+- Consistent import guards across all optional dependencies: missing extras now raise `ImportError` with the exact `pip install maddening[extra]` command
+- User guide: `docs/user_guide/installation.md` (full install reference), `docs/user_guide/quickstart.md` (5-minute intro)
+- `CostPolicy.spot_fallback`: when spot instances are unavailable, auto-retry on-demand (subject to same cost guards); configurable via job config YAML
+- `retry_until_up` on all SkyPilot launches to handle transient SSH/provisioning failures
+- Concise error message for spot unavailability (truncates verbose per-region table); other errors preserved in full
+- Multi-GPU Phase 1: `enable_multigpu()` wired into `_build_step_fn()` — Jacobi coupling uses `jax.device_put` for per-node device placement; correctness validated (single step, 100 steps, `lax.scan` all match non-sharded)
+- Multi-job architecture: `Coordinator` (ZMQ ROUTER-based rendezvous with registration, topology broadcast, heartbeat monitoring), `CloudGroup` (provision rank-0 first, inject `COORDINATOR_ADDR` into workers, `teardown_all` / `teardown_one` with `ISOLATE` mode), `SubgraphSpec` + `GroupConfig`
+- Cloud examples organized into subdirectories: `config/`, `launch/`, `server/`, `streaming/`, `multigpu/`, `multijob/`
+- `requires_halo` abstract property on `SimulationNode` — every node must declare whether it needs halo exchange for sharding
+- `ShardedNode` wrapper for data-parallel distribution of pointwise nodes across device meshes; rejects stencil nodes automatically
+- `WorkerClient` for multi-job rendezvous: `register_and_wait()`, heartbeat, shutdown/peer_dead callbacks
+- Validated 2-VM multi-job rendezvous on RunPod (coordinator + worker across VMs via ZMQ)
+- Real multi-GPU benchmark on 2xRTX4090: correctness validated, JIT fusion behaviour documented
+- Core reorganized into `core/coupling/`, `core/simulation/`, `core/compliance/` subpackages (backward compatible via `core/__init__.py` re-exports)
+- Docker image `ghcr.io/microrobotics-simulation-framework/maddening-cloud:latest` — pre-built with JAX CUDA, GStreamer, ZMQ, FastAPI; set as default `container_image` in `JobConfig`
+- CycloneDX SBOM generation (`sbom.json`) for IEC 62304 SOUP compliance
+
+### Fixed
+- Subcycling dividers were inverted: fast nodes now correctly take multiple sub-steps while slow nodes take one step
+- Coupling diagnostics were lost in multi-rate graphs when step counter overwrote `_meta`
+- `maddening.compliance` namespace with schema types, anomaly validator, and CLI
+- `NodeMeta` dataclass with `hazard_hints`, `validated_regimes`, `implementation_map` fields
+- `StabilityLevel` and `UQReadiness` enums
+- `@verification_benchmark` decorator and `ValidationBenchmark` registry
+- `@stability` decorator (identity decorator; functional machinery in Phase 4)
+- `HealthCheckNode` for execution-layer fault detection
+- `NodeMeta` attached to all existing nodes (BallNode, TableNode, SpringDamperNode, RigidBody2DNode, HeatNode, LBMPipeNode)
+- `AuditLogger` with `NullSink` and `JSONFileSink`
+- `SimulationProvenance` for reproducibility tracking
+- `UncertaintySpec` and `UncertainParameter` for UQ interface
+- Regulatory documentation: `intended_use.md`, `downstream_integration.md`, `iec62304_mapping.md`, `eu_mdr_guidelines.md`, `mdcg_2019_11.md`
+- `known_anomalies.yaml` with MADD-ANO-001 and MADD-ANO-002
+- `soup_package.md` (skeleton)
+- `SECURITY.md`, `CONTRIBUTING.md`, `CITATION.cff`
+- Algorithm guide template and HeatNode algorithm guide
+- `scripts/check_anomalies.py`, `scripts/check_impl_mapping.py`, and `scripts/check_citations.py`
+- GitHub issue template for anomalies
+- Developer guide: `docs/developer_guide/` with `node_authoring.md`, `documentation_standards.md`, `testing_standards.md`
+- Bibliography citation system: Pandoc-style `[@Key]` syntax with CI validation
+- Claude skill `.claude/skills/commit-and-push/` for commit/push compliance checklist
+- Migrated to `src/` layout with hatchling build backend
+- Reorganized tests into subdirectories: `core/`, `nodes/`, `surrogates/`, `api/`, `viz/`, `compliance/`, `verification/`
+
+### Changed
+- Build backend: setuptools → hatchling
+- Package layout: flat → src/
+- `pyproject.toml` URLs updated to Microrobotics-Simulation-Framework org
+
+### Verification
+- 512+ existing tests pass after restructure
+- New compliance test suite validates all Phase 0-4 artifacts
+
+### Security
+- No security-relevant changes in this release
+
+### Known Anomalies
+- MADD-ANO-001: LBM GPU segfault on CUDA 12.2 + jaxlib 0.5.1 (open, context_dependent)
+- MADD-ANO-002: HeatNode CFL stability not enforced at runtime (open, context_dependent)
+
+## [0.1.0] - 2025-03-01
+
+### Added
+- Initial release: modular simulation framework with functional state pattern
+- Core: GraphManager, SimulationNode ABC, EdgeSpec, scheduling, coupling, adaptive timestepping, parameter sweeps, checkpoint/restore
+- Nodes: BallNode, TableNode, SpringDamperNode, RigidBody2DNode, HeatNode, LBMPipeNode
+- Surrogate framework: SurrogateArchitecture ABC, SurrogateNode, SurrogateTrainer, DatasetGenerator, architectures (MLP, DeepONet, SDeepONet, FNO)
+- Visualization: matplotlib, terminal, PyVista, pygfx backends; ZMQ network transport
+- API: FastAPI server with REST, WebSocket (JSON + binary), server-side rendering
+- 545+ tests

maddening-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+title: "MADDENING: Modular Automatic Differentiation and Data-Enhanced Neural-network INteracting Graph"
+type: software
+version: 0.1.0
+date-released: "2025-03-01"
+license: LGPL-3.0-or-later
+repository-code: "https://github.com/Microrobotics-Simulation-Framework/MADDENING"
+abstract: >
+  A JAX-based modular simulation framework for multi-physics.
+  MADDENING provides a functional-state graph architecture for
+  composing, coupling, and differentiating physics simulations
+  with automatic differentiation and neural surrogates.
+authors:
+  - family-names: Roy
+    given-names: Nicholas Ehsan
+keywords:
+  - simulation
+  - multi-physics
+  - JAX
+  - automatic differentiation
+  - lattice Boltzmann
+  - neural surrogates
+  - microrobotics