scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/social/crowds/_guidance.py

@@ -0,0 +1,69 @@
+"""Encounters with the exit signs that speed pedestrians up again."""
+
+# 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 EncounterInteraction
+from ....specs import ParameterSpec, RoleSpec
+from ._crowding import crowding_table
+
+
+class GuidanceInteraction(EncounterInteraction):
+    """Encounters with the exit signs that speed pedestrians up again.
+
+    It is an `EncounterInteraction` of the crowd with the exit signs. A pedestrian meets the exit signs at the rate
+    `recovery` and speeds up one class. Pedestrians outside keep their speed.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        candidate:
+            The path of the crowd, a distribution over rooms and speed classes.
+
+        field:
+            The path of the group of one member whose fixed density is the guidance of the exit signs.
+
+        rooms:
+            The number of rooms.
+
+        speeds:
+            The number of speed classes.
+
+        recovery:
+            The rate at which pedestrians speed up again.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import GuidanceInteraction
+        >>> GuidanceInteraction('guidance', candidate='crowd', field='signs').recovery
+        0.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        candidate: Annotated[str, RoleSpec()],
+        field: Annotated[str, RoleSpec()],
+        rooms: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 7,
+        speeds: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 3,
+        recovery: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
+    ) -> None:
+        super().__init__(label, candidate=candidate, field=field, rate=self._get_rate, kernel=self._get_kernel)
+        self.rooms = rooms
+        self.speeds = speeds
+        self.recovery = recovery
+
+    def _get_rate(self, s: SimpleNamespace) -> object:
+        """Return the rate of the encounters of every class with the exit signs."""
+        return crowding_table(int(self.rooms), int(self.speeds), 1)[0] * s.recovery
+
+    def _get_kernel(self, s: SimpleNamespace) -> object:
+        """Return the table that moves a pedestrian up one speed class."""
+        return crowding_table(int(self.rooms), int(self.speeds), 1)[1]

skcomplex/models/social/crowds/_motivation.py

@@ -0,0 +1,67 @@
+"""Driving force of the social force model, which relaxes a walker's velocity to its desired velocity."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+import numpy.typing as npt
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import (
+    RelaxationInteraction,
+)
+from ....specs import ParameterSpec, RoleSpec
+
+
+class MotivationInteraction(RelaxationInteraction):
+    """Driving force of the social force model, which relaxes a walker's velocity to its desired velocity.
+
+    The force per unit mass is `(speed * direction - x_d1) / tau`, where the velocity `x_d1` is the first derivative of
+    the position `x`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the walker or group of walkers.
+
+        speed:
+            The desired speed.
+
+        direction:
+            The unit vector of the desired direction.
+
+        tau:
+            The relaxation time.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import MotivationInteraction
+        >>> MotivationInteraction('drive', target='walkers', direction=[1.0, 0.0]).speed
+        1.34
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        speed: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.34,
+        direction: Annotated[npt.ArrayLike, ParameterSpec(vector=True)] = 0.0,
+        tau: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.5,
+    ) -> None:
+        super().__init__(label, target=target, state='x_d1')
+        self.speed = speed
+        self.direction = direction
+        self.tau = tau
+
+    def _get_goal(self, namespace: SimpleNamespace) -> object:
+        """Return the desired velocity."""
+        return namespace.speed * namespace.direction
+
+    def _get_time(self, namespace: SimpleNamespace) -> object:
+        """Return the relaxation time."""
+        return namespace.tau

skcomplex/models/social/crowds/_pedestrians.py

@@ -0,0 +1,85 @@
+"""Pedestrian models: walkers driven by desired velocities and social forces."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+
+from ....core.elements import GroupElement, PointElement
+from ....core.interactions import (
+    BaseInteraction,
+)
+from ....core.spaces import ContinuousSpace
+from ....core.system import System
+from ....engine.solvers import RK4Solver
+from ..._catalog import register_model
+from ._motivation import MotivationInteraction
+from ._social_repulsion import SocialRepulsionInteraction
+from ._walls import WallsInteraction
+
+
+@register_model(
+    field='social/crowds',
+    tags=('pedestrians', 'particles', 'lanes', 'self-organization'),
+    references=('Helbing and Molnár 1995', 'Helbing 2001'),
+    defaults={'until': 20.0, 'dt': 0.2, 'solver': RK4Solver(dt=0.05)},
+)
+def social_force(
+    n_walkers: int = 20,
+    *,
+    length: float = 10.0,
+    speed: float = 1.34,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return two crowds walking in opposite directions along a periodic corridor, which form lanes.
+
+    Args:
+        n_walkers:
+            The number of walkers in each direction.
+
+        length:
+            The length and the width of the corridor, periodic along its length.
+
+        speed:
+            The desired speed.
+
+        random_state:
+            The seed or generator of the initial positions.
+
+    Returns:
+        system:
+            The model, with the groups `rightward` and `leftward`.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import social_force
+        >>> [group.size for group in social_force(5).elements]
+        [5, 5]
+    """
+    rng = np.random.default_rng(random_state)
+    cutoff = 2.0
+    walkers = [
+        GroupElement(
+            label,
+            element=PointElement,
+            size=n_walkers,
+            values={'x': rng.uniform([0.0, 0.5], [length, length - 0.5], (n_walkers, 2))},
+        )
+        for label in ('rightward', 'leftward')
+    ]
+    interactions: list[BaseInteraction] = []
+    for label, sign in (('rightward', 1.0), ('leftward', -1.0)):
+        interactions += [
+            MotivationInteraction(f'{label}_drive', target=label, speed=speed, direction=[sign, 0.0]),
+            WallsInteraction(f'{label}_walls', target=label, width=length),
+        ]
+    pairs = (('rightward', 'rightward'), ('leftward', 'leftward'), ('rightward', 'leftward'))
+    interactions += [
+        SocialRepulsionInteraction(f'{first}_{second}', first=first, second=second, cutoff=cutoff, period=length)
+        for first, second in pairs
+    ]
+    return System(
+        elements=walkers,
+        interactions=interactions,
+        space=ContinuousSpace(extent=(length, length), boundary='periodic'),
+    )

skcomplex/models/social/crowds/_recruitment.py

@@ -0,0 +1,90 @@
+"""Recruitment of security agents in proportion to the mean criminality, a macro-scale external action."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+import numpy as np
+import numpy.typing as npt
+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 moment
+from ....specs import ParameterSpec, RoleSpec
+
+
+def criminality_grid(classes: int) -> npt.NDArray[np.float64]:
+    """Return the criminality of every class of citizens, from 0 for honest to 1 for criminal.
+
+    Args:
+        classes:
+            The number of criminality classes.
+
+    Returns:
+        criminality:
+            The criminality of every class.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import criminality_grid
+        >>> criminality_grid(3).tolist()
+        [0.0, 0.5, 1.0]
+    """
+    return np.linspace(0.0, 1.0, classes)
+
+
+class RecruitmentInteraction(RateInteraction):
+    """Recruitment of security agents in proportion to the mean criminality, a macro-scale external action.
+
+    It is a `RateInteraction` of the density `f` of the security forces that reads the citizens. The security forces
+    grow at the rate `recruitment m share_k` in efficacy class `k`, where `m` is the mean criminality of the citizens,
+    a moment of their distribution, and retire at the rate `retirement`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the distribution of the security forces over efficacy.
+
+        citizens:
+            The path of the distribution of citizens.
+
+        classes:
+            The number of criminality classes.
+
+        recruitment:
+            The recruitment rate per unit of mean criminality.
+
+        retirement:
+            The retirement rate.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import RecruitmentInteraction
+        >>> RecruitmentInteraction('recruitment', target='security', citizens='citizens').retirement
+        0.1
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        citizens: Annotated[str, RoleSpec()],
+        classes: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 5,
+        recruitment: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
+        retirement: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
+    ) -> None:
+        super().__init__(label, target=target, state='f', rate=self._get_rate)
+        self.citizens = citizens
+        self.classes = classes
+        self.recruitment = recruitment
+        self.retirement = retirement
+
+    def _get_rate(self, s: SimpleNamespace) -> Expression:
+        """Return the recruitment in proportion to the mean criminality of the citizens, less the retirement."""
+        security, citizens = s.target, s.citizens
+        criminality = moment(citizens.f, 1, criminality_grid(int(self.classes)), normalized=True)
+        return s.recruitment * criminality * security.share - s.retirement * security.f

skcomplex/models/social/crowds/_security_agents.py

@@ -0,0 +1,48 @@
+"""Density of security agents at one efficacy class, with the share of new recruits that join the class."""
+
+# 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 SecurityAgentsElement(Element):
+    """Density of security agents at one efficacy class, with the share of new recruits that join the class.
+
+    Args:
+        label:
+            The label of the distribution.
+
+        visual:
+            How the agent is drawn, or `None` for `default_visual_`.
+
+        f:
+            The initial density.
+
+        share:
+            The share of new recruits that join the efficacy class.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.social.crowds import SecurityAgentsElement
+        >>> GroupElement('security', element=SecurityAgentsElement, size=3, values={'share': [0.5, 0.3, 0.2]}).size
+        3
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        f: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        share: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.f = f
+        self.share = share

skcomplex/models/social/crowds/_social_repulsion.py

@@ -0,0 +1,86 @@
+"""Repulsion between two walkers, the force `strength * exp((2 * radius - r) / falloff)` of the social force model."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import Expression, exp, oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import (
+    PairCouplingInteraction,
+)
+from ....specs import ParameterSpec
+
+
+class SocialRepulsionInteraction(PairCouplingInteraction):
+    """Repulsion between two walkers, the force `strength * exp((2 * radius - r) / falloff)` of the social force model.
+
+    It derives from the pair energy `strength * falloff * exp((2 * radius - r) / falloff)`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        first:
+            The path of the group or walker of the first members.
+
+        second:
+            The path of the group or walker of the second members.
+
+        cutoff:
+            The distance beyond which walkers do not interact.
+
+        position:
+            The name of the vector state that holds the positions of the walkers.
+
+        period:
+            The side of a periodic box, for minimum image distances, or `None` for an open space.
+
+        strength:
+            The strength of the repulsion.
+
+        falloff:
+            The distance over which the repulsion falls off.
+
+        radius:
+            The radius of a walker.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import SocialRepulsionInteraction
+        >>> SocialRepulsionInteraction('repulsion', first='walkers', second='walkers').strength
+        2.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        first: str,
+        second: str,
+        cutoff: float = 1.0,
+        position: str = 'x',
+        *,
+        period: float | None = None,
+        strength: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
+        falloff: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.3,
+        radius: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
+    ) -> None:
+        super().__init__(
+            label,
+            first,
+            second,
+            cutoff=cutoff,
+            position=position,
+            potential=self._get_pair_energy,
+            period=period,
+        )
+        self.strength = strength
+        self.falloff = falloff
+        self.radius = radius
+
+    @staticmethod
+    def _get_pair_energy(s: SimpleNamespace, r: Expression) -> Expression:
+        """Return the pair energy `strength * falloff * exp((2 * radius - r) / falloff)`."""
+        return s.strength * s.falloff * exp((2 * s.radius - r) / s.falloff)

skcomplex/models/social/crowds/_walking.py

@@ -0,0 +1,186 @@
+"""Walking of pedestrians to the next room on the way out, an encounter with the exit signs."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+import networkx as nx
+import numpy as np
+import numpy.typing as npt
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import EncounterInteraction
+from ....specs import ParameterSpec, RoleSpec
+
+
+def building_of(branching: int, depth: int) -> nx.Graph:
+    """Return a building whose rooms form a balanced tree, with the exit door in room 0, the root.
+
+    Args:
+        branching:
+            The number of rooms behind every door of a room further from the exit.
+
+        depth:
+            The number of doors between the exit room and the rooms furthest from it.
+
+    Returns:
+        building:
+            The network of rooms, labelled `0` to `rooms - 1`, whose edges are the doors.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import building_of
+        >>> building_of(2, 2).number_of_nodes()
+        7
+    """
+    return nx.balanced_tree(branching, depth)
+
+
+def walking_speeds(speeds: int) -> npt.NDArray[np.float64]:
+    """Return the walking speed of every speed class, evenly spaced from a quarter of the free speed to the free speed.
+
+    Args:
+        speeds:
+            The number of speed classes.
+
+    Returns:
+        speeds:
+            The walking speed of every class, as a fraction of the free speed.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import walking_speeds
+        >>> walking_speeds(4).tolist()
+        [0.25, 0.5, 0.75, 1.0]
+    """
+    return np.linspace(0.25, 1.0, speeds)
+
+
+def next_rooms(building: nx.Graph, exit_room: int) -> list[int]:
+    """Return the next room on the shortest path to the exit room from every room, and the outside for the exit room.
+
+    Args:
+        building:
+            The network of rooms, labelled `0` to `rooms - 1`, whose edges are the doors.
+
+        exit_room:
+            The room whose door leads outside.
+
+    Returns:
+        next_rooms:
+            The next room of every room, with `rooms` standing for the outside.
+
+    Examples:
+        >>> import networkx as nx
+        >>> from skcomplex.models.social.crowds import next_rooms
+        >>> next_rooms(nx.path_graph(3), 0)
+        [3, 0, 1]
+    """
+    paths = nx.shortest_path(building, target=exit_room)
+    rooms = building.number_of_nodes()
+    return [rooms if room == exit_room else int(paths[room][1]) for room in range(rooms)]
+
+
+def walking_table(building: nx.Graph, exit_room: int, speeds: int) -> tuple[npt.NDArray[np.float64], ...]:
+    """Return the rate pattern and the transition table of walking to the next room, an encounter with exit signs.
+
+    The sites of the crowd are indexed by room and speed class in row-major order, with one last row of sites for the
+    outside. A pedestrian of speed `v` in a room walks to the next room on the way to the exit at the rate `v`.
+
+    Args:
+        building:
+            The network of rooms, labelled `0` to `rooms - 1`.
+
+        exit_room:
+            The room whose door leads outside.
+
+        speeds:
+            The number of speed classes.
+
+    Returns:
+        pattern:
+            The rate pattern `eta[h, 0]`, the walking speed of the site, 0 outside.
+
+        table:
+            The transition table `A[h, 0, i]`.
+
+    Examples:
+        >>> import networkx as nx
+        >>> from skcomplex.models.social.crowds import walking_table
+        >>> pattern, table = walking_table(nx.path_graph(2), 0, 2)
+        >>> pattern.ravel().tolist()
+        [0.25, 1.0, 0.25, 1.0, 0.0, 0.0]
+    """
+    following = next_rooms(building, exit_room)
+    velocity = walking_speeds(speeds)
+    sites = (len(following) + 1) * speeds
+    pattern = np.zeros((sites, 1))
+    table = np.zeros((sites, 1, sites))
+    for site in range(sites):
+        room, speed = divmod(site, speeds)
+        if room == len(following):
+            table[site, 0, site] = 1.0
+            continue
+        pattern[site, 0] = velocity[speed]
+        table[site, 0, following[room] * speeds + speed] = 1.0
+    return pattern, table
+
+
+class WalkingInteraction(EncounterInteraction):
+    """Walking of pedestrians to the next room on the way out, an encounter with the exit signs.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        candidate:
+            The path of the crowd, a distribution over rooms and speed classes.
+
+        field:
+            The path of the group of one member whose fixed density is the guidance of the exit signs.
+
+        branching:
+            The number of rooms behind every door of the building, a balanced tree of rooms with the exit in room 0.
+
+        depth:
+            The number of doors between the exit room and the rooms furthest from it.
+
+        speeds:
+            The number of speed classes.
+
+        mobility:
+            The rate at which pedestrians at the free speed leave a room.
+
+    Examples:
+        >>> from skcomplex.models.social.crowds import WalkingInteraction
+        >>> WalkingInteraction('walking', candidate='crowd', field='signs').mobility
+        0.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        candidate: Annotated[str, RoleSpec()],
+        field: Annotated[str, RoleSpec()],
+        branching: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 2,
+        depth: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 2,
+        speeds: Annotated[int, ParameterSpec(domain=RealSet.open(0, oo))] = 3,
+        mobility: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
+    ) -> None:
+        super().__init__(label, candidate=candidate, field=field, rate=self._get_rate, kernel=self._get_kernel)
+        self.branching = branching
+        self.depth = depth
+        self.speeds = speeds
+        self.mobility = mobility
+
+    def _get_rate(self, s: SimpleNamespace) -> object:
+        """Return the rate at which every speed class of every room leaves it."""
+        building = building_of(int(self.branching), int(self.depth))
+        return walking_table(building, 0, int(self.speeds))[0] * s.mobility
+
+    def _get_kernel(self, s: SimpleNamespace) -> object:
+        """Return the table that moves a walker to the next room on the way out."""
+        building = building_of(int(self.branching), int(self.depth))
+        return walking_table(building, 0, int(self.speeds))[1]