matlab/agent-skills-playground / demos/embedded-ai-deployment/skills/embedded-ai-deployment
embedded-ai-deployment
VerifiedDeploy AI models to embedded hardware using MathWorks tools (MATLAB, Simulink, Embedded Coder). Covers two workflow patterns: (1) MathWorks-native or 3P-imported models rebuilt as dlnetwork for lean hardware (Cortex-M, DSP), (2) direct C/C++ code generation from PyTorch and LiteRT models for high-performance hardware (Cortex-A, x86, GPU). Trigger when: user wants to deploy AI to embedded targets; generate C/CUDA from neural networks; compress AI models for MCU/DSP; 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, importNetworkFromPyTorch, dlquantizer, exportNetworkToSimulink, or Embedded Coder with AI models.
references/pattern1/compression.md
View on GitHub# Model Compression and Quantization
Patterns for compressing AI models for deployment on resource-constrained embedded hardware.
Compression reduces flash/RAM footprint for flash-constrained targets. Compression
requirements differ by technique:
- **Quantization (`dlquantizer`):** requires a **native dlnetwork** with built-in layers —
imported networks with custom autogenerated layers are not supported.
- **Projection (`compressNetworkUsingProjection`):** works on imported networks **as long
as the learnables live in built-in layers** (e.g., `fullyConnectedLayer`, `lstmLayer`,
`convolution2dLayer`). The more common blocker is **unformatted dlarray inputs**:
imported networks frequently end up with input formats labelled `"UU"` or `"UUU"`,
which the projection PCA step cannot interpret. Workarounds typically involve wrapping the
imported network so the input is presented with a proper format (`"CB"`, `"CBT"`,
`"SSCB"`, etc.) before calibration.
- **Pruning (`compressNetworkUsingTaylorPruning`):** also expects a native dlnetwork.
For maximum compatibility, rebuilding as a native dlnetwork remains the safest path.
**Choose the compression path before applying techniques.** The right combination of
pruning, projection, and quantization depends on the user's hardware target, deployment
goal (flash vs SRAM vs latency vs accuracy), and retraining tolerance. Load
[`compression-decision.md`](compression-decision.md) at the start of Phase 5 and walk
the user through the question flow before applying any technique. Compression is not
mandatory and is not always optimal — for example, on ARM Cortex-M with a latency-bound
LSTM model, the float32 path with CMSIS-DSP matrix-multiply replacement outperforms a
quantized path because CMSIS-NN provides no INT8 kernels for recurrent layers.
**CRITICAL:** Do NOT implement pruning, projection, or quantization in custom MATLAB
code. Always use the official MathWorks functions listed below. These functions are
part of the Deep Learning Toolbox Model Compression Library and are designed for
correctness, code generation compatibility, and integration with the deployment toolchain.
## Official Compression Functions Reference
| Technique | Key Functions |
|--------------|---------------------------------------------------------------------------|
| Pruning | `compressNetworkUsingTaylorPruning` |
| Projection | `compressNetworkUsingProjection` (calls `neuronPCA` internally; precompute separately only for multi-goal sweeps), `ProjectedLayer`, `lstmProjectedLayer`, `gruProjectedLayer` |
| Quantization | `prepareNetwork`, `dlquantizer`, `dlquantizationOptions`, `calibrate`, `quantize`, `validate`, `quantizationDetails`, `estimateNetworkMetrics`, `equalizeLayers` |
## Compression Techniques Overview
The table below summarizes the **mechanism** of each technique. **Flash, SRAM, and
accuracy outcomes are model-dependent** — especially for structural compression
(pruning and projection), where the same reduction goal can produce very different
results across architectures and datasets. Always measure on the actual model with
held-out data before committing to a path.
| Technique | Function | Flash impact | SRAM (activation memory) impact | Accuracy impact | Retraining |
|-----------|----------|--------------|-------------------------------|-----------------|------------|
| **Pruning** (structural) | `compressNetworkUsingTaylorPruning` | Reduces — removes filters, so weight matrices shrink | **Reduces** — fewer activations to store between layers | Model-dependent; iterative scoring + fine-tuning aims to hold accuracy within the user's budget | Required (between iterations) |
| **Projection** (structural) | `compressNetworkUsingProjection` | Reduces — low-rank factorization shrinks weight matrices | Does **not** reduce | Model-dependent; do a trade-off analysis | Typically required; modest goals can be tried without retraining as a trade-off pass |
| **INT8 quantization** (non-structural) | `dlquantizer` (`prepareNetwork`, `calibrate`, `quantize`) | Up to ~4× from the FP32 → INT8 weight storage drop, before per-layer overhead | Activation buffers also drop to INT8 (up to ~4× depending on shapes) | Model-dependent; usually small for CNN/FC, depends on output dynamic range and calibration set | Not required (post-training) |
| **Combined** (pruning and/or projection + quantization) | All of the above, in order | Multiplicative across techniques | Multiplicative (skip projection if SRAM is the goal) | Model-dependent; ~77% combined flash savings has been reported on representative CNN + FC examples | Required for the structural stages |
A separate manual INT8 (per-matrix min-max scaling) fallback is documented later
in this file for cases where `dlquantizer` is not viable; it is a fallback, not
a peer technique.
**No single recommended default.** Pick the technique based on the goal collected via
[`compression-decision.md`](compression-decision.md):
- **Flash-bound + retraining OK** → combined **pruning + projection + quantization**
(each technique attacks a different source of flash; combining them is multiplicative)
- **Flash-bound + no retraining** → quantization, optionally with a conservative
projection trade-off pass on overparameterized models (try the default
`ExplainedVarianceGoal=0.95` first, or sweep `LearnablesReductionGoal` and
measure accuracy)
- **SRAM-bound** → **pruning + quantization** (skip projection — it does not reduce
activation memory)
- **Latency-bound** → hardware-dependent. Structural compression (pruning, projection)
is also worth trying — fewer MACs typically means lower latency, and on MCU targets
the structural savings can dominate kernel-replacement gains. On Cortex-M with
recurrent layers, skip quantization for the LSTM/GRU portion (CMSIS-NN has no
INT8 recurrent kernels; float32 + CMSIS-DSP is faster).
- **Accuracy-first** → try compression with accuracy gating before falling back to
the float32 baseline. `compressNetworkUsingTaylorPruning` exposes a
`ValidationThreshold` NVP that stops pruning as soon as the validation metric
drops below the threshold; quantization with proper calibration often preserves
accuracy on overparameterized models.
## Compression Paths by Model Type
| Model Type | Compression Toolbox | Primary Techniques |
|--------------------------|------------------------------------------------|----------------------------|
| `dlnetwork` | Deep Learning Toolbox Model Compression Library | Quantization, Pruning, Projection |
| `fitcnet` / `fitrnet` | Fixed-Point Designer | Fixed-point conversion |
## Compression Order (Combined Pipeline)
For maximum compression, apply techniques in this order:
1. **Prune first** -- Remove unnecessary weights (structured weight removal)
2. **Project second** -- Reduce layer dimensions (`compressNetworkUsingProjection`)
3. **Quantize last** -- Convert to lower precision (INT8)
### When to Include Projection
`compressNetworkUsingProjection` supports `convolution1dLayer`
(since R2024b), `convolution2dLayer`, `fullyConnectedLayer`, `lstmLayer`, and
`gruLayer`. Include projection when:
- The user's goal is **flash reduction** (projection shrinks weight matrices), AND
- The user can tolerate **retraining / fine-tuning** (projection always requires it), AND
- The model contains at least one supported layer type, AND
- No projectable layer shares learnable parameters via weight tying (unsupported).
**Skip projection when:**
- The user's goal is latency (projection doesn't help; for Cortex-M LSTM/GRU,
un-quantized float32 with CMSIS-DSP is the latency winner)
- The user's goal is SRAM reduction only (projection does not shrink activation memory)
- Retraining is not acceptable
- The model has no supported layer types
- The user is targeting maximum accuracy with no compression budget
### Reporting Compression Results
After each compression step, summarize the outcome (accuracy delta vs. the
uncompressed baseline, flash/SRAM savings) so the user can make a go/no-go
decision before proceeding. No fixed template is required.
**Anti-pattern: do not hardcode numeric values in print statements.** Always
read the values from MATLAB variables computed in the same run. If a script is
re-executed with different inputs or a different model, hardcoded numbers in
`fprintf`/`disp` strings will silently lie about the new results.
```matlab
% BAD — value is baked into the format string:
fprintf("Quantization MAE: 1.2e-3 (within budget)\n");
% GOOD — value is computed and printed from a variable:
mae = mean(abs(yBase(:) - yQuant(:)));
verdict = "FAIL";
if mae < budget
verdict = "PASS";
end
fprintf("Quantization MAE: %.3e (budget: %.1e) — %s\n", mae, budget, verdict);
```
---
## dlnetwork Compression: Deep Learning Toolbox Model Compression Library
This library is a **support package**, not a toolbox. It is NOT detected by
`detect_matlab_toolboxes`. To check availability, use:
```matlab
pkgs = matlabshared.supportpkg.getInstalled;
hasCompLib = false;
if ~isempty(pkgs)
hasCompLib = any(contains({pkgs.Name}, "Model Compression"));
end
```
If not installed, **do not install on the user's behalf**. Direct the user to the
MATLAB Add-On Explorer to download it, then wait for confirmation before proceeding.
---
## Pruning (Structured Weight Removal)
Pruning removes the least important convolutional filters to reduce model size and
computation. Use `compressNetworkUsingTaylorPruning` — it handles the full iterative
workflow (score calculation, filter removal, fine-tuning) in a single call.
```matlab
% Define fine-tuning options for the pruning loop
options = trainingOptions("adam", ...
MaxEpochs=10, ...
MiniBatchSize=32, ...
InitialLearnRate=1e-4, ...
Verbose=false);
% Prune: remove 30% of learnable parameters
[prunedNet, info] = compressNetworkUsingTaylorPruning(net, XTrain, YTrain, ...
"crossentropy", options, ...
LearnablesReductionGoal=0.3, ...
LearnablesReductionIncrement=0.05, ...
Plots="pruning-progress");
% Inspect results
fprintf("Achieved reduction: %.1f%%\n", info.LearnablesReduction * 100);
fprintf("Pruned layers: %s\n", strjoin(info.PrunedLayerNames, ", "));
fprintf("Stop reason: %s\n", info.StopReason);
```
For the full list of name-value arguments, defaults, and behavior, consult the
function's help (`help compressNetworkUsingTaylorPruning`) or the
[reference page](https://www.mathworks.com/help/deeplearning/ref/compressnetworkusingtaylorpruning.html)
rather than relying on a list in this file. Two name-value arguments that are
worth flagging because they affect the recipe:
- `LearnablesReductionGoal` — target proportion of parameters to remove. Drives
the trade-off between flash savings and accuracy.
- `ValidationThreshold` — stops the iterative pruning loop as soon as the
validation metric drops below the threshold. Use this when accuracy is the
primary constraint (see the "Maximize accuracy" recipe in [`compression-decision.md`](compression-decision.md)).
**Notes:**
- Requires the Deep Learning Toolbox Model Compression Library (support package).
`compressNetworkUsingTaylorPruning` is the high-level R2026a API; older builds
of the support package shipped only the lower-level `taylorPrunableNetwork`
workflow (score → updateScore → updatePrunables → trainnet loop). If
`which compressNetworkUsingTaylorPruning` returns "not found" on a system
with the support package installed, the SPKG is on a stale build — ask the
user to update the support package via Add-On Explorer.
- Operates on convolutional layers only; for FC/LSTM/GRU reduction (or for additional conv-layer reduction), use projection
- Output is a standard `dlnetwork` — no conversion step needed
- The function iteratively scores filters, removes lowest-scoring, and fine-tunes
---
## Projection (Layer Dimension Reduction)
Projection reduces the dimensionality of supported layers using principal component
analysis of neuron activations. For the up-to-date list of supported layers and any
release-specific limitations (such as restrictions on layers that share learnable
parameters via weight tying), see the
[`compressNetworkUsingProjection` reference page](https://www.mathworks.com/help/deeplearning/ref/compressnetworkusingprojection.html).
To inspect a specific network's compressibility visually, open it in **Deep Network
Designer** (`deepNetworkDesigner(net)`) and use the compression analysis pane — it
flags which layers are eligible for projection, pruning, and quantization without
requiring you to reason about the support list yourself.
```matlab
% Single-call projection: pass calibration data directly. Internally the
% function runs the PCA step and applies projection in one call.
% Always capture the second output (info struct) — it reports what
% actually happened, which is essential for verifying that the requested
% reduction was applied to the layers you expected.
[projectedNet, info] = compressNetworkUsingProjection(net, XTrain);
fprintf("Achieved learnables reduction: %.1f%%\n", info.LearnablesReduction * 100);
fprintf("Mean explained variance: %.3f\n", mean(info.ExplainedVariance));
fprintf("Projected layers: %s\n", strjoin(info.LayerNames, ", "));
% When to call neuronPCA separately: only when you plan to reuse the PCA
% across multiple projection goals (e.g., a trade-off sweep), since the
% PCA step can be expensive. For a single goal, the one-call form above
% is the recommended path.
% With UnpackProjectedLayers=false (the default), every compressed layer in
% the result is wrapped in a ProjectedLayer object — regardless of whether
% the original was an FC, conv, LSTM, or GRU layer. The actual unpacked
% structure (multiple FC/conv layers for FC/conv inputs, or
% lstmProjectedLayer / gruProjectedLayer for recurrent inputs) only
% appears after unpacking — see "Preparing Projected Networks for Code
% Generation" below.
% Fine-tune after projection
options = trainingOptions("adam", ...
MaxEpochs=20, ...
MiniBatchSize=32, ...
InitialLearnRate=1e-4, ...
Verbose=false);
projectedNet = trainnet(XTrain, YTrain, projectedNet, "crossentropy", options);
```
**Layer types in the output network:**
| `UnpackProjectedLayers` | What `compressNetworkUsingProjection` returns |
|---|---|
| `false` (default) | Every compressed layer is a `ProjectedLayer`, regardless of the original layer type. The `ProjectedLayer` wraps the equivalent sub-network internally. |
| `true` | Each `ProjectedLayer` is replaced by its unpacked equivalent: two or three `fullyConnectedLayer` objects (from an FC original), two or three `convolution1dLayer`/`convolution2dLayer` objects (from conv originals), a single `lstmProjectedLayer` (from an LSTM), or a single `gruProjectedLayer` (from a GRU). |
The same unpacking can also be applied after the fact via
`unpackProjectedLayers(projectedNet)`. Codegen support depends on the
unpacked layer type:
- `lstmProjectedLayer` and `gruProjectedLayer` are supported for generic
C/C++ code generation via `coder.loadDeepLearningNetwork` (no MKL-DNN /
ARM Compute Library acceleration; in R2026a, `HasStateInputs` /
`HasStateOutputs` modes are also supported on the generic path).
- A `ProjectedLayer` wrapper is supported for codegen when its contents
are stateless — that is, conv/FC layers, or LSTM/GRU layers in
stateful-I/O mode. A wrapped LSTM/GRU with stored state is not
codegen-compatible until unpacked.
`exportNetworkToSimulink` accepts projected networks directly in R2026a.
For the direct MATLAB Coder path, when in doubt, calling
`unpackProjectedLayers` before `coder.loadDeepLearningNetwork` removes
the wrapper and produces the most codegen-friendly form (see "Preparing
Projected Networks for Code Generation" below).
### Projection for Sequence Models (LSTM/GRU)
Since R2026a, `compressNetworkUsingProjection` accepts the same input data
types as `trainnet` (including a **cell array of sequences**), and exposes
the sequence-batching name-value arguments — `MiniBatchSize`,
`SequenceLength`, `SequencePaddingDirection`, `SequencePaddingValue`,
`InputDataFormats` — directly. The older `minibatchqueue` wrapper is no
longer needed.
```matlab
% Calibration data: cell array of single sequences in [features × time] layout
calibData = cell(numCalib, 1);
for i = 1:numCalib
calibData{i} = single(randn(numFeatures, seqLen));
end
% Single-call projection. MiniBatchSize=1 avoids padding across sequences
% (padding is documented to hurt PCA quality); use SequenceLength="shortest"
% instead if larger mini-batches are required. Omit LearnablesReductionGoal
% to let the function use its default (ExplainedVarianceGoal=0.95).
[projNet, info] = compressNetworkUsingProjection(baseNet, calibData, ...
MiniBatchSize=1);
fprintf('Actual reduction: %.1f%%\n', info.LearnablesReduction * 100);
fprintf('Compressed layers: %s\n', strjoin(info.LayerNames, ', '));
```
If the function cannot infer the input format (for example, when the
network's input is unformatted, with format `"UU"` / `"UUU"`), set
`InputDataFormats` explicitly. For the full list of name-value arguments
see the [`compressNetworkUsingProjection` reference page](https://www.mathworks.com/help/deeplearning/ref/compressnetworkusingprojection.html).
### Projection Limitations
- **Choose `LearnablesReductionGoal` empirically, not by rule of thumb.** The
achievable reduction without retraining is highly model- and
data-dependent. If the user has no specific target, prefer the default
behavior (driven by `ExplainedVarianceGoal=0.95`) or run a trade-off sweep
across several goals and pick the one that meets the accuracy budget.
- **Data distribution matters.** The calibration set passed to
`compressNetworkUsingProjection` must reflect the true deployment
distribution; results inferred from unrepresentative data do not
transfer.
- **No synthetic fine-tuning shortcuts.** If the real data distribution is narrow, generating
synthetic N(0,1) data for fine-tuning does not help -- it introduces out-of-distribution noise.
- **Test on real data.** Projection accuracy must be validated on the actual expected input
distribution, not random data.
### Preparing Projected Networks for Code Generation
Codegen support for projected networks depends on the layer:
- `lstmProjectedLayer` and `gruProjectedLayer` (the unpacked recurrent
forms) are supported for generic C/C++ codegen via
`coder.loadDeepLearningNetwork`. No third-party libraries (MKL-DNN, ARM
Compute Library) are used on this path. R2026a adds support for
`HasStateInputs` / `HasStateOutputs` modes.
- A `ProjectedLayer` wrapper is supported for codegen only when its
contents are stateless — conv/FC, or LSTM/GRU configured with state
inputs/outputs (`HasStateInputs=true`, `HasStateOutputs=true`) instead
of stored state.
- A `ProjectedLayer` wrapping a stateful LSTM/GRU is **not**
codegen-compatible. Unpack it first.
When in doubt, unpack before saving for `coder.loadDeepLearningNetwork`:
```matlab
% Unpack projected layers — produces lstmProjectedLayer / gruProjectedLayer
% directly (no ProjectedLayer wrapper) plus FC/conv expansions.
unpackedNet = unpackProjectedLayers(projectedNet);
save("deployableNet.mat", "unpackedNet");
% Alternative: set UnpackProjectedLayers=true during projection
[projectedNet, info] = compressNetworkUsingProjection(net, calibData, ...
UnpackProjectedLayers=true);
```
---
## Quantization (Float32 to Int8)
### When to Quantize
Quantization reduces model size (4x for float32 → int8). On ARM Cortex-M targets with
the Embedded Coder Support Package for ARM Cortex-M Processors, INT8 quantized models
can use CMSIS-NN kernels for **`convolution2dLayer` and `fullyConnectedLayer` only**
(~2.8–3x speedup). LSTM, GRU, and BiLSTM layers in R2026a have **no INT8 CMSIS-NN
kernel** — they generate as plain fixed-point C when quantized, which can be slower
than the float32 + CMSIS-DSP `mw_arm_mat_mult_f32` path for recurrent layers. Choose
quantization based on the goal collected via [`compression-decision.md`](compression-decision.md).
**Two consumers of quantization data (do not confuse):**
| | Simulink path | MATLAB Coder CMSIS-NN path |
|---|---|---|
| Calls `quantize()`? | **Yes** — produces quantized dlnetwork for `exportNetworkToSimulink` | **No** — only `calibrate()`, calibration data passed to code generator |
| Requires Simulink? | Yes | No |
| Code gen mechanism | `slbuild` with CRL "ARM Cortex-M" | `codegen` with `coder.DeepLearningConfig('cmsis-nn')` |
See `codegen-embedded.md` for full CMSIS-NN deployment details.
### Checking dlquantizer Layer Support
Do not maintain a layer-by-layer support list in code or in this skill — it goes
stale across releases. Two ways to check whether a specific layer is supported by
`dlquantizer` in the user's installed release:
1. **Doc:** [Supported Layers for Quantization](https://www.mathworks.com/help/deeplearning/ug/supported-layers-for-quantization.html) — authoritative, release-versioned.
2. **Visual tool:** open the network in **Deep Network Designer**
(`deepNetworkDesigner(net)`) and use the compression analysis pane. It flags
each layer's eligibility for quantization, projection, and pruning directly
on the architecture diagram, which is faster than cross-referencing a table.
**LSTM/GRU implication for Cortex-M deployment:** Although `dlquantizer` quantizes
LSTM/GRU layers in the MATLAB execution environment and `exportNetworkToSimulink`
preserves them as fixed-point blocks, **the ARM Cortex-M code replacement library
in R2026a does not provide INT8 CMSIS kernels for recurrent layers** (Conv2D and FC
have CMSIS-NN INT8 wrappers; LSTM/GRU/BiLSTM only have float32 CMSIS-DSP
matrix-multiply replacement). Quantizing an LSTM saves flash but does NOT speed up
inference on Cortex-M. If latency is the priority, keep recurrent layers in float32
and rely on CMSIS-DSP. See [`codegen-embedded.md`](codegen-embedded.md) for the
CMSIS support tables.
### INT8 Suitability Check
Before quantizing, check whether the model's output range is suitable for INT8.
INT8 quantization works well when the model's output range is narrow. It fails when
the output range is too wide for 256 INT8 levels.
| Output Range | INT8 Suitability | Example |
|-------------|-----------------|---------|
| 0 to 1 | Excellent | Probabilities, SOC estimation |
| 0 to 5 | Good | Advisory scores, small classifications |
| -10 to 10 | Acceptable | Bounded regression |
| 100 to 500 | **Poor** (~50%+ error) | Wide-range regression |
**Rule:** If `(max_output - min_output) / 256 > acceptable_error`, INT8 is inadequate.
Use FP32 or FP16 instead.
### Step 1: Prepare Calibration Data
```matlab
% Create calibration dataset of representative inputs
numCalibSamples = 100;
% For sequence models (LSTM/GRU): cell array of [features × time] sequences.
% Pass this directly to calibrate() — see Step 2d. If you prefer a
% datastore form, wrap with arrayDatastore.
calibData = cell(numCalibSamples, 1);
for i = 1:numCalibSamples
calibData{i} = single(randn(numFeatures, seqLen));
end
% For image models (CNN): 4D array [H x W x C x N]
calibImages = single(randn(224, 224, 3, numCalibSamples));
ds = arrayDatastore(calibImages, 'IterationDimension', 4);
% For feature models (MLP): 2D array [features x N]
calibFeatures = single(randn(numFeatures, numCalibSamples));
ds = arrayDatastore(calibFeatures, 'IterationDimension', 2);
```
### Step 2: Quantize
```matlab
% Step 2a (optional): Equalize layer parameters for better quantization quality
net = equalizeLayers(net);
% Step 2b: Create the quantizer object
qOpts = dlquantizationOptions(MetricFcn={@(x) myMetric(x)}); % Optional
quantObj = dlquantizer(net, ExecutionEnvironment="MATLAB");
% Step 2c: Prepare the quantizer's network for quantization
% In R2026a, prepareNetwork takes the dlquantizer object (not a dlnetwork)
% and mutates it in place. It accepts projected networks: any
% ProjectedLayer / lstmProjectedLayer / gruProjectedLayer in the wrapped
% network is unpacked into its underlying built-in layers (e.g., a
% ProjectedLayer becomes two fullyConnectedLayer objects named
% "<orig>_proj_in" and "<orig>_proj_out") before calibration.
prepareNetwork(quantObj);
% Step 2d: Calibrate with representative data
% For tabular data:
calData = arrayDatastore(XCal, IterationDimension=1);
calibrate(quantObj, calData);
% For sequence models, pad variable-length sequences with padsequences,
% then wrap as a formatted dlarray. For [C × T] inputs padded along dim 2,
% padsequences returns [C × T_pad × N] — format as "CBT" (channel × batch
% × time). Do NOT use cat(3, X{:}); it requires equal-length sequences and
% gives the wrong axis order.
% XPad = padsequences(XCal, 2); % [C × T_pad × N]
% dlXCal = dlarray(XPad, "CBT");
% calibrate(quantObj, dlXCal);
% Step 2e: Quantize the network
quantizedNet = quantize(quantObj);
save('quantized_net.mat', 'quantizedNet', '-v7.3');
```
**Code generation from quantized networks — two paths:**
1. **Simulink path (SUPPORTED):** Pass the quantized network to
`exportNetworkToSimulink(qNet)`. This creates a Simulink model with
fixed-point data types (embedded.fi) pre-configured in block parameters.
Embedded Coder then generates integer C code (int8/int16/int32) via `slbuild`.
This is the recommended path for fixed-point embedded deployment.
See: https://www.mathworks.com/help/deeplearning/ug/export-quantized-network-to-simulink.html
For Cortex-M targets: configure the ARM Cortex-M CRL before `slbuild` to enable
CMSIS-NN INT8 block replacement for **Conv2D and FC layers only**. LSTM/GRU/BiLSTM
in the quantized model generate as plain fixed-point C — there is no CMSIS-NN
recurrent-layer kernel in R2026a. See [`codegen-embedded.md`](codegen-embedded.md).
2. **Direct MATLAB Coder path (NOT SUPPORTED):** `coder.loadDeepLearningNetwork`
does NOT accept the output of `quantize()`. For the direct codegen path
(without Simulink), use the uncompressed, pruned, or unpacked projected
network instead.
### Step 3: Validate
```matlab
% Validate using dlquantizer's built-in validation
valData = arrayDatastore(XVal, IterationDimension=1);
valResults = validate(quantObj, valData);
disp(valResults);
% Manual error comparison
errors = zeros(numTests, 1);
for i = 1:numTests
x = dlarray(single(testInputs{i}), formatString);
yBase = predict(baseNet, x);
yQuant = predict(quantizedNet, x);
errors(i) = max(abs(extractdata(yBase(:)) - extractdata(yQuant(:))));
end
mae = mean(errors);
fprintf('INT8 quantization: MAE=%.4e, MaxErr=%.4e\n', mae, max(errors));
assert(mae < 1e-3, 'Quantization error exceeds budget');
```
### Understanding Quantization Results
After calibration and validation:
- Compare accuracy/error before and after quantization
- Check per-layer quantization parameters (scale, zero-point)
- Identify layers with high quantization error
```matlab
% Get detailed quantization information from the quantized network (not quantObj)
qDetails = quantizationDetails(quantizedNet);
% qDetails struct fields:
% IsQuantized - logical
% TargetLibrary - string ("none" for MATLAB execution)
% QuantizedLayerNames - string array of quantized layer names
% QuantizedLearnables - table (Layer, Parameter, Value as embedded.fi)
fprintf('Quantized: %d, Layers: %s\n', qDetails.IsQuantized, ...
strjoin(qDetails.QuantizedLayerNames, ', '));
% Estimate inference metrics for the quantized network
metrics = estimateNetworkMetrics(quantObj);
disp(metrics);
```
---
## Manual INT8 Quantization (Fallback)
When dlquantizer does not work (e.g., on networks with residual custom layers),
use per-matrix min-max scaling:
```matlab
learnables = net.Learnables;
for i = 1:height(learnables)
W = learnables.Value{i};
if isfloat(W) && numel(W) > 1
absMax = max(abs(W(:)));
scale = absMax / 127.0;
Wq = int8(round(W / scale));
% Dequantize back for inference (keeps the network runnable)
learnables.Value{i} = single(Wq) * single(scale);
end
end
net.Learnables = learnables;
```
---
## Combined Pipeline (Best Results: 77%+ Flash Savings)
Use the combined pipeline only when the user's goal is flash reduction AND retraining
is acceptable. Confirm via [`compression-decision.md`](compression-decision.md) before
applying it. The pipeline applies projection first (modest parameter reduction), then
INT8 quantization (aggressive bit-width reduction). Together they achieve 77%+ flash
savings.
### Full Combined Workflow: Prune -> Project -> Quantize
This pseudo-code mirrors the structure of the
[Compress Sequence Classification Network for Road Damage Detection](https://www.mathworks.com/help/deeplearning/ug/compress-sequence-classification-network-for-road-damage-detection.html)
example. All steps reuse the same in-memory cell arrays
(`XTrain`/`TTrain`, `XValidation`/`TValidation`, `XTest`/`TTest`) and the
same trained network and training options — no minibatchqueue, no
datastore wrappers.
```matlab
% Inputs assumed in workspace:
% netTrained — trained dlnetwork
% XTrain, TTrain, XValidation, TValidation, XTest, TTest — cell arrays
% options — trainingOptions used for the original training
% lossFcn — loss function name or handle (e.g., "crossentropy")
%% Step 1: Prune (optional; only effective when conv/FC layers are present)
optionsFineTuning = options;
optionsFineTuning.MaxEpochs = 10;
[netPruned, infoPruned] = compressNetworkUsingTaylorPruning(netTrained, ...
XTrain, TTrain, lossFcn, optionsFineTuning, ...
LearnablesReductionGoal = 0.3, ...
LearnablesReductionIncrement = 0.02);
% Retrain pruned network on the same data
netPruned = trainnet(XTrain, TTrain, netPruned, lossFcn, options);
%% Step 2: Projection
% Pass training data directly. No separate neuronPCA call is needed for a
% single goal — compressNetworkUsingProjection runs PCA internally. Omit
% LearnablesReductionGoal to use the default driven by ExplainedVarianceGoal.
[netProjected, infoProjection] = compressNetworkUsingProjection(netPruned, ...
XTrain, LearnablesReductionGoal = 0.10);
% Fine-tune the projected network
netProjected = trainnet(XTrain, TTrain, netProjected, lossFcn, options);
%% Step 3: INT8 quantization
% prepareNetwork(quantObj) performs batch-normalization fusion, parameter
% equalization, and unpacks projected layers as part of preparing the
% network inside the dlquantizer object for calibration.
quantObj = dlquantizer(netProjected, ExecutionEnvironment = "MATLAB");
prepareNetwork(quantObj);
calibrate(quantObj, XTrain);
netQuantized = quantize(quantObj, ExponentScheme = "histogram");
save("combined_compressed.mat", "netQuantized", "-v7.3");
% Deployment via Simulink (R2026a):
% exportNetworkToSimulink(netQuantized, ...) → slbuild with ARM Cortex-M CRL
% Deployment via direct MATLAB Coder:
% not supported — coder.loadDeepLearningNetwork does not accept quantize() output.
% For that path, use the unpacked projected float32 network instead.
%% Verify combined accuracy on the held-out test set (same in-memory cell array)
YTest = minibatchpredict(netQuantized, XTest);
YBaseline = minibatchpredict(netTrained, XTest);
maeCombined = mean(abs(YTest(:) - YBaseline(:)));
fprintf("Combined: MAE vs baseline = %.4e\n", maeCombined);
%% Calculate flash savings
% Use estimateNetworkMetrics — the Learnables of a quantized dlnetwork are
% NOT stored as int8, so summing numel(v)*sizeof(class(v)) over .Learnables
% misreports the deployed flash footprint. estimateNetworkMetrics accepts
% a quantized network and reports the int8 parameter memory in its
% "ParameterMemory (MB)" column.
[metricsFloat, metricsQuantized] = estimateNetworkMetrics(netTrained, netQuantized);
flashFloatMB = sum(metricsFloat.("ParameterMemory (MB)"));
flashQuantizedMB = sum(metricsQuantized.("ParameterMemory (MB)"));
fprintf("Flash: %.2f MB -> %.2f MB (%.1f%% savings)\n", ...
flashFloatMB, flashQuantizedMB, ...
(1 - flashQuantizedMB/flashFloatMB) * 100);
```
---
## fitcnet / fitrnet Compression: Fixed-Point Designer
### Fixed-Point Conversion
```matlab
% Generate a predict function for the trained model
function y = predictFromModel(mdl, x)
y = predict(mdl, x);
end
% Use the Fixed-Point Tool to convert
% 1. Open the Fixed-Point Tool
fixedPointDesigner
% 2. Or use programmatic conversion with fxpopt
% Define input types
inputTypes = {coder.typeof(single(0), [1 numFeatures])};
% Create fixed-point configuration
fxpCfg = coder.config("fixpt");
fxpCfg.TestBenchName = "testBench"; % Function that exercises the code
fxpCfg.DefaultWordLength = 16;
fxpCfg.DefaultFractionLength = 8;
% Generate fixed-point code
codegen -float2fixed fxpCfg predictFunction -args inputTypes
```
### Fixed-Point Considerations for Lean Hardware
| Target Hardware | Typical Word Length | Notes |
|-------------------------|--------------------|---------------------------------|
| Cortex-M0/M0+ | 8 or 16 bit | Very constrained, aggressive quantization |
| Cortex-M4/M4F | 16 or 32 bit | Has FPU, but fixed-point still faster |
| Cortex-M7 | 16 or 32 bit | Double-precision FPU available |
| DSP (e.g., C2000) | 16 or 32 bit | Native fixed-point support |
| Custom ASIC / NPU | 8 bit | Often int8-only inference |
---
## Compression Validation
After any compression step, always validate:
```matlab
% Compare original vs. compressed model
YOriginal = minibatchpredict(net, XTest);
YCompressed = minibatchpredict(compressedNet, XTest);
% Classification accuracy comparison
[~, origLabels] = max(YOriginal, [], 2);
[~, compLabels] = max(YCompressed, [], 2);
origAcc = mean(origLabels == YTest);
compAcc = mean(compLabels == YTest);
fprintf("Original accuracy: %.2f%%\n", origAcc * 100);
fprintf("Compressed accuracy: %.2f%%\n", compAcc * 100);
fprintf("Accuracy drop: %.2f%%\n", (origAcc - compAcc) * 100);
% Model size comparison
origInfo = whos("net");
compInfo = whos("compressedNet");
fprintf("Original size: %.1f KB\n", origInfo.bytes / 1024);
fprintf("Compressed size: %.1f KB\n", compInfo.bytes / 1024);
fprintf("Compression ratio: %.1fx\n", origInfo.bytes / compInfo.bytes);
```
---
## CRITICAL Rules Summary
1. **prepareNetwork(quantObj) before calibrate()** -- In R2026a, `prepareNetwork`
takes the `dlquantizer` object (not a `dlnetwork`) and mutates it in place.
It handles unfused batch normalization, certain LSTM state configurations,
and unpacks projected layers (`ProjectedLayer`, `lstmProjectedLayer`,
`gruProjectedLayer`) into their underlying built-in layers. Without it,
calibration may fail with fi() type errors on networks that need fusion.
2. **Projected-layer codegen** -- `lstmProjectedLayer` and `gruProjectedLayer`
are supported by `coder.loadDeepLearningNetwork` for generic C/C++ codegen
(no MKL-DNN / ARM Compute acceleration). A `ProjectedLayer` wrapper is
supported only when its contents are stateless (conv/FC, or LSTM/GRU in
stateful-I/O mode). When in doubt, call `unpackProjectedLayers()` before
saving for the direct MATLAB Coder path — that produces the most
codegen-friendly form. **Not required for the Simulink path in R2026a:**
`exportNetworkToSimulink` accepts projected networks directly.
3. **quantize() output is deployable via Simulink, NOT via direct MATLAB Coder** --
`coder.loadDeepLearningNetwork` does not accept the output of `quantize()`. For
embedded deployment of a quantized network, use `exportNetworkToSimulink(qNet)`
followed by `slbuild`. For the direct MATLAB Coder path, use the uncompressed,
pruned, or unpacked projected float32 network.
4. **Use ExecutionEnvironment="MATLAB"** -- For target-agnostic C/C++ code generation, always
set `ExecutionEnvironment` to `"MATLAB"` when creating the dlquantizer.
5. **Compression Library is a support package** -- It is NOT detected by
`detect_matlab_toolboxes`. Use `matlabshared.supportpkg.getInstalled` to check.
---
## Workflow Pattern 1 Compression Targets
For lean hardware deployment (Cortex-M, DSPs):
| Metric | Target | Notes |
|--------------------|-------------------------|------------------------------------|
| Model size | < 500 KB (ideally < 100 KB) | Flash/ROM constraint |
| RAM usage | < 64 KB | SRAM constraint for inference |
| Inference time | < 10 ms (application-dependent) | Real-time constraint |
| Data type | int8 or fixed-point | No FPU on some targets |
| Accuracy drop | < 2% relative | Application-dependent tolerance |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |