pydantic

datamodel.pydantic

Classes

Name Description
Aggregation Specifies how to aggregate values across a dimension. Used for loss functions to define per-element loss with reduction.
AggregationType How to aggregate time series data
Algorithm A complete specification of an iterative parameter tuning algorithm. Combines update rules, objectives, observations, and hyperparameters.
AlgorithmInclude Reference to an included algorithm with optional argument overrides. Allows combining algorithms with different hyperparameter values.
Argument A function argument with explicit value specification. Value can be: literal (number/string), reference to input (input.key), or cross-observation reference (observation_name.output_key).
BidsEntities BIDS filename entities (BEP017-aligned) for provenance and data discovery. Reusable on Network, BrainAtlas, Tractogram, or any dataset with BIDS-conformant naming.
BrainAtlas A schema for representing a version of a brain atlas.
BrainRegionSeries A series whose values represent latitude
BranchSwitch Specification for switching from a detected bifurcation point to a new branch (periodic orbits from Hopf, fold continuation, etc.). Each BranchSwitch says: “from which special point on the parent branch, continue what kind of object, with what settings.” Override parent solver settings via the inline continuation field — only explicitly set attributes take effect; everything else is inherited from the parent Continuation.
ClassReference Reference to a class that can be instantiated and called. Used for external library classes (e.g., tvboptim.Bold, custom monitors). The class is instantiated with constructor_args, then called with call_args. Generalizable pattern: works for tvboptim, TVB, or any Python class.
ClinicalImprovement Relative improvement on a defined clinical score.
ClinicalScale A clinical assessment inventory or structured scale composed of multiple scores or items.
ClinicalScore Metadata about a clinical score or scale.
CommonCoordinateSpace A schema for representing a version of a common coordinate space.
ConditionalBlock A single condition and its corresponding equation segment.
Contact Individual contact on a DBS electrode.
Continuation Complete specification of a numerical continuation / bifurcation analysis. All universal solver settings live directly here. Toolkit-specific string options go in the options slot. When used inside a BranchSwitch, only explicitly set attributes override the parent’s values.
ContinuationAlgorithm Predictor-corrector algorithm for numerical continuation.
Coordinate A 3D coordinate with X, Y, Z values.
CouplingInput Specification of a coupling input channel for multi-coupling dynamics
DBSProtocol A protocol describing DBS therapy, potentially bilateral or multi-lead.
DataSource Specification for loading external/empirical data.
Dataset Collection of data related to a specific DBS study.
DerivedObservation Observation derived from one or more other observations. Examples: - fc (from bold) - single source transformation - fc_corr (from fc and fc_target) - multi-source comparison Unlike regular Observations, these don’t generate monitor classes but are computed from existing observation values.
DimensionType Dimensions along which operations can be applied
Discretization Discretization method for boundary value problems in continuation (periodic orbits, connecting orbits, quasi-periodic tori). Specifies the method; method-specific numerics go in parameters.
Distribution A probability distribution for sampling parameters or initial conditions. Standard distributions (Uniform, Gaussian) are specified by name and domain/parameters. Custom distributions use a Function for the PDF/sampling rule. Default name is Uniform when only domain is given.
EField Simulated electric field from DBS modeling.
Edge An edge in a network. Two modes: explicit (source+target set, scalar parameters in YAML) or template (no source/target, N×N matrix measure in HDF5). Both coexist in the same edges list.
Electrode Implanted DBS electrode and contact geometry.
Event A discrete or continuous event that modifies the system during simulation. Generalizes Stimulus: can represent external inputs (stimulus type), threshold-triggered state changes (continuous/discrete type), or time-scheduled interventions (preset_time type). Attaches to components (nodes/edges) or to the experiment level.
EventType Type of event triggering mechanism.
ExecutionConfig Configuration for computational execution (parallelization, precision, hardware).
Exploration Parameter space exploration (grid search, sweep).
Function A function with explicit input -> transformation -> output flow. Can be equation-based (symbolic) or software-based (callable). In a pipeline, functions are chained: output of one becomes input of next.
FunctionCall Invocation of a function in a pipeline. Can reference a defined Function by name, OR inline a callable directly for external library functions, OR inline an equation, OR use class_call for class instantiation. Mirrors Function attributes so pipeline steps can be self-contained.
GraphGenerator Backend-agnostic graph generator specification. Captures the mathematical family (type) and its parameters so that each backend can emit the correct constructor call (Graphs.jl, NetworkX, etc.). The number of nodes is always taken from Network.number_of_nodes.
InitialState How to obtain the starting equilibrium or periodic orbit for continuation. Most robust: time-integrate to steady state.
InitialStateMethod Strategy for obtaining the starting equilibrium or periodic orbit.
Integrator Fixed-step or adaptive ODE integrator with TVB-specific extensions (noise, transient time, etc.). Inherits abs_tol, rel_tol from Solver. Overrides method default to ‘euler’.
LossFunction A loss function for optimization with optional aggregation. Extends Function with aggregation specification for per-element losses.
Matrix Adjacency matrix of a network.
ModelType Coarse classification of a Dynamics model by its mathematical/biological origin. Used for filtering and display in list_db().
Network Network specification with nodes, edges, and reusable coupling configurations. Supports both explicit node/edge representation and matrix-based connectivity (Connectome compatibility).
Node A node in a network with its own dynamics and properties
NumericalDiscretizationMethod Numerical discretization method for boundary value problems (periodic orbits, connecting orbits, quasi-periodic tori).
Observation Unified class for all observation/measurement specifications. Covers monitors (BOLD, EEG), tuning observables, and derived quantities. Pipeline is a sequence of Functions with input -> output flow.
Optimization Configuration for parameter optimization. Inherits single-stage fields from OptimizationStage. For multi-stage workflows, use ‘stages’ (ignores inherited single-stage fields). Loss equation references observations directly by name.
OptimizationStage A single stage in a multi-stage optimization workflow. Stages run sequentially, with each stage potentially using different parameters, shapes, learning rates, and algorithms.
Option A toolkit-specific key-value option (string name + string value). Used for backend settings that are not universal numeric parameters (e.g., solver name, tangent method, jacobian type).
PDE Partial differential equation problem definition.
ParcellationEntity A schema for representing a parcellation entity, which is an anatomical location or study target.
ParcellationTerminology A schema for representing a parcellation terminology, which consists of parcellation entities.
PhysicalDimension Physical dimension categories for LEMS and dimensional analysis. Each dimension decomposes into SI base dimensions (M, L, T, I, K, N).
Provenance W3C PROV-O aligned provenance. Reusable on any entity (Network, TimeSeries, Dynamics, etc.).
Range Specifies a range for array generation, parameter bounds, or grid exploration.
ReductionType Operations for reducing/aggregating values across dimensions
RegionMapping Maps vertices to parent regions for hierarchical/aggregated coupling
SamplingAxis Dimension along which a distribution is sampled.
SoftwarePackage Identity information about a software package independent of a specific version requirement.
Solver Lightweight specification of a numerical ODE solver / integrator. Covers adaptive solvers (Vern9, Rodas5, Tsit5, etc.) used in shooting methods, initial-state integration, and other contexts where only the algorithm and tolerances matter.
SpecimenEnum A set of permissible types for specimens used in brain atlas creation.
StandardGraphType Well-known graph generator families with automatic backend mapping. The type field on GraphGenerator is a free string; this enum lists common types that get automatic code generation for Julia (Graphs.jl) and Python (NetworkX).
StateValue A named state variable value for per-node initialization.
StimulationSetting DBS parameters for a specific session.
Subject Human or animal subject receiving DBS.
TimeSeries Time series data from simulations or measurements. Supports BIDS-compatible export for computational modeling (BEP034).
Tractogram Reference to tractography/diffusion MRI data used to derive structural connectivity
TuningObjective Defines what the tuning algorithm optimizes for. Can be an activity target (FIC) or a connectivity target (EIB).
UnitEnum Physical units of measurement for model parameters, state variables, and integration settings. Uses conventional abbreviations as values, mapped to the QUDT ontology (http://qudt.org/vocab/unit/) with UO cross-references where available.
UpdateRule Defines how a parameter is updated based on observables. Represents iterative learning rules like FIC or EIB updates. Functions from experiment.functions are available in the equation.

Aggregation

datamodel.pydantic.Aggregation()

Specifies how to aggregate values across a dimension. Used for loss functions to define per-element loss with reduction.

AggregationType

datamodel.pydantic.AggregationType()

How to aggregate time series data

Attributes

Name Description
first First value in window
last Last value in window
mean Average over time
none No aggregation
window Sliding window aggregation

Algorithm

datamodel.pydantic.Algorithm()

A complete specification of an iterative parameter tuning algorithm. Combines update rules, objectives, observations, and hyperparameters.

AlgorithmInclude

datamodel.pydantic.AlgorithmInclude()

Reference to an included algorithm with optional argument overrides. Allows combining algorithms with different hyperparameter values.

Argument

datamodel.pydantic.Argument()

A function argument with explicit value specification. Value can be: literal (number/string), reference to input (input.key), or cross-observation reference (observation_name.output_key).

BidsEntities

datamodel.pydantic.BidsEntities()

BIDS filename entities (BEP017-aligned) for provenance and data discovery. Reusable on Network, BrainAtlas, Tractogram, or any dataset with BIDS-conformant naming.

BrainAtlas

datamodel.pydantic.BrainAtlas()

A schema for representing a version of a brain atlas.

BrainRegionSeries

datamodel.pydantic.BrainRegionSeries()

A series whose values represent latitude

BranchSwitch

datamodel.pydantic.BranchSwitch()

Specification for switching from a detected bifurcation point to a new branch (periodic orbits from Hopf, fold continuation, etc.). Each BranchSwitch says: “from which special point on the parent branch, continue what kind of object, with what settings.” Override parent solver settings via the inline continuation field — only explicitly set attributes take effect; everything else is inherited from the parent Continuation.

ClassReference

datamodel.pydantic.ClassReference()

Reference to a class that can be instantiated and called. Used for external library classes (e.g., tvboptim.Bold, custom monitors). The class is instantiated with constructor_args, then called with call_args. Generalizable pattern: works for tvboptim, TVB, or any Python class.

ClinicalImprovement

datamodel.pydantic.ClinicalImprovement()

Relative improvement on a defined clinical score.

ClinicalScale

datamodel.pydantic.ClinicalScale()

A clinical assessment inventory or structured scale composed of multiple scores or items.

ClinicalScore

datamodel.pydantic.ClinicalScore()

Metadata about a clinical score or scale.

CommonCoordinateSpace

datamodel.pydantic.CommonCoordinateSpace()

A schema for representing a version of a common coordinate space.

ConditionalBlock

datamodel.pydantic.ConditionalBlock()

A single condition and its corresponding equation segment.

Contact

datamodel.pydantic.Contact()

Individual contact on a DBS electrode.

Continuation

datamodel.pydantic.Continuation()

Complete specification of a numerical continuation / bifurcation analysis. All universal solver settings live directly here. Toolkit-specific string options go in the options slot. When used inside a BranchSwitch, only explicitly set attributes override the parent’s values.

ContinuationAlgorithm

datamodel.pydantic.ContinuationAlgorithm()

Predictor-corrector algorithm for numerical continuation.

Attributes

Name Description
MoorePenrose Moore-Penrose continuation.
Natural Natural parameter continuation. Simple parameter stepping, no arc-length constraint.
PALC Pseudo-arclength continuation (default). Uses weighted dot product constraint.

Coordinate

datamodel.pydantic.Coordinate()

A 3D coordinate with X, Y, Z values.

CouplingInput

datamodel.pydantic.CouplingInput()

Specification of a coupling input channel for multi-coupling dynamics

DBSProtocol

datamodel.pydantic.DBSProtocol()

A protocol describing DBS therapy, potentially bilateral or multi-lead.

DataSource

datamodel.pydantic.DataSource()

Specification for loading external/empirical data.

Dataset

datamodel.pydantic.Dataset()

Collection of data related to a specific DBS study.

DerivedObservation

datamodel.pydantic.DerivedObservation()

Observation derived from one or more other observations. Examples: - fc (from bold) - single source transformation - fc_corr (from fc and fc_target) - multi-source comparison Unlike regular Observations, these don’t generate monitor classes but are computed from existing observation values.

DimensionType

datamodel.pydantic.DimensionType()

Dimensions along which operations can be applied

Attributes

Name Description
batch Batch dimension (for parallel processing)
frequency Frequency dimension (spectral analysis)
mode Mode dimension (e.g., coupling modes)
node Network node dimension (general graph term)
region Spatial/regional dimension (alias for node in brain networks)
sample Sample/trial/realization dimension
state State variable dimension
time Temporal dimension

Discretization

datamodel.pydantic.Discretization()

Discretization method for boundary value problems in continuation (periodic orbits, connecting orbits, quasi-periodic tori). Specifies the method; method-specific numerics go in parameters.

Distribution

datamodel.pydantic.Distribution()

A probability distribution for sampling parameters or initial conditions. Standard distributions (Uniform, Gaussian) are specified by name and domain/parameters. Custom distributions use a Function for the PDF/sampling rule. Default name is Uniform when only domain is given.

EField

datamodel.pydantic.EField()

Simulated electric field from DBS modeling.

Edge

datamodel.pydantic.Edge()

An edge in a network. Two modes: explicit (source+target set, scalar parameters in YAML) or template (no source/target, N×N matrix measure in HDF5). Both coexist in the same edges list.

Electrode

datamodel.pydantic.Electrode()

Implanted DBS electrode and contact geometry.

Event

datamodel.pydantic.Event()

A discrete or continuous event that modifies the system during simulation. Generalizes Stimulus: can represent external inputs (stimulus type), threshold-triggered state changes (continuous/discrete type), or time-scheduled interventions (preset_time type). Attaches to components (nodes/edges) or to the experiment level.

EventType

datamodel.pydantic.EventType()

Type of event triggering mechanism.

Attributes

Name Description
continuous Triggered when condition function crosses zero (root-finding). Maps to ContinuousCallback / ContinuousComponentCallback.
discrete Triggered when condition function returns true (checked at each step). Maps to DiscreteCallback / DiscreteComponentCallback.
preset_time Triggered at predetermined time points. Maps to PresetTimeCallback / PresetTimeComponentCallback.
stimulus Continuous time-dependent input signal (e.g., external current). Legacy Stimulus behavior.

ExecutionConfig

datamodel.pydantic.ExecutionConfig()

Configuration for computational execution (parallelization, precision, hardware).

Exploration

datamodel.pydantic.Exploration()

Parameter space exploration (grid search, sweep).

Function

datamodel.pydantic.Function()

A function with explicit input -> transformation -> output flow. Can be equation-based (symbolic) or software-based (callable). In a pipeline, functions are chained: output of one becomes input of next.

FunctionCall

datamodel.pydantic.FunctionCall()

Invocation of a function in a pipeline. Can reference a defined Function by name, OR inline a callable directly for external library functions, OR inline an equation, OR use class_call for class instantiation. Mirrors Function attributes so pipeline steps can be self-contained.

GraphGenerator

datamodel.pydantic.GraphGenerator()

Backend-agnostic graph generator specification. Captures the mathematical family (type) and its parameters so that each backend can emit the correct constructor call (Graphs.jl, NetworkX, etc.). The number of nodes is always taken from Network.number_of_nodes.

InitialState

datamodel.pydantic.InitialState()

How to obtain the starting equilibrium or periodic orbit for continuation. Most robust: time-integrate to steady state.

InitialStateMethod

datamodel.pydantic.InitialStateMethod()

Strategy for obtaining the starting equilibrium or periodic orbit.

Attributes

Name Description
from_branch Start from a point on a previously computed branch.
given Use the model’s default initial values directly.
newton Use Newton’s method to find the nearest fixed point.
time_integration Integrate the ODE forward until convergence (robust, default).

Integrator

datamodel.pydantic.Integrator()

Fixed-step or adaptive ODE integrator with TVB-specific extensions (noise, transient time, etc.). Inherits abs_tol, rel_tol from Solver. Overrides method default to ‘euler’.

LossFunction

datamodel.pydantic.LossFunction()

A loss function for optimization with optional aggregation. Extends Function with aggregation specification for per-element losses.

Matrix

datamodel.pydantic.Matrix()

Adjacency matrix of a network.

ModelType

datamodel.pydantic.ModelType()

Coarse classification of a Dynamics model by its mathematical/biological origin. Used for filtering and display in list_db().

Attributes

Name Description
field Spatially distributed neural-field models described by integro- differential or PDE formulations.
generic Generic / normal-form dynamical systems not specific to neural modelling (e.g. Generic2dOscillator, GenericLinear).
mean_field Mathematically derived mean-field models obtained by exact reduction of spiking networks (Ott-Antonsen ansatz, Lorentzian heterogeneity, etc.). Examples: MontbrioPazoRoxin, CoombesByrne, ReducedWongWang, ZerlautAdaptationFirstOrder.
neural_mass Phenomenological population-rate / neural-mass models that describe synaptic and firing-rate dynamics without an explicit derivation from single-neuron statistics. Examples: JansenRit, WilsonCowan, LarterBreakspear, TsodyksMarkram.
phase_oscillator Phase-reduced or Kuramoto-type oscillator models. Examples: Kuramoto, SupHopf.
phenomenological Empirical / phenomenological models that capture macroscopic dynamics without direct biophysical derivation. Examples: Epileptor2D, Epileptor5D.
spiking Single-neuron or conductance-based spiking models (HH, AdEx, LIF, Izhikevich, etc.). These can be used as nodes in a network alongside mean-field models.

Network

datamodel.pydantic.Network()

Network specification with nodes, edges, and reusable coupling configurations. Supports both explicit node/edge representation and matrix-based connectivity (Connectome compatibility).

Node

datamodel.pydantic.Node()

A node in a network with its own dynamics and properties

NumericalDiscretizationMethod

datamodel.pydantic.NumericalDiscretizationMethod()

Numerical discretization method for boundary value problems (periodic orbits, connecting orbits, quasi-periodic tori).

Attributes

Name Description
collocation Orthogonal collocation at Gauss points.
poincare Poincaré shooting.
shooting Standard multiple shooting.
trapezoid Trapezoidal rule discretization.

Observation

datamodel.pydantic.Observation()

Unified class for all observation/measurement specifications. Covers monitors (BOLD, EEG), tuning observables, and derived quantities. Pipeline is a sequence of Functions with input -> output flow.

Optimization

datamodel.pydantic.Optimization()

Configuration for parameter optimization. Inherits single-stage fields from OptimizationStage. For multi-stage workflows, use ‘stages’ (ignores inherited single-stage fields). Loss equation references observations directly by name.

OptimizationStage

datamodel.pydantic.OptimizationStage()

A single stage in a multi-stage optimization workflow. Stages run sequentially, with each stage potentially using different parameters, shapes, learning rates, and algorithms.

Option

datamodel.pydantic.Option()

A toolkit-specific key-value option (string name + string value). Used for backend settings that are not universal numeric parameters (e.g., solver name, tangent method, jacobian type).

PDE

datamodel.pydantic.PDE()

Partial differential equation problem definition.

ParcellationEntity

datamodel.pydantic.ParcellationEntity()

A schema for representing a parcellation entity, which is an anatomical location or study target.

ParcellationTerminology

datamodel.pydantic.ParcellationTerminology()

A schema for representing a parcellation terminology, which consists of parcellation entities.

PhysicalDimension

datamodel.pydantic.PhysicalDimension()

Physical dimension categories for LEMS and dimensional analysis. Each dimension decomposes into SI base dimensions (M, L, T, I, K, N).

Attributes

Name Description
capacitance Capacitance [M⁻¹ L⁻² T⁴ I²]
charge Electric charge [T I]
concentration Concentration [L⁻³ N]
conductance Conductance [M⁻¹ L⁻² T³ I²]
current Electric current [I]
length Length [L]
none Dimensionless
per_time Inverse time [T⁻¹]
resistance Resistance [M L² T⁻³ I⁻²]
substance Amount of substance [N]
temperature Temperature [K]
time Time [T]
voltage Voltage [M L² T⁻³ I⁻¹]
volume Volume [L³]

Provenance

datamodel.pydantic.Provenance()

W3C PROV-O aligned provenance. Reusable on any entity (Network, TimeSeries, Dynamics, etc.).

Range

datamodel.pydantic.Range()

Specifies a range for array generation, parameter bounds, or grid exploration.

ReductionType

datamodel.pydantic.ReductionType()

Operations for reducing/aggregating values across dimensions

Attributes

Name Description
max Maximum value
mean Arithmetic mean
min Minimum value
none No reduction (return per-element values)
sum Sum of values

RegionMapping

datamodel.pydantic.RegionMapping()

Maps vertices to parent regions for hierarchical/aggregated coupling

SamplingAxis

datamodel.pydantic.SamplingAxis()

Dimension along which a distribution is sampled.

Attributes

Name Description
space Sample once per node (heterogeneous parameter or spatially varying IC).
time Resample every integration timestep (stochastic time-varying input).

SoftwarePackage

datamodel.pydantic.SoftwarePackage()

Identity information about a software package independent of a specific version requirement.

Solver

datamodel.pydantic.Solver()

Lightweight specification of a numerical ODE solver / integrator. Covers adaptive solvers (Vern9, Rodas5, Tsit5, etc.) used in shooting methods, initial-state integration, and other contexts where only the algorithm and tolerances matter.

SpecimenEnum

datamodel.pydantic.SpecimenEnum()

A set of permissible types for specimens used in brain atlas creation.

StandardGraphType

datamodel.pydantic.StandardGraphType()

Well-known graph generator families with automatic backend mapping. The type field on GraphGenerator is a free string; this enum lists common types that get automatic code generation for Julia (Graphs.jl) and Python (NetworkX).

Attributes

Name Description
BarabasiAlbert Barabasi-Albert preferential attachment (params: k)
Complete Complete graph (all-to-all)
Cycle Cycle graph (ring)
ErdosRenyi Erdos-Renyi random graph (params: p)
Grid Grid/lattice graph (params: dims)
RandomRegular Random regular graph (params: k)
Star Star graph
WattsStrogatz Watts-Strogatz small-world (params: k, p)

StateValue

datamodel.pydantic.StateValue()

A named state variable value for per-node initialization.

StimulationSetting

datamodel.pydantic.StimulationSetting()

DBS parameters for a specific session.

Subject

datamodel.pydantic.Subject()

Human or animal subject receiving DBS.

TimeSeries

datamodel.pydantic.TimeSeries()

Time series data from simulations or measurements. Supports BIDS-compatible export for computational modeling (BEP034).

Tractogram

datamodel.pydantic.Tractogram()

Reference to tractography/diffusion MRI data used to derive structural connectivity

TuningObjective

datamodel.pydantic.TuningObjective()

Defines what the tuning algorithm optimizes for. Can be an activity target (FIC) or a connectivity target (EIB).

UnitEnum

datamodel.pydantic.UnitEnum()

Physical units of measurement for model parameters, state variables, and integration settings. Uses conventional abbreviations as values, mapped to the QUDT ontology (http://qudt.org/vocab/unit/) with UO cross-references where available.

Attributes

Name Description
A Ampere
H_per_m Henry per metre (permeability)
Hz Hertz (s⁻¹)
Hz_per_nA Hertz per nanoampere (neural gain)
N_per_m Newton per metre (spring constant)
S_per_m Siemens per metre (conductivity)
V Volt
arbitrary_unit Arbitrary units (a.u.)
cm Centimetre
dimensionless Dimensionless (unitless)
kHz Kilohertz
kg Kilogram
kg_per_s Kilogram per second
m Metre
mV Millivolt
mV_per_ms Millivolt per millisecond
mV_per_s Millivolt per second
m_per_s Metre per second
m_per_s2 Metre per second squared (acceleration)
mm Millimetre
mm_per_ms Millimetre per millisecond (= m/s)
mmol_per_m3 Millimole per cubic metre (mmol/m³ ≈ mM)
mol_per_m3 Mole per cubic metre (mol/m³)
ms Millisecond
nA Nanoampere
nF Nanofarad
nS Nanosiemens
pA Picoampere
pF Picofarad
per_mV Reciprocal millivolt (mV⁻¹)
per_ms Per millisecond (ms⁻¹)
per_nC Reciprocal nanocoulomb (nC⁻¹)
per_pC Reciprocal picocoulomb (pC⁻¹)
per_s Per second (s⁻¹)
per_unit Per-unit (dimensionless power-systems convention)
percent Percent (%)
rad Radian
rad_per_ms Radian per millisecond
rad_per_s Radian per second (angular velocity)
s Second
s2 Second squared (inertia constant)
uS Microsiemens
um3 Cubic micrometre (µm³)
us Microsecond

UpdateRule

datamodel.pydantic.UpdateRule()

Defines how a parameter is updated based on observables. Represents iterative learning rules like FIC or EIB updates. Functions from experiment.functions are available in the equation.