Core concepts¶
This chapter builds the whole framework from first principles. The vocabulary is deliberately small: a handful of structural ideas, then a handful of temporal ones, then the way models compose. Everything later in the guide is an application of what is here.
Where the vocabulary comes from
The formal anchors come from the Process Bigraph paper's core vocabulary (Table 1); the plain-language framing comes from the Composition Interface Protocol primer. Where a term has a legacy synonym, it is noted — the ecosystem is mid-migration and older documents use different words for the same idea.
Structure: stores, edges, and wires¶
A Vivarium model is a bigraph — a structure with two orthogonal parts: a place graph (what contains what) and a link graph (what is wired to what).
Stores — the state¶
A Store holds a typed value: a molecule count, a concentration field, the clock. If
you think of a model as a program, stores are its variables. Stores nest
hierarchically — a cell store contains a cytoplasm store contains a metabolites store —
and that nesting is the place graph. A value's address is the path to it, e.g.
['cell', 'cytoplasm', 'glucose'].
Formally, state is a map from paths to values, x : P ⇀ V, and a schema is a map
from paths to types, Σ : P ⇀ T — "the typed organizational blueprint of the system."
The separation between schema and state is the central principle: it lets you validate a
model, reuse its structure, and reason about composition independently of execution.
Edges — the functionality¶
An Edge is a unit of functionality attached to stores. Each input or output of an edge is a Port. An edge never talks to another edge directly; it reads and writes shared stores, and that shared wiring is the coupling between them.
There are exactly two kinds of edge, and the difference is time (see below): a Process and a Step.
Wires — the coupling¶
A Wire connects a port of an edge to a store by its path, W : (process, port) → P.
Wiring makes every coupling explicit and checkable. Where the place graph says where
things are, wires say how they are connected.
Place graph vs link graph
- Place graph = containment = dict nesting. "Cell contains cytoplasm."
- Link graph = wiring = ports connected to store paths. "Transcription reads the gene store and writes the mRNA store."
Time: processes and steps¶
The Composition Interface Protocol describes structure. What it does not specify is time. Process Bigraph adds a global clock and splits edges by their relationship to it. It helps to keep two things apart: composition is how edges are wired together through shared stores, while orchestration is when each one acts and how its updates combine.
A Process — temporal¶
Declares an interval (a timestep) and an update(state, interval) method that advances
dynamics over a span of time — an ODE integrator, an FBA solve, a stochastic step, a
spatial update. The clock drives it.
A Step — reactive¶
Declares no interval. Its update(state) fires when its inputs are ready — a dataflow
rule run to convergence. Steps form a DAG that settles whenever the state they depend on
changes. Emitters, analyses, visualizations, and report cards are all Steps.
Together, processes and steps let one simulation express both continuous dynamics (processes running at regular intervals) and discrete events (steps firing in response to conditions).
The one semantic that makes it compose¶
Processes never mutate state directly. Each update() returns a typed delta; the
runtime merges it into shared state through the schema's apply method.
A process reads the state it is wired to, computes, and returns a change — it does not write anything itself. The runtime collects every process's delta and applies it through the type's own combination rule:
- Accumulate — numeric types add (two processes both consuming glucose subtract their amounts; the pool ends up correct).
- Set — replace the value.
- Merge — dict update.
Because how deltas combine is a property of the data type, not the process, two independently-written processes can write to the same store without knowing about each other. Numerical updates, structural rewrites, and scheduling therefore all live under one execution protocol.
Types and the type system¶
A type knows how to do a few things: produce a default value, serialize and
deserialize, check whether a value is valid, and — crucially — apply a delta. These
behaviors live in bigraph-schema. Types compose (a map[string, float], an
array[(3|4), float], a tree[float]), carry units, and can declare inheritance. A
composite's wiring is therefore checkable, not ad hoc: the type system knows whether two
ports can legally connect.
The operational object is a Core — a registry of types (and of process classes) that the engine consults. You will meet it directly in Schemas, types & state.
Accuracy note
bigraph-schema was rewritten (the Core API landed in the v1.4 line; the package is
now at v1.8.x). If you find older tutorials referring to a
TypeSystem class or dict-keyed _apply/_serialize methods, that API is gone — the
current object is Core, built via allocate_core(), with type behaviors dispatched
as methods. The concepts above are stable; verify code against the current package.
Composition: the composite¶
A Composite is a state-tree of typed process and step nodes wired to shared stores. It is the only object the engine actually runs. Everything higher up in the framework merely points at a composite and records what came out.
A composite is a document: state + processes + the port wiring between them.
Crucially, a composite is itself a Process — it owns an internal state-tree and scheduler and exposes a bridge that maps its external ports onto internal store paths. So a composite drops into a parent composite as a single node. This is how multiscale models are built: big models are assembled from small ones. Nesting a ready-to-run composite inside a parent and filling a template's open site are two faces of one move — a nested sub-composite can be both at once — so composition and hole-filling are the same mechanism, not rivals.
And because the pieces take on their biological meaning from how they are composed, the same processes wired into different patterns — cell–environment coupling, growth, division — give rise to different biology.
flowchart TB
subgraph Composite["Composite (a Process via its bridge)"]
direction LR
P1["Process: transcription"] -->|writes mRNA| S1[("Store: mRNA")]
S2[("Store: gene")] -->|reads| P1
P2["Process: translation"] -->|writes protein| S3[("Store: protein")]
S1 -->|reads| P2
E["Step: emitter"] -.->|records| S3
end
From documents to templates: sites, fill, and ground¶
A composite you can run is ground — every required slot is filled. A composite with a hole in it is a template.
- A site is a place-graph hole: a slot where a whole composite, process, or value plugs in. (This is Milner's bigraph site.) A composite refuses to run while any required site is open — "a hole is where a process should be."
- The one operation on documents is fill: substitute a value or a sub-composite into a site.
- The one law is groundness (
is_ground): a document runs iff it has no unfilled required sites.
This collapses a lot of apparent machinery into one idea: one object (a typed document),
one operation (fill its sites), one law (is_ground). A composite, a template, a
study, and an investigation are all the same kind of thing — they differ in structure, not
in execution machinery.
Legacy vocabulary
Older design documents call sites slots, and call filling them bind or reify. Prefer site / fill / ground; treat slot / bind / reify as synonyms when you meet them.
Process contracts¶
An edge's interface can be made explicit as a process contract (contract.face): a
typed declaration of its input and output ports, each carrying a _type and, where it
applies, _units, _min, and _max. A contract is a mathematically-legible superset of
the older describe() / ports convention — it states not just which ports exist but the
type, units, and bounds each one obeys, so the wiring between two edges can be checked
against the physics, not just the names. A draft process (below) is one application of a
contract: an interface declared ahead of its mechanism.
Draft processes¶
A draft process is a template idea applied to a single process. A DraftProcess
declares a contract — its input and output ports plus a human-readable description of
the transformation it is meant to perform — but carries no dynamics. Stepped, it
stays inert and never fabricates behavior; it appears in the dashboard marked
DRAFT. This lets you design an interface first and supply
the mechanism later.
DraftProcess is deprecated — prefer a hole in place
DraftProcess / @draft_process still work but now emit a
DraftProcessDeprecationWarning. The current way to declare an interface ahead of its
mechanism is a hole: an open site whose sort is a ProcessContract
(bigraph_schema.contract). draft_to_contract() (from process_bigraph) migrates an
existing draft to one. The interface-first idea is unchanged — only the primitive.
See Templates & draft processes.
The knowledge concepts¶
Above the composite sit the concepts of the agentic spine. They are all metadata that references a composite by a dotted id and records what came out — none of them is the thing that runs.
| Concept | One-line definition |
|---|---|
| Composite | The runnable object — the only thing the engine executes. |
| Study | The reason you run it: one question, one emit-contract, one pass/fail bar wrapped around a composite. |
| Investigation | The argument several studies build together: a gated DAG under one research question. |
| Run | One execution of a composite; produces a run store of trajectories. |
| Emitter | A Step that records wired state each tick into a durable sink. |
| Analysis / Visualization | Steps that read a run's normalized results and write artifacts (figures, tables). |
| Behavior test | A machine-checkable spec: how to measure a result and what passing means. |
| Report card | A Step that reads a run and produces pass/fail outcomes keyed by test — the raw evidence. |
| Acceptance band | The tolerance or direction a test accepts (e.g. "within 2%"), ideally cited to literature. |
| Finding | A summary of what was seen, floored by a lifecycle so an unproven claim can't look settled. |
| Verdict | The study's computed gate state — one of blocked · needs_calibration · passed · failed · stale (distinct from the free-form report.verdict narrative). |
| Provenance | Every write is a git commit; verdict, readiness, and debts are diff-able. |
The sentence to remember
A Composite is the runnable object; a Study is the reason you run it; an Investigation is the argument several studies build together.
Baselines, variants, and the workspace¶
A study names the composites it runs by role:
- A Baseline is a study's runnable composite(s) — the reference configuration the question is asked against.
- A Variant is a baseline plus a set of parameter overrides — the same wiring, perturbed, so a study can compare conditions against its baseline.
All of this lives in a Workspace: the git repository that is the model. Its typed documents — composites, studies, investigations — and their commit history are the versioned substrate the Workbench serves and every write lands in.
Each of these gets a full chapter in Investigate.
Next: The stack — how the four packages layer and depend on each other.