Add PiecewiseBlackVarianceSurface for ragged vol grids

[pandashark]

Closes #2173.

New BlackVarianceTermStructure subclass that builds a Black volatility surface from a vector of SmileSection objects, one per tenor. Each tenor keeps its own strike grid, so the surface handles ragged (non-rectangular) market data natively. Time interpolation is linear in total variance; strike interpolation is delegated to each SmileSection.

New files:

• ql/termstructures/volatility/equityfx/blackvariancesurfacefromsmilesections.hpp — class declaration
• ql/termstructures/volatility/equityfx/blackvariancesurfacefromsmilesections.cpp — constructor validation, blackVarianceImpl, visitor pattern
• test-suite/blackvariancesurfacefromsmilesections.cpp — 7 test cases

Build system: registered in ql/CMakeLists.txt, ql/.../Makefile.am, ql/.../all.hpp, test-suite/CMakeLists.txt, test-suite/Makefile.am.

Test: 7 cases covering exact repricing at tenor points, linear variance interpolation between tenors, blackVol derivation from blackVariance, flat-vol extrapolation beyond the last tenor, observer notification propagation through SmileSections, strike-dependent smile handling, and multi-tenor interpolation with different smile shapes. All pass.

[paolodelia99]

Hi @pandashark, thanks for doing that! I like this simple implementation.
Maybe I'll just add some sanity checks for calendar arbitrage and butterfly arbitrage for the midpoint smile section in the last test case, just to be sure.
Also, it would be nice to have the BlackVolTimeExtrapolation timeExtrapolation as an additional parameter in the ctor, which is the one that I'm adding in #2368 for the BlackVolDurfaceDelta class.

[pandashark]

Thanks @paolodelia99!

I've added calendar and butterfly arbitrage sanity checks to the midpoint smile in testMultiTenorSmileInterpolation:

• Calendar: verifies total variance is non-decreasing across d1 → dMid → d2 at each strike
• Butterfly: verifies d²w/dK² ≥ 0 at the midpoint via finite differences across several interior strikes

Both pass — linear variance interpolation between the piecewise-linear smile sections preserves both properties for this test data.

For the BlackVolTimeExtrapolation parameter — I agree it would be a useful addition. The current implementation uses flat-vol extrapolation, which is consistent with every existing QuantLib Black variance surface (BlackVarianceCurve, BlackVarianceSurface, etc.). Since the enum and helpers are being introduced in your #2368 and that API is still under review, I think the cleanest approach is to add the time extrapolation parameter as a follow-up once #2368 lands — that way we avoid duplicating the type and can potentially add it to multiple classes at once for consistency. Does that work for you?

[coveralls]

coverage: 74.241% (+0.03%) from 74.215%
when pulling 23678dd on pandashark:feature/ragged-vol-surface
into a385759 on lballabio:master.

[paolodelia99]

Yes, please add it when #2368 will be merged.
Thank you again!

[lballabio]

We need a name here (either a person or a company). Same for the other new files.

[pandashark]

Thanks for catching that. I followed the existing template but wasn't sure what to use - happy to add whatever you prefer. Do you have a preferred convention for individual contributors?

[lballabio]

It's not a matter of what I prefer, it's who holds the copyright :)

[pandashark]

Fair enough! I'll update all new files with the correct copyright.

[lballabio]

Nice, thanks. BlackVarianceSurface can be implemented in terms of this one by using InterpolatedSmileSection, I guess, so ideally I'd replace it with this one so that this one can steal the simpler name. It will take a round of deprecation, though—unless we can also give this one the rest of the interface of BlackVarianceSurface (deprecating it at the same time). What do you think?

[pandashark]

Thanks! Agreed — BlackVarianceSurface is really just a special case where each matrix row is an InterpolatedSmileSection with a shared strike grid.

The tricky bit is setInterpolation<>(). That swaps a single Interpolation2D, but here each SmileSection owns its own strike interpolation and the cross-tenor piece is always linear in variance — there's no single knob to swap.

I'd lean toward a separate deprecation round: deprecate BlackVarianceSurface pointing to this class + InterpolatedSmileSection, and let setInterpolation go — users who want custom interpolation just pass in their own SmileSections. A convenience ctor taking (dates, strikes, Matrix) could smooth the migration as a follow-up.

Happy to open a separate issue to track the deprecation, or I can fold it into this one — whatever you prefer.

[lballabio]

Yes, setInterpolation is tricky to port here. Ok, let's keep the two classes and deprecate BlackVarianceSurface. The convenience constructor is a good idea but maybe I'm leaning more towards a static factory method, or a free function.

I would also try to think of a shorter name for this class but I don't have any ideas right now :)

[pandashark]

Sounds good — separate deprecation round it is.

For the factory method, I'm thinking a free function that constructs the surface from a rectangular grid (strikes + vol matrix), mirroring the BlackVarianceSurface constructor signature. Something like:

ext::shared_ptr<...>
makeFromGrid(const Date& referenceDate,
             const std::vector<Date>& dates,
             const std::vector<Real>& strikes,
             const Matrix& blackVols,
             const DayCounter& dc = Actual365Fixed());

That way users migrating from BlackVarianceSurface get a straightforward path.

For shorter names, following the [Modifier]BlackVarianceSurface pattern (like HestonBlackVolSurface, FixedLocalVolSurface):

• PiecewiseBlackVarianceSurface — follows the Piecewise* convention (PiecewiseYieldCurve, PiecewiseDefaultCurve); each tenor is a piece stitched together
• CompositeBlackVarianceSurface — composed from individual smile sections
• SplicedBlackVarianceSurface — splicing smile sections together
• BlackVarianceSmileSurface — short, but could be read as a surface of smile params

I'd lean toward PiecewiseBlackVarianceSurface given the existing precedent, welcome your input on naming ideas.

[lballabio]

I'm ok with PiecewiseBlackVarianceSurface. BlackVarianceSmileSurface would work, too. I'll leave it to you.

The free function is ok too, but the name will be a mouthful (makePiecewiseBlackVarianceSurfaceFromGrid?). A static method like PiecewiseBlackVarianceSurface::makeFromGrid might be better.

[pandashark]

Thanks! I've gone with PiecewiseBlackVarianceSurface and added a static makeFromGrid that takes (referenceDate, dates, strikes, Matrix, dc) — same layout as BlackVarianceSurface (rows = strikes, columns = dates). It constructs InterpolatedSmileSection<Linear> per tenor internally.

Force-pushed with the rename + factory method.

[lballabio]

This might loop over the set of smile sections and ask them for their min strike. If the sections have different min strikes, we'd have to think if we want the largest or the smallest. It might be an expensive operation though, so we might have the further problem of precalculating and refreshing when something changes. What do you think?

[pandashark]

I think QL_MIN_REAL/QL_MAX_REAL is the right choice. The surface delegates to smile sections for the strike dimension, and sections handle out-of-range strikes via their interpolator's extrapolation — so it can produce a value at any strike.

The ragged case makes the alternative problematic: if section A covers [80, 120] and section B covers [90, 130], the intersection is [90, 120]. A query at strike 85 at section A's tenor gets rejected even though section A handles it within its own grid. The user would have to call enableExtrapolation() for something that isn't actually extrapolated.

[lballabio]

Agreed, I was also thinking of the ragged case and it is indeed problematic.

However, SmileSection does provide minStrike and maxStrike methods. We could use them here to range-check the calls to smileSections_[i]->variance(strike). As for other curves, the check would be also based on whether we called enableExtrapolation on this class. This would give us the correct check for each section.

[pandashark]

Good idea — done. Added a private sectionVariance(i, strike) helper that checks strike against smileSections_[i]->minStrike()/maxStrike() before querying variance. If the strike is out of range and allowsExtrapolation() is false on the surface, it throws. All variance queries in blackVarianceImpl route through this helper.

The surface-level minStrike()/maxStrike() still return QL_MIN_REAL/QL_MAX_REAL since there's no single range that works for the ragged case — the per-section check handles the actual enforcement.

Updated the ragged grid test to verify the throw (strike 75 outside section 0's [80, 120] range) and that enableExtrapolation() allows it through. Also switched all validation tests to use ExpectedErrorMessage.

[lballabio]

Great, thanks.

[lballabio]

We have an existing ExpectedErrorMessage that you can use as

    BOOST_CHECK_EXCEPTION(
        PiecewiseBlackVarianceSurface(today, {}, {}, dc),
        Error,
        ExpectedErrorMessage("at least one date"));

if you include "utilities.hpp"

[pandashark]

Done — switched all validation tests to use ExpectedErrorMessage. Much cleaner, thanks for the pointer.