matlab-manage-sparameters

# S-Parameter I/O and Visualization

Load, inspect, visualize, and export S-parameters using the `sparameters` object and RF Toolbox plotting functions.

## When to Use

- Loading Touchstone files (.s1p, .s2p, .s4p, .snp) into MATLAB
- Extracting S-parameter values with `rfparam`
- Plotting S-parameters with `rfplot` or `smithplot`
- Computing group delay from S-parameter data
- Interpolating S-parameters to a new frequency grid with `rfinterp1`
- Changing reference impedance with `newref`
- Exporting S-parameters to Touchstone format with `rfwrite`

## When NOT to Use

- Converting between network parameter types (S, Z, Y, ABCD) -- use `matlab-convert-network-parameters`
- Cascading or de-embedding S-parameter networks -- use `matlab-deembed-rf-cascade`
- Fitting rational models to S-parameter data -- use `matlab-fit-rational-model`
- Amplifier stability or gain analysis -- use `matlab-analyze-rf-amplifier`

## Workflow

1. **Load** — Construct `sparameters` from Touchstone file, raw data, or circuit object
2. **Inspect** — Check ports, frequencies, impedance; extract parameters with `rfparam`
3. **Transform** — Interpolate with `rfinterp1`, re-reference with `newref`
4. **Visualize** — Plot with `rfplot`, `smithplot`, or compute group delay
5. **Export** — Write to Touchstone with `rfwrite`

## Core Object: `sparameters`

### Construction

```matlab
% From Touchstone file (most common)
s = sparameters('device.s2p');

% From raw complex data
s = sparameters(data, freq, Z0);       % data: N×N×K, freq: K×1 (Hz), Z0: scalar or vector

% From other network parameter objects
s = sparameters(yObj);                  % Y → S (uses yObj's impedance)
s = sparameters(zObj, 75);              % Z → S with explicit Z0

% From RF circuit objects
s = sparameters(circuitObj, freq);      % circuit, rffilter, nport, transmission line, RLC
```

### Properties

| Property | Description |
|----------|-------------|
| `Parameters` | N×N×K complex array — indexed as `(row, col, freqIdx)` |
| `Frequencies` | K×1 vector in Hz (ascending) |
| `Impedance` | Reference impedance — scalar or per-port vector |
| `NumPorts` | Number of ports (read-only) |

### Per-Port Reference Impedance (R2023a+)

```matlab
s = sparameters(data, freq, [50 75]);   % Port 1: 50 Ohm, Port 2: 75 Ohm
```

**Gotcha:** When `NumPorts == numel(Frequencies)`, MATLAB cannot distinguish per-port from per-frequency impedance. Use `reshape(z0, 1, 1, [])` to force frequency-dependent interpretation.

## Quality Checks

```matlab
ispassive(s)                            % true if max singular value of S <= 1 at all freqs
iscausal(s)                             % true if network is causal (no output before input)
p = passivity(s);                       % max singular value per frequency (passive where <= 1)
sp = makepassive(s);                    % enforce passivity by clipping singular values to <= 1
```

All four work directly on `sparameters` objects (no rational fit required). `passivity(s)` returns a vector showing *where* violations occur — useful for diagnostics before calling `makepassive`. `makepassive(s)` modifies data point-by-point — for optimization-based passivity enforcement on a fitted model, see `matlab-fit-rational-model`.

### IEEE P370 Quality Metrics (R2023b+)

```matlab
[cm, rm, pm] = ieee370QualityCheckFrequencyDomain(s);
% cm = causality metric (0-100, higher is better)
% rm = reciprocity metric (0-100)
% pm = passivity metric (0-100)
```

Returns percentage scores per the IEEE 370 standard — quantitative grades beyond pass/fail booleans. Accepts a `sparameters` object, filename, or raw 3-D array.

## Extracting Parameters

```matlab
s21 = rfparam(s, 2, 1);                % Complex S21 across all frequencies
s21_dB = 20*log10(abs(s21));            % Convert to dB magnitude
s21_phase = angle(s21)*180/pi;          % Phase in degrees
```

**Gotcha:** `rfparam` returns complex values, NOT dB. Always use `20*log10(abs(...))` for dB magnitude.

## Interpolation

```matlab
fNew = linspace(1e9, 6e9, 500);
sInterp = rfinterp1(s, fNew);          % Interpolate to new frequency grid
sExtrap = rfinterp1(s, fNew, 'extrap'); % Allow extrapolation outside original range
```

**Gotcha:** `rfinterp1` interpolates the **real and imaginary parts** of each S-parameter independently (like `interp1`), not magnitude and angle. This can produce artifacts near sharp resonances or rapid phase transitions.

## Change Reference Impedance

```matlab
s75 = newref(s, 75);                   % Re-reference from 50 to 75 Ohm
```

**Gotcha:** `sparameters(filename, Z0)` is not a valid call signature — it errors with "Too many input arguments." Always load first, then use `newref` to change impedance.

## Export to Touchstone

```matlab
rfwrite(s, 'output.s2p');
rfwrite(s, 'output.s2p', 'FrequencyUnit', 'GHz', 'Format', 'RI', 'ForceOverwrite', true);
```

`Format` options: `'MA'` (magnitude/angle, default), `'DB'` (dB/angle), `'RI'` (real/imaginary).

**Gotcha:** `'DB'` format writes `-Inf` for any zero-valued S-parameter (e.g., S12=0 in an isolator), producing a file that `sparameters` cannot re-read. Use `'RI'` for lossless round-trip fidelity.

## Visualization

### `rfplot` — Rectangular Plots

```matlab
rfplot(s);                              % All S-parameters, magnitude in dB
rfplot(s, 2, 1);                        % S21 only
rfplot(s, [1 2], [1 2]);               % S11, S12, S21, S22
rfplot(s, {[2 1]; [1 1]});             % S21 and S11 specifically
rfplot(s, 'diag');                      % Diagonal only (S11, S22, ...) — reflection coefficients
rfplot(s, 'triu');                      % Upper triangular portion
```

Plot types via the `plotflag` argument:
```matlab
rfplot(s, 2, 1, 'db');                 % Magnitude in dB (default)
rfplot(s, 2, 1, 'angle');              % Phase in degrees
rfplot(s, 2, 1, 'abs');                % Linear magnitude
rfplot(s, 2, 1, 'real');               % Real part
rfplot(s, 2, 1, 'imag');               % Imaginary part
```