README.md

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