derivkit.adaptive.grid module¶

Utility functions for building grids of points.

derivkit.adaptive.grid.chebyshev_offsets(halfwidth: float, n_points: int, include_center: bool = True) → ndarray¶

Generate Chebyshev-distributed offsets within [-halfwidth, halfwidth].

This function generates n_points offsets based on the Chebyshev nodes, which are distributed to minimize interpolation error. The offsets lie within the interval [-halfwidth, halfwidth]. Optionally, the center point 0.0 can be included in the offsets if it is not already present.

Parameters:

halfwidth – Half the width of the interval (>0).
n_points – Number of points to generate (>=1).
include_center – If True, include 0.0 in the offsets if not already present. Default is True.

Returns:

Array of offsets sorted in ascending order.

derivkit.adaptive.grid.ensure_min_samples_and_maybe_rebuild(*, mode: str, x: ndarray, t: ndarray, spacing_resolved: float, sign_used: float | None, x0: float, order: int, n_points: int, spacing: str | float, base_abs: float = 0.001, max_cheby_points: int = 30) → tuple[str, ndarray, ndarray, float, float | None]¶

Guarantee sufficient samples for the requested derivative; rebuild if needed.

Computes the minimum number of samples required for a stable polynomial-fit derivative estimate and, when the current grid is a default Chebyshev grid (indicated by a finite spacing_resolved), rebuilds it with more nodes if necessary. For explicit/physical grids (spacing_resolved is not finite), a deficiency is treated as an error.

The required sample count is:

min_pts = 2 * deg_req + 1, where
deg_req = 2 * order for mode == "sqrt" (due to pullback), else deg_req = order.

Parameters:

mode – Sampling mode, one of "x", "signed_log", or "sqrt".
x – Physical sample locations, shape (n,).
t – Internal offsets used for fitting, shape (n,).
spacing_resolved – Numeric half-width used to generate the Chebyshev grid. Finite implies a default/rebuildable grid; non-finite implies an explicit grid.
sign_used – For "sqrt" mode, the branch sign (+1 or -1); otherwise None.
x0 – Expansion point about which derivatives are computed.
order – Derivative order (>= 1).
n_points – Target number of Chebyshev nodes if a rebuild is performed.
spacing – Half-width control used when rebuilding ("auto", percentage string, or positive float).
base_abs – Absolute fallback scale for resolving spacing near zero. Defaults to 1e-3.
max_cheby_points – Safety cap on Chebyshev node count when rebuilding.

Returns:

A 5-tuple (mode, x_out, t_out, spacing_out, sign_out) with the (possibly) rebuilt grid and associated metadata. The return types mirror the inputs.

Return type:

Tuple[str, np.ndarray, np.ndarray, float, float | None]

Raises:

ValueError – If the grid is explicit (non-finite spacing_resolved) and has fewer than the required samples.
ValueError – If a rebuild would exceed max_cheby_points.
ValueError – If order < 1.

Notes

When rebuilding in "signed_log" or "sqrt" mode, spacing is resolved in the transform coordinate (log/sqrt) space and mapped back to physical x.
The center point is included for Chebyshev grids if not already present.

Build a Chebyshev grid around x0 with optional domain-aware transforms.

This constructs Chebyshev-distributed sample points around x0. If a one-sided domain is supplied, it switches to a transform that respects the domain. When the domain is strictly non-negative or non-positive and x0 == 0, a square-root coordinate centered at the boundary is used. When the domain is single-signed and a symmetric grid around x0 would violate it, a signed-log coordinate is used.

Parameters:

x0 – Expansion point about which to place the grid.
n_points – Number of Chebyshev nodes to generate (center included).
spacing – Sampling half-width control. Accepts "auto", a percentage string such as "2%", or a positive float half-width.
base_abs – Absolute fallback scale used by "auto" (and transforms) near zero.
domain – Optional bounds (lo, hi). Use None for an open end. If the domain is strictly non-negative or non-positive, a domain-aware transform may be applied as described above.
max_cheby_points – Safety cap for the default Chebyshev node count.

Returns:

A 5-tuple: (mode, x, t, spacing_resolved, sign_used). mode is one of "x", "signed_log", or "sqrt". x are physical samples. t are internal offsets in the fit coordinate. spacing_resolved is the numeric half-width actually used. sign_used is +1 or -1 for "sqrt" mode and None otherwise.

Return type:

Tuple[str, np.ndarray, np.ndarray, float, float | None]

Raises:

ValueError – If n_points exceeds max_cheby_points or if spacing cannot be resolved to a positive finite half-width.

Notes

The returned x always respects a one-sided domain. Chebyshev nodes include the center if not already present.

derivkit.adaptive.grid.make_grid(x0: float, *, n_points: int, spacing: str | float | ndarray, base_abs: float | None, need_min: int, use_physical_grid: bool) → tuple[ndarray, ndarray, int, float, str]¶

Unified grid builder.

Parameters:

x0 – expansion point
n_points – number of points to generate (if not use_physical_grid)
spacing – ‘auto’, ‘<pct>%’, numeric > 0, or array of physical sample points (if use_physical_grid)
base_abs – absolute fallback (also used by ‘auto’); if None, uses 1
need_min – minimum number of points required (for validation)
use_physical_grid – if True, spacing is an array of physical sample points

Returns:

array of physical sample points t: offsets (x - x0) n_pts: number of samples spacing_resolved: numeric spacing used (np.nan if physical grid given) direction_used: ‘custom’ if physical grid, else the input direction

Return type:

derivkit.adaptive.grid.make_offsets(n_points: int, base: float, direction: str) → ndarray¶

Construct a grid of offsets around zero, never including 0.

Parameters:

n_points – number of points to generate (>=1)
base – spacing between points (>0)
direction – ‘both’, ‘pos’, or ‘neg’. ‘both’ gives a symmetric grid around 0, ‘pos’ gives points > 0, ‘neg’ gives points < 0.

Returns:

Array of offsets (length n_points), never including 0.