Fix calibration (#59)

Author: lsbardel

.github/copilot-instructions.md

@@ -57,3 +57,13 @@ The release procedure is fully driven by `make release` and the `release.yml` wo
 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.
+
+### Release-notes conventions
+
+The `## vX.Y.Z` section in `docs/release-notes.md` must follow these conventions, since the same content is rendered both on the docs site and as the GitHub Release body:
+
+* 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 write a bare `(#NN)` — both readers (docs and GitHub) benefit from the explicit URL, and GitHub's auto-linking only works in some contexts. When a single entry references multiple PRs, list them comma-separated inside one set of parentheses, each as its own markdown 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.

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

docs/assets/logos/png/quantflow-github-social-1280x640.png

@@ -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 @@ def _iv_error(
         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 @@ def run_ttm(self) -> None:
             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 @@ def run_ttm(self) -> None:
                 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 = (

docs/examples/pricing_method_comparison.py

@@ -2,7 +2,8 @@
 
 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 @@
     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()

docs/examples/vol_surface_bns2_calibration.py

@@ -2,7 +2,7 @@
 
 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 @@
 # 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(

docs/examples/vol_surface_bns_calibration.py

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

docs/examples/vol_surface_heston_calibration.py

@@ -2,10 +2,12 @@
 
 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 @@
         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()

docs/examples/vol_surface_hestonj_calibration.py

@@ -24,7 +24,7 @@ and signature changes were made along the way: see **Breaking changes** below.
   re-exports. Code reaching into the old `quantflow.options.heston_calibration`
   must switch to `quantflow.options.calibration.heston`.
 
-**`ModelOptionPrice` field rename.** (#47)
+**`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
@@ -37,31 +37,40 @@ and signature changes were made along the way: see **Breaking changes** below.
 - **`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)
+  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)
+  `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)
-- **CIR tutorial** with PDF comparison example. (#49)
+  `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, #49)
+- 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, #51)
+  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)
+  the integrated Laplace transform.
+  ([#51](https://github.com/quantmind/quantflow/pull/51))
 - `pricing_method_comparison` example simplified; redundant time-comparison
-  code removed. (#48)
+  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)
+  `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, #49)
+  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`.