scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/economics/finance/_book.py

@@ -0,0 +1,115 @@
+"""Limit order book that matches the orders of the traders and reports the last traded price."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable, Sequence
+from typing import Annotated, ClassVar
+
+from ....core.interactions import MatchingInteraction
+from ....core.types import MatchingRule
+from ....engine.solvers import ModelView
+from ....specs import (
+    MatchSpec,
+    RandomSearchSpec,
+    RoleSpec,
+)
+
+
+class BookInteraction(MatchingInteraction[ModelView]):
+    """Limit order book that matches the orders of the traders and reports the last traded price.
+
+    The book is a matching of the traders with themselves, which binds the requesters' limit to their `bid` and the
+    providers' to their `ask`, and every trade is two transfers, money from buyer to seller and shares from seller to
+    buyer, so the total money and the total shares stay the same, which the default run checks as invariants. The book
+    reports the last traded `price`, the previous price when nothing trades, and the traded `volume`.
+
+    Args:
+        label:
+            The label of the book.
+
+        requesters:
+            The path of the group of buying traders.
+
+        providers:
+            The path of the group of selling traders.
+
+        rule:
+            The spec of the algorithm that matches the orders, such as `ContinuousMatchingSpec()`.
+
+        limit:
+            The states with the limit prices of the buyers and of the sellers.
+
+        quantity:
+            The states with the quantities the buyers want and the sellers offer.
+
+        allowance:
+            The state of a buyer with the money it can spend.
+
+        transfers:
+            The states every trade moves, money paid by the buyer and shares delivered to it.
+
+        phase:
+            The phase the book clears in.
+
+        on_match:
+            A function of every trade and the model view, run after the transfers, or `None`.
+
+        opening:
+            The price before the first trade.
+
+    Examples:
+        >>> from skcomplex.models.economics.finance import BookInteraction
+        >>> BookInteraction('book', requesters='traders', providers='traders').reports
+        ('price', 'volume')
+    """
+
+    reports: ClassVar[tuple[str, ...]] = ('price', 'volume')
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        requesters: Annotated[str, RoleSpec()],
+        providers: Annotated[str, RoleSpec()],
+        rule: MatchingRule = RandomSearchSpec(),
+        limit: str | tuple[str, str] = ('bid', 'ask'),
+        quantity: str | tuple[str, str] = ('demand', 'supply'),
+        allowance: str = 'money',
+        transfers: Sequence[tuple[str, int]] = (('money', -1), ('shares', 1)),
+        phase: str | None = 'trade',
+        on_match: Callable[[MatchSpec, ModelView], None] | None = None,
+        opening: float = 100.0,
+    ) -> None:
+        super().__init__(
+            label,
+            requesters=requesters,
+            providers=providers,
+            rule=rule,
+            limit=limit,
+            quantity=quantity,
+            allowance=allowance,
+            transfers=transfers,
+            phase=phase,
+            on_match=on_match,
+        )
+        self.opening = opening
+
+    def _report_matches(self, matches: list[MatchSpec], unmatched: float, model: ModelView) -> None:
+        """Report the last traded price, the previous price when nothing trades, and the traded volume.
+
+        Args:
+            matches:
+                The trades of the clearing.
+
+            unmatched:
+                The quantity of both sides left after the clearing, which the book does not report.
+
+            model:
+                The model view of the book.
+        """
+        del unmatched
+        last = model.history('price', 1)
+        price = matches[-1].value if matches else (float(last[-1]) if len(last) else self.opening)
+        model.report('price', price)
+        model.report('volume', sum(match.quantity for match in matches))

skcomplex/models/economics/finance/_contagion.py

@@ -0,0 +1,116 @@
+"""Finance models: distress that spreads through a network of interbank loans."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+
+import numpy as np
+
+from ....core.elements import GroupElement
+from ....core.system import System
+from ....specs import ObservableSpec
+from ....types import Array
+from ..._catalog import register_model
+from ._debt_rank_cascade import DISTRESSED, DebtRankCascadeInteraction
+from ._interbank import UNDISTRESSED, InterbankElement
+from ._interbank_view import InterbankView
+
+
+def _random_exposures(n_banks: int, density: float, rng: np.random.Generator) -> tuple[Array, Array]:
+    """Return random interbank liabilities and capitals of a given density of links."""
+    links = rng.random((n_banks, n_banks)) < density
+    np.fill_diagonal(links, val=False)
+    liabilities = links * rng.uniform(1.0, 10.0, (n_banks, n_banks))
+    capital = rng.uniform(5.0, 20.0, n_banks)
+    return liabilities, capital
+
+
+def _impact(liabilities: Array, capital: Array) -> Array:
+    """Return the impact matrix `W_ij = min(1, M_ij / C_j)` of a default of `i` on `j`."""
+    return np.minimum(1.0, np.asarray(liabilities, dtype=float) / np.asarray(capital, dtype=float)[None, :])
+
+
+def _economic_values(liabilities: Array) -> Array:
+    """Return the economic value of every bank, its share of all interbank lending."""
+    lent = np.asarray(liabilities, dtype=float).sum(axis=0)
+    return lent / lent.sum()
+
+
+def _value_at_risk(agent: InterbankView) -> float:
+    """Return the distress of a bank weighted by its economic value."""
+    return float(agent.h * agent.value)
+
+
+@register_model(
+    field='economics/finance',
+    tags=('systemic risk', 'network', 'contagion', 'agents'),
+    references=('Thurner et al. 2018', 'Battiston et al. 2012'),
+    defaults={'until': 10},
+    observables=lambda system: [ObservableSpec('value_at_risk', _value_at_risk, group='banks', reduce='sum')],
+)
+def debtrank(
+    liabilities: Sequence[Sequence[float]] | None = None,
+    capital: Sequence[float] | None = None,
+    *,
+    distressed: Sequence[int] = (0,),
+    psi: float = 1.0,
+    n_banks: int = 10,
+    density: float = 0.3,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return the DebtRank cascade of distress from a set of banks through their interbank loans.
+
+    `liabilities[i][j]` is the loan from bank `j` to bank `i`, which `j` loses when `i` defaults, and the impact of `i`
+    on `j` is `min(1, liabilities[i][j] / capital[j])`. The banks in `distressed` start with distress `psi`. The
+    DebtRank is the final value at risk minus the initial one.
+
+    Args:
+        liabilities:
+            The interbank liabilities, or `None` for a random network of `n_banks` banks.
+
+        capital:
+            The capital of every bank, or `None` for random capitals.
+
+        distressed:
+            The indices of the banks distressed at the start.
+
+        psi:
+            The initial distress of those banks, where 1 is default.
+
+        n_banks:
+            The number of banks of a random network.
+
+        density:
+            The probability of a loan between two banks of a random network.
+
+        random_state:
+            The seed or generator of a random network.
+
+    Returns:
+        system:
+            The model, with the group `banks` and the distress weighted by economic value `value_at_risk`.
+
+    Examples:
+        >>> from skcomplex.models.economics.finance import debtrank
+        >>> debtrank([[0.0, 5.0], [0.0, 0.0]], [10.0, 10.0]).elements[0].check().prepare().size_
+        2
+    """
+    if liabilities is None or capital is None:
+        matrix, capitals = _random_exposures(n_banks, density, np.random.default_rng(random_state))
+    else:
+        matrix, capitals = np.asarray(liabilities, dtype=float), np.asarray(capital, dtype=float)
+    size = len(matrix)
+    h = np.zeros(size)
+    h[list(distressed)] = psi
+    status = np.where(h > 0, DISTRESSED, UNDISTRESSED).astype(float)
+    banks = GroupElement(
+        'banks',
+        element=InterbankElement,
+        size=size,
+        values={'h': h, 'status': status, 'value': _economic_values(matrix)},
+    )
+    return System(
+        elements=[banks],
+        interactions=[DebtRankCascadeInteraction('cascade', banks='banks', impact=_impact(matrix, capitals).tolist())],
+    )

skcomplex/models/economics/finance/_correlated_assets.py

@@ -0,0 +1,69 @@
+"""Finance models: asset prices driven by correlated Wiener processes."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....core.system import System
+from ....engine.solvers import EulerMaruyamaSolver
+from ....specs import WienerProcessSpec
+from ..._catalog import register_model
+from ._asset import AssetElement
+from ._geometric_brownian_motion import GeometricBrownianMotionInteraction
+
+
+@register_model(
+    field='economics/finance',
+    tags=('asset', 'sde', 'correlated noise'),
+    references=('Black and Scholes 1973', 'Merton 1973'),
+    defaults={'until': 1.0, 'dt': 0.01, 'solver': EulerMaruyamaSolver(dt=1e-3)},
+)
+def correlated_geometric_brownian_motion(
+    prices: tuple[float, float] = (100.0, 100.0),
+    *,
+    mu: tuple[float, float] = (0.05, 0.08),
+    sigma: tuple[float, float] = (0.2, 0.3),
+    rho: float = 0.7,
+) -> System:
+    """Return two assets whose prices follow geometric Brownian motions driven by correlated Wiener processes.
+
+    A `WienerProcessSpec` of dimension 2 with the covariance `[[1, rho], [rho, 1]]` drives the two prices, so their log
+    returns over a short time have the correlation `rho`.
+
+    Args:
+        prices:
+            The initial prices of the two assets.
+
+        mu:
+            The drifts of the two assets.
+
+        sigma:
+            The volatilities of the two assets.
+
+        rho:
+            The correlation of the two Wiener processes, from -1 to 1.
+
+    Returns:
+        system:
+            The model, with the assets `first` and `second`, whose motions share the Wiener processes `market`.
+
+    Examples:
+        >>> from skcomplex.models.economics.finance import correlated_geometric_brownian_motion
+        >>> correlated_geometric_brownian_motion(rho=0.5).interactions[1].process.covariance
+        [[1.0, 0.5], [0.5, 1.0]]
+    """
+    labels = ('first', 'second')
+    market = WienerProcessSpec('market', dimension=2, covariance=[[1.0, rho], [rho, 1.0]])
+    return System(
+        elements=[AssetElement(label, price=price) for label, price in zip(labels, prices, strict=True)],
+        interactions=[
+            GeometricBrownianMotionInteraction(
+                f'{label}_motion',
+                target=label,
+                process=market,
+                index=index,
+                mu=drift,
+                sigma=volatility,
+            )
+            for index, (label, drift, volatility) in enumerate(zip(labels, mu, sigma, strict=True))
+        ],
+    )

skcomplex/models/economics/finance/_debt_rank_cascade.py

@@ -0,0 +1,86 @@
+"""Synchronous spread of distress, `h_i = min(1, h_i + sum_j W_ji h_j)` over the distressed banks `j`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+from types import SimpleNamespace
+from typing import Annotated
+
+import numpy as np
+
+from ....core.interactions import Interaction
+from ....core.laws import BaseLaw, RuleLaw
+from ....engine.solvers import ModelView
+from ....specs import RoleSpec
+from ._interbank import UNDISTRESSED
+from ._interbank_view import InterbankView
+
+DISTRESSED = 1
+
+
+INACTIVE = 2
+
+
+class DebtRankCascadeInteraction(Interaction):
+    """Synchronous spread of distress, `h_i = min(1, h_i + sum_j W_ji h_j)` over the distressed banks `j`.
+
+    A bank whose distress becomes positive turns distressed, and a distressed bank turns inactive after one step, so
+    every bank passes its distress on once.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        banks:
+            The path of the group of banks.
+
+        impact:
+            The impact matrix, `impact[i][j]` the relative loss of `j` when `i` defaults.
+
+    Examples:
+        >>> from skcomplex.models.economics.finance import DebtRankCascadeInteraction
+        >>> DebtRankCascadeInteraction('cascade', banks='banks', impact=[[0.0, 0.5], [0.0, 0.0]]).impact
+        [[0.0, 0.5], [0.0, 0.0]]
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        banks: Annotated[str, RoleSpec()],
+        impact: Sequence[Sequence[float]] = (),
+    ) -> None:
+        super().__init__(label)
+        self.banks = banks
+        self.impact = impact
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the cascade rule.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the component.
+        """
+        return [RuleLaw(self.spread)]
+
+    def spread(self, model: ModelView) -> None:
+        """Advance the distress and the states of every bank by one step.
+
+        Args:
+            model:
+                The model.
+        """
+        banks = sorted(model.agents('banks', InterbankView), key=lambda bank: bank.id)
+        h = np.array([bank.h for bank in banks])
+        status = np.array([bank.status for bank in banks])
+        distressed = status == DISTRESSED
+        new_h = np.minimum(1.0, h + np.asarray(self.impact, dtype=float).T @ (h * distressed))
+        hit = (status == UNDISTRESSED) & (new_h > 0)
+        new_status = np.where(distressed, INACTIVE, np.where(hit, DISTRESSED, status))
+        for bank, level, code in zip(banks, new_h, new_status, strict=True):
+            bank.h, bank.status = float(level), float(code)

skcomplex/models/economics/finance/_geometric_brownian_motion.py

@@ -0,0 +1,89 @@
+"""Geometric Brownian motion, `dS = mu * S * dt + sigma * S * dW`, of the price of an asset."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.interactions import RateInteraction
+from ....specs import ParameterSpec, RoleSpec, WienerProcessSpec
+
+
+class GeometricBrownianMotionInteraction(RateInteraction):
+    """Geometric Brownian motion, `dS = mu * S * dt + sigma * S * dW`, of the price of an asset.
+
+    The Wiener process `dW` is independent by default, or process `index` of a `WienerProcessSpec` that correlates it
+    with the motions of other assets.
+
+    Args:
+        label:
+            The label of the interaction.
+
+        target:
+            The path of the asset.
+
+        mu:
+            The drift.
+
+        sigma:
+            The volatility.
+
+        process:
+            The Wiener processes, one of which drives the price, or `None` for an independent process.
+
+        index:
+            The process of `process` that drives the price, or `None` without processes.
+
+    Examples:
+        >>> from skcomplex.models.economics.finance import GeometricBrownianMotionInteraction
+        >>> from skcomplex.specs import WienerProcessSpec
+        >>> GeometricBrownianMotionInteraction('gbm', target='stock', sigma=0.3).sigma
+        0.3
+        >>> market = WienerProcessSpec('market', dimension=2)
+        >>> GeometricBrownianMotionInteraction('gbm', target='stock', process=market, index=1).check().index
+        1
+    """
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        target: Annotated[str, RoleSpec()],
+        mu: Annotated[float, ParameterSpec()] = 0.05,
+        sigma: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.2,
+        process: Annotated[WienerProcessSpec | None, RoleSpec(noise=True)] = None,
+        index: int | None = None,
+    ) -> None:
+        super().__init__(label, target=target, state='price', process=process, index=index)
+        self.mu = mu
+        self.sigma = sigma
+
+    def _get_rate(self, namespace: SimpleNamespace) -> object:
+        """Return the drift `mu * S`.
+
+        Args:
+            namespace:
+                The namespace of the symbols the rate can use.
+
+        Returns:
+            rate:
+                The drift.
+        """
+        return namespace.mu * namespace.target.price
+
+    def _get_noise(self, namespace: SimpleNamespace) -> object:
+        """Return the noise amplitude `sigma * S`.
+
+        Args:
+            namespace:
+                The namespace of the symbols the noise can use.
+
+        Returns:
+            noise:
+                The noise amplitude.
+        """
+        return namespace.sigma * namespace.target.price

skcomplex/models/economics/finance/_gibrat_firm.py

@@ -0,0 +1,82 @@
+"""Firm whose size is multiplied every step by an independent normal growth factor, `x = lambda x`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....engine.solvers import ModelView
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+from ._gibrat_firm_view import GibratFirmView
+
+
+class GibratFirmElement(Element):
+    """Firm whose size is multiplied every step by an independent normal growth factor, `x = lambda x`.
+
+    Args:
+        label:
+            The label of the agent or group.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        x:
+            The initial size.
+
+        previous:
+            The size before the last step.
+
+        mu:
+            The mean of the growth factor.
+
+        sigma:
+            The standard deviation of the growth factor.
+
+    Examples:
+        >>> from skcomplex.core.elements import GroupElement
+        >>> from skcomplex.models.economics.finance import GibratFirmElement
+        >>> GroupElement('firms', element=GibratFirmElement, size=10, values={'mu': 1.0}).size
+        10
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        x: Annotated[float, StateSpec()] = 100.0,
+        previous: Annotated[float, StateSpec()] = 100.0,
+        mu: Annotated[float, ParameterSpec()] = 1.02,
+        sigma: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.x = x
+        self.previous = previous
+        self.mu = mu
+        self.sigma = sigma
+
+    @classmethod
+    def _get_view(cls) -> type[GibratFirmView]:
+        """Return the view of the agents of the element."""
+        return GibratFirmView
+
+    @staticmethod
+    def get_growth(agent: GibratFirmView, model: ModelView) -> float:
+        """Return the size multiplied by a growth factor drawn from a normal distribution.
+
+        Args:
+            agent:
+                The firm.
+
+            model:
+                The model view of the growth.
+
+        Returns:
+            size:
+                The size after the step.
+        """
+        return agent.x * float(model.rng.normal(agent.mu, agent.sigma))

skcomplex/models/economics/finance/_gibrat_firm_view.py

@@ -0,0 +1,18 @@
+"""Define the view of a firm of Gibrat's process, as its growth and the reflecting floor see it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ....engine.solvers import AgentView
+
+
+class GibratFirmView(AgentView):
+    """Firm of Gibrat's process as the rules see it, with its size and growth factor.
+
+    It reads its size `x`, its `previous` size, and the mean `mu` and the deviation `sigma` of its growth factor.
+    """
+
+    x: float
+    previous: float
+    mu: float
+    sigma: float