Module calibration

Expand description

Curve calibration: recovering pillars from quoted instruments.

§Why this layer sits above instruments

A calibration prices instruments to recover curve parameters, so it depends on everything a valuation depends on. Filed inside curves, it would make curves reach up into instruments, cashflows and analytics. Hoisting it here is what makes the layer graph acyclic.

§The mode is the whole point

A sequential calibration solves one unknown against one residual, over and over. That is the exact shape forward mode is for: seed the pillar being solved, price once, and the derivative comes back beside the value.

Reverse mode would record the entire swap-pricing forward pass onto a tape at each Newton step, sweep the whole tape backwards, and read one scalar off the result — a full reverse pass to recover a single one-input, one-output derivative, on a tape that grows with every pillar.

Here nothing is recorded at all. The tests assert that as a statement count, not as a claim.

§A helper is a rung

A calibration instrument is here a Rung: a real instrument, priced by the pricer a trade uses, with its quote declared and verified at the solve. The template-dated builders — deposit_rung, fra_rung, future_rung, par_rungs, tenor_basis_rung, cross_currency_rungs, bond_rung in crate::products — are the helper family, and calibrate_curve_helpers is the one verb that takes a list of them: it groups the rungs by the curve each solves, read off the instrument’s declared risk factors, solves each group as a ladder or jointly where groups read each other, refuses two rungs on one pillar by name, and pins every curve with its provenance. calibrate_recipe is that verb on a recipe’s templates filled from a quote sheet — a swaps-only sheet is the one-template case.

Modules§

sabr: SABR calibration from a grid rate smile: one slice per smiled (expiry, tenor) node, and the record each fit keeps so its parameter risk can be read back onto the quotes that built it.

Structs§

Calibrated: A calibrated curve, and how it was reached.
CalibratedBaseCorrelation: A base-correlation curve solved from a tranche capital structure: one correlation per detachment and one solve record per tranche.
CalibratedDensity: A survival curve solved in default density: one density per pillar, the node at the reference date reading the first pillar’s, one solve record per pillar, and the ladder the curve reprices.
CalibratedInflation: A calibrated inflation curve, and what each pillar’s solve cost.
CalibratedSurvival: A survival curve solved from a ladder of credit default swaps: the ISDA piecewise-flat-hazard curve and one solve record per pillar.
CalibrationOptions: How a par curve is solved: the rung notional, the interpolation scheme and the tolerance — every knob of calibrate, gathered so the one-step verb and a caller who wants the defaults name none of them.
CapQuote: A term cap quote: the cap from the strip’s effective date to termination, quoted as one flat volatility.
CollateralCurves 🔒: The fixed curves of a collateral ladder: the pay leg’s discount and both legs’ projections.
CreditLadder 🔒: What a credit ladder was solved against — the part of its inputs its read back needs, whichever family it solved.
CurveProvenance: The ladder a curve was calibrated from: what it reprices, and how its pillars move when those quotes do.
CurveRefit: The inputs a rate curve was calibrated from, less the published data a market carries: enough to solve the same ladder again — at the same quotes, or at quotes a scenario moved. The rate twin of SurvivalRefit.
HelperGroup 🔒: The helpers that solve one curve.
HelperSolve: One curve the helper verb solved: the roles it was pinned under and, where it was solved as a ladder of its own, the solve — its curve, records and par-quote provenance. A curve solved jointly with another carries no ladder of its own, and ladder is None.
JointCalibration: Curves solved together, each under its role, and what the solve cost.
JointCurve: One curve of a joint solve: the roles it is pinned under — a discount key, a projection index, or both, as a self-discounting overnight curve is — and the rungs whose pillars are its nodes.
LiftedForm 🔒: A Form’s fixed curves, lifted.
PillarSolve: The result of one pillar’s solve, for a caller that wants to see the work.
ProvenanceEntry: One rung of the ladder that calibrated a curve, kept so the curve can say what it reprices.
ProvenanceShape: A ladder whose ∂z/∂q does not have one row and one column per rung.
QuoteSheet: A quote sheet as a desk reads it: entries in sheet order, each a template, a locator and a value. The sheet is the grid — a recipe says which templates build the curve, and the sheet says where.
Rung: One rung of a calibration ladder: an instrument, the pillar it determines, and the kind of quote it was built at.
SheetEntry: One quote on a sheet: the template it is quoted on, where it sits, and the number — a rate for a deposit or a swap, a price for a future, an outright for an FX swap, a spread for a basis swap.
SmoothedCalibration: A discount curve fitted globally, trading repricing error for smoothness of the pillar log discount factors — and saying so: it carries no provenance, because it reprices no rung exactly.
SolvedPillar 🔒: One pillar’s Newton solve: x, the steps it took, and the residual it left.
Stores 🔒: The lifted stores a pass prices against, borrowed by every valuation.
SurvivalRefit: The inputs a survival curve was calibrated from, less the recovery and the published data a market carries: enough to solve the same ladder again.
Tolerance: How hard the solver tries.

Enums§

BondRungError: Why a bond could not be made a rung.
CalibrationError: A calibration that did not produce a curve.
Form 🔒: Which curve a ladder solves, and where the rest of the view comes from.
HelperForm 🔒: How a group of helpers solves: where the curve under solve sits, and what it reads.
JacobianEngine: Which engine built a ladder’s ∂q/∂z.
Provenance: What a converged solve knows about the ladder behind its curve.
QuoteKind: The two are not interchangeable and the difference is not cosmetic: a par rung’s instrument is worth nothing at its quote, while a priced rung’s is worth its quote. The solver’s target, the Jacobian’s read, and the check that a rung reprices at what it declared all follow from this one choice, so they cannot disagree.
RecipeQuoteError: Why a quote sheet could not be bound to a recipe.
RefitForm: The form a rate ladder was solved in, with the curves it held fixed — the owned twin of the solve’s own form, so a refit can name it again.
Route 🔒: The engine a quote block runs in.
StripScheme: How term cap quotes are turned into caplet vols.
SurvivalFamily: The parameterisation a credit ladder solves: one segment hazard per rung (ISDA), or one default density per rung, the first segment flat.

Constants§

ADJOINT_BUDGET_BYTES 🔒: How much adjoint memory the reverse engine’s read-back may hold at once.
BISECTION_CAP 🔒: Bisection steps allowed per tranche — a bracket of width one halves to the step tolerance in fifty, and the cap is there for a residual that will not settle, not as a budget.
LANES 🔒: ∂q/∂z: rung i’s par quote against pillar j, on the solved curve.
REVERSE_FROM 🔒: The largest ladder the eight-lane engine still builds the Jacobian for.
RHO_MAX 🔒: The top of the correlation bracket: the store refuses 1.0 itself.
SEED_HAZARD 🔒: The hazard a ladder starts from when its first rung is upfront-quoted, whose quote is not a spread to triangulate from.
SEED_LEVEL 🔒: The index level a pillar starts its Newton solve from, before the previous pillar’s answer is available to re-seed it. Arbitrary but strictly positive, which is all a level has to be for the curve to build.
SEED_RECOVERY 🔒: The recovery a seed assumes when neither the contract nor the ladder states one. It shapes where Newton starts and nothing about where it stops: the solve itself prices under the contract’s or the ladder’s recovery, and a contract that needs one and finds none fails by name.
STRIP_ITERATION_CAP 🔒: Brent halves the bracket at worst; five vols to a 1e-12 step is under fifty halvings.

Functions§

adjoint_budget 🔒: The budget the reverse engine reads back under.
bond_rung: A priced rung from a quote-less bond static and a tagged market quote.
calibrate: Calibrates a discount curve so that every rung prices to zero.
calibrate_base_correlation: Calibrates a base-correlation curve to a contiguous capital structure of CDO tranches on one index — the market-standard bootstrap.
calibrate_cross_currency: Calibrates the discount curve of a cross-currency swap’s receive leg under its collateral — EUR under a USD CSA, from EUR/USD basis swaps — against a pay-leg discount curve and both legs’ projection curves already known.
calibrate_curve_helpers: Calibrates the curves a list of helpers solves and pins them into a copy of market.
calibrate_inflation: Calibrates an inflation curve to a ladder of index-quoted instruments, discounted on a curve already known.
calibrate_jointly: Solves several rate curves at once — each a JointCurve, its rungs’ pillars its nodes — by damped Newton on the stacked log discount factors.
calibrate_jointly_on: calibrate_jointly on a market that already holds curves the ladders read but do not solve — a tenor basis ladder’s base index, a term ladder’s discount pinned yesterday. The trial curves are pinned over base at each iteration; base itself is untouched and supplies the fixings and FX.
calibrate_projection_under: Calibrates an index’s projection curve from non-deliverable swaps, against the held settlement-currency discount and the held foreign curve — the local currency’s discount under the settlement collateral, which every conversion reads. calibrate_with’s solve with the foreign slot filled.
calibrate_recipe: The market with the curves its recipe for key describes solved from sheet and pinned, beside the solves — recipe_rungs_at through the helper verb.
calibrate_smoothed: Fits a discount curve to a ladder globally under scheme, minimising the rung quote residuals together with smoothness times the squared second divided difference of the log discount factor at each interior pillar.
calibrate_survival: Calibrates an ISDA survival curve to a ladder of credit default swaps, discounted on a curve already known.
calibrate_survival_density: Calibrates a default-density survival curve to a ladder of credit default swaps, discounted on a curve already known, the density linear between pillars.
calibrate_with: Calibrates a projection curve against a caller-supplied discount curve.
cap_maturity_years 🔒: When a cap’s last caplet pays, in years from the valuation date — the maturity its quote is the vol of, rolled as the schedule rolls it.
capital_structure 🔒: The shape a tranche bootstrap solves: non-empty, attaching at zero, contiguous, detachments strictly increasing to at most one, and every tranche’s recovery stated by its contract or by recovery.
caplet_nodes 🔒: One node per caplet still to fix, at its interval’s vol: the expiries and the vols, a caplet already fixed or sharing an expiry with the node before it dropped.
caplet_value 🔒: One caplet’s discounted value at vol, by the convention’s kernel.
check_credit_ladder 🔒: A credit ladder’s shape, checked before any pillar is solved: at least one rung, pillars strictly increasing from the reference date, and a market recovery where a contract needs one.
check_joint 🔒: The shape a joint solve needs: at least one curve, each under discount or projection roles, with rungs whose pillars strictly increase and whose values are read today.
check_pillars_ascend: Every rung’s pillar strictly after the previous one’s, and the first after the reference date.
check_quotes 🔒: The two things a quote block must satisfy before it becomes a ladder: every rung moves under its own pillar, and every rung reads back the quote it was declared at.
collateral_ladder_indices 🔒: The pay and receive projection indices a collateral ladder’s rungs declare, read off any rung that names one, and the check that every rung solves the same collateral key.
curve_from 🔒: A piecewise curve over dates with the given log discount factors, read under scheme.
discount_quotes_in 🔒: The discount form’s pass in mode R: the stores lifted once, then run handed the closure that values every rung on the curve seeded describes.
fx_swap_sheet_rung 🔒: A sheet entry on an FX-swap template: the outright at a tenor, in the template’s pair, against the pair’s spot in the market’s FX store.
held_curve 🔒: The held curve under id, or the market’s own missing-curve refusal.
helper_group_of 🔒: Which curve rung solves, and how, read off the roles its instrument declares and the family of the index it projects.
helper_groups 🔒: The rungs grouped by the curve they solve, each group’s rungs in pillar order and checked for overlaps.
inflation_from 🔒: The inflation curve levels describes, in the shape the solve substitutes parameters into.
inflation_quote_block 🔒: Every rung’s quote read back on the inflation curve levels describes, and its derivative with respect to every node level — the inflation form of the quote block, over the same lane loop.
inflation_quotes_in 🔒: The inflation form’s pass in mode R — see discount_quotes_in.
is_year_end 🔒: Whether date is a 31 December — the start of the year-end turn.
joint_curves 🔒: Each curve read off its slice of the stacked log discount factors.
joint_market 🔒: base pinning each trial curve under every role it was given — on top of whatever base already holds, so a ladder may read a held curve the solve does not move.
joint_seed 🔒: The stacked log discount factors a joint solve starts from: each curve solved sequentially in the order given — a discount curve self-discounting, a projection curve against the first discount curve — where that succeeds, and flat at its first rung’s quote (as a continuously compounded rate) where it does not.
ladder_provenance 🔒: ∂q/∂z inverted into the ladder a curve carries: ∂z/∂q row-major with one entry per rung.
names 🔒: Whether recipe names template anywhere: as a discount segment, an own-strip projection, or a window it fixes.
newton_on_pillar 🔒: The damped Newton solve itself, over whatever one pillar substitutes into a view.
newton_pillar 🔒: Newton on pillar j of the curve over dates with parameters params, starting from params[j], every other pillar held.
par_quote_jacobian 🔒
pin_roles 🔒: market with curve pinned under every one of roles.
policy_rung 🔒: A sheet entry on the meeting template: a window opening on a year end is the turn, quoted as the simple forward over it; any other window is a policy window; a decision date is the window that decision opens, truncated at spot; anything else is refused by shape.
policy_spot 🔒: The spot date a policy window is truncated to: the par-swap template’s spot where the recipe has one, two business days on the meeting template’s calendar otherwise.
quote_block 🔒
quotes_in_reverse 🔒: The reverse engine: every rung’s quote recorded once on the thread’s calibration tape, the parameters registered as inputs and the quotes as outputs, and dq read back by vector sweeps over that one recording — width directions per sweep, as many sweeps as budget makes necessary. Returns (read_back, dq, Reverse { sweeps }).
quotes_over_lanes 🔒: The block loop every quote block shares: eight forward lanes at a time, each seeding one parameter, quotes_for reading every rung’s quote in whatever view the seeded parameters build. Returns (read_back, dq): each rung’s quote at the parameters, and dq[i][j] = ∂qᵢ/∂paramⱼ.
reads_a_solved_curve 🔒: Whether group reads a curve another group in groups solves.
reads_one 🔒: Whether reader reads a curve solved pins.
recipe_rungs_at: The helpers sheet binds to under market’s effective recipe for key, each on notional — rungs_for on the recipe the market resolves.
requoted_rungs 🔒: Every rung at its quote in quotes, in order.
route 🔒: Which engine builds the Jacobian of an n-pillar ladder on this thread.
rung_quotes 🔒: Every rung’s quote in view: the quantity its sensitivity is with respect to, which must be the one the solve drove.
rungs_for: The rungs a sheet binds to a recipe: one per entry, dispatched on the template’s family and the locator’s shape; a template the recipe does not name is refused by name, a shape the template cannot take by shape, and a window the recipe fixes must be on the sheet. The market supplies the as-of date, the FX spots a cross segment reads, and the bank schedules that name a policy window’s decision.
seed_hazard 🔒: Where the first pillar’s Newton starts: the credit triangle for a spread quote, under the recovery the rung will price with; a flat guess for an upfront quote, whose number is not a spread.
shape_refusal 🔒: A refusal for a locator shape template cannot take.
sheet_rung 🔒: One sheet entry’s rung, dispatched on the template’s family and the locator’s shape.
slot 🔒: A registered handle’s tape slot, as an index.
solve_helper_group 🔒: One group solved against the curves market holds: the curve to pin and, where it was a ladder of its own, the solve.
solve_ladder 🔒: The one ladder loop behind both forms.
strip_caplet_smile: Caplet vols from a quoted cap matrix: one smiled surface in which each strike column is the caplet ladder stripped at that strike.
strip_caplet_vols: Caplet vols from term cap quotes: the surface under which every quoted cap reprices, exactly, at its own strike.
strip_interval 🔒: The vol of one new interval: the earlier caplets valued at their stripped vols (settled), the interval’s at the unknown, the sum reaching target.
strip_ladder 🔒: One strike’s caplet ladder: the expiry nodes still to fix and the vol at each, under the named scheme.
strip_overnight_caplet_vols: Caplet vols from term cap quotes on an overnight index at frequency: the ladder strip_caplet_vols strips, over caps whose coupons compound the index’s daily prints.
strip_per_caplet 🔒: The caplet-by-caplet strip: one caplet at a time, the cap ending at each caplet’s maturity priced at the term vol interpolated there, the earlier caplets at their stripped vols.
strip_refusal 🔒
surface_or_refusal 🔒: A built surface, or the market-data refusal it reports.
survival_from 🔒: The survival curve hazards describes, in the shape the solve substitutes parameters into.
survival_quote_block 🔒: Every rung’s quote read back on the survival curve hazards describes, and its derivative with respect to every segment hazard — the credit form of the quote block, over the same lane loop.
survival_quotes_in 🔒: The survival form’s pass in mode R — see discount_quotes_in.
sweeps_exhausted 🔒: A fit still moving when its sweeps ran out, named by the rung left worst off (or fallback, for a ladder with no solves to name).
term_vol_at 🔒: The term vol curve read at t: linear between quoted maturities, the end segments extended — a term vol surface in time. One quote is a flat curve.
term_vol_nodes 🔒: The term vol curve’s nodes: each quote at the time its cap actually matures — the last caplet’s payment, rolled as the schedule rolls it — so the cap ending there reads its own quote exactly.
view_over 🔒: The view a rung is valued in, with under_solve in the role the ladder’s form gives it: the discount curve for a self-discounting solve, the projection curve over a fixed discount otherwise.
window_dates 🔒: The dates a window locator’s ends stand for.
with_calibration_tape 🔒: Runs f on this thread’s calibration tape and adjoint buffer: created on the first call, kept at the largest capacity either ever reached, the tape cleared on every recording. Its own rather than the trading layer’s — that one is the tape a risk pass is recording on, and a calibration inside a risk pass has already been routed away from here.
xccy_recipe_rungs 🔒

Type Aliases§

QuoteBlock 🔒: Every rung’s quote read back on the curve params describes, and its derivative with respect to every log discount factor: (read_back, dq), dq[i][j] = ∂qᵢ/∂zⱼ, from eight-lane forward-mode passes.
QuotesFor 🔒: The pass a quote block hands its engine: every rung’s quote on whatever view the seeded parameters build, in the engine’s mode.