fitwise 0.1.0__py3-none-any.whl

fitwise/__init__.py

@@ -0,0 +1,30 @@
+"""fitwise: curve fitting made easy.
+
+One call, one fit, one report you can trust.
+
+>>> import fitwise as fw
+>>> result = fw.fit(fw.models.gaussian, x, y, yerr=dy)  # doctest: +SKIP
+>>> print(result)  # doctest: +SKIP
+"""
+
+from fitwise import models, warnings
+from fitwise.api import fit
+from fitwise.model import CompositeModel, Model
+from fitwise.parameters import Parameter, Parameters
+from fitwise.result import FitResult
+from fitwise.warnings import FitWarning
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CompositeModel",
+    "FitResult",
+    "FitWarning",
+    "Model",
+    "Parameter",
+    "Parameters",
+    "__version__",
+    "fit",
+    "models",
+    "warnings",
+]

fitwise/_typing.py

@@ -0,0 +1,11 @@
+"""Shared type aliases."""
+
+from typing import TypeAlias
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FloatArray: TypeAlias = NDArray[np.float64]
+Bounds: TypeAlias = tuple[float, float]
+
+__all__ = ["ArrayLike", "Bounds", "FloatArray"]

fitwise/_validate.py

@@ -0,0 +1,110 @@
+"""Input validation with error messages that tell the user what to do."""
+
+from __future__ import annotations
+
+import difflib
+import math
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import numpy as np
+
+from fitwise._typing import ArrayLike, Bounds, FloatArray
+
+NanPolicy = Literal["raise", "omit"]
+
+
+@dataclass(frozen=True)
+class FitData:
+    """Validated data of one fit."""
+
+    x: FloatArray
+    y: FloatArray
+    yerr: FloatArray | None
+    n_omitted: int = 0
+
+    @property
+    def n(self) -> int:
+        return len(self.y)
+
+    @property
+    def weights(self) -> FloatArray:
+        """Residual weights ``1/yerr`` (ones without ``yerr``)."""
+        return np.ones_like(self.y) if self.yerr is None else 1.0 / self.yerr
+
+
+def validate_data(
+    x: ArrayLike, y: ArrayLike, yerr: ArrayLike | None, nan_policy: NanPolicy
+) -> FitData:
+    """Convert to float arrays, check shapes and handle non-finite values."""
+    if nan_policy not in ("raise", "omit"):
+        raise ValueError(f"nan_policy must be 'raise' or 'omit', not {nan_policy!r}")
+    xa = np.asarray(x, dtype=float)
+    ya = np.asarray(y, dtype=float)
+    if ya.ndim != 1:
+        raise ValueError(f"y must be one-dimensional, got shape {ya.shape}")
+    if xa.ndim == 0 or xa.shape[0] != ya.shape[0]:
+        raise ValueError(
+            f"x and y must have the same length along the first axis, "
+            f"got x.shape={xa.shape} and y.shape={ya.shape}"
+        )
+
+    ea: FloatArray | None = None
+    if yerr is not None:
+        ea = np.broadcast_to(np.asarray(yerr, dtype=float), ya.shape).copy()
+
+    finite = np.isfinite(ya) & np.isfinite(xa.reshape(len(ya), -1)).all(axis=1)
+    if ea is not None:
+        finite &= np.isfinite(ea)
+    n_bad = int((~finite).sum())
+    if n_bad:
+        if nan_policy == "raise":
+            raise ValueError(
+                f"{n_bad} data point(s) contain NaN or inf in x, y or yerr. "
+                "Clean the data or pass nan_policy='omit' to drop them."
+            )
+        xa, ya = xa[finite], ya[finite]
+        ea = None if ea is None else ea[finite]
+
+    if ea is not None and np.any(ea <= 0):
+        raise ValueError("yerr must be strictly positive; zero uncertainty gives infinite weight")
+    return FitData(xa, ya, ea, n_bad)
+
+
+def check_names(argument: str, given: Iterable[str], known: Iterable[str]) -> None:
+    """Raise a helpful error if ``given`` contains names not in ``known``."""
+    known = list(known)
+    for name in given:
+        if name not in known:
+            hint = difflib.get_close_matches(name, known, n=1)
+            suggestion = f" Did you mean {hint[0]!r}?" if hint else ""
+            raise ValueError(
+                f"Unknown parameter {name!r} in {argument}.{suggestion} "
+                f"Model parameters: {', '.join(known)}"
+            )
+
+
+def as_float(argument: str, name: str, value: Any) -> float:
+    """Convert a user-supplied scalar to float with a clear error."""
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        raise TypeError(f"{argument}[{name!r}] must be a number, got {value!r}") from None
+    return f
+
+
+def normalize_bounds(bounds: Mapping[str, Any] | None) -> dict[str, Bounds]:
+    """Turn ``{name: (lo, hi)}`` with ``None`` for open sides into float pairs."""
+    result: dict[str, Bounds] = {}
+    for name, pair in (bounds or {}).items():
+        try:
+            lo, hi = pair
+        except (TypeError, ValueError):
+            raise TypeError(f"bounds[{name!r}] must be a pair (lo, hi), got {pair!r}") from None
+        lo_f = -math.inf if lo is None else as_float("bounds", name, lo)
+        hi_f = math.inf if hi is None else as_float("bounds", name, hi)
+        if math.isnan(lo_f) or math.isnan(hi_f) or not lo_f < hi_f:
+            raise ValueError(f"bounds[{name!r}] = {pair!r}: need lo < hi")
+        result[name] = (lo_f, hi_f)
+    return result

fitwise/api.py

@@ -0,0 +1,230 @@
+"""The public entry point :func:`fit`."""
+
+from __future__ import annotations
+
+import math
+import warnings
+from collections.abc import Callable, Mapping
+from typing import Any, Literal
+
+import numpy as np
+
+from fitwise._typing import ArrayLike, Bounds
+from fitwise._validate import (
+    FitData,
+    NanPolicy,
+    as_float,
+    check_names,
+    normalize_bounds,
+    validate_data,
+)
+from fitwise.backends import Backend, FitProblem, LeastSquaresBackend
+from fitwise.model import Model, as_model
+from fitwise.result import FitResult, build_result
+
+__all__ = ["fit"]
+
+Method = Literal["auto", "trf", "lm", "linear", "odr", "multistart"]
+
+_PLANNED = {
+    "linear": "0.2",
+    "multistart": "0.2",
+    "odr": "0.3",
+}
+
+
+def fit(
+    model: Model | Callable[..., ArrayLike] | str,
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    yerr: ArrayLike | None = None,
+    xerr: ArrayLike | None = None,
+    p0: Mapping[str, float] | None = None,
+    bounds: Mapping[str, tuple[float | None, float | None]] | None = None,
+    fixed: Mapping[str, float] | None = None,
+    loss: str = "linear",
+    method: Method = "auto",
+    scale_covar: bool | None = None,
+    nan_policy: NanPolicy = "raise",
+) -> FitResult:
+    """Fit a model to data.
+
+    Parameters
+    ----------
+    model : Model or callable
+        A built-in model from :mod:`fitwise.models`, a composition such as
+        ``gaussian + linear``, or a function ``f(x, p1, p2, ...)``.
+    x : array_like
+        Independent variable, shape ``(n,)`` or ``(n, k)``; passed to the model unchanged.
+    y : array_like
+        Measured values, shape ``(n,)``.
+    yerr : float or array_like, optional
+        Absolute one-sigma uncertainties of ``y``. Without ``yerr``, uncertainties are
+        estimated from the scatter of the residuals.
+    xerr : array_like, optional
+        Uncertainties of ``x`` (orthogonal distance regression; planned for 0.3).
+    p0 : dict, optional
+        Starting values ``{name: value}``; override any heuristic per parameter.
+    bounds : dict, optional
+        ``{name: (lo, hi)}``; use ``None`` for an open side.
+    fixed : dict, optional
+        ``{name: value}`` of parameters held constant.
+    loss : str
+        Only ``"linear"`` (ordinary least squares) is supported so far.
+    method : {"auto", "trf", "lm"}
+        Solver. ``"auto"`` currently selects Trust Region Reflective, which also handles
+        bounds; ``"lm"`` is Levenberg–Marquardt without bounds.
+    scale_covar : bool, optional
+        Multiply the covariance by χ²/ndf. Default: ``False`` with ``yerr`` (uncertainties are
+        taken as absolute), ``True`` without.
+    nan_policy : {"raise", "omit"}
+        What to do with non-finite data points.
+
+    Returns
+    -------
+    FitResult
+        Parameters with uncertainties, goodness of fit, warnings and a printable report.
+
+    Examples
+    --------
+    >>> import fitwise as fw
+    >>> x = np.linspace(-5, 5, 101)
+    >>> y = fw.models.gaussian(x, amp=2.0, cen=0.3, sigma=1.1)
+    >>> result = fw.fit(fw.models.gaussian, x, y + 0.01 * np.cos(7 * x))
+    >>> round(result.params["cen"].value, 2)
+    0.3
+    """
+    m = as_model(model)
+    if xerr is not None:
+        raise NotImplementedError(
+            "xerr (orthogonal distance regression) is planned for fitwise 0.3"
+        )
+    if loss != "linear":
+        raise NotImplementedError("robust loss functions are planned for fitwise 0.2")
+    data = validate_data(x, y, yerr, nan_policy)
+
+    names = m.param_names
+    p0_given = dict(p0 or {})
+    fixed_given = dict(fixed or {})
+    bounds_given = normalize_bounds(bounds)
+    for argument, mapping in (("p0", p0_given), ("bounds", bounds_given), ("fixed", fixed_given)):
+        check_names(argument, mapping, names)
+    fixed_values = {n: as_float("fixed", n, v) for n, v in fixed_given.items()}
+    for n, v in fixed_values.items():
+        if not math.isfinite(v):
+            raise ValueError(f"fixed[{n!r}] must be finite, got {v}")
+        for argument, mapping in (("p0", p0_given), ("bounds", bounds_given)):
+            if n in mapping:
+                raise ValueError(f"parameter {n!r} is fixed and must not appear in {argument}")
+
+    free = [n for n in names if n not in fixed_values]
+    if not free:
+        raise ValueError("all parameters are fixed; there is nothing to fit")
+    if data.n < len(free):
+        raise ValueError(f"{data.n} data points cannot determine {len(free)} free parameters")
+
+    free_bounds = {n: bounds_given.get(n, (-math.inf, math.inf)) for n in free}
+    init, strategies = _initial_values(m, data, free, p0_given, free_bounds)
+    strategies.update(dict.fromkeys(fixed_values, "fixed"))
+    problem = FitProblem(m, data, init, fixed_values, free_bounds)
+    _check_start(problem, strategies)
+
+    backend, reason = _select_backend(method, problem)
+    solved = backend.solve(problem)
+    result = build_result(
+        problem,
+        solved,
+        strategies=strategies,
+        scale_covar=scale_covar,
+        method_reason=reason,
+        options={
+            "p0": p0_given,
+            "bounds": {n: list(b) for n, b in bounds_given.items()},
+            "fixed": fixed_values,
+            "method": method,
+            "scale_covar": scale_covar,
+            "nan_policy": nan_policy,
+            "loss": loss,
+        },
+    )
+    for w in result.warnings:
+        warnings.warn(w, stacklevel=2)
+    return result
+
+
+def _initial_values(
+    model: Model,
+    data: FitData,
+    free: list[str],
+    p0: Mapping[str, Any],
+    bounds: Mapping[str, Bounds],
+) -> tuple[dict[str, float], dict[str, str]]:
+    """Choose starting values by precedence: p0 > signature default > heuristic > fallback."""
+    defaults = model.defaults
+    needs_guess = any(n not in p0 and n not in defaults for n in free)
+    guessed = model._guess_labeled(data.x, data.y) if needs_guess else {}
+
+    init: dict[str, float] = {}
+    strategies: dict[str, str] = {}
+    for n in free:
+        lo, hi = bounds[n]
+        if n in p0:
+            value, strategy = as_float("p0", n, p0[n]), "p0"
+            if not lo <= value <= hi:
+                raise ValueError(f"p0[{n!r}] = {value:g} is outside its bounds ({lo:g}, {hi:g})")
+        elif n in defaults:
+            value, strategy = defaults[n], "signature default"
+        elif n in guessed:
+            value, strategy = guessed[n]
+        else:
+            value, strategy = _fallback(lo, hi), "fallback"
+        if not lo <= value <= hi:
+            value = float(np.clip(value, lo, hi))
+            strategy += " (clipped to bounds)"
+        init[n], strategies[n] = value, strategy
+    return init, strategies
+
+
+def _fallback(lo: float, hi: float) -> float:
+    if math.isfinite(lo) and math.isfinite(hi):
+        return (lo + hi) / 2
+    if math.isfinite(lo):
+        return lo + max(1.0, abs(lo))
+    if math.isfinite(hi):
+        return hi - max(1.0, abs(hi))
+    return 1.0
+
+
+def _check_start(problem: FitProblem, strategies: Mapping[str, str]) -> None:
+    """Fail early with a clear message if the model cannot be evaluated at the start."""
+    n = problem.data.n
+    start = problem.all_params(problem.init)
+    with np.errstate(all="ignore"):
+        model_y = problem.model.eval(problem.data.x, start)
+    try:
+        model_y = np.broadcast_to(model_y, (n,))
+    except ValueError:
+        raise ValueError(
+            f"the model returned an array of shape {np.shape(model_y)}, expected ({n},)"
+        ) from None
+    if not np.all(np.isfinite(model_y)):
+        values = ", ".join(f"{k} = {v:g} ({strategies[k]})" for k, v in start.items())
+        raise ValueError(
+            f"the model is not finite at the starting values {values}. "
+            "Pass better starting values with p0= or restrict parameters with bounds=."
+        )
+
+
+def _select_backend(method: str, problem: FitProblem) -> tuple[Backend, str]:
+    if method == "auto":
+        return LeastSquaresBackend("trf"), "auto"
+    if method == "trf":
+        return LeastSquaresBackend("trf"), "requested"
+    if method == "lm":
+        if problem.has_bounds:
+            raise ValueError("method='lm' does not support bounds; use 'trf' or 'auto'")
+        return LeastSquaresBackend("lm"), "requested"
+    if method in _PLANNED:
+        raise NotImplementedError(f"method={method!r} is planned for fitwise {_PLANNED[method]}")
+    raise ValueError(f"unknown method {method!r}; choose 'auto', 'trf' or 'lm'")

fitwise/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Solver backends behind :func:`fitwise.fit`."""
+
+from fitwise.backends.base import Backend, BackendResult, FitProblem
+from fitwise.backends.least_squares import LeastSquaresBackend
+
+__all__ = ["Backend", "BackendResult", "FitProblem", "LeastSquaresBackend"]

fitwise/backends/base.py

@@ -0,0 +1,103 @@
+"""The contract between :func:`fitwise.fit` and the solver backends.
+
+Every backend receives a normalized :class:`FitProblem` and returns a :class:`BackendResult`.
+:class:`fitwise.FitResult` is built only from these two objects, so all solvers produce
+results with identical structure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import numpy as np
+
+from fitwise._typing import Bounds, FloatArray
+from fitwise._validate import FitData
+from fitwise.model import Model
+
+
+@dataclass(frozen=True)
+class FitProblem:
+    """A fully specified least-squares problem.
+
+    Attributes
+    ----------
+    model, data
+        The model and the validated data.
+    init : dict
+        Starting values of the free parameters, in model order.
+    fixed : dict
+        Values of the fixed parameters.
+    bounds : dict
+        Bounds of the free parameters (``±inf`` if unbounded).
+    """
+
+    model: Model
+    data: FitData
+    init: dict[str, float]
+    fixed: dict[str, float]
+    bounds: dict[str, Bounds]
+
+    @property
+    def free_names(self) -> tuple[str, ...]:
+        """Names of the varied parameters in model order."""
+        return tuple(self.init)
+
+    @property
+    def has_bounds(self) -> bool:
+        """Whether any free parameter has a finite bound."""
+        return any(np.isfinite(b).any() for b in self.bounds.values())
+
+    def all_params(self, free: dict[str, float]) -> dict[str, float]:
+        """Merge free and fixed values into a full parameter dict in model order."""
+        merged = {**free, **self.fixed}
+        return {n: merged[n] for n in self.model.param_names}
+
+    def weighted_residual(self, free: dict[str, float]) -> FloatArray:
+        """``(y - f(x)) / yerr`` (or unweighted without ``yerr``)."""
+        model_y = self.model.eval(self.data.x, self.all_params(free))
+        return (self.data.y - np.broadcast_to(model_y, self.data.y.shape)) * self.data.weights
+
+
+@dataclass(frozen=True)
+class BackendResult:
+    """What a backend reports back.
+
+    Attributes
+    ----------
+    values : dict
+        Best-fit values of the free parameters.
+    cov_unscaled : ndarray or None
+        ``(JᵀJ)⁻¹`` of the weighted residuals, in ``free_names`` order; not multiplied by
+        χ²/ndf. ``None`` if it could not be computed.
+    converged : bool
+        Whether the solver met its convergence criteria.
+    nfev : int
+        Number of model evaluations.
+    message : str
+        The solver's own status message.
+    method : str
+        Human-readable solver description for the report.
+    raw : object
+        The backend's native result object.
+    log : tuple of str
+        Notes about what the backend did, for ``FitResult.solver_log``.
+    """
+
+    values: dict[str, float]
+    cov_unscaled: FloatArray | None
+    converged: bool
+    nfev: int
+    message: str
+    method: str
+    raw: object = None
+    log: tuple[str, ...] = field(default_factory=tuple)
+
+
+class Backend(Protocol):
+    """A solver that turns a :class:`FitProblem` into a :class:`BackendResult`."""
+
+    def solve(self, problem: FitProblem) -> BackendResult:
+        """Solve the problem."""
+        ...

fitwise/backends/least_squares.py

@@ -0,0 +1,145 @@
+"""Nonlinear least squares via :func:`scipy.optimize.least_squares`.
+
+Three measures make this robust on badly scaled problems (see ADR 5):
+
+1. The solver works on normalized parameters ``u = p / s`` with ``s = |p_start|``, so that all
+   parameters are of order one.
+2. The Jacobian uses central (3-point) finite differences. For Levenberg–Marquardt they are
+   computed here, because older scipy versions silently fall back to 2-point for ``lm``.
+3. After convergence, the solver restarts from the solution with fresh normalization until the
+   cost no longer improves.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import partial
+from typing import Literal
+
+import numpy as np
+from scipy.optimize import OptimizeResult, least_squares
+
+from fitwise._typing import FloatArray
+from fitwise.backends.base import BackendResult, FitProblem
+
+_EPS_CBRT = float(np.finfo(float).eps ** (1 / 3))
+
+_DESCRIPTIONS = {
+    "trf": "Trust Region Reflective (scipy least_squares)",
+    "lm": "Levenberg-Marquardt (MINPACK via scipy)",
+}
+
+
+@dataclass(frozen=True)
+class LeastSquaresBackend:
+    """Solve a :class:`FitProblem` with ``scipy.optimize.least_squares``.
+
+    Parameters
+    ----------
+    method : {"trf", "lm"}
+        Trust Region Reflective supports bounds; Levenberg–Marquardt does not.
+    tol : float
+        ``xtol``, ``ftol`` and ``gtol`` of each solver run.
+    max_restarts : int
+        Maximum number of restarts from the current solution.
+    max_nfev : int or None
+        Evaluation limit per solver run; ``None`` uses scipy's default.
+    """
+
+    method: Literal["trf", "lm"] = "trf"
+    tol: float = 1e-15
+    max_restarts: int = 10
+    max_nfev: int | None = None
+
+    def solve(self, problem: FitProblem) -> BackendResult:
+        """Solve the problem, restarting until the cost stops improving."""
+        names = problem.free_names
+        if self.method == "lm" and problem.has_bounds:
+            raise ValueError("Levenberg-Marquardt does not support bounds; use method='trf'")
+        lo = np.array([problem.bounds[n][0] for n in names])
+        hi = np.array([problem.bounds[n][1] for n in names])
+        p = np.array([problem.init[n] for n in names])
+
+        log: list[str] = []
+        best_cost = np.inf
+        result: OptimizeResult | None = None
+        best_scale = _scale(p)
+        nfev = 0
+        for attempt in range(self.max_restarts + 1):
+            scale = _scale(p)
+
+            def residual(u: FloatArray, scale: FloatArray = scale) -> FloatArray:
+                return problem.weighted_residual(dict(zip(names, u * scale, strict=True)))
+
+            # Trial points may overflow; the solver rejects such steps by itself, and the final
+            # result is checked separately, so floating-point warnings here are only noise.
+            with np.errstate(all="ignore"):
+                run = least_squares(
+                    residual,
+                    p / scale,
+                    jac="3-point" if self.method == "trf" else partial(_central_jacobian, residual),
+                    bounds=(lo / scale, hi / scale) if self.method == "trf" else (-np.inf, np.inf),
+                    method=self.method,
+                    xtol=self.tol,
+                    ftol=self.tol,
+                    gtol=self.tol,
+                    max_nfev=self.max_nfev,
+                )
+            nfev += int(run.nfev)
+            cost = 2 * float(run.cost)
+            if result is not None and not cost < best_cost * (1 - 1e-13):
+                log.append(f"restart {attempt}: no further improvement (χ² = {cost:.10g})")
+                break
+            label = "initial run" if attempt == 0 else f"restart {attempt}"
+            log.append(f"{label}: χ² = {cost:.10g}, {run.nfev} evals, status {run.status}")
+            best_cost, result, best_scale = cost, run, scale
+            p = np.clip(run.x * scale, lo, hi)
+
+        assert result is not None
+        values = dict(zip(names, map(float, p), strict=True))
+        cov_u = _covariance(np.asarray(result.jac, dtype=float))
+        cov = None if cov_u is None else cov_u * np.outer(best_scale, best_scale)
+        if cov is None:
+            log.append("Jacobian is rank deficient; covariance not available")
+        return BackendResult(
+            values=values,
+            cov_unscaled=cov,
+            converged=bool(result.success),
+            nfev=nfev,
+            message=str(result.message),
+            method=_DESCRIPTIONS[self.method],
+            raw=result,
+            log=tuple(log),
+        )
+
+
+def _central_jacobian(fun: Callable[[FloatArray], FloatArray], u: FloatArray) -> FloatArray:
+    """Central finite differences with step ``eps^(1/3) * max(1, |u|)`` (no bounds)."""
+    h = _EPS_CBRT * np.maximum(1.0, np.abs(u))
+    columns = []
+    for i, hi in enumerate(h):
+        step = np.zeros_like(u)
+        step[i] = hi
+        columns.append((fun(u + step) - fun(u - step)) / (2 * hi))
+    return np.column_stack(columns)
+
+
+def _scale(p: FloatArray) -> FloatArray:
+    return np.where(np.abs(p) > 0, np.abs(p), 1.0)
+
+
+#: Relative singular value below which the Jacobian counts as rank deficient. Finite-difference
+#: Jacobians of redundant parameters reach ~1e-12; with normalized parameters, the worst
+#: legitimately ill-conditioned NIST problem (Nelson) stays at 3e-6.
+RCOND = 1e-9
+
+
+def _covariance(jac: FloatArray) -> FloatArray | None:
+    """``(JᵀJ)⁻¹`` via SVD; ``None`` if ``J`` is numerically rank deficient."""
+    if jac.size == 0 or not np.all(np.isfinite(jac)):
+        return None
+    _, s, vt = np.linalg.svd(jac, full_matrices=False)
+    if s[-1] <= RCOND * s[0]:
+        return None
+    return np.asarray((vt.T / s**2) @ vt, dtype=float)