cicwave 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
cicwave/wavefiles.py ADDED
@@ -0,0 +1,935 @@
1
+ #!/usr/bin/env python3
2
+
3
+ import os
4
+ import re
5
+ import numpy as np
6
+ import pandas as pd
7
+ from matplotlib.ticker import EngFormatter
8
+
9
+ from .ngraw import toDataFrame as _ngraw_toDataFrame
10
+
11
+ # ---------------------------------------------------------------------------
12
+ # Unit auto-detection from column names.
13
+ # ---------------------------------------------------------------------------
14
+
15
+ # SI-prefix scale factors (lower-case) plus the case-sensitive ones we
16
+ # tolerate. ``u`` is accepted as an alias for ``µ`` (micro).
17
+ _SI_PREFIXES = {
18
+ 'y': 1e-24, 'z': 1e-21, 'a': 1e-18, 'f': 1e-15, 'p': 1e-12,
19
+ 'n': 1e-9, 'u': 1e-6, 'µ': 1e-6, 'm': 1e-3,
20
+ 'k': 1e3, 'K': 1e3,
21
+ 'M': 1e6, 'G': 1e9, 'T': 1e12, 'P': 1e15, 'E': 1e18,
22
+ }
23
+
24
+ # Plain-unit symbols (no prefix scaling) that we recognise as-is.
25
+ _PLAIN_UNITS = {
26
+ 's', 'Hz', 'V', 'A', 'W', 'F', 'H', 'Ω', 'ohm', 'rad', 'deg',
27
+ '°C', 'C', 'K', 'J', 'N', 'Pa', 'T', 'lx', 'cd',
28
+ }
29
+
30
+ # Log-domain units. Always treated as the literal string and never
31
+ # rescaled (you don't say "kdBm").
32
+ _LOG_UNITS = {
33
+ 'dB', 'dBm', 'dBV', 'dBuV', 'dBµV', 'dBc', 'dBFS', 'dBi', 'dBA',
34
+ }
35
+
36
+ # Base units that accept SI prefixes for auto-rescaling.
37
+ _PREFIXABLE_BASES = {'Hz', 'V', 'A', 's', 'W', 'F', 'H', 'Ω', 'ohm'}
38
+
39
+ # Match a unit token at the end of a column name, possibly enclosed in
40
+ # brackets/parens/braces or separated by underscore / space / slash.
41
+ # Examples that match:
42
+ # "Frequency_MHz" -> "MHz"
43
+ # "Amplitude [dBm]" -> "dBm"
44
+ # "Power (W)" -> "W"
45
+ # "phase / deg" -> "deg"
46
+ # Examples that DON'T match (good — these are node names, not units):
47
+ # "v(out)", "i(M1.d)", "v-out"
48
+ _UNIT_SUFFIX_RE = re.compile(
49
+ r"""
50
+ [\s_/]*
51
+ (?:
52
+ \[ \s* (?P<b>[^\[\]]+?) \s* \] # [unit]
53
+ | \( \s* (?P<p>[^()]+?) \s* \) # (unit)
54
+ | \{ \s* (?P<c>[^{}]+?) \s* \} # {unit}
55
+ | (?P<n>[A-Za-zµΩ°]+) # bare suffix
56
+ )
57
+ \s*$
58
+ """,
59
+ re.VERBOSE,
60
+ )
61
+
62
+
63
+ def _classify_unit_token(tok):
64
+ """Return ``(scale, unit_str)`` if ``tok`` is a recognised unit token,
65
+ otherwise ``None``. ``scale`` is the multiplicative factor to apply to
66
+ the data so the data, after scaling, is in the returned base unit."""
67
+ if not tok:
68
+ return None
69
+ t = tok.strip()
70
+ if not t:
71
+ return None
72
+ # Log-domain units: literal, no scaling.
73
+ if t in _LOG_UNITS:
74
+ return (1.0, t)
75
+ # Plain units: literal, no scaling.
76
+ if t in _PLAIN_UNITS:
77
+ return (1.0, t)
78
+ # SI prefix + base unit -> rescale to base.
79
+ if len(t) >= 2:
80
+ prefix, rest = t[0], t[1:]
81
+ if prefix in _SI_PREFIXES and rest in _PREFIXABLE_BASES:
82
+ return (_SI_PREFIXES[prefix], rest)
83
+ return None
84
+
85
+
86
+ def parse_unit_from_name(name):
87
+ """Detect the unit encoded in a column name.
88
+
89
+ Returns a tuple ``(scale, unit, stripped_label)`` or ``None`` if no
90
+ unit could be identified.
91
+
92
+ - ``scale`` is the multiplier to apply to the data so it ends up in
93
+ the returned base unit (e.g. ``Frequency_MHz`` -> 1e6 + ``Hz``).
94
+ - ``unit`` is the unit string suitable for ``EngFormatter`` /
95
+ axis labels.
96
+ - ``stripped_label`` is ``name`` with the trailing unit token removed,
97
+ for use as a clean axis label.
98
+ """
99
+ if not name:
100
+ return None
101
+ s = str(name)
102
+ m = _UNIT_SUFFIX_RE.search(s)
103
+ if not m:
104
+ return None
105
+ tok = m.group('b') or m.group('p') or m.group('c') or m.group('n')
106
+ cls = _classify_unit_token(tok)
107
+ if cls is None:
108
+ return None
109
+ scale, unit = cls
110
+ stripped = s[:m.start()].rstrip(" _/-:")
111
+ return (scale, unit, stripped or s)
112
+
113
+
114
+ #- Model for wavefiles
115
+
116
+ class Wave():
117
+
118
+ def __init__(self,wfile,key,xaxis):
119
+ self.xaxis = xaxis
120
+ self.wfile = wfile
121
+ self.x = None
122
+ self.y = None
123
+ self.xlabel = "Samples"
124
+ self.key = key
125
+ self.ylabel = key + f" ({wfile.name})"
126
+ self.logx = False
127
+ self.logy = False
128
+ self.xunit = ""
129
+ self.yunit, self._yscale = self._infer_yunit_and_scale(key)
130
+ self.tag = wfile.getTag(self.key)
131
+ self.line = None
132
+ self.reload()
133
+
134
+ @staticmethod
135
+ def _infer_yunit(key):
136
+ unit, _scale = Wave._infer_yunit_and_scale(key)
137
+ return unit
138
+
139
+ @staticmethod
140
+ def _infer_yunit_and_scale(key):
141
+ parsed = parse_unit_from_name(key)
142
+ if parsed is not None:
143
+ scale, unit, _ = parsed
144
+ return unit, scale
145
+ kl = (key or "").lower()
146
+ if kl.startswith("v(") or kl.startswith("v-"):
147
+ return "V", 1.0
148
+ if kl.startswith("i(") or kl.startswith("i-"):
149
+ return "A", 1.0
150
+ return "", 1.0
151
+
152
+ def deleteLine(self):
153
+ if(self.line):
154
+ self.line.remove()
155
+ self.line = None
156
+
157
+ def plot(self,ax):
158
+ x = np.real(self.x) if self.x is not None else None
159
+ y = np.real(self.y) if self.y is not None else self.y
160
+ if(x is not None):
161
+ if(not self.logx and not self.logy):
162
+ self.line, = ax.plot(x,y,label=self.ylabel)
163
+ elif(self.logx and not self.logy):
164
+ self.line, = ax.semilogx(x,y,label=self.ylabel)
165
+ elif(not self.logx and self.logy):
166
+ self.line, = ax.semilogy(x,y,label=self.ylabel)
167
+ elif(self.logx and self.logy):
168
+ self.line, = ax.loglog(x,y,label=self.ylabel)
169
+ else:
170
+ self.line, = ax.plot(y,label=self.ylabel)
171
+
172
+ if self.xunit:
173
+ ax.xaxis.set_major_formatter(EngFormatter(unit=self.xunit))
174
+ if self.yunit:
175
+ ax.yaxis.set_major_formatter(EngFormatter(unit=self.yunit))
176
+
177
+ def _set_x_from_column(self, col, label, unit, logx=False):
178
+ arr = self.wfile.df[col].to_numpy()
179
+ parsed = parse_unit_from_name(col)
180
+ if parsed is not None:
181
+ scale, base_unit, clean = parsed
182
+ if scale != 1.0:
183
+ arr = arr * scale
184
+ self.x = arr
185
+ self.xlabel = clean or label
186
+ self.xunit = base_unit
187
+ else:
188
+ self.x = arr
189
+ self.xlabel = label
190
+ self.xunit = unit
191
+ self.logx = logx
192
+
193
+ def reload(self):
194
+ self.wfile.reload()
195
+ keys = self.wfile.df.columns
196
+
197
+ if "time" in keys:
198
+ self._set_x_from_column("time", "Time", "s")
199
+ elif "frequency" in keys:
200
+ self._set_x_from_column("frequency", "Frequency", "Hz",
201
+ logx=True)
202
+ elif "v(v-sweep)" in keys:
203
+ self._set_x_from_column("v(v-sweep)", "Voltage", "V")
204
+ elif "i(i-sweep)" in keys:
205
+ self._set_x_from_column("i(i-sweep)", "Current", "A")
206
+ elif "temp-sweep" in keys:
207
+ self._set_x_from_column("temp-sweep", "Temperature", "°C")
208
+ elif self.xaxis and self.xaxis in keys:
209
+ self._set_x_from_column(self.xaxis, " ", "")
210
+ else:
211
+ for col in keys:
212
+ if col == self.key:
213
+ continue
214
+ if parse_unit_from_name(col) is not None:
215
+ self._set_x_from_column(col, col, "")
216
+ break
217
+
218
+ if self.key in keys:
219
+ y = self.wfile.df[self.key].to_numpy()
220
+ if self._yscale != 1.0:
221
+ y = y * self._yscale
222
+ self.y = y
223
+
224
+ if self.line:
225
+ if self.x is not None:
226
+ self.line.set_xdata(self.x)
227
+ self.line.set_ydata(self.y)
228
+
229
+
230
+ class WaveFile():
231
+
232
+ # Extensions where reading the column list is much cheaper than reading
233
+ # the full file. For everything else we fall back to a full load on open
234
+ # (matching pre-lazy behavior).
235
+ _HEADER_ONLY_EXTS = {
236
+ '.csv', '.tsv', '.txt',
237
+ '.xlsx', '.xls', '.ods',
238
+ '.parquet', '.feather',
239
+ }
240
+
241
+ def __init__(self, fname, xaxis, sheet_name=0, df=None):
242
+ self.xaxis = xaxis
243
+ self.fname = fname
244
+ self.sheet_name = sheet_name
245
+ self.name = os.path.basename(fname)
246
+ if isinstance(sheet_name, str):
247
+ self.name += " [%s]" % sheet_name
248
+ self.waves = dict()
249
+ self._df = df
250
+ self._columns = None
251
+ self._virtual = df is not None
252
+ if self._virtual and df is not None:
253
+ self._columns = list(df.columns)
254
+ self.modified = None
255
+ self.reload()
256
+
257
+ @property
258
+ def df(self):
259
+ if self._virtual:
260
+ return self._df
261
+ if self._df is None:
262
+ self._df = self._read_file()
263
+ self._columns = list(self._df.columns)
264
+ return self._df
265
+
266
+ @df.setter
267
+ def df(self, value):
268
+ self._df = value
269
+ if value is not None:
270
+ self._columns = list(value.columns)
271
+
272
+ def reload(self):
273
+ """Refresh metadata. Header-only on first open for cheap formats; the
274
+ full DataFrame is loaded lazily on first ``df`` access. If the file
275
+ on disk has changed since we last loaded it, drop any cached data so
276
+ the next access re-reads."""
277
+ if self._virtual:
278
+ return
279
+
280
+ if self.modified is None:
281
+ self._read_header_or_full()
282
+ self.modified = os.path.getmtime(self.fname)
283
+ return
284
+
285
+ newmodified = os.path.getmtime(self.fname)
286
+ if newmodified > self.modified:
287
+ had_full = self._df is not None
288
+ self._df = None
289
+ self._columns = None
290
+ self._read_header_or_full()
291
+ if had_full:
292
+ # Trigger full reload right away to match pre-lazy semantics
293
+ # for callers that expected fresh data after reload().
294
+ _ = self.df
295
+ self.modified = newmodified
296
+
297
+ def _read_header_or_full(self):
298
+ """Populate ``self._columns`` cheaply if possible; otherwise fall back
299
+ to a full read (which also fills ``self._df``)."""
300
+ ext = os.path.splitext(self.fname)[1].lower()
301
+ if ext in self._HEADER_ONLY_EXTS:
302
+ try:
303
+ self._columns = list(self._read_header(ext))
304
+ return
305
+ except Exception:
306
+ self._columns = None
307
+ # Formats without a cheap header path (or header read failed):
308
+ # do a full load now, matching pre-lazy behavior.
309
+ self._df = self._read_file()
310
+ self._columns = list(self._df.columns)
311
+
312
+ def _read_header(self, ext):
313
+ if ext in ('.csv',):
314
+ return self._read_csv_header(',')
315
+ if ext in ('.tsv', '.txt'):
316
+ return self._read_csv_header('\t')
317
+ if ext in ('.xlsx', '.xls', '.ods'):
318
+ df = pd.read_excel(self.fname, sheet_name=self.sheet_name, nrows=0)
319
+ return [c.strip() for c in df.columns]
320
+ if ext == '.parquet':
321
+ import pyarrow.parquet as pq
322
+ return list(pq.read_schema(self.fname).names)
323
+ if ext == '.feather':
324
+ import pyarrow.feather as pf
325
+ return list(pf.read_table(self.fname, columns=[]).schema.names)
326
+ raise ValueError("no header reader for %s" % ext)
327
+
328
+ def _read_csv_header(self, sep):
329
+ try:
330
+ df = pd.read_csv(self.fname, sep=sep, nrows=0,
331
+ engine='c', memory_map=True)
332
+ except Exception:
333
+ try:
334
+ df = pd.read_csv(self.fname, sep=sep, nrows=0)
335
+ except Exception:
336
+ df = pd.read_csv(self.fname, sep=None, engine='python',
337
+ nrows=0)
338
+ return [c.strip() for c in df.columns]
339
+
340
+ PANDAS_READERS = {
341
+ '.prn': lambda self: self._read_prn(),
342
+ '.vcd': lambda self: read_vcd(self.fname),
343
+ '.iqvsa': lambda self: read_iqvsa(self.fname),
344
+ '.csv': lambda self: self._read_csv(','),
345
+ '.tsv': lambda self: self._read_csv('\t'),
346
+ '.txt': lambda self: self._read_csv('\t'),
347
+ '.xlsx': lambda self: self._read_excel(),
348
+ '.xls': lambda self: self._read_excel(),
349
+ '.ods': lambda self: self._read_excel(),
350
+ '.pkl': lambda self: pd.read_pickle(self.fname),
351
+ '.pickle': lambda self: pd.read_pickle(self.fname),
352
+ '.json': lambda self: pd.read_json(self.fname),
353
+ '.parquet': lambda self: pd.read_parquet(self.fname),
354
+ '.feather': lambda self: pd.read_feather(self.fname),
355
+ '.h5': lambda self: pd.read_hdf(self.fname),
356
+ '.hdf5': lambda self: pd.read_hdf(self.fname),
357
+ '.html': lambda self: pd.read_html(self.fname)[0],
358
+ '.xml': lambda self: pd.read_xml(self.fname),
359
+ '.fwf': lambda self: pd.read_fwf(self.fname),
360
+ '.stata': lambda self: pd.read_stata(self.fname),
361
+ '.dta': lambda self: pd.read_stata(self.fname),
362
+ '.sas7bdat': lambda self: pd.read_sas(self.fname),
363
+ '.sav': lambda self: pd.read_spss(self.fname),
364
+ }
365
+
366
+ def _read_file(self):
367
+ ext = os.path.splitext(self.fname)[1].lower()
368
+ reader = self.PANDAS_READERS.get(ext)
369
+ if reader:
370
+ return reader(self)
371
+ return _ngraw_toDataFrame(self.fname)
372
+
373
+ def _read_csv(self, sep):
374
+ # Prefer pyarrow (much faster on large numeric CSVs); fall back to
375
+ # the C engine with memory_map, then the slow Python engine.
376
+ try:
377
+ df = pd.read_csv(self.fname, sep=sep, engine='pyarrow')
378
+ except Exception:
379
+ try:
380
+ df = pd.read_csv(self.fname, sep=sep, engine='c',
381
+ low_memory=False, memory_map=True)
382
+ except Exception:
383
+ df = pd.read_csv(self.fname, sep=None, engine='python')
384
+ df.columns = [c.strip() for c in df.columns]
385
+ return df
386
+
387
+ def _read_excel(self):
388
+ df = pd.read_excel(self.fname, sheet_name=self.sheet_name)
389
+ df.columns = [c.strip() for c in df.columns]
390
+ return df
391
+
392
+ def _read_prn(self):
393
+ """Parse Xyce .prn (print) waveform file into a DataFrame."""
394
+ sweep_var = "time"
395
+ var_names = []
396
+ times = []
397
+ data_rows = []
398
+
399
+ with open(self.fname, 'r') as f:
400
+ in_header = False
401
+ in_nodes = False
402
+ pending_time = None
403
+
404
+ for line in f:
405
+ line_s = line.strip()
406
+
407
+ if line_s.startswith('#H'):
408
+ in_header = True
409
+ in_nodes = False
410
+ continue
411
+
412
+ if line_s.startswith('#N'):
413
+ in_header = False
414
+ in_nodes = True
415
+ continue
416
+
417
+ if line_s.startswith('#C'):
418
+ in_nodes = False
419
+ in_header = False
420
+ parts = line_s.split()
421
+ pending_time = float(parts[1])
422
+ continue
423
+
424
+ if line_s.startswith('#'):
425
+ in_header = False
426
+ in_nodes = False
427
+ pending_time = None
428
+ continue
429
+
430
+ if in_header:
431
+ m = re.search(r"SWEEPVAR='([^']+)'", line_s)
432
+ if m:
433
+ sweep_var = m.group(1).lower()
434
+ continue
435
+
436
+ if in_nodes:
437
+ var_names.extend(re.findall(r"'([^']+)'", line_s))
438
+ continue
439
+
440
+ if pending_time is not None and line_s:
441
+ vals = [float(v.split(':')[0]) for v in line_s.split()]
442
+ if vals:
443
+ times.append(pending_time)
444
+ data_rows.append(vals)
445
+ pending_time = None
446
+
447
+ n_vars = len(var_names)
448
+ cols = [sweep_var] + [v.lower() for v in var_names]
449
+ rows = [[t] + d[:n_vars] for t, d in zip(times, data_rows)]
450
+ return pd.DataFrame(rows, columns=cols)
451
+
452
+ @staticmethod
453
+ def excel_sheet_names(fname):
454
+ xl = pd.ExcelFile(fname)
455
+ return xl.sheet_names
456
+
457
+ def getWaveNames(self):
458
+ if self._columns is not None:
459
+ return self._columns
460
+ return list(self.df.columns)
461
+
462
+ def getWave(self,yname):
463
+
464
+ if(yname not in self.waves):
465
+ wave = Wave(self,yname,self.xaxis)
466
+ self.waves[yname] = wave
467
+
468
+ wave = self.waves[yname]
469
+ wave.reload()
470
+
471
+ return wave
472
+
473
+ def getTag(self,yname):
474
+ return self.fname + "/" + yname
475
+
476
+
477
+ class WaveFiles(dict):
478
+
479
+ def __init__(self):
480
+ self.current = None
481
+ pass
482
+
483
+ def open(self,fname,xaxis,sheet_name=0):
484
+ key = fname if sheet_name == 0 else "%s::%s" % (fname, sheet_name)
485
+ self[key] = WaveFile(fname,xaxis,sheet_name)
486
+ self.current = key
487
+ return self[key]
488
+
489
+ def openDataFrame(self, df, name, xaxis):
490
+ key = "::virtual::" + name
491
+ self[key] = WaveFile(name, xaxis, df=df)
492
+ self.current = key
493
+ return self[key]
494
+
495
+ def select(self,fname):
496
+ if(fname in self):
497
+ self.current = fname
498
+
499
+ def remove(self, key):
500
+ """Remove a loaded file by dict key. Updates current if needed."""
501
+ if key not in self:
502
+ return
503
+ del self[key]
504
+ if self.current == key:
505
+ self.current = next(iter(self.keys()), None)
506
+
507
+ def clear_all(self):
508
+ """Remove every loaded file."""
509
+ dict.clear(self)
510
+ self.current = None
511
+
512
+ def getSelected(self):
513
+ if(self.current is not None):
514
+ return self[self.current]
515
+
516
+
517
+ # ---------------------------------------------------------------------------
518
+ # VCD parser
519
+ # ---------------------------------------------------------------------------
520
+
521
+ #- VCD timescale unit -> seconds. The standard set per IEEE 1364.
522
+ _VCD_TIMESCALE_UNITS = {
523
+ 's': 1.0, 'ms': 1e-3, 'us': 1e-6, 'µs': 1e-6, 'ns': 1e-9,
524
+ 'ps': 1e-12, 'fs': 1e-15,
525
+ }
526
+
527
+
528
+ def _vcd_parse_timescale(text):
529
+ """Parse a ``$timescale`` body like ``"1 ps"`` / ``"10ns"`` -> seconds.
530
+
531
+ Returns the multiplier that converts a raw ``#<n>`` tick into seconds.
532
+ Falls back to 1.0 if the body is missing or unrecognised.
533
+ """
534
+ s = (text or "").strip().lower().replace('\n', ' ')
535
+ if not s:
536
+ return 1.0
537
+ m = re.match(r"\s*([0-9.eE+\-]+)\s*([a-zµ]+)\s*$", s)
538
+ if m is None:
539
+ #- Sometimes the number and unit are on separate tokens with extra
540
+ #- whitespace; do a looser split.
541
+ toks = s.split()
542
+ if len(toks) >= 2:
543
+ num_s, unit_s = toks[0], toks[1]
544
+ else:
545
+ return 1.0
546
+ else:
547
+ num_s, unit_s = m.group(1), m.group(2)
548
+ try:
549
+ num = float(num_s)
550
+ except ValueError:
551
+ return 1.0
552
+ return num * _VCD_TIMESCALE_UNITS.get(unit_s, 1.0)
553
+
554
+
555
+ def read_vcd(fname, max_signals=None):
556
+ """Parse a VCD (Value Change Dump) file into a pandas DataFrame.
557
+
558
+ The result has a ``time`` column (in seconds, after applying
559
+ ``$timescale``) plus one column per signal. Single-bit signals are
560
+ stored as object arrays of ``"0" / "1" / "x" / "z"``; vector
561
+ signals are stored as Python ints (or ``None`` for x/z); real
562
+ signals are stored as floats.
563
+
564
+ The DataFrame attaches metadata in ``df.attrs['cicwave_vcd']``:
565
+ ``{'kinds': {col: 'bit'|'vector'|'real'},
566
+ 'widths': {col: int},
567
+ 'scope': {col: scoped_name}}``
568
+
569
+ Parameters
570
+ ----------
571
+ fname : str
572
+ Path to the VCD file.
573
+ max_signals : int or None
574
+ If set, only the first N declared signals are kept (used to
575
+ bound memory on huge dumps). ``None`` keeps everything.
576
+
577
+ Notes
578
+ -----
579
+ Only the subset of VCD actually emitted by Icarus / Verilator /
580
+ ngspice is supported. We follow the structure but don't try to
581
+ enforce strict compliance.
582
+ """
583
+ timescale = 1.0
584
+ #- id_code -> {'name': scoped_name, 'kind': 'bit'/'vector'/'real',
585
+ #- 'width': int}
586
+ sig_info = {}
587
+ scope_stack = []
588
+
589
+ def _parse_decls(fh):
590
+ nonlocal timescale
591
+ cur = []
592
+ in_timescale = False
593
+ for line in fh:
594
+ ls = line.strip()
595
+ if not ls:
596
+ continue
597
+ if ls.startswith('$timescale'):
598
+ in_timescale = True
599
+ cur = [ls[len('$timescale'):]]
600
+ if '$end' in ls:
601
+ timescale = _vcd_parse_timescale(
602
+ ' '.join(cur).replace('$end', ''))
603
+ in_timescale = False
604
+ continue
605
+ if in_timescale:
606
+ if '$end' in ls:
607
+ cur.append(ls.replace('$end', ''))
608
+ timescale = _vcd_parse_timescale(' '.join(cur))
609
+ in_timescale = False
610
+ else:
611
+ cur.append(ls)
612
+ continue
613
+ if ls.startswith('$scope'):
614
+ toks = ls.split()
615
+ #- $scope <type> <name> $end
616
+ if len(toks) >= 3:
617
+ scope_stack.append(toks[2])
618
+ continue
619
+ if ls.startswith('$upscope'):
620
+ if scope_stack:
621
+ scope_stack.pop()
622
+ continue
623
+ if ls.startswith('$var'):
624
+ #- $var <type> <width> <id> <name> [<bit-select>] $end
625
+ toks = ls.split()
626
+ if len(toks) < 6:
627
+ continue
628
+ vtype = toks[1]
629
+ try:
630
+ width = int(toks[2])
631
+ except ValueError:
632
+ continue
633
+ idc = toks[3]
634
+ name = toks[4]
635
+ if width == 1 and vtype != 'real':
636
+ kind = 'bit'
637
+ elif vtype == 'real':
638
+ kind = 'real'
639
+ else:
640
+ kind = 'vector'
641
+ #- Multiple $var lines can share the same id (alias). Keep
642
+ #- the first; remember every alias name in ``aliases``.
643
+ full = '.'.join(scope_stack + [name]) if scope_stack else name
644
+ if idc in sig_info:
645
+ sig_info[idc].setdefault('aliases', []).append(full)
646
+ else:
647
+ sig_info[idc] = {
648
+ 'name': full, 'kind': kind, 'width': width,
649
+ 'aliases': [],
650
+ }
651
+ continue
652
+ if ls.startswith('$enddefinitions'):
653
+ return
654
+
655
+ with open(fname, 'r', errors='replace') as fh:
656
+ _parse_decls(fh)
657
+
658
+ if max_signals is not None and len(sig_info) > max_signals:
659
+ #- Keep only the first ``max_signals`` declared ids by
660
+ #- insertion order.
661
+ keep = set(list(sig_info.keys())[:max_signals])
662
+ sig_info = {k: v for k, v in sig_info.items() if k in keep}
663
+
664
+ ids = list(sig_info.keys())
665
+ col_names = [sig_info[i]['name'] for i in ids]
666
+ kind_by_id = {i: sig_info[i]['kind'] for i in ids}
667
+ width_by_id = {i: sig_info[i]['width'] for i in ids}
668
+
669
+ #- Pre-allocate per-signal change lists: list of (time_idx, value).
670
+ changes = {i: [] for i in ids}
671
+ times = []
672
+ cur_t = 0
673
+ in_dump = False # inside $dumpvars / $dumpall block
674
+
675
+ def _ensure_t0():
676
+ #- Some VCDs (e.g. our compact unit-test fixtures) emit
677
+ #- ``$dumpvars`` initial values before any ``#0`` time tick.
678
+ #- Inject t=0 so those initial values are anchored properly.
679
+ if not times:
680
+ times.append(0)
681
+
682
+ for line in fh:
683
+ ls = line.strip()
684
+ if not ls:
685
+ continue
686
+ c0 = ls[0]
687
+ if c0 == '#':
688
+ #- Time tick.
689
+ try:
690
+ cur_t = int(ls[1:])
691
+ except ValueError:
692
+ continue
693
+ if not times or times[-1] != cur_t:
694
+ times.append(cur_t)
695
+ continue
696
+ if c0 == '$':
697
+ if ls.startswith('$dumpvars') or ls.startswith('$dumpall'):
698
+ in_dump = True
699
+ _ensure_t0()
700
+ elif ls.startswith('$end'):
701
+ in_dump = False
702
+ #- Other directives ($comment etc.) ignored.
703
+ continue
704
+ if c0 in ('0', '1', 'x', 'X', 'z', 'Z', 'h', 'H', 'l', 'L'):
705
+ #- Single-bit change: value char + id (no space).
706
+ idc = ls[1:].strip()
707
+ if idc in changes:
708
+ changes[idc].append(
709
+ (len(times) - 1 if times else 0, c0.lower()))
710
+ continue
711
+ if c0 == 'b' or c0 == 'B':
712
+ #- Vector: b<bits> <id>
713
+ try:
714
+ bits, idc = ls.split(None, 1)
715
+ except ValueError:
716
+ continue
717
+ idc = idc.strip()
718
+ bits = bits[1:] # drop leading 'b'
719
+ if idc in changes:
720
+ if any(c in 'xXzZ' for c in bits):
721
+ val = None # unknown -> store as None
722
+ raw = bits.lower()
723
+ else:
724
+ try:
725
+ val = int(bits, 2)
726
+ raw = val
727
+ except ValueError:
728
+ val = None
729
+ raw = bits.lower()
730
+ changes[idc].append(
731
+ (len(times) - 1 if times else 0, raw))
732
+ continue
733
+ if c0 == 'r' or c0 == 'R':
734
+ #- Real: r<float> <id>
735
+ try:
736
+ fval, idc = ls.split(None, 1)
737
+ except ValueError:
738
+ continue
739
+ idc = idc.strip()
740
+ try:
741
+ rv = float(fval[1:])
742
+ except ValueError:
743
+ continue
744
+ if idc in changes:
745
+ changes[idc].append(
746
+ (len(times) - 1 if times else 0, rv))
747
+ continue
748
+
749
+ if not times:
750
+ #- Pathological: no time markers. Return empty frame with the
751
+ #- declared column list so the UI still shows the signal names.
752
+ df = pd.DataFrame({c: [] for c in ['time'] + col_names})
753
+ df.attrs['cicwave_vcd'] = {
754
+ 'kinds': {sig_info[i]['name']: sig_info[i]['kind'] for i in ids},
755
+ 'widths': {sig_info[i]['name']: sig_info[i]['width'] for i in ids},
756
+ 'scope': {sig_info[i]['name']: sig_info[i]['name'] for i in ids},
757
+ 'timescale_s': timescale,
758
+ }
759
+ return df
760
+
761
+ #- Build forward-filled per-signal columns.
762
+ n = len(times)
763
+ data = {'time': np.asarray(times, dtype=np.float64) * timescale}
764
+ for idc in ids:
765
+ kind = kind_by_id[idc]
766
+ if kind == 'real':
767
+ col = np.full(n, np.nan, dtype=np.float64)
768
+ cur = np.nan
769
+ j = 0
770
+ ch = changes[idc]
771
+ for t_idx in range(n):
772
+ while j < len(ch) and ch[j][0] <= t_idx:
773
+ cur = ch[j][1]
774
+ j += 1
775
+ col[t_idx] = cur
776
+ elif kind == 'bit':
777
+ col = np.empty(n, dtype=object)
778
+ cur = 'x'
779
+ j = 0
780
+ ch = changes[idc]
781
+ for t_idx in range(n):
782
+ while j < len(ch) and ch[j][0] <= t_idx:
783
+ cur = ch[j][1]
784
+ j += 1
785
+ col[t_idx] = cur
786
+ else: # vector
787
+ col = np.empty(n, dtype=object)
788
+ cur = None
789
+ j = 0
790
+ ch = changes[idc]
791
+ for t_idx in range(n):
792
+ while j < len(ch) and ch[j][0] <= t_idx:
793
+ cur = ch[j][1]
794
+ j += 1
795
+ col[t_idx] = cur
796
+ name = sig_info[idc]['name']
797
+ data[name] = col
798
+ for alias in sig_info[idc].get('aliases', []):
799
+ #- Aliases share data but get their own column for selection.
800
+ data[alias] = col
801
+
802
+ df = pd.DataFrame(data)
803
+ kinds = {sig_info[i]['name']: sig_info[i]['kind'] for i in ids}
804
+ widths = {sig_info[i]['name']: sig_info[i]['width'] for i in ids}
805
+ for i in ids:
806
+ for alias in sig_info[i].get('aliases', []):
807
+ kinds[alias] = sig_info[i]['kind']
808
+ widths[alias] = sig_info[i]['width']
809
+ df.attrs['cicwave_vcd'] = {
810
+ 'kinds': kinds,
811
+ 'widths': widths,
812
+ 'timescale_s': timescale,
813
+ }
814
+ return df
815
+
816
+
817
+ # ---------------------------------------------------------------------------
818
+ # LitePoint .iqvsa parser
819
+ # ---------------------------------------------------------------------------
820
+
821
+ #- LitePoint VSA capture: ASCII XML header terminated by ``</LPHeader>``
822
+ #- followed by interleaved little-endian float32 I,Q samples (volts at the
823
+ #- instrument port). Header carries sample rate, sample count, center
824
+ #- frequency and the full SCPI module configuration.
825
+ _IQVSA_HEADER_END = b'</LPHeader>'
826
+ _IQVSA_HEADER_SCAN_LIMIT = 1 << 20 # 1 MiB is plenty; real headers are < 4 KiB
827
+
828
+
829
+ def _iqvsa_parse_module_config(text):
830
+ """Parse the SCPI-style ``<ModuleConfiguration>`` block into a dict.
831
+ Lines look like ``FREQuency:CENTer 2.412000e+09;`` — keep the key as
832
+ written and try to coerce the value to float, else keep the string."""
833
+ out = {}
834
+ for raw in (text or "").splitlines():
835
+ line = raw.strip().rstrip(';').strip()
836
+ if not line or ';' in line and line.endswith(';'):
837
+ line = line.rstrip(';').strip()
838
+ if not line or line.endswith(';') or ' ' not in line:
839
+ continue
840
+ key, _, val = line.partition(' ')
841
+ val = val.strip()
842
+ try:
843
+ out[key] = float(val)
844
+ except ValueError:
845
+ out[key] = val
846
+ return out
847
+
848
+
849
+ def read_iqvsa(fname):
850
+ """Parse a LitePoint ``.iqvsa`` IQ capture into a pandas DataFrame.
851
+
852
+ Columns: ``time`` (s), ``I (V)``, ``Q (V)``, ``mag (V)``. Header
853
+ metadata is stashed in ``df.attrs['cicwave_iqvsa']`` (sample rate,
854
+ center frequency, sample count, raw XML header, parsed SCPI config).
855
+
856
+ Only the v0.3 ``DataFormat=IQ`` / float32 layout we have a sample of
857
+ is supported; other variants raise ``ValueError``.
858
+ """
859
+ import xml.etree.ElementTree as ET
860
+
861
+ with open(fname, 'rb') as fh:
862
+ head = fh.read(_IQVSA_HEADER_SCAN_LIMIT)
863
+ idx = head.find(_IQVSA_HEADER_END)
864
+ if idx < 0:
865
+ raise ValueError(
866
+ "iqvsa: no </LPHeader> found in first %d bytes of %s"
867
+ % (_IQVSA_HEADER_SCAN_LIMIT, fname))
868
+ header_end = idx + len(_IQVSA_HEADER_END)
869
+ header_xml = head[:header_end].decode('ascii', errors='replace')
870
+ fh.seek(header_end)
871
+ payload = fh.read()
872
+
873
+ try:
874
+ root = ET.fromstring(header_xml)
875
+ except ET.ParseError as e:
876
+ raise ValueError("iqvsa: malformed XML header in %s: %s" % (fname, e))
877
+
878
+ def _txt(path, default=None):
879
+ node = root.find(path)
880
+ return node.text.strip() if node is not None and node.text else default
881
+
882
+ fmt = _txt('General/DataFormat', 'IQ')
883
+ if fmt.upper() != 'IQ':
884
+ raise ValueError("iqvsa: unsupported DataFormat=%r (only 'IQ')" % fmt)
885
+
886
+ try:
887
+ fs = float(_txt('DataInfo/SamplingRate'))
888
+ n_declared = int(_txt('DataInfo/SampleCount'))
889
+ except (TypeError, ValueError) as e:
890
+ raise ValueError("iqvsa: missing/bad SamplingRate or SampleCount in %s"
891
+ % fname) from e
892
+
893
+ #- Format inference: payload should be n_declared * 2 * itemsize bytes.
894
+ #- We only know float32 for sure; sniff but require an exact match.
895
+ bytes_per_pair = len(payload) // n_declared if n_declared else 0
896
+ if bytes_per_pair == 8 and len(payload) == n_declared * 8:
897
+ iq = np.frombuffer(payload, dtype='<f4').reshape(-1, 2)
898
+ elif bytes_per_pair == 4 and len(payload) == n_declared * 4:
899
+ #- int16 IQ — not seen in the wild yet, but plausible. Treat as
900
+ #- raw counts; downstream can scale.
901
+ iq = np.frombuffer(payload, dtype='<i2').reshape(-1, 2).astype(
902
+ np.float32)
903
+ else:
904
+ raise ValueError(
905
+ "iqvsa: payload size %d does not match SampleCount=%d for "
906
+ "float32 (%d) or int16 (%d) IQ in %s"
907
+ % (len(payload), n_declared, n_declared * 8, n_declared * 4,
908
+ fname))
909
+
910
+ I = iq[:, 0]
911
+ Q = iq[:, 1]
912
+ n = I.shape[0]
913
+ t = np.arange(n, dtype=np.float64) / fs
914
+ mag = np.hypot(I, Q)
915
+
916
+ df = pd.DataFrame({
917
+ 'time': t,
918
+ 'I (V)': I,
919
+ 'Q (V)': Q,
920
+ 'mag (V)': mag,
921
+ })
922
+
923
+ cfg_text = _txt('ModuleConfiguration', '')
924
+ cfg = _iqvsa_parse_module_config(cfg_text)
925
+ df.attrs['cicwave_iqvsa'] = {
926
+ 'sampling_rate_hz': fs,
927
+ 'sample_count': n,
928
+ 'center_freq_hz': cfg.get('FREQuency:CENTer'),
929
+ 'capture_time_s': cfg.get('CAPTure:TIME'),
930
+ 'idn': _txt('General/IDN'),
931
+ 'datetime': _txt('General/DateTime'),
932
+ 'header_xml': header_xml,
933
+ 'config': cfg,
934
+ }
935
+ return df