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

oscura/exporters/spice_export.py

@@ -1,210 +0,0 @@
-"""SPICE PWL export functionality for Oscura.
-
-This module provides export to SPICE Piece-Wise Linear (PWL) format for
-use in circuit simulation tools like LTspice, ngspice, Cadence, etc.
-
-
-Example:
-    >>> from oscura.exporters.spice_export import export_pwl
-    >>> export_pwl(trace, "stimulus.pwl")
-    >>> # Use in SPICE: V1 in 0 PWL file=stimulus.pwl
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-import numpy as np
-
-from oscura.core.types import DigitalTrace, WaveformTrace
-
-if TYPE_CHECKING:
-    from numpy.typing import NDArray
-
-
-def export_pwl(
-    data: WaveformTrace | DigitalTrace | NDArray[Any] | tuple[NDArray[Any], NDArray[Any]],
-    path: str | Path,
-    *,
-    time_scale: float = 1.0,
-    amplitude_scale: float = 1.0,
-    time_offset: float = 0.0,
-    amplitude_offset: float = 0.0,
-    precision: int = 12,
-    comment: str | None = None,
-    downsample: int = 1,
-    format_style: str = "ltspice",
-) -> None:
-    """Export data to SPICE PWL (Piece-Wise Linear) format.
-
-    Creates a PWL file that can be used as a stimulus source in SPICE
-    circuit simulators. The format consists of time-value pairs.
-
-    Args:
-        data: Data to export. Can be:
-            - WaveformTrace or DigitalTrace
-            - NumPy array (uses trace.time_vector or generates index-based time)
-            - Tuple of (time_array, value_array)
-        path: Output file path.
-        time_scale: Scaling factor for time values (e.g., 1e-9 for ns).
-        amplitude_scale: Scaling factor for amplitude values.
-        time_offset: Offset to add to all time values.
-        amplitude_offset: Offset to add to all amplitude values.
-        precision: Decimal precision for output values.
-        comment: Optional comment to include at top of file.
-        downsample: Downsample factor to reduce file size (1 = no downsampling).
-        format_style: Output format style:
-            - "ltspice": LTspice compatible (time value pairs)
-            - "ngspice": ngspice compatible (same as ltspice)
-            - "hspice": HSPICE compatible (with header)
-
-    Raises:
-        TypeError: If data type is not supported.
-
-    Example:
-        >>> # Export as stimulus for simulation
-        >>> export_pwl(trace, "input.pwl")
-        >>> # In LTspice: V1 in 0 PWL file=input.pwl
-
-        >>> # Scale time to nanoseconds for display
-        >>> export_pwl(trace, "input.pwl", time_scale=1e9)
-
-    References:
-        EXP-005
-    """
-    path = Path(path)
-
-    # Extract time and value arrays
-    if isinstance(data, WaveformTrace | DigitalTrace):
-        time = data.time_vector
-        values = data.data
-    elif isinstance(data, tuple) and len(data) == 2:
-        time, values = data
-    elif isinstance(data, np.ndarray):
-        # Generate time based on array index (assume 1 unit per sample)
-        time = np.arange(len(data), dtype=np.float64)
-        values = data
-    else:
-        raise TypeError(f"Unsupported data type: {type(data)}")
-
-    # Apply downsampling
-    if downsample > 1:
-        time = time[::downsample]
-        values = values[::downsample]
-
-    # Apply scaling and offset
-    time = time * time_scale + time_offset
-    values = values * amplitude_scale + amplitude_offset
-
-    # Write to file
-    with open(path, "w") as f:
-        # Write comment/header
-        if format_style == "hspice":
-            f.write("* HSPICE PWL Data\n")
-            if comment:
-                f.write(f"* {comment}\n")
-            f.write(f"* Points: {len(time)}\n")
-            f.write("*\n")
-        elif comment:
-            f.write(f"; {comment}\n")
-
-        # Write time-value pairs
-        fmt = f"{{:.{precision}g}} {{:.{precision}g}}\n"
-        f.writelines(fmt.format(t, v) for t, v in zip(time, values, strict=False))
-
-
-def export_pwl_multi(
-    traces: dict[str, WaveformTrace | DigitalTrace | NDArray[Any]],
-    path: str | Path,
-    *,
-    time_scale: float = 1.0,
-    amplitude_scale: float = 1.0,
-    precision: int = 12,
-    downsample: int = 1,
-) -> None:
-    """Export multiple traces to individual PWL files.
-
-    Creates separate PWL files for each trace in the dictionary,
-    with filenames based on the dictionary keys.
-
-    Args:
-        traces: Dictionary mapping signal names to trace data.
-        path: Output directory path.
-        time_scale: Scaling factor for time values.
-        amplitude_scale: Scaling factor for amplitude values.
-        precision: Decimal precision for output values.
-        downsample: Downsample factor to reduce file size.
-
-    Example:
-        >>> traces = {
-        ...     "clk": clock_trace,
-        ...     "data": data_trace,
-        ...     "reset": reset_trace,
-        ... }
-        >>> export_pwl_multi(traces, "stimuli/")
-        >>> # Creates: stimuli/clk.pwl, stimuli/data.pwl, stimuli/reset.pwl
-
-    References:
-        EXP-005
-    """
-    path = Path(path)
-    path.mkdir(parents=True, exist_ok=True)
-
-    for name, data in traces.items():
-        # Sanitize filename
-        safe_name = "".join(c if c.isalnum() or c in "_-" else "_" for c in name)
-        file_path = path / f"{safe_name}.pwl"
-
-        export_pwl(
-            data,
-            file_path,
-            time_scale=time_scale,
-            amplitude_scale=amplitude_scale,
-            precision=precision,
-            downsample=downsample,
-            comment=f"Signal: {name}",
-        )
-
-
-def generate_spice_source(
-    pwl_path: str | Path,
-    node_positive: str = "in",
-    node_negative: str = "0",
-    source_name: str = "V1",
-    source_type: str = "voltage",
-) -> str:
-    """Generate SPICE source definition for a PWL file.
-
-    Args:
-        pwl_path: Path to PWL file.
-        node_positive: Positive node name.
-        node_negative: Negative node name (usually "0" for ground).
-        source_name: Source instance name.
-        source_type: Source type ("voltage" or "current").
-
-    Returns:
-        SPICE source definition string.
-
-    Example:
-        >>> line = generate_spice_source("input.pwl", "in", "0", "V1")
-        >>> print(line)
-        V1 in 0 PWL file=input.pwl
-
-    References:
-        EXP-005
-    """
-    prefix = "V" if source_type == "voltage" else "I"
-
-    # Ensure source name starts with correct prefix
-    if not source_name.upper().startswith(prefix):
-        source_name = f"{prefix}{source_name}"
-
-    return f"{source_name} {node_positive} {node_negative} PWL file={pwl_path}"
-
-
-__all__ = [
-    "export_pwl",
-    "export_pwl_multi",
-    "generate_spice_source",
-]

oscura/search/context.py

@@ -1,149 +0,0 @@
-"""Context extraction around points of interest.
-
-
-This module provides efficient extraction of signal context around
-events, maintaining original time references for debugging workflows.
-"""
-
-from typing import Any
-
-import numpy as np
-from numpy.typing import NDArray
-
-
-def extract_context(
-    trace: NDArray[np.float64],
-    index: int | list[int] | NDArray[np.int_],
-    *,
-    before: int = 100,
-    after: int = 100,
-    sample_rate: float | None = None,
-    include_metadata: bool = True,
-) -> dict[str, Any] | list[dict[str, Any]]:
-    """Extract signal context around a point of interest.
-
-    : Context extraction with time reference preservation.
-    Supports batch extraction for multiple indices and optional protocol data.
-
-    Args:
-        trace: Input signal trace
-        index: Sample index or list of indices to extract context around.
-            Can be int, list of ints, or numpy array.
-        before: Number of samples to include before index (default: 100)
-        after: Number of samples to include after index (default: 100)
-        sample_rate: Optional sample rate in Hz for time calculations
-        include_metadata: Include metadata dict with context info (default: True)
-
-    Returns:
-        If index is scalar: Single context dictionary
-        If index is list/array: List of context dictionaries
-
-        Each context dictionary contains:
-        - data: Extracted sub-trace array
-        - start_index: Starting index in original trace
-        - end_index: Ending index in original trace
-        - center_index: Center index (original query index)
-        - time_reference: Time offset if sample_rate provided
-        - length: Number of samples in context
-
-    Raises:
-        ValueError: If index is out of bounds
-        ValueError: If before or after are negative
-
-    Examples:
-        >>> # Extract context around a glitch
-        >>> trace = np.random.randn(1000)
-        >>> glitch_index = 500
-        >>> context = extract_context(
-        ...     trace,
-        ...     glitch_index,
-        ...     before=50,
-        ...     after=50,
-        ...     sample_rate=1e6
-        ... )
-        >>> print(f"Context length: {len(context['data'])}")
-        >>> print(f"Time reference: {context['time_reference']*1e6:.2f} µs")
-
-        >>> # Batch extraction for multiple events
-        >>> event_indices = [100, 200, 300]
-        >>> contexts = extract_context(
-        ...     trace,
-        ...     event_indices,
-        ...     before=25,
-        ...     after=25
-        ... )
-        >>> print(f"Extracted {len(contexts)} contexts")
-
-    Notes:
-        - Handles edge cases at trace boundaries automatically
-        - Context may be shorter than before+after at boundaries
-        - Time reference is relative to start of extracted context
-        - Original trace is not modified
-
-    References:
-        SRCH-003: Context Extraction
-    """
-    if before < 0 or after < 0:
-        raise ValueError("before and after must be non-negative")
-
-    if trace.size == 0:
-        raise ValueError("Trace cannot be empty")
-
-    # Handle single index vs multiple indices
-    if isinstance(index, int | np.integer):
-        indices = [int(index)]
-        return_single = True
-    else:
-        indices = [int(i) for i in index]
-        return_single = False
-
-    # Validate indices
-    for idx in indices:
-        if idx < 0 or idx >= len(trace):
-            raise ValueError(f"Index {idx} out of bounds for trace of length {len(trace)}")
-
-    # Extract contexts
-    contexts = []
-
-    for idx in indices:
-        # Calculate window bounds with boundary handling
-        start_idx = max(0, idx - before)
-        end_idx = min(len(trace), idx + after + 1)
-
-        # Extract data
-        data = trace[start_idx:end_idx].copy()
-
-        # Build context dictionary
-        context: dict[str, Any] = {
-            "data": data,
-            "start_index": start_idx,
-            "end_index": end_idx,
-            "center_index": idx,
-            "length": len(data),
-        }
-
-        # Add time reference if sample rate provided
-        if sample_rate is not None:
-            time_offset = start_idx / sample_rate
-            context["time_reference"] = time_offset
-            context["sample_rate"] = sample_rate
-
-            # Time array for the context
-            dt = 1.0 / sample_rate
-            context["time_array"] = np.arange(len(data)) * dt + time_offset
-
-        if include_metadata:
-            context["metadata"] = {
-                "samples_before": idx - start_idx,
-                "samples_after": end_idx - idx - 1,
-                "at_start_boundary": start_idx == 0,
-                "at_end_boundary": end_idx == len(trace),
-            }
-
-        contexts.append(context)
-
-    # Return single context or list
-    if return_single:
-        return contexts[0]
-    else:
-        return contexts

oscura/session/__init__.py

@@ -1,34 +0,0 @@
-"""Session management for Oscura analysis sessions.
-
-This module provides session save/restore, trace annotations, and
-operation history tracking.
-
-
-Example:
-    >>> import oscura as osc
-    >>> session = osc.Session()
-    >>> session.load_trace('capture.wfm')
-    >>> session.annotate(time=1.5e-6, text='Glitch here')
-    >>> session.save('debug_session.tks')
-    >>>
-    >>> # Later...
-    >>> session = osc.load_session('debug_session.tks')
-    >>> print(session.annotations)
-"""
-
-from oscura.session.annotations import Annotation, AnnotationLayer, AnnotationType
-from oscura.session.history import HistoryEntry, OperationHistory
-from oscura.session.session import Session, load_session
-
-__all__ = [
-    # Annotations (SESS-002)
-    "Annotation",
-    "AnnotationLayer",
-    "AnnotationType",
-    # History (SESS-003)
-    "HistoryEntry",
-    "OperationHistory",
-    # Session (SESS-001)
-    "Session",
-    "load_session",
-]

oscura/session/annotations.py

@@ -1,289 +0,0 @@
-"""Trace annotation support.
-
-This module provides annotation capabilities for marking points of interest
-in signal traces.
-
-
-Example:
-    >>> layer = AnnotationLayer("Debug Markers")
-    >>> layer.add(Annotation(time=1.5e-6, text="Glitch detected"))
-    >>> layer.add(Annotation(time_range=(2e-6, 3e-6), text="Data packet"))
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from datetime import datetime
-from enum import Enum
-from typing import Any
-
-
-class AnnotationType(Enum):
-    """Types of annotations."""
-
-    POINT = "point"  # Single time point
-    RANGE = "range"  # Time range
-    VERTICAL = "vertical"  # Vertical line
-    HORIZONTAL = "horizontal"  # Horizontal line
-    REGION = "region"  # 2D region (time + amplitude)
-    TEXT = "text"  # Free-floating text
-
-
-@dataclass
-class Annotation:
-    """Single annotation on a trace.
-
-    Attributes:
-        text: Annotation text/label
-        time: Time point (for point annotations)
-        time_range: (start, end) time range
-        amplitude: Amplitude value (for horizontal lines)
-        amplitude_range: (min, max) amplitude range
-        annotation_type: Type of annotation
-        color: Display color (hex or name)
-        style: Line style ('solid', 'dashed', 'dotted')
-        visible: Whether annotation is visible
-        created_at: Creation timestamp
-        metadata: Additional metadata
-    """
-
-    text: str
-    time: float | None = None
-    time_range: tuple[float, float] | None = None
-    amplitude: float | None = None
-    amplitude_range: tuple[float, float] | None = None
-    annotation_type: AnnotationType = AnnotationType.POINT
-    color: str = "#FF6B6B"
-    style: str = "solid"
-    visible: bool = True
-    created_at: datetime = field(default_factory=datetime.now)
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-    def __post_init__(self) -> None:
-        """Infer annotation type from provided parameters."""
-        if self.annotation_type == AnnotationType.POINT:
-            if self.time_range is not None:
-                self.annotation_type = AnnotationType.RANGE
-            elif self.amplitude is not None and self.time is None:
-                self.annotation_type = AnnotationType.HORIZONTAL
-            elif self.amplitude_range is not None and self.time_range is not None:
-                self.annotation_type = AnnotationType.REGION  # type: ignore[unreachable]
-
-    @property
-    def start_time(self) -> float | None:
-        """Get start time for range annotations."""
-        if self.time_range:
-            return self.time_range[0]
-        return self.time
-
-    @property
-    def end_time(self) -> float | None:
-        """Get end time for range annotations."""
-        if self.time_range:
-            return self.time_range[1]
-        return self.time
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "text": self.text,
-            "time": self.time,
-            "time_range": self.time_range,
-            "amplitude": self.amplitude,
-            "amplitude_range": self.amplitude_range,
-            "annotation_type": self.annotation_type.value,
-            "color": self.color,
-            "style": self.style,
-            "visible": self.visible,
-            "created_at": self.created_at.isoformat(),
-            "metadata": self.metadata,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> Annotation:
-        """Create from dictionary."""
-        data = data.copy()
-        data["annotation_type"] = AnnotationType(data.get("annotation_type", "point"))
-        if "created_at" in data and isinstance(data["created_at"], str):
-            data["created_at"] = datetime.fromisoformat(data["created_at"])
-        return cls(**data)
-
-
-@dataclass
-class AnnotationLayer:
-    """Collection of related annotations.
-
-    Attributes:
-        name: Layer name
-        annotations: List of annotations
-        visible: Whether layer is visible
-        locked: Whether layer is locked (read-only)
-        color: Default color for new annotations
-        description: Layer description
-    """
-
-    name: str
-    annotations: list[Annotation] = field(default_factory=list)
-    visible: bool = True
-    locked: bool = False
-    color: str = "#FF6B6B"
-    description: str = ""
-
-    def add(
-        self,
-        annotation: Annotation | None = None,
-        *,
-        text: str = "",
-        time: float | None = None,
-        time_range: tuple[float, float] | None = None,
-        **kwargs: Any,
-    ) -> Annotation:
-        """Add annotation to layer.
-
-        Args:
-            annotation: Pre-built Annotation object.
-            text: Annotation text (if not using pre-built).
-            time: Time point.
-            time_range: Time range.
-            **kwargs: Additional Annotation parameters.
-
-        Returns:
-            Added annotation.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        if annotation is None:
-            annotation = Annotation(
-                text=text,
-                time=time,
-                time_range=time_range,
-                color=kwargs.pop("color", self.color),
-                **kwargs,
-            )
-
-        self.annotations.append(annotation)
-        return annotation
-
-    def remove(self, annotation: Annotation) -> bool:
-        """Remove annotation from layer.
-
-        Args:
-            annotation: Annotation to remove.
-
-        Returns:
-            True if removed, False if not found.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        try:
-            self.annotations.remove(annotation)
-            return True
-        except ValueError:
-            return False
-
-    def find_at_time(
-        self,
-        time: float,
-        tolerance: float = 0.0,
-    ) -> list[Annotation]:
-        """Find annotations at or near a specific time.
-
-        Args:
-            time: Time to search.
-            tolerance: Time tolerance for matching.
-
-        Returns:
-            List of matching annotations.
-        """
-        matches = []
-        for ann in self.annotations:
-            if ann.time is not None:
-                if abs(ann.time - time) <= tolerance:
-                    matches.append(ann)
-            elif ann.time_range is not None and (
-                ann.time_range[0] - tolerance <= time <= ann.time_range[1] + tolerance
-            ):
-                matches.append(ann)
-        return matches
-
-    def find_in_range(
-        self,
-        start_time: float,
-        end_time: float,
-    ) -> list[Annotation]:
-        """Find annotations within a time range.
-
-        Args:
-            start_time: Range start.
-            end_time: Range end.
-
-        Returns:
-            List of annotations within range.
-        """
-        matches = []
-        for ann in self.annotations:
-            ann_start = ann.start_time
-            ann_end = ann.end_time
-
-            if ann_start is not None and (
-                start_time <= ann_start <= end_time
-                or (ann_end is not None and ann_start <= end_time and ann_end >= start_time)
-            ):
-                matches.append(ann)
-
-        return matches
-
-    def clear(self) -> int:
-        """Remove all annotations.
-
-        Returns:
-            Number of annotations removed.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        count = len(self.annotations)
-        self.annotations.clear()
-        return count
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "name": self.name,
-            "annotations": [a.to_dict() for a in self.annotations],
-            "visible": self.visible,
-            "locked": self.locked,
-            "color": self.color,
-            "description": self.description,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> AnnotationLayer:
-        """Create from dictionary."""
-        annotations = [Annotation.from_dict(a) for a in data.get("annotations", [])]
-        return cls(
-            name=data["name"],
-            annotations=annotations,
-            visible=data.get("visible", True),
-            locked=data.get("locked", False),
-            color=data.get("color", "#FF6B6B"),
-            description=data.get("description", ""),
-        )
-
-
-__all__ = [
-    "Annotation",
-    "AnnotationLayer",
-    "AnnotationType",
-]