OpenMINDS Interoperability

Exporting TVBO simulations to OpenMINDS JSON-LD

Author

TVBO Team

Published

March 25, 2026

Overview

TVBO provides bidirectional interoperability with OpenMINDS, enabling:

  • Export simulation experiments to OpenMINDS-compatible JSON-LD
  • Import OpenMINDS JSON-LD back into TVBO objects
  • Integration with EBRAINS Knowledge Graph

Define a Simulation Experiment

The most readable way to define an experiment is using pure YAML with SimulationExperiment.from_string():

Code 
import json
from tvbo.classes.experiment import SimulationExperiment
from IPython.display import Markdown
yaml_definition = """
id: 1
label: Three-Node Oscillator Network
description: >
  A simple 3-node network simulation using a damped harmonic oscillator model.
  Demonstrates round-trip conversion to/from OpenMINDS JSON-LD.

# Custom oscillator model (avoids ontology lookup)
dynamics:
  name: TEST_Oscillator
  label: Damped Harmonic Oscillator
  description: Simple 2D oscillator for testing
  system_type: continuous

  state_variables:
    x:
      name: x
      label: Position
      equation:
        lhs: d(x)/dt
        rhs: y
      domain: {lo: -10.0, hi: 10.0}
      variable_of_interest: true
      initial_value: 1.0

    y:
      name: y
      label: Velocity
      equation:
        lhs: d(y)/dt
        rhs: -omega**2 * x - gamma * y + k * c_in
      coupling_variable: true
      initial_value: 0.0

  parameters:
    omega:
      name: omega
      label: Angular frequency
      value: 1.0
      unit: rad/s
    gamma:
      name: gamma
      label: Damping coefficient
      value: 0.1
    k:
      name: k
      label: Coupling strength
      value: 0.05

  coupling_terms:
    c_in:

# 3-node network with connectivity
network:
  number_of_nodes: 3
  nodes:
    - id: 0
      label: Region_A
    - id: 1
      label: Region_B
    - id: 2
      label: Region_C
  edges:
    - source: 0
      target: 1
      parameters:
        weight: {value: 0.5}
    - source: 1
      target: 0
      parameters:
        weight: {value: 0.5}
    - source: 1
      target: 2
      parameters:
        weight: {value: 0.3}
    - source: 2
      target: 1
      parameters:
        weight: {value: 0.3}
    - source: 0
      target: 2
      parameters:
        weight: {value: 0.2}
    - source: 2
      target: 0
      parameters:
        weight: {value: 0.2}

# Integration settings
integration:
  method: heun
  step_size: 0.1
  duration: 100.0
  time_scale: s

# Coupling function
coupling:
  name: Linear
  label: Linear Diffusive Coupling
"""

# Step 1: Create experiment from YAML string
experiment = SimulationExperiment.from_string(yaml_definition)

Markdown(experiment.generate_report())

Three-Node Oscillator Network

A simple 3-node network simulation using a damped harmonic oscillator model. Demonstrates round-trip conversion to/from OpenMINDS JSON-LD.

1. Brain Network

  • Regions: 3

Coupling: Linear Diffusive Coupling

Receives \(y\) from connected regions with conduction delays.

2. Local Dynamics: Damped Harmonic Oscillator

Simple 2D oscillator for testing. The model comprises 2 state variables.

2.1 State Equations

\[\dot{x} = y\]

\[\dot{y} = c_{in} \cdot k - \gamma \cdot y - x \cdot \omega^{2}\]

2.2 Parameters

Parameter Value Unit Description
\(\gamma\) 0.1 —
\(k\) 0.05 —
\(\omega\) 1.0 rad_per_s

3. Numerical Integration

  • Method: heun
  • Time step: \(\Delta t = 0.1\) ms
  • Duration: 100.0 ms
experiment.run().integration.plot()

============================================================
STEP 1: Running simulation...
============================================================
  Simulation period: 100.0 ms, dt: 0.1 ms
  Transient period: 0.0 ms
  Simulation complete.

============================================================
Experiment complete.
============================================================

Export to OpenMINDS JSON-LD

# Step 2: Convert to OpenMINDS JSON-LD
jsonld = experiment.to_openminds(base_id="https://example.org/simulations")


print("JSON-LD preview:")
print(json.dumps(jsonld, indent=2, default=str)[:1500])
JSON-LD preview:
{
  "@context": {
    "@vocab": "https://openminds.ebrains.eu/vocab/",
    "tvbo": "http://www.thevirtualbrain.org/tvb-o/",
    "sands": "https://openminds.ebrains.eu/sands/",
    "core": "https://openminds.ebrains.eu/core/",
    "computation": "https://openminds.ebrains.eu/computation/"
  },
  "@type": "tvbo:SimulationExperiment",
  "id": 1,
  "model": "TEST_Oscillator",
  "description": "A simple 3-node network simulation using a damped harmonic oscillator model. Demonstrates round-trip conversion to/from OpenMINDS JSON-LD.\n",
  "additional_equations": [],
  "label": "Three-Node Oscillator Network",
  "dynamics": {
    "name": "TEST_Oscillator",
    "label": "Damped Harmonic Oscillator",
    "parameters": {
      "gamma": {
        "@type": "tvbo:Parameter",
        "name": "gamma",
        "label": "Damping coefficient",
        "value": 0.1,
        "explored_values": [],
        "element_domains": []
      },
      "k": {
        "@type": "tvbo:Parameter",
        "name": "k",
        "label": "Coupling strength",
        "value": 0.05,
        "explored_values": [],
        "element_domains": []
      },
      "omega": {
        "@type": "tvbo:Parameter",
        "name": "omega",
        "label": "Angular frequency",
        "value": 1.0,
        "explored_values": [],
        "element_domains": []
      }
    },
    "description": "Simple 2D oscillator for testing",
    "references": [],
    "coupling_terms": {
      "c_in": {
        "@type": "tvbo:Parameter",

Import from OpenMINDS JSON-LD

reconstructed = SimulationExperiment.from_openminds(jsonld)
reconstructed.run().integration.plot()

============================================================
STEP 1: Running simulation...
============================================================
  Simulation period: 100.0 ms, dt: 0.1 ms
  Transient period: 0.0 ms
  Simulation complete.

============================================================
Experiment complete.
============================================================

Convert Back to YAML

yaml_output = reconstructed.to_yaml()
print(yaml_output[:2000])
print("\n... [truncated]")
id: 1
model: TEST_Oscillator
description: 'A simple 3-node network simulation using a damped harmonic oscillator
  model. Demonstrates round-trip conversion to/from OpenMINDS JSON-LD.

  '
label: Three-Node Oscillator Network
dynamics:
  name: TEST_Oscillator
  label: Damped Harmonic Oscillator
  parameters:
    gamma:
      name: gamma
      label: Damping coefficient
      value: 0.1
    k:
      name: k
      label: Coupling strength
      value: 0.05
    omega:
      name: omega
      label: Angular frequency
      value: 1.0
  description: Simple 2D oscillator for testing
  coupling_terms:
    c_in:
      name: c_in
  coupling_inputs:
    c_in:
      name: c_in
      dimension: 1
  state_variables:
    x:
      name: x
      label: Position
      domain:
        lo: '-10.0'
        hi: '10.0'
        log_scale: false
      equation:
        lhs: Derivative(x, t)
        rhs: y
        latex: false
      variable_of_interest: true
      coupling_variable: false
      equation_type: differential
      equation_order: 1
      initial_value: 1.0
    y:
      name: y
      label: Velocity
      equation:
        lhs: Derivative(y, t)
        rhs: c_in*k - gamma*y - omega**2*x
        latex: false
      variable_of_interest: true
      coupling_variable: true
      equation_type: differential
      equation_order: 1
      initial_value: 0.0
  number_of_modes: 1
  system_type: continuous
  autonomous: true
integration:
  method: heun
  abs_tol: 1.0e-10
  rel_tol: 1.0e-10
  time_scale: ms
  duration: 100.0
  step_size: 0.1
  transient_time: 0.0
  scipy_ode_base: false
  number_of_stages: 2
  intermediate_expressions:
    X1:
      name: X1
      equation:
        lhs: X1
        rhs: X + dX0 * dt + noise + stimulus * dt
        latex: false
      conditional: false
  update_expression:
    name: dX
    equation:
      lhs: X_{t+1}
      rhs: (dX0 + dX1) * (dt / 2)
      latex: false
    conditional: false
  delayed: false
network:
  nodes:
  - id: 0
    label: Region_A

... [truncated]