quantflow 0.8.0__tar.gz → 0.9.0__tar.gz

{quantflow-0.8.0 → quantflow-0.9.0}/.github/copilot-instructions.md

@@ -45,15 +45,3 @@ applyTo: '/**'
 
 * Strategy runtime markdown descriptions (read by `load_description()` at runtime) live inside the package at `quantflow/options/strategies/docs/` — they must be inside the package to be accessible when the library is installed
 * mkdocs documentation pages live in `docs/api/options/` — do not mix these two locations
-
-## Releasing
-
-The release procedure is fully driven by `make release` and the `release.yml` workflow:
-
-1. Bump `version` in `pyproject.toml` to the new release version.
-2. Add a `## vX.Y.Z` section to `docs/release-notes.md` with the notes for the release. The header text is matched verbatim by the workflow's `awk` extractor, so it must be `## vX.Y.Z` exactly (no trailing dash, no title after the version).
-3. Commit and merge to `main`.
-4. From `main`, run `make release` — it reads the version from `pyproject.toml`, prompts for confirmation, then creates an annotated `vX.Y.Z` tag and pushes it.
-5. The tag push triggers `.github/workflows/release.yml`, which runs lint and tests, publishes the package to PyPI (`make publish`), and posts the extracted `## vX.Y.Z` section as the GitHub Release body.
-
-Do not publish to PyPI manually or via the old `head_commit.message == 'release'` flow — the tag-triggered workflow is the only supported path.

quantflow-0.9.0/.github/instructions/release.instructions.md

@@ -0,0 +1,48 @@
+# Release Instructions
+
+Releases are driven by `v*` git tags. Pushing a tag triggers
+`.github/workflows/release.yml`, which runs lint and the test suite, publishes
+the package to PyPI (`make publish`), then extracts the matching `## vX.Y.Z`
+section from `docs/release-notes.md` and publishes it as the GitHub Release
+body.
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` to the new release version.
+2. Add a `## vX.Y.Z` section at the top of `docs/release-notes.md` with the
+   notes for the release. The header text is matched verbatim by the
+   workflow's `awk` extractor, so it must be `## vX.Y.Z` exactly (no trailing
+   dash, no title after the version). The release workflow fails if this
+   section is missing.
+3. Commit and merge to `main`; let the `build` workflow pass.
+4. From `main`, run `make release` — it reads the version from
+   `pyproject.toml`, asks for confirmation, then creates an annotated `vX.Y.Z`
+   tag and pushes it. The `release` workflow takes it from there.
+
+Do not publish to PyPI manually, and do not revive the old
+`head_commit.message == 'release'` flow — the tag-triggered workflow is the
+only supported path.
+
+## Release-notes conventions
+
+The `## vX.Y.Z` section in `docs/release-notes.md` is rendered both on the
+docs site and as the GitHub Release body, so it must follow these conventions:
+
+- Open with a one-paragraph summary describing the theme of the release. If
+  the release contains breaking changes, point readers to the **Breaking
+  changes** section in that paragraph.
+- Group entries under H3 subsections in this order: `### Breaking changes`,
+  `### New features`, `### Improvements and fixes`,
+  `### Documentation and assets`. Omit any subsection that has no entries.
+- Every PR reference must be a markdown link of the form
+  `[#NN](https://github.com/quantmind/quantflow/pull/NN)` — never a bare
+  `(#NN)`. GitHub's auto-linking only works in some contexts, and the explicit
+  URL works everywhere. When one entry references multiple PRs, list them
+  comma-separated inside one set of parentheses, each as its own link.
+- Build the PR list by running `git log vPREV..HEAD --oneline` against the
+  previous release tag and following each squashed-merge commit back to its
+  PR. Cross-check with `gh pr list --state merged --base main` for any PRs
+  merged since the previous tag.
+- End the section with a
+  `[Full changelog](https://github.com/quantmind/quantflow/compare/vPREV...vX.Y.Z)`
+  link comparing the new tag against the previous one.

{quantflow-0.8.0 → quantflow-0.9.0}/CLAUDE.md

@@ -1,4 +1,5 @@
 @readme.md
 @.github/copilot-instructions.md
 @.github/instructions/makefile.instructions.md
+@.github/instructions/release.instructions.md
 @.github/instructions/tutorial.instructions.md

{quantflow-0.8.0 → quantflow-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantflow
-Version: 0.8.0
+Version: 0.9.0
 Summary: quantitative analysis
 Project-URL: Homepage, https://github.com/quantmind/quantflow
 Project-URL: Repository, https://github.com/quantmind/quantflow

{quantflow-0.8.0 → quantflow-0.9.0}/docs/api/options/black.md

@@ -1,13 +1,12 @@
 # Black Pricing
 
-Here we define the log strike `k` as
-$$
+Here we define the [log strike](../../glossary.md#log-strike) `k` as
+
+\begin{equation}
   k = \log{\frac{K}{F}}
-$$
+\end{equation}
 
 where $K$ is the strike price and $F$ is the forward price of the underlying asset.
-We also refers to this log-strike as `moneyness`, since it is zero for at-the-money (ATM) options,
-negative for in-the-money (ITM) call options, and positive for out-of-the-money (OTM) call options.
 
 
 ::: quantflow.options.bs.black_price

{quantflow-0.8.0 → quantflow-0.9.0}/docs/examples/pricing_method_comparison.py

@@ -62,7 +62,7 @@ class PricingMethodComparison(BaseModel):
     def _implied_vols(
         self, r: OptionPricingResult, log_strikes: np.ndarray, ttm: float
     ) -> np.ndarray:
-        call = np.asarray(r.call_at(log_strikes))
+        call = np.asarray(r.call_price(log_strikes))
         intrinsic = np.maximum(0.0, 1.0 - np.exp(log_strikes))
         call = np.clip(call, intrinsic, 1.0)
         return implied_black_volatility(log_strikes, call, ttm, 0.5, 1.0).values
@@ -75,10 +75,10 @@ class PricingMethodComparison(BaseModel):
         ttm: float,
     ) -> float:
         iv = implied_black_volatility(
-            log_strikes, np.asarray(r.call_at(log_strikes)), ttm, 0.5, 1.0
+            log_strikes, np.asarray(r.call_price(log_strikes)), ttm, 0.5, 1.0
         ).values
         iv_ref = implied_black_volatility(
-            log_strikes, np.asarray(ref.call_at(log_strikes)), ttm, 0.5, 1.0
+            log_strikes, np.asarray(ref.call_price(log_strikes)), ttm, 0.5, 1.0
         ).values
         finite = np.isfinite(iv) & np.isfinite(iv_ref)
         return float(np.max(np.abs(iv[finite] - iv_ref[finite])))
@@ -90,7 +90,7 @@ class PricingMethodComparison(BaseModel):
             log_strikes = ms.option_support(
                 self.ref_n + 1, max_log_strike=max_log_strike
             )
-            ref = ms.call_option(self.ref_n, max_log_strike=max_log_strike)
+            ref = ms.call_option(self.ref_n, max_moneyness=self.max_moneyness)
             iv_ref = self._implied_vols(ref, log_strikes, ttm)
             moneyness_ref = log_strikes / np.sqrt(ttm)
             ttm_label = f"TTM={ttm}"
@@ -121,7 +121,7 @@ class PricingMethodComparison(BaseModel):
                 for n in self.ns:
                     r = ms.call_option(
                         n,
-                        max_log_strike=max_log_strike,
+                        max_moneyness=self.max_moneyness,
                         pricing_method=method,
                     )
                     ks = (

{quantflow-0.8.0 → quantflow-0.9.0}/docs/examples/vol_surface_bns2_calibration.py

@@ -2,7 +2,8 @@ import json
 
 from docs.examples._utils import assets_path, print_model
 from quantflow.options.calibration import BNS2Calibration
-from quantflow.options.pricer import OptionPricer
+from quantflow.options.calibration.base import ResidualKind
+from quantflow.options.pricer import OptionPricer, OptionPricingMethod
 from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
 from quantflow.sp.bns import BNS, BNS2
 
@@ -23,14 +24,16 @@ pricer = OptionPricer(
     model=BNS2(
         bns1=BNS.create(vol=0.45, kappa=20.0, decay=10.0, rho=-0.6),
         bns2=BNS.create(vol=0.45, kappa=0.3, decay=10.0, rho=0.3),
-        weight=0.3,
-    )
+        weight=0.5,
+    ),
+    method=OptionPricingMethod.COS,
 )
 
 calibration: BNS2Calibration[BNS2] = BNS2Calibration(
     pricer=pricer,
     vol_surface=surface,
-    moneyness_weight=0.2,
+    moneyness_weight=0.3,
+    residual_kind=ResidualKind.IV,
 )
 
 result = calibration.fit()

{quantflow-0.8.0 → quantflow-0.9.0}/docs/examples/vol_surface_bns_calibration.py

@@ -2,7 +2,7 @@ import json
 
 from docs.examples._utils import assets_path, print_model
 from quantflow.options.calibration import BNSCalibration
-from quantflow.options.pricer import OptionPricer
+from quantflow.options.pricer import OptionPricer, OptionPricingMethod
 from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
 from quantflow.sp.bns import BNS
 
@@ -16,6 +16,7 @@ surface.disable_outliers()
 # Create a BNS pricer with initial parameters
 pricer = OptionPricer(
     model=BNS.create(vol=0.5, kappa=1.0, decay=10.0, rho=-0.2),
+    method=OptionPricingMethod.COS,
 )
 
 calibration: BNSCalibration[BNS] = BNSCalibration(

{quantflow-0.8.0 → quantflow-0.9.0}/docs/examples/vol_surface_heston_calibration.py

@@ -23,6 +23,7 @@ pricer = OptionPricer(
 calibration: HestonCalibration[Heston] = HestonCalibration(
     pricer=pricer,
     vol_surface=surface,
+    moneyness_weight=0.3,
 )
 
 result = calibration.fit()

{quantflow-0.8.0 → quantflow-0.9.0}/docs/examples/vol_surface_hestonj_calibration.py

@@ -2,10 +2,12 @@ import json
 
 from docs.examples._utils import assets_path, print_model
 from quantflow.options.calibration import HestonJCalibration
+from quantflow.options.calibration.base import ResidualKind
 from quantflow.options.pricer import OptionPricer
 from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
 from quantflow.sp.heston import HestonJ
 from quantflow.utils.distributions import DoubleExponential
+from quantflow.utils.marginal import OptionPricingMethod
 
 # Load a saved volatility surface snapshot and build the surface
 with open("docs/examples/volsurface.json") as fp:
@@ -24,14 +26,15 @@ pricer = OptionPricer(
         sigma=0.8,
         jump_fraction=0.3,
         jump_asymmetry=0.2,
-    )
+    ),
+    method=OptionPricingMethod.COS,
 )
 
 # Set up the calibration, dropping the first (very short) maturity
 calibration: HestonJCalibration[DoubleExponential] = HestonJCalibration(
     pricer=pricer,
     vol_surface=surface,
-    moneyness_weight=0.5,
+    residual_kind=ResidualKind.IV,
 )
 
 result = calibration.fit()

quantflow-0.9.0/docs/release-notes.md

@@ -0,0 +1,165 @@
+# Release Notes
+
+This page is the source of truth for quantflow release notes. Each section
+below maps to a tagged release on
+[GitHub](https://github.com/quantmind/quantflow/releases). When a new tag is
+pushed, the matching section is extracted by
+`.github/workflows/release.yml` and published as the GitHub Release body.
+
+## v0.9.0
+
+Pricing-engine and calibration overhaul. `MaturityPricer` now evaluates call
+prices and Greeks lazily at arbitrary log-strikes instead of carrying a
+precomputed grid, Fourier pricers take a moneyness-based truncation parameter,
+and the volatility-surface calibration can fit Black implied vols directly.
+This release contains several API changes: see **Breaking changes** below.
+
+### Breaking changes
+
+**`MaturityPricer` reworked.** ([#59](https://github.com/quantmind/quantflow/pull/59))
+
+- The precomputed `std`, `log_strike` and `call` arrays are gone. A
+  `MaturityPricer` now holds a single `pricing` field (an
+  `OptionPricingResult`) that evaluates call prices and Greeks on demand at
+  any log-strike.
+- `moneyness` is now a method, `moneyness(log_strikes)`, not a cached array
+  property. The `time_value` and `intrinsic_value` array properties and the
+  `interp(...)` helper were removed; use `prices(log_strikes)` to get a
+  DataFrame of prices and implied vols on a chosen log-strike grid.
+
+**Fourier pricing truncation: `max_log_strike` → moneyness parameters.**
+([#59](https://github.com/quantmind/quantflow/pull/59))
+
+- `Marginal1D.call_option`, `call_option_carr_madan` and `call_option_lewis`
+  take `max_moneyness` (a multiple of the marginal standard deviation)
+  instead of `max_log_strike`. The COS path takes
+  `cos_moneyness_std_precision` instead.
+- `OptionPricingResult.call_at(...)` is renamed `call_price(...)`, the
+  `method` field is removed, and a new abstract `call_greeks(log_strike)`
+  returns a `Greeks` namedtuple `(price, delta, gamma)`.
+
+**`OptionPricerBase.call_price` → `call_prices`.**
+([#59](https://github.com/quantmind/quantflow/pull/59)) The method is now
+vectorised: it takes arrays of times-to-maturity and log-strikes and prices
+them in a single maturity-grouped call.
+
+**`DIVFMPricer` no longer builds a fixed moneyness grid.**
+([#59](https://github.com/quantmind/quantflow/pull/59)) The
+`max_moneyness_ttm` and `n` fields are removed; the fitted IV surface is
+evaluated on demand through `OptionPricingResultDIVFM`.
+
+### New features
+
+- **Implied-vol calibration residuals.** New `ResidualKind` enum and a
+  `residual_kind` field on `VolModelCalibration`: set it to `ResidualKind.IV`
+  to fit the model to Black implied vols (recovered by inverting the model
+  price) rather than to forward-space prices. The IV residual is naturally
+  well-scaled across moneyness, so `moneyness_weight` is not applied in that
+  mode. ([#59](https://github.com/quantmind/quantflow/pull/59))
+- **Greeks from the pricing result.** `OptionPricingCosResult.call_greeks`
+  returns closed-form price, delta and gamma from the COS expansion; the
+  transform-based result derives delta and gamma by differentiating the call
+  grid; DIVFM uses finite differences on the fitted surface.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- **COS truncation control on `OptionPricer`.** New
+  `cos_moneyness_std_precision` field (default 12) sets the width of the COS
+  integration interval in standard deviations.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+
+### Improvements and fixes
+
+- Calibration residuals are now computed in a single vectorised pricing call.
+  Deep-wing strikes where the model price falls outside the no-arbitrage band
+  (so Newton fails to invert it) are masked out instead of poisoning the fit,
+  and a parameter set that fails to invert on more than half the options is
+  rejected with a large penalty.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- Calibration plots now evaluate the model on a fresh moneyness grid;
+  `plot(max_moneyness=...)` no longer accepts `None`.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- `OptionEntry.mid_price()` no longer caches through a private attribute.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- Stale Jupytext notebook mirrors under `notebooks/` removed.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+
+### Documentation and assets
+
+- New GitHub social-preview banner under `docs/assets/logos/png/`.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- `docs/api/options/black.md` and the volatility-surface calibration examples
+  updated for the new pricer API.
+  ([#59](https://github.com/quantmind/quantflow/pull/59))
+- The release procedure moved out of `.github/copilot-instructions.md` into
+  its own `.github/instructions/release.instructions.md`.
+
+[Full changelog](https://github.com/quantmind/quantflow/compare/v0.8.0...v0.9.0)
+
+## v0.8.0
+
+Volatility-surface calibration overhaul. This release adds a two-factor BNS
+model, a double-Heston model (with optional jumps), Lewis and COS pricing
+methods, and reworks the calibration package layout. Several module renames
+and signature changes were made along the way: see **Breaking changes** below.
+
+### Breaking changes
+
+**Module renames.**
+
+- `quantflow.sp.weiner` is now `quantflow.sp.wiener` (typo fix). Update
+  imports.
+- `quantflow.options.calibration` is now a package, not a single module.
+  Top-level imports keep working through the package `__init__.py`
+  re-exports. Code reaching into the old `quantflow.options.heston_calibration`
+  must switch to `quantflow.options.calibration.heston`.
+
+**`ModelOptionPrice` field rename.** ([#47](https://github.com/quantmind/quantflow/pull/47))
+
+- `ModelOptionPrice.moneyness` previously meant `log(K/F)`. It now means
+  standardised moneyness `log(K/F) / sqrt(ttm)`, and the raw log-strike is
+  exposed as a new field `log_strike`. Code reading `option.moneyness` and
+  expecting a log-strike must switch to `option.log_strike`.
+- `get_intrinsic_value(moneyness=...)` argument renamed to `log_strike=...`.
+
+### New features
+
+- **`BNS2`**: two-factor Barndorff-Nielsen & Shephard stochastic-volatility
+  model with a single Brownian motion driving a convex combination of
+  independent Gamma-OU variances and per-factor leverage. New section in the
+  BNS calibration tutorial. ([#54](https://github.com/quantmind/quantflow/pull/54))
+- **`DoubleHeston` and `DoubleHestonJ`**: two-factor Heston (with optional
+  log-price jumps) and matching `DoubleHestonCalibration` /
+  `DoubleHestonJCalibration`. ([#46](https://github.com/quantmind/quantflow/pull/46))
+- **Lewis and COS option-pricing methods**: selectable via
+  `OptionPricingMethod`, alongside the existing Carr-Madan / FFT path.
+  ([#47](https://github.com/quantmind/quantflow/pull/47))
+- **CIR tutorial** with PDF comparison example.
+  ([#49](https://github.com/quantmind/quantflow/pull/49))
+
+### Improvements and fixes
+
+- Heston calibration convergence fixes.
+  ([#45](https://github.com/quantmind/quantflow/pull/45),
+  [#49](https://github.com/quantmind/quantflow/pull/49))
+- BNS calibration: dedicated `BNSCalibration` class extracted, characteristic
+  exponent derivation cleaned up, broader test coverage.
+  ([#50](https://github.com/quantmind/quantflow/pull/50),
+  [#51](https://github.com/quantmind/quantflow/pull/51))
+- OU module reworked: clearer Gamma-OU API, stronger tests for moments and
+  the integrated Laplace transform.
+  ([#51](https://github.com/quantmind/quantflow/pull/51))
+- `pricing_method_comparison` example simplified; redundant time-comparison
+  code removed. ([#48](https://github.com/quantmind/quantflow/pull/48))
+
+### Documentation and assets
+
+- New logo set (favicon, lockup, marks, social banners) under
+  `docs/assets/logos/`. ([#53](https://github.com/quantmind/quantflow/pull/53))
+- New `docs/mcp.md` page covering the MCP server.
+- Bibliography rebuilt from BibTeX via `docs/bib2md.py`; glossary expanded;
+  mathjax tweaks for inline rendering.
+  ([#47](https://github.com/quantmind/quantflow/pull/47),
+  [#49](https://github.com/quantmind/quantflow/pull/49))
+- Tutorial-writing instructions added at
+  `.github/instructions/tutorial.instructions.md`.
+
+[Full changelog](https://github.com/quantmind/quantflow/compare/v0.7.0...v0.8.0)

{quantflow-0.8.0 → quantflow-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantflow"
-version = "0.8.0"
+version = "0.9.0"
 description = "quantitative analysis"
 authors = [ { name = "Luca Sbardella", email = "luca@quantmind.com" } ]
 license = "BSD-3-Clause"

{quantflow-0.8.0 → quantflow-0.9.0}/quantflow/options/calibration/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import enum
 from abc import ABC, abstractmethod
 from datetime import datetime
 from decimal import Decimal
@@ -13,12 +14,26 @@ from scipy.optimize import Bounds, OptimizeResult, least_squares, minimize
 from quantflow.sp.base import StochasticProcess1D
 from quantflow.utils import plot
 
+from ..bs import implied_black_volatility
 from ..pricer import OptionPricerBase
 from ..surface import OptionPrice, VolSurface
 
 M = TypeVar("M", bound=StochasticProcess1D)
 
 
+class ResidualKind(enum.StrEnum):
+    """How calibration residuals are measured against the market"""
+
+    PRICE = enum.auto()
+    """Residual on forward-space option prices: `weight * (model_price - mid_price)`"""
+
+    IV = enum.auto()
+    """Residual on Black implied volatilities: `weight * (model_iv - mid_iv)`,
+    where `model_iv` is recovered from the model price by Black-Scholes
+    inversion. Naturally well-scaled across moneyness, so `moneyness_weight`
+    is usually unnecessary."""
+
+
 class ModelCalibrationEntryKey(NamedTuple):
     maturity: datetime
     strike: Decimal
@@ -36,7 +51,6 @@ class OptionEntry(BaseModel):
     log_strike: float = Field(description="Log-strike as log(K/F)")
     options: list[OptionPrice] = Field(default_factory=list)
     """Bid and ask option prices for this entry"""
-    _mid_price: float | None = PrivateAttr(default=None)
 
     def implied_vol_range(self) -> Bounds:
         """Get the range of implied volatilities across bid and ask"""
@@ -45,10 +59,8 @@ class OptionEntry(BaseModel):
 
     def mid_price(self) -> float:
         """Mid price as the average of bid and ask call prices"""
-        if self._mid_price is None:
-            prices = tuple(float(option.call_price) for option in self.options)
-            self._mid_price = sum(prices) / len(prices)
-        return self._mid_price
+        prices = tuple(float(option.call_price) for option in self.options)
+        return sum(prices) / len(prices)
 
     def mid_iv(self) -> float:
         """Mid implied volatility as the average of bid and ask"""
@@ -81,6 +93,18 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]):
             " to calibrate the model with"
         ),
     )
+    residual_kind: ResidualKind = Field(
+        default=ResidualKind.PRICE,
+        description=(
+            "Kind of residual used by the calibration cost function."
+            " `price` (default) measures the residual on forward-space"
+            " option prices and applies the `moneyness_weight` cost weights;"
+            " `iv` measures it on Black implied volatilities by inverting"
+            " the model price. The `iv` residual is already in vol units"
+            " and is naturally well-scaled across moneyness, so the"
+            " `moneyness_weight` cost weights are not applied in that mode."
+        ),
+    )
     moneyness_weight: float = Field(
         default=0.0,
         ge=0.0,
@@ -108,6 +132,11 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]):
         repr=False,
         description="The options to calibrate",
     )
+    _log_strikes: np.ndarray = PrivateAttr(default_factory=lambda: np.empty(0))
+    _ttms: np.ndarray = PrivateAttr(default_factory=lambda: np.empty(0))
+    _moneyness: np.ndarray = PrivateAttr(default_factory=lambda: np.empty(0))
+    _mid_prices: np.ndarray = PrivateAttr(default_factory=lambda: np.empty(0))
+    _mid_ivs: np.ndarray = PrivateAttr(default_factory=lambda: np.empty(0))
 
     def model_post_init(self, _ctx: Any) -> None:
         if not self.options:
@@ -118,6 +147,12 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]):
                     entry = OptionEntry(ttm=option.ttm, log_strike=option.log_strike)
                     self.options[key] = entry
                 entry.options.append(option)
+        entries = tuple(self.options.values())
+        self._log_strikes = np.asarray([e.log_strike for e in entries])
+        self._ttms = np.asarray([e.ttm for e in entries])
+        self._moneyness = self._log_strikes / np.sqrt(self._ttms)
+        self._mid_prices = np.asarray([e.mid_price() for e in entries])
+        self._mid_ivs = np.asarray([e.mid_iv() for e in entries])
 
     @abstractmethod
     def get_params(self) -> np.ndarray:
@@ -192,52 +227,84 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]):
         weight = np.exp(self.moneyness_weight * moneyness * moneyness)
         return float(min(weight, self.max_cost_weight))
 
+    def cost_weights(self) -> np.ndarray:
+        """Vector of cost weights for all calibration options"""
+        weights = np.exp(self.moneyness_weight * self._moneyness * self._moneyness)
+        return np.minimum(weights, self.max_cost_weight)
+
     def penalize(self) -> float:
         """Additional scalar penalty added to the cost function (default: 0)"""
         return 0.0
 
     def residuals(self, params: np.ndarray) -> np.ndarray:
-        """Weighted price residuals: `weight * (model_price - mid_price)` per option"""
+        """Weighted residuals per option, in price or implied-vol space.
+
+        Controlled by `residual_kind`:
+
+        - `price`: `weight * (model_price - mid_price)`
+        - `iv`: `weight * (model_iv - mid_iv)`, where `model_iv` is the
+          Black implied volatility of the model price.
+        """
         self.set_params(params)
         self.pricer.reset()
-        res = []
         with np.errstate(all="ignore"):
-            for entry in self.options.values():
-                model_price = self.pricer.call_price(entry.ttm, entry.log_strike)
-                weight = self.cost_weight(entry.ttm, entry.log_strike)
-                r = weight * (model_price - entry.mid_price())
-                res.append(r if np.isfinite(r) else 1e6)
-        return np.asarray(res)
+            try:
+                model_prices = self.pricer.call_prices(self._ttms, self._log_strikes)
+            except ValueError:
+                return np.full(self._log_strikes.shape, 1e6)
+            if self.residual_kind is ResidualKind.IV:
+                implied = implied_black_volatility(
+                    self._log_strikes,
+                    model_prices,
+                    self._ttms,
+                    initial_sigma=self._mid_ivs,
+                    call_put=1,
+                )
+                # Fourier pricers can return prices outside the no-arb band
+                # for deep-wing strikes, where Newton fails to invert. Mask
+                # those points out (zero residual). If fewer than half of the
+                # options invert successfully the parameter set is treated as
+                # invalid and a large penalty is returned.
+                ok = implied.converged
+                if 2 * int(ok.sum()) < ok.size:
+                    return np.full(self._log_strikes.shape, 1e6)
+                r = np.where(ok, implied.values - self._mid_ivs, 0.0)
+            else:
+                r = self.cost_weights() * (model_prices - self._mid_prices)
+        return np.where(np.isfinite(r), r, 1e6)
 
     def cost_function(self, params: np.ndarray) -> float:
         """Scalar cost: sum of squared residuals plus any penalty"""
         r = self.residuals(params)
         return float(np.dot(r, r)) + self.penalize()
 
+    def _model_grid(
+        self, ttm: float, max_moneyness: float, support: int
+    ) -> pd.DataFrame:
+        log_strikes = np.linspace(-max_moneyness, max_moneyness, support) * np.sqrt(ttm)
+        return self.pricer.maturity(ttm).prices(log_strikes)
+
     def plot(
         self,
         index: int = 0,
         *,
-        max_moneyness: float | None = 1.0,
+        max_moneyness: float = 1.0,
         support: int = 51,
         **kwargs: Any,
     ) -> Any:
         """Plot implied volatility for market and model prices"""
         cross = self.vol_surface.maturities[index]
         options = tuple(self.vol_surface.option_prices(index=index, converged=True))
-        model = self.pricer.maturity(cross.ttm(self.ref_date))
-        if max_moneyness is not None:
-            model = model.max_moneyness(max_moneyness=max_moneyness, support=support)
         return plot.plot_vol_surface(
             pd.DataFrame([d.info_dict() for d in options]),
-            model=model.df,
+            model=self._model_grid(cross.ttm(self.ref_date), max_moneyness, support),
             **kwargs,
         )
 
     def plot_maturities(
         self,
         *,
-        max_moneyness: float | None = 1.0,
+        max_moneyness: float = 1.0,
         support: int = 51,
         cols: int = 2,
         row_height: int = 400,
@@ -257,15 +324,11 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]):
             row = i // cols + 1
             col = i % cols + 1
             options = tuple(self.vol_surface.option_prices(index=i, converged=True))
-            model = self.pricer.maturity(cross.ttm(self.ref_date))
-            if max_moneyness is not None:
-                model = model.max_moneyness(
-                    max_moneyness=max_moneyness, support=support
-                )
-
             plot.plot_vol_surface(
                 pd.DataFrame([d.info_dict() for d in options]),
-                model=model.df,
+                model=self._model_grid(
+                    cross.ttm(self.ref_date), max_moneyness, support
+                ),
                 fig=fig,
                 fig_params={"row": row, "col": col},
                 **kwargs,