foolbox.models

Provides classes to wrap existing models in different framworks so that they provide a unified API to the attacks.

Models

Model Base class to provide attacks with a unified interface to models.
DifferentiableModel Base class for differentiable models that provide gradients.
TensorFlowModel Creates a Model instance from existing TensorFlow tensors.
PyTorchModel Creates a Model instance from a PyTorch module.
KerasModel Creates a Model instance from a Keras model.
TheanoModel Creates a Model instance from existing Theano tensors.
LasagneModel Creates a Model instance from a Lasagne network.
MXNetModel Creates a Model instance from existing MXNet symbols and weights.

Wrappers

ModelWrapper Base class for models that wrap other models.
GradientLess Turns a model into a model without gradients.
CompositeModel Combines predictions of a (black-box) model with the gradient of a (substitute) model.

Detailed description

class foolbox.models.Model(bounds, channel_axis, preprocessing=(0, 1))[source]

Base class to provide attacks with a unified interface to models.

The Model class represents a model and provides a unified interface to its predictions. Subclasses must implement batch_predictions and num_classes.

Model instances can be used as context managers and subclasses can require this to allocate and release resources.

Parameters:

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

channel_axis : int

The index of the axis that represents color channels.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

batch_predictions(images)[source]

Calculates predictions for a batch of images.

Parameters:

images : numpy.ndarray

Batch of images with shape (batch size, height, width, channels).

Returns:

numpy.ndarray

Predictions (logits, i.e. beforre the softmax) with shape (batch size, number of classes).

See also

prediction()

num_classes()[source]

Determines the number of classes.

Returns:

int

The number of classes for which the model creates predictions.

predictions(image)[source]

Convenience method that calculates predictions for a single image.

Parameters:

image : numpy.ndarray

Image with shape (height, width, channels).

Returns:

numpy.ndarray

Vector of predictions (logits, i.e. beforre the softmax) with shape (number of classes,).

class foolbox.models.DifferentiableModel(bounds, channel_axis, preprocessing=(0, 1))[source]

Base class for differentiable models that provide gradients.

The DifferentiableModel class can be used as a base class for models that provide gradients. Subclasses must implement predictions_and_gradient.

A model should be considered differentiable based on whether it provides a predictions_and_gradient() method and a gradient() method, not based on whether it subclasses DifferentiableModel.

A differentiable model does not necessarily provide reasonable values for the gradients, the gradient can be wrong. It only guarantees that the relevant methods can be called.

gradient(image, label)[source]

Calculates the gradient of the cross-entropy loss w.r.t. the image.

The default implementation calls predictions_and_gradient. Subclasses can provide more efficient implementations that only calculate the gradient.

Parameters:

image : numpy.ndarray

Image with shape (height, width, channels).

label : int

Reference label used to calculate the gradient.

Returns:

gradient : numpy.ndarray

The gradient of the cross-entropy loss w.r.t. the image. Will have the same shape as the image.

See also

gradient()

predictions_and_gradient(image, label)[source]

Calculates predictions for an image and the gradient of the cross-entropy loss w.r.t. the image.

Parameters:

image : numpy.ndarray

Image with shape (height, width, channels).

label : int

Reference label used to calculate the gradient.

Returns:

predictions : numpy.ndarray

Vector of predictions (logits, i.e. beforre the softmax) with shape (number of classes,).

gradient : numpy.ndarray

The gradient of the cross-entropy loss w.r.t. the image. Will have the same shape as the image.

See also

gradient()

class foolbox.models.TensorFlowModel(images, logits, bounds, channel_axis=3, preprocessing=(0, 1))[source]

Creates a Model instance from existing TensorFlow tensors.

Parameters:

images : tensorflow.Tensor

The input to the model, usually a tensorflow.placeholder.

logits : tensorflow.Tensor

The predictions of the model, before the softmax.

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

channel_axis : int

The index of the axis that represents color channels.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

class foolbox.models.PyTorchModel(model, bounds, num_classes, channel_axis=1, cuda=True, preprocessing=(0, 1))[source]

Creates a Model instance from a PyTorch module.

Parameters:

model : torch.nn.Module

The PyTorch model that should be attacked.

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

num_classes : int

Number of classes for which the model will output predictions.

channel_axis : int

The index of the axis that represents color channels.

cuda : bool

A boolean specifying whether the model uses CUDA.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

class foolbox.models.KerasModel(model, bounds, channel_axis=3, preprocessing=(0, 1), predicts='probabilities')[source]

Creates a Model instance from a Keras model.

Parameters:

model : keras.models.Model

The Keras model that should be attacked.

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

channel_axis : int

The index of the axis that represents color channels.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

predicts : str

Specifies whether the Keras model predicts logits or probabilities. Logits are preferred, but probabilities are the default.

class foolbox.models.TheanoModel(images, logits, bounds, num_classes, channel_axis=1, preprocessing=[0, 1])[source]

Creates a Model instance from existing Theano tensors.

Parameters:

images : theano.tensor

The input to the model.

logits : theano.tensor

The predictions of the model, before the softmax.

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

num_classes : int

Number of classes for which the model will output predictions.

channel_axis : int

The index of the axis that represents color channels.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

class foolbox.models.LasagneModel(input_layer, logits_layer, bounds, channel_axis=1, preprocessing=(0, 1))[source]

Creates a Model instance from a Lasagne network.

Parameters:

input_layer : lasagne.layers.Layer

The input to the model.

logits_layer : lasagne.layers.Layer

The output of the model, before the softmax.

bounds : tuple

Tuple of lower and upper bound for the pixel values, usually (0, 1) or (0, 255).

channel_axis : int

The index of the axis that represents color channels.

preprocessing: 2-element tuple with floats or numpy arrays

Elementwises preprocessing of input; we first subtract the first element of preprocessing from the input and then divide the input by the second element.

class foolbox.models.ModelWrapper(model)[source]

Base class for models that wrap other models.

This base class can be used to implement model wrappers that turn models into new models, for example by preprocessing the input or modifying the gradient.

Parameters:

model : Model

The model that is wrapped.

class foolbox.models.GradientLess(model)[source]

Turns a model into a model without gradients.