matlab-create-rfbudget-elements

# rfbudget Element Objects

Create and configure all rfbudget-compatible elements -- active components (amplifier, modulator, attenuator, phaseshift) and passive networks (seriesRLC, shuntRLC, lcladder, rffilter, nport, transmission lines). These are the building blocks for `rfbudget` cascade analysis and `circuit` composition.

## When to Use

- Defining amplifiers, mixers, filters, attenuators, phase shifters, antennas for rfbudget
- Creating generic RF components with gain, NF, IP3 specifications
- Synthesizing LC filters with rffilter (Butterworth, Chebyshev)
- Loading measured S-parameter data as nport elements
- Setting up link budgets with rfantenna (EIRP, path loss)
- Creating inline passive networks (DC blocks, bias tees, matching sections) for rfbudget
- Building LC ladder filters for cascade analysis
- Adding transmission line segments to an rfbudget signal chain

## When NOT to Use

- Building arbitrary circuit topologies with node wiring -- use `matlab-compose-rf-circuit`
- Computing rfbudget cascade analysis -- use `matlab-analyze-rf-budget`
- Analyzing amplifier stability or gain -- use `matlab-analyze-rf-amplifier`
- Impedance matching network design and optimization -- use `matlab-design-matching-network`
- Signal integrity channel modeling -- use `matlab-model-si-channel`

## Workflow

1. **Select element type** -- Choose from active, passive, or transmission line elements
2. **Configure properties** -- Set gain, NF, IP3, impedance, R/L/C values, or physical line parameters
3. **Validate** -- Extract S-parameters or inspect properties to verify behavior
4. **Use in chain** -- Add to `rfbudget` or `circuit` for cascade or circuit analysis

## Element Hierarchy

All rfbudget elements subclass from a circuit Element class, so every element below also works in `circuit` via `add()`.

### Active Elements

| Object | Represents | Key Properties |
|--------|-----------|----------------|
| `amplifier` | Active gain stage (LNA, PA, driver) | Gain, NF, OIP3, nonlinear model |
| `modulator` | Frequency converter (mixer) | Gain, NF, OIP3, LO, ConverterType |
| `rfelement` | Generic 2-port (cable, coupler) | Gain, NF, OIP3 |
| `attenuator` | Matched attenuator pad | Attenuation, Zin, Zout |
| `phaseshift` | Lossless phase shifter | PhaseShift (degrees) |

### Passive / Data-Driven Elements

| Object | Represents | Key Properties |
|--------|-----------|----------------|
| `nport` | Component from S-parameter data | Touchstone file or sparameters object |
| `rffilter` | Synthesized LC filter | ResponseType, FilterType, FilterOrder |
| `rfantenna` | Antenna in link budget | Type, Gain, TxEIRP, PathLoss |
| `seriesRLC` | Series R+L+C in signal path | R, L, C |
| `shuntRLC` | Shunt R+L+C to ground | R, L, C |
| `lcladder` | LC ladder filter (pi/tee topologies) | Topology, L, C values |

### Transmission Lines

| Object | Description |
|--------|-------------|
| `txlineDelayLossless` | Ideal lossless delay line (Z0 + TimeDelay) |
| `txlineDelayLossy` | Ideal lossy delay line (Z0 + TimeDelay + Resistance) |
| `txlineMicrostrip` | Microstrip line |
| `txlineCoaxial` | Coaxial cable |
| `txlineCPW` | Coplanar waveguide |
| `txlineStripline` | Stripline |
| `txlineRLCGLine` | RLCG per-unit-length model |
| `txlineWRLGC` | Frequency-dependent W-element RLGC model |
| `txlineWtable` | Table-based frequency-dependent R/L/C/G model |
| `txlineParallelPlate` | Parallel plate line |
| `txlineTwoWire` | Two-wire line |

**Not rfbudget-compatible:** `resistor`, `capacitor`, `inductor`, `circuit` -- these are primitive elements for general circuit composition only (see `matlab-compose-rf-circuit` skill).

## `amplifier` -- Active Gain Stages

```matlab
lna = amplifier('Gain', 15, 'NF', 2, 'OIP3', 35, 'Name', 'LNA');
ampFromFile = amplifier('FileName', 'default.s2p', 'Name', 'LNAMeasured');
```

### Properties

| Property | Default | Description |
|----------|---------|-------------|
| `Gain` | 0 | Small-signal gain (dB) |
| `NF` | 0 | Noise figure (dB) |
| `OIP3` / `IIP3` | Inf | Third-order intercept (dBm) -- related: OIP3 = IIP3 + Gain |
| `OIP2` | Inf | Output second-order intercept (dBm) |
| `OP1dB` / `IP1dB` | Inf | 1-dB compression (dBm) -- related: OP1dB = IP1dB + Gain - 1 |
| `OPsat` / `IPsat` | Inf | Saturation power (dBm) -- independent of each other |
| `Model` | `'poly'` | Nonlinear model: `'poly'`, `'cubic'`, `'ampm'`, `'sparam'` |
| `Zin` / `Zout` | 50 | Impedance (Ohm) |
| `Name` | `''` | Element name (must be valid MATLAB identifier) |

**Conventions:** Amplifiers use output-referred (OIP3, OP1dB, OPsat). Mixers/modulators use input-referred (IIP3, IP1dB, IPsat). For `'poly'` model, set all compression params you have. For `'cubic'`, set `Nonlinearity` to select which ONE param shapes the curve.

See `reference/amplifier-models.md` for detailed model comparison, compression parameter relationships, and S-parameter file loading.

## `modulator` -- Mixers and Frequency Converters

```matlab
downMixer = modulator('Gain', -6, 'NF', 10, 'OIP3', 20, ...
    'LO', 2.1e9, 'ConverterType', 'Down', 'Name', 'Mixer');

upMixer = modulator('Gain', -8, 'NF', 12, 'OIP3', 18, ...
    'LO', 1.5e9, 'ConverterType', 'Up', 'Name', 'UpConv');
```

### Properties

| Property | Default | Description |
|----------|---------|-------------|
| `LO` | 0 | Local oscillator frequency (Hz) |
| `ConverterType` | `'Down'` | `'Down'` or `'Up'` conversion |
| `Gain` | 0 | Conversion gain/loss (dB) |
| `NF` | 0 | Noise figure (dB) |
| `OIP3` | Inf | Output IP3 (dBm) |
| `ImageReject` | true | Reject image frequency |
| `ChannelSelect` | true | Select desired channel |

**Gotcha:** After a `modulator`, the signal frequency changes. In an `rfbudget`, subsequent stages operate at the converted frequency. For a down-converter: `fOut = fIn - LO` (or `LO - fIn` depending on sideband).

## `rfelement` -- Generic 2-Port Components

Use for cables, couplers, or any passive/active component defined by scalar specs:

```matlab
at