wavekit 0.5.1__tar.gz → 0.5.3__tar.gz

{wavekit-0.5.1 → wavekit-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavekit
-Version: 0.5.1
+Version: 0.5.3
 Summary: a fundamental package for digital circuit waveform analysis
 License-File: LICENSE
 Author: cxzzzz

{wavekit-0.5.1 → wavekit-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.5.1"
+version = "0.5.3"
 description = "a fundamental package for digital circuit waveform analysis"
 authors = ["cxzzzz <cxz19961010@outlook.com>"]
 readme = "README.md"

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/readers/base.py

@@ -38,7 +38,7 @@ class Reader:
     If the bit-range suffix is omitted and the file stores the signal with a
     range, the range is appended automatically.
 
-    Pattern syntax (used by :meth:`get_matched_signals`,
+    Pattern syntax (used by :meth:`get_matched_signals`, :meth:`get_matched_scopes`,
     :meth:`load_matched_waveforms`, :meth:`eval`)
     -------------------------------------------------
     * ``{a,b,c}``     — matches ``a``, ``b``, or ``c``; captures each as a key.
@@ -233,7 +233,7 @@ class Reader:
             )
         return matched_signals
 
-    def get_matched_scope(
+    def get_matched_scopes(
         self,
         pattern: str,
         root_scope: Scope | None = None,
@@ -270,7 +270,7 @@ class Reader:
         ::
 
             # Find all fifo_N sub-scopes under tb.dut
-            scopes = reader.get_matched_scope("tb.dut.fifo_{0..3}")
+            scopes = reader.get_matched_scopes("tb.dut.fifo_{0..3}")
             for (idx,), scope in scopes.items():
                 waves = reader.load_matched_waveforms(
                     "w_ptr[2:0]", clock_pattern="clk", root_scope=scope

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/readers/fsdb/npi_fsdb_reader.pyx

@@ -3,7 +3,6 @@ import math
 import sys
 import numpy as np
 cimport numpy as np
-#from cpython import PyBytes_FromString
 import cython
 from libcpp.vector cimport vector
 from libc.stdlib cimport malloc, free
@@ -17,165 +16,159 @@ NPI_FSDB_CT_TAGGED_UNION = <int>npiFsdbSigCtTaggedUnion
 NPI_FSDB_CT_RECORD       = <int>npiFsdbSigCtRecord
 
 
-cdef class NpiFsdbScope:
-    pass
+cdef class NpiFsdbSignal:
+    """Wraps a npiFsdbSigHandle — a single signal (leaf or composite) in the FSDB hierarchy."""
+    cdef npiFsdbSigHandle sig_handle
+
+    @staticmethod
+    cdef init(npiFsdbSigHandle sig_handle):
+        sig = NpiFsdbSignal()
+        sig.sig_handle = sig_handle
+        return sig
+
+    def __init__(self):
+        self.sig_handle = NULL
+
+    def name(self) -> str:
+        assert self.sig_handle != NULL
+        name = npi_fsdb_sig_property_str(npiFsdbSigName, self.sig_handle).decode('ascii')
+        # NPI returns fully-qualified names like "tb.dut.field"; take only the last component.
+        # Array elements are named "a[0]", "a[0][1]" etc. — splitting by "." is safe since
+        # brackets cannot contain ".".
+        name = name.split(".")
+        name = name[len(name)-1]
+        return name
+
+    def has_member(self) -> bool:
+        assert self.sig_handle != NULL
+        cdef int has_member
+        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member):
+            return has_member != 0
+        return False
+
+    def composite_type(self):
+        """Return the npiFsdbSigCompositeType_e int value, or None if not composite."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int ct
+        if not (npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member):
+            return None
+        if npi_fsdb_sig_property(npiFsdbSigCompositeType, self.sig_handle, &ct):
+            return ct
+        return None
+
+    def width(self) -> int:
+        """Return the total bit-width of this signal (sum of all leaf members for composites)."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int w
+        cdef npiFsdbSigIter sub_signal_iter
+        cdef npiFsdbSigHandle sub_signal
+        assert npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member)
+        if has_member == 0:
+            assert npi_fsdb_sig_property(npiFsdbSigRangeSize, self.sig_handle, &w)
+            return w
+        else:
+            sub_signal_iter = npi_fsdb_iter_member(self.sig_handle)
+            assert sub_signal_iter != NULL
+            w = 0
+            while (sub_signal := npi_fsdb_iter_sig_next(sub_signal_iter)):
+                w += NpiFsdbSignal.init(sub_signal).width()
+            return w
+
+    def range(self):
+        """Return the (high, low) bit-range tuple, or None for non-array composites."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int ct
+        cdef int left_range, right_range
+        assert npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member)
+        assert npi_fsdb_sig_property(npiFsdbSigLeftRange, self.sig_handle, &left_range)
+        assert npi_fsdb_sig_property(npiFsdbSigRightRange, self.sig_handle, &right_range)
+        if has_member != 0:
+            assert npi_fsdb_sig_property(npiFsdbSigCompositeType, self.sig_handle, &ct)
+            if ct == <int>npiFsdbSigCtArray:
+                return (left_range, right_range)
+            return None
+        return None
+
+    def member_list(self) -> list:
+        """Return direct member NpiFsdbSignal objects for composite signals."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef npiFsdbSigIter member_iter
+        cdef npiFsdbSigHandle member_handle
+
+        res = []
+        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
+            member_iter = npi_fsdb_iter_member(self.sig_handle)
+            while True:
+                member_handle = npi_fsdb_iter_sig_next(member_iter)
+                if member_handle == NULL:
+                    break
+                res.append(NpiFsdbSignal.init(member_handle))
+            npi_fsdb_iter_sig_stop(member_iter)
+        return res
 
 
-cdef class NpiFsdbNormalScope(NpiFsdbScope):
+cdef class NpiFsdbScope:
+    """Wraps a npiFsdbScopeHandle — a scope node (module/block) in the FSDB hierarchy."""
     cdef npiFsdbScopeHandle scope_handle
 
     @staticmethod
     cdef init(npiFsdbScopeHandle scope_handle):
-        scope = NpiFsdbNormalScope()
+        scope = NpiFsdbScope()
         scope.scope_handle = scope_handle
         return scope
 
     def __init__(self):
         self.scope_handle = NULL
 
-    def child_scope_list(self, include_signal_scope:bool = True) -> list[NpiFsdbScope]:
+    def child_scope_list(self) -> list:
+        """Return direct child NpiFsdbScope nodes (not signals)."""
         assert self.scope_handle != NULL
         res = []
         child_scope_handle_iter = npi_fsdb_iter_child_scope(self.scope_handle)
-        
+
         cdef npiFsdbScopeHandle child_scope_handle
         while True:
             child_scope_handle = npi_fsdb_iter_scope_next(child_scope_handle_iter)
             if child_scope_handle == NULL:
                 break
-            res.append(NpiFsdbNormalScope.init(child_scope_handle))
+            res.append(NpiFsdbScope.init(child_scope_handle))
         npi_fsdb_iter_scope_stop(child_scope_handle_iter)
-
-
-        cdef npiFsdbSigHandle child_sig_handle
-        if include_signal_scope:
-            child_sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
-            while True:
-                child_sig_handle = npi_fsdb_iter_sig_next(child_sig_handle_iter)
-                if child_sig_handle == NULL:
-                    break
-                res.append(NpiFsdbSignalScope.init(child_sig_handle))
-            npi_fsdb_iter_sig_stop(child_sig_handle_iter)
         return res
 
-    def signal_list(self) -> list[str]:
+    def signal_list(self) -> list:
+        """Return direct child NpiFsdbSignal objects declared in this scope."""
         assert self.scope_handle != NULL
-
         res = []
-        sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
-        cdef npiFsdbSigHandle sig_handle
-        cdef const char* c_str
+        child_sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
+
+        cdef npiFsdbSigHandle child_sig_handle
         while True:
-            sig_handle = npi_fsdb_iter_sig_next(sig_handle_iter)
-            if sig_handle == NULL:
+            child_sig_handle = npi_fsdb_iter_sig_next(child_sig_handle_iter)
+            if child_sig_handle == NULL:
                 break
-            c_str = npi_fsdb_sig_property_str(npiFsdbSigName, sig_handle)
-            name = c_str.decode('ascii')
-            res.append(name)
-        npi_fsdb_iter_sig_stop(sig_handle_iter)
-
+            res.append(NpiFsdbSignal.init(child_sig_handle))
+        npi_fsdb_iter_sig_stop(child_sig_handle_iter)
         return res
 
     def name(self) -> str:
         assert self.scope_handle != NULL
-        name = npi_fsdb_scope_property_str(npiFsdbScopeName, self.scope_handle).decode('ascii')
-        return name
+        return npi_fsdb_scope_property_str(npiFsdbScopeName, self.scope_handle).decode('ascii')
 
     def type(self) -> str:
         assert self.scope_handle != NULL
-        type_str = npi_fsdb_scope_property_str(npiFsdbScopeType, self.scope_handle).decode('ascii')
-        return type_str
-
-    def def_name(self) -> str:
-        assert self.scope_handle != NULL
-        def_name = npi_fsdb_scope_property_str(npiFsdbScopeDefName, self.scope_handle).decode('ascii')
-        return def_name
-
-cdef class NpiFsdbSignalScope(NpiFsdbScope):
-    cdef npiFsdbSigHandle sig_handle
-
-    @staticmethod
-    cdef init(npiFsdbSigHandle sig_handle):
-        scope = NpiFsdbSignalScope()
-        scope.sig_handle = sig_handle
-        return scope
-
-    def __init__(self):
-        self.sig_handle = NULL
+        return npi_fsdb_scope_property_str(npiFsdbScopeType, self.scope_handle).decode('ascii')
 
-    def child_scope_list(self, include_signal_scope:bool = True) -> list[NpiFsdbScope]:
-        assert self.sig_handle != NULL
-
-        cdef int has_member
-        cdef npiFsdbSigIter member_iter
-        cdef npiFsdbSigHandle member_handle
-
-        res = []
-        if include_signal_scope:
-            if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
-                member_iter = npi_fsdb_iter_member(self.sig_handle)
-                while True:
-                    member_handle = npi_fsdb_iter_sig_next(member_iter)
-                    if member_handle == NULL:
-                        break
-                    res.append(NpiFsdbSignalScope.init(member_handle))
-                npi_fsdb_iter_sig_stop(member_iter)
-        return res
-
-    def signal_list(self) -> list[str]:
-        assert self.sig_handle != NULL
-
-        cdef const char* c_str
-        cdef npiFsdbSigIter member_iter
-        cdef npiFsdbSigHandle member_handle
-        cdef int has_member
-        res = []
-
-        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
-            member_iter = npi_fsdb_iter_member(self.sig_handle)
-            while True:
-                member_handle = npi_fsdb_iter_sig_next(member_iter)
-                if member_handle == NULL:
-                    break
-                c_str = npi_fsdb_sig_property_str(npiFsdbSigName, member_handle)
-                name = c_str.decode('ascii')
-                name = name.split(".")
-                name = name[len(name)-1]
-                res.append(name)
-            npi_fsdb_iter_sig_stop(member_iter)
-        return res
-
-    def name(self) -> str:
-        assert self.sig_handle != NULL
-        name = npi_fsdb_sig_property_str(npiFsdbSigName, self.sig_handle).decode('ascii')
-        #TODO: this only works for non-array type (array's name is like data[0],can't be split by ".")
-        name = name.split(".")
-        name = name[len(name)-1]
-        return name
-
-    def has_member(self) -> bool:
-        assert self.sig_handle != NULL
-        cdef int has_member
-        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member):
-            return has_member != 0
-        return False
-
-    def composite_type(self):
-        """Return the npiFsdbSigCompositeType_e int value, or None if not composite."""
-        assert self.sig_handle != NULL
-        cdef int has_member
-        cdef int ct
-        if not (npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member):
+    def def_name(self) -> str | None:
+        """Return the module definition name, or None if this scope is not a module."""
+        if self.type() != 'npiFsdbScopeSvModule':
             return None
-        if npi_fsdb_sig_property(npiFsdbSigCompositeType, self.sig_handle, &ct):
-            return ct
-        return None
+        return npi_fsdb_scope_property_str(npiFsdbScopeDefName, self.scope_handle).decode('ascii')
 
-    def type(self) -> str:
-        raise NotImplementedError("type property of signal scope is not supported")
 
-    def def_name(self) -> str:
-        raise NotImplementedError("def_name property of signal scope is not supported")
 @cython.boundscheck(False)  # 关闭边界检查以提升性能
 @cython.wraparound(False)   # 关闭负索引检查以提升性能
 cdef inline cstr_to_ull(char* str, unsigned int xz_value, int max_bit_num = 2147483647):
@@ -210,88 +203,6 @@ cdef inline cstr_to_bit(char* str, unsigned int xz_value):
         value = xz_value
     return value
 
-cdef inline fsdb_read_value_change(vct_handle: npiFsdbVctHandle, begin_time, end_time, width:int, xz_value:int):
-
-    cdef npiFsdbTime cur_time
-    cdef npiFsdbValue cur_value
-    cdef int stat
-
-    cdef vector[unsigned long long] time_array
-
-    cdef int value_array_num = math.ceil(width/64)
-    assert width <= 64*64
-    cdef vector[unsigned long long] value_array[64]
-
-    cdef int first = 1
-    cdef int i,j
-    cdef unsigned long long cur_int_value
-    while True:
-        if first:
-            if begin_time is None:
-                stat = npi_fsdb_goto_first(vct_handle)
-            else:
-                stat = npi_fsdb_goto_time(vct_handle,  <npiFsdbTime> begin_time)
-        else:
-            stat = npi_fsdb_goto_next(vct_handle)
-        if stat == 0:
-            break
-
-        cur_value.format = npiFsdbBinStrVal
-        npi_fsdb_vct_time(vct_handle, &cur_time)
-        npi_fsdb_vct_value(vct_handle, &cur_value)
-        if cur_time > end_time:
-            break
-
-        time_array.push_back(cur_time)
-        if width == 1: # opt for clk
-            value_array[0].push_back(cstr_to_bit(<char*>cur_value.value.str, xz_value))
-        else:
-            cur_lllint_value = 0
-            for i in range(value_array_num):
-                value_array[i].push_back(cstr_to_ull(<char*>cur_value.value.str + 64*i, xz_value, 64))
-
-    result = np.zeros((value_array[0].size(), 2), dtype=np.uint64 if width <= 64 else np.object_)  # 创建一个 (n, 2) 的二维数组，dtype 为 int32
-    for j in range(value_array[0].size()):
-        result[j][0] = time_array[j]
-        if width <= 64:
-            result[j][1] = value_array[0][j]
-        else:
-            for i in range(value_array_num):
-                result[j][1] = (result[j][1] << 64) + value_array[i][j]
-
-    return result
-
-cdef get_signal_handle_width(npiFsdbSigHandle signal_handle):
-    cdef int has_member
-    cdef int width
-    cdef npiFsdbSigIter sub_signal_iter
-    cdef npiFsdbSigHandle sub_signal
-    assert(npi_fsdb_sig_property(npiFsdbSigHasMember, signal_handle, &has_member))
-    if(has_member == 0):
-        assert(npi_fsdb_sig_property(npiFsdbSigRangeSize, signal_handle, &width))
-        return width
-    else:
-        sub_signal_iter = npi_fsdb_iter_member(signal_handle)
-        assert(sub_signal_iter != NULL)
-        width = 0
-        while(sub_signal := npi_fsdb_iter_sig_next(sub_signal_iter)):
-            width += get_signal_handle_width(sub_signal)
-        return width
-
-cdef get_signal_handle_range(npiFsdbSigHandle signal_handle):
-    cdef int has_member
-    cdef int type
-    cdef int left_range, right_range
-    assert(npi_fsdb_sig_property(npiFsdbSigHasMember, signal_handle, &has_member))
-    assert(npi_fsdb_sig_property(npiFsdbSigLeftRange, signal_handle, &left_range))
-    assert(npi_fsdb_sig_property(npiFsdbSigRightRange, signal_handle, &right_range))
-
-    if has_member != 0:
-        assert(npi_fsdb_sig_property(npiFsdbSigCompositeType, signal_handle, &type))
-        if type == <int>npiFsdbSigCtArray:
-            return (left_range, right_range)
-        return None
-    return None
 
 cdef class NpiFsdbReader:
     cdef npiFsdbFileHandle fsdb_handle
@@ -299,69 +210,36 @@ cdef class NpiFsdbReader:
 
     def __init__(self, str file):
         import os
-        
+
         # 检查VERDI_HOME环境变量
         verdi_home = os.environ.get('VERDI_HOME')
         if verdi_home:
             npi_lib_path = os.path.join(verdi_home, 'share/NPI/lib/LINUX64/libNPI.so')
-        
-        #cdef int argc = len(sys.argv)
-        #cdef char** argv = <char**>malloc((argc + 1) * sizeof(char*))
-
-        #for i in range(argc):
-        #    argv[i] = <char*>malloc(strlen(sys.argv[i].encode('ascii')))
-        #    strcpy(argv[i], sys.argv[i].encode('ascii'))
-        #argv[argc] = NULL  # Null-terminate the array
-
-        #npi_init(argc, argv)
-        #self.file = file
-        #free(argv)
 
-        #cdef npiFsdbFileHandle fsdb_handle
         file_str = file.encode('utf-8')
         cdef char* file_s = file_str
         self.fsdb_handle = npi_fsdb_open(file_s)
         if(self.fsdb_handle == NULL):
             raise OSError(f"Failed to open fsdb file :{file_str}")
 
-
-
-    def get_signal_width(
-        self,
-        str signal
-    ) -> int:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
-        assert signal_handle != NULL, f"can't find signal: {signal}"
-        
-        cdef int width = get_signal_handle_width(signal_handle)
-        return width
-
-    def get_signal_range(
-        self,
-        str signal
-    ) -> tuple[int,int]:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
+    def get_signal(self, str signal) -> NpiFsdbSignal:
+        """Look up a signal by its full hierarchical path and return an NpiFsdbSignal handle."""
+        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle, signal.encode('ascii'), NULL)
         assert signal_handle != NULL, f"can't find signal: {signal}"
-
-        return get_signal_handle_range(signal_handle)
+        return NpiFsdbSignal.init(signal_handle)
 
     @cython.boundscheck(False)  # 关闭边界检查以提升性能
     @cython.wraparound(False)   # 关闭负索引检查以提升性能
     def load_value_change(
         self,
-        str signal,
+        NpiFsdbSignal signal,
         unsigned long long begin_time,
         unsigned long long end_time,
         int xz_value
     ) -> np.ndarray:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
-        assert signal_handle != NULL, f"can't find signal: {signal}"
-        cdef int width = get_signal_handle_width(signal_handle)
 
-        cdef npiFsdbVctHandle signal_vct_handle = npi_fsdb_create_vct(signal_handle)
+        cdef int width = signal.width()
+        cdef npiFsdbVctHandle signal_vct_handle = npi_fsdb_create_vct(signal.sig_handle)
         cdef npiFsdbTime cur_time
         cdef npiFsdbValue cur_value
         cdef int stat
@@ -382,7 +260,7 @@ cdef class NpiFsdbReader:
                     stat = npi_fsdb_goto_time(signal_vct_handle,  <npiFsdbTime> begin_time)
             else:
                 stat = npi_fsdb_goto_next(signal_vct_handle)
-            
+
             if stat == 0:
                 break
 
@@ -422,11 +300,7 @@ cdef class NpiFsdbReader:
                 result_object[:,1] = (result_object[:,1] << shift) + value_np_array
             return result_object
 
-        #npi_fsdb_release_vct(signal_vct_handle)
-        #npi_fsdb_unload_vc(self.fsdb_handle)
-        #return result
-
-    def top_scope_list(self) -> list[NpiFsdbScope]:
+    def top_scope_list(self) -> list:
         cdef npiFsdbScopeIter top_scope_iter
         cdef npiFsdbScopeHandle top_scope_handle
 
@@ -436,7 +310,7 @@ cdef class NpiFsdbReader:
             top_scope_handle = npi_fsdb_iter_scope_next(top_scope_iter)
             if top_scope_handle == NULL:
                 break
-            res.append(NpiFsdbNormalScope.init(top_scope_handle))
+            res.append(NpiFsdbScope.init(top_scope_handle))
         npi_fsdb_iter_scope_stop(top_scope_iter)
         return res
 

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/readers/fsdb/reader.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import importlib
 from collections import defaultdict
 from collections.abc import Sequence
+from dataclasses import dataclass, field
 from functools import cached_property
 from typing import Any
 
@@ -20,92 +21,95 @@ from .npi_fsdb_reader import (
     NPI_FSDB_CT_UNION,
     NpiFsdbReader,
     NpiFsdbScope,
-    NpiFsdbSignalScope,
+    NpiFsdbSignal,
 )
 
-_NPI_CT_TO_ENUM = {
-    NPI_FSDB_CT_ARRAY: SignalCompositeType.ARRAY,
-    NPI_FSDB_CT_STRUCT: SignalCompositeType.STRUCT,
-    NPI_FSDB_CT_UNION: SignalCompositeType.UNION,
-    NPI_FSDB_CT_TAGGED_UNION: SignalCompositeType.TAGGED_UNION,
-    NPI_FSDB_CT_RECORD: SignalCompositeType.RECORD,
-}
-
-
-def _build_signal_from_handle(
-    sig_scope: NpiFsdbSignalScope,
-    full_name: str,
-    reader: FsdbReader,
-) -> Signal:
-    """Recursively build a Signal (with children) from a NpiFsdbSignalScope handle."""
-    width = reader._get_signal_width(full_name)
-    rng = reader._get_signal_range(full_name)
-    ct_raw = sig_scope.composite_type()
-    if ct_raw is None:
-        composite_type = None
-    elif ct_raw in _NPI_CT_TO_ENUM:
-        composite_type = _NPI_CT_TO_ENUM[ct_raw]
-    else:
-        raise ValueError(f"Unknown NPI composite type value: {ct_raw} for signal '{full_name}'")
-
-    children = None
-    if composite_type is not None:
-        children = []
-        for child_scope in sig_scope.child_scope_list():
-            child_full_name = f'{full_name}.{child_scope.name()}'
-            children.append(_build_signal_from_handle(child_scope, child_full_name, reader))
-
-    return Signal(
-        name=sig_scope.name(),
-        full_name=full_name,
-        width=width,
-        range=rng,
-        signed=False,
-        composite_type=composite_type,
-        children=children,
-    )
+
+@dataclass
+class FsdbSignal(Signal):
+    """FSDB-backed :class:`~wavekit.signal.Signal` with lazy member loading.
+
+    Extends :class:`~wavekit.signal.Signal` by holding an NPI signal handle
+    directly, enabling on-demand loading of composite members without any
+    reader reference.  Construct via :meth:`from_handle`.
+    """
+
+    _npi_signal: NpiFsdbSignal | None = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def from_handle(cls, npi_sig: NpiFsdbSignal, full_name: str) -> FsdbSignal:
+        """Build an :class:`FsdbSignal` from an NPI signal handle and its full path."""
+        _npi_ct_to_enum = {
+            NPI_FSDB_CT_ARRAY: SignalCompositeType.ARRAY,
+            NPI_FSDB_CT_STRUCT: SignalCompositeType.STRUCT,
+            NPI_FSDB_CT_UNION: SignalCompositeType.UNION,
+            NPI_FSDB_CT_TAGGED_UNION: SignalCompositeType.TAGGED_UNION,
+            NPI_FSDB_CT_RECORD: SignalCompositeType.RECORD,
+        }
+        ct_raw = npi_sig.composite_type()
+        if ct_raw is None:
+            composite_type = None
+        elif ct_raw in _npi_ct_to_enum:
+            composite_type = _npi_ct_to_enum[ct_raw]
+        else:
+            raise ValueError(f"Unknown NPI composite type value: {ct_raw} for signal '{full_name}'")
+        return cls(
+            name=npi_sig.name(),
+            full_name=full_name,
+            width=npi_sig.width(),
+            range=npi_sig.range(),
+            composite_type=composite_type,
+            _npi_signal=npi_sig,
+        )
+
+    @cached_property
+    def member_list(self) -> list[Signal] | None:
+        if self.composite_type is None:
+            return None
+        assert self._npi_signal is not None
+        npi_members = self._npi_signal.member_list()
+        if self.composite_type == SignalCompositeType.ARRAY:
+            # Array members' NPI names already include the array base name at every
+            # level, e.g. parent "a" has members "a[0]", "a[1]", and "a[0]" further
+            # has members "a[0][0]", "a[0][1]", etc.  The member name is therefore an
+            # extension of the parent name with no extra "." separator, so we must NOT
+            # prepend full_name (which would produce "tb.dut.a.a[0]").  Instead we use
+            # the parent scope path (full_name minus the signal's own local name) as
+            # the base, giving "tb.dut.a[0]", "tb.dut.a[0][1]", etc.
+            scope_path = self.full_name[: -(len(self.name) + 1)]
+            return [FsdbSignal.from_handle(m, f'{scope_path}.{m.name()}') for m in npi_members]
+        else:
+            return [FsdbSignal.from_handle(m, f'{self.full_name}.{m.name()}') for m in npi_members]
 
 
 class FsdbScope(Scope):
     def __init__(self, handle: NpiFsdbScope, parent_scope: FsdbScope | None, reader: FsdbReader):
         super().__init__(name=handle.name())
-        self.handle = handle
+        self._npi_scope = handle
         self.parent_scope = parent_scope
         self.reader = reader
 
     @cached_property
     def signal_list(self) -> Sequence[Signal]:
         full_scope_name = self.full_name()
-        signals = []
-        for sig_scope in self.handle.child_scope_list(include_signal_scope=True):
-            if not isinstance(sig_scope, NpiFsdbSignalScope):
-                continue
-            signal_path = f'{full_scope_name}.{sig_scope.name()}'
-            signals.append(_build_signal_from_handle(sig_scope, signal_path, self.reader))
-        return signals
+        return [
+            FsdbSignal.from_handle(npi_sig, f'{full_scope_name}.{npi_sig.name()}')
+            for npi_sig in self._npi_scope.signal_list()
+        ]
 
     @cached_property
     def child_scope_list(self) -> Sequence[Scope]:
-        return [FsdbScope(c, self, self.reader) for c in self.handle.child_scope_list()]
+        return [FsdbScope(c, self, self.reader) for c in self._npi_scope.child_scope_list()]
 
     @cached_property
-    def child_normal_scope_list(self) -> Sequence[Scope]:
-        return [
-            FsdbScope(c, self, self.reader)
-            for c in self.handle.child_scope_list(include_signal_scope=False)
-        ]
-
-    @property
     def type(self) -> str:
-        if not hasattr(self, '_type'):
-            self._type = self.handle.type()
-        return self._type
+        """Return the NPI scope type string, e.g. 'npiFsdbScopeSvModule'."""
+        return self._npi_scope.type()
 
-    @property
+    @cached_property
     def def_name(self) -> str | None:
-        if not hasattr(self, '_def_name'):
-            self._def_name = self.handle.def_name()
-        return self._def_name
+        """Return the module definition name, or None if this scope is not a module."""
+        return self._npi_scope.def_name()
 
     def find_scope_by_module(self, module_name: str, depth: int = 0) -> list[Scope]:
         if not hasattr(self, '_preloaded_module_scope'):
@@ -113,11 +117,8 @@ class FsdbScope(Scope):
         return self._preloaded_module_scope[module_name]
 
     def preload_module_scope(self):
-        if isinstance(self.handle, NpiFsdbSignalScope):
-            return {}
-
         preloaded_module_scope = defaultdict(list)
-        for c in self.child_normal_scope_list:
+        for c in self.child_scope_list:
             for module_name, module_scope_list in c.preload_module_scope().items():
                 preloaded_module_scope[module_name].extend(module_scope_list)
 
@@ -166,9 +167,21 @@ class FsdbReader(Reader):
         signal_path = signal.full_name if isinstance(signal, Signal) else signal
         clock_path = clock.full_name if isinstance(clock, Signal) else clock
 
+        # Resolve NPI signal handles — reuse the handle if already available
+        npi_signal = (
+            signal._npi_signal
+            if isinstance(signal, FsdbSignal) and signal._npi_signal is not None
+            else self.file_handle.get_signal(signal_path)
+        )
+        npi_clock = (
+            clock._npi_signal
+            if isinstance(clock, FsdbSignal) and clock._npi_signal is not None
+            else self.file_handle.get_signal(clock_path)
+        )
+
         # Always load the full clock to compute absolute cycle numbers
         all_clock_changes = self.file_handle.load_value_change(
-            clock_path,
+            npi_clock,
             begin_time=0,
             end_time=2**64 - 1,
             xz_value=0,
@@ -199,7 +212,7 @@ class FsdbReader(Reader):
         # Load signal within the requested window only (FSDB NPI provides the
         # correct initial value at begin_time even if the last change was earlier)
         signal_value_change = self.file_handle.load_value_change(
-            signal_path,
+            npi_signal,
             begin_time=begin_time_actual,
             end_time=end_time_actual,
             xz_value=xz_value,
@@ -208,7 +221,7 @@ class FsdbReader(Reader):
         full_wave = self.value_change_to_waveform(
             signal_value_change,
             windowed_clock_changes,
-            width=self.file_handle.get_signal_width(signal_path),
+            width=npi_signal.width(),
             signed=signed,
             sample_on_posedge=sample_on_posedge,
             signal=signal_path,
@@ -229,12 +242,6 @@ class FsdbReader(Reader):
             ]
         return self._top_scope_list
 
-    def _get_signal_width(self, signal: str) -> int:
-        return self.file_handle.get_signal_width(signal)
-
-    def _get_signal_range(self, signal: str) -> tuple[int, int]:
-        return self.file_handle.get_signal_range(signal)
-
     @property
     def begin_time(self) -> str:
         return self.file_handle.min_time()

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/readers/vcd/reader.py

@@ -75,9 +75,6 @@ class VcdReader(Reader):
     def end_time(self) -> int:
         return self.file_handle.endtime
 
-    def _get_signal_width(self, signal: str) -> int:
-        return int(self.file_handle[signal].size)
-
     def load_waveform(
         self,
         signal: Signal | str,

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/scope.py

@@ -11,7 +11,7 @@ from .readers.pattern_parser import (
     PatternMap,
     split_by_range_expr,
 )
-from .signal import Signal
+from .signal import Signal, SignalCompositeType
 
 T = TypeVar('T')
 
@@ -84,25 +84,6 @@ class Scope:
         raise NotImplementedError()
 
 
-def _range_str_to_tuple(range_str: str) -> tuple[int, int] | None:
-    """Extract the innermost (last) ``[high:low]`` or ``[n]`` from *range_str*.
-
-    For multi-dimensional suffixes such as ``"[3][7:0]"`` only the final
-    bracket pair is returned (``(7, 0)``), because in practice only the last
-    dimension carries a bit-range; all preceding dimensions are index
-    selectors of the form ``[n]`` and are encoded in the signal name only.
-    Returns ``None`` if *range_str* is empty or contains no bracket expression.
-    """
-    if not range_str:
-        return None
-    last = re.search(r'\[(\d+)(?::(\d+))?\]$', range_str)
-    if last is None:
-        return None
-    high = int(last.group(1))
-    low = int(last.group(2)) if last.group(2) is not None else high
-    return (high, low)
-
-
 def _prepend_scope_name(value: Any, scope_name: str) -> Any:
     if isinstance(value, Signal):
         return dataclasses.replace(value, full_name=f'{scope_name}.{value.full_name}')
@@ -212,68 +193,6 @@ def _traverse_scope_tree(
     return res
 
 
-def _match_signals_in_list(
-    signals: Sequence[Signal], pattern_list: list[PatternMap]
-) -> dict[tuple[Any, ...], Signal]:
-    """Match *pattern_list* against *signals*, recursing into composite children.
-
-    The first element of *pattern_list* is matched against signal names in
-    *signals*.  When more patterns remain and the matched signal is composite
-    (``signal.children is not None``), the function recurses into those
-    children with the remaining patterns, allowing patterns to address
-    struct/union members across multiple levels.
-
-    .. note::
-        Composite member path separators are assumed to be ``"."`` (the same
-        as scope separators).  For array elements such as ``a[10].b`` this
-        means the pattern segment for the array element is ``"a[10]"`` and the
-        next segment is ``"b"``.
-
-    TODO: Verify actual NPI naming for composite members — NPI may return the
-    full name from the root signal rather than just the local node name, and
-    array-element separators may differ from ``"."``.  Adjust accordingly once
-    confirmed.
-    """
-    if not pattern_list:
-        return {}
-
-    def resolve_leaf(sig: Signal, sig_bare: str, range_suffix: str) -> Signal:
-        new_range = _range_str_to_tuple(range_suffix) if range_suffix else sig.range
-        new_local = f'{sig_bare}{range_suffix}' if range_suffix else sig.name
-        return dataclasses.replace(sig, full_name=new_local, range=new_range)
-
-    res: dict[tuple[Any, ...], Signal] = {}
-    for sig in signals:
-        sig_bare, _ = split_by_range_expr(sig.name)
-        for k, p in pattern_list[0].items():
-            if p[0] == '@':
-                name_regex, range_suffix = split_by_range_expr(p[1:])
-                if match := re.fullmatch(name_regex, sig.name):
-                    assert len(k) == 0
-                    key = (match.groups(),)
-                    if len(pattern_list) == 1:
-                        assert key not in res, f'pattern {name_regex} matches more than one signal'
-                        res[key] = resolve_leaf(sig, sig_bare, range_suffix)
-                    elif sig.children is not None:
-                        for ck, cv in _match_signals_in_list(
-                            sig.children, pattern_list[1:]
-                        ).items():
-                            res[key + ck] = _prepend_scope_name(cv, sig.name)
-            else:
-                p_bare, range_suffix = split_by_range_expr(p)
-                if p_bare != sig_bare:
-                    continue
-                key = k
-                if len(pattern_list) == 1:
-                    assert key not in res
-                    res[key] = resolve_leaf(sig, sig_bare, range_suffix)
-                elif sig.children is not None:
-                    for ck, cv in _match_signals_in_list(sig.children, pattern_list[1:]).items():
-                        res[key + ck] = _prepend_scope_name(cv, sig.name)
-                break
-    return res
-
-
 def match_signals(
     scope: Scope, descendant_scope_pattern_list: list[PatternMap]
 ) -> dict[tuple[Any, ...], Signal]:
@@ -286,6 +205,89 @@ def match_signals(
     objects whose ``full_name`` is the complete hierarchical path.
     """
 
+    def _match_signals_in_list(
+        signals: Sequence[Signal], pattern_list: list[PatternMap]
+    ) -> dict[tuple[Any, ...], Signal]:
+        """Match *pattern_list* against *signals*, recursing into composite members.
+
+        The first element of *pattern_list* is matched against signal names in
+        *signals*.  When more patterns remain and the matched signal is composite
+        (``signal.member_list is not None``), the function recurses into those
+        members with the remaining patterns, allowing patterns to address
+        struct/union members across multiple levels.
+
+        **Array signals** require special treatment because NPI reports each
+        element's name as an extension of the parent name with no ``"."``
+        separator.  For example, signal ``a`` (ARRAY) has members ``a[0]``,
+        ``a[1]``, which in turn have members ``a[0][0]``, ``a[0][1]``, etc.
+        A user pattern like ``a[10][0]`` therefore cannot be resolved by a
+        single exact-name match at the top level.  Instead, for ARRAY signals
+        we check whether the signal name is a string prefix of the pattern:
+        if yes, we recurse into members with the **same** pattern (not
+        advancing to the next element), letting each member self-select by the
+        same prefix rule until an exact match is found.
+        """
+        if not pattern_list:
+            return {}
+
+        def resolve_leaf(sig: Signal, sig_bare: str, range_suffix: str) -> Signal:
+            if range_suffix:
+                # Extract (high, low) from the innermost bracket of range_suffix,
+                # e.g. "[7:0]" → (7, 0), "[3]" → (3, 3).
+                m = re.search(r'\[(\d+)(?::(\d+))?\]$', range_suffix)
+                assert m is not None
+                h = int(m.group(1))
+                low = int(m.group(2)) if m.group(2) is not None else h
+                new_range: tuple[int, int] | None = (h, low)
+            else:
+                new_range = sig.range
+            return dataclasses.replace(
+                sig,
+                full_name=f'{sig_bare}{range_suffix}' if range_suffix else sig.name,
+                range=new_range,
+            )
+
+        res: dict[tuple[Any, ...], Signal] = {}
+        for sig in signals:
+            sig_bare, _ = split_by_range_expr(sig.name)
+            for k, p in pattern_list[0].items():
+                if p[0] == '@':
+                    name_regex, range_suffix = split_by_range_expr(p[1:])
+                    if match := re.fullmatch(name_regex, sig.name):
+                        assert len(k) == 0
+                        key = (match.groups(),)
+                        if len(pattern_list) == 1:
+                            assert (
+                                key not in res
+                            ), f'pattern {name_regex} matches more than one signal'
+                            res[key] = resolve_leaf(sig, sig_bare, range_suffix)
+                        elif sig.member_list is not None:
+                            for ck, cv in _match_signals_in_list(
+                                sig.member_list, pattern_list[1:]
+                            ).items():
+                                res[key + ck] = _prepend_scope_name(cv, sig.name)
+                else:
+                    p_bare, range_suffix = split_by_range_expr(p)
+                    if p_bare != sig_bare:
+                        continue
+                    key = k
+                    if sig.composite_type == SignalCompositeType.ARRAY and range_suffix:
+                        if sig.member_list is not None:
+                            for ck, cv in _match_signals_in_list(
+                                sig.member_list, pattern_list
+                            ).items():
+                                res[key + ck] = cv
+                    elif len(pattern_list) == 1:
+                        assert key not in res
+                        res[key] = resolve_leaf(sig, sig_bare, range_suffix)
+                    elif sig.member_list is not None:
+                        for ck, cv in _match_signals_in_list(
+                            sig.member_list, pattern_list[1:]
+                        ).items():
+                            res[key + ck] = _prepend_scope_name(cv, sig.name)
+                    break
+        return res
+
     def match_signals_in_scope(
         scope: Scope, signal_pattern_list: list[PatternMap]
     ) -> dict[tuple[Any, ...], Signal]:

{wavekit-0.5.1 → wavekit-0.5.3}/src/wavekit/signal.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
+from functools import cached_property
 
 
 class SignalCompositeType(Enum):
@@ -24,7 +25,7 @@ class Signal:
 
     Stores the signal's local name, full hierarchical path, bit-width,
     declared bit-range, and signedness.  For composite signals (structs,
-    unions, arrays) the ``composite_type`` and ``children`` fields carry
+    unions, arrays) the ``composite_type`` and ``member_list`` fields carry
     the internal structure.
 
     Attributes
@@ -59,12 +60,13 @@ class Signal:
         value describing the kind of composite.  Not all backends populate
         this field; backends that do not support composite introspection leave
         it as ``None`` (e.g. VCD).
-    children:
+    member_list:
         ``None`` for leaf signals.  For composite signals this is the list of
         direct member :class:`Signal` objects, populated in the same order the
         backend reports them.  Always ``None`` when ``composite_type`` is
         ``None``, and always a list (possibly empty) when ``composite_type``
-        is set.
+        is set.  Lazily evaluated on first access; backend-specific subclasses
+        override the ``member_list`` cached property to provide the actual loading logic.
     """
 
     name: str
@@ -73,7 +75,10 @@ class Signal:
     range: tuple[int, int] | None
     signed: bool = False
     composite_type: SignalCompositeType | None = None
-    children: list[Signal] | None = None
+
+    @cached_property
+    def member_list(self) -> list[Signal] | None:
+        return None
 
     def __str__(self) -> str:
         return (