wavekit

English | 中文

Wavekit is a Python library for high-level digital waveform analysis. It loads signals from waveform files as clock-aligned Waveform objects, allowing users to query and operate on them at the cycle and transaction levels, making complex hardware behavior easier to analyze.

Quick links: Online playground · AI integration

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:
    fifo = r['tb.u_fifo']
    with r.clock_domain(clock='tb.clk'):
        w_ptr = fifo['w_ptr'].w
        r_ptr = fifo['r_ptr'].w

    depth = 16
    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.