{"id":31760670,"url":"https://github.com/torch/nngraph","last_synced_at":"2025-10-29T09:29:43.945Z","repository":{"id":7796765,"uuid":"9166958","full_name":"torch/nngraph","owner":"torch","description":"Graph Computation for nn","archived":false,"fork":false,"pushed_at":"2017-08-01T14:08:52.000Z","size":1909,"stargazers_count":300,"open_issues_count":29,"forks_count":96,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-05-12T22:36:07.727Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/torch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-02T09:40:10.000Z","updated_at":"2024-04-22T16:11:13.000Z","dependencies_parsed_at":"2022-09-17T11:10:29.201Z","dependency_job_id":null,"html_url":"https://github.com/torch/nngraph","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/torch/nngraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torch%2Fnngraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torch%2Fnngraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torch%2Fnngraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torch%2Fnngraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/torch","download_url":"https://codeload.github.com/torch/nngraph/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torch%2Fnngraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002054,"owners_count":26083286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T21:39:55.737Z","updated_at":"2025-10-09T21:39:59.619Z","avatar_url":"https://github.com/torch.png","language":"Lua","readme":"# Neural Network Graph Package\n\n[![Build Status](https://travis-ci.org/torch/nngraph.svg)](https://travis-ci.org/torch/nngraph) \n\nThis package provides graphical computation for `nn` library in [Torch](https://github.com/torch/torch7/blob/master/README.md).\n\n## Requirements\n\nYou do *not* need `graphviz` to be able to use this library, but if you have it you will be able to display the graphs that you have created. For installing the package run the appropriate command below:\n\n```bash\n# Mac users\nbrew install graphviz\n# Debian/Ubuntu users\nsudo apt-get install graphviz -y\n```\n\n## Usage\n\n[Plug: A more explanatory nngraph tutorial by Nando De Freitas of  Oxford](https://www.cs.ox.ac.uk/people/nando.defreitas/machinelearning/practicals/practical5.pdf)\n\nThe aim of this library is to provide users of `nn` package with tools to easily create complicated architectures.\nAny given `nn` `module` is going to be bundled into a *graph node*.\nThe `__call__` operator of an instance of `nn.Module` is used to create architectures as if one is writing function calls.\n\n### Two hidden layers MLP\n\n```lua\nh1 = nn.Linear(20, 10)()\nh2 = nn.Linear(10, 1)(nn.Tanh()(nn.Linear(10, 10)(nn.Tanh()(h1))))\nmlp = nn.gModule({h1}, {h2})\n\nx = torch.rand(20)\ndx = torch.rand(1)\nmlp:updateOutput(x)\nmlp:updateGradInput(x, dx)\nmlp:accGradParameters(x, dx)\n\n-- draw graph (the forward graph, '.fg')\ngraph.dot(mlp.fg, 'MLP')\n```\n\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp.png\" width=\"300px\"/\u003e\n\nRead this diagram from top to bottom, with the first and last nodes being *dummy nodes* that regroup all inputs and outputs of the graph.\nThe `module` entry describes the function of the node, as applies to `input`, and producing a result of the shape `gradOutput`; `mapindex` contains pointers to the parent nodes.\n\nTo save the *graph* on file, specify the file name, and both a `dot` and `svg` files will be saved. For example, you can type:\n\n```lua\ngraph.dot(mlp.fg, 'MLP', 'myMLP')\n```\n\nYou can also use the `__unm__` and `__sub__` operators to replace all `__call__`:\n```lua\nh1 = - nn.Linear(20,10)\nh2 = h1\n     - nn.Tanh()\n     - nn.Linear(10,10)\n     - nn.Tanh()\n     - nn.Linear(10, 1)\nmlp = nn.gModule({h1}, {h2})\n```\n\n\n### A network with 2 inputs and 2 outputs\n\n```lua\nh1 = nn.Linear(20, 20)()\nh2 = nn.Linear(10, 10)()\nhh1 = nn.Linear(20, 1)(nn.Tanh()(h1))\nhh2 = nn.Linear(10, 1)(nn.Tanh()(h2))\nmadd = nn.CAddTable()({hh1, hh2})\noA = nn.Sigmoid()(madd)\noB = nn.Tanh()(madd)\ngmod = nn.gModule({h1, h2}, {oA, oB})\n\nx1 = torch.rand(20)\nx2 = torch.rand(10)\n\ngmod:updateOutput({x1, x2})\ngmod:updateGradInput({x1, x2}, {torch.rand(1), torch.rand(1)})\ngraph.dot(gmod.fg, 'Big MLP')\n```\n\nAlternatively, you can use `-` to make your code looks like the data flow:\n\n```lua\nh1 = - nn.Linear(20,20)\nh2 = - nn.Linear(10,10)\nhh1 = h1 - nn.Tanh() - nn.Linear(20,1)\nhh2 = h2 - nn.Tanh() - nn.Linear(10,1)\nmadd = {hh1,hh2} - nn.CAddTable()\noA = madd - nn.Sigmoid()\noB = madd - nn.Tanh()\ngmod = nn.gModule( {h1,h2}, {oA,oB} )\n```\n\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp2.png\" width=\"300px\"/\u003e\n\n\n### A network with containers\n\nAnother net that uses container modules (like `ParallelTable`) that output a table of outputs.\n\n```lua\nm = nn.Sequential()\nm:add(nn.SplitTable(1))\nm:add(nn.ParallelTable():add(nn.Linear(10, 20)):add(nn.Linear(10, 30)))\ninput = nn.Identity()()\ninput1, input2 = m(input):split(2)\nm3 = nn.JoinTable(1)({input1, input2})\n\ng = nn.gModule({input}, {m3})\n\nindata = torch.rand(2, 10)\ngdata = torch.rand(50)\ng:forward(indata)\ng:backward(indata, gdata)\n\ngraph.dot(g.fg, 'Forward Graph')\ngraph.dot(g.bg, 'Backward Graph')\n```\n\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp3_forward.png\" width=\"300px\"/\u003e\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp3_backward.png\" width=\"300px\"/\u003e\n\n\n### More fun with graphs\n\nA multi-layer network where each layer takes output of previous two layers as input.\n\n```lua\ninput = nn.Identity()()\nL1 = nn.Tanh()(nn.Linear(10, 20)(input))\nL2 = nn.Tanh()(nn.Linear(30, 60)(nn.JoinTable(1)({input, L1})))\nL3 = nn.Tanh()(nn.Linear(80, 160)(nn.JoinTable(1)({L1, L2})))\n\ng = nn.gModule({input}, {L3})\n\nindata = torch.rand(10)\ngdata = torch.rand(160)\ng:forward(indata)\ng:backward(indata, gdata)\n\ngraph.dot(g.fg, 'Forward Graph')\ngraph.dot(g.bg, 'Backward Graph')\n```\n\nAs your graph getting bigger and more complicated, the nested parentheses may become confusing. In this case, using `-` to chain the modules is a clearer and easier way:\n```lua\ninput = - nn.Identity()\nL1 =  input \n     - nn.Linear(10, 20) \n     - nn.Tanh()\nL2 =  { input, L1 }\n     -  nn.JoinTable(1)\n     -  nn.Linear(30,60) \n     -  nn.Tanh()\nL3 = { L1,L2 }\n     - nn.JoinTable(1)\n     - nn.Linear(80,160)\n     - nn.Tanh()\ng = nn.gModule({input},{L3})\n```\n\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp4_forward.png\" width=\"300px\"/\u003e\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/mlp4_backward.png\" width=\"300px\"/\u003e\n\n\n## Annotations\n\nIt is possible to add annotations to your network, such as labeling nodes with names or attributes which will show up when you graph the network.\nThis can be helpful in large graphs.\n\nFor the full list of graph attributes see the\n[graphviz documentation](http://www.graphviz.org/doc/info/attrs.html).\n\n```lua\ninput = nn.Identity()()\nL1 = nn.Tanh()(nn.Linear(10, 20)(input)):annotate{\n   name = 'L1', description = 'Level 1 Node',\n   graphAttributes = {color = 'red'}\n}\nL2 = nn.Tanh()(nn.Linear(30, 60)(nn.JoinTable(1)({input, L1}))):annotate{\n   name = 'L2', description = 'Level 2 Node',\n   graphAttributes = {color = 'blue', fontcolor = 'green'}\n}\nL3 = nn.Tanh()(nn.Linear(80, 160)(nn.JoinTable(1)({L1, L2}))):annotate{\n   name = 'L3', description = 'Level 3 Node',\n   graphAttributes = {color = 'green',\n   style = 'filled', fillcolor = 'yellow'}\n}\n\ng = nn.gModule({input},{L3})\n\nindata = torch.rand(10)\ngdata = torch.rand(160)\ng:forward(indata)\ng:backward(indata, gdata)\n\ngraph.dot(g.fg, 'Forward Graph', '/tmp/fg')\ngraph.dot(g.bg, 'Backward Graph', '/tmp/bg')\n```\n\nIn this case, the graphs are saved in the following 4 files: `/tmp/{fg,bg}.{dot,svg}`.\n\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/annotation_fg.png\" width=\"300px\"/\u003e\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/annotation_bg.png\" width=\"300px\"/\u003e\n\n## Debugging\n\nWith nngraph, one can create very complicated networks. In these cases, finding errors can be hard. For that purpose, nngraph provides several useful utilities. The following code snippet shows how to use local variable names for annotating the nodes in a graph and how to enable debugging mode that automatically creates an svg file with error node marked in case of a runtime error.\n\n```lua\n\nrequire 'nngraph'\n\n-- generate SVG of the graph with the problem node highlighted\n-- and hover over the nodes in svg to see the filename:line_number info\n-- nodes will be annotated with local variable names even if debug mode is not enabled.\nnngraph.setDebug(true)\n\nlocal function get_net(from, to)\n\tlocal from = from or 10\n\tlocal to = to or 10\n\tlocal input_x = nn.Identity()()\n\tlocal linear_module = nn.Linear(from, to)(input_x)\n\n\t-- Annotate nodes with local variable names\n\tnngraph.annotateNodes()\n\treturn nn.gModule({input_x},{linear_module})\nend\n\nlocal net = get_net(10,10)\n\n-- if you give a name to the net, it will use that name to produce the\n-- svg in case of error, if not, it will come up with a name\n-- that is derived from number of inputs and outputs to the graph\nnet.name = 'my_bad_linear_net'\n\n-- prepare an input that is of the wrong size to force an error\nlocal input = torch.rand(11)\npcall(function() net:updateOutput(input) end)\n-- it should have produced an error and spit out a graph\n-- just run Safari to display the svg\nos.execute('open -a  Safari my_bad_linear_net.svg')\n```\n\u003cimg src= \"https://raw.github.com/koraykv/torch-nngraph/master/doc/my_bad_linear_net.png\" width=\"300px\"/\u003e\n\n","funding_links":[],"categories":["Lua","Libraries"],"sub_categories":["Tools","[Tools](#tools-1)","Speech Recognition","Model related"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorch%2Fnngraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftorch%2Fnngraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorch%2Fnngraph/lists"}