scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/economics/innovation/_technology.py

@@ -0,0 +1,203 @@
+"""Innovation models: technologies that improve by redesigning their components or combining logic circuits."""
+
+# 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 NN
+
+from ....core.elements import Element, GroupElement
+from ....core.laws import BaseLaw
+from ....core.system import System
+from ....specs import ObservableSpec, StateSpec, VisualSpec
+from ....types import Array
+from ..._catalog import register_model
+from ._invention import InventionInteraction
+from ._part import PartElement
+from ._redesign import RedesignInteraction
+from ._technology_view import TechnologyView
+
+NAND = (2, 0b0111)
+
+
+FALSE = (0, 0)
+
+
+TRUE = (0, 1)
+
+
+def _design_structure(n_components: int, d: int, rng: np.random.Generator) -> Array:
+    """Return a design structure matrix where a change of every component changes it and `d - 1` other components."""
+    matrix = np.eye(n_components)
+    for column in range(n_components):
+        others = rng.choice([row for row in range(n_components) if row != column], d - 1, replace=False)
+        matrix[others, column] = 1.0
+    return matrix
+
+
+class TechnologyElement(Element):
+    """Logic circuit in the pool of technologies, described by the truth table of the function it computes.
+
+    Bit `r` of the table is the output on the inputs whose bits form `r`, with the first input as the lowest bit.
+
+    Args:
+        label:
+            The label of the agent or group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        arity:
+            The number of inputs.
+
+        table:
+            The truth table.
+
+        cost:
+            The number of NAND gates in the circuit.
+
+    Examples:
+        >>> from skcomplex.models.economics.innovation import TechnologyElement
+        >>> GroupElement(
+        ...     'technologies', element=TechnologyElement, size=3, values={'arity': [2, 0, 0], 'table': [7, 0, 1]}
+        ... ).size
+        3
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        arity: Annotated[float, StateSpec(domain=NN)] = 2,
+        table: Annotated[float, StateSpec(domain=NN)] = NAND[1],
+        cost: Annotated[float, StateSpec(domain=NN)] = 1,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.arity = arity
+        self.table = table
+        self.cost = cost
+
+    @classmethod
+    def _get_view(cls) -> type[TechnologyView]:
+        """Return the view of the agents of the element."""
+        return TechnologyView
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return no laws, since inventions combine several technologies at once.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return []
+
+
+@register_model(
+    field='economics/innovation',
+    tags=('innovation', 'technology', 'learning curve', 'agents'),
+    references=('Thurner et al. 2018', 'McNerney et al. 2011'),
+    defaults={'until': 200},
+    observables=lambda system: [ObservableSpec('total_cost', group='components', reduce='sum', variable='cost')],
+)
+def nk_technology(
+    n_components: int = 10,
+    d: int = 2,
+    *,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return McNerney's model of technological improvement, whose cost falls as a power of the cumulative production.
+
+    Every step is one unit of production and one attempt to redesign a random component together with the components
+    that depend on it. Redesigns are kept only when they cut the total cost, which falls like Wright's law, more slowly
+    for designs whose components depend on more others.
+
+    Args:
+        n_components:
+            The number of components.
+
+        d:
+            The number of components that a redesign of one component changes, itself included.
+
+        random_state:
+            The seed or generator of the design structure matrix and the initial costs.
+
+    Returns:
+        system:
+            The model, with the group `components` and the total cost `total_cost`.
+
+    Examples:
+        >>> from skcomplex.models.economics.innovation import nk_technology
+        >>> nk_technology(5, 1).interactions[0].dependencies[0]
+        [1.0, 0.0, 0.0, 0.0, 0.0]
+    """
+    rng = np.random.default_rng(random_state)
+    dependencies = _design_structure(n_components, d, rng)
+    components = GroupElement(
+        'components',
+        element=PartElement,
+        size=n_components,
+        values={'cost': rng.random(n_components)},
+    )
+    return System(
+        elements=[components],
+        interactions=[RedesignInteraction('redesign', components='components', dependencies=dependencies.tolist())],
+    )
+
+
+@register_model(
+    field='economics/innovation',
+    tags=('innovation', 'technology', 'combinatorial evolution', 'agents'),
+    references=('Thurner et al. 2018', 'Arthur and Polak 2006'),
+    defaults={'until': 200},
+)
+def arthur_polak(*, max_components: int = 12, max_inputs: int = 3) -> System:
+    """Return Arthur and Polak's evolution of technology, which builds logic functions from NAND gates.
+
+    The pool starts with the NAND gate and the constants 0 and 1. Every step wires a random circuit from the pool and
+    keeps it when it computes a wanted function, negation, two-input and, or, exclusive or, nor, equivalence, and
+    implication, or three-input and, or, parity, and majority, so simple inventions become the building blocks of
+    complex ones.
+
+    Args:
+        max_components:
+            The largest number of technologies in a circuit.
+
+        max_inputs:
+            The largest number of inputs of a circuit.
+
+    Returns:
+        system:
+            The model, with the pool `technologies`, whose size is the reporter `technologies.count`.
+
+    Examples:
+        >>> from skcomplex.models.economics.innovation import arthur_polak
+        >>> arthur_polak().elements[0].check().prepare().size_
+        3
+    """
+    primitives = (NAND, FALSE, TRUE)
+    technologies = GroupElement(
+        'technologies',
+        element=TechnologyElement,
+        size=len(primitives),
+        values={
+            'arity': [float(arity) for arity, _ in primitives],
+            'table': [float(table) for _, table in primitives],
+            'cost': [1.0, 0.0, 0.0],
+        },
+        variable=True,
+    )
+    invention = InventionInteraction(
+        'invention',
+        technologies='technologies',
+        max_components=float(max_components),
+        max_inputs=float(max_inputs),
+    )
+    return System(elements=[technologies], interactions=[invention])

skcomplex/models/economics/innovation/_technology_view.py

@@ -0,0 +1,14 @@
+"""Define the view of a technology of the pool, as the invention sees it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class TechnologyView(AgentView):
+    """Technology as the invention sees it: its `arity`, its truth `table`, and its `cost` in NAND gates."""
+
+    arity: float
+    table: float
+    cost: float

skcomplex/models/economics/macroeconomics/__init__.py

@@ -0,0 +1,70 @@
+"""Macroeconomics: growth, business cycles, investment, international trade, and mortal monetary economies."""
+
+from ._banking import fractional_reserve_banking
+from ._business import BusinessElement
+from ._capital import CapitalStockElement, capital_stock
+from ._central_bank import CentralBankElement
+from ._circuit import CircuitInteraction
+from ._commons import CommonsInteraction
+from ._credit import credit_networks
+from ._credit_market import CreditMarketInteraction
+from ._depositor import DepositorElement
+from ._economy import EconomyElement
+from ._estate import EstateInteraction
+from ._firm import FirmElement
+from ._firms import InvestingFirmElement, toy_firm_investment
+from ._firms_element import FirmsElement
+from ._food_market import FoodMarketInteraction
+from ._growth import multiplier_accelerator, solow
+from ._households import HouseholdsElement
+from ._income import IncomeElement
+from ._labour_market import LabourMarketInteraction
+from ._lender import LenderElement
+from ._metaphoria import metaphoria
+from ._monetary import stock_flow_consistent_economy
+from ._monetary_bank import MonetaryBankElement
+from ._optimal_growth import RamseyEconomyElement, optimal_consumption
+from ._plot import PlotElement
+from ._policy_switch import PolicySwitchInteraction
+from ._reserve_bank import ReserveBankElement
+from ._settler import SettlerElement
+from ._solow_growth import SolowGrowthInteraction
+from ._trade import TradingEconomyElement, exchange_rates
+
+__all__: list[str] = [
+    'BusinessElement',
+    'CapitalStockElement',
+    'CentralBankElement',
+    'CircuitInteraction',
+    'CommonsInteraction',
+    'CreditMarketInteraction',
+    'DepositorElement',
+    'EconomyElement',
+    'EstateInteraction',
+    'FirmElement',
+    'FirmsElement',
+    'FoodMarketInteraction',
+    'HouseholdsElement',
+    'IncomeElement',
+    'InvestingFirmElement',
+    'LabourMarketInteraction',
+    'LenderElement',
+    'MonetaryBankElement',
+    'PlotElement',
+    'PolicySwitchInteraction',
+    'RamseyEconomyElement',
+    'ReserveBankElement',
+    'SettlerElement',
+    'SolowGrowthInteraction',
+    'TradingEconomyElement',
+    'capital_stock',
+    'credit_networks',
+    'exchange_rates',
+    'fractional_reserve_banking',
+    'metaphoria',
+    'multiplier_accelerator',
+    'optimal_consumption',
+    'solow',
+    'stock_flow_consistent_economy',
+    'toy_firm_investment',
+]

skcomplex/models/economics/macroeconomics/_banking.py

@@ -0,0 +1,148 @@
+"""Macroeconomics models: fractional-reserve banking, where loans redeposited at banks multiply the base money."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+
+from ....core.elements import GroupElement
+from ....core.interactions import TransferInteraction
+from ....core.laws import Sink
+from ....core.spaces import DiscreteTime
+from ....core.system import System
+from ....specs import ObservableSpec, PhaseSpec, PhasesScheduleSpec
+from ..._catalog import register_model
+from ._depositor import DepositorElement
+from ._policy_switch import PolicySwitchInteraction
+from ._reserve_bank import ReserveBankElement
+
+
+@register_model(
+    field='economics/macroeconomics',
+    tags=('money', 'banks', 'agents', 'institution'),
+    references=('Hamill and Gilbert 2016 ch. 9',),
+    defaults={'until': 300},
+    observables=lambda system: [
+        ObservableSpec('broad_money', group='banks', variable='deposits', reduce='sum'),
+        ObservableSpec('reserves', group='banks', variable='reserves', reduce='sum'),
+        ObservableSpec('loans', group='banks', variable='loans', reduce='sum'),
+    ],
+)
+def fractional_reserve_banking(
+    customers: int = 100,
+    banks: int = 5,
+    *,
+    base_money: float = 1000.0,
+    ratio: float = 0.1,
+    new_ratio: float | None = None,
+    change_at: float = 150.0,
+    spending: float = 0.1,
+    repayment: float = 0.05,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return customers and banks whose lending of excess reserves multiplies the base money by `1 / ratio`.
+
+    The base money starts as equal deposits of the customers, held as reserves by their banks, picked at random. Every
+    step the customers pay a share of their deposits to random customers and repay a share of their loans from their
+    deposits, and every bank lends its reserves above the
+    required share of its deposits; the loans are spent and redeposited at random banks. The reserves stay equal to the
+    base money, so the broad money, the sum of deposits, settles near `base_money / ratio`. A regulator changes the
+    reserve ratio to `new_ratio` at `change_at`, and the broad money moves to the new multiplier.
+
+    Args:
+        customers:
+            The number of customers.
+
+        banks:
+            The number of banks.
+
+        base_money:
+            The base money, deposited by the customers in equal shares.
+
+        ratio:
+            The reserve ratio.
+
+        new_ratio:
+            The reserve ratio from `change_at` on, or `None` to keep `ratio`.
+
+        change_at:
+            The time the reserve ratio changes.
+
+        spending:
+            The share of its deposit a customer pays to a random customer every step.
+
+        repayment:
+            The share of its loan a customer repays every step.
+
+        random_state:
+            The seed or generator of the customers' banks.
+
+    Returns:
+        system:
+            The model, with the groups `customers` and `banks`, the institution `regulator`, and the observables
+            `broad_money`, `reserves`, and `loans`.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import fractional_reserve_banking
+        >>> fractional_reserve_banking(new_ratio=0.2).interactions[0].new_ratio
+        0.2
+    """
+    rng = np.random.default_rng(random_state)
+    owners = rng.integers(banks, size=customers)
+    deposit = base_money / customers
+    holdings = np.bincount(owners, minlength=banks) * deposit
+    depositors = GroupElement(
+        'customers',
+        element=DepositorElement,
+        size=customers,
+        values={'bank': owners, 'deposit': deposit, 'spending': spending, 'repayment': repayment},
+    )
+    payments = TransferInteraction(
+        'payments',
+        source='customers',
+        target='customers',
+        state='deposit',
+        amount=DepositorElement.get_payment,
+        pairing='random',
+        legs=(
+            ('bank.deposits', None, DepositorElement.get_payment),
+            ('bank.reserves', None, DepositorElement.get_payment),
+        ),
+        form='agent',
+        phase='pay',
+    )
+    repayments = TransferInteraction(
+        'repayments',
+        source='customers',
+        target='customers',
+        state='deposit',
+        into=Sink(),
+        amount=DepositorElement.get_repayment,
+        legs=tuple(
+            (state, Sink(), DepositorElement.get_repayment) for state in ('loan', 'bank.deposits', 'bank.loans')
+        ),
+        guard=lambda customer, same, model: DepositorElement.get_repayment(customer, same, model) > 0,
+        form='agent',
+        phase='pay',
+    )
+    lenders = GroupElement(
+        'banks',
+        element=ReserveBankElement,
+        size=banks,
+        values={'reserves': holdings, 'deposits': holdings, 'reserve_ratio': ratio},
+    )
+    regulator = PolicySwitchInteraction(
+        'regulator',
+        phase='regulate',
+        ratio=ratio,
+        new_ratio=ratio if new_ratio is None else new_ratio,
+        change_at=change_at,
+    )
+    return System(
+        elements=[depositors, lenders],
+        interactions=[regulator, payments, repayments],
+        time=DiscreteTime(
+            schedule=PhasesScheduleSpec([PhaseSpec('regulate'), PhaseSpec('pay'), PhaseSpec('lend', repeat=10)]),
+        ),
+    )

skcomplex/models/economics/macroeconomics/_business.py

@@ -0,0 +1,221 @@
+"""Firm on a patch that harvests with its workers, pays wages with money it borrows, and sells food in its shop."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import math
+from types import SimpleNamespace
+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 ....core.laws import BaseLaw, RuleLaw
+from ....core.laws.utils import transfer
+from ....engine.solvers import ModelView
+from ....specs import (
+    ParameterSpec,
+    StateSpec,
+    VisualSpec,
+)
+from ._business_view import BusinessView
+from ._central_bank_view import CentralBankView
+from ._people_spec import _PeopleSpec
+from ._plot_view import PlotView
+from ._settler import SettlerElement
+from ._settler_view import SettlerView
+
+
+class BusinessElement(Element):
+    """Firm on a patch that harvests with its workers, pays wages with money it borrows, and sells food in its shop.
+
+    Every step the workers pool their labour on the firm's patch, the firm pays each the wage, borrowing what it
+    lacks from the bank, and pays the interest and a share of the principal of its loans. A firm that sold out
+    raises its price, and one with a stock above `stock_limit` lowers it and lays a worker off. Otherwise a firm
+    posts vacancies up to the workforce that harvests the whole capacity of its patch, raises the wage while a
+    vacancy went unfilled, and lowers it while its sales fall short of its wage bill. Profits above twice the wage
+    bill go to the owner, and a firm without a living owner passes to one of its workers.
+
+    Args:
+        label:
+            The label of the firm or the group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        money:
+            The money the firm holds.
+
+        loans:
+            The loans of the firm, negative for its debt.
+
+        stock:
+            The food in the shop.
+
+        wage:
+            The wage of a worker.
+
+        price:
+            The price of a unit of food.
+
+        owner:
+            The id of the owner.
+
+        workers:
+            The number of workers in the step.
+
+        vacancies:
+            The open vacancies.
+
+        revenue:
+            The sales of the step.
+
+        interest:
+            The interest rate of loans per step.
+
+        repayment:
+            The share of the principal repaid per step.
+
+        adjustment:
+            The relative step of a change of price or wage.
+
+        stock_limit:
+            The stock above which the firm lowers its price and lays off.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.economics.macroeconomics import BusinessElement
+        >>> GroupElement('businesses', element=BusinessElement, size=2, variable=True).size
+        2
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        money: Annotated[float, StateSpec(quantity='money')] = 0.0,
+        loans: Annotated[float, StateSpec(quantity='credit')] = 0.0,
+        stock: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        wage: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 4.0,
+        price: Annotated[float, StateSpec(domain=RealSet.open(0, oo))] = 1.0,
+        owner: Annotated[float, StateSpec(reference='people')] = -1.0,
+        workers: Annotated[float, StateSpec(domain=NN)] = 1.0,
+        vacancies: Annotated[float, StateSpec(domain=NN)] = 1.0,
+        revenue: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
+        interest: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.003,
+        repayment: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.004,
+        adjustment: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
+        stock_limit: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 30.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.money = money
+        self.loans = loans
+        self.stock = stock
+        self.wage = wage
+        self.price = price
+        self.owner = owner
+        self.workers = workers
+        self.vacancies = vacancies
+        self.revenue = revenue
+        self.interest = interest
+        self.repayment = repayment
+        self.adjustment = adjustment
+        self.stock_limit = stock_limit
+
+    @classmethod
+    def _get_view(cls) -> type[BusinessView]:
+        """Return the view of a firm, with its states and parameters."""
+        return BusinessView
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the rule of production in the phase of work.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [RuleLaw(self.produce, phase='work')]
+
+    def _borrow(self, agent: BusinessView, bank: CentralBankView, amount: float) -> None:
+        """Borrow an amount the bank creates as money and records as a loan."""
+        if amount > 0:
+            transfer(bank, agent, amount, 'money')
+            transfer(agent, bank, amount, 'loans')
+
+    def _service(self, agent: BusinessView, bank: CentralBankView) -> None:
+        """Pay the interest and the repayment of the debt, borrowing anew what the firm lacks."""
+        debt = -agent.loans
+        interest, principal = agent.interest * debt, agent.repayment * debt
+        self._borrow(agent, bank, interest + principal - agent.money)
+        transfer(agent, bank, interest + principal, 'money')
+        transfer(bank, agent, principal, 'loans')
+
+    def _adjust(self, agent: BusinessView, workers: list[SettlerView], patch: PlotView, sold_out: bool) -> None:
+        """Adjust the price, the wage, and the workforce to the stock, the labour, and the sales."""
+        step = agent.adjustment
+        if sold_out:
+            agent.price *= 1 + step
+        if agent.stock > agent.stock_limit:
+            agent.price *= 1 - step
+            agent.vacancies = 0.0
+            if len(workers) > 1:
+                workers[-1].employer = -1.0
+            return
+        if agent.vacancies > 0:
+            agent.wage *= 1 + step
+        if agent.revenue < agent.wage * len(workers):
+            agent.wage *= 1 - step
+        wanted = math.ceil((patch.capacity + patch.resistance) / workers[0].labour) if workers else 1
+        agent.vacancies = float(max(wanted - len(workers), 0))
+
+    def produce(self, agent: BusinessView, model: ModelView) -> None:
+        """Harvest with the workers, pay wages and the bank, adjust, and pay a dividend to the owner.
+
+        Args:
+            agent:
+                The firm.
+
+            model:
+                The model.
+        """
+        people = BusinessElement._people_by_id(model)
+        workers = [person for person in people.values() if person.employer == agent.id]
+        bank = model.agents('bank', CentralBankView)[0]
+        patch = SettlerElement._patch_here(agent)
+        sold_out = agent.stock <= 0
+        for worker in workers:
+            worker.move_to(agent.location)
+        labour = sum(worker.labour for worker in workers)
+        harvest = min(patch.food, max(labour - patch.resistance, 0.0))
+        patch.food -= harvest
+        agent.stock += harvest
+        bill = agent.wage * len(workers)
+        self._borrow(agent, bank, bill - agent.money)
+        for worker in workers:
+            transfer(agent, worker, agent.wage, 'money')
+            worker.harvested = worker.need
+        self._service(agent, bank)
+        self._adjust(agent, workers, patch, sold_out)
+        agent.workers, agent.revenue = float(len(workers)), 0.0
+        owner = agent.referenced('owner')
+        if not isinstance(owner, SettlerView) and workers:
+            owner = workers[0]
+            agent.owner = float(owner.id)
+        if isinstance(owner, SettlerView) and agent.money > 2 * bill:
+            transfer(agent, owner, agent.money - 2 * bill, 'money')
+
+    @staticmethod
+    def _people_by_id(model: ModelView) -> dict[int, SettlerView]:
+        """Return the living people by id, built once per step in the storage of the caller."""
+        cached = model.storage.get('people')
+        if not isinstance(cached, _PeopleSpec) or cached.time != model.time:
+            people = {person.id: person for person in model.agents('people', SettlerView) if person.alive}
+            cached = _PeopleSpec(model.time, people)
+            model.storage['people'] = cached
+        return dict(cached.people)

skcomplex/models/economics/macroeconomics/_business_view.py

@@ -0,0 +1,24 @@
+"""Define the view of a firm of Metaphoria, as the rules see it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class BusinessView(AgentView):
+    """Firm as the rules see it: its holdings, stock, wage, price, owner, workforce, sales, and policy parameters."""
+
+    money: float
+    loans: float
+    stock: float
+    wage: float
+    price: float
+    owner: float
+    workers: float
+    vacancies: float
+    revenue: float
+    interest: float
+    repayment: float
+    adjustment: float
+    stock_limit: float