API and documentation

C++ models

vbi.models.cpp.jansen_rit

class JR_sde(par={})

Jansen-Rit model C++ implementation.

Parameters:

par: dict

Including the following: - A : [mV] determine the maximum amplitude of the excitatory PSP (EPSP) - B : [mV] determine the maximum amplitude of the inhibitory PSP (IPSP) - a : [Hz] 1/tau_e, \(\sum\) of the reciprocal of the time constant of passive membrane and all other spatially distributed delays in the dendritic network - b : [Hz] 1/tau_i - r [mV] the steepness of the sigmoidal transformation. - v0 parameter of nonlinear sigmoid function - vmax parameter of nonlinear sigmoid function - C_i [list or np.array] average number of synaptic contacts in th inhibitory and excitatory feedback loops - noise_amp - noise_std

• dt [second] integration time step

• t_initial [s] initial time

• t_end [s] final time

• method [str] method of integration

• t_transition [s] time to reach steady state

• dim [int] dimention of the system

valid_params = ['noise_seed', 'seed', 'G', 'weights', 'A', 'B', 'a', 'b', 'noise_mu', 'noise_std', 'vmax', 'v0', 'r', 'C0', 'C1', 'C2', 'C3', 'dt', 'method', 't_transition', 't_end', 'control', 'output', 'RECORD_AVG', 'initial_state']

check_parameters(par)

Check if the parameters are valid.

get_default_parameters()

return default parameters for the Jansen-Rit sde model.

set_initial_state()

Set initial state for the system of JR equations with N nodes.

prepare_input()

prepare input parameters for passing to C++ engine.

run(par={}, x0=None, verbose=False)

Integrate the system of equations for Jansen-Rit sde model.

Parameters:

par: dict

parameters to control the Jansen-Rit sde model.

x0: np.array

initial state

verbose: bool

print the message if True

Returns:

dict

• t : time series

• x : state variables

class JR_sdde(par={})

valid_params = ['weights', 'delays', 'dt', 't_end', 'G', 'A', 'a', 'B', 'b', 'mu', 'nstart', 't_end', 't_transition', 'sigma', 'C', 'record_step', 'C0', 'C1', 'C2', 'C3', 'vmax', 'r', 'v0', 'output', 'sti_ti', 'sti_duration', 'sti_amplitude', 'sti_gain', 'noise_seed', 'seed', 'method']

check_parameters(par)

check if the parameters are valid

get_default_parameters()

get default parameters for the system of JR equations.

prepare_stimulus(sti_gain, sti_ti)

prepare stimulation parameteres

set_initial_state()

set initial state for the system of JR equations with N nodes.

prepare_input()

prepare input parameters for C++ code.

run(par={}, x0=None, verbose=False)

Integrate the system of equations for Jansen-Rit model.

check_sequence(x, n)

check if x is a scalar or a sequence of length n

Parameters:

x: scalar or sequence of length n

n: number of nodes

Returns:

x: sequence of length n

set_initial_state(nn, seed=None)

set initial state for the system of JR equations with N nodes.

Parameters:

nn: number of nodes

seed: random seed

Returns:

y: initial state of length 6N

vbi.models.cpp.km

class KM_sde(par)

Kuramoto model with noise (sde), C++ implementation.

Parameters:

pardict

Dictionary of parameters.

valid_parameters = ['G', 'dt', 'noise_amp', 'omega', 'weights', 'noise_seed', 'seed', 'alpha', 't_initial', 't_transition', 't_end', 'output', 'num_threads', 'initial_state', 'type']

set_initial_state()

get_default_parameters()

check_parameters(par)

prepare_input()

run(par={}, x0=None, verbose=False)

Simulate the model.

Parameters:

pardict

Dictionary of parameters.

x0array

Initial state.

verbosebool

Print simulation progress.

Returns:

dict

tarray

Time points.

xarray

State time series.

set_initial_state(num_nodes, seed=None)

vbi.models.cpp.mpr

class MPR_sde(par: dict = {}, parbold={})

MPR model

set_initial_state()

check_parameters(par: dict)

get_default_parameters()

prepare_input()

Prepare input parameters for passing to C++ engine.

run(par: dict = {}, x0: ndarray | None = None, verbose: bool = False)

Integrate the MPR model with the given parameters.

Parameters:

pardict

Dictionary of parameters.

x0array_like

Initial condition of the system.

verbosebool

If True, print the progress of the simulation.

Returns:

boldarray_like

Simulated BOLD signal.

class BoldParams(par={})

check_parameters(par)

get_default_parameters()

get_params()

check_sequence(x: int | float | ndarray, n: int)

check if x is a scalar or a sequence of length n

Parameters:

x: scalar or sequence of length n

n: number of nodes

Returns:

x: sequence of length n

set_initial_state(nn, seed=None)

vbi.models.cpp.vep

class VEP(par: dict = {})

Virtual Epileptic Patient (VEP) model

set_initial_state()

check_parameters(par: dict)

prepare_input()

get_default_parameters()

run(par: dict = {}, x0: ndarray | None = None, verbose: bool = False)

set_initial_state(nn: int, seed: int | None = None)

check_sequence(x: int | float | ndarray, n: int)

check if x is a scalar or a sequence of length n

Parameters:

x: scalar or sequence

n: number of elements

Returns:

x: sequence of length n

vbi.models.cpp.wc

class WC_ode(par={})

References:

[WC_1972] (1,2)

Wilson, H.R. and Cowan, J.D. Excitatory and inhibitory interactions in localized populations of model neurons, Biophysical journal, 12: 1-24, 1972.

[WC_1973]

Wilson, H.R. and Cowan, J.D A Mathematical Theory of the Functional Dynamics of Cortical and Thalamic Nervous Tissue

[D_2011]

Daffertshofer, A. and van Wijk, B. On the influence of amplitude on the connectivity between phases Frontiers in Neuroinformatics, July, 2011

Used Eqns 11 and 12 from [WC_1972] in rhs. P and Q represent external inputs, which when exploring the phase portrait of the local model are set to constant values. However in the case of a full network, P and Q are the entry point to our long range and local couplings, that is, the activity from all other nodes is the external input to the local population [WC_1973], [D_2011] .

The default parameters are taken from figure 4 of [WC_1972], pag. 10.

check_parameters(par)

get_default_parameters()

set_initial_state(seed=None)

prepare_input()

run(par={}, x0=None, verbose=False)

Integrate the system of equations for the Wilson-Cowan model.

Parameters:

pardict

Dictionary with parameters of the model.

x0array-like

Initial state of the system.

verbosebool

If True, print the integration progress.

check_sequence(x, n)

check if x is a scalar or a sequence of length n

Parameters:

x: scalar or sequence of length n

n: number of nodes

Returns:

x: sequence of length n

Cupy models

vbi.models.cupy.mpr

class Bold(par: dict = {})

get_default_parameters()

get balloon model parameters.

update_dependent_parameters()

check_parameters(par)

allocate_memory(xp, nn, ns, n_steps, bold_decimate, dtype)

do_bold_step(r_in, dtt)

class MPR_sde(par: dict = {}, Bpar: dict = {})

Montbrio-Pazo-Roxin model Cupy and Numpy implementation.

Parameters:

G: float. np.ndarray

global coupling strength

dt: float

time step

dt_bold: float

time step for Balloon model

J: float, np.ndarray

model parameter

eta: float, np.ndarray

model parameter

tau:

model parameter

delta:

model parameter

tr: float

repetition time of fMRI

noise_amp: float

amplitude of noise

same_noise_per_sim:

same noise for all simulations

iapp: float, np.ndarray

external input

t_start: float

initial time

t_cut: float

transition time

t_end: float

end time

num_nodes: int

number of nodes

weights: np.ndarray

weighted connection matrix

rv_decimate: int

sampling step from r and v

output: str

output directory

RECORD_TS: bool

store r and v time series

num_sim: int

number of simulations

method: str

integration method

engine: str

cpu or gpu

seed: int

seed for random number generator

dtype: str

float or f

initial_state: np.ndarray

initial state

same_initial_state: bool

same initial state for all simulations

set_initial_state()

get_default_parameters()

check_parameters(par)

prepare_input()

f_mpr(x, t)

MPR model

heunStochastic(y, t, dt)

Heun scheme to integrate MPR model with noise.

sync_(engine='gpu')

run(verbose=True)

set_initial_state(nn, ns, engine, seed=None, same_initial_state=False, dtype=<class 'float'>)

Set initial state

Parameters:

nnint

number of nodes

nsint

number of simulations

enginestr

cpu or gpu

same_initial_conditionbool

same initial condition for all simulations

seedint

random seed

dtypestr

float: float64 f : float32

vbi.models.cupy.ghb

vbi.models.cupy.jansen_rit

class JR_sde(par: dict = {})

Jansen-Rit model cupy implementation.

Parameters

Name	Explanation	Default Value
A	Excitatory post synaptic potential amplitude.	3.25
B	Inhibitory post synaptic potential amplitude.	22.0
1/a	Time constant of the excitatory postsynaptic potential.	a: 0.1 (1/a: 10.0)
1/b	Time constant of the inhibitory postsynaptic potential.	b: 0.05 (1/b: 20.0)
C0, C1	Average numbers of synapses between excitatory populations. If array-like, it should be the shape of (num_nodes, num_sim).	C0: 1.0 * 135.0, C1: 0.8 * 135.0
C2, C3	Average numbers of synapses between inhibitory populations. If array-like, it should be the shape of (num_nodes, num_sim).	C2: 0.25 * 135.0, C3: 0.25 * 135.0
vmax	Maximum firing rate	0.005
v	Potential at half of maximum firing rate	6.0
r	Slope of sigmoid function at v_0	0.56
G	Scaling the strength of network connections. If array-like, it should of length num_sim.	1.0
mu	Mean of the noise	0.24
noise_amp	Amplitude of the noise	0.01
weights	Weight matrix of shape (num_nodes, num_nodes)	None
num_sim	Number of simulations	1
dt	Time step	0.01
t_end	End time of simulation	1000.0
t_cut	Cut time	500.0
engine	“cpu” or “gpu”	“cpu”
method	“heun” or “euler” method for integration	“heun”
seed	Random seed	None
initial_state	Initial state of the system of shape (num_nodes, num_sim)	None
same_initial_state	If True, all simulations have the same initial state	False
same_noise_per_sim	If True, all simulations have the same noise	False
decimate	Decimation factor for the output time series	1
dtype	Data type to use for the simulation, float for float64 or f for float32.	“float”

check_parameters(par)

Check if the provided parameters are valid.

Parameters:

pardict

Dictionary of parameters to check.

Raises:

ValueError

If any parameter in par is not valid.

set_initial_state()

get_default_parameters() → dict

Default parameters for the Jansen-Rit model

Parameters:

nnint

number of nodes

Returns:

paramsdict

default parameters

prepare_input()

Prepare input parameters for the Jansen-Rit model.

S_(x)

Compute the sigmoid function.

This function calculates the sigmoid of the input x using the parameters vmax, r, and v0.

Parameters:

xfloat or array-like

The input value(s) for which to compute the sigmoid function.

Returns:

float or array-like

The computed sigmoid value(s).

f_sys(x0, t)

Compute the derivatives of the Jansen-Rit neural mass model.

Parameters:

x0array_like

Initial state vector of the system. It should have a shape of (6*nn, ns), where nn is the number of neurons and ns is the number of simulations.

tfloat

Current time point (not used in the computation but required for compatibility with ODE solvers).

Returns:

dxarray_like

Derivatives of the state vector. It has the same shape as x0.

The function computes the derivatives of the state vector based on the Jansen-Rit model equations.

euler(x0, t)

Perform one step of the Euler-Maruyama method for stochastic differential equations.

Parameters:

x0array_like

The initial state of the system.

tfloat

The current time.

Returns:

array_like

The updated state of the system after one Euler step.

heun(x0, t)

Perform a single step of the Heun’s method for stochastic differential equations.

Parameters:

x0ndarray

The initial state of the system.

tfloat

The current time.

Returns:

ndarray

The updated state of the system after one Heun step.

run(x0=None)

Simulate the Jansen-Rit model.

Parameters:

x0: array [num_nodes, num_sim]

initial state

Returns:

dict: simulation results

t: array [n_step]

time

x: array [n_step, num_nodes, num_sim]

y1-y2 time series

set_initial_state(nn, ns, engine, seed=None, same_initial_state=False, dtype='float')

set initial state for the Jansen-Rit model

Parameters:

nn: int

number of nodes

ns: int

number of simulations

engine: str

cpu or gpu

seed: int

random seed

same_initial_state: bool

if True, all simulations have the same initial state

dtype: str

data type

Returns:

y0: array [nn, ns]

initial state

vbi.models.cupy.utils

get_module(engine='gpu')

Switches the computational engine between GPU and CPU.

Parameters:

enginestr, optional

The computational engine to use. Can be either “gpu” or “cpu”. Default is “gpu”.

Returns:

module

The appropriate array module based on the specified engine. If “gpu”, returns the CuPy module. If “cpu”, returns the NumPy module.

Raises:

ValueError

• If the specified engine is not “gpu” or “cpu”.

• If CuPy is not installed.

tohost(x)

move data to cpu if it is on gpu

Parameters:

x: array

data

Returns:

array

data moved to cpu

todevice(x)

move data to gpu

Parameters:

x: array

data

Returns:

array

data moved to gpu

move_data(x, engine)

repmat_vec(vec, ns, engine)

repeat vector ns times

Parameters:

vec: array 1d

vector to be repeated

ns: int

number of repetitions

engine: str

cpu or gpu

Returns:

vec: array [len(vec), n_sim]

repeated vector

is_seq(x)

check if x is a sequence

Parameters:

x: any

variable to be checked

Returns:

bool

True if x is a sequence

prepare_vec(x, ns, engine, dtype='float')

check and prepare vector dimension and type

Parameters:

x: array 1d

vector to be prepared, if x is a scalar, only the type is changed

ns: int

number of simulations

engine: str

cpu or gpu

Returns:

x: array [len(x), n_sim]

prepared vector

get_(x, engine='cpu', dtype='f')

Parameters:

xarray-like

The input array to be converted.

enginestr, optional

The computation engine to use. If “gpu”, the array is transferred from GPU to CPU. Defaults to “cpu”.

dtypestr, optional

The desired data type for the output array. Defaults to “f”.

Returns:

array-like

The converted array with the specified data type.