matlab-import-external-ai-model

# Import Deep Learning Models into MATLAB

Import trained PyTorch, ONNX, or Keras 3 models into MATLAB as `dlnetwork`
objects and verify numerical correctness.

## When to Use

- User wants to import a deep learning model from PyTorch, ONNX, or Keras/TensorFlow
- User has `.pt2`, `.pt`, `.onnx`, or `.keras` files to bring into MATLAB
- User mentions `importNetworkFromPyTorch`, `importNetworkFromONNX`, `importNetworkFromKeras`, or `importNetworkFromTensorFlow`
- User mentions `torch.export.export`, `torch.jit.trace`, `PyTorchInputSizes`, `InputDataFormats`, or `matlabsaver`
- User encounters import errors, unsupported operator warnings, uninitialized networks, or 0 learnables after import
- User wants to validate that an imported model matches the source framework's outputs

## When NOT to Use

- Exporting MATLAB networks to ONNX/PyTorch (use `exportONNXNetwork` / `exportNetworkToPyTorch`)
- Training or fine-tuning after import — use `/matlab-train-network`
- Deploying to embedded hardware — use `/matlab-deploy-embedded-ai`
- Simulink integration after import (agent handles this well without guidance)

## Router: Which Framework?

```
Q: What format is the source model?
 |
 +-- .pt2 (PyTorch exported program) ──────────> PYTORCH IMPORT below
 +-- .pt (PyTorch traced model) ───────────────> PYTORCH IMPORT below
 +-- .onnx ────────────────────────────────────> ONNX IMPORT below
 +-- .keras / TensorFlow 2.16+ / matlabsaver ──> KERAS IMPORT below
 +-- Unknown ("import my model") ──────────────> Ask: framework? file extension?
```

---

## PyTorch Import

Full pipeline: export from PyTorch → import into MATLAB → validate numerics.

### Determine Starting Point

| User has | Action |
|----------|--------|
| PyTorch model (code or saved) | Export as .pt2 first → see `references/pytorch-export-guidance.md` |
| `.pt2` file (exported program) | Import directly (below) |
| `.pt` file (traced model) | Import with input sizes (below) |

**Always prefer .pt2 over .pt.** If user has a traced model, recommend re-exporting
with `torch.export.export` first. Only use traced path if re-export is not feasible.

### Import .pt2 (Exported Program)

```matlab
net = importNetworkFromPyTorch("model.pt2");
```

No input size argument needed — shape info is embedded in the .pt2 file.

### Import .pt (Traced Model)

```matlab
net = importNetworkFromPyTorch("model.pt", ...
    PyTorchInputSizes=[1 3 224 224]);
```

`PyTorchInputSizes` is **mandatory** for traced models. Specify sizes in PyTorch
dimension ordering. For multiple inputs use a cell array: `{[1 3 256 256], [1 10]}`.

### Name-Value Arguments

| Argument | When to use |
|----------|-------------|
| `PyTorchInputSizes` | **Required** for traced models (.pt). Not needed for .pt2 |
| `Namespace` | Control where auto-generated custom layer files are stored |
| `PreferredNestingType` | Choose `"networklayer"` (default) or `"customlayer"` |

### PyTorch Critical Mistakes

| Mistake | Correct Approach |
|---------|-----------------|
| Using `InputShape` NV argument | Does not exist — use `PyTorchInputSizes` for .pt, nothing for .pt2 |
| Using `PackageName` NV argument | Deprecated — use `Namespace` |
| Not calling `model.to("cpu")` before export | Always `model.to("cpu")` before export |
| Not checking PyTorch version before export | Assert `torch.__version__` starts with "2.8" |
| Passing `PyTorchInputSizes` for .pt2 | Unnecessary — .pt2 embeds shape info, omit it |
| Guessing input size for unknown models | Always ask the user for exact input dimensions |
| Assuming `net.InputNames` matches `forward()` order | Importer may reorder — always check `net.InputNames` |

### PyTorch Conventions

- Always `model.to("cpu")` and `model.eval()` before export
- Always verify PyTorch version is 2.8 before exporting as .pt2
- Never guess input sizes — ask the user or inspect the model
- Use `Namespace` not `PackageName` for custom layer storage
- Prefer .pt2 over .pt — recommend `torch.export.export` over `torch.jit.trace`

### PyTorch References

- `references/pytorch-export-guidance.md` — Full Python-side export procedure
- `references/pytorch-import-guidance.md` — Detailed MATLAB import for both formats
- `references/pytorch-numeric-validation.md` — Dimension conversion and tolerance comparison
- `references/pytorch-placeholder-guidance.md` — Implementing unsupported ops in custom layers
- `scripts/validateImportedNetwork.m` — Helper function for numeric validation against .npy reference data

---

## ONNX Import

Import ONNX models using `importNetworkFromONNX`, diagnose issues, verify numerics.

### Workflow

```
1. IMPORT  → importNetworkFromONNX with appropriate NVPs
2. DIAGNOSE → Check initialization, custom layers, warnings
3. RESOLVE  → Fix issues (InputDataFormats, placeholder functions)
4. VERIFY   → Compare outputs against ONNX Runtime (if installed)
```

**CRITICAL: Do NOT re-import after step 3.** Re-importing regenerates `+ops/` and overwrites all custom implementations.

### Import

```matlab
net = importNetworkFromONNX("model.onnx");
```

If you know the input format:

```matlab
net = importNetworkFromONNX("model.onnx", InputDataFormats="BCSS");
```

### Diagnose and Resolve

If `net.Initialized` is false, read the input shape and re-import with `InputDataFormats`:

```matlab
net = importNetworkFromONNX("model.onnx");
if ~net.Initialized
    inputLayer = net.Layers(1);
    fprintf("NumDims: %d\n", inputLayer.NumDims);
end
```

### InputDataFormats Reference

Characters: `B` (batch), `C` (channel), `S` (spatial), `T` (time), `U` (unspecified).

| ONNX Input Shape | InputDataFormats |
|-----------------|------------------|
| [N, C, H, W] | `"BCSS"` |
| [N, C] | `"BC"` |
| [N, T, C] | `"BTC"` |
| [N, C, T] | `"BCT"` |

### Verify Against ONNX Runtime

If `onnxruntime` is installed in the user's Python environment, compare outputs. If not installed, skip — do not ask the user to install it.

```matlab
try
    ort = py.importlib.import_module("onnxruntime");