matlab-design-matching-network

# Impedance Matching Network Design

Design, evaluate, and optimize **1-port** impedance matching networks. The `matchingnetwork` object and `matchingNetworkDesigner` app match a source impedance to a load impedance — they do not yet design 2-port (e.g., filter-style) matching. The object generates candidate topologies, ranks them by performance, and exports as circuit objects.

## When to Use

- Designing L, Pi, or Tee impedance matching networks
- Matching a source impedance to a frequency-dependent load (antenna, filter)
- Ranking candidate topologies by return loss or transducer gain
- Converting lumped matching designs to transmission line stubs via Richards transformation
- Evaluating component tolerance sensitivity in matching networks
- Importing custom matching circuits for comparison

## When NOT to Use

- Building general-purpose RF circuits with arbitrary topologies -- use `matlab-compose-rf-circuit`
- Composing rfbudget cascade elements -- use `matlab-create-rfbudget-elements`
- Analyzing amplifier stability or gain circles -- use `matlab-analyze-rf-amplifier`

## Workflow

1. **Define impedances** — Set source and load impedances (scalar, S-parameter object, or function handle)
2. **Create network** — Construct `matchingnetwork` with center frequency, bandwidth, and topology
3. **Evaluate** — Add evaluation parameters, inspect candidates with `circuitDescriptions`
4. **Export** — Extract best circuit with `exportCircuits` for use in larger designs

## Creating a Matching Network

```matlab
mn = matchingnetwork( ...
    'SourceImpedance', 50, ...
    'LoadImpedance', 75 + 20i, ...
    'CenterFrequency', 2.4e9, ...
    'Bandwidth', 200e6, ...
    'Components', 2);
```

### Properties

| Property | Default | Description |
|----------|---------|-------------|
| `SourceImpedance` | 50 | Source impedance (see formats below) |
| `LoadImpedance` | 50 | Load impedance (see formats below) |
| `CenterFrequency` | 1e9 | Design frequency (Hz) |
| `Bandwidth` | 100e6 | Target bandwidth (Hz) |
| `LoadedQ` | 10 | Loaded Q factor |
| `Components` | 2 | Topology: `2`, `3`, `'L'`, `'Pi'`, `'Tee'` |
| `Circuit` | (auto) | Read-only array of generated circuits |

### Bandwidth and LoadedQ Are Coupled

`LoadedQ = CenterFrequency / Bandwidth`. Setting one updates the other. If both are specified, `Bandwidth` takes precedence.

### Components / Topology Options

| Value | Circuits Generated |
|-------|-------------------|
| `2` or `'L'` | 2 L-section designs (series-L/shunt-C and series-C/shunt-L) |
| `3` | 8 three-element designs (all permutations) |
| `'Pi'` | 4 shunt-series-shunt designs |
| `'Tee'` | 4 series-shunt-series designs |

**Gotcha:** Maximum is 3 components. `Components = 1` or `Components = 4` error.

## Impedance Source Formats

Both `SourceImpedance` and `LoadImpedance` accept:

```matlab
% Scalar (constant impedance)
mn.LoadImpedance = 75 + 20i;

% S-parameter object (frequency-dependent, 1-port)
sAnt = sparameters('antenna.s1p');
mn.LoadImpedance = sAnt;

% Z-parameter or Y-parameter object
mn.LoadImpedance = zparameters(sAnt);

% Touchstone file path
mn.LoadImpedance = 'antenna.s1p';

% 1-port circuit object (must have setports called)
ckt = circuit('Load');
add(ckt, [1 0], resistor(75, 'RL'));
add(ckt, [1 0], capacitor(1e-12, 'CL'));
setports(ckt, [1 0]);
mn.LoadImpedance = ckt;

% Function handle (frequency in Hz)
mn.LoadImpedance = @(f) 50 + 30i*(f/1e9);
```

## Inspecting Candidate Designs

```matlab
[topology, performance] = circuitDescriptions(mn);
disp(topology);       % Component types and values for each design
disp(performance);    % Pass/fail, tests failed, performance score
```

The **topology table** columns: `circuitName`, `component1Type`, `component1Value`, `component2Type`, `component2Value`, etc. Component types are `"Series L"`, `"Series C"`, `"Shunt L"`, `"Shunt C"`.

The **performance table** columns: `circuitName`, `evaluationPassed` (`"Yes"`/`"No"`), `testsFailed`, `performanceScore`. Designs are ranked by score (descending). The `performanceScore` is a weighted composite — higher is better, but the scale depends on your evaluation parameters (it is not a fixed 0–100 range). Use it for relative ranking between candidates, not as an absolute quality metric.

Use `component1Type`/`component2Type` columns in the topology table to identify which topology each auto-generated design represents (e.g., `"Series L"` + `"Shunt C"` vs `"Series C"` + `"Shunt L"`).

## Evaluation Parameters

Add performance goals to rank and filter designs. Only two parameter types: `'gammain'` (input reflection) and `'Gt'` (transducer gain).

```matlab
% Require return loss below -15 dB in-band
addEvaluationParameter(mn, 'gammain', '<', -15, [2.3e9 2.5e9], 2);

% Require insertion loss above -1 dB
addEvaluationParameter(mn, 'Gt', '>', -1, [2.3e9 2.5e9], 1);

% View current evaluations
params = getEvaluationParameters(mn);
disp(params);

% Remove an evaluation by row index
clearEvaluationParameter(mn, 1);
```

Arguments: `(mn, parameter, comparison, targetdB, [fLow fHigh], weight)`

A **default automatic evaluation** (`Gt > -3 dB` over `[CenterFrequency - Bandwidth/2, CenterFrequency + Bandwidth/2]`) is always present. Clear it with `clearEvaluationParameter(mn, 1)` if the automatic entry is at row 1.

**Gotcha:** Only `'gammain'` and `'Gt'` are supported — no S11, S21, VSWR, or other parameters.

## Exporting Circuits

```matlab
ckt = exportCircuits(mn);            % Best-ranked circuit only
ckts = exportCircuits(mn, [1 3]);    % Specific designs by index
```

Returns `circuit` objects containing `inductor` and `capacitor` elements. These can be used directly with `sparameters(ckt, freq)`, embedded in larger circuits via `add()`, or cascaded.

## Visualization

### Frequency Response

```matlab
rfplot(mn);                          % All designs, auto frequency range
rfplot(mn, freq);                    % Custom frequencies
rfplot(mn, freq, [1 3]);             % Specific designs
```