version: "1.0.1" name: matlab-model-via description: "Via modeling: pads, antipads, ground return vias, GRV placement, and signal integrity for high-speed layer transitions. TRIGGER: user asks to model a via, design a via transition, place ground return vias, analyze via performance, or check signal integrity through layer transitions. Invoke BEFORE writing code — only viaSingleEnded exists (no viaDifferential), and the location format is non-obvious. SKIP: general signal integrity without vias (use matlab-analyze-em), transmission line design (use matlab-design-pcb-transmission-line), PDN analysis (use matlab-analyze-pcb-pdn), material/stackup setup only (use matlab-manage-pcb-material)." license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Modeling Vias

When to Use

• Modeling signal vias through multi-layer PCB stackups (viaSingleEnded)
• Configuring pad and antipad geometry per layer
• Placing ground return vias for signal integrity
• Analyzing via S-parameters and identifying barrel resonances
• Evaluating GRV placement with criticalwavelength and gapratedistance

When NOT to Use

• Designing transmission lines or impedance control — use matlab-design-pcb-transmission-line
• Building custom PCB structures from shapes — use matlab-assemble-pcb-layout
• Setting up substrate or conductor materials — use matlab-manage-pcb-material
• Running full-wave EM analysis on non-via structures — use matlab-analyze-em
• PDN analysis on imported boards — use matlab-analyze-pcb-pdn

Typical Workflow

1. Before: matlab-manage-pcb-material — set up substrate and conductor for the stackup
2. This skill: Model the via, place GRVs, check signal integrity
3. After: matlab-integrate-pcb-circuit — cascade via model with trace/connector models → matlab-optimize-pcb-design — optimize GRV placement or pad geometry

Quick Reference

viaSingleEnded Object

The viaSingleEnded object models signal vias through multi-layer PCB stackups with configurable pads, antipads, and ground return vias.

Basic Setup

via = viaSingleEnded;
via.SignalLayer = [1 5];
via.GroundLayer = [3 7 9];
via.Substrate = dielectric("Name","FR4","EpsilonR",4.8,...
    "LossTangent",0.026,"Thickness",1.27e-4,"Frequency",1e8);
via.Conductor = metal("Copper");
show(via);

Key Properties

Signal Via Configuration

Placing a Signal Via

via = viaSingleEnded;
via.SignalLayer = [1 5];
via.GroundLayer = [3 7 9];
 
X = 0; Y = 0;
startLayer = 1;
stopLayer = 7;
via.SignalViaLocations = [X Y startLayer stopLayer];

The via barrel spans from startLayer to stopLayer. Signal connections occur on layers listed in SignalLayer that fall within this range.

Via Diameter

via.SignalViaDiameter = 0.25e-3;          % Drill diameter
via.SignalViaFinishedDiameter = 0.20e-3;  % After copper plating

Unit Conversion Helper

The object provides a built-in mils-to-meters conversion:

via.SignalViaDiameter = 10 * via.mils2meters;   % 10 mils

Port Definition (SignalTable)

The SignalTable property defines which layers become ports for S-parameter extraction.

Format

Each row: {signalViaNumber, layerIndex, traceWidth, direction}

• signalViaNumber: Which signal via (1-based index into SignalViaLocations)
• layerIndex: The layer where the port is placed
• traceWidth: Width of the connecting trace (meters)
• direction: Angle in degrees (0 = +x direction, 90 = +y, etc.)

Example: Two-Port Via

via.SignalTable = {1, 1, 3e-4, 45;   % Port 1: via 1, layer 1, 0.3mm trace, 45 deg
                   1, 5, 3e-4, 0};    % Port 2: via 1, layer 5, 0.3mm trace, 0 deg

Using Table Syntax for Clarity

vPorts = table('Size', [2 4], ...
    'VariableTypes', ["cell","cell","cell","cell"], ...
    'VariableNames', ["Signal Via Num","Layer","Trace Width","Direction"]);
vPorts(1,:) = {{1} {1} {3e-4} {45}};
vPorts(2,:) = {{1} {5} {3e-4} {0}};
via.SignalTable = vPorts.Variables;

Ground Return Vias

Ground return vias provide a low-impedance return path near the signal via, critical for signal integrity.

Placement

via.GroundReturnViaLocations = [
    1.0015  2.001  1  9;
    1.0015  1.999  1  9;
    0.999   1.999  1  9;
    1.000   2.0015 1  9;
    0.999   2.001  1  9;
    1.0001  1.9987 1  9];

Each row: [x, y, startLayer, stopLayer]. Ground return vias typically span from the topmost to the bottommost ground layer.

GRV Diameter

via.GroundReturnViaDiameter = 0.25e-3;
via.GroundReturnViaFinishedDiameter = 0.20e-3;

These can be scalars (same for all GRVs) or vectors (one per GRV).

Pad and Antipad Customization

Viewing Pad/Antipad Tables

padsTable(via)       % Rows = signal vias, Columns = conductive layers; cells are pad shape objects (e.g. antenna.Circle) or []. Scalar SignalViaPad is expanded across all positions.
antipadsTable(via)            % Signal via antipads: rows = signal vias, columns = connected layers
antipadsTable(via, "ground")  % Ground return via antipads: rows = GRVs, columns = power planes

Default Pad Shape

By default, SignalViaPad is a circle:

via.SignalViaPad.Radius = 3e-4;    % Set pad radius

Per-Layer Pad Customization

Use getpads to get a cell array of pad shapes (one per layer), modify individual entries, then reassign:

pad_temp = getpads(via);
pad_temp{3}.Radius = 4.5e-4;   % Customize pad on the 3rd layer
via.SignalViaPad = pad_temp;

Antipad Customization

via.SignalViaAntipad.Radius = 5e-4;   % Clearance radius on ground layers
 
% Per-layer antipad customization (cell array: SignalViaLocations × GroundLayer)
antipad_temp = getantipads(via);
antipad_temp{1,2}.Radius = 6e-4;   % Customize antipad on 2nd ground layer
via.SignalViaAntipad = antipad_temp;

RemoveUnusedPads

When RemoveUnusedPads = true (default), pads are only placed on layers in SignalLayer. Set to false to place pads on all layers the via passes through:

via.RemoveUnusedPads = false;
padsTable(via)   % Now shows pads on all layers

Via Arrays

For modeling multiple signal vias (e.g., BGA breakout or bus routing):

Grid-Based Via Array

obj = viaSingleEnded;
obj.SignalLayer = [1 3];
obj.GroundLayer = [1 3];   % Mixed signal/ground layers
obj.Conductor = metal('Name','Copper','Thickness',3*obj.mils2meters,'Conductivity',10e9);
obj.Substrate = dielectric('EpsilonR',3.7,'LossTangent',0.03,'Thickness',12*obj.mils2meters);
obj.SignalViaDiameter = 10 * obj.mils2meters;
obj.SignalViaPad.Radius = 1.00001 * obj.SignalViaDiameter/2;
obj.SignalViaAntipad.Radius = 15 * obj.mils2meters;
 
% Create grid of all via positions
[X,Y] = meshgrid(1:8, 1:8);
allXYs = [X(:) Y(:)];
 
% Signal via subset
[X,Y] = meshgrid([1 3 5 8], [1 2 4 6 8]);
SVXYs = [X(:) Y(:)];
 
% Ground via locations = everything else
GRVXYs = setdiff(allXYs, SVXYs, 'rows');

Assigning Multiple Signal Vias

startLayer = 1; stopLayer = 3;
obj.SignalViaLocations = [SVXYs, repmat([startLayer stopLayer], size(SVXYs,1), 1)];
obj.GroundReturnViaLocations = [GRVXYs, repmat([startLayer stopLayer], size(GRVXYs,1), 1)];

Open Signal Vias (No Ports)

To model signal vias without assigning ports (open-circuited), leave SignalTable empty or assign ports only to specific vias:

% Only port via #1 on layers 1 and 3
obj.SignalTable = {1, 1, 5*obj.mils2meters, 0;
                   1, 3, 5*obj.mils2meters, 0};

All other signal vias remain as open (unported) stubs — useful for studying coupling in dense via fields.

Multi-Layer Stackup

Layer Numbering Convention

Layers alternate metal and dielectric, numbered sequentially:

Layer 1:  Metal (signal or ground)
Layer 2:  Dielectric
Layer 3:  Metal (signal or ground)
Layer 4:  Dielectric
Layer 5:  Metal (signal or ground)
...

Only odd-numbered layers are metal. SignalLayer and GroundLayer use these odd indices.

Example: 10-Layer Board

via = viaSingleEnded;
via.SignalLayer = [1 7];         % Signal on layers 1 and 7
via.GroundLayer = [3 5 9];      % Ground on layers 3, 5, and 9
via.Substrate = dielectric("Name","FR4","EpsilonR",4.4,...
    "LossTangent",0.02,"Thickness",0.1e-3);

The substrate Thickness is the thickness of each dielectric layer (uniform). For non-uniform stackups, use a multi-element dielectric.

Analysis

S-Parameters

freq = linspace(1e9, 20e9, 51);
sp = sparameters(via, freq, 'Behavioral', true);
rfplot(sp);
 
% Verify insertion loss meets threshold across band
S21_dB = 20*log10(abs(squeeze(sp.Parameters(2,1,:))));
idx = find(S21_dB <= -1, 1);
if isempty(idx), fprintf('PASS: IL < 1 dB across band\n');
else, fprintf('FAIL: IL exceeds 1 dB at %.1f GHz\n', sp.Frequencies(idx)/1e9); end

TDR (Time Domain Reflectometry)

Use the tdr function from the Signal Integrity Toolbox. Thumb rules for parameters: RiseTime = 1/fmax, SampleTime = 1/(100*fmax), EndTime = 0.1e-9, where fmax is the maximum frequency of the S-parameter sweep:

fmax = 20e9;
tdrObj = tdr(sp, RiseTime=1/fmax, SampleTime=1/(100*fmax), EndTime=0.1e-9);
plot(tdrObj)

SI Analysis Functions

Two functions help evaluate whether ground return vias are close enough to the signal via at a target frequency:

% Check resonance risk at 28 GHz
cw = criticalwavelength(via, 28e9);
 
% Plot max allowable GRV distance vs frequency
freq = linspace(1e9, 56e9, 200);
gapratedistance(via, freq);
 
% Stricter threshold (0.125 instead of default 0.25)
gapratedistance(via, freq, 0.125);

Use criticalwavelength to spot-check a specific frequency of concern. Use gapratedistance to generate a curve showing how tight GRV placement must be across a frequency range. Both require at least one ground return via to be defined.

Gotcha: criticalwavelength(via) requires a frequency argument. Omitting it will error.

Identifying Via Resonances

Via barrel resonances appear as sharp dips in S21 (insertion loss) during a wideband sweep. To find them:

1. Sweep well beyond the signaling bandwidth (at least 2-3x the Nyquist frequency).
2. Use fine frequency resolution (300-500 points) so narrow dips are not missed.
3. Plot S21 and look for notches; their frequencies correspond to resonant modes of the via barrel bounded by the ground planes.

% Wideband sweep to identify resonances
via = viaSingleEnded;
freq = linspace(1e9, 50e9, 500);
s = sparameters(via, freq);
 
% Insertion loss — dips indicate barrel resonances
figure;
rfplot(s, 2, 1);
title('Via Insertion Loss — Check for Resonance Dips');
 
% Return loss — peaks correspond to the same resonances
figure;
rfplot(s, 1, 1);
title('Via Return Loss');

Moving ground return vias closer to the signal via pushes resonances to higher frequencies. Use criticalwavelength at the dip frequency to confirm the mechanism, and gapratedistance to determine how close GRVs must be to keep resonances above the band of interest.

Visualization

show(via);          % 3-D view with pads, antipads, and vias
layout(via);        % Top-down layout view

Note: viaSingleEnded uses a behavioral (circuit) model, not a full-wave MoM mesh. Functions like mesh, memoryEstimate, and getZ0 are not available on this object. To extract characteristic impedance, compute it from S-parameters or ABCD parameters post-solve.

High-Speed Via Design (40+ Gbps)

For high-speed signaling, ground return via (GRV) placement is critical to managing return path inductance and crosstalk.

GRV Placement Strategy

Sweep GRV configurations to find the minimum number of ground vias that meet insertion loss targets:

via = viaSingleEnded;
via.Substrate = dielectric('Name', {'FR4','FR4','FR4','FR4'}, ...
    'EpsilonR', [4.4, 4.4, 4.4, 4.4], ...
    'LossTangent', [0.02, 0.02, 0.02, 0.02], ...
    'Thickness', [0.5e-3, 0.5e-3, 0.5e-3, 0.5e-3], ...
    'Frequency', [1e9, 1e9, 1e9, 1e9], ...
    'FrequencyModel', {'DjordjevicSarkar','DjordjevicSarkar','DjordjevicSarkar','DjordjevicSarkar'});
 
% Parametric GRV placement — compare 1, 2, 4, 8 ground vias
for nGRV = [1, 2, 4, 8]
    via.GroundReturnViaLocations = generateGRVPositions(nGRV, pitch);
    S = sparameters(via, freq, 50);
    rfplot(S);
    hold on;
end

Differential Via Pairs

There is no viaDifferential class — model differential via pairs using viaSingleEnded with two entries in SignalViaLocations. For 40 Gbps differential pairs, manage crosstalk by controlling via-to-via spacing and GRV fence placement:

via = viaSingleEnded;
via.SignalViaLocations = [0, -pitch/2; 0, pitch/2];   % Differential pair
via.GroundReturnViaLocations = [                        % GRV fence
    -pitch, -pitch; -pitch, 0; -pitch, pitch;
     pitch, -pitch;  pitch, 0;  pitch, pitch];

Frequency Range Guidelines for Interface Standards

When analyzing vias for a specific interface, sweep S-parameters to at least the Nyquist frequency. For resonance checks, sweep to 2-3x Nyquist.

Use these ranges when setting up sparameters(via, freq) sweeps. For resonance identification, extend the upper limit by 2-3x beyond the Nyquist frequency shown above.

Pitfalls

1. Layer numbering alternates metal and dielectric: With the default viaSingleEnded constructor (no arguments), metal layers are odd (1, 3, 5, ...) and dielectric layers are even. With viaSingleEnded(N), soldermask layers are added and metal layers use even numbering (2, 4, 6, ...). Always check the object's SignalLayer and GroundLayer properties to confirm which indices are metal.

1. SignalViaLocations and GroundReturnViaLocations require 4 columns: Each row must be [x y startLayer stopLayer]. Do NOT use 2-column [x y] — it will error or produce invalid geometry. Example: via.SignalViaLocations = [0 0 1 9] (not [0 0]).

1. SignalTable viaNum must match SignalViaLocations: The first column of SignalTable indexes into SignalViaLocations rows. If you have 3 signal vias, valid via numbers are 1, 2, 3.

1. Pad radius must exceed via radius: SignalViaPad.Radius must be larger than SignalViaDiameter/2. If they're equal or pad is smaller, the geometry is invalid.

1. Antipad vs pad clearance: The antipad is the clearance hole in ground planes. It must be larger than the pad to provide insulation. Typical rule: antipad radius >= pad radius + 0.1mm.

1. GRV span: Ground return vias should span at least from the signal entry layer to the signal exit layer. Shorter GRVs degrade return path quality at higher frequencies. Currently, ground return vias must always be PTH (full span of the stackup) and cannot be back-drilled.

1. mils2meters units: All geometric properties are in meters. Use via.mils2meters (= 2.54e-5) for conversion from mils: 10*via.mils2meters = 0.254mm.

1. Behavioral model only: viaSingleEnded uses a behavioral (circuit) model — not MoM. mesh(via), memoryEstimate(via, freq), and getZ0(via, freq) are not available. Use sparameters(via, freq, 'Behavioral', true) to suppress the "Switching to behavioral model" warning.

1. Direction in SignalTable: The direction angle determines where the trace exits the pad. Ensure traces from adjacent ports don't overlap — check with show(via).

1. Default GRV span may exceed stackup: The default GroundReturnViaLocations spans to layer 9 regardless of actual stackup size. Always set GroundReturnViaLocations explicitly to match your stackup's layer range.

1. Set geometry before getpads(): getpads() triggers checkDimensions() internally. All properties — including GroundReturnViaLocations — must be valid before calling it, or it will error.

1. Mixed layers (Signal and Ground) only at top/bottom: Only the top and bottom metal layers of the stackup can appear in both SignalLayer and GroundLayer. Middle layers cannot be mixed — MATLAB errors with "must be either assigned as a Ground Layer or a Signal Layer but not both." Mixed top/bottom layers enable vertical ports while providing ground references for the behavioral model.

1. Back-drilled vias must terminate on a ground (connected) layer: When modeling a back-drilled (non-PTH) signal via, the behavioral model requires the via's start/stop layer to be a ground (connected) layer or any bottom/top layer of the stackup. If the via ends on a signal-only layer, sparameters errors with "signal via must end on a connected layer."

1. "Vertical" is a valid direction in SignalTable: In addition to numeric angles (0, 90, 180, etc.), "Vertical" is an accepted value for the direction field in SignalTable. It creates a vertical port connection through the via barrel. Constraint: vertical ports are only valid on signal layers at the top or bottom of the full stackup.

1. `show(via, "View", "metal")`: Use the "View","metal" name-value pair to display only metal layers (pads, antipads, barrels) without dielectric fill.

1. Dielectric arrays must all match in size: When specifying a multi-layer substrate, Name, EpsilonR, LossTangent, Thickness, and Frequency must all have the same number of elements. If Name is a cell array with K entries, all other properties must also have K entries — otherwise MATLAB errors with "size of 'Thickness' (or 'Frequency') does not match number of layers specified in 'Name'." The default FrequencyModel is 'DjordjevicSarkar' (not 'Constant').

1. Dielectric layer count for `viaSingleEnded(N)`: When using viaSingleEnded(N) (N = number of conductive layers), the substrate requires a minimum of N dielectric layers. N-1 layers errors with "Incorrect number of Substrate: Expected N." Extra layers beyond N are added as soldermask (top/bottom). The default constructor creates N+1 dielectric layers (N-1 core/prepreg + 2 thin soldermask). Metal layers use even numbering (2, 4, 6, ...) with this constructor.

1. At least 2 ground planes required for S-parameter analysis: The behavioral model requires at least 2 ground (connected) layers in GroundLayer for sparameters to work. With only 1 ground plane, MATLAB errors with "At least 2 connected layers must be present for analysis." Use mixed top/bottom layers (pitfall #12) to satisfy this requirement on boards with fewer dedicated ground layers. Additionally, if power planes are present, there must be at least one ground plane above and below each power plane.

Related Skills

• matlab-manage-pcb-material — Substrate and conductor setup for via stackups
• matlab-analyze-pcb-pdn — Power distribution network analysis
• matlab-analyze-em — S-parameter extraction and mesh control
• matlab-integrate-pcb-circuit — serialLinkDesigner for eye diagram analysis
• matlab-assemble-pcb-layout — Using ViaLocations in pcbComponent

Copyright 2026 The MathWorks, Inc.