derivkit 1.0.0__py3-none-any.whl

derivkit/derivatives/local_polynomial_derivative/diagnostics.py

@@ -0,0 +1,90 @@
+"""Diagnostics for local polynomial derivative estimation."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import numpy as np
+
+from derivkit.derivatives.local_polynomial_derivative.fit import design_matrix
+from derivkit.derivatives.local_polynomial_derivative.local_poly_config import (
+    LocalPolyConfig,
+)
+
+__all = ["make_diagnostics"]
+
+
+def make_diagnostics(
+    x0: float,
+    config: LocalPolyConfig,
+    xs: np.ndarray,
+    ys: np.ndarray,
+    used: np.ndarray,
+    coeffs: np.ndarray,
+    degree: int,
+    order: int,
+    ok: bool,
+) -> Dict[str, Any]:
+    """Builds diagnostics dictionary.
+
+    Args:
+        x0:
+            The center point for polynomial fitting.
+        config:
+            LocalPolyConfig instance with fitting settings.
+        xs:
+            An array of sample points (shape ``(n_samples,)``).
+        ys:
+            An array of function evaluations (shape
+            ``(n_samples, n_components)``).
+        used:
+            A boolean array indicating which samples were used (shape
+            ``(n_samples,)``).
+        coeffs:
+            The polynomial coefficients (shape ``(degree + 1, n_components)``).
+        degree:
+            The degree of the polynomial fit.
+        order:
+            The order of the derivative being estimated.
+        ok:
+            Whether the fit met the residual tolerances.
+
+    Returns:
+        A diagnostics dictionary.
+    """
+    used_x = xs[used]
+    used_y = ys[used]
+
+    if used_x.size:
+        mat = design_matrix(x0, config, used_x, degree)
+        y_fit = mat @ coeffs
+        denom = np.maximum(np.abs(used_y), config.tol_abs)
+        err = np.abs(y_fit - used_y) / denom
+        max_err = float(err.max())
+    else:
+        max_err = float("nan")
+
+    diag: Dict[str, Any] = {
+        "ok": bool(ok),
+        "x0": float(x0),
+        "degree": int(degree),
+        "order": int(order),
+        "n_all": int(xs.size),
+        "n_used": int(used.sum()),
+        "x_used": used_x.tolist(),
+        "max_rel_err_used": max_err,
+        "tol_rel": float(config.tol_rel),
+        "tol_abs": float(config.tol_abs),
+        "min_samples": int(config.min_samples),
+        "max_trim": int(config.max_trim),
+        "center": bool(config.center),
+        "coeffs": coeffs.tolist(),
+    }
+
+    if not ok:
+        diag["note"] = (
+            "No interval fully satisfied residual tolerances; derivative is taken "
+            "from the last polynomial fit and should be treated with caution."
+        )
+
+    return diag

derivkit/derivatives/local_polynomial_derivative/fit.py

@@ -0,0 +1,199 @@
+"""Local polynomial fitting with outlier trimming."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from derivkit.derivatives.local_polynomial_derivative.local_poly_config import (
+    LocalPolyConfig,
+)
+
+__all__ = [
+    "design_matrix",
+    "trimmed_polyfit",
+    "centered_polyfit_least_squares",
+]
+
+
+def design_matrix(
+        x0: float,
+        config: LocalPolyConfig,
+        sample_points: np.ndarray,
+        degree: int) -> np.ndarray:
+    """Builds a Vandermonde design matrix.
+
+    This method constructs the Vandermonde matrix for polynomial fitting based
+    on whether centering around x0 is specified in the config.
+
+    Args:
+        x0:
+            The center point for polynomial fitting.
+        config:
+            LocalPolyConfig instance with fitting settings.
+        sample_points:
+            An array of sample points (shape ``(n_samples,)``).
+        degree:
+            The degree of the polynomial to fit.
+
+    Returns:
+        A Vandermonde matrix (shape ``(n_samples, degree + 1)``).
+    """
+    if config.center:
+        z = sample_points - x0
+    else:
+        z = sample_points
+    return np.vander(z, N=degree + 1, increasing=True)
+
+
+def trimmed_polyfit(
+    x0: float,
+    config: LocalPolyConfig,
+    xs: np.ndarray,
+    ys: np.ndarray,
+    degree: int,
+) -> tuple[np.ndarray, np.ndarray, bool]:
+    """Returns a polynomial fit with trimmed outliers.
+
+    This method fits a polynomial of the specified degree to the provided samples
+    and iteratively removes sample points whose residuals exceed the configured
+    tolerances. Trimming continues until either all residuals are within tolerance
+    or the maximum number of trims is reached. If trimming can no longer proceed
+    without violating the minimum sample requirement, the last valid fit is
+    returned.
+
+    Args:
+        x0:
+            The center point for polynomial fitting.
+        config:
+            LocalPolyConfig instance with fitting settings.
+        xs:
+            An array of sample points (shape ``(n_samples,)``).
+        ys:
+            An array of function evaluations (shape
+            ``(n_samples, n_components)``).
+        degree:
+            The degree of the polynomial to fit.
+
+    Returns:
+        coeffs:
+            The fitted polynomial coefficients. Each column corresponds to
+            one output component of ``ys``, and row ``k`` contains the
+            coefficient of the ``x^k`` term (or ``(x−x0)^k`` if centering is
+            enabled).
+        used_mask:
+            A boolean array indicating which sample points were kept after
+            trimming. ``True`` means the point was used in the final fit.
+        ok:
+            ``True`` if, after trimming, all remaining sample points satisfied
+            the residual tolerances defined in ``config``. ``False`` means the
+            loop stopped due to hitting trimming limits or minimum-sample
+            constraints.
+    """
+    n_samples, n_comp = ys.shape
+    keep = np.ones(n_samples, dtype=bool)
+    n_trim = 0
+
+    last_coeffs = None
+    last_keep = keep.copy()
+    last_ok = False
+
+    needed = max(config.min_samples, degree + 1)
+
+    while keep.sum() >= needed and n_trim <= config.max_trim:
+        idx = np.where(keep)[0]
+        x_use = xs[idx]
+        y_use = ys[idx]
+
+        mat = design_matrix(x0, config, x_use, degree)
+        coeffs, *_ = np.linalg.lstsq(mat, y_use, rcond=None)
+
+        y_fit = mat @ coeffs
+        denom = np.maximum(np.abs(y_use), config.tol_abs)
+        err = np.abs(y_fit - y_use) / denom
+
+        bad_rows = (err > config.tol_rel).any(axis=1)
+        if not bad_rows.any():
+            last_coeffs = coeffs
+            last_keep = keep.copy()
+            last_ok = True
+            break
+
+        bad_idx_all = idx[bad_rows]
+        leftmost, rightmost = idx[0], idx[-1]
+        trimmed = False
+
+        # shave edges only if we keep enough for this degree
+        if bad_idx_all[0] == leftmost and keep.sum() - 1 >= needed:
+            keep[leftmost] = False
+            trimmed = True
+        if bad_idx_all[-1] == rightmost and keep.sum() - 1 >= needed:
+            keep[rightmost] = False
+            trimmed = True
+
+        if not trimmed:
+            last_coeffs = coeffs
+            last_keep = keep.copy()
+            last_ok = False
+            break
+
+        last_coeffs = coeffs
+        last_keep = keep.copy()
+        last_ok = False
+        n_trim += 1
+
+    if last_coeffs is None:
+        last_coeffs = np.zeros((degree + 1, n_comp), dtype=float)
+        last_keep = keep.copy()
+        last_ok = False
+
+    return last_coeffs, last_keep, last_ok
+
+
+def centered_polyfit_least_squares(
+    x0: float,
+    xs: np.ndarray,
+    ys: np.ndarray,
+    degree: int,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Calculates a plain least-squares polynomial fit in powers of (x - x0).
+
+    Args:
+        x0: Expansion point.
+        xs: Sample locations (1D array-like).
+        ys: Sample values (shape ``(n_samples,)`` or ``(n_samples, n_comp)``).
+        degree: Polynomial degree.
+
+    Returns:
+        A tuple containing
+
+            - An array of shape ``(degree+1, n_comp)`` with coefficients for
+              :math:`sum_k a_k (x - x0)^k`.
+            - A boolean mask of length ``n_samples`` (all ``True`` here).
+            - An array of shape ``(degree+1, n)``.
+    """
+    xs = np.asarray(xs, dtype=float)
+    ys = np.asarray(ys)
+
+    if ys.ndim == 1:
+        ys = ys[:, None]
+
+    t = xs - x0
+    vander = np.vander(t, N=degree + 1, increasing=True)  # (n_samples, degree+1)
+
+    coeffs, *_ = np.linalg.lstsq(vander, ys, rcond=None)
+    used_mask = np.ones(xs.shape[0], dtype=bool)
+
+    y_fit = vander @ coeffs
+    residuals = y_fit - ys  # (n_samples, n_comp)
+    n_samples = vander.shape[0]
+    n_params = degree + 1
+    dof = max(n_samples - n_params, 1)
+
+    sigma2 = np.sum(residuals ** 2, axis=0) / dof  # shape (n_comp,)
+
+    xtx_inv = np.linalg.inv(vander.T @ vander)  # (p, p)
+    diag_xtx_inv = np.diag(xtx_inv)[:, None]  # (p, 1)
+
+    coeff_std = np.sqrt(diag_xtx_inv * sigma2[None, :])
+
+    return coeffs, used_mask, coeff_std

derivkit/derivatives/local_polynomial_derivative/local_poly_config.py

@@ -0,0 +1,95 @@
+"""Configuration for the local polynomial regression baseline.
+
+This config controls how
+:class:`derivkit.local_polynomial_derivative.local_polynomial_derivative.LocalPolynomialDerivative`
+chooses sample locations, fits the local polynomial, and decides whether the
+fit is trustworthy enough to mark ``ok=True`` in diagnostics.
+"""
+
+from __future__ import annotations
+
+
+class LocalPolyConfig:
+    """Configuration for the local polynomial regression baseline.
+
+    This config controls how
+    :class:`derivkit.local_polynomial_derivative.local_polynomial_derivative.LocalPolynomialDerivative`
+    chooses sample locations, fits the local polynomial, and decides whether the
+    fit is trustworthy enough to mark ``ok=True`` in diagnostics.
+    """
+
+    def __init__(
+        self,
+        rel_steps=(0.01, 0.02, 0.04, 0.08),
+        tol_rel: float = 0.01,
+        tol_abs: float = 1e-10,
+        min_samples: int = 9,
+        max_trim: int = 10,
+        max_degree: int = 7,
+        center: bool = True,
+    ):
+        """Initialize configuration.
+
+        Args:
+            rel_steps:
+                Symmetric relative offsets around ``x0`` used to build the
+                default sample grid.
+
+                - For ``x0 != 0`` the grid is
+                  ``x = x0 * (1 ± rel_steps[i])``.
+                - For ``x0 == 0`` the grid is
+                  ``x = ± rel_steps[i]``.
+
+                Values are deduplicated and sorted; must be a non-empty
+                1D sequence.
+
+            tol_rel:
+                Relative residual tolerance used when deciding whether a
+                sample row is consistent with the current polynomial fit.
+                A row is flagged as "bad" if any component satisfies
+                ``|y_fit - y| / max(|y|, tol_abs) > tol_rel``.
+                Lower values make trimming more aggressive.
+
+            tol_abs:
+                Absolute floor in the residual normalization. Prevents
+                division by very small ``|y|`` when computing relative
+                errors. Used as
+                ``denom = max(|y|, tol_abs)``.
+
+            min_samples:
+                Minimum number of sample points that must remain after
+                trimming for a fit to be considered. Also used (together
+                with ``max_degree``) to ensure the system is not
+                underdetermined. If trimming would reduce the usable
+                samples below this threshold, trimming stops.
+
+            max_trim:
+                Maximum number of trimming iterations. Each iteration may
+                remove at most one point from each edge of the grid.
+                Acts as a safety bound to avoid pathological loops on
+                extremely noisy or adversarial data.
+
+            max_degree:
+                Maximum polynomial degree allowed for the local fit.
+                The actual degree used in :meth:`differentiate` is
+                ``min(max_degree, chosen_degree)`` where
+                ``chosen_degree`` is usually ``max(order + 2, 3)`` or an
+                explicit ``degree=`` passed by the caller.
+
+            center:
+                If ``True``, the polynomial is expressed in powers of
+                ``(x - x0)``; derivatives at ``x0`` are then read off as
+                ``k! * a_k``. If ``False``, the polynomial is in powers
+                of ``x`` directly. Centering generally improves numerical
+                stability and is recommended.
+
+        """
+        # Normalize to a sorted, deduplicated tuple of floats
+        self.rel_steps = tuple(float(s) for s in rel_steps)
+
+        self.tol_rel = tol_rel
+        self.tol_abs = tol_abs
+        self.min_samples = min_samples
+        self.max_trim = max_trim
+        self.max_degree = max_degree
+        self.center = center

derivkit/derivatives/local_polynomial_derivative/local_polynomial_derivative.py

@@ -0,0 +1,205 @@
+"""Local polynomial-regression derivative estimator."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable
+
+import numpy as np
+
+from derivkit.derivatives.local_polynomial_derivative.diagnostics import (
+    make_diagnostics,
+)
+from derivkit.derivatives.local_polynomial_derivative.fit import (
+    centered_polyfit_least_squares,
+    trimmed_polyfit,
+)
+from derivkit.derivatives.local_polynomial_derivative.local_poly_config import (
+    LocalPolyConfig,
+)
+from derivkit.derivatives.local_polynomial_derivative.sampling import (
+    build_samples,
+)
+from derivkit.utils.numerics import relative_error
+
+
+class LocalPolynomialDerivative:
+    """Estimates derivatives via trimmed local polynomial regression around x0."""
+
+    def __init__(
+        self,
+        func: Callable[[float], Any],
+        x0: float,
+        config: LocalPolyConfig | None = None,
+    ):
+        """Initializes the LocalPolynomialDerivative instance.
+
+        Args:
+            func:
+                Function to differentiate. It should take a float and return either
+                a scalar or a NumPy array (vector or tensor); derivatives are
+                computed componentwise with the same output shape.
+            x0:
+                The point at which to estimate the derivative.
+            config:
+                An optional :class:`derivkit.local_polynomial_derivative.local_poly_config.LocalPolyConfig`
+                instance with configuration settings.
+        """
+        self.func = func
+        self.x0 = float(x0)
+        self.config = config or LocalPolyConfig()
+
+    def differentiate(
+        self,
+        order: int = 1,
+        degree: int | None = None,
+        n_workers: int = 1,
+        return_error: bool = False,
+        diagnostics: bool = False,
+    ):
+        """Local polynomial-regression derivative estimator.
+
+        This class estimates derivative at ``x0`` by sampling the function in a
+        small neighborhood around that point, fitting a polynomial to those samples,
+        and trimming away samples whose residuals are inconsistent with the fit.
+        Once a stable local polynomial is obtained, the k-th derivative is read off
+        directly from the coefficient of the fitted polynomial (``k! * a_k``). The
+        method works for scalar or vector/tensor-valued functions, and can optionally return
+        a diagnostics dictionary showing which samples were used, how trimming
+        behaved, and whether the final fit passed all internal checks.
+
+        Args:
+            order: The order of the derivative to estimate (must be >= 1).
+            degree: The degree of the polynomial fit. If ``None``, it is set to
+                ``max(order + 2, 3)`` but capped by ``self.config.max_degree``.
+            n_workers: The number of parallel workers for function evaluation
+                (must be >= 1).
+            return_error: If ``True``, also returns a relative error estimate
+                based on the disagreement between trimmed and least-squares fits.
+            diagnostics: If ``True``, returns a diagnostics dictionary along with
+                the derivative estimate.
+
+        Returns:
+            The return type depends on ``return_error`` and ``diagnostics``:
+
+            - If ``return_error`` is False and ``diagnostics`` is False:
+              the estimated derivative (float or np.ndarray).
+            - If ``return_error`` is True and ``diagnostics`` is False:
+              ``(derivative, error)``.
+            - If ``return_error`` is False and ``diagnostics`` is True:
+              ``(derivative, diagnostics_dict)``.
+            - If both ``return_error`` and ``diagnostics`` are True:
+              ``(derivative, error, diagnostics_dict)``.
+
+        Raises:
+            ValueError:
+                If order < 1, n_workers < 1, or degree < order.
+        """
+        if order < 1:
+            raise ValueError(f"order must be at least 1 but is {order}.")
+        if n_workers < 1:
+            raise ValueError(f"n_workers must be at least 1 but is {n_workers}.")
+
+        # Choose polynomial degree with a bit of headroom.
+        if degree is None:
+            degree = max(order + 2, 3)
+        degree = int(min(degree, self.config.max_degree))
+        if degree < order:
+            raise ValueError("degree must be >= order.")
+
+        xs, ys = build_samples(self.func, self.x0, self.config, n_workers=n_workers)
+
+        # First, try the trimmed fit
+        coeffs_trim, used_mask_trim, ok = trimmed_polyfit(
+            self.x0, self.config, xs, ys, degree
+        )
+
+        # Always compute LS fit as a backup / cross-check
+        coeffs_ls, used_mask_ls, coeff_std_ls = centered_polyfit_least_squares(
+            self.x0, xs, ys, degree
+        )
+
+        # Decide which coefficients to trust
+        if not ok:
+            # Trimmed fit failed -> trust LS and estimate error from LS statistics.
+            coeffs = coeffs_ls
+            used_mask = used_mask_ls
+            fit_type = "least_squares"
+
+            factorial = math.factorial(order)
+            a_k_ls = coeffs_ls[order]  # shape (n_comp,)
+            sigma_ak = coeff_std_ls[order]  # shape (n_comp,)
+
+            deriv_ls = factorial * a_k_ls
+            sigma_deriv = factorial * sigma_ak
+
+            tiny = np.finfo(float).tiny  # this avoids division by zero
+            err = np.abs(sigma_deriv) / np.maximum(np.abs(deriv_ls), tiny)
+        else:
+            # Both fits available -> compare their implied derivatives
+            coeffs_trim = np.asarray(coeffs_trim)
+            coeffs_ls = np.asarray(coeffs_ls)
+            if coeffs_trim.ndim == 1:
+                coeffs_trim = coeffs_trim[:, None]
+            if coeffs_ls.ndim == 1:
+                coeffs_ls = coeffs_ls[:, None]
+
+            # Derivative from trimmed fit
+            deriv_trim = math.factorial(order) * coeffs_trim[order]
+            # Derivative from LS fit
+            deriv_ls = math.factorial(order) * coeffs_ls[order]
+
+            err = relative_error(deriv_trim, deriv_ls)
+            # Tolerance can be tuned; keep it modest so polynomials/sin pass.
+            rel_err_tol = 1e-3
+
+            if err <= rel_err_tol:
+                coeffs = coeffs_trim
+                used_mask = used_mask_trim
+                fit_type = "trimmed"
+            else:
+                coeffs = coeffs_ls
+                used_mask = used_mask_ls
+                fit_type = "least_squares"
+
+        coeffs = np.asarray(coeffs)
+        if coeffs.ndim == 1:
+            coeffs = coeffs[:, None]
+
+        n_comp = coeffs.shape[1]
+        factorial = math.factorial(order)
+        a_k = coeffs[order]
+        deriv = factorial * a_k
+        deriv_out = float(deriv[0]) if n_comp == 1 else deriv
+
+        # Make error output shape match the derivative shape
+        err_arr = np.asarray(err)
+        if n_comp == 1 and err_arr.ndim > 0:
+            err_out = float(err_arr[0])
+        else:
+            err_out = err_arr
+
+        if diagnostics:
+            diag = make_diagnostics(
+                self.x0,
+                self.config,
+                xs,
+                ys,
+                used_mask,
+                coeffs,
+                degree,
+                order,
+                ok,
+            )
+            diag["n_workers"] = int(n_workers)
+            diag["fit_type"] = fit_type
+
+            if return_error:
+                return deriv_out, err_out, diag
+            return deriv_out, diag
+
+        # diagnostics is False
+        if return_error:
+            return deriv_out, err_out
+
+        return deriv_out

derivkit/derivatives/local_polynomial_derivative/sampling.py

@@ -0,0 +1,72 @@
+"""Sampling utilities for local polynomial derivative estimation."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable
+
+import numpy as np
+
+from derivkit.derivatives.local_polynomial_derivative.local_poly_config import (
+    LocalPolyConfig,
+)
+
+__all__ = ["build_samples"]
+
+
+def build_samples(
+    func: Callable[[float], Any],
+    x0: float,
+    config: LocalPolyConfig,
+    n_workers: int = 1,
+):
+    """Builds sample points for a function around a central value.
+
+    Args:
+        func:
+            Function to evaluate. Takes a float and returns a scalar or
+            np.ndarray.
+        x0:
+            Point around which to sample.
+        config:
+            LocalPolyConfig instance with sampling settings.
+        n_workers:
+            Number of parallel workers for function evaluation.
+
+    Returns:
+        xs: An array of sample points (shape ``(n_samples,)``).
+        ys: An array of function evaluations (shape ``(n_samples, n_components)``).
+
+    Raises:
+        ValueError:
+            if rel_steps in config is not a 1D non-empty sequence of floats.
+    """
+    rel_steps = np.asarray(config.rel_steps, float)
+    if rel_steps.ndim != 1 or rel_steps.size == 0:
+        raise ValueError("rel_steps must be a 1D non-empty sequence of floats.")
+
+    if np.isscalar(rel_steps):
+        rel_steps = np.array([rel_steps], dtype=float)
+
+    if x0 == 0.0:
+        xs = np.concatenate([-rel_steps, rel_steps])
+    else:
+        xs = x0 * (1.0 + np.concatenate([-rel_steps, rel_steps]))
+
+    xs = np.unique(xs)
+    xs.sort()
+
+    if n_workers == 1:
+        ys_list = [np.atleast_1d(func(float(x))) for x in xs]
+    else:
+        def _eval_one(x):
+            return np.atleast_1d(func(float(x)))
+
+        with ThreadPoolExecutor(max_workers=n_workers) as ex:
+            ys_list = list(ex.map(_eval_one, xs))
+
+    ys = np.stack(ys_list, axis=0)
+    if ys.ndim != 2:
+        ys = ys.reshape(ys.shape[0], -1)
+
+    return xs, ys

derivkit/derivatives/tabulated_model/__init__.py

@@ -0,0 +1 @@
+"""Tabulate module for formatting data in tables."""