estimateNetworkOutputBounds

Compute output bounds of MATLAB, ONNX, and PyTorch networks

Since R2022b

Syntax

[YLower,YUpper] = estimateNetworkOutputBounds(net,XLower,XUpper)

[YLower,YUpper] = estimateNetworkOutputBounds(___,Name=Value)

[YLower,YUpper] = estimateNetworkOutputBounds(modelfile,XLower,XUpper)

[YLower,YUpper] = estimateNetworkOutputBounds(___,Name=Value)

Description

Add-On Required: This feature requires the AI Verification Library for Deep Learning Toolbox add-on.

dlnetwork bounds

[YLower,YUpper] = estimateNetworkOutputBounds(net,XLower,XUpper) computes lower and upper output bounds, YLower and YUpper, respectively, for the network net for input within the bounds specified by XLower and XUpper.

The function uses abstract interpretation to compute the range of output values that the network returns when the input is between the specified lower and upper bounds. Use this function to determine the sensitivity of the network predictions to input perturbations. Abstract interpretation can introduce overapproximations so these bounds may not be tight.

[YLower,YUpper] = estimateNetworkOutputBounds(___,Name=Value) computes lower and upper output bounds with additional options specified by one or more name-value arguments.

ONNX and PyTorch network bounds

This feature requires the Deep Learning Toolbox Interface for alpha-beta-CROWN Verifier add-on.

[YLower,YUpper] = estimateNetworkOutputBounds(modelfile,XLower,XUpper) computes lower and upper output bounds, YLower and YUpper, respectively, for the ONNX™ or PyTorch^® network specified in modelfile for input within the bounds specified by XLower and XUpper.

[YLower,YUpper] = estimateNetworkOutputBounds(___,Name=Value) computes lower and upper output bounds with additional options specified by one or more name-value arguments.

Examples

Estimate Output Bounds

Estimate the output bounds for an image regression network.

Load a pretrained regression network. This network is a dlnetwork object that has been trained to predict the rotation angle of images of handwritten digits.

load("digitsRegressionNetwork.mat");

Load the test data.

[XTest,~,TTest] = digitTest4DArrayData;

Select the first ten images.

X = XTest(:,:,:,1:10);
T = TTest(1:10);

Convert the test images to dlarray objects.

X = dlarray(X,"SSCB");

Estimate the output bounds for an input perturbation between –0.01 and 0.01 for each pixel. Create lower and upper bounds for the input.

perturbation = 0.01;
XLower = X - perturbation;
XUpper = X + perturbation;

Estimate the output bounds for each input.

[YLower,YUpper] = estimateNetworkOutputBounds(net,XLower,XUpper);

The output bounds are dlarray objects. To plot the output bounds, first extract the data using extractdata.

YLower = extractdata(YLower);
YUpper = extractdata(YUpper);

Visualize the output bounds.

figure
hold on
for i = 1:10
    plot(i,T(i),"ko")
    line([i i],[YLower(i) YUpper(i)],Color="b")
end
hold off
xlim([0 10])
xlabel("Observation")
ylabel("Angle of Rotation")
legend(["True value","Output bounds"])

Estimate Output Bounds Using Custom Optimizer

Since R2026a

Load a pretrained regression network. This network is a dlnetwork object that has been trained to predict the rotation angle of images of handwritten digits.

load("digitsRegressionNetwork.mat");

Load the test data.

[XTest,~,TTest] = digitTest4DArrayData;

Select the first ten images.

X = XTest(:,:,:,1:10);
T = TTest(1:10);

Convert the test images to dlarray objects.

X = dlarray(X,"SSCB");

Estimate the output bounds for an input perturbation between –0.01 and 0.01 for each pixel. Create lower and upper bounds for the input.

perturbation = 0.01;
XLower = X - perturbation;
XUpper = X + perturbation;

Create an AlphaCROWN options object. Optimize the upper bound and optimize over the average objective.

opts = alphaCROWNOptions(InitialLearnRate=0.9,MaxEpochs=20, ...
    Objective="upper", ...
    ObjectiveMode="average", ...
    Verbose=true);

Estimate the output bounds for each input.

[YLower,YUpper] = estimateNetworkOutputBounds(net,XLower,XUpper);

The output bounds are dlarray objects. To plot the output bounds, first extract the data using extractdata.

YLower = extractdata(YLower);
YUpper = extractdata(YUpper);

Visualize the output bounds.

figure
hold on
for i = 1:10
    plot(i,T(i),"ko")
    line([i i],[YLower(i) YUpper(i)],Color="b")
end
hold off
xlim([0 10])
xlabel("Observation")
ylabel("Angle of Rotation")
legend(["True value","Output bounds"])

Compute Output Bounds of a PyTorch Network

Since R2026a

Load a pretrained image regression PyTorch network. This network has been trained to predict the rotation angle of images of handwritten digits.

modelfile = "digitsRotationConvolutionNet.pt";

Load the test data.

[XTest,~,TTest] = digitTest4DArrayData;

Select the first ten images.

X = XTest(:,:,:,1:10);
T = TTest(1:10);

Estimate the output bounds for an input perturbation between –0.01 and 0.01 for each pixel. Create lower and upper bounds for the input.

perturbation = 0.01;
XLower = X - perturbation;
XUpper = X + perturbation;

Estimate the output bounds for each input using alpha-CROWN.

options = outputBoundsOptions(Method="alpha-CROWN",Iteration=10);
[YLower,YUpper] = estimateNetworkOutputBounds(modelfile,XLower,XUpper,Algorithm=options,InputDataPermutation=[4 3 1 2]);

Visualize the output bounds.

figure
hold on
for i = 1:10
    line([i i],[YLower(i) YUpper(i)],Color="b")
end
hold off
xlim([0 10])
xlabel("Observation")
ylabel("Angle of Rotation")
legend("Output bounds")

Input Arguments

XLower — Input lower bound

dlarray object | numeric array

Input lower bound, specified as a dlarray object or a numeric array.

• If you provide a dlnetwork object as input, XLower must be a formatted dlarray object. For more information about dlarray formats, see the fmt input argument of dlarray.

• If you provide an ONNX or PyTorch modelfile as input, XLower can be a numeric array or a dlarray object. See Input Dimension Ordering for more information.

The lower and upper bounds, XLower and XUpper, must have the same size and format. The function computes the results across the batch ("B") dimension of the input lower and upper bounds.

For ONNX and PyTorch networks, the batch dimension is the first dimension of the data after it is permuted to Python^® dimension ordering.

XUpper — Input upper bound

formatted dlarray object | numeric array

Input upper bound, specified as a formatted dlarray object or a numeric array.

• If you provide a dlnetwork object as input, XUpper must be a formatted dlarray object. For more information about dlarray formats, see the fmt input argument of dlarray.

• If you provide an ONNX or PyTorch modelfile as input, XUpper must be a numeric array.

The lower and upper bounds, XLower and XUpper, must have the same size and format. The function computes the results across the batch ("B") dimension of the input lower and upper bounds.

For ONNX and PyTorch networks, the batch dimension is the first dimension of the data after it is permuted to Python dimension ordering.

dlnetwork only

net — Network

initialized dlnetwork object

Network, specified as an initialized dlnetwork object. To initialize a dlnetwork object, use the initialize function.

The function supports these layers:

Layer	Notes and Limitations
additionLayer (since R2024b)
averagePooling2dLayer (since R2023a)	Supported when PaddingValue is set to 0.
batchNormalizationLayer (since R2023a)
clippedReluLayer (since R2026a)
convolution2dLayer (since R2023a)	Supported when Dilation is set to [1 1] or 1 and PaddingValue is set to 0.
depthConcatenationLayer (since R2026a)
dropoutLayer (since R2023a)
featureInputLayer	Supported when Normalization is set to "none" (since R2022b) or "zerocenter", "zscore", "rescale-symmetric", "rescale-zero-one" (since R2023a). Custom normalization functions are not supported.
flattenLayer (since R2026a)
fullyConnectedLayer
globalAveragePooling2dLayer (since R2023a)
globalMaxPooling2dLayer (since R2023a)
identityLayer (since R2026a)
imageInputLayer	Supported when Normalization is set to "none" (since R2022b) or "zerocenter", "zscore", "rescale-symmetric", "rescale-zero-one" (since R2023a). Custom normalization functions are not supported.
leakyReluLayer (since R2026a)	You can optimize this layer using the α-CROWN algorithm.
maxPooling2dLayer (since R2023a)
nnet.onnx.layer.CustomOutputLayer (built-in ONNX layer) (since R2025a)	Supported when DataFormat is set to "CB" or "SSCB". The data format is commonly set by the InputDataFormats and OutputDataFormats options of the importNetworkFromONNX function.
nnet.onnx.layer.ElementwiseAffineLayer (built-in ONNX layer) (since R2023a)
nnet.onnx.layer.FlattenInto2dLayer (built-in ONNX layer) (since R2025a)
reluLayer	You can optimize this layer using the α-CROWN algorithm.
sigmoidLayer (since R2023a)
tanhLayer

The function does not support networks with multiple inputs and multiple outputs.

The function estimates the output bounds using the final layer in the network. For most applications, use the final fully connected layer when computing the output bounds. If your network has a different layer as its final layer, remove the layer before calling the function.

ONNX or PyTorch only

Since R2026a

modelfile — ONNX or PyTorch model file name

character vector | string scalar

ONNX or PyTorch model file name specified as a character vector or a string scalar. The modelfile must be a full PyTorch model (saved using torch.save()) or an ONNX model with the .onnx extension.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: estimateNetworkOutputBounds(net,XLower,XUpper,MiniBatchSize=32,ExecutionEnvironment="multi-gpu") estimates the network output bounds using a mini-batch size of 32 and using multiple GPUs.

All Model Types

Algorithm — Optimization algorithm

"crown" (default) | "alpha-crown" | "alpha-beta-crown" | AlphaCROWNOptions object | outputBoundsOptions object

Since R2026a

Optimization algorithm, specified as one of these values:

• "crown" — Use the CROWN algorithm [4]. This option is the same as using an OutputBoundsOptions object with the default values if used with a ONNX or PyTorch network.

• "alpha-crown" — Use the α-CROWN algorithm [6] with default options. This option is the same as using an AlphaCROWNOptions object with the default values if used with a dlnetwork.

• "alpha-beta-crown" — Use the α,β-CROWN algorithm with default options. This option is only available with ONNX or PyTorch networks.

• AlphaCROWNOptions object — Use the α-CROWN algorithm with custom options. Create an AlphaCROWNOptions object using the alphaCROWNOptions function. This option is only available with dlnetwork.

• OutputBoundsOptions object — Use the α,β-CROWN algorithm with custom options. Create a OutputBoundsOptions object using the outputBoundsOptions function. This option is only available with ONNX or PyTorch networks.

For more information, see

The α-CROWN algorithm produces tighter bounds at the cost of longer computation times and requiring more memory.

Note

The α-CROWN algorithm tightens bounds for networks with reluLayer or leakyReluLayer layers.

ExecutionEnvironment — Hardware resource

"auto" (default) | "cpu" | "gpu" | "multi-gpu" | "parallel-auto" | "parallel-cpu" | "parallel-gpu"

Since R2024a

Hardware resource, specified as one of these values:

• "auto" – Use a local GPU if one is available. Otherwise, use the local CPU.

• "cpu" – Use the local CPU.

• "gpu" – Use the local GPU.

• "multi-gpu" – Use multiple GPUs on one machine, using a local parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts a parallel pool with pool size equal to the number of available GPUs. Only available when input is a dlnetwork object.

• "parallel-auto" – Use a local or remote parallel pool. If there is no current parallel pool, the software starts one using the default cluster profile. If the pool has access to GPUs, then only workers with a unique GPU perform the computations and excess workers become idle. If the pool does not have GPUs, then the computations take place on all available CPU workers instead. Only available when input is a dlnetwork object.

• "parallel-cpu" – Use CPU resources in a local or remote parallel pool, ignoring any GPUs. If there is no current parallel pool, the software starts one using the default cluster profile. Only available when input is a dlnetwork object.

• "parallel-gpu" – Use GPUs in a local or remote parallel pool. Excess workers become idle. If there is no current parallel pool, the software starts one using the default cluster profile. Only available when input is a dlnetwork object.

The "gpu", "multi-gpu", "parallel-auto", "parallel-cpu", and "parallel-gpu" options require Parallel Computing Toolbox™. To use a GPU for deep learning, you must also have a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). If you choose one of these options and Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

For more information on when to use the different execution environments, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.

Dependency

If you specify Algorithm as an AlphaCROWNOptions object, then the execution environment specified in the options object takes precedence.

dlnetwork only

MiniBatchSize — Size of mini-batch

128 (default) | positive integer

Since R2023b

Size of the mini-batch, specified as a positive integer.

Larger mini-batch sizes require more memory, but can lead to faster computations.

Dependency

If you specify Algorithm as an AlphaCROWNOptions object, then the value of the mini-batch size in the options object takes precedence.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Verbose — Option to enable verbose output

false or 0 (default) | true or 1

Since R2026a

Option to enable verbose output, specified as a numeric or logical 1 (true) or 0 (false). When you set this input to 1 (true), the function returns the progress of the algorithm by indicating which mini-batch the function is processing and the total number of mini-batches.

Dependency

If you specify Algorithm as an AlphaCROWNOptions object, then the verbose value specified in the options object takes precedence.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

ONNX or PyTorch only

Since R2026a

InputDataPermutation — Input dimension ordering

[] (default) | numeric row vector

Input dimension ordering specified as a numeric row vector. The ordering is the desired permutation of data in XLower and XUpper from MATLAB to Python dimension ordering. See Input Dimension Ordering for more information.

Example: [4 3 1 2]

InputDataNumDims — Number of dimensions in input data

[] (default) | positive integer

Number of dimensions in input data specified as a positive integer.

Example: 4

OutputDataPermutation — Output dimension ordering

[] (default) | numeric row vector

Output dimension ordering specified as a numeric row vector. The ordering is the desired permutation of data in YLower and YUpper from Python to MATLAB dimension ordering.

Example: [4 3 1 2]

Output Arguments

YLower — Output lower bound

formatted dlarray object | numeric array

Output lower bound, returned as a formatted dlarray object if the input is a dlnetwork or a numeric array if the input is a ONNX or PyTorch modelfile. For more information about dlarray formats, see the fmt input argument of dlarray.

The function estimates the output bounds for each observation across the batch ("B") dimension. If you supply k upper bounds and lower bounds, then YLower contains k output lower bounds. For more information, see Algorithms.

YUpper — Output upper bound

formatted dlarray object | numeric array

Output upper bound, returned as a formatted dlarray object if the input is a dlnetwork or a numeric array if the input is a ONNX or PyTorch modelfile. For more information about dlarray formats, see the fmt input argument of dlarray.

The function estimates the output bounds for each observation across the batch ("B") dimension. If you supply k upper bounds and lower bounds, then YUpper contains k output upper bounds. For more information, see Algorithms.

Algorithms

Network Robustness

Let X be the input for which you want to estimate the output bounds. To use the estimateNetworkOutputBounds function, you must specify a lower and upper bound for the input. For example, let $$ϵ$$ be a small perturbation. You can define a lower and upper bound for the input as $$X_{\text{lower}}=X-ϵ$$ and $$X_{\text{upper}}=X+ϵ$$, respectively.

To estimate the output bounds for the network net and the input bounds X_lower and X_upper, the function performs these steps.

1. Create an input set using the lower and upper input bounds.

2. Pass the input set through the network and return an output set. To reduce computational overhead, the function performs abstract interpretation by approximating the output of each layer using the CROWN method [4] (also known as DeepPoly).

3. Return the minimum and maximum estimated output values for the input set.

If you specify multiple pairs of input lower and upper bounds, then the function estimates the output bounds for each pair of input bounds.

Note

Soundness with respect to floating point: In rare cases, floating-point rounding errors can accumulate which can cause the network output to be outside the computed bounds and the verification results to be different. This can also be true when working with networks you produced using C/C++ code generation.

CROWN, α-CROWN and α,β-CROWN

CROWN (equivalently DeepPoly) and alpha-CROWN are algorithms for neural network verification that use abstract interpretation to prove properties of the neural networks [3], [4], [5], [6].

α-β-CROWN is an algorithm for neural network verification. The algorithm efficiently propagates input bounds through the neural network to produce bounds on the output. You can use the output bounds to verify properties of a neural network, such as the robustness of the network to input perturbations.

• CROWN [4] — Formal verification framework that uses convex relaxations to compute certified bounds on neural network outputs under input and/or weight perturbations. It enables provable, scalable robustness guarantees by efficiently bounding worst-case behavior layer-by-layer without exhaustive enumeration. CROWN is an incomplete verification algorithm, meaning that for networks with nonlinear behavior, the bounds on neural network outputs are not exact and overapproximate the exact bounds.

• α-CROWN [6] — Extends CROWN using tighter, optimization-based bounds by introducing learnable dual variables (α) that are optimized to strengthen layer-wise convex relaxations. Compared to CROWN, α-CROWN has increased memory and runtime costs. Similar to CROWN, α-CROWN is also an incomplete verification algorithm.

• β-CROWN — Further refines bounds by jointly optimizing split constraints (β), enabling branch-and-bound with strong, data-dependent relaxations that significantly tighten certificates and scale to larger networks. For networks with only piecewise linear activations, such as ReLU layers, and no other sources of non-linearity, β-CROWN provides complete verification. This means that β-CROWN has the capacity to return exact neural network output bounds. However, this can add significant memory and runtime costs.

Algorithm	Tightness of Bounds	Speed of Computation	Memory Consumption
CROWN	Loosest bounds	Fastest	Lowest
α-CROWN	Tighter bounds	Slower	Higher
α-β-CROWN	Tightest bounds	Slowest	Highest

References

[1] Goodfellow, Ian J., Jonathon Shlens, and Christian Szegedy. “Explaining and Harnessing Adversarial Examples.” Preprint, submitted March 20, 2015. https://arxiv.org/abs/1412.6572.

[2] Singh, Gagandeep, Timon Gehr, Markus Püschel, and Martin Vechev. “An Abstract Domain for Certifying Neural Networks”. Proceedings of the ACM on Programming Languages 3, no. POPL (January 2, 2019): 1–30. https://doi.org/10.1145/3290354.

[3] Singh, Gagandeep, Timon Gehr, Markus Püschel, and Martin Vechev. “An Abstract Domain for Certifying Neural Networks.” Proceedings of the ACM on Programming Languages 3, no. POPL (January 2, 2019): 1–30. https://doi.org/10.1145/3290354.

[4] Zhang, Huan, Tsui-Wei Weng, Pin-Yu Chen, Cho-Jui Hsieh, and Luca Daniel. “Efficient Neural Network Robustness Certification with General Activation Functions.” arXiv, 2018. https://doi.org/10.48550/ARXIV.1811.00866.

[5] Xu, Kaidi, Zhouxing Shi, Huan Zhang, Yihan Wang, Kai-Wei Chang, Minlie Huang, Bhavya Kailkhura, Xue Lin, and Cho-Jui Hsieh. “Automatic Perturbation Analysis for Scalable Certified Robustness and Beyond.” arXiv, 2020. https://doi.org/10.48550/ARXIV.2002.12920.

[6] Xu, Kaidi, Huan Zhang, Shiqi Wang, Yihan Wang, Suman Jana, Xue Lin, and Cho-Jui Hsieh. “Fast and Complete: Enabling Complete Neural Network Verification with Rapid and Massively Parallel Incomplete Verifiers.” arXiv, 2020. https://doi.org/10.48550/ARXIV.2011.13824.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The estimateNetworkOutputBounds function fully supports GPU acceleration.

By default, estimateNetworkOutputBounds uses a GPU if one is available. You can specify the hardware that the estimateNetworkOutputBounds function uses by specifying the ExecutionEnvironment name-value argument.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2022b

R2026a: Verify ONNX or PyTorch network robustness using the α,β-CROWN Verifier

Estimate network output bounds for pretrained ONNX or PyTorch networks using the new Deep Learning Toolbox™ Interface for alpha-beta-CROWN Verifier. This new interface supports algorithms like "alpha-beta-crown" which produce tighter bounds than CROWN leading to fewer unknown results.

Use the OutputBoundsOptions object to specify custom options for the α,β-CROWN Verifier.

R2026a: Verify more types of layers

Estimate network output bounds for networks with these layers:

• clippedReluLayer

• depthConcatenationLayer

• flattenLayer

• identityLayer

• leakyReluLayer

R2026a: Compute output bounds using α-CROWN

Starting in R2026a, the estimateNetworkOutputBounds function supports computing output bounds using the α-CROWN algorithm. α-CROWN produces tighter output bounds than the CROWN algorithm [6].

Use the Algorithm property to specify the algorithm to use. To use α-CROWN with the default options, set Algorithm to "alpha-crown". To specify custom options for the α-CROWN algorithm, set Algorithm to an AlphaCROWNOptions object.

R2026a: Display verification progress

Starting in R2026a, you can track verification progress using the Verbose option. When Verbose is set to true, the function returns the progress of the algorithm by indicating which mini-batch the function is processing and the total number of mini-batches.

R2025a: Verify more ONNX layers

Estimate network output bounds for networks with these layers:

• nnet.onnx.layer.FlattenInto2dLayer (built-in ONNX layer)

• nnet.onnx.layer.CustomOutputLayer (built-in ONNX layer) with DataFormat set to "CB" or "SSCB". The data format is commonly set by the InputDataFormats and OutputDataFormats options of the importNetworkFromONNX function.

R2024b: Verify branched networks (February 2025; Version 24.2.2)

The estimateNetworkOutputBounds function now supports networks with addition layers. You can use addition layers to create branched networks. To add an addition layer to your network, use the additionLayer function.

R2024a: Estimate output bounds in parallel (May 2024; Version 24.1.1)

Starting from R2024a Update 1, the estimateNetworkOutputBounds function supports estimating network output bounds in parallel. To perform computations in parallel, set the ExecutionEnvironment option. By default, the function uses a GPU if one is available. Performing computations in parallel requires a Parallel Computing Toolbox license.

Before R2024a Update 1, the estimateNetworkOutputBounds function only uses the GPU if the input data is a gpuArray object.

R2023b: Improved performance and MiniBatchSize option (November 2023; Version 23.2.1)

The estimateNetworkOutputBounds function shows improved performance because it now uses mini-batches when computing the results. You can use the MiniBatchSize name-value option to control how many observations the function processes at once. Larger mini-batch sizes require more memory, but can lead to faster computations.

R2023a: Verify more types of layers (June 2023; Version 23.1.1)

Estimate network output bounds for networks with these layers:

• maxPooling2dLayer — 2-D max pooling layer

• globalMaxPooling2dLayer — 2-D global max pooling layer

• nnet.onnx.layer.ElementwiseAffineLayer — ONNX built-in layer

You can also estimate output bounds for networks with imageInputLayer and featureInputLayer layers with the Normalization option set to "zerocenter", "zscore", "rescale-symmetric", "rescale-zero-one", or "none".

R2023a: Verify convolutional neural networks

Estimate network output bounds for networks with these layers:

• convolution2dLayer with Dilation set to [1 1] or 1 and PaddingValue set to 0

• batchNormalizationLayer

• averagePooling2dLayer with PaddingValue set to 0

• globalAveragePooling2dLayer

• dropoutLayer

• sigmoidLayer