Metadata-Version: 2.4
Name: viva-tellurium
Version: 0.2.2
Summary: Process-bigraph wrapper for Tellurium / libroadrunner SBML simulation
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: process-bigraph>=1.8.5
Requires-Dist: bigraph-schema
Requires-Dist: tellurium>=2.2
Requires-Dist: libroadrunner>=2.11.0
Requires-Dist: numpy
Requires-Dist: pyyaml
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: six
Provides-Extra: dashboard
Requires-Dist: viva-superpowers; extra == "dashboard"
Requires-Dist: vivarium-workbench; extra == "dashboard"
Requires-Dist: plotly; extra == "dashboard"
Provides-Extra: cli
Requires-Dist: typer; extra == "cli"
Requires-Dist: rich; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: bigraph-viz; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: jsonschema[format-nongpl]>=4.21; extra == "dev"
Requires-Dist: jinja2>=3.1; extra == "dev"
Requires-Dist: pypdf>=4.0; extra == "dev"
Requires-Dist: viva-tellurium[dashboard]; extra == "dev"
Dynamic: license-file

# viva-tellurium

<!-- BEGIN:badges -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

[![CI](https://github.com/vivarium-collective/viva-tellurium/actions/workflows/workspace-ci.yml/badge.svg)](https://github.com/vivarium-collective/viva-tellurium/actions/workflows/workspace-ci.yml)
[![read-only workbench](https://img.shields.io/badge/read--only_workbench-live-2ea44f)](https://vivarium-collective.github.io/viva-tellurium/workbench/)
[![license](https://img.shields.io/github/license/vivarium-collective/viva-tellurium)](./LICENSE)
<!-- END:badges -->

Process-bigraph wrapper for [Tellurium](https://tellurium.analogmachine.org/) /
[libroadrunner](https://libroadrunner.org/), exposing any SBML or Antimony
kinetic model as a `process-bigraph` Process so it can be composed with
other simulators in a bigraph document.

<!-- BEGIN:dashboard -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

**[Open the read-only workbench](https://vivarium-collective.github.io/viva-tellurium/workbench/)** to browse every composite, study, and result in your browser — or run it locally (below).
<!-- END:dashboard -->

## Installation

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

## Quick Start

```python
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):

<!-- BEGIN:composites -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

| 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'. |
<!-- END:composites -->

<!-- BEGIN:investigations -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

| Investigation | Research question |
|---|---|
| [Tellurium sbml simulation _(planning)_](https://vivarium-collective.github.io/viva-tellurium/investigations/tellurium-sbml-simulation.html) | TBD — what overarching question ties these studies together? |
<!-- END:investigations -->

## Demo & Tests

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