matlab-integrate-pcb-circuit

name: matlab-integrate-pcb-circuit description: "Cascade PCB components, add lumped elements, export Touchstone, and bridge to eye diagram or antenna array workflows. TRIGGER: user asks to cascade or connect multiple RF PCB components, add lumped R/L/C, export S-parameters to Touchstone, or combine PCB elements into a circuit. Invoke BEFORE writing pcbcascade or circuit code — cascade rules and port matching are non-obvious. SKIP: designing individual components (use the specific matlab-design-pcb-* skill), EM analysis of a single component (use matlab-analyze-em), material/stackup setup only (use matlab-manage-pcb-material), optimization (use matlab-optimize-pcb-design)." license: MathWorks BSD-3-Clause metadata: author: MathWorks version: "1.0"

Cascading and Integrating RF PCB Components

When to Use

• Cascading two or more PCB components end-to-end with pcbcascade
• Wrapping PCB components as circuit elements with pcbElement for RF Toolbox
• Loading internal ports with lumped elements (varactors, terminators)
• Exporting S-parameters to Touchstone files via rfwrite
• Integrating RF PCB feed networks with antenna arrays
• Bridging to Signal Integrity Toolbox for eye diagram analysis

When NOT to Use

• Designing individual filters, couplers, or transmission lines — use the respective designing skill
• Building custom PCB geometry from scratch — use matlab-assemble-pcb-layout
• Running EM analysis on a single component — use matlab-analyze-em
• Setting up materials — use matlab-manage-pcb-material

Typical Workflow

1. Before: Design skills (matlab-design-pcb-filter, matlab-design-pcb-coupler, etc.) or matlab-analyze-em — create and validate individual components
2. This skill: Cascade components, add lumped elements, export Touchstone, bridge to eye diagram analysis
3. After: matlab-write-pcb-layout — export final design to Gerber; or feed S-parameters into Signal Integrity Toolbox workflows

Quick Reference

pcbcascade — Connecting Components End-to-End

The pcbcascade function joins two RF PCB components port-to-port, producing a single pcbComponent for full-wave analysis.

Basic Cascade

HPF = filterStub;
HPF.StubShort = [1 1 1 1 1];
HPF.Height = 0.508e-3;
% ... set HPF properties ...

LPF = filterStepImpedanceLowPass;
LPF.Height = 0.508e-3;
LPF = design(LPF, 7e9);

BPF = pcbcascade(LPF, HPF, "RectangularBoard", true);
show(BPF);

Analyzing the Cascade

freq = linspace(1e6, 12e9, 51);
sp = sparameters(BPF, freq, 'SweepOption', 'interp');
rfplot(sp);

RectangularBoard Option

Interactive Cascade Mode

For visual port alignment:

pcbcascade(comp1, comp2, 'Interactive', true);

This launches a GUI that lets you visually connect ports and adjust spacing.

Multi-Stage Cascade

Chain more than two components by cascading sequentially:

stage1 = design(filterStepImpedanceLowPass, 5e9);
stage2 = design(microstripLine, 5e9);
stage3 = design(filterStepImpedanceLowPass, 5e9);

% Match substrates — design() defaults differ across object types
stage2.Substrate = stage1.Substrate;
stage2.Height = stage1.Height;
stage2.Conductor = stage1.Conductor;
stage3.Substrate = stage1.Substrate;
stage3.Height = stage1.Height;
stage3.Conductor = stage1.Conductor;

% Cascade stage1 + stage2, then result + stage3
intermediate = pcbcascade(stage1, stage2, 'RectangularBoard', true);
final = pcbcascade(intermediate, stage3, 'RectangularBoard', true);
show(final);

Cascade Requirements

• Both components must share the same substrate (Height, Substrate)
• Port line widths should match at the connection interface
• Components connect at their port edges (port 2 of comp1 to port 1 of comp2)

pcbElement — RF Toolbox Circuit Integration

pcbElement wraps an RF PCB component as a circuit element usable in the RF Toolbox circuit framework. This enables hybrid distributed+lumped modeling.

Basic Usage

comp = design(couplerBranchline, 5e9);
elem = pcbElement(pcbComponent(comp));
S = sparameters(elem, linspace(3e9, 7e9, 51), 'SweepOption', 'interp');
rfplot(S);

Behavioral vs Full-Wave

% Behavioral model (fast, uses analytic approximation)
elem = pcbElement(comp, 'Behavioral', true);

% Full-wave solve (accurate, uses MoM)
elem = pcbElement(comp, 'Behavioral', false);

Not all components support behavioral mode. If unsupported, a warning is issued and full-wave is used automatically.

Adding pcbElement to a Circuit

ckt = circuit;
c1 = interdigitalCapacitor;
c2 = interdigitalCapacitor('NumFingers', 3);
p = pcbElement(c2, 'Behavioral', false);
add(ckt, [1 2 0 0], c1);    % Default pcbElement created automatically
add(ckt, [2 3 0 0], p);
setports(ckt, [1 0], [3 0]);
S = sparameters(ckt, 8e9);

Hybrid Distributed+Lumped Modeling with Internal Ports

The most powerful use of pcbElement is connecting lumped components (capacitors, resistors, inductors) to internal ports on an EM structure. This models tunable filters with varactors, loaded resonators, and bias-T networks.

Concept

1. Define extra FeedLocations on the PCB as internal port pairs
2. Wrap with pcbElement
3. Assign AnalysisPorts (external I/O ports for S-parameter extraction)
4. Assign PortNumber (internal port indices to load)
5. Assign PortValue (lumped elements connected at those ports)

Pattern: Loaded Coupler with Terminations

% Start with a 4-port coupler
comp = design(couplerRatrace, 5e9);
pcb = pcbComponent(comp);

% Create pcbElement
elem = pcbElement(pcb);

% Ports 1,2 are external I/O (for S-parameter extraction)
elem.AnalysisPorts = {1, 2};

% Ports 3,4 are loaded with lumped elements
elem.PortNumber = {3, 4};
elem.PortValue = {resistor(50), resistor(50)};

% Analyze the 2-port network with internal loads
S = sparameters(elem, linspace(3e9, 7e9, 51), 'SweepOption', 'interp');
rfplot(S);

Pattern: Tunable Filter with Varactors

% Design a filter with extra internal feed points for varactors
pcb = pcbComponent;
% ... build custom filter geometry with internal feed pads ...
% FeedLocations rows 1,2 = external I/O
% FeedLocations rows 3,4 and 5,6 = varactor pads (internal port pairs)

pcb.FeedLocations = [x1 y1 1 3;    % Port 1: input
                     x2 y2 1 3;    % Port 2: output
                     x3 y3 1 3;    % Port 3: varactor pad A+
                     x4 y4 1 3;    % Port 4: varactor pad A-
                     x5 y5 1 3;    % Port 5: varactor pad B+
                     x6 y6 1 3];   % Port 6: varactor pad B-

elem = pcbElement(pcb);
elem.AnalysisPorts = {1, 2};
elem.PortNumber = {{3,4}, {5,6}};
elem.PortValue = {capacitor(2.2e-12), capacitor(2.2e-12)};

S = sparameters(elem, linspace(1e9, 10e9, 51), 'SweepOption', 'interp');
rfplot(S);

Supported PortValue Types

PortNumber Formats

% Single-port loads (each port terminated individually)
elem.PortNumber = {3, 4};
elem.PortValue = {resistor(50), resistor(50)};

% Port-pair loads (2-port element connected across a pair)
elem.PortNumber = {{3,4}, {5,6}};
elem.PortValue = {capacitor(2.2e-12), nport('varactor.s2p')};

Antenna Integration

Integrate RF PCB feed networks with Antenna Toolbox arrays.

Corporate Divider + Patch Array

% Design corporate power divider
pdc = powerDividerCorporate;
pdc = design(pdc, 5e9);
pdc.NumOutputPorts = 4;
pdc.PortSpacing = physconst('lightspeed') / 5e9;

% Design patch antenna
ant = patchMicrostripInsetfed;
ant.Substrate = dielectric('Teflon');
ant = design(ant, 5e9);

% Convert to pcbStack for shape extraction
pcbant = pcbStack(ant);
TopLayer = pcbant.Layers{1};

% Create linear array of patches
for i = 2:4
    a = copy(TopLayer);
    a = translate(a, [0, pdc.PortSpacing*(i-1), 0]);
    TopLayer = TopLayer + a;
end

% Merge divider and antenna array into single pcbStack
pcbcomp = pcbComponent(pdc);
pcbant1 = pcbStack;
pcbant1.BoardShape = pcbcomp.BoardShape;
pcbant1.BoardThickness = pcbcomp.BoardThickness;
pcbant1.Layers = pcbcomp.Layers;
pcbant1.FeedDiameter = pcbcomp.FeedDiameter;
pcbant1.FeedLocations = pcbcomp.FeedLocations(1,:);  % Keep only input port

% Combine top layers
pcbant1.Layers{1} = pcbant1.Layers{1} + TopLayer;
show(pcbant1);

pcb2D Cross-Section and Crosstalk

For pcb2D cross-section analysis, trace2D setup, RLGC extraction, slice(), and crosstalk with coupled traces, see matlab-design-pcb-txline.

Exporting S-Parameters to Touchstone Files

Use rfwrite to save computed S-parameters as Touchstone files for reuse in other tools or simulations.

Basic Export

sp = sparameters(pcbComponent, freq, 'SweepOption', 'interp');
rfwrite(sp, 'component.s2p');

rfwrite Options

rfwrite(sp, 'filter_2p4GHz.s2p', FrequencyUnit='GHz', Format='DB');

Load Touchstone as nport

n = nport('component.s2p');
% Use in any RF Toolbox circuit
add(ckt, [1 2], n);

The file extension (.s2p, .s4p, etc.) is selected automatically by rfwrite based on port count.

Advanced Integration Patterns

Nolen Matrix Beam-Forming

A Nolen matrix uses cascaded branchline couplers and phase shifters to create an N×N beam-forming network. Build by cascading individual RF PCB components:

coupler = design(couplerBranchline, fc);
ps = design(phaseShifter, fc, PhaseShift=90);
% Extract S-parameters for each, then cascade via circuit()
ckt = circuit;
add(ckt, [1 2 3 4], nport(sparameters(coupler, freq, 'SweepOption', 'interp')));
add(ckt, [3 5], nport(sparameters(ps, freq, 'SweepOption', 'interp')));
% ... build full N×N matrix

Monopulse Comparator

An X-band monopulse comparator uses four ratrace couplers to generate sum and difference beams:

rr = design(couplerRatrace, fc);
S_rr = sparameters(rr, freq, 'SweepOption', 'interp');
% Build 4-coupler comparator network using circuit()

Amplifier Matching Networks

Use microstrip tee junctions and stubs to create input/output matching networks, then cascade with amplifier S-parameters:

% Build matching network as pcbComponent
tee = traceTee(Length=[L1, L2], Width=[W1, W2]);
pcb = pcbComponent(tee);
pcb.Substrate = dielectric("FR4");
S_match = sparameters(pcb, freq, 'SweepOption', 'interp');

% Load amplifier S-parameters and cascade
amp = nport('amplifier.s2p');
ckt = circuit;
add(ckt, [1 2 0 0], nport(S_match));     % Input match
add(ckt, [2 3 0 0], amp);                 % Amplifier
add(ckt, [3 4 0 0], nport(S_match));     % Output match
setports(ckt, [1 0], [4 0]);
S_total = sparameters(ckt, freq);

FEXT/NEXT with Parallel Link Designer

Full-wave EM results from pcb2D can be exported to Signal Integrity Toolbox for system-level analysis:

cs = pcb2D;
% ... configure traces, substrate
[r, l, g, c] = rlgc(cs, freq);
% Export to Parallel Link Designer for eye diagram analysis

Optimization via S-Parameter Connection Formula

When searching for the optimal lumped element to bridge a gap or load an internal port, re-solving EM for every candidate value is prohibitively slow. Instead, extract the N-port S-matrix once and sweep element values analytically using S-parameter network math.

Pattern: Extract Once, Sweep Analytically

% 1. Build 4-port structure (2 external + 2 internal ports at the gap)
pcb = pcbComponent;
% ... set up geometry with 4 feeds ...
freq = linspace(9e9, 11e9, 101);
S4 = sparameters(pcb, freq, 50, 'SweepOption', 'interp');  % Solve once

% 2. Partition the 4-port S-matrix into external (1,2) and internal (3,4)
S = S4.Parameters;
S11 = S(1:2, 1:2, :);  S12 = S(1:2, 3:4, :);
S21 = S(3:4, 1:2, :);  S22 = S(3:4, 3:4, :);

% 3. Sweep element impedance analytically (no EM re-solve)
Z0 = 50;
Zvals = linspace(1, 500, 1000);  % Candidate impedances
bestS11 = 0;  bestZ = NaN;

for k = 1:numel(Zvals)
    Gamma_L = (Zvals(k) - Z0) / (Zvals(k) + Z0);
    GammaM = Gamma_L * eye(2);
    % S-parameter connection: S_ext = S11 + S12*GammaM*inv(I - S22*GammaM)*S21
    for fi = 1:size(S,3)
        Sext = S11(:,:,fi) + S12(:,:,fi) * GammaM / ...
            (eye(2) - S22(:,:,fi) * GammaM) * S21(:,:,fi);
        s11_dB = 20*log10(abs(Sext(1,1)));
        if s11_dB < bestS11
            bestS11 = s11_dB;  bestZ = Zvals(k);
        end
    end
end

When to Use

This technique is orders of magnitude faster than re-solving EM per iteration — Task 8 swept 1000 impedance values in seconds vs. hours of EM solves.

Pitfalls

1. pcbcascade substrate match: Both components must have identical Substrate, Height, and Conductor. design() uses different defaults for different object types (e.g. filterStepImpedanceLowPass defaults to a custom dielectric while microstripLine defaults to Teflon). Always copy substrate properties from one component to the other before calling pcbcascade.

2. Port width matching: When cascading, the port line width of comp1's output port should match comp2's input port width. Mismatched widths cause impedance discontinuities that aren't physical.

3. pcbElement port ordering: AnalysisPorts indices must be a subset of the feed indices defined in FeedLocations. Port 1 in AnalysisPorts corresponds to the first row of FeedLocations.

4. PortNumber vs AnalysisPorts: Ports listed in PortNumber are loaded with lumped elements and NOT available as external analysis ports. Don't include the same port index in both AnalysisPorts and PortNumber.

5. Behavioral mode availability: Not all catalog objects support Behavioral=true. The behavioral model is a fast approximation — use Behavioral=false for final design validation.

6. Corporate divider + antenna assembly: When combining shapes with +, ensure they physically overlap or touch. Disjoint shapes create disconnected geometry that won't simulate correctly.

7. No design() for filterStub: filterStub does not support design(). Set stub dimensions manually.

8. pcbElement Behavioral default is true: When wrapping a catalog object, Behavioral defaults to true (fast analytic). Set Behavioral=false explicitly for full-wave accuracy.

9. Port renumbering after cascade: pcbcascade(comp1, comp2, portA, portB) connects comp1:portA to comp2:portB — those two ports disappear. Surviving ports are renumbered: comp1's remaining ports first (in original order, skipping portA), then comp2's remaining ports (skipping portB). Example: comp1 has ports [1,2], comp2 has ports [1,2,3]. pcbcascade(comp1, comp2, 2, 1) produces combined ports: [comp1:1, comp2:2, comp2:3]. Always verify with show(combined).

10. Ground plane continuity in antenna cascades: By default, pcbcascade does not merge ground planes. Use 'GroundFloodFill', true for a continuous ground plane, which is essential for microstrip-fed antennas: pcbcascade(feed, ant, 2, 1, 'GroundFloodFill', true).

11. SI frequency sampling: Use at least 400 frequency points for wideband SI channels. Too few points cause artifacts in time-domain conversion (eye diagrams).

12. pcbcascade does not accept lumped elements: pcbcascade only connects pcbComponent objects. To combine a PCB component with lumped resistor/capacitor/inductor elements, use the circuit() object: wrap the PCB component with pcbElement, then add() both the pcbElement and lumped elements to a circuit with node connections and setports(). Example:

pe = pcbElement(comp); pe.Name = 'txline';
C = capacitor(100e-12); C.Name = 'Cblock';
R = resistor(50); R.Name = 'Rterm';
ckt = circuit('modified');
add(ckt, [1 2], C);        % Series DC block
add(ckt, [2 3], pe);       % PCB element
add(ckt, [3 0], R);        % Shunt termination
setports(ckt, [1 0], [3 0]);
S = sparameters(ckt, freq);

Related Skills

• matlab-design-pcb-filter — Filter objects for cascade
• matlab-design-pcb-coupler — Coupler/splitter objects for cascade
• matlab-assemble-pcb-layout — Custom geometry with pcbComponent
• matlab-analyze-em — S-parameter extraction and field analysis

Copyright 2026 The MathWorks, Inc.