ThinkMatch puts twelve graph matching methods under one benchmark harness

Three purposes, and they are not the same purpose

The README states the repository's purposes as a list of three, and separating them is the fastest way to understand what kind of project this is.

The first is providing modules for developing deep graph matching algorithms to facilitate future research. The second is providing implementation of state-of-the-art deep graph matching methods. The third is benchmarking existing deep graph matching algorithms under different dataset and experiment settings, for the purpose of fair comparison.

The third one is the interesting commitment, and it is the one that shapes the repository. A comparison of two graph matching methods is only meaningful if the data, the split, the training schedule and the evaluation are the same for both, and a codebase that keeps the implementations in one tree with one training script is the way to make that hold. A method added later runs through the same harness as a method added earlier.

The maintainers are named too: ThinkMatch is developed and maintained by ThinkLab at Shanghai Jiao Tong University, with the laboratory site at thinklab.sjtu.edu.cn, and the official documentation at thinkmatch.readthedocs.io.

So the repository is three things at once: a toolbox, a set of paper implementations, and a measurement apparatus. An adopter who only wants one of them will find far more in the tree than they need, and the question of which one they need decides which files they should be reading.

The problem is the quadratic assignment problem

The introduction section explains the underlying problem, and the explanation is short enough to be worth quoting rather than paraphrasing.

Graph matching is described as a fundamental yet challenging problem in computer vision, pattern recognition and data mining. It aims to find node-to-node correspondence among multiple graphs, by solving an NP-hard combinatorial problem named the Quadratic Assignment Problem. Recently, there is growing interest in developing deep learning based graph matching methods.

The NP-hardness is the reason the field looks the way it does. If assigning nodes of one graph to nodes of another were tractable, there would be no need for the learned methods at all. The whole point of a neural graph matcher is to learn something that lets you avoid solving the general combinatorial problem exactly, and the different methods in this repository differ in what they learn and what they relax.

The applications listed give a sense of the reach. There is bridging movie and synopses, where a film and its plot summary are matched as graphs. There is image correspondence, illustrated with the SuperGlue work. There is molecules matching, from a combinatorial learning of graph edit distance paper. And more.

But the repository says it mainly focuses on image keypoint matching because it is a popular testbed for existing graph matching methods. That scoping decision is what makes the benchmarking possible at all. Image keypoints give a dataset with a known ground truth correspondence, a fixed size range and a single well-defined metric, which is exactly what a fair comparison needs, and it is why this repository is useful even if your own application is molecule matching or film and synopsis alignment.

Twelve methods, from 2018 to 2023

The model list is the substance of the repository, and each entry is a paper with its own directory under models.

GMN is Andrei Zanfir and Cristian Sminchisescu's Deep Learning of Graph Matching from CVPR 2018. PCA-GM and IPCA-GM cover two papers by Runzhong Wang, Junchi Yan and Xiaokang Yang, the embedding-based approach from TPAMI 2020 and the combinatorial embedding networks from ICCV 2019. NGM and NGM-v2 are the Neural Graph Matching Network work from TPAMI 2021, which learns Lawler's quadratic assignment problem with extension to hypergraph and multiple-graph matching. CIE-H is the channel-independent embedding and Hungarian attention paper from ICLR 2020.

GANN covers two papers, graduated assignment for joint multi-graph matching and clustering from NeurIPS 2020, and unsupervised learning of graph matching with a mixture of modes via discrepancy minimization from TPAMI 2023. BBGM is the blackbox differentiation of combinatorial solvers paper from ECCV 2020, which is notable for treating the solver as differentiable rather than replacing it. GCAN is the graph-context attention networks work for size-varied matching from CVPR 2022.

Then there are the more recent ones. AFAT is deep learning of partial graph matching via differentiable top-k from CVPR 2023, which is a different problem again since the graphs need not correspond in full. LinSAT is the positive linear satisfiability neural networks paper from ICML 2023. And COMMON and COMMON+ cover the bi-level noisy graph matching work.

The span from 2018 to 2023 is itself informative, because the middle of that range is where the field moved from single-graph correspondence towards multiple and partial graph matching, and the directory names reflect that shift: NGM explicitly extends to hypergraph and multiple-graph matching, and GANN handles joint multi-graph matching and clustering.

For a reader, the survey cited in the README is the entry point. Readers are referred to a short survey of recent advances in graph matching by Junchi Yan, Xu-Cheng Yin, Weiyao Lin, Cheng Deng, Hongyuan Zha and Xiaokang Yang at ICMR 2016, and the README positions the implementations as things to be read against that survey.

The repository is scripts plus model directories

The top-level layout is small and tells you where the work happens.

There are four Python entry points at the root: eval.py, eval_qap.py, train_eval.py and train_eval_qap.py. The naming pattern is the useful part. A train and evaluate script, and a separate evaluate script, in two flavours, plain and QAP. The QAP variants exist because the quadratic assignment problem is the underlying combinatorial problem, and evaluating a method on a QAP instance rather than on an image keypoint task is a different measurement.

The models directory holds one directory per method, matching the model names in the README. The src directory holds the shared code: the modules the README talks about providing, which is where the data loading, the training loop and the common network pieces live. There is an experiments directory for configuration and result definitions, a data directory for the datasets, a docs directory for the documentation, and CITATION.cff at the root for citation metadata.

The documentation is published on ReadTheDocs with a status badge, and the repository also publishes a Docker image on Docker Hub, under the runzhongwang/thinkmatch name, with a pull count badge. A container image for a research code base is a slightly unusual choice, and it makes sense for this project, because the dependencies for the frameworks these methods are built on are heavy, and a fixed image removes the difference between a reproduction that runs and one that fails on a version mismatch.

The two top-level scripts that a newcomer should look at first are train_eval.py and eval.py, because they are the entry points to the shared harness. Which of the four you want depends on whether you are working in the image keypoint testbed or on a quadratic assignment instance.

Getting the code, the image and the documentation

There is no install command in this repository, and the reason is worth stating plainly: what you need is not a package but a research environment with a specific set of deep learning dependencies, and the project has chosen to offer that in two forms.

The first is the source, and the entry point is the four scripts at the root of the tree. For the image keypoint testbed you would use train_eval.py to train and evaluate a model and eval.py to evaluate an existing one, and for a quadratic assignment instance the pair train_eval_qap.py and eval_qap.py. The models directory holds one directory per method, so pointing the script at a method directory is the whole of the selection step. The data directory holds the datasets and the experiments directory holds the configurations.

The second is the container. The project publishes a Docker image on Docker Hub under the runzhongwang/thinkmatch name, and the README carries badges for the available images and the pull count, so the image tags are the thing to check when you want a specific set of dependencies rather than whatever your machine has. The docker directory in the repository is where that image is defined, which means you can also build it yourself and see exactly what went in.

The documentation is the third piece, and the README says official documentation is at thinkmatch.readthedocs.io, with the status badge pointing at the same site. The wiki-style documentation is where the per-method details live, and the README is careful to point at the repository for the source code and at the documentation site rather than trying to hold the method descriptions itself.

For a first run, the honest order is to read the documentation for the method you want, take the published image, and run the evaluation script against a dataset in the data directory. That way the first thing you see is a number the paper claims, and only then do you change anything.

Where the limits are, and why the version number matters

Two constraints are worth stating directly, and the second is the one that catches people out.

The first is scope. The repository says it mainly focuses on image keypoint matching because it is a popular testbed. The molecules and film applications are listed as places where graph matching is applied, but the implementations shipped here are aimed at the keypoint setting. A team with a molecule matching problem should expect to adapt rather than to point at a model directory, and the size-varied and partial matching work in AFAT and GCAN shows that even within the keypoint setting the problems differ enough to need different models.

The second is the release line. The recent releases are 0.3.0 on 2022-11-21, 0.2.0 on 2022-02-16 and 0.1.0 on 2021-11-02, and the last push to the repository was on 2026-08-13. The repository is not archived and work has continued, but the published versions stopped more than three years ago. Anyone installing by version gets 0.3.0 and not the current branch, and the README does not describe the API as stable.

The licence is the other loose end. The metadata records a custom classification that GitHub cannot map, so the terms are in the LICENSE file at the root, and for a research code base whose methods are published in peer-reviewed venues, the code licence and the paper licences are separate questions. Anyone planning to build a product on one of these implementations needs to read that file and check the terms of the specific method they are using.

None of this makes the repository hard to use for its purpose. It makes it a repository to read, run and cite rather than to depend on.

Editorial conclusion

ThinkMatch suits a computer vision researcher who needs to run a published deep graph matching method, compare two of them on the same datasets and experiment settings, or build a new model on reusable modules. It is the wrong tool for a production application, since it is a research code base with a 0.x version line whose last release was 0.3.0 in 2022, and it is the wrong tool for a graph matching problem outside the image keypoint testbed the project focuses on. Before you adopt it, read the survey the README points to, since the methods are compared against each other in that paper, and confirm that the dataset and experiment setting you need are in the benchmarks the repository runs, because a fair comparison in this field is mostly a question of holding the setting fixed.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Thinklab-SJTU/ThinkMatch on GitHub