Arcadia-1 · Arcadia-1 · Mar 10, 2026 · Mar 10, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -42,13 +42,17 @@ jobs:
           pip install --upgrade pip
           pip install -e .[docs]
 
-      - name: Build Sphinx documentation
+      - name: Build English docs
         run: |
           cd python/docs
           python -m sphinx -b html source build/html
-          # Create .nojekyll file to allow files starting with underscore
           touch build/html/.nojekyll
 
+      - name: Build Chinese docs
+        run: |
+          cd python/docs
+          python -m sphinx -b html -D language=zh_CN source build/html/zh_CN
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

diff --git a/.gitignore b/.gitignore
@@ -201,7 +201,7 @@ python/docs/source/_autosummary/
 # Claude Playground (temporary test scripts and experiments)
 # =============================================================================
 .claude
-
+CLAUDE.md
 test_dataset/
 agent_playground/
 matlab/debug

diff --git a/docs/python_matlab_parity.md b/docs/python_matlab_parity.md
@@ -0,0 +1,82 @@
+# Python vs MATLAB Parity Tracker
+
+Last updated: 2026-03-10
+
+This document tracks feature parity between the Python (`adctoolbox` v0.5.0) and MATLAB (`ADCToolbox` v1.30) implementations.
+
+---
+
+## Function Mapping
+
+### Shared (present in both)
+
+| Category | MATLAB | Python | Notes |
+|---|---|---|---|
+| Spectrum | `plotspec` | `analyze_spectrum` | Python returns dict; MATLAB returns individual values |
+| Polar Spectrum | `plotphase` | `analyze_spectrum_polar` | |
+| Perf vs OSR | `perfosr` | *(in-example only)* | Python has no dedicated function; done in `exp_s06` example script |
+| Sine Fit | `sinfit` | `fit_sine_4param` | |
+| Find Coherent Bin | `findbin` | `find_coherent_frequency` | Python returns frequency, MATLAB returns bin index |
+| Estimate Frequency | `findfreq` | `estimate_frequency` | |
+| Alias Folding | `alias` | `fold_frequency_to_nyquist` | Python also has `fold_bin_to_nyquist` |
+| Error by Phase/Value | `errsin` | `analyze_error_by_phase`, `analyze_error_by_value` | MATLAB uses `xaxis` param to switch; Python split into two functions |
+| Error by Value (shortcut) | `errsinv` | `analyze_error_by_value` | Python absorbed the shortcut |
+| Time Decomposition | `tomdec` | `analyze_decomposition_time`, `analyze_decomposition_polar` | Python split into time and polar variants |
+| INL from Sine | `inlsin` | `analyze_inl_from_sine` | |
+| Overflow Check | `bitchk` | `analyze_overflow` | |
+| Weight Calibration | `wcalsin` | `calibrate_weight_sine` | |
+| Weight/Radix Plot | `plotwgt` | `analyze_weight_radix` | |
+| NTF Analysis | `ntfperf` | `ntf_analyzer` | |
+| Dashboard | `adcpanel` | `generate_aout_dashboard`, `generate_dout_dashboard` | Python split analog/digital into separate dashboards |
+
+### MATLAB-only (not yet ported to Python)
+
+| MATLAB Function | Description | Priority |
+|---|---|---|
+| `cdacwgt` | Capacitive DAC weight calculation from capacitor values (cd, cb, cp) | Low — niche, design-phase utility |
+| `ifilter` | FFT-based ideal (brickwall) bandpass filter | Medium — useful general utility |
+| `plotres` | Partial-sum residual plots for bit-matrix correlation analysis | Medium — useful debug visualization |
+| `plotressin` | Shortcut: `wcalsin` + `plotres` combined | Low — follows once `plotres` is ported |
+| `perfosr` (dedicated fn) | Sweep and plot SNDR/SFDR/ENOB vs OSR | Medium — exists as example script but not a reusable function |
+
+### Python-only (not in MATLAB)
+
+| Python Function | Description | Notes |
+|---|---|---|
+| `analyze_two_tone_spectrum` | Two-tone spectrum with IMD analysis | New feature in Python |
+| `analyze_error_pdf` | Error probability density function | New analysis |
+| `analyze_error_spectrum` | FFT of error signal | New analysis |
+| `analyze_error_autocorr` | Error autocorrelation | New analysis |
+| `analyze_error_envelope_spectrum` | Envelope spectrum of error | New analysis |
+| `fit_static_nonlin` | Fit static nonlinearity polynomial | New analysis |
+| `analyze_bit_activity` | Bit toggle activity analysis | MATLAB has legacy `bitact.m` only |
+| `analyze_enob_sweep` | ENOB per bit sweep | MATLAB has legacy `bitsweep.m` only |
+| `calibrate_weight_sine_lite` | Lightweight calibration variant | Internal (not exported), no MATLAB equivalent |
+| `analyze_phase_plane` | Phase-space anomaly detection | Internal (not exported), no MATLAB equivalent |
+| `siggen.nonidealities` | Signal generation with jitter, thermal noise, quantization, settling, nonlinearity | Entire module, no MATLAB equivalent |
+| Unit conversions (16 functions) | `db_to_mag`, `snr_to_enob`, `lsb_to_volts`, `dbm_to_vrms`, etc. | Utility library, no MATLAB equivalent |
+| FOM calculators (4 functions) | `calculate_walden_fom`, `calculate_schreier_fom`, `calculate_thermal_noise_limit`, `calculate_jitter_limit` | Utility library, no MATLAB equivalent |
+| `vpp_for_target_dbfs` | Calculate Vpp for target dBFS | Internal utility, no MATLAB equivalent |
+
+---
+
+## Structural / Behavioral Differences
+
+| Aspect | MATLAB | Python |
+|---|---|---|
+| **Naming** | camelCase (`plotspec`, `sinfit`, `wcalsin`) | snake_case (`analyze_spectrum`, `fit_sine_4param`, `calibrate_weight_sine`) |
+| **Return type** | Multiple return values (`[enob,sndr,sfdr,...] = plotspec(...)`) | Single dictionary (`result = analyze_spectrum(...)`) |
+| **Plot control** | `disp` parameter (0/1) | `create_plot` boolean; separate `plot_*` functions |
+| **API granularity** | One function does multiple things (e.g., `errsin` handles both phase and value binning) | Split into focused functions (`analyze_error_by_phase` vs `analyze_error_by_value`) |
+| **Dashboard** | Single `adcpanel` handles both analog and digital | Separate `generate_aout_dashboard` and `generate_dout_dashboard` |
+| **Legacy functions** | 15 deprecated functions in `legacy/` | No legacy layer; MATLAB names were never shipped |
+| **Shortcut wrappers** | `shortcut/` directory with convenience wrappers | Absorbed into main API (no separate layer) |
+
+---
+
+## Recommendations for Convergence
+
+1. **Port to Python**: `ifilter`, `plotres`, `perfosr` (as dedicated functions)
+2. **Port to MATLAB**: `analyze_two_tone_spectrum`, error analysis suite (PDF, spectrum, autocorr, envelope), `fit_static_nonlin`, signal generation module, unit conversion utilities, FOM calculators
+3. **Promote in Python**: `analyze_phase_plane` and `calibrate_weight_sine_lite` are implemented but not exported — decide whether to make them public
+4. **Decide on `cdacwgt`**: Very MATLAB-specific (CDAC design). May not be needed in Python if the toolbox focuses on measurement/characterization rather than circuit design
diff --git a/python/docs/source/_templates/layout.html b/python/docs/source/_templates/layout.html
@@ -0,0 +1,16 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+{{ super() }}
+<style>
+  .language-banner { background:#1a1a2e; color:#fff; text-align:center; padding:6px; font-size:0.85em; }
+  .language-banner a { color:#4fc3f7; margin:0 8px; }
+</style>
+{% endblock %}
+{% block content %}
+<div class="language-banner">
+  &#x1F310; Language:
+  <a href="/ADCToolbox/{% if pagename != 'index' %}{{ pagename }}{% endif %}">English</a> |
+  <a href="/ADCToolbox/zh_CN/{% if pagename != 'index' %}{{ pagename }}{% endif %}">中文</a>
+</div>
+{{ super() }}
+{% endblock %}
diff --git a/python/docs/source/conf.py b/python/docs/source/conf.py
@@ -38,6 +38,9 @@
 
 language = 'en'
 
+locale_dirs = ['locale']      # where .po files live (relative to source/)
+gettext_compact = False        # one .po file per source file (easier to manage)
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

diff --git a/python/docs/source/index.rst b/python/docs/source/index.rst
@@ -14,6 +14,7 @@ and digital output analysis.
    api/index
    algorithms/index
    examples/index
+   python_matlab_parity
    changelog
 
 Features