wavekit 0.7.2__tar.gz → 0.7.3__tar.gz

wavekit-0.7.3/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: wavekit
+Version: 0.7.3
+Summary: High-level digital waveform analysis in Python
+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: lark (>=1.2,<2)
+Requires-Dist: numpy (>=2.0.0,<3.0.0)
+Requires-Dist: pylibfst (>=0.2.1,<0.3.0)
+Requires-Dist: pytest (>=8.2.2,<9.0.0)
+Requires-Dist: vcdvcd (>=2.3.5,<3.0.0)
+Project-URL: Documentation, https://cxzzzz.github.io/wavekit
+Project-URL: Repository, https://github.com/cxzzzz/wavekit
+Description-Content-Type: text/markdown
+
+# <img src="docs/en/images/logo.svg" alt="" width="30" height="30" valign="middle"> wavekit
+
+[![CI](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml/badge.svg)](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml)
+[![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/)
+[![Downloads](https://pepy.tech/badge/wavekit)](https://pepy.tech/project/wavekit)
+[![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
+
+English | [中文](README_ZH.md)
+
+**Wavekit is a Python library for high-level digital waveform analysis.**
+Wavekit supports common digital waveform formats; by combining batch signal
+queries with analysis at the cycle and transaction levels, it helps users
+interpret recorded signal changes in terms of per-cycle state and temporal
+relationships.
+
+> **AI integration:** [wavekit-mcp](https://github.com/cxzzzz/wavekit-mcp) exposes wavekit analysis through
+> MCP tools for AI-assisted workflows.
+
+## Features
+
+- **Flexible signal queries:** find and batch-load related signals from
+  hierarchical waveform data using multiple path-matching options.
+- **Cycle-level analysis:** use a range of waveform operations on clock-sampled
+  data to analyze cycle-based behavior such as interface backpressure and FIFO
+  occupancy.
+- **Transaction-level analysis:** use temporal pattern matching to describe
+  signal relationships across multiple clock cycles for protocol analysis,
+  transaction extraction, and latency measurement.
+- **Multi-format waveform support:** load and analyze VCD, FST, and FSDB files
+  using the same API.
+
+## Installation
+
+```console
+python -m pip install wavekit
+```
+
+wavekit supports Python 3.9 and newer. FSDB support requires the Verdi NPI
+runtime (`libNPI.so`); see the [installation guide](https://cxzzzz.github.io/wavekit/getting-started/installation/) for
+setup details.
+
+## Quick start
+
+Calculate the occupancy of a FIFO from a VCD waveform:
+
+```python
+import numpy as np
+
+from wavekit import VcdReader
+
+with VcdReader('simulation.vcd') as r:
+    clock = 'tb.clk'
+    depth = 16
+
+    w_ptr = r.load_waveform(
+        'tb.u_fifo.w_ptr',
+        clock=clock,
+    )
+    r_ptr = r.load_waveform(
+        'tb.u_fifo.r_ptr',
+        clock=clock,
+    )
+
+    occupancy = (w_ptr + depth - r_ptr) % depth
+
+    print('Average occupancy:', np.mean(occupancy.value))
+```
+
+See the [first waveform tutorial](https://cxzzzz.github.io/wavekit/getting-started/first-waveform/) for a
+complete runnable FIFO example.
+
+## Documentation
+
+See the [documentation](https://cxzzzz.github.io/wavekit/) for the full reference and guides:
+
+- [Installation](https://cxzzzz.github.io/wavekit/getting-started/installation/)
+- [First waveform](https://cxzzzz.github.io/wavekit/getting-started/first-waveform/)
+- [Reader guide](https://cxzzzz.github.io/wavekit/guides/reader/)
+- [Signal queries](https://cxzzzz.github.io/wavekit/guides/signal-query/)
+- [Waveform analysis](https://cxzzzz.github.io/wavekit/guides/waveform-analysis/)
+- [Pattern matching](https://cxzzzz.github.io/wavekit/guides/pattern-matching/)
+- [API reference](https://cxzzzz.github.io/wavekit/reference/api/)
+- [Complete examples](https://cxzzzz.github.io/wavekit/examples/)
+
+## Development
+
+Install the development dependencies and run the checks with Poetry:
+
+```console
+poetry install
+poetry run pytest
+poetry run ruff check .
+poetry run ruff format --check .
+poetry run mypy
+```
+
+Build the documentation locally with Python 3.10 or newer:
+
+```console
+poetry install --with docs
+poetry run zensical build --clean --strict
+```
+
+See [Contributing](https://cxzzzz.github.io/wavekit/contributing/) for contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).
+

wavekit-0.7.3/README.md

@@ -0,0 +1,109 @@
+# <img src="docs/en/images/logo.svg" alt="" width="30" height="30" valign="middle"> wavekit
+
+[![CI](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml/badge.svg)](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml)
+[![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/)
+[![Downloads](https://pepy.tech/badge/wavekit)](https://pepy.tech/project/wavekit)
+[![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
+
+English | [中文](README_ZH.md)
+
+**Wavekit is a Python library for high-level digital waveform analysis.**
+Wavekit supports common digital waveform formats; by combining batch signal
+queries with analysis at the cycle and transaction levels, it helps users
+interpret recorded signal changes in terms of per-cycle state and temporal
+relationships.
+
+> **AI integration:** [wavekit-mcp](https://github.com/cxzzzz/wavekit-mcp) exposes wavekit analysis through
+> MCP tools for AI-assisted workflows.
+
+## Features
+
+- **Flexible signal queries:** find and batch-load related signals from
+  hierarchical waveform data using multiple path-matching options.
+- **Cycle-level analysis:** use a range of waveform operations on clock-sampled
+  data to analyze cycle-based behavior such as interface backpressure and FIFO
+  occupancy.
+- **Transaction-level analysis:** use temporal pattern matching to describe
+  signal relationships across multiple clock cycles for protocol analysis,
+  transaction extraction, and latency measurement.
+- **Multi-format waveform support:** load and analyze VCD, FST, and FSDB files
+  using the same API.
+
+## Installation
+
+```console
+python -m pip install wavekit
+```
+
+wavekit supports Python 3.9 and newer. FSDB support requires the Verdi NPI
+runtime (`libNPI.so`); see the [installation guide](https://cxzzzz.github.io/wavekit/getting-started/installation/) for
+setup details.
+
+## Quick start
+
+Calculate the occupancy of a FIFO from a VCD waveform:
+
+```python
+import numpy as np
+
+from wavekit import VcdReader
+
+with VcdReader('simulation.vcd') as r:
+    clock = 'tb.clk'
+    depth = 16
+
+    w_ptr = r.load_waveform(
+        'tb.u_fifo.w_ptr',
+        clock=clock,
+    )
+    r_ptr = r.load_waveform(
+        'tb.u_fifo.r_ptr',
+        clock=clock,
+    )
+
+    occupancy = (w_ptr + depth - r_ptr) % depth
+
+    print('Average occupancy:', np.mean(occupancy.value))
+```
+
+See the [first waveform tutorial](https://cxzzzz.github.io/wavekit/getting-started/first-waveform/) for a
+complete runnable FIFO example.
+
+## Documentation
+
+See the [documentation](https://cxzzzz.github.io/wavekit/) for the full reference and guides:
+
+- [Installation](https://cxzzzz.github.io/wavekit/getting-started/installation/)
+- [First waveform](https://cxzzzz.github.io/wavekit/getting-started/first-waveform/)
+- [Reader guide](https://cxzzzz.github.io/wavekit/guides/reader/)
+- [Signal queries](https://cxzzzz.github.io/wavekit/guides/signal-query/)
+- [Waveform analysis](https://cxzzzz.github.io/wavekit/guides/waveform-analysis/)
+- [Pattern matching](https://cxzzzz.github.io/wavekit/guides/pattern-matching/)
+- [API reference](https://cxzzzz.github.io/wavekit/reference/api/)
+- [Complete examples](https://cxzzzz.github.io/wavekit/examples/)
+
+## Development
+
+Install the development dependencies and run the checks with Poetry:
+
+```console
+poetry install
+poetry run pytest
+poetry run ruff check .
+poetry run ruff format --check .
+poetry run mypy
+```
+
+Build the documentation locally with Python 3.10 or newer:
+
+```console
+poetry install --with docs
+poetry run zensical build --clean --strict
+```
+
+See [Contributing](https://cxzzzz.github.io/wavekit/contributing/) for contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

{wavekit-0.7.2 → wavekit-0.7.3}/pyproject.toml

@@ -1,10 +1,11 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.7.2"
-description = "a fundamental package for digital circuit waveform analysis"
+version = "0.7.3"
+description = "High-level digital waveform analysis in Python"
 authors = ["cxzzzz <cxz19961010@outlook.com>"]
 readme = "README.md"
 repository = "https://github.com/cxzzzz/wavekit"
+documentation = "https://cxzzzz.github.io/wavekit"
 build = "build.py"
 include = [
     { path = "src/wavekit/**/*.so", format = "wheel" },
@@ -22,6 +23,11 @@ lark = ">=1.2,<2"
 ruff = "^0.6.2"
 mypy = "^1.11.2"
 
+
+[tool.poetry.group.docs.dependencies]
+zensical = {version = "^0.0.57", python = ">=3.10,<4.0"}
+mkdocstrings-python = {version = "1.18.2", python = ">=3.10,<4.0"}
+
 [tool.ruff]
 target-version = "py39"
 line-length = 100

{wavekit-0.7.2 → wavekit-0.7.3}/src/wavekit/__init__.py

@@ -16,7 +16,6 @@ from .readers.hierarchy import Signal as Signal
 from .readers.hierarchy import SignalCompositeType as SignalCompositeType
 from .readers.matcher import BraceCapture as BraceCapture
 from .readers.matcher import Capture as Capture
-from .readers.matcher import CaptureKey as CaptureKey
 from .readers.matcher import ExactCapture as ExactCapture
 from .readers.matcher import RegexCapture as RegexCapture
 from .readers.matcher import WildcardCapture as WildcardCapture
@@ -35,7 +34,6 @@ __all__ = [
     'Signal',
     'SignalCompositeType',
     'Capture',
-    'CaptureKey',
     'ExactCapture',
     'BraceCapture',
     'RegexCapture',

{wavekit-0.7.2 → wavekit-0.7.3}/src/wavekit/expression.py

@@ -149,7 +149,7 @@ def evaluate_expression(expr: str, namespace: dict[str, Any]) -> Any:
     Parameters
     ----------
     expr:
-        The substituted expression returned by :func:`parse_expression`.
+        The substituted expression returned by ``parse_expression``.
         Physical paths must be resolved and replaced before calling this
         function.
     namespace:

{wavekit-0.7.2 → wavekit-0.7.3}/src/wavekit/pattern/dsl.py

@@ -28,8 +28,8 @@ class Pattern:
     """Declarative temporal pattern builder over waveform signals.
 
     Build steps with ``Pattern().wait(...).capture(...)`` and execute with
-    module-level :func:`match`. ``Pattern`` stores only the declarative step AST;
-    programmable checking/extraction uses :func:`match(body)` or :func:`collect(body)`.
+    module-level ``match``. ``Pattern`` stores only the declarative step AST;
+    programmable checking/extraction uses ``match(body)`` or ``collect(body)``.
 
     The first blocking step selects candidate start cycles. Later blocking steps
     wait within a matched transaction.
@@ -77,7 +77,10 @@ class Pattern:
     def consume(
         self,
         cond: Waveform | Callable[[int, dict[str, Any]], bool] | bool,
-        channel: Channel | Hashable | Callable[[int, dict[str, Any]], Channel | Hashable],
+        channel: Channel
+        | Hashable
+        | Callable[[int, dict[str, Any]], Channel | Hashable]
+        | None = None,
         *,
         require: Waveform | Callable[[int, dict[str, Any]], bool] | bool | None = None,
         require_message: str | Callable[[int, dict[str, Any]], str] | None = None,
@@ -93,10 +96,11 @@ class Pattern:
             cycle number. ``captures`` is the current match's capture dict.
         channel:
             ``Channel``, hashable key, or ``callable(index, captures) -> Channel | Hashable``.
-            Channel callbacks use the same ``(index, captures)`` arguments.
-            The resolved ``(channel, cycle)`` can be claimed by at most one match;
-            earlier start cycles win. This does not reserve the channel while
-            ``cond`` is false.
+            If omitted, this consume step receives a private channel created when
+            the step is declared. Channel callbacks use the same ``(index, captures)``
+            arguments. The resolved ``(channel, cycle)`` can be claimed by at most
+            one match; earlier start cycles win. This does not reserve the channel
+            while ``cond`` is false.
         require:
             Optional condition checked while ``cond`` is false, or while ``cond`` is
             true but the current ``(channel, cycle)`` was already claimed. It is not
@@ -110,9 +114,13 @@ class Pattern:
         Pattern
             This pattern, for chaining.
         """
+        resolved_channel = Channel() if channel is None else channel
         self._steps.append(
             ConsumeStep(
-                cond=cond, channel=channel, require=require, require_message=require_message
+                cond=cond,
+                channel=resolved_channel,
+                require=require,
+                require_message=require_message,
             )
         )
         return self
@@ -235,7 +243,7 @@ class Pattern:
         Notes
         -----
         Exactly one of ``until`` and ``when`` is required. Conditions use the same
-        ``Waveform`` / ``bool`` / callable forms as :meth:`wait`.
+        ``Waveform`` / ``bool`` / callable forms as ``wait``.
         """
         if until is not None and when is not None:
             raise ValueError("Cannot specify both 'until' and 'when' in loop()")

{wavekit-0.7.2 → wavekit-0.7.3}/src/wavekit/pattern/result.py

@@ -19,14 +19,18 @@ class MatchStatus:
 
     @dataclass(frozen=True)
     class OK(MatchStatusValue):
-        pass
+        """Successful completion of a pattern candidate."""
 
     @dataclass(frozen=True)
     class Timeout(MatchStatusValue):
+        """A pattern candidate did not complete within its allowed duration."""
+
         message: str | None = None
 
     @dataclass(frozen=True)
     class RequireViolated(MatchStatusValue):
+        """A non-blocking ``require`` check failed."""
+
         message: str | None = None
 
 

{wavekit-0.7.2 → wavekit-0.7.3}/src/wavekit/pattern/runtime.py

@@ -37,7 +37,7 @@ class PatternContext:
 
     Programmable bodies run once per scanned start cycle. Use ``ctx.value(...)``
     to read waveforms, ``ctx.wait(...)`` / ``ctx.consume(...)`` / ``ctx.delay(...)``
-    to move through time, and return ``ctx.OK`` from :func:`wavekit.pattern.match`
+    to move through time, and return ``ctx.OK`` from ``wavekit.pattern.match``
     bodies to record a successful match.
     """
 

wavekit-0.7.3/src/wavekit/readers/__init__.py

@@ -0,0 +1 @@
+"""Waveform reader backends and hierarchy types."""