johnridesabike / re-blossom

A Reason implementation of the blossom maximum-matching algorithm

Re-Blossom 🌺

Re-Blossom is a Reason implementation of the famous blossom algorithm. It finds a maximum matching of vertices on general, undirected, weighted graphs.

📖 Read the documentation

Notice

If you're using ReScript, check out ReScript-Blossom. It's the same algorithm, but optimized for a JavaScript environment.

This package originally had similar optimizations, but I've reworked it to be more compatible with native-Reason. This package currently still relies on bs-platform to compile to JavaScript, but that's only for testing. All of the core modules should be native-compatible.

I'm not currently using this package in a native environment, so I haven't fully converted it yet. If you think you will find this useful, I encourage you to fork it and make the modifications you need.

Installation

Re-Blossom requires BuckleScript as a peer dependency, so you will have to install it separately. Add it by running:

npm install bs-platform -D

You can add Re-Blossom to your project by running:

npm install re-blossom

You will need to edit your project's bsconfig.json file and list Re-Blossom in the bs-dependencies.

{
  "bs-dependencies": [
    "re-blossom"
  ]
}

Development

Download the code:

git clone https://github.com/johnridesabike/re-blossom.git

If you want to make your own changes, then it's recommended to fork the repository on GitHub and clone your forked version.

Install the dependencies:

npm install

Compile a production build:

npm run build

Run the Reason watcher (not necessary if your IDE automatically compiles Reason):

npm run start

Run the tests:

npm run test

Run benchmarks that compare it to the similar JavaScript algorithm:

npm run bench

Run benchmarks in a browser:

npm run browser

Then open the URL provided and navigate to the __benchmarks__ directory.

To turn on debug logging, enable bs-log with the BS_LOG environmental variable:

BS_LOG=re-blossom=* npm run build

# or with your editor

BS_LOG=re-blossom=* vim

When reading the code, you may need familiarity with BuckleScript's uncurrying, as well as its map and set structures.

This code uses many terms and ideas from "Efficient algorithms for finding maximum matching in graphs" by Zvi Galil, ACM Computing Surveys, 1986. Reading the paper will make this code much more understandable.