matlab-analyze-em

# Analyzing EM Performance of RF PCB Components

## When to Use

- Extracting S-parameters from any RF PCB component (catalog or custom pcbComponent)
- Comparing MoM vs FEM solvers or selecting the right solver for a structure
- Using interpolating sweeps or frequencySweep objects for faster multi-frequency analysis
- Controlling mesh density for accuracy vs speed tradeoffs
- Visualizing E/H fields, surface currents, or charge distributions
- Using behavioral (analytic) S-parameter models for fast estimates or optimization

## When NOT to Use

- Building or assembling custom PCB structures — use `matlab-assemble-pcb-layout`
- Designing standard transmission lines or catalog objects — use `matlab-design-pcb-txline`
- Defining dielectric or metal materials — use `matlab-manage-pcb-material`
- Cascading or connecting multiple components into circuits — use `matlab-integrate-pcb-circuit`
- Importing PCB layouts from Gerber, ODB++, or Allegro — use `matlab-read-pcb-layout`

## Typical Workflow

1. **Before:** `matlab-manage-pcb-material` — substrate/conductor setup; then a design skill or `matlab-assemble-pcb-layout` — create the component
2. **This skill:** Extract S-parameters, visualize fields and currents, verify performance
3. **After:** `matlab-optimize-pcb-design` — tune dimensions if specs not met → `matlab-integrate-pcb-circuit` — cascade into larger network → `matlab-write-pcb-layout` — export Gerber

## Quick Reference

| Task | Code |
|------|------|
| S-parameters (MoM) | `sp = sparameters(obj, freq, 'SweepOption', 'interp')` |
| S-params with port Z0 | `sp = sparameters(obj, freq, 50, 'SweepOption', 'interp')` |
| Interpolating sweep | `sp = sparameters(obj, freq, 50, 'SweepOption', 'interp')` |
| Interp with gradient | `sp = sparameters(obj, freq, 50, 'SweepOption', 'interpWithGrad')` |
| Plot S-params | `rfplot(sp)` or `rfplot(sp, [2 1], 1)` |
| Current distribution | `current(obj, fc)` |
| Charge distribution | `charge(obj, fc)` |
| Feed current | `feedCurrent(obj, freq)` |
| E/H fields | `[e, h] = EHfields(obj, fc, points)` |
| Set mesh | `mesh(obj, 'MaxEdgeLength', val)` |
| Memory estimate | `memoryEstimate(obj, fc)` |
| Switch to FEM solver | `pcb.SolverType = 'FEM'` |
| FEM boundary condition | `s = solver(pcb); s.BoundaryCondition = 'absorbing'` |
| Frequency sweep object | `fsweep = frequencySweep; sp = sparameters(obj, freq, 'SweepOption', fsweep)` |
| Rational model from sweep | `rmodel = getRationalModel(fsweep)` |
| Discover methods | `methods(obj)` |

## S-Parameter Extraction

The `sparameters` function is the primary analysis method for all RF PCB components.

### Basic Usage

```matlab
obj = design(couplerBranchline, 5e9);
freq = linspace(1e9, 10e9, 101);
sp = sparameters(obj, freq, 'SweepOption', 'interp');
figure;
rfplot(sp);
```

### Specifying Port Impedance

```matlab
sp = sparameters(obj, freq, 50, 'SweepOption', 'interp');   % 50-ohm reference
sp = sparameters(obj, freq, 75, 'SweepOption', 'interp');   % 75-ohm reference
```

### Plotting Specific S-Parameters

```matlab
rfplot(sp, [2 1], 1);              % Plot S21 only
rfplot(sp, [1 1], 1);              % Plot S11 only
rfplot(sp, 2:4, 1);               % Plot S21, S31, S41 vs port 1
```

### Extracting Numeric Data

```matlab
sp = sparameters(obj, freq, 'SweepOption', 'interp');
S21_dB = 20*log10(abs(squeeze(sp.Parameters(2,1,:))));
S11_dB = 20*log10(abs(squeeze(sp.Parameters(1,1,:))));
```

## Solver Selection

RF PCB Toolbox supports two electromagnetic solvers:

| Solver | Property Value | Best For |
|--------|---------------|----------|
| Method of Moments (MoM) | `'MoM'` (default) | Planar structures, open radiators |
| Finite Element Method (FEM) | `'FEM'` | Shielded catalog elements; also available on pcbComponent via SolverType |

### Switching to FEM

FEM is available via `pcbComponent`:

```matlab
pcb = pcbComponent(couplerBranchline);
pcb.SolverType = 'FEM';
sp_fem = sparameters(pcb, freq);
```

### FEM Boundary Condition Configuration

After setting `SolverType` to `'FEM'`, retrieve the solver object via `solver()` to configure boundary conditions:

```matlab
pcb = pcbComponent(catalogObj);
pcb.SolverType = 'FEM';

s = solver(pcb);                          % Returns em.solvers.fem.FEM object
s.BoundaryCondition = 'absorbing';        % or 'perfectly-matched-layer' (default)
```

| Boundary Condition | Value | Use Case |
|--------------------|-------|----------|
| Perfectly Matched Layer (PML) | `'perfectly-matched-layer'` (default) | Open radiating structures, antennas |
| Absorbing | `'absorbing'` | Shielded enclosures, waveguide ports |

**Gotcha:** `solver(comp, 'SolverType', 'FEM')` errors with "Too many input arguments." `SolverType` is a property of `pcbComponent`, not an argument to `solver()`. `BoundaryCondition` is a property of the returned FEM solver object, not of the component.

### FEM Prerequisites

The FEM solver (introduced R2025a) requires two dependencies:

1. **Integro-Differential Modeling Framework for MATLAB (IDMF)** — Install via Home > Add-Ons > search "Integro-Differential Modeling Framework for MATLAB". Verify with `matlab.addons.installedAddons`.
2. **Windows Subsystem for Linux (WSL)** — Required on Windows. Install via `wsl --install` from an elevated PowerShell prompt. Verify with `wsl --status`.

If WSL is available, the FEM solver can be used when designing custom structures via pcbComponent. For shielded catalog elements, FEM is used automatically.

**Firewall note:** Windows Defender may block the PostgreSQL server used by IDMF (`<matlabroot>\sys\postgresql\win64\PostgreSQL\bin\postgres.exe`). If FEM solves hang on first use, inform the user of this potential cause and defer to them on what action to take per their IT/security policies. Do not modify firewall settings autonomously.

### WSL Memory Tuning

WSL is allocated only **50% of system RAM** by default. Large FEM problems may fail with out-of-memory errors. If the user hits OOM during an FEM solve,