SciPy Type Stubs

Warnings

• breaking In `scipy-stubs` v1.16.3.3, the internal `_lib._util._RichResult` class was changed to be a covariant (immutable) type and no longer a subtype of `dict`. Code relying on `_RichResult` behaving like a `dict` at the type level will break.
  Fix: Avoid treating `_RichResult` as a `dict` at the type level. Access attributes directly or convert to a dict explicitly if dictionary-like behavior is truly needed.
• gotcha Ensuring version compatibility between `scipy-stubs` and `scipy` is crucial. Each `scipy-stubs` release targets a specific `SciPy` version (e.g., `scipy-stubs 1.17.1.3` targets `SciPy 1.17.1`), and also specifies supported Python and NumPy versions. Mismatched versions can lead to incorrect or missing type hints, causing false positives or negatives from type checkers.
  Fix: Always install `scipy-stubs` and `scipy` versions that are explicitly compatible. Check the `scipy-stubs` release notes or PyPI page for the exact `SciPy`, Python, and NumPy version requirements. Consider using `pip install scipy-stubs[scipy]` to ensure both are installed correctly.
• gotcha Type stubs are for static analysis only; they have no runtime impact or overhead. You do not import from `scipy-stubs` in your code. Instead, you import `scipy` as usual, and your type checker (e.g., MyPy, Pyright) automatically discovers and uses the stub files for type checking.
  Fix: Understand that `scipy-stubs` is a development-time dependency. Do not add `import scipy_stubs` statements to your production code. Ensure your type checker is configured to find installed stub packages.
• gotcha Earlier versions of `scipy-stubs` (and `SciPy`) had known issues with type hints for `scipy.sparse` array/matrix slicing and multi-indexing operations. These were fixed in recent stub releases (e.g., v1.17.1.2, v1.17.1.3).
  Fix: Update `scipy-stubs` to the latest compatible version with your `SciPy` installation to benefit from the most accurate type hints, especially for `scipy.sparse` operations.
• gotcha Certain generic types provided by `scipy-stubs` (e.g., for `Rotation` or `RigidTransform` in `scipy.spatial.transform`) might not be subscriptable at runtime in older SciPy versions. This could require `from __future__ import annotations` or stringifying type annotations to avoid runtime `TypeError` when using generic types directly in type hints.
  Fix: Utilize `from __future__ import annotations` in your modules. Keep `scipy-stubs` and `scipy` updated to versions that support runtime subscriptability for generic types if you intend to use them.

Install

• pip install scipy-stubs Standard Installation
• pip install scipy-stubs[scipy] Install with SciPy if not already present

Imports

• scipy

  import scipy

  scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.
• optimize

  from scipy import optimize

  scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.
• linalg

  from scipy import linalg

  scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.

Quickstart

This quickstart demonstrates using `scipy.optimize.minimize` with type annotations for inputs and outputs. After installing `scipy-stubs`, your type checker (like MyPy or Pyright) and IDE will automatically provide type-checking and autocompletion for SciPy functions, even without explicit type annotations in your own code. The stubs ensure that the types for `x0`, `res`, and function arguments are correctly understood.

import numpy as np
from scipy.optimize import minimize, OptimizeResult
from typing import Tuple

def rosen(x: np.ndarray) -> np.float64:
    """The Rosenbrock function"""
    return np.sum(100.0 * (x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)

def rosen_der(x: np.ndarray) -> np.ndarray:
    """The Rosenbrock function gradient"""
    xm = x[1:-1]
    xm_m1 = x[:-2]
    xm_p1 = x[2:]
    grad = np.zeros_like(x)
    grad[1:-1] = 200.0 * (xm - xm_m1**2) - 400.0 * (xm_p1 - xm**2) * xm - 2.0 * (1 - xm)
    grad[0] = -400.0 * x[0] * (x[1] - x[0]**2) - 2.0 * (1 - x[0])
    grad[-1] = 200.0 * (x[-1] - x[-2]**2)
    return grad

x0: np.ndarray = np.array([0.5, 0.5])
res: OptimizeResult = minimize(rosen, x0, method='BFGS', jac=rosen_der, options={'disp': True})

print(f"Optimization successful: {res.success}")
print(f"Function value at minimum: {res.fun}")
print(f"Optimal parameters: {res.x}")