derivkit 1.0.0__py3-none-any.whl

derivkit/utils/numerics.py

@@ -0,0 +1,262 @@
+"""Numerical utilities."""
+
+from __future__ import annotations
+
+from typing import Callable, Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from derivkit.utils.logger import derivkit_logger
+
+__all__ = [
+    "central_difference_error_estimate",
+    "relative_error",
+    "evaluate_logprior",
+    "is_in_bounds",
+    "apply_hard_bounds",
+    "sum_terms",
+    "get_index_value",
+    "logsumexp_1d",
+]
+
+
+def central_difference_error_estimate(step_size: float, order: int = 1) -> float:
+    """Computes a general heuristic size of the first omitted term in central-difference stencils.
+
+    Uses the general pattern h^2 / ((order + 1) * (order + 2)) as a
+    rule-of-thumb O(h^2) truncation-error scale.
+
+    Args:
+        step_size: Grid spacing.
+        order: Derivative order (positive integer).
+
+    Returns:
+        Estimated truncation error scale.
+
+    Raises:
+        ValueError: If order is not a positive integer.
+    """
+    if order < 1:
+        raise ValueError("order must be a positive integer.")
+
+    # if order higher than 4 we do not support it, but we can still compute the estimate
+    if order > 4:
+        derivkit_logger.warning(
+            "central_difference_error_estimate called with order > 4,"
+            " which is not supported by finite_difference module.",
+        )
+    return step_size**2 / ((order + 1) * (order + 2))
+
+
+def relative_error(a: np.ndarray, b: np.ndarray) -> float:
+    """Computes the relative error metric between a and b.
+
+    This metric is defined as the maximum over all components of a and b of
+    the absolute difference divided by the maximum of 1.0 and the absolute values of
+    a and b.
+
+    Args:
+        a: First array-like input.
+        b: Second array-like input.
+
+    Returns:
+        The relative error metric as a float.
+    """
+    a = np.asarray(a, dtype=np.float64)
+    b = np.asarray(b, dtype=np.float64)
+    denom = np.maximum(1.0, np.maximum(np.abs(a), np.abs(b)))
+    return float(np.max(np.abs(a - b) / denom))
+
+
+def evaluate_logprior(
+        theta: ArrayLike,
+        logprior: Callable[[NDArray[np.floating]], np.floating] | None,
+) -> np.floating:
+    """Evaluates a user-supplied log-prior callable at ``theta``.
+
+    If ``logprior`` is ``None``, a flat prior is assumed and this returns ``0.0``.
+    If a callable is provided, its output is interpreted as a log-density defined
+    up to an additive constant. Any non-finite output (e.g., ``-np.inf`` or
+    ``np.nan``) is treated as zero probability and mapped to ``-np.inf``.
+
+    Args:
+        theta: Parameter vector at which to evaluate the prior.
+        logprior: Callable returning the log-prior density, or ``None`` to indicate
+            a flat prior.
+
+    Returns:
+        Log-prior value at ``theta`` (finite or ``-np.inf``).
+    """
+    if logprior is None:
+        return np.float64(0.0)
+    v = np.float64(logprior(np.asarray(theta, dtype=np.float64)))
+    return v if np.isfinite(v) else np.float64(-np.inf)
+
+
+def is_in_bounds(
+        theta: NDArray[np.floating],
+        bounds: Sequence[tuple[np.floating | None, np.floating | None]] | None,
+) -> bool:
+    """Checks whether a parameter vector lies within specified bounds.
+
+    If ``bounds`` is ``None``, this returns True by convention so callers can write
+    ``if is_in_bounds(theta, bounds): ...`` without special-casing the absence of bounds.
+
+    Bounds are interpreted component-wise. For each parameter, either side may
+    be unbounded by setting that limit to ``None``.
+
+    Args:
+        theta: Parameter vector to test.
+        bounds: Optional sequence of ``(lower, upper)`` pairs, one per parameter.
+            Use ``None`` for an unconstrained lower or upper limit.
+
+    Returns:
+        A boolean indicating whether all parameters satisfy their bounds
+        (or ``True`` if bounds is ``None``).
+
+    Raises:
+        ValueError: If ``bounds`` is provided and its length does not match ``theta``.
+    """
+    if bounds is None:
+        return True
+    if len(bounds) != theta.size:
+        raise ValueError(f"bounds length {len(bounds)} != theta length {theta.size}")
+
+    result = True
+    for t, (lo, hi) in zip(theta, bounds):
+        if (lo is not None and t < lo) or (hi is not None and t > hi):
+            result = False
+            break
+    return result
+
+
+def apply_hard_bounds(
+        term: Callable[[NDArray[np.floating]], np.floating],
+        *,
+        bounds: Sequence[tuple[np.floating | None, np.floating | None]] | None = None,
+) -> Callable[[NDArray[np.floating]], np.floating]:
+    """Returns a bounded version of a log-density contribution.
+
+    A ``term`` is a callable that returns a scalar log-density contribution
+    and support refers to the region where the density is non-zero.
+
+    This helper enforces a top-hat support region defined by ``bounds``. If
+    ``theta`` lies outside the allowed region, the result is ``-np.inf`` to denote
+    zero probability. If ``theta`` lies inside the region, the provided term is
+    evaluated and any non-finite output is treated as ``-np.inf``.
+
+    Args:
+        term: Callable returning a log-density contribution.
+        bounds: Optional sequence of ``(lower, upper)`` pairs defining the
+            allowed support region.
+
+    Returns:
+        A callable with the same signature as ``term`` that enforces the given
+        bounds, or ``term`` itself if no bounds are provided.
+    """
+    if bounds is None:
+        return term
+
+    def bounded(theta: NDArray[np.floating]) -> np.floating:
+        """Evaluates the bounded log-density term."""
+        th = np.asarray(theta, dtype=np.float64)
+        v = np.float64(-np.inf)
+        if is_in_bounds(th, bounds):
+            v = np.float64(term(th))
+        return v if np.isfinite(v) else np.float64(-np.inf)
+
+    return bounded
+
+
+def sum_terms(
+        *terms: Callable[[NDArray[np.floating]], np.floating]
+) -> Callable[[NDArray[np.floating]], np.floating]:
+    """Constructs a composite log term by summing multiple contributions.
+
+    The returned callable evaluates each provided term at the same parameter
+    vector and adds the results. If any term is non-finite, the composite term
+    evaluates to ``-np.inf``, corresponding to zero probability under the combined
+    density.
+
+    A ``term`` is a callable that returns a scalar log-density contribution
+    and support refers to the region where the density is non-zero.
+
+    Args:
+        *terms: One or more callables, each returning a log-density contribution.
+
+    Returns:
+        A callable that returns the sum of the provided log terms at ``theta``.
+
+    Raises:
+        ValueError: If no terms are provided.
+    """
+    if len(terms) == 0:
+        raise ValueError("sum_terms requires at least one term")
+
+    def summed(theta: NDArray[np.floating]) -> np.floating:
+        """Evaluates the summed log-density terms."""
+        th = np.asarray(theta, dtype=np.float64)
+        total = np.float64(0.0)
+        for f in terms:
+            v = np.float64(f(th))
+            if not np.isfinite(v):
+                return np.float64(-np.inf)
+            total = np.float64(total + v)
+        return total
+
+    return summed
+
+
+def get_index_value(theta: ArrayLike, index: int, *, name: str = "theta") -> float:
+    """Extracts a single parameter value from a 1D parameter vector.
+
+    This helper enforces that ``theta`` is one-dimensional and raises a clear,
+    user-facing error if the requested index is out of bounds. It is intended
+    for simple prior or likelihoods components that act on a single parameter.
+
+    Args:
+        theta: 1D parameter vector.
+        index: Index to extract.
+        name: Name used in error messages.
+
+    Returns:
+        Value at the given index as float.
+
+    Raises:
+        ValueError: If ``theta`` is not 1D.
+        IndexError: If ``index`` is out of bounds.
+    """
+    th = np.asarray(theta, dtype=np.float64)
+    if th.ndim != 1:
+        raise ValueError(f"{name} must be 1D, got shape {th.shape}")
+
+    j = int(index)
+    if j < 0 or j >= th.size:
+        raise IndexError(f"{name} index {j} out of bounds for length {th.size}")
+    return float(th[j])
+
+
+def logsumexp_1d(x: ArrayLike) -> float:
+    """Computes log(sum(exp(x))) for a 1D array using the max-shift identity.
+
+    This implements the common max-shift trick used to reduce overflow/underflow.
+
+    Args:
+        x: 1D array-like values.
+
+    Returns:
+        Value of log(sum(exp(x))) as a float.
+
+    Raises:
+        ValueError: If x is not 1D.
+    """
+    arr = np.asarray(x, dtype=np.float64)
+    if arr.ndim != 1:
+        raise ValueError(f"logsumexp_1d expects a 1D array, got shape {arr.shape}")
+
+    m = float(np.max(arr))
+    if not np.isfinite(m):
+        return m
+
+    return float(m + np.log(np.sum(np.exp(arr - m))))

derivkit/utils/sandbox.py

@@ -0,0 +1,74 @@
+"""Sandbox utilities for experimentation and testing."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+__all__ = [
+    "get_partial_function",
+    "generate_test_function",
+]
+
+
+def get_partial_function(
+    full_function: Callable,
+    variable_index: int,
+    fixed_values: list | np.ndarray,
+) -> Callable:
+    """Returns a single-variable version of a multivariate function.
+
+    A single parameter must be specified by index. All others parameters
+    are held fixed.
+
+    Args:
+        full_function: A function that takes a list of n_parameters
+            parameters and returns a vector of n_observables observables.
+        variable_index: The index of the parameter to treat as the variable.
+        fixed_values: The list of parameter values to use as fixed inputs for
+            all parameters except the one being varied.
+
+    Returns:
+        callable: A function of a single variable, suitable for use in
+            differentiation.
+
+    Raises:
+        ValueError: If ``fixed_values`` is not 1D or if `variable_index`` is out of bounds.
+        TypeError: If ``variable_index`` is not an integer.
+        IndexError: If ``variable_index`` is out of bounds for the size of ``fixed_values``.
+    """
+    fixed_arr = np.asarray(fixed_values, dtype=float)
+    if fixed_arr.ndim != 1:
+        raise ValueError(
+            f"fixed_values must be 1D; got shape {fixed_arr.shape}."
+        )
+    if not isinstance(variable_index, (int, np.integer)):
+        raise TypeError(
+            f"variable_index must be an integer; got {type(variable_index).__name__}."
+        )
+    if variable_index < 0 or variable_index >= fixed_arr.size:
+        raise IndexError(
+            f"variable_index {variable_index} out of bounds for size {fixed_arr.size}."
+        )
+
+    def partial_function(x):
+        params = fixed_arr.copy()
+        params[variable_index] = x
+        return np.atleast_1d(full_function(params))
+
+    return partial_function
+
+
+def generate_test_function(name: str = "sin"):
+    """Return (f, f', f'') tuple for a named test function.
+
+    Args:
+        name: One of {"sin"}; more may be added.
+
+    Returns:
+        Tuple of callables (f, df, d2f) for testing.
+    """
+    if name == "sin":
+        return lambda x: np.sin(x), lambda x: np.cos(x), lambda x: -np.sin(x)
+    raise ValueError(f"Unknown test function: {name!r}")

derivkit/utils/types.py

@@ -0,0 +1,15 @@
+"""Shared typing aliases for DerivKit."""
+
+from __future__ import annotations
+
+from typing import Sequence, TypeAlias
+
+import numpy as np
+from numpy.typing import NDArray
+
+Float: TypeAlias = np.floating
+Array: TypeAlias = NDArray[np.floating]
+FloatArray: TypeAlias = NDArray[np.float64]
+
+ArrayLike1D: TypeAlias = Sequence[float] | NDArray[np.floating]
+ArrayLike2D: TypeAlias = Sequence[Sequence[float]] | NDArray[np.floating]