ADCToolbox Algorithm Overview

Last Updated: 2025-12-03

Introduction

This document describes the working principles and architectural design of the MATLAB algorithms in ADCToolbox. The toolbox has been streamlined for efficiency, maintainability, and consistent output formatting.

Toolset Architecture

Design Principles

Separation of Concerns: Tool execution and panel generation are separate functions
Data-Driven Execution: Tool lists defined as data structures to eliminate repetitive code
Auto-Detection: Panel functions automatically locate plot files using naming conventions
Consistent Formatting: All tools use standardized figure properties and output

File Organization

matlab/src/
├── toolset_aout.m          # 9 analog analysis tools
├── toolset_aout_panel.m    # Combine AOUT plots into 3×3 panel
├── toolset_dout.m          # 6 digital analysis tools
├── toolset_dout_panel.m    # Combine DOUT plots into 3×2 panel
└── [individual tool functions]

toolset_aout: Analog Output Analysis

Files:

MATLAB: matlab/src/toolset_aout.m
Python: python/src/adctoolbox/toolset_aout.py

Purpose

Executes 9 diagnostic tools on calibrated ADC analog output data (sine wave). Covers time-domain, frequency-domain, and statistical error analysis.

Algorithm Workflow

1. Parse inputs (aout_data, outputDir, optional parameters)
2. Create output directory if needed
3. Pre-compute common parameters:
   - freqCal = findfreq(aout_data)          % Auto-detect input frequency
   - FullScale = max(aout_data) - min(aout_data)
   - err_data = aout_data - sinfit(aout_data)  % Error signal
4. For each tool i = 1:9:
   - Create figure (800×600, visible/hidden)
   - Execute tool function with pre-computed params
   - Format (title, font size 14)
   - Save PNG: <prefix>_<i>_<toolname>.png
   - Close figure
   - Print progress message
5. Return cell array of 9 file paths

Tool Execution Pattern

Each tool follows a standardized pattern:

fprintf('[%d/9] toolname');
figure('Position', [100, 100, 800, 600], 'Visible', opts.Visible);
tool_function(params...);
title('Tool Name');
set(gca, 'FontSize', 14);
plot_files{i} = fullfile(outputDir, sprintf('%s_%d_toolname.png', opts.Prefix, i));
saveas(gcf, plot_files{i});
close(gcf);
fprintf(' -> %s\n', plot_files{i});

Tools Executed

#	Tool	Key Parameters
1	`tomdec`	`freqCal`, `10` harmonics, `1` OSR
2	`plotspec`	`label=1`, `harmonic=5`, `OSR=1`, `window=@hann`
3	`plotphase`	`harmonic=10`, `mode='FFT'`
4	`errsin` (code)	`bin=20`, `fin=freqCal`, `xaxis='value'`
5	`errsin` (phase)	`bin=99`, `fin=freqCal`, `xaxis='phase'`
6	`errpdf`	`Resolution`, `FullScale`
7	`errac`	`MaxLag=200`, `Normalize=true`
8	`plotspec` (error)	`label=0`
9	`errevspec`	`Fs=1`

Key Features

Pre-computation: Expensive calculations (frequency detection, sine fit) done once and reused
Memory Management: Figures closed immediately after save to prevent memory buildup
Fail-Fast: Execution stops on first error (use try-catch for fail-safe execution)
Standardized Output: All plots have consistent size and formatting

toolset_dout: Digital Output Analysis

Files:

MATLAB: matlab/src/toolset_dout.m
Python: python/src/adctoolbox/toolset_dout.py

Purpose

Executes 6 diagnostic tools on ADC digital bit outputs (for SAR ADCs and bit-weighted architectures). Performs calibration, weight analysis, and performance evaluation.

Algorithm Workflow

1. Parse inputs (bits, outputDir, optional parameters)
2. Create output directory if needed
3. Extract resolution: nBits = size(bits, 2)
4. Calibrate bit weights:
   [w_cal, ~, ~, ~, ~, f_cal] = wcalsine(bits, 'freq', 0, 'order', Order, 'verbose', 0)
5. Pre-compute digital codes:
   - digitalCodes = bits * (2.^(nBits-1:-1:0))'  % Nominal binary weights
   - digitalCodes_cal = bits * w_cal'             % Calibrated weights
6. Define tool execution table (struct array with 6 entries)
7. For each tool i = 1:6:
   - Create figure (variable size, visible/hidden)
   - Execute tool function handle from struct
   - Format (title, font size 14)
   - Save PNG with exportgraphics (150 DPI)
   - Close figure
   - Print progress message
8. Return cell array of 6 file paths

Data-Driven Tool Execution

Unlike the old repetitive approach, tools are defined as a struct array:

tools = {
    struct('idx', 1, 'name', 'Spectrum (Nominal)', 'suffix', '1_spectrum_nominal', ...
        'pos', [100, 100, 800, 600], ...
        'fn', @() plotspec(digitalCodes, 'label', 1, 'harmonic', 5, 'OSR', 1, 'window', @hann));
    struct('idx', 2, 'name', 'Spectrum (Calibrated)', 'suffix', '2_spectrum_calibrated', ...
        'pos', [100, 100, 800, 600], ...
        'fn', @() plotspec(digitalCodes_cal, 'label', 1, 'harmonic', 5, 'OSR', 1, 'window', @hann));
    % ... 4 more tools
};

for i = 1:6
    fprintf('[%d/6] %s', i, tools{i}.name);
    figure('Position', tools{i}.pos, 'Visible', p.Results.Visible);
    tools{i}.fn();  % Execute function handle
    title(tools{i}.name);
    set(gca, 'FontSize', 14);
    plot_files{i} = fullfile(outputDir, sprintf('%s_%s.png', p.Results.Prefix, tools{i}.suffix));
    exportgraphics(gcf, plot_files{i}, 'Resolution', 150);
    close(gcf);
    fprintf(' -> %s\n', plot_files{i});
end

Benefits of Data-Driven Approach:

Code Reduction: 109 lines → 66 lines (40% reduction)
Consistency: Single point of control for formatting
Maintainability: Easy to add/remove/modify tools
Readability: Tool properties clearly visible in struct definition

Tools Executed

#	Tool	Purpose	Figure Size
1	`plotspec` (nominal)	Spectrum before calibration	800×600
2	`plotspec` (calibrated)	Spectrum after `wcalsine` calibration	800×600
3	`bitact`	Bit toggle rate analysis	1000×750
4	`ovfchk`	Overflow/redundancy check	1000×600
5	`weightScaling`	Radix visualization	800×600
6	`bitsweep`	ENoB vs number of bits	800×600

Panel Functions

toolset_aout_panel

File: matlab/src/toolset_aout_panel.m

Combines 9 individual AOUT plots into a 3×3 panel figure.

Algorithm

1. Parse inputs (outputDir, optional Prefix, PlotFiles, Visible)
2. If PlotFiles not provided:
   - Auto-construct file paths: <outputDir>/<prefix>_<i>_<name>.png
3. Validate 9 files expected
4. Create 3×3 tiled layout figure (1800×1000)
5. For each plot i = 1:9:
   - nexttile
   - If file exists: imread, imshow, title
   - Else: display "Missing" text in red
6. Add super title "AOUT Toolset Overview"
7. Export panel: PANEL_<PREFIX>.png (300 DPI)
8. Close figure
9. Return status struct (.success, .panel_path, .errors)

File Naming Convention

Auto-detected files:

<prefix>_1_tomdec.png
<prefix>_2_plotspec.png
<prefix>_3_plotphase.png
<prefix>_4_errsin_code.png
<prefix>_5_errsin_phase.png
<prefix>_6_errPDF.png
<prefix>_7_errAutoCorrelation.png
<prefix>_8_errSpectrum.png
<prefix>_9_errEnvelopeSpectrum.png

toolset_dout_panel

File: matlab/src/toolset_dout_panel.m

Combines 6 individual DOUT plots into a 3×2 panel figure.

Algorithm

Same as toolset_aout_panel but with 6 plots in 3×2 layout (1200×1000).

File Naming Convention

Auto-detected files:

<prefix>_1_spectrum_nominal.png
<prefix>_2_spectrum_calibrated.png
<prefix>_3_bitActivity.png
<prefix>_4_overflowChk.png
<prefix>_5_weightScaling.png
<prefix>_6_ENoB_sweep.png

Key Features

Auto-Detection: Uses prefix to find files - no need to manually specify paths
Flexible: Can override with explicit PlotFiles parameter
Robust: Handles missing files gracefully (shows placeholder)
Reusable: Can re-generate panels without re-running tools

Common Utility Functions

findfreq

File: matlab/src/findfreq.m

Auto-detects sine wave frequency from time-domain signal using FFT.

Algorithm:

Compute FFT of input signal
Find peak in magnitude spectrum
Convert bin index to normalized frequency
Return frequency (0 to 0.5, normalized to sampling rate)

sinfit

File: matlab/src/sinfit.m

Fits a 4-parameter sine wave to data: A*sin(2πft + φ) + DC

Algorithm:

Use findfreq to detect frequency
Set up nonlinear least squares problem
Optimize amplitude, frequency, phase, DC offset
Return fitted sine wave

Naming Conventions

File Naming

Individual tool outputs:

<prefix>_<index>_<toolname>.png

Examples:

aout_1_tomdec.png
dout_3_bitActivity.png

Panel outputs:

PANEL_<PREFIX>.png

Examples:

PANEL_AOUT.png
PANEL_DOUT.png

Variable Naming

plot_files — Cell array of PNG file paths
outputDir — Directory for output files
freqCal — Calibrated/detected frequency
w_cal — Calibrated bit weights
digitalCodes — Digital output codes (nominal weights)
digitalCodes_cal — Digital output codes (calibrated weights)

Performance Optimizations

Memory Management

Figures closed immediately after save
Use 'Visible', false for batch processing (faster)
Pre-allocate cell arrays for file paths

Computation Efficiency

Pre-computation: Expensive operations (frequency detection, sine fit, calibration) done once
Data-driven loops: Eliminates repetitive code
Minimal disk I/O: Each plot saved once

Code Efficiency

Before (repetitive):

% Tool 1
fprintf('[1/6] Tool1...');
f = figure('Visible', figVis, 'Position', [100, 100, 800, 600]);
tool1_function(params);
save_and_close(f, outputDir, opts.Prefix, '1_tool1', 'Tool 1');

% Tool 2
fprintf('[2/6] Tool2...');
f = figure('Visible', figVis, 'Position', [100, 100, 800, 600]);
tool2_function(params);
save_and_close(f, outputDir, opts.Prefix, '2_tool2', 'Tool 2');

% ... repeated 4 more times

After (data-driven):

tools = {struct('name', 'Tool1', 'suffix', '1_tool1', 'pos', [100,100,800,600], 'fn', @() tool1_function(params)); ...};

for i = 1:6
    fprintf('[%d/6] %s', i, tools{i}.name);
    figure('Position', tools{i}.pos, 'Visible', figVis);
    tools{i}.fn();
    % ... standardized save
end

Result: 109 lines → 66 lines (40% reduction)

Usage Patterns

Pattern 1: Generate plots and panel together

% AOUT
plot_files = toolset_aout(aout_data, 'output/test1');
panel_status = toolset_aout_panel('output/test1', 'Prefix', 'aout');

% DOUT
plot_files = toolset_dout(bits, 'output/test1');
panel_status = toolset_dout_panel('output/test1', 'Prefix', 'dout');

Pattern 2: Batch generate plots, then gather panels

% Generate all plots first
for i = 1:N
    toolset_aout(data{i}, sprintf('output/run%d', i), 'Prefix', sprintf('run%d', i));
end

% Then generate all panels
for i = 1:N
    toolset_aout_panel(sprintf('output/run%d', i), 'Prefix', sprintf('run%d', i));
end

Pattern 3: Re-generate panels only (plots already exist)

% No need to re-run toolset - just regenerate panels
toolset_aout_panel('output/test1', 'Prefix', 'aout');
toolset_dout_panel('output/test2', 'Prefix', 'dout');

Error Handling

Current Behavior

Both toolsets use fail-fast error handling:

Execution stops on first error
MATLAB displays error message
Partial results may be saved

Implementing Fail-Safe Execution

To continue execution after errors, wrap tools in try-catch:

for i = 1:length(tools)
    try
        % ... tool execution
        success(i) = true;
    catch ME
        fprintf(' ✗ %s\n', ME.message);
        errors{end+1} = sprintf('Tool %d: %s', i, ME.message);
        success(i) = false;
    end
end

Future Enhancements

Planned Features

Python panel functions: Implement toolset_aout_panel and toolset_dout_panel in Python
Parallel execution: Run independent tools in parallel using parfor
Progress callbacks: Optional callback function for progress updates
Custom tool selection: Allow users to specify which tools to run
Fail-safe mode: Option to continue execution after errors

Architectural Improvements

Tool registry: Central registry of all available tools
Plugin system: Easy addition of custom tools
Configuration files: YAML/JSON config for tool parameters
Result caching: Cache expensive computations for reuse

References

IEEE Std 1241-2010: Standard for ADC Test Methods
IEEE Std 1057-2017: Standard for Digitizing Waveform Recorders
MATLAB documentation: Function handles, struct arrays, exportgraphics

Version History

Version	Date	Changes
2.0	2025-12-03	Streamlined toolsets with data-driven execution, separated panel functions
1.0	2025-01-28	Initial implementation