Coverage for src/tracekit/__init_

1"""TraceKit - Signal analysis framework for oscilloscope and logic analyzer data.

3TraceKit provides comprehensive tools for:

4- Waveform analysis (rise/fall time, frequency, amplitude)

5- Digital signal analysis (edge detection, clock recovery)

6- Spectral analysis (FFT, PSD, THD, SNR, SINAD, ENOB)

7- Protocol decoding (UART, SPI, I2C, CAN, 1-Wire, and more)

8- Signal filtering (IIR, FIR, Butterworth, Chebyshev, Bessel, Elliptic)

9- Triggering (edge, pattern, pulse width, glitch, runt, window)

10- Power analysis (AC/DC, switching, SOA, efficiency, ripple)

11- Arithmetic operations (add, subtract, differentiate, integrate)

12- Comparison and limit testing (golden waveform, mask testing)

13- Component analysis (TDR, impedance, capacitance, inductance)

14- Statistical analysis and distribution metrics

15- Memory management and large file handling

16- Professional report generation

17- EMC compliance testing

18- Session management

19- Data visualization and export

21Example:

22 >>> import tracekit as tk

23 >>> trace = tk.load("capture.wfm")

24 >>> print(f"Rise time: {tk.rise_time(trace):.2e} s")

25 >>> freq, mag = tk.fft(trace)

26 >>> print(f"THD: {tk.thd(trace):.1f} dB")

27 >>> # Filtering

28 >>> filtered = tk.low_pass(trace, cutoff=1e6)

29 >>> # Power analysis

30 >>> power = tk.instantaneous_power(v_trace, i_trace)

31 >>> # Math operations

32 >>> combined = tk.add(trace1, trace2)

33 >>> derivative = tk.differentiate(trace)

34 >>> # Session management

35 >>> session = tk.Session()

36 >>> session.load_trace('capture.wfm')

37 >>> session.annotate(time=1.5e-6, text='Glitch')

38 >>> session.save('debug_session.tks')

39 >>> # Multi-channel loading

40 >>> channels = tk.load_all_channels("multi_ch.wfm")

41 >>> for name, ch_trace in channels.items():

42 ... print(f"{name}: {len(ch_trace.data)} samples")

44For more information, see https://github.com/lair-click-bats/tracekit

45"""

47__version__ = "0.2.0"

48__author__ = "lair-click-bats"

50# Core types

51# Digital analysis (top-level convenience access)

52from tracekit.analyzers.digital.extraction import (

53 LOGIC_FAMILIES,

54 detect_edges,

55 to_digital,

56)

58# Signal quality analysis (QUAL-001, QUAL-002, QUAL-005, QUAL-006, QUAL-007)

59from tracekit.analyzers.digital.quality import (

60 Glitch,

61 MaskTestResult,

62 NoiseMarginResult,

63 PLLRecoveryResult,

64 Violation,

65 detect_glitches,

66 detect_violations,

67 noise_margin,

68 pll_clock_recovery,

69 signal_quality_summary,

70)

71from tracekit.analyzers.power.ac_power import (

72 apparent_power,

73 power_factor,

74 reactive_power,

75)

77# Power analysis (top-level convenience access)

78from tracekit.analyzers.power.basic import (

79 average_power,

80 energy,

81 instantaneous_power,

82 power_statistics,

83)

84from tracekit.analyzers.power.efficiency import (

85 efficiency,

86)

87from tracekit.analyzers.power.ripple import (

88 ripple,

89 ripple_statistics,

90)

92# Protocol decoders (top-level convenience access)

93from tracekit.analyzers.protocols import (

94 decode_can,

95 decode_can_fd,

96 decode_flexray,

97 decode_hdlc,

98 decode_i2c,

99 decode_i2s,

100 decode_jtag,

101 decode_lin,

102 decode_manchester,

103 decode_onewire,

104 decode_spi,

105 decode_swd,

106 decode_uart,

107 decode_usb,

108)

109

110# Statistics (top-level convenience access)

111from tracekit.analyzers.statistics.basic import (

112 basic_stats,

113 percentiles,

114 quartiles,

115)

116from tracekit.analyzers.statistics.distribution import (

117 distribution_metrics,

118 histogram,

119)

120

121# Waveform measurements (top-level convenience access)

122from tracekit.analyzers.waveform.measurements import (

123 amplitude,

124 duty_cycle,

125 fall_time,

126 frequency,

127 mean,

128 measure,

129 overshoot,

130 period,

131 preshoot,

132 pulse_width,

133 rise_time,

134 rms,

135 undershoot,

136)

137

138# Convenience aliases

139vpp = amplitude # Vpp (peak-to-peak voltage) is a common oscilloscope term

140

141# Spectral analysis (top-level convenience access)

142from tracekit.analyzers.waveform.spectral import (

143 enob,

144 fft,

145 psd,

146 sfdr,

147 sinad,

148 snr,

149 spectrogram,

150 thd,

151)

152

153# Comparison and limit testing

154from tracekit.comparison.compare import (

155 compare_traces,

156 correlation,

157 difference,

158 similarity_score,

159)

160from tracekit.comparison.golden import (

161 GoldenReference,

162 compare_to_golden,

163 create_golden,

164)

165from tracekit.comparison.limits import (

166 LimitSpec,

167 check_limits,

168 create_limit_spec,

169 margin_analysis,

170)

171from tracekit.comparison.mask import (

172 Mask,

173 create_mask,

174 eye_mask,

175 mask_test,

176)

177

178# EMC Compliance (EMC-001, EMC-002, EMC-003)

179from tracekit.compliance import (

180 AVAILABLE_MASKS,

181 ComplianceReportFormat,

182 ComplianceResult,

183 ComplianceViolation,

184 DetectorType,

185 LimitMask,

186 check_compliance,

187 create_custom_mask,

188 generate_compliance_report,

189 load_limit_mask,

190)

191

192# Component analysis

193from tracekit.component.impedance import (

194 discontinuity_analysis,

195 extract_impedance,

196 impedance_profile,

197)

198from tracekit.component.reactive import (

199 extract_parasitics,

200 measure_capacitance,

201 measure_inductance,

202)

203from tracekit.component.transmission_line import (

204 characteristic_impedance,

205 propagation_delay,

206 transmission_line_analysis,

207 velocity_factor,

208)

209

210# Audit trail (LOG-009)

211from tracekit.core.audit import (

212 AuditEntry,

213 AuditTrail,

214 get_global_audit_trail,

215 record_audit,

216)

217

218# Configuration

219from tracekit.core.config import (

220 DEFAULT_CONFIG,

221 SmartDefaults,

222 get_config_value,

223 load_config,

224 save_config,

225 validate_config,

226)

227

228# Exceptions - import from core.exceptions (the enhanced version)

229from tracekit.core.exceptions import (

230 AnalysisError,

231 ConfigurationError,

232 ExportError,

233 FormatError,

234 InsufficientDataError,

235 LoaderError,

236 SampleRateError,

237 TraceKitError,

238 UnsupportedFormatError,

239 ValidationError,

240)

241

242# Logging

243from tracekit.core.logging import (

244 configure_logging,

245 get_logger,

246 set_log_level,

247)

248

249# Performance timing

250from tracekit.core.performance import timed

251

252# Expert API - Results (API-005)

253from tracekit.core.results import (

254 AnalysisResult,

255 FFTResult,

256 FilterResult,

257 MeasurementResult,

258 WaveletResult,

259)

260from tracekit.core.types import (

261 DigitalTrace,

262 ProtocolPacket,

263 Trace,

264 TraceMetadata,

265 WaveformTrace,

266)

267

268# Data Export (top-level convenience access)

269from tracekit.exporters import (

270 export_csv,

271 export_hdf5,

272 export_json,

273 export_mat,

274)

275

276# Expert API - Extensibility (API-006, API-007, API-008, PLUG-008)

277from tracekit.extensibility import (

278 AlgorithmRegistry,

279 MeasurementDefinition,

280 MeasurementRegistry,

281 PluginError,

282 PluginManager,

283 PluginMetadata,

284 PluginTemplate,

285 PluginType,

286 generate_plugin_template,

287 get_algorithm,

288 get_algorithms,

289 get_measurement_registry,

290 get_plugin_manager,

291 list_measurements,

292 list_plugins,

293 load_plugin,

294 register_algorithm,

295 register_measurement,

296)

297from tracekit.extensibility import (

298 measure as measure_custom,

299)

300

301# Filtering (top-level convenience access)

302from tracekit.filtering.convenience import (

303 band_pass,

304 band_stop,

305 high_pass,

306 low_pass,

307 median_filter,

308 moving_average,

309 notch_filter,

310 savgol_filter,

311)

312from tracekit.filtering.design import (

313 BandPassFilter,

314 BandStopFilter,

315 HighPassFilter,

316 LowPassFilter,

317 design_filter,

318)

319

320# Auto-Inference (INF-001 to INF-009)

321from tracekit.inference import (

322 AnalysisRecommendation,

323 assess_signal_quality,

324 auto_spectral_config,

325 check_measurement_suitability,

326 classify_signal,

327 detect_logic_family,

328 detect_protocol,

329 get_optimal_domain_order,

330 recommend_analyses,

331 suggest_measurements,

332)

333

334# Loaders (including multi-channel support)

335from tracekit.loaders import get_supported_formats, load, load_all_channels

336

337# Math/arithmetic operations (top-level convenience access)

338from tracekit.math.arithmetic import (

339 absolute,

340 add,

341 differentiate,

342 divide,

343 integrate,

344 invert,

345 math_expression,

346 multiply,

347 offset,

348 scale,

349 subtract,

350)

351from tracekit.math.interpolation import (

352 align_traces,

353 downsample,

354 interpolate,

355 resample,

356)

357

358# Expert API - Pipeline and Composition (API-001, API-002, API-004)

359from tracekit.pipeline import (

360 Composable,

361 Pipeline,

362 TraceTransformer,

363 compose,

364 curry,

365 make_composable,

366 pipe,

367)

368

369# Reporting

370from tracekit.reporting.core import (

371 Report,

372 ReportConfig,

373 generate_report,

374)

375from tracekit.reporting.formatting import (

376 NumberFormatter,

377 format_value,

378 format_with_context,

379 format_with_units,

380)

381

382# Session Management (SESS-001, SESS-002, SESS-003)

383from tracekit.session import (

384 Annotation,

385 AnnotationLayer,

386 AnnotationType,

387 HistoryEntry,

388 OperationHistory,

389 Session,

390 load_session,

391)

392

393# Expert API - Streaming (API-003)

394from tracekit.streaming import (

395 StreamingAnalyzer,

396 load_trace_chunks,

397)

398

399# Triggering (top-level convenience access)

400from tracekit.triggering import (

401 EdgeTrigger,

402 PulseWidthTrigger,

403 find_falling_edges,

404 find_glitches,

405 find_pulses,

406 find_rising_edges,

407 find_runt_pulses,

408 find_triggers,

409)

410

411# Memory management

412from tracekit.utils.memory import (

413 MemoryCheckError,

414 check_memory_available,

415 estimate_memory,

416 get_available_memory,

417 get_memory_pressure,

418 get_total_memory,

419)

420

421# Visualization (top-level convenience access)

422from tracekit.visualization import (

423 plot_fft,

424 plot_spectrum,

425 plot_waveform,

426)

427

428# Workflows (WRK-001 to WRK-005)

429from tracekit.workflows import (

430 characterize_buffer,

431 debug_protocol,

432 emc_compliance_test,

433 power_analysis,

434 signal_integrity_audit,

435)

436

437__all__ = [

438 # EMC Compliance (EMC-001, EMC-002, EMC-003)

439 "AVAILABLE_MASKS",

440 "DEFAULT_CONFIG",

441 "LOGIC_FAMILIES",

442 # Expert API - Extensibility (API-006, API-007, API-008)

443 "AlgorithmRegistry",

444 "AnalysisError",

445 # Auto-Inference (INF-009)

446 "AnalysisRecommendation",

447 # Expert API - Results (API-005)

448 "AnalysisResult",

449 # Session Management (SESS-002)

450 "Annotation",

451 "AnnotationLayer",

452 "AnnotationType",

453 # Audit trail (LOG-009)

454 "AuditEntry",

455 "AuditTrail",

456 "BandPassFilter",

457 "BandStopFilter",

458 "ComplianceReportFormat",

459 "ComplianceResult",

460 "ComplianceViolation",

461 "Composable",

462 "ConfigurationError",

463 "DetectorType",

464 "DigitalTrace",

465 "EdgeTrigger",

466 "ExportError",

467 "FFTResult",

468 "FilterResult",

469 "FormatError",

470 # Signal quality (QUAL-005)

471 "Glitch",

472 "GoldenReference",

473 "HighPassFilter",

474 # Session Management (SESS-003)

475 "HistoryEntry",

476 "InsufficientDataError",

477 "LimitMask",

478 "LimitSpec",

479 "LoaderError",

480 "LowPassFilter",

481 "Mask",

482 # Signal quality (QUAL-006)

483 "MaskTestResult",

484 "MeasurementDefinition",

485 "MeasurementRegistry",

486 "MeasurementResult",

487 "MemoryCheckError",

488 # Signal quality (QUAL-001)

489 "NoiseMarginResult",

490 "NumberFormatter",

491 "OperationHistory",

492 # Signal quality (QUAL-007)

493 "PLLRecoveryResult",

494 # Expert API - Pipeline (API-001, API-002, API-004)

495 "Pipeline",

496 "PluginError",

497 "PluginManager",

498 "PluginMetadata",

499 "PluginTemplate",

500 "PluginType",

501 "ProtocolPacket",

502 "PulseWidthTrigger",

503 # Reporting

504 "Report",

505 "ReportConfig",

506 "SampleRateError",

507 # Session Management (SESS-001)

508 "Session",

509 "SmartDefaults",

510 "StreamingAnalyzer",

511 "Trace",

512 # Exceptions

513 "TraceKitError",

514 # Core types

515 "TraceMetadata",

516 "TraceTransformer",

517 "UnsupportedFormatError",

518 "ValidationError",

519 # Signal quality (QUAL-002)

520 "Violation",

521 "WaveformTrace",

522 "WaveletResult",

523 # Version

524 "__version__",

525 "absolute",

526 # Math operations

527 "add",

528 "align_traces",

529 "amplitude",

530 "apparent_power",

531 "assess_signal_quality",

532 "auto_spectral_config",

533 "average_power",

534 "band_pass",

535 "band_stop",

536 # Statistics

537 "basic_stats",

538 "characteristic_impedance",

539 # Workflows (WRK-001 to WRK-005)

540 "characterize_buffer",

541 "check_compliance",

542 "check_limits",

543 "check_measurement_suitability",

544 "check_memory_available",

545 "classify_signal",

546 "compare_to_golden",

547 # Comparison

548 "compare_traces",

549 "compose",

550 # Logging

551 "configure_logging",

552 "correlation",

553 "create_custom_mask",

554 "create_golden",

555 "create_limit_spec",

556 "create_mask",

557 "curry",

558 "debug_protocol",

559 # Protocol decoders

560 "decode_can",

561 "decode_can_fd",

562 "decode_flexray",

563 "decode_hdlc",

564 "decode_i2c",

565 "decode_i2s",

566 "decode_jtag",

567 "decode_lin",

568 "decode_manchester",

569 "decode_onewire",

570 "decode_spi",

571 "decode_swd",

572 "decode_uart",

573 "decode_usb",

574 "design_filter",

575 "detect_edges",

576 # Signal quality (QUAL-005)

577 "detect_glitches",

578 # Auto-Inference (INF-001 to INF-003)

579 "detect_logic_family",

580 "detect_protocol",

581 # Signal quality (QUAL-002)

582 "detect_violations",

583 "difference",

584 "differentiate",

585 "discontinuity_analysis",

586 "distribution_metrics",

587 "divide",

588 "downsample",

589 "duty_cycle",

590 "efficiency",

591 "emc_compliance_test",

592 "energy",

593 "enob",

594 # Memory management

595 "estimate_memory",

596 # Export functions

597 "export_csv",

598 "export_hdf5",

599 "export_json",

600 "export_mat",

601 # Component analysis

602 "extract_impedance",

603 "extract_parasitics",

604 "eye_mask",

605 "fall_time",

606 # Spectral analysis

607 "fft",

608 "find_falling_edges",

609 "find_glitches",

610 "find_pulses",

611 "find_rising_edges",

612 "find_runt_pulses",

613 # Triggering

614 "find_triggers",

615 "format_value",

616 "format_with_context",

617 "format_with_units",

618 "frequency",

619 "generate_compliance_report",

620 "generate_plugin_template",

621 "generate_report",

622 "get_algorithm",

623 "get_algorithms",

624 "get_available_memory",

625 "get_config_value",

626 "get_global_audit_trail",

627 "get_logger",

628 "get_measurement_registry",

629 "get_memory_pressure",

630 # Auto-Inference (INF-009)

631 "get_optimal_domain_order",

632 "get_plugin_manager",

633 "get_supported_formats",

634 "get_total_memory",

635 "high_pass",

636 "histogram",

637 "impedance_profile",

638 # Power analysis

639 "instantaneous_power",

640 "integrate",

641 "interpolate",

642 "invert",

643 "list_measurements",

644 "list_plugins",

645 # Loaders

646 "load",

647 # Multi-channel loading (Phase 3)

648 "load_all_channels",

649 # Configuration

650 "load_config",

651 "load_limit_mask",

652 "load_plugin",

653 # Session Management

654 "load_session",

655 # Expert API - Streaming (API-003)

656 "load_trace_chunks",

657 # Filtering

658 "low_pass",

659 "make_composable",

660 "margin_analysis",

661 "mask_test",

662 "math_expression",

663 "mean",

664 "measure",

665 "measure_capacitance",

666 "measure_custom",

667 "measure_inductance",

668 "median_filter",

669 "moving_average",

670 "multiply",

671 # Signal quality (QUAL-001)

672 "noise_margin",

673 "notch_filter",

674 "offset",

675 "overshoot",

676 "percentiles",

677 "period",

678 "pipe",

679 # Signal quality (QUAL-007)

680 "pll_clock_recovery",

681 # Visualization

682 "plot_fft",

683 "plot_spectrum",

684 "plot_waveform",

685 "power_analysis",

686 "power_factor",

687 "power_statistics",

688 "preshoot",

689 "propagation_delay",

690 "psd",

691 "pulse_width",

692 "quartiles",

693 "reactive_power",

694 # Auto-Inference (INF-009)

695 "recommend_analyses",

696 "record_audit",

697 "register_algorithm",

698 "register_measurement",

699 "resample",

700 "ripple",

701 "ripple_statistics",

702 # Waveform measurements

703 "rise_time",

704 "rms",

705 "save_config",

706 "savgol_filter",

707 "scale",

708 "set_log_level",

709 "sfdr",

710 "signal_integrity_audit",

711 # Signal quality summary

712 "signal_quality_summary",

713 "similarity_score",

714 "sinad",

715 "snr",

716 "spectrogram",

717 "subtract",

718 "suggest_measurements",

719 "thd",

720 "timed",

721 # Digital analysis

722 "to_digital",

723 "transmission_line_analysis",

724 "undershoot",

725 "validate_config",

726 "velocity_factor",

727 "vpp",

728]

Coverage for src / tracekit / init.py: 100%

48 statements