relax4 1.0.0

data/README.rdoc

@@ -0,0 +1,145 @@
+= relax4_ruby
+
+http://relax4.rubyforge.org
+
+http://github.com/jdleesmiller/relax4_ruby
+
+== DESCRIPTION
+
+Ruby interface for the RELAX IV code for the minimum cost network flow problem.
+In the words of the code's authors:
+
+  PURPOSE - THIS ROUTINE IMPLEMENTS THE RELAXATION METHOD
+            OF BERTSEKAS AND TSENG (SEE [1], [2]) FOR LINEAR 
+            COST ORDINARY NETWORK FLOW PROBLEMS.
+
+  [1] BERTSEKAS, D. P., "A UNIFIED FRAMEWORK FOR PRIMAL-DUAL METHODS ..."
+      MATHEMATICAL PROGRAMMING, VOL. 32, 1985, PP. 125-145.
+  [2] BERTSEKAS, D. P., AND TSENG, P., "RELAXATION METHODS FOR 
+      MINIMUM COST ..." OPERATIONS RESEARCH, VOL. 26, 1988, PP. 93-114.
+
+     THE RELAXATION METHOD IS ALSO DESCRIBED IN THE BOOKS:
+
+  [3] BERTSEKAS, D. P., "LINEAR NETWORK OPTIMIZATION: ALGORITHMS AND CODES"
+      MIT PRESS, 1991.
+  [4] BERTSEKAS, D. P. AND TSITSIKLIS, J. N., "PARALLEL AND DISTRIBUTED 
+      COMPUTATION: NUMERICAL METHODS", PRENTICE-HALL, 1989.
+
+  THIS CODE WAS WRITTEN BY DIMITRI P. BERTSEKAS AND PAUL TSENG,
+  WITH A CONTRIBUTION BY JONATHAN ECKSTEIN IN THE PHASE II INITIALIZATION.
+  THE ROUTINE AUCTION WAS WRITTEN BY DIMITRI P. BERTSEKAS AND IS BASED ON
+  THE METHOD DESCRIBED IN THE PAPER:
+
+  [5] BERTSEKAS, D. P., "AN AUCTION/SEQUENTIAL SHORTEST PATH ALGORITHM 
+      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/
+
+See also:
+* http://www-neos.mcs.anl.gov/neos/solvers/lno:RELAX4/RELAX4.html
+* http://web.mit.edu/afs/athena.mit.edu/user/d/i/dimitrib/www/RELAX4.txt
+
+== SYNOPSIS
+
+  require 'rubygems'
+  require 'relax4'
+  
+  # From Figure 29.3 of Cormen, Leiserson, Rivest and Stein (2001).
+  # Introduction to Algorithms, 2nd Edition.
+  #
+  #      (2)          edges are directed ((1,2), (1,3), ...)
+  #     / | \         each edge has a cost and a capacity
+  #    /  |  \        
+  #  (1)  |  (4)      the aim is to find the flow on each edge such that we 
+  #    \  |  /        move four units of flow from (1) to (4) at minimum cost
+  #     \ | /
+  #      (3)
+  #
+  Relax4.solve(
+      :demands     => [-4, 0, 0, 4],
+      :start_nodes => [ 1, 1, 2, 2, 3],
+      :end_nodes   => [ 2, 3, 3, 4, 4],
+      :costs       => [ 2, 5, 3, 7, 1],
+      :capacities  => [ 5, 2, 1, 2, 4]) #=> [2, 2, 1, 1, 3]
+
+A lower-level interface is also available; see the docs for the Relax4 module.
+
+== REQUIREMENTS
+
+The following packages were required to install on Ubuntu 10.04:
+
+* ruby, ruby-dev, rubygems, rake
+
+The bindings were generated with f2c (FORTRAN to C converter) and SWIG
+(www.swig.org), but you don't need either to build the gem.
+
+Has been tested on:
+* x86-linux (Ubuntu 10.04) with Ruby 1.8.7-p302
+* x86-linux (Ubuntu 10.04) with Ruby 1.9.2-p0
+* x86_64-linux (CentOS) with Ruby 1.8.7-p72
+
+== INSTALL
+
+You should be able to install with
+
+  gem install relax4
+
+on an x86_64-linux machine. Otherwise, you'll have to get the source
+
+  git clone http://github.com/jdleesmiller/relax4_ruby.git
+  
+and run
+
+  gem build relax4.gemspec
+  gem install relax4-<version>.gem
+
+== TODO
+
+* 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
+
+== LICENSE
+
+The authors of RELAX IV (D.P. Bertsekas and P. Tseng) released the code with the
+following user guidelines:
+
+  THIS ROUTINE IS IN THE PUBLIC DOMAIN TO BE USED ONLY FOR RESEARCH
+  PURPOSES.  IT CANNOT BE USED AS PART OF A COMMERCIAL PRODUCT, OR
+  TO SATISFY IN ANY PART COMMERCIAL DELIVERY REQUIREMENTS TO
+  GOVERNMENT OR INDUSTRY, WITHOUT PRIOR AGREEMENT WITH THE AUTHORS.
+  USERS ARE REQUESTED TO ACKNOWLEDGE THE AUTHORSHIP OF THE CODE,
+  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:
+
+  DIMITRI P. BERTSEKAS
+  LABORATORY FOR INFORMATION AND DECISION SYSTEMS
+  MASSACHUSETTS INSTITUTE OF TECHNOLOGY
+  CAMBRIDGE, MA 02139
+  (617) 253-7267, DIMITRIB@MIT.EDU
+
+The code for these Ruby bindings is released under the MIT license.
+
+Copyright (c) 2010 John Lees-Miller
+
+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/ext/extconf.rb

@@ -0,0 +1,11 @@
+require 'mkmf'
+
+#have_header('f2c.h') or raise 'You must install f2c (FORTRAN to C).'
+
+# This is slightly nonstandard, because f2c always inserts a function MAIN__
+# into the translated source, and it won't link unless this function is present.
+#have_library('f2c','e_rsle') {|src|
+#  src += "\nint MAIN__(void){ }\n"
+#} or raise 'You must install f2c (FORTRAN to C converter).'
+
+create_makefile("relax4")