scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/biology/neuroscience/_conductances.py

@@ -0,0 +1,193 @@
+"""Neuroscience models: conductance-based and reduced excitable neurons."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable
+from types import SimpleNamespace
+
+from sage.all__sagemath_symbolics import Expression, exp
+
+from ....core.interactions import CrossingInteraction, RateInteraction
+from ....core.system import System
+from ..._catalog import register_model
+from ..common.excitable import FitzHughNagumoInteraction
+from ._fitz_hugh_nagumo_neuron import FitzHughNagumoNeuronElement
+from ._hodgkin_huxley import HodgkinHuxleyElement
+from .types import GateRates
+
+
+def _gate_rates(v: Expression) -> GateRates:
+    """Return the opening and closing rates per ms of the gates `n`, `m`, and `h` at a potential in mV."""
+    return {
+        'n': (0.01 * (v + 55) / (1 - exp(-(v + 55) / 10)), 0.125 * exp(-(v + 65) / 80)),
+        'm': (0.1 * (v + 40) / (1 - exp(-(v + 40) / 10)), 4 * exp(-(v + 65) / 18)),
+        'h': (0.07 * exp(-(v + 65) / 20), 1 / (1 + exp(-(v + 35) / 10))),
+    }
+
+
+def _gate_kinetics(gate: str) -> Callable[[SimpleNamespace], Expression]:
+    """Return the rate `alpha(v) (1 - x) - beta(v) x` of a gate `x` as a function of the namespace of the neuron."""
+
+    def kinetics(s: SimpleNamespace) -> Expression:
+        opening, closing = _gate_rates(s.target.v)[gate]
+        x = getattr(s.target, gate)
+        rate: Expression = opening * (1 - x) - closing * x
+        return rate
+
+    return kinetics
+
+
+def _resting_gates(v: float) -> dict[str, float]:
+    """Return the steady-state opening of every gate at a fixed potential in mV."""
+    return {gate: float(opening / (opening + closing)) for gate, (opening, closing) in _gate_rates(v).items()}
+
+
+@register_model(
+    field='biology/neuroscience',
+    tags=('neuron', 'excitability', 'spiking', 'conductance'),
+    references=('Hodgkin and Huxley 1952', 'Rinzel and Miller 1980', 'Trzaska 2023', 'arXiv:2112.12147'),
+    defaults={'until': 50.0, 'dt': 0.1},
+)
+def hodgkin_huxley(
+    v: float = -65.0,
+    *,
+    I: float = 10.0,
+    C: float = 1.0,
+    g_na: float = 120.0,
+    g_k: float = 36.0,
+    g_l: float = 0.3,
+) -> System:
+    """Return the Hodgkin-Huxley neuron, whose sodium and potassium channels produce action potentials.
+
+    The gates start at their steady state at the initial potential, and the current is switched on at the start. A
+    constant current above about 6.2 µA/cm² makes the neuron fire periodically, and a weaker one gives at most a few
+    spikes before it settles.
+
+    Args:
+        v:
+            The initial membrane potential in mV.
+
+        I:
+            The applied current in µA/cm².
+
+        C:
+            The membrane capacitance in µF/cm².
+
+        g_na:
+            The maximal sodium conductance in mS/cm².
+
+        g_k:
+            The maximal potassium conductance in mS/cm².
+
+        g_l:
+            The leak conductance in mS/cm².
+
+    Returns:
+        system:
+            The model, with the potential `neuron.v`, the gates `neuron.n`, `neuron.m`, and `neuron.h`, and its spikes
+            as `spike` events.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import hodgkin_huxley
+        >>> round(hodgkin_huxley().elements[0].h, 4)
+        0.5961
+    """
+    gates = _resting_gates(v)
+    return System(
+        elements=[
+            HodgkinHuxleyElement(
+                'neuron',
+                v=v,
+                I=I,
+                C=C,
+                g_na=g_na,
+                g_k=g_k,
+                g_l=g_l,
+                n=gates['n'],
+                m=gates['m'],
+                h=gates['h'],
+            ),
+        ],
+        interactions=[
+            RateInteraction('applied_current', target='neuron', state='v', rate=lambda s: s.target.I, divisor='C'),
+            RateInteraction(
+                'sodium_current',
+                target='neuron',
+                state='v',
+                rate=lambda s: -s.target.g_na * s.target.m**3 * s.target.h * (s.target.v - s.target.e_na),
+                divisor='C',
+            ),
+            RateInteraction(
+                'potassium_current',
+                target='neuron',
+                state='v',
+                rate=lambda s: -s.target.g_k * s.target.n**4 * (s.target.v - s.target.e_k),
+                divisor='C',
+            ),
+            RateInteraction(
+                'leak_current',
+                target='neuron',
+                state='v',
+                rate=lambda s: -s.target.g_l * (s.target.v - s.target.e_l),
+                divisor='C',
+            ),
+            *[
+                RateInteraction(f'{gate}_gating', target='neuron', state=gate, rate=_gate_kinetics(gate))
+                for gate in ('n', 'm', 'h')
+            ],
+            CrossingInteraction('spike', target='neuron', guard=lambda s: s.target.v, direction=1),
+        ],
+    )
+
+
+@register_model(
+    field='biology/neuroscience',
+    tags=('neuron', 'excitability', 'relaxation oscillations'),
+    references=('FitzHugh 1961', 'Nagumo, Arimoto, and Yoshizawa 1962', 'Trzaska 2023', 'Datseris and Parlitz 2022'),
+    defaults={'until': 100.0, 'dt': 0.2},
+)
+def fitzhugh_nagumo_ode(
+    v: float = -1.2,
+    w: float = -0.6,
+    *,
+    a: float = 0.7,
+    b: float = 0.8,
+    epsilon: float = 0.08,
+    I: float = 0.5,
+) -> System:
+    """Return the FitzHugh-Nagumo neuron, the two-variable reduction of Hodgkin and Huxley's excitable membrane.
+
+    Without current the neuron rests on a stable fixed point and answers a large enough kick with one spike. A current
+    `I` between about 0.33 and 1.42 destabilizes the rest and the neuron fires periodically.
+
+    Args:
+        v:
+            The initial potential.
+
+        w:
+            The initial recovery.
+
+        a:
+            The offset of the recovery.
+
+        b:
+            The damping of the recovery.
+
+        epsilon:
+            The time scale of the recovery.
+
+        I:
+            The applied current.
+
+    Returns:
+        system:
+            The model, with the potential `neuron.v` and the recovery `neuron.w`.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import fitzhugh_nagumo_ode
+        >>> fitzhugh_nagumo_ode(I=0.0).interactions[0].I
+        0.0
+    """
+    kinetics = FitzHughNagumoInteraction('kinetics', target='neuron', a=a, b=b, epsilon=epsilon, I=I)
+    return System(elements=[FitzHughNagumoNeuronElement('neuron', v=v, w=w)], interactions=[kinetics])

skcomplex/models/biology/neuroscience/_delayed_synapse.py

@@ -0,0 +1,70 @@
+"""Synapse that adds the presynaptic trace from a transmission delay ago to the postsynaptic potential."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import Expression, oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import RateInteraction
+from ....core.laws.utils import delayed
+from ....specs import ParameterSpec, RoleSpec
+
+
+class DelayedSynapseInteraction(RateInteraction):
+    """Synapse that adds the presynaptic trace from a transmission delay ago to the postsynaptic potential.
+
+    The target gains `J s_source(t - D)`, so every presynaptic spike moves the postsynaptic potential by `J` in
+    total, spread over the decay time of the trace and arriving after the delay `D`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        source:
+            The path of the presynaptic neuron.
+
+        target:
+            The path of the postsynaptic neuron.
+
+        J:
+            The efficacy in mV, positive for excitation and negative for inhibition.
+
+        D:
+            The transmission delay in ms.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import DelayedSynapseInteraction
+        >>> DelayedSynapseInteraction('synapse', source='a', target='b', J=-1.0).D
+        1.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        source: Annotated[str, RoleSpec()],
+        target: Annotated[str, RoleSpec()],
+        J: Annotated[float, ParameterSpec()] = 0.5,
+        D: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.5,
+    ) -> None:
+        super().__init__(label, target=target, state='v')
+        self.source = source
+        self.J = J
+        self.D = D
+
+    def _get_rate(self, namespace: SimpleNamespace) -> Expression:
+        """Return the delayed synaptic input `J s_source(t - D)`.
+
+        Args:
+            namespace:
+                The namespace of the symbols the rate can use, with the namespaces of the source and the target.
+
+        Returns:
+            rate:
+                The rate of the postsynaptic potential.
+        """
+        return namespace.J * delayed(namespace.source.s, namespace.D)

skcomplex/models/biology/neuroscience/_excitable.py

@@ -0,0 +1,178 @@
+"""Excitable networks: cyclic excitable elements that excite their neighbours with a transmission probability."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+import networkx as nx
+import numpy as np
+from sage.all__sagemath_symbolics import NN, Expression, exp, oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element, LatticeElement
+from ....core.interactions import TransitionInteraction
+from ....core.laws.utils import neighbors, where
+from ....core.spaces import DiscreteTime, NetworkSpace
+from ....core.system import System
+from ....specs import ObservableSpec, ParameterSpec, StateSpec, VisualSpec
+from ....types import AnyArray
+from ..._catalog import register_model
+
+EXCITED = 1
+
+
+def _excited_fraction(phases: AnyArray) -> float:
+    """Return the fraction of elements that are excited."""
+    return float(np.mean(np.asarray(phases) == EXCITED))
+
+
+class ExcitableElement(Element):
+    """Cyclic excitable element of the Kinouchi-Copelli network: quiescent at 0, excited at 1, refractory up to `m - 1`.
+
+    Transitions move its phase every step. A quiescent element is excited by the external stimulus with probability
+    `1 - exp(-r)`, where `r` is the stimulus rate per step, or by each excited neighbour with the transmission
+    probability `p`, so it stays quiescent with probability `exp(-r) (1 - p)^n` when `n` neighbours are excited. An
+    excited or refractory element moves to the next state, and the last refractory state returns to quiescence.
+
+    Args:
+        label:
+            The label of the element or the site group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        phase:
+            The initial state, 0 for quiescent, 1 for excited, and 2 to `n_states - 1` for refractory.
+
+        p:
+            The probability that an excited neighbour excites the element in one step.
+
+        stimulus:
+            The rate `r` of the external stimulus per step.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import ExcitableElement
+        >>> ExcitableElement('neuron').p
+        0.1
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        phase: Annotated[float, StateSpec(domain=NN)] = 0,
+        p: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
+        stimulus: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.phase = phase
+        self.p = p
+        self.stimulus = stimulus
+
+
+def _get_excitation(s: SimpleNamespace) -> Expression:
+    """Return the probability that the stimulus or an excited neighbour excites a quiescent element in a step."""
+    excited = neighbors(where(s.target.other.phase == EXCITED, 1, 0))
+    probability: Expression = 1 - exp(-s.target.stimulus) * (1 - s.target.p) ** excited
+    return probability
+
+
+def _get_cycle(n_states: int) -> list[TransitionInteraction]:
+    """Return the moves of an excited or refractory element to the next state of the cycle, the last to quiescence."""
+    return [
+        TransitionInteraction(
+            f'cycle_{phase}',
+            target='neurons',
+            state='phase',
+            source=phase,
+            destination=(phase + 1) % n_states,
+            condition=lambda s: 1,
+        )
+        for phase in range(EXCITED, n_states)
+    ]
+
+
+@register_model(
+    field='biology/neuroscience',
+    tags=('excitable', 'network', 'criticality', 'dynamic range', 'stochastic'),
+    references=('Kinouchi and Copelli 2006', 'Larremore et al. 2011'),
+    defaults={'until': 1000, 'dt': 1},
+    observables=lambda system: [
+        ObservableSpec('activity', group='neurons', variable='phase', reduce=_excited_fraction),
+    ],
+)
+def kinouchi_copelli(
+    graph: nx.Graph | None = None,
+    *,
+    sigma: float = 1.0,
+    stimulus: float = 0.0,
+    n_states: int = 5,
+    excited: float | None = None,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return the Kinouchi-Copelli network of excitable elements, whose dynamic range peaks at the critical point.
+
+    Every element excites each quiescent neighbour with the transmission probability `p = sigma / K`, where `K` is
+    the mean degree of the graph, so `sigma` is the branching ratio, the mean number of elements one excitation
+    excites. Below `sigma = 1` activity dies out without a stimulus, and above it activity sustains itself. The
+    response, the mean firing rate against the stimulus rate, spans the most decades of stimulus at `sigma = 1`.
+
+    Args:
+        graph:
+            The NetworkX graph, or `None` for an Erdős-Rényi graph of 1000 nodes with mean degree 10.
+
+        sigma:
+            The branching ratio.
+
+        stimulus:
+            The rate `r` of the external stimulus per step, which excites a quiescent element with probability
+            `1 - exp(-r)`.
+
+        n_states:
+            The number of states of the cycle, one quiescent, one excited, and `n_states - 2` refractory.
+
+        excited:
+            The initial fraction of excited elements, with the others quiescent, or `None` for states drawn uniformly
+            over the cycle.
+
+        random_state:
+            The seed or generator of the default graph and of the initial states.
+
+    Returns:
+        system:
+            The model, with the states `neurons.phase`, one value per node. Its standard observable `activity` is the
+            fraction of excited elements, the firing rate per step.
+
+    Examples:
+        >>> import networkx as nx
+        >>> from skcomplex.models.biology.neuroscience import kinouchi_copelli
+        >>> kinouchi_copelli(nx.random_regular_graph(4, 20, seed=0), sigma=1.0).elements[0].values['p']
+        0.25
+    """
+    rng = np.random.default_rng(random_state)
+    graph = nx.gnp_random_graph(1000, 10 / 999, seed=int(rng.integers(2**31))) if graph is None else graph
+    size = graph.number_of_nodes()
+    degree = 2 * graph.number_of_edges() / size
+    phase = (
+        rng.integers(0, n_states, size=size).astype(float)
+        if excited is None
+        else (rng.random(size) < excited).astype(float)
+    )
+    neurons = LatticeElement(
+        'neurons',
+        element=ExcitableElement,
+        space=NetworkSpace(graph),
+        values={'phase': phase, 'p': sigma / degree, 'stimulus': stimulus},
+    )
+    excitation = TransitionInteraction(
+        'excitation',
+        target='neurons',
+        state='phase',
+        source=0,
+        destination=EXCITED,
+        probability=_get_excitation,
+    )
+    return System(elements=[neurons], interactions=[excitation, *_get_cycle(n_states)], time=DiscreteTime())

skcomplex/models/biology/neuroscience/_fitz_hugh_nagumo_neuron.py

@@ -0,0 +1,46 @@
+"""FitzHugh-Nagumo neuron, with a fast potential `v` and a slow recovery `w`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import StateSpec, VisualSpec
+
+
+class FitzHughNagumoNeuronElement(Element):
+    """FitzHugh-Nagumo neuron, with a fast potential `v` and a slow recovery `w`.
+
+    The neuron has no laws of its own. FitzHugh-Nagumo kinetics change it.
+
+    Args:
+        label:
+            The label of the neuron.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        v:
+            The initial potential.
+
+        w:
+            The initial recovery.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import FitzHughNagumoNeuronElement
+        >>> FitzHughNagumoNeuronElement('neuron').w
+        -0.6
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        v: Annotated[float, StateSpec()] = -1.2,
+        w: Annotated[float, StateSpec()] = -0.6,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.v = v
+        self.w = w

skcomplex/models/biology/neuroscience/_global_inhibition.py

@@ -0,0 +1,71 @@
+"""Inhibition of every oscillator of a lattice by a global inhibitor, once the inhibitor exceeds its threshold."""
+
+# 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.interactions import CouplingInteraction
+from ....core.laws.utils import logistic
+from ....core.types import Target
+from ....specs import ParameterSpec, RoleSpec
+
+
+class GlobalInhibitionInteraction(CouplingInteraction):
+    """Inhibition of every oscillator of a lattice by a global inhibitor, once the inhibitor exceeds its threshold.
+
+    Every oscillator gets `-W_z H(z - theta_z)` from the inhibitor, a smooth step of width `kappa` of the oscillator.
+    It is the coupling of the members of a group to a hub element, and `InhibitorDriveInteraction` drives the hub.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        oscillators:
+            The path of the lattice of oscillators.
+
+        inhibitor:
+            The path of the inhibitor.
+
+        W_z:
+            The strength of the inhibition.
+
+        theta_z:
+            The threshold of the inhibitor.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import GlobalInhibitionInteraction
+        >>> GlobalInhibitionInteraction('inhibition', inhibitor='z', oscillators='grid').W_z
+        1.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        oscillators: Annotated[str, RoleSpec()],
+        inhibitor: Annotated[str, RoleSpec()],
+        W_z: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.5,
+        theta_z: Annotated[float, ParameterSpec()] = 0.1,
+    ) -> None:
+        super().__init__(
+            label,
+            target=oscillators,
+            source=inhibitor,
+            write='x',
+            function=self._get_inhibition,
+            mode='group',
+        )
+        self.oscillators = oscillators
+        self.inhibitor = inhibitor
+        self.W_z = W_z
+        self.theta_z = theta_z
+
+    @staticmethod
+    def _get_inhibition(namespace: SimpleNamespace) -> Target:
+        """Return the inhibition `-W_z H(z - theta_z)` of an oscillator."""
+        return -namespace.W_z * logistic(namespace.other.z - namespace.theta_z, 0, namespace.member.kappa)

skcomplex/models/biology/neuroscience/_hodgkin_huxley.py

@@ -0,0 +1,103 @@
+"""Squid giant axon membrane of Hodgkin and Huxley, with sodium, potassium, and leak currents."""
+
+# 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 HodgkinHuxleyElement(Element):
+    """Squid giant axon membrane of Hodgkin and Huxley, with sodium, potassium, and leak currents.
+
+    The potential follows `C v' = I - g_Na m³ h (v - E_Na) - g_K n⁴ (v - E_K) - g_L (v - E_L)`, and each gate `x` of
+    `n`, `m`, and `h` relaxes as `x' = alpha_x(v) (1 - x) - beta_x(v) x`, in the modern convention with rest near -65
+    mV. Upward crossings of 0 mV are recorded as `spike` events. Units are mV, ms, mS/cm², and µA/cm². The element holds
+    the states and parameters and has no laws of its own: the current, gating, and crossing interactions of
+    `hodgkin_huxley` read its parameters.
+
+    Args:
+        label:
+            The label of the neuron.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        v:
+            The initial membrane potential.
+
+        n:
+            The initial potassium activation.
+
+        m:
+            The initial sodium activation.
+
+        h:
+            The initial sodium inactivation.
+
+        C:
+            The membrane capacitance.
+
+        g_na:
+            The maximal sodium conductance.
+
+        g_k:
+            The maximal potassium conductance.
+
+        g_l:
+            The leak conductance.
+
+        e_na:
+            The sodium reversal potential.
+
+        e_k:
+            The potassium reversal potential.
+
+        e_l:
+            The leak reversal potential.
+
+        I:
+            The applied current.
+
+    Examples:
+        >>> from skcomplex.models.biology.neuroscience import HodgkinHuxleyElement
+        >>> HodgkinHuxleyElement('axon', I=10.0).g_na
+        120.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        v: Annotated[float, StateSpec()] = -65.0,
+        n: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.3177,
+        m: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0529,
+        h: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.5961,
+        C: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        g_na: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 120.0,
+        g_k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 36.0,
+        g_l: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
+        e_na: Annotated[float, ParameterSpec()] = 50.0,
+        e_k: Annotated[float, ParameterSpec()] = -77.0,
+        e_l: Annotated[float, ParameterSpec()] = -54.387,
+        I: Annotated[float, ParameterSpec()] = 10.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.v = v
+        self.n = n
+        self.m = m
+        self.h = h
+        self.C = C
+        self.g_na = g_na
+        self.g_k = g_k
+        self.g_l = g_l
+        self.e_na = e_na
+        self.e_k = e_k
+        self.e_l = e_l
+        self.I = I