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

oscura/utils/__init__.py

@@ -1,8 +1,11 @@
 """Oscura utilities package.
 
-Provides utility functions for memory management, windowing, and progressive analysis.
+Provides utility functions for memory management, windowing, progressive analysis,
+geometry, serial communication, validation, and bitwise operations.
 """
 
+from oscura.utils.bitwise import bits_to_byte, bits_to_value
+from oscura.utils.geometry import generate_leader_line
 from oscura.utils.memory import (
     MemoryCheck,
     MemoryCheckError,
@@ -50,6 +53,8 @@ from oscura.utils.progressive import (
     progressive_analysis,
     select_roi,
 )
+from oscura.utils.serial import connect_serial_port
+from oscura.utils.validation import validate_protocol_spec
 
 __all__ = [
     # Advanced memory management (MEM-014, 020, 023, 025, 028, 030-033)
@@ -75,13 +80,20 @@ __all__ = [
     "ROISelection",
     "WSLSwapChecker",
     "analyze_roi",
+    # Bitwise operations
+    "bits_to_byte",
+    "bits_to_value",
     "check_memory_available",
     "configure_memory",
+    # Serial communication
+    "connect_serial_port",
     "create_preview",
     "detect_wsl",
     "estimate_memory",
     "estimate_optimal_preview_factor",
     "gc_aggressive",
+    # Geometry
+    "generate_leader_line",
     "get_available_memory",
     "get_max_memory",
     "get_memory_config",
@@ -96,4 +108,6 @@ __all__ = [
     "select_roi",
     "set_max_memory",
     "suggest_downsampling",
+    # Validation
+    "validate_protocol_spec",
 ]

oscura/utils/bitwise.py

@@ -0,0 +1,118 @@
+"""Bitwise operation utilities for protocol decoding.
+
+This module provides bitwise conversion utilities used across protocol analyzers.
+Performance-optimized with NumPy vectorized operations (10-100x faster for large arrays).
+"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def bits_to_byte(bits: list[int] | NDArray[np.uint8], lsb_first: bool = True) -> int:
+    """Convert up to 8 bits to byte value.
+
+    Performance: Uses NumPy vectorized operations for 10-100x speedup vs loops.
+
+    Args:
+        bits: List or array of bits (0 or 1)
+        lsb_first: If True, bits[0] is LSB. If False, bits[0] is MSB.
+
+    Returns:
+        Byte value (0-255)
+
+    Raises:
+        ValueError: If bits contain values other than 0 or 1
+
+    Example:
+        >>> bits_to_byte([1, 0, 1, 0, 1, 0, 1, 0])  # LSB first
+        85
+        >>> bits_to_byte([1, 0, 1, 0, 1, 0, 1, 0], lsb_first=False)  # MSB first
+        170
+    """
+    # Validate input types before conversion
+    if isinstance(bits, (list, tuple)):
+        # Check for non-integer types in list/tuple
+        if any(not isinstance(b, (int, np.integer)) for b in bits):
+            raise ValueError("All bits must be 0 or 1")
+
+    # Convert to numpy array for vectorized operations
+    bits_arr = np.asarray(bits, dtype=np.uint8)
+
+    if not np.all((bits_arr == 0) | (bits_arr == 1)):
+        raise ValueError("All bits must be 0 or 1")
+
+    num_bits = min(8, len(bits_arr))
+    bits_arr = bits_arr[:num_bits]
+
+    if lsb_first:
+        # Vectorized: bits[i] * 2^i
+        shifts = np.arange(num_bits, dtype=np.uint8)
+        value = np.sum(bits_arr << shifts)
+    else:
+        # Vectorized: bits[i] * 2^(7-i)
+        shifts = np.arange(7, 7 - num_bits, -1, dtype=np.uint8)
+        value = np.sum(bits_arr << shifts)
+
+    return int(value)
+
+
+def bits_to_value(bits: list[int] | NDArray[np.uint8], lsb_first: bool = True) -> int:
+    """Convert arbitrary number of bits to integer value.
+
+    Performance: Uses NumPy vectorized operations for 10-100x speedup vs loops.
+
+    Args:
+        bits: List or array of bits (0 or 1)
+        lsb_first: If True, bits[0] is LSB. If False, bits[0] is MSB.
+
+    Returns:
+        Integer value
+
+    Raises:
+        ValueError: If bits contain values other than 0 or 1
+
+    Example:
+        >>> bits_to_value([1, 1, 1, 1, 1, 1, 1, 1, 1, 1])  # 10 bits
+        1023
+        >>> bits_to_value([1, 0, 1, 0], lsb_first=False)
+        10
+    """
+    # Validate input types before conversion
+    if isinstance(bits, (list, tuple)):
+        # Check for non-integer types in list/tuple
+        if any(not isinstance(b, (int, np.integer)) for b in bits):
+            raise ValueError("All bits must be 0 or 1")
+
+    # Convert to numpy array for vectorized operations
+    bits_arr = np.asarray(bits, dtype=np.uint8)
+
+    if not np.all((bits_arr == 0) | (bits_arr == 1)):
+        raise ValueError("All bits must be 0 or 1")
+
+    num_bits = len(bits_arr)
+
+    # For very large bit arrays (>64 bits), use packbits for efficiency
+    if num_bits > 64:
+        if lsb_first:
+            # Reverse for LSB-first interpretation
+            bits_arr = bits_arr[::-1]
+        # Pack into bytes (MSB first)
+        packed = np.packbits(bits_arr, bitorder="big")
+        # Convert bytes to integer
+        value = int.from_bytes(packed.tobytes(), byteorder="big")
+        # Adjust for partial byte
+        if not lsb_first:
+            value >>= (8 - (num_bits % 8)) % 8
+        return value
+
+    # For smaller arrays, use vectorized shift and sum
+    if lsb_first:
+        # Vectorized: bits[i] * 2^i
+        shifts = np.arange(num_bits, dtype=np.uint64)
+        value = np.sum(bits_arr.astype(np.uint64) << shifts)
+    else:
+        # Vectorized: bits[i] * 2^(num_bits-1-i)
+        shifts = np.arange(num_bits - 1, -1, -1, dtype=np.uint64)
+        value = np.sum(bits_arr.astype(np.uint64) << shifts)
+
+    return int(value)

oscura/{builders → utils/builders}/__init__.py

@@ -32,7 +32,7 @@ References:
     - Protocol Test Signal Specifications
 """
 
-from oscura.builders.signal_builder import SignalBuilder
+from oscura.utils.builders.signal_builder import SignalBuilder
 
 __all__ = [
     "SignalBuilder",

oscura/{comparison → utils/comparison}/__init__.py

@@ -4,31 +4,31 @@ This module provides waveform comparison, limit testing, mask testing,
 and golden waveform comparison functionality.
 """
 
-from oscura.comparison.compare import (
+from oscura.utils.comparison.compare import (
     compare_traces,
     correlation,
     difference,
     similarity_score,
 )
-from oscura.comparison.golden import (
+from oscura.utils.comparison.golden import (
     GoldenReference,
     compare_to_golden,
     create_golden,
     tolerance_envelope,
 )
-from oscura.comparison.limits import (
+from oscura.utils.comparison.limits import (
     LimitSpec,
     check_limits,
     create_limit_spec,
     margin_analysis,
 )
-from oscura.comparison.mask import (
+from oscura.utils.comparison.mask import (
     Mask,
     create_mask,
     eye_mask,
     mask_test,
 )
-from oscura.comparison.trace_diff import (
+from oscura.utils.comparison.trace_diff import (
     Difference,
     TraceDiff,
 )
@@ -36,7 +36,7 @@ from oscura.comparison.trace_diff import (
 # Note: compare_traces is imported from both compare.py and trace_diff.py
 # The trace_diff version is from discovery.comparison (intelligent comparison)
 # Import as compare_traces_intelligent to avoid conflict
-from oscura.comparison.trace_diff import compare_traces as compare_traces_intelligent
+from oscura.utils.comparison.trace_diff import compare_traces as compare_traces_intelligent
 
 __all__ = [
     # Intelligent trace diff (DISC-004)

oscura/{comparison → utils/comparison}/compare.py

@@ -5,7 +5,7 @@ difference calculation, correlation, and similarity scoring.
 
 
 Example:
-    >>> from oscura.comparison import compare_traces, similarity_score
+    >>> from oscura.utils.comparison import compare_traces, similarity_score
     >>> result = compare_traces(trace1, trace2)
     >>> score = similarity_score(trace1, trace2)
 
@@ -205,11 +205,30 @@ def similarity_score(
         >>> if score > 0.95:
         ...     print("Traces match")
     """
-    # Get data
+    data1, data2 = _prepare_trace_data(trace1, trace2, normalize_offset, normalize_amplitude)
+
+    if method == "correlation":
+        return _correlation_similarity(data1, data2)
+    elif method == "rms":
+        return _rms_similarity(data1, data2)
+    elif method == "mse":
+        return _mse_similarity(data1, data2)
+    elif method == "cosine":
+        return _cosine_similarity(data1, data2)
+    else:
+        raise ValueError(f"Unknown similarity method: {method}")
+
+
+def _prepare_trace_data(
+    trace1: WaveformTrace,
+    trace2: WaveformTrace,
+    normalize_offset: bool,
+    normalize_amplitude: bool,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Prepare trace data for similarity comparison."""
     data1 = trace1.data.astype(np.float64).copy()
     data2 = trace2.data.astype(np.float64).copy()
 
-    # Check for NaN/Inf values
     if np.any(~np.isfinite(data1)) or np.any(~np.isfinite(data2)):
         raise ValueError("Input traces contain NaN or Inf values")
 
@@ -232,151 +251,180 @@ def similarity_score(
         if std2 > 0:
             data2 = data2 / std2
 
-    if method == "correlation":
-        # Pearson correlation coefficient
-        # Handle constant inputs gracefully
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore", category=stats.ConstantInputWarning)
-            try:
-                r, _ = stats.pearsonr(data1, data2)
-                # Handle NaN result (constant traces after normalization)
-                if np.isnan(r):
-                    # If both traces are constant and identical, perfect match
-                    if np.allclose(data1, data2, equal_nan=False):
-                        r = 1.0
-                    else:
-                        r = 0.0
-            except Exception:
-                r = 0.0
-        # Map from [-1, 1] to [0, 1]
-        return float((r + 1) / 2)
+    return data1, data2
 
-    elif method == "rms":
-        # RMS-based similarity
-        rms_diff = np.sqrt(np.mean((data1 - data2) ** 2))
-        rms_ref = np.sqrt(np.mean(data2**2)) + 1e-10
-        return float(max(0, 1 - rms_diff / rms_ref))
 
-    elif method == "mse":
-        # MSE-based similarity
-        mse = np.mean((data1 - data2) ** 2)
-        var_ref = np.var(data2) + 1e-10
-        return float(max(0, 1 - mse / var_ref))
+def _correlation_similarity(data1: NDArray[np.float64], data2: NDArray[np.float64]) -> float:
+    """Compute Pearson correlation-based similarity."""
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=stats.ConstantInputWarning)
+        try:
+            r, _ = stats.pearsonr(data1, data2)
+            if np.isnan(r):
+                r = 1.0 if np.allclose(data1, data2, equal_nan=False) else 0.0
+        except Exception:
+            r = 0.0
+    return float((r + 1) / 2)
 
-    elif method == "cosine":
-        # Cosine similarity
-        dot = np.dot(data1, data2)
-        norm1 = np.linalg.norm(data1) + 1e-10
-        norm2 = np.linalg.norm(data2) + 1e-10
-        cosine = dot / (norm1 * norm2)
-        # Map from [-1, 1] to [0, 1]
-        return float((cosine + 1) / 2)
 
-    else:
-        raise ValueError(f"Unknown similarity method: {method}")
+def _rms_similarity(data1: NDArray[np.float64], data2: NDArray[np.float64]) -> float:
+    """Compute RMS-based similarity."""
+    rms_diff = np.sqrt(np.mean((data1 - data2) ** 2))
+    rms_ref = np.sqrt(np.mean(data2**2)) + 1e-10
+    return float(max(0, 1 - rms_diff / rms_ref))
 
 
-def compare_traces(
-    trace1: WaveformTrace,
-    trace2: WaveformTrace,
-    *,
-    tolerance: float | None = None,
-    tolerance_pct: float | None = None,
-    method: Literal["absolute", "relative", "statistical"] = "absolute",
-    include_difference: bool = True,
-) -> ComparisonResult:
-    """Compare two traces and determine if they match.
+def _mse_similarity(data1: NDArray[np.float64], data2: NDArray[np.float64]) -> float:
+    """Compute MSE-based similarity."""
+    mse = np.mean((data1 - data2) ** 2)
+    var_ref = np.var(data2) + 1e-10
+    return float(max(0, 1 - mse / var_ref))
 
-    Comprehensive comparison of two waveforms including difference
-    analysis, correlation, and match determination.
 
-    Args:
-        trace1: First trace (typically measured).
-        trace2: Second trace (typically reference).
-        tolerance: Absolute tolerance for matching.
-        tolerance_pct: Percentage tolerance (0-100) relative to reference range.
-        method: Comparison method:
-            - "absolute": Compare absolute values
-            - "relative": Compare relative to reference
-            - "statistical": Use statistical tests
-        include_difference: Include difference trace in result.
+def _cosine_similarity(data1: NDArray[np.float64], data2: NDArray[np.float64]) -> float:
+    """Compute cosine similarity."""
+    dot = np.dot(data1, data2)
+    norm1 = np.linalg.norm(data1) + 1e-10
+    norm2 = np.linalg.norm(data2) + 1e-10
+    cosine = dot / (norm1 * norm2)
+    return float((cosine + 1) / 2)
 
-    Returns:
-        ComparisonResult with match status and statistics.
 
-    Raises:
-        ValueError: If method is unknown.
+def _align_trace_data(
+    trace1: WaveformTrace, trace2: WaveformTrace
+) -> tuple[NDArray[np.float64], NDArray[np.float64], int]:
+    """Align trace data to same length.
 
-    Example:
-        >>> result = compare_traces(measured, golden, tolerance=0.01)
-        >>> if result.match:
-        ...     print(f"Match! Similarity: {result.similarity:.1%}")
+    Args:
+        trace1: First trace.
+        trace2: Second trace.
+
+    Returns:
+        Tuple of (data1, data2, min_len).
     """
-    # Get data
     data1 = trace1.data.astype(np.float64)
     data2 = trace2.data.astype(np.float64)
-
-    # Align lengths
     min_len = min(len(data1), len(data2))
-    data1 = data1[:min_len]
-    data2 = data2[:min_len]
+    return data1[:min_len], data2[:min_len], min_len
 
-    # Compute difference
-    diff = data1 - data2
 
-    # Compute statistics
+def _compute_difference_stats(diff: NDArray[np.float64]) -> tuple[float, float]:
+    """Compute max and RMS of difference.
+
+    Args:
+        diff: Difference array.
+
+    Returns:
+        Tuple of (max_diff, rms_diff).
+    """
     max_diff = float(np.max(np.abs(diff)))
     rms_diff = float(np.sqrt(np.mean(diff**2)))
+    return max_diff, rms_diff
+
 
-    # Compute correlation
+def _compute_correlation_coefficient(
+    data1: NDArray[np.float64], data2: NDArray[np.float64]
+) -> float:
+    """Compute Pearson correlation coefficient.
+
+    Args:
+        data1: First data array.
+        data2: Second data array.
+
+    Returns:
+        Correlation coefficient.
+    """
     if len(data1) > 1:
-        # Handle constant inputs (e.g., DC signals) gracefully
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", category=stats.ConstantInputWarning)
             try:
                 corr, _ = stats.pearsonr(data1, data2)
             except Exception:
-                # Fallback for any correlation computation issues
                 corr = 0.0
     else:
         corr = 1.0 if data1[0] == data2[0] else 0.0
+    return float(corr)
 
-    # Compute similarity score
-    sim_score = similarity_score(trace1, trace2)
 
-    # Determine tolerance
+def _determine_tolerance(
+    tolerance: float | None, tolerance_pct: float | None, data2: NDArray[np.float64]
+) -> float:
+    """Determine effective tolerance value.
+
+    Args:
+        tolerance: Absolute tolerance value.
+        tolerance_pct: Percentage tolerance.
+        data2: Reference data array.
+
+    Returns:
+        Effective tolerance value.
+    """
     if tolerance is None and tolerance_pct is not None:
         ref_range = float(np.ptp(data2))
-        tolerance = ref_range * tolerance_pct / 100.0
+        return ref_range * tolerance_pct / 100.0
     elif tolerance is None:
-        # Default: 1% of reference range
         ref_range = float(np.ptp(data2))
-        tolerance = ref_range * 0.01
+        return ref_range * 0.01
+    return tolerance
 
-    # Find violations
-    violations = np.where(np.abs(diff) > tolerance)[0]
 
-    # Determine match
+def _determine_match(
+    method: str,
+    max_diff: float,
+    tolerance: float,
+    tolerance_pct: float | None,
+    data1: NDArray[np.float64],
+    data2: NDArray[np.float64],
+) -> bool:
+    """Determine if traces match based on method.
+
+    Args:
+        method: Comparison method.
+        max_diff: Maximum difference.
+        tolerance: Tolerance value.
+        tolerance_pct: Percentage tolerance.
+        data1: First data array.
+        data2: Second data array.
+
+    Returns:
+        True if traces match.
+
+    Raises:
+        ValueError: If method is unknown.
+    """
     if method == "absolute":
-        match = max_diff <= tolerance
+        return max_diff <= tolerance
     elif method == "relative":
         ref_range = float(np.ptp(data2)) + 1e-10
         relative_max = max_diff / ref_range
-        match = relative_max <= (tolerance_pct or 1.0) / 100.0
+        return relative_max <= (tolerance_pct or 1.0) / 100.0
     elif method == "statistical":
-        # Use t-test for statistical matching
         _, p_value = stats.ttest_rel(data1, data2)
-        match = p_value > 0.05  # No significant difference
+        return bool(p_value > 0.05)
     else:
         raise ValueError(f"Unknown method: {method}")
 
-    # Create difference trace if requested
-    diff_trace = None
-    if include_difference:
-        diff_trace = difference(trace1, trace2, channel_name="comparison_diff")
 
-    # Compute additional statistics
-    statistics = {
+def _compute_comparison_statistics(
+    diff: NDArray[np.float64],
+    violations: NDArray[np.int64],
+    min_len: int,
+    data1: NDArray[np.float64],
+    data2: NDArray[np.float64],
+) -> dict[str, float]:
+    """Compute additional comparison statistics.
+
+    Args:
+        diff: Difference array.
+        violations: Violation indices.
+        min_len: Minimum length.
+        data1: First data array.
+        data2: Second data array.
+
+    Returns:
+        Dictionary of statistics.
+    """
+    return {
         "mean_difference": float(np.mean(diff)),
         "std_difference": float(np.std(diff)),
         "median_difference": float(np.median(diff)),
@@ -385,6 +433,59 @@ def compare_traces(
         "p_value": float(stats.ttest_rel(data1, data2)[1]) if len(data1) > 1 else 1.0,
     }
 
+
+def compare_traces(
+    trace1: WaveformTrace,
+    trace2: WaveformTrace,
+    *,
+    tolerance: float | None = None,
+    tolerance_pct: float | None = None,
+    method: Literal["absolute", "relative", "statistical"] = "absolute",
+    include_difference: bool = True,
+) -> ComparisonResult:
+    """Compare two traces and determine if they match.
+
+    Comprehensive comparison of two waveforms including difference
+    analysis, correlation, and match determination.
+
+    Args:
+        trace1: First trace (typically measured).
+        trace2: Second trace (typically reference).
+        tolerance: Absolute tolerance for matching.
+        tolerance_pct: Percentage tolerance (0-100) relative to reference range.
+        method: Comparison method:
+            - "absolute": Compare absolute values
+            - "relative": Compare relative to reference
+            - "statistical": Use statistical tests
+        include_difference: Include difference trace in result.
+
+    Returns:
+        ComparisonResult with match status and statistics.
+
+    Raises:
+        ValueError: If method is unknown.
+
+    Example:
+        >>> result = compare_traces(measured, golden, tolerance=0.01)
+        >>> if result.match:
+        ...     print(f"Match! Similarity: {result.similarity:.1%}")
+    """
+    data1, data2, min_len = _align_trace_data(trace1, trace2)
+    diff = data1 - data2
+
+    max_diff, rms_diff = _compute_difference_stats(diff)
+    corr = _compute_correlation_coefficient(data1, data2)
+    sim_score = similarity_score(trace1, trace2)
+
+    tolerance = _determine_tolerance(tolerance, tolerance_pct, data2)
+    violations = np.where(np.abs(diff) > tolerance)[0]
+    match = _determine_match(method, max_diff, tolerance, tolerance_pct, data1, data2)
+
+    diff_trace = (
+        difference(trace1, trace2, channel_name="comparison_diff") if include_difference else None
+    )
+    statistics = _compute_comparison_statistics(diff, violations, min_len, data1, data2)
+
     return ComparisonResult(
         match=match,
         similarity=sim_score,