matlab-analyze-rf-mixer

# Mixer Intermodulation Analysis

Analyze mixer spurious products using the `mixerIMT` object. Build intermodulation tables, visualize spur charts, and integrate with `rfbudget` for cascade analysis.

## When to Use

- Building intermodulation tables (IMT) for mixer spur analysis
- Visualizing spur charts at specific RF input frequencies
- Identifying spurious products and designing frequency plans
- Using mixerIMT in rfbudget for cascade analysis with spur-aware mixer models

## When NOT to Use

- Simple cascade budgets without spur analysis -- use `modulator` via `matlab-create-rfbudget-elements`
- General rfbudget cascade analysis -- use `matlab-analyze-rf-budget`
- Composing mixer circuits with node wiring -- use `matlab-compose-rf-circuit`
- Processing complex baseband signals through mixers -- use `matlab-process-rf-baseband`

## Workflow

1. **Create mixer** — Construct `mixerIMT` with LO, ConverterType, and power levels
2. **Configure IMT** — Set custom intermodulation table or use defaults
3. **Visualize spurs** — Plot spur chart with `rfplot(m, fRF)`
4. **Integrate** — Add to `rfbudget` chain or `circuit` for cascade/circuit analysis

## `mixerIMT` vs `modulator`

Both model frequency converters, but serve different purposes:

| Feature | `modulator` | `mixerIMT` |
|---------|------------|------------|
| Gain specification | `Gain` property (direct) | `NominalOutputPower - ReferenceInputPower` |
| Nonlinearity | OIP3-based (poly model) | IMT table (arbitrary spur levels) |
| Spur visualization | No | Yes — `rfplot(m, fRF)` |
| Constructor accepts `Gain` | Yes | **No** — settable after construction but ignored by rfbudget |
| Use case | System-level cascade budgets | Spur analysis and frequency planning |

Use `modulator` for quick cascade budgets. Use `mixerIMT` when you need to model specific spurious products or visualize spur charts.

## Creating a mixerIMT

```matlab
m = mixerIMT('LO', 2.1e9, 'ConverterType', 'Down', 'NF', 10, 'Name', 'Mixer');
```

### Constructor Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `LO` | 1e8 | Local oscillator frequency (Hz) |
| `ConverterType` | `'Up'` | `'Down'` or `'Up'` conversion — **must set explicitly for down-conversion** |
| `NF` | 0 | Noise figure (dB) |
| `ReferenceInputPower` | -15 | Reference input power (dBm) |
| `NominalOutputPower` | -5 | Nominal output power (dBm) |
| `Model` | auto | `'mod'` (up) or `'demod'` (down) — set automatically from ConverterType |
| `Zin` | 50 | Input impedance (Ohm) |
| `Zout` | 50 | Output impedance (Ohm) |
| `IMT` | 3x3 default | Intermodulation table |
| `Name` | `'MixerIMT'` | Element name |

### Post-Construction Properties

These properties are read-write but **cannot be passed to the constructor**:

```matlab
m.OIP3 = 20;       % Output IP3 (dBm)
m.OIP2 = 40;       % Output IP2 (dBm)
```

**Do not set `m.Gain` manually.** Although `Gain` is a settable property, `rfbudget` ignores it — the budget gain is determined entirely by `NominalOutputPower` and `ReferenceInputPower`. Setting `m.Gain` has no effect on cascade results and can be misleading.

## Conversion Gain

Conversion gain in `rfbudget` is determined by `NominalOutputPower` and `ReferenceInputPower`. Although `Gain` is a settable property, `rfbudget` ignores it and computes gain from `NominalOutputPower - ReferenceInputPower`. Do not set `m.Gain` manually.

```
Budget gain = NominalOutputPower - ReferenceInputPower
```

```matlab
% This gives 10 dB conversion gain in rfbudget:
m = mixerIMT('ReferenceInputPower', -15, 'NominalOutputPower', -5, ...
    'LO', 2.1e9, 'ConverterType', 'Down', 'Name', 'Mixer');
% Budget sees: -5 - (-15) = 10 dB

% To get -6 dB conversion loss in rfbudget:
m2 = mixerIMT('ReferenceInputPower', -10, 'NominalOutputPower', -16, ...
    'LO', 2.1e9, 'ConverterType', 'Down', 'Name', 'Mixer');
% Budget sees: -16 - (-10) = -6 dB
```

## The IMT Table

The intermodulation table (IMT) is an MxN matrix where:
- **Rows** = RF harmonic order (row 1 = order 0, row 2 = order 1, ...)
- **Columns** = LO harmonic order (col 1 = order 0, col 2 = order 1, ...)
- **Values** = relative power in **dBc below the reference** (non-negative)
- `0` = reference level (desired output)
- `99` = fully suppressed

### Default Table

```matlab
m = mixerIMT;
disp(m.IMT);
%    99    99    99
%    99     0    99
%    99    99    99
```

The default 3x3 table has only the desired product (RF×1, LO×1) at row 2, col 2 with value 0 (reference). Everything else is suppressed (99).

### Custom IMT Table

```matlab
imt = 99*ones(5,5);       % Start with everything suppressed
imt(2,2) = 0;             % RF×1, LO×1: desired output (reference)
imt(2,1) = 20;            % RF×1, LO×0: RF feedthrough at -20 dBc
imt(1,2) = 15;            % RF×0, LO×1: LO feedthrough at -15 dBc
imt(3,2) = 30;            % RF×2, LO×1: 2RF-LO spur at -30 dBc
imt(2,3) = 25;            % RF×1, LO×2: RF-2LO spur at -25 dBc
m.IMT = imt;
```

**Gotcha:** The IMT must be a **real 2-D numeric matrix** (class `double`). Setting a cell array, 3-D array, complex matrix, or non-numeric type errors with "An Intermodulation Table must be real two dimensional matrix." Ensure `imt` is created with standard `double` operations (e.g., `99*ones(M,N)`).

**Gotcha:** IMT values must be **non-negative and ≤ 99** (they represent dBc below reference). Setting a negative value errors with "Value must be nonnegative." Setting a value > 99 errors with "Expected Spur table to be an array with all of the values <= 99." Using `inf` for "fully suppressed" also errors ("Value must be finite") — use `99` instead.

### Reading the IMT Table

| IMT Position | RF Order | LO Order | Spur Frequency (Down) |
|-------------|----------|----------|----------------------|
| `(1,1)` | 0 | 0 | DC |
| `(2,1)` | 1 | 0 | fRF (RF feedthrough) |
| `(1,2)` | 0 | 1 | fLO (LO feedthrough) |
| `(2,2)` | 1 | 1 | fRF - fLO (desired IF) |
| `(3,2)` | 2 | 1 | 2·fRF - fLO |
| `(2,3)` | 1 | 2