graph_matching 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2224cf0e34e3cc897fa1e0821db9f74ddc7f1c75
+  data.tar.gz: 3acc5640fc7c25a56526503c07cb07ecfe6e6762
+SHA512:
+  metadata.gz: 6111293c87bcc34728de5324892c2ef84d0d0e74c88ede76ac299daf95192988541708c2872ceb853502a658490ff695688c2a55318f4e7a3932f90df75e60d8
+  data.tar.gz: 27827741f5b04a39d209fdf90970667fafc70c23f434d735593d866e6fdaeb4b352cba37c4dd4d50dec5e0b63bac0d574622f906ee274a04a2ebc7c12f691d81

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+*.pyc
+.bundle
+.config
+.idea
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store

data/.rubocop.yml

@@ -0,0 +1,112 @@
+# Use `rubocop --display-cop-names` and consult
+# https://github.com/bbatsov/rubocop/blob/master/config/default.yml
+# for options.
+
+# > Literal true appeared in a condition.
+# The `while do break` loop is not my favorite type of loop
+# either, but it's a valid technique and shouldn't be a lint
+# error.  At worst, it should be a style recommendation.
+# Finally, there is a `loop do .. end` alternative to `while true`
+# but it's nearly 3x slower. (https://www.ruby-forum.com/topic/179264)
+Lint/LiteralInCondition:
+  Enabled: false
+
+# TODO: Resolve, then increase severity
+Metrics/AbcSize:
+  Severity: refactor
+
+# TODO: Resolve, then increase severity
+Metrics/CyclomaticComplexity:
+  Severity: refactor
+
+Metrics/LineLength:
+  Max: 100 # TODO: Reduce to 80
+
+# TODO: Resolve, then increase severity
+Metrics/MethodLength:
+  Severity: refactor
+
+# TODO: Resolve, then increase severity
+Metrics/PerceivedComplexity:
+  Severity: refactor
+
+# Besides being racist, this also prevents the use of mathematical
+# symbols like π.  We're using utf-8 for a reason, c'mon.
+Style/AsciiComments:
+  Enabled: false
+
+# Block style should express the presence or absence of
+# side-effects, not the length of the block.
+Style/Blocks:
+  Enabled: false
+
+# An empty else clause is a good place to put comments explaining
+# a no-op.
+Style/EmptyElse:
+  Enabled: false
+
+# We can't say, in all cases that a guard clause is more
+# readable.  It should be left to the discretion of the
+# programmer.
+Style/GuardClause:
+  Enabled: false
+
+# > Favor modifier if usage when having a single-line body.
+# Yes, but there are still times, even with very short lines,
+# where a multi-line conditional is more readable.  Should
+# be left to the discretion of the programmer.
+Style/IfUnlessModifier:
+  Enabled: false
+
+# Normally I'd agree, but `loop` is nearly 3x slower, so we can't
+# use it in this performance-sensitive application.
+# (https://www.ruby-forum.com/topic/179264)
+Style/InfiniteLoop:
+  Enabled: false
+
+# > Align the operands of a condition in an unless statement
+# > spanning multiple lines.
+# This kind of style recommendation leads to too much mind-numbing
+# text shuffling.  It's not worth the "whitespace maintenance".
+Style/MultilineOperationIndentation:
+  Enabled: false
+
+# > Use next to skip iteration.
+# I agree, but this cop produces false positives.
+Style/Next:
+  Enabled: false
+
+# Normally, I'd agree, but `nil?` is actually a tiny bit slower,
+# and that matters when implementing algorithms.
+Style/NilComparison:
+  Enabled: false
+
+# String literal quoting has no impact on performance or
+# legibility.
+Style/StringLiterals:
+  Enabled: false
+
+# Percent-literal delimiters should express the content
+# of the literal, for example using square braces in `%w[]` to
+# indicate an array.
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+# > The RedundantReturn cop doesn't allow you to specify a return
+# > statement as the last line. But if the point is to return
+# > several values, I think return a, b, reads better than [a, b]
+# > https://github.com/bbatsov/rubocop/issues/528
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+# Use space inside range literals.
+# Bad: `(a..b - 1)`
+# Good: `(a .. b - 1)`
+# All other binary operators in the language  (`+`, `<<`) have
+# spaces around them, so `..` and `...` should too.
+Style/SpaceInsideRangeLiteral:
+  Enabled: false
+
+# Disagree. Indentation of loops is an important visual clue.
+Style/WhileUntilModifier:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.2.0

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - "1.9.3-p551"
+  - "2.0.0-p598"
+  - "2.1.5"
+  - "2.2.0"
+script: bundle exec rspec spec
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in graph_matching.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jared Beck
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+GraphMatching
+=============
+
+Efficient algorithms for **maximum cardinality** and
+**maximum weighted** [matchings][6] in undirected [graphs][7].
+Uses the [Ruby Graph Library (RGL)][4].
+
+[![Build Status][20]][23]
+[![Code Climate][22]][21]
+
+Algorithms
+----------
+
+This library implements the four algorithms described by Galil (1986).
+
+### 1. Maximum Cardinality Matching in Bipartite Graphs
+
+Uses the [Augmenting Path][5] algorithm, which performs in O(e * v)
+where e is the number of edges, and v, the number of vertexes ([benchmark][14]).
+
+```ruby
+require 'graph_matching'
+g = GraphMatching::Graph::Bigraph[1,3, 1,4, 2,3]
+m = g.maximum_cardinality_matching
+m.edges
+#=> [[4, 1], [3, 2]]
+```
+
+![MCM is O(e * v)][17]
+
+See [Benchmarking MCM in Complete Bigraphs][14]
+
+TO DO: This algorithm is inefficient compared to the [Hopcroft-Karp algorithm][13]
+which performs in O(e * sqrt(v)) in the worst case.
+
+### 2. Maximum Cardinality Matching in General Graphs
+
+Uses Gabow (1976) which performs in O(n^3).
+
+```ruby
+require 'graph_matching'
+g = GraphMatching::Graph::Graph[1,2, 1,3, 1,4, 2,3, 2,4, 3,4]
+m = g.maximum_cardinality_matching
+m.edges
+#=> [[2, 1], [4, 3]]
+```
+
+![MCM is O(v ^ 3)][18]
+
+See [Benchmarking MCM in Complete Graphs][15]
+
+Gabow (1976) is not the fastest algorithm, but it is "one exponent
+faster" than the original, [Edmonds' blossom algorithm][9], which
+performs in O(n^4).
+
+Faster algorithms include Even-Kariv (1975) and Micali-Vazirani (1980).
+Galil (1986) describes the latter as "a simpler approach".
+
+### 3. Maximum Weighted Matching in Bipartite Graphs
+
+Uses the [Augmenting Path][5] algorithm from Maximum Cardinality
+Matching, with the "scaling" approach described by Gabow (1983)
+and Galil (1986), which performs in O(n ^ (3/4) m log N).
+
+```ruby
+require 'graph_matching'
+g = GraphMatching::Graph::WeightedGraph[
+  [1, 2, 10],
+  [1, 3, 11]
+]
+m = g.maximum_weighted_matching
+m.edges
+#=> [[3, 1]]
+m.weight(g)
+#=> 11
+```
+
+![MWM is O(n ^ (3/4) m log N)][19]
+
+See [Benchmarking MWM in Complete Bigraphs][16]
+
+### 4. Maximum Weighted Matching in General Graphs
+
+A direct port of [Van Rantwijk's][11] implementation in python,
+while referring to Gabow (1985) and Galil (1986) for the big
+picture.
+
+Unlike the other algorithms above,
+`WeightedGraph#maximum_weighted_matching` takes an argument,
+`max_cardinality`.  If true, only maximum cardinality matchings
+will be considered.
+
+```ruby
+require 'graph_matching'
+g = GraphMatching::Graph::WeightedGraph[
+  [1, 2, 10],
+  [1, 3, 11]
+]
+m = g.maximum_weighted_matching(false)
+m.edges
+#=> [[3, 1]]
+m.weight(g)
+#=> 11
+```
+
+The algorithm performs in O(mn log n) as described by 
+Galil (1986) p. 34.
+
+![MWM is O(mn log n)][26]
+
+See [Benchmarking MWM in Complete Graphs][25]
+
+Limitations
+-----------
+
+All vertexes in a `Graph` must be consecutive positive nonzero
+integers.  This simplifies many algorithms.  For your convenience,
+a module (`GraphMatching::IntegerVertexes`) is provided to convert
+the vertexes of any `RGL::MutableGraph` to integers.
+
+```ruby
+require 'graph_matching'
+require 'graph_matching/integer_vertexes'
+g1 = RGL::AdjacencyGraph['a', 'b']
+g2, legend = GraphMatching::IntegerVertexes.to_integers(g1)
+g2.vertices
+#=> [1, 2]
+legend
+#=> {1=>"a", 2=>"b"}
+```
+
+Troubleshooting
+---------------
+
+* If you have [graphviz][24] installed, calling `#print` on
+  any `GraphMatching::Graph` will write a `png` to `/tmp` and
+  `open` it.
+
+Glossary
+--------
+
+- [Bipartite Graph][3] (bigraph)
+- [Graph][7]
+- [Matching][6]
+
+References
+----------
+
+- Edmonds, J. (1965). Paths, trees, and flowers. *Canadian Journal
+of Mathematics*.
+- Even, S. and Kariv, O. (1975). An O(n^2.5) Algorithm for Maximum
+Matching in General Graphs. *Proceedings of the 16th Annual IEEE
+Symposium on Foundations of Computer Science*. IEEE, New York, pp. 100-112
+- Kusner, M. [Edmonds's Blossom Algorithm (pdf)][12]
+- Gabow, H. J. (1973). Implementation of algorithms for maximum
+matching on nonbipartite graphs, Stanford Ph.D thesis.
+- Gabow, H. N. (1976). An Efficient Implementation of Edmonds'
+Algorithm for Maximum Matching on Graphs. *Journal of the Association
+for Computing Machinery*, Vol. 23, No. 2, pp. 221-234
+- Gabow, H. N. (1983). Scaling algorithms for network problems.
+*Proceedings of the 24th Annual IEEE Symposium on Foundations of
+Computer Science*. IEEE, New York, pp. 248-257
+- Gabow, H. N. (1985). A scaling algorithm for weighted matching on
+general graphs. *Proceedings of the 26th Annual IEEE Symposium on
+Foundations of Computer Science*. IEEE, New York, pp. 90-100
+- Galil, Z. (1986). Efficient algorithms for finding maximum
+matching in graphs. *ACM Computing Surveys*. Vol. 18, No. 1, pp. 23-38
+- Micali, S., and Vazirani, V. (1980). An O(e * sqrt(v)) Algorithm for
+finding maximal matching in general graphs. *Proceedings of the 21st
+Annual IEEE Symposium on Foundations of Computer Science*.
+IEEE, New York, pp. 17-27
+- Van Rantwijk, J. (2013) [Maximum Weighted Matching][11]
+- [Stolee, D.][8]
+    - [The Augmenting Path Algorithm for Bipartite Matching][1]
+    - [The Augmenting Path Algorithm (Example)][2]
+- West, D. B. (2001). *Introduction to graph theory*. Prentice Hall. p. 142
+- Zwick, U. (2013). [Lecture notes on: Maximum matching in bipartite
+and non-bipartite graphs (pdf)][10]
+
+[1]: http://www.youtube.com/watch?v=ory4WMX0rDU "The Augmenting Path Algorithm for Bipartite Matching"
+[2]: http://www.youtube.com/watch?v=C9c8zEZXboA "The Augmenting Path Algorithm (Example)"
+[3]: http://en.wikipedia.org/wiki/Bipartite_graph
+[4]: http://rgl.rubyforge.org/rgl/index.html
+[5]: http://en.wikipedia.org/wiki/Matching_%28graph_theory%29#In_unweighted_bipartite_graphs
+[6]: http://en.wikipedia.org/wiki/Matching_%28graph_theory%29
+[7]: http://en.wikipedia.org/wiki/Graph_theory
+[8]: http://www.math.uiuc.edu/~stolee/
+[9]: http://en.wikipedia.org/wiki/Blossom_algorithm
+[10]: http://www.cs.tau.ac.il/~zwick/grad-algo-13/match.pdf
+[11]: http://jorisvr.nl/maximummatching.html
+[12]: http://matthewkusner.com/MatthewKusner_BlossomAlgorithmReport.pdf
+[13]: http://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm
+[14]: https://github.com/jaredbeck/graph_matching/wiki/Benchmarking-MCM-in-Complete-Bigraphs
+[15]: https://github.com/jaredbeck/graph_matching/wiki/Benchmarking-MCM-in-Complete-Graphs
+[16]: https://github.com/jaredbeck/graph_matching/wiki/Benchmarking-MWM-in-Complete-Bigraphs
+[17]: https://github.com/jaredbeck/graph_matching/blob/master/benchmark/mcm_bipartite/complete_bigraphs/plot.png
+[18]: https://github.com/jaredbeck/graph_matching/blob/master/benchmark/mcm_general/complete_graphs/plot.png
+[19]: https://github.com/jaredbeck/graph_matching/blob/master/benchmark/mwm_bipartite/complete_bigraphs/plot.png
+[20]: https://travis-ci.org/jaredbeck/graph_matching.svg?branch=master
+[21]: https://codeclimate.com/github/jaredbeck/graph_matching
+[22]: https://codeclimate.com/github/jaredbeck/graph_matching/badges/gpa.svg
+[23]: https://travis-ci.org/jaredbeck/graph_matching/builds
+[24]: http://www.graphviz.org/
+[25]: https://github.com/jaredbeck/graph_matching/wiki/Benchmarking-MWM-in-Complete-Graphs
+[26]: https://github.com/jaredbeck/graph_matching/blob/master/benchmark/mwm_general/complete_graphs/plot.png

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+# TODO: add rubocop as a prerequisite once it's passing.
+task :default => [:spec]

data/benchmark/mcm_bipartite/complete_bigraphs/benchmark.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+# No shebang here.  Usage:
+# BM_DIR='benchmark/mcm_bipartite/complete_bigraphs'
+# ruby -I lib "$BM_DIR/benchmark.rb" > "$BM_DIR/time.data"
+
+require 'benchmark'
+require 'graph_matching'
+
+MIN_SIZE = 2
+MAX_SIZE = 500
+
+$stdout.sync = true
+
+def complete_bigraph(n)
+  g = GraphMatching::Graph::Bigraph.new
+  max_u = (n.to_f / 2).ceil
+  min_v = max_u + 1
+  1.upto(max_u) do |i|
+    min_v.upto(n) do |j|
+      g.add_edge(i, j)
+    end
+  end
+  g
+end
+
+MIN_SIZE.upto(MAX_SIZE) do |v|
+  print "%5d\t" % [v]
+  g = complete_bigraph(v)
+  GC.disable
+  puts Benchmark.realtime { g.maximum_cardinality_matching }
+  GC.enable
+end

data/benchmark/mcm_bipartite/complete_bigraphs/compare.gnuplot

@@ -0,0 +1,19 @@
+data_dir = "~/git/jaredbeck/graph_matching/benchmark/mcm_bipartite/complete_bigraphs"
+
+set title "MCM in Complete Bigraph"
+set key left box
+set term png size 800, 500
+set output data_dir."/plot_compare.png"
+
+set linetype 1 pointtype 7 linecolor rgb "#FF0000"
+set linetype 2 pointtype 7 linecolor rgb "#00B800"
+
+set xlabel 'Number of Vertexes (n)' textcolor rgb "black"
+set ytics autofreq textcolor rgb "black"
+set ylabel 'Time (s)' textcolor rgb "black"
+
+plot \
+data_dir."/time.data" \
+using 1:2 title "Before" lt 1 axes x1y1, \
+data_dir."/time2.data" \
+using 1:2 title "After" lt 2 axes x1y1