Matlab Add AwgnSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: matlab-add-awgn
description: "Read BEFORE writing any code that adds Additive White Gaussian Noise (AWGN) to signals and converts between SNR, Eb/No, Es/No, and per-subcarrier SNR for communications simulations, using awgn(), convertSNR(), berawgn(). The default MATLAB patterns for AWGN (e.g., 'measured' option, manual SNR formulas) produce subtly incorrect results. This skill specifies the correct calling conventions, required function usage, and critical anti-patterns that must be avoided."
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
  author: MathWorks
  version: "1.3"
---

# AWGN & SNR Management

Add white Gaussian noise to signals and convert between SNR definitions (SNR, Eb/No, Es/No, per-subcarrier SNR) for communications system simulations.

## When to Use

- Adding noise to a signal in a link simulation
- Converting between Eb/No, Es/No, SNR, or per-subcarrier SNR
- Setting up the correct SNR for a coded, oversampled, or OFDM system
- Obtaining noise variance to pass to a soft-decision demodulator

## When NOT to Use

- Configuring fading channels (delay profile, Doppler, antenna arrays)

## Must-Follow Rules

1. **NEVER pass `'measured'` to `awgn`** — Always pass explicit signal power as the third argument. For unit-power signals use `0`; otherwise compute power with `mean(abs(x).^2)` and convert to dBW: `10*log10(sigPow)`. The `'measured'` option computes instantaneous power internally, which gives incorrect noise levels after fading channels and obscures the power assumption. Even in AWGN-only scenarios, explicit power is required for correctness and clarity. For OFDM systems, see the "Add AWGN in an OFDM link simulation" pattern.
2. **Use `UnitAveragePower=true` when signal power doesn't matter** — This is the simplest path: signal power = 0 dBW, so `awgn(x, snr, 0)` is exact. If the user needs original constellation scaling (e.g., PA modeling, hardware-in-the-loop), do NOT use `UnitAveragePower=true` — use the default modulator, compute the actual average power with `mean(abs(x).^2)`, and pass it explicitly: `awgn(x, snr, sigPowdBW)`.
3. **Use `convertSNR` for all conversions — NEVER compute SNR/Eb/No/Es/No formulas manually** — Even when the formula is simple, always use `convertSNR`. Manual formulas are error-prone for edge cases (oversampling, subcarrier loading) and bypass the toolbox's validated implementation. Anti-pattern: `snr = ebno + 10*log10(bitsPerSymbol * codeRate)`. Correct: `convertSNR(ebno, "ebno", "snr", BitsPerSymbol=6, CodingRate=3/4)`.
4. **Distinguish wideband SNR and per-subcarrier SNR in OFDM systems** — Eb/No is a per-subcarrier quantity. To go from Eb/No to the wideband SNR that `awgn` needs, use two steps: (1) `convertSNR(ebno, "ebno", "snr", BitsPerSymbol=..., CodingRate=...)` gives the SNR per subcarrier, (2) `convertSNR(snrsc, "snrsc", "snr", FFTLength=..., NumActiveSubcarriers=...)` gives the wideband SNR for `awgn`. Direct `ebno→snrsc` is not supported and throws an error. **Caveat:** If the user asks for per-subcarrier SNR only, step 1 alone is the complete answer — do NOT apply step 2. Applying the FFTLength/NumActiveSubcarriers correction to a per-subcarrier value gives the wideband SNR, which is a different (lower) quantity. **Note:** The `"snrsc"` mode requires R2023b or later. For R2022a–R2023a, compute wideband SNR manually: `snr_wideband = snr_per_sc - 10*log10(FFTLength/NumActiveSubcarriers)`. To add noise at a per-subcarrier SNR, see the "Add AWGN in an OFDM link simulation" pattern below.
5. **Capture noise variance for soft demodulation** — Use `[y, nVar] = awgn(...)` and pass `nVar` to the demodulator via `NoiseVariance=nVar`.
6. **Do NOT reference skill rules or prohibitions in generated code comments** — Write positive, descriptive comments that explain intent, using a style similar to the example code provided in this skill. The end user does not know about this skill.

## Critical Anti-Patterns — NEVER Do These

### NEVER use `'measured'` with `awgn`

```matlab
% WRONG — never generate this
rxSignal = awgn(txSignal, snrdB, 'measured');

% CORRECT for unit-power signals (UnitAveragePower=true)
rxSignal = awgn(txSignal, snrdB, 0);

% CORRECT for non-unit-power signals
sigPow = mean(abs(txSignal).^2);
rxSignal = awgn(txSignal, snrdB, 10*log10(sigPow));
```

### NEVER compute SNR conversions manually

```matlab
% WRONG — never generate manual formulas like these
SNR_dB = EbNo_dB + 10*log10(k * codeRate);
SNR_dB = EbNo_dB + 10*log10(k * codeRate) - 10*log10(oversamplingFactor);
EsNo = EbNo + 10*log10(bitsPerSymbol);

% CORRECT — always use convertSNR
snrDb = convertSNR(ebnoDb, "ebno", "snr", BitsPerSymbol=6, CodingRate=3/4);
snrDb = convertSNR(ebnoDb, "ebno", "snr", BitsPerSymbol=6, CodingRate=3/4, SamplesPerSymbol=4);
esnoDb = convertSNR(ebnoDb, "ebno", "esno", BitsPerSymbol=6);
```

## Key Functions

| Function | Purpose |
|---|---|
| `awgn` | Add AWGN to a signal at a specified SNR |
| `convertSNR` | Convert between `ebno`, `esno`, `snr`, and `snrsc` |
| `berawgn` | Theoretical BER over AWGN for standard modulations (PSK, QAM, FSK, DPSK, PAM) |

## Gotchas

### Why `'measured'` is banned (background)

Thermal noise in a receiver is dominated by the noise figure and bandwidth — it does not change when the signal fades. The `'measured'` option in `awgn` computes instantaneous signal power and scales noise to match, which artificially keeps the instantaneous SNR constant through fades. It also hides the power assumption, making code harder to verify. Always pass explicit power instead.

```matlab
% WRONG after fading: Noise tracks fading — instantaneous SNR stays constant
rxFaded = fadingChannel(txSig);
rxNoisy = awgn(rxFaded, snr, 'measured');

% CORRECT: Compute signal power before fading, pass explicitly
sigPow = mean(abs(txSig).^2);
sigPowdBW = 10*log10(sigPow);
rxFaded = fadingChannel(txSig);
rxNoisy = awgn(rxFaded, snr, sigPowdBW);

% SIMPLEST: Use unit-power signal, t

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.