matlab-train-network

# matlab-train-network

Train, evaluate, and export neural networks to Simulink in MATLAB using the
recommended `dlnetwork`-based API (`trainnet`, `dlnetwork`, `minibatchpredict`,
`scores2label`, `testnet`, `imagePretrainedNetwork`) or, for tabular data, the
Statistics and Machine Learning Toolbox functions `fitcnet` and `fitrnet`.

## When to Use

Activate this skill when a user asks to:

- Train any neural network (classifier, regression, multi-output, LSTM, CNN, etc.)
- Fine-tune or use a pretrained model for transfer learning
- Evaluate a trained network on test data
- Run inference / predict with a trained network
- Export a trained network to Simulink
- Migrate existing legacy (patternnet, fitnet, narxnet, gensim) or discouraged
  (trainNetwork, DAGNetwork, classify) code to recommended APIs
- Create a "pattern recognition network", "function fitting network", "NARX
  network", or any task historically associated with the Neural Network Toolbox
  shallow nets API
- Speed up or optimize any deep learning code (even without mentioning dlaccelerate by name)
- Make existing deep learning code faster using dlaccelerate
- Diagnose and fix dlaccelerate issues (low HitRate, retracing, code is slower after using dlaccelerate)
- Accelerate custom training (code that uses dlfeval/dlgradient)
- Accelerate a function that supports dlarray input and is long running
- Accelerate a custom loss function passed to trainnet (R2026a+)

## When NOT to Use

- Importing/exporting models (importNetworkFromPyTorch, exportONNXNetwork)
- Data loading and preprocessing (imageDatastore, transforms, augmentation)
- Network architecture design decisions (choosing CNN vs LSTM vs transformer)
- Reinforcement learning workflows (use Reinforcement Learning Toolbox)
- Object detection (use specialized detector training functions in Computer Vision Toolbox)

## Decision: fitrnet/fitcnet or trainnet

Apply this check before starting any training workflow below.

| Criterion | fitcnet/fitrnet | trainnet |
|-----------|----------------|----------|
| Ease of use | Simplest — one function call | Requires network definition + trainingOptions |
| Solver | L-BFGS | Adam, SGDM, RMSProp, L-BFGS, LM (R2024b+) |
| Loss functions | MSE and cross-entropy only | Any built-in or custom (pass function handle) |
| Multiple input/output branches | No | Yes |
| Custom architecture | Via `Network` argument (R2025a+) | Yes |
| Data type | Tabular data only (a table or a numeric matrix) | Tabular data plus everything else (sequences, images, multi-input) |

Pass tables directly to `trainnet`, `fitcnet`, and `fitrnet`. If inputs have
categorical columns, pass them directly — they are encoded automatically
(`fitcnet`/`fitrnet` always; `trainnet`/`minibatchpredict`/`testnet` from R2025a).

```matlab
% Classification
mdl = fitcnet(tbl,responseName,LayerSizes=20);
[labels,score] = predict(mdl,tblTest);
L = loss(mdl,tblTest);

% Regression
mdl = fitrnet(tbl,responseName,LayerSizes=[20 20]);
Y = predict(mdl,tblTest);
L = loss(mdl,tblTest);

% Tabular data with trainnet (when fitcnet/fitrnet can't be used)
net = trainnet(tbl,net,"crossentropy",options);
accuracy = testnet(net,tblTest,"accuracy");
scores = minibatchpredict(net,tblPredictors);
```

- From R2024b, `fitrnet` supports multi-response variables.
- From R2025a, for custom architectures beyond `LayerSizes`, `Activations`, `LayerWeightsInitializer`, and `LayerBiasesInitializer`, pass a `dlnetwork` via the `Network` name-value argument.

---

## Conventions

### Training with trainnet + dlnetwork

#### Data formats

`trainnet` expects data in specific orientations by default:

| Input layer | Expected data shape |
|-------------|-------------------|
| `featureInputLayer(C)` | observations×channels (e.g., 150×4) |
| `imageInputLayer([H W C])` | height×width×channels×observations (e.g., 28×28×1×5000) |
| `sequenceInputLayer(C)` | timesteps×channels×observations, or an observations×1 cell array where each element is a timesteps×channels time series |

If your data has a different layout, use `InputDataFormats` and/or
`TargetDataFormats` in `trainingOptions` instead of transposing the data manually.
The format string describes your data's current layout — one letter per
dimension, not the desired layout. MATLAB handles the remapping internally.
For cell arrays, add `"B"` (batch) to the format string — e.g.,
`InputDataFormats="CTB"` for cells of C×T matrices. Do not specify these
options when data already matches the input layer's default.

#### What trainnet supports

Use `trainnet` and `dlnetwork` for all Deep Learning Toolbox training. This includes:

- Standard classification and regression
- Transfer learning
- Multi-input or multi-output networks
- Custom loss functions (pass a function handle to `trainnet`)
- Custom loss function backward passes via `DifferentiableFunction`
- Custom metrics (string, function handle, or `deep.Metric` subclass)
- Custom stopping criteria via `OutputFcn` in `trainingOptions`
- Custom layers

Custom training loops (`dlfeval`/`dlgradient`/update functions) are appropriate
when the workflow requires customizations impossible via `trainingOptions` or
the specific workflow — multi-model adversarial training, alternating updates,
or custom weight update rules. Note that `trainingOptions` supports L-BFGS (R2023b+)
and Levenberg-Marquardt `"lm"` (R2024b+).

When a user has a working custom training loop and asks to speed it up, apply
`dlaccelerate` directly. Mention that their workflow may also be expressible
with `trainnet` (which handles acceleration internally), but do not push the
conversion — focus on accelerating the code they have.

### NEVER use these legacy or discouraged APIs

If the user has existing code using these APIs, migrate it to the recommended
replacement and briefly explain which APIs were replaced and what the modern
equivalents are. If the user asks for a legacy or discouraged API by name,
acknowledge their request and explain that the function