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

oscura/triggering/__init__.py

@@ -0,0 +1,68 @@
+"""Signal triggering and event detection module for TraceKit.
+
+Provides oscilloscope-style triggering functionality including edge
+triggering, pattern triggering, pulse width triggering, glitch detection,
+runt pulse detection, and window/zone triggering.
+
+Example:
+    >>> from oscura.triggering import EdgeTrigger, find_triggers
+    >>> trigger = EdgeTrigger(level=1.5, edge="rising")
+    >>> events = trigger.find_events(trace)
+    >>> # Or use convenience function
+    >>> events = find_triggers(trace, "edge", level=1.5, edge="rising")
+"""
+
+from oscura.triggering.base import (
+    Trigger,
+    TriggerEvent,
+    find_triggers,
+)
+from oscura.triggering.edge import (
+    EdgeTrigger,
+    find_all_edges,
+    find_falling_edges,
+    find_rising_edges,
+)
+from oscura.triggering.pattern import (
+    PatternTrigger,
+    find_pattern,
+)
+from oscura.triggering.pulse import (
+    PulseWidthTrigger,
+    find_glitches,
+    find_pulses,
+    find_runt_pulses,
+)
+from oscura.triggering.window import (
+    WindowTrigger,
+    ZoneTrigger,
+    check_limits,
+    find_window_violations,
+    find_zone_events,
+)
+
+__all__ = [
+    # Edge triggering
+    "EdgeTrigger",
+    # Pattern triggering
+    "PatternTrigger",
+    # Pulse triggering
+    "PulseWidthTrigger",
+    # Base
+    "Trigger",
+    "TriggerEvent",
+    # Window triggering
+    "WindowTrigger",
+    "ZoneTrigger",
+    "check_limits",
+    "find_all_edges",
+    "find_falling_edges",
+    "find_glitches",
+    "find_pattern",
+    "find_pulses",
+    "find_rising_edges",
+    "find_runt_pulses",
+    "find_triggers",
+    "find_window_violations",
+    "find_zone_events",
+]

oscura/triggering/base.py

@@ -0,0 +1,229 @@
+"""Base classes and utilities for TraceKit triggering module.
+
+Provides abstract base class for triggers and common trigger event
+data structure.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Literal
+
+from oscura.core.exceptions import AnalysisError
+
+if TYPE_CHECKING:
+    import numpy as np
+    from numpy.typing import NDArray
+
+    from oscura.core.types import DigitalTrace, WaveformTrace
+
+
+class TriggerType(Enum):
+    """Types of trigger events."""
+
+    RISING_EDGE = "rising_edge"
+    FALLING_EDGE = "falling_edge"
+    PATTERN_MATCH = "pattern_match"
+    PULSE_WIDTH = "pulse_width"
+    GLITCH = "glitch"
+    RUNT = "runt"
+    WINDOW_ENTRY = "window_entry"
+    WINDOW_EXIT = "window_exit"
+    ZONE_VIOLATION = "zone_violation"
+
+
+@dataclass
+class TriggerEvent:
+    """Represents a detected trigger event.
+
+    Attributes:
+        timestamp: Time of the trigger event in seconds.
+        sample_index: Sample index where trigger occurred.
+        event_type: Type of trigger event.
+        level: Voltage/signal level at trigger point.
+        data: Additional event-specific data.
+    """
+
+    timestamp: float
+    sample_index: int
+    event_type: TriggerType
+    level: float | None = None
+    duration: float | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return (
+            f"TriggerEvent({self.event_type.value} at t={self.timestamp:.6e}s, "
+            f"sample={self.sample_index})"
+        )
+
+
+class Trigger(ABC):
+    """Abstract base class for all trigger types.
+
+    Defines the common interface for finding trigger events in traces.
+    """
+
+    @abstractmethod
+    def find_events(
+        self,
+        trace: WaveformTrace | DigitalTrace,
+    ) -> list[TriggerEvent]:
+        """Find all trigger events in a trace.
+
+        Args:
+            trace: Input trace to search.
+
+        Returns:
+            List of trigger events found.
+        """
+        ...
+
+    def find_first(
+        self,
+        trace: WaveformTrace | DigitalTrace,
+    ) -> TriggerEvent | None:
+        """Find the first trigger event.
+
+        Args:
+            trace: Input trace to search.
+
+        Returns:
+            First trigger event, or None if no triggers found.
+        """
+        events = self.find_events(trace)
+        return events[0] if events else None
+
+    def count_events(
+        self,
+        trace: WaveformTrace | DigitalTrace,
+    ) -> int:
+        """Count trigger events.
+
+        Args:
+            trace: Input trace to search.
+
+        Returns:
+            Number of trigger events found.
+        """
+        return len(self.find_events(trace))
+
+
+def find_triggers(
+    trace: WaveformTrace | DigitalTrace,
+    trigger_type: Literal["edge", "pattern", "pulse_width", "glitch", "runt", "window"],
+    **kwargs: Any,
+) -> list[TriggerEvent]:
+    """Unified function to find trigger events.
+
+    Args:
+        trace: Input trace to search.
+        trigger_type: Type of trigger to use.
+        **kwargs: Trigger-specific parameters.
+
+    Returns:
+        List of trigger events.
+
+    Raises:
+        AnalysisError: If unknown trigger type.
+
+    Example:
+        >>> events = find_triggers(trace, "edge", level=1.5, edge="rising")
+        >>> events = find_triggers(trace, "pulse_width", min_width=1e-6, max_width=2e-6)
+        >>> events = find_triggers(trace, "glitch", max_width=50e-9)
+    """
+    from oscura.triggering.edge import EdgeTrigger
+    from oscura.triggering.pulse import PulseWidthTrigger
+    from oscura.triggering.window import WindowTrigger
+
+    if trigger_type == "edge":
+        trigger = EdgeTrigger(
+            level=kwargs.get("level", 0.0),
+            edge=kwargs.get("edge", "rising"),
+            hysteresis=kwargs.get("hysteresis", 0.0),
+        )
+    elif trigger_type == "pattern":
+        from oscura.triggering.pattern import PatternTrigger
+
+        trigger = PatternTrigger(  # type: ignore[assignment]
+            pattern=kwargs.get("pattern", []),
+            levels=kwargs.get("levels"),
+        )
+    elif trigger_type == "pulse_width":
+        trigger = PulseWidthTrigger(  # type: ignore[assignment]
+            level=kwargs.get("level", 0.0),
+            polarity=kwargs.get("polarity", "positive"),
+            min_width=kwargs.get("min_width"),
+            max_width=kwargs.get("max_width"),
+        )
+    elif trigger_type == "glitch":
+        from oscura.triggering.pulse import GlitchTrigger
+
+        trigger = GlitchTrigger(  # type: ignore[assignment]
+            level=kwargs.get("level", 0.0),
+            max_width=kwargs.get("max_width", 100e-9),
+            polarity=kwargs.get("polarity", "either"),
+        )
+    elif trigger_type == "runt":
+        from oscura.triggering.pulse import RuntTrigger
+
+        trigger = RuntTrigger(  # type: ignore[assignment]
+            low_threshold=kwargs.get("low_threshold", 0.0),
+            high_threshold=kwargs.get("high_threshold", 1.0),
+            polarity=kwargs.get("polarity", "either"),
+        )
+    elif trigger_type == "window":
+        trigger = WindowTrigger(  # type: ignore[assignment]
+            low_threshold=kwargs.get("low_threshold", 0.0),
+            high_threshold=kwargs.get("high_threshold", 1.0),
+            trigger_on=kwargs.get("trigger_on", "exit"),
+        )
+    else:
+        raise AnalysisError(f"Unknown trigger type: {trigger_type}")
+
+    return trigger.find_events(trace)
+
+
+def interpolate_crossing(
+    data: NDArray[np.floating[Any]],
+    idx: int,
+    threshold: float,
+    sample_period: float,
+    rising: bool = True,
+) -> float:
+    """Interpolate exact threshold crossing time.
+
+    Args:
+        data: Waveform data array.
+        idx: Sample index near crossing.
+        threshold: Threshold level.
+        sample_period: Time between samples.
+        rising: True for rising edge, False for falling.
+
+    Returns:
+        Interpolated crossing time in seconds.
+    """
+    if idx < 0 or idx >= len(data) - 1:
+        return idx * sample_period
+
+    v1, v2 = data[idx], data[idx + 1]
+
+    if abs(v2 - v1) < 1e-12:
+        return (idx + 0.5) * sample_period
+
+    # Linear interpolation
+    t_offset = (threshold - v1) / (v2 - v1) * sample_period
+    t_offset = max(0, min(sample_period, t_offset))
+
+    return idx * sample_period + t_offset  # type: ignore[no-any-return]
+
+
+__all__ = [
+    "Trigger",
+    "TriggerEvent",
+    "TriggerType",
+    "find_triggers",
+    "interpolate_crossing",
+]

oscura/triggering/edge.py

@@ -0,0 +1,353 @@
+"""Edge triggering for TraceKit.
+
+Provides edge detection with configurable thresholds, hysteresis,
+and edge polarity (rising, falling, or both).
+
+Example:
+    >>> from oscura.triggering.edge import EdgeTrigger, find_rising_edges
+    >>> # Object-oriented approach
+    >>> trigger = EdgeTrigger(level=1.5, edge="rising", hysteresis=0.1)
+    >>> events = trigger.find_events(trace)
+    >>> # Functional approach
+    >>> timestamps = find_rising_edges(trace, level=1.5)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+
+from oscura.core.types import DigitalTrace, WaveformTrace
+from oscura.triggering.base import (
+    Trigger,
+    TriggerEvent,
+    TriggerType,
+    interpolate_crossing,
+)
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class EdgeTrigger(Trigger):
+    """Edge trigger with threshold and optional hysteresis.
+
+    Detects signal crossings of a threshold level with configurable
+    hysteresis for noise immunity.
+
+    Attributes:
+        level: Trigger threshold level.
+        edge: Edge type - "rising", "falling", or "either".
+        hysteresis: Hysteresis band (Schmitt trigger style).
+    """
+
+    def __init__(
+        self,
+        level: float,
+        edge: Literal["rising", "falling", "either"] = "rising",
+        hysteresis: float = 0.0,
+    ) -> None:
+        """Initialize edge trigger.
+
+        Args:
+            level: Trigger threshold level in signal units (e.g., volts).
+            edge: Edge polarity to trigger on.
+            hysteresis: Hysteresis band width. Trigger requires signal to
+                       cross level +/- hysteresis/2 before retriggering.
+        """
+        self.level = level
+        self.edge = edge
+        self.hysteresis = hysteresis
+
+    def find_events(
+        self,
+        trace: WaveformTrace | DigitalTrace,
+    ) -> list[TriggerEvent]:
+        """Find all edge events in the trace.
+
+        Args:
+            trace: Input waveform or digital trace.
+
+        Returns:
+            List of trigger events for each detected edge.
+        """
+        if isinstance(trace, DigitalTrace):
+            # For digital traces, use edge list if available
+            data = trace.data.astype(np.float64)
+        else:
+            data = trace.data
+
+        sample_period = trace.metadata.time_base
+        events: list[TriggerEvent] = []
+
+        if self.hysteresis > 0:
+            # Schmitt trigger mode
+            events = self._find_edges_with_hysteresis(data, sample_period)
+        else:
+            # Simple threshold crossing
+            events = self._find_edges_simple(data, sample_period)
+
+        return events
+
+    def _find_edges_simple(
+        self,
+        data: NDArray[np.floating[Any]],
+        sample_period: float,
+    ) -> list[TriggerEvent]:
+        """Find edges using simple threshold crossing."""
+        events: list[TriggerEvent] = []
+
+        below = data < self.level
+        above = data >= self.level
+
+        if self.edge in ("rising", "either"):
+            # Rising: below -> above
+            rising_idx = np.where(below[:-1] & above[1:])[0]
+            for idx in rising_idx:
+                timestamp = interpolate_crossing(data, idx, self.level, sample_period, rising=True)
+                events.append(
+                    TriggerEvent(
+                        timestamp=timestamp,
+                        sample_index=int(idx),
+                        event_type=TriggerType.RISING_EDGE,
+                        level=float(data[idx + 1]),
+                    )
+                )
+
+        if self.edge in ("falling", "either"):
+            # Falling: above -> below
+            falling_idx = np.where(above[:-1] & below[1:])[0]
+            for idx in falling_idx:
+                timestamp = interpolate_crossing(data, idx, self.level, sample_period, rising=False)
+                events.append(
+                    TriggerEvent(
+                        timestamp=timestamp,
+                        sample_index=int(idx),
+                        event_type=TriggerType.FALLING_EDGE,
+                        level=float(data[idx + 1]),
+                    )
+                )
+
+        # Sort by timestamp if we detected both edge types
+        if self.edge == "either":
+            events.sort(key=lambda e: e.timestamp)
+
+        return events
+
+    def _find_edges_with_hysteresis(
+        self,
+        data: NDArray[np.floating[Any]],
+        sample_period: float,
+    ) -> list[TriggerEvent]:
+        """Find edges using Schmitt trigger with hysteresis."""
+        events: list[TriggerEvent] = []
+
+        high_thresh = self.level + self.hysteresis / 2
+        low_thresh = self.level - self.hysteresis / 2
+
+        # State machine: track if we're currently "high" or "low"
+        state = "low" if data[0] < self.level else "high"
+
+        for i in range(1, len(data)):
+            if state == "low" and data[i] >= high_thresh:
+                # Rising edge detected
+                state = "high"
+                if self.edge in ("rising", "either"):
+                    timestamp = interpolate_crossing(
+                        data, i - 1, high_thresh, sample_period, rising=True
+                    )
+                    events.append(
+                        TriggerEvent(
+                            timestamp=timestamp,
+                            sample_index=i,
+                            event_type=TriggerType.RISING_EDGE,
+                            level=float(data[i]),
+                        )
+                    )
+
+            elif state == "high" and data[i] <= low_thresh:
+                # Falling edge detected
+                state = "low"
+                if self.edge in ("falling", "either"):
+                    timestamp = interpolate_crossing(
+                        data, i - 1, low_thresh, sample_period, rising=False
+                    )
+                    events.append(
+                        TriggerEvent(
+                            timestamp=timestamp,
+                            sample_index=i,
+                            event_type=TriggerType.FALLING_EDGE,
+                            level=float(data[i]),
+                        )
+                    )
+
+        return events
+
+
+def find_rising_edges(
+    trace: WaveformTrace,
+    level: float | None = None,
+    *,
+    hysteresis: float = 0.0,
+    return_indices: bool = False,
+) -> NDArray[np.float64] | NDArray[np.int64]:
+    """Find all rising edge timestamps or indices.
+
+    Args:
+        trace: Input waveform trace.
+        level: Trigger threshold. If None, uses signal midpoint.
+        hysteresis: Hysteresis band for noise immunity.
+        return_indices: If True, return sample indices instead of timestamps.
+
+    Returns:
+        Array of timestamps (seconds) or sample indices.
+
+    Example:
+        >>> edges = find_rising_edges(trace, level=1.5)
+        >>> print(f"Found {len(edges)} rising edges")
+    """
+    if level is None:
+        level = (np.min(trace.data) + np.max(trace.data)) / 2
+
+    trigger = EdgeTrigger(level=level, edge="rising", hysteresis=hysteresis)
+    events = trigger.find_events(trace)
+
+    if return_indices:
+        return np.array([e.sample_index for e in events], dtype=np.int64)
+    return np.array([e.timestamp for e in events], dtype=np.float64)
+
+
+def find_falling_edges(
+    trace: WaveformTrace,
+    level: float | None = None,
+    *,
+    hysteresis: float = 0.0,
+    return_indices: bool = False,
+) -> NDArray[np.float64] | NDArray[np.int64]:
+    """Find all falling edge timestamps or indices.
+
+    Args:
+        trace: Input waveform trace.
+        level: Trigger threshold. If None, uses signal midpoint.
+        hysteresis: Hysteresis band for noise immunity.
+        return_indices: If True, return sample indices instead of timestamps.
+
+    Returns:
+        Array of timestamps (seconds) or sample indices.
+
+    Example:
+        >>> edges = find_falling_edges(trace, level=1.5)
+    """
+    if level is None:
+        level = (np.min(trace.data) + np.max(trace.data)) / 2
+
+    trigger = EdgeTrigger(level=level, edge="falling", hysteresis=hysteresis)
+    events = trigger.find_events(trace)
+
+    if return_indices:
+        return np.array([e.sample_index for e in events], dtype=np.int64)
+    return np.array([e.timestamp for e in events], dtype=np.float64)
+
+
+def find_all_edges(
+    trace: WaveformTrace,
+    level: float | None = None,
+    *,
+    hysteresis: float = 0.0,
+) -> tuple[NDArray[np.float64], NDArray[np.bool_]]:
+    """Find all edges (rising and falling) with polarity.
+
+    Args:
+        trace: Input waveform trace.
+        level: Trigger threshold. If None, uses signal midpoint.
+        hysteresis: Hysteresis band for noise immunity.
+
+    Returns:
+        Tuple of (timestamps, is_rising) where is_rising is True for
+        rising edges and False for falling edges.
+
+    Example:
+        >>> timestamps, is_rising = find_all_edges(trace, level=1.5)
+        >>> rising = timestamps[is_rising]
+        >>> falling = timestamps[~is_rising]
+    """
+    if level is None:
+        level = (np.min(trace.data) + np.max(trace.data)) / 2
+
+    trigger = EdgeTrigger(level=level, edge="either", hysteresis=hysteresis)
+    events = trigger.find_events(trace)
+
+    timestamps = np.array([e.timestamp for e in events], dtype=np.float64)
+    is_rising = np.array([e.event_type == TriggerType.RISING_EDGE for e in events], dtype=np.bool_)
+
+    return timestamps, is_rising
+
+
+def edge_count(
+    trace: WaveformTrace,
+    level: float | None = None,
+    edge: Literal["rising", "falling", "either"] = "either",
+    *,
+    hysteresis: float = 0.0,
+) -> int:
+    """Count edges in a trace.
+
+    Args:
+        trace: Input waveform trace.
+        level: Trigger threshold. If None, uses signal midpoint.
+        edge: Edge type to count.
+        hysteresis: Hysteresis band for noise immunity.
+
+    Returns:
+        Number of edges found.
+
+    Example:
+        >>> n_rising = edge_count(trace, level=1.5, edge="rising")
+    """
+    if level is None:
+        level = (np.min(trace.data) + np.max(trace.data)) / 2
+
+    trigger = EdgeTrigger(level=level, edge=edge, hysteresis=hysteresis)
+    return trigger.count_events(trace)
+
+
+def edge_rate(
+    trace: WaveformTrace,
+    level: float | None = None,
+    edge: Literal["rising", "falling", "either"] = "either",
+    *,
+    hysteresis: float = 0.0,
+) -> float:
+    """Calculate edge rate (edges per second).
+
+    Args:
+        trace: Input waveform trace.
+        level: Trigger threshold.
+        edge: Edge type to count.
+        hysteresis: Hysteresis band for noise immunity.
+
+    Returns:
+        Edge rate in Hz.
+
+    Example:
+        >>> rate = edge_rate(trace, level=1.5, edge="rising")
+        >>> print(f"Toggle rate: {rate} Hz")
+    """
+    count = edge_count(trace, level, edge, hysteresis=hysteresis)
+    duration = trace.duration
+
+    if duration <= 0:
+        return 0.0
+
+    return count / duration
+
+
+__all__ = [
+    "EdgeTrigger",
+    "edge_count",
+    "edge_rate",
+    "find_all_edges",
+    "find_falling_edges",
+    "find_rising_edges",
+]