{"id":22668387,"url":"https://github.com/lanl/pyqbtns","last_synced_at":"2025-07-06T10:06:58.297Z","repository":{"id":43082631,"uuid":"372319581","full_name":"lanl/pyQBTNs","owner":"lanl","description":"Python Quantum Boolean Tensor Networks","archived":false,"fork":false,"pushed_at":"2022-07-17T16:52:38.000Z","size":7024,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-16T11:26:49.988Z","etag":null,"topics":["boolean-matrices","boolean-tensor","boolean-tucker-factorization","d-wave","factor-boolean-tensors","hierarchical-tucker","latent-factors","matrix-factorization","numpy","python","quantum-annealing","quantum-computing","tensor-decomposition","tensor-factorization","tensor-train","tucker-decomposition"],"latest_commit_sha":null,"homepage":"https://lanl.github.io/pyQBTNs/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-30T21:35:08.000Z","updated_at":"2023-11-27T20:11:20.000Z","dependencies_parsed_at":"2022-08-31T21:21:22.900Z","dependency_job_id":null,"html_url":"https://github.com/lanl/pyQBTNs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lanl/pyQBTNs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FpyQBTNs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FpyQBTNs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FpyQBTNs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FpyQBTNs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/pyQBTNs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FpyQBTNs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263882289,"owners_count":23524461,"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":["boolean-matrices","boolean-tensor","boolean-tucker-factorization","d-wave","factor-boolean-tensors","hierarchical-tucker","latent-factors","matrix-factorization","numpy","python","quantum-annealing","quantum-computing","tensor-decomposition","tensor-factorization","tensor-train","tucker-decomposition"],"created_at":"2024-12-09T15:14:56.073Z","updated_at":"2025-07-06T10:06:58.267Z","avatar_url":"https://github.com/lanl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyQBTNs - Python Quantum Boolean Tensor Networks\n\n\u003cdiv align=\"center\", style=\"font-size: 50px\"\u003e\n\n[![Build Status](https://github.com/lanl/pyQBTNs/actions/workflows/ci_tests.yml/badge.svg?branch=main)](https://github.com/lanl/pyCP_APR/actions/workflows/ci_tests.yml/badge.svg?branch=main) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg) [![Python Version](https://img.shields.io/badge/python-v3.7.3-blue)](https://img.shields.io/badge/python-v3.7.3-blue) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.4876527-blue.svg)](https://doi.org/10.5281/zenodo.4876527)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"324\" height=\"200\" src=\"docs/rd100.png\"\u003e\n\u003c/p\u003e\n\npyQBTNs is a Python library for boolean matrix and tensor factorization using D-Wave quantum annealers. The library includes five different boolean tensor decomposition methods making up three distinct types of tensor networks.\n\npyQBTNs allows the user to specify local solvers that do not require a connection to a quantum annealer, but still solve the optimization problems the quantum annealer would solve in the factorization algorithm. In order to use a D-Wave quantum annealer as the solver for this software, the user must set up a D-Wave configuration file. The tensor methods allow for multi-rank factorization, but the current implementation only allows single rank factorization (i.e. one rank used across the entire algorithm).\n\n\u003cdiv align=\"center\", style=\"font-size: 50px\"\u003e\n\n### [:information_source: Documentation](https://lanl.github.io/pyQBTNs/) \u0026emsp; [:orange_book: Examples](examples/) \u0026emsp; [:page_facing_up: Paper 1](https://arxiv.org/abs/2103.07399) \u0026emsp; [:page_facing_up: Paper 2](https://arxiv.org/abs/2107.13659)\n\n\u003c/div\u003e\n\n## Installation\n\n#### Option 1: Install using pip\n```shell\npip install git+https://github.com/lanl/pyQBTNs\n```\n#### Option 2: Install from source\n```shell\ngit clone https://github.com/lanl/pyQBTNs\ncd pyQBTNs\nconda create --name pyQBTNs python=3.9.7\nsource activate pyQBTNs\npython setup.py install\n```\n\n\n## Setup and Verify D-Wave connection\n1. Install [pyQBTNs](#installation).\n2. Sign up with [D-Wave Leap](https://cloud.dwavesys.com/leap/signup/).\n    - Make sure that you have at least 1 minute of QPU time on your free acccount.\n3. Set up [D-Wave config file](https://docs.ocean.dwavesys.com/en/stable/overview/sapi.html).\n    - You can use either an **Advantage** system or a **2000Q** system, but NOT a **Hybrid** solver. The Hybrid solvers are partially classical solvers, and do not exclusively use quantum annealing to solve optimization problems. \n4. Run an example:\n```shell\ncd tests\npython -m unittest TestMatrixFactorizationQuantum.py\n```\n**Note:** For more detailed description of the D-Wave setup process see the [tutorials](tutorials/) or the [example notebook on D-Wave](examples/D-Wave_matrix_factorization.ipynb). \n\n## Example Usage\n```python\n\n# Example Boolean Matrix Factorization\n\nfrom pyQBTNs import QBTNs\nimport numpy as np\n\nqbtns = QBTNs(factorization_method=\"Matrix_Factorization\", solver_method=\"classical-simulated-annealing\")\n\np = 0.7 ### Bernoulli boolean density parameter\nN1 = 10 ### Dimension 1\nN2 = 10 ### Dimension 2\nRANK = 3 ### Factorization rank\n\nnp.random.seed(42)\nA = np.random.choice(a=[False, True], size=(N1, RANK), p=[p, 1-p])\nA = np.array(A, dtype=bool)\nB = np.random.choice(a=[False, True], size=(RANK, N2), p=[p, 1-p])\nB = np.array(B, dtype=bool)\nX = np.matmul(A, B)\n\nprint(\"A =\", A)\nprint(\"B =\", B)\nprint(\"X =\", X)\n\nprint(\"X dimensions =\", X.shape)\n\nqbtns.fit(X, RANK)\n\nprint(\"Hamming distance =\", qbtns.get_score())\n\nA_prime, B_prime = qbtns.get_factors()\nprint(\"A_prime =\", A_prime)\nprint(\"B_prime =\", B_prime)\n\nprint(\"Reconstructed Matrix =\", qbtns.get_reconstructed_tensor())\n\n```\n\n## Prerequisites\n- [Anaconda](https://docs.anaconda.com/anaconda/install/)(Optional)\n- pyparsing==2.4.7\n- decorator==4.3.0\n- dwave-ocean-sdk\u003e=3.3.0\n- numpy\u003e=1.19.4\n- tensorly\u003e=0.4.5\n- networkx\u003e=2.5\n- nimfa\u003e=1.4.0\n- scikit-learn\u003e=0.24.1\n- matplotlib\u003e=3.4.2\n- Pillow\u003e=8.2.0\n- symengine\u003e=0.8.1\n\n## How to Cite pyQBTNs?\n```latex\n@MISC{Pelofske2021_pyQBTNs,\n    author = {E. {Pelofske} and H. {Djidjev} and D. {O'Malley} and M. E. {Eren} and B. S. {Alexandrov}},\n    title = {pyQBTNs},\n    year = {2021},\n    publisher = {GitHub},\n    journal = {GitHub repository},\n    doi = {10.5281/zenodo.4876527},\n    howpublished = {\\url{https://github.com/lanl/pyQBTNs}}\n}\n\n@inproceedings{pelofske2021boolean,\n  title={Boolean hierarchical tucker networks on quantum annealers},\n  author={Pelofske, Elijah and Hahn, Georg and O’Malley, Daniel and Djidjev, Hristo N and Alexandrov, Boian S},\n  booktitle={International Conference on Large-Scale Scientific Computing},\n  pages={351--358},\n  year={2021},\n  organization={Springer}\n}\n\n@article{pelofske2022quantum,\n  title={Quantum annealing algorithms for Boolean tensor networks},\n  author={Pelofske, Elijah and Hahn, Georg and O’Malley, Daniel and Djidjev, Hristo N and Alexandrov, Boian S},\n  journal={Scientific Reports},\n  volume={12},\n  number={1},\n  pages={1--19},\n  year={2022},\n  publisher={Nature Publishing Group}\n}\n```\n\n\n## Authors\n- [Elijah Pelofske](mailto:epelofske@lanl.gov): Information Sciences, Los Alamos National Laboratory\n- [Hristo Djidjev](mailto:hdjidjev@msn.com): Information Sciences, Los Alamos National Laboratory and Institute of Information and Communication Technologies, Sofia, Bulgaria\n- [Dan O'Malley](mailto:omalled@lanl.gov): Computational Earth Science, Los Alamos National Laboratory\n- [Maksim E. Eren](mailto:maksim@lanl.gov): Advanced Research in Cyber Systems, Los Alamos National Laboratory\n- [Boian S. Alexandrov](mailto:boian@lanl.gov): Theoretical Division, Los Alamos National Laboratory\n\n## Copyright Notice:\n© 2021. Triad National Security, LLC. All rights reserved.\nThis program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos\nNational Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S.\nDepartment of Energy/National Nuclear Security Administration. All rights in the program are\nreserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear\nSecurity Administration. The Government is granted for itself and others acting on its behalf a\nnonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare\nderivative works, distribute copies to the public, perform publicly and display publicly, and to permit\nothers to do so.\n\n**LANL C Number: C21027**\n\n## License:\nThis program is open source under the BSD-3 License.\nRedistribution and use in source and binary forms, with or without modification, are permitted\nprovided that the following conditions are met:\n1. Redistributions of source code must retain the above copyright notice, this list of conditions and\nthe following disclaimer.\n \n2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions\nand the following disclaimer in the documentation and/or other materials provided with the\ndistribution.\n \n3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse\nor promote products derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS\nIS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR\nPURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR\nCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,\nEXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,\nPROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;\nOR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,\nWHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR\nOTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF\nADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\n## References\n[1] D. O’Malley, H. N. Djidjev and B. S. Alexandrov, \"Tucker-1 Boolean Tensor Factorization with Quantum Annealers,\" 2020 International Conference on Rebooting Computing (ICRC), 2020, pp. 58-65, doi: 10.1109/ICRC2020.2020.00002.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fpyqbtns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fpyqbtns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fpyqbtns/lists"}