# torchview
[](https://www.python.org/downloads/release/python-370/)
[](https://badge.fury.io/py/torchview)
[](https://anaconda.org/conda-forge/torchview)
[](https://github.com/mert-kurttutan/torchview/actions/workflows/test.yml)
[](https://github.com/mert-kurttutan/torchview/blob/main/LICENSE)
[](https://codecov.io/gh/mert-kurttutan/torchview)
[](https://pepy.tech/project/torchview)
Torchview provides visualization of pytorch models in the form of visual graphs. Visualization includes tensors, modules, torch.functions and info such as input/output shapes.
Pytorch version of `plot_model of keras` (and more)
Supports PyTorch versions $\geq$ 1.7.
## Useful features
<p align="center">
<picture align="center">
<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/88637659/213171745-7acf07df-6578-4a50-a106-1a7b368f8d6c.svg">
<source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/88637659/213173736-6e91724c-8de1-4568-9d52-297b4b5ff0d2.svg">
<img alt="Shows a bar chart with benchmark results." src="https://user-images.githubusercontent.com/88637659/213173736-6e91724c-8de1-4568-9d52-297b4b5ff0d2.svg">
</picture>
</p>
## Installation
First, you need to install graphviz,
```Bash
pip install graphviz
```
For python interface of graphiz to work, you need to have dot layout command working in your system. If it isn't already installed, I suggest you run the following depeding on your OS,
Debian-based Linux distro (e.g. Ubuntu):
```Bash
apt-get install graphviz
```
Windows:
```Bash
choco install graphviz
```
macOS
```Bash
brew install graphviz
```
see more details [here](https://graphviz.readthedocs.io/en/stable/manual.html)
Then, continue with installing torchview using pip
```Bash
pip install torchview
```
or if you want via conda
```Bash
conda install -c conda-forge torchview
```
or if you want most up-to-date version, install directly from repo
```Bash
pip install git+https://github.com/mert-kurttutan/torchview.git
```
## How To Use
```python
from torchview import draw_graph
model = MLP()
batch_size = 2
# device='meta' -> no memory is consumed for visualization
model_graph = draw_graph(model, input_size=(batch_size, 128), device='meta')
model_graph.visual_graph
```
## Notebook Examples
For more examples, see colab notebooks below,
**Introduction Notebook:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_introduction.ipynb)
**Computer Vision Models:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_vision.ipynb)
**NLP Models:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_text.ipynb)
<!-- single_input_all_cols.out -->
**Note:** Output graphviz visuals return images with desired sizes. But sometimes, on VSCode, some shapes are being cropped due to large size and svg rendering on by VSCode. To solve this, I suggest you run the following
```python
import graphviz
graphviz.set_jupyter_format('png')
```
This problem does not occur on other platforms e.g. JupyterLab or Google Colab.
## Supported Features
* Almost all the models, RNN, Sequentials, Skip Connection, Hugging Face Models
* Support for meta tensors -> no memory consumption (for very Large models) (pytorch version $\geq$ 1.13) .
* Shows operations between tensors (in addition to module calls)
* Rolling/Unrolling feature. Recursively used modules can be rolled visually, see below.
* Diverse set of inputs/output types, e.g. nested data structure (dict, list, etc), huggingface tokenizer outputs
## Documentation
```python
def draw_graph(
model: nn.Module,
input_data: INPUT_DATA_TYPE | None = None,
input_size: INPUT_SIZE_TYPE | None = None,
graph_name: str = 'model',
depth: int | float = 3,
device: torch.device | str | None = None,
dtypes: list[torch.dtype] | None = None,
mode: str | None = None,
strict: bool = True,
expand_nested: bool = False,
graph_dir: str | None = None,
hide_module_functions: bool = True,
hide_inner_tensors: bool = True,
roll: bool = False,
show_shapes: bool = True,
save_graph: bool = False,
filename: str | None = None,
directory: str = '.',
**kwargs: Any,
) -> ComputationGraph:
'''Returns visual representation of the input Pytorch Module with
ComputationGraph object. ComputationGraph object contains:
1) Root nodes (usually tensor node for input tensors) which connect to all
the other nodes of computation graph of pytorch module recorded during forward
propagation.
2) graphviz.Digraph object that contains visual representation of computation
graph of pytorch module. This graph visual shows modules/ module hierarchy,
torch_functions, shapes and tensors recorded during forward prop, for examples
see documentation, and colab notebooks.
Args:
model (nn.Module):
Pytorch model to represent visually.
input_data (data structure containing torch.Tensor):
input for forward method of model. Wrap it in a list for
multiple args or in a dict or kwargs
input_size (Sequence of Sizes):
Shape of input data as a List/Tuple/torch.Size
(dtypes must match model input, default is FloatTensors).
Default: None
graph_name (str):
Name for graphviz.Digraph object. Also default name graphviz file
of Graph Visualization
Default: 'model'
depth (int):
Upper limit for depth of nodes to be shown in visualization.
Depth is measured how far is module/tensor inside the module hierarchy.
For instance, main module has depth=0, whereas submodule of main module
has depth=1, and so on.
Default: 3
device (str or torch.device):
Device to place and input tensors. Defaults to
gpu if cuda is seen by pytorch, otherwise to cpu.
Default: None
dtypes (list of torch.dtype):
Uses dtypes to set the types of input tensor if
input size is given.
mode (str):
Mode of model to use for forward prop. Defaults
to Eval mode if not given
Default: None
strict (bool):
if true, graphviz visual does not allow multiple edges
between nodes. Mutiple edge occurs e.g. when there are tensors
from module node to module node and hiding those tensors
Default: True
expand_nested(bool):
if true shows nested modules with dashed borders
graph_dir (str):
Sets the direction of visual graph
'TB' -> Top to Bottom
'LR' -> Left to Right
'BT' -> Bottom to Top
'RL' -> Right to Left
Default: None -> TB
hide_module_function (bool):
Determines whether to hide module torch_functions. Some
modules consist only of torch_functions (no submodule),
e.g. nn.Conv2d.
True => Dont include module functions in graphviz
False => Include modules function in graphviz
Default: True
hide_inner_tensors (bool):
Inner tensor is all the tensors of computation graph
but input and output tensors
True => Does not show inner tensors in graphviz
False => Shows inner tensors in graphviz
Default: True
roll (bool):
If true, rolls recursive modules.
Default: False
show_shapes (bool):
True => Show shape of tensor, input, and output
False => Dont show
Default: True
save_graph (bool):
True => Saves output file of graphviz graph
False => Does not save
Default: False
filename (str):
name of the file to store dot syntax representation and
image file of graphviz graph. Defaults to graph_name
directory (str):
directory in which to store graphviz output files.
Default: .
Returns:
ComputationGraph object that contains visualization of the input
pytorch model in the form of graphviz Digraph object
'''
```
## Examples
### Rolled Version of Recursive Networks
```python
from torchview import draw_graph
model_graph = draw_graph(
SimpleRNN(), input_size=(2, 3),
graph_name='RecursiveNet',
roll=True
)
model_graph.visual_graph
```
### Show/Hide intermediate (hidden) tensors and Functionals
```python
# Show inner tensors and Functionals
model_graph = draw_graph(
MLP(), input_size=(2, 128),
graph_name='MLP',
hide_inner_tensors=False,
hide_module_functions=False,
)
model_graph.visual_graph
```
### ResNet / Skip Connection / Support for Torch operations / Nested Modules
```python
import torchvision
model_graph = draw_graph(resnet18(), input_size=(1,3,32,32), expand_nested=True)
model_graph.visual_graph
```
## TODO
* [ ] Display Module parameter info
* [ ] Support for Graph Neural Network (GNN)
* [ ] Support for Undirected edges for GNNs
* [ ] Support for torch-based functions[^1]
[^1]: Here, torch-based functions refers to any function that uses only torch functions and modules. This is more general than modules.
## Contributing
All issues and pull requests are much appreciated! If you are wondering how to build the project:
* torchview is actively developed using the latest version of Python.
* Changes should be backward compatible to Python 3.7, and will follow Python's End-of-Life guidance for old versions.
* Run `pip install -r requirements-dev.txt`. We use the latest versions of all dev packages.
* To run unit tests, run `pytest`.
* To update the expected output files, run `pytest --overwrite`.
* To skip output file tests, use `pytest --no-output`
## References
* Parts related to input processing and validation are taken/inspired from torchinfo repository!!.
* Many of the software related parts (e.g. testing) are also taken/inspired from torchinfo repository. So big thanks to @TylerYep!!!
* The algorithm for constructing visual graphs is thanks to `__torch_function__` and subclassing `torch.Tensor`. Big thanks to all those who developed this API!!.
Raw data
{
"_id": null,
"home_page": "",
"name": "torchview",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Mert Kurttutan <kurttutan.mert@gmail.com>",
"keywords": "pytorch,visualization,keras,torch,deep learning,machine learning,ml,neural network",
"author": "Mert Kurttutan",
"author_email": "kurttutan.mert@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0e/56/133b3b958f23def706c37d2ae70648040b4d6bdaec524335dc9a388d869d/torchview-0.2.5.tar.gz",
"platform": null,
"description": "# torchview\n\n[](https://www.python.org/downloads/release/python-370/)\n[](https://badge.fury.io/py/torchview)\n[](https://anaconda.org/conda-forge/torchview)\n[](https://github.com/mert-kurttutan/torchview/actions/workflows/test.yml)\n[](https://github.com/mert-kurttutan/torchview/blob/main/LICENSE)\n[](https://codecov.io/gh/mert-kurttutan/torchview)\n[](https://pepy.tech/project/torchview)\n\nTorchview provides visualization of pytorch models in the form of visual graphs. Visualization includes tensors, modules, torch.functions and info such as input/output shapes.\n\nPytorch version of `plot_model of keras` (and more)\n\nSupports PyTorch versions $\\geq$ 1.7.\n\n## Useful features\n\n<p align=\"center\">\n <picture align=\"center\">\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://user-images.githubusercontent.com/88637659/213171745-7acf07df-6578-4a50-a106-1a7b368f8d6c.svg\">\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://user-images.githubusercontent.com/88637659/213173736-6e91724c-8de1-4568-9d52-297b4b5ff0d2.svg\">\n <img alt=\"Shows a bar chart with benchmark results.\" src=\"https://user-images.githubusercontent.com/88637659/213173736-6e91724c-8de1-4568-9d52-297b4b5ff0d2.svg\">\n </picture>\n</p>\n\n\n\n## Installation\n\nFirst, you need to install graphviz,\n\n```Bash\npip install graphviz\n```\n\nFor python interface of graphiz to work, you need to have dot layout command working in your system. If it isn't already installed, I suggest you run the following depeding on your OS,\n\nDebian-based Linux distro (e.g. Ubuntu):\n\n```Bash\napt-get install graphviz\n```\n\nWindows:\n\n```Bash\nchoco install graphviz\n```\n\nmacOS\n\n```Bash\nbrew install graphviz\n```\n\nsee more details [here](https://graphviz.readthedocs.io/en/stable/manual.html)\n\nThen, continue with installing torchview using pip\n\n```Bash\npip install torchview\n```\n\nor if you want via conda\n\n```Bash\nconda install -c conda-forge torchview\n```\n\nor if you want most up-to-date version, install directly from repo\n\n```Bash\npip install git+https://github.com/mert-kurttutan/torchview.git\n```\n\n## How To Use\n\n```python\nfrom torchview import draw_graph\n\nmodel = MLP()\nbatch_size = 2\n# device='meta' -> no memory is consumed for visualization\nmodel_graph = draw_graph(model, input_size=(batch_size, 128), device='meta')\nmodel_graph.visual_graph\n```\n\n\n\n## Notebook Examples\n\nFor more examples, see colab notebooks below,\n\n**Introduction Notebook:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_introduction.ipynb)\n\n**Computer Vision Models:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_vision.ipynb)\n\n**NLP Models:** [](https://colab.research.google.com/github/mert-kurttutan/torchview/blob/main/docs/example_text.ipynb)\n\n<!-- single_input_all_cols.out -->\n\n**Note:** Output graphviz visuals return images with desired sizes. But sometimes, on VSCode, some shapes are being cropped due to large size and svg rendering on by VSCode. To solve this, I suggest you run the following\n\n```python\nimport graphviz\ngraphviz.set_jupyter_format('png')\n```\n\nThis problem does not occur on other platforms e.g. JupyterLab or Google Colab.\n\n## Supported Features\n\n* Almost all the models, RNN, Sequentials, Skip Connection, Hugging Face Models\n* Support for meta tensors -> no memory consumption (for very Large models) (pytorch version $\\geq$ 1.13) .\n* Shows operations between tensors (in addition to module calls)\n* Rolling/Unrolling feature. Recursively used modules can be rolled visually, see below.\n* Diverse set of inputs/output types, e.g. nested data structure (dict, list, etc), huggingface tokenizer outputs\n\n## Documentation\n\n```python\ndef draw_graph(\n model: nn.Module,\n input_data: INPUT_DATA_TYPE | None = None,\n input_size: INPUT_SIZE_TYPE | None = None,\n graph_name: str = 'model',\n depth: int | float = 3,\n device: torch.device | str | None = None,\n dtypes: list[torch.dtype] | None = None,\n mode: str | None = None,\n strict: bool = True,\n expand_nested: bool = False,\n graph_dir: str | None = None,\n hide_module_functions: bool = True,\n hide_inner_tensors: bool = True,\n roll: bool = False,\n show_shapes: bool = True,\n save_graph: bool = False,\n filename: str | None = None,\n directory: str = '.',\n **kwargs: Any,\n) -> ComputationGraph:\n '''Returns visual representation of the input Pytorch Module with\n ComputationGraph object. ComputationGraph object contains:\n\n 1) Root nodes (usually tensor node for input tensors) which connect to all\n the other nodes of computation graph of pytorch module recorded during forward\n propagation.\n\n 2) graphviz.Digraph object that contains visual representation of computation\n graph of pytorch module. This graph visual shows modules/ module hierarchy,\n torch_functions, shapes and tensors recorded during forward prop, for examples\n see documentation, and colab notebooks.\n\n\n Args:\n model (nn.Module):\n Pytorch model to represent visually.\n\n input_data (data structure containing torch.Tensor):\n input for forward method of model. Wrap it in a list for\n multiple args or in a dict or kwargs\n\n input_size (Sequence of Sizes):\n Shape of input data as a List/Tuple/torch.Size\n (dtypes must match model input, default is FloatTensors).\n Default: None\n\n graph_name (str):\n Name for graphviz.Digraph object. Also default name graphviz file\n of Graph Visualization\n Default: 'model'\n\n depth (int):\n Upper limit for depth of nodes to be shown in visualization.\n Depth is measured how far is module/tensor inside the module hierarchy.\n For instance, main module has depth=0, whereas submodule of main module\n has depth=1, and so on.\n Default: 3\n\n device (str or torch.device):\n Device to place and input tensors. Defaults to\n gpu if cuda is seen by pytorch, otherwise to cpu.\n Default: None\n\n dtypes (list of torch.dtype):\n Uses dtypes to set the types of input tensor if\n input size is given.\n\n mode (str):\n Mode of model to use for forward prop. Defaults\n to Eval mode if not given\n Default: None\n\n strict (bool):\n if true, graphviz visual does not allow multiple edges\n between nodes. Mutiple edge occurs e.g. when there are tensors\n from module node to module node and hiding those tensors\n Default: True\n \n expand_nested(bool):\n if true shows nested modules with dashed borders\n\n graph_dir (str):\n Sets the direction of visual graph\n 'TB' -> Top to Bottom\n 'LR' -> Left to Right\n 'BT' -> Bottom to Top\n 'RL' -> Right to Left\n Default: None -> TB\n\n hide_module_function (bool):\n Determines whether to hide module torch_functions. Some\n modules consist only of torch_functions (no submodule),\n e.g. nn.Conv2d.\n True => Dont include module functions in graphviz\n False => Include modules function in graphviz\n Default: True\n\n hide_inner_tensors (bool):\n Inner tensor is all the tensors of computation graph\n but input and output tensors\n True => Does not show inner tensors in graphviz\n False => Shows inner tensors in graphviz\n Default: True\n\n roll (bool):\n If true, rolls recursive modules.\n Default: False\n\n show_shapes (bool):\n True => Show shape of tensor, input, and output\n False => Dont show\n Default: True\n\n save_graph (bool):\n True => Saves output file of graphviz graph\n False => Does not save\n Default: False\n\n filename (str):\n name of the file to store dot syntax representation and\n image file of graphviz graph. Defaults to graph_name\n\n directory (str):\n directory in which to store graphviz output files.\n Default: .\n\n Returns:\n ComputationGraph object that contains visualization of the input\n pytorch model in the form of graphviz Digraph object\n '''\n```\n\n## Examples\n\n### Rolled Version of Recursive Networks\n\n```python\nfrom torchview import draw_graph\n\nmodel_graph = draw_graph(\n SimpleRNN(), input_size=(2, 3),\n graph_name='RecursiveNet',\n roll=True\n)\nmodel_graph.visual_graph\n```\n\n\n\n### Show/Hide intermediate (hidden) tensors and Functionals\n\n```python\n# Show inner tensors and Functionals\nmodel_graph = draw_graph(\n MLP(), input_size=(2, 128),\n graph_name='MLP',\n hide_inner_tensors=False,\n hide_module_functions=False,\n)\n\nmodel_graph.visual_graph\n```\n\n\n\n\n### ResNet / Skip Connection / Support for Torch operations / Nested Modules\n\n```python\nimport torchvision\n\nmodel_graph = draw_graph(resnet18(), input_size=(1,3,32,32), expand_nested=True)\nmodel_graph.visual_graph\n```\n\n\n\n## TODO\n\n* [ ] Display Module parameter info\n* [ ] Support for Graph Neural Network (GNN)\n* [ ] Support for Undirected edges for GNNs\n* [ ] Support for torch-based functions[^1]\n\n[^1]: Here, torch-based functions refers to any function that uses only torch functions and modules. This is more general than modules.\n\n## Contributing\n\nAll issues and pull requests are much appreciated! If you are wondering how to build the project:\n\n* torchview is actively developed using the latest version of Python.\n* Changes should be backward compatible to Python 3.7, and will follow Python's End-of-Life guidance for old versions.\n* Run `pip install -r requirements-dev.txt`. We use the latest versions of all dev packages.\n* To run unit tests, run `pytest`.\n* To update the expected output files, run `pytest --overwrite`.\n* To skip output file tests, use `pytest --no-output`\n\n## References\n\n* Parts related to input processing and validation are taken/inspired from torchinfo repository!!.\n* Many of the software related parts (e.g. testing) are also taken/inspired from torchinfo repository. So big thanks to @TylerYep!!!\n* The algorithm for constructing visual graphs is thanks to `__torch_function__` and subclassing `torch.Tensor`. Big thanks to all those who developed this API!!.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Visualization of Pytorch Models",
"version": "0.2.5",
"split_keywords": [
"pytorch",
"visualization",
"keras",
"torch",
"deep learning",
"machine learning",
"ml",
"neural network"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51e4b87459fac4f42110ecdac96c6d6a85101b97783adf01eef0c5463dee9b03",
"md5": "b077abad975dc842c3c99ba3732f1d9e",
"sha256": "2e4cfcf7945c60d2dd5a704162e41262a4b92e9a5b3195289c3850d797f6c5dd"
},
"downloads": -1,
"filename": "torchview-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b077abad975dc842c3c99ba3732f1d9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25405,
"upload_time": "2023-01-24T03:17:46",
"upload_time_iso_8601": "2023-01-24T03:17:46.711479Z",
"url": "https://files.pythonhosted.org/packages/51/e4/b87459fac4f42110ecdac96c6d6a85101b97783adf01eef0c5463dee9b03/torchview-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e56133b3b958f23def706c37d2ae70648040b4d6bdaec524335dc9a388d869d",
"md5": "ad521d4930df58ece6e224024471e1cd",
"sha256": "677fb6435999669f922146488492f0d5184d99385f9014a5876f452e9d19f92a"
},
"downloads": -1,
"filename": "torchview-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "ad521d4930df58ece6e224024471e1cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25638,
"upload_time": "2023-01-24T03:17:48",
"upload_time_iso_8601": "2023-01-24T03:17:48.367480Z",
"url": "https://files.pythonhosted.org/packages/0e/56/133b3b958f23def706c37d2ae70648040b4d6bdaec524335dc9a388d869d/torchview-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-24 03:17:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "torchview"
}
JSON