scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/biology/neuroscience/_inhibitor.py

@@ -0,0 +1,62 @@
+"""Global inhibitor of a LEGION network, whose activity `z` decays at rate `phi` without drive."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....core.laws import BaseLaw, RateLaw
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class InhibitorElement(Element):
+    """Global inhibitor of a LEGION network, whose activity `z` decays at rate `phi` without drive.
+
+    Args:
+        label:
+            The label of the inhibitor.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        z:
+            The initial activity.
+
+        phi:
+            The rate of the inhibitor.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import InhibitorElement
+        >>> InhibitorElement('inhibitor').phi
+        3.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        z: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        phi: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 3.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.z = z
+        self.phi = phi
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the decay of the inhibitor.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [RateLaw(s.z, -s.phi * s.z)]

skcomplex/models/biology/neuroscience/_inhibitor_drive.py

@@ -0,0 +1,61 @@
+"""Define the drive of a global inhibitor by the most active oscillator of a lattice."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.interactions import CouplingInteraction
+from ....core.laws.utils import logistic
+from ....core.types import Target
+from ....specs import RoleSpec
+
+
+class InhibitorDriveInteraction(CouplingInteraction):
+    """Drive of a global inhibitor by the largest activity `m H(x - theta_x)` of the oscillators of a lattice.
+
+    The inhibitor gets `phi max_j m_j H(x_j - theta_x)`, with the rate `phi` of the inhibitor and a smooth step of
+    width `kappa` of every oscillator, so it is driven when at least one stimulated oscillator is active. It is the
+    coupling of a hub element to a group by the largest value over the group.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        inhibitor:
+            The path of the inhibitor.
+
+        oscillators:
+            The path of the lattice of oscillators.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import InhibitorDriveInteraction
+        >>> InhibitorDriveInteraction('drive', inhibitor='z', oscillators='grid').reduce
+        'max'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        inhibitor: Annotated[str, RoleSpec()],
+        oscillators: Annotated[str, RoleSpec()],
+    ) -> None:
+        super().__init__(
+            label,
+            target=inhibitor,
+            source=oscillators,
+            write='z',
+            function=self._get_drive,
+            reduce='max',
+            mode='group',
+        )
+        self.inhibitor = inhibitor
+        self.oscillators = oscillators
+
+    @staticmethod
+    def _get_drive(namespace: SimpleNamespace) -> Target:
+        """Return the drive `phi m H(x - theta_x)` of the inhibitor by one oscillator."""
+        other = namespace.other
+        return namespace.member.phi * other.m * logistic(other.x - other.theta_x, 0, other.kappa)

skcomplex/models/biology/neuroscience/_izhikevich.py

@@ -0,0 +1,77 @@
+"""Izhikevich neuron, a quadratic potential `v` and a linear recovery `u`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.elements import Element
+from ....core.laws import BaseLaw, RateLaw
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class IzhikevichElement(Element):
+    """Izhikevich neuron, a quadratic potential `v` and a linear recovery `u`.
+
+    The potential follows `v' = 0.04 v² + 5 v + 140 - u + I` and the recovery `u' = a (b v - u)`. A spike reset fires
+    the neuron.
+
+    Args:
+        label:
+            The label of the neuron.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        v:
+            The initial potential.
+
+        u:
+            The initial recovery.
+
+        a:
+            The time scale of the recovery.
+
+        b:
+            The sensitivity of the recovery to the potential.
+
+        I:
+            The input current.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import IzhikevichElement
+        >>> IzhikevichElement('neuron').b
+        0.2
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        v: Annotated[float, StateSpec()] = -65.0,
+        u: Annotated[float, StateSpec()] = -13.0,
+        a: Annotated[float, ParameterSpec()] = 0.02,
+        b: Annotated[float, ParameterSpec()] = 0.2,
+        I: Annotated[float, ParameterSpec()] = 10.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.v = v
+        self.u = u
+        self.a = a
+        self.b = b
+        self.I = I
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the quadratic potential and the linear recovery.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [RateLaw(s.v, 0.04 * s.v**2 + 5 * s.v + 140 - s.u + s.I), RateLaw(s.u, s.a * (s.b * s.v - s.u))]

skcomplex/models/biology/neuroscience/_leaky_integrate_and_fire.py

@@ -0,0 +1,80 @@
+"""Leaky integrate-and-fire neuron, whose potential relaxes to `rest + resistance I` over the time `tau`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....core.laws import BaseLaw, RateLaw
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class LeakyIntegrateAndFireElement(Element):
+    """Leaky integrate-and-fire neuron, whose potential relaxes to `rest + resistance I` over the time `tau`.
+
+    The potential follows `tau v' = -(v - rest) + resistance I`. A spike reset fires the neuron. Units are mV, ms, MΩ,
+    and nA.
+
+    Args:
+        label:
+            The label of the neuron.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        v:
+            The initial potential.
+
+        rest:
+            The resting potential.
+
+        resistance:
+            The membrane resistance.
+
+        tau:
+            The membrane time constant.
+
+        I:
+            The input current.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import LeakyIntegrateAndFireElement
+        >>> LeakyIntegrateAndFireElement('neuron').tau
+        10.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        v: Annotated[float, StateSpec()] = -65.0,
+        rest: Annotated[float, ParameterSpec()] = -65.0,
+        resistance: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
+        tau: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
+        I: Annotated[float, ParameterSpec()] = 2.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.v = v
+        self.rest = rest
+        self.resistance = resistance
+        self.tau = tau
+        self.I = I
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the leaky integration of the input current.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [RateLaw(s.v, (-(s.v - s.rest) + s.resistance * s.I) / s.tau)]

skcomplex/models/biology/neuroscience/_mutual_inhibition.py

@@ -0,0 +1,55 @@
+"""Inhibition of every unit by the summed activity of all the other units, `-beta x_i sum_{j != i} x_j / tau_i`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import CouplingInteraction
+from ....core.types import Target
+from ....specs import ParameterSpec, RoleSpec
+
+
+class MutualInhibitionInteraction(CouplingInteraction):
+    """Inhibition of every unit by the summed activity of all the other units, `-beta x_i sum_{j != i} x_j / tau_i`.
+
+    It is the coupling of the units to each other, as separate elements or as the members of a group, with the term
+    `-beta x_i x_j / tau_i` of every other unit `j`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        units:
+            The paths of the units, an element set, or the path of a group of units.
+
+        beta:
+            The strength of the inhibition.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import MutualInhibitionInteraction
+        >>> MutualInhibitionInteraction('inhibition', units=['a', 'b'], beta=2.0).beta
+        2.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        units: Annotated[str | Sequence[str], RoleSpec()],
+        beta: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
+    ) -> None:
+        super().__init__(label, target=units, function=self._get_inhibition, mode='group')
+        self.units = units
+        self.beta = beta
+
+    @staticmethod
+    def _get_inhibition(namespace: SimpleNamespace) -> Target:
+        """Return the inhibition of the unit by one other unit, `-beta x_i x_j / tau_i`."""
+        member = namespace.member
+        return -namespace.beta * member.x * namespace.other.x / member.tau

skcomplex/models/biology/neuroscience/_networks.py

@@ -0,0 +1,235 @@
+"""Neuroscience models: networks of spiking neurons and of relaxation oscillators."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+from types import SimpleNamespace
+
+import networkx as nx
+import numpy as np
+from sage.all__sagemath_symbolics import Expression
+from scipy.ndimage import convolve
+
+from ....core.elements import FieldElement
+from ....core.interactions import CouplingInteraction, RateInteraction, RelaxationInteraction
+from ....core.laws.utils import logistic
+from ....core.spaces import LatticeSpace
+from ....core.system import System
+from ....types import Array
+from ..._catalog import register_model
+from ._delayed_synapse import DelayedSynapseInteraction
+from ._global_inhibition import GlobalInhibitionInteraction
+from ._inhibitor import InhibitorElement
+from ._inhibitor_drive import InhibitorDriveInteraction
+from ._spike_reset import SpikeResetInteraction
+from ._spiking_neuron import SpikingNeuronElement
+from ._terman_wang import SILENT, TermanWangElement
+
+NEAREST = np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]])
+
+
+LEGION_OBJECTS = ((1, 1, 0, 0), (1, 0, 0, 0), (0, 0, 0, 1), (0, 0, 0, 1))
+
+
+THRESHOLD = 20.0
+
+
+RESET = 10.0
+
+
+TRACE_TIME = 2.0
+
+
+def _excitation(s: SimpleNamespace) -> Expression:
+    """Return the excitation of an oscillator by a stimulated neighbour in its active phase."""
+    active = s.other.m * logistic(s.other.x - s.other.theta_x, 0, s.other.kappa)
+    excitation: Expression = s.member.W * s.member.m * active
+    return excitation
+
+
+def _random_connections(n_neurons: int, probability: float, rng: np.random.Generator) -> list[tuple[int, int]]:
+    """Return the directed links of a random network without self-links."""
+    return list(nx.gnp_random_graph(n_neurons, probability, seed=rng, directed=True).edges)
+
+
+def _link_weights(stimulus: Array, total: float) -> Array:
+    """Return the weight of each link into every site, a total weight shared among its stimulated neighbours."""
+    neighbours = convolve(stimulus, NEAREST, mode='constant')
+    return total / np.maximum(neighbours, 1.0)
+
+
+@register_model(
+    field='biology/neuroscience',
+    tags=('neuron', 'spiking', 'network', 'delay', 'events'),
+    references=('Brunel and Hakim 1999', 'arXiv:2112.12147'),
+    defaults={'until': 100.0, 'dt': 0.5},
+)
+def delayed_lif_network(
+    n_neurons: int = 10,
+    *,
+    probability: float = 0.3,
+    J: float = 0.5,
+    D: float = 1.5,
+    mu: float = 25.0,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return a random network of leaky integrate-and-fire neurons whose spikes reach their targets after a delay.
+
+    Every neuron is driven above threshold and fires on its own with period `tau ln((mu - reset) / (mu -
+    threshold))`. Each directed link exists with a probability and moves the target's potential by `J` per spike,
+    after the delay `D`. Excitation speeds the firing up and inhibition slows it down.
+
+    Args:
+        n_neurons:
+            The number of neurons.
+
+        probability:
+            The probability of each directed link.
+
+        J:
+            The efficacy of every link in mV.
+
+        D:
+            The transmission delay in ms.
+
+        mu:
+            The constant drive in mV.
+
+        random_state:
+            The seed or generator of the links and the initial potentials.
+
+    Returns:
+        system:
+            The model, with the potentials `neuron_<i>.v`, the traces `neuron_<i>.s`, and the spikes of neuron `i` as
+            `spike_<i>` events.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import delayed_lif_network
+        >>> len(delayed_lif_network(5).elements)
+        5
+    """
+    rng = np.random.default_rng(random_state)
+    potentials = rng.uniform(10.0, 20.0, n_neurons)
+    neurons = [
+        SpikingNeuronElement(f'neuron_{index}', v=float(potentials[index]), mu=mu, tau_s=TRACE_TIME)
+        for index in range(n_neurons)
+    ]
+    leaks = [
+        RelaxationInteraction(
+            f'leak_{index}',
+            target=neuron.label,
+            state='v',
+            goal=lambda s: s.target.mu,
+            time=lambda s: s.target.tau,
+        )
+        for index, neuron in enumerate(neurons)
+    ]
+    traces = [
+        RateInteraction(
+            f'trace_decay_{index}',
+            target=neuron.label,
+            state='s',
+            rate=lambda s: -s.target.s / s.target.tau_s,
+        )
+        for index, neuron in enumerate(neurons)
+    ]
+    spikes = [
+        SpikeResetInteraction(
+            f'spike_{index}',
+            target=neuron.label,
+            threshold=THRESHOLD,
+            after=RESET,
+            kicked='s',
+            kick=1 / TRACE_TIME,
+        )
+        for index, neuron in enumerate(neurons)
+    ]
+    synapses = [
+        DelayedSynapseInteraction(
+            f'synapse_{source}_{target}',
+            source=f'neuron_{source}',
+            target=f'neuron_{target}',
+            J=J,
+            D=D,
+        )
+        for source, target in _random_connections(n_neurons, probability, rng)
+    ]
+    return System(elements=neurons, interactions=[*leaks, *traces, *spikes, *synapses])
+
+
+@register_model(
+    field='biology/neuroscience',
+    tags=('oscillators', 'synchronization', 'segmentation', 'lattice', 'field'),
+    references=('Terman and Wang 1995', 'Wang and Terman 1995', 'Gros 2015'),
+    defaults={'until': 150.0, 'dt': 0.5},
+)
+def legion(
+    stimulus: Sequence[Sequence[float]] = LEGION_OBJECTS,
+    *,
+    epsilon: float = 0.1,
+    W: float = 6.0,
+    W_z: float = 1.5,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return a LEGION network, a lattice of relaxation oscillators that segments a stimulus into its objects.
+
+    Stimulated oscillators excite their stimulated neighbours, so each connected object synchronizes, and a global
+    inhibitor lets only one object be active at a time, so different objects take turns. The inhibitor is driven by the
+    largest activity of the oscillators, so one active oscillator drives it fully. Unstimulated sites have a negative
+    input and stay silent.
+
+    The default `epsilon = 0.1` gives a cycle of about 60 time units, so with the default stimulus the second object
+    first fires near `t = 51` and the first near `t = 70`. The value 0.02 of Terman and Wang makes the slow phases five
+    times longer, and then no object starts an active phase before `t = 220`.
+
+    Args:
+        stimulus:
+            The lattice of 1 for stimulated and 0 for unstimulated sites, by rows. The default holds two objects.
+
+        epsilon:
+            The time scale of the slow variables.
+
+        W:
+            The total excitatory weight into a stimulated site, shared among its stimulated neighbours.
+
+        W_z:
+            The strength of the global inhibition.
+
+        random_state:
+            The seed or generator of the initial states.
+
+    Returns:
+        system:
+            The model, with the fast variables `oscillators.x`, the slow variables `oscillators.y`, and the inhibitor
+            `inhibitor.z`.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import legion
+        >>> legion().elements[0].space.shape
+        (4, 4)
+    """
+    marks = np.asarray(stimulus, dtype=float)
+    rng = np.random.default_rng(random_state)
+    values = {
+        'x': rng.uniform(-2.0, 2.0, marks.shape),
+        'y': rng.uniform(0.0, 6.0, marks.shape),
+        'I': np.where(marks > 0, 0.2, -0.02),
+        'm': marks,
+        'W': _link_weights(marks, W),
+        'epsilon': epsilon,
+    }
+    oscillators = FieldElement(
+        'oscillators',
+        element=TermanWangElement,
+        space=LatticeSpace(marks.shape),
+        boundary={'x': ('fixed', SILENT), 'y': 'zero-flux'},
+        values=values,
+    )
+    excitation = CouplingInteraction('excitation', target='oscillators', read='x', write='x', function=_excitation)
+    drive = InhibitorDriveInteraction('drive', inhibitor='inhibitor', oscillators='oscillators')
+    inhibition = GlobalInhibitionInteraction('inhibition', inhibitor='inhibitor', oscillators='oscillators', W_z=W_z)
+    return System(
+        elements=[oscillators, InhibitorElement('inhibitor')],
+        interactions=[excitation, drive, inhibition],
+    )

skcomplex/models/biology/neuroscience/_neural_field_site.py

@@ -0,0 +1,66 @@
+"""Site of a neural field, the mean membrane potential of the neurons at one position."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class NeuralFieldSiteElement(Element):
+    """Site of a neural field, the mean membrane potential of the neurons at one position.
+
+    The site holds the potential `u`, its time constant `tau`, the resting level `h`, and the amplitude `A` and the
+    range `sigma` of the lateral-inhibition kernel `w(x) = A (1 - |x| / sigma) exp(-|x| / sigma)`, which excites near
+    neighbours and inhibits distant ones.
+
+    Args:
+        label:
+            The label of the site or the field.
+
+        visual:
+            How the site is drawn, or `None` for `default_visual_`.
+
+        u:
+            The initial membrane potential.
+
+        tau:
+            The time constant of the potential.
+
+        h:
+            The resting level.
+
+        A:
+            The amplitude of the kernel.
+
+        sigma:
+            The range of the kernel.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import NeuralFieldSiteElement
+        >>> NeuralFieldSiteElement('site').h
+        -0.2
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        u: Annotated[float, StateSpec()] = 0.0,
+        tau: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        h: Annotated[float, ParameterSpec()] = -0.2,
+        A: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        sigma: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.u = u
+        self.tau = tau
+        self.h = h
+        self.A = A
+        self.sigma = sigma