Recipes

Copy-paste cookbook for common tasks.

Inspect what’s in a YAML before running

tvbo info ./study.yaml
tvbo info ./study.yaml --json | jq .explorations

Convert YAML ↔︎ openMINDS JSON-LD

tvbo export openminds ./study.yaml -o ./bundle.jsonld
tvbo import ./bundle.jsonld --format openminds -o ./roundtrip.yaml

Generate runnable scripts for every backend

for fmt in tvb tvboptim jax pde networkdynamics modelingtoolkit; do
    tvbo export "$fmt" experiment:JR_MEG -o "./scripts/${fmt}/"
done

Quickly check a Markdown report

tvbo export markdown experiment:JR_MEG | less

Run one experiment from a multi-experiment study

tvbo run study:Schirner2023 --experiment JR_MEG -b jax -o ./out

Sweep G locally with the JAX backend (vectorized — single process)

The jax backend vectorizes parameter sweeps internally, so this stays a single process:

tvbo run experiment:G_Sweep -b jax -o ./out

The same sweep on Slurm with array tasks

Switch the backend to one without parameter vectorization (e.g. tvb) and use the workflow emitter:

tvbo workflow slurm experiment:G_Sweep -b tvb -o ./kit
sbatch ./kit/run.sbatch

The kit’s README.md will report workflow cells: <N>, array tasks: <N>.

Snakemake kit, JAX backend, GPU container

tvbo workflow snakemake experiment:JR_MEG -b jax \
    --set container=ghcr.io/the-virtual-brain/tvbo:0.7.0-gpu \
    --set retries=1 \
    -o ./kit-jax-gpu

cd kit-jax-gpu && snakemake --cores 8

Run only cell 5 of an array job locally for debugging

tvbo run experiment:Sweep -b jax --slurm-chunk 5/16 -o ./debug-cell5

Validate before committing

Useful as a pre-commit hook:

tvbo validate schema ./study.yaml
tvbo validate bids   ./bids/

CI smoke test for SED-ML / OMEX outputs

tvbo validate sedml ./out/experiment.sedml
tvbo validate omex  ./out/bundle.omex

Re-run a kit on another machine without tvbo

After copying the kit:

# Plain Python — no tvbo needed at runtime
python ./kit/scripts/JR_MEG_FrequencyGradient_Optimization.py \
    --spec ./kit/spec/JR_MEG_FrequencyGradient_Optimization.yaml \
    --output ./reproduced

# Or fire the engine
sbatch ./kit/run.sbatch
snakemake --cores all -d ./kit
nextflow run ./kit/main.nf

See also