doribt 0.2.0__py3-none-any.whl

doribt/__init__.py

@@ -0,0 +1,69 @@
+"""DoriBT: A-share backtesting with explicit data, rules and accounting."""
+
+from doribt.accounting.costs import Costs
+from doribt.accounting.orders import Fill, IntentRecord, Order, Reason
+from doribt.accounting.rights import CorporateEvent, EntitlementRecord, UnsupportedCorporateAction
+from doribt.accounting.taxes import TaxLotRecord, TaxPayment, TaxRecord
+from doribt.market.actions import CorporateAction
+from doribt.market.adjustments import PriceAdjustment
+from doribt.market.china import china_rules
+from doribt.market.clock import MinuteClock
+from doribt.market.data import MarketData
+from doribt.market.instruments import Instrument, TradingStatus
+from doribt.market.rules import RuleBook, RulePeriod, TradingRule
+from doribt.provenance import RunInfo
+from doribt.reporting.benchmark import Benchmark
+from doribt.reporting.report import ResearchReport
+from doribt.reporting.result import BacktestResult
+from doribt.research.config import RunConfig
+from doribt.research.outputs import Metric, ResearchOutput, Series, Table
+from doribt.research.parameters import Parameter, ParameterSet
+from doribt.runtime.context import Context
+from doribt.runtime.engine import Backtest
+from doribt.runtime.slippage import BarExecution, FixedBps, FixedTicks, VolumeImpact
+from doribt.runtime.targets import PositionTargets, WeightTargets
+
+__all__ = [
+    "MinuteClock",
+    "RunConfig",
+    "Parameter",
+    "ParameterSet",
+    "Metric",
+    "Series",
+    "Table",
+    "ResearchOutput",
+    "ResearchReport",
+    "Backtest",
+    "BarExecution",
+    "FixedBps",
+    "FixedTicks",
+    "VolumeImpact",
+    "BacktestResult",
+    "Benchmark",
+    "RunInfo",
+    "Context",
+    "Costs",
+    "WeightTargets",
+    "PositionTargets",
+    "CorporateAction",
+    "PriceAdjustment",
+    "china_rules",
+    "CorporateEvent",
+    "EntitlementRecord",
+    "UnsupportedCorporateAction",
+    "TaxLotRecord",
+    "TaxPayment",
+    "TaxRecord",
+    "Instrument",
+    "MarketData",
+    "RuleBook",
+    "RulePeriod",
+    "TradingRule",
+    "TradingStatus",
+    "Order",
+    "Fill",
+    "IntentRecord",
+    "Reason",
+]
+
+__version__ = "0.2.0"

doribt/accounting/__init__.py

@@ -0,0 +1 @@
+"""DoriBT accounting implementation; public API is exported by doribt."""

doribt/accounting/account.py

@@ -0,0 +1,91 @@
+"""FIFO acquisition lots and trading-session settlement state."""
+
+from dataclasses import dataclass
+from datetime import date
+
+import numpy as np
+
+from doribt.accounting.orders import Order
+from doribt.kernels.execution import IntArray
+from doribt.validation import MAX_MONEY
+
+
+@dataclass
+class Lot:
+    symbol: str
+    quantity: int
+    acquired: date
+    available_session: int
+    price_units: int
+
+
+@dataclass(frozen=True)
+class Position:
+    symbol: str
+    quantity: int
+    sellable: int
+    value: float
+    pending_quantity: int = 0
+    frozen_quantity: int = 0
+
+    @property
+    def available_quantity(self) -> int:
+        return max(0, self.sellable - self.frozen_quantity)
+
+
+class Account:
+    def __init__(self, initial_cash: int, symbols: tuple[str, ...]) -> None:
+        self.cash = initial_cash
+        self.symbols = symbols
+        self.lots: list[Lot] = []
+
+    def quantities(self, index: int | None = None) -> IntArray:
+        totals = dict.fromkeys(self.symbols, 0)
+        for lot in self.lots:
+            if index is None or lot.available_session <= index:
+                totals[lot.symbol] += lot.quantity
+        if any(quantity > 1_000_000_000 for quantity in totals.values()):
+            raise OverflowError("registered share quantity exceeds supported bounds")
+        return np.array(list(totals.values()), dtype=np.int64)
+
+    def apply(self, order: Order, index: int, settlement: int) -> None:
+        if order.filled > 0:
+            self.lots.append(
+                Lot(
+                    order.symbol, order.filled, order.session, index + settlement, order.price_units
+                )
+            )
+        elif order.filled < 0:
+            self._sell(order.symbol, -order.filled, index)
+
+    def _sell(self, symbol: str, quantity: int, index: int) -> None:
+        for lot in self.lots:
+            if lot.symbol != symbol or lot.available_session > index:
+                continue
+            consumed = min(quantity, lot.quantity)
+            lot.quantity -= consumed
+            quantity -= consumed
+        self.lots = [lot for lot in self.lots if lot.quantity]
+        if quantity:
+            raise RuntimeError("execution sold more than settled lots")
+
+    def value(
+        self,
+        closes: IntArray,
+        pending_shares: IntArray | None = None,
+        receivable: int = 0,
+        tax_payable: int = 0,
+    ) -> int:
+        equity = self.cash + receivable - tax_payable
+        quantities = self.quantities()
+        if pending_shares is not None:
+            quantities = quantities + pending_shares
+        if np.any(quantities > 1_000_000_000):
+            raise OverflowError("economic share quantity exceeds supported bounds")
+        for quantity, price in zip(quantities, closes, strict=True):
+            if quantity and price <= 0:
+                raise ValueError("held security has no active valuation; unsupported delisting")
+            equity += int(quantity) * int(price)
+        if not 0 <= equity <= MAX_MONEY:
+            raise OverflowError("account equity exceeds supported bounds")
+        return equity

doribt/accounting/costs.py

@@ -0,0 +1,32 @@
+"""Account-specific execution assumptions, separate from historical market rules."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from doribt.kernels.execution import IntArray
+from doribt.validation import Number, amount, integer, ratio
+
+
+@dataclass(frozen=True, kw_only=True)
+class Costs:
+    commission: Number = "0.0003"
+    minimum_commission: Number = "5.00"
+    slippage_ticks: int = 0
+
+    def __post_init__(self) -> None:
+        ratio(self.commission, "commission")
+        minimum = amount(self.minimum_commission, "minimum_commission")
+        if minimum % 100:
+            raise ValueError("minimum commission must use whole cents")
+        integer(self.slippage_ticks, 1, "slippage_ticks", 0, 1000)
+
+    def compile(self) -> IntArray:
+        return np.array(
+            [
+                ratio(self.commission),
+                amount(self.minimum_commission),
+                self.slippage_ticks,
+            ],
+            dtype=np.int64,
+        )

doribt/accounting/orders.py

@@ -0,0 +1,162 @@
+"""Immutable public order history. All money fields are integer 1/10,000 yuan."""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from enum import StrEnum
+
+
+class Reason(StrEnum):
+    NONE = "none"
+    SUSPENDED = "suspended"
+    INACTIVE = "inactive"
+    BUY_AT_UPPER_LIMIT = "buy_at_upper_limit"
+    SELL_AT_LOWER_LIMIT = "sell_at_lower_limit"
+    NO_VOLUME = "no_volume"
+    INVALID_QUANTITY = "invalid_quantity"
+    INSUFFICIENT_CASH = "insufficient_cash"
+    INSUFFICIENT_SELLABLE = "insufficient_sellable"
+    INSUFFICIENT_POSITION = "insufficient_position"
+    PRICE_OUT_OF_RANGE = "price_out_of_range"
+    PARTICIPATION_LIMIT = "participation_limit"
+    LIMIT_PRICE = "limit_price"
+    AUCTION = "auction"
+
+
+REASONS = tuple(Reason)
+
+
+@dataclass(frozen=True)
+class Order:
+    order_id: int
+    intent_id: int
+    session: date
+    symbol: str
+    quantity: int
+    filled: int
+    price_units: int
+    commission_units: int
+    stamp_duty_units: int
+    transfer_fee_units: int
+    reason: Reason
+    created_at: date | None = None
+    updated_at: date | None = None
+    state: str = ""
+    notional_units: int = 0
+    valid_for: str = "next_bar"
+    limit_units: int = 0
+    frozen_cash_units: int = 0
+    frozen_quantity: int = 0
+
+    @property
+    def commission(self) -> float:
+        return self.commission_units / 10_000
+
+    @property
+    def stamp_duty(self) -> float:
+        return self.stamp_duty_units / 10_000
+
+    @property
+    def transfer_fee(self) -> float:
+        return self.transfer_fee_units / 10_000
+
+    @property
+    def events(self) -> tuple[str, ...]:
+        if self.state:
+            middle = ("partially_filled",) if self.filled and self.remaining else ()
+            return ("created", "accepted", *middle, self.state)
+        if self.reason == Reason.INVALID_QUANTITY:
+            return ("created", "rejected")
+        if self.filled == self.quantity:
+            return ("created", "accepted", "filled")
+        if self.filled:
+            return ("created", "accepted", "partially_filled", "expired")
+        return ("created", "accepted", "expired")
+
+    @property
+    def fees(self) -> float:
+        return (self.commission_units + self.stamp_duty_units + self.transfer_fee_units) / 10_000
+
+    @property
+    def status(self) -> str:
+        return self.events[-1]
+
+    @property
+    def remaining(self) -> int:
+        return self.quantity - self.filled
+
+    @property
+    def price(self) -> float | None:
+        if self.state and self.filled:
+            return self.notional_units / abs(self.filled) / 10_000
+        return self.price_units / 10_000 if self.filled else None
+
+
+@dataclass(frozen=True)
+class Fill:
+    fill_id: int
+    order_id: int
+    intent_id: int
+    session: date
+    symbol: str
+    quantity: int
+    price_units: int
+    commission_units: int
+    stamp_duty_units: int
+    transfer_fee_units: int
+    timestamp: datetime | None = None
+
+    @property
+    def commission(self) -> float:
+        return self.commission_units / 10_000
+
+    @property
+    def stamp_duty(self) -> float:
+        return self.stamp_duty_units / 10_000
+
+    @property
+    def transfer_fee(self) -> float:
+        return self.transfer_fee_units / 10_000
+
+    @property
+    def price(self) -> float:
+        return self.price_units / 10_000
+
+    @property
+    def fees(self) -> float:
+        return (self.commission_units + self.stamp_duty_units + self.transfer_fee_units) / 10_000
+
+    @classmethod
+    def from_order(cls, fill_id: int, order: Order) -> "Fill":
+        return cls(
+            fill_id,
+            order.order_id,
+            order.intent_id,
+            order.session,
+            order.symbol,
+            order.filled,
+            order.price_units,
+            order.commission_units,
+            order.stamp_duty_units,
+            order.transfer_fee_units,
+        )
+
+
+@dataclass(frozen=True)
+class TargetAdjustment:
+    action_id: str
+    session: date
+    before: int
+    after: int
+
+
+@dataclass(frozen=True)
+class IntentRecord:
+    intent_id: int
+    created: date
+    symbol: str
+    kind: str
+    quantity: int
+    status: str
+    closed: date | None
+    reason: str
+    adjustments: tuple[TargetAdjustment, ...] = ()

doribt/accounting/rights.py

@@ -0,0 +1,239 @@
+"""Record-date ownership, receivables, share credit and subsequent availability."""
+
+from bisect import bisect_left
+from dataclasses import dataclass
+from datetime import date
+
+import numpy as np
+
+from doribt.accounting.account import Account, Lot
+from doribt.accounting.taxes import TaxBook
+from doribt.kernels.execution import IntArray
+from doribt.market.actions import CorporateAction
+from doribt.market.data import MarketData
+from doribt.runtime.intents import IntentBook
+from doribt.validation import MAX_MONEY, day, integer
+
+
+class UnsupportedCorporateAction(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class CorporateEvent:
+    session: date
+    action_id: str
+    symbol: str
+    kind: str
+    quantity: int = 0
+    amount_units: int = 0
+
+
+@dataclass
+class Entitlement:
+    action: CorporateAction
+    quantity: int
+    cash_units: int
+    bonus_quantity: int
+    accrued: bool = False
+    cash_paid: bool = False
+    shares_credited: bool = False
+
+
+@dataclass(frozen=True)
+class EntitlementRecord:
+    action_id: str
+    symbol: str
+    record_date: date
+    ex_date: date
+    pay_date: date | None
+    share_credit_date: date | None
+    share_listing_date: date | None
+    eligible_quantity: int
+    cash_units: int
+    bonus_quantity: int
+    accrued: bool
+    cash_paid: bool
+    shares_credited: bool
+
+
+class RightsBook:
+    def __init__(self, data: MarketData) -> None:
+        self.data = data
+        self.kinds = {item.symbol: item.kind for item in data.instruments}
+        self.tax = TaxBook(self.kinds)
+        self.entitlements: dict[str, Entitlement] = {}
+        self.events: list[CorporateEvent] = []
+        self._record: dict[date, list[CorporateAction]] = {}
+        self._ex: dict[date, list[CorporateAction]] = {}
+        for action in data.actions:
+            self._record.setdefault(day(action.record_date), []).append(action)
+            self._ex.setdefault(day(action.ex_date), []).append(action)
+
+    def start(self, index: int, account: Account, intents: IntentBook) -> None:
+        session = self.data.sessions[index]
+        for action in self._ex.get(session, []):
+            if action.kind != "distribution" and action.symbol in intents.pending:
+                raise UnsupportedCorporateAction(f"unsupported {action.kind}: {action.action_id}")
+            self._ex_date(action, session, account)
+            bonus = integer(action.bonus_per_share, 1_000_000, "bonus", 0, 100_000_000)
+            intents.adjust(action.symbol, action.action_id, session, bonus)
+        for entitlement in self.entitlements.values():
+            if not entitlement.accrued:
+                continue
+            self._pay(entitlement, session, account)
+            self._credit(entitlement, index, account)
+        account.cash = self.tax.settle(session, account.cash)
+
+    def close(self, index: int, account: Account) -> None:
+        session = self.data.sessions[index]
+        quantities = dict(zip(self.data.symbols, map(int, account.quantities()), strict=True))
+        self.tax.reconcile(session, quantities)
+        for action in self._record.get(session, []):
+            quantity = quantities[action.symbol]
+            if quantity:
+                self._capture(action, quantity, session)
+
+    def _capture(self, action: CorporateAction, quantity: int, session: date) -> None:
+        cash_micros = integer(action.cash_per_share, 1_000_000, "cash per share", 0, MAX_MONEY)
+        bonus = integer(action.bonus_per_share, 1_000_000, "bonus per share", 0, 100_000_000)
+        if quantity * bonus % 1_000_000:
+            raise UnsupportedCorporateAction(
+                f"fractional share allocation unavailable: {action.action_id}"
+            )
+        cash = (quantity * cash_micros + 5000) // 10_000 * 100
+        if cash > MAX_MONEY:
+            raise OverflowError("dividend entitlement exceeds supported bounds")
+        entitlement = Entitlement(
+            action,
+            quantity,
+            cash,
+            quantity * bonus // 1_000_000,
+            cash_paid=not bool(cash),
+            shares_credited=not bool(bonus),
+        )
+        self.entitlements[action.action_id] = entitlement
+        if action.kind == "distribution":
+            taxable_bonus = self._taxable_bonus(action, bonus)
+            self.tax.attach(action.symbol, action.action_id, cash_micros + taxable_bonus, session)
+        self.events.append(
+            CorporateEvent(session, action.action_id, action.symbol, "recorded", quantity)
+        )
+
+    def _taxable_bonus(self, action: CorporateAction, bonus: int) -> int:
+        value = action.taxable_bonus_amount_per_share
+        if bonus and value is None and self.kinds[action.symbol] == "stock":
+            raise ValueError(f"taxable bonus amount is required: {action.action_id}")
+        return integer(value or 0, 1_000_000, "taxable bonus", 0, MAX_MONEY)
+
+    def _ex_date(self, action: CorporateAction, session: date, account: Account) -> None:
+        entitlement = self.entitlements.get(action.action_id)
+        held = int(account.quantities()[self.data.symbols.index(action.symbol)])
+        pending = any(
+            e.action.symbol == action.symbol
+            and e.accrued
+            and (not e.shares_credited or not e.cash_paid)
+            for e in self.entitlements.values()
+        )
+        if action.kind != "distribution" and (entitlement is not None or held or pending):
+            raise UnsupportedCorporateAction(f"unsupported {action.kind}: {action.action_id}")
+        if entitlement is not None:
+            entitlement.accrued = True
+            self.events.append(
+                CorporateEvent(
+                    session,
+                    action.action_id,
+                    action.symbol,
+                    "accrued",
+                    entitlement.bonus_quantity,
+                    entitlement.cash_units,
+                )
+            )
+
+    def _pay(self, entitlement: Entitlement, session: date, account: Account) -> None:
+        action = entitlement.action
+        if entitlement.cash_paid or action.pay_date is None or session < day(action.pay_date):
+            return
+        account.cash += entitlement.cash_units
+        if account.cash > MAX_MONEY:
+            raise OverflowError("dividend payment exceeds supported cash bounds")
+        entitlement.cash_paid = True
+        self.events.append(
+            CorporateEvent(
+                session,
+                action.action_id,
+                action.symbol,
+                "cash_paid",
+                amount_units=entitlement.cash_units,
+            )
+        )
+
+    def _credit(self, entitlement: Entitlement, index: int, account: Account) -> None:
+        action, session = entitlement.action, self.data.sessions[index]
+        if entitlement.shares_credited or action.share_credit_date is None:
+            return
+        if session < day(action.share_credit_date):
+            return
+        if action.share_listing_date is None:
+            raise RuntimeError("validated bonus shares require a listing date")
+        available = bisect_left(self.data.sessions, day(action.share_listing_date))
+        account.lots.append(
+            Lot(
+                action.symbol,
+                entitlement.bonus_quantity,
+                day(action.share_credit_date),
+                available,
+                0,
+            )
+        )
+        entitlement.shares_credited = True
+        self.events.append(
+            CorporateEvent(
+                session,
+                action.action_id,
+                action.symbol,
+                "shares_credited",
+                entitlement.bonus_quantity,
+            )
+        )
+
+    @property
+    def receivable(self) -> int:
+        total = sum(
+            e.cash_units for e in self.entitlements.values() if e.accrued and not e.cash_paid
+        )
+        if total > MAX_MONEY:
+            raise OverflowError("dividend receivables exceed supported bounds")
+        return total
+
+    def pending_shares(self) -> IntArray:
+        pending = dict.fromkeys(self.data.symbols, 0)
+        for entitlement in self.entitlements.values():
+            if entitlement.accrued and not entitlement.shares_credited:
+                pending[entitlement.action.symbol] += entitlement.bonus_quantity
+        if any(quantity > 1_000_000_000 for quantity in pending.values()):
+            raise OverflowError("pending share quantity exceeds supported bounds")
+        return np.array(list(pending.values()), dtype=np.int64)
+
+    def records(self) -> tuple[EntitlementRecord, ...]:
+        result = []
+        for e in self.entitlements.values():
+            action = e.action
+            result.append(
+                EntitlementRecord(
+                    action.action_id,
+                    action.symbol,
+                    day(action.record_date),
+                    day(action.ex_date),
+                    None if action.pay_date is None else day(action.pay_date),
+                    None if action.share_credit_date is None else day(action.share_credit_date),
+                    None if action.share_listing_date is None else day(action.share_listing_date),
+                    e.quantity,
+                    e.cash_units,
+                    e.bonus_quantity,
+                    e.accrued,
+                    e.cash_paid,
+                    e.shares_credited,
+                )
+            )
+        return tuple(result)