X-Git-Url: https://fleuret.org/cgi-bin/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.md;h=869a1d97c09df81fd886168e78159bc56b7f8bdf;hb=91d22819226af01ec2eee6aed49007e058dc6e50;hp=3b8d274294ac1316b5fbbb38e9228703cce89917;hpb=34eff36879f9b2fa3ec1130fccb723c5b907a586;p=dagnn.git

diff --git a/README.md b/README.md
index 3b8d274..869a1d9 100644
--- a/README.md
+++ b/README.md
@@ -1,51 +1,114 @@
 
-This package implements a new module nn.DAG which inherits from nn.Container and allows to combine modules in an arbitrary graph without cycle.
+# Introduction #
 
-#Example#
+This package implements a new module nn.DAG for the torch framework,
+which inherits from nn.Container and allows to combine modules in an
+arbitrary graph without cycle.
 
-The typical use is:
+## Example ##
 
-```Lua
+A typical use would be:
+
+```lua
 model = nn.DAG()
 
 a = nn.Linear(100, 10)
 b = nn.ReLU()
 c = nn.Linear(10, 15)
-d = nn.Linear(10, 15)
-e = nn.CMulTable()
-f = nn.Linear(15, 15)
+d = nn.CMulTable()
+e = nn.Linear(15, 15)
 
-model:addEdge(a, b)
-model:addEdge(b, c)
-model:addEdge(b, d)
-model:addEdge(c, e)
-model:addEdge(d, e)
-model:addEdge(d, f)
+model:connect(a, b)
+model:connect(b, nn.Linear(10, 15), nn.ReLU(), d)
+model:connect(b, c)
+model:connect(c, d)
+model:connect(c, nn.Mul(-1), e)
 
 model:setInput(a)
-model:setOutput({ e, f })
+model:setOutput({ d, e })
 
-input = torch.Tensor(300, 100):uniform()
-output = model:updateOutput(input):clone()
+input = torch.Tensor(30, 100):uniform()
+output = model:updateOutput(input)
 
 ```
 
 which would encode the following graph
 
-                       +--> c ----> e -->
-                      /            /
-                     /            /
-    input --> a --> b ----> d ---+          output
-                             \
+                 +- Linear(10, 10) -> ReLU ---> d -->
+                /                              /
+               /                              /
+    --> a --> b -----------> c --------------+
                               \
-                               +--> f -->
+                               \
+                                +-- Mul(-1) --> e -->
+
+and run a forward pass with a random batch of 30 samples.
+
+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.
+
+# Usage #
+
+## Input and output ##
+
+The DAG can deal with modules which take as input and produce as
+output tensors and nested tables of tensors.
+
+If a node has a single predecessor, the output of the latter is taken
+as-is as the input to the former. 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 reflect the
+chronological order in which the edges where created in the
+DAG:connect() commands.
+
+The input to the DAG (respectively the produced output) is a nested
+table of inputs reflecting the structure of the nested table of
+modules given as argument to DAG:setInput (respectively DAG:setOutput)
+
+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.
+
+## Functions ##
+
+### nn.DAG() ###
 
-#Input and output#
+Create a new empty DAG, which inherits from nn.Container.
 
-If a node has a single successor, its output is sent unchanged as input to that successor. If it has multiple successors, the outputs are collected into a table, and the table is used as input to the successor node. The indexes of the outputs in that table reflects the order in which they appear in the addEdge commands.
+### nn.DAG:connect([module1 [, module2 [, ...]]]) ###
 
-The expected input (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)
+Add new nodes corresponding to the modules passed as arguments if they
+have not been already added in a previous call. Add edges between
+every two nodes associated to two successive modules in the arguments.
 
-So for instance, in the example above, the DAG 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 e and f respectively.
+Calling this function with n > 2 arguments is strictly equivalent to
+calling it n-1 times on the pairs of successive arguments.
+
+### nn.DAG:setInput(i) ###
+
+Defines the content and structure of the input. The argument should be
+either a module, or a (nested) table of modules. The input to the DAG
+should be a (nested) table of inputs, with the corresponding structure.
+
+### nn.DAG:setOutput(o) ###
+
+Similar to DAG:setInput().
+
+### nn.DAG:print() ###
+
+Prints the list of nodes.
+
+### nn.DAG:saveDot(filename) ###
+
+Save a dot file to be used by the Graphviz set of tools for graph
+visualization. This dot file can than be used for instance to produce
+a pdf file with
+
+```
+dot graph.dot -T pdf -o graph.pdf
+```
 
-*Francois Fleuret, Jan 12th, 2017*
+-- 
+*Francois Fleuret, Jan 13th, 2017*