scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/economics/macroeconomics/_capital.py

@@ -0,0 +1,122 @@
+"""Macroeconomics models: physical capital that reinvests its output and depreciates."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import Expression, oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....core.interactions import RateInteraction
+from ....core.system import System
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+from ..._catalog import register_model
+
+
+class CapitalStockElement(Element):
+    """Capital stock that reinvests a fraction of its output and depreciates over its lifetime.
+
+    Args:
+        label:
+            The label of the stock.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        K:
+            The capital stock.
+
+        investment_fraction:
+            The fraction of the output that is reinvested.
+
+        output_per_capital:
+            The output per unit of capital and unit time.
+
+        lifetime:
+            The average lifetime of the capital.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import CapitalStockElement
+        >>> CapitalStockElement('economy', lifetime=20.0).lifetime
+        20.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        K: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 100.0,
+        investment_fraction: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.2,
+        output_per_capital: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1 / 3,
+        lifetime: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 15.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.K = K
+        self.investment_fraction = investment_fraction
+        self.output_per_capital = output_per_capital
+        self.lifetime = lifetime
+
+
+def _net_investment(s: SimpleNamespace) -> Expression:
+    """Return the reinvested output minus the depreciation of the capital stock."""
+    stock = s.target
+    rate: Expression = stock.investment_fraction * stock.output_per_capital * stock.K - stock.K / stock.lifetime
+    return rate
+
+
+@register_model(
+    field='economics/macroeconomics',
+    tags=('growth', 'system dynamics', 'ode'),
+    references=('Meadows 2008',),
+    defaults={'until': 50.0, 'dt': 1.0},
+)
+def capital_stock(
+    capital: float = 100.0,
+    *,
+    investment_fraction: float = 0.2,
+    output_per_capital: float = 1 / 3,
+    lifetime: float = 15.0,
+) -> System:
+    """Return Meadows' capital stock, grown by reinvested output and drained by depreciation.
+
+    The stock follows `dK/dt = investment_fraction * output_per_capital * K - K / lifetime`. It grows exponentially when
+    the capital lives longer than `1 / (investment_fraction * output_per_capital)`, declines when it lives shorter, and
+    stays in dynamic equilibrium otherwise.
+
+    Args:
+        capital:
+            The initial capital stock.
+
+        investment_fraction:
+            The fraction of the output that is reinvested.
+
+        output_per_capital:
+            The annual output per unit of capital.
+
+        lifetime:
+            The average lifetime of the capital.
+
+    Returns:
+        system:
+            The model, with the capital stock `economy.K`.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import capital_stock
+        >>> capital_stock(lifetime=20.0).elements[0].lifetime
+        20.0
+    """
+    economy = CapitalStockElement(
+        'economy',
+        K=capital,
+        investment_fraction=investment_fraction,
+        output_per_capital=output_per_capital,
+        lifetime=lifetime,
+    )
+    return System(
+        elements=[economy],
+        interactions=[RateInteraction('investment', target='economy', state='K', rate=_net_investment)],
+    )

skcomplex/models/economics/macroeconomics/_central_bank.py

@@ -0,0 +1,80 @@
+"""Bank that creates money as loans and pays its interest income to a random person as a dividend."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....engine.solvers import AgentView, ModelView
+from ....specs import (
+    StateSpec,
+    VisualSpec,
+)
+from ._central_bank_view import CentralBankView
+
+
+class CentralBankElement(Element):
+    """Bank that creates money as loans and pays its interest income to a random person as a dividend.
+
+    The transfer `dividends` of the model pays the income to a random person, or to a random firm when nobody lives.
+
+    The money it issued, a negative holding, and the loans it holds sum to zero after every step, so every unit of
+    money in the economy is matched by a loan.
+
+    Args:
+        label:
+            The label of the bank or the group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        money:
+            The money of the bank, the negative of the money it issued plus its income of the step.
+
+        loans:
+            The loans the bank holds.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.economics.macroeconomics import CentralBankElement
+        >>> GroupElement('bank', element=CentralBankElement, size=1).size
+        1
+    """
+
+    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,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.money = money
+        self.loans = loans
+
+    @classmethod
+    def _get_view(cls) -> type[CentralBankView]:
+        """Return the view of the bank, with its money and loans."""
+        return CentralBankView
+
+    @staticmethod
+    def get_income(agent: CentralBankView, holder: AgentView, model: ModelView) -> float:
+        """Return the income of the step that the bank pays as a dividend, its money plus its loans.
+
+        Args:
+            agent:
+                The bank.
+
+            holder:
+                The person, or the firm when nobody lives, that receives the dividend.
+
+            model:
+                The model view of the dividends.
+
+        Returns:
+            income:
+                The income.
+        """
+        return agent.money + agent.loans

skcomplex/models/economics/macroeconomics/_central_bank_view.py

@@ -0,0 +1,13 @@
+"""Define the view of the bank of Metaphoria, as its rule sees it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class CentralBankView(AgentView):
+    """Bank as its rule sees it: its `money` and its `loans`."""
+
+    money: float
+    loans: float

skcomplex/models/economics/macroeconomics/_circuit.py

@@ -0,0 +1,93 @@
+"""Circuit of money between households, firms, and a bank, one period per step."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import Expression
+
+from ....core.interactions import TransferInteraction
+from ....core.laws import Sink, Source
+from ....specs import RoleSpec
+
+
+class CircuitInteraction(TransferInteraction):
+    """Circuit of money between households, firms, and a bank, one period per step.
+
+    The flows of a period are the legs of one transfer between the deposits of the sectors, consumption, wages,
+    interest, dividends, and profits, lending from the environment, and repayments to it, each reading the parameters
+    of the sectors. Every leg is named by its flow, so the reporters `<label>.<flow>` record it.
+
+    Args:
+        label:
+            The label of the circuit.
+
+        households:
+            The path of the households.
+
+        firms:
+            The path of the firms.
+
+        bank:
+            The path of the bank.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import CircuitInteraction
+        >>> CircuitInteraction('circuit', households='households', firms='firms', bank='bank').bank
+        'bank'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        households: Annotated[str, RoleSpec()],
+        firms: Annotated[str, RoleSpec()],
+        bank: Annotated[str, RoleSpec()],
+    ) -> None:
+        super().__init__(
+            label,
+            source=households,
+            target=firms,
+            state='households.deposits',
+            into='firms.deposits',
+            amount=lambda s: CircuitInteraction._consumption(s.households, s.firms),
+            flow='consumption',
+            legs=[
+                ('firms.deposits', 'households.deposits', lambda s: s.firms.wage_share * s.firms.sales, 'wages'),
+                ('firms.deposits', 'bank.deposits', lambda s: s.bank.interest * s.firms.loans, 'interest'),
+                ('bank.deposits', 'households.deposits', lambda s: s.bank.payout * s.bank.deposits, 'dividends'),
+                (
+                    'firms.deposits',
+                    'households.deposits',
+                    lambda s: s.firms.distribution * s.firms.deposits,
+                    'profits',
+                ),
+                (
+                    Source('lending'),
+                    'firms.deposits',
+                    lambda s: CircuitInteraction._lending(s.firms, s.bank),
+                    'lending',
+                ),
+                ('firms.deposits', Sink('repayment'), lambda s: s.firms.repayment * s.firms.loans, 'repayments'),
+            ],
+        )
+        self.households = households
+        self.firms = firms
+        self.bank = bank
+
+    def _get_holders(self, namespace: SimpleNamespace) -> list[tuple[SimpleNamespace, SimpleNamespace]]:
+        """Return the households and the firms, the first pair of the circuit, whose other legs name their roles."""
+        return [(namespace.households, namespace.firms)]
+
+    @staticmethod
+    def _consumption(households: SimpleNamespace, firms: SimpleNamespace) -> Expression:
+        """Return the consumption of a period, a share of the wages and a share of the deposits of the households."""
+        return households.alpha_income * firms.wage_share * firms.sales + households.alpha_wealth * households.deposits
+
+    @staticmethod
+    def _lending(firms: SimpleNamespace, bank: SimpleNamespace) -> Expression:
+        """Return the new loans of a period, in proportion to the sales of the firms."""
+        return bank.credit * firms.sales

skcomplex/models/economics/macroeconomics/_commons.py

@@ -0,0 +1,77 @@
+"""Harvest of the hunter-gatherers, who pool the labour of the adults on a patch and share the food equally."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.interactions import Interaction
+from ....core.laws import BaseLaw, RuleLaw
+from ....engine.solvers import ModelView
+from ....specs import (
+    RoleSpec,
+)
+from ._settler import SettlerElement
+from ._settler_view import SettlerView
+
+
+class CommonsInteraction(Interaction):
+    """Harvest of the hunter-gatherers, who pool the labour of the adults on a patch and share the food equally.
+
+    The adults of a patch harvest `min(food, labour - resistance)`, and everyone on the patch, child or adult, gets an
+    equal share.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        people:
+            The path of the group of people.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import CommonsInteraction
+        >>> CommonsInteraction('commons', people='people').people
+        'people'
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        people: Annotated[str, RoleSpec()],
+    ) -> None:
+        super().__init__(label)
+        self.people = people
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the harvest rule 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.harvest, phase='work')]
+
+    def harvest(self, model: ModelView) -> None:
+        """Harvest every occupied patch and share the food among the people on it.
+
+        Args:
+            model:
+                The model view of the interaction.
+        """
+        cells: dict[tuple[int, ...], list[SettlerView]] = {}
+        for person in model.agents('people', SettlerView):
+            cells.setdefault(SettlerElement._cell(person), []).append(person)
+        for group in cells.values():
+            patch = SettlerElement._patch_here(group[0])
+            labour = sum(person.labour for person in group if person.age >= person.maturity)
+            harvest = min(patch.food, max(labour - patch.resistance, 0.0))
+            patch.food -= harvest
+            for person in group:
+                person.food += harvest / len(group)
+                person.harvested = harvest / len(group)

skcomplex/models/economics/macroeconomics/_credit.py

@@ -0,0 +1,219 @@
+"""Macroeconomics models: credit networks of firms that borrow from banks and switch to cheaper lenders."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+
+from ....core.elements import GroupElement
+from ....core.interactions import MapInteraction
+from ....core.spaces import DiscreteTime
+from ....core.system import System
+from ....engine.solvers import ModelView
+from ....specs import (
+    MatchSpec,
+    ObservableSpec,
+    PartnerSwitchSpec,
+    PhaseSpec,
+    PhasesScheduleSpec,
+)
+from ..._catalog import register_model
+from ._credit_market import CreditMarketInteraction
+from ._firm import FirmElement
+from ._firm_view import FirmView
+from ._lender import LenderElement
+from ._lender_view import LenderView
+
+
+def _lend(trade: MatchSpec, model: ModelView) -> None:
+    """Record a loan on the books of the firm and of the bank."""
+    del model
+    firm, bank = trade.requester, trade.provider
+    if not isinstance(firm, FirmView) or not isinstance(bank, LenderView):
+        error_msg = 'A loan is a trade of a firm with a bank.'
+        raise TypeError(error_msg)
+    firm.loan += trade.quantity
+    firm.rate = trade.value
+    bank.lent += trade.quantity
+
+
+def _herfindahl(values: object) -> float:
+    """Return the Herfindahl index of the banks' shares of the loans."""
+    lent = np.asarray(values, dtype=float)
+    total = lent.sum()
+    return float(np.sum((lent / total) ** 2)) if total > 0 else float('nan')
+
+
+def _largest_share(values: object) -> float:
+    """Return the share of the loans of the largest lender."""
+    lent = np.asarray(values, dtype=float)
+    total = lent.sum()
+    return float(lent.max() / total) if total > 0 else float('nan')
+
+
+def _credit_observables(system: System) -> list[ObservableSpec]:
+    """Return the concentration, equity, worth, returns, injections, defaults, and losses of the credit market."""
+    return [
+        ObservableSpec('herfindahl', group='banks', variable='lent', reduce=_herfindahl),
+        ObservableSpec('largest_share', group='banks', variable='lent', reduce=_largest_share),
+        ObservableSpec('bank_equity', group='banks', variable='equity', reduce='sum'),
+        ObservableSpec('firm_worth', group='firms', variable='net_worth', reduce='sum'),
+        ObservableSpec('returns', group='firms', variable='gross_return', reduce='sum'),
+        ObservableSpec('injected', group='firms', variable='injected', reduce='sum'),
+        ObservableSpec('defaults', group='firms', variable='defaulted', reduce='sum'),
+        ObservableSpec('bad_debt', group='banks', variable='losses', reduce='sum'),
+    ]
+
+
+@register_model(
+    field='economics/macroeconomics',
+    tags=('credit', 'banks', 'agents', 'market', 'network'),
+    references=('Caiani et al. 2016 ch. 2', 'Delli Gatti et al. 2010'),
+    defaults={'until': 100},
+    observables=_credit_observables,
+)
+def credit_networks(
+    firms: int = 100,
+    banks: int = 10,
+    *,
+    sample: int = 3,
+    intensity: float = 4.0,
+    leverage: float = 1.0,
+    mean_return: float = 0.03,
+    volatility: float = 0.3,
+    net_worth: float = 10.0,
+    equity: float = 100.0,
+    alpha: float = 0.1,
+    capital_ratio: float = 0.1,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return a credit market where firms sample banks and switch to cheaper lenders, and defaults hit the lenders.
+
+    Every step the banks quote rates that fall with their equity, every firm samples `sample` banks and switches from
+    its lender to the cheapest of them with probability `1 - exp(intensity * (r_new - r_old) / r_new)`, borrows, and
+    invests at a random return. Interest and write-offs of defaulted firms move net worth between firms and banks, so
+    the total net worth changes only by the firms' returns and the entrants' net worth. A higher intensity of switching
+    concentrates the loans in the cheapest banks and narrows the spread of the rates that firms pay.
+
+    Args:
+        firms:
+            The number of firms.
+
+        banks:
+            The number of banks.
+
+        sample:
+            The number of banks every firm samples.
+
+        intensity:
+            The intensity of switching to a cheaper bank.
+
+        leverage:
+            The ratio of the loan a firm wants to its net worth.
+
+        mean_return:
+            The mean return on capital.
+
+        volatility:
+            The standard deviation of the return on capital.
+
+        net_worth:
+            The initial net worth of every firm and of every entrant.
+
+        equity:
+            The mean initial equity of the banks, drawn uniformly within 50% of it.
+
+        alpha:
+            The elasticity of the interest rate to the equity.
+
+        capital_ratio:
+            The smallest ratio of a bank's equity to its loans.
+
+        random_state:
+            The seed or generator of the initial equities.
+
+    Returns:
+        system:
+            The model, with the groups `firms` and `banks`, the market `credit` with its reporter `credit.spread`, and
+            the observables `herfindahl`, `largest_share`, `bank_equity`, `firm_worth`, `returns`, `injected`,
+            `defaults`, and `bad_debt`.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import credit_networks
+        >>> [element.label for element in credit_networks().elements]
+        ['firms', 'banks']
+    """
+    rng = np.random.default_rng(random_state)
+    lenders = GroupElement(
+        'banks',
+        element=LenderElement,
+        size=banks,
+        values={'equity': equity * rng.uniform(0.5, 1.5, banks), 'alpha': alpha, 'capital_ratio': capital_ratio},
+    )
+    borrowers = GroupElement(
+        'firms',
+        element=FirmElement,
+        size=firms,
+        values={
+            'net_worth': net_worth,
+            'leverage': leverage,
+            'mean_return': mean_return,
+            'volatility': volatility,
+            'entry': net_worth,
+        },
+    )
+    market = CreditMarketInteraction(
+        'credit',
+        requesters='firms',
+        providers='banks',
+        rule=PartnerSwitchSpec(sample=sample, intensity=intensity),
+        limit=('bid', 'ask'),
+        quantity=('demand', 'supply'),
+        phase='credit',
+        on_match=_lend,
+    )
+    plan = [
+        MapInteraction(f'{group}_plan_{name}', target=group, state=name, function=function, form='agent', phase='plan')
+        for group, steps in (('firms', FirmElement.get_plan()), ('banks', LenderElement.get_quote()))
+        for name, function in steps
+    ]
+    settlement = [
+        MapInteraction(
+            'returns',
+            target='firms',
+            state='gross_return',
+            function=FirmElement.get_return,
+            form='agent',
+            phase='settle',
+        ),
+        *(
+            MapInteraction(
+                f'bank_{name}',
+                target='banks',
+                state=name,
+                function=function,
+                sources=('firms',),
+                mode='increment',
+                form='agent',
+                phase='settle',
+            )
+            for name, function in (('equity', LenderElement.get_income), ('losses', LenderElement.get_losses))
+        ),
+        *(
+            MapInteraction(
+                f'firms_settle_{name}',
+                target='firms',
+                state=name,
+                function=function,
+                form='agent',
+                phase='settle',
+            )
+            for name, function in FirmElement.get_default()
+        ),
+    ]
+    return System(
+        elements=[borrowers, lenders],
+        interactions=[*plan, market, *settlement],
+        time=DiscreteTime(schedule=PhasesScheduleSpec([PhaseSpec('plan'), PhaseSpec('credit'), PhaseSpec('settle')])),
+    )

skcomplex/models/economics/macroeconomics/_credit_market.py

@@ -0,0 +1,83 @@
+"""Credit market that also reports the spread of the rates firms pay over the cheapest bank's rate."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import ClassVar
+
+import numpy as np
+
+from ....core.interactions import MatchingInteraction
+from ....engine.solvers import ModelView
+from ....specs import (
+    MatchSpec,
+)
+from ._firm_view import FirmView
+from ._lender_view import LenderView
+
+
+class CreditMarketInteraction(MatchingInteraction[ModelView]):
+    """Credit market that also reports the spread of the rates firms pay over the cheapest bank's rate.
+
+    The firms request loans and the banks provide them. The spread is the mean of `r_i / r_min - 1` over the borrowing
+    firms, the dispersion of rates that a market with costly search leaves and that switching to cheaper lenders
+    erodes.
+
+    Args:
+        label:
+            The label of the market.
+
+        requesters:
+            The path of the group of firms.
+
+        providers:
+            The path of the group of banks.
+
+        rule:
+            The spec of the algorithm that matches firms with banks, such as `PartnerSwitchSpec()`.
+
+        limit:
+            The state with the rate of both sides, or a pair of the firms' and the banks' states.
+
+        quantity:
+            The state with the loan of both sides, or a pair of the firms' and the banks' states.
+
+        allowance:
+            The state of a firm with what it can spend.
+
+        transfers:
+            The states every loan moves, each with the sign `-1` for a payment of the firm or `1` for a delivery to
+            it.
+
+        phase:
+            The phase the market clears in, or `None` for the default phase.
+
+        on_match:
+            A function of every loan and the model view, run after the transfers, or `None`.
+
+    Examples:
+        >>> from skcomplex.models.economics.macroeconomics import CreditMarketInteraction
+        >>> CreditMarketInteraction('credit', requesters='firms', providers='banks').reports[-1]
+        'spread'
+    """
+
+    reports: ClassVar[tuple[str, ...]] = (*MatchingInteraction.reports, 'spread')
+
+    def _report_matches(self, matches: list[MatchSpec], unmatched: float, model: ModelView) -> None:
+        """Report the price, the volume, the unmatched quantity, and the spread of the rates over the cheapest rate.
+
+        Args:
+            matches:
+                The loans of the clearing.
+
+            unmatched:
+                The quantity of both sides left after the clearing.
+
+            model:
+                The model view of the market.
+        """
+        super()._report_matches(matches, unmatched, model)
+        cheapest = min((bank.ask for bank in model.agents('providers', LenderView) if bank.ask > 0), default=0.0)
+        paid = [firm.rate for firm in model.agents('requesters', FirmView) if firm.loan > 0]
+        spread = float(np.mean(paid) / cheapest - 1) if paid and cheapest > 0 else float('nan')
+        model.report('spread', spread)