Models

A model in Sconce is just a torch.nn.Module with a few restrictions (see note below). Sconce comes with a few example models to get you started.

Note

For a model to be used by a Trainer, the model must satisfy a few constraints.

  1. It must accept arbitrary keyword arguments in it’s forward method. The base class of trainer will pass inputs and targets, but subclasses may modify that behavior to include other keyword arguments.
  2. It must return a dictionary from it’s forward method. The dictionary is expected to include at least the key outputs but may include any other keys you like. The value of the key outputs is expected to be the torch.Tensor output of the model, used for calculating the loss.
  3. It must define a calculate_loss method. This method must accept arbitrary keyword arguments. The base class of trainer will pass inputs, outputs, and targets, but subclasses may modify that behavior to include other keyword arguments.
  4. It must return a dictionary form it’s calculate_loss method. The dictionary is expected to include at least the key ‘loss’, but may include any otehr keys you like. The value of the key loss is expected to be the torch.Tensor output of the loss function, used to back-propagate the gradients used by the optimizer.
  5. It may define a calculate_metrics method. This method must accept arbitrary keyword arguments. The base class of trainer will pass inputs, outputs, targets, and loss, but subclasses may modify that behavior to include other keyword arguments.
  6. If it defines a calculate_metrics method, it must return a dictionary. No restrictions are made on the keys or values of this dictionary.

BasicAutoencoder

class sconce.models.BasicAutoencoder(image_height, image_width, hidden_size, latent_size)[source]

A basic 2D image autoencoder built up of fully connected layers, three each in the encoder and the decoder.

Loss:
This model uses binary cross-entropy for the loss.
Metrics:
None
Parameters:
  • image_height (int) – image height in pixels.
  • image_width (int) – image width in pixels.
  • hidden_size (int) – the number of activations in each of the 4 hidden layers.
  • latent_size (int) – the number of activations in the latent representation (encoder output).

BasicConvolutionalAutoencoder

class sconce.models.BasicConvolutionalAutoencoder(image_channels, conv_channels)[source]

A basic 2D image autoencoder built up of convolutional layers, three each in the encoder and the decoder.

Loss:
This model uses binary cross-entropy for the loss.
Metrics:
None
Parameters:
  • image_channels (int) – the number of channels in the input images.
  • conv_channels (list of python:int) – a list of length three of integers describing the number of channels in each of the three convolutional layers.

BasicClassifer

class sconce.models.BasicClassifier(image_height, image_width, image_channels, convolutional_layer_kwargs, fully_connected_layer_kwargs, num_categories=10)[source]

A basic 2D image classifier built up of some number of convolutional layers followed by some number of densly connected layers.

Loss:
This model uses cross-entropy for the loss.
Metrics:
classification_accuracy: [0.0, 1.0] the fraction of correctly predicted labels.
Parameters:
  • image_height (int) – image height in pixels.
  • image_width (int) – image width in pixels.
  • image_channels (int) – number of channels in the input images.
  • convolutional_layer_kwargs (list[dict]) – a list of dictionaries describing the convolutional layers. See Convolution2dLayer for details.
  • fully_connected_layer_kwargs (list[dict]) – a list of dictionaries describing the fully connected layers. See FullyConnectedLayer for details.
  • num_categories (int) – [2, inf) the number of different image classes.
classmethod new_from_yaml_file(yaml_file)[source]

Construct a new BasicClassifier from a yaml file.

Parameters:yaml_file (file) – a file-like object that yaml contents can be read from.

Example yaml file contents:

---
# Values for MNIST and FashionMNIST
image_height: 28
image_width: 28
image_channels: 1
num_categories: 10

# Remaining values are not related to the dataset
convolutional_layer_attributes: ["out_channels", "stride", "padding", "kernel_size"]
convolutional_layer_values:  [ # ==============  ========  =========  =============
                                [16,             1,        4,         9],
                                [8,              2,        1,         3],
                                [8,              2,        1,         3],
                                [8,              2,        1,         3],
                                [8,              2,        1,         3],
]

fully_connected_layer_attributes: ['out_size', 'dropout']
fully_connected_layer_values:  [ # ======      =========
                                  [100,        0.4],
                                  [100,        0.8],
]
classmethod new_from_yaml_filename(yaml_filename)[source]

Construct a new BasicClassifier from a yaml file.

Parameters:filename (path) – the filename of a yaml file. See new_from_yaml_file() for more details.

MultilayerPerceptron

class sconce.models.MultilayerPerceptron(image_height, image_width, image_channels, layer_kwargs, num_categories=10)[source]

A basic 2D image multi-layer perceptron built up of a number of densly connected layers.

Loss:
This model uses cross-entropy for the loss.
Metrics:
classification_accuracy: [0.0, 1.0] the fraction of correctly predicted labels.
Parameters:
  • image_height (int) – image height in pixels.
  • image_width (int) – image width in pixels.
  • image_channels (int) – number of channels in the input images.
  • layer_kwargs (list[dict]) – a list of dictionaries describing layers. See FullyConnectedLayer for details.
  • num_categories (int) – [2, inf) the number of different image classes.
classmethod new_from_yaml_file(yaml_file)[source]

Construct a new MultilayerPerceptron from a yaml file.

Parameters:yaml_file (file) – a file-like object that yaml contents can be read from.

Example yaml file contents:

---
# Values for MNIST and FashionMNIST
image_height: 28
image_width: 28
image_channels: 1
num_categories: 10

layer_attributes: ['out_size', 'dropout', 'with_batchnorm']
layer_values:  [ # ======      =========  ================
                  [100,        0.4,       true],
                  [100,        0.8,       true],
]
classmethod new_from_yaml_filename(yaml_filename)[source]

Construct a new MultilayerPerceptron from a yaml file.

Parameters:filename (path) – the filename of a yaml file. See new_from_yaml_file() for more details.

WideResnetImageClassifier

class sconce.models.WideResnetImageClassifier(image_channels=1, depth=28, widening_factor=10, num_categories=10)[source]

A wide resnet image classifier, based on this paper

Loss:
This model uses cross-entropy for the loss.
Metrics:
classification_accuracy: [0.0, 1.0] the fraction of correctly predicted labels.
Parameters:
  • image_channels (int) – number of channels in the input images.
  • depth (int) – total number of convolutional layers in the network. This should be divisible by (6n + 4) where n is a positive integer.
  • widening_factor (int) – [1, inf) determines how many convolutional channels are in the network (see paper above for details).
  • num_categories (int) – [2, inf) the number of different image classes.