Metadata-Version: 2.4
Name: tracekit
Version: 0.1.0
Summary: Signal analysis framework for oscilloscope and logic analyzer data
Project-URL: Repository, https://github.com/lair-click-bats/tracekit
License-Expression: MIT
License-File: LICENSE
Keywords: logic-analyzer,oscilloscope,protocol-decoder,signal-analysis,waveform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: bokeh>=3.8.1
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=6.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.4.7
Requires-Dist: scapy>=2.6.1
Requires-Dist: scipy>=1.10.0
Requires-Dist: tm-data-types>=0.3.0
Provides-Extra: all
Requires-Dist: check-jsonschema>=0.29.0; extra == 'all'
Requires-Dist: h5py>=3.0.0; extra == 'all'
Requires-Dist: ipython>=8.0.0; extra == 'all'
Requires-Dist: jupyter>=1.0.0; extra == 'all'
Requires-Dist: pytest-cov>=6.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: python-pptx>=0.6.21; extra == 'all'
Requires-Dist: reportlab>=4.0.0; extra == 'all'
Requires-Dist: types-pyyaml>=6.0; extra == 'all'
Requires-Dist: yamllint>=1.35; extra == 'all'
Provides-Extra: dev
Requires-Dist: check-jsonschema>=0.29.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: yamllint>=1.35; extra == 'dev'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.0.0; extra == 'hdf5'
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0.0; extra == 'jupyter'
Requires-Dist: jupyter>=1.0.0; extra == 'jupyter'
Provides-Extra: reporting
Requires-Dist: python-pptx>=0.6.21; extra == 'reporting'
Requires-Dist: reportlab>=4.0.0; extra == 'reporting'
Description-Content-Type: text/markdown

# TraceKit

A comprehensive signal analysis framework for oscilloscope and logic analyzer data.

## Features

### Waveform Analysis

- Rise/fall time measurements (IEEE 181-2011)
- Period, frequency, duty cycle
- Amplitude measurements (Vpp, Vmax, Vmin, RMS)
- Overshoot/undershoot detection

### Digital Analysis

- Threshold-based digital extraction
- Edge detection with sub-sample interpolation
- Clock recovery (FFT and edge-based methods)
- Glitch detection

### Spectral Analysis

- FFT with configurable windowing
- Power Spectral Density (Welch method)
- THD, SNR, SINAD, ENOB calculations
- Spectrogram generation
- Wavelet transforms (CWT, DWT)

### Protocol Decoding

- UART, SPI, I2C, CAN, CAN-FD
- 1-Wire, LIN, JTAG, SWD
- I2S, USB, HDLC
- Manchester encoding
- FlexRay, DMX512, SENT

### Exploratory Analysis

- Unknown signal field detection and entropy analysis
- Legacy multi-family logic level detection
- Fuzzy pattern matching with Hamming distance tolerance
- Error-tolerant DAQ packet parsing and recovery

### File Format Support

- Tektronix WFM/ISF
- Rigol WFM
- Sigrok/PulseView
- VCD (Value Change Dump)
- PCAP
- TDMS
- WAV
- CSV, HDF5, NPZ

## Production Readiness

**Current Version:** v0.1.0 (Release Candidate)

TraceKit is a mature, fully-featured signal analysis framework currently in release candidate status. Version 1.0.0 release is pending final validation.

### All Domains Production Ready

| Domain                | Status | Features                                           |
| --------------------- | ------ | -------------------------------------------------- |
| **Core Analysis**     | 100%   | Waveform, timing, digital signal analysis          |
| **Spectral**          | 100%   | FFT, PSD, THD, harmonics, wavelets                 |
| **Statistics**        | 100%   | Descriptive stats, distributions, correlation      |
| **Protocol Decoders** | 100%   | 16 protocols with auto-detection                   |
| **Power Analysis**    | 100%   | IEEE 1459, IEC 61000-4-7 compliance                |
| **Data Loading**      | 100%   | Multi-format support (10+ formats)                 |
| **Export**            | 100%   | CSV, JSON, VCD, WAV, Parquet, Excel, PowerPoint    |
| **Memory Management** | 100%   | Chunked processing, streaming, caching, memory map |
| **Logging**           | 100%   | Structured, rotation, compression, batch metrics   |
| **Reporting**         | 100%   | Templates, inheritance, multi-format export        |
| **Visualization**     | 100%   | Accessibility, interactive, specialized plots      |
| **Configuration**     | 100%   | Schema validation, migration, hot reload           |
| **Plugins**           | 100%   | Discovery, registration, sandboxed execution       |
| **Expert API**        | 100%   | Fluent interface, operators, DSL                   |
| **Auto-Discovery**    | 100%   | Format detection, protocol inference               |
| **Exploratory**       | 100%   | Unknown signals, legacy analysis, fuzzy matching   |
| **Accessibility**     | 100%   | Colorblind-safe palettes, alt-text, keyboard nav   |

### v1.0.0 Release Highlights

- **16 Protocol Decoders** - UART, SPI, I2C, CAN, CAN-FD, 1-Wire, LIN, JTAG, SWD, I2S, USB, HDLC, Manchester, FlexRay, DMX512, SENT
- **Exploratory Analysis** - Unknown signal detection, legacy multi-family analysis, fuzzy pattern matching, error-tolerant DAQ
- **Accessibility Features** - Colorblind-safe visualization, alt-text generation, keyboard navigation
- **Report Templates** - 6 built-in templates with inheritance and customization
- **Batch Metrics** - Performance tracking with JSON/CSV export
- **Time-based Logging** - Rotation with compression and retention policies

## Installation

```bash
# Using uv (recommended)
uv pip install tracekit

# Or from source
git clone https://github.com/lair-click-bats/tracekit.git
cd tracekit
uv pip install -e ".[dev]"
```

## Quick Start

```python
import tracekit as tk

# Load waveform data
trace = tk.load("oscilloscope_capture.wfm")

# Basic measurements
print(f"Rise time: {tk.rise_time(trace):.2e} s")
print(f"Frequency: {tk.frequency(trace):.2f} Hz")
print(f"Vpp: {tk.vpp(trace):.3f} V")

# Spectral analysis
spectrum = tk.fft(trace, window="hann")
thd = tk.thd(trace)
snr = tk.snr(trace)

# Protocol decoding
uart_packets = tk.decode_uart(trace, baudrate=115200)
spi_frames = tk.decode_spi(trace, clock_pin=0, mosi_pin=1, miso_pin=2)

# Visualization
tk.plot_waveform(trace)
tk.plot_spectrum(spectrum)
tk.plot_eye_diagram(trace)
```

### Exploratory Analysis

```python
from tracekit.exploratory import unknown, legacy, fuzzy

# Analyze unknown binary signal
result = unknown.detect_binary_fields(data)
print(f"Detected {len(result.fields)} fields")

# Multi-family logic level detection
families = legacy.detect_logic_families_multi_channel(channels)
for family in families:
    print(f"Channel {family.channel}: {family.logic_family}")

# Fuzzy pattern matching with bit errors
from tracekit.exploratory.sync import fuzzy_sync_search
matches = fuzzy_sync_search(data, pattern=0xAA55, max_errors=2)
```

### Time-based Log Rotation

```python
from tracekit.core.logging import configure_logging

# Daily rotation with compression and 30-day retention
configure_logging(handlers={
    "file": {
        "filename": "analysis.log",
        "when": "midnight",
        "backup_count": 30,
        "compress": True,
        "max_age": "30d"
    }
})
```

### Report Templates

```python
from tracekit.reporting.template_system import (
    load_template, extend_template, register_template, TemplateSection
)

# Use built-in template
template = load_template("compliance")

# Create custom template
custom = extend_template(
    "compliance",
    name="FDA Compliance",
    add_sections=[TemplateSection(title="FDA Requirements", order=25)]
)
register_template("fda_compliance", custom)
```

### Batch Job Metrics

```python
from tracekit.batch.metrics import BatchMetrics

metrics = BatchMetrics(batch_id="analysis-001")
metrics.start()

for file in files:
    # ... process file ...
    metrics.record_file(file, duration=0.5, samples=100000)

metrics.finish()
summary = metrics.summary()
metrics.export_json("metrics.json")
```

### Accessibility

```python
from tracekit.visualization.accessibility import (
    get_colorblind_palette,
    generate_alt_text,
    KeyboardHandler
)

# Use colorblind-safe palette
palette = get_colorblind_palette("viridis")

# Generate alt-text for accessibility
alt_text = generate_alt_text(signal, "waveform", title="Clock Signal")

# Enable keyboard navigation
handler = KeyboardHandler(fig, ax)
handler.enable()
```

## Development

```bash
# Clone and install
git clone https://github.com/lair-click-bats/tracekit.git
cd tracekit
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Lint and format
uv run ruff check src/
uv run ruff format src/

# Type check
uv run mypy src/
```

## Testing

> **⚠️ IMPORTANT**: If you encountered terminal crashes when running tests, this has been fixed! See [docs/TESTING_CRASH_FIX.md](docs/TESTING_CRASH_FIX.md) for details.

TraceKit includes a comprehensive test suite:

- 16,690+ unit and integration tests
- IEEE/JEDEC compliance tests
- Performance benchmarks
- Full test coverage for all critical functionality

### Running Tests

```bash
# Run all tests
uv run pytest tests/unit

# Run with coverage
uv run pytest tests/unit --cov=src/tracekit --cov-report=term

# Run in parallel (safe after fix)
uv run pytest tests/unit -n 4
```

**See**: [docs/TESTING_GUIDELINES.md](docs/TESTING_GUIDELINES.md) for comprehensive testing guide.

## Standards Compliance

- IEEE 181-2011: Pulse measurements
- IEEE 1057-2017: Digitizer characterization
- IEEE 1241-2010: ADC testing
- IEEE 1149.1: JTAG
- IEEE 1459: Power measurements
- IEEE 2414-2020: Jitter measurements
- IEC 61000-4-7: Power quality
- JEDEC: Setup/hold timing
- RFC 3550: RTP packet timing

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! When contributing:

1. Follow the existing code style (use `ruff format`)
2. Include tests for all new functionality
3. Ensure all tests pass (`pytest`)
4. Add type hints and docstrings
5. Submit a pull request with a clear description
