Skip to content

matlab/matlab-agentic-toolkit / skills-catalog/ai-and-statistics/matlab-deploy-embedded-ai

matlab-deploy-embedded-ai

Verified

Deploy AI models to embedded hardware using MathWorks tools (MATLAB, Simulink, Embedded Coder). Covers two workflow patterns: (1) MathWorks-native or imported models rebuilt as dlnetwork for lean hardware, (2) direct C/C++ code generation from PyTorch and LiteRT models. Both patterns support all targets (Cortex-M/A/R, x86, GPU). Trigger when: user wants to deploy AI to embedded targets; generate C/CUDA from neural networks; compress AI models for MCU; integrate AI in Simulink for system-level simulation; import PyTorch/ONNX/TensorFlow models for embedded deployment; optimize AI for resource-constrained hardware; or use loadPyTorchExportedProgram, loadLiteRTModel, importNetworkFromPyTorch, importNetworkFromONNX, importNetworkFromTensorFlow, importNetworkFromKeras, dlquantizer, exportNetworkToSimulink, or Embedded Coder with AI models.

references/pattern2/troubleshooting.md

View on GitHub
# Troubleshooting -- Pattern 2 (PyTorch/LiteRT Code Generation)

Common errors when using `loadPyTorchExportedProgram` and the PyTorch/LiteRT code
generation pipeline.

## Codegen Failures

### Error: DeepLearningConfig not set / library not found

**Cause:** Default config tries to use CUDNN/TensorRT/oneDNN which aren't installed.

**Fix:**
```matlab
cfg.DeepLearningConfig = coder.DeepLearningConfig('none');
```

This generates fully portable C with zero external dependencies.

### Error: Unsupported operation

**Cause:** A PyTorch op maps to an intermediate operation that MATLAB Coder does not
yet support for code generation. This is rare but possible for uncommon ops.

**Diagnosis:**
```matlab
% The codegen error message will name the specific unsupported operation
% e.g., "scatter is not supported for code generation"
```

**Fix options:**
1. Check if a newer MATLAB release supports the op (coverage expands each release)
2. Restructure the PyTorch model to avoid the unsupported op before re-exporting
3. If the op is at the output stage (e.g., argmax, topk), consider removing it from the
   PyTorch model and implementing it in the MATLAB entry-point function instead

### Error: Input size mismatch

**Cause:** The `coder.typeof` input specification doesn't match what the .pt2 model expects.

**Fix:** The input type must exactly match the shape used during `torch.export`:
```matlab
% If PyTorch was exported with: torch.randn(1, 10, 5)
% Then MATLAB must use:
inputType = coder.typeof(single(zeros(1, 10, 5)), [1 10 5], [false false false]);
```

The third argument `[false false false]` means all dimensions are fixed (not variable-size).
For embedded codegen, all dimensions should be fixed.

---

## Import / Loading Failures

### Error: loadPyTorchExportedProgram not found

**Cause:** MATLAB Coder Support Package for PyTorch and LiteRT Models not installed.

**Fix:**
```matlab
% Check availability
exist('loadPyTorchExportedProgram', 'file')
```
Install via Add-On Explorer (Home > Add-Ons > Get Add-Ons).

### Error: Failed to load .pt2 file

**Cause:** The .pt2 file was created with an incompatible torch version, or the export was incomplete.

**Fix:**
1. Verify the .pt2 loads in Python first:
   ```python
   ep = torch.export.load('model.pt2')
   out = ep.module()(example_input)  # Should run without error
   ```
2. Re-export with the same torch version that MATLAB's support package expects
3. Ensure `model.eval()` was called before export

---

## Configuration Mistakes

### InstructionSetExtensions on wrong object

```matlab
% WRONG -- dlcfg does not have this property
dlcfg = coder.DeepLearningConfig('none');
dlcfg.InstructionSetExtensions = 'Neon v7';   % ERROR: Unrecognized property

% CORRECT -- it belongs to cfg (the coder config, not the DL config)
cfg.InstructionSetExtensions = 'Neon v7';
```

### Invalid hardware names

```matlab
% These are NOT valid Embedded Coder hardware names:
'ARM Cortex-A embedded platform'    % Not recognized
'ARM Cortex-A'                      % Not recognized
'STM32F746G-Discovery'              % Only if STM32 support pkg installed

% Valid names (require corresponding support packages):
'Raspberry Pi'
'BeagleBone Black'
'NVIDIA Jetson'
```

### OpenMP on single-core MCU

```matlab
% WRONG for Cortex-M (single-core) -- adds threading overhead for no benefit
cfg.EnableOpenMP = true;

% CORRECT for Cortex-M
cfg.EnableOpenMP = false;

% CORRECT for Cortex-A (quad-core) -- measured 3x speedup
cfg.EnableOpenMP = true;
```

---

## C Compilation Issues

### Missing MATLAB runtime headers

**Error:** `rtwtypes.h not found` or `tmwtypes.h not found`

**Fix:** Add MATLAB extern include path to your compiler command:
```bash
gcc -I"$MATLAB_ROOT/extern/include" ...
```

Where `MATLAB_ROOT` is typically:
- **Windows:** `C:\Program Files\MATLAB\R2026a`
- **macOS:** `/Applications/MATLAB_R2026a.app`
- **Linux:** `/usr/local/MATLAB/R2026a`

### Linker errors when using LargeConstantThreshold = 0

**Error:** Undefined reference to `fopen`, `fread` -- the generated code tries to load .bin files.

**Fix:** Ensure stdio is available on your target. For bare-metal MCU without a filesystem,
use a high `LargeConstantThreshold` value (or omit the setting) to embed weights inline:
```matlab
% For targets WITH filesystem (Linux, RTOS with FS)
cfg.LargeConstantThreshold = 0;  % Weights in .bin files

% For bare-metal targets WITHOUT filesystem
% Don't set LargeConstantThreshold -- weights inline in .c
```

### Wrong output from generated C

**Most common cause:** Input layout mismatch. The generated C code expects **column-major**
input arrays. If you're feeding row-major data (the default in C/Python), the results will
be wrong.

**Fix:** Transpose in the test harness:
```c
// Row-major [t][f] --> column-major [t + f * SEQ_LEN]
for (int t = 0; t < SEQ_LEN; t++)
    for (int f = 0; f < NUM_FEATURES; f++)
        c_input[t + f * SEQ_LEN] = row_major_input[t * NUM_FEATURES + f];
```

See [`architecture-patterns.md`](architecture-patterns.md) for format details per model type.

---

## PyTorch Export Issues

### torch.export fails with dynamic control flow

**Error:** `torch._dynamo.exc.Unsupported: ...`

**Cause:** The model uses Python `if/else` on tensor values or data-dependent loops.

**Fix:** Restructure the model to use static control flow:
```python
# WRONG -- dynamic control flow
def forward(self, x):
    if x.sum() > 0:  # Data-dependent branch
        return self.path_a(x)
    else:
        return self.path_b(x)

# CORRECT -- static (always runs both, selects via mask)
def forward(self, x):
    a = self.path_a(x)
    b = self.path_b(x)
    mask = (x.sum() > 0).float()
    return a * mask + b * (1 - mask)
```

### torch.export fails with in-place operations

**Error:** `RuntimeError: Mutations on a value inside the trace`

**Cause:** In-place operations like `x.add_(y)` or `x[0] = val`

**Fix:** Replace with out-of-place equivalents:
```python
# WRONG
x.add_(y)

# CORRECT
x = x + y
```

---

## Diagnostic Commands

```matlab
% Check if support package is installed
exist('loadPyTorchExportedProgram', 'file')

% Verify .pt2 loads
net = loadPyTorchExportedProgram('model.pt2');
out = invoke(net, single(randn(inputShape)));
disp(size(out))

% Retry codegen after fixing the issue
codegen -config cfg predict_fn -args {inputType}
```

## Quick Decision Matrix

| Symptom | Most Likely Cause | Fix |
|---------|------------------|-----|
| `loadPyTorchExportedProgram` not found | Support package not installed | Install via Add-On Explorer |
| Python error during load | Support package Python env issue | Reinstall support package from Add-On Explorer |
| Codegen fails with library error | DeepLearningConfig not set | Set to `'none'` |
| Codegen fails on unsupported op | Operation not yet supported | Restructure model or update MATLAB |
| C output is wrong | Column-major vs row-major | Transpose input in C harness |
| C compilation fails on headers | Missing MATLAB include path | Add `-I$(MATLAB_ROOT)/extern/include` |
| C fails to load weights | No filesystem on MCU | Remove `LargeConstantThreshold = 0` |
| Performance is slow | OpenMP/SIMD not enabled | See [`coder-configuration.md`](coder-configuration.md) |


Copyright 2026 The MathWorks, Inc.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall