fracpll: charge-pump fractional-N PLL design from measured pieces

Abstract

First release: the charge-pump fractional-N loop, noise, delta-sigma, tuning-curve, lock and measurement-planning machinery distilled from a monolithic GaN-on-SOI HEMT-varactor PLL co-design study, generalized to any technology that fits a charge-pump loop -- CMOS, SiGe, GaN or board-level. The physics-informed-ML and adjoint layers of that study stay with the study; what generalizes is here, running on YOUR measured tuning curves and noise points, each behind a mandatory reference field. What is inside filters / loop: the general passive loop-filter one-port, L = Icp Kvco Z / (jw N), exact complementary transfers, and a crossover/phase-margin report with validity refusals -- no crossover, non-positive margin, or a crossover past f_ref/10, the classical validity edge of the averaged continuous-time model (Gardner, IEEE Trans. Commun. 28, 1849 (1980)). mash: MASH 1/2/3 delta-sigma division sequences computed with exact integer accumulators, and the one-sided quantization phase PSD. First-order modulation is refused: it produces discrete spurs, not the smooth PSD. noise: measured NoiseSpec points with mandatory provenance and no extrapolation, the three-path closed-loop noise assembly, one-sided RMS jitter. tuning: monotone PCHIP tuning curves through measured (Vc, f) points -- negative-Kvco oscillators are first-class -- with analytic-derivative gain, linear temperature interpolation between measured corners, and refusals for folded curves (offending bias voltage named) and any extrapolation. lock: the averaged nonlinear lock transient (saturating tanh detector, leakage, mismatch) on the measured curve, and the closed-form static offset 2 pi atanh(I_leak/Icp - mismatch); refusals for unreachable lock targets and leakage the pump cannot cancel. plan: the closed-form error bar of an averaged jitter measurement and its exact 1/sqrt(n) inversion into instrument time. How this release is checked (26 tests, Python 3.9-3.14) The general filter impedance equals the textbook second-order closed form at machine precision (rtol 1e-12); a branch sent to infinite resistance drops out of the network. 1/(1+L) + L/(1+L) = 1 to 1e-12; the crossover/margin report matches an independent 400,000-point dense-grid reading. The MASH mean division offset equals num/den EXACTLY, asserted with rational arithmetic (fractions.Fraction) over full periods; the sequence ranges hit their closed per-order bounds. The quantization phase PSD closed form matches the Welch spectrum of the exact accumulator sequence for MASH-2 and MASH-3 (median ratio within 15% across the band) -- the formula is validated against the sequence, not taken on authority. (The common textbook form differs by the one/two-sided convention; this package states its convention and tests it.) Jitter reproduces the flat and 1/f^2 closed forms; the noise assembly equals an independently computed |L/(1+L)|^2 N^2 path to 1e-12. The PCHIP tuning gain equals a central finite difference across the fitted curve; the fitted curve hits the measured points exactly. The integrated nonlinear lock transient settles to the closed-form static offset and puts the oscillator exactly on N f_ref (two independent routes, one number). The measurement-planning error bar matches a 4000-trial seeded Monte Carlo with exponentially distributed periodogram bins; the inversion is asserted on both sides (n meets the target, n-1 fails it). Honest limits Everything here is the AVERAGED model: per-edge PFD behavior (dead zone, cycle-slip granularity, reset overlap) is below its resolution, and the stability report refuses past f_ref/10 rather than pretending otherwise. No device physics, no transistor models and no PDK data ship with this package: the source study's foundry PDK files are licensed material and are not redistributed.