API Reference

This section provides a comprehensive reference for all public APIs in the brainmass package. The package is organized into several main categories that follow the hierarchical structure of whole-brain network modeling:

Structural Connectivity (DTI / Structural MRI)
   ↓
Neural Mass Models (NMMs)
   ↓
Biophysical Forward Model
   ↓
Observed Signals (EEG, MEG, fMRI BOLD)

Package Contents

The brainmass package provides the following components:

Component	Description
Neural Mass Models	Neural mass models for phenomenological and physiological brain dynamics
Noise Processes	Stochastic noise processes for adding realistic variability
Coupling Mechanisms	Coupling mechanisms for connecting regions in brain networks
Forward Models	Forward models for mapping neural activity to observed signals (BOLD, EEG/MEG)
Observation Models	Observation models: convolution BOLD (HRF kernels) and temporal averaging
HORN Models	Harmonic Oscillator Recurrent Networks (HORN) for sequence learning
Orchestration	Simulator driver and composable objective builders for fitting
Datasets	Bundled example data and the extensible dataset registry
Visualization	Thin plotting helpers for time series, connectivity, and spectra
Utilities & Types	Utility functions, the model catalogue, and public type aliases

Quick Navigation

Neural Mass Models

Phenomenological and physiological models for simulating neural population dynamics

Neural Mass Models

Noise Processes

Stochastic processes including OU, Gaussian, colored noise, and Brownian motion

Noise Processes

Coupling Mechanisms

Diffusive and additive coupling for multi-region brain networks

Coupling Mechanisms

Forward Models

BOLD hemodynamics and EEG/MEG lead-field models

Forward Models

Observation Models

Convolution BOLD (HRF kernels) and temporal averaging

Observation Models

HORN Models

Harmonic oscillator recurrent networks for temporal sequences

HORN Models

Orchestration

Simulator run loop and composable objective builders for parameter fitting

Orchestration

Datasets

Bundled example data and the extensible dataset registry

Datasets

Visualization

Thin plotting helpers for time series, connectivity, and spectra

Visualization

Utilities & Types

Helper functions and type definitions

Utilities & Types

General API Conventions

High-level entry points:

Most workflows go through three orchestration classes (see Orchestration) rather than driving the step models by hand:

• Simulator – wraps any model (a single node or a whole-brain Network) in the compiled run loop and collects monitored trajectories into a unit-aware result dict.

• Network – wires a node model into a delay-coupled whole-brain network from a connectome.

• Fitter – fits a model’s trainable parameters to data behind one .fit call, swapping gradient / Nevergrad / SciPy backends.

The per-step conventions below describe the underlying model contract that these entry points build on.

Initialization:

model = brainmass.ModelName(in_size=..., **parameters)
model.init_all_states(batch_size=None)

• in_size: Shape of the input (number of regions/nodes)

• Parameters are keyword arguments with default values

• init_state() must be called before simulation

Dynamics:

output = model.update(**inputs)

• update() advances the model by one time step

• Returns observable(s) relevant to the model

• Internal states are accessible as .value attributes

Units:

All models are unit-aware via brainunit:

• Time constants: typically u.ms or u.s

• Firing rates: typically u.Hz

• Membrane potentials: typically u.mV

• Quantities can be passed as float (unitless) or brainunit.Quantity