Metadata-Version: 2.4
Name: viva-tellurium
Version: 0.1.1
Summary: Process-bigraph wrapper for Tellurium / libroadrunner SBML simulation
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: process-bigraph>=1.8.5
Requires-Dist: bigraph-schema
Requires-Dist: viva-superpowers
Requires-Dist: tellurium>=2.2
Requires-Dist: numpy
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: bigraph-viz; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

# viva-tellurium

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.

**[View Interactive Demo Report](https://vivarium-collective.github.io/viva-tellurium/)** — Lotka-Volterra predator-prey, Elowitz-Leibler repressilator, and Gillespie stochastic dimerization with Plotly time series, phase portraits, reaction-rate charts, and bigraph architecture diagrams.

## 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`.

| Port         | Dir    | Schema                  |
|--------------|--------|-------------------------|
| `species`    | input  | `maybe[map[float]]`     |
| `species`    | output | `overwrite[map[float]]` |
| `rates`      | output | `overwrite[map[float]]` |
| `parameters` | output | `overwrite[map[float]]` |
| `time`       | output | `overwrite[float]`      |

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

### `TelluriumStep` (Step)

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

### `make_tellurium_document(...)`

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

## Demo & Tests

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