openscript 0.4.0__py3-none-any.whl

openscript/accounting/charges.py

@@ -0,0 +1,397 @@
+"""What a fill costs, as an ordered list of lines the platform brings.
+
+**The language has three commission spellings and a slippage in ticks, and a real
+cost stack is not shaped like that.** It is a flat fee, a percentage, a charge
+levied on a charge, and a tax that applies to one side of the trade only.
+Teaching the language one market's stack would be teaching it a market, so the
+platform passes a schedule instead and the language keeps the three spellings it
+has, which turn into a schedule of one line.
+
+**Order is part of the result.** The lines are applied in the order they are
+declared, a line charged on other lines may only name lines declared before it,
+and that is what makes a schedule evaluable in exactly one order. Two engines
+that disagree about the order disagree about the money, and a disagreement in the
+last bit is still a failed conformance comparison (``conformance.md`` 6).
+
+**Where it is applied is not here.** ``stdlib.md`` 17.1 puts slippage and
+commission on the destination: the engine folds the price it is told and never
+adjusts one, so a cost model inside the ledger would be the engine moving a
+price, which is the one thing that invariant forbids. This module says what a
+charge is and works out what one fill came to.
+
+**What is charged to a fill, and only to a fill.** Every line is measured against
+this fill and nothing else, so a tier that changes with the month's cumulative
+volume, a cap counted per day and margin and its interest are outside this model
+rather than approximated inside it. A cost model that quietly approximates is a
+report that is wrong in the strategy's favour and says nothing about it.
+"""
+
+import math
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+from .shapes import Contract, RecordedFill
+
+#: What a line's rate is measured against. Four bases cover every stack the
+#: documentation describes without naming a market: a fraction of turnover, money
+#: per unit, money per fill, and a fraction of the lines named before this one,
+#: which is the charge on a charge.
+BASES: Tuple[str, ...] = ("turnover", "units", "order", "charges")
+
+#: Which side of the trade a line applies to. A transaction tax levied on one
+#: side is expressed exactly rather than smeared across both fills at half the
+#: rate, which is what makes a reader's figure disagree with their broker's.
+SIDES: Tuple[str, ...] = ("buy", "sell", "both")
+
+#: The most digits money is rounded to. A rounding scale is a power of ten and a
+#: binary64 holds about fifteen significant decimal digits, so past this the scale
+#: itself is approximate and the rounding stops being arithmetic and becomes
+#: noise.
+MAX_DIGITS = 15
+
+#: A percentage, as the declaration states one, over the fraction a rate is.
+PERCENT = 100
+
+#: What a refusal calls the setting it is about, ``errors.md`` OS6021.
+SETTING = "The charge schedule"
+
+
+@dataclass(frozen=True)
+class ChargeLine:
+    """One line of a schedule, applied to one fill."""
+
+    #: The platform's own word.
+    name: str
+    base: str
+    side: str = "both"
+    #: Fraction for turnover and charges, money per unit for units, money for
+    #: order.
+    rate: float = 0.0
+    #: Floor per application.
+    min: Optional[float] = None
+    #: Cap per application.
+    max: Optional[float] = None
+    #: Base ``charges`` only: names of lines declared before this one.
+    of: Tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ChargeSchedule:
+    """The whole cost model a run was carried out under."""
+
+    currency: str = "CUR"
+    digits: int = 2
+    slippage_ticks: float = 0.0
+    #: Applied in order, and order is part of the result.
+    lines: Tuple[ChargeLine, ...] = ()
+    #: Where the schedule came from. One derived from the declaration is derived
+    #: again on replay rather than stored, because what the program states is
+    #: stored once, as the program.
+    source: str = "declaration"
+
+
+@dataclass(frozen=True)
+class ChargeBreakdown:
+    """What one fill was charged, line by line and in total."""
+
+    lines: Tuple[Tuple[str, float], ...] = ()
+    total: float = 0.0
+
+
+def round_money(amount: float, digits: int) -> float:
+    """One money figure, rounded once, halves to even.
+
+    Half to even, and not the language's own rounding. ``round()`` in the language
+    is halves away from zero, because a price a trader reads should agree with
+    what they would write down (``stdlib.md`` 8.1). Money folded over thousands of
+    fills is a different question: away from zero biases every exact half upward,
+    and half a unit of the last digit per fill is a bias that grows with the length
+    of the backtest.
+
+    A digit count this cannot round by is one ``schedule_problem`` refuses before
+    the first bar. If one arrives anyway the amount is returned as it stands,
+    because an unrounded figure is worth more than a scale of ten to an impossible
+    power.
+    """
+    if not math.isfinite(amount):
+        return amount
+    if isinstance(digits, bool) or not isinstance(digits, int) or digits < 0 or digits > MAX_DIGITS:
+        return amount
+
+    scale = 10**digits
+    scaled = amount * scale
+    below = math.floor(scaled)
+    fraction = scaled - below
+
+    whole = below
+    if fraction > 0.5:
+        whole = below + 1
+    elif fraction == 0.5 and below % 2 != 0:
+        whole = below + 1
+
+    money = whole / scale
+    # A negative zero is the same money as a zero and a different set of bytes.
+    return 0.0 if money == 0 else money
+
+
+def _bounded(raw: float, line: ChargeLine) -> float:
+    """The floor and the cap, per application.
+
+    Which is applied first does not decide the answer, because a floor above a cap
+    is refused before the first bar rather than resolved here by whichever
+    comparison runs first.
+    """
+    amount = raw
+    if line.min is not None and amount < line.min:
+        amount = line.min
+    if line.max is not None and amount > line.max:
+        amount = line.max
+    return amount
+
+
+def _base_of(
+    line: ChargeLine, turnover: float, units: float, applied: Sequence[Tuple[str, float]]
+) -> float:
+    """What a line's rate is measured against, for this fill.
+
+    The earlier lines are searched rather than indexed. An index would be a map,
+    and this module depends on no map's iteration order; a schedule is a handful
+    of lines, so the search costs nothing and the promise costs one less thing to
+    be careful about.
+    """
+    if line.base == "turnover":
+        return turnover
+    if line.base == "units":
+        return units
+    if line.base == "order":
+        return 1.0
+    # A name whose line did not apply to this side is absent and adds nothing,
+    # which is a charge levied on a charge that was never taken.
+    total = 0.0
+    for named in line.of:
+        for one, amount in applied:
+            if one == named:
+                total += amount
+    return total
+
+
+def charge_for(
+    schedule: ChargeSchedule, fill: RecordedFill, contract: Contract
+) -> ChargeBreakdown:
+    """What one fill cost, line by line and in total.
+
+    **The lines are the arithmetic and the total is the money.** Each line's
+    amount is computed in binary64 and left unrounded, and the per-fill total is
+    rounded once, half to even, to the contract's digits. Rounding each line would
+    round once per line, and two engines rounding in two places disagree in the
+    last bit. So a reader adding the lines up by hand may land a fraction of the
+    last digit away from the total, and that is the honest way round: the total is
+    the figure the report accumulates.
+
+    **A line that does not apply to this side is not in the breakdown at all.** A
+    name beside a zero reads as a charge that was levied and came to nothing, and
+    a later line levied on that name is levied on nothing, which is exactly what a
+    tax on one side of the trade does.
+    """
+    turnover = fill.units * fill.price * contract.point_value
+    applied: List[Tuple[str, float]] = []
+
+    for line in schedule.lines:
+        if line.side != "both" and line.side != fill.side:
+            continue
+        base = _base_of(line, turnover, fill.units, applied)
+        applied.append((line.name, _bounded(line.rate * base, line)))
+
+    exact = 0.0
+    for _name, amount in applied:
+        exact += amount
+
+    return ChargeBreakdown(lines=tuple(applied), total=round_money(exact, contract.digits))
+
+
+def _commission_line(commission: float, commission_type: str) -> ChargeLine:
+    """The one line a declared commission is, in the base its spelling names."""
+    if commission_type == "perUnit":
+        return ChargeLine(name="commission", base="units", rate=commission)
+    if commission_type == "percent":
+        return ChargeLine(name="commission", base="turnover", rate=commission / PERCENT)
+    return ChargeLine(name="commission", base="order", rate=commission)
+
+
+def schedule_from_declaration(
+    commission: float,
+    commission_type: str,
+    slippage: float,
+    currency: str,
+    digits: int,
+) -> ChargeSchedule:
+    """The declaration's own cost model, as the one schedule this module evaluates.
+
+    **The declaration is not a second cost engine.** Its three commission
+    spellings are a schedule of one line: a flat fee is a line charged per fill, a
+    per unit fee is a line charged per unit, and a percentage is a line charged on
+    turnover.
+
+    **A commission of zero is no line at all**, rather than a line charging
+    nothing. A zero line would put a name in every breakdown and would make a
+    declaration that states no commission indistinguishable from one that states a
+    commission.
+
+    **A flat fee is charged per fill**, which is the one place ``language.md``
+    13.3 lets a reasonable person read the words two ways. A charge is attributed
+    to the fill that incurred it everywhere in this module, because that is what
+    attributes it to a trade, so a round trip of two fills is charged twice.
+
+    The currency and the digit count are parameters because neither is the
+    declaration's to state: the declaration's currency is a label and is often
+    left blank, and money rounding is a fact about the contract.
+    """
+    return ChargeSchedule(
+        currency=currency,
+        digits=digits,
+        slippage_ticks=slippage,
+        lines=() if commission == 0 else (_commission_line(commission, commission_type),),
+        source="declaration",
+    )
+
+
+def _money_problem(schedule: ChargeSchedule, contract: Optional[Contract]) -> Optional[str]:
+    """The currency the money is in and the digits it is rounded to.
+
+    A schedule states both and so does the contract, and the two are compared here
+    rather than one of them being quietly preferred. A schedule in another currency
+    charges a fill in money the contract is not priced in, and a total nobody can
+    add to the profit is worse than no total.
+    """
+    digits = schedule.digits
+    if isinstance(digits, bool) or not isinstance(digits, int) or digits < 0 or digits > MAX_DIGITS:
+        return (
+            f"it rounds money to {digits} digits, and a digit count is a whole "
+            f"number from 0 to {MAX_DIGITS}"
+        )
+    if schedule.currency.strip() == "":
+        return "it names no currency, so what it charges is a number with no unit on it"
+    if contract is None:
+        return None
+    if schedule.currency != contract.currency:
+        return (
+            f"it charges in {schedule.currency} and the contract is priced in "
+            f"{contract.currency}"
+        )
+    if digits != contract.digits:
+        return f"it rounds money to {digits} digits and the contract rounds to {contract.digits}"
+    return None
+
+
+def _slippage_problem(schedule: ChargeSchedule, contract: Optional[Contract]) -> Optional[str]:
+    """The slippage, which this module refuses and does not apply.
+
+    A slippage in ticks with no tick size to measure a tick in would charge
+    nothing at all, and a backtest that silently charges nothing is one that lies
+    in the strategy's favour.
+    """
+    ticks = schedule.slippage_ticks
+    if not math.isfinite(ticks) or ticks < 0:
+        return (
+            f"it states {ticks} ticks of slippage, and slippage is adverse, so it "
+            "is never negative"
+        )
+    if ticks == 0 or contract is None:
+        return None
+    tick = contract.tick_size
+    if tick is None or not tick > 0:
+        return (
+            f"it states {ticks} ticks of slippage and the contract has no tick "
+            "size to measure a tick in"
+        )
+    return None
+
+
+def _bound_problem(line: ChargeLine) -> Optional[str]:
+    """The floor and the cap: money, not negative, and the floor no higher than the cap."""
+    if line.min is not None and (not math.isfinite(line.min) or line.min < 0):
+        return f'the line "{line.name}" has a floor of {line.min}, and a bound on a charge is money'
+    if line.max is not None and (not math.isfinite(line.max) or line.max < 0):
+        return f'the line "{line.name}" has a cap of {line.max}, and a bound on a charge is money'
+    if line.min is not None and line.max is not None and line.min > line.max:
+        return f'the line "{line.name}" has a floor of {line.min} above its cap of {line.max}'
+    return None
+
+
+def _levy_problem(line: ChargeLine, declared: Sequence[str]) -> Optional[str]:
+    """What a line is levied on, which is the rule the whole ordering exists for.
+
+    A line levied on lines not declared before it has no single evaluation order,
+    so two engines would charge two different amounts and both would be
+    defensible. Naming itself, naming a line declared after it and naming a line
+    that is not in the schedule at all are one problem in three spellings.
+    """
+    name = line.name
+    if line.base != "charges":
+        if not line.of:
+            return None
+        return (
+            f'the line "{name}" names {len(line.of)} lines to be levied on and its '
+            f"base is {line.base}, so the names are read by nothing"
+        )
+    if not line.of:
+        return f'the line "{name}" is levied on charges and names none, so it is levied on nothing'
+
+    seen: List[str] = []
+    for named in line.of:
+        if named not in declared:
+            return f'the line "{name}" is levied on "{named}", which is not declared before it'
+        if named in seen:
+            return (
+                f'the line "{name}" is levied on "{named}" twice, so that line is '
+                "charged on twice over"
+            )
+        seen.append(named)
+    return None
+
+
+def _line_problem(line: ChargeLine, declared: Sequence[str]) -> Optional[str]:
+    name = line.name
+    if name.strip() == "":
+        return "a line carries no name, and a line levied on charges names the lines it is levied on"
+    if name in declared:
+        return f'two lines are named "{name}", so a line levied on that name is levied on two answers'
+    if not math.isfinite(line.rate) or line.rate < 0:
+        return (
+            f'the line "{name}" charges a rate of {line.rate}, and a charge is '
+            "money taken, never given"
+        )
+    return _bound_problem(line) or _levy_problem(line, declared)
+
+
+def _lines_problem(lines: Sequence[ChargeLine]) -> Optional[str]:
+    declared: List[str] = []
+    for line in lines:
+        problem = _line_problem(line, declared)
+        if problem is not None:
+            return problem
+        declared.append(line.name)
+    return None
+
+
+def schedule_problem(
+    schedule: ChargeSchedule, contract: Optional[Contract] = None
+) -> Optional[Tuple[str, str]]:
+    """Why this schedule cannot be carried out, or none.
+
+    **Asked before the first bar, and answered once.** Everything here is a fact
+    about the schedule rather than about any fill, so a run that would produce a
+    number nobody can explain is refused while nothing has been computed and the
+    cost of correcting it is one run.
+
+    The first problem found is the one reported. A list of everything wrong with a
+    schedule reads as a worse schedule than it is, and it is corrected one line at
+    a time regardless. What comes back is the setting and the problem, which are
+    the two values OS6021's message names: the sentence itself is the catalogue's.
+    """
+    problem = (
+        _money_problem(schedule, contract)
+        or _slippage_problem(schedule, contract)
+        or _lines_problem(schedule.lines)
+    )
+    return None if problem is None else (SETTING, problem)

openscript/accounting/equity.py

@@ -0,0 +1,234 @@
+"""The equity curve: one point per bar in the report window.
+
+**Marked to the close and to nothing else.** An intrabar extreme is a price the
+strategy could not have acted on, so it is not a profit it had, and a curve drawn
+through the extremes flatters every run that ever held a losing position. Where a
+bar's close is absent the previous mark carries and the point says so, rather
+than a zero a reader would compare against.
+
+**Drawdown is stated on equity including open profit**, and the basis is carried
+on every point rather than left to the reader. A report whose drawdown basis is
+not written down is a report whose worst figure means a different thing to each
+reader.
+
+**A trade's charges land on the bar it opened** and **its gross on the bar it
+closed.** The trade list does not carry the timing of the fills underneath it, so
+the cost has to land somewhere, and the open is the one place that is never later
+than the truth. The gross lands at the close because that is the bar it stopped
+being an opinion and became a number; while the trade is open it is in the open
+profit instead, marked to the close, and the two never overlap.
+
+**What a trade list cannot say, said here rather than discovered later.** A trade
+holds one entry price weighted over its entry fills, so a trade whose size changed
+while it was open is not visible in it. A partial close is marked at the full size
+from the bar the reduction settled on, so the open profit of the part already
+closed is counted twice over. A scale-in is the worse of the two, because it is
+wrong from the beginning: a trade that buys a hundred at ten and another hundred
+at twenty is marked, from the bar it first opened, as two hundred units bought at
+fifteen, and the curve reports a drawdown the account never had. Neither reaches
+the realised total, which is folded from the fills. A curve folded from the fills
+rather than from the trades would have neither, and that is a different fold
+rather than a correction to this one.
+
+**A percentage here is a fraction of its basis.** A hundredth of a percent down is
+``-0.0001`` and not ``-0.01``, for every figure in this module that divides. The
+multiplication by a hundred belongs to whatever prints it.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+from .shapes import BarMark, Contract
+from .trades import Trade
+
+
+@dataclass(frozen=True)
+class EquityPoint:
+    """One report bar's standing, folded from the fills settled up to it."""
+
+    bar_index: int
+    time: Optional[float]
+    #: Cumulative gross of closed trades.
+    realised: float
+    #: Cumulative.
+    charges: float
+    #: Marked to this bar's close.
+    open_profit: float
+    #: capital + realised - charges.
+    cash: float
+    #: cash + open profit.
+    equity: float
+    #: The open position's magnitude at this close.
+    exposure: float
+    #: equity less the running peak, zero or negative.
+    drawdown: float
+    #: That distance against the peak, a fraction.
+    drawdown_percent: float
+    #: equity less the running trough, zero or positive: drawdown's mirror, so
+    #: the run's best stretch is measured the same way its worst one is.
+    run_up: float
+    #: That distance against the trough, a fraction, and zero where the trough
+    #: is not above zero. Not the same guard drawdown gets, because the two
+    #: bases are not the same kind of number: a peak starts at the capital and
+    #: only rises, a trough starts there and only falls, so an account that lost
+    #: everything has a trough at or below zero and reports zero here from that
+    #: bar on. Zero is the wrong answer for a run that recovered and is reported
+    #: anyway, because a percentage against a negative basis turns a positive
+    #: climb into a negative fraction. ``run_up`` itself is unaffected.
+    run_up_percent: float
+
+
+def open_on_bar(trade: Trade, bar_index: int) -> bool:
+    """Whether this trade was still held at the close of this bar.
+
+    The boundaries are the whole of the rule and both are decisions. A trade is
+    held from the close of the bar it opened on, because an entry that settled
+    during a bar is a position that bar ended holding. It is not held at the close
+    of the bar it closed on, because that bar ended flat. So a trade opened and
+    closed inside one bar is held at no close at all.
+    """
+    if bar_index < trade.opened_on_bar:
+        return False
+    return trade.closed_on_bar is None or bar_index < trade.closed_on_bar
+
+
+def ratio_of(value: float, basis: float) -> float:
+    """A ratio against a basis that may not be there to divide by.
+
+    Capital of zero and a peak of zero are both reachable, and both turn an honest
+    division into a value a document cannot carry. A basis that is not positive has
+    no ratio to state, so the figure beside it, which is money and is always true,
+    is the one a reader is left with.
+    """
+    return value / basis if basis > 0 else 0.0
+
+
+def _closed_by(trade: Trade, bar_index: int) -> bool:
+    """Whether this bar is the bar the trade closed on, or one after it."""
+    return trade.closed_on_bar is not None and trade.closed_on_bar <= bar_index
+
+
+def equity_over(
+    trades: Sequence[Trade],
+    marks: Sequence[BarMark],
+    contract: Contract,
+    capital: float,
+) -> Tuple[EquityPoint, ...]:
+    """The curve, one point per report bar, in the order the bars arrived.
+
+    Warmup bars are swept and not reported: their orders were real, so a trade
+    opened during the warmup is already in the fold at the first point, with its
+    charges already paid and its position already marked. A curve that began its
+    fold at the first report bar would lose both, and would lose them silently.
+
+    The running peak starts at the capital rather than at the first point, so a run
+    that is down from its first bar is in drawdown at its first bar. Starting it at
+    the first point would report every run as having begun at its high.
+
+    The trades arrive in the order they opened and the bars in the order they were
+    loaded, and both are swept with a pointer rather than searched: a report over
+    fifty thousand bars that rescans its trade list on every one of them is a
+    report nobody waits for.
+    """
+    points: List[EquityPoint] = []
+    held: List[Trade] = []
+    at = 0
+    realised = 0.0
+    charges = 0.0
+    peak = capital
+    trough = capital
+    mark: Optional[float] = None
+
+    for bar in marks:
+        # Opened by this bar, charges and all.
+        while at < len(trades) and trades[at].opened_on_bar <= bar.bar_index:
+            charges += trades[at].charges
+            held.append(trades[at])
+            at += 1
+
+        # Closed by this bar, gross and all. A trade that opened and closed inside
+        # one bar is taken on and given up here in that order, so its cost and its
+        # gross are both in this point and its position is in none.
+        closed_here = False
+        for trade in held:
+            if _closed_by(trade, bar.bar_index):
+                realised += trade.gross_profit
+                closed_here = True
+        if closed_here:
+            held = [trade for trade in held if not _closed_by(trade, bar.bar_index)]
+
+        # A close the host did not have leaves the previous mark standing. It is
+        # carried across the warmup boundary too, so the first report bar of a run
+        # whose close is absent is marked at the last price there was.
+        if bar.close is not None:
+            mark = bar.close
+        if not bar.in_report:
+            continue
+
+        open_profit = 0.0
+        exposure = 0.0
+        for trade in held:
+            # Before the first close there has ever been, a trade is marked at its
+            # own entry: no profit, and the position still visible in the exposure.
+            price = trade.entry_price if mark is None else mark
+            way = 1 if trade.side == "long" else -1
+            open_profit += way * (price - trade.entry_price) * trade.units * contract.point_value
+            exposure += abs(trade.units * price * contract.point_value)
+
+        cash = capital + realised - charges
+        equity = cash + open_profit
+        if equity > peak:
+            peak = equity
+        if equity < trough:
+            trough = equity
+        drawdown = equity - peak
+        run_up = equity - trough
+        points.append(
+            EquityPoint(
+                bar_index=bar.bar_index,
+                time=bar.time,
+                realised=realised,
+                charges=charges,
+                open_profit=open_profit,
+                cash=cash,
+                equity=equity,
+                exposure=exposure,
+                drawdown=drawdown,
+                drawdown_percent=ratio_of(drawdown, peak),
+                run_up=run_up,
+                run_up_percent=ratio_of(run_up, trough),
+            )
+        )
+
+    return tuple(points)
+
+
+def bars_in_market_over(trades: Sequence[Trade], equity: Sequence[EquityPoint]) -> int:
+    """How many of these bars ended with something held.
+
+    Swept rather than searched: a sorted list of the bars trades opened on, a
+    sorted list of the bars they closed on, and the running difference between how
+    many of each have gone by. That is the boundary rule ``open_on_bar`` states,
+    arrived at from the other side, and a count that disagreed with the curve
+    beside it about which bars were in the market is exactly the kind of defect a
+    reader finds by adding two of the printed figures up.
+    """
+    opens = sorted(trade.opened_on_bar for trade in trades)
+    closes = sorted(
+        trade.closed_on_bar for trade in trades if trade.closed_on_bar is not None
+    )
+
+    opened = 0
+    closed = 0
+    live = 0
+    bars = 0
+    for point in equity:
+        while opened < len(opens) and opens[opened] <= point.bar_index:
+            live += 1
+            opened += 1
+        while closed < len(closes) and closes[closed] <= point.bar_index:
+            live -= 1
+            closed += 1
+        if live > 0:
+            bars += 1
+    return bars