---

name: matlab-model-ams-systems description: "Model a Phase-Locked Loop (PLL) IC from its datasheet or system specs using Mixed-Signal Blockset. Without this skill, agents universally select the wrong solver and produce non-functional PLL models — 100% of unguided attempts fail. Covers Integer-N, Fractional-N, Dual Modulus architectures, loop filter design, lock time optimization, VCO phase noise configuration, and msbPllArchitectures/msbPllFoundation block assembly. Use when: PLL modeling, frequency synthesizer design, phase noise simulation, lock time analysis, charge pump design, loop filter tuning, datasheet-to-model, Mixed-Signal Blockset PLL, msbPllArchitectures." license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Skill: PLL Datasheet Modeling -- Core (Phases 1-4)

Model a PLL IC from its datasheet or system specifications using Simulink building blocks from the Mixed-Signal Blockset (MSB) foundation library msbPllFoundation.

Companion file: modeling-pll-datasheet-validate.md covers Phases 5-9 (loop filter design, validation, measurement, iteration, pitfalls).

When to Use

• Modeling a PLL IC from its datasheet (extracting parameters, selecting architecture)
• Designing a frequency synthesizer from system specs (fVco, fRef, lock time, phase noise targets)
• Building a behavioral PLL model in Simulink using Mixed-Signal Blockset
• Validating phase noise performance against datasheet measurements
• Selecting between Integer-N, Fractional-N, or Dual Modulus PLL architectures

When NOT to Use

• Circuit-level PLL design (transistor-level VCO, charge pump schematic)
• PLL analysis without building a Simulink model (use estimatePLLPhaseNoise directly)
• Clock distribution or jitter cleaning (not frequency synthesis)
• Non-MSB PLL modeling (e.g., custom Simulink blocks without the Mixed-Signal Blockset)

---

Workflow Directives (MANDATORY)

1. Gather specs ONE AT A TIME (MANDATORY — no exceptions) -- For ANY PLL or frequency synthesizer design request (spec-driven or exploratory), ask exactly ONE question per response. Do NOT list multiple questions or present a bulleted requirements checklist. This reduces cognitive load and makes the interaction conversational. Sequence:

   1. Output frequency (or frequency range)
   2. Reference frequency (flag if N > 200 — high in-band noise penalty)
   3. Architecture (Integer-N / Frac-N / auto — may be predetermined by N)
   4. Lock time target
   5. Phase noise / jitter / spur targets (or confirm "none")
   6. Charge pump current (offer typical value as default)
   7. VCO requirements (Kvco, phase noise profile — offer rule-of-thumb)
   8. Loop filter preference (order, BW override)
   9. Any other requirements?
   10. Save location (folder path for .slx and results)

   Rules:

   • Ask ONE question, wait for answer, then ask the next.
   • Skip questions already answered in the user's initial prompt.
   • Offer a sensible default in parentheses so user can just confirm.
   • After all specs are gathered, present the Design Plan (Directive 5, Step A).

2. Iterate autonomously ONLY when targets are NOT met -- If the first attempt PASSES with >3x margin, STOP. The BW formula already gives a good design — do NOT sweep BW or iterate "for completeness." Only sweep/iterate when the first attempt FAILS or margin is < 2x. When iteration IS needed, sweep parameters and re-simulate until met.

3. Report progress and generate HTML summary -- Print brief status per attempt (e.g., "BW=1MHz, PM=70 -> lock=5.2us X"). After ALL targets pass, generate an HTML report saved alongside the model. Required sections:

   Report contents (mandatory):

   • Summary box: pass/fail verdict with margin
   • Model screenshot: print(['-s' model], path, '-dpng', '-r150')
   • Architecture diagram (text-based)
   • Design parameters grid (fVCO, fRef, N, Icp, Kvco, filter type, etc.)
   • Loop filter component table with time constants (τ_z = R2·C2, τ_p3 = R3·C3)
   • Transfer function box: Z(s), G(s)=Icp·Kvco·2π·Z(s)/(N·s), H(s)=G/(1+G), plus key values: fc, PM, zero freq, pole freqs
   • Bode plots (open-loop + closed-loop): export from pllOpenLoopPlot/ pllCloseLoopPlot via exportgraphics(fig, path, 'Resolution', 150). Find figures by Tag: 'PllOpenLoopDynamicPlot', 'PllCloseLoopDynamicPlot'
   • Vctrl transient: plot from simOut timeseries with lock time marker
   • Simulation results table (spec vs measured)
   • Simulation config (solver, stopTime, holdOff, averages)
   • Session metrics: include [COST] and [DURATION] placeholders in the report footer. The user fills these in from the Claude Code UI after the task completes (visible at session end).

   How to export plots:

   pllOpenLoopPlot(Icp, Kvco, N, 0, R2, R3, 0, C1, C2, C3, 0);
   fig = findobj('Type','figure','Tag','PllOpenLoopDynamicPlot');
   exportgraphics(fig, fullfile(outDir,'open_loop_bode.png'), 'Resolution', 150);
   

   Use relative src="filename.png" paths in HTML. Open report with web(reportPath, '-browser').

4. Figures must be visible -- After simulation, call set(0,'DefaultFigureVisible','on') and ensure all plot figures have 'Visible','on'. Call drawnow to force rendering. The MCP MATLAB server defaults to Visible='off'.

5. Show progress on screen at each step -- At key milestones, print status:

   • Step A — Design plan: ASCII block diagram + params before building

     [PLL TB]──▶[PFD]──▶[CP]──▶[Loop Filter]──▶[VCO]──┐
        ▲                                               │
        └─────────────[Divider ÷N]◀─────────────────────┘
     

     Include: architecture, fRef, N, Icp, Kvco, Fc, PM, filter type, solver. When adding impairments, show updated diagram BEFORE implementing.
   • Step B — Filter + Bode: component values, then pllOpenLoopPlot/pllCloseLoopPlot
   • Step C — Sim start: Simulating Pass 1 (lock time)... StopTime=9µs
   • Step D — Results: Lock time = 2.1 µs (target < 3 µs) ✓ [1.4× margin]
   • Step E — Pass 2 (only if PN spec): offsets, measured vs target, pass/fail

---

Prerequisites

• Access to the target PLL IC datasheet (PDF) -- OR basic specs (fVco, fRef, lock time)
• Mixed-Signal Blockset installed (provides msbPllFoundation library)
• Control System Toolbox (for estimatePLLPhaseNoise validation, R2026b+)

Entry Points

A. Datasheet-Driven (Full workflow, Phases 1-4)

Use when you have a PLL IC datasheet. Follow all phases below.

B. Spec-Driven (No datasheet)

Use when you have basic PLL specs but no datasheet. Follow Directive 1 to gather specs, then derive remaining parameters.

Parameter derivation rules:

N = fVco / fRef  (or P*N+S for dual modulus)
BW = min(12/t_lock, fPFD/10)  (capped at fPFD/10 for stability)
Kvco: fVco/50 typical if not specified (e.g., 6 GHz → 120 MHz/V)
Icp: 1-5 mA typical (higher Icp → wider achievable BW with smaller R2)
PM: 50° default (60° if adding 4th-order pole)

Architecture selection:

| Condition | Architecture | |-----------|-------------| | N is integer, single prescaler | Integer N PLL with Single Modulus Prescaler | | N is integer, need P/P+1 flexibility | Integer N PLL with Dual Modulus Prescaler | | N is fractional, low spur requirement | Fractional N PLL with Delta Sigma Modulator | | N is fractional, simple design | Fractional N PLL with Accumulator |

DSM order selection (when using Frac-N DSM):

• Order 1: simplest, highest spurs at fPFD/denom
• Order 2: good balance for most designs
• Order 3-4: lowest spurs, but more quantization noise energy pushed to high offsets (requires adequate filter attenuation)
• Match datasheet DSM order if available; default to order 3

R-divider tradeoff (when fRef ≠ fComp):

• Using R-counter: fComp = fRef/R → N_eff = fVco/fComp = N×R
• In-band noise penalty: +20×log10(N_eff) — larger N hurts in-band PN
• Only use R > 1 when channel spacing requires it (fComp = channel step)

Spec-driven steps:

1. Gather specs (Directive 1) → present Design Plan (Directive 5, Step A)
2. If VCO PN data available: validate VCO standalone first (see below)
3. Select architecture block from msbPllArchitectures (Strategy A — DEFAULT)
4. Design loop filter:
   • N ≤ 50: CompSelectionMethod='Automatic' with Fc and Phi
   • N > 50 (P79): thirdOrderPassiveFilterDesign → CompSelectionMethod='Manual'
   • N threshold applies to effective N (including fractional part)
5. Build model, simulate, present results

VCO standalone validation (when PN data provided):

% 1. Create VCO testbench model
vcoModel = 'VCO_Validation';
new_system(vcoModel); open_system(vcoModel);
set_param(vcoModel, 'Solver', 'VariableStepDiscrete');
add_block('msbPllFoundation/Ring Oscillator VCO', [vcoModel '/VCO']);
add_block('msbPllMeasurements/VCO Testbench', [vcoModel '/VCO TB']);
add_line(vcoModel, 'VCO TB/1', 'VCO/1', 'autorouting', 'smart');
add_line(vcoModel, 'VCO/1', 'VCO TB/1', 'autorouting', 'smart');

% 2. Get PeriodJitter and CornerFrequency from PN data
[pJitter, cFreq] = msblks.VCO.estimatePhaseNoiseCore(fVco, Foffset, PN_dBc);
set_param([vcoModel '/VCO'], 'Fo', num2str(fVco), ...
    'PeriodJitter', num2str(pJitter), 'CornerFrequency', num2str(cFreq));

% 3. Simulate and compare to datasheet (accept ±3 dB)
sim(vcoModel);
ud = get_param([vcoModel '/VCO TB'], 'UserData');

Skip to Phase 4.0 (Strategy A assembly) after deriving parameters.

C. Tune Existing Model (Meet a new spec)

Use when the user provides an existing .slx model and wants to meet a target (lock time, phase noise, spurs) without rebuilding from scratch.

Workflow:

1. Probe — extract current params: Fc, Phi, N, OutputCurrent, Kvco, CompSelectionMethod, filter components via get_param
2. Check for PLL Testbench — if missing or PLL input unconnected, ASK the user for fComp (P104). Add a PLL Testbench if needed.
3. Baseline sim — sim(model), read get_param(tbBlk, 'UserData') for lock time, frequency, phase noise. This is the ONLY valid baseline (P103).
4. Identify the lever:
   • Lock time too slow → increase Fc (BW ≈ 12/t_lock)
   • Phase noise too high in-band → decrease Fc, increase Icp, or reduce N
   • Spurs too high → increase filter order or narrow Fc
5. Redesign — set new Fc (and Phi if needed), keep CompSelectionMethod='Automatic' so the block recomputes filter components
6. Re-simulate — read testbench UserData. Iterate until spec is met.
7. Report — before/after comparison with trade-off notes

Key rules:

• NEVER estimate lock time from Vctrl settling (P103)
• NEVER guess fComp from Fo/N or RefFreq param (P104)
• Cap Fc at fPFD/10 for stability
• Use lock_time ≈ 12/Fc only for initial sizing, then verify with testbench

---

Availability Check (MANDATORY)

Before using ANY function or block, verify it exists. Check exist(func,'file') for key functions (thirdOrderPassiveFilterDesign, estimatePLLPhaseNoise, phaseNoiseMeasure, phaseNoiseToJitter) and exist(lib,'file')==4 for libraries (msbPllFoundation, msbPllMeasurements, msbPllArchitectures). If not found, do NOT use — skip dependent steps.

---

Phase 1: Extract Datasheet Parameters

1.0 Reading the Datasheet PDF

Use MATLAB's extractFileText (never read PDFs directly with the Read tool):

pdfPath = 'path/to/datasheet.pdf';
txtContent = extractFileText(pdfPath);
txtPath = strrep(pdfPath, '.pdf', '_extracted.txt');
fid = fopen(txtPath, 'w'); fprintf(fid, '%s', txtContent); fclose(fid);
fprintf('Extracted %d characters to: %s\n', strlength(txtContent), txtPath);

1.1 Architecture Identification

Determine the PLL topology from the functional block diagram:

| Question | Typical Options