README

adc-model

adc-model provides a configurable ADC behavioral model, SPICE testbenches, and analysis scripts for static INL/DNL and dynamic FFT characterization.

Repository: SJTU-YONGFU-RESEARCH-GRP/adc-model

• License: CC BY 4.0 (see LICENSE)
• Entry points: scripts/run_all_simulations.sh, scripts/compare_static_engines.py, scripts/run_analysis.py, scripts/run_static.py, scripts/run_dynamic.py
• Simulators: Python behavioral model (default), Cadence Spectre, ngspice

Table of contents

• Model reference
• Features
• Requirements
• Installation
• Quick start
  • Run all six simulations
  • Compare static engines
  • Full analysis report
  • Static INL/DNL only
  • Dynamic spectrum only
• CLI reference
• Python API
• Simulation engines
  • Cross-engine agreement and discrepancies
• Project layout
• Development
• License

Model reference

For signal-chain equations, sampling policies (ideal vs noisy static, dynamic S&H), INL/DNL methods, coherent FFT metrics, and multi-engine (Python / ngspice / Spectre) behavior, see MODEL.md.

Features

Requirements

• Python 3.10 or newer
• Runtime: NumPy, Matplotlib (installed automatically)
• Optional — Spectre: Cadence Spectre with Verilog-A (AHDL) support
• Optional — ngspice: ngspice 36+ (tested with ngspice 42)

Installation

From the repository root:

./scripts/install_python.sh
source .venv/bin/activate

Or install manually:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quick start

All commands assume the virtual environment is active and you are in the repository root.

Run all six simulations

scripts/run_all_simulations.sh runs every engine × testbench combination in one pass:

Default output layout (under outputs/ unless overridden):

outputs/
├── python/
│   ├── static_waveform.csv, inl_dnl.svg
│   ├── dynamic_waveform.csv, spectrum.svg
│   ├── SUMMARY.md     # configuration, metrics, embedded plot links
│   ├── logs/          # *.log (python, spectre, ngspice)
│   └── veriloga/      # archived configurable_adc.va + testbench copies
├── ngspice/           # same CSV/SVG layout + ngspice/*.cir rendered netlists
└── spectre/           # same + logs/*.nutascii, logs/netlists/*.scs, logs/*.ahdlSimDB/

Use --output-root outputs/noise or outputs/ideal to keep noisy and ideal batch runs separate.

./scripts/run_all_simulations.sh

Quantizer-limited baseline (no noise or nonlinearity), separate output tree:

./scripts/run_all_simulations.sh --ideal --output-root outputs/ideal

Skip external simulators when ngspice or spectre is not installed:

./scripts/run_all_simulations.sh --skip-missing

Forward shared CLI options to every run (must follow --):

./scripts/run_all_simulations.sh -- --bits 12 --fs 2e6

Environment variables: OUTPUT_ROOT (same as --output-root), VENV_DIR (Python interpreter under ${VENV_DIR}/bin/python).

Requires ngspice and spectre on PATH unless --skip-missing is set.

Compare static engines

After run_all_simulations.sh, use scripts/compare_static_engines.py to print a side-by-side table of static ramp statistics and INL/DNL metrics for each engine under the same --output-root. This uses the same ADC settings and INL/DNL method as run_static.py (histogram when noise is enabled, transition/auto when --ideal).

# Default-noise batch (outputs/noise/{python,ngspice,spectre}/)
python scripts/compare_static_engines.py --output-root outputs/noise

# Ideal batch
python scripts/compare_static_engines.py --ideal --output-root outputs/ideal

# Subset of engines or explicit ramp depth
python scripts/compare_static_engines.py --output-root outputs/noise --engines python spectre
python scripts/compare_static_engines.py --output-root outputs/noise --samples-per-code 4

The table reports sample count, code-transition count, per-code hit statistics (min/max/mean/std), and max |DNL| / |INL|. A short vs python summary shows deltas to the Python behavioral reference.

Example (default-noise static, from ./scripts/run_all_simulations.sh):

Engine      Samples  Transitions  Hits mean  Hits std  Max |DNL|  Max |INL|
python        16384         4817      15.87      2.81      1.000      4.441
ngspice       16384         4817      15.87      2.81      1.000      4.441
spectre       16384         1017      15.88      0.73      1.000      4.036

See Cross-engine agreement and discrepancies for why Spectre reports far fewer code transitions and how to interpret INL/DNL and FFT deltas. Use --check-parity to fail CI when metrics drift beyond scripted tolerances:

python scripts/compare_static_engines.py --output-root outputs --check-parity

Full analysis report

Run static and dynamic simulations, generate plots, archive logs, and write SUMMARY.md:

python scripts/run_analysis.py --output-dir outputs/python

Use --ideal for a quantizer-limited baseline (no noise or nonlinearity):

python scripts/run_analysis.py --ideal --output-dir outputs/python_ideal

Static INL/DNL only

python scripts/run_static.py --output-dir outputs/static

Analyze an existing waveform CSV (skip simulation):

python scripts/run_static.py --input outputs/python/static_waveform.csv --output-dir outputs/static

Dynamic spectrum only

python scripts/run_dynamic.py --output-dir outputs/dynamic

Override the input tone frequency or coherent bin:

python scripts/run_dynamic.py --fin 100000 --num-samples 8192 --output-dir outputs/dynamic

CLI reference

Shared ADC and noise options are available on all three scripts (run_analysis.py, run_static.py, run_dynamic.py).

Script-specific options:

Python API

import numpy as np
from adc_model import AdcConfig, AdcNoiseConfig, compute_inl_dnl, compute_dynamic_metrics
from adc_model import simulate_static, simulate_dynamic

cfg = AdcConfig(bits=10, fs_hz=1e6)
noise = AdcNoiseConfig(sigma_thermal_v=250e-6, dnl_sigma_lsb=0.08)

static = simulate_static(cfg, samples_per_code=4, noise=noise)
codes = static["code"].astype(np.int64)
linearity = compute_inl_dnl(static["vin"], codes, cfg)

dynamic = simulate_dynamic(cfg, num_samples=8192, fin_hz=121_704.0, noise=noise)
dyn_codes = dynamic["code"].astype(np.int64)
metrics = compute_dynamic_metrics(dyn_codes, cfg, fin_hz=121_704.0)

simulate_static / simulate_dynamic return dicts with keys time, vin, clk, v_code, and code. Public exports are listed in adc_model.__all__.

Simulation engines

Cross-engine agreement and discrepancies

All engines share the same CLI defaults (--gain 1.01, --offset-v 5e-3, noise on unless --ideal), per-clock sampling aligned with configurable_adc.va (@(cross(clk))), and the same post-simulation analysis (compute_inl_dnl, compute_dynamic_metrics). Differences come from how each engine produces the waveform CSV, not from different metric formulas.

Default-noise batch (representative)

Running ./scripts/run_all_simulations.sh (output under outputs/) with ngspice and Spectre on PATH yields:

Fin is the coherent bin default: 997 × fs / 8192 at fs = 1 MHz.

Python and ngspice — near-identical

For the default-noise configuration, Python and ngspice should match to numerical noise:

• Static: identical sample counts, code-transition counts, hit statistics, and max |DNL| / |INL| (see compare_static_engines.py table above).
• Dynamic: SNDR/ENOB within ~0.01 dB / 0.01 bit; SFDR may differ by a few tenths of a dB from FFT numerics.

ngspice runs the behavioral netlist in SPICE, but when thermal noise or DNL spread is enabled it re-applies those mechanisms in Python at clock edges using the same noise_seed as the Python model. That hybrid path is intentional so open-source regression stays deterministic and aligned with tests/test_model_parity.py.

Treat Python as the golden reference for CI and algorithm work; use ngspice to validate the exported netlist and PULSE clock wiring.

Spectre — expected static gaps

Spectre often agrees on max |DNL| but disagrees on static shape metrics versus Python:

Noisy static INL/DNL uses the histogram method (same as run_static.py when noise is enabled). Spectre is still useful for sign-off on configurable_adc.va and Spectre netlists; do not expect bit-exact INL curves next to Python.

compare_static_engines.py --check-parity enforces:

Spectre — expected dynamic gaps

Dynamic metrics are computed from the same FFT pipeline on each engine’s CSV, but the captured codes differ slightly:

• SNDR / ENOB can be ~2 dB higher on Spectre (less in-band noise power in the FFT) while SFDR can be ~2 dB lower (spur energy counted differently). THD usually stays within ~1 dB.
• This is normal for a noisy, nonlinear 10-bit model: use Python/ngspice for tight regression; use Spectre to confirm the VA dynamic testbench is in the right ballpark.

Interpreting large static INL

With default mismatch (gain = 1.01, offset_v = 5 mV on a 1 V full-scale 10-bit ADC), max |INL| ≈ 4+ LSB is dominated by gain/offset error, not the 0.08 LSB DNL spread alone. Reducing mismatch or using --ideal collapses INL toward the quantizer-limited case.

Ideal (--ideal) baseline

Quantizer-limited runs disable thermal noise, jitter, nonlinearity, and DNL spread:

./scripts/run_all_simulations.sh --ideal --output-root outputs/ideal

Expect roughly ~0.25 LSB max |DNL| on static tests and ~61.5 dB SNDR on dynamic tests across engines, with smaller spread than the noisy batch above.

Which engine when

Detailed engine setup and netlist notes:

• testbench/spectre/README.md — Cadence Spectre and Verilog-A
• testbench/ngspice/README.md — Open-source ngspice behavioral netlists

Example with ngspice:

python scripts/run_analysis.py --ngspice --output-dir outputs/ngspice

Project layout

adc-model/
├── LICENSE
├── README.md
├── pyproject.toml
├── scripts/
│   ├── install_python.sh      # Create venv and editable install
│   ├── run_all_simulations.sh     # All engines: static + dynamic (6 runs)
│   ├── compare_static_engines.py  # Static waveform comparison table
│   ├── run_analysis.py            # Static + dynamic + SUMMARY.md
│   ├── run_static.py          # INL/DNL testbench
│   └── run_dynamic.py         # FFT spectrum testbench
├── src/adc_model/             # Installable Python package
│   ├── model.py               # Behavioral ADC (matches Verilog-A)
│   ├── io.py                  # Clock waveforms and edge-aligned downsampling
│   ├── static.py              # INL/DNL analysis and plots
│   ├── static_compare.py      # Multi-engine static comparison (CLI backend)
│   ├── dynamic.py             # FFT metrics and spectrum plots
│   ├── spectre_engine.py      # Spectre driver helpers
│   ├── ngspice_engine.py      # ngspice netlist rendering
│   └── report.py              # SUMMARY.md generation
├── testbench/
│   ├── spectre/               # Spectre netlists (.scs)
│   └── ngspice/               # ngspice netlists (.cir)
├── veriloga/
│   ├── configurable_adc.va    # Reference Verilog-A model
│   └── ti_channel_adc.va
└── tests/                     # pytest suite

Simulation outputs (CSV waveforms, SVG figures, logs, rendered netlists) are written to --output-dir and are gitignored under outputs/. Spectre AHDL debris (status, *.ahdlSimDB/ in the repo root) is listed in .gitignore and cleaned when using the Python Spectre driver.

Development

source .venv/bin/activate
pytest
ruff check .

Install without dev dependencies:

./scripts/install_python.sh --no-dev

License

Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). See LICENSE.

Third-party tools (Cadence Spectre, ngspice) are subject to their own license terms.