Skip to content
Cannot retrieve contributors at this time
456 lines (393 sloc) 16.7 KB
# Solve a placement, to give a starting point for
# instructors to work from
# Currently implements the Hungarian Algorithm,
# see references at the bottom of this file
require 'matrix'
# For some reason Ruby matricies aren't mutable
# But apparently there's an easy way to make them so
# *sigh* sometimes I really do miss Python
class Matrix
public :"[]=", :set_element, :set_component
# Raised when the solution does not converge
class SolutionError < StandardError; end
class Solver
# For test introspection
attr_reader :matrix, :students, :companies, :iterations
# Constraints:
# Number of students must equal number of company slots
# Invariants:
# Students are rows and companies are columns
# Initialization and the initial reduction are both O(V^2).
# TODO: Add support for initial_pairings
def initialize(classroom)
@rankings = classroom.rankings
# Build row and column headers
# (lists of students and company slots)
@students = classroom.students
@companies = []
classroom.companies.each do |company|
# If a company has multiple slots, add that many rows
company.slots.times do
@companies << company
unless @students.length == @companies.length
raise"Number of students (#{@students.length}) does not match number of company slots (#{@companies.length})")
unless @students.length > 0
raise"No students provided")
@matrix =, @companies.length) do |row, col|
initial_cost(row, col)
# Convert all costs to positive values by adding 1+abs(lowest cost) to each
offset = @matrix.to_a.flatten.min.abs + 1
@matrix = do |cost|
cost + offset
def solve
# Iterate until we've found a complete assignment. Since we add at least one
# zero to the reduced matrix every iteration, this is guaranteed to happen
# in O(E) < O(V^2) iterations.
# Finding the MM and MVC are both currently O(V^3), so our total runtime
# is at most O(V^5). Pretty gross, and the internet claims we can get the
# whole thing down to O(V^3), but since our V is at most 48 I don't think
# it's an issue. Basically until someone complains about performance IDGAF
@iterations = 0
while (true)
@iterations += 1
# puts "Current matrix reduction:"
# puts @matrix
# First build a flow graph for the current reduced matrix
flow_graph = build_flow_graph
# puts "Built flow graph:"
# puts flow_graph
# Find the maximum matching, that is, a set of assignments
# using the current reduced matrix. The slots in the array
# represent companies (columns), and the values represent
# students (rows). -1 means the company has no student assigned
assignments = maximum_matching(flow_graph)
# puts "Flow graph resulted in assignments:"
# print assignments
# puts
# Safety: outside of -1, there should be no duplicate assignments
real_assignments = { |a| a >= 0 }
# :nocov:
raise "maximum_matching returned a duplicate value in the assignment array: #{assignments}" unless real_assignments.length == real_assignments.uniq.length
# :nocov:
# If every company has a student assigned, we're done
unless assignments.include?(-1)
return build_pairings(assignments)
# If we've gotten here that means we're not done yet.
# Need to reduce the matrix, then go again.
# To reduce the matrix, we first convert our maximum matching
# into a minimum vertex cover using Koning's graph theorem
mvc_students, mvc_companies = minimum_vertex_cover(flow_graph, assignments)
# puts "MVC (students, companies):"
# print mvc_students
# puts
# print mvc_companies
# puts
reduce(mvc_students, mvc_companies)
# Initialization
# What is the initial cost for a student/company pair?
# Requires @rankings, @students and @companies to have been initialized
def initial_cost(row, col)
# Retrieve the ranking for this student-company pair
interview = Interview.find_by(student: @students[row], company: @companies[col])
if interview.nil?
# Students who did not interview with a company are assigned a value of
# Float::INFINITY, to represent the fact that they cannot intern there.
# XXX: not sure how this affects performance
return Float::INFINITY
# Currently, student preferences and interview results are 1 to 5,
# with 1 the worst and 5 the best
# Our intuition about the problem is that there's a small difference
# between an (incoming) 4 (inclined yes) and a 5 (strong yes),
# but a large difference between a 2 (inclined no) and a 1 (strong no).
# To build the cost: subtract each number from 6 (so it's 5 to 1,
# with 5 the worst and 1 the best) then multiply.
# TODO DPR: might make sense to adopt this schema gloabally
return -interview.score
# Optimization: reduce the number of times the algorithm
# iterates by seeding our matrix with some initial zeros
# Runs in O(V^2)
def initial_reduction
# For each row, subtract the smallest cost from each element
# Then repeat for columns
# r and c are row and column indicies
# row and column are actual vectors
# puts "Pre-reduction"
# puts @matrix
# Reduce rows
@matrix.row_count.times do |r|
min = @matrix.row(r).min
if min > 0
@matrix.column_count.times do |c|
@matrix[r,c] -= min
# Reduce columns
@matrix.column_count.times do |c|
min = @matrix.column(c).min
if min > 0
@matrix.row_count.times do |r|
@matrix[r,c] -= min
# Maximum matching
# The binary flow graph is used to compute both the
# maximum matching and the minimum vertex cover.
def build_flow_graph
return do |row, col|
@matrix[row, col] == 0
# Recursive subroutine based on DFS, that finds an assignment
# for the student in row r if possible
def find_match(flow_graph, r, seen, assignments)
# try each company, one by one
flow_graph.column_count.times do |c|
# If this student-company pairing is a candidate, and
# we haven't yet examined this company
if flow_graph[r,c] and not seen[c]
# Mark this company as seen
seen[c] = true
# If company c has no assigned student, or if
# the currently assigned student can be switched
# to a different company, we assign the student
# to this company and call it good
if assignments[c] < 0 or find_match(flow_graph, assignments[c], seen, assignments)
assignments[c] = r
return true
return false
# A matching is a set of edges (pairings) without any common
# vertices (students or companies). A maximum matching is a
# matching that contains the largest possible number of vertices.
# In this context, we're finding the maximum matching for our
# matrix as it has been reduced so far, that is, including only
# pairing where the current value is 0.
# To do so, we convert the matrix to a flow graph and use
# a variant on the Ford-Fulkerson algorithm to find the
# maximum matching.
# This method runs in O(V(V*E)) < O(V^3)
# The internet claims it's possible to achieve O(V^2) by
# using the matching from the previous step, but until
# performance is an issue I'm not going to bother
def maximum_matching(flow_graph)
# Array to keep track of which student is assigned to which company
# The value of assignments[c] is the student number s
# assigned to company c, or -1 if no one is assigned
assignments = [-1] * flow_graph.column_count
flow_graph.row_count.times do |r|
# Array to keep track of which companies
# have been seen while attempting to place this student
seen = [false] * flow_graph.column_count
find_match(flow_graph, r, seen, assignments)
return assignments
# Minimum vertex cover
# Implementation of the algorithm described by Konig's Theorem
def minimum_vertex_cover(flow_graph, assignments)
# Konig's theorm tells us that, given:
# a bipartate graph G, with vertices partitioned into students S and companies C,
# and edges E (all of which currently have cost 0, a.k.a. are marked true in the flow graph), and
# a maximum matching M (a subset of the edges in E),
# a minim vertex cover K can be constructed via the following technique:
# Let S' be the (possible empty) set of students in S not connected by M
# Define an alterating path as a path that alternates between
# edges in M and those not in M (doesn't matter which you start on)
# Let S* be the set of students in S that are either in S', or can
# be reached by following an alternating path from S' (a superset of S')
# Let C* be the set of companies in C that can be reached by such a path from S'
# Then the MVC K can be defined as the union of students not in S* and companies in C*
# More formally:
# S' = { s in S not connected by M }
# S* = S' U { s in S reachable by an alternating path from S' }
# C* = { c in C reachable by an alternating path from S' }
# then
# K = ( S - S* ) U C*
# How do we find vertices in S* and C*? BFS or DFS, of course!
# In the following code, S' will be called unmatched_students, and
# S* and C* will be called reachable_[students|companies], respectively
# Note: the provided flow graph is not (quite) bipartate - it may contain
# students or companies that are not connected to anything else. We'll have to
# explicitly check for and filter these as we compute our MVC
# Since it's built around a DFS from each unmatched student,
# I believe the runtime has an upper bound of O(V(V*E)) < O(V^3).
# Because the visited list for the DFS is maintained between
# students, it may just be O(V*E) < O(V^2), but I haven't
# bothered to actually run the math yet
# TODO DPR: how do results change if we swap S and C in the above?
# First compute S', the set of students not assigned to a company by M,
# but still with an edge in the flow graph
unmatched_students = []
flow_graph.row_count.times do |r|
# If the student doesn't have an edge in the flow graph, or if
# one of the edges for this student is in M, skip this student
found_edge = false
matched = false
flow_graph.column_count.times do |c|
if flow_graph[r, c]
if assignments[c] == r
matched = true
found_edge = true
unless matched or not found_edge
unmatched_students << r
# Safety: there should be no duplicates in unmatched_students
raise "in Konig, unmatched students contained a duplicate: #{unmatched_students}" unless unmatched_students.uniq.length == unmatched_students.length
# Next, compute S* and C*, the sets of students and companies reachable
# via an alternating path from S'. To do so, we use a DFS.
visited_students = [false] * flow_graph.row_count
visited_companies = [false] * flow_graph.column_count
# Since DFS is (traditionally) recursive, we'll define a couple helper
# methods: visit_company and visit_student
# And yes, mutually recursive functions do work in Ruby
# XXX DPR: there must be a better way to iterate across a range than
# flow_graph.row_count.times.[enumerable method]
# Note that since each search starts at a student not connected by M,
# odd legs in the path (student -> company) will always *not* be in M,
# while even legs (company -> student) always *will* be in M.
def visit_company(c, flow_graph, visited_companies, visited_students, assignments)
# Check the visited list
return if visited_companies[c]
# Add to visited list
visited_companies[c] = true
# Iterate across rows { |r|
# Only investigate rows that are both in the graph and not yet visited,
# and which *are* included in M for this column
flow_graph[r, c] and not visited_students[r] and assignments[c] == r
}.each do |r|
visit_student(r, flow_graph, visited_companies, visited_students, assignments)
# Has same form as visit_company, but with student and company swapped.
# Refer to the above for comments. The only difference is in whether we're
# looking for a vertex that is in M or not.
def visit_student(r, flow_graph, visited_companies, visited_students, assignments)
return if visited_students[r]
visited_students[r] = true { |c|
# Only investigate columns that are both in the graph and not yet visited,
# and which are *not* included in M for this row
flow_graph[r, c] and not visited_companies[c] and assignments[c] != r
}.each do |c|
visit_company(c, flow_graph, visited_companies, visited_students, assignments)
# Now that we've got our bipartate DFS methods set up, actually run the search!
unmatched_students.each do |r|
visit_student(r, flow_graph, visited_companies, visited_students, assignments)
# Now that we've got S* and C*, we can compute our MVC. Recall:
# K = ( S - S* ) U C*
# Note that a student is in S* if it was visited in the previous DFS, and
# similarly for companies in C*
# XXX DPR: each of these loops is n^2, we could probably do some
# preproscessing for lists of matched students and companies to eliminate that
mvc_students = do |r|
not visited_students[r] and flow_graph.row(r).include? true
mvc_companies = do |c|
visited_companies[c] and flow_graph.column(c).include? true
return mvc_students, mvc_companies
def reduce(mvc_students, mvc_companies)
# We'll need the minimum non-zero value in the matrix
min_value = { |v| v > 0 }.min
# XXX DPR: Not sure if we'll always hit this
# or if there's some thrashing behavior we might encounter
if min_value == Float::INFINITY
raise"Cannot further reduce the placement matrix. Either there's a programming error or this classroom has no solution!")
# To reduce the matrix, we use the following method:
# for each element (r,c) in the matrix:
# if r not in mvc_students and c not in mvc_companies (i.e. the cell in the matrix is not covered by any lines)
# subtract min_value from the element
# else if both r in mvc_students and c in mvc_companies (i.e. cell is covered by two lines)
# add min_value to the element
# I haven't yet read or come up with a convincing explanation of why this works, but as
# far as I can tell it's something to do with lowering our standards for
# uncovered nodes while not letting covered nodes stagnate. Worth doing
# some more serious thinking (especially if it ends up not working).
@matrix.each_with_index do |value, r, c|
if !mvc_students[r] and !mvc_companies[c]
# Not covered -> lower our standards
@matrix[r, c] = value - min_value
elsif mvc_students[r] and mvc_companies[c]
# Covered twice -> raise our stanards
@matrix[r, c] = value + min_value
def build_pairings(assignments)
# Note: none of these will be valid until attached to a placement
pairings = []
assignments.each_with_index do |r, c|
pairings << @students[r], company: @companies[c])
return pairings
# Sources:
# Hungarian Algorithm:
# Ruby matrix math:
# Finding a maximum matching:
# Converting a maximum matching to a minimum vertex cover: