Compose Subsystem Overview¶

Available since v0.9.0 · Latest additions: process runtime, BioModels, v2ecoli, wrapper generation (v0.9.3)

The compose subsystem brings the process-bigraph ecosystem into Atlantis as a production-grade, HPC-backed simulation platform. It runs alongside the vEcoli batch subsystem — both share the same PostgreSQL database, SLURM cluster, and Singularity container infrastructure.

What you can do¶

Capability	CLI entry point	Guide
Whole-cell E. coli simulation	`atlantis compose ecoli`	v2ecoli
Colony simulations (multi-seed)	`atlantis compose ecoli` × N	v2ecoli → Colony
BioModels database (EBI)	`atlantis compose biomodels-*`	BioModels
COPASI / Tellurium (SBML)	`atlantis compose copasi/tellurium`	below
Stateful process runtime	`atlantis compose init/update/end`	REST-Process
Interactive live sandbox	`atlantis compose sandbox`	Sandbox
PBG wrapper generation	`atlantis compose wrapper-create`	Wrappers
Package registry	`atlantis compose packages/package-get/package-audit/package-register`	Registry

Architecture¶

Compose simulations differ from the vEcoli batch workflow in one key way: containers are generated automatically from the simulation’s Python dependencies rather than built from a fixed git commit.

User request (CLI / REST)
        │
        ▼
FastAPI  /compose/v1/...
        │
        ▼  parse PBG document
        │  auto-generate Singularity .def (pbest)
        │  hash definition → check container cache
        │
        ├─── container not cached ──▶ SLURM: build image (~15 min)
        │
        ▼  container cached
SCP experiment files to HPC
        │
        ▼
SLURM: singularity exec <container> python runner.py
        │
        ▼
results.zip ◀── SCP ◀── /experiment/output/

Comparison with vEcoli batch¶

Aspect	vEcoli Batch	Compose
Input	Config JSON + git repo	OMEX/PBG/SBML file or curated template
Engine	Nextflow + vEcoli	process-bigraph + Singularity
Container	Built once from git hash	Auto-generated from PBG dependencies
Base endpoints	`/api/v1/simulations`	`/compose/v1/`
CLI prefix	`atlantis simulation`	`atlantis compose`

Quick Start¶

v2ecoli whole-cell simulation¶

uv run atlantis compose ecoli \
    --duration 60 \
    --seed 0 \
    --poll \
    --base-url https://sms.cam.uchc.edu

COPASI ODE from SBML¶

uv run atlantis compose copasi my_model.sbml \
    --duration 100 \
    --num-data-points 200 \
    --poll \
    --base-url https://sms.cam.uchc.edu

Tellurium from SBML¶

uv run atlantis compose tellurium my_model.sbml \
    --end-time 100 \
    --num-data-points 200 \
    --poll \
    --base-url https://sms.cam.uchc.edu

Generic PBG / OMEX upload¶

uv run atlantis compose run mymodel.omex \
    --interval-time 1.0 \
    --poll \
    --base-url https://sms.cam.uchc.edu

Fetch status and results¶

uv run atlantis compose status <SIM_ID> --base-url https://sms.cam.uchc.edu
uv run atlantis compose results <SIM_ID> --dest ./output --base-url https://sms.cam.uchc.edu
uv run atlantis compose doc <SIM_ID> --base-url https://sms.cam.uchc.edu

Database¶

Compose uses the same PostgreSQL instance as the vEcoli subsystem, with separate compose_-prefixed tables:

Table	Contents
`compose_simulators`	Container definition registry (content-hashed)
`compose_simulations`	Simulation metadata and input PBG documents
`compose_hpcruns`	SLURM job tracking
`compose_packages`	Registered process-bigraph packages
`compose_bigraph_compute`	Registered processes and steps
`compose_process_instance`	Live process runtime instances (UUID-keyed)
`compose_process_update`	Audit trail of every `update` call
`compose_pbg_wrapper`	PBG wrapper generation jobs

Process-Bigraph Document Format¶

.pbg files are JSON documents describing a composable simulation:

{
    "state": {
        "my_process": {
            "_type": "process",
            "address": "local:my_module.MyProcess",
            "config": { "rate": 0.1 },
            "interval": 1.0,
            "inputs": { "substrate": ["stores", "substrate"] },
            "outputs": { "product":  ["stores", "product"] }
        }
    }
}

Key concepts:

address — Python resolution path for the compute class (local: = same environment)
config — passed to the class constructor
inputs/outputs — port names mapped to paths in the shared store tree
interval — timestep for continuous processes

.pbg files can be submitted standalone or bundled inside an OMEX archive (ZIP).

Notes¶

Compose endpoints are independent of vEcoli batch endpoints — both run simultaneously.
Container builds run on SLURM; first build with a new definition takes ~15 minutes. Subsequent simulations reuse the cached image instantly.
Compose is available on SLURM deployments only (sms-api-rke, sms-api-rke-dev). It is not deployed on the Stanford/AWS Batch path.