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]]
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.

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.2

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.2
File Size Uploaded Provenance Actions
viva_tellurium-0.2.2.tar.gz 49.4 kB With provenance Details for viva_tellurium-0.2.2.tar.gz

Built distribution (wheel)

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

Total release size: 83.8 kB

Release files / viva_tellurium-0.2.2.tar.gz

Download URL viva_tellurium-0.2.2.tar.gz
Size 49.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fc29f86f2898f4704e32c34e14fd1518a264b355d21ea76aa5d48d4b28fb4589
BLAKE2b-256 checksum
How to use checksums
12e226e317cf41460e6f9305c7f1acbfe8b8321e93094fd6b3fc38e747e27e3b
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.2-py3-none-any.whl

Download URL viva_tellurium-0.2.2-py3-none-any.whl
Size 34.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8140286ba68b3a85ae411d46c2b98a6ab1dec6d1347511c0bcdbc01a0d2f9b0a
BLAKE2b-256 checksum
How to use checksums
ca603b52af93b87970331a9a60e33dce44a37ca3d03f9c883197e6b4c066f0db
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.2

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.2.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