TVB-O API Documentation

tvbo

Importing the package is deliberately cheap. Only a NullHandler goes on the tvbo logger, so tvbo is silent as a library; the entry points — tvbo run, SimulationExperiment.run — surface progress through configure_logging, and one switch (TVBO_LOG_LEVEL, or set_log_level) controls all of it. Nothing here imports JAX, PyRates or the ontology.

log	Central logging configuration for TVBO.
multiscale	Flatten a multi-scale reservoir SimulationExperiment to a flat one (Python).
platform	Client for the TVBO platform REST API (load/push saved models & experiments).

Adapters

This module contains adapters for different simulation backends: - pyrates: PyRates backend adapter - pyrates_bifurcation: PyRates/PyCoBi bifurcation analysis adapter - julia: Julia language integration (juliacall) - networkdynamics: NetworkDynamics.jl backend adapter - modelingtoolkit: ModelingToolkit.jl backend adapter - bifurcationkit: BifurcationKit.jl backend adapter

adapters	Backend adapters for SimulationExperiment.
base	Base adapter for processing SimulationExperiment metadata.
bids	BIDS BEP034 Export Module.
bifurcationkit	BifurcationKit.jl backend adapter for SimulationExperiment.
brian2	Native Brian2 backend for small-scale spiking networks.
bsplot	bsplot figure codegen adapter.
colormaps	Colormaps a figure can name that the plotting stack does not ship.
diffeq	DifferentialEquations.jl backend adapter for SimulationExperiment.
figure_workflow	Figure -> distributed-workflow emitter.
gillespie	Gillespie SSA backend — a finite-size stochastic realization of a mean-field rate model.
julia	Python ↔︎ Julia bridge using juliacall (PythonCall.jl).
julia_model	Prepared codegen context for the Julia model templates.
modelingtoolkit	Standalone ModelingToolkit.jl backend adapter for SimulationExperiment.
networkdynamics	NetworkDynamics.jl backend adapter for SimulationExperiment.
neuroml	NeuroML/LEMS adapter for SimulationExperiment.
numcont	Self-contained AUTO-07p (numcont) backend adapter for SimulationExperiment.
observation_sampling	Backend-agnostic resolver for observation-monitor sampling step counts.
openminds	OpenMINDS JSON-LD conversion utilities for TVBO.
pyrates	PyRates backend adapter for SimulationExperiment.
pyrates_bifurcation	PyRates/PyCoBi bifurcation analysis backend adapter for SimulationExperiment.
tvb	TVB (The Virtual Brain) adapter for tvbo.
tvboptim	tvboptim adapter for tvbo.

Shared small-scale network-lowering core.

TVB-O’s small-scale backends (NeuroML/LEMS, Brian2, later NEST/Jaxley) all turn the same declarative primitives — Network, Node(size), Edge(dynamics, coupling, events, connectivity) — into populations of cells and an explicit set of cell-to-cell connections. That lowering is backend-neutral and lives here once; each backend contributes only a role vocabulary, an expression printer, a template tree, and its synapse/cell rendering.

smallscale	Shared small-scale network-lowering core.
lowering	Backend-neutral network lowering for small-scale simulators.

Analysis

Houses analysis result container classes (e.g., BifurcationResult) and related APIs that are logically distinct from plotting utilities or simulation drivers.

analysis	Analysis subpackage.
bifurcation	Bifurcation analysis result objects and helpers.
linear_response	Linear response.
replication	The canonical replication-pairs contract.
units	Dimensional analysis of a model’s equations.

API

This module provides the API for the TVB Ontology.

api	TVB-O API.
direct_ontology_api	Direct RDF/SPARQL-based ontology API.
dynamics_api	Dynamics model API — serves neural mass models from the tvbo database.
experiment_api	Experiment API — serves simulation experiments from the tvbo database.
main	FastAPI application exposing the TVBO ontology and simulation experiment endpoints.
network_api	Network retrieval API — serves normative connectomes from the tvbo database.
ontology_api	Read the ontology as graph data a front end can render.

Hand-written behaviour attached to the generated model classes.

Each module here holds one class’s user-facing helpers as a plain mixin. hatch_build discovers them by name — EventBehaviour attaches to Event — and makes each a base of both generated forms, so the helpers are present on every object however it was built: loaded through LinkML, validated through Pydantic, or constructed by hand. Adding behaviour to a class is creating a file here; there is nothing to register.

behaviour	Hand-written behaviour attached to the generated model classes.
continuation	Factory constructors for :class:`Continuation`.
coupling	Ontology population, symbolic reading, code generation and plotting for coupling.
dynamics	The symbolic layer, on every :class:`Dynamics` however it was built.
dynamics_runtime	What a `Dynamics` does, on every `Dynamics` however it was built.
event	User-facing helpers for :class:`Event`.
integrator	Ontology-backed metadata, code generation and factories for :class:`Integrator`.
perturbation	Symbolic reading, code generation and plotting for :class:`Stimulus`.

Classes

Core simulation classes: dynamics, coupling, noise, continuation, observation, perturbation, equation, functions, experiment, study, network, and atlas.

classes	tvbo.classes.
atlas	Runtime helpers for brain atlases and parcellation volumes.
continuation	Continuation.
correlated_noise	Correlated-noise lowering: a declared covariance becomes a Wiener-increment mixer.
coupling	Coupling functions.
dynamics	Dynamics models.
equation	Parse, substitute and sort the symbolic equations of a model.
experiment	The `SimulationExperiment` host object that ties a whole simulation together.
function	Function Classes.
network	Brain-network connectivity classes for TVBO.
noise	Runtime `Noise` wrapper, and the public import location for `Integrator`.
observation	Observation models that transform simulation output into observables.
parcellation	This module provides functions for loading and accessing parcellation data.
perturbation	Exogenous stimuli for simulation experiments.
phenotype	Runtime :class:`Phenotype` class.
software	The `SimulationTool` runtime wrapper, and a tool’s own unit vocabulary.
study	User-facing `SimulationStudy` class for grouping related experiments.

CLI

The CLI is Typer-based, registry-driven and transport-aware. This module assembles the top-level :class:typer.Typer app from per-verb sub-modules.

cli	TVB-O command-line interface.
brain	`tvbo brain` — the ASCII spec-to-cortex portrait, and the bare-`tvbo` splash.
cache	Inspect and reclaim the produced-constant store.
config	`tvbo config` — view CLI configuration (full impl in C2).
export	`tvbo export` — render a SPEC into a target format (no execution).
figures	`tvbo figure` — render declarative figures from a Figure or Study YAML.
formats	`tvbo formats` — list every registered I/O format.
import_	`tvbo import` — load a foreign file via the registry’s importer dispatch.
info	`tvbo info` — inspect a SPEC without running it.
install	`tvbo install` — provision optional components that pip alone cannot place.
network	`tvbo network` — build brain-network connectomes from tractograms.
run	`tvbo run` — execute a Study or Experiment.
save	`tvbo save` — alias for `tvbo export --with-data`.
skills	`tvbo skills` — manage TVBO skill files for AI coding assistants.
study	`tvbo study` — scaffold and inspect a study dataset.
units	Inspect the curated unit vocabulary, and promote a unit into it.
validate	`tvbo validate` — sub-tree of validators (schema today; OMEX/SED-ML/BIDS later).
verify	`tvbo verify` — check a study-of-studies is buildable, and hard-fail if not.
version	`tvbo version` — print the package version.
workflow	`tvbo workflow` — emit Slurm / Snakemake / Nextflow artefacts from a Study.

TVB-O Code Generation

Template rendering, code printing, and backend-specific code generation.

codegen	TVB-O Code Generation.
code	SymPy expression printers that render symbolic model math to backend source code.
cuda	CUDA Adapter for TVBO.
functions	Function Code Generation.
lems	# LEMS-Generator Create LEMS model from TVB-O.
prune	Drop the imports and bindings a generated module does not use.
pyrates	PyRates Integration Module.
reducers	General resolver: lower a declarative streaming-reducer spec to backend source.
streaming_reducers	Codegen registry: pipeline reducer callable -> backend streaming reducer.
style	House style for generated source, one formatter per output language.
templater	Shared codegen helpers the Mako templates and the export registry read.
transforms	Transform vocabulary: the network’s own edge attributes, and masked reductions.

Data

Access and manage TVB-O data.

data	Data Module.
analysis_io	Run a study’s declarative `analyses:` and persist each as its own container.
connectome_build	Build a structural connectome from a tractogram + parcellation via MRtrix3.
converters	Format converters: BEP017 export.
dataref	Resolve a :class:`DataRef` to a labelled array — the one cross-container reference path.
experiment_result_io	Sidecar I/O + cross-experiment cache for :class:`ExperimentResult`.
matrix_io	Low-level matrix read/write for HDF5 groups and Zarr groups.
mesh_fem	P1 finite-element operators for a triangular mesh, flat or curved.
mesh_io	Read a surface mesh file into vertices and faces.
network_io	High-level Network I/O. Dispatches by companion file extension.
param_io	Resolve a :class:`Parameter`’s value from its declared provenance.
provenance	What a run actually did, recorded beside the container it produced.
registry	Canonical database registry — resolves short names to YAML file paths.
study_manifest	The results manifest and the `tvbo verify` checks.
types	Runtime data types for TVBO simulations.

Data Model

Auto-generated from LinkML schema.

datamodel	TVB-O Data Model.
dialect	The TVBO YAML dialect — one implementation, both construction paths.
dialect_tables	Generated dialect tables — see :mod:`tvbo.datamodel.dialect`.
pydantic
schema

Export

Non-code exports: reports, metadata standards (OpenMINDS).

export	TVB-O Export.
formats	Built-in export-format registrations.
registry	Export-format registry.

Graph Generators

A curated GraphGenerator under tvbo/database/graph_generators/ is defined by its procedure: block: an ordered DAG of typed steps whose options are schema fields. :mod:tvbo.graph_generators.procedural resolves that DAG to SymPy and renders it through the printer tables in tvbo/codegen/code.py, so eager construction at Network load time and emitted backend source are the same expressions rendered twice. There are no per-generator Python materialisers.

graph_generators	TVBO graph generators — declarative typed DAGs, one resolver.
catalog	The curated GraphGenerator catalog: entry lookup, declared defaults, reference matrices.
procedural	Resolve a `Procedural` GraphGenerator’s typed DAG into backend-independent expressions.

JAX

JAX integration utilities for tvbo.

jax	JAX integration utilities for tvbo.
xarray_pytrees	Register xarray data structures as JAX pytree nodes.

TVB-O Ontology

OWL ontology access, query, and configuration.

ontology	TVB-O Ontology.
config	TVB-O Model Configuration Module.
constants	Constants.
db	Load bundled example `SimulationStudy` definitions from the ontology data directory.
graph	# Graph-based representation of the ontology.
owl	— title: “Ontology Module for TVB-O” author: Leon Martin.
query	SPARQL-based query helpers for the TVBO ontology.

Atlas

Groups helpers for working with brain parcellation schemes, such as mapping between region indices and labels and translating between atlas naming conventions (for example FreeSurfer and HCP-MMP1).

atlas	Brain atlas utilities for the TVBO ontology.
freesurfer	FreeSurfer atlas utilities for mapping between region indices and labels.

Semantic Web

This subpackage bridges the TVB Ontology (TVB-O) with external semantic-web resources. It currently provides the tvbgo module, which links TVB models and their parameters to the Gene Ontology (GO) through curated keyword mappings.

semanticweb	Semantic-web integration utilities for the TVB Ontology.
tvbgo	TVB-GO Module.

Parse

This module provides functions for parsing different types of data to extract model components and metadata.

parse	TVB-O Parse.
expression	Parse TVBO equation strings into SymPy expressions.
lems_loader	This module deals with loading elements from LEMS-generated files.
symbols	Parsing namespaces: the names an expression is allowed to mean.
system	The symbolic layer between a model’s metadata and everything rendered from it.

Plot

This module contains utilities for plotting TVB-O models.

plot	TVB-O’s plotting utilities.
analysis	Plotting helpers for analysing simulation output.
animate	Animation utilities for SimulationResult.
capture	Render an HTML page to a static file with a headless browser, from a figure spec.
dynamics	General-purpose plotting for `Dynamics` objects.
dynamics_layout	Declarative layout composition for Dynamics plotting.
experiment_layout	Declarative and auto-configured layout composition for Experiment plotting.
layout_mosaic	Reusable subplot_mosaic helpers for declarative panel layouts.
network	Network graph plotting utilities.
network_graph	Network graph plotting utilities.
ontology	Plots of the ontology graph and of a model’s place in it.
palette	Named colour roles for figures, so a project’s colours live in one file.
phase	Phase-space trajectory and vector-field plots for SimulationResult.
schematic	Population-schematic diagrams for neural-mass / mean-field / spiking models.
timeseries	Time-series, EEG, and power-spectrum plotting for SimulationResult.
utils	Plotting helpers for TVB-O figures.

Run

This package collects the execution helpers used once a model and connectome are assembled: graph-based integration of a connectome as a network of coupled local models (GraphRunner), the SciPy reference helpers it builds on (tvbo.run.compgraph), and low-level utilities for running TVBO-generated Julia code (tvbo.run.julia).

run	Runners that execute TVBO simulations on different backends.
compgraph	Reference simulation of network dynamics on a computational graph.
graph	Graph-based simulation of a connectome as a network of coupled local models.
julia	Low-level Julia execution utilities for running generated Julia code.

PDE/FEM code-generation templates for TVBO field models.

Renders a self-contained scikit-fem solver from a SimulationExperiment’s field_dynamics. utils resolves the declared equations into the assembly plan the template emits, so the operator that runs is the operator that was written down.

pde	PDE/FEM code-generation templates for TVBO field models.
utils	Resolve `field_dynamics` into the assembly plan the FEM template emits.

RateML

Renders TVB-compatible model code (Python/Numba) and CUDA GPU kernels from TVBO SimulationExperiment specifications, following the conventions of TVB’s RateML while sourcing dynamics from TVBO’s YAML model specifications instead of LEMS XML.

rateml	RateML-style code generation templates for TVBO models.
utils	Code printers for generating RateML-style CUDA and Python from TVBO.

tvboptim

Mako templates for generating tvboptim network dynamics code from TVBO models.

tvboptim	# TVB-Optim Templates.
callbacks	Runtime callbacks for generated tvboptim scripts.
observations	TVB-compatible observation monitors for generated tvboptim code.
utils	TVB-Optim Template Utilities.

Utilities

Core utilities: Bunch container, PyTree formatting, YAML I/O, and metadata traversal helpers.

utils	Utilities Module for TVB-O.
auto	Helpers for locating the auto-07p installation used by the NumCont backend.
figure_compare	Measure how a rendered figure differs in LAYOUT from a reference image.
pydantic_loader	Pydantic loader / validator for TVBO YAML — the trustworthy validation path.
report	Report Module.
study_layout	Read the study-layout record and answer questions about it.
units	Unit and Dimension Utilities.
yaml_loader	YAML loader wrapper used by every `Network.from_file` / `SimulationExperiment.from_file` / `SimulationStudy.from_file` entry point in TVBO.