maximum-matching/README.md

Implementation of Blossom's Algorithm for Maximum Matching

# Typescript Maximum Matching 📘

Implementation of [Edmonds’ Blossom algorithm](https://en.wikipedia.org/wiki/Blossom_algorithm) for a maximum matching in graphs with Typescript and [graphology](https://github.com/graphology/graphology)

## Installation 💾

```bash
yarn add maximum-matching

# or

npm install maximum-matching

# ...
```

## Usage 🔬

First we need to create our graph. You can use a regular one from [graphology](https://graphology.github.io/) or our [MatchingGraph](./src/matchings/algorithm/MatchingGraph.ts)

```ts
import { MatchingGraph, maximumMatching } from 'maximum-matching'

const graph = new MatchingGraph()

graph.addNode('1')
graph.addNode('2')
graph.addNode('3')
graph.addNode('4')

// 1 - 2
// |   |
// 3 - 4
graph.addEdge('1', '2')
graph.addEdge('2', '4')
graph.addEdge('4', '3')
graph.addEdge('3', '1')
```

Then we can use the [maximumMatching](./src/matchings/algorithm/maximumMatching.ts) function to calculate it

```ts
const result = maximumMatching(graph)
// [ [ '1', '2' ], [ '3', '4' ] ]
```

# Special cases 🧐

When it is not possible to create a perfect matching (e.g. in graphs with an odd number of nodes), it can be interesting to use the `maximumMatchingGraph` function, which returns a [MatchingGraph](./src/matchings/algorithm/MatchingGraph.ts)

This is simply a subclass of `UndirectedGraph` from [graphology](https://github.com/graphology/graphology) that has useful methods for working with matchings.

In most cases you may not want to use them, but a very interesting one is `.unpairedNodes()`, which lets you know which nodes are unpaired after running the algorithm.

```ts
import { maximumMatchingGraph, MatchingGraph } from 'maximum-matching'

const graph = new MatchingGraph()

graph.addNode('Peter')
graph.addNode('Dave')
graph.addNode('Maria')
graph.addNode('Sara')
graph.addNode('Daniel')

// Peter - Dave
//  |       |
// Maria - Sara - Daniel
graph.addEdge('Daniel', 'Sara')
graph.addEdge('Sara', 'Maria')
graph.addEdge('Maria', 'Peter')
graph.addEdge('Peter', 'Dave')
graph.addEdge('Dave', 'Sara')

const resultGraph = maximumMatchingGraph(graph)

const maximumMatching = resultGraph.matching()
// [ [ 'Maria', 'Peter' ], [ 'Dave', 'Sara' ] ]

const unpairedNodes = resultGraph.unpairedNodes()
// [ 'Daniel' ]
```

calling the `.matching()` method in the resulting graph is the same thing as using the `maximumMatching` function directly.

## Theory 🎓

Formal proof: [Stanford University](https://stanford.edu/~rezab/classes/cme323/S16/projects_reports/shoemaker_vare.pdf)

Simplified proof: [Made by me (Spanish)](./docs/Simplified%20Proof%20by%20Julio%20Castro.pdf)

## Author 🧑‍🔬

Developed by [Julio César Castro López](https://linkedin.com/in/julio-cesar-castro-lopez-b759491b0)