viva-tellurium
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.