Skip to content

The Vivarium Users Guide

Compose living models.

Start here Quick start What is Vivarium? ↓ Download PDF

Vivarium is a framework for building multiscale biological models by composing independently-written simulators into one executable whole — and for turning the runs into auditable scientific evidence. It is built as two spines wired into a single discovery loop:

The computational spine

What runs. Typed Stores hold state; Processes and Steps wired to them carry the dynamics; whole simulations nest as Composites. Updates are deltas merged by the type system.

The agentic spine

What reasons. Each run is a Study inside an Investigation. Studies form a gated DAG; a code-computed evaluator rolls runs up into a verdict, a readiness score, and open epistemic debts.

Neither spine is the engine — the engine is the closed loop between them, and the Workbench is where the loop turns.

The four packages

Each layer imports the ones below it and never the reverse. Click through to any layer.

viva-superpowersthe /viva-* skills The Claude Code skills that author and run everything. All AI lives here, so the tool below stays auditable. vivarium-workbenchthe dashboard server The AI-free server: investigations, studies, runs, analyses, report cards — every change committed to git. process-bigraphthe engine The composite / process / step / template primitives, the tick scheduler, and the emitters that record state. bigraph-schemathe type system The types beneath every store. apply is the one law that merges deltas, so independent processes compose.

A Composite is the runnable object; a Study is the reason you run it; an Investigation is the argument several studies build together.

How it all fits together

Read the map bottom-up and it's a simulation; read it top-down and it's an argument. Every box links to the chapter that covers it.

types read / write wired into emits groups grades computes runs Schematypes every store Storetyped state Process · Stepthe dynamics Compositethe runnable object Emitterrecords the run Investigationthe argument Studythe question Report cardgrades the tests Verdictcomputed, not asserted

Choose a path

New here?

Start with What is Vivarium? for the mental model, then Core concepts for the vocabulary.

Build a model

Go to Processes & Steps and Composites & wiring to write and run your first composite.

Do science

Head to Studies and Investigations to turn runs into gated, verdict-bearing evidence.

Look something up

The Reference section has the skill catalog, HTTP API, schemas, install/deploy, and a full worked example.

See the Start here guide for full step-by-step learning paths.

What a composed model looks like

Three-panel overview: each subsystem in its own best formalism; process bigraphs make coupling explicit as a nested composite; compositions become reusable, testable simulations.
Process Bigraph composes heterogeneous models into executable, reusable multiscale simulations. (a) Each subsystem is modeled in the formalism best suited to it — ODEs, flux-balance analysis, reaction–diffusion PDEs, agent-based models, learned dynamics. (b) Typed process interfaces expose variables and make coupling explicit, connecting models across formalisms and scales. (c) Process Bigraph encodes components, interfaces, and couplings as declarative specifications that execute, analyze, test, and share. (Agmon & Spangler, Fig 1.)

The Vivarium framework is described in Agmon & Spangler, Process bigraphs and the architecture of compositional systems biology (arXiv:2512.23754). Source packages live at github.com/vivarium-collective.