wavekit 0.7.1__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.1 → wavekit-0.7.3}/pyproject.toml

@@ -1,10 +1,11 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.7.1"
-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" },
@@ -16,11 +17,17 @@ numpy = "^2.0.0"
 vcdvcd = "^2.3.5"
 pylibfst = "^0.2.1"
 pytest = "^8.2.2"
+lark = ">=1.2,<2"
 
 [tool.poetry.group.dev.dependencies]
 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.1 → 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.3/src/wavekit/expression.py

@@ -0,0 +1,165 @@
+"""Parsing and evaluating WaveKit waveform expressions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from lark import Lark, Transformer
+
+_EXPRESSION_GRAMMAR = r"""
+?start: expr
+?expr: bit_or
+?bit_or: bit_xor | bit_or VBAR bit_xor
+?bit_xor: bit_and | bit_xor CIRCUMFLEX bit_and
+?bit_and: comparison | bit_and AMPERSAND comparison
+?comparison: shift
+           | comparison EQEQ shift
+           | comparison NEQ shift
+           | comparison LE shift
+           | comparison LT shift
+           | comparison GE shift
+           | comparison GT shift
+?shift: sum | shift LSHIFT sum | shift RSHIFT sum
+?sum: product | sum PLUS product | sum MINUS product
+?product: unary
+        | product STAR unary
+        | product SLASH unary
+        | product FLOOR unary
+        | product PERCENT unary
+        | product POWER unary
+?unary: TILDE unary | PLUS unary | MINUS unary | atom
+?atom: call | path | NUMBER | group
+group: LPAR expr RPAR
+call: NAME LPAR [expr (COMMA expr)*] RPAR
+path: segment (DOT segment)* SUBSCRIPT*
+segment: segment_text | WILDCARD
+segment_text: segment_piece+
+?segment_piece: NAME | MODULE | BRACE | REGEX
+
+MODULE: /\${1,2}/
+BRACE: /\{[^{}]*\}/
+WILDCARD.3: "**" | "*"
+REGEX: /\/(?:\\.|[^\/\\])*\//
+SUBSCRIPT: /\[\d+(?::\d+)?\]/
+NAME: /[A-Za-z_][A-Za-z0-9_]*/
+HEX_NUMBER.2: /0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*/
+BIN_NUMBER.2: /0[bB][01](?:_?[01])*/
+OCT_NUMBER.2: /0[oO][0-7](?:_?[0-7])*/
+DECIMAL_FLOAT_NUMBER.2: /(?:\d(?:_?\d)*)?\.(?:\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/
+EXP_NUMBER.2: /\d(?:_?\d)*[eE][+-]?\d(?:_?\d)*/
+DEC_NUMBER.1: /\d(?:_?\d)*/
+NUMBER: HEX_NUMBER | BIN_NUMBER | OCT_NUMBER | DECIMAL_FLOAT_NUMBER | EXP_NUMBER | DEC_NUMBER
+
+VBAR: "|"
+CIRCUMFLEX: "^"
+AMPERSAND: "&"
+EQEQ: "=="
+NEQ: "!="
+LE: "<="
+LT: "<"
+GE: ">="
+GT: ">"
+LSHIFT: "<<"
+RSHIFT: ">>"
+PLUS: "+"
+MINUS: "-"
+STAR: "*"
+SLASH: "/"
+FLOOR: "//"
+PERCENT: "%"
+POWER: "**"
+TILDE: "~"
+LPAR: "("
+RPAR: ")"
+COMMA: ","
+DOT: "."
+
+%import common.WS_INLINE
+%ignore WS_INLINE
+"""
+
+_EXPRESSION_PARSER = Lark(
+    _EXPRESSION_GRAMMAR,
+    parser='lalr',
+    lexer='contextual',
+)
+_EXPRESSION_FUNCTIONS: dict[str, Callable[..., Any]] = {}
+
+
+def expression_function(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Register a Waveform method as callable from an expression string."""
+    _EXPRESSION_FUNCTIONS[func.__name__] = func
+    return func
+
+
+class ExpressionTransformer(Transformer):
+    def __init__(self, *, function_names: set[str]):
+        super().__init__()
+        self.function_names = function_names
+        self.path_entries: list[tuple[str, str]] = []
+
+    @staticmethod
+    def join(items: list[Any]) -> str:
+        return ''.join(str(item) for item in items)
+
+    def call(self, items: list[Any]) -> str:
+        name = str(items[0])
+        if name not in self.function_names:
+            raise ValueError(f'unknown expression function {name!r}')
+        return self.join(items)
+
+    def path(self, items: list[Any]) -> str:
+        path = self.join(items)
+        placeholder = f'__wave_{len(self.path_entries)}__'
+        self.path_entries.append((placeholder, path))
+        return placeholder
+
+    def __default__(self, data: str, children: list[Any], meta: Any) -> Any:
+        return self.join(children)
+
+    def __default_token__(self, token: Any) -> str:
+        return str(token)
+
+
+def parse_expression(expr: str) -> tuple[str, list[tuple[str, str]]]:
+    """Parse an expression and replace each signal path with a placeholder.
+
+    Parameters
+    ----------
+    expr:
+        WaveKit expression containing physical signal paths.
+
+    Returns
+    -------
+    tuple[str, list[tuple[str, str]]]
+        The substituted expression and ordered ``(placeholder, path)`` entries.
+    """
+    tree = _EXPRESSION_PARSER.parse(expr)
+    transformer = ExpressionTransformer(
+        function_names=set(_EXPRESSION_FUNCTIONS),
+    )
+    result = transformer.transform(tree)
+    return str(result), transformer.path_entries
+
+
+def evaluate_expression(expr: str, namespace: dict[str, Any]) -> Any:
+    """Evaluate an already-parsed expression against preloaded Waveforms.
+
+    Parameters
+    ----------
+    expr:
+        The substituted expression returned by ``parse_expression``.
+        Physical paths must be resolved and replaced before calling this
+        function.
+    namespace:
+        Names available to the expression, normally Waveform objects.
+
+    Returns
+    -------
+    Any
+        The result produced by the Waveform expression.
+    """
+    evaluation_namespace = {**_EXPRESSION_FUNCTIONS, **namespace}
+    code = compile(expr, '<wavekit-expression>', 'eval')
+    return eval(code, {'__builtins__': {}}, evaluation_namespace)  # noqa: S307

{wavekit-0.7.1 → 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.1 → 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.1 → 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."""