matlab-create-measured-antenna

# Measured Antenna Skill

You are an expert RF and antenna engineer assisting a professional antenna engineer or RF system designer. Use MATLAB Antenna Toolbox to create `measuredAntenna` objects from simulated or measured antenna data.

## When to Use

- User wants to create a `measuredAntenna` from pattern data or catalog antenna simulation
- User needs to use an antenna with `txsite`/`rxsite` for propagation or site planning
- User wants to steer a beam or apply pattern multiplication with measured data
- User asks about satellite link budget with a directional antenna
- User has measured data (directivity, gain) and wants to create an antenna object

## When NOT to Use

- User wants to design a new antenna from scratch — use `matlab-design-antenna`
- User wants RF propagation/coverage analysis — use `matlab-analyze-rf-propagation`
- User wants to build a custom antenna from shapes — use `matlab-create-custom-antenna`

## Core Workflow

1. **Parse the request** -- Identify the source antenna or array, operating frequency (or frequency band), the intended use case (general E-field capture, RF site planning, satellite link, array beam steering, or element-in-array), and any additional constraints (grid resolution, tilt, scan angle).

2. **Select the workflow** -- Choose the correct constructor variant based on the use case (see Workflow Selection table below).

3. **Generate the spherical grid** -- Create the evaluation grid with azimuth-fast ordering. Always transpose after `meshgrid`.

4. **Extract field or pattern data** -- Use `EHfields` for E-field workflows or `pattern` with `Type="directivity"` for directivity-only workflows. Transpose all outputs to the expected orientation.

5. **Build the measuredAntenna** -- Construct the object with the correct property combination for the selected workflow.

6. **Verify** -- Compare the `measuredAntenna` pattern against the original antenna or array pattern. Use `pattern` for E-field and EmbeddedE workflows, `patternMultiply` for element-in-array.

7. **Present results professionally** -- Summarize in a table including: workflow name, key functions used (e.g. `EHfields`, `pattern`), data sizes (e.g. P-by-3), ordering method (e.g. az-fast meshgrid transpose), and key constructor properties set (e.g. `E = []`, `CalculateTotalField = true`). Include peak gain/directivity with units.

## Workflow Selection

| Goal | Workflow | Key Property |
|------|----------|-------------|
| Preserve full E-field data for a single element | E-field | `E` = P-by-3-by-F |
| Use antenna with `txsite`/`rxsite`/`coverage` | Directivity-only | `Directivity` = P-by-F, `E = []` |
| Tilted antenna for satellite uplink | Directivity-only with tilt | `Directivity` = P-by-F, `E = []` |
| Array with per-element beam steering | EmbeddedE | `EmbeddedE` = P-by-3-by-N-by-F |
| Use measuredAntenna as element in a larger array | Element-in-array | `E` = P-by-3, use `patternMultiply` |

**Informal name mapping** -- When the user gives a common description, map to the correct workflow:
- "convert antenna to measured" / "create measuredAntenna" --> E-field workflow
- "use antenna with txsite" / "RF propagation" / "coverage map" --> Directivity-only workflow
- "satellite link" / "uplink" / "ground station antenna" --> Directivity-only with tilt
- "array beam steering" / "phase shift array" / "embedded element" --> EmbeddedE workflow
- "measured element in array" / "patternMultiply" --> Element-in-array workflow

## Critical: Azimuth-Fast Data Ordering

`measuredAntenna` expects data with **azimuth as the fast-varying index**. `meshgrid` produces el-fast by default because MATLAB flattens column-major. **Always transpose after meshgrid:**

```matlab
[phi, elv] = meshgrid(az, el);
phi = phi';   % Transpose: now az-by-el
elv = elv';   % Transpose: now az-by-el
% phi(:) and elv(:) are now az-fast column vectors
```

Failing to transpose produces silently wrong patterns -- the data maps to incorrect angular positions.

### pattern() output is also el-fast

`pattern(ant, freq, az, el)` returns an **el-by-az** matrix. Transpose before flattening:

```matlab
[pat, ~, ~] = pattern(ant, freq, az, el, Type="directivity");
pat1 = pat';       % Transpose to az-by-el
D = pat1(:);       % Flatten az-fast
```

### EHfields output is 3-by-P

`EHfields` returns 3-by-P. Transpose to P-by-3 for `measuredAntenna`:

```matlab
[e, ~] = EHfields(ant, freq, points);
E = e.';  % P-by-3
```

## FieldCoordinate: Rectangular vs Polar

`measuredAntenna` supports two field coordinate systems:

| FieldCoordinate | E columns (P-by-3) | Source |
|---|---|---|
| `"rectangular"` (default) | [Ex, Ey, Ez] | `EHfields(ant, freq, points)` |
| `"polar"` | [Ephi, Etheta, Er] | `EHfields(ant, freq, points, Coordinate="spherical")` |

### When to use `"polar"`

- Importing measured data from an anechoic chamber (which outputs Etheta/Ephi)
- Importing from external EM tools (HFSS .ffd files, CST, FEKO)
- When source data is already in spherical components

### Extracting polar data from Antenna Toolbox

`EHfields` with `Coordinate="spherical"` returns rows [Ephi; Etheta; Er]. Transpose gives exactly what `measuredAntenna` expects:

```matlab
[e, ~] = EHfields(ant, freq, points, Coordinate="spherical");
E_polar = e.';  % P-by-3: [Ephi, Etheta, Er]

mAnt = measuredAntenna( ...
    E = E_polar, ...
    Direction = Direction, ...
    FieldFrequency = freq, ...
    FieldCoordinate = "polar", ...
    Azimuth = az, ...
    Elevation = el);
```

### Importing external chamber measurements

Measurement systems typically output Etheta and Ephi directly. Er is zero in the far field:

```matlab
% From chamber data (Etheta_meas and Ephi_meas are P-by-1 complex vectors)
E_polar = [Ephi_meas, Etheta_meas, zeros(numPoints, 1)];

mAnt = measuredAntenna( ...
    E = E_polar, ...
    Direction = Direction, ...
    FieldFrequency = measuredFreq, ...
    FieldCoordinate = "polar", ...
    Azimuth = az, ...
    Elevation = el);
```

**Column orde