relax4 1.0.5 → 1.1.0

data/README.rdoc

@@ -6,7 +6,8 @@ http://github.com/jdleesmiller/relax4_ruby
 
 == DESCRIPTION
 
-Ruby interface for the RELAX IV code for the minimum cost network flow problem.
+Ruby interface for the RELAX IV code for minimum cost network flow problems,
+which include transportation problems and assignment problems.
 In the words of the code's authors:
 
   PURPOSE - THIS ROUTINE IMPLEMENTS THE RELAXATION METHOD
@@ -34,7 +35,7 @@ In the words of the code's authors:
       FOR THE MINIMUM COST FLOW PROBLEM", LIDS REPORT P-2146, MIT, NOV. 1992.
 
 The original source can be downloaded from:
-* http://elib.zib.de/pub/Packages/mathprog/mincost/relax-4/
+* http://elib.zib.de/pub/Packages/mathprog/mincost/relax-4
 
 See also:
 * http://www-neos.mcs.anl.gov/neos/solvers/lno:RELAX4/RELAX4.html
@@ -44,7 +45,10 @@ See also:
 
   require 'rubygems'
   require 'relax4'
-  
+
+A general network flow problem:
+
+  #
   # From Figure 29.3 of Cormen, Leiserson, Rivest and Stein (2001).
   # Introduction to Algorithms, 2nd Edition.
   #
@@ -65,6 +69,32 @@ See also:
 
 A lower-level interface is also available; see the docs for the Relax4 module.
 
+A transportation problem:
+
+  #
+  # From http://www.me.utexas.edu/~jensen/models/network/net8.html
+  # A nil cost means that the flow is not allowed.
+  #
+  Relax4.solve_transportation_problem(
+    :costs =>   [[   3,   1, nil],
+                 [   4,   2,   4],
+                 [ nil,   3,   3]],
+    :demands =>  [   7,   3,   5],
+    :supplies => [   5,   7,   3]) #=> [[2, 3, 0], [5, 0, 2], [0, 0, 3]]
+
+An assignment problem:
+
+  #
+  # From http://www.me.utexas.edu/~jensen/models/network/net9.html
+  # A nil cost means that the assignment is not allowed.
+  #
+  Relax4.solve_assignment_problem(:costs =>
+    [[ nil,   8,   6,  12,   1],
+     [  15,  12,   7, nil,  10],
+     [  10, nil,   5,  14, nil],
+     [  12, nil,  12,  16,  15],
+     [  18,  17,  14, nil,  13]]) #=> [4, 2, 3, 0, 1]
+
 == REQUIREMENTS
 
 Has been tested on:
@@ -98,10 +128,13 @@ and run
 
 * there are some hard-coded parameters that could be exposed
 * problem state is global (cf. FORTRAN), so can have only one instance at a time
-* add some wrappers for transportation and assignment problems
 
 == HISTORY
 
+<em>1.1.0</em>
+* added wrappers for transportation and assignment problems
+* updated docs
+
 <em>1.0.5</em>
 * fix in previous version didn't quite solve the problem; new fix applied
 
@@ -138,7 +171,7 @@ following user guidelines:
   AND THE RELAXATION METHOD.  THEY SHOULD ALSO REGISTER WITH THE
   AUTHORS TO RECEIVE UPDATES AND SUBSEQUENT RELEASES.
 
-The author of the RELAX IV code is:
+The main author of the RELAX IV code is:
 
   DIMITRI P. BERTSEKAS
   LABORATORY FOR INFORMATION AND DECISION SYSTEMS

data/lib/relax4.rb

@@ -158,6 +158,119 @@ module Relax4
     end
   end
 
+  #
+  # Solve a transportation problem.
+  #
+  # There are +m+ suppliers and +n+ consumers of some commodity. Each supplier
+  # has a given _supply_ which must be used, and each consumer has a given
+  # _demand_ which must be satisfied; it is assumed that the total supply equals
+  # the total demand. The cost of transporting one unit of the commodity from
+  # each supplier to each consumer is given, and the objective is to perform the
+  # transport with minimum cost. The output is a +m+ by +n+ matrix that gives
+  # the flow from each supplier to each consumer.
+  #
+  # @param [Hash] args named arguments
+  #
+  # @option args [Array<Array<Integer>>] :costs matrix with +m+ rows (one for
+  # each supplier) and +n+ columns (one for each consumer); a cost of +nil+
+  # means that there is no corresponding edge (transport is impossible);
+  # negative costs are allowed; may be non-square but must be rectangular (all
+  # rows must have the same size).
+  #
+  # @option args [Array<Integer>] :supplies for each supplier; size +m+; total
+  # demand should equal total supply, or else the problem will be infeasible
+  # (but you can add a dummy node to fix this).
+  #
+  # @option args [Array<Integer>] :demands for each consumer; size +n+; total
+  # demand should equal total supply, or else the problem will be infeasible
+  # (but you can add a dummy node to fix this).
+  #
+  # @option args [Boolean] :auction_init see {solve}
+  #
+  # @option args [Integer] :large see {solve}
+  # 
+  # @option args [Integer] :max_cost see {solve}
+  #
+  # @return [Array<Array<Integer>>] optimal flows from each supplier to each
+  # consumer; size +m+ by +n+; +nil+ entries in the cost matrix will have flow 0
+  # here.
+  #
+  # @raise [ArgumentError] if problem inputs are invalid
+  #
+  # @raise [InfeasibleError] if problem is infeasible
+  #
+  def self.solve_transportation_problem args
+    args     = args.dup
+    costs    = get_arg(args, :costs)
+    supplies = get_arg(args, :supplies)
+    demands  = get_arg(args, :demands)
+
+    m = supplies.size
+    n = demands.size
+
+    arcs = set_args_from_cost_matrix(args, costs, m, n)
+    args[:demands] = supplies.map{|x| -x} + demands
+
+    arc_flows = Relax4.solve(args)
+
+    # Extract output into matrix with same dims as input cost matrix.
+    flows = Array.new(m) { Array.new(n, 0) }
+    arcs.zip(arc_flows).each do |(i,j),fij|
+      flows[i][j] = fij
+    end
+    flows
+  end
+
+  #
+  # Solve a square assignment problem.
+  #
+  # There are +n+ agents and +n+ tasks, and each agent must be assigned to
+  # exactly one task. The cost of each assignment is given, and the objective is
+  # to find the assignment with the lowest cost.
+  #
+  # Some assignments can be made illegal by passing +nil+ in the relevant entry
+  # in the cost matrix. If you have more agents than tasks (or vice versa), you
+  # can add some columns (or rows) of zeros to the cost matrix. 
+  #
+  # @param [Hash] args named arguments
+  #
+  # @option args [Array<Array<Integer>>] :costs square matrix with +n+ rows (one
+  # for each agent) and +n+ columns (one for each task); a cost of +nil+ means
+  # that the corresponding assignment is not allowed; negative costs are
+  # allowed.
+  #
+  # @option args [Boolean] :auction_init see {solve}
+  #
+  # @option args [Integer] :large see {solve}
+  # 
+  # @option args [Integer] :max_cost see {solve}
+  #
+  # @return [Array<Integer>] zero-based index of task assigned to each agent.
+  #
+  # @raise [ArgumentError] if problem inputs are invalid
+  #
+  # @raise [InfeasibleError] if problem is infeasible
+  # 
+  #
+  def self.solve_assignment_problem args
+    args  = args.dup
+    costs = get_arg(args, :costs)
+
+    n = costs.size
+
+    arcs = set_args_from_cost_matrix(args, costs, n, n)
+    args[:demands]     = [-1]*n + [1]*n
+
+    arc_flows = Relax4.solve(args)
+
+    # Find indexes.
+    assignment = Array.new(n)
+    arcs.zip(arc_flows).each do |(i,j),fij|
+      assignment[i] = j if fij > 0
+    end
+    assignment
+  end
+
   #
   # Raised to indicate that a problem is infeasible.
   #
@@ -220,5 +333,25 @@ module Relax4
   private
 
   def self.get_arg(args, key); args[key] or raise "#{key} is required" end
+
+  #
+  # Set start_nodes, end_nodes and costs based on cost matrix; nil entries in
+  # the cost matrix are not mapped to arcs.
+  #
+  # @return Array<Array<Integer>> array of pairs of (zero-based) indices into
+  # costs that correspond to the created arcs; size is <tt>m*n</tt> minus the
+  # number of nil entries in the costs matrix
+  #
+  def self.set_args_from_cost_matrix(args, costs, m, n)
+    # Filter out any nil costs.
+    arcs = (0...m).to_a.product((0...n).to_a).delete_if {|i,j| !costs[i][j]}
+
+    # Make problem inputs.
+    args[:start_nodes] = arcs.map{|i,j| i+1}
+    args[:end_nodes]   = arcs.map{|i,j| m+j+1}
+    args[:costs]       = arcs.map{|i,j| costs[i][j]}
+
+    arcs
+  end
 end
 

data/lib/relax4/version.rb

@@ -1,3 +1,3 @@
 module Relax4
-  VERSION = '1.0.5'
+  VERSION = '1.1.0'
 end

data/test/test_relax4.rb

@@ -56,6 +56,20 @@ class TestRelax4< Test::Unit::TestCase
     flows.zip(prob[:costs]).map{|f,c|f*c}.inject(:+)
   end
 
+  # Compute cost of flows when costs and flows are represented as matrices, and
+  # some of the costs may be nil.
+  def matrix_problem_cost prob, flows
+    flows = flows.flatten
+    costs = prob[:costs].flatten
+    flows.zip(costs).map{|f,c|f*c if c}.compact.inject(:+)
+  end
+
+  # Compute cost of given assignment. 
+  def assignment_problem_cost prob, assignment
+    n = prob[:costs].size # assumed square
+    n.times.map{|i| prob[:costs][i][assignment[i]]}.inject(:+)
+  end
+
   def test_solve_3
     prob = problem_from_relax4_inp 'test/RELAX4.INP'
 
@@ -292,4 +306,139 @@ ARCS
       Relax4.solve(prob.merge(:auction_init => true))
     end
   end
+
+  def test_transportation_problem_1
+    # From http://www.me.utexas.edu/~jensen/models/network/net8.html
+    prob = {
+      :costs =>   [[   3,   1, nil],
+                   [   4,   2,   4],
+                   [ nil,   3,   3]],
+      :demands =>  [   7,   3,   5],
+      :supplies => [   5,   7,   3]}
+    flows = Relax4.solve_transportation_problem(prob)
+    assert_equal 46, matrix_problem_cost(prob, flows)
+    assert_equal [[2, 3, 0],
+                  [5, 0, 2],
+                  [0, 0, 3]], flows
+  end
+
+  def test_transportation_problem_2
+    # From http://www.nios.ac.in/srsec311/opt-lp6.pdf (terminal questions)
+    prob = {
+      :costs =>   [[   1,   2,   1,   4],
+                   [   3,   3,   2,   1],
+                   [   4,   2,   5,   9]],
+      :supplies => [  30,  50,  20],
+      :demands  => [  20,  40,  30,  10]}
+    flows = Relax4.solve_transportation_problem(prob)
+    assert_equal 180, matrix_problem_cost(prob, flows)
+
+    prob = {
+      :costs =>   [[  21,  16,  25,  13],
+                   [  17,  18,  14,  23],
+                   [  32,  17,  18,  41]],
+      :supplies => [  11,  13,  19],
+      :demands  => [   6,  10,  12,  15]}
+    flows = Relax4.solve_transportation_problem(prob)
+    assert_equal 711, matrix_problem_cost(prob, flows)
+  end
+
+  def test_assignment_problem_1
+    # From http://www.me.utexas.edu/~jensen/models/network/net9.html
+    prob = {
+      :costs =>   [[ nil,   8,   6,  12,   1],
+                   [  15,  12,   7, nil,  10],
+                   [  10, nil,   5,  14, nil],
+                   [  12, nil,  12,  16,  15],
+                   [  18,  17,  14, nil,  13]]}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [4, 2, 3, 0, 1], assignment
+  end
+
+  def test_assignment_problem_2
+    # Test with no nils.
+    assert_equal [0, 1, 2],
+      Relax4.solve_assignment_problem(:costs => [[1, 2, 3],
+                                                 [4, 5, 6],
+                                                 [7, 8, 9]])
+
+    # Test with a row of nils; problem is infeasible.
+    assert_raise Relax4::InfeasibleError do
+      Relax4.solve_assignment_problem(:costs => [[nil, nil, nil],
+                                                 [  4,   5,   6],
+                                                 [  7,   8,   9]])
+    end
+
+    # Test with a column of nils; problem is infeasible.
+    assert_raise Relax4::InfeasibleError do
+      Relax4.solve_assignment_problem(:costs => [[nil,   2,   3],
+                                                 [nil,   5,   6],
+                                                 [nil,   8,   9]])
+    end
+  end
+
+  def test_assignment_problem_3
+    # From http://www.utdallas.edu/~scniu/OPRE-6201/documents/TP5-Assignment.pdf
+    prob = {
+      :costs =>   [[  13,   4,   7,   6],
+                   [   1,  11,   5,   4],
+                   [   6,   7,   2,   8],
+                   [   1,   3,   5,   9]]}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [1, 3, 2, 0], assignment
+    assert_equal 11, assignment_problem_cost(prob, assignment)
+  end
+
+  def string_array_to_matrix xs, n
+    xs = xs.map{|x| x.to_i}
+    n.times.map{|i| xs[i*n,n]}
+  end
+
+  def test_assignment_problem_4
+    # From http://www.nios.ac.in/srsec311/opt-lp5.pdf
+    prob = {:costs => string_array_to_matrix(%w(
+      140 110 155 170 180
+      115 100 110 140 155
+      120 90 135 150 165
+      30 30 60 60 90
+      35 15 50 60 85), 5)}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [4,2,1,0,3], assignment
+    assert_equal 470, assignment_problem_cost(prob, assignment)
+
+    prob = {:costs => string_array_to_matrix(%w(
+      15 17 24 16
+      10 15 12 13
+      17 19 18 16
+      13 20 16 14), 4)}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [1, 2, 3, 0], assignment
+    assert_equal 58, assignment_problem_cost(prob, assignment)
+
+    prob = {:costs => string_array_to_matrix(%w(
+       8 26 17 11
+      14 29 5 27
+      40 21 20 17
+      19 26 24 10), 4)}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [0, 2, 1, 3], assignment
+
+    prob = {:costs => string_array_to_matrix(%w(
+      10  6  4  8  3
+       2 11  7  7  6
+       5 10 11  4  8
+       6  5  3  2  5
+      11  7 10 11  7), 5)}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal [4, 0, 3, 2, 1], assignment
+    
+    prob = {:costs => string_array_to_matrix(%w(
+       8  9 10 11
+      10 11 12 13
+      13 14 15 13
+       9 11 14 10), 4)}
+    assignment = Relax4.solve_assignment_problem(prob)
+    assert_equal 43, assignment_problem_cost(prob, assignment)
+    assert_equal 43, assignment_problem_cost(prob, [2, 1, 3, 0])
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: relax4
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 19
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 5
-  version: 1.0.5
+  version: 1.1.0
 platform: ruby
 authors: 
 - John Lees-Miller
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-25 00:00:00 +01:00
+date: 2010-10-30 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -52,7 +52,7 @@ rdoc_options:
 - --main
 - README.rdoc
 - --title
-- relax4-1.0.5
+- relax4-1.1.0
 - --exclude
 - ext
 require_paths: