Fix vol surface consistency

Author: lsbardel

.github/copilot-instructions.md

@@ -12,6 +12,8 @@ applyTo: '/**'
 
 * Always run `make lint` after code changes — runs taplo, isort, black, ruff, and mypy
 * Never edit `readme.md` directly — it is generated from `docs/index.md` via `make docs`
+* To run all tests use `make test` — runs all tests in the `tests/` directory using pytest
+* To run a specific test file, use `uv run pytest tests/path/to/test_file.py`
 
 ## Docker
 
@@ -24,4 +26,4 @@ applyTo: '/**'
 
 * The documentation for quantflow is available at `https://quantflow.quantmid.com`
 * Documentation is built using [mkdocs](https://www.mkdocs.org/) and stored in the `docs/` directory. The documentation source files are written in markdown format.
-
+* Do not use em dashes (—) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead.

app/volatility_surface.py

@@ -19,13 +19,24 @@ def _(mo):
 
     In this notebook we illustrate the use of the Volatility Surface tool in the library. We use [deribit](https://docs.deribit.com/) options on ETHUSD as example.
 
-    The library provide a volatility surface loader for Deribit. This code loads the surface as a [VolSurfaceLoader](api/options/vol_surface/#quantflow.options.surface.VolSurfaceLoader):
+    The library provide a [VolSurfaceLoader](api/options/vol_surface/#quantflow.options.surface.VolSurfaceLoader) for Deribit:
 
     ```python
+    import pandas as pd
     from quantflow.data.deribit import Deribit
 
     async with Deribit() as cli:
         loader = await cli.volatility_surface_loader("eth", exclude_open_interest=0)
+
+    # build the volatility surface
+    surface = loader.surface()
+    # calculate black implied volatilities
+    surface.bs()
+    # disable outliers
+    surface.disable_outliers()
+    # display inputs - only options with converged implied volatility
+    surface_inputs = surface.inputs(converged=True)
+    pd.DataFrame([i.model_dump() for i in surface_inputs.inputs])
     ```
     """)
     return
@@ -43,9 +54,39 @@ async def _():
     surface = loader.surface()
     # calculate black implied volatilities
     surface.bs()
-    # display inputs
-    surface_inputs = surface.inputs()
+    # disable outliers
+    surface.disable_outliers()
+    # display inputs - only options with converged implied volatility
+    surface_inputs = surface.inputs(converged=True)
     pd.DataFrame([i.model_dump() for i in surface_inputs.inputs])
+    return (surface,)
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ##Volatility Surface
+    """)
+    return
+
+
+@app.cell
+def _(surface):
+    surface.plot3d()
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    ## Term Structure
+    """)
+    return
+
+
+@app.cell
+def _(surface):
+    surface.term_structure()
     return
 
 

docs/api/options/index.md

@@ -1,5 +1,52 @@
-# Option Pricing
+# Options
 
-The `options` module provides classes and functions for pricing and analyzing options.
-The main class is the [VolSurface][quantflow.options.surface.VolSurface] class which is used to represent a volatility surface for a given asset.
-A volatility surface is usually created via a [VolSurfaceLoader][quantflow.options.surface.VolSurfaceLoader] object.
+The `options` module provides classes and functions for pricing and calibrating options.
+
+## Volatility Surface
+
+The central class is [VolSurface][quantflow.options.surface.VolSurface], which represents
+the implied volatility surface for an asset across all strikes and maturities. It holds:
+
+- a [SpotPrice][quantflow.options.surface.SpotPrice] for the underlying asset
+- a sorted tuple of [VolCrossSection][quantflow.options.surface.VolCrossSection] objects, one per maturity
+
+Each [VolCrossSection][quantflow.options.surface.VolCrossSection] contains the forward price
+at that maturity and a tuple of [Strike][quantflow.options.surface.Strike] objects.
+Each [Strike][quantflow.options.surface.Strike] holds a call and/or put as an
+[OptionPrices][quantflow.options.surface.OptionPrices], which in turn pairs a bid and ask
+[OptionPrice][quantflow.options.surface.OptionPrice].
+
+A surface is typically constructed via [VolSurfaceLoader][quantflow.options.surface.VolSurfaceLoader],
+which accepts price inputs incrementally and builds the surface through its `surface()` method.
+The lower-level [GenericVolSurfaceLoader][quantflow.options.surface.GenericVolSurfaceLoader]
+provides the same functionality with a user-defined security type.
+
+## Price Classes
+
+| Class | Description |
+|---|---|
+| [Price][quantflow.options.surface.Price] | Base bid/ask price for any security |
+| [SpotPrice][quantflow.options.surface.SpotPrice] | Spot bid/ask price of an underlying asset |
+| [FwdPrice][quantflow.options.surface.FwdPrice] | Forward bid/ask price at a specific maturity |
+| [OptionPrice][quantflow.options.surface.OptionPrice] | Single-sided option price with implied volatility and convergence flag |
+| [OptionPrices][quantflow.options.surface.OptionPrices] | Paired bid and ask [OptionPrice][quantflow.options.surface.OptionPrice] for a given strike and option type |
+
+## Input Classes
+
+The input classes are plain data containers used to serialize and deserialize volatility surface data,
+for example when storing or transmitting a snapshot of the surface.
+
+| Class | Description |
+|---|---|
+| [VolSurfaceInputs][quantflow.options.inputs.VolSurfaceInputs] | Top-level container: asset name, reference date, and a list of inputs |
+| [VolSurfaceInput][quantflow.options.inputs.VolSurfaceInput] | Base input with bid, ask, open interest and volume |
+| [SpotInput][quantflow.options.inputs.SpotInput] | Input for a spot price |
+| [ForwardInput][quantflow.options.inputs.ForwardInput] | Input for a forward price with maturity |
+| [OptionInput][quantflow.options.inputs.OptionInput] | Input for an option with strike, maturity, type, and optional implied vols |
+
+A [VolSurface][quantflow.options.surface.VolSurface] can be round-tripped via:
+
+```python
+inputs = surface.inputs()          # VolSurface -> VolSurfaceInputs
+surface = surface_from_inputs(inputs)  # VolSurfaceInputs -> VolSurface
+```

docs/api/options/vol_surface.md

@@ -11,12 +11,30 @@
 
 ::: quantflow.options.surface.VolCrossSectionLoader
 
+## Bid/Ask Prices
+
+::: quantflow.options.surface.Price
+
+::: quantflow.options.surface.SpotPrice
+
+::: quantflow.options.surface.FwdPrice
+
 ::: quantflow.options.surface.Strike
 
+::: quantflow.options.surface.OptionArrays
+
+::: quantflow.options.surface.OptionMetadata
+
 ::: quantflow.options.surface.OptionPrice
 
+::: quantflow.options.surface.OptionPrices
+
 ::: quantflow.options.surface.OptionSelection
 
+::: quantflow.options.inputs.OptionType
+
+## Vol Surface Inputs
+
 ::: quantflow.options.inputs.VolSurfaceInputs
 
 ::: quantflow.options.inputs.VolSurfaceInput

mkdocs.yml

@@ -64,6 +64,7 @@ nav:
       - Double Exponential Sampling: examples/double-exponential-sampling
       - Hurst: examples/hurst
       - Supersmoother: examples/supersmoother
+      - Volatility Surface: examples/volatility-surface
   - API Reference:
       - api/index.md
       - Data:

quantflow/options/bs.py

@@ -75,7 +75,7 @@ def black_price(
             "(1 for call, -1 for put)"
         ),
     ],
-) -> np.ndarray:
+) -> FloatArray:
     r"""Calculate the Black call/put option prices in forward terms
     from the following params
 

quantflow/options/calibration.py

@@ -87,7 +87,7 @@ class VolModelCalibration(BaseModel, ABC, Generic[M], arbitrary_types_allowed=Tr
     def model_post_init(self, _ctx: Any) -> None:
         if not self.options:
             self.vol_surface.bs()
-            for option in self.vol_surface.option_prices():
+            for option in self.vol_surface.option_prices(converged=True):
                 key = ModelCalibrationEntryKey(option.maturity, option.strike)
                 if key not in self.options:
                     entry = OptionEntry(ttm=option.ttm, moneyness=option.moneyness)