[](https://pypi.python.org/pypi/ipyexperiments)
[](https://anaconda.org/stason/ipyexperiments)
[](https://anaconda.org/stason/ipyexperiments)
[](https://pypi.python.org/pypi/ipyexperiments)
[](https://pypi.python.org/pypi/ipyexperiments)
# ipyexperiments
Automatic GPU+CPU memory profiling, re-use and memory leaks detection using jupyter/ipython experiment containers.
## About
This module's main purpose is to help calibrate hyper parameters in deep learning notebooks to fit the available GPU and CPU memory, but, of course, it can be useful for any other use where CPU memory limits is a constant issue. It is also useful for detecting memory leaks in your code. And over time other goodies that help with running machine learning experiments have been added.
This package is slowly evolving into a suite of different helper modules that are designed to help diagnose issues with memory leakages and make the debug of these easy.
Currently the package contains several modules:
1. `IpyExperiments` - a smart container for ipython/jupyter experiments ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/ipyexperiments.md) / [demo](https://github.com/stas00/ipyexperiments/blob/master/demo.ipynb))
2. `CellLogger` - per cell memory profiler and more features ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/cell_logger.md) / [demo](https://github.com/stas00/ipyexperiments/blob/master/demo_cl.ipynb))
3. `ipython` utils - workarounds for ipython memory leakage on exception ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_ipython.md))
4. memory debugging and profiling utils ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_mem.md))
Using this framework you can run multiple consequent experiments without needing to restart the kernel all the time, especially when you run out of GPU memory - the familiar to all "cuda: out of memory" error. When this happens you just go back to the notebook cell where you started the experiment, change the hyper parameters, and re-run the updated experiment until it fits the available memory. This is much more efficient and less error-prone then constantly restarting the kernel, and re-running the whole notebook.
As an extra bonus you get access to the memory consumption data, so you can use it to automate the discovery of the hyper parameters to suit your hardware's unique memory limits.
The idea behind this module is very simple - it implements a python function-like functionality, where its local variables get destroyed at the end of its run, giving us memory back, except it'll work across multiple jupyter notebook cells (or ipython). In addition it also runs `gc.collect()` to immediately release badly behaved variables with circular references, and reclaim general and GPU RAM. It also helps to discover memory leaks, and performs various other useful things behind the scenes.
If you need a more fine-grained memory profiling, the `CellLogger` sub-system reports RAM usage on a per cell-level when used with jupyter or per line of code in ipython. You get the resource usage report automatically as soon as a command or a cell finished executing. It includes other features, such as resetting RNG seed in python/numpy/pytorch if you need a reproducible result when re-running the whole notebook or just one cell.
Currently this sub-system logs GPU RAM, general RAM and execution time. But it can be expanded to track other important things. While there are various similar loggers out there, the main focus of this implementation is to help track GPU, whose main scarce resource is GPU RAM.
## Installation
* pypi:
```
pip install ipyexperiments
```
* conda:
```
conda install -c conda-forge -c stason ipyexperiments
```
* dev:
```
pip install git+https://github.com/stas00/ipyexperiments.git
```
## Usage
Here is an example with using code from the [`fastai v1`](https://github.com/fastai/fastai) library, spread out through 8 jupyter notebook cells:
```
# cell 1
exp1 = IPyExperimentsPytorch() # new experiment
# cell 2
learn1 = language_model_learner(data_lm, bptt=60, drop_mult=0.25, pretrained_model=URLs.WT103)
# cell 3
learn1.lr_find()
# cell 4
del exp1
# cell 5
exp2 = IPyExperimentsPytorch() # new experiment
# cell 6
learn2 = language_model_learner(data_lm, bptt=70, drop_mult=0.3, pretrained_model=URLs.WT103)
# cell 7
learn2.lr_find()
# cell 8
del exp2
```
## Demo
See [this demo notebook](https://github.com/stas00/ipyexperiments/blob/master/demo.ipynb), to see how this system works.
## Documentation
1. [IPyExperiments](https://github.com/stas00/ipyexperiments/blob/master/docs/ipyexperiments.md)
2. [CellLogger sub-system](https://github.com/stas00/ipyexperiments/blob/master/docs/cell_logger.md)
3. [ipython utils](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_ipython.md)
4. [memory debug/profiling utils](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_mem.md)
## Contributing and Testing
Please see [CONTRIBUTING.md](https://github.com/stas00/ipyexperiments/blob/master/CONTRIBUTING.md).
## Caveats
### Google Colab
As of this writing colab runs [a really old version of ipython (5.5.0)](https://github.com/googlecolab/colabtools/issues/891#issuecomment-562427698) which doesn't support the modern ipython events API.
To solve this problem automatically so you never have to think about it again, always add this cell as the very first one in each colab notebook
```
# This magic cell should be put first in your colab notebook.
# It'll automatically upgrade colab's really antique ipython/ipykernel to their
# latest versions which are required for packages like ipyexperiments
from packaging import version
import IPython, ipykernel
if version.parse(IPython.__version__) <= version.parse("5.5.0"):
!pip install -q --upgrade ipython
!pip install -q --upgrade ipykernel
import os
import signal
os.kill(os.getpid(), signal.SIGTERM)
print(f"ipykernel=={ipykernel.__version__}")
print(f"IPython=={IPython.__version__}")
```
If you're on the default old ipykernel/ipython this cell will update it, then crash the current session. After the crash restart the execution and the code will work normally.
## History
A detailed history of changes can be found [here](https://github.com/stas00/ipyexperiments/blob/master/CHANGES.md).
## Related Projects
* https://github.com/Stonesjtu/pytorch_memlab - A simple and accurate CUDA memory management laboratory for pytorch.
(If you know of a related pytorch gpu memory profiler please send a PR to add the link. Thank you!)
Raw data
{
"_id": null,
"home_page": "https://github.com/stas00/ipyexperiments",
"name": "ipyexperiments",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "ipyexperiments,jupyter,ipython,memory,gpu,memory profiler",
"author": "Stas Bekman",
"author_email": "stas@stason.org",
"download_url": "https://files.pythonhosted.org/packages/c4/88/6770be152af2c48d51a798bdce3c39cd74417751082379829043f40d4b19/ipyexperiments-0.1.29.tar.gz",
"platform": null,
"description": "\n[](https://pypi.python.org/pypi/ipyexperiments)\n[](https://anaconda.org/stason/ipyexperiments)\n[](https://anaconda.org/stason/ipyexperiments)\n[](https://pypi.python.org/pypi/ipyexperiments)\n\n[](https://pypi.python.org/pypi/ipyexperiments)\n\n# ipyexperiments\n\nAutomatic GPU+CPU memory profiling, re-use and memory leaks detection using jupyter/ipython experiment containers.\n\n## About\n\nThis module's main purpose is to help calibrate hyper parameters in deep learning notebooks to fit the available GPU and CPU memory, but, of course, it can be useful for any other use where CPU memory limits is a constant issue. It is also useful for detecting memory leaks in your code. And over time other goodies that help with running machine learning experiments have been added.\n\nThis package is slowly evolving into a suite of different helper modules that are designed to help diagnose issues with memory leakages and make the debug of these easy.\n\nCurrently the package contains several modules:\n\n1. `IpyExperiments` - a smart container for ipython/jupyter experiments ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/ipyexperiments.md) / [demo](https://github.com/stas00/ipyexperiments/blob/master/demo.ipynb))\n2. `CellLogger` - per cell memory profiler and more features ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/cell_logger.md) / [demo](https://github.com/stas00/ipyexperiments/blob/master/demo_cl.ipynb))\n3. `ipython` utils - workarounds for ipython memory leakage on exception ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_ipython.md))\n4. memory debugging and profiling utils ([documentation](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_mem.md))\n\n\nUsing this framework you can run multiple consequent experiments without needing to restart the kernel all the time, especially when you run out of GPU memory - the familiar to all \"cuda: out of memory\" error. When this happens you just go back to the notebook cell where you started the experiment, change the hyper parameters, and re-run the updated experiment until it fits the available memory. This is much more efficient and less error-prone then constantly restarting the kernel, and re-running the whole notebook.\n\nAs an extra bonus you get access to the memory consumption data, so you can use it to automate the discovery of the hyper parameters to suit your hardware's unique memory limits.\n\nThe idea behind this module is very simple - it implements a python function-like functionality, where its local variables get destroyed at the end of its run, giving us memory back, except it'll work across multiple jupyter notebook cells (or ipython). In addition it also runs `gc.collect()` to immediately release badly behaved variables with circular references, and reclaim general and GPU RAM. It also helps to discover memory leaks, and performs various other useful things behind the scenes.\n\nIf you need a more fine-grained memory profiling, the `CellLogger` sub-system reports RAM usage on a per cell-level when used with jupyter or per line of code in ipython. You get the resource usage report automatically as soon as a command or a cell finished executing. It includes other features, such as resetting RNG seed in python/numpy/pytorch if you need a reproducible result when re-running the whole notebook or just one cell.\n\nCurrently this sub-system logs GPU RAM, general RAM and execution time. But it can be expanded to track other important things. While there are various similar loggers out there, the main focus of this implementation is to help track GPU, whose main scarce resource is GPU RAM.\n\n\n\n## Installation\n\n* pypi:\n\n ```\n pip install ipyexperiments\n ```\n* conda:\n\n ```\n conda install -c conda-forge -c stason ipyexperiments\n ```\n\n* dev:\n\n ```\n pip install git+https://github.com/stas00/ipyexperiments.git\n ```\n\n## Usage\n\nHere is an example with using code from the [`fastai v1`](https://github.com/fastai/fastai) library, spread out through 8 jupyter notebook cells:\n\n```\n# cell 1\nexp1 = IPyExperimentsPytorch() # new experiment\n# cell 2\nlearn1 = language_model_learner(data_lm, bptt=60, drop_mult=0.25, pretrained_model=URLs.WT103)\n# cell 3\nlearn1.lr_find()\n# cell 4\ndel exp1\n# cell 5\nexp2 = IPyExperimentsPytorch() # new experiment\n# cell 6\nlearn2 = language_model_learner(data_lm, bptt=70, drop_mult=0.3, pretrained_model=URLs.WT103)\n# cell 7\nlearn2.lr_find()\n# cell 8\ndel exp2\n```\n\n## Demo\n\nSee [this demo notebook](https://github.com/stas00/ipyexperiments/blob/master/demo.ipynb), to see how this system works.\n\n\n## Documentation\n\n1. [IPyExperiments](https://github.com/stas00/ipyexperiments/blob/master/docs/ipyexperiments.md)\n2. [CellLogger sub-system](https://github.com/stas00/ipyexperiments/blob/master/docs/cell_logger.md)\n3. [ipython utils](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_ipython.md)\n4. [memory debug/profiling utils](https://github.com/stas00/ipyexperiments/blob/master/docs/utils_mem.md)\n\n\n\n\n## Contributing and Testing\n\nPlease see [CONTRIBUTING.md](https://github.com/stas00/ipyexperiments/blob/master/CONTRIBUTING.md).\n\n## Caveats\n\n### Google Colab\n\nAs of this writing colab runs [a really old version of ipython (5.5.0)](https://github.com/googlecolab/colabtools/issues/891#issuecomment-562427698) which doesn't support the modern ipython events API.\n\nTo solve this problem automatically so you never have to think about it again, always add this cell as the very first one in each colab notebook\n\n```\n# This magic cell should be put first in your colab notebook.\n# It'll automatically upgrade colab's really antique ipython/ipykernel to their\n# latest versions which are required for packages like ipyexperiments\nfrom packaging import version\nimport IPython, ipykernel\nif version.parse(IPython.__version__) <= version.parse(\"5.5.0\"):\n !pip install -q --upgrade ipython\n !pip install -q --upgrade ipykernel\n\n import os\n import signal\n os.kill(os.getpid(), signal.SIGTERM)\nprint(f\"ipykernel=={ipykernel.__version__}\")\nprint(f\"IPython=={IPython.__version__}\")\n```\n\nIf you're on the default old ipykernel/ipython this cell will update it, then crash the current session. After the crash restart the execution and the code will work normally.\n\n\n## History\n\nA detailed history of changes can be found [here](https://github.com/stas00/ipyexperiments/blob/master/CHANGES.md).\n\n## Related Projects\n\n* https://github.com/Stonesjtu/pytorch_memlab - A simple and accurate CUDA memory management laboratory for pytorch.\n\n(If you know of a related pytorch gpu memory profiler please send a PR to add the link. Thank you!)\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "jupyter/ipython experiment containers for GPU+CPU memory profiling, re-use and memory leaks detection.",
"version": "0.1.29",
"project_urls": {
"Homepage": "https://github.com/stas00/ipyexperiments"
},
"split_keywords": [
"ipyexperiments",
"jupyter",
"ipython",
"memory",
"gpu",
"memory profiler"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc99ba9b3349c6c5a3d4896050f1a7b8916b1598b43eda4c95793541b0d4a487",
"md5": "733a4df9fcdd736e0aaa3be97615c0cf",
"sha256": "0eb1768930b0fc1d6498ede199bb618c1db6513c6bff4541768cb17365047c82"
},
"downloads": -1,
"filename": "ipyexperiments-0.1.29-py3-none-any.whl",
"has_sig": false,
"md5_digest": "733a4df9fcdd736e0aaa3be97615c0cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 17940,
"upload_time": "2023-12-15T03:21:06",
"upload_time_iso_8601": "2023-12-15T03:21:06.634728Z",
"url": "https://files.pythonhosted.org/packages/dc/99/ba9b3349c6c5a3d4896050f1a7b8916b1598b43eda4c95793541b0d4a487/ipyexperiments-0.1.29-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4886770be152af2c48d51a798bdce3c39cd74417751082379829043f40d4b19",
"md5": "ac6c945311b9384dfa1928ca33a2d47d",
"sha256": "b2241111e3d3cdb75b44c26fbf6499148c554380cdbeb055619e381b3c22f175"
},
"downloads": -1,
"filename": "ipyexperiments-0.1.29.tar.gz",
"has_sig": false,
"md5_digest": "ac6c945311b9384dfa1928ca33a2d47d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 72994,
"upload_time": "2023-12-15T03:21:09",
"upload_time_iso_8601": "2023-12-15T03:21:09.012913Z",
"url": "https://files.pythonhosted.org/packages/c4/88/6770be152af2c48d51a798bdce3c39cd74417751082379829043f40d4b19/ipyexperiments-0.1.29.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-15 03:21:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stas00",
"github_project": "ipyexperiments",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ipyexperiments"
}
JSON
