Module lattice 

Recombining binomial lattices, asset-class agnostic.

Every classic parameterization reduces to one recombining structure: a node after j up-moves out of i steps sits at S(i, j) = S0 * exp(j*log_up + (i-j)*log_down), with up-probability p_up — LatticeParams. The BinomialTreeType enum supplies the (log_up, log_down, p_up) triple for Cox-Ross-Rubinstein, Jarrow-Rudd, Tian, Trigeorgis, Leisen-Reimer (Peizer-Pratt method 2, strike-aware, second-order smooth convergence) and the equal-probability additive tree (Clewlow-Strickland / QuantLib’s AdditiveEQPBinomialTree).

Three engines share the parameterization:

• price_backward — the production engine: a rolling one-dimensional value array (O(n) memory, no tree materialized) with the layer spot levels rebuilt from two precomputed power tables.
• price_backward_with_greeks — the same rolling pass, additionally keeping the first two layers so the value and the tree delta/gamma/theta come from a single induction.
• price_with_diagnostics — the debug engine: keeps the full spot and value trees, records the early-exercise boundary per layer, tree Greeks read off the first layers, and wall-clock time.

convergence_study prices across a ladder of step counts (with per-point timing) to expose each scheme’s convergence behavior — CRR oscillates at first order, Leisen-Reimer converges smoothly at second.

Payoffs and early exercise enter as closures, so the same lattice prices equity payoffs today and other asset classes later.

Structs

ConvergencePoint

One rung of a convergence ladder.

LatticeConfig

Lattice engine configuration carried by an instrument.

LatticeDiagnostics

Everything the debug lattice records beyond the price.

LatticeParams

The general recombining step: S(i, j) = S0 e^{j lu + (i-j) ld}, up with probability p_up.

LatticeSolution

Value and the tree Greeks read off a single backward pass.

TermLattice

A recombining binomial lattice under time-dependent parameters: term structures of rates, carry and volatility applied directly on the tree.

TrinomialBranch

One node’s branching: the middle child’s absolute index on the next layer and the probabilities onto (target+1, target, target-1).

TrinomialLattice

A recombining trinomial lattice over the integer state grid x_j = j * dx (the caller maps j to its own state, e.g. r(i, j) = alpha_i + j * dx for a fitted short-rate tree).

Enums

BinomialTreeType

The lattice parameterization: how (u, d, p) are chosen.

Functions

convergence_study

Price the same contract across a ladder of step counts on the optimized engine, timing each rung — the raw material for studying a scheme’s convergence order and oscillation.

diffusion_branching

Moment-matched branching for a constant-coefficient diffusion dx_t = nu dt + sigma dW on spacing dx (Boyle / Kamrad-Ritchken: dx = sigma sqrt(3 dt) gives the classic 1/6, 2/3, 1/6 weights at zero drift). Same rule at every node — the equity-style tree.

hull_white_branching

Hull-White branching for the mean-reverting state dx_t = -a x_t dt + sigma dW with dx = sigma sqrt(3 dt): standard branching in the interior, switching to downward branching at +j_cap and upward at -j_cap so probabilities stay positive (Hull’s j_max = ceil(0.184 / (a dt)) is the usual cap).

hull_white_j_cap

Hull’s recommended clamp for hull_white_branching.

price_backward

Backward induction on a rolling one-dimensional array: O(n) memory, O(n^2) work, spot levels rebuilt from two precomputed power tables.

price_backward_with_greeks

The same rolling-array induction as price_backward (identical price, bit for bit) that additionally keeps the first two layers, so the value and the tree delta/gamma/theta come out of one pass — no re-pricing per Greek.

price_with_diagnostics

The debug engine: same induction as price_backward but keeping every layer, the exercise boundary, tree Greeks and timing.