oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/analyzers/patterns/periodic.py

@@ -11,7 +11,7 @@ Author: Oscura Development Team
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
 
@@ -150,8 +150,6 @@ def detect_periods_fft(
 ) -> list[PeriodResult]:
     """Detect periods using FFT spectral analysis.
 
-    : Periodic Pattern Detection via FFT
-
     Uses power spectral density to identify dominant frequencies and their
     harmonics. More efficient than autocorrelation for long signals.
 
@@ -170,42 +168,99 @@ def detect_periods_fft(
         >>> periods = detect_periods_fft(signal, sample_rate=1000.0, num_peaks=3)
     """
     trace = np.asarray(trace).flatten()
-
     if trace.size == 0:
         return []
 
-    # Remove DC component
-    trace_centered = trace - np.mean(trace)
+    power, freqs = _compute_power_spectrum(trace, sample_rate)
+    peak_indices = _find_valid_peaks(power, freqs, min_freq, max_freq, num_peaks)
+
+    if len(peak_indices) == 0:
+        return []
 
-    # Compute FFT
+    return _build_period_results(peak_indices, freqs, power, sample_rate)
+
+
+def _compute_power_spectrum(
+    trace: NDArray[np.float64], sample_rate: float
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Compute power spectrum from FFT.
+
+    Args:
+        trace: Input signal array.
+        sample_rate: Sampling rate in Hz.
+
+    Returns:
+        Tuple of (power spectrum, frequencies).
+    """
+    trace_centered = trace - np.mean(trace)
     n = len(trace_centered)
-    fft_result = np.fft.rfft(trace_centered)
+
+    # Apply Hanning window to reduce spectral leakage (improves noise robustness)
+    window = np.hanning(n)
+    trace_windowed = trace_centered * window
+
+    fft_result = np.fft.rfft(trace_windowed)
     power = np.asarray(np.abs(fft_result) ** 2, dtype=np.float64)
     freqs = np.fft.rfftfreq(n, 1.0 / sample_rate)
+    return power, freqs
+
+
+def _find_valid_peaks(
+    power: NDArray[np.float64],
+    freqs: NDArray[np.float64],
+    min_freq: float | None,
+    max_freq: float | None,
+    num_peaks: int,
+) -> NDArray[np.intp]:
+    """Find valid spectral peaks within frequency range.
 
-    # Apply frequency range filtering
+    Args:
+        power: Power spectrum array.
+        freqs: Frequency array.
+        min_freq: Minimum frequency.
+        max_freq: Maximum frequency.
+        num_peaks: Maximum peaks to return.
+
+    Returns:
+        Array of peak indices sorted by power.
+    """
     valid_mask = np.ones(len(freqs), dtype=bool)
     if min_freq is not None:
         valid_mask &= freqs >= min_freq
     if max_freq is not None:
         valid_mask &= freqs <= max_freq
+    valid_mask[0] = False  # Exclude DC
 
-    # Exclude DC component
-    valid_mask[0] = False
-
-    # Find peaks in power spectrum
     peak_indices = _find_spectral_peaks(power, min_distance=1)
     peak_indices = peak_indices[valid_mask[peak_indices]]
 
     if len(peak_indices) == 0:
-        return []
+        empty_result: NDArray[np.signedinteger[Any]] = peak_indices
+        return empty_result
 
-    # Sort by power
     peak_powers = power[peak_indices]
     sorted_indices = np.argsort(peak_powers)[::-1][:num_peaks]
-    peak_indices = peak_indices[sorted_indices]
+    result: NDArray[np.signedinteger[Any]] = peak_indices[sorted_indices]
+    return result
 
-    # Build results
+
+def _build_period_results(
+    peak_indices: NDArray[np.intp],
+    freqs: NDArray[np.float64],
+    power: NDArray[np.float64],
+    sample_rate: float,
+) -> list[PeriodResult]:
+    """Build PeriodResult objects from spectral peaks.
+
+    Args:
+        peak_indices: Array of peak indices.
+        freqs: Frequency array.
+        power: Power spectrum array.
+        sample_rate: Sampling rate in Hz.
+
+    Returns:
+        List of PeriodResult objects.
+    """
     results = []
     max_power = np.max(power[peak_indices]) if len(peak_indices) > 0 else 1.0
 
@@ -214,28 +269,14 @@ def detect_periods_fft(
         if freq == 0:
             continue
 
-        period_seconds = 1.0 / freq
-        period_samples = sample_rate / freq
-
-        # Confidence based on relative power
-        confidence = float(power[idx] / max_power)
-
-        # Detect harmonics (simple approach: look for integer multiples)
-        harmonics = []
-        for mult in range(2, 6):
-            harmonic_freq = freq * mult
-            if harmonic_freq < freqs[-1]:
-                # Find closest frequency bin
-                harmonic_idx = np.argmin(np.abs(freqs - harmonic_freq))
-                if power[harmonic_idx] > 0.1 * power[idx]:
-                    harmonics.append(harmonic_freq)
+        harmonics = _detect_harmonics(freq, freqs, power, power[idx])
 
         results.append(
             PeriodResult(
-                period_samples=period_samples,
-                period_seconds=period_seconds,
+                period_samples=sample_rate / freq,
+                period_seconds=1.0 / freq,
                 frequency_hz=freq,
-                confidence=min(confidence, 1.0),
+                confidence=min(float(power[idx] / max_power), 1.0),
                 method="fft",
                 harmonics=harmonics if harmonics else None,
             )
@@ -244,6 +285,30 @@ def detect_periods_fft(
     return results
 
 
+def _detect_harmonics(
+    freq: float, freqs: NDArray[np.float64], power: NDArray[np.float64], base_power: float
+) -> list[float]:
+    """Detect harmonic frequencies.
+
+    Args:
+        freq: Base frequency.
+        freqs: Frequency array.
+        power: Power spectrum.
+        base_power: Power at base frequency.
+
+    Returns:
+        List of harmonic frequencies.
+    """
+    harmonics = []
+    for mult in range(2, 6):
+        harmonic_freq = freq * mult
+        if harmonic_freq < freqs[-1]:
+            harmonic_idx = np.argmin(np.abs(freqs - harmonic_freq))
+            if power[harmonic_idx] > 0.1 * base_power:
+                harmonics.append(harmonic_freq)
+    return harmonics
+
+
 def detect_periods_autocorr(
     trace: NDArray[np.float64],
     sample_rate: float = 1.0,
@@ -429,6 +494,8 @@ def _find_spectral_peaks(data: NDArray[np.float64], min_distance: int = 1) -> ND
     """Find peaks in 1D array.
 
     Simple peak detection: point is peak if higher than neighbors.
+    Includes noise threshold to filter out spurious peaks.
+    Handles boundary conditions at edges of the array.
 
     Args:
         data: 1D array
@@ -437,15 +504,31 @@ def _find_spectral_peaks(data: NDArray[np.float64], min_distance: int = 1) -> ND
     Returns:
         Array of peak indices
     """
-    if len(data) < 3:
+    if len(data) < 2:
         return np.array([], dtype=np.intp)
 
-    # Find local maxima
+    # Calculate noise threshold (5% of max value to filter noise peaks)
+    threshold = 0.05 * np.max(data)
+
+    # Find local maxima above threshold
     peaks_list: list[int] = []
+
+    # Check interior points (only elements with both neighbors)
     for i in range(1, len(data) - 1):
-        if data[i] > data[i - 1] and data[i] > data[i + 1]:
+        if data[i] > data[i - 1] and data[i] > data[i + 1] and data[i] > threshold:
             peaks_list.append(i)
 
+    # Check boundary elements (for Nyquist frequency peaks)
+    # Only consider boundary as peak if it's a TRUE local maximum (not just monotonic increase)
+    # Require it to be significantly higher than neighbor (at least 2x threshold)
+    if len(data) >= 3:
+        # Check first element
+        if data[0] > data[1] and data[0] > max(threshold * 2, data[1] * 1.5):
+            peaks_list.insert(0, 0)
+        # Check last element (important for Nyquist frequency in FFT)
+        if data[-1] > data[-2] and data[-1] > max(threshold * 2, data[-2] * 1.5):
+            peaks_list.append(len(data) - 1)
+
     peaks: NDArray[np.intp] = np.array(peaks_list, dtype=np.intp)
 
     # Apply minimum distance constraint

oscura/analyzers/patterns/sequences.py

@@ -279,6 +279,155 @@ def find_longest_repeat(data: bytes | NDArray[np.uint8]) -> RepeatingSequence |
     )
 
 
+def _extract_substrings(data_bytes: bytes, min_length: int) -> list[tuple[bytes, int]]:
+    """Extract all substrings of given length with their positions.
+
+    Args:
+        data_bytes: Input byte string
+        min_length: Length of substrings to extract
+
+    Returns:
+        List of (pattern, position) tuples
+    """
+    n = len(data_bytes)
+    substrings = []
+    for i in range(n - min_length + 1):
+        substrings.append((data_bytes[i : i + min_length], i))
+    return substrings
+
+
+def _build_fuzzy_hash_buckets(
+    substrings: list[tuple[bytes, int]], min_length: int
+) -> dict[tuple[bytes, bytes], list[tuple[bytes, int]]]:
+    """Group substrings by fuzzy hash for efficient approximate matching.
+
+    Uses locality-sensitive hashing: hash of first few bytes + last few bytes.
+    Sequences with same prefix/suffix are likely similar.
+
+    Args:
+        substrings: List of (pattern, position) tuples
+        min_length: Minimum pattern length
+
+    Returns:
+        Dictionary mapping fuzzy hash to list of patterns
+    """
+    hash_buckets: dict[tuple[bytes, bytes], list[tuple[bytes, int]]] = defaultdict(list)
+    prefix_len = min(3, min_length // 3)  # First 3 bytes or ~1/3 of length
+    suffix_len = min(3, min_length // 3)  # Last 3 bytes
+
+    for pattern, pos in substrings:
+        prefix = pattern[:prefix_len]
+        suffix = pattern[-suffix_len:] if len(pattern) > suffix_len else pattern
+        fuzzy_hash = (prefix, suffix)
+        hash_buckets[fuzzy_hash].append((pattern, pos))
+
+    return hash_buckets
+
+
+def _is_pattern_compatible(pattern: bytes, other_pattern: bytes, max_distance: int) -> bool:
+    """Check if two patterns can be within edit distance threshold.
+
+    Args:
+        pattern: First pattern
+        other_pattern: Second pattern
+        max_distance: Maximum allowed edit distance
+
+    Returns:
+        True if patterns might be within threshold (quick check)
+    """
+    return abs(len(pattern) - len(other_pattern)) <= max_distance
+
+
+def _try_add_to_cluster(
+    pattern: bytes,
+    other_pattern: bytes,
+    other_pos: int,
+    max_distance: int,
+    cluster_patterns: list[bytes],
+    cluster_positions: list[int],
+) -> bool:
+    """Try to add a pattern to existing cluster if within distance threshold.
+
+    Args:
+        pattern: Representative pattern of cluster
+        other_pattern: Pattern to potentially add
+        other_pos: Position of other pattern
+        max_distance: Maximum edit distance allowed
+        cluster_patterns: Current cluster patterns (modified in place)
+        cluster_positions: Current cluster positions (modified in place)
+
+    Returns:
+        True if pattern was added to cluster
+    """
+    if not _is_pattern_compatible(pattern, other_pattern, max_distance):
+        return False
+
+    distance = _edit_distance_optimized(pattern, other_pattern, max_distance)
+    if distance <= max_distance:
+        cluster_patterns.append(other_pattern)
+        cluster_positions.append(other_pos)
+        return True
+    return False
+
+
+def _cluster_bucket_patterns(
+    bucket_patterns: list[tuple[bytes, int]],
+    substrings: list[tuple[bytes, int]],
+    max_distance: int,
+    min_count: int,
+    global_used: set[int],
+) -> list[tuple[list[bytes], list[int]]]:
+    """Cluster patterns within a single hash bucket.
+
+    Args:
+        bucket_patterns: Patterns in this bucket
+        substrings: All substrings (for index lookup)
+        max_distance: Maximum edit distance
+        min_count: Minimum cluster size
+        global_used: Set of globally used indices (modified in place)
+
+    Returns:
+        List of (cluster_patterns, cluster_positions) tuples
+    """
+    clusters = []
+    bucket_used: set[int] = set()
+
+    for i, (pattern, pos) in enumerate(bucket_patterns):
+        # Check if already used globally
+        actual_idx = substrings.index((pattern, pos))
+        if actual_idx in global_used:
+            continue
+
+        # Start new cluster
+        cluster_patterns = [pattern]
+        cluster_positions = [pos]
+        bucket_used.add(i)
+        global_used.add(actual_idx)
+
+        # Compare within same bucket
+        for j in range(i + 1, len(bucket_patterns)):
+            if j in bucket_used:
+                continue
+
+            other_pattern, other_pos = bucket_patterns[j]
+            other_idx = substrings.index((other_pattern, other_pos))
+            if other_idx in global_used:
+                continue
+
+            # Try to add to cluster
+            if _try_add_to_cluster(
+                pattern, other_pattern, other_pos, max_distance, cluster_patterns, cluster_positions
+            ):
+                bucket_used.add(j)
+                global_used.add(other_idx)
+
+        # Add cluster if large enough
+        if len(cluster_patterns) >= min_count:
+            clusters.append((cluster_patterns, cluster_positions))
+
+    return clusters
+
+
 @memoize_analysis(maxsize=16)
 def find_approximate_repeats(
     data: bytes | NDArray[np.uint8],
@@ -328,98 +477,46 @@ def find_approximate_repeats(
     if n < min_length:
         return []
 
-    # OPTIMIZATION 1: Extract substrings with numpy for better memory efficiency
-    substrings = []
-    for i in range(n - min_length + 1):
-        substrings.append((data_bytes[i : i + min_length], i))
-
-    # OPTIMIZATION 2: Hash-based pre-grouping
-    # Group sequences by fuzzy hash to reduce comparisons
-    # Use a locality-sensitive hash: hash of first few bytes + last few bytes
-    hash_buckets: dict[tuple[bytes, bytes], list[tuple[bytes, int]]] = defaultdict(list)
-    prefix_len = min(3, min_length // 3)  # First 3 bytes or ~1/3 of length
-    suffix_len = min(3, min_length // 3)  # Last 3 bytes
+    # Extract all substrings
+    substrings = _extract_substrings(data_bytes, min_length)
 
-    for pattern, pos in substrings:
-        # Create fuzzy hash from prefix and suffix
-        # Sequences with same prefix/suffix are likely similar
-        prefix = pattern[:prefix_len]
-        suffix = pattern[-suffix_len:] if len(pattern) > suffix_len else pattern
-        fuzzy_hash = (prefix, suffix)
-        hash_buckets[fuzzy_hash].append((pattern, pos))
+    # Group by fuzzy hash to reduce comparisons
+    hash_buckets = _build_fuzzy_hash_buckets(substrings, min_length)
 
-    # OPTIMIZATION 3: Cluster within hash buckets only
-    # This reduces O(n²) comparisons to O(k * m²) where k is number of buckets
-    # and m is average bucket size (m << n)
-    clusters = []
+    # Cluster within hash buckets
+    results = []
     global_used: set[int] = set()
 
     for bucket_patterns in hash_buckets.values():
         # Skip small buckets that can't form clusters
         if len(bucket_patterns) < min_count:
-            # Still need to check if they can join other buckets
-            # For now, skip - could optimize further by cross-bucket matching
             continue
 
-        # Cluster within this bucket
-        bucket_used: set[int] = set()
+        # Cluster patterns in this bucket
+        bucket_clusters = _cluster_bucket_patterns(
+            bucket_patterns, substrings, max_distance, min_count, global_used
+        )
 
-        for i, (pattern, pos) in enumerate(bucket_patterns):
-            # Check if already used globally
-            actual_idx = substrings.index((pattern, pos))
-            if actual_idx in global_used:
-                continue
+        # Convert clusters to RepeatingSequence objects
+        for cluster_patterns, cluster_positions in bucket_clusters:
+            # Use most common pattern as representative
+            pattern_counter = Counter(cluster_patterns)
+            representative = pattern_counter.most_common(1)[0][0]
 
-            # Start new cluster
-            cluster_patterns = [pattern]
-            cluster_positions = [pos]
-            bucket_used.add(i)
-            global_used.add(actual_idx)
-
-            # OPTIMIZATION 4: Only compare within same bucket
-            for j in range(i + 1, len(bucket_patterns)):
-                if j in bucket_used:
-                    continue
-
-                other_pattern, other_pos = bucket_patterns[j]
-                other_idx = substrings.index((other_pattern, other_pos))
-                if other_idx in global_used:
-                    continue
-
-                # OPTIMIZATION 5: Early termination with quick checks
-                # Check if lengths are compatible
-                if abs(len(pattern) - len(other_pattern)) > max_distance:
-                    continue
-
-                # OPTIMIZATION 6: Use optimized edit distance
-                distance = _edit_distance_optimized(pattern, other_pattern, max_distance)
-
-                if distance <= max_distance:
-                    cluster_patterns.append(other_pattern)
-                    cluster_positions.append(other_pos)
-                    bucket_used.add(j)
-                    global_used.add(other_idx)
-
-            # Add cluster if large enough
-            if len(cluster_patterns) >= min_count:
-                # Use most common pattern as representative
-                pattern_counter = Counter(cluster_patterns)
-                representative = pattern_counter.most_common(1)[0][0]
-
-                clusters.append(
-                    RepeatingSequence(
-                        pattern=representative,
-                        length=len(representative),
-                        count=len(cluster_patterns),
-                        positions=sorted(cluster_positions),
-                        frequency=len(cluster_patterns) / (n - min_length + 1),
-                    )
+            results.append(
+                RepeatingSequence(
+                    pattern=representative,
+                    length=len(representative),
+                    count=len(cluster_patterns),
+                    positions=sorted(cluster_positions),
+                    frequency=len(cluster_patterns) / (n - min_length + 1),
                 )
+            )
 
     # Sort by count (descending)
-    clusters.sort(key=lambda x: x.count, reverse=True)
+    results.sort(key=lambda x: x.count, reverse=True)
 
-    return clusters
+    return results
 
 
 def _to_bytes(data: bytes | NDArray[np.uint8] | memoryview | bytearray) -> bytes:
@@ -439,7 +536,7 @@ def _to_bytes(data: bytes | NDArray[np.uint8] | memoryview | bytearray) -> bytes
     elif isinstance(data, bytearray | memoryview):
         return bytes(data)
     elif isinstance(data, np.ndarray):
-        return data.astype(np.uint8).tobytes()  # type: ignore[no-any-return]
+        return data.astype(np.uint8).tobytes()
     else:
         raise TypeError(f"Unsupported data type: {type(data)}")
 

oscura/analyzers/power/conduction.py

@@ -108,7 +108,7 @@ def on_resistance(
 
     mask = np.abs(i_data) >= min_current
     if not np.any(mask):
-        return np.nan  # type: ignore[no-any-return]
+        return np.nan
 
     v_on = v_data[mask]
     i_on = i_data[mask]

oscura/analyzers/power/soa.py

@@ -111,13 +111,13 @@ def soa_analysis(
     if pulse_width is None:
         pulse_width = np.inf
 
-    applicable_limits = [l for l in limits if l.pulse_width >= pulse_width]  # noqa: E741
+    applicable_limits = [l for l in limits if l.pulse_width >= pulse_width]
     if not applicable_limits:
         applicable_limits = limits  # Use all if none match
 
     # Build SOA boundary (interpolate between limit points)
     # Sort by voltage
-    sorted_limits = sorted(applicable_limits, key=lambda l: l.v_max)  # noqa: E741
+    sorted_limits = sorted(applicable_limits, key=lambda l: l.v_max)
 
     violations: list[SOAViolation] = []
     margins: list[float] = []
@@ -171,7 +171,7 @@ def _interpolate_soa_limit(voltage: float, limits: list[SOALimit]) -> float:
         Interpolated current limit in Amps
     """
     if len(limits) == 0:
-        return np.inf  # type: ignore[no-any-return]
+        return np.inf
 
     if len(limits) == 1:
         if voltage <= limits[0].v_max:
@@ -259,9 +259,9 @@ def plot_soa(
     fig, ax = plt.subplots(figsize=figsize)
 
     # Plot SOA boundary
-    sorted_limits = sorted(limits, key=lambda l: l.v_max)  # noqa: E741
-    v_boundary = [l.v_max for l in sorted_limits]  # noqa: E741
-    i_boundary = [l.i_max for l in sorted_limits]  # noqa: E741
+    sorted_limits = sorted(limits, key=lambda l: l.v_max)
+    v_boundary = [l.v_max for l in sorted_limits]
+    i_boundary = [l.i_max for l in sorted_limits]
 
     # Add corner points for closed boundary
     v_boundary = [0, *v_boundary, v_boundary[-1], 0]