The Virtual Brain Project

Previous topic

Simulator

Next topic

models Package

This Page

Coupling

Class diagram for tvb.simulator.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}\]
class tvb.simulator.coupling.Coupling(**kwargs)[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)

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

pre(x_i, x_j)[source]
post(gx)[source]
class tvb.simulator.coupling.SparseCoupling(**kwargs)[source]
A coupling implementation which takes advantage of a sparse weights structure to reduce the number of coupling terms evaluated.

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

class tvb.simulator.coupling.Linear(**kwargs)[source]

Provides a linear coupling function of the following form

\[a x + b\]
a : tvb.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.
b : tvb.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 float32. 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 float32. 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)[source]
class tvb.simulator.coupling.Scaling(**kwargs)[source]

Provides a simple scaling of the connectivity of the form

\[a x\]
a : tvb.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 float32. 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)[source]
class tvb.simulator.coupling.HyperbolicTangent(**kwargs)[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.
a : tvb.simulator.coupling.HyperbolicTangent.a = NArray(label=’\(a\)‘, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Minimum of the sigmoid function
b : tvb.simulator.coupling.HyperbolicTangent.b = NArray(label=’\(b\)‘, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Scaling factor for the variable
midpoint : tvb.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
sigma : tvb.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 float32. 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 float32. 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 float32. 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 float32. 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)[source]
class tvb.simulator.coupling.Sigmoidal(**kwargs)[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.
cmin : tvb.simulator.coupling.Sigmoidal.cmin = NArray(label=’\(c_{min}\)‘, dtype=float64, default=array([-1.]), dim_names=(), ndim=None, required=True)
Minimum of the sigmoid function
cmax : tvb.simulator.coupling.Sigmoidal.cmax = NArray(label=’\(c_{max}\)‘, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Maximum of the sigmoid function
midpoint : tvb.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
a : tvb.simulator.coupling.Sigmoidal.a = NArray(label=’\(a\)‘, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Scaling of sigmoidal
sigma : tvb.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 float32. 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 float32. 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 float32. 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 float32. 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 float32. 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)[source]
class tvb.simulator.coupling.SigmoidalJansenRit(**kwargs)[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.

cmin : tvb.simulator.coupling.SigmoidalJansenRit.cmin = NArray(label=’\(c_{min}\)‘, dtype=float64, default=array([0.]), dim_names=(), ndim=None, required=True)
Minimum of the sigmoid function
cmax : tvb.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
midpoint : tvb.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
r : tvb.simulator.coupling.SigmoidalJansenRit.r = NArray(label=’\(r\)‘, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
the steepness of the sigmoidal transformation
a : tvb.simulator.coupling.SigmoidalJansenRit.a = NArray(label=’\(a\)‘, dtype=float64, default=array([0.56]), 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 float32. 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 float32. 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 float32. 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 float32. 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 float32. 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)[source]
post(gx)[source]
class tvb.simulator.coupling.PreSigmoidal(**kwargs)[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.

H : tvb.simulator.coupling.PreSigmoidal.H = NArray(label=’H’, dtype=float64, default=array([0.5]), dim_names=(), ndim=None, required=True)
Global Factor.
Q : tvb.simulator.coupling.PreSigmoidal.Q = NArray(label=’Q’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Average.
G : tvb.simulator.coupling.PreSigmoidal.G = NArray(label=’G’, dtype=float64, default=array([60.]), dim_names=(), ndim=None, required=True)
Gain.
P : tvb.simulator.coupling.PreSigmoidal.P = NArray(label=’P’, dtype=float64, default=array([1.]), dim_names=(), ndim=None, required=True)
Excitation-Inhibition ratio.
theta : tvb.simulator.coupling.PreSigmoidal.theta = NArray(label=’\(\\theta\)‘, dtype=float64, default=array([0.5]), dim_names=(), ndim=None, required=True)
Threshold.
dynamic : tvb.simulator.coupling.PreSigmoidal.dynamic = Attr(field_type=<class ‘bool’>, default=True, required=True)
Use dynamic threshold (otherwise static).
globalT : tvb.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 float32. 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 float32. 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 float32. 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 float32. 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 float32. 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()[source]

Set the right indirect call.

class tvb.simulator.coupling.Difference(**kwargs)[source]

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

\[a G_ij (x_j - x_i)\]
a : tvb.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 float32. 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)[source]
post(gx)[source]
class tvb.simulator.coupling.Kuramoto(**kwargs)[source]

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

\[a / N G_ij sin(x_j - x_i)\]
a : tvb.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 float32. 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)[source]
post(gx)[source]