Process Runtime (REST-Process Mirror)

Available since v0.9.3

The process runtime subsystem exposes every class registered in the process-bigraph link_registry as a stateful, UUID-keyed REST resource. It mirrors the paradigm from rest-process — a sketch that was always intended to inform this integration — and implements it as a first-class API surface inside Atlantis with full database persistence.

Concepts

Term	Meaning
link_registry	The dict populated by allocate_core() mapping process names → classes
instance	One live instantiation of a registered process, identified by a UUID
update	One timestep execution: call process.update(state, interval)
end	Terminate an instance and release its memory
registry	PostgreSQL audit trail of every initialize/update/end call

The 42 bigraph-schema primitive types are exposed via GET /compose/v1/types. The 11 registered processes from pbsim_common and process_bigraph are each addressable by name.

Quick Demo: MSEComparison

No SBML file needed. This walks through the full instance lifecycle.

BASE=https://sms.cam.uchc.edu

# 1. See what's registered
uv run atlantis compose list-types --base-url $BASE
uv run atlantis compose processes --base-url $BASE

# 2. Inspect config schema
uv run atlantis compose config-schema MSEComparison --base-url $BASE
# → {"ignore_nans": false, "columns_of_interest": []}

# 3. Initialize an instance
uv run atlantis compose init MSEComparison --base-url $BASE
# → Process ID: a3f1c2d4-...

# 4. Inspect its ports
uv run atlantis compose inputs MSEComparison a3f1c2d4-... --base-url $BASE
uv run atlantis compose outputs MSEComparison a3f1c2d4-... --base-url $BASE

# 5. Terminate
uv run atlantis compose end MSEComparison a3f1c2d4-... --base-url $BASE

Registered Processes

Every process available in the live deployment:

Name	Package	SBML required	Config fields
MSEComparison	pbsim_common	no	ignore_nans, columns_of_interest
ComparisonTool	pbsim_common	no	ignore_nans, columns_of_interest
CopasiUTCStep	pbsim_common	yes	model_source, time, n_points, output_dir
CopasiUTCProcess	pbsim_common	yes	model_source, time, intervals
CopasiSteadyStateStep	pbsim_common	yes	model_source, time
TelluriumUTCStep	pbsim_common	yes	model_source, time, n_points, output_dir
TelluriumSteadyStateStep	pbsim_common	yes	model_source
TelluriumStep	pbsim_common	no	(none)
Step	process_bigraph	no	(none)
Process	process_bigraph	no	(none)
edge	bigraph_schema	no	(none)

CLI Reference

# List all bigraph-schema type names (42 types)
uv run atlantis compose list-types --base-url <URL>

# Config schema for a named process or step
uv run atlantis compose config-schema <NAME> --base-url <URL>

# Instantiate; prints the UUID
uv run atlantis compose init <NAME> --base-url <URL>

# Inputs / outputs schemas for an active instance
uv run atlantis compose inputs <NAME> <UUID> --base-url <URL>
uv run atlantis compose outputs <NAME> <UUID> --base-url <URL>

# Run one update step
uv run atlantis compose update <NAME> <UUID> --base-url <URL>

# Terminate instance
uv run atlantis compose end <NAME> <UUID> --base-url <URL>

REST API Reference

All endpoints are under /compose/v1/.

Method	Path	Description
GET	/types	List all bigraph-schema type names
GET	/process/{name}/config-schema	Config schema for a registered process or step
POST	/process/{name}/initialize	Create instance; returns {"process_id": "<uuid>"}
GET	/process/{name}/inputs/{id}	Inputs schema for an active instance
GET	/process/{name}/outputs/{id}	Outputs schema for an active instance
POST	/process/{name}/update/{id}	Run one update step
POST	/process/{name}/end/{id}	Terminate instance and release memory

Initialize request

curl -X POST https://sms.cam.uchc.edu/compose/v1/process/MSEComparison/initialize \
    -H "Content-Type: application/json" \
    -d '{"config": {"ignore_nans": false, "columns_of_interest": []}}'

Response:

{"process_id": "a3f1c2d4-5678-90ab-cdef-1234567890ab"}

Update request

curl -X POST https://sms.cam.uchc.edu/compose/v1/process/MSEComparison/update/a3f1c2d4-... \
    -H "Content-Type: application/json" \
    -d '{"state": {}, "interval": 1.0}'

Process Registry (Persistence + Audit)

Every initialize, update, and end call is mirrored to PostgreSQL — providing a full audit trail and cross-pod observability.

Read-only registry endpoints

# All instances (optionally filter by status)
curl https://sms.cam.uchc.edu/compose/v1/process/instances
curl https://sms.cam.uchc.edu/compose/v1/process/instances?status=active
curl https://sms.cam.uchc.edu/compose/v1/process/instances?status=ended

# Full update history for a specific instance
curl https://sms.cam.uchc.edu/compose/v1/process/instances/<uuid>/history

Database tables

Table	Contents
compose_process_instance	One row per initialized instance (UUID, name, config, status, timestamps)
compose_process_update	One row per update call (instance FK, inputs, outputs, interval, timestamp)

Instance record shape

{
    "process_id": "a3f1c2d4-...",
    "process_name": "MSEComparison",
    "config": {"ignore_nans": false, "columns_of_interest": []},
    "status": "ended",
    "created_at": "2026-05-11T14:30:00",
    "ended_at": "2026-05-11T14:30:45"
}

Correspondence with rest-process

The Atlantis implementation maps directly to the rest-process sketch:

rest-process endpoint	Atlantis equivalent
GET /process_types	GET /compose/v1/types
POST /process/{name}	POST /compose/v1/process/{name}/initialize
GET /process/{name}/inputs/{id}	GET /compose/v1/process/{name}/inputs/{id}
GET /process/{name}/outputs/{id}	GET /compose/v1/process/{name}/outputs/{id}
PUT /process/{name}/update/{id}	POST /compose/v1/process/{name}/update/{id}
DELETE /process/{name}/{id}	POST /compose/v1/process/{name}/end/{id}

Atlantis extends this with:

• Full database persistence (audit trail, cross-pod observability)

• CLI commands (atlantis compose init/inputs/outputs/update/end)

• Registry read endpoints (/process/instances, /process/instances/{id}/history)

• Integration with the PBG Live Sandbox