Architecture

Recruiter-facing systems view

option_pricing is organized as a layered quant library: typed public routes enter a reviewable quant core, and diagnostics stay downstream where they can inspect the same workflow that produces the proof pages.

The page walks the same stack as a workflow and safeguards story: repair, smooth handoff, local-vol extraction, PDE validation, and published proof outputs.

Recruiter-Facing System Picture

The architecture contract is simple: keep the public surface readable, keep the quant checkpoints explicit, and keep reviewer-facing evidence outside the engines so it can inspect the workflow rather than disappear inside it.

The main systems graphic centers the reviewable workflow itself: public routes feed into repair, smooth handoff, local-vol extraction, and PDE validation, while proof outputs remain downstream where they can expose the safeguards without becoming hidden engine dependencies.

Public surface Typed routes stay readable and library-first.

Workflow spine Repair, handoff, local-vol, and PDE remain explicit checkpoints.

Proof edge Diagnostics stay downstream so the evidence can stay rich without polluting the engines.

Workflow And Safeguards Story

The technical story is the five checkpoints below: each one answers a different reviewer question before the workflow is allowed to move forward.

Why this matters

The architecture is not trying to hide complexity. It is trying to put complexity where it can be inspected. The proof workflow becomes credible because each transition exposes the next failure mode before the next layer starts relying on it.

1. Repair the raw surface first

   Start with quotes, smiles, and SVI repair rather than jumping straight into local vol.

   • VolSurface, calibrate_svi(...), and no-arbitrage diagnostics keep slice quality visible.
   • The reviewer can inspect quoted data, repaired slices, and fit stress before any time-smoothing story begins.

2. Make the smooth handoff explicit

   The handoff is a design decision, not a hidden interpolation detail.

   • ESSVINodalSurface preserves the exact calibrated nodes.
   • project_essvi_nodes(...) and ESSVISmoothedSurface create the Dupire-oriented smooth surface only after explicit validation.
   • validate_essvi_nodes(...) and validate_essvi_continuous(...) separate nodal validity from continuous-surface admissibility.

3. Extract local vol with failure visibility

   The Dupire stage stays inspectable instead of turning into a silent derivative black box.

   • LocalVolSurface.from_implied(...) keeps the handoff object visible.
   • Invalid masks, denominator checks, and curvature diagnostics preserve the reason why extraction succeeds or fails instead of collapsing it into one opaque output.

4. Validate the PDE wiring

   The numerical stage exposes domain, method, and payoff-remedy choices instead of burying them in one opaque engine.

   • bs_pde_wiring, local_vol_pde_wiring, GridConfig, ICRemedy, and RannacherCN1D make the solver choices reviewable.
   • The final question at this stage is not whether the stack runs, but whether it reprices, localizes error, and behaves sensibly as the grid changes.

5. Publish proof outputs and diagnostics

   The workflow only closes when the evidence is visible to a reviewer rather than trapped inside the implementation.

   • Repricing grids, convergence sweeps, benchmark artifacts, and pytest -q demos --nbmake are all downstream of the same workflow.
   • That is what lets the docs, tests, and performance page tell one coherent story.

The supporting workflow view stays quieter than the main systems graphic: it traces the same path from repaired surface to local-vol extraction, PDE solve, and downstream diagnostics without becoming a second competing hero.

Public Routes Into The Stack

The package exposes several entry styles, but they are not equal in purpose. The point is to keep the default public path readable without hiding the more explicit routes needed for quant workflows.

Route	Use it when	Representative objects and functions
Instrument-based	You want the recommended typed public workflow	VanillaOption, bs_price_instrument, mc_price_instrument, binom_price_instrument
Flat-input	You want compact scripts or method comparisons	PricingInputs, bs_price, mc_price, binom_price
Curves-first	You want discounting and forwards to stay explicit	PricingContext, DiscountCurve, ForwardCurve
Volatility namespace	You are working on surfaces, eSSVI, local vol, or the proof path	VolSurface, ESSVINodalSurface, ESSVISmoothedSurface, LocalVolSurface

Confidence Model

Confidence comes from layered safeguards rather than one final integration test. Each stage has its own failure mode, its own guardrails, and its own published evidence.

Stage	Main guardrails	Evidence surfaced to the reviewer
Surface construction and repair	Strike ordering, forward positivity, no-arbitrage proxies, fit diagnostics	Quoted-versus-repaired plots, slice stress, no-arb summaries
Smooth eSSVI handoff	Constraint checks, seam inspection, nodal vs continuous validation	Seam-jump table, projection diagnostics, invalid-count summary
Local-vol extraction	Invalid masks, reason codes, denominator and curvature checks	Gatheral and Dupire reports, heatmaps, difference views
PDE solve	Domain bounds, boundary handling, remedy choice, convergence sweeps	Repricing grids, convergence plots, digital-remedy benchmarks
Proof outputs and CI loop	Notebook execution plus committed benchmark artifacts	Proof pages, benchmark page, CI-executed demos

Extension And Maintenance

Extension points

• Add new pricers under pricers/ without rewriting the surface or diagnostics layers.
• Add new volatility models under vol/ without changing the public entry patterns.
• Add new PDE methods by extending the numerical factory layer instead of hard-coding them into one workflow.
• Add new diagnostics downstream of the pricing stack so evidence stays rich without creating reverse dependencies.

Maintenance notes

• The generic SVI-derived local-vol path remains demo-grade for Dupire because its time-direction behavior is only piecewise smooth.
• Diagnostics depend on optional plotting and comparison tooling in places, so some cross-checks remain conditional.
• The docs should continue steering Dupire-oriented readers toward the smooth eSSVI handoff rather than implying all surface paths are equally defensible.