Skip to main content

viva-tellurium

CI read-only workbench license

Process-bigraph wrapper for Tellurium / libroadrunner, exposing any SBML or Antimony kinetic model as a process-bigraph Process so it can be composed with other simulators in a bigraph document.

Open the read-only workbench to browse every composite, study, and result in your browser — or run it locally (below).

Installation

uv venv .venv && source .venv/bin/activate
uv pip install -e .

Quick Start

from process_bigraph import Composite, allocate_core, gather_emitter_results
from process_bigraph.emitter import RAMEmitter
from viva_tellurium import TelluriumProcess, make_tellurium_document

ANTIMONY = """
model decay
  S1 = 10; S2 = 0
  S1 -> S2; k*S1; k = 0.3
end
"""

core = allocate_core()
core.register_link('TelluriumProcess', TelluriumProcess)
core.register_link('ram-emitter', RAMEmitter)

doc = make_tellurium_document(model=ANTIMONY, interval=1.0)
sim = Composite({'state': doc}, core=core)
sim.run(10.0)

print(gather_emitter_results(sim)[('emitter',)][-1]['species'])

API

TelluriumProcess (Process)

Time-driven bridge wrapping a RoadRunner instance. Lazy init; each update() advances by interval.

Species port is a bulk numpy Array by default (bulk_species=True) — it's moved through roadrunner's bulk C API (one buffer copy instead of a per-species map[float] loop), ~2× faster per update() and bit-identical. Wire species to an Array-shaped store. The default ports:

Port Dir Schema (default, bulk_species=True)
species input maybe[array[(n,),float]]
parameters_in input map[float]
species output overwrite[array[(n,),float]]
rates output overwrite[map[float]]
parameters output overwrite[map[float]]
time output overwrite[float]

species is ordered by getFloatingSpeciesIds(). For coupled multi-process composites (two+ processes sharing one species store), also set coupled_species=True — the species output becomes an additive array so the arms' deltas sum under reconcile. For the legacy per-species map[float] port (slower; only if a consumer needs a dict-shaped species store), set bulk_species=False.

parameters_in changes global parameters while the model runs (a rate constant, or an input parameter another layer drives). Before each interval is simulated, every {parameter_id: value} on the port is set in roadrunner, the same way the config parameter_overrides are set at build. So parameter_overrides gives the initial value, and the port overrides it from the first update that carries it.

  • A value stays in effect until the port changes it; removing a key keeps its last value. A process writing to the port's store should declare its output overwrite[map[float]] (or overwrite[float] when wired to one key): a plain map[float] output adds to the store each update.
  • The whole map is checked before anything is set. An id that is not a global parameter, or is defined by an assignment rule, and a value that is not a finite number, raise a ValueError.
  • Parameters declared constant="true" in SBML can be set. A parameter with a rate rule is a state variable: setting it restarts its integration from the given value.
  • An unwired or empty port changes nothing.
  • It is a separate port from the parameters output, which overwrites every global parameter after each update, so wire them to different stores.

Config (all optional, one of model/model_file required): model, model_format ('antimony'/'sbml'), model_file, integrator ('cvode'/'gillespie'), absolute_tolerance, relative_tolerance, seed, species_overrides, parameter_overrides, reset_on_init, bulk_species (default True), coupled_species, conserved_moiety_analysis.

TelluriumStep (Step)

One-shot trajectory Step. Extra config: start_time, end_time, n_points, output_times, selections. Outputs: time_series (list), species_trajectories (map[list]).

output_times is an explicit, possibly non-uniform list of output time points (assumed sorted ascending). When non-empty, the time course is sampled at exactly those times (roadrunner simulate(times=[...])), overriding the uniform start_time/end_time/n_points grid, and the returned time_series is those points verbatim. Empty (the default) keeps the uniform behavior. It composes with selections and species_units. The key name matches the viva-copasi wrapper (copasi's term is values, tellurium's is times).

selections is a list of roadrunner selection strings (e.g. 'time', 'S1', '[S1]' for a concentration, a reaction id for a flux). Empty (the default) keeps roadrunner's built-in output — time + all floating species for a time course, and floating-species concentrations for a steady state. When set, the trajectory/steady-state keys are exactly the requested selections ('time', if requested in a time course, is pulled out into time_series). The steady-state step uses roadrunner's steadyStateSelections path. The key name and semantics match the viva-copasi and viva-biomodels wrappers.

make_tellurium_document(...)

Ready-to-run composite document wiring a TelluriumProcess to a stores dict and a RAM emitter.

Workbench

Composites and investigations in this workspace (browse them interactively in the published read-only workbench linked above):

Composite What it is
decay-demo Tiny Tellurium / Antimony decay demo: S1 -> S2 first-order kinetics.
decay-with-viz Tellurium decay demo with a wired Visualization Step.
steady-state Tellurium / Antimony steady-state solver: computes equilibrium concentrations for a model using RoadRunner's steadyState(). Emits the steady-state species map as 'concentrations'.
Investigation Research question
Tellurium sbml simulation (planning) TBD — what overarching question ties these studies together?

Demo & Tests

python demo/demo_report.py   # regenerates demo/report.html, opens in Safari
pytest tests/                # 17 offline tests

Metadata

Release files for viva-tellurium 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for viva-tellurium 0.2.3
File Size Uploaded Provenance Actions
viva_tellurium-0.2.3.tar.gz 54.4 kB With provenance Details for viva_tellurium-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for viva-tellurium 0.2.3
File Interpreter ABI Platform Actions
viva_tellurium-0.2.3-py3-none-any.whl Python 3 none any Details for viva_tellurium-0.2.3-py3-none-any.whl

Total release size: 90.2 kB

Release files / viva_tellurium-0.2.3.tar.gz

Download URL viva_tellurium-0.2.3.tar.gz
Size 54.4 kB
Tags Source
SHA-256 checksum
How to use checksums
bcf904e2855016bb8a692498c95495d485fc0622106c9aa9036de76e37426e45
BLAKE2b-256 checksum
How to use checksums
71fed30db1359e435a48b61de49576d6a5d396b2297282afce5acc826069dd1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / viva_tellurium-0.2.3-py3-none-any.whl

Download URL viva_tellurium-0.2.3-py3-none-any.whl
Size 35.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c629a392750916cef2c18cf5d5106775fad34c7f1b2402b296eb4d48d55cac7
BLAKE2b-256 checksum
How to use checksums
fc3c08959481ad7de935d0f4e69ae8d8f7ebd19820dda458e8de63857c200df2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for viva-tellurium 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for viva_tellurium-0.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page