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 ##Input and output##
  52
  53 If a node has a single predecessor, its output is taken as-is. If it
  54 has multiple predecessors, all the outputs are collected into a table,
  55 and the table is used as input. The indexes of the outputs in that
  56 table reflects the order in which the predecessors appeared in the
  57 DAG:connect() commands.
  58
  59 The input to the DAG (respectively the produced output) is a nested
  60 table of inputs reflecting the structure of the nested table of
  61 modules provided to DAG:setInput (respectively DAG:setOutput)
  62
  63 So for instance, in the example above, the model expects a tensor as
  64 input, since it is the input to the module a, and its output will is a
  65 table composed of two tensors, corresponding to the outputs of d and e
  66 respectively.
  67
  68 #Usage#
  69
  70 ##nn.DAG()##
  71
  72 Create a new empty DAG, which inherits from nn.Container.
  73
  74 ##nn.DAG:connect([module1 [, module2 [, ...]]])##
  75
  76 Add new nodes corresponding to the modules passed as arguments if they
  77 are not already existing. Add edges between every two nodes
  78 corresponding to a pair of successive modules in the arguments.
  79
  80 Calling it with n > 2 arguments is strictly equivalent to calling it
  81 n-1 times on the pairs of successive arguments.
  82
  83 ##nn.DAG:setInput(i)##
  84
  85 Defines the content and structure of the input. The argument should be
  86 either a module, or a (nested) table of module. The input to the DAG
  87 should be a (nested) table of inputs with the corresponding structure.
  88
  89 ##nn.DAG:setOutput(o)##
  90
  91 Similar to DAG:setInput().
  92
  93 ##nn.DAG:print()##
  94
  95 Prints the list of nodes.
  96
  97 ##nn.DAG:saveDot(filename)##
  98
  99 Save a dot file to be used by the Graphviz set of tools for graph
 100 visualization. This dot file can than be used for instance to produce
 101 a pdf file with
 102
 103 ```
 104 dot graph.dot -T pdf -o graph.pdf
 105 ```
 106
 107 ##nn.DAG:updateOutput(input)##
 108
 109 See the torch documentation.
 110
 111 ##nn.DAG:updateGradInput(input, gradOutput)##
 112
 113 See the torch documentation.
 114
 115 ##nn.DAG:accGradParameters(input, gradOutput, scale)##
 116
 117 See the torch documentation.
 118
 119 --
 120 *Francois Fleuret, Jan 13th, 2017*