oscura 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

oscura/acquisition/synthetic.py

@@ -0,0 +1,229 @@
+"""Synthetic signal generation source.
+
+This module provides SyntheticSource, which wraps SignalBuilder to implement
+the unified Source protocol. SyntheticSource makes synthetic signals consistent
+with all other acquisition methods (files, hardware).
+
+Example:
+    >>> from oscura.acquisition import SyntheticSource
+    >>> from oscura import SignalBuilder
+    >>>
+    >>> # Create signal builder
+    >>> builder = SignalBuilder(sample_rate=1e6, duration=0.01)
+    >>> builder = builder.add_sine(frequency=1000, amplitude=1.0)
+    >>> builder = builder.add_noise(snr_db=40)
+    >>>
+    >>> # Wrap in Source for unified interface
+    >>> source = SyntheticSource(builder)
+    >>> trace = source.read()
+    >>>
+    >>> # Or one-liner
+    >>> source = SyntheticSource(
+    ...     SignalBuilder().sample_rate(1e6).add_sine(1000).add_noise(snr_db=40)
+    ... )
+    >>> trace = source.read()
+
+Pattern:
+    SyntheticSource bridges SignalBuilder (generator pattern) with
+    Source protocol (acquisition pattern). This enables:
+    - Polymorphic use with FileSource and HardwareSource
+    - Session management with synthetic signals
+    - Pipeline composition with generated data
+
+Note:
+    SignalBuilder.build() returns WaveformTrace for single-channel signals.
+    SignalBuilder.build_channels() returns dict[str, WaveformTrace] for multi-channel.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oscura.builders.signal_builder import SignalBuilder
+    from oscura.core.types import Trace, WaveformTrace
+
+
+class SyntheticSource:
+    """Synthetic signal source implementing Source protocol.
+
+    Wraps SignalBuilder to provide unified acquisition interface.
+    Enables synthetic signals to be used anywhere a Source is expected.
+
+    Attributes:
+        builder: SignalBuilder instance to generate from.
+        channel: Channel name to extract (for multi-channel signals).
+
+    Example:
+        >>> from oscura import SignalBuilder
+        >>> from oscura.acquisition import SyntheticSource
+        >>>
+        >>> # Create builder
+        >>> builder = (SignalBuilder(sample_rate=1e6, duration=0.01)
+        ...     .add_sine(frequency=1000)
+        ...     .add_noise(snr_db=40))
+        >>>
+        >>> # Wrap in source
+        >>> source = SyntheticSource(builder)
+        >>> trace = source.read()
+        >>>
+        >>> # Multi-channel
+        >>> builder = SignalBuilder().sample_rate(1e6)
+        >>> builder = builder.add_sine(1000, channel="sig")
+        >>> builder = builder.add_square(500, channel="clk")
+        >>> source = SyntheticSource(builder, channel="sig")
+        >>> trace = source.read()  # Gets "sig" channel only
+    """
+
+    def __init__(
+        self,
+        builder: SignalBuilder,
+        *,
+        channel: str | None = None,
+    ) -> None:
+        """Initialize synthetic source.
+
+        Args:
+            builder: SignalBuilder instance to generate from.
+            channel: Optional channel name for multi-channel signals.
+                If None, uses first channel (or converts multi-channel to
+                single-channel trace if possible).
+
+        Example:
+            >>> builder = SignalBuilder().sample_rate(1e6).add_sine(1000)
+            >>> source = SyntheticSource(builder)
+            >>> source = SyntheticSource(builder, channel="ch1")
+        """
+        self.builder = builder
+        self.channel = channel
+        self._closed = False
+        self._cached_trace: WaveformTrace | None = None
+
+    def read(self) -> Trace:
+        """Generate and return complete trace.
+
+        Returns:
+            WaveformTrace with generated signal data.
+
+        Raises:
+            ValueError: If source is closed or builder has no signals.
+
+        Example:
+            >>> builder = SignalBuilder().sample_rate(1e6).add_sine(1000)
+            >>> source = SyntheticSource(builder)
+            >>> trace = source.read()
+            >>> print(f"Generated {len(trace.data)} samples")
+
+        Note:
+            This method caches the generated trace to avoid regenerating
+            on multiple calls. Call close() and recreate to generate new data.
+        """
+        if self._closed:
+            raise ValueError("Cannot read from closed source")
+
+        # Return cached trace if available
+        if self._cached_trace is not None:
+            return self._cached_trace
+
+        # Build signal
+        # Phase 0.2: build() now returns WaveformTrace directly
+        trace = self.builder.build(channel=self.channel)
+
+        self._cached_trace = trace
+        return trace
+
+    def stream(self, chunk_size: int) -> Iterator[Trace]:
+        """Stream generated signal in chunks.
+
+        Args:
+            chunk_size: Number of samples per chunk.
+
+        Yields:
+            Trace chunks.
+
+        Example:
+            >>> builder = SignalBuilder().sample_rate(1e6).duration(1.0).add_sine(1000)
+            >>> source = SyntheticSource(builder)
+            >>> for chunk in source.stream(chunk_size=10000):
+            ...     process_chunk(chunk)
+
+        Note:
+            Synthetic signals are generated once and sliced into chunks.
+            This is different from hardware streaming where data arrives continuously.
+        """
+        if self._closed:
+            raise ValueError("Cannot stream from closed source")
+
+        # Generate full trace
+        trace = self.read()
+
+        # Yield chunks
+        from oscura.core.types import DigitalTrace, IQTrace, TraceMetadata, WaveformTrace
+
+        # IQTrace not supported by SyntheticSource
+        if isinstance(trace, IQTrace):
+            raise TypeError("IQTrace not supported by SyntheticSource")
+
+        n_samples = len(trace.data)
+
+        for start in range(0, n_samples, chunk_size):
+            end = min(start + chunk_size, n_samples)
+            chunk_data = trace.data[start:end]
+
+            # Create chunk metadata (same as parent)
+            chunk_metadata = TraceMetadata(
+                sample_rate=trace.metadata.sample_rate,
+                vertical_scale=trace.metadata.vertical_scale,
+                vertical_offset=trace.metadata.vertical_offset,
+                acquisition_time=trace.metadata.acquisition_time,
+                trigger_info=trace.metadata.trigger_info,
+                source_file=trace.metadata.source_file,
+                channel_name=trace.metadata.channel_name,
+                calibration_info=trace.metadata.calibration_info,
+            )
+
+            if isinstance(trace, DigitalTrace):
+                yield DigitalTrace(data=chunk_data, metadata=chunk_metadata)  # type: ignore[arg-type]
+            else:
+                yield WaveformTrace(data=chunk_data, metadata=chunk_metadata)  # type: ignore[arg-type]
+
+    def close(self) -> None:
+        """Close the source and release resources.
+
+        For synthetic sources, this clears the cached trace.
+
+        Example:
+            >>> source = SyntheticSource(builder)
+            >>> trace = source.read()
+            >>> source.close()
+            >>> # source.read() would now fail
+        """
+        self._closed = True
+        self._cached_trace = None
+
+    def __enter__(self) -> SyntheticSource:
+        """Context manager entry.
+
+        Returns:
+            Self for use in 'with' statement.
+
+        Example:
+            >>> with SyntheticSource(builder) as source:
+            ...     trace = source.read()
+        """
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit.
+
+        Automatically calls close() when exiting 'with' block.
+        """
+        self.close()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"SyntheticSource(builder={self.builder!r}, channel={self.channel!r})"
+
+
+__all__ = ["SyntheticSource"]

oscura/acquisition/visa.py

@@ -0,0 +1,376 @@
+"""PyVISA oscilloscope and instrument acquisition source.
+
+This module provides VISASource for acquiring waveforms from oscilloscopes and
+other SCPI-compatible instruments via PyVISA. Supports USB, GPIB, Ethernet, and
+serial connections.
+
+The VISA source communicates with instruments using SCPI commands and acquires
+waveform data directly from the oscilloscope, returning WaveformTrace format
+for analysis.
+
+Example:
+    >>> from oscura.acquisition import HardwareSource
+    >>>
+    >>> # USB oscilloscope
+    >>> with HardwareSource.visa("USB0::0x0699::0x0401::INSTR") as scope:
+    ...     scope.configure(channels=[1, 2], timebase=1e-6)
+    ...     trace = scope.read()
+    >>>
+    >>> # Ethernet oscilloscope
+    >>> with HardwareSource.visa("TCPIP::192.168.1.100::INSTR") as scope:
+    ...     scope.configure(channels=[1], vertical_scale=0.5)
+    ...     trace = scope.read()
+    >>>
+    >>> # Auto-detect
+    >>> with HardwareSource.visa() as scope:
+    ...     trace = scope.read()
+
+Dependencies:
+    Requires pyvisa and pyvisa-py: pip install pyvisa pyvisa-py
+
+Platform:
+    Cross-platform (Windows, macOS, Linux).
+
+Supported Instruments:
+    - Tektronix oscilloscopes (DPO, MSO, MDO series)
+    - Keysight oscilloscopes (InfiniiVision, MSO-X series)
+    - Rigol oscilloscopes (DS1000Z, DS4000 series)
+    - Other SCPI-compatible instruments
+
+References:
+    PyVISA: https://pyvisa.readthedocs.io/
+    SCPI Standard: IEEE 488.2
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pyvisa import Resource, ResourceManager
+
+    from oscura.core.types import Trace
+
+
+class VISASource:
+    """PyVISA instrument acquisition source.
+
+    Acquires waveforms from oscilloscopes and other SCPI-compatible instruments
+    via PyVISA. Supports multiple connection types (USB, GPIB, Ethernet, serial).
+
+    Attributes:
+        resource: VISA resource string.
+        instrument: PyVISA instrument instance.
+        channels: Configured channel list.
+        timebase: Configured timebase in seconds/division.
+        vertical_scale: Configured vertical scale in volts/division.
+
+    Example:
+        >>> scope = VISASource("USB0::0x0699::0x0401::INSTR")
+        >>> scope.configure(channels=[1, 2], timebase=1e-6)
+        >>> trace = scope.read()
+    """
+
+    def __init__(
+        self,
+        resource: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize VISA source.
+
+        Args:
+            resource: VISA resource string (optional, auto-detects if None).
+                Examples: "USB0::0x0699::0x0401::INSTR", "TCPIP::192.168.1.100::INSTR"
+            **kwargs: Additional PyVISA configuration options.
+
+        Raises:
+            ImportError: If pyvisa is not installed.
+
+        Example:
+            >>> scope = VISASource("USB0::0x0699::0x0401::INSTR")
+            >>> scope = VISASource()  # Auto-detect
+        """
+        self.resource = resource
+        self.kwargs = kwargs
+        self.rm: ResourceManager | None = None
+        self.instrument: Resource | None = None
+        self._closed = False
+
+        # Configuration
+        self.channels: list[int] = [1]
+        self.timebase: float = 1e-6
+        self.vertical_scale: float = 1.0
+        self.record_length: int = 10000
+
+    def _ensure_connection(self) -> None:
+        """Ensure connection to VISA instrument.
+
+        Raises:
+            ImportError: If pyvisa is not installed.
+            RuntimeError: If no instrument found or connection fails.
+        """
+        if self.instrument is not None:
+            return
+
+        try:
+            import pyvisa
+        except ImportError as e:
+            raise ImportError(
+                "VISA source requires pyvisa library. Install with: pip install pyvisa pyvisa-py"
+            ) from e
+
+        try:
+            self.rm = pyvisa.ResourceManager()
+
+            # Auto-detect if resource not specified
+            if self.resource is None:
+                resources = self.rm.list_resources()
+                if not resources:
+                    raise RuntimeError("No VISA instruments found")
+                self.resource = resources[0]
+
+            self.instrument = self.rm.open_resource(self.resource, **self.kwargs)
+
+            # Query instrument identity
+            try:
+                idn = self.instrument.query("*IDN?")
+                print(f"Connected to: {idn.strip()}")
+            except Exception:
+                # Some instruments may not support *IDN?
+                pass
+
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to connect to VISA instrument '{self.resource}'. "
+                f"Ensure instrument is connected and powered on. "
+                f"Error: {e}"
+            ) from e
+
+    def configure(
+        self,
+        *,
+        channels: list[int] | None = None,
+        timebase: float | None = None,
+        vertical_scale: float | None = None,
+        record_length: int | None = None,
+    ) -> None:
+        """Configure oscilloscope acquisition parameters.
+
+        Args:
+            channels: List of channel numbers to acquire (e.g., [1, 2]).
+            timebase: Timebase in seconds/division (e.g., 1e-6 for 1 µs/div).
+            vertical_scale: Vertical scale in volts/division (e.g., 0.5).
+            record_length: Number of samples to acquire (e.g., 10000).
+
+        Example:
+            >>> scope = VISASource()
+            >>> scope.configure(
+            ...     channels=[1, 2],
+            ...     timebase=1e-6,
+            ...     vertical_scale=0.5,
+            ...     record_length=10000
+            ... )
+        """
+        if channels is not None:
+            self.channels = channels
+        if timebase is not None:
+            self.timebase = timebase
+        if vertical_scale is not None:
+            self.vertical_scale = vertical_scale
+        if record_length is not None:
+            self.record_length = record_length
+
+        # Apply configuration to instrument
+        self._ensure_connection()
+
+        try:
+            # Set horizontal (timebase)
+            self.instrument.write(f":TIMebase:SCALe {self.timebase}")  # type: ignore[union-attr]
+
+            # Set vertical scale for each channel
+            for ch in self.channels:
+                self.instrument.write(f":CHANnel{ch}:SCALe {self.vertical_scale}")  # type: ignore[union-attr]
+                self.instrument.write(f":CHANnel{ch}:DISPlay ON")  # type: ignore[union-attr]
+
+            # Set record length
+            self.instrument.write(f":ACQuire:POINts {self.record_length}")  # type: ignore[union-attr]
+
+        except Exception as e:
+            # SCPI commands vary by manufacturer, log but continue
+            print(f"Warning: Configuration command failed: {e}")
+
+    def read(self, channel: int | None = None) -> Trace:
+        """Read waveform from oscilloscope.
+
+        Args:
+            channel: Channel to read (uses first configured channel if None).
+
+        Returns:
+            WaveformTrace containing acquired waveform.
+
+        Raises:
+            ImportError: If pyvisa is not installed.
+            RuntimeError: If acquisition fails.
+            ValueError: If source is closed.
+
+        Example:
+            >>> scope = VISASource()
+            >>> scope.configure(channels=[1, 2])
+            >>> trace = scope.read(channel=1)
+        """
+        if self._closed:
+            raise ValueError("Cannot read from closed source")
+
+        self._ensure_connection()
+
+        import numpy as np
+
+        from oscura.core.types import CalibrationInfo, TraceMetadata, WaveformTrace
+
+        if channel is None:
+            channel = self.channels[0]
+
+        acquisition_start = datetime.now()
+
+        try:
+            # Single acquisition
+            self.instrument.write(":SINGle")  # type: ignore[union-attr]
+
+            # Wait for acquisition to complete
+            import time
+
+            time.sleep(0.1)
+
+            # Set data source
+            self.instrument.write(f":DATa:SOURce CHANnel{channel}")  # type: ignore[union-attr]
+
+            # Get waveform preamble (metadata)
+            preamble = self.instrument.query(":WAVeform:PREamble?")  # type: ignore[union-attr]
+            preamble_parts = preamble.split(",")
+
+            # Parse preamble (format varies by manufacturer)
+            try:
+                x_increment = float(preamble_parts[4])  # Time between samples
+                sample_rate = 1.0 / x_increment
+            except (IndexError, ValueError):
+                sample_rate = 1e9  # Default 1 GSa/s
+
+            # Get waveform data
+            self.instrument.write(":WAVeform:FORMat WORD")  # type: ignore[union-attr]
+            raw_data = self.instrument.query_binary_values(  # type: ignore[union-attr]
+                ":WAVeform:DATA?", datatype="h", is_big_endian=True
+            )
+
+            # Convert to voltage
+            data = np.array(raw_data, dtype=np.float64)
+
+            # Get instrument identity for calibration info
+            try:
+                idn = self.instrument.query("*IDN?").strip()  # type: ignore[union-attr]
+            except Exception:
+                idn = "Unknown Instrument"
+
+            calibration_info = CalibrationInfo(
+                instrument=idn,
+                coupling="DC",  # Default
+                vertical_resolution=8,  # Typical for oscilloscopes
+            )
+
+            metadata = TraceMetadata(
+                sample_rate=sample_rate,
+                vertical_scale=self.vertical_scale,
+                acquisition_time=acquisition_start,
+                source_file=f"visa://{self.resource}",
+                channel_name=f"CH{channel}",
+                calibration_info=calibration_info,
+            )
+
+            return WaveformTrace(data=data, metadata=metadata)
+
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to acquire waveform from channel {channel}. Error: {e}"
+            ) from e
+
+    def stream(self, duration: float = 60.0, interval: float = 1.0) -> Iterator[Trace]:
+        """Stream waveforms at regular intervals.
+
+        Args:
+            duration: Total acquisition duration in seconds (default: 60.0).
+            interval: Time between acquisitions in seconds (default: 1.0).
+
+        Yields:
+            WaveformTrace for each acquisition.
+
+        Raises:
+            ValueError: If source is closed.
+
+        Example:
+            >>> scope = VISASource()
+            >>> scope.configure(channels=[1])
+            >>> for trace in scope.stream(duration=60, interval=1):
+            ...     analyze(trace)
+
+        Note:
+            Acquires repeated single-shot waveforms, not continuous streaming.
+        """
+        if self._closed:
+            raise ValueError("Cannot stream from closed source")
+
+        import time
+
+        start_time = time.time()
+
+        while time.time() - start_time < duration:
+            # Acquire waveform
+            trace = self.read()
+            yield trace
+
+            # Wait for next acquisition
+            time.sleep(interval)
+
+    def close(self) -> None:
+        """Close connection to VISA instrument.
+
+        Example:
+            >>> scope = VISASource()
+            >>> scope.configure(channels=[1])
+            >>> trace = scope.read()
+            >>> scope.close()
+        """
+        if self.instrument is not None:
+            self.instrument.close()
+            self.instrument = None
+        if self.rm is not None:
+            self.rm.close()
+            self.rm = None
+        self._closed = True
+
+    def __enter__(self) -> VISASource:
+        """Context manager entry.
+
+        Returns:
+            Self for use in 'with' statement.
+
+        Example:
+            >>> with VISASource() as scope:
+            ...     scope.configure(channels=[1])
+            ...     trace = scope.read()
+        """
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit.
+
+        Automatically calls close() when exiting 'with' block.
+        """
+        self.close()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"VISASource(resource={self.resource!r})"
+
+
+__all__ = ["VISASource"]

oscura/analyzers/__init__.py

@@ -9,6 +9,7 @@ Provides signal analysis functionality including:
 - Jitter analysis (RJ, DJ, PJ, DDJ, bathtub curves)
 - Eye diagram analysis (height, width, Q-factor)
 - Signal integrity (S-parameters, equalization)
+- Side-channel analysis (DPA, CPA, timing attacks)
 """
 
 # Import measurements module as namespace for DSL compatibility
@@ -18,6 +19,7 @@ from oscura.analyzers import (
     jitter,
     measurements,
     protocols,
+    side_channel,
     signal_integrity,
     statistics,
     validation,
@@ -30,6 +32,7 @@ __all__ = [
     "jitter",
     "measurements",
     "protocols",
+    "side_channel",
     "signal_integrity",
     "statistics",
     "validation",