outputBoundsOptions

Options for output bounds computation for ONNX and PyTorch networks

Since R2026a

expand all in page

Description

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

Use an OutputBoundsOptions object to set options for the estimateNetworkOutputBounds function for ONNX™ or PyTorch® networks.

α-β-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.

Creation

Create a OutputBoundsOptions object using the outputBoundsOptions function directly.

Syntax

options = outputBoundsOptions
options = outputBoundsOptions(Property=Value)

Description

options = outputBoundsOptions returns output bounds options for use with the Deep Learning Toolbox™ Interface for alpha-beta-CROWN Verifier support package. To use the interface to compute the output bounds for a neural network, use the options object as input to the estimateNetworkOutputBounds function.

example

options = outputBoundsOptions(Property=Value) returns additional options specified by one or more name-value arguments.

example

Properties

The following properties can be used in MATLAB to interface with auto_LiRPA using the Deep Learning Toolbox Interface for alpha-beta-CROWN Verifier support package. To learn more about these properties and example configurations, see the auto_LiRPA Github repository.

Note

The default values documented here are used internally at runtime. The values are not visible at the time of object creation.

FieldData TypeDescription
Methodcharacter vector or string scalar

Bound computation algorithm specified as

  • "CROWN" (default)

  • "IBP"

  • "CROWN-IBP"

  • "Forward"

  • "Forward+Backward"

  • "alpha-CROWN"

  • "CROWN-optimized"

  • "forward-optimized"

BoundLowerlogical

Specified as

BoundUpperlogical

Specified as

DecisionThreshpositive numeric scalarIn "alpha-CROWN" mode, the software used DecisionThresh to dynamically optimize those domains that are less than or equal to the threshold.
Determininisticlogical

Specified as

  • 1 (true) to enable deterministic algorithms in PyTorch.

  • 0(false) (default) otherwise

EarlyStopPatiencepositive integer scalarNumber of iterations before early stopping if no improvement is observed. This property is settable only if Method is "alpha-CROWN" or "forward-optimized". Default value is 10.
FinalNodeNamecharacter vector or string scalar

Set the final node in the computational graph for bound computation. By default, the final node of the originally built computational graph is used.

InitAlphalogical

Specified as

  • 1 (true) (default) to initialize α variables by calling CROWN once

  • 0(false) otherwise

This property is settable only if Method is "alpha-CROWN" or "forward-optimized"

Iterationpositive integer scalarNumber of iterations for α-CROWN. This property is settable only if Method is "alpha-CROWN" or "forward-optimized". Default value is 30.
KeepBestlogical

Specified as

  • 1 (true) (default) to use α and bound values at the best iteration

  • 0(false) to use the last iteration result

This property is settable only if Method is "alpha-CROWN" or "forward-optimized"

LossFusionlogical

Specified as

  • 1 (true) to enable loss fusion for the bounded module. In loss fusion, the loss function is also included in the module and the output of the model is the loss rather than logits.

  • 0(false) (default) otherwise

LrAlphapositive numeric scalar

Learning rate for α-CROWN. This property is settable only if Method is "alpha-CROWN" or "forward-optimized". Default value is 0.5.

LrDecaypositive numeric scalar

Learning rate decay factor for the ExponentialLR scheduler. This property is settable only if Method is "alpha-CROWN" or "forward-optimized". Default value is 0.98.

Matmulcharacter vector or string scalar

Specified as

  • "" (default) .

  • "economic" to use a memory-efficient IBP implementation for relaxing the matmul operation when both arguments of matmul are perturbed, which does not expand all the elementary multiplications to save memory.

Optimizercharacter vector or string scalar

Optimizer for α-CROWN specified as

  • "adam" (default)

  • "adam-autolr"

  • "sgd"

This property is settable only if Method is "alpha-CROWN" or "forward-optimized".

Relucharacter vector or string scalar

Method to treat Relu specified as

  • "adaptive" (default) for unstable neurons, when the slope of the upper bound is greater than one, use 1 as the slope of the lower bound, otherwise use 0 as the slope of the lower bound (this is described as CROWN-Ada in the original CROWN paper). Please also use this option if the CROWN-Optimized bound is used and the lower bound needs to be optimized.

  • "same-slope" to make the slope for lower bound the same as the upper bound.

  • "zero-lb" to Always use 0 as the slope of lower bound for unstable neurons.

  • "one-lb" to always use 1 as the slope of lower bound for unstable neurons.

  • "reversed-adaptive" for unstable neurons, when the slope of the upper bound is greater than one, use 0 as the slope of the lower bound, otherwise use 1 as the slope of the lower bound.

StartSaveBestpositive numeric scalarStart to save best optimized bounds when currentIteration > int(NumIteration*StartSaveBest). This property is settable only if Method is "alpha-CROWN" or "forward-optimized". Default value is 0.5.
StopCriterionFunccharacter vector or string scalar

Function for the criterion of stopping optimization early specified as

  • "" (default) uses a lambda function that always returns false

  • "auto_LiRPA.utils.stop_criterion_min"

  • “auto_LiRPA.utils.stop_criterion_mean”

  • “auto_LiRPA.utils.stop_criterion_max”

  • “auto_LiRPA.utils.stop_criterion_sum”

StopCriterionFunc internally returns a tensor of type torch.bool with number of elements equal to the batch size. For example, "auto_LiRPA.utils.stop_criterion_min" checks the minimum bound over all specifications of a batch element and returns true for that element when the minimum bound is greater than a specified threshold.

This property is settable only if Method is "alpha-CROWN" or "forward-optimized".

UseSharedAlphalogical

Specified as

  • 1 (true) (default) to use α and bound values at the best iteration

  • 0(false) to use the last iteration result

This property is settable only if Method is "alpha-CROWN" or "forward-optimized"

Examples

collapse all

This example uses:

Open Live Script

Create an OutpoutBoundsOptions object to specify custom properties to compute output bounds.

options = outputBoundsOptions(Method="alpha-crown",Iteration=100,LrAlpha=0.95)
options = 
  OutputBoundsOptions with properties:

            Optimizer: [0×0 string]
              LrAlpha: 0.9500
              LrDecay: []
            Iteration: 100
             KeepBest: []
       UseSharedAlpha: []
    EarlyStopPatience: []
        StartSaveBest: []
    StopCriterionFunc: [0×0 string]
            InitAlpha: []
                 Relu: [0×0 string]
           LossFusion: []
        Deterministic: []
               Matmul: [0×0 string]
               Method: "alpha-crown"
           BoundLower: []
           BoundUpper: []
        FinalNodeName: [0×0 string]
       DecisionThresh: []

This example uses:

Open Live Script

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")

Version History

Introduced in R2026a

See Also

External Websites