scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/biology/ecology/_factories.py

@@ -0,0 +1,322 @@
+"""Ecology models: population growth, predation, and invasion fronts."""
+
+# 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 ....core.interactions import BaseInteraction, MapInteraction
+from ....core.laws.utils import lag
+from ....core.system import System
+from ....specs import StateSpec, VisualSpec
+from ..._catalog import register_model
+from ..common.populations import (
+    ExponentialGrowthInteraction,
+    LogisticGrowthInteraction,
+    MortalityInteraction,
+    PopulationElement,
+)
+from ._predation_interaction import PredationInteraction
+from ._seasonal_logistic_growth import SeasonalLogisticGrowthInteraction
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('population', 'ode'),
+    references=('Malthus 1798',),
+    defaults={'until': 20.0, 'dt': 0.1},
+)
+def exponential_growth(n: float = 10.0, r: float = 0.1) -> System:
+    """Return a population that grows or declines at a constant per-capita rate.
+
+    Args:
+        n:
+            The initial size.
+
+        r:
+            The per-capita growth rate.
+
+    Returns:
+        system:
+            The model, with the population `population`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import exponential_growth
+        >>> exponential_growth(r=0.2).interactions[0].r
+        0.2
+    """
+    return System(
+        elements=[PopulationElement('population', n=n)],
+        interactions=[ExponentialGrowthInteraction('growth', target='population', r=r)],
+    )
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('population', 'ode'),
+    references=('Verhulst 1838',),
+    defaults={'until': 20.0, 'dt': 0.1},
+)
+def logistic_growth(n: float = 10.0, r: float = 1.0, K: float = 100.0) -> System:
+    """Return a population that grows logistically towards its carrying capacity.
+
+    Args:
+        n:
+            The initial size.
+
+        r:
+            The intrinsic growth rate.
+
+        K:
+            The carrying capacity.
+
+    Returns:
+        system:
+            The model, with the population `population`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import logistic_growth
+        >>> logistic_growth(K=500.0).interactions[0].K
+        500.0
+    """
+    return System(
+        elements=[PopulationElement('population', n=n)],
+        interactions=[LogisticGrowthInteraction('growth', target='population', r=r, K=K)],
+    )
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('population', 'ode', 'forcing', 'periodic'),
+    references=('Coleman 1979', 'Trzaska 2023'),
+    defaults={'until': 20.0, 'dt': 0.05},
+)
+def varying_capacity_logistic(
+    n: float = 10.0,
+    *,
+    r: float = 2.0,
+    K: float = 100.0,
+    amplitude: float = 0.5,
+    period: float = 1.0,
+) -> System:
+    """Return logistic growth under a seasonal carrying capacity, which settles on a cycle of the season's period.
+
+    Whatever its initial size, the population tends to a unique periodic solution, which lags behind the capacity and
+    varies less than it.
+
+    Args:
+        n:
+            The initial size.
+
+        r:
+            The intrinsic growth rate.
+
+        K:
+            The mean carrying capacity.
+
+        amplitude:
+            The relative amplitude of the seasonal variation of the capacity, below 1.
+
+        period:
+            The period of the seasons.
+
+    Returns:
+        system:
+            The model, with the population `population`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import varying_capacity_logistic
+        >>> varying_capacity_logistic(amplitude=0.2).interactions[0].amplitude
+        0.2
+    """
+    return System(
+        elements=[PopulationElement('population', n=n)],
+        interactions=[
+            SeasonalLogisticGrowthInteraction(
+                'growth',
+                target='population',
+                r=r,
+                K=K,
+                amplitude=amplitude,
+                period=period,
+            ),
+        ],
+    )
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('population', 'delay', 'oscillation'),
+    references=('Hutchinson 1948', 'Erneux 2009'),
+    defaults={'until': 100.0, 'dt': 0.1},
+)
+def hutchinson(n: float = 50.0, *, r: float = 1.0, K: float = 100.0, tau: float = 2.0) -> System:
+    """Return Hutchinson's delayed logistic equation, which oscillates around `K` when `r * tau` exceeds π/2.
+
+    The history before the start is the initial size.
+
+    Args:
+        n:
+            The initial size, also its history.
+
+        r:
+            The per-capita growth rate at low density.
+
+        K:
+            The carrying capacity.
+
+        tau:
+            The delay of the density feedback.
+
+    Returns:
+        system:
+            The model, with the population `population`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import hutchinson
+        >>> hutchinson(tau=1.0).interactions[0].tau
+        1.0
+    """
+    return System(
+        elements=[PopulationElement('population', n=n)],
+        interactions=[LogisticGrowthInteraction('growth', target='population', r=r, K=K, tau=tau)],
+    )
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('predator-prey', 'ode', 'oscillation'),
+    references=('Lotka 1925', 'Volterra 1926'),
+    defaults={'until': 50.0, 'dt': 0.1},
+)
+def lotka_volterra(
+    prey: float = 40.0,
+    predators: float = 9.0,
+    *,
+    r: float = 1.1,
+    a: float = 0.4,
+    b: float = 0.1,
+    d: float = 0.4,
+    K: float | None = None,
+) -> System:
+    """Return prey and predators whose populations oscillate through predation.
+
+    Args:
+        prey:
+            The initial number of prey.
+
+        predators:
+            The initial number of predators.
+
+        r:
+            The growth rate of the prey.
+
+        a:
+            The rate at which predation removes prey.
+
+        b:
+            The rate at which predation feeds predators.
+
+        d:
+            The mortality rate of the predators.
+
+        K:
+            The carrying capacity of the prey, or `None` for exponential growth of the prey.
+
+    Returns:
+        system:
+            The model, with the populations `prey` and `predators`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import lotka_volterra
+        >>> [element.label for element in lotka_volterra().elements]
+        ['prey', 'predators']
+    """
+    growth: BaseInteraction = (
+        ExponentialGrowthInteraction('growth', target='prey', r=r)
+        if K is None
+        else LogisticGrowthInteraction('growth', target='prey', r=r, K=K)
+    )
+    return System(
+        elements=[PopulationElement('prey', n=prey), PopulationElement('predators', n=predators)],
+        interactions=[
+            growth,
+            PredationInteraction('predation', predator='predators', prey='prey', a=a, b=b),
+            MortalityInteraction('death', target='predators', d=d),
+        ],
+    )
+
+
+class RabbitsElement(Element):
+    """Pairs of rabbits of this month and of last month, the two age classes of Fibonacci's recurrence.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        pairs:
+            The number of pairs this month, a state that keeps its value one month earlier.
+
+        pairs_lag1:
+            The number of pairs last month.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import RabbitsElement
+        >>> RabbitsElement('rabbits', pairs=3.0).pairs
+        3.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        pairs: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), lags=1, initial=(0.0,))] = 1.0,
+        pairs_lag1: float = 0.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.pairs = pairs
+        self.pairs_lag1 = pairs_lag1
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('population', 'discrete map', 'second order', 'age structure'),
+    references=('Fibonacci 1202',),
+    defaults={'until': 20, 'dt': 1},
+)
+def fibonacci_rabbits(pairs: float = 1.0, previous: float = 0.0) -> System:
+    """Return Fibonacci's rabbits, `N_{t+1} = N_t + N_{t-1}`, where every pair older than one month breeds a new pair.
+
+    The previous population counts the pairs old enough to breed, so the recurrence is an age structure of two classes.
+
+    Args:
+        pairs:
+            The number of pairs this month.
+
+        previous:
+            The number of pairs last month.
+
+    Returns:
+        system:
+            The model, with the population `rabbits.pairs` and last month's `rabbits.pairs_lag1`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import fibonacci_rabbits
+        >>> fibonacci_rabbits().elements[0].pairs
+        1.0
+    """
+    breeding = MapInteraction(
+        'breeding',
+        target='rabbits',
+        state='pairs',
+        function=lambda s: s.target.pairs + lag(s.target.pairs, 1),
+    )
+    return System(elements=[RabbitsElement('rabbits', pairs=pairs, pairs_lag1=previous)], interactions=[breeding])

skcomplex/models/biology/ecology/_forager.py

@@ -0,0 +1,116 @@
+"""Animal that hunts its food guided by its emotions and those its kind left on the ground, and breeds."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated, ClassVar
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.finite_enumerated_set import FiniteEnumeratedSet
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+from ._forager_view import ForagerView
+
+PLANTS = 'plants'
+
+
+class ForagerElement(Element):
+    """Animal that hunts its food guided by its emotions and those its kind left on the ground, and breeds.
+
+    Every step the animal ages and grows hungry, and starves when its hunger passes `starvation`. It moves to the
+    neighbouring cell, empty or holding food, of highest preference: 1 for food, plus, with emotions, the happiness
+    marked there minus its own and its own distress minus the distress marked there. It eats food it moves onto.
+    Its emotions follow `E' = (1 - memory) (X + communication C) + memory E`, with the experience `X` of the step and
+    the mean emotion `C` marked around it, and it marks its cell with them. A mature animal breeds into an empty
+    neighbouring cell with a probability that happiness raises and distress lowers, and its offspring shares its
+    hunger, so a lineage starves together when its food is gone. Subclasses name their food and the marks they read,
+    and the model adds the ageing, the hunger, the starvation, the experience of distress, the move, the meal, the
+    emotions, the marks, and the breeding as member interactions.
+
+    Args:
+        label:
+            The label of the agent or group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        age:
+            The steps since the animal last bred.
+
+        hunger:
+            The steps since the animal last ate.
+
+        happiness:
+            The happiness, which eating raises.
+
+        distress:
+            The fear or anger.
+
+        experience:
+            The distress the animal experienced in the step, before it moved.
+
+        maturity:
+            The age at which the animal can breed.
+
+        reproduction:
+            The probability of breeding at maturity without emotions.
+
+        starvation:
+            The hunger at which the animal dies.
+
+        memory:
+            The share of its previous emotion that an animal keeps.
+
+        communication:
+            The weight of the emotions marked around the animal.
+
+        emotions:
+            Whether emotions guide the animal, 1 or 0.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.biology.ecology import StigmergicPreyElement
+        >>> GroupElement('prey', element=StigmergicPreyElement, size=10).size
+        10
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = VisualSpec('agents', {'color_by': 'happiness', 'radius': 0.35}),
+        *,
+        age: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        hunger: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        happiness: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        distress: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        experience: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        maturity: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 5.0,
+        reproduction: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
+        starvation: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
+        memory: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
+        communication: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
+        emotions: Annotated[float, ParameterSpec(domain=FiniteEnumeratedSet([0, 1]))] = 1.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.age = age
+        self.hunger = hunger
+        self.happiness = happiness
+        self.distress = distress
+        self.experience = experience
+        self.maturity = maturity
+        self.reproduction = reproduction
+        self.starvation = starvation
+        self.memory = memory
+        self.communication = communication
+        self.emotions = emotions
+
+    food: ClassVar[str] = PLANTS
+    happiness_mark: ClassVar[str] = 'prey_happiness'
+    distress_mark: ClassVar[str] = 'prey_fear'
+
+    @classmethod
+    def _get_view(cls) -> type[ForagerView]:
+        """Return the view of a forager or a predator, `ForagerView`."""
+        return ForagerView

skcomplex/models/biology/ecology/_forager_view.py

@@ -0,0 +1,25 @@
+"""View of a forager or a predator as its rules see it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class ForagerView(AgentView):
+    """View of a forager or a predator, with its states and parameters as attributes.
+
+    `ForagerElement` names this class with `_get_view`, so its rules read them with checked types.
+    """
+
+    age: float
+    hunger: float
+    happiness: float
+    distress: float
+    experience: float
+    maturity: float
+    reproduction: float
+    starvation: float
+    memory: float
+    communication: float
+    emotions: float

skcomplex/models/biology/ecology/_fronts.py

@@ -0,0 +1,128 @@
+"""Ecology models: invasion fronts of a population that grows logistically and diffuses."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+import numpy as np
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element, FieldElement
+from ....core.laws import BaseLaw, RateLaw
+from ....core.laws.utils import laplacian
+from ....core.spaces import LatticeSpace
+from ....core.system import System
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+from ..._catalog import register_model
+
+
+class FisherKPPElement(Element):
+    """Site of a line whose density `u` diffuses and grows logistically, `du/dt = D laplacian(u) + r u (1 - u)`.
+
+    Args:
+        label:
+            The label of the site.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        u:
+            The initial density, as a fraction of the carrying capacity.
+
+        D:
+            The diffusion coefficient.
+
+        r:
+            The growth rate.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import FisherKPPElement
+        >>> FisherKPPElement('site', u=0.5).u
+        0.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        u: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        D: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
+        r: Annotated[object, ParameterSpec()] = 1.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.u = u
+        self.D = D
+        self.r = r
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the diffusion and the logistic growth of the density.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The rate law of the density.
+        """
+        return [RateLaw(s.u, s.D * laplacian(s.u) + s.r * s.u * (1 - s.u))]
+
+
+@register_model(
+    field='biology/ecology',
+    tags=('field', 'fronts', 'reaction-diffusion', 'pde'),
+    references=('Fisher 1937', 'Kolmogorov, Petrovsky, and Piskunov 1937'),
+    defaults={'until': 40.0, 'dt': 1.0},
+)
+def fisher_kpp(
+    length: int = 800,
+    *,
+    D: float = 1.0,
+    r: float = 1.0,
+    spacing: float = 0.25,
+    front: float = 0.05,
+) -> System:
+    """Return the Fisher-KPP equation, whose step invades the empty line as a front of speed `2 sqrt(r D)`.
+
+    Args:
+        length:
+            The number of sites of the line.
+
+        D:
+            The diffusion coefficient.
+
+        r:
+            The growth rate.
+
+        spacing:
+            The distance between sites.
+
+        front:
+            The fraction of the line that starts occupied, on its left.
+
+    Returns:
+        system:
+            The model, with the density `line.u`.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import fisher_kpp
+        >>> int(fisher_kpp(100, front=0.1).elements[0].values['u'].sum())
+        10
+    """
+    u = (np.arange(length) < front * length).astype(float)
+    space = LatticeSpace(length, spacing=spacing)
+    return System(
+        elements=[
+            FieldElement(
+                'line',
+                element=FisherKPPElement,
+                space=space,
+                boundary={'u': 'zero-flux'},
+                values={'u': u, 'D': D, 'r': r},
+            ),
+        ],
+    )

skcomplex/models/biology/ecology/_generalized_lotka_volterra.py

@@ -0,0 +1,66 @@
+"""Interactions of the species of a group, `x_i sum_j a_ij x_j`, through an interaction matrix parameter `a`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.interactions import CouplingInteraction
+from ....specs import ParameterSpec, RoleSpec
+
+
+class GeneralizedLotkaVolterraInteraction(CouplingInteraction):
+    """Interactions of the species of a group, `dx_i/dt += x_i sum_j a_ij x_j`, through an interaction matrix `a`.
+
+    Every species `i` couples to every species `j` of the group, itself included, through the term `x_i x_j` weighted
+    by the entry `a_ij` of the interaction matrix, a parameter with one row and one column per species, so a schedule or
+    an experiment changes it. The diagonal entries are the interactions of a species with itself, negative for
+    self-limitation. With the growth `b_i x_i` as a rate, it gives the generalized Lotka-Volterra equations
+    `dx_i/dt = x_i (b_i + sum_j a_ij x_j)`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the group of species.
+
+        a:
+            The interaction matrix, where `a_ij` is the effect of species `j` on the growth of species `i`, or a number
+            for every entry.
+
+        state:
+            The name of the state that holds the abundance of a species.
+
+    Examples:
+        >>> from skcomplex.models.biology.ecology import GeneralizedLotkaVolterraInteraction
+        >>> matrix = ((-1.0, 0.5), (0.5, -1.0))
+        >>> GeneralizedLotkaVolterraInteraction('glv', target='species', a=matrix).check().a
+        ((-1.0, 0.5), (0.5, -1.0))
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        a: Annotated[object, ParameterSpec(shape=('target', 'target'))] = -1.0,
+        state: str = 'x',
+    ) -> None:
+        super().__init__(
+            label,
+            target=target,
+            read=state,
+            write=state,
+            function=self._product,
+            mode='group',
+            weights='a',
+            include_self=True,
+        )
+        self.a = a
+        self.state = state
+
+    def _product(self, namespace: SimpleNamespace) -> object:
+        """Return the product `x_i x_j` of the abundances of the species and the other species."""
+        return getattr(namespace.member, self.state) * getattr(namespace.other, self.state)