README.md

   1
   2 #Introduction#
   3
   4 This package implements a new module nn.DAG which inherits from
   5 nn.Container and allows to combine modules in an arbitrary graph
   6 without cycle.
   7
   8 ##Example##
   9
  10 A typical use would be:
  11
  12 ```Lua
  13 model = nn.DAG()
  14
  15 a = nn.Linear(100, 10)
  16 b = nn.ReLU()
  17 c = nn.Linear(10, 15)
  18 d = nn.CMulTable()
  19 e = nn.Linear(15, 15)
  20
  21 model:connect(a, b)
  22 model:connect(b, nn.Linear(10, 15), nn.ReLU(), d)
  23 model:connect(b, c)
  24 model:connect(c, d)
  25 model:connect(c, nn.Mul(-1), e)
  26
  27 model:setInput(a)
  28 model:setOutput({ d, e })
  29
  30 input = torch.Tensor(30, 100):uniform()
  31 output = model:updateOutput(input)
  32
  33 ```
  34
  35 which would encode the following graph
  36
  37                  +- Linear(10, 10) -> ReLU ---> d -->
  38                 /                              /
  39                /                              /
  40     --> a --> b -----------> c --------------+
  41                               \
  42                                \
  43                                 +-- Mul(-1) --> e -->
  44
  45 and run a forward pass with a random batch of 30 samples.
  46
  47 Note that DAG:connect allows to add a bunch of edges at once. This is
  48 particularly useful to add anonymous modules which have a single
  49 predecessor and successor.
  50
  51 #Usage#
  52
  53 ##Input and output##
  54
  55 The DAG can deal with modules which take as input and produce as
  56 output tensors and nested tables of tensors.
  57
  58 If a node has a single predecessor, the output of the latter is taken
  59 as-is as the input of the former. If it has multiple predecessors, all
  60 the outputs are collected into a table, and the table is used as
  61 input. The indexes of the outputs in that table reflects the order in
  62 which the edges where created in the DAG:connect() commands.
  63
  64 The input to the DAG (respectively the produced output) is a nested
  65 table of inputs reflecting the structure of the nested table of
  66 modules provided to DAG:setInput (respectively DAG:setOutput)
  67
  68 So for instance, in the example above, the model expects a tensor as
  69 input, since it is the input to the module a, and its output will is a
  70 table composed of two tensors, corresponding to the outputs of d and e
  71 respectively.
  72
  73 ##Functions##
  74
  75 ###nn.DAG()###
  76
  77 Create a new empty DAG, which inherits from nn.Container.
  78
  79 ###nn.DAG:connect([module1 [, module2 [, ...]]])###
  80
  81 Add new nodes corresponding to the modules passed as arguments if they
  82 are not already existing. Add edges between every two nodes
  83 corresponding to a pair of successive modules in the arguments.
  84
  85 Calling it with n > 2 arguments is strictly equivalent to calling it
  86 n-1 times on the pairs of successive arguments.
  87
  88 ###nn.DAG:setInput(i)###
  89
  90 Defines the content and structure of the input. The argument should be
  91 either a module, or a (nested) table of modules. The input to the DAG
  92 should be a (nested) table of inputs, with the corresponding structure.
  93
  94 ###nn.DAG:setOutput(o)###
  95
  96 Similar to DAG:setInput().
  97
  98 ###nn.DAG:print()###
  99
 100 Prints the list of nodes.
 101
 102 ###nn.DAG:saveDot(filename)###
 103
 104 Save a dot file to be used by the Graphviz set of tools for graph
 105 visualization. This dot file can than be used for instance to produce
 106 a pdf file with
 107
 108 ```
 109 dot graph.dot -T pdf -o graph.pdf
 110 ```
 111
 112 --
 113 *Francois Fleuret, Jan 13th, 2017*