# Monitorch
A plug-and-use python module to monitor learning of PyTorch neural networks. Heavily inspired by [an article](https://ai.gopubby.com/better-ways-to-monitor-nns-while-training-7c246867ca4f) by Malcolm Lett. Provides easy to use interface to collect and display
- Loss and custom metrics
- Layer outputs (activation and norms)
- Gradients (norms, scalar products and activation)
- Neural Net's Parameters (norm)
Monitorch manages layer separation, data collection and vizualization with simple exposed methods and classes, so the code is concise and expressive without sacrificing informativness of the vizualizations and broad scope of its application. It also allows user to choose between static matplotlib and dynamic tensorboard plotting to help investigate both small models and keep track of large machines.
# Usage
## Requirments
- python>=3.10
- torch>=2.0.0
- matplotlib>=3.10.0
- tensorboard>=2.19.0
## Installation
Install the module using pip dependency manager.
```{bash}
pip install monitorch
```
## Code
Use `PyTorchInspector` from `monitorch.inspector` to hook your module and lenses (for example `LossMetrics` or `ParameterGradientGeometry`) from `monitorch.lens` to define vizualizations.
```{python}
import torch
from monitorch.inspector import PyTorchInspector
from monitorch.lens import LossMetrics, ParameterGradientGeometry
mynet = MyNeuralNet() # torch.nn.Module subclass
loss_fn = MSELoss()
optimizer = torch.optim.Adam(module.parameters())
inspector = PyTorchInspector(
lenses = [
LossMetrics(loss_fn=loss_fn),
ParameterGradientGeometry()
],
module = mynet,
vizualizer = "matplotlib"
)
for epoch in range(n_epochs):
# No changes to your training loop
# Passes through training and validation datasets remain the same
...
# at the end of an epoch inspector must be ticked
inspector.tick_epoch()
inspector.vizualizer.show_fig()
```
You can choose other vizualizers by passing `"tensorboard"`, `"print"` or an instance of vizualizer's class from `monitorch.vizualizers`. Note that matplotlib vizualier requires `show_fig()` call to plot.
Currently module supports gradient and parameter collection for arbitrary PyTorch module and output collection for single output architectures (feedforward, convolution, non-transformer autoencoders etc).
## Tests
Tests can be run with `pytest` from root project directory. Lens test have no assertions or other critical functionality tests, but are rather smoke tests to catch unhandled exceptions. To run functionality tests run `pytest -k "not smoke"`.
# TODO
- [ ] Documentation
- [ ] Setup sphinx
- [ ] Write docstrings
- [ ] Create demo notebooks
- [ ] Recurrent Neural Networks output collection
- [ ] Transformer output collection (value vector vs state vector)
- [ ] Debug Lens
Raw data
{
"_id": null,
"home_page": null,
"name": "monitorch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "pytorch, visualization, neural networks, gradients",
"author": null,
"author_email": "Maksym Khavil <mk.khavil@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ac/97/b235d2b66b189c828504418bc824986ebd24332905800050f8a5e558de76/monitorch-0.0.1.tar.gz",
"platform": null,
"description": "# Monitorch\n\nA plug-and-use python module to monitor learning of PyTorch neural networks. Heavily inspired by [an article](https://ai.gopubby.com/better-ways-to-monitor-nns-while-training-7c246867ca4f) by Malcolm Lett. Provides easy to use interface to collect and display\n\n- Loss and custom metrics\n- Layer outputs (activation and norms)\n- Gradients (norms, scalar products and activation)\n- Neural Net's Parameters (norm)\n\nMonitorch manages layer separation, data collection and vizualization with simple exposed methods and classes, so the code is concise and expressive without sacrificing informativness of the vizualizations and broad scope of its application. It also allows user to choose between static matplotlib and dynamic tensorboard plotting to help investigate both small models and keep track of large machines.\n\n# Usage\n\n## Requirments\n\n- python>=3.10\n- torch>=2.0.0\n- matplotlib>=3.10.0\n- tensorboard>=2.19.0\n\n## Installation\n\nInstall the module using pip dependency manager.\n\n```{bash}\npip install monitorch\n```\n\n## Code\n\nUse `PyTorchInspector` from `monitorch.inspector` to hook your module and lenses (for example `LossMetrics` or `ParameterGradientGeometry`) from `monitorch.lens` to define vizualizations.\n\n```{python}\nimport torch\n\nfrom monitorch.inspector import PyTorchInspector\nfrom monitorch.lens import LossMetrics, ParameterGradientGeometry\n\nmynet = MyNeuralNet() # torch.nn.Module subclass\nloss_fn = MSELoss()\noptimizer = torch.optim.Adam(module.parameters())\n\ninspector = PyTorchInspector(\n lenses = [\n LossMetrics(loss_fn=loss_fn),\n ParameterGradientGeometry()\n ],\n module = mynet,\n vizualizer = \"matplotlib\"\n)\n\nfor epoch in range(n_epochs):\n # No changes to your training loop\n # Passes through training and validation datasets remain the same\n\n ...\n\n # at the end of an epoch inspector must be ticked\n inspector.tick_epoch()\n\ninspector.vizualizer.show_fig()\n```\n\nYou can choose other vizualizers by passing `\"tensorboard\"`, `\"print\"` or an instance of vizualizer's class from `monitorch.vizualizers`. Note that matplotlib vizualier requires `show_fig()` call to plot.\n\nCurrently module supports gradient and parameter collection for arbitrary PyTorch module and output collection for single output architectures (feedforward, convolution, non-transformer autoencoders etc).\n\n\n## Tests\n\nTests can be run with `pytest` from root project directory. Lens test have no assertions or other critical functionality tests, but are rather smoke tests to catch unhandled exceptions. To run functionality tests run `pytest -k \"not smoke\"`.\n\n# TODO\n\n- [ ] Documentation\n - [ ] Setup sphinx\n - [ ] Write docstrings\n - [ ] Create demo notebooks\n- [ ] Recurrent Neural Networks output collection\n- [ ] Transformer output collection (value vector vs state vector)\n- [ ] Debug Lens\n",
"bugtrack_url": null,
"license": null,
"summary": "A plug-and-use python library to monitor learning of PyTorch neural networks",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/ZhigaMason/monitorch/issues",
"Homepage": "https://github.com/ZhigaMason/monitorch"
},
"split_keywords": [
"pytorch",
" visualization",
" neural networks",
" gradients"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0657b43bd041f64e18279ff6a74369907668f0f3e33a9172fd441449cd6be31d",
"md5": "6564bdcbe4a221ddfecf958cc7b3e3a4",
"sha256": "0264648379d2659bc3553d27af928c17bf42b648e5c3ccb45129e835177b2d93"
},
"downloads": -1,
"filename": "monitorch-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6564bdcbe4a221ddfecf958cc7b3e3a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 3777,
"upload_time": "2025-07-13T14:30:15",
"upload_time_iso_8601": "2025-07-13T14:30:15.080762Z",
"url": "https://files.pythonhosted.org/packages/06/57/b43bd041f64e18279ff6a74369907668f0f3e33a9172fd441449cd6be31d/monitorch-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ac97b235d2b66b189c828504418bc824986ebd24332905800050f8a5e558de76",
"md5": "1e705dd16d4d7903d856ffc192ac54bd",
"sha256": "ed3cd68ff5b4f665ff15144acc97fbe1c912a5ba0eb3c3ecff86be98edfe4a75"
},
"downloads": -1,
"filename": "monitorch-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1e705dd16d4d7903d856ffc192ac54bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3750,
"upload_time": "2025-07-13T14:30:16",
"upload_time_iso_8601": "2025-07-13T14:30:16.408786Z",
"url": "https://files.pythonhosted.org/packages/ac/97/b235d2b66b189c828504418bc824986ebd24332905800050f8a5e558de76/monitorch-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 14:30:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ZhigaMason",
"github_project": "monitorch",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "monitorch"
}
JSON
