X-Git-Url: https://www.fleuret.org/cgi-bin/gitweb/gitweb.cgi?p=dagnn.git;a=blobdiff_plain;f=README.md;h=fa77a7e785ccdb23880cacdea55e5d609f294399;hp=58c386f087e6f37e20197acb52870c4702852fb9;hb=HEAD;hpb=05b6ab6e2b97f6f8f551907ca92ffa2d12a79b75 diff --git a/README.md b/README.md index 58c386f..fa77a7e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ +# Introduction # -#Introduction# +This package implements a new module nn.DAG for the [torch framework](https://torch.ch), +which inherits from [nn.Container](https://github.com/torch/nn/blob/master/Container.lua) and allows to combine modules in an +arbitrary [Directed Acyclic Graph (DAG).](https://en.wikipedia.org/wiki/Directed_acyclic_graph) -This package implements a new module nn.DAG which inherits from nn.Container and allows to combine modules in an arbitrary graph without cycle. - -##Example## +## Example ## A typical use would be: -```Lua +```lua model = nn.DAG() a = nn.Linear(100, 10) @@ -42,56 +43,79 @@ which would encode the following graph 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. +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. -##Input and output## +# Usage # -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 of the DAG:connect() commands. +## Input and output ## -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) +The DAG can deal with modules which take as input and produce as +output tensors and nested tables of tensors. -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. +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. -#Usage# +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) -##nn.DAG()## +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 is a +table composed of two tensors, corresponding to the outputs of d and e +respectively. -Create a new empty DAG, which inherits from nn.Container. +## Functions ## -##nn.DAG:connect([module1 [, module2 [, ...]]])## +### nn.DAG() ### -Add new nodes corresponding to the modules passed as arguments if they -are not already existing. Add edges between every the nodes -corresponding to pairs of successive modules. +Create a new empty DAG, which inherits from nn.Container. -##nn.DAG:setInput(i)## +### nn.DAG:connect(module1, module2 [, module3, [...]]) ### -Defines the content and structure of the input. The argument should be -either a module, or a (nested) table of module. The input to the DAG -should be a (nested) table of inputs with the corresponding structure. +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. -##nn.DAG:setOutput(o)## +Calling this function with n > 2 arguments is strictly equivalent to +calling it n-1 times on the pairs of successive arguments. -Same as DAG:setInput. +Accepting more than two arguments allows in particular to add +anonymous modules, which are not associated to variables. In principle +the only ones that have to be non-anonymous are those that have more +than one successor/predecessor and/or are inputs/outputs. -##nn.DAG:print()## +### nn.DAG:setInput(i) ### -Prints the list of nodes. +Define 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:saveDot(filename)## +### nn.DAG:setOutput(o) ### -Save a dot file to be used by the Graphviz set of tools for graph visualization. +Similar to DAG:setInput(). -##nn.DAG:updateOutput(input)## +### nn.DAG:print() ### -See the torch documentation. +Print the list of nodes. -##nn.DAG:updateGradInput(input, gradOutput)## +### nn.DAG:saveDot(filename) ### -See the torch documentation. +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 such as [this one](https://fleuret.org/git-extract/dagnn/graph.pdf) with -##nn.DAG:accGradParameters(input, gradOutput, scale)## +``` +dot graph.dot -T pdf -o graph.pdf +``` -See the torch documentation. +### nn.DAG:setLabel(module, name) ### -*Francois Fleuret, Jan 13th, 2017* +Add a label to the given module, that will be used for DAG:print() and DAG:saveDot()