oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/core/memory_warnings.py

@@ -0,0 +1,315 @@
+"""Memory warning threshold system for TraceKit.
+
+This module provides configurable memory pressure warnings with
+automatic alerts and optional operation cancellation.
+
+
+Example:
+    >>> from oscura.core.memory_warnings import check_memory_warnings, MemoryWarningLevel
+    >>> level = check_memory_warnings()
+    >>> if level == MemoryWarningLevel.CRITICAL:
+    ...     print("Critical memory pressure!")
+
+References:
+    See oscura.config.memory for threshold configuration.
+"""
+
+from __future__ import annotations
+
+import warnings
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from oscura.config.memory import get_memory_config
+from oscura.utils.memory import get_available_memory, get_memory_pressure
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class MemoryWarningLevel(Enum):
+    """Memory warning levels based on pressure thresholds.
+
+    Attributes:
+        OK: Memory usage is normal (below warn threshold).
+        WARNING: Memory usage is elevated (above warn threshold).
+        CRITICAL: Memory usage is critical (above critical threshold).
+    """
+
+    OK = "ok"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+def check_memory_warnings() -> MemoryWarningLevel:
+    """Check current memory pressure against configured thresholds.
+
+
+    Returns:
+        Current memory warning level.
+
+    Example:
+        >>> level = check_memory_warnings()
+        >>> if level != MemoryWarningLevel.OK:
+        ...     print(f"Memory pressure: {level.value}")
+    """
+    pressure = get_memory_pressure()
+    config = get_memory_config()
+
+    if pressure >= config.critical_threshold:
+        return MemoryWarningLevel.CRITICAL
+    elif pressure >= config.warn_threshold:
+        return MemoryWarningLevel.WARNING
+    else:
+        return MemoryWarningLevel.OK
+
+
+def emit_memory_warning(force: bool = False) -> None:
+    """Emit warning if memory pressure exceeds thresholds.
+
+
+    Args:
+        force: If True, always emit warning regardless of level.
+
+    Example:
+        >>> emit_memory_warning()  # Emits warning if pressure high
+    """
+    level = check_memory_warnings()
+    pressure = get_memory_pressure()
+    available = get_available_memory()
+
+    if force or level != MemoryWarningLevel.OK:
+        if level == MemoryWarningLevel.CRITICAL:
+            warnings.warn(
+                f"CRITICAL memory pressure: {pressure * 100:.1f}% utilized. "
+                f"Only {available / 1e9:.2f} GB available. "
+                "Consider closing applications or canceling operations.",
+                ResourceWarning,
+                stacklevel=2,
+            )
+        elif level == MemoryWarningLevel.WARNING:
+            warnings.warn(
+                f"High memory pressure: {pressure * 100:.1f}% utilized. "
+                f"{available / 1e9:.2f} GB available. "
+                "Monitor memory usage closely.",
+                ResourceWarning,
+                stacklevel=2,
+            )
+
+
+def check_and_abort_if_critical(operation: str = "operation") -> None:
+    """Check memory and abort if critical threshold exceeded.
+
+
+    Args:
+        operation: Name of operation to abort.
+
+    Raises:
+        MemoryError: If memory pressure is critical.
+
+    Example:
+        >>> try:
+        ...     check_and_abort_if_critical('spectrogram')
+        ...     # ... perform operation ...
+        ... except MemoryError:
+        ...     print("Operation aborted due to critical memory")
+    """
+    level = check_memory_warnings()
+
+    if level == MemoryWarningLevel.CRITICAL:
+        pressure = get_memory_pressure()
+        available = get_available_memory()
+        config = get_memory_config()
+
+        raise MemoryError(
+            f"Critical memory pressure ({pressure * 100:.1f}% > {config.critical_threshold * 100:.0f}%). "
+            f"Only {available / 1e9:.2f} GB available. "
+            f"Operation '{operation}' aborted to prevent system crash. "
+            "Free memory or increase critical threshold to proceed."
+        )
+
+
+class MemoryWarningMonitor:
+    """Context manager for monitoring memory warnings during operations.
+
+
+    Monitors memory pressure during an operation and emits warnings
+    when thresholds are crossed.
+
+    Example:
+        >>> with MemoryWarningMonitor('spectrogram', check_interval=100):
+        ...     for i in range(1000):
+        ...         # ... perform work ...
+        ...         pass
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        *,
+        check_interval: int = 100,
+        abort_on_critical: bool = True,
+    ):
+        """Initialize memory warning monitor.
+
+        Args:
+            operation: Name of operation being monitored.
+            check_interval: Check memory every N iterations.
+            abort_on_critical: Abort if critical threshold reached.
+        """
+        self.operation = operation
+        self.check_interval = check_interval
+        self.abort_on_critical = abort_on_critical
+        self._iteration = 0
+        self._warned = False
+        self._critical_warned = False
+
+    def __enter__(self) -> MemoryWarningMonitor:
+        """Enter context and perform initial check."""
+        # Initial check
+        emit_memory_warning()
+        return self
+
+    def __exit__(self, exc_type: type, exc_val: Exception, exc_tb: object) -> None:
+        """Exit context."""
+        # Note: exc_val and exc_tb intentionally unused but required for Python 3.11+ compatibility
+
+    def check(self, iteration: int | None = None) -> None:
+        """Check memory pressure and emit warnings.
+
+        Args:
+            iteration: Current iteration number (for periodic checking).
+
+        Raises:
+            MemoryError: If critical threshold exceeded and abort_on_critical=True.
+        """
+        self._iteration += 1
+
+        # Only check periodically
+        if iteration is not None and iteration % self.check_interval != 0:
+            return
+
+        level = check_memory_warnings()
+        pressure = get_memory_pressure()
+        available = get_available_memory()
+
+        if level == MemoryWarningLevel.CRITICAL:
+            if not self._critical_warned:
+                warnings.warn(
+                    f"Critical memory pressure during {self.operation}: "
+                    f"{pressure * 100:.1f}% utilized, {available / 1e9:.2f} GB available.",
+                    ResourceWarning,
+                    stacklevel=2,
+                )
+                self._critical_warned = True
+
+            if self.abort_on_critical:
+                raise MemoryError(
+                    f"Critical memory pressure during {self.operation}. "
+                    f"Operation aborted to prevent system crash. "
+                    f"Pressure: {pressure * 100:.1f}%, Available: {available / 1e9:.2f} GB"
+                )
+
+        elif level == MemoryWarningLevel.WARNING:
+            if not self._warned:
+                warnings.warn(
+                    f"High memory pressure during {self.operation}: "
+                    f"{pressure * 100:.1f}% utilized, {available / 1e9:.2f} GB available.",
+                    ResourceWarning,
+                    stacklevel=2,
+                )
+                self._warned = True
+
+
+def register_memory_warning_callback(callback: Callable[[MemoryWarningLevel], None]) -> None:
+    """Register a callback for memory warnings.
+
+    The callback will be invoked whenever memory warnings are checked
+    via emit_memory_warning() or MemoryWarningMonitor.
+
+    Args:
+        callback: Function that accepts MemoryWarningLevel.
+
+    Example:
+        >>> def my_callback(level):
+        ...     if level == MemoryWarningLevel.CRITICAL:
+        ...         print("CRITICAL MEMORY!")
+        >>> register_memory_warning_callback(my_callback)
+    """
+    _warning_callbacks.append(callback)
+
+
+def clear_memory_warning_callbacks() -> None:
+    """Clear all registered memory warning callbacks.
+
+    Example:
+        >>> clear_memory_warning_callbacks()
+    """
+    _warning_callbacks.clear()
+
+
+# Global list of warning callbacks
+_warning_callbacks: list[Callable[[MemoryWarningLevel], None]] = []
+
+
+def _invoke_callbacks(level: MemoryWarningLevel) -> None:
+    """Invoke all registered callbacks with current warning level.
+
+    Args:
+        level: Current memory warning level.
+    """
+    for callback in _warning_callbacks:
+        try:
+            callback(level)
+        except Exception as e:
+            warnings.warn(
+                f"Memory warning callback failed: {e}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+
+def format_memory_warning(level: MemoryWarningLevel) -> str:
+    """Format memory warning message.
+
+    Args:
+        level: Memory warning level.
+
+    Returns:
+        Formatted warning message.
+
+    Example:
+        >>> msg = format_memory_warning(MemoryWarningLevel.WARNING)
+        >>> print(msg)
+        High memory pressure: 75.0% utilized...
+    """
+    pressure = get_memory_pressure()
+    available = get_available_memory()
+    config = get_memory_config()
+
+    if level == MemoryWarningLevel.CRITICAL:
+        return (
+            f"CRITICAL memory pressure: {pressure * 100:.1f}% utilized "
+            f"(threshold: {config.critical_threshold * 100:.0f}%). "
+            f"Only {available / 1e9:.2f} GB available."
+        )
+    elif level == MemoryWarningLevel.WARNING:
+        return (
+            f"High memory pressure: {pressure * 100:.1f}% utilized "
+            f"(threshold: {config.warn_threshold * 100:.0f}%). "
+            f"{available / 1e9:.2f} GB available."
+        )
+    else:
+        return f"Memory OK: {pressure * 100:.1f}% utilized, {available / 1e9:.2f} GB available."
+
+
+__all__ = [
+    "MemoryWarningLevel",
+    "MemoryWarningMonitor",
+    "check_and_abort_if_critical",
+    "check_memory_warnings",
+    "clear_memory_warning_callbacks",
+    "emit_memory_warning",
+    "format_memory_warning",
+    "register_memory_warning_callback",
+]

oscura/core/numba_backend.py

@@ -0,0 +1,362 @@
+"""Numba JIT compilation backend for performance-critical code paths.
+
+This module provides a unified interface for Numba JIT compilation with graceful
+fallback when Numba is not available. Provides 10-50x speedup for numerical loops
+that cannot be fully vectorized.
+
+Usage:
+    from oscura.core.numba_backend import njit, prange, HAS_NUMBA
+
+    @njit(parallel=True, cache=True)
+    def fast_function(data):
+        result = np.zeros_like(data)
+        for i in prange(len(data)):
+            result[i] = expensive_computation(data[i])
+        return result
+
+Performance characteristics:
+    - First call: Compilation overhead (~100-500ms)
+    - Subsequent calls: 10-50x faster than Python loops
+    - Parallel execution: Additional speedup on multi-core systems
+    - Cache: Compilation results cached between runs
+
+Example:
+    >>> from oscura.core.numba_backend import njit, HAS_NUMBA
+    >>> import numpy as np
+    >>>
+    >>> @njit(cache=True)
+    >>> def sum_of_squares(arr):
+    ...     total = 0.0
+    ...     for i in range(len(arr)):
+    ...         total += arr[i] ** 2
+    ...     return total
+    >>>
+    >>> data = np.random.randn(1_000_000)
+    >>> result = sum_of_squares(data)  # Fast on second call
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import numpy as np
+
+# Try to import Numba
+try:
+    from numba import guvectorize as _numba_guvectorize  # type: ignore[import-untyped]
+    from numba import jit as _numba_jit  # type: ignore[import-untyped]
+    from numba import njit as _numba_njit  # type: ignore[import-untyped]
+    from numba import prange as _numba_prange  # type: ignore[import-untyped]
+    from numba import vectorize as _numba_vectorize  # type: ignore[import-untyped]
+
+    HAS_NUMBA = True
+except ImportError:
+    HAS_NUMBA = False
+
+
+# Type variable for generic functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+if HAS_NUMBA:
+    # Numba is available - use real implementations
+    njit = _numba_njit
+    prange = _numba_prange
+    vectorize = _numba_vectorize
+    guvectorize = _numba_guvectorize
+    jit = _numba_jit
+
+else:
+    # Numba not available - provide fallback decorators that do nothing
+    def njit(*args: Any, **kwargs: Any) -> Callable[[F], F]:
+        """No-op decorator when Numba is not available.
+
+        This decorator does nothing but allows code to remain syntactically valid
+        when Numba is not installed.
+
+        Args:
+            *args: Positional arguments (ignored).
+            **kwargs: Keyword arguments (ignored).
+
+        Returns:
+            Decorator function or decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            @functools.wraps(func)
+            def wrapper(*call_args: Any, **call_kwargs: Any) -> Any:
+                return func(*call_args, **call_kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        # Handle both @njit and @njit() syntax
+        if len(args) == 1 and callable(args[0]) and not kwargs:
+            return decorator(args[0])  # type: ignore[no-any-return]
+        return decorator  # type: ignore[no-any-return]
+
+    def prange(*args: Any, **kwargs: Any) -> range:
+        """Fallback to regular range when Numba is not available.
+
+        Args:
+            *args: Same as range().
+            **kwargs: Same as range().
+
+        Returns:
+            Standard Python range object.
+        """
+        return range(*args, **kwargs)
+
+    def vectorize(*args: Any, **kwargs: Any) -> Callable[[F], F]:
+        """No-op decorator when Numba is not available.
+
+        Args:
+            *args: Positional arguments (ignored).
+            **kwargs: Keyword arguments (ignored).
+
+        Returns:
+            Decorator that returns the original function.
+        """
+
+        def decorator(func: F) -> F:
+            return func
+
+        if len(args) == 1 and callable(args[0]):
+            return decorator(args[0])  # type: ignore[no-any-return]
+        return decorator  # type: ignore[no-any-return]
+
+    def guvectorize(*args: Any, **kwargs: Any) -> Callable[[F], F]:
+        """No-op decorator when Numba is not available.
+
+        Args:
+            *args: Positional arguments (ignored).
+            **kwargs: Keyword arguments (ignored).
+
+        Returns:
+            Decorator that returns the original function.
+        """
+
+        def decorator(func: F) -> F:
+            return func
+
+        if len(args) == 1 and callable(args[0]):
+            return decorator(args[0])  # type: ignore[no-any-return]
+        return decorator  # type: ignore[no-any-return]
+
+    def jit(*args: Any, **kwargs: Any) -> Callable[[F], F]:
+        """No-op decorator when Numba is not available.
+
+        Args:
+            *args: Positional arguments (ignored).
+            **kwargs: Keyword arguments (ignored).
+
+        Returns:
+            Decorator that returns the original function.
+        """
+
+        def decorator(func: F) -> F:
+            @functools.wraps(func)
+            def wrapper(*call_args: Any, **call_kwargs: Any) -> Any:
+                return func(*call_args, **call_kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        if len(args) == 1 and callable(args[0]) and not kwargs:
+            return decorator(args[0])  # type: ignore[no-any-return]
+        return decorator  # type: ignore[no-any-return]
+
+
+def get_optimal_numba_config(
+    parallel: bool = False,
+    cache: bool = True,
+    fastmath: bool = False,
+    nogil: bool = False,
+) -> dict[str, Any]:
+    """Get optimal Numba configuration for given requirements.
+
+    Args:
+        parallel: Enable parallel execution using prange.
+        cache: Enable compilation caching for faster subsequent runs.
+        fastmath: Enable fast math optimizations (may reduce precision).
+        nogil: Release GIL during execution (useful for threading).
+
+    Returns:
+        Dictionary of Numba configuration options.
+
+    Example:
+        >>> config = get_optimal_numba_config(parallel=True, cache=True)
+        >>> @njit(**config)
+        >>> def my_function(data):
+        ...     pass
+    """
+    if not HAS_NUMBA:
+        return {}
+
+    return {
+        "parallel": parallel,
+        "cache": cache,
+        "fastmath": fastmath,
+        "nogil": nogil,
+    }
+
+
+# Example Numba-optimized functions for common operations
+
+
+@njit(cache=True)  # type: ignore[misc,untyped-decorator]
+def find_crossings_numba(
+    data: np.ndarray,  # type: ignore[type-arg]
+    threshold: float,
+    direction: int = 0,
+) -> np.ndarray:  # type: ignore[type-arg]
+    """Find threshold crossings with Numba acceleration.
+
+    Args:
+        data: Input signal data.
+        threshold: Threshold value to detect crossings.
+        direction: 0=both, 1=rising only, -1=falling only.
+
+    Returns:
+        Array of indices where crossings occur.
+    """
+    crossings = []
+    for i in range(1, len(data)):
+        prev_val = data[i - 1]
+        curr_val = data[i]
+
+        if direction >= 0:  # Rising or both
+            if prev_val < threshold <= curr_val:
+                crossings.append(i)
+        if direction <= 0 and direction != 1:  # Falling or both
+            if prev_val > threshold >= curr_val:
+                crossings.append(i)
+
+    return np.array(crossings, dtype=np.int64)
+
+
+@njit(parallel=True, cache=True)  # type: ignore[misc,untyped-decorator]
+def moving_average_numba(
+    data: np.ndarray,  # type: ignore[type-arg]
+    window_size: int,
+) -> np.ndarray:  # type: ignore[type-arg]
+    """Compute moving average with Numba parallel acceleration.
+
+    Args:
+        data: Input signal data.
+        window_size: Size of the moving window.
+
+    Returns:
+        Array of moving averages.
+    """
+    n = len(data)
+    result = np.zeros(n - window_size + 1, dtype=np.float64)
+
+    for i in prange(len(result)):
+        total = 0.0
+        for j in range(window_size):
+            total += data[i + j]
+        result[i] = total / window_size
+
+    return result
+
+
+@njit(cache=True)  # type: ignore[misc,untyped-decorator]
+def argrelextrema_numba(
+    data: np.ndarray,  # type: ignore[type-arg]
+    comparator: int,
+    order: int = 1,
+) -> np.ndarray:  # type: ignore[type-arg]
+    """Find relative extrema (peaks/valleys) with Numba acceleration.
+
+    Args:
+        data: Input signal data.
+        comparator: 1 for maxima (peaks), -1 for minima (valleys).
+        order: How many points on each side to use for comparison.
+
+    Returns:
+        Array of indices where extrema occur.
+    """
+    extrema = []
+    n = len(data)
+
+    for i in range(order, n - order):
+        is_extremum = True
+
+        for j in range(1, order + 1):
+            if comparator > 0:  # Maximum
+                if data[i] <= data[i - j] or data[i] <= data[i + j]:
+                    is_extremum = False
+                    break
+            else:  # Minimum
+                if data[i] >= data[i - j] or data[i] >= data[i + j]:
+                    is_extremum = False
+                    break
+
+        if is_extremum:
+            extrema.append(i)
+
+    return np.array(extrema, dtype=np.int64)
+
+
+@njit(cache=True)  # type: ignore[misc,untyped-decorator]
+def interpolate_linear_numba(
+    x: np.ndarray,  # type: ignore[type-arg]
+    y: np.ndarray,  # type: ignore[type-arg]
+    x_new: np.ndarray,  # type: ignore[type-arg]
+) -> np.ndarray:  # type: ignore[type-arg]
+    """Linear interpolation with Numba acceleration.
+
+    Args:
+        x: Original x coordinates (must be sorted).
+        y: Original y values.
+        x_new: New x coordinates to interpolate.
+
+    Returns:
+        Interpolated y values at x_new.
+    """
+    n = len(x)
+    m = len(x_new)
+    y_new = np.zeros(m, dtype=np.float64)
+
+    for i in range(m):
+        xi = x_new[i]
+
+        # Binary search for bracketing indices
+        left = 0
+        right = n - 1
+
+        while left < right - 1:
+            mid = (left + right) // 2
+            if x[mid] <= xi:
+                left = mid
+            else:
+                right = mid
+
+        # Linear interpolation
+        if xi <= x[0]:
+            y_new[i] = y[0]
+        elif xi >= x[n - 1]:
+            y_new[i] = y[n - 1]
+        else:
+            x0, x1 = x[left], x[right]
+            y0, y1 = y[left], y[right]
+            t = (xi - x0) / (x1 - x0)
+            y_new[i] = y0 + t * (y1 - y0)
+
+    return y_new
+
+
+__all__ = [
+    "HAS_NUMBA",
+    "argrelextrema_numba",
+    "find_crossings_numba",
+    "get_optimal_numba_config",
+    "guvectorize",
+    "interpolate_linear_numba",
+    "jit",
+    "moving_average_numba",
+    "njit",
+    "prange",
+    "vectorize",
+]