Models — Pytorch-Sconce master documentation

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

  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)

  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)

  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)

    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)

    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)

  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)

    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)

    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)

  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.