scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/economics/markets/_exchange.py

@@ -0,0 +1,171 @@
+"""Define bilateral exchange of goods between agents with Cobb-Douglas preferences."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import itertools
+import math
+from collections.abc import Sequence
+
+from ....core.laws.utils import transfer
+
+
+def cobb_douglas(agent: object, goods: Sequence[str], weights: Sequence[str]) -> float:
+    """Return the logarithm of the Cobb-Douglas utility of an agent, `sum_i a_i log x_i`.
+
+    Args:
+        agent:
+            The agent, with a state for the holding of every good and for the weight of every good.
+
+        goods:
+            The names of the states that hold the goods.
+
+        weights:
+            The names of the states that hold the weights of the goods, in the order of `goods`.
+
+    Returns:
+        utility:
+            The logarithm of the utility, minus infinity when a weighted good runs out.
+
+    Examples:
+        >>> from types import SimpleNamespace
+        >>> from skcomplex.models.economics.markets import cobb_douglas
+        >>> agent = SimpleNamespace(x=4.0, y=1.0, a=0.5, b=0.5)
+        >>> round(cobb_douglas(agent, ('x', 'y'), ('a', 'b')), 6)
+        0.693147
+    """
+    total = 0.0
+    for good, weight in zip(goods, weights, strict=True):
+        share, holding = float(getattr(agent, weight)), float(getattr(agent, good))
+        if share == 0:
+            continue
+        if holding <= 0:
+            return -math.inf
+        total += share * math.log(holding)
+    return total
+
+
+def marginal_rate(agent: object, good: str, numeraire: str, weights: tuple[str, str]) -> float:
+    """Return the marginal rate of substitution of a good for a numeraire, the units of numeraire one unit is worth.
+
+    Args:
+        agent:
+            The agent.
+
+        good:
+            The name of the state that holds the good.
+
+        numeraire:
+            The name of the state that holds the numeraire.
+
+        weights:
+            The names of the states that hold the weights of the good and of the numeraire.
+
+    Returns:
+        rate:
+            The ratio of the marginal utilities, `(a_good / x_good) / (a_numeraire / x_numeraire)`.
+
+    Examples:
+        >>> from types import SimpleNamespace
+        >>> from skcomplex.models.economics.markets import marginal_rate
+        >>> agent = SimpleNamespace(x=2.0, y=6.0, a=0.5, b=0.5)
+        >>> marginal_rate(agent, 'x', 'y', ('a', 'b'))
+        3.0
+    """
+    good_weight, numeraire_weight = (float(getattr(agent, name)) for name in weights)
+    return (good_weight / float(getattr(agent, good))) / (numeraire_weight / float(getattr(agent, numeraire)))
+
+
+def _trade_once(
+    first: object,
+    second: object,
+    pair: tuple[int, int],
+    *,
+    goods: Sequence[str],
+    weights: Sequence[str],
+    quantity: float,
+) -> float | None:
+    """Trade a quantity of one good for its price in another when both traders gain, and return the price."""
+    good, numeraire = goods[pair[0]], goods[pair[1]]
+    names = (weights[pair[0]], weights[pair[1]])
+    if not all(float(getattr(agent, name)) > 0 for agent in (first, second) for name in names):
+        return None
+    rates = [marginal_rate(agent, good, numeraire, names) for agent in (first, second)]
+    if math.isclose(rates[0], rates[1]):
+        return None
+    buyer, seller = (first, second) if rates[0] > rates[1] else (second, first)
+    price = math.sqrt(rates[0] * rates[1])
+    payment = price * quantity
+    if float(getattr(seller, good)) <= quantity or float(getattr(buyer, numeraire)) <= payment:
+        return None
+    before = (cobb_douglas(buyer, goods, weights), cobb_douglas(seller, goods, weights))
+    transfer(seller, buyer, quantity, good)
+    transfer(buyer, seller, payment, numeraire)
+    if cobb_douglas(buyer, goods, weights) > before[0] and cobb_douglas(seller, goods, weights) > before[1]:
+        return price
+    transfer(buyer, seller, quantity, good)
+    transfer(seller, buyer, payment, numeraire)
+    return None
+
+
+def trade_goods(
+    first: object,
+    second: object,
+    goods: Sequence[str],
+    weights: Sequence[str],
+    *,
+    quantity: float = 0.1,
+    limit: int = 1000,
+) -> list[tuple[int, int, float]]:
+    """Barter small quantities of goods between two agents while both gain, and return the trades.
+
+    For every pair of goods in turn, the agent that values the first good more in units of the second buys `quantity`
+    of it from the other at the geometric mean of their marginal rates of substitution, as in the Sugarscape trade of
+    Epstein and Axtell (1996). A trade happens only when it raises the Cobb-Douglas utility of both agents, and every
+    trade is two transfers, so the total of every good is unchanged. The agents trade until a round over all pairs of
+    goods makes no trade, or until `limit` trades.
+
+    Args:
+        first:
+            The first agent, with a state for the holding and for the weight of every good.
+
+        second:
+            The second agent.
+
+        goods:
+            The names of the states that hold the goods.
+
+        weights:
+            The names of the states that hold the weights of the goods, in the order of `goods`.
+
+        quantity:
+            The quantity of the bought good in every trade.
+
+        limit:
+            The largest number of trades.
+
+    Returns:
+        trades:
+            The index of the bought good, the index of the good paid with, and the price of every trade.
+
+    Examples:
+        >>> from types import SimpleNamespace
+        >>> from skcomplex.models.economics.markets import trade_goods
+        >>> first = SimpleNamespace(x=9.0, y=1.0, a=0.5, b=0.5)
+        >>> second = SimpleNamespace(x=1.0, y=9.0, a=0.5, b=0.5)
+        >>> trades = trade_goods(first, second, ('x', 'y'), ('a', 'b'), quantity=0.5)
+        >>> first.x + second.x, len(trades) > 0
+        (10.0, True)
+    """
+    trades: list[tuple[int, int, float]] = []
+    pairs = list(itertools.combinations(range(len(goods)), 2))
+    while len(trades) < limit:
+        traded = False
+        for pair in pairs:
+            price = _trade_once(first, second, pair, goods=goods, weights=weights, quantity=quantity)
+            if price is not None:
+                trades.append((pair[0], pair[1], price))
+                traded = True
+        if not traded:
+            break
+    return trades

skcomplex/models/economics/markets/_exchange_interaction.py

@@ -0,0 +1,134 @@
+"""Bilateral barter between paired traders, a transfer whose trades repeat while both traders gain."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import math
+from types import SimpleNamespace
+from typing import ClassVar
+
+import numpy as np
+
+from ....core.interactions import TransferInteraction
+from ....core.laws import BaseLaw, RuleLaw
+from ....core.types import AgentViewProtocol, ModelViewProtocol
+from ._exchange import trade_goods
+
+GOODS = ('sugar', 'spice', 'salt')
+
+
+class ExchangeInteraction(TransferInteraction):
+    """Bilateral barter between paired traders, a transfer whose trades repeat while both traders gain.
+
+    Every step the transfer pairs the traders, and every pair barters small quantities of every pair of goods at the
+    geometric mean of their marginal rates of substitution while both gain. A trader holds every good in the state of
+    its name and its Cobb-Douglas weight in the state `<good>_weight`. Every trade moves goods between the two traders,
+    so the total of every good stays the same, which the default run checks as invariants. The exchange reports the
+    mean `price` of the second good in units of the first, the standard deviation `dispersion` of its logarithm over
+    the trades of the step, and the number of trades `volume`.
+
+    Args:
+        label:
+            The label of the exchange.
+
+        source:
+            The path of the group of traders.
+
+        target:
+            The path of the group of traders, the source again.
+
+        goods:
+            The names of the traded goods.
+
+        pairing:
+            How the transfer pairs the traders, such as `'neighbor-pairs'` for disjoint pairs of neighbours or
+            `'pairs'` for disjoint random pairs.
+
+        quantity:
+            The quantity of the bought good in every trade.
+
+        phase:
+            The phase the trades run in.
+
+    Examples:
+        >>> from skcomplex.models.economics.markets import ExchangeInteraction
+        >>> ExchangeInteraction('exchange', source='traders', target='traders').reports
+        ('price', 'dispersion', 'volume')
+    """
+
+    reports: ClassVar[tuple[str, ...]] = ('price', 'dispersion', 'volume')
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        source: str,
+        target: str,
+        goods: tuple[str, ...] = GOODS,
+        pairing: str = 'pairs',
+        quantity: float = 0.1,
+        phase: str = 'trade',
+    ) -> None:
+        super().__init__(
+            label,
+            source=source,
+            target=target,
+            state=goods[0],
+            amount=quantity,
+            pairing=pairing,
+            form='agent',
+            phase=phase,
+        )
+        self.goods = goods
+        self.quantity = quantity
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the barter of every pair of traders and the report of the trades of the step.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [*super()._get_laws(s), RuleLaw(self.report_trades, phase=self.phase)]
+
+    def transfer(self, source: AgentViewProtocol, target: AgentViewProtocol, model: ModelViewProtocol) -> bool:
+        """Barter between two traders while both gain, and keep the trades of the step for its report.
+
+        Args:
+            source:
+                The first trader.
+
+            target:
+                The second trader.
+
+            model:
+                The model view of the exchange.
+
+        Returns:
+            traded:
+                Whether the traders made a trade.
+        """
+        weights = [f'{good}_weight' for good in self.goods]
+        trades = trade_goods(source, target, self.goods, weights, quantity=self.quantity)
+        logs = model.storage.setdefault('trades', [])
+        if isinstance(logs, list):
+            logs.extend(trades)
+        return bool(trades)
+
+    def report_trades(self, model: ModelViewProtocol) -> None:
+        """Report the mean price of the second good in the first, its dispersion, and the trades of the step.
+
+        Args:
+            model:
+                The model view of the exchange.
+        """
+        trades = model.storage.pop('trades', [])
+        trades = trades if isinstance(trades, list) else []
+        logs = [math.log(price) for bought, paid, price in trades if (bought, paid) == (0, 1)]
+        model.report('price', math.exp(float(np.mean(logs))) if logs else math.nan)
+        model.report('dispersion', float(np.std(logs)) if len(logs) > 1 else math.nan)
+        model.report('volume', len(trades))

skcomplex/models/economics/markets/_factory.py

@@ -0,0 +1,105 @@
+"""Factory of a supply chain, an echelon whose orders a brewery brews over the production delay."""
+
+# 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 ....specs import ParameterSpec, StateSpec, VisualSpec
+from ._echelon import EchelonElement
+
+
+class FactoryElement(EchelonElement):
+    """Factory of a supply chain, an echelon whose orders a brewery brews over the production delay.
+
+    Args:
+        label:
+            The label of the factory.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        inventory:
+            The initial inventory, in cases.
+
+        in_transit:
+            The initial beer on its way to the echelon.
+
+        backlog:
+            The initial orders waiting to ship.
+
+        expected:
+            The initial expected demand.
+
+        supply_line:
+            The initial beer ordered and not received.
+
+        desired:
+            The desired stock `S'`.
+
+        theta:
+            The rate at which the expected demand adapts to incoming orders.
+
+        alpha:
+            The fraction of the stock gap ordered per week.
+
+        beta:
+            The weight of the supply line in the stock gap.
+
+        dispatch_time:
+            The time over which the echelon ships its backlog.
+
+        mail_delay:
+            The average time an order of the echelon takes to reach its supplier.
+
+        shipping_delay:
+            The average time a shipment takes to reach the echelon from its supplier.
+
+        production_delay:
+            The average time the brewery takes to brew an order, through a third-order delay.
+
+    Examples:
+        >>> from skcomplex.models.economics.markets import FactoryElement
+        >>> FactoryElement('factory').production_delay
+        3.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        inventory: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='beer')] = 12.0,
+        in_transit: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='beer')] = 8.0,
+        backlog: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 4.0,
+        expected: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 4.0,
+        supply_line: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 16.0,
+        desired: Annotated[float, ParameterSpec()] = 13.44,
+        theta: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.36,
+        alpha: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.26,
+        beta: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.34,
+        dispatch_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        mail_delay: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
+        shipping_delay: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
+        production_delay: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 3.0,
+    ) -> None:
+        super().__init__(
+            label,
+            visual=visual,
+            inventory=inventory,
+            in_transit=in_transit,
+            backlog=backlog,
+            expected=expected,
+            supply_line=supply_line,
+            desired=desired,
+            theta=theta,
+            alpha=alpha,
+            beta=beta,
+            dispatch_time=dispatch_time,
+            mail_delay=mail_delay,
+            shipping_delay=shipping_delay,
+        )
+        self.production_delay = production_delay

skcomplex/models/economics/markets/_fair_food.py

@@ -0,0 +1,205 @@
+"""Markets models: consumers choosing between fair-trade and regular food under ethics, budget, and social influence."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import math
+from typing import Annotated
+
+import numpy as np
+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, GroupElement
+from ....core.interactions import ChoiceInteraction
+from ....core.spaces import DiscreteTime, LatticeSpace
+from ....core.system import System
+from ....engine.solvers import ModelView
+from ....specs import ObservableSpec, ParameterSpec, StateSpec, VisualSpec
+from ..._catalog import register_model
+from ._consumer_view import ConsumerView
+
+
+def _get_utility(agent: ConsumerView, model: ModelView, option: float) -> float:
+    """Return the utility of fair food, option 1, or regular food, option 0, `-inf` for fair food over the budget."""
+    if option == 0:
+        return 0.0
+    if agent.budget < 1 + agent.premium:
+        return -math.inf
+    neighbors = [neighbor for neighbor in agent.neighbors() if isinstance(neighbor, ConsumerView)]
+    share = sum(neighbor.fair for neighbor in neighbors) / len(neighbors) if neighbors else 0.0
+    return float(
+        agent.ethics_weight * agent.ethics
+        - agent.price_weight * agent.premium / agent.budget
+        + agent.social_weight * share,
+    )
+
+
+class ConsumerElement(Element):
+    """Consumer who buys fair-trade or regular food, with an ethical concern, a budget, and the weights of its utility.
+
+    The utility of fair food is `ethics_weight * ethics - price_weight * premium / budget + social_weight * share`,
+    where `share` is the share of neighbours who bought fair food in the last step, and the utility of regular food is
+    zero. A consumer whose budget does not cover the price `1 + premium` of fair food buys regular food.
+
+    Args:
+        label:
+            The label of the agent or group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        fair:
+            One when the consumer bought fair food in the last step, zero otherwise.
+
+        ethics:
+            The ethical concern of the consumer, between zero and one.
+
+        budget:
+            The money the consumer can spend on one unit of food, regular food costing one.
+
+        premium:
+            The extra price of fair food over regular food.
+
+        ethics_weight:
+            The weight of ethical concern in the utility of fair food.
+
+        price_weight:
+            The weight of the premium relative to the budget.
+
+        social_weight:
+            The weight of the share of neighbours who buy fair food.
+
+    Examples:
+        >>> from skcomplex.models.economics.markets import ConsumerElement
+        >>> GroupElement('consumers', element=ConsumerElement, size=4, values={'ethics': 0.5}).size
+        4
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = VisualSpec('agents', {'color_by': 'fair', 'color_range': (0.0, 1.0)}),
+        *,
+        fair: Annotated[float, StateSpec(domain=FiniteEnumeratedSet([0, 1]))] = 0.0,
+        ethics: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
+        budget: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
+        premium: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
+        ethics_weight: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
+        price_weight: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 5.0,
+        social_weight: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.fair = fair
+        self.ethics = ethics
+        self.budget = budget
+        self.premium = premium
+        self.ethics_weight = ethics_weight
+        self.price_weight = price_weight
+        self.social_weight = social_weight
+
+    @classmethod
+    def _get_view(cls) -> type[ConsumerView]:
+        """Return the view of a consumer, with its states and the parameters of its utility."""
+        return ConsumerView
+
+
+@register_model(
+    field='economics/markets',
+    tags=('consumer choice', 'social influence', 'agents', 'grid'),
+    references=('Chesney 2021 ch. 3', 'Chesney 2021 ch. 7'),
+    defaults={'until': 50},
+    observables=lambda system: [ObservableSpec('fair_share', group='consumers', variable='fair')],
+)
+def fair_food(
+    width: int = 20,
+    height: int = 20,
+    *,
+    premium: float = 0.3,
+    ethics_weight: float = 2.0,
+    price_weight: float = 5.0,
+    social_weight: float = 2.0,
+    intensity: float = 1.0,
+    low_budget: float = 1.0,
+    high_budget: float = 3.0,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return Chesney's choice between fair-trade and regular food of consumers who influence their neighbours.
+
+    Every consumer, of uniform ethical concern and budget, sits on a cell of a grid and every step buys fair or
+    regular food, all at once from the choices of their neighbours in the last step, as in the choice of Ajani. The
+    share of fair food rises with the weight of ethics and falls with the premium, and social influence raises it.
+
+    Args:
+        width:
+            The number of columns of the grid.
+
+        height:
+            The number of rows of the grid.
+
+        premium:
+            The extra price of fair food over regular food, which costs one.
+
+        ethics_weight:
+            The weight of ethical concern in the utility of fair food.
+
+        price_weight:
+            The weight of the premium relative to the budget.
+
+        social_weight:
+            The weight of the share of neighbours who buy fair food.
+
+        intensity:
+            The intensity of the logit choice.
+
+        low_budget:
+            The lowest budget.
+
+        high_budget:
+            The highest budget.
+
+        random_state:
+            The seed or generator of the ethics and the budgets.
+
+    Returns:
+        system:
+            The model, with the group `consumers`, their logit choice `shopping`, and the share of fair food
+            `fair_share`.
+
+    Examples:
+        >>> from skcomplex.models.economics.markets import fair_food
+        >>> fair_food(5, 4).elements[0].check().prepare().size_
+        20
+    """
+    rng = np.random.default_rng(random_state)
+    size = width * height
+    consumers = GroupElement(
+        'consumers',
+        element=ConsumerElement,
+        size=size,
+        values={
+            'ethics': rng.random(size),
+            'budget': rng.uniform(low_budget, high_budget, size),
+            'premium': premium,
+            'ethics_weight': ethics_weight,
+            'price_weight': price_weight,
+            'social_weight': social_weight,
+        },
+        location=[(x, y) for x in range(width) for y in range(height)],
+    )
+    choice = ChoiceInteraction(
+        'shopping',
+        target='consumers',
+        state='fair',
+        options=(0, 1),
+        utility=_get_utility,
+        intensity=intensity,
+        form='agent',
+    )
+    return System(
+        elements=[consumers],
+        interactions=[choice],
+        space=LatticeSpace((width, height), boundary='periodic', capacity=1),
+        time=DiscreteTime(),
+    )

skcomplex/models/economics/markets/_forager.py

@@ -0,0 +1,64 @@
+"""Agent that moves to the richest free cell in sight, harvests its sugar, burns its metabolism, and may starve."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import NN, oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....specs import StateSpec, VisualSpec
+from ._forager_view import ForagerView
+
+
+class ForagerElement(Element):
+    """Agent that moves to the richest free cell in sight, harvests its sugar, burns its metabolism, and may starve.
+
+    In its own activation, a forager sees `vision` cells along each of the four lattice directions and moves to the
+    free cell with the most sugar, the nearest among equals, or stays when no cell in sight beats its own, by a
+    `MovementInteraction` of the best step with a vision. Transfers then harvest the sugar of its cell and burn its
+    metabolism, and a `LifeCycleInteraction` removes it when its wealth falls below zero.
+
+    Args:
+        label:
+            The label of the agent or group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        sugar:
+            The wealth of the forager.
+
+        vision:
+            The number of cells the forager sees in every direction.
+
+        metabolism:
+            The sugar the forager burns in a step.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.economics.markets import ForagerElement
+        >>> GroupElement('foragers', element=ForagerElement, size=3, values={'vision': 2.0}).size
+        3
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = VisualSpec('agents', {'color_by': 'sugar'}),
+        *,
+        sugar: Annotated[float, StateSpec()] = 10.0,
+        vision: Annotated[float, StateSpec(domain=NN)] = 1.0,
+        metabolism: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.sugar = sugar
+        self.vision = vision
+        self.metabolism = metabolism
+
+    @classmethod
+    def _get_view(cls) -> type[ForagerView]:
+        """Return the view of a forager, with its sugar, vision, and metabolism."""
+        return ForagerView

skcomplex/models/economics/markets/_forager_view.py

@@ -0,0 +1,14 @@
+"""Define the view of a forager of the Sugarscape, as its rules and the census see it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class ForagerView(AgentView):
+    """Forager as the rules see it: its wealth `sugar`, its `vision`, and its `metabolism`."""
+
+    sugar: float
+    vision: float
+    metabolism: float