{"id":22058517,"url":"https://github.com/yoyolicoris/pytorch-nmf","last_synced_at":"2025-07-12T16:02:29.818Z","repository":{"id":46770336,"uuid":"155511966","full_name":"yoyolicoris/pytorch-NMF","owner":"yoyolicoris","description":"A pytorch package for non-negative matrix factorization.","archived":false,"fork":false,"pushed_at":"2024-07-25T11:13:41.000Z","size":5759,"stargazers_count":240,"open_issues_count":8,"forks_count":23,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-12T16:02:04.043Z","etag":null,"topics":["1d-convolution","beta-divergence","em-algorithm","gpu","kl-divergence","nmf","nonnegative-matrix-factorization","plca","pytorch","siplca"],"latest_commit_sha":null,"homepage":"https://pytorch-nmf.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yoyolicoris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"yoyololicon","custom":"PayPal.Me/iamycy"}},"created_at":"2018-10-31T06:50:21.000Z","updated_at":"2025-06-15T13:10:22.000Z","dependencies_parsed_at":"2024-06-19T22:46:19.062Z","dependency_job_id":"9e701477-ec16-4625-95db-308f60d3cb52","html_url":"https://github.com/yoyolicoris/pytorch-NMF","commit_stats":null,"previous_names":["yoyolicoris/pytorch-nmf","yoyololicon/pytorch-nmf"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/yoyolicoris/pytorch-NMF","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fpytorch-NMF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fpytorch-NMF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fpytorch-NMF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fpytorch-NMF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yoyolicoris","download_url":"https://codeload.github.com/yoyolicoris/pytorch-NMF/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fpytorch-NMF/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265016759,"owners_count":23698368,"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":["1d-convolution","beta-divergence","em-algorithm","gpu","kl-divergence","nmf","nonnegative-matrix-factorization","plca","pytorch","siplca"],"created_at":"2024-11-30T17:06:42.079Z","updated_at":"2025-07-12T16:02:29.770Z","avatar_url":"https://github.com/yoyolicoris.png","language":"Python","funding_links":["https://github.com/sponsors/yoyololicon","PayPal.Me/iamycy"],"categories":[],"sub_categories":[],"readme":"# Non-negative Matrix Fatorization in PyTorch\n\n[![build](https://github.com/yoyololicon/pytorch-NMF/actions/workflows/python-package.yml/badge.svg)](https://github.com/yoyololicon/pytorch-NMF/actions/workflows/python-package.yml)\n[![Upload Python Package](https://github.com/yoyololicon/pytorch-NMF/actions/workflows/python-publish.yml/badge.svg)](https://github.com/yoyololicon/pytorch-NMF/actions/workflows/python-publish.yml)\n[![codecov](https://codecov.io/gh/yoyololicon/pytorch-NMF/branch/master/graph/badge.svg?token=9UXAZ6PG2N)](https://codecov.io/gh/yoyololicon/pytorch-NMF)\n[![Documentation Status](https://readthedocs.org/projects/pytorch-nmf/badge/?version=latest)](https://pytorch-nmf.readthedocs.io/en/latest/?badge=latest)\n[![PyPI version](https://badge.fury.io/py/torchnmf.svg)](https://badge.fury.io/py/torchnmf)\n\nPyTorch is not only a good deep learning framework, but also a fast tool when it comes to matrix operations and convolutions on large data.\nA great example is [PyTorchWavelets](http://github.com/tomrunia/PyTorchWavelets).\n\n\nIn this package I implement NMF, PLCA and their deconvolutional variations in PyTorch based on `torch.nn.Module`, \nso the models can be moved freely among CPU/GPU devices and utilize parallel computation of cuda.\nWe also utilize the computational graph from `torch.autograd` to derive updated coefficients so the amount of codes is reduced and easy to maintain.\n\n# Modules\n\n## NMF\n\nBasic NMF and NMFD module minimizing beta-divergence using multiplicative update rules.\n\n\nThe interface is similar to `sklearn.decomposition.NMF` with some extra options.\n\n* `NMF`: Original NMF algorithm.\n* `NMFD`: 1-D deconvolutional NMF algorithm.\n* `NMF2D`: 2-D deconvolutional NMF algorithm. \n* `NMF3D`: 3-D deconvolutional NMF algorithm. \n\n## PLCA\n\nBasic PLCA and SIPLCA module using EM algorithm to minimize\nKL-divergence between the target distribution and the estimated\ndistribution.\n\n* `PLCA`: Original PLCA (Probabilistic Latent Component Analysis)\n  algorithm.\n* `SIPLCA`: Shift-Invariant PLCA algorithm (similar to NMFD).\n* `SIPLCA2`: 2-D deconvolutional SIPLCA algorithm.\n* `SIPLCA3`: 3-D deconvolutional SIPLCA algorithm.\n\n\n\n## Usage\n\nHere is a short example of decompose a spectrogram using deconvolutional NMF:\n\n```python\nimport torch\nimport librosa\nfrom torchnmf.nmf import NMFD\nfrom torchnmf.metrics import kl_div\n\ny, sr = librosa.load(librosa.util.example_audio_file())\ny = torch.from_numpy(y)\nwindowsize = 2048\nS = torch.stft(y, windowsize, \n               window=torch.hann_window(windowsize),\n               return_complex=True).abs().cuda()\nS = S.unsqueeze(0)\n\nR = 8   # number of components\nT = 400 # size of convolution window\n\nnet = NMFD(S.shape, rank=R, T=T).cuda()\n# run extremely fast on gpu\nnet.fit(S)      # fit to target matrix S\nV = net()\nprint(kl_div(V, S))        # KL divergence to S\n```\nA more detailed version can be found [here](examples/librosa_example.py). \nSee our [documentation](https://pytorch-nmf.readthedocs.io/en/latest/) to find out more usage of this package.\n\n![](examples/librosa_example.png)\n\n## Compare to sklearn\n\nThe barchart shows the time cost per iteration with different\nbeta-divergence. It shows that pytorch-based NMF has a much more constant process time across \ndifferent beta values, which can take advantage when beta is not 0, 1, or 2.\nThis is because our implementation use the same computational graph regardless which beta-divergence are we minimizing.\nIt runs even faster when computation is done on GPU. The test is conducted on a\nAcer E5 laptop with i5-7200U CPU and GTX 950M GPU.\n\n![](examples/performance.png) \n\n## Installation\n\n```\npip install torchnmf\n```\n\n## Requirements\n\n* PyTorch\n* tqdm\n\n## Tips\n\n* If you notice significant slow down when operating on CPU, please flush denormal numbers by `\ntorch.set_flush_denormal(True)`.\n\n\n## TODO\n\n- [x] Support sparse matrix target (only on `NMF` module).\n- [x] Regularization.\n- [ ] NNDSVD initialization.\n- [x] 2/3-D deconvolutional module.\n- [x] PLCA.\n- [x] Documentation.\n- [ ] ipynb examples.\n- [x] Refactor PLCA module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoyolicoris%2Fpytorch-nmf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoyolicoris%2Fpytorch-nmf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoyolicoris%2Fpytorch-nmf/lists"}