{"id":20960267,"url":"https://github.com/instance01/qubo-nn","last_synced_at":"2025-05-14T07:30:37.046Z","repository":{"id":57459316,"uuid":"334716688","full_name":"instance01/qubo-nn","owner":"instance01","description":"Classifying, auto-encoding and reverse-engineering QUBO matrices","archived":false,"fork":false,"pushed_at":"2021-09-29T19:02:26.000Z","size":133179,"stargazers_count":52,"open_issues_count":0,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-25T10:44:27.405Z","etag":null,"topics":["paper-implementations","qc","quantum-annealing","quantum-computing","quantum-machine-learning","quantum-ml","quantum-neural-networks","qubo","qubo-matrix","qubo-ml","qubo-nn"],"latest_commit_sha":null,"homepage":"","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/instance01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-31T17:39:08.000Z","updated_at":"2025-03-20T21:05:55.000Z","dependencies_parsed_at":"2022-09-10T08:40:16.203Z","dependency_job_id":null,"html_url":"https://github.com/instance01/qubo-nn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instance01%2Fqubo-nn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instance01%2Fqubo-nn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instance01%2Fqubo-nn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instance01%2Fqubo-nn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instance01","download_url":"https://codeload.github.com/instance01/qubo-nn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254094721,"owners_count":22013630,"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":["paper-implementations","qc","quantum-annealing","quantum-computing","quantum-machine-learning","quantum-ml","quantum-neural-networks","qubo","qubo-matrix","qubo-ml","qubo-nn"],"created_at":"2024-11-19T01:58:12.988Z","updated_at":"2025-05-14T07:30:32.028Z","avatar_url":"https://github.com/instance01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## QUBO - NN\n\n\u003cimg alt=\"qubo heat map\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/qubo_map_singles.png\"\u003e\n\u003cp align=\"center\"\u003e\n  9 problems and their respective QUBO matrices.\n\u003c/p\u003e\n\nQUBO matrices are used to describe an optimization problem as a matrix such that a Quantum Annealer (such as a D-Wave QA) can solve it.\n\nNow, these matrices are quite an interesting construct.. Thus, a few questions arise:\n\n* Is it possible to classify the problem class based on the QUBO matrix?\n* Is it possible to reverse-engineer the problem parameters that led to a QUBO matrix?\n\nLet's find out.\n\n```\npip install qubo-nn\n```\n\n## Project Structure\n\n|File|Purpose|\n|----|-------|\n|datasets/|Contains generated datasets.|\n|models/|Contains trained models.|\n|nn/|Contains neural network models.|\n|plots/|Contains plotting scripts and generated plots.|\n|problems/|Contains generators and evaluators for specific problems such as 3SAT or TSP.|\n|runs/|Contains tensorboard logging files.|\n|config.py|Configuration (json) handling.|\n|data.py|LMDB data handling.|\n|main.py|Main entry point.|\n|pipeline.py|End to end training and testing of NNs on QUBO matrices.|\n|simulations.json|All experiments and configurations.|\n\nProblems (20) implemented so far:\n\n* Number Partitioning\n* Maximum Cut\n* Minimum Vertex Cover\n* Set Packing\n* Maximum 2-SAT\n* Set Partitioning\n* Graph Coloring\n* Quadratic Assignment\n* Quadratic Knapsack\n* Maximum 3-SAT\n* Travelling Salesman (TSP)\n* Graph Isomorphism\n* Sub-Graph Isomorphism\n* Maximum Clique\n* Exact Cover\n* Binary Integer Linear Programming\n* Maximum Independent Set\n* Minimum Maximum Matching\n* Set Cover\n* Knapsack with Integer Weights\n\n## Setup\n\n```\npip install qubo-nn\n```\n\nOR\n\n```\npip3 install -r requirements.txt\npip3 install -e .\n```\n\n## Using\n\n### Classification / Reverse regression\n\n```\nusage: main.py [-h] [-t TYPE] [--eval] [--gendata] [--train] [-c CFG_ID] [-m [MODEL]] [-n [NRUNS]]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -t TYPE, --type TYPE  Type (classify, reverse)\n  --eval\n  --gendata\n  --train\n  -c CFG_ID, --cfg_id CFG_ID\n                        cfg_id\n  -m [MODEL], --model [MODEL]\n  -n [NRUNS], --nruns [NRUNS]\n```\n\nExamples for classification:\n```\npython3 -m qubo_nn.main -t classify -c 2 --train\npython3 -m qubo_nn.main -t classify -c 2 --eval -m models/21-02-16_20\\:28\\:42-9893713-instances-MacBook-Pro.local-2 \n```\n\nExamples for reverse regression:\n```\npython3 -m qubo_nn.main -t reverse -c tsp1 --gendata\npython3 -m qubo_nn.main -t reverse -c tsp1 --train -n 1\n```\n\n### Generating QUBOs for arbitrary problems\n\nThis is an example on how to create a MaxCut instance and generate a QUBO matrix for it:\n\n```\n\u003e\u003e\u003e graph = networkx.Graph([(1, 2), (1, 3), (2, 4), (3, 4), (4, 5), (3, 5)])\n\u003e\u003e\u003e problem = MaxCut(graph)\n\u003e\u003e\u003e matrix = problem.gen_qubo_matrix()\n[\n    [2, -1, -1, 0, 0],\n    [-1, 2, 0, -1, 0],\n    [-1, 0, 3, -1, -1],\n    [0, -1, -1, 3, -1],\n    [0, 0, -1, -1, 2]\n]\n```\n\nThe list of problems can be found in `qubo_nn/problems/__init__.py`. Also:\n\n```\n\u003e\u003e\u003e from qubo_nn.problems import PROBLEM_REGISTRY\n\u003e\u003e\u003e PROBLEM_REGISTRY\n{\n    'NP': \u003cclass 'qubo_nn.problems.number_partitioning.NumberPartitioning'\u003e,\n    'MC': \u003cclass 'qubo_nn.problems.max_cut.MaxCut'\u003e,\n    'MVC': \u003cclass 'qubo_nn.problems.minimum_vertex_cover.MinimumVertexCover'\u003e,\n    'SP': \u003cclass 'qubo_nn.problems.set_packing.SetPacking'\u003e,\n    'M2SAT': \u003cclass 'qubo_nn.problems.max2sat.Max2SAT'\u003e,\n    'SPP': \u003cclass 'qubo_nn.problems.set_partitioning.SetPartitioning'\u003e,\n    'GC': \u003cclass 'qubo_nn.problems.graph_coloring.GraphColoring'\u003e,\n    'QA': \u003cclass 'qubo_nn.problems.quadratic_assignment.QuadraticAssignment'\u003e,\n    'QK': \u003cclass 'qubo_nn.problems.quadratic_knapsack.QuadraticKnapsack'\u003e,\n    'M3SAT': \u003cclass 'qubo_nn.problems.max3sat.Max3SAT'\u003e,\n    'TSP': \u003cclass 'qubo_nn.problems.tsp.TSP'\u003e,\n    'GI': \u003cclass 'qubo_nn.problems.graph_isomorphism.GraphIsomorphism'\u003e,\n    'SGI': \u003cclass 'qubo_nn.problems.subgraph_isomorphism.SubGraphIsomorphism'\u003e,\n    'MCQ': \u003cclass 'qubo_nn.problems.max_clique.MaxClique'\u003e,\n    'EC': \u003cclass 'qubo_nn.problems.exact_cover.ExactCover'\u003e,\n    'BIP': \u003cclass 'qubo_nn.problems.binary_integer_linear_programming.BinaryIntegerLinearProgramming'\u003e,\n    'MIS': \u003cclass 'qubo_nn.problems.max_independent_set.MaxIndependentSet'\u003e,\n    'MMM': \u003cclass 'qubo_nn.problems.minimum_maximum_matching.MinimumMaximumMatching'\u003e,\n    'SC': \u003cclass 'qubo_nn.problems.set_cover.SetCover'\u003e,\n    'KIW': \u003cclass 'qubo_nn.problems.knapsack_integer_weights.KnapsackIntegerWeights'\u003e\n    ...\n}\n```\n\n## Results\n\nThe pipeline of interest is as follows.\n\n\u003cimg alt=\"Reverse-engineering pipeline/architecture.\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/architecture.png\"\u003e\n\nGiven some QUBO matrix that was generated using a set of problem parameters, we first classify the problem in step a and then predict the parameters in step b.\n\n### Classification\n\nUsing parameter configuration `100_genX` (see `simulations.json`), the average\ntotal misclassification rate over 20 models goes to near zero. The figure\nincludes the 95% confidence interval. Scrambling QUBOs leads to a nearly\nsimilar effect. Note that this is using a generalized dataset, i.e. the dataset\nconsists of not just 64x64 QUBO matrices for each problem, but also smaller\nsizes such as 32x32. The smaller sizes are zero-padded to the biggest supported\nsize, which most of the time is 64x64 and in rare cases goes up to 144x144 (for\nQuadratic Assignment).\n\n\u003cimg alt=\"Avg total misclassification rate\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/tot_mc_100_genX_100_genX.png\"\u003e\n\nThe t-SNE plot for this experiment is shown below.\n\n\u003cimg alt=\"t-SNE\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/tsne_100_genX_10.png\"\u003e\n\n### Reverse regression\n\nThis is preliminary. Some of the problems are easily learned by a neural network regressor. Each line represents 10 models and includes the 95% confidence interval.\n\n\u003cimg alt=\"Reversal regression losses over multiple problems\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/reverse_loss.png\"\u003e\n\n\u003cimg alt=\"Reversal regression R**2 over multiple problems\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/reverse_r2.png\"\u003e\n\n### Reversibility\n\nThis shows whether we can deduce the parameters that led to a QUBO matrix, given we predicted the problem beforehand.\nA lot of the graph based problems are easily reversable since the graph structure is kept intact in the QUBO matrix. Thus we can recreate the graph and other input parameters given a GraphColoring QUBO matrix.\n\nThis is still WIP - needs testing. These are hypotheses.\n\nReversing some problems like Quadratic Knapsack might be possible - an algorithm is an idea, but one could also make their life easy and try fitting a NN model to it.\n\n|Problem|Reversibility|Comment|\n|-------|-------------|-------|\n|Graph Coloring|**+**|Adjacency matrix found in QUBO.|\n|Maximum 2-SAT|**?**|Very complex to learn, but possible? C.f. `m2sat_to_bip.py` in `contrib`.|\n|Maximum 3-SAT|**?**|Very complex to learn, but possible?|\n|Maximum Cut|**+**|Adjacency matrix found in QUBO.|\n|Minimum Vertex Cover|**+**|Adjacency matrix found in QUBO.|\n|Number Partitioning|**+**|Easy, create equation system from the upper triangular part of the matrix (triu).|\n|Quadratic Assignment|**+**|Over-determined linear system of equations -\u003e solvable. P does not act as salt. A bit complex to learn.|\n|Quadratic Knapsack|**-**|Budgets can be deduced easily (Find argmin in first row. This column contains all the budgets.). P acts as a salt -\u003e thus not reversible.|\n|Set Packing|**-**|Multiple problem instances lead to the same QUBO.|\n|Set Partitioning|**-**|Multiple problem instances lead to the same QUBO.|\n|Travelling Salesman|**+**|Find a quadrant with non-zero entries (w/ an identical diagonal), transpose, the entries are the distance matrix. Norm result to between 0 and 1.|\n|Graph Isomorphism|**+**|Adjacency matrix found in QUBO.|\n|Sub-Graph Isomorphism|**+**|Adjacency matrix found in QUBO.|\n|Maximum Clique|**+**|Adjacency matrix found in QUBO.|\n|Exact Cover|**?**|Not investigated.|\n|Binary Integer Linear Programming|**?**|Not investigated.|\n|Maximum Independent Set|**?**|Not investigated.|\n|Minimum Maximum Matching|**?**|Not investigated.|\n|Set Cover|**?**|Not investigated.|\n|Knapsack with Integer Weights|**?**|Not investigated.|\n\n### Redundancy of QUBOs with AutoEncoders \n\nThe figure below shows that there are major differences between problem classes\nin terms of their overall redundancy.\n\n\u003cimg alt=\"Redundacy of QUBos with AutoEncoders, R**2\" src=\"https://raw.githubusercontent.com/instance01/qubo-nn/master/qubo_nn/plots/red_ae_all_matrix.png\"\u003e\n\n## Contributing\n\nPull requests are very welcome. Before submitting one, run all tests with `./test.sh` and make sure nothing is broken.\n\n## References\n\n```\nGlover, Fred, Gary Kochenberger, and Yu Du. \"A tutorial on formulating and using qubo models.\" arXiv preprint arXiv:1811.11538 (2018).\nMichael J. Dinneen, \"Maximum 3-SAT as QUBO\" https://canvas.auckland.ac.nz/courses/14782/files/574983/download?verifier=1xqRikUjTEBwm8PnObD8YVmKdeEhZ9Ui8axW8HwP\u0026wrap=1\nLucas, Andrew. \"Ising formulation of many NP-problems. Frontiers in Physics\" (2014)\nCristian S. Calude, Michael J. Dinneen and Richard Hua. \"QUBO Formulations for the Graph Isomorphism Problem and Related Problems\" (2017)\n```\n\n## Related Work / Blog Posts\n\n[Hadamard Gate Transformation for 3 or more QuBits](https://blog.xa0.de/post/Hadamard-Gate-Transformation-for-3-or-more-QuBits/)\n\n[QUBOs for TSP and Maximum-3SAT](https://blog.xa0.de/post/QUBOs-for-TSP-and-Maximum---3SAT/)\n\n[QUBO-NN - Reverse-Engineering QUBO matrices](https://blog.xa0.de/post/QUBO-NN%20---%20Reverse-Engineering-QUBO-matrices/)\n\n[A note on Adiabatic Evolution in Quantum Annealing](https://blog.xa0.de/post/A-note-on-Adiabatic-Evolution-in-Quantum-Annealing/)\n\n[Quantum Annealing Hamiltonian Example Calculation](https://blog.xa0.de/post/Quantum-Annealing-Hamiltonian-Example-Calculation/)\n\n[List of QUBO formulations (80)](https://blog.xa0.de/post/List-of-QUBO-formulations/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstance01%2Fqubo-nn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstance01%2Fqubo-nn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstance01%2Fqubo-nn/lists"}