# NeuralCompression
[](https://github.com/facebookresearch/NeuralCompression/tree/main/LICENSE)
[](https://github.com/facebookresearch/NeuralCompression/actions/workflows/build-and-test.yml)
## What's New
- **August 2023 (image compression)** - [Released PyTorch implementation of MS-ILLM](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/illm)
- **April 2023 (video compression)** - [Released PyTorch implementation of VCT](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/torch_vct)
- **November 2022 (image compression)** - [Released Bits-Back coding with diffusion models](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/bits_back_diffusion)!
- **July 2021 (video compression)** - [Released implementation of DVC](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/deep_video_compression)
## About
NeuralCompression is a Python repository dedicated to research of neural
networks that compress data. The repository includes tools such as JAX-based
entropy coders, image compression models, video compression models, and metrics
for image and video evaluation.
NeuralCompression is alpha software. The project is under active development.
The API will change as we make releases, potentially breaking backwards
compatibility.
## Installation
NeuralCompression is a project currently under development. You can install the
repository in development mode.
### PyPI Installation
First, install PyTorch according to the directions from the
[PyTorch website](https://pytorch.org/). Then, you should be able to run
```bash
pip install neuralcompression
```
to get the latest version from PyPI.
### Development Installation
First, clone the repository and navigate to the NeuralCompression root
directory and install the package in development mode by running:
```bash
pip install --editable ".[tests]"
```
If you are not interested in matching the test environment, then you can just
apply `pip install -e .`.
## Repository Structure
We use a 2-tier repository structure. The `neuralcompression` package contains
a core set of tools for doing neural compression research. Code committed to
the core package requires stricter linting, high code quality, and rigorous
review. The `projects` folder contains code for reproducing papers and training
baselines. Code in this folder is not linted aggressively, we don't enforce
type annotations, and it's okay to omit unit tests.
The 2-tier structure enables rapid iteration and reproduction via code in
`projects` that is built on a backbone of high-quality code in
`neuralcompression`.
## neuralcompression
- `neuralcompression` - base package
- `data` - PyTorch data loaders for various data sets
- `distributions` - extensions of probability models for compression
- `functional` - methods for image warping, information cost, flop counting, etc.
- `layers` - building blocks for compression models
- `metrics` - `torchmetrics` classes for assessing model performance
- `models` - complete compression models
- `optim` - useful optimization utilities
## projects
- `projects` - recipes and code for reproducing papers
- `bits_back_diffusion` - code for bits-back coding with diffusion models
- `deep_video_compression` [DVC (Lu et al., 2019)](https://openaccess.thecvf.com/content_CVPR_2019/html/Lu_DVC_An_End-To-End_Deep_Video_Compression_Framework_CVPR_2019_paper.html), might soon be deprecated
- `illm` [MS-ILLM (Muckley et al., 2023)](https://proceedings.mlr.press/v202/muckley23a.html)
- `jax_entropy_coders` - implementations of arithmetic coding and ANS in JAX
- `torch_vct` [VCT (Mentzer, et al.,)](https://proceedings.neurips.cc/paper_files/paper/2022/hash/54dcf25318f9de5a7a01f0a4125c541e-Abstract-Conference.html)
## Tutorial Notebooks
This repository also features interactive notebooks detailing different
parts of the package, which can be found in the `tutorials` directory.
Existing tutorials are:
- Walkthrough of the `neuralcompression` flop counter ([view on Colab](https://colab.research.google.com/github/facebookresearch/NeuralCompression/blob/main/tutorials/Flop_Count_Example.ipynb)).
- Using `neuralcompression.metrics` and `torchmetrics` to calculate rate-distortion curves ([view on Colab](https://colab.research.google.com/github/facebookresearch/NeuralCompression/blob/main/tutorials/Metrics_Example.ipynb)).
## Contributions
Please read our [CONTRIBUTING](https://github.com/facebookresearch/NeuralCompression/tree/main/.github/CONTRIBUTING.md) guide and our
[CODE_OF_CONDUCT](https://github.com/facebookresearch/NeuralCompression/tree/main/.github/CODE_OF_CONDUCT.md) prior to submitting a pull
request.
We test all pull requests. We rely on this for reviews, so please make sure any
new code is tested. Tests for `neuralcompression` go in the `tests` folder in
the root of the repository. Tests for individual projects go in those projects'
own `tests` folder.
We use `black` for formatting, `isort` for import sorting, `flake8` for
linting, and `mypy` for type checking.
## License
NeuralCompression is MIT licensed, as found in the [LICENSE](https://github.com/facebookresearch/NeuralCompression/tree/main/LICENSE) file.
Model weights released with NeuralCompression are CC-BY-NC 4.0 licensed, as
found in the [WEIGHTS_LICENSE](https://github.com/facebookresearch/NeuralCompression/tree/main/WEIGHTS_LICENSE)
file.
Some of the code may from other repositories and include other licenses.
Please read all code files carefully for details.
## Cite
If you use code for a paper reimplementation. If you would like to also cite
the repository, you can use:
```bibtex
@misc{muckley2021neuralcompression,
author={Matthew Muckley and Jordan Juravsky and Daniel Severo and Mannat Singh and Quentin Duval and Karen Ullrich},
title={NeuralCompression},
howpublished={\url{https://github.com/facebookresearch/NeuralCompression}},
year={2021}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/facebookresearch/NeuralCompression",
"name": "neuralcompression",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "Facebook AI Research",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/26/e9/5751cea9c26972e7f339891bd73b975ac10c1753f0c0e1a43c101bac159c/neuralcompression-0.3.1.tar.gz",
"platform": null,
"description": "# NeuralCompression\n\n[](https://github.com/facebookresearch/NeuralCompression/tree/main/LICENSE)\n[](https://github.com/facebookresearch/NeuralCompression/actions/workflows/build-and-test.yml)\n\n## What's New\n- **August 2023 (image compression)** - [Released PyTorch implementation of MS-ILLM](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/illm)\n- **April 2023 (video compression)** - [Released PyTorch implementation of VCT](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/torch_vct)\n- **November 2022 (image compression)** - [Released Bits-Back coding with diffusion models](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/bits_back_diffusion)!\n- **July 2021 (video compression)** - [Released implementation of DVC](https://github.com/facebookresearch/NeuralCompression/tree/main/projects/deep_video_compression)\n\n## About\n\nNeuralCompression is a Python repository dedicated to research of neural\nnetworks that compress data. The repository includes tools such as JAX-based\nentropy coders, image compression models, video compression models, and metrics\nfor image and video evaluation.\n\nNeuralCompression is alpha software. The project is under active development.\nThe API will change as we make releases, potentially breaking backwards\ncompatibility.\n\n## Installation\n\nNeuralCompression is a project currently under development. You can install the\nrepository in development mode.\n\n### PyPI Installation\n\nFirst, install PyTorch according to the directions from the\n[PyTorch website](https://pytorch.org/). Then, you should be able to run\n\n```bash\npip install neuralcompression\n```\n\nto get the latest version from PyPI.\n\n### Development Installation\n\nFirst, clone the repository and navigate to the NeuralCompression root\ndirectory and install the package in development mode by running:\n\n```bash\npip install --editable \".[tests]\"\n```\n\nIf you are not interested in matching the test environment, then you can just\napply `pip install -e .`.\n\n## Repository Structure\n\nWe use a 2-tier repository structure. The `neuralcompression` package contains\na core set of tools for doing neural compression research. Code committed to\nthe core package requires stricter linting, high code quality, and rigorous\nreview. The `projects` folder contains code for reproducing papers and training\nbaselines. Code in this folder is not linted aggressively, we don't enforce\ntype annotations, and it's okay to omit unit tests.\n\nThe 2-tier structure enables rapid iteration and reproduction via code in\n`projects` that is built on a backbone of high-quality code in\n`neuralcompression`.\n\n## neuralcompression\n\n- `neuralcompression` - base package\n - `data` - PyTorch data loaders for various data sets\n - `distributions` - extensions of probability models for compression\n - `functional` - methods for image warping, information cost, flop counting, etc.\n - `layers` - building blocks for compression models\n - `metrics` - `torchmetrics` classes for assessing model performance\n - `models` - complete compression models\n - `optim` - useful optimization utilities\n\n## projects\n\n- `projects` - recipes and code for reproducing papers\n - `bits_back_diffusion` - code for bits-back coding with diffusion models\n - `deep_video_compression` [DVC (Lu et al., 2019)](https://openaccess.thecvf.com/content_CVPR_2019/html/Lu_DVC_An_End-To-End_Deep_Video_Compression_Framework_CVPR_2019_paper.html), might soon be deprecated\n - `illm` [MS-ILLM (Muckley et al., 2023)](https://proceedings.mlr.press/v202/muckley23a.html)\n - `jax_entropy_coders` - implementations of arithmetic coding and ANS in JAX\n - `torch_vct` [VCT (Mentzer, et al.,)](https://proceedings.neurips.cc/paper_files/paper/2022/hash/54dcf25318f9de5a7a01f0a4125c541e-Abstract-Conference.html)\n\n## Tutorial Notebooks\n\nThis repository also features interactive notebooks detailing different \nparts of the package, which can be found in the `tutorials` directory. \nExisting tutorials are:\n\n- Walkthrough of the `neuralcompression` flop counter ([view on Colab](https://colab.research.google.com/github/facebookresearch/NeuralCompression/blob/main/tutorials/Flop_Count_Example.ipynb)).\n- Using `neuralcompression.metrics` and `torchmetrics` to calculate rate-distortion curves ([view on Colab](https://colab.research.google.com/github/facebookresearch/NeuralCompression/blob/main/tutorials/Metrics_Example.ipynb)).\n\n## Contributions\n\nPlease read our [CONTRIBUTING](https://github.com/facebookresearch/NeuralCompression/tree/main/.github/CONTRIBUTING.md) guide and our\n[CODE_OF_CONDUCT](https://github.com/facebookresearch/NeuralCompression/tree/main/.github/CODE_OF_CONDUCT.md) prior to submitting a pull\nrequest.\n\nWe test all pull requests. We rely on this for reviews, so please make sure any\nnew code is tested. Tests for `neuralcompression` go in the `tests` folder in\nthe root of the repository. Tests for individual projects go in those projects'\nown `tests` folder.\n\nWe use `black` for formatting, `isort` for import sorting, `flake8` for\nlinting, and `mypy` for type checking.\n\n## License\n\nNeuralCompression is MIT licensed, as found in the [LICENSE](https://github.com/facebookresearch/NeuralCompression/tree/main/LICENSE) file.\n\nModel weights released with NeuralCompression are CC-BY-NC 4.0 licensed, as\nfound in the [WEIGHTS_LICENSE](https://github.com/facebookresearch/NeuralCompression/tree/main/WEIGHTS_LICENSE)\nfile.\n\nSome of the code may from other repositories and include other licenses.\nPlease read all code files carefully for details.\n\n## Cite\n\nIf you use code for a paper reimplementation. If you would like to also cite\nthe repository, you can use:\n\n```bibtex\n@misc{muckley2021neuralcompression,\n author={Matthew Muckley and Jordan Juravsky and Daniel Severo and Mannat Singh and Quentin Duval and Karen Ullrich},\n title={NeuralCompression},\n howpublished={\\url{https://github.com/facebookresearch/NeuralCompression}},\n year={2021}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A collection of tools for neural compression enthusiasts",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/facebookresearch/NeuralCompression"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5fd96699c87f8239b8d59a18ba04d1a99b525928ebf7d341bf15b0c4a524d17",
"md5": "4d833138487396608afc5a4c8fc12804",
"sha256": "830c97f711723c6e30b8a87f1a39d7d6c921928fb263ce50d989741d67f7e3ed"
},
"downloads": -1,
"filename": "neuralcompression-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d833138487396608afc5a4c8fc12804",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 107815,
"upload_time": "2023-10-03T14:26:28",
"upload_time_iso_8601": "2023-10-03T14:26:28.857729Z",
"url": "https://files.pythonhosted.org/packages/d5/fd/96699c87f8239b8d59a18ba04d1a99b525928ebf7d341bf15b0c4a524d17/neuralcompression-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26e95751cea9c26972e7f339891bd73b975ac10c1753f0c0e1a43c101bac159c",
"md5": "f627f6e43f87f6275667bb5641d25151",
"sha256": "447ba7e12dcf253fcebf44dd61dfd8451c06dd3a2884d42d096e9bddb7418535"
},
"downloads": -1,
"filename": "neuralcompression-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "f627f6e43f87f6275667bb5641d25151",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1569827,
"upload_time": "2023-10-03T14:26:30",
"upload_time_iso_8601": "2023-10-03T14:26:30.771793Z",
"url": "https://files.pythonhosted.org/packages/26/e9/5751cea9c26972e7f339891bd73b975ac10c1753f0c0e1a43c101bac159c/neuralcompression-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-03 14:26:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "facebookresearch",
"github_project": "NeuralCompression",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "neuralcompression"
}
JSON
