scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/social/opinion_dynamics/_persuasion.py

@@ -0,0 +1,247 @@
+"""Persuasion models: agreeing pairs, majorities in small groups, and social impact."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+import networkx as nx
+import numpy as np
+
+from ....core.elements import GroupElement
+from ....core.interactions import GroupingInteraction
+from ....core.spaces import LatticeSpace, NetworkSpace
+from ....core.system import System
+from ....core.types import AgentViewProtocol, ModelViewProtocol
+from ....specs import RoleSpec
+from ....types import Array
+from ..._catalog import register_model
+from ._citizen import CitizenElement
+from ._discussions import DiscussionsInteraction
+from ._influencee import InfluenceeElement
+from ._persuader import PersuaderElement
+from ._persuader_view import PersuaderView
+from ._social_impact import SocialImpactInteraction
+
+
+def _shares(size: int, share: float, random_state: int | np.random.Generator | None) -> Array:
+    """Return opinions that are 1 with a probability and 0 otherwise."""
+    return (np.random.default_rng(random_state).random(size) < share).astype(float)
+
+
+class PersuasionInteraction(GroupingInteraction):
+    """Persuasion of the Sznajd model, where an agreeing pair of neighbours convinces the neighbours of both.
+
+    Every step every agent, in random order, picks a random neighbour, and when both share an opinion every neighbour
+    of either adopts it. On a ring this is the original one-dimensional rule, where the pair convinces the two agents
+    beside it.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the group of persuaders.
+
+        phase:
+            The phase of the step the persuasion runs in, or `None` for the default phase.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import PersuasionInteraction
+        >>> PersuasionInteraction('persuasion', target='people').groups
+        'neighborhood'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        phase: str | None = None,
+    ) -> None:
+        super().__init__(label, target=target, groups='neighborhood', phase=phase)
+
+    def act_on(self, members: list[AgentViewProtocol], model: ModelViewProtocol) -> None:
+        """Convince the neighbours of the first member and a random neighbour of it when the two agree.
+
+        Args:
+            members:
+                The persuader, followed by its neighbours.
+
+            model:
+                The model view of the rule.
+        """
+        agent, *neighbors = [member for member in members if isinstance(member, PersuaderView)]
+        if not neighbors:
+            return
+        partner = neighbors[int(model.rng.integers(len(neighbors)))]
+        if partner.opinion != agent.opinion:
+            return
+        for other in [*neighbors, *partner.neighbors()]:
+            if isinstance(other, PersuaderView):
+                other.opinion = agent.opinion
+
+
+@register_model(
+    field='social/opinion_dynamics',
+    tags=('opinion', 'agents', 'network', 'consensus'),
+    references=('Sznajd-Weron and Sznajd 2000', 'Castellano, Fortunato, and Loreto 2009'),
+    defaults={'until': 100},
+)
+def sznajd(
+    graph: object = None,
+    *,
+    share: float = 0.5,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return the Sznajd model, where agreeing pairs of agents convince their neighbours.
+
+    Args:
+        graph:
+            The NetworkX graph, or `None` for a ring of 50 agents.
+
+        share:
+            The share of agents with opinion 1.
+
+        random_state:
+            The seed or generator of the opinions.
+
+    Returns:
+        system:
+            The model, with the group `people` and the persuasion `persuasion`.
+
+    Examples:
+        >>> import networkx as nx
+        >>> from skcomplex.models.social.opinion_dynamics import sznajd
+        >>> sznajd(nx.cycle_graph(8), random_state=0).elements[0].check().prepare().size_
+        8
+    """
+    graph = nx.cycle_graph(50) if graph is None else graph
+    size = nx.number_of_nodes(graph)
+    people = GroupElement(
+        'people',
+        element=PersuaderElement,
+        size=size,
+        values={'opinion': _shares(size, share, random_state)},
+    )
+    return System(
+        elements=[people],
+        interactions=[PersuasionInteraction('persuasion', target='people')],
+        space=NetworkSpace(graph),
+    )
+
+
+@register_model(
+    field='social/opinion_dynamics',
+    tags=('opinion', 'agents', 'majority', 'consensus'),
+    references=('Galam 2002', 'Castellano, Fortunato, and Loreto 2009'),
+    defaults={'until': 20},
+)
+def galam_majority(
+    n_agents: int = 300,
+    *,
+    group_size: int = 3,
+    share: float = 0.4,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return the Galam majority model, where random groups adopt their majority until one opinion wins.
+
+    Args:
+        n_agents:
+            The number of agents.
+
+        group_size:
+            The number of agents in each discussion group.
+
+        share:
+            The share of agents with opinion 1.
+
+        random_state:
+            The seed or generator of the opinions.
+
+    Returns:
+        system:
+            The model, with the group `citizens`.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import galam_majority
+        >>> galam_majority(30, random_state=0).elements[0].check().prepare().size_
+        30
+    """
+    citizens = GroupElement(
+        'citizens',
+        element=CitizenElement,
+        size=n_agents,
+        values={'opinion': _shares(n_agents, share, random_state)},
+    )
+    return System(
+        elements=[citizens],
+        interactions=[DiscussionsInteraction('talks', target='citizens', size=group_size)],
+    )
+
+
+@register_model(
+    field='social/opinion_dynamics',
+    tags=('opinion', 'agents', 'grid', 'clusters'),
+    references=('Nowak, Szamrej, and Latané 1990', 'Castellano, Fortunato, and Loreto 2009'),
+    defaults={'until': 20},
+)
+def social_impact(
+    width: int = 15,
+    height: int = 15,
+    *,
+    share: float = 0.5,
+    exponent: float = 2.0,
+    noise: float = 0.0,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return the social impact model on a full grid, with random persuasiveness and supportiveness.
+
+    Args:
+        width:
+            The number of columns.
+
+        height:
+            The number of rows.
+
+        share:
+            The share of agents with opinion 1, the others holding -1.
+
+        exponent:
+            The exponent of the distance by which impact decays.
+
+        noise:
+            The half-width of the uniform random field.
+
+        random_state:
+            The seed or generator of the opinions and strengths.
+
+    Returns:
+        system:
+            The model, with the group `people`.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import social_impact
+        >>> social_impact(4, 5, random_state=0).elements[0].check().prepare().size_
+        20
+    """
+    rng = np.random.default_rng(random_state)
+    size = width * height
+    people = GroupElement(
+        'people',
+        element=InfluenceeElement,
+        size=size,
+        values={
+            'opinion': 2 * _shares(size, share, rng) - 1,
+            'persuasiveness': rng.random(size),
+            'supportiveness': rng.random(size),
+            'exponent': exponent,
+            'noise': noise,
+        },
+        location=[(column, row) for column in range(width) for row in range(height)],
+    )
+    return System(
+        elements=[people],
+        interactions=[SocialImpactInteraction('impact', target='people')],
+        space=LatticeSpace((width, height), boundary='fixed', capacity=1),
+    )

skcomplex/models/social/opinion_dynamics/_random_pairs.py

@@ -0,0 +1,53 @@
+"""Define random pairs, a grouping that draws as many random ordered pairs of agents per step as there are agents."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.interactions import GroupingInteraction
+from ....core.types import AgentViewProtocol, ModelViewProtocol
+from ....specs import RoleSpec
+
+PAIR = 2
+
+
+class RandomPairsInteraction(GroupingInteraction):
+    """Grouping that draws as many random ordered pairs of distinct agents per step as there are agents.
+
+    The pairs are drawn independently, so an agent can meet several partners in one step, and every pair acts in random
+    order through `act_on`, which a subclass overrides. One unit of time holds one encounter per agent, as in the
+    random sequential encounters of mean-field opinion and convention models.
+
+    Args:
+        label:
+            The label of the interaction, unique among the parts of its system.
+
+        target:
+            The path of the group whose agents meet in pairs.
+
+        phase:
+            The phase of the step the encounters run in, or `None` for the default phase.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import RandomPairsInteraction
+        >>> RandomPairsInteraction('meetings', target='people').groups
+        'pairs'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        phase: str | None = None,
+    ) -> None:
+        super().__init__(label, target=target, groups='pairs', phase=phase)
+
+    def _get_groups(self, model: ModelViewProtocol) -> list[list[AgentViewProtocol]]:
+        """Return one random ordered pair of distinct agents per agent."""
+        agents = [agent for agent in model.agents('target') if agent.alive]
+        if len(agents) < PAIR:
+            return []
+        draws = [model.rng.choice(len(agents), size=PAIR, replace=False) for _ in agents]
+        return [[agents[int(first)], agents[int(second)]] for first, second in draws]

skcomplex/models/social/opinion_dynamics/_schedule.py

@@ -0,0 +1,39 @@
+"""Triangle of a temporal hypergraph, active in every other half of a period from its own phase."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import ParameterSpec, VisualSpec
+
+
+class ScheduleElement(Element):
+    """Triangle of a temporal hypergraph, active in every other half of a period from its own phase.
+
+    Args:
+        label:
+            The label of the triangle or the group.
+
+        visual:
+            How the triangle is drawn, or `None` for `default_visual_`.
+
+        phase:
+            The phase of the schedule, in radians.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import ScheduleElement
+        >>> ScheduleElement('triangle', phase=1.0).phase
+        1.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        phase: Annotated[float, ParameterSpec()] = 0.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.phase = phase

skcomplex/models/social/opinion_dynamics/_separation.py

@@ -0,0 +1,71 @@
+"""Rewiring of discordant edges by one end, which keeps the edge and moves its other end to a like-minded node."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.interactions import TopologyInteraction
+from ....specs import RoleSpec
+
+SMALLEST_DEGREE = 1e-9
+
+
+class SeparationInteraction(TopologyInteraction):
+    """Rewiring of discordant edges by one end, which keeps the edge and moves its other end to a like-minded node.
+
+    It is a `TopologyInteraction` that rewires the edges of the voters. The end `keep` acts on an edge with
+    probability `activity / degree` per step, and when it holds the opinion `opinion` and the other end does not, it
+    rewires the edge with probability `rewiring`, drawing a new end among the voters of the opinion `opinion`.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        voters:
+            The path of the voters on the nodes.
+
+        keep:
+            The end of an edge that acts and keeps the edge, `'source'` or `'target'`.
+
+        opinion:
+            The opinion of the end that acts, 0 or 1.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import SeparationInteraction
+        >>> SeparationInteraction('separation', voters='voters', keep='target', opinion=0).check().action
+        'rewire'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        voters: Annotated[str, RoleSpec()],
+        keep: str = 'source',
+        opinion: float = 1.0,
+    ) -> None:
+        super().__init__(
+            label,
+            target=voters,
+            action='rewire',
+            probability=self._get_chance,
+            toward=self._get_weight,
+            keep=keep,
+        )
+        self.voters = voters
+        self.keep = keep
+        self.opinion = opinion
+
+    def _get_weight(self, node: SimpleNamespace) -> object:
+        """Return the weight of a candidate node as a new end, 1 when it holds the opinion of the acting end."""
+        return node.opinion if self.opinion == 1 else 1 - node.opinion
+
+    def _get_chance(self, namespace: SimpleNamespace) -> object:
+        """Return the probability that the acting end rewires the edge, when the ends hold different opinions."""
+        actor, other = (namespace.source, namespace.target)[:: 1 if self.keep == 'source' else -1]
+        chance = actor.activity * actor.rewiring / (actor.degree + SMALLEST_DEGREE)
+        if self.opinion == 1:
+            return chance * actor.opinion * (1 - other.opinion)
+        return chance * (1 - actor.opinion) * other.opinion

skcomplex/models/social/opinion_dynamics/_social_impact.py

@@ -0,0 +1,60 @@
+"""Synchronous update of the social impact model, where every agent takes the opinion of the stronger impact."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+import numpy as np
+
+from ....core.interactions import MapInteraction
+from ....core.types import ModelViewProtocol
+from ....specs import RoleSpec
+from ._influencee_view import InfluenceeView
+
+
+class SocialImpactInteraction(MapInteraction):
+    """Synchronous update of the social impact model, where every agent takes the opinion of the stronger impact.
+
+    The impact on agent `i` is `I_i = sum_j t_j (1 - o_i o_j) / d_ij^a - sum_j s_j (1 + o_i o_j) / d_ij^a`, with the
+    persuasiveness `t`, the supportiveness `s`, and the distance `d` on the grid, where an agent supports itself from
+    distance 1. The impact is the net pressure to change, whatever the opinion, so an agent flips its opinion when
+    `I_i + h_i > 0`, with a uniform random field `h_i`. Every agent decides from the opinions at the start of the step.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the group of agents.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import SocialImpactInteraction
+        >>> SocialImpactInteraction('impact', target='people').check().form
+        'agent'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+    ) -> None:
+        super().__init__(label, target=target, state='opinion', function=self._get_opinion, form='agent')
+
+    def _get_impact(self, agent: InfluenceeView, model: ModelViewProtocol) -> float:
+        """Return the net pressure to change on an agent from every agent of the group, itself from distance 1."""
+        agents = [item for item in model.agents('target') if isinstance(item, InfluenceeView)]
+        locations = np.array([item.location for item in agents], dtype=float)
+        distances = np.linalg.norm(locations - np.asarray(agent.location, dtype=float), axis=-1)
+        distances[[item.id == agent.id for item in agents]] = 1.0
+        weights = distances**-agent.exponent
+        agreement = agent.opinion * np.array([item.opinion for item in agents], dtype=float)
+        persuasion = np.array([item.persuasiveness for item in agents], dtype=float)
+        support = np.array([item.supportiveness for item in agents], dtype=float)
+        return float((weights * persuasion * (1 - agreement)).sum() - (weights * support * (1 + agreement)).sum())
+
+    def _get_opinion(self, agent: InfluenceeView, model: ModelViewProtocol) -> float:
+        """Return the opposite opinion of an agent under a positive net pressure to change, and its own otherwise."""
+        field = model.rng.uniform(-agent.noise, agent.noise)
+        return -agent.opinion if self._get_impact(agent, model) + field > 0 else float(agent.opinion)

skcomplex/models/social/opinion_dynamics/_standardization.py

@@ -0,0 +1,212 @@
+"""Opinion dynamics models: complex agents with many internal configurations whose interactions standardize them."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+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 GroupElement
+from ....core.interactions import ChoiceInteraction, MapInteraction
+from ....core.spaces import DiscreteTime
+from ....core.system import System
+from ....core.types import ModelViewProtocol
+from ....specs import ObservableSpec, ParameterSpec, PhaseSpec, PhasesScheduleSpec, RoleSpec
+from ....types import AnyArray, Array
+from ..._catalog import register_model
+from ._complex_agent import ComplexAgentElement
+from ._complex_agent_view import ComplexAgentView
+
+MARKED = 2
+
+
+PHASE = 'default'
+
+
+def _standardization(spins: AnyArray) -> float:
+    """Return the share `q` of agents that show the characteristic, the mean of `|S_i|`."""
+    return float(np.mean(np.abs(spins)))
+
+
+def _spin_of(agent: ComplexAgentView, model: ModelViewProtocol) -> float:
+    """Return the spin of the configuration of an agent."""
+    return float(StandardizationInteraction._spins_of(np.array(agent.configuration)))
+
+
+class StandardizationInteraction(ChoiceInteraction):
+    """Changes of configuration of random agents, accepted with the logistic probability of their gain in utility.
+
+    The utility of agent `i` is `u_i = K / N sum_j |S_i| |S_j| + J / N sum_j S_i S_j` over the other agents. An agent
+    proposes a configuration drawn uniformly from the `H + 2` configurations, its own included, and takes it with the
+    probability `1 / (1 + exp(-beta (u_i' - u_i)))` of the rule `'fermi'`, so the agents sample `P ~ exp(beta E)`. The
+    utilities read the counts of the configurations of the group, so every proposal sees the changes accepted before
+    it. In `standardized_agents`, a phase of visits draws `N` agents with replacement every unit of time.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the group of agents.
+
+        K:
+            The coupling of the characteristics `|S_i|`, which standardizes the agents.
+
+        J:
+            The coupling of the spins `S_i`, which orders the standardized agents.
+
+        H:
+            The number of configurations without the characteristic.
+
+        intensity:
+            The intensity of choice `beta`, the inverse of the temperature.
+
+        activity:
+            The probability that a visited agent proposes a configuration.
+
+        phase:
+            The phase of the step the choice runs in, or `None` for the default phase.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import StandardizationInteraction
+        >>> StandardizationInteraction('standardization', target='agents', H=100).check().options[-1]
+        101.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        K: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 10.0,
+        J: Annotated[float, ParameterSpec()] = 1.0,
+        H: int = 50,
+        intensity: float = 2.0,
+        activity: float = 1.0,
+        phase: str | None = None,
+    ) -> None:
+        super().__init__(
+            label,
+            target=target,
+            state='configuration',
+            options=tuple(float(option) for option in range(H + MARKED)),
+            utility=self._get_utility,
+            rule='fermi',
+            intensity=intensity,
+            schedule='member',
+            activity=activity,
+            form='agent',
+            phase=phase,
+            proposal='all',
+        )
+        self.K = K
+        self.J = J
+        self.H = H
+
+    def _get_utility(self, agent: ComplexAgentView, model: ModelViewProtocol, option: float) -> float:
+        """Return the utility of a configuration for an agent, from the counts of the configurations of the others."""
+        counts = model.composition('target', 'configuration')
+        up, down = counts.get(0.0, 0), counts.get(1.0, 0)
+        spin, new = float(StandardizationInteraction._spins_of(np.array(agent.configuration))), float(
+            StandardizationInteraction._spins_of(np.array(option)),
+        )
+        standardizing = model.parameter('K') * abs(new) * (up + down - abs(spin))
+        ordering = model.parameter('J') * new * (up - down - spin)
+        return (standardizing + ordering) / sum(counts.values())
+
+    @staticmethod
+    def _spins_of(configurations: Array) -> Array:
+        """Return the spin of each configuration: 1 for configuration 0, -1 for configuration 1, and 0 otherwise."""
+        return np.select([configurations == 0, configurations == 1], [1.0, -1.0], 0.0)
+
+
+@register_model(
+    field='social/opinion_dynamics',
+    tags=('agents', 'standardization', 'phase transition', 'large deviations', 'mean field'),
+    references=('Bertin 2021', 'Bertin and Jensen 2019'),
+    defaults={'until': 1000},
+    observables=lambda system: [
+        ObservableSpec('q', group='agents', variable='spin', reduce=_standardization),
+        ObservableSpec('m', group='agents', variable='spin', reduce='mean'),
+    ],
+)
+def standardized_agents(
+    agents: int = 100,
+    *,
+    K: float = 10.0,
+    J: float = 1.0,
+    T: float = 0.5,
+    H: int = 50,
+    standardized: float = 1.0,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return complex agents whose interactions make them standardized, all showing one characteristic, and ordered.
+
+    Below the temperature `T_S = K / (2 ln(H / 2))` the most probable share of agents with the characteristic jumps
+    from `q ~ 0` to `q ~ 1`, a discontinuous transition, and below `T_M = J` the standardized agents order, with a
+    magnetization `m` of either sign. Both states are long-lived on either side of `T_S` in large groups, so the
+    initial share `standardized` selects the branch that the run follows.
+
+    Args:
+        agents:
+            The number of agents `N`.
+
+        K:
+            The coupling of the characteristics `|S_i|`, which standardizes the agents.
+
+        J:
+            The coupling of the spins `S_i`, which orders the standardized agents.
+
+        T:
+            The temperature, the randomness of the choices.
+
+        H:
+            The number of configurations without the characteristic.
+
+        standardized:
+            The initial share of agents with the characteristic, each with a random spin. The others start in random
+            configurations without it.
+
+        random_state:
+            The seed or generator of the initial configurations.
+
+    Returns:
+        system:
+            The model, with the group `agents`, the share `q` of agents with the characteristic, and the magnetization
+            `m`, the mean spin.
+
+    Examples:
+        >>> from skcomplex.models.social.opinion_dynamics import standardized_agents
+        >>> standardized_agents(10, standardized=0.0).elements[0].values['spin'].tolist()
+        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+    """
+    rng = np.random.default_rng(random_state)
+    marked = rng.random(agents) < standardized
+    configurations = np.where(marked, rng.integers(MARKED, size=agents), rng.integers(MARKED, H + MARKED, size=agents))
+    configurations = configurations.astype(float)
+    return System(
+        elements=[
+            GroupElement(
+                'agents',
+                element=ComplexAgentElement,
+                size=agents,
+                values={'configuration': configurations, 'spin': StandardizationInteraction._spins_of(configurations)},
+            ),
+        ],
+        interactions=[
+            StandardizationInteraction('standardization', target='agents', K=K, J=J, H=H, intensity=1 / T, phase=PHASE),
+            MapInteraction(
+                'spin',
+                target='agents',
+                state='spin',
+                function=_spin_of,
+                schedule='member',
+                form='agent',
+                phase=PHASE,
+            ),
+        ],
+        time=DiscreteTime(schedule=PhasesScheduleSpec([PhaseSpec(PHASE, activation='visits', groups=('agents',))])),
+    )