hungarian_algorithm_c 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3131f481cd59f14347ab0881138cebeee3e426df
+  data.tar.gz: 8d5f3506ffe58e10ccb2bb5b550aaec1d3296a18
+SHA512:
+  metadata.gz: 3f41e80045ae12207881e794037d078e890e60bae9045c363cd86c3716f148318204ed06bdd67b2f0ef0630ede36cf83cc3a048a7edcb7cf1a83dbd8b0f5a957
+  data.tar.gz: ea61a05071cab151bb5e867e535b6127351889f610671800e8c800996ad432fbb20151e2a86333a5bb9179457f33c47c2a46133b29b6815db03ad4010f9892cc

data/.gitignore

@@ -0,0 +1,9 @@
+tmp/
+.DS_Store
+*.gem
+*.bundle
+Gemfile.lock
+lib/hungarian_algorithm_c.so
+ext/hungarian_algorithm_c/libhungarian/hungarian.o
+ext/hungarian_algorithm_c/libhungarian/hungarian_test
+ext/hungarian_algorithm_c/libhungarian/libhungarian.a

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+
+rvm:
+   - 2.2.7
+   - 2.3.1
+   - 2.4.1
+
+script:
+  - bundle exec rake test

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,49 @@
+# HungarianAlgorithmC
+
+A Ruby gem that computes the [Hungarian Algorithm](https://en.wikipedia.org/wiki/Hungarian_algorithm) in C.
+
+## Installation
+
+Add the following to your [Gemfile](http://tosbourn.com/what-is-the-gemfile/):
+
+```ruby
+# Gemfile
+gem 'hungarian_algorithm_c', github: 'deliveroo/hungarian_algorithm_c'
+```
+
+Run `bundle install`.
+
+## Usage
+
+Find the best pairings for elements with costs like so:
+
+```ruby
+costs = [
+  [4, 3],
+  [3, 0]
+]
+
+HungarianAlgorithmC.find_pairings(costs)
+
+#=> [[0, 0], [1, 1]]
+```
+
+The output will be an array of arrays; each sub-array will have the first element as the row index and the second element as the column index for the `costs` matrix. The indices together will select the lowest-cost combination.
+
+Another example:
+
+```ruby
+costs = [
+  [2, 3, 3],
+  [3, 3, 2],
+  [3, 2, 3]
+]
+
+HungarianAlgorithmC.find_pairings(costs)
+
+#=> [[0, 0], [1, 2], [2, 1]]
+```
+
+## Acknowledgements
+
+The C code uses the implementation by [Cyrill Stachniss](ext/hungarian_algorithm_c/libhungarian).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/extensiontask'
+require 'rake/testtask'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+Rake::ExtensionTask.new('hungarian_algorithm_c')
+
+task test: [:compile, :spec]

data/ext/hungarian_algorithm_c/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+extension_name = 'hungarian_algorithm_c'
+create_makefile(extension_name)

data/ext/hungarian_algorithm_c/hungarian_algorithm_c.c

@@ -0,0 +1,69 @@
+#include "ruby.h"
+#include "libhungarian/hungarian.c"
+#include "libhungarian/hungarian_test.c"
+
+// Define namespace / module name
+VALUE HungarianAlgorithmC = Qnil;
+
+// function declarations
+void Init_hungarian_algorithm_c();
+static VALUE indices_array(hungarian_problem_t* p, int row_size);
+VALUE pairs(VALUE self, VALUE flattened_array_ruby, VALUE row_size_val);
+
+// function to initialize module
+void Init_hungarian_algorithm_c() {
+  HungarianAlgorithmC = rb_define_module("HungarianAlgorithmC");
+  rb_define_singleton_method(HungarianAlgorithmC, "pairs", pairs, 2);
+}
+
+// function to extract assignment indices from a hungarian_problem_t struct to a '2D' Ruby array
+static VALUE indices_array(hungarian_problem_t* p, int row_size) {
+  int** values = p->assignment;
+  VALUE array = rb_ary_new2(row_size);
+
+  int i;
+  for (i = 0; i < row_size; i++) {
+    VALUE row = rb_ary_new2(2);
+
+    int j;
+    for (j = 0; j < row_size; j++) {
+      int value = values[i][j];
+      if (value == 1) {
+        rb_ary_push(row, INT2NUM(i));
+        rb_ary_push(row, INT2NUM(j));
+      }
+    }
+
+    rb_ary_push(array, row);
+  }
+
+  return array;
+}
+
+// function to find the optimal assignments from a flattend Ruby array
+// array must be flatted from an array representation of a rectangular matrix
+// i.e. the number of rows should equal the number of columns
+VALUE pairs(VALUE self, VALUE flattened_array_ruby, VALUE row_size_val) {
+  VALUE output;
+  hungarian_problem_t p;
+  int** matrix;
+  int row_size = NUM2INT(row_size_val);
+  int array_size = row_size * row_size;
+  int array_c[array_size];
+
+  int index;
+  for (index = 0; index < array_size; index++) {
+    double element = 100 * NUM2DBL(rb_ary_entry(flattened_array_ruby, index));
+    int rounded_element = element;
+    array_c[index] = rounded_element;
+  }
+
+  matrix = array_to_matrix(array_c, row_size, row_size);
+
+  hungarian_init(&p, matrix, row_size, row_size, 0);
+  hungarian_solve(&p);
+  output = indices_array(&p, row_size);
+  hungarian_free(&p);
+
+  return output;
+}

data/ext/hungarian_algorithm_c/libhungarian/Makefile

@@ -0,0 +1,20 @@
+CC = gcc
+AR = ar
+
+CFLAGS = -O3 -Wall -I.
+LDFLAGS = -L. -lhungarian
+
+all: libhungarian.a hungarian_test
+
+hungarian_test: hungarian_test.c $(HUNGARIANLIB)
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
+
+
+libhungarian.a: hungarian.o
+	$(AR) cr $@ hungarian.o
+
+%.o: %.c %.h
+	$(CC) $(CFLAGS) -c $<
+
+clean:
+	rm -f *.o *.a hungarian_test

data/ext/hungarian_algorithm_c/libhungarian/README.md

@@ -0,0 +1,11 @@
+# C Implementation of the Hungarian Method
+
+[Download libhungarian-v0.1.3.tgz (21.09.2015)](http://www2.informatik.uni-freiburg.de/~stachnis/misc/libhungarian-v0.1.3.tgz)
+
+From [homepage](http://www2.informatik.uni-freiburg.de/~stachnis/misc.html):
+
+> C-implementation of the Hungarian Method: finding the optimal assignment (assigning a set of jobs to a set of machines) in O(n^3), where n=max{#jobs, #machines}. The implementation is a sligntly enhanced version of the implementation provided by the Stanford GraphBase. See also: Stanford GraphBase, Hungarian Method by Brian Gerkey.
+
+From [implementation file](hungarian.c):
+
+> This file may be freely copied and distributed!

data/ext/hungarian_algorithm_c/libhungarian/hungarian.c

@@ -0,0 +1,419 @@
+/********************************************************************
+ ********************************************************************
+ **
+ ** libhungarian by Cyrill Stachniss, 2004
+ **
+ **
+ ** Solving the Minimum Assignment Problem using the
+ ** Hungarian Method.
+ **
+ ** ** This file may be freely copied and distributed! **
+ **
+ ** Parts of the used code was originally provided by the
+ ** "Stanford GraphGase", but I made changes to this code.
+ ** As asked by  the copyright node of the "Stanford GraphGase",
+ ** I hereby proclaim that this file are *NOT* part of the
+ ** "Stanford GraphGase" distrubition!
+ **
+ ** This file is distributed in the hope that it will be useful,
+ ** but WITHOUT ANY WARRANTY; without even the implied
+ ** warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ ** PURPOSE.
+ **
+ ********************************************************************
+ ********************************************************************/
+
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "hungarian.h"
+
+#define INF (0x7FFFFFFF)
+#define verbose (0)
+
+#define hungarian_test_alloc(X) do {if ((void *)(X) == NULL) fprintf(stderr, "Out of memory in %s, (%s, line %d).\n", __FUNCTION__, __FILE__, __LINE__); } while (0)
+
+
+void hungarian_print_matrix(int** C, int rows, int cols) {
+  int i,j;
+  fprintf(stderr , "\n");
+  for(i=0; i<rows; i++) {
+    fprintf(stderr, " [");
+    for(j=0; j<cols; j++) {
+      fprintf(stderr, "%5d ",C[i][j]);
+    }
+    fprintf(stderr, "]\n");
+  }
+  fprintf(stderr, "\n");
+}
+
+void hungarian_print_assignment(hungarian_problem_t* p) {
+  hungarian_print_matrix(p->assignment, p->num_rows, p->num_cols) ;
+}
+
+void hungarian_print_costmatrix(hungarian_problem_t* p) {
+  hungarian_print_matrix(p->cost, p->num_rows, p->num_cols) ;
+}
+
+void hungarian_print_status(hungarian_problem_t* p) {
+
+  fprintf(stderr,"cost:\n");
+  hungarian_print_costmatrix(p);
+
+  fprintf(stderr,"assignment:\n");
+  hungarian_print_assignment(p);
+
+}
+
+int hungarian_imax(int a, int b) {
+  return (a<b)?b:a;
+}
+
+int hungarian_init(hungarian_problem_t* p, int** cost_matrix, int rows, int cols, int mode) {
+
+  int i,j, org_cols, org_rows;
+  int max_cost;
+  max_cost = 0;
+
+  org_cols = cols;
+  org_rows = rows;
+
+  // is the number of cols  not equal to number of rows ?
+  // if yes, expand with 0-cols / 0-cols
+  rows = hungarian_imax(cols, rows);
+  cols = rows;
+
+  p->num_rows = rows;
+  p->num_cols = cols;
+
+  p->cost = (int**)calloc(rows,sizeof(int*));
+  hungarian_test_alloc(p->cost);
+  p->assignment = (int**)calloc(rows,sizeof(int*));
+  hungarian_test_alloc(p->assignment);
+
+  for(i=0; i<p->num_rows; i++) {
+    p->cost[i] = (int*)calloc(cols,sizeof(int));
+    hungarian_test_alloc(p->cost[i]);
+    p->assignment[i] = (int*)calloc(cols,sizeof(int));
+    hungarian_test_alloc(p->assignment[i]);
+    for(j=0; j<p->num_cols; j++) {
+      p->cost[i][j] =  (i < org_rows && j < org_cols) ? cost_matrix[i][j] : 0;
+      p->assignment[i][j] = 0;
+
+      if (max_cost < p->cost[i][j])
+	max_cost = p->cost[i][j];
+    }
+  }
+
+
+  if (mode == HUNGARIAN_MODE_MAXIMIZE_UTIL) {
+    for(i=0; i<p->num_rows; i++) {
+      for(j=0; j<p->num_cols; j++) {
+	p->cost[i][j] =  max_cost - p->cost[i][j];
+      }
+    }
+  }
+  else if (mode == HUNGARIAN_MODE_MINIMIZE_COST) {
+    // nothing to do
+  }
+  else
+    fprintf(stderr,"%s: unknown mode. Mode was set to HUNGARIAN_MODE_MINIMIZE_COST !\n", __FUNCTION__);
+
+  return rows;
+}
+
+
+
+
+void hungarian_free(hungarian_problem_t* p) {
+  int i;
+  for(i=0; i<p->num_rows; i++) {
+    free(p->cost[i]);
+    free(p->assignment[i]);
+  }
+  free(p->cost);
+  free(p->assignment);
+  p->cost = NULL;
+  p->assignment = NULL;
+}
+
+
+
+void hungarian_solve(hungarian_problem_t* p)
+{
+  int i, j, m, n, k, l, s, t, q, unmatched, cost;
+  int* col_mate;
+  int* row_mate;
+  int* parent_row;
+  int* unchosen_row;
+  int* row_dec;
+  int* col_inc;
+  int* slack;
+  int* slack_row;
+
+  cost=0;
+  m =p->num_rows;
+  n =p->num_cols;
+
+  col_mate = (int*)calloc(p->num_rows,sizeof(int));
+  hungarian_test_alloc(col_mate);
+  unchosen_row = (int*)calloc(p->num_rows,sizeof(int));
+  hungarian_test_alloc(unchosen_row);
+  row_dec  = (int*)calloc(p->num_rows,sizeof(int));
+  hungarian_test_alloc(row_dec);
+  slack_row  = (int*)calloc(p->num_rows,sizeof(int));
+  hungarian_test_alloc(slack_row);
+
+  row_mate = (int*)calloc(p->num_cols,sizeof(int));
+  hungarian_test_alloc(row_mate);
+  parent_row = (int*)calloc(p->num_cols,sizeof(int));
+  hungarian_test_alloc(parent_row);
+  col_inc = (int*)calloc(p->num_cols,sizeof(int));
+  hungarian_test_alloc(col_inc);
+  slack = (int*)calloc(p->num_cols,sizeof(int));
+  hungarian_test_alloc(slack);
+
+  for (i=0;i<p->num_rows;i++) {
+    col_mate[i]=0;
+    unchosen_row[i]=0;
+    row_dec[i]=0;
+    slack_row[i]=0;
+  }
+  for (j=0;j<p->num_cols;j++) {
+    row_mate[j]=0;
+    parent_row[j] = 0;
+    col_inc[j]=0;
+    slack[j]=0;
+  }
+
+  for (i=0;i<p->num_rows;++i)
+    for (j=0;j<p->num_cols;++j)
+      p->assignment[i][j]=HUNGARIAN_NOT_ASSIGNED;
+
+  // Begin subtract column minima in order to start with lots of zeroes 12
+  if (verbose)
+    fprintf(stderr, "Using heuristic\n");
+  for (l=0;l<n;l++)
+    {
+      s=p->cost[0][l];
+      for (k=1;k<m;k++)
+	if (p->cost[k][l]<s)
+	  s=p->cost[k][l];
+      cost+=s;
+      if (s!=0)
+	for (k=0;k<m;k++)
+	  p->cost[k][l]-=s;
+    }
+  // End subtract column minima in order to start with lots of zeroes 12
+
+  // Begin initial state 16
+  t=0;
+  for (l=0;l<n;l++)
+    {
+      row_mate[l]= -1;
+      parent_row[l]= -1;
+      col_inc[l]=0;
+      slack[l]=INF;
+    }
+  for (k=0;k<m;k++)
+    {
+      s=p->cost[k][0];
+      for (l=1;l<n;l++)
+	if (p->cost[k][l]<s)
+	  s=p->cost[k][l];
+      row_dec[k]=s;
+      for (l=0;l<n;l++)
+	if (s==p->cost[k][l] && row_mate[l]<0)
+	  {
+	    col_mate[k]=l;
+	    row_mate[l]=k;
+	    if (verbose)
+	      fprintf(stderr, "matching col %d==row %d\n",l,k);
+	    goto row_done;
+	  }
+      col_mate[k]= -1;
+      if (verbose)
+	fprintf(stderr, "node %d: unmatched row %d\n",t,k);
+      unchosen_row[t++]=k;
+    row_done:
+      ;
+    }
+  // End initial state 16
+
+  // Begin Hungarian algorithm 18
+  if (t==0)
+    goto done;
+  unmatched=t;
+  while (1)
+    {
+      if (verbose)
+	fprintf(stderr, "Matched %d rows.\n",m-t);
+      q=0;
+      while (1)
+	{
+	  while (q<t)
+	    {
+	      // Begin explore node q of the forest 19
+	      {
+		k=unchosen_row[q];
+		s=row_dec[k];
+		for (l=0;l<n;l++)
+		  if (slack[l])
+		    {
+		      int del;
+		      del=p->cost[k][l]-s+col_inc[l];
+		      if (del<slack[l])
+			{
+			  if (del==0)
+			    {
+			      if (row_mate[l]<0)
+				goto breakthru;
+			      slack[l]=0;
+			      parent_row[l]=k;
+			      if (verbose)
+				fprintf(stderr, "node %d: row %d==col %d--row %d\n",
+				       t,row_mate[l],l,k);
+			      unchosen_row[t++]=row_mate[l];
+			    }
+			  else
+			    {
+			      slack[l]=del;
+			      slack_row[l]=k;
+			    }
+			}
+		    }
+	      }
+	      // End explore node q of the forest 19
+	      q++;
+	    }
+
+	  // Begin introduce a new zero into the matrix 21
+	  s=INF;
+	  for (l=0;l<n;l++)
+	    if (slack[l] && slack[l]<s)
+	      s=slack[l];
+	  for (q=0;q<t;q++)
+	    row_dec[unchosen_row[q]]+=s;
+	  for (l=0;l<n;l++)
+	    if (slack[l])
+	      {
+		slack[l]-=s;
+		if (slack[l]==0)
+		  {
+		    // Begin look at a new zero 22
+		    k=slack_row[l];
+		    if (verbose)
+		      fprintf(stderr,
+			     "Decreasing uncovered elements by %d produces zero at [%d,%d]\n",
+			     s,k,l);
+		    if (row_mate[l]<0)
+		      {
+			for (j=l+1;j<n;j++)
+			  if (slack[j]==0)
+			    col_inc[j]+=s;
+			goto breakthru;
+		      }
+		    else
+		      {
+			parent_row[l]=k;
+			if (verbose)
+			  fprintf(stderr, "node %d: row %d==col %d--row %d\n",t,row_mate[l],l,k);
+			unchosen_row[t++]=row_mate[l];
+		      }
+		    // End look at a new zero 22
+		  }
+	      }
+	    else
+	      col_inc[l]+=s;
+	  // End introduce a new zero into the matrix 21
+	}
+    breakthru:
+      // Begin update the matching 20
+      if (verbose)
+	fprintf(stderr, "Breakthrough at node %d of %d!\n",q,t);
+      while (1)
+	{
+	  j=col_mate[k];
+	  col_mate[k]=l;
+	  row_mate[l]=k;
+	  if (verbose)
+	    fprintf(stderr, "rematching col %d==row %d\n",l,k);
+	  if (j<0)
+	    break;
+	  k=parent_row[j];
+	  l=j;
+	}
+      // End update the matching 20
+      if (--unmatched==0)
+	goto done;
+      // Begin get ready for another stage 17
+      t=0;
+      for (l=0;l<n;l++)
+	{
+	  parent_row[l]= -1;
+	  slack[l]=INF;
+	}
+      for (k=0;k<m;k++)
+	if (col_mate[k]<0)
+	  {
+	    if (verbose)
+	      fprintf(stderr, "node %d: unmatched row %d\n",t,k);
+	    unchosen_row[t++]=k;
+	  }
+      // End get ready for another stage 17
+    }
+ done:
+
+  // Begin doublecheck the solution 23
+  for (k=0;k<m;k++)
+    for (l=0;l<n;l++)
+      if (p->cost[k][l]<row_dec[k]-col_inc[l])
+	exit(0);
+  for (k=0;k<m;k++)
+    {
+      l=col_mate[k];
+      if (l<0 || p->cost[k][l]!=row_dec[k]-col_inc[l])
+	exit(0);
+    }
+  k=0;
+  for (l=0;l<n;l++)
+    if (col_inc[l])
+      k++;
+  if (k>m)
+    exit(0);
+  // End doublecheck the solution 23
+  // End Hungarian algorithm 18
+
+  for (i=0;i<m;++i)
+    {
+      p->assignment[i][col_mate[i]]=HUNGARIAN_ASSIGNED;
+      /*TRACE("%d - %d\n", i, col_mate[i]);*/
+    }
+  for (k=0;k<m;++k)
+    {
+      for (l=0;l<n;++l)
+	{
+	  /*TRACE("%d ",p->cost[k][l]-row_dec[k]+col_inc[l]);*/
+	  p->cost[k][l]=p->cost[k][l]-row_dec[k]+col_inc[l];
+	}
+      /*TRACE("\n");*/
+    }
+  for (i=0;i<m;i++)
+    cost+=row_dec[i];
+  for (i=0;i<n;i++)
+    cost-=col_inc[i];
+  if (verbose)
+    fprintf(stderr, "Cost is %d\n",cost);
+
+
+  free(slack);
+  free(col_inc);
+  free(parent_row);
+  free(row_mate);
+  free(slack_row);
+  free(row_dec);
+  free(unchosen_row);
+  free(col_mate);
+}
+
+

data/ext/hungarian_algorithm_c/libhungarian/hungarian.h

@@ -0,0 +1,74 @@
+/********************************************************************
+ ********************************************************************
+ **
+ ** libhungarian by Cyrill Stachniss, 2004
+ **
+ **
+ ** Solving the Minimum Assignment Problem using the
+ ** Hungarian Method.
+ **
+ ** ** This file may be freely copied and distributed! **
+ **
+ ** Parts of the used code was originally provided by the
+ ** "Stanford GraphGase", but I made changes to this code.
+ ** As asked by  the copyright node of the "Stanford GraphGase",
+ ** I hereby proclaim that this file are *NOT* part of the
+ ** "Stanford GraphGase" distrubition!
+ **
+ ** This file is distributed in the hope that it will be useful,
+ ** but WITHOUT ANY WARRANTY; without even the implied
+ ** warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ ** PURPOSE.
+ **
+ ********************************************************************
+ ********************************************************************/
+
+#ifndef HUNGARIAN_H
+#define HUNGARIAN_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define HUNGARIAN_NOT_ASSIGNED 0
+#define HUNGARIAN_ASSIGNED 1
+
+#define HUNGARIAN_MODE_MINIMIZE_COST   0
+#define HUNGARIAN_MODE_MAXIMIZE_UTIL 1
+
+typedef struct {
+  int num_rows;
+  int num_cols;
+  int** cost;
+  int** assignment;
+} hungarian_problem_t;
+
+/** This method initialize the hungarian_problem structure and init
+ *  the  cost matrices (missing lines or columns are filled with 0).
+ *  It returns the size of the quadratic(!) assignment matrix. **/
+int hungarian_init(hungarian_problem_t* p,
+		   int** cost_matrix,
+		   int rows,
+		   int cols,
+		   int mode);
+
+/** Free the memory allocated by init. **/
+void hungarian_free(hungarian_problem_t* p);
+
+/** This method computes the optimal assignment. **/
+void hungarian_solve(hungarian_problem_t* p);
+
+/** Print the computed optimal assignment. **/
+void hungarian_print_assignment(hungarian_problem_t* p);
+
+/** Print the cost matrix. **/
+void hungarian_print_costmatrix(hungarian_problem_t* p);
+
+/** Print cost matrix and assignment matrix. **/
+void hungarian_print_status(hungarian_problem_t* p);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/ext/hungarian_algorithm_c/libhungarian/hungarian_test.c

@@ -0,0 +1,83 @@
+/********************************************************************
+ ********************************************************************
+ **
+ ** libhungarian by Cyrill Stachniss, 2004
+ **
+ **
+ ** Solving the Minimum Assignment Problem using the
+ ** Hungarian Method.
+ **
+ ** ** This file may be freely copied and distributed! **
+ **
+ ** Parts of the used code was originally provided by the
+ ** "Stanford GraphGase", but I made changes to this code.
+ ** As asked by  the copyright node of the "Stanford GraphGase",
+ ** I hereby proclaim that this file are *NOT* part of the
+ ** "Stanford GraphGase" distrubition!
+ **
+ ** This file is distributed in the hope that it will be useful,
+ ** but WITHOUT ANY WARRANTY; without even the implied
+ ** warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ ** PURPOSE.
+ **
+ ********************************************************************
+ ********************************************************************/
+
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "hungarian.h"
+
+int** array_to_matrix(int* m, int rows, int cols) {
+  int i,j;
+  int** r;
+  r = (int**)calloc(rows,sizeof(int*));
+  for(i=0;i<rows;i++)
+  {
+    r[i] = (int*)calloc(cols,sizeof(int));
+    for(j=0;j<cols;j++)
+      r[i][j] = m[i*cols+j];
+  }
+  return r;
+}
+
+
+int main() {
+
+  hungarian_problem_t p;
+
+  /* an example cost matrix */
+  int r[4*3] =  {  100, 1, 1,
+		   100, 2, 2,
+		   1, 0, 0,
+		   0, 2, 0 };
+  int** m = array_to_matrix(r,4,3);
+
+  /* initialize the gungarian_problem using the cost matrix*/
+  int matrix_size = hungarian_init(&p, m , 4,3, HUNGARIAN_MODE_MINIMIZE_COST) ;
+
+  fprintf(stderr, "assignement matrix has a now a size %d rows and %d columns.\n\n",  matrix_size,matrix_size);
+
+  /* some output */
+  fprintf(stderr, "cost-matrix:");
+  hungarian_print_costmatrix(&p);
+
+  /* solve the assignement problem */
+  hungarian_solve(&p);
+
+  /* some output */
+  fprintf(stderr, "assignment:");
+  hungarian_print_assignment(&p);
+
+  /* free used memory */
+  hungarian_free(&p);
+
+  int idx;
+  for (idx=0; idx < 4; idx+=1) {
+    free(m[idx]);
+  }
+  free(m);
+
+  return 0;
+}
+

data/hungarian_algorithm_c.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+require_relative './lib/hungarian_algorithm_c/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hungarian_algorithm_c"
+  spec.version       = HungarianAlgorithmC::VERSION
+  spec.authors       = ["Syed Humza Shah"]
+  spec.email         = ["humza.shah@deliveroo.co.uk"]
+
+  spec.summary       = 'Evaluates the Hungarian algorithm in C'
+  spec.description   = 'A Ruby gem that evaluates the Hungarian algorithm in C'
+  spec.homepage      = 'https://github.com/deliveroo/hungarian_algorithm_c'
+  spec.license       = "MIT"
+
+  spec.require_paths = ["lib"]
+
+  all_files          = `git ls-files -z`.split("\x0")
+  test_file_regex    = %r{^(test|spec|features)/}
+  spec.files         = all_files.reject { |f| f.match(test_file_regex) }
+  spec.test_files    = all_files.select { |f| f.match(test_file_regex) }
+
+  spec.has_rdoc      = false
+  spec.extensions    = %w[ext/hungarian_algorithm_c/extconf.rb]
+
+  spec.required_ruby_version = '>= 2.0.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rake-compiler'
+end

data/lib/hungarian_algorithm_c.rb

@@ -0,0 +1,22 @@
+require 'hungarian_algorithm_c.so'
+
+module HungarianAlgorithmC
+  class << self
+    def find_pairings(array)
+      validate!(array)
+      pairs(array.flatten, array.size)
+    end
+
+    def validate!(array)
+      return if rectangular?(array)
+      raise ArgumentError.new('array must be rectangular')
+    end
+
+    def rectangular?(array)
+      row_size = array.size
+      array.all? { |column| row_size == column.size }
+    end
+
+    private :pairs, :validate!, :rectangular?
+  end
+end

data/lib/hungarian_algorithm_c/version.rb

@@ -0,0 +1,3 @@
+module HungarianAlgorithmC
+  VERSION = '0.0.1'
+end

data/spec/hungarian_algorithm_c_spec.rb

@@ -0,0 +1,64 @@
+require_relative './spec_helper'
+require_relative '../lib/hungarian_algorithm_c'
+
+RSpec.describe HungarianAlgorithmC do
+  describe '.find_pairings' do
+    subject { described_class.find_pairings(matrix_with_costs) }
+
+    context 'unbalanced array / non-square matrix' do
+      let(:matrix_with_costs) { [1, 2] }
+
+      it 'raises ArgumentError' do
+        expect { subject }.to raise_error(ArgumentError)
+      end
+    end
+
+    context '2x2 array' do
+      let(:matrix_with_costs) { [
+        [4, 3],
+        [3, 0]
+      ] }
+
+      it 'should output minimum cost pairs' do
+        should match_array([
+          [1, 1],
+          [0, 0]
+        ])
+      end
+    end
+
+    context '3x3 array' do
+      let(:matrix_with_costs) { [
+        [2, 3, 3],
+        [3, 3, 2],
+        [3, 2, 3]
+      ] }
+
+      it 'should output minimum cost pairs' do
+        should match_array([
+          [0, 0],
+          [1, 2],
+          [2, 1]
+        ])
+      end
+    end
+
+    context '4x4 array' do
+      let(:matrix_with_costs) { [
+        [2, 3, 1, 3],
+        [10, 2, 90, 6],
+        [10, 3, 34, 4],
+        [11, 13, 15, 17]
+      ] }
+
+      it 'should output minimum cost pairs' do
+        should match_array([
+          [0, 2],
+          [1, 1],
+          [2, 3],
+          [3, 0]
+        ])
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+RSpec.configure do |config|
+  config.color = true
+  config.tty = true
+  config.formatter = :documentation
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: hungarian_algorithm_c
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Syed Humza Shah
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby gem that evaluates the Hungarian algorithm in C
+email:
+- humza.shah@deliveroo.co.uk
+executables: []
+extensions:
+- ext/hungarian_algorithm_c/extconf.rb
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- ext/hungarian_algorithm_c/extconf.rb
+- ext/hungarian_algorithm_c/hungarian_algorithm_c.c
+- ext/hungarian_algorithm_c/libhungarian/Makefile
+- ext/hungarian_algorithm_c/libhungarian/README.md
+- ext/hungarian_algorithm_c/libhungarian/hungarian.c
+- ext/hungarian_algorithm_c/libhungarian/hungarian.h
+- ext/hungarian_algorithm_c/libhungarian/hungarian_test.c
+- hungarian_algorithm_c.gemspec
+- lib/hungarian_algorithm_c.rb
+- lib/hungarian_algorithm_c/version.rb
+- spec/hungarian_algorithm_c_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/deliveroo/hungarian_algorithm_c
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Evaluates the Hungarian algorithm in C
+test_files:
+- spec/hungarian_algorithm_c_spec.rb
+- spec/spec_helper.rb
+has_rdoc: false