Monte Carlo path generation (pathGenerator/sobolPathGenerator/next/asset) plus lsmRegress, a standalone Longstaff-Schwartz early-exercise regression primitive.

Custom early exercise with a Haskell payoff

lsmRegress lets a Haskell-defined payoff drive early exercise, something no bound pricing engine offers: every early-exercise engine in QuantLib.PricingEngine (e.g. mcAmericanEngine) computes its payoff entirely on the C++ side against a bound Payoff. lsmRegress is pure regression -- it never sees a payoff at all, so it works for any underlying-state-dependent early-exercise payoff, not just a vanilla put/call. The pattern, worked in full in test/example/QuantLib/Example/AmericanLSM.hs:

1. Draw two path sets with pathGenerator: a calibration set used only to fit each date's regression, and a separate pricing set evaluated against the frozen fit. Splitting the sets avoids the in-sample bias a single-pass fit-and-price would have (the same reason mcAmericanEngine exposes its own nCalibrationSamples parameter). Use a fixed nonzero seed for each -- seed 0 means "seed from entropy" for PseudoRandom.
2. Read out the state at every exercise date, across all paths, with asset (or assetAt), and transpose (transpose) into one state list per exercise date.

3. Walk exercise dates *strictly backward*. At each date:

   • discount both the calibration and pricing cashflow vectors by the one-step discount factor (discount(t[i+1]) / discount(t[i]) from the underlying yield curve);
   • compute the Haskell payoff at this date for every path in both sets;
   • restrict the regression's fit inputs to *in-the-money calibration paths only* (fitStates/fitTargets below);
   • call lsmRegress twice against that one fit -- once evaluating at the calibration states (to keep the backward recursion's own targets self-consistent), once at the pricing states (the actual out-of-sample continuation-value estimate);
   • exercise wherever payoff > continuationValue (max(exercise, continuation)), on each path set independently.
4. The pricing set's cashflows, discounted all the way back and averaged, are the estimated price. Never evaluate the fit on the calibration set's own state for the reported price -- that reintroduces the in-sample bias step 1 split the paths to avoid.

A rough sketch (see the full example for discounting, ITM filtering, and the backward recursion itself):

step df calibS priceS calibCF priceCF = do
  let calibTargets = map (* df) calibCF  -- discount to this date
      (fitStates, fitTargets) = -- ITM calibration paths only
        unzip $ filter (inTheMoney . fst) $ zip calibS calibTargets
  contCalib <- lsmRegress Monomial order fitStates fitTargets calibS
  contPrice <- lsmRegress Monomial order fitStates fitTargets priceS
  -- exercise wherever payoff > continuation, on each path set
  ...

Validated in the example against both mcAmericanEngine pricing the equivalent bound vanilla option (same process/grid/seed) and the published Longstaff-Schwartz (2001) reference value for the same benchmark fixture.

The same pattern extends to a Haskell-defined basket payoff (several correlated underlyings) via lsmRegressMulti / lsmBasisSize in place of lsmRegress: read each exercise date's state for every underlying (still with asset/assetAt, once per underlying) into a Matrix of one row per path, and guard the ITM-fit-size check with lsmBasisSize instead of the basis order -- the multi-asset basis has combinatorially many more terms than the scalar case.

test/example/QuantLib/Example/HaskellLSM.hs benchmarks lsmRegress against the same backward induction with the per-date regression reimplemented from scratch in plain Haskell (QuantLib used only for path generation) -- a worked illustration of why this module exposes the regression as a batched primitive instead of leaving callers to reinvent it.

Finite-difference PDE solving

This module also binds a full-grid finite-difference (FDM) driver, built up across two related issues (custom step-condition/operator hooks, then custom inner-value calculators) and spread across several functions with no single overview until now. Worked in full in test/example/QuantLib/Example/Fdm.hs -- every snippet below is a trimmed extract from that file; read it end to end for the full picture (discounting, fixtures, imports).

In one sentence, for anyone new to FDM pricing: instead of an integral (Monte Carlo) or a closed-form formula (an analytic*Engine), you discretize the underlying's state space (e.g. log-spot) into a grid of points, put the option's payoff on the grid at maturity, and step it backward to today, solving a small local linear system at each timestep. Reach for it when you need American/Bermudan-style early exercise (a plain Monte Carlo run can't do backward induction the way a grid can) or a process/payoff with no closed-form price. If a bound analytic*Engine or mc*Engine already covers your case (see QuantLib.PricingEngine), prefer that instead -- it's simpler, and this module's own examples validate their FDM results against exactly those engines.

Walkthrough: which function do I actually want?

Start here rather than at the reference list below -- picking the right entry point up front avoids reading five functions' haddock only to discover a sixth was the one you needed.

"I have a grid already, just roll it back"

fdmRollback. Supply the grid as a plain [Double] (one value per state, at maturity) plus three Haskell closures describing the PDE operator, and get the same grid rolled back to today -- no mesher, no FdmInnerValueCalculator, the simplest possible entry point:

let grid0 = map (\x -> max (exp x - strike) 0) xs   -- payoff at maturity, one value per grid point
fdmEuro <- fdmRollback 1 applyFn applyDirFn solveFn Nothing [] Douglas grid0 tMat 0 nSteps 0

"...and I need early exercise"

the same fdmRollback call, plus a step condition: a t -> [Double] -> [Double] closure called once per outer timestep with the whole current grid, returning it clamped to whatever the early-exercise rule requires:

let stepCond _t u = zipWith max u grid0   -- American: value can never fall below intrinsic
fdmAmerican <- fdmRollback 1 applyFn applyDirFn solveFn (Just stepCond) stepTimes Douglas grid0 tMat 0 nSteps 0

"I'd rather not hand-build the initial grid myself"

fdmSolve -- fdmRollback's sibling. Same operator/step-condition/scheme machinery, but the initial condition comes from an FdmMesher plus an FdmInnerValueCalculator evaluated at each node, instead of a grid you assembled by hand. Worth it once the mesher is doing real work (e.g. concentrating points near a strike or barrier) rather than just wrapping a list you already had:

mesh1d <- predefined1dMesher xs
mesher <- fdmMesherComposite [mesh1d]
let ivFn _t loc = case loc of [x] -> intrinsicAt x; _ -> error "expected a 1D location"
withCustomFdmInnerValueCalculator mesher ivFn ivFn $ \calc ->
  fdmSolve mesher calc 1 applyFn applyDirFn solveFn Nothing [] Douglas tMat 0 nSteps 0

"my payoff is a standard vanilla/log payoff, I don't want a per-node callback"

skip withCustomFdmInnerValueCalculator and reach for one of the native calculators instead -- QuantLib's own built-in FdmInnerValueCalculator subclasses, bound directly so pricing a plain payoff doesn't pay a Haskell round-trip per grid node:

logCalc <- fdmLogInnerValue payoff mesher 0        -- striked payoff on a log-spot grid
fdmLogEuro <- fdmSolve mesher logCalc 1 applyFn applyDirFn solveFn Nothing [] Douglas tMat 0 nSteps 0

fdmZeroInnerValue (always 0), fdmCellAveragingInnerValue/withCustomCellAveragingInnerValue (identity or custom gridMapping), and fdmLogInnerValue (gridMapping = exp, the common case on a log-spot grid) round out the set -- see the reference entries below for the exact cell-averaging-vs-point-evaluation contract each one has. Reach for withCustomFdmInnerValueCalculator only once none of these fit your payoff shape.

"my payoff depends on more than one underlying"

build one Fdm1dMesher per underlying and combine them with fdmMesherComposite; fdmLogBasketInnerValue takes a basket payoff (e.g. Max, see QuantLib.Instrument.Option) evaluated across all dimensions at once:

basketMesher <- fdmMesherComposite [mesh1d, mesh1d]   -- two correlated log-spot dimensions
basketCalc <- fdmLogBasketInnerValue (Max payoff) basketMesher
val <- fdmAvgInnerValue basketCalc basketMesher [i, j] tMat   -- inspect one node directly

"I want to price a swap/swaption under a calibrated short-rate model"

the most specialized entry points here: fdmAffineG2ModelSwapInnerValue/fdmAffineHullWhiteModelSwapInnerValue drive the same calculator fdG2SwaptionEngine/fdHullWhiteSwaptionEngine already use internally. Reach for these directly only when composing your own custom FDM pipeline around this calculator; if a plain Bermudan-swaption NPV is all you need, prefer those two already-bound black-box engines from QuantLib.PricingEngine instead.

"I just want one node's value, no PDE solve"

fdmInnerValue/fdmAvgInnerValue evaluate any bound calculator -- custom or native -- at a single mesher node directly, without assembling a whole fdmSolve. Handy as a sanity check while developing (as Fdm.hs's own tests do throughout), or whenever a single point's intrinsic value is all you actually need.

Technical reference

The terse version of the above, for a reader who already knows the vocabulary and wants the exact contract rather than the walkthrough's prose.

Rolling a grid back

fdmRollback takes a precomputed initial grid (a plain [Double]) and rolls it back through time via three Haskell-defined operator callbacks (withFdmApply et al.) plus an optional step condition (e.g. American/Bermudan early exercise). These callbacks cross the language boundary once per outer timestep, over the whole grid. fdmSolve is the sibling that instead derives its own initial grid from a mesher and an FdmInnerValueCalculator (below), reusing the same operator/step-condition machinery.

Building a grid

Fdm1dMeshers (predefined1dMesher, uniform1dMesher, concentrating1dMesher, fdmBlackScholesMesher, and the other process-specific meshers) each describe one PDE dimension; fdmMesherComposite combines one or more into the multi-dimensional FdmMesher fdmSolve and FdmInnerValueCalculator operate over. fdmMesherLocations reads a dimension's real-valued node locations back out, e.g. to map a flat result array back to coordinates. gluedMesher splices two Fdm1dMeshers end to end (e.g. a fine mesh near a barrier glued to a coarse one further out) -- their ranges must already be ordered and non-overlapping, and a shared boundary point is deduplicated automatically.

Custom inner values, fully general

withCustomFdmInnerValueCalculator wraps a Haskell t -> location -> value pair of functions as an FdmInnerValueCalculator. Unlike every callback above, this one crosses the language boundary once per grid node -- there is no batched shape for it anywhere in QuantLib or QuantLib-SWIG, so the real per-call cost is accepted, matching QuantLib-SWIG's own FdmInnerValueCalculatorDelegate precedent. Because the two callbacks are stored inside the returned calculator and invoked again on every later fdmSolve/fdmInnerValue call (not just during construction), the calculator is only valid inside this continuation -- it cannot be built with a plain IO FdmInnerValueCalculator smart constructor the way the native calculators below can.

Custom inner values, native

QuantLib's own concrete FdmInnerValueCalculator subclasses are bound directly, for the common cases that don't need a per-node Haskell callback at all: fdmZeroInnerValue (always 0), fdmCellAveragingInnerValue/fdmLogInnerValue (a payoff cell-averaged -- Simpson-integrated across each grid cell, not just evaluated at its center -- with an identity or exp value mapping respectively), and fdmLogBasketInnerValue (the multi-asset counterpart, one exp mapping per dimension). These hold no Haskell callback, so they're plain IO FdmInnerValueCalculator constructors -- except withCustomCellAveragingInnerValue, the one native constructor that does take an explicit gridMapping callback, which needs the same continuation treatment as the fully custom case above. fdmAffineG2ModelSwapInnerValue/fdmAffineHullWhiteModelSwapInnerValue price a swap under a calibrated G2/HullWhite model directly -- the same calculator fdG2SwaptionEngine/fdHullWhiteSwaptionEngine use internally.

Inspecting a calculator directly

fdmInnerValue/fdmAvgInnerValue evaluate any bound calculator (custom or native) at a single mesher node, without assembling a whole fdmSolve -- useful for a targeted self-consistency check, as Fdm.hs's own tests do throughout.

What's deliberately not bound: operators, schemes, boundary conditions

QuantLib-SWIG also exposes QuantLib's concrete FdmLinearOpComposite subclasses (FdmBlackScholesOp, FdmHestonOp, FdmG2Op, ...), its scheme objects (DouglasScheme, CraigSneydScheme, HundsdorferScheme, ...), and its FdmBoundaryCondition family as real C++ objects. hasquant does not mirror these, and won't by default -- it's a design boundary already crossed once, not a gap.

fdmRollback/fdmSolve take the operator, the implicit-solve step, and the scheme all as Haskell closures instead (applyFn/applyDirFn/solveFn above). That's the same "coarsen the language-boundary crossing" call already made for step conditions: bind the reusable numerical primitive (rollback through a fixed timestep, of an arbitrary tridiagonal/multi-dimensional operator) and let Haskell drive it, rather than bind every concrete operator/scheme QuantLib ships as its own object. test/example/QuantLib/Example/Fdm.hs's hand-rolled operatorBands/applyOp is the replacement for FdmBlackScholesOp + DouglasScheme, not a stand-in waiting for those to get bound -- pricing a new payoff/process combination here means writing its operator once in Haskell, not calling into fifteen QuantLib operator classes one by one.

Binding the operator/scheme family as objects would add a second, redundant way to drive the same fdmSolve/fdmRollback backbone, without extending what's actually solvable -- anything a bound FdmXxxOp could do, a Haskell applyFn already can. Revisit only if a concrete need shows up that the callback shape genuinely can't express (none has, so far).