Simulator

models Package

# Coupling¶

Coupling functions

The activity (state-variables) that have been propagated over the long-range Connectivity pass through these functions before entering the equations (Model.dfun()) describing the local dynamics.

The state-variable vector for the $k$-th node or region in the network can be expressed as: Derivative = Noise + Local dynamics + Coupling(time delays).

More formally:

$\dot{\Psi}_{k} = - \Lambda\left(\Psi_{k}\right) + Z \left(\Xi_{k} + \sum_{j=1}^{l} u_{kj} \Gamma_{v=2}[\left(\Psi_{k}(t), \Psi_{j}(t-\tau_{kj}\right)]\right).$

Here we compute the term Coupling(time delays) or $$\sum_{j=1}^{l} u_{kj} \Gamma_{v=2}[\left(\Psi_{k}(t), \Psi_{j}(t-\tau_{kj}\right)]$$, where $$u_{kj}$$ are the elements of the weights matrix from a Connectivity datatype.

This term is equivalent to the dot product between the weights matrix (on the left) and the delayed state vector. This order is important in the case case of an asymmetric connectivity matrix, where the convention to distinguish target ($k$) and source ($j$) nodes is the following:

$\begin{split}\left(\begin{matrix} a & b \ c & d \end{matrix}\right)\end{split}$$\begin{split} C_{kj} &= \left(\begin{matrix} ^\mathrm{To}/_\mathrm{from} & 0 & 1 & 2 & \cdots & l \ 0 & 1 & 1 & 0 & 1 & 0 \ 1 & 1 & 1 & 0 & 1 & 0 \ 2 & 1 & 0 & 0 & 1 & 0 \ \vdots & 1 & 0 & 1 & 0 & 1 \ l & 0 & 0 & 0 & 0 & 0 \ \end{matrix}\right)\end{split}$
tvb.simulator.coupling.Coupling[source]

The base class for Coupling functions.

Instances of the Coupling class are called by the simulator in the following way:

$k_i = coupling(g_ij, x_i, x_j)$

where g_ij is the connectivity weight matrix, x_i is the current state, x_j is the delayed state of the coupling variables chosen for the simulation, and k_i is the input to the ith node due to the coupling between the nodes.

Coupling functions can all be defined as a combination of a pre-“synaptic” or pre-summation function, the summation over weighted afferents and the post-“synaptic” or post-summation function. Therefore, a Coupling subclass should not define the __call__ method directly but rather appropriate pre and post methods, which are used by Coupling.__call__ to compute the coupling correctly.

Default implementations of pre and post are provided, which simply apply the connectivity to afferent activity, without scaling or other changes.

PreSigmoidal.__call__(step, history, na=None)[source]

traits on this class:

tvb.simulator.coupling.SparseCoupling[source]

A coupling implementation which takes advantage of a sparse weights structure to reduce the number of coupling terms evaluated.

traits on this class:

tvb.simulator.coupling.Linear[source]

Provides a linear coupling function of the following form

$a x + b$

traits on this class:

a ($$a$$)
Rescales the connection strength while maintaining the ratio between different values.
default: [ 0.00390625]
range: low = 0.0 ; high = 1.0
b ($$b$$)
Shifts the base of the connection strength while maintaining the absolute difference between different values.
default: [ 0.]
tvb.simulator.coupling.Scaling[source]

Provides a simple scaling of the connectivity of the form

$a x$

traits on this class:

a (Scaling factor)
Rescales the connection strength while maintaining the ratio between different values.
default: 0.00390625
range: low = 0.0 ; high = 1.0
tvb.simulator.coupling.HyperbolicTangent[source]

Provides a sigmoidal coupling function of the form

$a * (1 + tanh((x - midpoint)/sigma))$
NB: This coupling function is applied pre-summation. For a post-summation
sigmoidal, see Sigmoidal.

traits on this class:

a ($$a$$)
Minimum of the sigmoid function
default: [ 1.]
range: low = -1000.0 ; high = 1000.0
b ($$b$$)
Scaling factor for the variable
default: [ 1.]
range: low = -1.0 ; high = 1.0
midpoint (midpoint)
Midpoint of the linear portion of the sigmoid
default: [ 0.]
range: low = -1000.0 ; high = 1000.0
sigma ($$\sigma$$)
Standard deviation of the coupling
default: [ 1.]
range: low = 0.01 ; high = 1000.0
tvb.simulator.coupling.Sigmoidal[source]

Provides a sigmoidal coupling function of the form

$c_{min} + (c_{max} - c_{min}) / (1.0 + \exp(-a(x-midpoint)/\sigma))$
NB: using a = numpy.pi / numpy.sqrt(3.0) and the default parameter
produces something close to the current default for Linear (a=0.00390625, b=0) over the linear portion of the sigmoid, with saturation at -1 and 1.

traits on this class:

a ($$a$$)
Scaling of sigmoidal
default: [ 1.]
range: low = 0.01 ; high = 1000.0
cmax ($$c_{max}$$)
Maximum of the sigmoid function
default: [ 1.]
range: low = -1000.0 ; high = 1000.0
cmin ($$c_{min}$$)
Minimum of the sigmoid function
default: [-1.]
range: low = -1000.0 ; high = 1000.0
midpoint (midpoint)
Midpoint of the linear portion of the sigmoid
default: [ 0.]
range: low = -1000.0 ; high = 1000.0
sigma ($$\sigma$$)
Standard deviation of the sigmoidal
default: [ 230.]
range: low = 0.01 ; high = 1000.0
tvb.simulator.coupling.SigmoidalJansenRit[source]

Provides a sigmoidal coupling function as described in the Jansen and Rit model, of the following form

$c_{min} + (c_{max} - c_{min}) / (1.0 + \exp(-a(x-midpoint)/\sigma))$

Assumes that x has have two state variables.

traits on this class:

a ($$a$$)
Scaling of the coupling term
default: [ 0.56]
range: low = 0.01 ; high = 1000.0
cmax ($$c_{max}$$)
Maximum of the sigmoid function
default: [ 0.005]
range: low = -1000.0 ; high = 1000.0
cmin ($$c_{min}$$)
Minimum of the sigmoid function
default: [ 0.]
range: low = -1000.0 ; high = 1000.0
midpoint (midpoint)
Midpoint of the linear portion of the sigmoid
default: [ 6.]
range: low = -1000.0 ; high = 1000.0
r ($$r$$)
the steepness of the sigmoidal transformation
default: [ 1.]
range: low = 0.01 ; high = 1000.0
tvb.simulator.coupling.PreSigmoidal[source]

Provides a pre-summation sigmoidal coupling function with a static or dynamic and local or global threshold.

$H * (Q + \tanh(G * (P*x - \theta)))$

The dynamic threshold as state variable given by the second state variable. With the coupling term, returns the direct node output for the dynamic threshold.

traits on this class:

G (G)
Gain.
default: [ 60.]
range: low = -1000.0 ; high = 1000.0
H (H)
Global Factor.
default: [ 0.5]
range: low = -100.0 ; high = 100.0
P (P)
Excitation-Inhibition ratio.
default: [ 1.]
range: low = -100.0 ; high = 100.0
Q (Q)
Average.
default: [ 1.]
range: low = -100.0 ; high = 100.0
dynamic (Dynamic)
Use dynamic threshold (otherwise static).
default: True
globalT ($$global_{\theta}$$)
Use global threshold (otherwise local).
default: False
theta ($$\theta$$)
Threshold.
default: [ 0.5]
range: low = -100.0 ; high = 100.0
tvb.simulator.coupling.Difference[source]

Provides a difference coupling function, between pre and post synaptic activity of the form

$a G_ij (x_j - x_i)$

traits on this class:

a ($$a$$)
Rescales the connection strength.
default: [ 0.1]
range: low = 0.0 ; high = 10.0
tvb.simulator.coupling.Kuramoto[source]

Provides a Kuramoto-style coupling, a periodic difference of the form

$a / N G_ij sin(x_j - x_i)$

traits on this class:

a ($$a$$)
Rescales the connection strength.
default: [ 1.]
range: low = 0.0 ; high = 1.0