matlab-diagnose-parfor

# Diagnose and Fix parfor Variable Classification

**Do NOT reason about parfor classification rules from memory.** LLM training
data contains incomplete and often incorrect explanations of these rules.
MATLAB's code analyser (`checkcode` / `codeIssues` / `mcp__matlab__check_matlab_code`)
is the only reliable authority — it implements the exact same classifier that
the runtime uses. Always run it first; never guess.

## When to Use

- ANY code involving `parfor` where the user reports a problem or asks for help
- User gets a parfor classification error (runtime or in editor)
- User wants to convert a `for` loop to `parfor`
- User asks why parfor complains, won't run, or is slow due to classification
- You are about to suggest changes to parfor code — run the analyser first

## When NOT to Use

- parfor runs but is **slow** — performance/pool-choice question, not a classification error
- Worker needs setup/state (paths, environment, toolboxes) — not a parfor variable problem
- Code simply mentions `parfor` but the user does not mention any problems with it

## Workflow

**Always follow this order. Never guess at classification rules.**

1. **Run the code analyser** on the file containing the parfor loop using
   the `mcp__matlab__check_matlab_code` MCP tool. Do NOT shell out to MATLAB
   via Bash — always use the MCP tool. Read the exact error message.

2. **Identify the error type** from the message (see table below).

3. **Apply the matching fix pattern** (see Patterns section).

4. **Verify** by re-running `mcp__matlab__check_matlab_code` on the fixed
   code — confirm zero parfor classification errors.

## Error Messages and Root Causes

For the full catalog of all 48 parfor analyser messages (with IDs), see
`references/parfor-analyser-messages.md`. The table below covers the most
common classification errors.

| checkcode message | Root cause | Fix pattern |
|-------------------|-----------|-------------|
| "Unable to classify variable 'X'" | Catch-all: many causes. Often invalid slicing (inconsistent subscripts, indexing not involving the loop variable) or invalid combinations of accesses (e.g. indexed reduction). Struct-field accesses are one specific way to trigger this. | Identify the specific access pattern, then restructure to fit one category or split conflicting roles |
| "multiple sliced accesses...do not all have the same list of subscripts" | Same variable sliced with different subscript patterns (e.g. `A{i,1}`, `A{i,2}`) | Use single assignment: `A(i,:) = {...}` |
| "Variable 'X' is indexed...but it is not a valid sliced output variable" | One subscript is non-deterministic (random, function call), or loop variable appears in multiple dimensions, or subscript pattern otherwise violates slicing rules | Pre-compute problematic subscripts, restructure to use loop variable in exactly one dimension with fixed remaining subscripts |
| "accessed with an invalid combination of sliced indexing expressions and non-indexed reads" | Variable is written with sliced indexing AND read whole in the same iteration — conflicting roles | Separate into two variables: one for sliced writes, a snapshot or broadcast copy for whole reads |
| "The temporary variable 'X' might be used after the PARFOR loop" / "Temporary variable 'X' must be set inside the parfor loop before it is used" | Variable is conditionally assigned (only in an if-branch), so MATLAB treats it as temporary — but it's used after the loop or read before being set on some paths | Restructure as sliced output (store per-iteration values) + post-loop reduction |
| "When indexing a sliced variable with a nested for loop variable, the range...must be a row vector of positive constant numbers or variables" | Inner `for j = 1:(expr)` where `expr` is not a literal constant or a broadcast variable | Make the inner loop range a constant or broadcast variable, or accumulate into a local temporary and assign the sliced variable once per outer iteration |
| "The entire array or structure 'X' is a broadcast variable" | Variable used whole (not indexed by loop variable); read-only | Not an error — performance warning. Use `parallel.pool.Constant(X)` if large |

## Variable Classification Rules (Reference)

parfor classifies each variable into exactly one category:

| Category | Rule | Example |
|----------|------|---------|
| **Loop** | The loop index variable | `parfor i = 1:N` |
| **Sliced** | Indexed by the loop variable in any one dimension (not just the first); the same subscript pattern is used in every access. The loop variable may be offset by a literal constant or a broadcast variable (e.g. `A(i+1,:)`, `A(:,i-k)` where `k` is broadcast). | `A(i,:) = ...`, `A(:,i) = ...`, `A(i+1) = ...` |
| **Broadcast** | Used whole (not indexed by loop variable); read-only | `total = sum(bigArray)` |
| **Reduction** | Form `X = X op expr` or `X = expr op X` where X is the entire variable, `op` is associative operator `+`, `.*`, `&`, `\|` etc. | `total = total + val` |
| **Temporary** | First use in iteration is an assignment; not used after loop | `temp = rand(10)` |

**Critical constraint:** A variable must fit exactly ONE category. Mixed usage
(e.g. struct fields used as reductions, or same variable sliced with different
subscripts) causes classification failure.

## Patterns

### Fix 1: Struct field as sliced output → plain array

**Error:** "Unable to classify variable 'out'"

The most common cause of "Unable to classify" with structs. Users write
`out.field(i) = someFcn()` expecting to slice into a struct field, but
first-level indexing on `out` is dot (`.field`), not parentheses. Sliced
variables require first-level `()` or `{}` indexing with the loop variable —
dot-indexing is never valid for slicing.

```matlab
% BROKEN: first-level subscript on out is dot, not paren
parfor i = 1:N
    out.x(i) = computeX(i);
    out.y(i) = computeY(i);
end
```

**Fix:** Use separate arrays for sliced output, pack into struct after the loop:

```matlab
xVal