{"id":19932358,"url":"https://github.com/amazon-science/co-with-gnns-example","last_synced_at":"2026-02-12T19:33:42.590Z","repository":{"id":37685125,"uuid":"434354687","full_name":"amazon-science/co-with-gnns-example","owner":"amazon-science","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-13T23:12:26.000Z","size":893,"stargazers_count":159,"open_issues_count":4,"forks_count":37,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-09T05:03:31.099Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/amazon-science.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"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}},"created_at":"2021-12-02T19:49:35.000Z","updated_at":"2025-09-05T11:32:44.000Z","dependencies_parsed_at":"2025-01-12T01:45:43.745Z","dependency_job_id":null,"html_url":"https://github.com/amazon-science/co-with-gnns-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/amazon-science/co-with-gnns-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fco-with-gnns-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fco-with-gnns-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fco-with-gnns-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fco-with-gnns-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amazon-science","download_url":"https://codeload.github.com/amazon-science/co-with-gnns-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-science%2Fco-with-gnns-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29378819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T19:05:20.189Z","status":"ssl_error","status_checked_at":"2026-02-12T19:01:44.216Z","response_time":55,"last_error":"SSL_read: 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":[],"created_at":"2024-11-12T23:09:55.197Z","updated_at":"2026-02-12T19:33:42.574Z","avatar_url":"https://github.com/amazon-science.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Combinatorial Optimization with Graph Neural Networks\n\n## Introduction\n\nCombinatorial optimization problems are pervasive across science and industry alike. Modern deep learning tools are \npoised to solve these problems at unprecedented scales, but a unifying framework that incorporates insights from \nstatistical physics is still outstanding. Here we demonstrate how graph neural networks can be used to solve \ncombinatorial optimization problems. Our approach is broadly applicable to canonical NP-hard problems in the form of \nquadratic unconstrained binary optimization problems, such as maximum cut, minimum vertex cover, maximum independent \nset, as well as Ising spin glasses and higher-order generalizations thereof in the form of polynomial unconstrained \nbinary optimization problems. We apply a relaxation strategy to the problem Hamiltonian to generate a differentiable \nloss function with which we train the graph neural network and apply a simple projection to integer variables once \nthe unsupervised training process has completed. We showcase our approach with numerical results for the canonical \nmaximum cut and maximum independent set problems. We find that the graph neural network optimizer performs on par \nor outperforms existing solvers, with the ability to scale beyond the state of the art to problems with millions \nof variables.\n\n## Method\n\n![PI-GNN Solver Flow](./media/fig3_flowchart_v2.png \"PI-GNN Solver Flow\")\n\nFlow chart illustrating the end-to-end workflow for the proposed physics-inspired GNN optimizer. (a), The problem \nis specified by a graph G with associated adjacency matrix A, and a cost function as described (for example) by the \nQUBO Hamiltonian HQUBO. Within the QUBO framework the cost function is fully captured by the QUBO matrix Q, as \nillustrated for both MaxCut and MIS for a sample (undirected) graph with five vertices and six edges. (b), The \nproblem setup is complemented by a training strategy that specifies the GNN Ansatz, a choice of hyperparameters \nand a specific ML optimizer. (c), The GNN is iteratively trained against a custom loss function LQUBO(θ) that \nencodes a relaxed version of the underlying optimization problem as specified by the cost function HQUBO. Typically, \na GNN layer operates by aggregating information within the local one-hop neighbourhood (as illustrated by the k = 1 \ncircle for the top node with label 0). By stacking layers one can extend the receptive field of each node, thereby \nallowing distant propagation of information (as illustrated by the k = 2 circle for the top node with label 0). \n(d)-(e), The GNN generates soft node assignments which can be viewed as class probabilities. Using some projection \nscheme, we then project the soft node assignments back to (hard) binary variables xi = 0, 1 (as indicated by the \nbinary black/white node coloring), providing the final solution bit string x.\n\n## Example code\n\nIn this notebook ([gnn_example.ipynb](gnn_example.ipynb)) we show how to solve combinatorial optimization problems \nwith physics-inspired graph neural networks, as outlined in M. J. A. Schuetz, J. K. Brubaker, H. G. Katzgraber,\n_Combinatorial Optimization with Physics-Inspired Graph Neural Networks_, \n[arXiv:2107.01188](https://arxiv.org/abs/2107.01188). Here we focus on the canonical maximum independent set \n(MIS) problem, but our approach can easily be extended to other combinatorial optimization problems. For the \nactual implementation of the graph neural network we use the open-source ```dgl``` library. \n\n## Environment Setup\n\nPlease note we have provided a `requirements.txt` file, which defines the environment required to run this code. \nBecause some of the packages are not available on default OSX conda channels, we have also provided suggested \nchannels to find them on. These can be distilled into a single line as such:\n\n\u003e conda create -n \u003cenvironment_name\u003e python=3.8 --file requirements.txt -c conda-forge -c dglteam -c pytorch\n\n**NOTE:** The contents of the requirements file are pegged to python version 3.8, and have been tested with \nversions 3.8.5 and 3.8.12. It's possible to use more recent python versions (3.9+), but the specified \nrequirements packages will likely have version conflicts, therefore we recommend sticking to python 3.8. \nEnvironment setup is expected to take a couple of minutes (2-5min), depending on package download speeds.\n\n## Code Execution\n\nOnce the virtual environment is established (see above), running the code is straightforward. From the parent folder, \nlaunch the notebook via \n\n\u003e conda activate \u003cenvironment_name\u003e\n\u003e jupyter notebook gnn_example.ipynb\n\nOnce in the notebook, run the cells via \n\n`Cell` \u003e `Run All` \n\nor \n\n`Kernel` \u003e `Restart \u0026 Run All`\n\n**NOTE:** On a standard laptop (e.g. a 2019 13\" MacBook Pro), the full notebook takes ~30-60 seconds to run. \nThis should not vary much across hardware, as the code is not parallelized and the problem instance and \nGNN model are small enough to fit in memory.\n\n### Key Hyperparameters\n\n`n` Problem size (e.g. graph size)\n\n`number_epochs` The maximum number of epochs to train the GNN model\n\n`learning_rate` Learning rate for the optimizer (Adam, AdamW, etc)\n\n`dim_embedding` Dimensionality of embedding vector, per input\n\n`hidden_dim` Size of intermediate hidden layer\n\n`dropout` Fraction of nodes to drop out in each layer\n\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License Summary\n\nThe documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file.\n\nThe sample code within this documentation is made available under the MIT-0 license. See the LICENSE-SAMPLECODE file.\n\n## Citation\n\n```\n@article{Schuetz2021,\n  title={Combinatorial Optimization with Physics-Inspired Graph Neural Networks},\n  author={Schuetz, Martin J A and Brubaker, J Kyle and Katzgraber, Helmut G},\n  journal={arXiv preprint arXiv:2107.01188},\n  year={2021}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Fco-with-gnns-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famazon-science%2Fco-with-gnns-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-science%2Fco-with-gnns-example/lists"}