{"id":32159231,"url":"https://github.com/smarttensors/nmfk.jl","last_synced_at":"2026-02-18T22:01:51.994Z","repository":{"id":37846883,"uuid":"324016187","full_name":"SmartTensors/NMFk.jl","owner":"SmartTensors","description":"Nonnegative Matrix Factorization + k-means clustering and physics constraints for Unsupervised and Physics-Informed Machine Learning","archived":false,"fork":false,"pushed_at":"2026-02-13T06:00:55.000Z","size":89105,"stargazers_count":17,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-02-13T12:59:36.241Z","etag":null,"topics":["blind-source-separation","feature-extraction","julia","machine-learning","physics-informed-learning","scientific-computing","scientific-machine-learning","source-identification","unsupervised-machine-learning"],"latest_commit_sha":null,"homepage":"https://smarttensors.github.io","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmartTensors.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-12-23T22:44:13.000Z","updated_at":"2026-02-13T06:00:58.000Z","dependencies_parsed_at":"2025-12-10T21:06:41.334Z","dependency_job_id":null,"html_url":"https://github.com/SmartTensors/NMFk.jl","commit_stats":{"total_commits":1052,"total_committers":8,"mean_commits":131.5,"dds":"0.011406844106463865","last_synced_commit":"77e69e4bde8341b1da9cabe64e044a04598fcda9"},"previous_names":[],"tags_count":163,"template":false,"template_full_name":null,"purl":"pkg:github/SmartTensors/NMFk.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartTensors%2FNMFk.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartTensors%2FNMFk.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartTensors%2FNMFk.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartTensors%2FNMFk.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmartTensors","download_url":"https://codeload.github.com/SmartTensors/NMFk.jl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartTensors%2FNMFk.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29596329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T20:59:56.587Z","status":"ssl_error","status_checked_at":"2026-02-18T20:58:41.434Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["blind-source-separation","feature-extraction","julia","machine-learning","physics-informed-learning","scientific-computing","scientific-machine-learning","source-identification","unsupervised-machine-learning"],"created_at":"2025-10-21T13:01:55.912Z","updated_at":"2026-02-18T22:01:51.989Z","avatar_url":"https://github.com/SmartTensors.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NMFk: Nonnegative Matrix Factorization + k-means clustering and physics constraints\n\n\u003cdiv style=\"text-align: left;\"\u003e\n    \u003cimg src=\"logo/nmfk-logo.jpg\" alt=\"nmfk\" width=50%  max-width=125px;/\u003e\n\u003c/div\u003e\n\n**NMFk** is a module of the **SmartTensors** ML framework ([smarttensors.com](https://smarttensors.com)).\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"logo/SmartTensorsNewSmall.png\" alt=\"SmartTensors\" width=25%  max-width=125px;/\u003e\n\u003c/div\u003e\n\n**NMFk** is a novel unsupervised machine learning methodology that allows for the automatic identification of the optimal number of features (signals/signatures) present in the data.\n\nClassical **NMF** approaches do not allow for automatic estimation of the number of features.\n\n**NMFk** estimates the number of features `k` through *k*-means clustering coupled with regularization constraints (sparsity, physical, mathematical, etc.).\n\n**SmartTensors** can be applied to perform:\n- Feature extraction (**FE**)\n- Blind source separation (**BSS**)\n- Detection of disruptions/anomalies\n- Data gap discovery\n- Data gap filling and reconstruction\n- Image recognition\n- Text mining\n- Data classification\n- Separation (deconstruction) of co-occurring (physics) processes\n- Discovery of unknown dependencies and phenomena\n- Development of reduced-order/surrogate models\n- Identification of dependencies between model inputs and outputs\n- Guiding the development of physics models representing the ML-analyzed data\n- Blind predictions\n- Optimization of data acquisition (optimal experimental design)\n- Labeling of datasets for supervised ML analyses\n\n**NMFk** provides high-performance computing capabilities to solve problems in parallel using Shared and Distributed Arrays.\nThe parallelization allows for the utilization of multi-core / multi-processor environments.\nGPU and TPU accelerations are available through existing Julia packages.\n\n**NMFk** provides advanced tools for data visualization, pre- and post-processing.\nThese tools substantially facilitate the utilization of the package in various real-world applications.\n\n**NMFk** methodology and applications are discussed in the research papers and presentations listed below.\n\n**NMFk** is demonstrated with a series of examples and test problems provided here.\n\n## Awards\n\n**SmartTensors** and **NMFk** were recently awarded:\n* 2021 R\u0026D100 Award: [Information Technologies (IT)](https://www.rdworldonline.com/2021-rd-100-award-winners-announced-in-analytical-test-and-it-electrical-categories)\n* 2021 R\u0026D100 Bronze Medal: [Market Disruptor in Services](https://www.rdworldonline.com/2021-rd-100-special-recognition-winners-announced)\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"logo/RD100Awards-300x300.png\" alt=\"R\u0026D100\" width=25%  max-width=125px;/\u003e\n\u003c/div\u003e\n\n## Installation\n\nAfter starting Julia, execute:\n\n```julia\nimport Pkg\nPkg.add(\"NMFk\")\n```\n\nto access the latest released version.\n\nTo utilize the latest code updates (commits), use:\n\n```julia\nimport Pkg\nPkg.add(Pkg.PackageSpec(name=\"NMFk\", rev=\"master\"))\n```\n\n## Docker\n\n```bash\ndocker run --interactive --tty montyvesselinov/tensors\n```\n\nThe docker image provides access to all **SmartTensors** packages ([smarttensors.github.io](https://smarttensors.github.io)).\n\n## Testing\n\n```julia\nimport Pkg\nPkg.test(\"NMFk\")\n```\n\n## Examples\n\nA simple problem demonstrating **NMFk** can be executed as follows.\nFirst, generate 3 random signals in a matrix `W`:\n\n```julia\na = rand(15)\nb = rand(15)\nc = rand(15)\nW = [a b c]\n```\n\nThen, mix the signals to produce a data matrix `X` of 5 sensors observing the mixed signals as follows:\n\n```julia\nX = [a+c*3 a*10+b b b*5+c a+b*2+c*5]\n```\n\nThis is equivalent to generating a mixing matrix `H` and obtaining `X` by multiplying `W` and `H`\n\n```julia\nH = [1 10 0 0 1; 0 1 1 5 2; 3 0 0 1 5]\nX = W * H\n```\n\nAfter that, execute **NMFk** to estimate the number of unknown mixed signals based only on the information in `X`.\n\n```julia\nimport NMFk\nWe, He, fitquality, robustness, aic, kopt = NMFk.execute(X, 2:5; save=false, method=:simple);\n```\n\nThe execution will produce output like this:\n\n```\n[ Info: Results\nSignals:  2 Fit:       15.489 Silhouette:    0.9980145 AIC:    -38.30184\nSignals:  3 Fit: 3.452203e-07 Silhouette:    0.8540085 AIC:    -1319.743\nSignals:  4 Fit: 8.503988e-07 Silhouette:   -0.5775127 AIC:    -1212.129\nSignals:  5 Fit: 2.598571e-05 Silhouette:   -0.6757581 AIC:    -915.6589\n[ Info: Optimal solution: 3 signals\n```\n\nThe code returns the estimated optimal number of signals `kopt`, which in this case, as expected, is equal to 3.\n\nThe code returns the `fitquality` and `robustness`; they can applied to represent how the solutions change with the increase of `k`:\n\n```julia\nNMFk.plot_signal_selecton(2:5, fitquality, robustness)\n```\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"images/signal_selection.png\" alt=\"signal_selection\" width=75%  max-width=200px;/\u003e\n\u003c/div\u003e\n\nThe code also returns estimates of matrices `W` and `H`.\n\nIt can be easily verified that estimated `We[kopt]` and `He[kopt]` are scaled versions of the original `W` and `H` matrices.\n\nNote that the order of columns ('signals') in `W` and  `We[kopt]` are not expected to match.\nThe order of rows ('sensors') in `H` and  `He[kopt]` are also not expected to match.\nThe estimated orders will be different every time the code is executed.\n\nThe matrices can be visualized using:\n\n```julia\nimport Pkg; Pkg.add(\"Mads\")\nimport Mads\nMads.plotseries([a b c])\nMads.plotseries(We[kopt] ./ maximum(We[kopt]))\n```\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"images/signals_original.png\" alt=\"signals_original\" width=75%  max-width=200px;/\u003e\n\u003c/div\u003e\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"images/signals_reconstructed.png\" alt=\"signals_reconstructed\" width=75%  max-width=200px;/\u003e\n\u003c/div\u003e\n\n```julia\nNMFk.plotmatrix(H)\nNMFk.plotmatrix(He[kopt] ./ maximum(He[kopt]))\n```\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"images/blind_source_separation_24_0.svg\" alt=\"signals_original\" width=50%  max-width=200px;/\u003e\n\u003c/div\u003e\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"images/blind_source_separation_25_0.svg\" alt=\"signals_reconstructed\" width=50%  max-width=200px;/\u003e\n\u003c/div\u003e\n\nMore examples can be found in the `test`, `demo`, `examples`, and `notebooks` directories of the **NMFk** repository.\n\n## Applications:\n\n**NMFk** has been applied in a wide range of real-world applications.\nThe analyzed datasets include model outputs, experimental laboratory data, and field tests:\n\n- Climate data and simulations\n- Watershed data and simulations\n- Aquifer simulations\n- Surface-water and Groundwater analyses\n- Material characterization\n- Reactive mixing\n- Molecular dynamics\n- Contaminant transport\n- Induced seismicity\n- Phase separation of co-polymers\n- Oil / Gas extraction from unconventional reservoirs\n- Geothermal exploration and production\n- Geologic carbon storage\n- Wildfires\n\n## Videos:\n\n- Progress of nonnegative matrix factorization process:\n\n\u003cdiv style=\"text-align: left\"\u003e\n    \u003cimg src=\"movies/m643.gif\" alt=\"nmfk-example\" width=75%  max-width=250px;/\u003e\n\u003c/div\u003e\n\nMore videos are available at [YouTube](https://www.youtube.com/playlist?list=PLpVcrIWNlP22LfyIu5MSZ7WHp7q0MNjsj)\n\n## Notebooks:\n\nA series of Jupyter notebooks demonstrating **NMFk** have been developed:\n* [Blind Source Separation](https://github.com/TensorDecompositions/NMFk.jl/blob/master/notebooks/blind_source_separation/blind_source_separation.ipynb)\n* [Feature Extraction)](https://github.com/TensorDecompositions/NMFk.jl/blob/master/notebooks/feature_extraction/feature_extraction.ipynb)\n* [Blind Prediction](https://github.com/TensorDecompositions/NMFk.jl/blob/master/notebooks/mapping_variables/mapping_variables.ipynb)\n* [Unmixing concentration data](https://github.com/TensorDecompositions/NMFk.jl/blob/master/notebooks/unmixing_groudwater/unmixing_groudwater.ipynb)\n\nThe notebooks can also be accessed using:\n\n```julia\nNMFk.notebooks()\n```\n\n## Other Examples:\n\n* [Machine Learning](https://madsjulia.github.io/Mads.jl/Examples/machine_learning/index.html)\n* [Blind Source Separation (i.e. Feature Extraction)](https://madsjulia.github.io/Mads.jl/Examples/blind_source_separation/index.html)\n* [Source Identification](https://madsjulia.github.io/Mads.jl/Examples/contaminant_source_identification/index.html)\n\n## Patent:\n\nAlexandrov, B.S., Vesselinov, V.V., Alexandrov, L.B., Stanev, V., Iliev, F.L., Source identification by non-negative matrix factorization combined with semi-supervised clustering, [US20180060758A1](https://patents.google.com/patent/US20180060758A1/en)\n\n## Publications:\n\n- Vesselinov, V.V., Mudunuru, M., Karra, S., O'Malley, D., Alexandrov, B.S., Unsupervised Machine Learning Based on Non-Negative Tensor Factorization for Analyzing Reactive-Mixing, 10.1016/j.jcp.2019.05.039, Journal of Computational Physics, 2019. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Vesselinov%20et%20al%202018%20Unsupervised%20Machine%20Learning%20Based%20on%20Non-Negative%20Tensor%20Factorization%20for%20Analyzing%20Reactive-Mixing.pdf)\n- Vesselinov, V.V., Alexandrov, B.S., O'Malley, D., Nonnegative Tensor Factorization for Contaminant Source Identification, Journal of Contaminant Hydrology, 10.1016/j.jconhyd.2018.11.010, 2018. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Vesselinov%20et%20al%202018%20Nonnegative%20Tensor%20Factorization%20for%20Contaminant%20Source%20Identification.pdf)\n- O'Malley, D., Vesselinov, V.V., Alexandrov, B.S., Alexandrov, L.B., Nonnegative/binary matrix factorization with a D-Wave quantum annealer, PlosOne, 10.1371/journal.pone.0206653, 2018. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/OMalley%20et%20al%202017%20Nonnegative:binary%20matrix%20factorization%20with%20a%20D-Wave%20quantum%20annealer.pdf)\n- Stanev, V., Vesselinov, V.V., Kusne, A.G., Antoszewski, G., Takeuchi, I., Alexandrov, B.A., Unsupervised Phase Mapping of X-ray Diffraction Data by Nonnegative Matrix Factorization Integrated with Custom Clustering, Nature Computational Materials, 10.1038/s41524-018-0099-2, 2018. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Stanev%20et%20al%202018%20Unsupervised%20phase%20mapping%20of%20X-ray%20diffraction%20data%20by%20nonnegative%20matrix%20factorization%20integrated%20with%20custom%20clustering.pdf)\n- Iliev, F.L., Stanev, V.G., Vesselinov, V.V., Alexandrov, B.S., Nonnegative Matrix Factorization for identification of unknown number of sources emitting delayed signals PLoS ONE, 10.1371/journal.pone.0193974. 2018. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Iliev%20et%20al%202018%20Nonnegative%20Matrix%20Factorization%20for%20identification%20of%20unknown%20number%20of%20sources%20emitting%20delayed%20signals.pdf)\n- Stanev, V.G., Iliev, F.L., Hansen, S.K., Vesselinov, V.V., Alexandrov, B.S., Identification of the release sources in advection-diffusion system by machine learning combined with Green function inverse method, Applied Mathematical Modelling, 10.1016/j.apm.2018.03.006, 2018. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Stanev%20et%20al%202018%20Identification%20of%20release%20sources%20in%20advection-diffusion%20system%20by%20machine%20learning%20combined%20with%20Green's%20function%20inverse%20method.pdf)\n- Vesselinov, V.V., O'Malley, D., Alexandrov, B.S., Contaminant source identification using semi-supervised machine learning, Journal of Contaminant Hydrology, 10.1016/j.jconhyd.2017.11.002, 2017. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Vesselinov%202017%20Contaminant%20source%20identification%20using%20semi-supervised%20machine%20learning.pdf)\n- Alexandrov, B., Vesselinov, V.V., Blind source separation for groundwater level analysis based on non-negative matrix factorization, Water Resources Research, 10.1002/2013WR015037, 2014. [PDF](https://gitlab.com/monty/monty.gitlab.io/raw/master/papers/Alexandrov%20\u0026%20Vesselinov%202014%20Blind%20source%20separation%20for%20groundwater%20pressure%20analysis%20based%20on%20nonnegative%20matrix%20factorization.pdf)\n\nResearch papers are also available at [Google Scholar](http://scholar.google.com/citations?user=sIFHVvwAAAAJ\u0026hl=en), [ResearchGate](https://www.researchgate.net/profile/Velimir_Vesselinov) and [Academia.edu](https://lanl.academia.edu/monty)\n\n## Presentations:\n\n- Vesselinov, V.V., Physics-Informed Machine Learning Methods for Data Analytics and Model Diagnostics, M3 NASA DRIVE Workshop, Los Alamos, 2019. [PDF](http://monty.gitlab.io/presentations/Vesselinov%202019%20Physics-Informed%20Machine%20Learning%20Methods%20for%20Data%20Analytics%20and%20Model%20Diagnostics.pdf)\n- Vesselinov, V.V., Unsupervised Machine Learning Methods for Feature Extraction, New Mexico Big Data \u0026amp; Analytics Summit, Albuquerque, 2019. [PDF](http://monty.gitlab.io/presentations/vesselinov%202019%20Unsupervised%20Machine%20Learning%20Methods%20for%20Feature%20Extraction%20LA-UR-19-21450.pdf)\n- Vesselinov, V.V., Novel Unsupervised Machine Learning Methods for Data Analytics and Model Diagnostics, Machine Learning in Solid Earth Geoscience, Santa Fe, 2019. [PDF](http://monty.gitlab.io/presentations/Vesselinov%202019%20GeoScienceMLworkshop.pdf)\n- Vesselinov, V.V., Novel Machine Learning Methods for Extraction of Features Characterizing Datasets and Models, AGU Fall meeting, Washington D.C., 2018. [PDF](http://monty.gitlab.io/presentations/Vesselinov%202018%20Novel%20Machine%20Learning%20Methods%20for%20Extraction%20of%20Features%20Characterizing%20Datasets%20and%20Models%20LA-UR-18-31366.pdf)\n- Vesselinov, V.V., Novel Machine Learning Methods for Extraction of Features Characterizing Complex Datasets and Models, Recent Advances in Machine Learning and Computational Methods for Geoscience, Institute for Mathematics and its Applications, University of Minnesota, 10.13140/RG.2.2.16024.03848, 2018. [PDF](http://monty.gitlab.io/presentations/Vesselinov%202018%20Novel%20Machine%20Learning%20Methods%20for%20Extraction%20of%20Features%20Characterizing%20Complex%20Datasets%20and%20Models%20LA-UR-18-30987.pdf)\n- Vesselinov, V.V., Mudunuru. M., Karra, S., O'Malley, D., Alexandrov, Unsupervised Machine Learning Based on Non-negative Tensor Factorization for Analysis of Filed Data and Simulation Outputs, Computational Methods in Water Resources (CMWR), Saint-Malo, France, 10.13140/RG.2.2.27777.92005, 2018. [PDF](http://monty.gitlab.io/presentations/vesselinov%20et%20al%202018%20Unsupervised%20Machine%20Learning%20Based%20on%20Non-negative%20Tensor%20Factorization%20for%20Analysis%20of%20Filed%20Data%20and%20Simulation%20Outputs%20cmwr-ML-20180606.pdf)\n- O'Malley, D., Vesselinov, V.V., Alexandrov, B.S., Alexandrov, L.B., Nonnegative/binary matrix factorization with a D-Wave quantum annealer [PDF](http://monty.gitlab.io/presentations/OMalley%20et%20al%202017%20Nonnegative%20binary%20matrix%20factorization%20with%20a%20D-Wave%20quantum%20annealer.pdf)\n- Vesselinov, V.V., Alexandrov, B.A, Model-free Source Identification, AGU Fall Meeting, San Francisco, CA, 2014. [PDF](http://monty.gitlab.io/presentations/vesselinov%20bss-agu2014-LA-UR-14-29163.pdf)\n\nPresentations are also available at [slideshare.net](https://www.slideshare.net/VelimirmontyVesselin), [ResearchGate](https://www.researchgate.net/profile/Velimir_Vesselinov) and [Academia.edu](https://lanl.academia.edu/monty)\n\n## Extra information\n\nFor more information, visit [monty.gitlab.io](http://monty.gitlab.io), [http://smarttensors.com](http://smarttensors.com) [smarttensors.github.io],(https://smarttensors.github.io), and [tensors.lanl.gov](http://tensors.lanl.gov).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarttensors%2Fnmfk.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmarttensors%2Fnmfk.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarttensors%2Fnmfk.jl/lists"}