wavekit

English | 中文

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 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

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 for setup details.

Quick start

Calculate the occupancy of a FIFO from a VCD waveform:

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 for a complete runnable FIFO example.

Documentation

See the documentation for the full reference and guides:

• Installation
• First waveform
• Reader guide
• Signal queries
• Waveform analysis
• Pattern matching
• API reference
• Complete examples

Development

Install the development dependencies and run the checks with Poetry:

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:

poetry install --with docs
poetry run zensical build --clean --strict

See Contributing for contribution guidelines.

License

This project is licensed under the MIT License. See LICENSE.