wavekit 0.1.1__tar.gz → 0.2.0__tar.gz

wavekit-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: wavekit
+Version: 0.2.0
+Summary: a fundamental package for digital circuit waveform analysis
+License-File: LICENSE
+Author: cxzzzz
+Author-email: cxz19961010@outlook.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy (>=2.0.0,<3.0.0)
+Requires-Dist: pytest (>=8.2.2,<9.0.0)
+Requires-Dist: vcdvcd (>=2.3.5,<3.0.0)
+Project-URL: Repository, https://github.com/cxzzzz/wavekit
+Description-Content-Type: text/markdown
+
+# wavekit
+
+[![PyPI version](https://img.shields.io/pypi/v/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
+
+**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+
+## ✨ Features
+
+- **High Performance**: Cython-optimized parsers and Numpy-backed storage deliver exceptional speed and memory efficiency for large waveform files.
+- **Flexible Extraction**: Effortlessly batch-extract signals using glob patterns or regular expressions.
+- **Rich Analysis Tools**: Comprehensive toolkit for bit-precise manipulation, temporal analysis, and signal transformation, streamlining complex analysis tasks with succinct, Numpy-like APIs.
+
+## 📦 Installation
+
+### Using pip (For Users)
+
+You can install the library using pip:
+
+```bash
+pip install wavekit
+```
+
+**Note**: To read FSDB files, ensure the `VERDI_HOME` environment variable is set before installation.
+
+### From Source (For Developers)
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management.
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/cxzzzz/wavekit.git
+   cd wavekit
+   ```
+
+2. Install dependencies:
+   ```bash
+   poetry install
+   ```
+
+## 🚀 Quick Start
+
+### Batch Signal Extraction
+
+Wavekit simplifies extracting multiple signals using brace expansion or regular expressions.
+
+**1. Using Brace Expansion**
+Use brace patterns (e.g., `{state,next}` or `{0..7}`) to load related signals in one go.
+
+```python
+from wavekit import VcdReader
+
+with VcdReader("jtag.vcd") as f:
+    # Load both J_state and J_next signals
+    # Returns: { ('state',): Waveform(...), ('next',): Waveform(...) }
+    waves = f.load_matched_waveforms(
+        "tb.u0.J_{state,next}[3:0]",
+        clock="tb.tck"
+    )
+
+    for (suffix,), wave in waves.items():
+        print(f"Signal J_{suffix}: width={wave.width}")
+```
+
+**2. Using Regular Expressions**
+Prefix the pattern with `@` to enable regex matching. Capture groups `(...)` become the dictionary keys.
+
+```python
+with VcdReader("jtag.vcd") as f:
+    # Use '@' prefix for regex mode
+    # Match signals like J_state[3:0] and J_next[3:0]
+    # Capture the suffix (state/next)
+    regex_pattern = r"tb.u0.@J_([a-z]+)"
+
+    # Returns: { ('state',): Waveform(...), ('next',): Waveform(...) }
+    waves = f.load_matched_waveforms(regex_pattern, clock="tb.tck")
+
+    for (name_part,), wave in waves.items():
+        print(f"Matched: {name_part}")
+```
+
+### Basic: FIFO Occupancy Analysis
+
+Here is a simple example demonstrating how to read a VCD file and calculate the average occupancy level of a FIFO:
+
+```python
+import numpy as np
+from wavekit import VcdReader
+
+with VcdReader("fifo_tb.vcd") as f:
+    clock = "fifo_tb.s_fifo.clk"
+    depth = 8
+
+    # Load signals with clock synchronization
+    w_ptr = f.load_waveform("fifo_tb.s_fifo.w_ptr[2:0]", clock=clock)
+    r_ptr = f.load_waveform("fifo_tb.s_fifo.r_ptr[2:0]", clock=clock)
+
+    # Perform vectorized arithmetic operations directly on waveforms
+    fifo_water_level = (w_ptr + depth - r_ptr) % depth
+
+    # Calculate average occupancy using Numpy
+    average_level = np.mean(fifo_water_level.value)
+    print(f"Average FIFO occupancy: {average_level:.2f}")
+```
+
+### Advanced: Data Validity Filtering
+
+Use the powerful masking capabilities to filter data based on valid signals:
+
+```python
+from wavekit import VcdReader
+
+with VcdReader("bus_tb.vcd") as f:
+    clock = "top.clk"
+
+    # Load data and valid signals
+    data = f.load_waveform("top.bus_data[31:0]", clock=clock)
+    valid = f.load_waveform("top.bus_valid", clock=clock)
+
+    # Filter data where valid is high (1)
+    # The mask() method accepts a boolean waveform or numpy array
+    valid_data = data.mask(valid == 1)
+
+    # Analyze the valid transactions
+    print(f"Total valid transactions: {len(valid_data.value)}")
+    print(f"First valid data: {hex(valid_data.value[0])}")
+```
+
+## 🛠️ Development
+
+This project adheres to strict code quality standards using modern Python tooling:
+
+- **Linting & Formatting**: [Ruff](https://github.com/astral-sh/ruff)
+- **Type Checking**: [Mypy](https://mypy-lang.org/)
+
+Ensure all checks pass before submitting a Pull Request:
+
+```bash
+# Run linting and formatting checks
+poetry run ruff check .
+poetry run ruff format --check .
+
+# Run type checks
+poetry run mypy .
+```
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+

wavekit-0.2.0/README.md

@@ -0,0 +1,151 @@
+# wavekit
+
+[![PyPI version](https://img.shields.io/pypi/v/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
+
+**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+
+## ✨ Features
+
+- **High Performance**: Cython-optimized parsers and Numpy-backed storage deliver exceptional speed and memory efficiency for large waveform files.
+- **Flexible Extraction**: Effortlessly batch-extract signals using glob patterns or regular expressions.
+- **Rich Analysis Tools**: Comprehensive toolkit for bit-precise manipulation, temporal analysis, and signal transformation, streamlining complex analysis tasks with succinct, Numpy-like APIs.
+
+## 📦 Installation
+
+### Using pip (For Users)
+
+You can install the library using pip:
+
+```bash
+pip install wavekit
+```
+
+**Note**: To read FSDB files, ensure the `VERDI_HOME` environment variable is set before installation.
+
+### From Source (For Developers)
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management.
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/cxzzzz/wavekit.git
+   cd wavekit
+   ```
+
+2. Install dependencies:
+   ```bash
+   poetry install
+   ```
+
+## 🚀 Quick Start
+
+### Batch Signal Extraction
+
+Wavekit simplifies extracting multiple signals using brace expansion or regular expressions.
+
+**1. Using Brace Expansion**
+Use brace patterns (e.g., `{state,next}` or `{0..7}`) to load related signals in one go.
+
+```python
+from wavekit import VcdReader
+
+with VcdReader("jtag.vcd") as f:
+    # Load both J_state and J_next signals
+    # Returns: { ('state',): Waveform(...), ('next',): Waveform(...) }
+    waves = f.load_matched_waveforms(
+        "tb.u0.J_{state,next}[3:0]",
+        clock="tb.tck"
+    )
+
+    for (suffix,), wave in waves.items():
+        print(f"Signal J_{suffix}: width={wave.width}")
+```
+
+**2. Using Regular Expressions**
+Prefix the pattern with `@` to enable regex matching. Capture groups `(...)` become the dictionary keys.
+
+```python
+with VcdReader("jtag.vcd") as f:
+    # Use '@' prefix for regex mode
+    # Match signals like J_state[3:0] and J_next[3:0]
+    # Capture the suffix (state/next)
+    regex_pattern = r"tb.u0.@J_([a-z]+)"
+
+    # Returns: { ('state',): Waveform(...), ('next',): Waveform(...) }
+    waves = f.load_matched_waveforms(regex_pattern, clock="tb.tck")
+
+    for (name_part,), wave in waves.items():
+        print(f"Matched: {name_part}")
+```
+
+### Basic: FIFO Occupancy Analysis
+
+Here is a simple example demonstrating how to read a VCD file and calculate the average occupancy level of a FIFO:
+
+```python
+import numpy as np
+from wavekit import VcdReader
+
+with VcdReader("fifo_tb.vcd") as f:
+    clock = "fifo_tb.s_fifo.clk"
+    depth = 8
+
+    # Load signals with clock synchronization
+    w_ptr = f.load_waveform("fifo_tb.s_fifo.w_ptr[2:0]", clock=clock)
+    r_ptr = f.load_waveform("fifo_tb.s_fifo.r_ptr[2:0]", clock=clock)
+
+    # Perform vectorized arithmetic operations directly on waveforms
+    fifo_water_level = (w_ptr + depth - r_ptr) % depth
+
+    # Calculate average occupancy using Numpy
+    average_level = np.mean(fifo_water_level.value)
+    print(f"Average FIFO occupancy: {average_level:.2f}")
+```
+
+### Advanced: Data Validity Filtering
+
+Use the powerful masking capabilities to filter data based on valid signals:
+
+```python
+from wavekit import VcdReader
+
+with VcdReader("bus_tb.vcd") as f:
+    clock = "top.clk"
+
+    # Load data and valid signals
+    data = f.load_waveform("top.bus_data[31:0]", clock=clock)
+    valid = f.load_waveform("top.bus_valid", clock=clock)
+
+    # Filter data where valid is high (1)
+    # The mask() method accepts a boolean waveform or numpy array
+    valid_data = data.mask(valid == 1)
+
+    # Analyze the valid transactions
+    print(f"Total valid transactions: {len(valid_data.value)}")
+    print(f"First valid data: {hex(valid_data.value[0])}")
+```
+
+## 🛠️ Development
+
+This project adheres to strict code quality standards using modern Python tooling:
+
+- **Linting & Formatting**: [Ruff](https://github.com/astral-sh/ruff)
+- **Type Checking**: [Mypy](https://mypy-lang.org/)
+
+Ensure all checks pass before submitting a Pull Request:
+
+```bash
+# Run linting and formatting checks
+poetry run ruff check .
+poetry run ruff format --check .
+
+# Run type checks
+poetry run mypy .
+```
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

wavekit-0.2.0/build.py

@@ -0,0 +1,52 @@
+import os
+
+import numpy as np
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
+extensions = [
+    Extension(
+        'src.wavekit.readers.value_change',
+        sources=['src/wavekit/readers/value_change.pyx'],
+        include_dirs=[np.get_include()],
+        extra_compile_args=['-fpic', '-O3', '-march=native'],
+        extra_link_args=['-O3', '-march=native'],
+        language='c++',
+    )
+]
+
+if VERDI_HOME := os.environ.get('VERDI_HOME'):
+    npi_include_dir = os.path.join(VERDI_HOME, 'share/NPI/inc')
+    npi_library_dir = os.path.join(VERDI_HOME, 'share/NPI/lib/LINUX64')
+
+    extensions.append(
+        Extension(
+            'src.wavekit.readers.fsdb.npi_fsdb_reader',
+            sources=['src/wavekit/readers/fsdb/npi_fsdb_reader.pyx'],
+            include_dirs=[np.get_include(), npi_include_dir],
+            library_dirs=[npi_library_dir],
+            libraries=['NPI', 'rt'],
+            extra_compile_args=['-fpic', '-O3', '-march=native'],
+            extra_link_args=[
+                '-O3',
+                '-march=native',
+                f'-Wl,-rpath,{npi_library_dir}',
+            ],
+            language='c++',
+        )
+    )
+
+setup(
+    ext_modules=cythonize(
+        extensions,
+        compiler_directives={
+            'language_level': 3,
+            'embedsignature': True,
+            'boundscheck': False,
+            'wraparound': False,
+            'cdivision': True,
+            'nonecheck': False,
+        },
+    ),
+    script_args=['build_ext', '--inplace'],
+)

wavekit-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "wavekit"
+version = "0.2.0"
+description = "a fundamental package for digital circuit waveform analysis"
+authors = ["cxzzzz <cxz19961010@outlook.com>"]
+readme = "README.md"
+repository = "https://github.com/cxzzzz/wavekit"
+build = "build.py"
+include = ["src/wavekit/**/*.so"]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+numpy = "^2.0.0"
+vcdvcd = "^2.3.5"
+pytest = "^8.2.2"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.6.2"
+mypy = "^1.11.2"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = ["B017"]
+
+[tool.ruff.format]
+quote-style = "single"
+line-ending = "lf"
+
+[tool.mypy]
+python_version = "3.9"
+files = ["src", "tests"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+check_untyped_defs = false
+ignore_missing_imports = true
+no_implicit_optional = false
+disable_error_code = ["misc"]
+
+[build-system]
+requires = ["poetry-core", "Cython", "setuptools", "wheel", "numpy>=2.0.0"]
+build-backend = "poetry.core.masonry.api"

wavekit-0.2.0/src/wavekit/__init__.py

@@ -0,0 +1,21 @@
+#   -------------------------------------------------------------
+#   Copyright (c) Microsoft Corporation. All rights reserved.
+#   Licensed under the MIT License. See LICENSE in project root for information.
+#   -------------------------------------------------------------
+"""Python Package Template"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version('wavekit')
+except metadata.PackageNotFoundError:
+    __version__ = 'unknown'
+
+from .readers.vcd.reader import VcdReader as VcdReader
+from .scope import Scope as Scope
+from .signal import Signal as Signal
+from .waveform import Waveform as Waveform
+
+__all__ = ['Waveform', 'VcdReader', 'FsdbReader', 'Scope', 'Signal']

wavekit-0.2.0/src/wavekit/readers/base.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+from ..scope import Scope, traverse_scope
+from ..signal import Signal
+from ..waveform import Waveform
+from .pattern_parser import (
+    PatternMap,
+    expand_brace_pattern,
+    split_by_hierarchy,
+)
+from .value_change import value_change_to_value_array
+
+
+class Reader:
+    def __init__(self):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        # exception wont be suppressed
+        return False
+
+    @abstractmethod
+    def load_waveform(
+        self,
+        signal: str,
+        clock: str,
+        xz_value: int = 0,
+        signed: bool = False,
+        sample_on_posedge: bool = False,
+        begin_time: int | None = None,
+        end_time: int | None = None,
+    ) -> Waveform:
+        pass
+
+    @abstractmethod
+    def get_signal_width(self, signal: str) -> int:
+        pass
+
+    @staticmethod
+    def value_change_to_waveform(
+        value_change: np.ndarray,
+        clock_changes: np.ndarray,
+        width: int | None,
+        signed: bool,
+        sample_on_posedge: bool = False,
+        signal: str = '',
+    ) -> Waveform:
+        value, clock, time = value_change_to_value_array(
+            value_change, clock_changes, sample_on_posedge=sample_on_posedge
+        )
+
+        return Waveform(
+            value=value,
+            clock=clock,
+            time=time,
+            signal=Signal(signal, width, signed),
+        )
+
+    @abstractmethod
+    def top_scope_list(self) -> Sequence[Scope]:
+        pass
+
+    def get_matched_signals(
+        self,
+        pattern: str,
+    ) -> dict[tuple[Any, ...], str]:
+        def combine_dict(
+            dict1: dict[tuple[Any, ...], str],
+            dict2: dict[tuple[Any, ...], str],
+        ) -> dict[tuple[Any, ...], str]:
+            common_keys = set(dict1.keys()).intersection(dict2.keys())
+
+            if common_keys:
+                signal1s = [dict1[k] for k in common_keys]
+                signal2s = [dict2[k] for k in common_keys]
+                raise Exception(
+                    'found more than one signal with the same keys: '
+                    f'keys:{list(common_keys)} , signals:{signal1s + signal2s}'
+                )
+
+            return {**dict1, **dict2}
+
+        pattern = pattern.strip()
+        expanded_pattern_list: list[PatternMap] = [
+            expand_brace_pattern(p) for p in split_by_hierarchy(pattern)
+        ]
+
+        matched_signals: dict[tuple[Any, ...], str] = {}
+        for scope in self.top_scope_list():
+            matched_signals = combine_dict(
+                matched_signals,
+                traverse_scope(scope, expanded_pattern_list),
+            )
+        return matched_signals
+
+    def load_matched_waveforms(
+        self,
+        pattern: str,
+        clock_pattern: str,
+        xz_value: int = 0,
+        signed: bool = False,
+        sample_on_posedge: bool = False,
+        begin_time: int | None = None,
+        end_time: int | None = None,
+    ) -> dict[tuple[Any, ...], Waveform]:
+        clock_patterns = self.get_matched_signals(clock_pattern)
+        if not clock_patterns:
+            raise Exception(f'clock pattern {clock_pattern} can not match any signal')
+        if len(clock_patterns) > 1:
+            raise Exception(
+                f'clock pattern {clock_pattern} match more than one signal: {clock_patterns}'
+            )
+        clock_full_name = next(iter(clock_patterns.values()))
+
+        matched_signals = self.get_matched_signals(pattern)
+
+        return {
+            k: self.load_waveform(
+                s,
+                clock_full_name,
+                xz_value=xz_value,
+                signed=signed,
+                sample_on_posedge=sample_on_posedge,
+                begin_time=begin_time,
+                end_time=end_time,
+            )
+            for k, s in matched_signals.items()
+        }
+
+    @abstractmethod
+    def close(self):
+        pass