snuffled 0.1.0__py3-none-any.whl

snuffled/__init__.py

@@ -0,0 +1,12 @@
+from ._core import (
+    Diagnostic,
+    FunctionProperty,
+    NamedArray,
+    PropertyExtractionStats,
+    RootProperty,
+    SnuffledDiagnostics,
+    SnuffledFunctionProperties,
+    SnuffledProperties,
+    SnuffledRootProperties,
+    Snuffler,
+)

snuffled/_core/__init__.py

@@ -0,0 +1,12 @@
+from .analysis import Snuffler
+from .models import (
+    Diagnostic,
+    FunctionProperty,
+    NamedArray,
+    PropertyExtractionStats,
+    RootProperty,
+    SnuffledDiagnostics,
+    SnuffledFunctionProperties,
+    SnuffledProperties,
+    SnuffledRootProperties,
+)

snuffled/_core/analysis/__init__.py

@@ -0,0 +1,2 @@
+from ._function_sampler import FunctionSampler
+from .snuffler import Snuffler

snuffled/_core/analysis/_function_sampler.py

@@ -0,0 +1,257 @@
+import math
+from collections.abc import Callable
+from functools import cache
+
+import numpy as np
+
+from snuffled._core.models.root_analysis import Root
+from snuffled._core.utils.constants import EPS, SEED_OFFSET_FUNCTION_SAMPLER
+from snuffled._core.utils.math import smooth_sign_array
+from snuffled._core.utils.root_finding import find_odd_root
+from snuffled._core.utils.sampling import multi_scale_samples, sample_integers
+
+
+class FunctionSampler:
+    """
+    Class holding (cached) data related to a specific function, shared across different analyses.
+    All the following classes make use of this class to access the data they need for their analyses:
+      - FunctionAnalyser
+      - RootAnalyser
+      - DiagnosticAnalyser
+    """
+
+    # -------------------------------------------------------------------------
+    #  Constructor
+    # -------------------------------------------------------------------------
+    def __init__(
+        self,
+        fun: Callable[[float], float],
+        x_min: float,
+        x_max: float,
+        dx: float,
+        seed: int,
+        n_fun_samples: int = 1_000,
+        n_roots: int = 100,
+        rel_tol_scale: float = 10.0,
+    ):
+        # --- randomization -------------------------------
+        self._seed = seed + SEED_OFFSET_FUNCTION_SAMPLER
+
+        # --- function properties -------------------------
+        self._fun = fun
+        self.x_min = x_min
+        self.x_max = x_max
+
+        # --- settings ------------------------------------
+        self.dx = dx
+        self.n_fun_samples = n_fun_samples
+        self.n_roots = n_roots
+        self.rel_tol = EPS * rel_tol_scale
+
+        # --- cache ---------------------------------------
+        self._fun_cache: dict[float, float] = dict()
+
+    # -------------------------------------------------------------------------
+    #  Low-level generic functionality
+    # -------------------------------------------------------------------------
+    def f(self, x: float | list[float]) -> float | list[float]:
+        # simple cached version of fun(x), without size limit (and simpler than lru_cache, so less overhead)
+        if isinstance(x, list):
+            # --- get MULTIPLE f(x) values ------
+            fx_values = []
+            for single_x in x:
+                if not (self.x_min <= single_x <= self.x_max):
+                    raise ValueError(f"x={single_x} is out of bounds [{self.x_min}, {self.x_max}]")
+                elif single_x not in self._fun_cache:
+                    self._fun_cache[single_x] = fx = self._fun(single_x)
+                else:
+                    fx = self._fun_cache[single_x]
+                fx_values.append(fx)
+            return fx_values
+        else:
+            # --- get SINGLE f(x) values --------
+            if x in self._fun_cache:
+                return self._fun_cache[x]
+            elif self.x_min <= x <= self.x_max:
+                fx = self._fun(x)
+                self._fun_cache[x] = fx
+                return fx
+            else:
+                raise ValueError(f"x={x} is out of bounds [{self.x_min}, {self.x_max}]")
+
+    @cache
+    def x_values(self) -> np.ndarray:
+        """
+        Returns an array of x-values in [x_min, x_max] that we use to sample the function and infer its properties.
+        This is based on the multi_scale_samples function and does not include any other cached x-values resulting
+        from other calls to .f(.)
+        """
+        return multi_scale_samples(
+            x_min=self.x_min,
+            x_max=self.x_max,
+            dx_min=self.dx,
+            n=self.n_fun_samples,
+            seed=self._seed,
+        )
+
+    @cache
+    def fx_values(self) -> np.ndarray:
+        """f(x) values corresponding to the x_values()."""
+        return np.array(self.f(list(self.x_values())), dtype=np.float64)
+
+    def function_cache(self) -> list[tuple[float, float]]:
+        """
+        Returns contents of the function cache as a list of (x, f(x))-tuples.
+        Note this might return more information than .x_values() and .fx_values(), since those methods
+        only return information related to the initial multiscale sampling.
+        """
+        return list(self._fun_cache.items())
+
+    def function_cache_size(self) -> int:
+        """Return number of values in function cache."""
+        return len(self._fun_cache)
+
+    @cache
+    def fx_diff_values(self) -> np.ndarray:
+        return np.diff(self.fx_values())
+
+    @cache
+    def fx_quantile(self, q: float, absolute: bool) -> float:
+        """
+        Returns the requested quantile f(x).
+            absolute==False    --> quantile of f(x)
+            absolute==True     --> quantile of abs(f(x))
+        """
+        if absolute:
+            return float(np.quantile(abs(self.fx_values()), q))
+        else:
+            return float(np.quantile(self.fx_values(), q))
+
+    @cache
+    def robust_estimated_fx_max(self) -> float:
+        """
+        Robust, approximate estimate of max(f(x)), without being susceptible to single-sample outliers, which might
+        arise in certain corner cases.
+
+        NOTE: this value is not guaranteed to be equal or larger than abs(f(x)), but should provide a reasonable
+              estimate under most regular circumstances.
+        """
+        q = 1 - (1 / math.sqrt(self.n_fun_samples))
+        return (1 / q) * self.fx_quantile(q, absolute=True)
+
+    # -------------------------------------------------------------------------
+    #  Specialized - Tolerances
+    # -------------------------------------------------------------------------
+    @cache
+    def tol_array_local(self) -> np.ndarray:
+        """
+        Return (n_fun_samples, )-sized array with absolute tolerance values > 0, representing the LOCAL tolerance wrt
+        numerical rounding errors on a LOCAL per-sample basis, i.e. computed based on the magnitude of each f(x) sample.
+        """
+        return self.rel_tol * abs(self.fx_values())
+
+    @cache
+    def tol_array_global(self) -> np.ndarray:
+        """
+        Return (n_fun_samples, )-sized array with absolute tolerance values > 0, representing the GLOBAL tolerance wrt
+        numerical rounding errors on a GLOBAL basis, i.e. computed based on the overall (~maximum) magnitude of f(x).
+        This is a constant matrix.
+        """
+        return np.full(self.n_fun_samples, self.rel_tol * self.robust_estimated_fx_max())
+
+    @cache
+    def fx_diff_smooth_sign(self) -> np.ndarray:
+        """
+        Returns an array with elements in [-1,+1] representing a more nuanced np.sign(np.diff(fx_values())).
+
+        Local and global tolerances are used to determine the threshold around which differences transition
+        (smoothly) from 0 to 1 or 0 to -1.
+
+        See also smooth_sign().
+        """
+
+        # determine inner_tol, outer_tol
+        tol_global = self.tol_array_global()
+        tol_local = self.tol_array_local()
+
+        inner_tol = np.minimum(tol_local, tol_global)  # make sure inner_tol[i] is the smallest of both tolerances
+        outer_tol = np.maximum(tol_local, tol_global)  # make sure outer_tol[i] is the largest of both tolerances
+
+        # reduce to size n-1 from size n  (take sum)
+        inner_tol = inner_tol[1:] + inner_tol[:-1]  # take sum of both tolerances
+        outer_tol = outer_tol[1:] + outer_tol[:-1]  # take sum of both tolerances
+
+        # compute smooth_sign
+        return smooth_sign_array(
+            x=self.fx_diff_values(),
+            inner_tol=inner_tol,
+            outer_tol=outer_tol,
+        )
+
+    # -------------------------------------------------------------------------
+    #  Specialized - Roots
+    # -------------------------------------------------------------------------
+    @cache
+    def candidate_root_intervals(self) -> tuple[list[tuple[float, float]], list[tuple[float, float]]]:
+        """
+        Return a list of 'root intervals' and 'non-root intervals', with the root intervals serving as candidates
+        (but potentially too many) for root finding.
+        :return: (root_intervals, non_root_intervals)-tuple
+                    root_intervals      : list of (x_left, x_right)-tuples   WITH    sign flip
+                    non_root_intervals  : list of (x_left, x_right)-tuples   WITHOUT sign flip
+        """
+
+        # multi-scale samples as (x, fx)-tuples
+        samples = list(zip(self.x_values(), self.fx_values()))
+
+        # remove 0-valued samples, we are looking for strict sign flips
+        samples = [(x, fx) for i, (x, fx) in enumerate(samples) if (fx != 0.0)]
+
+        # split in root- and non-root-intervals
+        root_intervals = []
+        non_root_intervals = []
+        for (x_left, fx_left), (x_right, fx_right) in zip(samples[:-1], samples[1:]):
+            if np.sign(fx_left) != np.sign(fx_right):
+                # sign flip
+                root_intervals.append((x_left, x_right))
+            else:
+                # no sign flip
+                non_root_intervals.append((x_left, x_right))
+
+        # we're done
+        return root_intervals, non_root_intervals
+
+    @cache
+    def roots(self) -> list[Root]:
+        """
+        Returns at most 'n_roots' root intervals [root_min, root_max] obtained using find_root_and_width().
+        We start from the candidate_root_intervals and - if needed - sample 'n_roots' intervals randomly
+        to if there are too many candidate intervals.
+        :return: list of Root objects, with deriv_sign != 0.
+        """
+
+        # get intervals
+        cand_intervals, _ = self.candidate_root_intervals()
+
+        # sample if needed
+        if len(cand_intervals) > self.n_roots:
+            cand_intervals = [
+                cand_intervals[i]
+                for i in sample_integers(
+                    i_min=0,
+                    i_max=len(cand_intervals),
+                    n=self.n_roots,
+                    seed=self._seed,
+                )
+            ]
+
+        # compute roots & return
+        return [
+            find_odd_root(
+                fun=self.f,
+                x_min=x_min,
+                x_max=x_max,
+                dx_min=(EPS * EPS) * (self.x_max - self.x_min),
+            )
+            for x_min, x_max in cand_intervals
+        ]

snuffled/_core/analysis/_property_extractor.py

@@ -0,0 +1,75 @@
+from abc import ABC, abstractmethod
+from time import perf_counter_ns, time_ns
+from typing import Generic, TypeVar
+
+from snuffled._core.models import NamedArray, PropertyExtractionStats
+
+from ._function_sampler import FunctionSampler
+
+NA = TypeVar("NA", bound=NamedArray)
+
+
+class PropertyExtractor(ABC, Generic[NA]):
+    # =================================================================================================
+    #  Main API
+    # =================================================================================================
+    def __init__(self, function_sampler: FunctionSampler):
+        self.function_sampler = function_sampler
+        self.__stats: dict[str, PropertyExtractionStats] = dict()  # property -> stats
+
+    def supported_properties(self) -> list[str]:
+        """Return list of all supported properties, in order in which they should be extracted by extract_all"""
+        return self._new_named_array().names()
+
+    def extract_all(self) -> NA:
+        """Extract all properties and returned as specific NamedArray subclass."""
+        named_array = self._new_named_array()
+        for property_name in self.supported_properties():
+            named_array[property_name] = self.extract(property_name)
+        return named_array
+
+    def extract(self, prop: str) -> float:
+        """Extract specific property, while tracking time and duration of extraction."""
+
+        # --- timed property extraction -------------------
+        t_start_ns_epoch = time_ns()  # ns since epoch
+        t_start_ns = perf_counter_ns()
+        n_f_samples_before = self.function_sampler.function_cache_size()
+        result = self._extract(prop)
+        t_end_ns = perf_counter_ns()
+        n_f_samples_after = self.function_sampler.function_cache_size()
+
+        # --- store stats ---------------------------------
+        self.__stats[prop] = PropertyExtractionStats(
+            property=prop,
+            t_start_ns=t_start_ns_epoch,
+            t_duration_sec=(t_end_ns - t_start_ns) / 1e9,
+            n_f_samples=n_f_samples_after - n_f_samples_before,
+        )
+
+        # --- return result -------------------------------
+        return result
+
+    def statistics(self) -> dict[str, PropertyExtractionStats]:
+        """
+        Return dictionary with property extraction stats by property name.  Entries are sorted by
+        order of extraction.
+        """
+        return dict(
+            sorted(
+                self.__stats.items(),
+                key=lambda prop_stat: prop_stat[1].t_start_ns,
+            )
+        )
+
+    # =================================================================================================
+    #  Abstract methods
+    # =================================================================================================
+    @abstractmethod
+    def _extract(self, prop: str) -> float:
+        """Extract specific property."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def _new_named_array(self) -> NA:
+        raise NotImplementedError()

snuffled/_core/analysis/diagnostic/__init__.py

@@ -0,0 +1 @@
+from .diagnostic_analyser import DiagnosticAnalyser

snuffled/_core/analysis/diagnostic/diagnostic_analyser.py

@@ -0,0 +1,66 @@
+import numpy as np
+
+from snuffled._core.analysis._function_sampler import FunctionSampler
+from snuffled._core.analysis._property_extractor import PropertyExtractor
+from snuffled._core.models.properties import Diagnostic, SnuffledDiagnostics
+
+
+class DiagnosticAnalyser(PropertyExtractor[SnuffledDiagnostics]):
+    # -------------------------------------------------------------------------
+    #  Constructor
+    # -------------------------------------------------------------------------
+    def __init__(self, function_sampler: FunctionSampler):
+        super().__init__(function_sampler)
+
+    # -------------------------------------------------------------------------
+    #  Main Implementation
+    # -------------------------------------------------------------------------
+    def supported_properties(self) -> list[str]:
+        # return in order of increasing number of required function evals
+        return [
+            Diagnostic.INTERVAL_NOT_BRACKETING_READY,
+            Diagnostic.NO_ZEROS_DETECTED,
+            Diagnostic.MAX_ZERO_WIDTH,
+        ]
+
+    def _new_named_array(self) -> SnuffledDiagnostics:
+        return SnuffledDiagnostics()
+
+    def _extract(self, prop: str) -> float:
+        match prop:
+            case Diagnostic.INTERVAL_NOT_BRACKETING_READY:
+                return self._extract_interval_not_bracketing_ready()
+            case Diagnostic.MAX_ZERO_WIDTH:
+                return self._extract_max_zero_width()
+            case Diagnostic.NO_ZEROS_DETECTED:
+                return self._extract_no_zeros_detected()
+            case _:
+                raise ValueError(f"Property {prop} not supported")
+
+    # -------------------------------------------------------------------------
+    #  Internal methods
+    # -------------------------------------------------------------------------
+    def _extract_interval_not_bracketing_ready(self) -> float:
+        x_min, x_max = self.function_sampler.x_min, self.function_sampler.x_max
+        fx_min, fx_max = self.function_sampler.f(x_min), self.function_sampler.f(x_max)
+        fx_min_sign, fx_max_sign = np.sign(fx_min), np.sign(fx_max)
+        if fx_min_sign * fx_max_sign > 0:
+            # interval end-point f-values have same sign -> NOT READY
+            return 0.0
+        elif fx_min_sign * fx_max_sign == 0.0:
+            # one of the end-point f-values is 0         -> BORDERLINE
+            return 0.5
+        else:
+            # end-point f-values have opposite sign      -> READY
+            return 1.0
+
+    def _extract_max_zero_width(self) -> float:
+        return max([root.width for root in self.function_sampler.roots()])
+
+    def _extract_no_zeros_detected(self) -> float:
+        root_intervals, no_root_intervals = self.function_sampler.candidate_root_intervals()
+        if len(root_intervals) == 0:
+            # no candidate intervals to find roots
+            return 1.0
+        else:
+            return 0.0

snuffled/_core/analysis/function/__init__.py

@@ -0,0 +1 @@
+from .function_analyser import FunctionAnalyser

snuffled/_core/analysis/function/function_analyser.py

@@ -0,0 +1,123 @@
+import math
+
+import numpy as np
+
+from snuffled._core.analysis._function_sampler import FunctionSampler
+from snuffled._core.analysis._property_extractor import PropertyExtractor
+from snuffled._core.models import FunctionProperty, SnuffledFunctionProperties
+from snuffled._core.utils.statistics import estimate_sign_flip_frequency
+
+from .helpers_discontinuous import discontinuity_score
+from .helpers_non_monotonic import non_monotonicity_score
+
+
+class FunctionAnalyser(PropertyExtractor[SnuffledFunctionProperties]):
+    # -------------------------------------------------------------------------
+    #  Constructor
+    # -------------------------------------------------------------------------
+    def __init__(self, function_sampler: FunctionSampler):
+        super().__init__(function_sampler)
+
+    # -------------------------------------------------------------------------
+    #  Main Implementation
+    # -------------------------------------------------------------------------
+    def supported_properties(self) -> list[str]:
+        return [
+            FunctionProperty.HIGH_DYNAMIC_RANGE,
+            FunctionProperty.MANY_ZEROES,
+            FunctionProperty.FLAT_INTERVALS,
+            FunctionProperty.NON_MONOTONIC,
+            FunctionProperty.DISCONTINUOUS,  # this goes last to benefit from sampling of earlier properties
+        ]
+
+    def _new_named_array(self) -> SnuffledFunctionProperties:
+        return SnuffledFunctionProperties()
+
+    def _extract(self, prop: str) -> float:
+        match prop:
+            case FunctionProperty.HIGH_DYNAMIC_RANGE:
+                return self._extract_high_dynamic_range()
+            case FunctionProperty.MANY_ZEROES:
+                return self._extract_many_zeroes()
+            case FunctionProperty.FLAT_INTERVALS:
+                return self._extract_flat_intervals()
+            case FunctionProperty.NON_MONOTONIC:
+                return self._extract_non_monotonic()
+            case FunctionProperty.DISCONTINUOUS:
+                return self._extract_discontinuous()
+            case _:
+                raise ValueError(f"Property {prop} not supported")
+
+    # -------------------------------------------------------------------------
+    #  Internal methods
+    # -------------------------------------------------------------------------
+    def _extract_high_dynamic_range(self) -> float:
+        """
+        Looks at q10, q90 percentiles of abs(f(x)) for x in [x_min, x_max] and
+        looks at the ratio q90/q10.  High dynamic range score is calibrated as:
+
+            q90/q10     score
+
+            2^10         0.0     (most 'normal' functions will fall below)
+            2^52         0.5     (= accuracy of 64-bit float)
+            2^94         1.0     (extrapolated from the above)
+
+        :return: score in [0.0, 1.0] indicating to what extent this function exhibits a high dynamic range.
+        """
+        q10 = self.function_sampler.fx_quantile(0.1, absolute=True)
+        q90 = self.function_sampler.fx_quantile(0.9, absolute=True)
+        return float(np.interp(np.log2(q90 / q10), [10.0, 94.0], [0.0, 1.0], left=0.0, right=1.0))
+
+    def _extract_many_zeroes(self) -> float:
+        """
+        The MANY_ZEROES score indicates if we're 'suffering' from a large number of zeroes,
+        and is calibrated on a log scale as follows:
+
+            estimated # of zeroes            score
+
+                1                             0.0
+                (x_max-x_min)/dx              1.0
+
+        We estimate the # of zeroes by using the 'estimate_sign_flip_frequency' stats method.
+
+        :return: (float) score in [0,1]
+        """
+
+        # Estimate 'zero frequency' lambda = # of zeroes estimated to occur in a unit interval
+
+        #  STEP 1: build list of observations (w, p) with w the interval width and p indicating if we have a sign flip
+        root_intervals, non_root_intervals = self.function_sampler.candidate_root_intervals()
+        observations = [(x_right - x_left, 1.0) for x_left, x_right in root_intervals]
+        observations += [(x_right - x_left, 0.0) for x_left, x_right in non_root_intervals]
+        w_values = np.array([w for w, p in observations])
+        p_values = np.array([p for w, p in observations])
+
+        #  STEP 2: estimate lambda
+        # note that we use a factor of 1.1 in lambda_min to ensure we only give score>0.0 if we see some convincing
+        # evidence for multiple zeroes.
+        lambda_min = 1.1 / (self.function_sampler.x_max - self.function_sampler.x_min)
+        lambda_max = 1 / self.function_sampler.dx
+        zeroes_lambda = estimate_sign_flip_frequency(w_values, p_values, lambda_min, lambda_max)
+
+        #  STEP 3: convert to score in [0,1]
+        score = (math.log2(zeroes_lambda) - math.log2(lambda_min)) / (math.log2(lambda_max) - math.log2(lambda_min))
+        score = min(max(score, 0.0), 1.0)
+
+        # done
+        return float(score)
+
+    def _extract_non_monotonic(self) -> float:
+        return non_monotonicity_score(
+            fx_diff=self.function_sampler.fx_diff_values(),
+            fx_diff_signs=self.function_sampler.fx_diff_smooth_sign(),
+        )
+
+    def _extract_flat_intervals(self) -> float:
+        fx_sign = self.function_sampler.fx_diff_smooth_sign()
+        return 1.0 - float(np.mean(abs(fx_sign)))
+
+    def _extract_discontinuous(self) -> float:
+        return discontinuity_score(
+            function_sampler=self.function_sampler,
+            n_samples=self.function_sampler.n_fun_samples,
+        )