matlab-integrate-pcb-circuit

# 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

| Task | Code |
|------|------|
| Cascade two components | `out = pcbcascade(comp1, comp2)` |
| Cascade with rectangular board | `out = pcbcascade(comp1, comp2, 'RectangularBoard', true)` |
| Interactive cascade | `pcbcascade(comp1, comp2, 'Interactive', true)` |
| Create circuit element | `elem = pcbElement(comp)` |
| Set analysis ports | `elem.AnalysisPorts = {1, 2}` |
| Attach lumped elements | `elem.PortNumber = {3, 4}; elem.PortValue = {capacitor(2.2e-12), resistor(50)}` |
| Add to RF circuit | `add(ckt, [1 2 0 0], elem)` |
| Export to Touchstone | `rfwrite(sp, 'comp.s2p')` |
| Export with options | `rfwrite(sp, 'comp.s2p', FrequencyUnit='GHz', Format='DB')` |

## 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

```matlab
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

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

### RectangularBoard Option

| Value | Behavior |
|-------|----------|
| `true` | Creates a rectangular dielectric board around the cascaded layout |
| `false` (default) | Uses the natural board shape from the component geometries |

### Interactive Cascade Mode

For visual port alignment:

```matlab
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:

```matlab
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

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

### Behavioral vs Full-Wave

```matlab
% 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

```matlab
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

```matlab
% 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 lo