derivkit.adaptive.diagnostics module¶

Diagnostics for derivative approximations.

derivkit.adaptive.diagnostics.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.

Parameters:

metrics – Dictionary with keys like: - "rrms_rel", "loo_rel", "cond_vdm", "deriv_rel" - "thresholds" : dict of nominal per-metric thresholds

Returns:

(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 "".

Return type:

tuple[bool, str]

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.).

derivkit.adaptive.diagnostics.format_derivative_diagnostics(diag: Dict[str, Any], *, meta: Dict[str, Any] | None = None, decimals: int = 4, max_rows: int = 12) → str¶

Format derivative diagnostics into a human-readable string.

Parameters:

diag – Diagnostics dictionary as returned by 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.

derivkit.adaptive.diagnostics.make_derivative_diag(*, x: ndarray, t: ndarray, u: ndarray, y: ndarray, degree: int | list[int], spacing_resolved: float | None = None, rrms: ndarray[tuple[Any, ...], dtype[floating]] | None = None, coeffs: ndarray[tuple[Any, ...], dtype[floating]] | None = 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.

Parameters:

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:

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.

Return type:

dict

derivkit.adaptive.diagnostics.print_derivative_diagnostics(diag: Dict[str, Any], *, meta: Dict[str, Any] | None = None) → None¶

Print derivative diagnostics to standard output.

Parameters:

diag – Diagnostics dictionary as returned by make_derivative_diag.
meta – Optional metadata dictionary to include in the output.

Returns:

None