{"id":13407117,"url":"https://github.com/ericjang/tdb","last_synced_at":"2025-05-16T05:06:56.621Z","repository":{"id":57474801,"uuid":"47898542","full_name":"ericjang/tdb","owner":"ericjang","description":"Interactive, node-by-node debugging and visualization for TensorFlow","archived":false,"fork":false,"pushed_at":"2017-01-27T04:42:40.000Z","size":159,"stargazers_count":1355,"open_issues_count":8,"forks_count":141,"subscribers_count":68,"default_branch":"master","last_synced_at":"2025-05-10T17:04:19.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericjang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-12T23:20:02.000Z","updated_at":"2025-04-12T10:05:00.000Z","dependencies_parsed_at":"2022-09-10T02:22:22.591Z","dependency_job_id":null,"html_url":"https://github.com/ericjang/tdb","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericjang%2Ftdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericjang%2Ftdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericjang%2Ftdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericjang%2Ftdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericjang","download_url":"https://codeload.github.com/ericjang/tdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471061,"owners_count":22076585,"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","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":"2024-07-30T20:00:21.653Z","updated_at":"2025-05-16T05:06:51.607Z","avatar_url":"https://github.com/ericjang.png","language":"JavaScript","funding_links":[],"categories":["Developer Tools","Python","JavaScript"],"sub_categories":["Deep Learning","General-Purpose Machine Learning"],"readme":"# TDB\n\n*Note: This project is no longer actively being maintained. Please check out the official [tfdbg debugger](https://www.tensorflow.org/versions/master/how_tos/debugger/)\n\nTensorDebugger (TDB) is a visual debugger for deep learning. It extends [TensorFlow](https://www.tensorflow.org/) (Google's Deep Learning framework) with breakpoints + real-time visualization of the data flowing through the computational graph.\n\n[Video Demo](https://www.youtube.com/watch?v=VcoVEvGEmFM)\n\n\u003cimg src=\"http://i.imgur.com/n0PmXQn.gif\"/\u003e\n\nSpecifically, TDB is the combination of a Python library and a Jupyter notebook extension, built around Google's TensorFlow framework. Together, these extend TensorFlow with the following features:\n\n- **Breakpoints**: Set breakpoints on Ops and Tensors in the graph. Graph execution is paused on breakpoints and resumed by the user (via `tdb.c()`) Debugging features can be used with or without the visualization frontend.\n- **Arbitrary Summary Plots**: Real-time visualization of high-level information (e.g. histograms, gradient magnitudes, weight saturation) while the network is being trained. Supports arbitrary, user-defined plot functions.\n- **Flexible**: Mix user-defined Python and plotting functions with TensorFlow Nodes. These take in `tf.Tensors` and output placeholder nodes to be plugged into TensorFlow nodes. The below diagram illustrates how TDB nodes can be mixed with the TensorFlow graph.\n\n![heterogenous](http://i.imgur.com/7xfA6Pg.png?1)\n\n\n## Motivations\n\nModern machine learning models are parametrically complex and require considerable intuition to fine-tune properly.\n\nIn particular, Deep Learning methods are especially powerful, but hard to interpret in regards to their capabilities and learned representations.\n\nCan we enable better understanding of how neural nets learn, without having to change model code or sacrifice performance? Can I finish my thesis on time?\n\nTDB addresses these challenges by providing run-time visualization tools for neural nets. Real-time visual debugging allows training bugs to be detected sooner, thereby reducing the iteration time needed to build the right model.\n\n## Setup\n\nTo install the Python library,\n\n```bash\npip install tfdebugger\n```\n\nTo install the Jupyter Notebook extension, run the following in a Python terminal (you will need to have IPython or [Jupyter](https://jupyter.readthedocs.org/en/latest/install.html) installed)\n\n```python\nimport notebook.nbextensions\nimport urllib\nimport zipfile\nSOURCE_URL = 'https://github.com/ericjang/tdb/releases/download/tdb_ext_v0.1/tdb_ext.zip'\nurllib.urlretrieve(SOURCE_URL, 'tdb_ext.zip')\nwith zipfile.ZipFile('tdb_ext.zip', \"r\") as z:\n    z.extractall(\"\")\nnotebook.nbextensions.install_nbextension('tdb_ext',user=True)\n```\n\n## Tutorial\n\nTo get started, check out the [MNIST Visualization Demo](notebooks/mnist_demo.ipynb). More examples and visualizations to come soon.\n\n## User Guide\n\n### Debugging\n\n#### Start \n```python\nstatus,result=tdb.debug(evals,feed_dict=None,breakpoints=None,break_immediately=False,session=None)\n```\n\n`debug()` behaves just like Tensorflow's Session.run(). If a breakpoint is hit, `status` is set to 'PAUSED' and `result` is set to `None`. Otherwise, `status` is set to 'FINISHED' and `result` is set to a list of evaluated values.\n\n#### Continue\n```python\nstatus,result=tdb.c()\n```\n\nContinues execution of a paused session, until the next breakpoint or end. Behaves like `debug`.\n\n\n#### Step\n```python\nstatus,result=tdb.s()\n```\n\nEvaluate the next node, then pause immediately to await user input. Unless we have reached the end of the execution queue, `status` will remain 'PAUSED'. `result` is set to the value of the node we just evaluated.\n\n#### Where\n\n```python\nq=tdb.get_exe_queue()\n```\n\nReturn value: list of remaining nodes to be evaluated, in order.\n\n#### print\n\n```python\nval=tdb.get_value(node)\n```\n\nReturns value of an evaluated node (a string name or a tf.Tensor)\n\n### Custom Nodes\n\nTDB supports 2 types of custom Ops:\n\n#### Python\n\nHere is an example of mixing tdb.PythonOps with TensorFlow.\n\nDefine the following function:\n```\ndef myadd(ctx,a,b):\n\treturn a+b\n```\n\n```python\na=tf.constant(2)\nb=tf.constant(3)\nc=tdb.python_op(myadd,inputs=[a,b],outputs=[tf.placeholder(tf.int32)]) # a+b\nd=tf.neg(c)\nstatus,result=tdb.debug([d], feed_dict=None, breakpoints=None, break_immediately=False)\t\n```\n\nWhen `myadd` gets evaluated, `ctx` is the instance of the PythonOp that it belongs to. You can use ctx to store state information (i.e. accumulate loss history).\n\n#### Plotting\n\nPlotOps are a special instance of PythonOp that send graphical output to the frontend.\n\nThis only works with Matplotlib at the moment, but other plotting backends (Seaborn, Bokeh, Plotly) are coming soon.\n\n```python\ndef watch_loss(ctx,loss):\n  if not hasattr(ctx, 'loss_history'):\n    ctx.loss_history=[]\n  ctx.loss_history.append(loss)\n  plt.plot(ctx.loss_history)\n  plt.ylabel('loss')\n```\n\n```python\nploss=tdb.plot_op(viz.watch_loss,inputs=[loss])\n```\n\nRefer to the [MNIST Visualization Demo](notebooks/mnist_demo.ipynb) for more examples. You can also find more examples in the [tests/](tdb/tests) directory.\n\n## FAQ\n\n### Is TDB affiliated with TensorFlow?\n\nNo, but it is built on top of it.\n\n### What is TDB good for?\n\nTDB is especially useful at the model prototyping stage and verifying correctness in an intuitive manner. It is also useful for high-level visualization of hidden layers during training.\n\n### How is TDB different from TensorBoard?\n\nTensorBoard is a suite of visualization tools included with Tensorflow. Both TDB and TensorBoard attach auxiliary nodes to the TensorFlow graph in order to inspect data.\n\nTensorBoard cannot be used concurrently with running a TensorFlow graph; log files must be written first. TDB interfaces directly with the execution of a TensorFlow graph, and allows for stepping through execution one node at a time.\n\nOut of the box, TensorBoard currently only supports logging for a few predefined data formats. \n\nTDB is to TensorBoard as GDB is to printf. Both are useful in different contexts.\n\n\n\n## License\n\nApache 2.0\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericjang%2Ftdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericjang%2Ftdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericjang%2Ftdb/lists"}