Fix lint

Author: lsbardel

docs/api/rates/index.md

@@ -6,7 +6,7 @@ The central concept is the [discount factor](../../glossary.md#discount-factor)
 
 **[Rate](interest_rate.md)** represents a spot or forward interest rate with a chosen compounding frequency (continuous by default) and day count convention. It supports continuous and periodic compounding and can be bootstrapped directly from a spot/forward pair.
 
-**[YieldCurve](yield_curve.md)** is the abstract base for term-structure models. It defines the interface via `discount_factor` and `instantaneous_forward_rate`, with the two quantities linked by
+**[YieldCurve](yield_curve.md)** is the abstract base for term-structure models. It defines the interface via [discount_factor][quantflow.rates.yield_curve.YieldCurve.discount_factor] and [instantaneous_forward_rate][quantflow.rates.yield_curve.YieldCurve.instantaneous_forward_rate], with the two quantities linked by
 
 \begin{equation}
     f(\tau) = -\frac{\partial \ln D_\tau}{\partial \tau}
@@ -18,4 +18,4 @@ The central concept is the [discount factor](../../glossary.md#discount-factor)
 
 **[VasicekCurve](vasicek.md)** is a Gaussian mean-reverting short-rate model with analytical formulas for discount factors and instantaneous forward rates.
 
-**[Options Discounting](options.md)** provides `YieldCurveCalibration`, the base class for fitting a yield curve to discount factors, and `OptionsDiscountingCalibration`, which bootstraps asset and quote curves from put-call parity observations.
+**[Calibration](calibration.md)** provides [YieldCurveCalibration][quantflow.rates.calibration.YieldCurveCalibration], the base class for fitting a yield curve to discount factors, and [OptionsDiscountingCalibration][quantflow.rates.calibration.OptionsDiscountingCalibration], which bootstraps asset and quote curves from put-call parity observations.

docs/theory/kalman.md

@@ -239,9 +239,11 @@ without user intervention.
 When the transition $f(x, \Delta t)$ is non-linear the Kalman predict step
 is no longer exact. The unscented Kalman filter (UKF), introduced by
 [Julier & Uhlmann (1997)](../bibliography.md#julier_uhlmann), replaces it
-with a **sigma-point** propagation. The observation update is unchanged: it
-reuses the Kalman update step described above, so the UKF inherits the
-Sherman-Morrison optimisation when applicable.
+with a **sigma-point** propagation. The observation update follows the same
+structure, but builds the innovation covariance $S_t$ and the cross covariance
+$C_t$ from the propagated sigma points and solves the gain $K_t = C_t S_t^{-1}$
+with a dense Cholesky factorisation. The Sherman-Morrison fast path is specific
+to the exact linear filter and is not used here.
 
 ### Sigma-Point Predict
 

quantflow/ta/kalman.py

@@ -199,6 +199,28 @@ def kalman_filter(
 # ---------------------------------------------------------------------------
 
 
+def isotropic_noise(
+    R: Annotated[FloatArray, Doc("Observation noise covariance of shape (n_y, n_y).")],
+) -> float | None:
+    r"""Detect isotropic observation noise of the form $R = h^2 I$.
+
+    Returns the scalar variance $h^2$ when every diagonal entry equals $h^2$
+    and all off-diagonal entries are zero, otherwise returns ``None``.
+
+    This is the precondition for the Sherman-Morrison fast path in the Kalman
+    update: when the noise is isotropic and the state is one-dimensional, the
+    innovation covariance is a rank-1 update to a scaled identity and can be
+    inverted in $O(n_y)$ instead of $O(n_y^3)$.
+    """
+    n = R.shape[0]
+    h2 = float(R[0, 0])
+    if h2 <= 0.0:
+        return None
+    if n > 1 and not np.allclose(R, h2 * np.eye(n)):
+        return None
+    return h2
+
+
 class KalmanFilter(BaseModel, arbitrary_types_allowed=True):
     r"""Kalman filter for a [LinearGaussianModel][..LinearGaussianModel].
 
@@ -240,6 +262,23 @@ class KalmanFilter(BaseModel, arbitrary_types_allowed=True):
             n_y \log 2\pi + \log\det S_t + e_t^\top S_t^{-1} e_t
         \right).
     \end{equation}
+
+    When the state is one-dimensional and the observation noise is isotropic
+    ($R = h^2 I$), the innovation covariance $S_t = h^2 I + P_{t \mid t-1}\, c c^\top$
+    is a rank-1 update to a scaled identity, where $c = H$ is a column vector.
+
+    The [Sherman-Morrison identity](../../glossary.md#sherman-morrison-identity)
+    inverts it in $O(n_y)$ instead of $O(n_y^3)$:
+
+    \begin{equation}
+        S_t^{-1} = \frac{1}{h^2}\left(
+            I - \frac{P_{t \mid t-1}\, c c^\top}{h^2 + P_{t \mid t-1}\, c^\top c}
+        \right).
+    \end{equation}
+
+    The update detects this case automatically (see
+    [isotropic_noise][..isotropic_noise]) and applies the fast path; otherwise
+    it falls back to a dense Cholesky solve.
     """
 
     model: LinearGaussianModel = Field(description="Linear-Gaussian state-space model.")
@@ -334,6 +373,9 @@ def update(
         H = model.H[:, None] if model.H.ndim == 1 else model.H
         obs = np.atleast_1d(np.asarray(y, dtype=float))
         innov = obs - H @ pred.mean
+        h2 = isotropic_noise(model.R)
+        if h2 is not None and model.n_x == 1:
+            return self._update_isotropic(pred, H[:, 0], innov, h2)
         S = H @ pred.cov @ H.T + model.R
         sign, log_det = np.linalg.slogdet(S)
         if sign <= 0:
@@ -345,6 +387,32 @@ def update(
         cov = pred.cov - gain @ H @ pred.cov
         return MeanAndCov(mean=mean, cov=cov), log_lik
 
+    def _update_isotropic(
+        self,
+        pred: MeanAndCov,
+        c: FloatArray,
+        innov: FloatArray,
+        h2: float,
+    ) -> tuple[MeanAndCov, float]:
+        """Sherman-Morrison fast path of [update][..update] for a 1d state with
+        isotropic noise.
+
+        Equivalent to the dense path but inverts the rank-1 innovation
+        covariance in closed form. See the class docstring and the theory docs
+        for the derivation.
+        """
+        n_y = innov.shape[0]
+        p = float(pred.cov[0, 0])
+        d = h2 + p * float(c @ c)  # h^2 + P c^T c
+        ce = float(c @ innov)  # c^T e_t
+        log_det = (n_y - 1) * np.log(h2) + np.log(d)
+        quad = (float(innov @ innov) - p * ce * ce / d) / h2
+        log_lik = -0.5 * (n_y * np.log(2.0 * np.pi) + log_det + quad)
+        gain = (p / d) * c  # K_t = (P / d) c^T, shape (n_y,)
+        mean = pred.mean + gain @ innov
+        cov = np.array([[p * h2 / d]])
+        return MeanAndCov(mean=mean, cov=cov), log_lik
+
 
 # ---------------------------------------------------------------------------
 # Unscented Kalman filter