adctoolbox 0.1.0__tar.gz

adctoolbox-0.1.0/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2025 Zhishuai Zhang, Lu Jie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+CITATION NOTICE
+
+If you use this software in academic research or publications, please cite:
+
+Zhishuai Zhang, Lu Jie, "ADCToolbox: A comprehensive toolbox for ADC testing
+and characterization"
+
+BibTeX:
+@software{adctoolbox2025,
+  author = {Zhang, Zhishuai and Jie, Lu},
+  title = {ADCToolbox: A comprehensive toolbox for ADC testing and characterization},
+  year = {2025},
+  url = {https://github.com/yourusername/ADCToolbox}
+}

adctoolbox-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: adctoolbox
+Version: 0.1.0
+Summary: A comprehensive toolbox for ADC testing and characterization
+Author: Zhishuai Zhang, Lu Jie
+License: MIT
+Project-URL: Homepage, https://github.com/Arcadia-1/ADCToolbox
+Project-URL: Documentation, https://github.com/Arcadia-1/ADCToolbox#readme
+Project-URL: Repository, https://github.com/Arcadia-1/ADCToolbox
+Project-URL: Issues, https://github.com/Arcadia-1/ADCToolbox/issues
+Keywords: ADC,analog-to-digital,converter,testing,characterization,signal-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: pandas>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# ADCToolbox
+
+A comprehensive Python toolbox for **ADC (Analog-to-Digital Converter)** characterization and analysis.
+
+Delivers clear **multi-angle diagnostic views** of ADC behavior, enabling deeper insight and faster issue location.
+
+## Features
+
+- **Spectrum Analysis**: ENOB, SNDR, SFDR, SNR, THD, Noise Floor
+- **Error Analysis**: PDF, Autocorrelation, Envelope Spectrum, Histogram Analysis
+- **Jitter Detection**: Amplitude vs Phase Noise Decomposition
+- **Calibration**: Foreground Calibration for SAR/Pipeline ADCs
+- **INL/DNL Extraction**: Histogram-based nonlinearity analysis
+- **100% MATLAB Parity**: Validated against reference MATLAB implementation
+
+---
+
+## Installation
+
+```bash
+pip install adctoolbox
+```
+
+or (recommended)
+
+```bash
+uv pip install adctoolbox
+```
+
+**Requirements**: Python >= 3.8, numpy, scipy, matplotlib, pandas
+
+---
+
+## Quick Start
+
+### Spectrum Analysis
+
+```python
+from adctoolbox.aout import spec_plot
+import numpy as np
+
+# Load ADC output data
+data = np.loadtxt("adc_output.csv", delimiter=',')
+
+# Analyze spectrum and get performance metrics
+ENoB, SNDR, SFDR, SNR, THD, pwr, NF, _ = spec_plot(data)
+
+print(f"ENOB: {ENoB:.2f} bits")
+print(f"SNDR: {SNDR:.2f} dB")
+print(f"SFDR: {SFDR:.2f} dB")
+```
+
+### Sine Wave Fitting
+
+```python
+from adctoolbox.common import sine_fit
+
+# Fit sine wave and extract parameters
+data_fit, freq, mag, dc, phi = sine_fit(data)
+err = data - data_fit
+
+print(f"Frequency: {freq:.6f}")
+print(f"Magnitude: {mag:.4f}")
+print(f"DC offset: {dc:.4f}")
+print(f"Phase: {phi:.2f} deg")
+```
+
+### Jitter Analysis
+
+```python
+from adctoolbox.aout import err_hist_sine
+
+# Extract jitter from error histogram
+emean, erms, phase, anoi, pnoi, err, xx = err_hist_sine(
+    data, bin=99, fin=freq, disp=0
+)
+
+# Calculate jitter RMS (assuming input frequency Fin in Hz)
+jitter_rms = pnoi / (2 * np.pi * Fin)
+print(f"Jitter RMS: {jitter_rms*1e15:.2f} fs")
+```
+
+### Error PDF Analysis
+
+```python
+from adctoolbox.aout import err_pdf
+
+# Analyze error distribution
+noise_lsb, mu, sigma, KL_div, x, fx, gauss = err_pdf(err)
+
+print(f"Noise RMS: {noise_lsb:.4f} LSB")
+print(f"Mean: {mu:.4f} LSB")
+print(f"Std Dev: {sigma:.4f} LSB")
+print(f"KL Divergence: {KL_div:.4f}")
+```
+
+### INL/DNL Extraction
+
+```python
+from adctoolbox.aout import inl_sine
+
+# Extract INL and DNL from sine histogram
+INL, DNL, code = inl_sine(data)
+
+print(f"Max INL: {np.max(np.abs(INL)):.4f} LSB")
+print(f"Max DNL: {np.max(np.abs(DNL)):.4f} LSB")
+```
+
+---
+
+## Available Tools
+
+### Spectrum Analysis (`adctoolbox.aout`)
+- **`spec_plot`** - FFT spectrum with ENOB, SNDR, SFDR, SNR, THD, noise floor
+- **`spec_plot_phase`** - Phase spectrum with polar plot
+- **`tom_decomp`** - Thompson decomposition (deterministic vs random error)
+
+### Error Analysis (`adctoolbox.aout`)
+- **`err_pdf`** - Error PDF with KDE and Gaussian fitting
+- **`err_hist_sine`** - Histogram-based error analysis with jitter detection
+- **`err_auto_correlation`** - Error autocorrelation function
+- **`err_envelope_spectrum`** - Envelope spectrum via Hilbert transform
+- **`inl_sine`** - INL/DNL extraction from sine histogram
+
+### Common Utilities (`adctoolbox.common`)
+- **`sine_fit`** - Multi-parameter sine fitting with auto frequency search
+- **`find_bin`** - FFT bin finder with sub-bin resolution
+- **`find_fin`** - Input frequency finder
+- **`alias`** - Frequency aliasing calculator
+- **`cap2weight`** - Capacitor array to weight conversion
+
+### Calibration (`adctoolbox.dout`)
+- **`fg_cal_sine`** - Foreground calibration using sinewave
+- **`overflow_chk`** - Overflow detection and validation
+
+### Oversampling (`adctoolbox.oversampling`)
+- **`ntf_analyzer`** - Noise Transfer Function analysis
+
+---
+
+## Package Structure
+
+```
+adctoolbox/
+├── aout/           # Analog output analysis
+├── common/         # Common utilities
+├── dout/           # Digital output calibration
+├── oversampling/   # Oversampling analysis
+└── utils/          # Utility functions
+```
+
+---
+
+## Documentation
+
+- **GitHub Repository**: [https://github.com/Arcadia-1/ADCToolbox](https://github.com/Arcadia-1/ADCToolbox)
+- **Full Documentation**: See GitHub repository for complete guides
+- **API Reference**: Comprehensive docstrings in all modules
+- **Test Suite**: 15 unit tests with 100% MATLAB-Python parity validation
+
+---
+
+## Validation
+
+**Tested against MATLAB reference implementation**:
+- 15 Python unit tests
+- 96 comparison test cases
+- 100% numerical parity achieved
+- Results: 27 PERFECT + 51 EXCELLENT + 13 GOOD + 5 ACCEPTABLE
+
+---
+
+## Example Use Cases
+
+- **ADC Characterization**: Measure ENOB, SNDR, SFDR for performance verification
+- **Jitter Analysis**: Separate amplitude noise from phase noise/jitter
+- **Nonlinearity Testing**: Extract INL/DNL using sine histogram method
+- **Calibration**: Foreground calibration for SAR and pipeline ADCs
+- **Error Diagnosis**: Multi-view error analysis (time, frequency, phase domains)
+- **Research**: ADC algorithm development with validated reference implementation
+
+---
+
+## License
+
+MIT License - See [LICENSE](https://github.com/Arcadia-1/ADCToolbox/blob/main/LICENSE) for details.
+
+## Citation
+
+If you use this toolbox in your research, please cite:
+
+```bibtex
+@software{adctoolbox2025,
+  author = {Zhang, Zhishuai and Jie, Lu},
+  title = {ADCToolbox},
+  year = {2025},
+  url = {https://github.com/Arcadia-1/ADCToolbox}
+}
+```
+
+---
+
+## Authors
+
+Zhishuai Zhang, Lu Jie
+
+---
+
+## Contributing
+
+Contributions welcome! Please visit the [GitHub repository](https://github.com/Arcadia-1/ADCToolbox) for contribution guidelines.
+
+**Development Setup**:
+```bash
+git clone https://github.com/Arcadia-1/ADCToolbox.git
+cd ADCToolbox/python
+pip install -e .[dev]
+python tests/run_all_tests.py
+```
+
+---
+
+## Links
+
+- **GitHub**: [https://github.com/Arcadia-1/ADCToolbox](https://github.com/Arcadia-1/ADCToolbox)
+- **Issues**: [https://github.com/Arcadia-1/ADCToolbox/issues](https://github.com/Arcadia-1/ADCToolbox/issues)
+- **MATLAB Version**: Also available in the same repository

adctoolbox-0.1.0/README.md

@@ -0,0 +1,227 @@
+# ADCToolbox
+
+A comprehensive Python toolbox for **ADC (Analog-to-Digital Converter)** characterization and analysis.
+
+Delivers clear **multi-angle diagnostic views** of ADC behavior, enabling deeper insight and faster issue location.
+
+## Features
+
+- **Spectrum Analysis**: ENOB, SNDR, SFDR, SNR, THD, Noise Floor
+- **Error Analysis**: PDF, Autocorrelation, Envelope Spectrum, Histogram Analysis
+- **Jitter Detection**: Amplitude vs Phase Noise Decomposition
+- **Calibration**: Foreground Calibration for SAR/Pipeline ADCs
+- **INL/DNL Extraction**: Histogram-based nonlinearity analysis
+- **100% MATLAB Parity**: Validated against reference MATLAB implementation
+
+---
+
+## Installation
+
+```bash
+pip install adctoolbox
+```
+
+or (recommended)
+
+```bash
+uv pip install adctoolbox
+```
+
+**Requirements**: Python >= 3.8, numpy, scipy, matplotlib, pandas
+
+---
+
+## Quick Start
+
+### Spectrum Analysis
+
+```python
+from adctoolbox.aout import spec_plot
+import numpy as np
+
+# Load ADC output data
+data = np.loadtxt("adc_output.csv", delimiter=',')
+
+# Analyze spectrum and get performance metrics
+ENoB, SNDR, SFDR, SNR, THD, pwr, NF, _ = spec_plot(data)
+
+print(f"ENOB: {ENoB:.2f} bits")
+print(f"SNDR: {SNDR:.2f} dB")
+print(f"SFDR: {SFDR:.2f} dB")
+```
+
+### Sine Wave Fitting
+
+```python
+from adctoolbox.common import sine_fit
+
+# Fit sine wave and extract parameters
+data_fit, freq, mag, dc, phi = sine_fit(data)
+err = data - data_fit
+
+print(f"Frequency: {freq:.6f}")
+print(f"Magnitude: {mag:.4f}")
+print(f"DC offset: {dc:.4f}")
+print(f"Phase: {phi:.2f} deg")
+```
+
+### Jitter Analysis
+
+```python
+from adctoolbox.aout import err_hist_sine
+
+# Extract jitter from error histogram
+emean, erms, phase, anoi, pnoi, err, xx = err_hist_sine(
+    data, bin=99, fin=freq, disp=0
+)
+
+# Calculate jitter RMS (assuming input frequency Fin in Hz)
+jitter_rms = pnoi / (2 * np.pi * Fin)
+print(f"Jitter RMS: {jitter_rms*1e15:.2f} fs")
+```
+
+### Error PDF Analysis
+
+```python
+from adctoolbox.aout import err_pdf
+
+# Analyze error distribution
+noise_lsb, mu, sigma, KL_div, x, fx, gauss = err_pdf(err)
+
+print(f"Noise RMS: {noise_lsb:.4f} LSB")
+print(f"Mean: {mu:.4f} LSB")
+print(f"Std Dev: {sigma:.4f} LSB")
+print(f"KL Divergence: {KL_div:.4f}")
+```
+
+### INL/DNL Extraction
+
+```python
+from adctoolbox.aout import inl_sine
+
+# Extract INL and DNL from sine histogram
+INL, DNL, code = inl_sine(data)
+
+print(f"Max INL: {np.max(np.abs(INL)):.4f} LSB")
+print(f"Max DNL: {np.max(np.abs(DNL)):.4f} LSB")
+```
+
+---
+
+## Available Tools
+
+### Spectrum Analysis (`adctoolbox.aout`)
+- **`spec_plot`** - FFT spectrum with ENOB, SNDR, SFDR, SNR, THD, noise floor
+- **`spec_plot_phase`** - Phase spectrum with polar plot
+- **`tom_decomp`** - Thompson decomposition (deterministic vs random error)
+
+### Error Analysis (`adctoolbox.aout`)
+- **`err_pdf`** - Error PDF with KDE and Gaussian fitting
+- **`err_hist_sine`** - Histogram-based error analysis with jitter detection
+- **`err_auto_correlation`** - Error autocorrelation function
+- **`err_envelope_spectrum`** - Envelope spectrum via Hilbert transform
+- **`inl_sine`** - INL/DNL extraction from sine histogram
+
+### Common Utilities (`adctoolbox.common`)
+- **`sine_fit`** - Multi-parameter sine fitting with auto frequency search
+- **`find_bin`** - FFT bin finder with sub-bin resolution
+- **`find_fin`** - Input frequency finder
+- **`alias`** - Frequency aliasing calculator
+- **`cap2weight`** - Capacitor array to weight conversion
+
+### Calibration (`adctoolbox.dout`)
+- **`fg_cal_sine`** - Foreground calibration using sinewave
+- **`overflow_chk`** - Overflow detection and validation
+
+### Oversampling (`adctoolbox.oversampling`)
+- **`ntf_analyzer`** - Noise Transfer Function analysis
+
+---
+
+## Package Structure
+
+```
+adctoolbox/
+├── aout/           # Analog output analysis
+├── common/         # Common utilities
+├── dout/           # Digital output calibration
+├── oversampling/   # Oversampling analysis
+└── utils/          # Utility functions
+```
+
+---
+
+## Documentation
+
+- **GitHub Repository**: [https://github.com/Arcadia-1/ADCToolbox](https://github.com/Arcadia-1/ADCToolbox)
+- **Full Documentation**: See GitHub repository for complete guides
+- **API Reference**: Comprehensive docstrings in all modules
+- **Test Suite**: 15 unit tests with 100% MATLAB-Python parity validation
+
+---
+
+## Validation
+
+**Tested against MATLAB reference implementation**:
+- 15 Python unit tests
+- 96 comparison test cases
+- 100% numerical parity achieved
+- Results: 27 PERFECT + 51 EXCELLENT + 13 GOOD + 5 ACCEPTABLE
+
+---
+
+## Example Use Cases
+
+- **ADC Characterization**: Measure ENOB, SNDR, SFDR for performance verification
+- **Jitter Analysis**: Separate amplitude noise from phase noise/jitter
+- **Nonlinearity Testing**: Extract INL/DNL using sine histogram method
+- **Calibration**: Foreground calibration for SAR and pipeline ADCs
+- **Error Diagnosis**: Multi-view error analysis (time, frequency, phase domains)
+- **Research**: ADC algorithm development with validated reference implementation
+
+---
+
+## License
+
+MIT License - See [LICENSE](https://github.com/Arcadia-1/ADCToolbox/blob/main/LICENSE) for details.
+
+## Citation
+
+If you use this toolbox in your research, please cite:
+
+```bibtex
+@software{adctoolbox2025,
+  author = {Zhang, Zhishuai and Jie, Lu},
+  title = {ADCToolbox},
+  year = {2025},
+  url = {https://github.com/Arcadia-1/ADCToolbox}
+}
+```
+
+---
+
+## Authors
+
+Zhishuai Zhang, Lu Jie
+
+---
+
+## Contributing
+
+Contributions welcome! Please visit the [GitHub repository](https://github.com/Arcadia-1/ADCToolbox) for contribution guidelines.
+
+**Development Setup**:
+```bash
+git clone https://github.com/Arcadia-1/ADCToolbox.git
+cd ADCToolbox/python
+pip install -e .[dev]
+python tests/run_all_tests.py
+```
+
+---
+
+## Links
+
+- **GitHub**: [https://github.com/Arcadia-1/ADCToolbox](https://github.com/Arcadia-1/ADCToolbox)
+- **Issues**: [https://github.com/Arcadia-1/ADCToolbox/issues](https://github.com/Arcadia-1/ADCToolbox/issues)
+- **MATLAB Version**: Also available in the same repository

adctoolbox-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adctoolbox"
+version = "0.1.0"
+description = "A comprehensive toolbox for ADC testing and characterization"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Zhishuai Zhang"},
+    {name = "Lu Jie"}
+]
+keywords = ["ADC", "analog-to-digital", "converter", "testing", "characterization", "signal-processing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+dependencies = [
+    "numpy>=1.20.0",
+    "scipy>=1.7.0",
+    "matplotlib>=3.4.0",
+    "pandas>=1.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Arcadia-1/ADCToolbox"
+Documentation = "https://github.com/Arcadia-1/ADCToolbox#readme"
+Repository = "https://github.com/Arcadia-1/ADCToolbox"
+Issues = "https://github.com/Arcadia-1/ADCToolbox/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

adctoolbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adctoolbox-0.1.0/src/adctoolbox/__init__.py

@@ -0,0 +1,42 @@
+"""
+ADCToolbox: A comprehensive toolbox for ADC testing and characterization.
+
+This package provides tools for analyzing both analog and digital aspects of
+Analog-to-Digital Converters, including spectrum analysis, error characterization,
+calibration algorithms, and more.
+
+Submodules:
+-----------
+- common: Common utility functions (alias, find_bin, find_fin, sine_fit, etc.)
+- aout: Analog output / time-domain analysis (spectrum, error analysis, etc.)
+- dout: Digital output / code-level analysis (calibration, overflow detection, etc.)
+- oversampling: Oversampling and noise transfer function tools
+- utils: Utility functions and reporting tools
+- data_generation: Test data generation utilities
+
+Usage:
+------
+>>> from adctoolbox.aout import spec_plot
+>>> from adctoolbox.common import sine_fit
+>>> from adctoolbox.dout import fg_cal_sine
+"""
+
+__version__ = '0.1.0'
+
+# Expose submodules for convenience
+from . import common
+from . import aout
+from . import dout
+from . import oversampling
+from . import utils
+from . import data_generation
+
+__all__ = [
+    'common',
+    'aout',
+    'dout',
+    'oversampling',
+    'utils',
+    'data_generation',
+    '__version__',
+]

adctoolbox-0.1.0/src/adctoolbox/aout/__init__.py

@@ -0,0 +1,23 @@
+"""Analog output (time-domain) analysis tools."""
+
+from .spec_plot import spec_plot
+from .spec_plot_phase import spec_plot_phase
+from .spec_plot_2tone import spec_plot_2tone
+from .err_envelope_spectrum import err_envelope_spectrum
+from .err_auto_correlation import err_auto_correlation
+from .err_hist_sine import err_hist_sine
+from .err_pdf import err_pdf
+from .tom_decomp import tom_decomp
+from .inl_sine import inl_sine
+
+__all__ = [
+    'spec_plot',
+    'spec_plot_phase',
+    'spec_plot_2tone',
+    'err_envelope_spectrum',
+    'err_auto_correlation',
+    'err_hist_sine',
+    'err_pdf',
+    'tom_decomp',
+    'inl_sine',
+]