19Pricing-Library Architecture

A client asked on Friday for a price on a worst-of autocallable with memory coupons and a lookback on the knock-in: the capital is at risk if the worst performance was ever below 60% on an observation date, not only at maturity. The library had no class for it. By Monday it was priced from eleven lines of payoff script, on the same market objects, model and Monte Carlo engine as every other trade in the library, with Greeks, scenarios and batches for free. This chapter is about the architecture that makes that possible: a library in layers, whose engines do not know which products they price, and a small language in which a product is data.

19.1 The analytics library and its layers

Book 5 built one (firm.pricing, chapter 28) and froze its interface for the rest of the series: instruments are descriptions of cash flows; market data is an immutable snapshot; a model says how the market evolves; an engine computes a value for an instrument under a model on a snapshot; and every Greek, scenario and batch is one repricing function applied to bumped snapshots. The layers are the architecture: a new engine prices old instruments, a new instrument uses old engines, and a risk system (chapter 18, and Book 6’s engine) needs to know nothing but the repricing function.

19.2 Instruments, market objects, models and engines

In firm.pricing a snapshot holds the market objects and a bump makes a new snapshot with one object replaced; the Monte Carlo engine reads forwards, variances and correlations from it and generates paths from a seed fixed per instrument (common random numbers, Book 5), so that a bumped price differs from the base price by the bump alone. The script engine of this chapter reuses those paths: it is the Monte Carlo engine with the payoff taken from a script instead of from a class.

19.3 Payoff scripting

The chapter’s language (firm.payoffdsl) has what the chapter’s products need and nothing more: state variables, blocks run at the dates of named schedules, assignments, if/else, pay and stop, arithmetic and comparisons, and min, max and abs. At each date a block sees S (the first underlying’s spot), perf (the worst performance) and t. A tokenizer turns the text into tokens, a recursive-descent parser turns them into a syntax tree with an error position for anything it cannot read, and the schedule is extracted from the tree: every block’s dates, in date order, in script order on the same date.

AUTOCALL = """state missed = 0;
at all {
  if perf >= barrier { pay cpn + missed; missed = 0; }
  else { missed = missed + cpn; }
}
at calls { if perf >= trigger { pay 100; stop; } }
at last {
  if perf < protection { pay 100 * min(perf, 1); } else { pay 100; }
}"""

    def stmt(self):
        t = self.peek()
        if t.text == "if":
            self.take("if")
            cond, then = self.expr(), self.block()
            other = ()
            if self.peek("else"):
                self.take("else")
                other = (self.stmt(),) if self.peek("if") else self.block()
            return If(cond, then, other)
        if t.text == "pay":
            self.take("pay")
            e = self.expr()
            self.take(";")
            return Pay(e)
        if t.text == "stop":
            self.take("stop")
            self.take(";")
            return Stop()
        name = self.take(kind="name").text
        self.take("=")
        e = self.expr()
        self.take(";")
        return Assign(name, e)

The client’s product changes three lines: a state variable lowest, updated with lowest = min(lowest, perf) at every observation, and the maturity test on lowest instead of perf. It prices at 94.25 per 100, 1.63 below the plain autocallable’s 95.88: the lookback knock-in triggers on paths that dip below 60% and recover.

19.4 Two ways to evaluate a script

The simplest evaluator walks the syntax tree once per path and per event, with scalar values: an interpreter. It is easy to trust and slow. The compiled evaluator walks the tree once per event with arrays over all paths: every statement runs under a mask of the paths it applies to, an if splits the mask, a pay adds under it, a stop removes paths from the living set (Listing 19.3). The two give the same numbers to the last digit (the tests compare them); the compiled one is 19 to 34 times faster (Figure 19.3).

def compile_program(program: Program):
    """The same semantics on all paths at once: each statement under a mask of its paths."""

    def block(stmts, env, mask, pay, alive):
        for s in stmts:
            live = mask & alive
            if isinstance(s, Assign):
                old = env[s.name] if s.name in env else 0.0
                env[s.name] = np.where(live, _eval(s.expr, env), old)
            elif isinstance(s, Pay):
                pay += np.where(live, _eval(s.expr, env), 0.0)
            elif isinstance(s, Stop):
                alive &= ~live
            else:
                c = np.asarray(_eval(s.cond, env), bool)
                block(s.then, env, live & c, pay, alive)
                block(s.other, env, live & ~c, pay, alive)

    def run(perf, spot, events, times, dfs, params) -> np.ndarray:
        n = perf.shape[0]
        env = {k: np.full(n, float(v)) for k, v in params.items()}
        for name, e in program.states:
            env[name] = np.broadcast_to(np.asarray(_eval(e, env), float), (n,)).copy()
        pv, alive = np.zeros(n), np.ones(n, bool)
        for j, k in events:
            env.update(S=spot[:, j], perf=perf[:, j], t=np.full(n, times[j]))
            pay = np.zeros(n)
            block(program.events[k][1], env, np.ones(n, bool), pay, alive)
            pv += pay * dfs[j]
        return pv

    return run

The script engine is registered in the library like any engine (Listing 19.4): it parses the script, extracts the schedule, asks the Monte Carlo engine for paths on the schedule’s dates with the instrument’s seed, and evaluates. Because the seed depends only on the instrument’s identifier, a script with the same identifier as a library instrument sees the same paths.

class ScriptEngine:
    n_paths: int = 100_000
    mode: str = "compiled"
    name: str = "Script"

    def supports(self, inst, model) -> bool:
        return isinstance(inst, ScriptedInstrument) and type(model) is FP.BlackScholes

    def cashflows(self, inst: ScriptedInstrument, model, md: FP.MarketData) -> np.ndarray:
        prog = parse(inst.script)
        ev = schedule(prog, dict(inst.dates))
        dates = sorted({d for d, _k in ev})
        idx = {d: j for j, d in enumerate(dates)}
        names = inst.underlyings or (inst.underlying,)
        refs = [md.spots[u] for u in names]
        mc = FP.MonteCarloEngine(n_paths=self.n_paths)
        s = mc.paths(inst, md, list(names), dates, refs, model)
        init = np.array(inst.initial or refs)
        perf = (s / init[None, None, :]).min(axis=2)
        times = np.array([md.t(d) for d in dates])
        dfs = np.array([md.df(inst.curve(md), d) for d in dates])
        events = [(idx[d], k) for d, k in ev]
        run = compile_program(prog) if self.mode == "compiled" else Interpreter(prog).run
        return inst.notional * run(perf, s[:, :, 0], events, times, dfs, dict(inst.params))

    def price(self, inst, model, md) -> float:
        return float(self.cashflows(inst, model, md).mean())

19.5 Lazy recalculation and observers

QuantLib’s LazyObject is the best-known implementation: a “framework for calculation on demand and result caching” that is both an observer and an observable. The chapter’s LazyPrice is the same idea in twenty lines (Listing 19.5): a European call observing a rate quote is computed once (11.35), the quote changes three times, and the next read recomputes once (11.59) — two calculations for four states of the market. The snapshot design of firm.pricing is the other answer to the same problem: nothing is mutable, so nothing is stale; a new snapshot is a new question. Libraries serving interactive tools favour observers; libraries serving batch risk favour snapshots.

class LazyPrice(Observable):
    """A price marked stale when an input changes, recomputed only when it is asked for."""

    def __init__(self, compute, *inputs):
        super().__init__()
        self.compute, self.inputs = compute, inputs
        self.cached, self.stale, self.calculations = None, True, 0
        for q in inputs:
            q.register(self)

    def update(self) -> None:
        if not self.stale:
            self.stale = True
            self.notify()                   # observers of this price are stale too

    @property
    def value(self) -> float:
        if self.stale:
            self.cached = self.compute(*(q.value for q in self.inputs))
            self.calculations += 1
            self.stale = False
        return self.cached

19.6 Bindings to other languages

A library written once is called from many places: Python research, a C++ pricing service, a spreadsheet on a trader’s desk. Chapter 9 measured what a binding costs per call; for a library the lesson is to bind at the level of whole requests — a batch of trades, a snapshot — never at the level of an operation. Book 5’s library has C++20 and Rust twins of its core, tested against the Python reference on the same inputs; a payoff script is portable by construction, since it is text that any implementation of the language can price, which is why scripts travel between front-office tools, risk systems and the canonical trade model of chapter 21 more easily than classes do.

19.7 Tutorial: a language, an engine, five products

19.8 Build: the payoff language

19.9 Exercises

19.10 Problem: Priced by Monday

19.11 Interview questions