setVCD 0.2.0__py3-none-any.whl

setVCD/__init__.py

@@ -0,0 +1,51 @@
+"""SetVCD - Convert VCD signals to sets of time points."""
+
+from .exceptions import (
+    ClockSignalError,
+    EmptyVCDError,
+    InvalidInputError,
+    InvalidSignalConditionError,
+    InvalidTimeRangeError,
+    SignalNotFoundError,
+    VCDFileNotFoundError,
+    VCDParseError,
+    VCDSetError,
+)
+from .setVCD import SetVCD
+from .types import (
+    FP,
+    Raw,
+    SignalCondition,
+    String,
+    Time,
+    TimeValue,
+    Value,
+    ValueType,
+    VCDInput,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "SetVCD",
+    # Exceptions
+    "VCDSetError",
+    "VCDFileNotFoundError",
+    "VCDParseError",
+    "ClockSignalError",
+    "SignalNotFoundError",
+    "EmptyVCDError",
+    "InvalidInputError",
+    "InvalidSignalConditionError",
+    "InvalidTimeRangeError",
+    # Types
+    "Time",
+    "Value",
+    "TimeValue",
+    "SignalCondition",
+    "VCDInput",
+    # ValueTypes
+    "ValueType",
+    "Raw",
+    "String",
+    "FP",
+]

setVCD/exceptions.py

@@ -0,0 +1,101 @@
+"""Exception classes for VCD2Set package."""
+
+
+class VCDSetError(Exception):
+    """Base exception for all VCD2Set errors.
+
+    All exceptions raised by VCD2Set inherit from this class,
+    making it easy to catch all VCD2Set-specific errors.
+    """
+
+    pass
+
+
+class VCDFileNotFoundError(VCDSetError):
+    """Raised when a VCD file cannot be found.
+
+    This occurs when a filename is passed to VCDSet but the file
+    doesn't exist at the specified path.
+    """
+
+    pass
+
+
+class VCDParseError(VCDSetError):
+    """Raised when a VCD file cannot be parsed.
+
+    This can occur due to:
+    - Malformed VCD file
+    - Unsupported VCD format
+    - vcdvcd library errors during parsing
+    - Signal access errors
+    """
+
+    pass
+
+
+class ClockSignalError(VCDSetError):
+    """Raised when clock signal is not found or ambiguous.
+
+    This occurs when:
+    - Specified clock signal doesn't exist in VCD
+    - Clock signal name is misspelled
+    """
+
+    pass
+
+
+class SignalNotFoundError(VCDSetError):
+    """Raised when requested signal is not in VCD.
+
+    This occurs in the get() method when signal_name doesn't
+    match any signal in the VCD file.
+    """
+
+    pass
+
+
+class EmptyVCDError(VCDSetError):
+    """Raised when VCD file has no signals or no time data.
+
+    This can occur when:
+    - VCD file is empty or has no signals
+    - Clock signal has no time/value pairs
+    - VCD has signals but no actual data
+    """
+
+    pass
+
+
+class InvalidInputError(VCDSetError):
+    """Raised when input type is invalid.
+
+    This occurs when the vcd parameter is neither:
+    - A string filename
+    - A Path object
+    - A vcdvcd.VCDVCD object
+    """
+
+    pass
+
+
+class InvalidSignalConditionError(VCDSetError):
+    """Raised when signal_condition is not callable or raises exception.
+
+    This occurs when:
+    - signal_condition is not a callable object
+    - signal_condition raises an exception during evaluation
+    """
+
+    pass
+
+
+class InvalidTimeRangeError(VCDSetError):
+    """Raised when time range is invalid.
+
+    This occurs when:
+    - Clock signal has negative timestamps
+    - Time iteration encounters invalid bounds
+    """
+
+    pass

setVCD/py.typed

@@ -0,0 +1,2 @@
+# PEP 561 marker file
+# This file indicates that the package supports type hints

setVCD/setVCD.py

@@ -0,0 +1,453 @@
+"""SetVCD - Convert VCD signals to sets of time points based on conditions."""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple, Union
+
+import vcdvcd
+
+from .exceptions import (
+    ClockSignalError,
+    EmptyVCDError,
+    InvalidInputError,
+    InvalidSignalConditionError,
+    SignalNotFoundError,
+    VCDFileNotFoundError,
+    VCDParseError,
+)
+from .types import (
+    FP,
+    AnyValue,
+    FPValue,
+    Raw,
+    RawValue,
+    SignalConditionProtocol,
+    SignalProtocol,
+    String,
+    StringValue,
+    Time,
+    ValueType,
+    VCDInput,
+    VCDVCDProtocol,
+)
+
+
+def _convert_to_int(value: str) -> Optional[int]:
+    """Convert vcdvcd binary string to integer (Raw conversion).
+
+    Args:
+        value: Binary string from vcdvcd (e.g., "1010", "xxxx", "z")
+
+    Returns:
+        Integer value for valid binary strings, None for x/z or malformed strings.
+
+    Examples:
+        >>> _convert_to_int("1010")  # Binary to decimal
+        10
+        >>> _convert_to_int("xxxx")  # X/Z values
+        None
+    """
+    # Case-insensitive check for unknown/high-impedance
+    value_lower = value.lower()
+    if "x" in value_lower or "z" in value_lower:
+        return None
+
+    # Binary to decimal conversion
+    try:
+        return int(value, 2)
+    except ValueError:
+        # Defensive: malformed VCD value
+        return None
+
+
+def _convert_to_string(value: str) -> Optional[str]:
+    """Convert vcdvcd string to string (String conversion - passthrough)."""
+    # Return as-is, only return None for truly invalid input
+    if value is None or value == "":
+        return None
+    return value
+
+
+def _convert_to_fp(value: str, frac: int, signed: bool) -> Optional[float]:
+    """Convert vcdvcd binary string to fixed-point float (FP conversion)."""
+    # Validate frac parameter
+    if frac < 0:
+        raise ValueError(f"frac must be >= 0, got {frac}")
+
+    # Check for x/z - return NaN per requirements
+    value_lower = value.lower()
+    if "x" in value_lower or "z" in value_lower:
+        return float("nan")
+
+    try:
+        # Convert binary string to integer (unsigned initially)
+        int_value = int(value, 2)
+        total_bits = len(value)
+
+        # Handle signed values (two's complement)
+        if signed and total_bits > 0:
+            sign_bit = 1 << (total_bits - 1)
+            if int_value & sign_bit:
+                # Negative number in two's complement
+                int_value = int_value - (1 << total_bits)
+
+        # Apply fractional scaling: divide by 2^frac
+        float_value = int_value / (1 << frac)
+
+        return float_value
+
+    except ValueError:
+        # Malformed binary string
+        return float("nan")
+
+
+def _convert_value(value_str: str, value_type: ValueType) -> AnyValue:
+    """Dispatch to appropriate converter based on ValueType."""
+    if isinstance(value_type, Raw):
+        return _convert_to_int(value_str)
+    elif isinstance(value_type, String):
+        return _convert_to_string(value_str)
+    elif isinstance(value_type, FP):
+        return _convert_to_fp(value_str, value_type.frac, value_type.signed)
+    else:
+        # Should never happen with proper typing
+        raise ValueError(f"Unknown ValueType: {type(value_type)}")
+
+
+class SetVCD:
+    """
+    Query VCD signals with functionally, and combine them with set theory operators.
+    """
+
+    def __init__(self, vcd: VCDInput, clock: str = "clk") -> None:
+        """
+        Args:
+            vcd: Either a filename (str/Path) to a VCD file, or an already-parsed
+                vcdvcd.VCDVCD object. If a filename is provided, it will be loaded
+                and parsed automatically.
+            clock: Exact name of the clock signal to use as time reference. This
+                signal's last transition determines the iteration range. Must match
+                a signal name exactly (case-sensitive).
+        """
+        # Load VCD object
+        if isinstance(vcd, (str, Path)):
+            vcd_path = Path(vcd)
+            if not vcd_path.exists():
+                raise VCDFileNotFoundError(f"VCD file not found: {vcd_path}")
+
+            try:
+                self.wave: VCDVCDProtocol = vcdvcd.VCDVCD(str(vcd_path))
+            except Exception as e:
+                raise VCDParseError(f"Failed to parse VCD file: {e}") from e
+        elif hasattr(vcd, "get_signals") and hasattr(vcd, "__getitem__"):
+            # Duck typing check for VCDVCD-like object
+            self.wave = vcd
+        else:
+            raise InvalidInputError(
+                f"vcd must be a filename (str/Path) or VCDVCD object, "
+                f"got {type(vcd).__name__}"
+            )
+
+        # Validate VCD has signals
+        try:
+            all_signals = self.wave.get_signals()
+        except Exception as e:
+            raise VCDParseError(f"Failed to retrieve signals from VCD: {e}") from e
+
+        if not all_signals:
+            raise EmptyVCDError("VCD file contains no signals")
+
+        # Initialize signal storage
+        self.sigs: Dict[str, SignalProtocol] = {}
+
+        # Find clock signal - EXACT match only
+        if clock not in all_signals:
+            # Provide helpful error message with similar signals using fuzzy matching
+            # Split the search term into parts and find signals containing those parts
+            search_parts = [p for p in clock.lower().split(".") if p]
+            similar = []
+
+            # Score each signal based on how many parts match
+            scored_signals = []
+            for sig in all_signals:
+                sig_lower = sig.lower()
+                matches = sum(1 for part in search_parts if part in sig_lower)
+                if matches > 0:
+                    scored_signals.append((matches, sig))
+
+            # Sort by number of matches (descending) and take top matches
+            scored_signals.sort(reverse=True, key=lambda x: x[0])
+            similar = [sig for _, sig in scored_signals[:5]]
+
+            error_msg = f"Clock signal '{clock}' not found in VCD."
+            if similar:
+                error_msg += f" Did you mean one of: {similar}?"
+            else:
+                error_msg += f" Available signals: {all_signals[:10]}..."
+            raise ClockSignalError(error_msg)
+
+        try:
+            self.sigs["clock"] = self.wave[clock]
+        except Exception as e:
+            raise VCDParseError(f"Failed to access clock signal '{clock}': {e}") from e
+
+        # Verify clock has data
+        if not self.sigs["clock"].tv:
+            raise EmptyVCDError(f"Clock signal '{clock}' has no time/value data")
+
+        # Get last clock timestamp
+        try:
+            self.last_clock: Time = self.sigs["clock"].tv[-1][0]
+        except (IndexError, TypeError) as e:
+            raise EmptyVCDError(
+                f"Failed to get last timestamp from clock signal: {e}"
+            ) from e
+
+    def search(self, search_regex: str = "") -> List[str]:
+        """Search for signals matching a regex pattern.
+
+        Args:
+            search_regex: Regular expression pattern to match signal names.
+                Empty string returns all signals.
+
+        Returns:
+            List of signal names matching the pattern.
+
+        Example:
+            >>> vs = SetVCD("sim.vcd", clock="TOP.clk")
+            >>> output_signals = vs.search("output")
+            >>> accelerator_signals = vs.search("Accelerator.*valid")
+        """
+        signals = self.wave.get_signals()
+        searched = [s for s in signals if re.search(search_regex, s)]
+        return searched
+
+    def get(
+        self,
+        signal_name: str,
+        signal_condition: Union[
+            SignalConditionProtocol[int],
+            SignalConditionProtocol[str],
+            SignalConditionProtocol[float],
+        ],
+        value_type: Optional[ValueType] = None,
+    ) -> Set[Time]:
+        """Filter time points based on signal condition.
+
+        Args:
+            signal_name: Exact name of signal (case-sensitive). Must exist in VCD file.
+            signal_condition: Function (sm1, s, sp1) -> bool that evaluates signal values.
+                The value types passed depend on value_type parameter:
+                - Raw(): receives Optional[int] values
+                - String(): receives Optional[str] values
+                - FP(): receives Optional[float] values
+            value_type: Value conversion type (default: Raw() for backward compatibility).
+                - Raw(): Binary to int, x/z become None
+                - String(): Keep raw strings including x/z as literals
+                - FP(frac, signed): Fixed-point to float, x/z become NaN
+
+        Returns:
+            Set of timesteps where signal_condition returns True.
+
+        Examples:
+            >>> # Integer comparison (default Raw)
+            >>> rising = vs.get("clk", lambda sm1, s, sp1: sm1 == 0 and s == 1)
+            >>>
+            >>> # String matching to detect x/z
+            >>> has_x = vs.get("data", lambda sm1, s, sp1: s is not None and 'x' in s,
+            ...                value_type=String())
+            >>>
+            >>> # Fixed-point comparison
+            >>> above_threshold = vs.get("temp",
+            ...                          lambda sm1, s, sp1: s is not None and s > 25.5,
+            ...                          value_type=FP(frac=8, signed=True))
+        """
+        # Default to Raw() if not specified
+        if value_type is None:
+            value_type = Raw()
+
+        # Validate signal exists
+        try:
+            all_signals = self.wave.get_signals()
+        except Exception as e:
+            raise VCDParseError(f"Failed to retrieve signals: {e}") from e
+
+        if signal_name not in all_signals:
+            # Provide helpful error with similar signals using fuzzy matching
+            # Split the search term into parts and find signals containing those parts
+            search_parts = [p for p in signal_name.lower().split(".") if p]
+            similar = []
+
+            # Score each signal based on how many parts match
+            scored_signals = []
+            for sig in all_signals:
+                sig_lower = sig.lower()
+                matches = sum(1 for part in search_parts if part in sig_lower)
+                if matches > 0:
+                    scored_signals.append((matches, sig))
+
+            # Sort by number of matches (descending) and take top matches
+            scored_signals.sort(reverse=True, key=lambda x: x[0])
+            similar = [sig for _, sig in scored_signals[:5]]
+
+            error_msg = f"Signal '{signal_name}' not found in VCD."
+            if similar:
+                error_msg += f" Did you mean one of: {similar}?"
+            else:
+                error_msg += f" Available signals: {all_signals[:10]}..."
+            raise SignalNotFoundError(error_msg)
+
+        # Validate signal_condition is callable
+        if not callable(signal_condition):
+            raise InvalidSignalConditionError(
+                f"signal_condition must be callable, got {type(signal_condition).__name__}"
+            )
+
+        # Get signal object
+        try:
+            signal_obj = self.wave[signal_name]
+        except Exception as e:
+            raise VCDParseError(f"Failed to access signal '{signal_name}': {e}") from e
+
+        # Iterate through ALL time steps (not just deltas)
+        out: Set[Time] = set()
+
+        for time in range(0, self.last_clock + 1):
+            try:
+                # Get raw string values from vcdvcd
+                sm1_str: Optional[str] = signal_obj[time - 1] if time > 0 else None
+                s_str: str = signal_obj[time]
+                sp1_str: Optional[str] = (
+                    signal_obj[time + 1] if time < self.last_clock else None
+                )
+
+                # Convert values using specified ValueType (None for boundaries)
+                sm1: AnyValue = (
+                    _convert_value(sm1_str, value_type) if sm1_str is not None else None
+                )
+                s: AnyValue = _convert_value(s_str, value_type)
+                sp1: AnyValue = (
+                    _convert_value(sp1_str, value_type) if sp1_str is not None else None
+                )
+
+                # Evaluate user's condition
+                try:
+                    # Tell pyright to ignore this because we have dependent types.
+                    check = signal_condition(sm1, s, sp1)  # type: ignore[arg-type]
+                except Exception as e:
+                    raise InvalidSignalConditionError(
+                        f"signal_condition raised exception at time {time}: {e}. "
+                        f"Note: signal values can be None (for x/z values or boundaries)."
+                    ) from e
+
+                # Add time to result set if condition is True
+                if check:
+                    out.add(time)
+
+            except InvalidSignalConditionError:
+                # Re-raise our own exceptions
+                raise
+            except Exception as e:
+                # Wrap any other errors
+                raise VCDParseError(
+                    f"Failed to access signal '{signal_name}' at time {time}: {e}"
+                ) from e
+
+        return out
+
+    def get_values(
+        self,
+        signal_name: str,
+        timesteps: Set[Time],
+        value_type: Optional[ValueType] = None,
+    ) -> Union[
+        List[Tuple[Time, RawValue]],
+        List[Tuple[Time, StringValue]],
+        List[Tuple[Time, FPValue]],
+    ]:
+        """Get signal values at specific timesteps.
+
+        This method takes a set of timesteps (typically from get()) and returns
+        the signal values at those times as a sorted list of (time, value) tuples.
+
+        Args:
+            signal_name: Exact name of the signal to query (case-sensitive).
+                Must exist in the VCD file.
+            timesteps: Set of integer timesteps to query. Can be empty.
+            value_type: Value conversion type (default: Raw() for backward compatibility).
+                - Raw(): Binary to int, x/z become None → List[Tuple[Time, Optional[int]]]
+                - String(): Keep raw strings including x/z → List[Tuple[Time, Optional[str]]]
+                - FP(frac, signed): Fixed-point to float, x/z → NaN → List[Tuple[Time, Optional[float]]]
+
+        Returns:
+            Sorted list of (time, value) tuples. Value type depends on value_type parameter.
+
+        Examples:
+            >>> handshakes = valid_times & ready_times
+            >>>
+            >>> # Get as integers (default)
+            >>> int_values = vs.get_values("counter", handshakes)
+            >>>
+            >>> # Get as strings to see x/z
+            >>> str_values = vs.get_values("data_bus", handshakes, String())
+            >>>
+            >>> # Get as fixed-point floats
+            >>> fp_values = vs.get_values("voltage", handshakes, FP(frac=12, signed=False))
+        """
+        # Default to Raw() if not specified
+        if value_type is None:
+            value_type = Raw()
+
+        # Validate signal exists
+        try:
+            all_signals = self.wave.get_signals()
+        except Exception as e:
+            raise VCDParseError(f"Failed to retrieve signals: {e}") from e
+
+        if signal_name not in all_signals:
+            # Provide helpful error with similar signals using fuzzy matching
+            search_parts = [p for p in signal_name.lower().split(".") if p]
+            similar = []
+
+            # Score each signal based on how many parts match
+            scored_signals = []
+            for sig in all_signals:
+                sig_lower = sig.lower()
+                matches = sum(1 for part in search_parts if part in sig_lower)
+                if matches > 0:
+                    scored_signals.append((matches, sig))
+
+            # Sort by number of matches (descending) and take top matches
+            scored_signals.sort(reverse=True, key=lambda x: x[0])
+            similar = [sig for _, sig in scored_signals[:5]]
+
+            error_msg = f"Signal '{signal_name}' not found in VCD."
+            if similar:
+                error_msg += f" Did you mean one of: {similar}?"
+            else:
+                error_msg += f" Available signals: {all_signals[:10]}..."
+            raise SignalNotFoundError(error_msg)
+
+        # Get signal object
+        try:
+            signal_obj = self.wave[signal_name]
+        except Exception as e:
+            raise VCDParseError(f"Failed to access signal '{signal_name}': {e}") from e
+
+        # Get values at each timestep and sort by time
+        result: List[Tuple[Time, AnyValue]] = []
+        for time in timesteps:
+            try:
+                value_str: str = signal_obj[time]
+                value_converted: AnyValue = _convert_value(value_str, value_type)
+                result.append((time, value_converted))
+            except Exception as e:
+                raise VCDParseError(
+                    f"Failed to access signal '{signal_name}' at time {time}: {e}"
+                ) from e
+
+        # Sort by time
+        result.sort(key=lambda x: x[0])
+
+        # Tell pyright to ignore this because we have dependent types.
+        return result  # type: ignore[return-value]

setVCD/types.py

@@ -0,0 +1,185 @@
+"""Type definitions and protocols for setVCD package."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, List, Optional, Protocol, Tuple, TypeVar, Union
+
+# Type aliases for clarity and documentation
+Time = int
+"""Integer timestamp in VCD time units."""
+
+Value = Optional[int]
+"""Signal value as integer (binary conversion) or None (for x/z/boundaries)."""
+
+TimeValue = Tuple[Time, Value]
+"""Tuple of (time, value) representing a signal transition."""
+
+
+class SignalProtocol(Protocol):
+    """Protocol describing the interface of a vcdvcd Signal object.
+
+    This protocol documents the expected interface without requiring
+    an explicit dependency on vcdvcd for type checking.
+    """
+
+    tv: List[TimeValue]
+    """List of (time, value) tuples representing signal transitions."""
+
+    def __getitem__(self, time: Time) -> str:
+        """Random access to get signal value at specific time.
+
+        Returns RAW string value from vcdvcd - will be converted by SetVCD layer.
+        Uses binary search to interpolate value at any time point,
+        even between transitions.
+        """
+        ...
+
+
+class VCDVCDProtocol(Protocol):
+    """Protocol describing the interface of a vcdvcd.VCDVCD object.
+
+    This protocol documents the expected interface without requiring
+    an explicit dependency on vcdvcd for type checking.
+    """
+
+    def get_signals(self) -> List[str]:
+        """Returns list of all signal names in the VCD file."""
+        ...
+
+    def __getitem__(self, signal_name: str) -> SignalProtocol:
+        """Returns Signal object for the given signal name.
+
+        Args:
+            signal_name: Exact signal name (case-sensitive).
+
+        Returns:
+            Signal object with tv attribute and random access.
+        """
+        ...
+
+
+SignalCondition = Callable[[Optional[int], Optional[int], Optional[int]], bool]
+"""Type for signal condition callbacks.
+
+A SignalCondition is a function that takes:
+- sm1: Signal value at time-1 (None if at time 0 or if value is x/z)
+- s: Signal value at current time (None if value is x/z)
+- sp1: Signal value at time+1 (None if at last time or if value is x/z)
+
+Returns:
+- True if this time point should be included in the result set
+- False otherwise
+
+Examples:
+    >>> # Rising edge detector
+    >>> rising_edge: SignalCondition = lambda sm1, s, sp1: sm1 == 0 and s == 1
+    >>>
+    >>> # High level detector
+    >>> is_high: SignalCondition = lambda sm1, s, sp1: s == 1
+    >>>
+    >>> # Change detector
+    >>> changed: SignalCondition = lambda sm1, s, sp1: sm1 is not None and sm1 != s
+"""
+
+VCDInput = Union[str, Path, VCDVCDProtocol]
+"""Type for VCD input to SetVCD.
+
+Can be:
+- str: Filename path to VCD file
+- Path: Pathlib Path object to VCD file
+- VCDVCDProtocol: Already-parsed vcdvcd.VCDVCD object
+"""
+
+
+# ValueType classes for controlling signal value conversion
+@dataclass(frozen=True)
+class Raw:
+    """Represent signal bits as integers (default).
+
+    X and Z values get turned to None.
+
+    Example:
+        >>> # Default behavior - binary to decimal
+        >>> vs.get("data[3:0]", lambda sm1, s, sp1: s == 10, value_type=setvcd.Raw)  # "1010" → 10
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class String:
+    """Represent signal bits as a string.
+
+    X and Z values stay in the string.
+
+    Example:
+        >>> # Detect x/z values in signal
+        >>> vs.get("data", lambda sm1, s, sp1: s is not None and 'x' in s,
+        ...        value_type=String())
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class FP:
+    """Represent signal bits as floating point, by assuming its fixed point.
+
+    X and Z values get turned to None.
+
+    Args:
+        frac: Number of fractional bits (LSBs). Must be >= 0.
+        signed: Whether value has a sign bit (MSB in two's complement).
+            Default is False (unsigned).
+
+    Examples:
+        >>> # Temperature sensor with 8 fractional bits, unsigned
+        >>> vs.get("temp", lambda sm1, s, sp1: s is not None and s > 25.5,
+        ...        value_type=FP(frac=8, signed=False))
+    """
+
+    frac: int
+    signed: bool = False
+
+
+# Union type for all value types
+ValueType = Union[Raw, String, FP]
+"""Union of all ValueType options for signal value conversion."""
+
+# Polymorphic value type aliases
+RawValue = Optional[int]
+"""Signal value as integer (binary conversion) or None (for x/z/boundaries)."""
+
+StringValue = Optional[str]
+"""Signal value as string (preserved from vcdvcd) or None (for boundaries)."""
+
+FPValue = Optional[float]
+"""Signal value as float (fixed-point conversion) or None."""
+
+AnyValue = Union[RawValue, StringValue, FPValue]
+"""Any signal value type (int, str, or float, or None)."""
+
+# Generic type variable for signal conditions
+T = TypeVar("T", int, str, float, contravariant=True)
+"""Type variable for signal value types (contravariant for function parameters)."""
+
+
+class SignalConditionProtocol(Protocol[T]):
+    """Protocol for value-type-aware signal condition functions.
+
+    A generic protocol that accepts signal values of a specific type (int, str, or float)
+    and returns a boolean indicating whether the condition is met.
+    """
+
+    def __call__(self, sm1: Optional[T], s: Optional[T], sp1: Optional[T]) -> bool:
+        """Evaluate condition on three consecutive signal values.
+
+        Args:
+            sm1: Signal value at time-1 (None if at time 0 or x/z for Raw)
+            s: Signal value at current time (None if x/z for Raw)
+            sp1: Signal value at time+1 (None if at last time or x/z for Raw)
+
+        Returns:
+            True if this time point should be included in the result set
+        """
+        ...

setvcd-0.2.0.dist-info/METADATA

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: setVCD
+Version: 0.2.0
+Summary: Convert VCD signals to sets of time points based on conditions
+Author-email: Michail Rontionov <mrontionov@mront.io>
+License: MIT
+Project-URL: Homepage, https://github.com/mrontio/setVCD
+Project-URL: Repository, https://github.com/mrontio/setVCD
+Project-URL: Issues, https://github.com/mrontio/setVCD/issues
+Keywords: vcd,verilog,waveform,signal,testing,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Hardware
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: vcdvcd>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Dynamic: license-file
+
+# SetVCD
+Programmatically inspect hardware VCD signals using a high-level functional interface.
+
+Higher-order programming constructs and set operations are a natural fit for inspecting VCD signals, and this Python library allows you to easily specify, in text, what simulation timesteps matter to functional correctness.
+
+## Motivating Example
+Say you are debugging a streaming interface, you often only care about the values of the data at timesteps meeting the following condition:
+
+$\text{Rising edge} \land \text{Reset is 0} \land \text{ready} \land \text{valid}$
+
+![img/gtkwave.png](img/gtkwave.png "GTKWave screenshot of streaming interface we want to debug.")
+
+You can filter through an individual signal with a filter function of this signature:
+
+$(\text{Bits}, \text{Bits}, \text{Bits}) \rightarrow \text{Bool}$
+
+with the left-hand tuple representing *values* at timestep $t$: $(t-1, t, t+1)$.
+
+We then define our `get` method, which takes the name of the signal (as a String), a function with the above signature, and returns a set of *timesteps*:
+
+$\texttt{get}: (\text{String}, ((\text{Bits}, \text{Bits}, \text{Bits}) \rightarrow \text{Bool})) \rightarrow \text{Set(Timestep)}$
+
+As what is returned is a set, you can then use [set operations](https://en.wikipedia.org/wiki/Set_(mathematics)#Basic_operations) to manipulate them as needed, and finally extract the values from your desired signal using our `get_value` function:
+
+$\texttt{get-value}: (\text{String}, \text{Set(Timestep)}) \rightarrow \text{List((Timestep, Bits))}$
+
+Here's an example of finding the rising edges of the clock signal `TOP.clk` of our test wavefile `wave.vcd`:
+```python
+from setVCD import SetVCD
+
+# Load VCD file
+vcd_path = "./tests/fixtures/wave.vcd"
+sv = SetVCD(vcd_path, clock="TOP.clk")
+
+rising_edges = sv.get("TOP.clk", lambda tm1, t, tp1: tm1 == 0 and t == 1)
+print(rising_edges)
+# {34, 36, 38, 40, 42, 44, ...}
+```
+
+Because `rising_edges` is returned as a set, we can use set operations to combine it with other signals:
+```python
+# Get times when the reset signal is 0
+reset_is_0 = sv.get("TOP.reset", lambda tm1, t, tp1: t == 0)
+# Use set intersection to get valid clock updates.
+clock_update = rising_edges & reset_is_0
+```
+
+Finally, you can search the wavefile with a regex (e.g. "output"), and apply the same operations to it:
+```python
+# Find VCD signals relating to keyword "output"
+sv.search("output")
+
+# Get times when output_valid and output_ready are asserted.
+out_valid = sv.get("TOP.Accelerator.io_output_valid", lambda tm1, t, tp1: t == 1)
+out_ready = sv.get("TOP.Accelerator.io_output_ready", lambda tm1, t, tp1: t == 1)
+
+# Get timesteps of valid outputs
+valid_output_timesteps = rising_edges & reset0 & out_ready & out_valid
+
+# Get the values of the Stream `value` signal (the data) at timesteps when it is valid
+outputs = sv.get_values("TOP.Accelerator.io_output_payload_fragment_value_0[0:0]", valid_output_timesteps)
+print(outputs)
+# [(52, 0), (62, 0), (72, 1), ...]  # Integer values
+```
+
+## Overview
+
+SetVCD is a Python package for analyzing Verilog VCD files and extracting time points where specific signal conditions are met. It provides a simple, type-safe interface for working with simulation waveforms using set-based operations.
+
+## Installation
+The package is available in PyPI:
+```bash
+pip install setVCD
+```
+
+
+## Usage
+### Initialization
+
+You can initialize SetVCD with either a filename or a vcdvcd object:
+
+```python
+import setVCD
+from pathlib import Path
+
+# From string filename
+sv = SetVCD("simulation.vcd", clock="clk")
+
+# From Path object
+sv = SetVCD(Path("simulation.vcd"), clock="clk")
+
+# From vcdvcd object
+import vcdvcd
+vcd = vcdvcd.VCDVCD("simulation.vcd")
+sv = SetVCD(vcd, clock="clk")
+```
+
+The `clock` parameter must be the exact name of the clock signal in your VCD file (case-sensitive). This signal determines the time range for queries.
+
+### Signal Conditions
+
+The `signal_condition` callback receives three arguments representing the signal value at three consecutive time points:
+
+- `sm1`: Signal value at time-1 (None at time 0 or if value is x/z)
+- `s`: Signal value at current time (None if value is x/z)
+- `sp1`: Signal value at time+1 (None at last time or if value is x/z)
+
+Signal values are `Optional[int]`:
+- Integers: Binary values converted to decimal (e.g., "1010" → 10)
+- None: Represents x/z values or boundary conditions (t-1 at time 0, t+1 at last time)
+
+The callback should return `True` to include that time point in the result set.
+
+### Examples
+
+#### Basic Signal Detection
+
+```python
+# Rising edge: 0 -> 1 transition
+rising = sv.get("clk", lambda sm1, s, sp1: sm1 == 0 and s == 1)
+
+# Falling edge: 1 -> 0 transition
+falling = sv.get("clk", lambda sm1, s, sp1: sm1 == 1 and s == 0)
+
+# Any edge: value changed
+edges = sv.get("data", lambda sm1, s, sp1: sm1 is not None and sm1 != s)
+
+# Level high
+high = sv.get("enable", lambda sm1, s, sp1: s == 1)
+
+# Level low
+low = sv.get("reset", lambda sm1, s, sp1: s == 0)
+```
+
+#### Multi-bit Signals
+
+```python
+# Specific pattern on a bus (binary "1010" = decimal 10)
+pattern = sv.get("bus[3:0]", lambda sm1, s, sp1: s == 10)
+
+# Bus is non-zero
+active = sv.get("data[7:0]", lambda sm1, s, sp1: s != 0)
+
+# Bus transition detection
+bus_changed = sv.get("addr[15:0]", lambda sm1, s, sp1: sm1 is not None and sm1 != s)
+```
+
+#### Complex Queries with Set Operations
+
+```python
+# Rising clock edges when enable is high
+clk_rising = sv.get("clk", lambda sm1, s, sp1: sm1 == 0 and s == 1)
+enable_high = sv.get("enable", lambda sm1, s, sp1: s == 1)
+valid_clocks = clk_rising & enable_high
+
+# Data changes while not in reset
+data_changes = sv.get("data", lambda sm1, s, sp1: sm1 is not None and sm1 != s)
+not_reset = sv.get("reset", lambda sm1, s, sp1: s == 0)
+valid_changes = data_changes & not_reset
+
+# Either signal is high
+sig1_high = sv.get("sig1", lambda sm1, s, sp1: s == 1)
+sig2_high = sv.get("sig2", lambda sm1, s, sp1: s == 1)
+either_high = sig1_high | sig2_high
+
+# Exclusive high (one but not both)
+exclusive_high = sig1_high ^ sig2_high
+```
+
+#### Advanced Pattern Detection
+
+```python
+# Detect setup violation: data changes right before clock edge
+data_change = sv.get("data", lambda sm1, s, sp1: sm1 is not None and sm1 != s)
+clk_about_to_rise = sv.get("clk", lambda sm1, s, sp1: s == 0 and sp1 == 1)
+setup_violations = data_change & clk_about_to_rise
+
+# Handshake protocol: valid and ready both high
+valid_high = sv.get("valid", lambda sm1, s, sp1: s == 1)
+ready_high = sv.get("ready", lambda sm1, s, sp1: s == 1)
+handshake_times = valid_high & ready_high
+
+# State machine transitions (binary "00" = 0, "01" = 1)
+state_a = sv.get("state[1:0]", lambda sm1, s, sp1: s == 0)
+state_b = sv.get("state[1:0]", lambda sm1, s, sp1: s == 1)
+# Times when transitioning from state A to state B
+transition = sv.get("state[1:0]", lambda sm1, s, sp1: sm1 == 0 and s == 1)
+```
+
+## Value Types
+
+SetVCD supports three ValueType options to control how signal values are converted before being passed to your condition lambdas:
+
+### Raw() - Integer Conversion (Default)
+
+Converts binary strings to decimal integers. X/Z values become `None`. This is the default behavior.
+
+```python
+from setVCD import SetVCD, Raw
+
+sv = SetVCD("simulation.vcd", clock="clk")
+
+# Default behavior (Raw is implicit)
+rising = sv.get("data[7:0]", lambda sm1, s, sp1: sm1 is not None and sm1 < s)
+
+# Explicit Raw (same as above)
+rising = sv.get("data[7:0]", lambda sm1, s, sp1: sm1 is not None and sm1 < s, value_type=Raw())
+
+# Multi-bit signals converted to decimal
+# Binary "00001010" → integer 10
+high_values = sv.get("bus[7:0]", lambda sm1, s, sp1: s is not None and s > 128)
+```
+
+### String() - Preserve Raw Strings
+
+Keeps vcdvcd's raw string representation, including X/Z values as literal strings. Useful for detecting unknown states.
+
+```python
+from setVCD import SetVCD, String
+
+sv = SetVCD("simulation.vcd", clock="clk")
+
+# Detect X/Z values in data bus
+has_x = sv.get("data[7:0]",
+               lambda sm1, s, sp1: s is not None and 'x' in s.lower(),
+               value_type=String())
+
+# String pattern matching
+all_ones = sv.get("bus[3:0]",
+                  lambda sm1, s, sp1: s == "1111",
+                  value_type=String())
+
+# Get string values
+values = sv.get_values("data", timesteps, value_type=String())
+# Returns: [(50, "1010"), (60, "1111"), (70, "xxxx"), ...]
+```
+
+**X/Z Handling:** X and Z values are preserved as strings (`"x"`, `"z"`, `"xxxx"`, etc.)
+
+### FP() - Fixed-Point to Float
+
+Converts binary strings to floating-point by interpreting them as fixed-point numbers with configurable fractional bits and optional sign bit.
+
+```python
+from setVCD import SetVCD, FP
+
+sv = SetVCD("simulation.vcd", clock="clk")
+
+# Temperature sensor with 8 fractional bits (Q8.8 format)
+# Binary "0001100100000000" → 25.0 degrees
+above_threshold = sv.get("temp_sensor[15:0]",
+                        lambda sm1, s, sp1: s is not None and s > 25.5,
+                        value_type=FP(frac=8, signed=False))
+
+# Signed fixed-point (Q3.4 format - 1 sign bit, 3 integer bits, 4 fractional bits)
+# Binary "11111110" → -0.125 (two's complement)
+negative_values = sv.get("signed_value[7:0]",
+                        lambda sm1, s, sp1: s is not None and s < 0,
+                        value_type=FP(frac=4, signed=True))
+
+# Get fixed-point values
+voltages = sv.get_values("adc_reading[11:0]", timesteps,
+                        value_type=FP(frac=12, signed=False))
+# Returns: [(50, 1.2), (60, 2.5), (70, 3.8), ...]
+```
+
+**X/Z Handling:** X and Z values become `float('nan')`. Use `math.isnan()` to detect them:
+
+```python
+import math
+
+# Filter out NaN values
+valid_readings = sv.get("sensor",
+                       lambda sm1, s, sp1: s is not None and not math.isnan(s),
+                       value_type=FP(frac=8, signed=False))
+```
+
+**Fixed-Point Formula:**
+- Unsigned: `value = int_value / (2^frac)`
+- Signed: Two's complement, then divide by `2^frac`
+
+**Examples:**
+- `"00001010"` with `frac=4, signed=False` → `10 / 16 = 0.625`
+- `"11111110"` with `frac=4, signed=True` → `-2 / 16 = -0.125`
+- `"00010000"` with `frac=0, signed=False` → `16 / 1 = 16.0` (integer)
+
+### Hardware Use Cases
+
+**Raw (Default):** Most general-purpose verification - state machines, counters, addresses, data comparisons
+
+**String:** Debugging X/Z propagation, detecting uninitialized signals, bit-pattern analysis
+
+**FP:** Analog interfaces (ADC/DAC), sensor data, fixed-point DSP verification, power/temperature monitors
+
+## Future Enhancements
+
+Planned for future versions:
+
+- Higher-order operations for signal conditions
+- Performance optimization for large VCD files
+- Streaming interface for very large files
+- MCP (Model Context Protocol) integration

setvcd-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+setVCD/__init__.py,sha256=9XD5kj1dA6Ow_oI0TiEO3T9CKC4j3TuXRs25ZpOLA7E,923
+setVCD/exceptions.py,sha256=0hXqETlYsmZ4sx8X2wJPIYOXA7OI82Nozq6wcgpae2Y,2149
+setVCD/py.typed,sha256=uPBAYYlQuNeFaWWlnXX8ALU2iHi41MrB_u1ZSa3U4lA,81
+setVCD/setVCD.py,sha256=yIRaYauPjXln5n6GuOHBcUgPbr-xbcj37CJfNLJQBpI,17139
+setVCD/types.py,sha256=OZLJszYveOr6pxU36O7qhub_GrJLcefkfZUXiwsL3IM,5644
+setvcd-0.2.0.dist-info/licenses/LICENSE,sha256=rHs-K10ejk3J6IkzDG_iJseZllEVzrR48gEwyqehK_g,1077
+setvcd-0.2.0.dist-info/METADATA,sha256=8WOqJrH2QIhh1puZWnMooa4iGy0v0tiQMsw_b47cdqw,12142
+setvcd-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+setvcd-0.2.0.dist-info/top_level.txt,sha256=CRByAnG-0SIIj8FXsocVOHmwoInY5FQFuRHnyCqS6mo,7
+setvcd-0.2.0.dist-info/RECORD,,

setvcd-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

setvcd-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 VCD2Set Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

setvcd-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+setVCD