derivkit 1.0.0__py3-none-any.whl

derivkit/derivatives/adaptive/batch_eval.py

@@ -0,0 +1,179 @@
+"""Batch evaluation utilities for derivative estimation.
+
+Evaluate a user function over a 1D grid with optional parallelism and return
+a 2D array with consistent shape suitable for downstream polynomial fitting
+and diagnostics (e.g., in :class:`adaptive.adaptive_fit.AdaptiveFitDerivative`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from multiprocess import Pool
+
+__all__ = ["eval_function_batch"]
+
+
+def eval_function_batch(
+    function: Callable[[float], Any],
+    xs: np.ndarray,
+    n_workers: int = 1,
+) -> np.ndarray:
+    """Evaluate a function over 1D inputs and return a (n_points, n_comp) float array.
+
+    Evaluates ``function(x)`` for each ``x`` in ``xs``. If ``n_workers > 1``,
+    uses a ``multiprocess.Pool``; otherwise runs serially. Scalars become a single
+    column. For array outputs, this routine coerces to a consistent 2D shape that
+    downstream polynomial-fitting code expects.
+
+    Args:
+      function: Callable mapping a float to a scalar or array-like. Must be
+        picklable if used with multiple processes.
+      xs: 1D array of abscissae.
+      n_workers: If > 1, evaluate in parallel using ``multiprocess.Pool``.
+
+    Returns:
+      np.ndarray: Array of shape ``(n_points, n_comp)`` with dtype ``float``.
+
+    Raises:
+      ValueError: If ``xs`` is not 1D or outputs cannot be coerced consistently.
+
+    Examples:
+      >>> import numpy as np
+      >>> from derivkit.derivatives.adaptive.batch_eval import eval_function_batch
+      >>> def f(x):
+      ...     return np.array([x, x**2])
+      >>> xs = np.linspace(-1.0, 1.0, 5)
+      >>> y = eval_function_batch(f, xs)
+      >>> y.shape
+      (5, 2)
+    """
+    xs = np.asarray(xs, dtype=float)
+    if xs.ndim != 1:
+        raise ValueError(
+            f"eval_function_batch: xs.ndim must be 1 but is {xs.ndim}."
+        )
+
+    ys = (
+        _eval_parallel(function, xs, n_workers)
+        if n_workers > 1
+        else _eval_serial(function, xs)
+    )
+
+    # Convert outputs to a consistent 2D float array (n_points × n_outputs).
+    y = _coerce_stack(ys, n_points=xs.size)
+
+    if not np.all(np.isfinite(y)):
+        pass
+
+    return y
+
+
+def _eval_serial(
+    function: Callable[[float], Any], xs: np.ndarray
+) -> list[np.ndarray]:
+    """Evaluate a function over points serially.
+
+    Args:
+      function: Callable mapping a float to a scalar or array-like.
+      xs: 1D array of x-axis points to evaluate.
+
+    Returns:
+      list[np.ndarray]: One array per input x (each at least 1D).
+    """
+    return [np.atleast_1d(function(float(x))) for x in xs]
+
+
+def _eval_parallel(
+    function: Callable[[float], Any],
+    xs: np.ndarray,
+    n_workers: int,
+) -> list[np.ndarray]:
+    """Evaluate a function over points in parallel using multiprocess.Pool.
+
+    Falls back to the serial path for tiny workloads or if pool creation/execution fails.
+
+    Args:
+      function: Maps a float to a scalar or array-like.
+      xs: 1D points on x-axis to evaluate.
+      n_workers: Desired number of processes.
+
+    Returns:
+      list[np.ndarray]: One 1D array per input, order-preserving.
+    """
+    if n_workers <= 1:
+        return _eval_serial(function, xs)
+
+    # Avoid pool overhead for very small batches.
+    n = max(1, min(int(n_workers), int(xs.size)))
+    if xs.size < max(8, 2 * n):
+        return _eval_serial(function, xs)
+
+    try:
+        with Pool(n) as pool:
+            ys = pool.map(function, xs.tolist())
+    except Exception:
+        # Spawn/pickle/start-method issues → graceful serial fallback.
+        return _eval_serial(function, xs)
+
+    return [np.atleast_1d(y) for y in ys]
+
+
+def _coerce_stack(ys: list[np.ndarray], n_points: int) -> np.ndarray:
+    """Coerce a list of per-point outputs into an (n_points, n_comp) float array.
+
+    The user function may return scalars or arrays of varying shapes. This routine
+    coerces them into a consistent 2D array shape that downstream code expects. The rules are:
+        - scalar → column vector
+        - 1D → row
+        - 2D with a transposed batch (n_comp, n_points) → auto-transpose
+        - higher-D → flattened per row
+
+    Args:
+        ys: List of arrays, one per input point. Each array is at least 1
+            dimensional (scalars become shape (1,)).
+        n_points: Number of input points (length of ys).
+
+    Returns:
+        np.ndarray: Array of shape (n_points, n_comp) with dtype float.
+
+    Raises:
+        ValueError: If outputs cannot be coerced to a consistent shape.
+    """
+    arr = np.asarray(ys, dtype=float)
+
+    # Common cases fast-path
+    if arr.ndim == 1:
+        # all scalars
+        return arr.reshape(n_points, 1)
+    if arr.ndim == 2 and arr.shape[0] == n_points:
+        # already (n_points, n_comp)
+        return arr
+    if arr.ndim == 2 and arr.shape[1] == n_points:
+        # likely (n_comp, n_points) → transpose
+        return arr.T
+
+    # Fallback: stack row-wise and flatten per sample if needed.
+    rows = []
+    for y in ys:
+        y = np.asarray(y, dtype=float)
+        if y.ndim == 0:
+            y = y.reshape(1)
+        elif y.ndim >= 2:
+            y = y.reshape(-1)  # flatten higher-D deterministically
+        rows.append(y)
+    y = np.vstack(rows)
+
+    # Ensure (n_points, n_comp)
+    if y.shape[0] != n_points:
+        # If the function accidentally returned (n_comp, n_points), fix it once more.
+        if y.shape[1] == n_points and y.shape[0] != n_points:
+            y = y.T
+        else:
+            raise ValueError(
+                f"eval_function_batch: cannot coerce outputs to (n_points, n_comp); "
+                f"got shape {y.shape} for n_points={n_points}"
+            )
+    return y

derivkit/derivatives/adaptive/diagnostics.py

@@ -0,0 +1,325 @@
+"""Diagnostics for derivative approximations."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+from numpy.typing import NDArray
+
+from derivkit.derivatives.adaptive.polyfit_utils import assess_polyfit_quality
+from derivkit.utils.logger import derivkit_logger
+
+__all__ = [
+    "format_derivative_diagnostics",
+    "print_derivative_diagnostics",
+    "make_derivative_diag",
+    "fit_is_obviously_bad"
+]
+
+
+def format_derivative_diagnostics(
+    diag: Dict[str, Any],
+    *,
+    meta: Optional[Dict[str, Any]] = None,
+    decimals: int = 4,
+    max_rows: int = 12,
+) -> str:
+    """Format derivative diagnostics into a human-readable string.
+
+    Args:
+      diag: Diagnostics dictionary as returned by
+        :func:`adaptive.diagnostics.make_derivative_diag`.
+      meta: Optional metadata dictionary to include in the output.
+      decimals: Number of decimal places for floating-point numbers.
+      max_rows: Maximum number of rows to display for arrays; larger arrays are truncated.
+
+    Returns:
+      A formatted string summarizing the diagnostics.
+    """
+    if not isinstance(diag, dict):
+        return "‹diagnostics unavailable›"
+
+    x = np.asarray(diag.get("x", []), float)
+    t = np.asarray(diag.get("t", []), float)
+    y = np.asarray(diag.get("y", []), float)
+    degree = diag.get("degree", None)
+
+    step_min = step_max = None
+    if t.size >= 2:
+        dt = np.diff(np.sort(t))
+        step_min = float(np.min(dt))
+        step_max = float(np.max(dt))
+    uniformish = (
+        step_min is not None
+        and step_max is not None
+        and abs(step_max - step_min) <= 1e-12 * max(1.0, step_max)
+    )
+
+    with np.printoptions(precision=decimals, suppress=True):
+        lines = ["=== Derivative Diagnostics ==="]
+        if meta:
+            lines.append("Meta:")
+            wanted = [
+                "x0",
+                "order",
+                "n_points",
+                "spacing",
+                "base_abs",
+                "spacing_resolved",
+                "n_workers",
+                "domain",
+                "mode",
+                "ridge",
+            ]
+            for k in wanted:
+                if k in meta:
+                    lines.append(f"  {k}={meta[k]}")
+            for k, v in meta.items():
+                if k not in wanted:
+                    lines.append(f"  {k}={v}")
+            lines.append("")
+
+        lines += [
+            "Grid:",
+            f"  t offsets (preview): {_preview_1d(t, max_rows)}",
+            f"  u offsets (preview): {_preview_1d(np.asarray(diag.get('u', []), float), max_rows)}",
+            f"  x points  (preview): {_preview_1d(x, max_rows)}",
+        ]
+        if step_min is not None:
+            lines.append(
+                f"step_min={step_min:.{decimals}g}, "
+                f"step_max={step_max:.{decimals}g}, "
+                f"uniformish={uniformish}"
+            )
+        lines.append("")
+
+        lines.append("Samples y (rows correspond to x/t):")
+        lines.append(f"{_preview_2d_rows(y, max_rows)}")
+        lines.append("")
+
+        lines.append("Fit:")
+        lines.append(f"  chosen degree(s): {degree}")
+        rrms = diag.get("rrms", None)
+        if rrms is not None:
+            lines.append(f"  rrms: {rrms}")
+
+        fq = diag.get("fit_quality", None)
+        fs = diag.get("fit_suggestions", None)
+        if isinstance(fq, dict):
+            lines.append("")
+            lines.append("Fit quality:")
+            lines.append(
+                "  rrms_rel={:.2e}, loo_rel={:.2e}, cond_vdm={:.2e}, deriv_rel={:.2e}".format(
+                    fq.get("rrms_rel", float("nan")),
+                    fq.get("loo_rel", float("nan")),
+                    fq.get("cond_vdm", float("nan")),
+                    fq.get("deriv_rel", float("nan")),
+                )
+            )
+            th = fq.get("thresholds", {})
+            if not isinstance(th, dict):
+                th = {}
+            lines.append(
+                "  thresholds: rrms_rel={:.1e}, loo_rel={:.1e}, cond_vdm={:.1e}, deriv_rel={:.1e}".format(
+                    th.get("rrms_rel", float("nan")),
+                    th.get("loo_rel", float("nan")),
+                    th.get("cond_vdm", float("nan")),
+                    th.get("deriv_rel", float("nan")),
+                )
+            )
+            if isinstance(fs, (list, tuple)) and len(fs) > 0:
+                lines.append("  suggestions:")
+                for s in fs:
+                    lines.append(f"    - {s}")
+
+        return "\n".join(lines)
+
+
+def print_derivative_diagnostics(
+    diag: Dict[str, Any], *, meta: Optional[Dict[str, Any]] = None
+) -> None:
+    """Print derivative diagnostics to standard output.
+
+    Args:
+      diag: Diagnostics dictionary as returned by
+        :func:`adaptive.diagnostics.make_derivative_diag`.
+      meta: Optional metadata dictionary to include in the output.
+
+    Returns:
+      None
+    """
+    derivkit_logger.info(format_derivative_diagnostics(diag, meta=meta))
+
+
+def _preview_1d(a: np.ndarray, max_rows: int) -> np.ndarray:
+    """Return a preview of a 1D array, truncating with NaN if too long.
+
+    Args:
+      a: Input 1D array.
+      max_rows: Maximum number of rows to display.
+
+    Returns:
+      A 1D array with at most ``max_rows`` elements, with NaN in the middle if truncated.
+    """
+    a = np.asarray(a)
+    if a.ndim != 1 or a.size <= max_rows:
+        return a
+    k = max_rows // 2
+    return np.concatenate([a[:k], np.array([np.nan]), a[-k:]])
+
+
+def _preview_2d_rows(a: np.ndarray, max_rows: int) -> np.ndarray:
+    """Return a preview of a 2D array by rows.
+
+    The preview is truncated with a NaN row if there are too many elements.
+
+    Args:
+      a: Input 2D array.
+      max_rows: Maximum number of rows to display.
+
+    Returns:
+      A 2D array with at most ``max_rows`` rows, with a NaN row in the middle if truncated.
+    """
+    a = np.asarray(a)
+    if a.ndim != 2 or a.shape[0] <= max_rows:
+        return a
+    k = max_rows // 2
+    return np.vstack([a[:k], np.full((1, a.shape[1]), np.nan), a[-k:]])
+
+
+def make_derivative_diag(
+    *,
+    x: np.ndarray,
+    t: np.ndarray,
+    u: np.ndarray,
+    y: np.ndarray,
+    degree: int | list[int],
+    spacing_resolved: float | None = None,
+    rrms: Optional[NDArray[np.floating]] = None,
+    coeffs: Optional[NDArray[np.floating]] = None,
+    ridge: float | None = None,
+    order: int | None = None,
+) -> dict:
+    """Builds a lightweight diagnostics for a local polynomial derivative fit.
+
+    This assembles the core quantities used in plotting/printing diagnostics and,
+    when enough inputs are provided, augments them with polynomial-fit quality
+    metrics and human-readable suggestions.
+
+    Args:
+        x: Absolute sample locations, shape ``(n_points,)`` where ``n_points`` is the
+            number of grid points where the function was evaluated.
+        t: Offsets relative to ``x0`` (``t = x - x0``), shape ``(n_points,)``.
+        u: Scaled offsets used in the polynomial basis (typically ``u = t / s``),
+           shape ``(n_points,)``.
+        y: Function evaluations at ``x``, shape ``(n_points, n_observables)``.
+        degree: Final polynomial degree used. May be an ``int`` or a per-observable
+            list of ints (length ``n_observables``).
+        spacing_resolved: Resolved spacing descriptor for the default grid (numeric
+            half-width or ``None`` if not applicable).
+        rrms: Relative RMS residuals of the fit, shape ``(n_observables,)`` (optional).
+        coeffs: Polynomial coefficients in the scaled basis, shape ``(deg+1, n_observables)`` (optional).
+        ridge: Ridge regularization strength used in the fit (optional).
+        order: Derivative order of interest (optional).
+
+    Returns:
+        dict: A plain dictionary with fields suited for logging/printing/plotting.
+
+        Always present:
+            - ``"x"`` : ``np.ndarray`` with shape ``(n_points,)``
+            - ``"t"`` : ``np.ndarray`` with shape ``(n_points,)``
+            - ``"u"`` : ``np.ndarray`` with shape ``(n_points,)``
+            - ``"y"`` : ``np.ndarray`` with shape ``(n_points, n_observables)``
+            - ``"degree"`` : ``int`` or ``list[int]``
+
+        Included when available:
+            - ``"spacing_resolved"`` : ``float | None``
+            - ``"rrms"`` : ``np.ndarray`` or ``float``
+
+        Included when quality inputs are provided (``coeffs``, ``ridge``, ``order``):
+            - ``"fit_quality"`` : ``dict`` with keys like ``"rrms_rel"``, ``"loo_rel"``,
+              ``"cond_vdm"``, ``"deriv_rel"``, and a nested ``"thresholds"`` dict.
+            - ``"fit_suggestions"`` : ``list[str]`` with human-readable hints.
+    """
+    out: Dict[str, Any] = {
+        "x": x,
+        "t": t,
+        "u": u,
+        "y": y,
+        "degree": degree,
+    }
+    if spacing_resolved is not None:
+        out["spacing_resolved"] = float(spacing_resolved)
+    if rrms is not None:
+        out["rrms"] = rrms if not (rrms.ndim == 1 and rrms.size == 1) else float(rrms[0])
+
+    have_quality_args = (
+        coeffs is not None
+        and ridge is not None
+        and order is not None
+    )
+    if have_quality_args:
+        metrics, suggestions = assess_polyfit_quality(
+            u=u,
+            y=y,
+            coeffs=coeffs,
+            deg=(degree if isinstance(degree, int) else int(degree[0])),
+            ridge=float(ridge),
+            order=int(order),
+        )
+        out["fit_quality"] = metrics
+        out["fit_suggestions"] = suggestions
+
+    return out
+
+
+def fit_is_obviously_bad(metrics: dict) -> tuple[bool, str]:
+    """Heuristically flag a clearly unstable polynomial fit and return a brief reason.
+
+    This inspects scalar diagnostics (from ``assess_polyfit_quality``) against amplified
+    thresholds. If any metric is far beyond its nominal limit, the fit is flagged.
+
+    Args:
+        metrics: Dictionary with keys like:
+            - ``"rrms_rel"``, ``"loo_rel"``, ``"cond_vdm"``, ``"deriv_rel"``
+            - ``"thresholds"`` : ``dict`` of nominal per-metric thresholds
+
+    Returns:
+        tuple[bool, str]: ``(is_bad, message)`` where:
+            - ``is_bad`` is ``True`` if any metric exceeds its amplified threshold
+              (×5 for ``rrms_rel``, ``loo_rel``, ``deriv_rel``; ×10 for ``cond_vdm``),
+              otherwise ``False``.
+            - ``message`` is a short human-readable summary when ``is_bad`` is ``True``,
+              otherwise ``""``.
+
+    Notes:
+        This is a soft, non-fatal screen for diagnostics/logging. Callers decide how to
+        react (warn, rebuild grid, widen spacing, add samples, increase ridge, etc.).
+    """
+    th = metrics.get("thresholds", {})
+
+    rrms_rel = float(metrics.get("rrms_rel", 0.0))
+    loo_rel = float(metrics.get("loo_rel", 0.0))
+    cond_vdm = float(metrics.get("cond_vdm", 0.0))
+    deriv_rel = float(metrics.get("deriv_rel", 0.0))
+
+    # Only mark as bad when we're off by orders of magnitude vs nominal.
+    is_bad = (
+            rrms_rel > max(10.0 * th.get("rrms_rel", 1e-3), 1e-2)
+            or loo_rel > max(10.0 * th.get("loo_rel", 1e-3), 1e-2)
+            or cond_vdm > max(10.0 * th.get("cond_vdm", 1e8), 1e12)
+            or deriv_rel > max(10.0 * th.get("deriv_rel", 5e-3), 0.1)
+    )
+
+    if not is_bad:
+        return False, ""
+
+    msg = (
+        "Adaptive polynomial fit at this point looks numerically unstable. "
+        f"(rrms_rel={rrms_rel:.2e}, "
+        f"loo_rel={loo_rel:.2e}, "
+        f"cond_vdm={cond_vdm:.2e}, "
+        f"deriv_rel={deriv_rel:.2e})"
+    )
+    return True, msg