README.md

   1 # Introduction #
   2
   3 This is a port of the Synthetic Visual Reasoning Test problems to the
   4 pytorch framework, with an implementation of two convolutional
   5 networks to solve them.
   6
   7 # Installation and test #
   8
   9 Executing
  10
  11 ```
  12 make -j -k
  13 ./test-svrt.py
  14 ```
  15
  16 should generate an image example.png in the current directory.
  17
  18 Note that the image generation does not take advantage of GPUs or
  19 multi-core, and can be as fast as 10,000 vignettes per second and as
  20 slow as 40 on a 4GHz i7-6700K.
  21
  22 # Vignette generation and compression #
  23
  24 ## Vignette sets ##
  25
  26 The svrtset.py implements the classes `VignetteSet` and
  27 `CompressedVignetteSet` with the following constructor
  28
  29 ```
  30 __init__(problem_number, nb_samples, batch_size, cuda = False, logger = None)
  31 ```
  32
  33 and the following method to return one batch
  34
  35 ```
  36 (torch.FloatTensor, torch.LongTensor) get_batch(b)
  37 ```
  38
  39 ## Low-level functions ##
  40
  41 The main function for genering vignettes is
  42
  43 ```
  44 torch.ByteTensor svrt.generate_vignettes(int problem_number, torch.LongTensor labels)
  45 ```
  46
  47 where
  48
  49  * `problem_number` indicates which of the 23 problem to use
  50  * `labels` indicates the boolean labels of the vignettes to generate
  51
  52 The returned ByteTensor has three dimensions:
  53
  54  * Vignette index
  55  * Pixel row
  56  * Pixel col
  57
  58 The two additional functions
  59
  60 ```
  61 torch.ByteStorage svrt.compress(torch.ByteStorage x)
  62 ```
  63
  64 and
  65
  66 ```
  67 torch.ByteStorage svrt.uncompress(torch.ByteStorage x)
  68 ```
  69
  70 provide a lossless compression scheme adapted to the ByteStorage of
  71 the vignette ByteTensor (i.e. expecting a lot of 255s, a few 0s, and
  72 no other value).
  73
  74 This compression reduces the memory footprint by a factor ~50, and may
  75 be usefull to deal with very large data-sets and avoid re-generating
  76 images at every batch. It induces a little overhead for decompression,
  77 and moving from CPU to GPU memory.
  78
  79 See vignette_set.py for a class CompressedVignetteSet using it.
  80
  81 # Testing convolution networks #
  82
  83 The file
  84
  85 ```
  86 cnn-svrt.py
  87 ```
  88
  89 provides the implementation of two deep networks, and use the
  90 compressed vignette code to allow the training with several millions
  91 vignettes on a PC with 16Gb and a GPU with 8Gb.
  92
  93 The networks were designed by Afroze Baqapuri during an internship at
  94 Idiap.