Future Valuation Date: pricing a portfolio at a future date with today's market data

[mattmenefee]

Hi all,

I've been working on a feature that I think could be a useful addition to ORE, and I'd like to gauge interest before putting together a formal PR.

The Use Case

The question is simple: "What would this portfolio be worth on a future date, given today's market data?"

This is a common what-if analysis in risk management — you want to see projected P&L at a future horizon using your current yield curve, without shifting the entire evaluation date (which would break fixings, curve references, and cashflow filtering). Some concrete scenarios:

• A risk manager wants to project swap MTM at quarter-end for reserve planning
• A portfolio manager wants to estimate theta (time decay) on an options book
• A treasury desk wants to forecast collateral requirements at a future settlement date

Key Finding: QuantLib Already Supports This

The DiscountingSwapEngine already accepts npvDate and settlementDate constructor parameters that correctly value a swap at a future date:

NPV(npvDate) = Σ cf_i × D(asOf → t_i) / D(asOf → npvDate)
             = Σ cf_i × D(npvDate → t_i)

Setting settlementDate to the same date excludes cashflows that have already "occurred" relative to the what-if date. And because evaluationDate stays at asOf, all fixings between asOf and the future date are automatically forecast from the forwarding curve — no synthetic fixings needed.

The gap is that ORE's engine builders never pass these parameters through, so the capability sits unused.

Proposed Implementation

The implementation adds a valuationDate parameter to the <Setup> section of ore.xml, treating it as a global pricing context alongside asofDate:

<Setup>
  <Parameter name="asofDate">2026-03-03</Parameter>
  <Parameter name="valuationDate">2027-03-03</Parameter>
  ...
</Setup>

Omitting the parameter preserves current behavior (valuation at asOf).

How it flows through the architecture

ore.xml
  → InputParameters              (parses and stores valuationDate)
    → analytic.cpp                (injects into EngineData::globalParameters)
      → EngineFactory             (passes globalParameters to builders)
        → SwapEngineBuilder       (reads from globalParameters_, passes to engine)
        → CapFlooredIborLegEB     (wraps optionlet vol with ImpliedOptionletVolatilityStructure)
        → EuropeanSwaptionEB      (wraps swaption vol with ImpliedSwaptionVolatilityStructure)
        → [future builders]       (same pattern)

This uses the existing globalParameters mechanism (already used for GenerateAdditionalResults and RunType), so there are no changes to the EngineFactory constructor or the EngineBuilder::init() signature.

Changes in the initial phase

Core wiring:

• InputParameters — new valuationDate_ member with getter/setter, following the asof_ pattern
• oreapp.cpp — parse valuationDate from ore.xml <Setup> section
• analytic.cpp — inject into EngineData::globalParameters()
• SwapEngineBuilder — read from globalParameters_, pass as npvDate and settlementDate to DiscountingSwapEngine

Optionlet time decay fix (caps/floors):

• New ImpliedOptionletVolatilityStructure class in QuantExt — a header-only wrapper (analogous to ImpliedVolTermStructure for equity/FX vols) that presents an optionlet vol surface with a shifted reference date, so that σ√T correctly shrinks when the valuation date moves forward
• CapFlooredIborLegEngineBuilder — wraps the market's optionlet vol surface with the future reference date when ValuationDate is set

Swaption time decay fix (European swaptions):

• New ImpliedSwaptionVolatilityStructure class in QuantExt — same pattern as the optionlet wrapper, but for the 2D swaption vol surface. The optionTime dimension is shifted by timeOffset_ (reducing time-to-exercise), while swapLength passes through unchanged (the underlying swap duration is independent of the pricing date)
• EuropeanSwaptionEngineBuilder — wraps the market's swaption vol surface when ValuationDate is set
• LGM-based Bermudan/American swaption builders emit a warning when ValuationDate is set — LGM calibration is anchored to evaluationDate and forward-starting it is non-trivial

Stress testing support:

• runStressTest() injects ValuationDate into the stress engine's globalParameters, so stressed NPVs are computed at the future date
• CashflowReportCalculator passes valuationDate through to generateCashflowReportData(), so stress cashflow DFs are correctly re-anchored

Safety net:

• New virtual method supportedGlobalParameters() on EngineBuilder (returns empty set by default). Builders that handle ValuationDate override it. EngineFactory::builder() checks and emits a StructuredConfigurationWarningMessage if ValuationDate is set but the builder doesn't support it — because unlike other global parameters, silently ignoring ValuationDate produces wrong NPVs rather than just missing output.

Example and test:

• FutureValuationDate example with three USD SOFR trades (vanilla swap, interest rate cap, European swaption), run in four configurations (baseline pricing, future pricing, baseline stress, future stress) with real LSEG market data
• 11 automated verification steps in run.py covering NPV comparison, DF re-anchoring, optionlet time decay, swaption time decay, stress base NPV consistency, and stress cashflow cross-checks
• Unit test in OREData/test/swapnpvdate.cpp covering baseline, future date, date = asOf, past date rejection, and cashflow exclusion

Instrument coverage and phased rollout

Currently supported (Phase 1):

• Vanilla swaps (SwapEngineBuilder) — uses engine's native npvDate/settlementDate
• Capped/floored IBOR legs (CapFlooredIborLegEngineBuilder) — wraps optionlet vol via ImpliedOptionletVolatilityStructure
• European swaptions (EuropeanSwaptionEngineBuilder) — wraps swaption vol via ImpliedSwaptionVolatilityStructure
• Cashflow reports and stress testing — correctly threaded through

Not yet supported (Phase 2):

• Instrument types whose engines already accept npvDate/settlementDate natively — cross-currency swaps (DiscountingCurrencySwapEngine), FX forwards, equity forwards, commodity swaps, bonds. These would follow the same pattern of reading from globalParameters_.
• Standalone cap/floors — need npvDate support in BlackCapFloorEngine/BachelierCapFloorEngine
• LGM-based Bermudan/American swaptions — LGM calibration grid is anchored to evaluationDate; forward-starting it is a separate, more complex effort. A runtime warning is emitted when this combination is attempted.

What doesn't change

Area	Reason
QuantLib engine code	Already supports npvDate/settlementDate natively
evaluationDate	Stays at asOf — fixings between asOf and the valuation date are forecast, not looked up
Fixing generation	QuantLib auto-forecasts all future fixings — no synthetic fixings needed
NPV report	Already picks up instrument->NPV() which reflects the engine's npvDate
Additional results report	Engine already populates npvDateDiscount and valuationDate
Sensitivity analysis	Re-prices through the same engine; ValuationDate is correctly preserved
Engine cache keys	ValuationDate is a global engine parameter, not per-trade; no cache key change needed

Questions for the Maintainers

1. Does this seem like a useful addition to the open-source version of ORE?
2. Is the ore.xml <Setup> section the right home for this parameter, or would you prefer it elsewhere?
3. Is the supportedGlobalParameters() virtual method a reasonable approach for the safety warnings, or would you prefer a different mechanism?
4. Any concerns about the ImpliedOptionletVolatilityStructure / ImpliedSwaptionVolatilityStructure approach for handling option time decay?

I have a working implementation with tests and an example that I'd be happy to clean up into a PR if there's interest. Feedback welcome!