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{align}\begin{aligned}\left(\begin{matrix} a & b \ c & d \end{matrix}\right)\\ 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{aligned}\end{align} \]

class tvb.simulator.coupling.Coupling(**kwargs)

Traited class [tvb.simulator.coupling.Coupling]

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)

Call self as a function.

Attributes declared

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

pre(x_i, x_j)

post(gx)

class tvb.simulator.coupling.SparseCoupling(**kwargs)

Traited class [tvb.simulator.coupling.SparseCoupling]

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

Attributes declared

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

class tvb.simulator.coupling.Linear(**kwargs)

Traited class [tvb.simulator.coupling.Linear]

Provides a linear coupling function of the following form

\[a x + b\]

Attributes declared

atvb.simulator.coupling.Linear.a = NArray(label=’\(a\)’, dtype=float64, default=array([0.00390625]), dim_names=(), ndim=None, required=True)

Rescales the connection strength while maintaining the ratio between different values.

btvb.simulator.coupling.Linear.b = NArray(label=’\(b\)’, dtype=float64, default=array([0.]), dim_names=(), ndim=None, required=True)

Shifts the base of the connection strength while maintaining the absolute difference between different values.

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

b

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

parameter_names = ['a', 'b']

pre_expr = 'x_j'

post_expr = 'a * gx + b'

post(gx)

class tvb.simulator.coupling.Scaling(**kwargs)

Traited class [tvb.simulator.coupling.Scaling]

Provides a simple scaling of the connectivity of the form

\[a x\]

Attributes declared

atvb.simulator.coupling.Scaling.a = NArray(label=’Scaling factor’, dtype=float64, default=array([0.00390625]), dim_names=(), ndim=None, required=True)

Rescales the connection strength while maintaining the ratio between different values.

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

post(gx)

class tvb.simulator.coupling.HyperbolicTangent(**kwargs)

Traited class [tvb.simulator.coupling.HyperbolicTangent]

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.

Attributes declared

atvb.simulator.coupling.HyperbolicTangent.a = NArray(label=’\(a\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Minimum of the sigmoid function

btvb.simulator.coupling.HyperbolicTangent.b = NArray(label=’\(b\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Scaling factor for the variable

midpointtvb.simulator.coupling.HyperbolicTangent.midpoint = NArray(label=’midpoint’, dtype=float64, default=array([0.]), dim_names=(), ndim=None, required=True)

Midpoint of the linear portion of the sigmoid

sigmatvb.simulator.coupling.HyperbolicTangent.sigma = NArray(label=’\(\\sigma\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Standard deviation of the coupling

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

b

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

midpoint

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

sigma

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

pre(x_i, x_j)

class tvb.simulator.coupling.Sigmoidal(**kwargs)

Traited class [tvb.simulator.coupling.Sigmoidal]

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.

Attributes declared

cmintvb.simulator.coupling.Sigmoidal.cmin = NArray(label=’\(c_{min}\)’, dtype=float64, default=array([-1.]), dim_names=(), ndim=None, required=True)

Minimum of the sigmoid function

cmaxtvb.simulator.coupling.Sigmoidal.cmax = NArray(label=’\(c_{max}\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Maximum of the sigmoid function

midpointtvb.simulator.coupling.Sigmoidal.midpoint = NArray(label=’midpoint’, dtype=float64, default=array([0.]), dim_names=(), ndim=None, required=True)

Midpoint of the linear portion of the sigmoid

atvb.simulator.coupling.Sigmoidal.a = NArray(label=’\(a\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Scaling of sigmoidal

sigmatvb.simulator.coupling.Sigmoidal.sigma = NArray(label=’\(\\sigma\)’, dtype=float64, default=array([230.]), dim_names=(), ndim=None, required=True)

Standard deviation of the sigmoidal

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

cmin

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

cmax

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

midpoint

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

sigma

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

parameter_names = ['cmin', 'cmax', 'midpoint', 'a', 'sigma']

pre_expr = 'x_j'

post_expr = 'cmin + ((cmax - cmin) / (1.0 + exp(-a *((gx - midpoint) / sigma))))'

post(gx)

class tvb.simulator.coupling.SigmoidalJansenRit(**kwargs)

Traited class [tvb.simulator.coupling.SigmoidalJansenRit]

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(-r(x-midpoint)/\sigma))\]

Assumes that x has have two state variables.

Attributes declared

cmintvb.simulator.coupling.SigmoidalJansenRit.cmin = NArray(label=’\(c_{min}\)’, dtype=float64, default=array([0.]), dim_names=(), ndim=None, required=True)

Minimum of the sigmoid function

cmaxtvb.simulator.coupling.SigmoidalJansenRit.cmax = NArray(label=’\(c_{max}\)’, dtype=float64, default=array([0.005]), dim_names=(), ndim=None, required=True)

Maximum of the sigmoid function

midpointtvb.simulator.coupling.SigmoidalJansenRit.midpoint = NArray(label=’midpoint’, dtype=float64, default=array([6.]), dim_names=(), ndim=None, required=True)

Midpoint of the linear portion of the sigmoid

rtvb.simulator.coupling.SigmoidalJansenRit.r = NArray(label=’\(r\)’, dtype=float64, default=array([0.56]), dim_names=(), ndim=None, required=True)

the steepness of the sigmoidal transformation

atvb.simulator.coupling.SigmoidalJansenRit.a = NArray(label=’\(a\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Scaling of the coupling term

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

cmin

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

cmax

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

midpoint

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

r

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

pre(x_i, x_j)

post(gx)

class tvb.simulator.coupling.PreSigmoidal(**kwargs)

Traited class [tvb.simulator.coupling.PreSigmoidal]

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.

Attributes declared

Htvb.simulator.coupling.PreSigmoidal.H = NArray(label=’H’, dtype=float64, default=array([0.5]), dim_names=(), ndim=None, required=True)

Global Factor.

Qtvb.simulator.coupling.PreSigmoidal.Q = NArray(label=’Q’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Average.

Gtvb.simulator.coupling.PreSigmoidal.G = NArray(label=’G’, dtype=float64, default=array([60.]), dim_names=(), ndim=None, required=True)

Gain.

Ptvb.simulator.coupling.PreSigmoidal.P = NArray(label=’P’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Excitation-Inhibition ratio.

thetatvb.simulator.coupling.PreSigmoidal.theta = NArray(label=’\(\\theta\)’, dtype=float64, default=array([0.5]), dim_names=(), ndim=None, required=True)

Threshold.

dynamictvb.simulator.coupling.PreSigmoidal.dynamic = Attr(field_type=<class ‘bool’>, default=True, required=True)

Use dynamic threshold (otherwise static).

globalTtvb.simulator.coupling.PreSigmoidal.globalT = Attr(field_type=<class ‘bool’>, default=False, required=True)

Use global threshold (otherwise local).

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

H

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

Q

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

G

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

P

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

theta

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

dynamic

An Attr declares the following about the attribute it describes: * the type * a default value shared by all instances * if the value might be missing * documentation It will resolve to attributes on the instance.

globalT

An Attr declares the following about the attribute it describes: * the type * a default value shared by all instances * if the value might be missing * documentation It will resolve to attributes on the instance.

configure()

Set the right indirect call.

class tvb.simulator.coupling.Difference(**kwargs)

Traited class [tvb.simulator.coupling.Difference]

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

\[a G_ij (x_j - x_i)\]

Attributes declared

atvb.simulator.coupling.Difference.a = NArray(label=’\(a\)’, dtype=float64, default=array([0.1]), dim_names=(), ndim=None, required=True)

Rescales the connection strength.

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

pre(x_i, x_j)

post(gx)

class tvb.simulator.coupling.Kuramoto(**kwargs)

Traited class [tvb.simulator.coupling.Kuramoto]

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

\[a / N G_ij sin(x_j - x_i)\]

Attributes declared

atvb.simulator.coupling.Kuramoto.a = NArray(label=’\(a\)’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)

Rescales the connection strength.

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

a

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

pre(x_i, x_j)

post(gx)