matlab-compose-rf-circuit

# General-Purpose RF Circuit Composition

Build RF circuits from primitive R/L/C elements, active components (amplifier, modulator, mixerIMT), and `nport` S-parameter blocks -- all wired between nodes in a SPICE-like netlist. Extract S-parameters, embed subcircuits hierarchically, and convert lumped designs to distributed implementations.

## When to Use

- Building arbitrary RF circuit topologies with node wiring (SPICE-like netlist)
- Combining R/L/C elements with active components (amplifier, modulator, mixerIMT)
- Embedding nport S-parameter blocks alongside lumped elements
- Creating reusable subcircuits with setterminals for hierarchical composition
- Converting lumped designs to distributed implementations (Richards/Kuroda)

## When NOT to Use

- Building SI channel models from nport + transmission lines -- use `matlab-model-si-channel`
- Creating 2-port circuit blocks for rfbudget (seriesRLC, shuntRLC, lcladder) -- use `matlab-create-rfbudget-elements`
- Defining standalone RF elements for rfbudget cascade -- use `matlab-create-rfbudget-elements`
- Cascading or de-embedding S-parameter blocks -- use `matlab-deembed-rf-cascade`

## Workflow

1. **Create circuit** — Instantiate with `circuit('Name')`
2. **Add elements** — Wire R/L/C, active components, and nport blocks to nodes with `add`
3. **Define ports** — Call `setports` for S-parameter extraction or `setterminals` for subcircuit embedding
4. **Analyze** — Extract S-parameters with `sparameters(ckt, freq)`

## Primitive Elements (2-Terminal)

Each has terminals `p` (positive) and `n` (negative). Connect to any two circuit nodes.

```matlab
r = resistor(100, 'R1');          % 100 Ohm
c = capacitor(1e-12, 'C1');       % 1 pF
l = inductor(10e-9, 'L1');        % 10 nH
```

**Gotcha:** Primitive constructors (`resistor`, `capacitor`, `inductor`) accept only a positional value and an optional name string: `resistor(100, 'R1')`. Name-value syntax like `resistor('Resistance', 100, 'Name', 'R1')` is **not** supported.

Properties: `Resistance`, `Capacitance`, `Inductance`, `Name`, `Terminals`.

**Handle semantics:** Changing a property (e.g., `r.Resistance = 200`) after adding to a circuit immediately affects the circuit -- no need to re-add.

### mutualInductor (4-Terminal, R2023a+)

Coupled inductors for transformer modeling:

```matlab
mi = mutualInductor('Name', 'Xfmr', ...
    'Inductance1', 10e-9, 'Inductance2', 10e-9, ...
    'CouplingCoefficient', 0.95);
```

Terminals: `p1+`, `p2+`, `p1-`, `p2-`. Use `CouplingCoefficient = 1` for an ideal transformer.

**Gotcha:** Constructor uses name-value pairs only -- no positional arguments. The coupling parameter is `CouplingCoefficient`, **not** `MutualInductance`.

### rfdivider (6-Terminal / 3-Port, R2023a+)

Wilkinson power divider:

```matlab
d = rfdivider('Name', 'Split1', 'Impedance', 50);
```

Terminals: `p1+`, `p2+`, `p3+`, `p1-`, `p2-`, `p3-`. Add to a circuit with 6 nodes.

## Active Elements in Circuit

`amplifier`, `modulator`, and `mixerIMT` are 2-port (4-terminal) elements that work in `circuit` via `add()`. This lets you build complete RF front-end topologies with active and passive elements in a single netlist.

### amplifier in Circuit

```matlab
lna = amplifier('Gain', 15, 'NF', 2, 'OIP3', 35, 'Name', 'LNA');

ckt = circuit('RxFrontEnd');
add(ckt, [1 2], capacitor(1e-12, 'DCBlk'));   % DC block
add(ckt, [2 3 0 0], lna);                      % LNA: 4-node mapping
add(ckt, [3 4], inductor(2.7e-9, 'Lmatch'));   % matching inductor
setports(ckt, [1 0], [4 0]);

freq = linspace(1e9, 6e9, 500);
s = sparameters(ckt, freq);
```

### modulator in Circuit

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

ckt = circuit('DownConv');
add(ckt, [1 2 0 0], mix);
add(ckt, [2 3], resistor(50, 'Rload'));
setports(ckt, [1 0], [3 0]);
```

### mixerIMT in Circuit

```matlab
m = mixerIMT('LO', 2.1e9, 'ConverterType', 'Down', 'NF', 10, ...
    'ReferenceInputPower', -10, 'NominalOutputPower', -16, 'Name', 'Mixer');

ckt = circuit('MixerStage');
add(ckt, [1 2 0 0], m);    % 4-terminal: p1+->1, p2+->2, p1-->0, p2-->0
setports(ckt, [1 0], [2 0]);
```

### Active Element Node Mapping

All 2-port RF elements (amplifier, modulator, mixerIMT, nport, rffilter, attenuator, phaseshift) have 4 terminals (`p1+`, `p2+`, `p1-`, `p2-`). Use 4-node mapping in `add`:

```matlab
add(ckt, [nodeIn nodeOut nodeInRef nodeOutRef], element);
```

For grounded references, the shorthand `add(ckt, [nodeIn nodeOut 0 0], element)` is typical. Primitive 2-terminal elements (resistor, capacitor, inductor) use 2-node mapping: `add(ckt, [nodeA nodeB], element)`.

**Gotcha:** Active elements are handle objects -- modifying properties after `add` immediately affects the circuit. Use `clone()` for independent copies.

## nport Elements in Circuit

Embed measured or simulated S-parameter data as a circuit element:

```matlab
np = nport('measured.s2p');
np.Name = 'Filter';

ckt = circuit('RxChain');
add(ckt, [1 2 0 0], np);               % 4 nodes: p1+->1, p2+->2, p1-->0, p2-->0
add(ckt, [2 3], inductor(10e-9, 'L1')); % lumped element after nport
setports(ckt, [1 0], [3 0]);
```

A 2-port nport has 4 terminals (`p1+`, `p2+`, `p1-`, `p2-`), so `add` takes a 4-element node vector.

For multi-port nport (4-port, etc.), differential port mapping, and SI channel modeling with nport, see the `matlab-model-si-channel` skill.

### Identifying Input vs Output Ports

Before wiring a multi-port nport, determine which ports are inputs (near-end) and which are outputs (far-end). Look at the **lowest-frequency S-parameter data**: the off-diagonal elements closest to unity (0 dB) identify the through connections.

```matlab
% Inspect at the lowest frequency to find through paths
s4 = sparameters('device.s4p');
S = s4.Parameters(:,:,1);          % S-matrix at lowest frequency
disp(abs(S));                       % Through paths have magnitude ≈ 1
% If S(2,1) ≈ 1 and S(4