knapsack_solver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7d04df167b3dc41b861e541d7fba44765765280
+  data.tar.gz: 1832b618f0828d2409583bf97f0804cd13ac5b24
+SHA512:
+  metadata.gz: 5615a26a781ae3cd094666aaf93c8d412083882a4e4c8c3eb800735d6513794e9f27ad81cda4d447dd6707eb8b18f4b73868ef92ef54792d243f804a8f936b1c
+  data.tar.gz: 697349d2dce6d2f8d9acdaf32e552594c30745aa787f46b7051ff2635908bafb8374bd27d2b3e00a43dbb05436c24a99514872786dc315e1e92fcf2b999d449c

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018, Ján Sučan
+
+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,2 @@
+# knapsack-solver
+0/1 knapsack problem solver.

data/bin/knapsack_solver

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'knapsack_solver/cli'
+
+begin
+  KnapsackSolver::CLI.run(ARGV)
+  exit 0
+rescue StandardError => e
+  STDERR.puts "ERROR: #{e.message}"
+  STDERR.puts "Try 'knapsack_solver --help' for more information."
+  exit 1
+end

data/knapsack_solver.gemspec

@@ -0,0 +1,33 @@
+require File.expand_path('lib/knapsack_solver/version', __dir__)
+
+Gem::Specification.new do |s|
+  s.name        = 'knapsack_solver'
+  s.version     = KnapsackSolver::VERSION
+  s.homepage    = 'https://github.com/sucanjan/knapsack-solver'
+  s.license     = 'MIT'
+  s.author      = 'Jan Sucan'
+  s.email       = 'sucanjan@fit.cvut.cz'
+
+  s.summary     = '0/1 knapsack problem solver.'
+  s.description = <<-EOF
+This gem contains command-line utility for solving 0/1 knapsack problem using
+branch-and-bound method, dynamic programming, simple heuristic (weight/price)
+and fully polynomial time approximation scheme.
+
+It can measure CPU and wall-clock time spent by solving a problem, compute
+relative error of the result and generate graphs from those values.
+EOF
+
+  s.files       = Dir['bin/*', 'lib/**/*', '*.gemspec', 'LICENSE*', 'README*', 'test/*']
+  s.executables = Dir['bin/*'].map { |f| File.basename(f) }
+  s.has_rdoc    = 'yard'
+
+  s.required_ruby_version = '>= 2.2'
+  
+  s.add_runtime_dependency 'gnuplot', '~> 2.6'
+
+  s.add_development_dependency 'rake', '~> 12.0'
+  s.add_development_dependency 'rspec', '~> 3.6'
+  s.add_development_dependency 'rubocop', '~> 0.50.0'
+  s.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/knapsack_solver.rb

@@ -0,0 +1,2 @@
+require 'knapsack_solver/version'
+require 'knapsack_solver/solver'

data/lib/knapsack_solver/cli.rb

@@ -0,0 +1,49 @@
+require 'knapsack_solver/solver'
+require 'knapsack_solver/version'
+require 'knapsack_solver/cli_option_parser'
+require 'knapsack_solver/output_printer'
+require 'knapsack_solver/graph_printer'
+
+module KnapsackSolver
+  # This class implements a command-line interface for the 0/1 knapsack
+  # problem solver.
+  class CLI
+    # Suffix of a text file which will containg results of dataset solving
+    # (price, knapsack things presence, cpu time, wall clock time,
+    # relative_error).
+    RESULTS_FILNEMAE_SUFFIX = '.results'.freeze
+
+    # Suffix of a text file which will containg statistic data (average price,
+    # execution times, relative error)
+    STATS_FILNEMAE_SUFFIX = '.stats'.freeze
+
+    # Processes command-line arguments. If no option is given, converts arabic
+    # number to roman number and prints it to stdout.
+    #
+    # @param args [Array] the command-line arguments
+    def self.run(args)
+      options = CliOptionParser.parse(args)
+      return if options.nil?
+      datasets = args.each_with_object([]) do |file, sets|
+        sets << Dataset.parse(File.new(file))
+      end
+      s = Solver.new(options, datasets)
+      results = s.run
+      print_results(results, s.stats(results), options, args)
+    end
+
+    # Prints output of datasets solving. Results and statistics are printed to
+    # stdout or to a text files. Graphs of statistic values can be created.
+    #
+    # @param results [Hash] results of dataset solvings
+    # @param stats [Hash] statistics from the results of dataset solvings
+    # @param options [Hash] Command-line line options supplied to the CLI
+    # @param args [Array] array of the positional command-line arguments
+    def self.print_results(results, stats, options, args)
+      OutputPrinter.new(args, RESULTS_FILNEMAE_SUFFIX, results).print(options[:output_dir])
+      OutputPrinter.new(args, STATS_FILNEMAE_SUFFIX, stats).print(options[:output_dir])
+      return unless options[:graphs_dir]
+      GraphPrinter.new(args, stats, options[:graphs_dir]).print
+    end
+  end
+end

data/lib/knapsack_solver/cli_option_checker.rb

@@ -0,0 +1,83 @@
+require 'optparse'
+
+module KnapsackSolver
+  # This class checks command line arguments provided to the knapsack_solver
+  # binary.
+  class CliOptionChecker
+    # Checks command-line options, their arguments and positional arguments
+    # provided to the CLI.
+    #
+    # @param opts [Hash] parsed command-line options
+    # @param args [Array<String>] command-line positional arguments
+    def self.check(opts, args)
+      if !opts[:branch_and_bound] && !opts[:dynamic_programming] &&
+         !opts[:fptas] && !opts[:heuristic]
+        raise StandardError, 'At least one method of solving must be requested'
+      end
+      check_fptas_options(opts)
+      check_directories(opts)
+      check_positional_arguments(args)
+    end
+
+    # Checks command-line options and arguments used by FPTAS solving method.
+    #
+    # @param opts [Hash] parsed command-line options
+    def self.check_fptas_options(opts)
+      return if !opts[:fptas] && !opts.key?(:fptas_epsilon)
+      check_incomplete_fptas_options(opts)
+      eps = opts[:fptas_epsilon].to_f
+      return unless eps <= 0 || eps >= 1 || eps.to_s != opts[:fptas_epsilon]
+      raise StandardError,
+            'FPTAS epsilon must be number from range (0,1)'
+    end
+
+    # Checks command-line options and arguments used by FPTAS solving
+    # method. Recignizes cases when mandatory FPTAS epsilon constant is
+    # missing or when it the constant is provided and FPTAS method is not
+    # requested.
+    #
+    # @param opts [Hash] parsed command-line options
+    def self.check_incomplete_fptas_options(opts)
+      raise StandardError, 'Missing FPTAS epsilon constant' if opts[:fptas] && !opts.key?(:fptas_epsilon)
+      return unless !opts[:fptas] && opts.key?(:fptas_epsilon)
+      raise StandardError,
+            'epsilon constant must not be provided when FPTAS is not selected'
+    end
+
+    # Checks directory for result and statistic output logs, and directory for
+    # graph files.
+    #
+    # @param opts [Hash] parsed command-line options
+    def self.check_directories(opts)
+      check_output_directory(opts[:output_dir]) if opts[:output_dir]
+      check_output_directory(opts[:graphs_dir]) if opts[:graphs_dir]
+    end
+
+    # Checks if at least one dataset input file was provided and if the input
+    # files are readable.
+    #
+    # @param args [Array<String>] positional arguments provided to the CLI
+    def self.check_positional_arguments(args)
+      raise StandardError, 'Missing datset file(s)' if args.empty?
+      args.each { |f| check_input_file(f) }
+    end
+
+    # Checks if an output directory exist and is writable.
+    #
+    # @param path [Path] path to output directory
+    def self.check_output_directory(path)
+      raise StandardError, "Directory '#{path}' does not exists" unless File.exist?(path)
+      raise StandardError, "'#{path}' is not a directory" unless File.directory?(path)
+      raise StandardError, "Directory '#{path}' is not writable" unless File.writable?(path)
+    end
+
+    # Checks if an input file exist and is readable.
+    #
+    # @param path [Path] path to input regular file
+    def self.check_input_file(path)
+      raise StandardError, "File '#{path}' does not exists" unless File.exist?(path)
+      raise StandardError, "'#{path}' is not a regular file" unless File.file?(path)
+      raise StandardError, "File '#{path}' is not readable" unless File.readable?(path)
+    end
+  end
+end

data/lib/knapsack_solver/cli_option_parser.rb

@@ -0,0 +1,68 @@
+require 'optparse'
+require 'knapsack_solver/cli_option_checker'
+
+module KnapsackSolver
+  # This class parses command line arguments provided to the knapsack_solver
+  # binary.
+  class CliOptionParser
+    # Message that describes how to use this CLI utility.
+    USAGE_MESSAGE = 'Usage: knapsack_solver OPTIONS DATASET_FILE...'.freeze
+
+    # Parses command-line arguments and removes them from the array of
+    # arguments.
+    #
+    # @param [Array] arguments the command-line arguments.
+    # @return [Hash] hash of recognized options.
+    #
+    # rubocop:disable Metrics/AbcSize, Metric/MethodLength, Metric/BlockLength
+    def self.parse(arguments)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = USAGE_MESSAGE
+        opts.on('-b', '--branch-and-bound', 'Use branch and boung method of solving') do
+          options[:branch_and_bound] = true
+        end
+        opts.on('-d', '--dynamic-programming', 'Use dynamic programming for solving') do
+          options[:dynamic_programming] = true
+        end
+        opts.on('-f', '--fptas', 'Use FPTAS for solving') do
+          options[:fptas] = true
+        end
+        opts.on('-r', '--heuristic', 'Use brute force method of solving') do
+          options[:heuristic] = true
+        end
+        opts.on('-e', '--fptas-epsilon EPS', 'Relative error for FPTAS from range (0,1)') do |eps|
+          options[:fptas_epsilon] = eps
+        end
+        opts.on('-o', '--output DIR', 'Directory for output log files') do |dir|
+          options[:output_dir] = dir
+        end
+        opts.on('-g', '--graphs DIR', 'Directory for graphs') do |dir|
+          options[:graphs_dir] = dir
+        end
+        opts.on('-v', '--version', 'Show program version') do
+          options[:version] = true
+        end
+        opts.on_tail('-h', '--help', 'Show this help message') do
+          options[:help] = true
+        end
+      end
+      parser.parse!(arguments)
+      process_help_and_version_opts(options, arguments, parser.to_s)
+    end
+    # rubocop:enable Metrics/AbcSize, Metric/MethodLength, Metric/BlockLength
+
+    def self.process_help_and_version_opts(options, arguments, usage_msg)
+      if !options[:help] && !options[:version]
+        CliOptionChecker.check(options, arguments)
+        return options
+      end
+      if options[:help]
+        puts usage_msg
+      elsif options[:version]
+        puts "knapsack_solver #{KnapsackSolver::VERSION}"
+      end
+      nil
+    end
+  end
+end

data/lib/knapsack_solver/dataset.rb

@@ -0,0 +1,44 @@
+require 'knapsack_solver/instance'
+
+module KnapsackSolver
+  # This class represents a set of 0/1 knapsack problem instances.
+  class Dataset
+    # Initializes set of 0/1 knapsack problem instances.
+    #
+    # @param id [Integer] Dataset ID number.
+    # @param instances [Array<Instance>] set of the 0/1 knapsack problem instances.
+    def initialize(id, instances)
+      @id = id
+      @instances = instances
+    end
+
+    # Parses set of a 0/1 knapsack problem instances from a character stream.
+    #
+    # @param stream [#eof?,#readline,#each_line] character stream holding the dataset.
+    # @return [Dataset] dataset instance parsed from the stream.
+    def self.parse(stream)
+      id = parse_id(stream)
+      instances = stream.each_line.with_object([]) { |l, o| o << Instance.parse(l) }
+      raise StandardError, 'dataset: missing instances' if instances.empty?
+      Dataset.new(id, instances)
+    end
+
+    # Parses ID of a 0/1 knapsack problem dataset from a character stream.
+    #
+    # @param stream [#eof?,#readline,#each_line] character stream holding the dataset.
+    # @return [Integer] dataset ID number.
+    def self.parse_id(stream)
+      raise StandardError, 'dataset: missing ID' if stream.eof?
+      s = stream.readline.split
+      raise StandardError, 'dataset: first line does not contain ID' if s.size != 1
+      begin
+        raise StandardError, 'dataset: ID is negative' if Integer(s.first) < 0
+      rescue ArgumentError
+        raise StandardError, 'dataset: ID is not an integer'
+      end
+      Integer(s.first)
+    end
+
+    attr_reader :id, :instances
+  end
+end

data/lib/knapsack_solver/graph_printer.rb

@@ -0,0 +1,115 @@
+require 'gnuplot'
+
+module KnapsackSolver
+  # This class provides support for making graphs from statistics of datasets
+  # solving results. It uses Gnuplot and also generates a Gnuplot config file
+  # for each generated graph.
+  class GraphPrinter
+    # Initializes printer for graph data (graphs, Gnuplot config files).
+    #
+    # @param dataset_filenames [Array<String>] dataset filenames
+    # @param stats [Hash] statistics of results
+    # @param out_dir [String] statistics of results to print
+    def initialize(dataset_filenames, stats, out_dir)
+      @dataset_basenames = file_basenames(dataset_filenames)
+      @stats = stats
+      @out_dir = out_dir
+    end
+
+    # Create graphs from statistics and Gnuplot configuration files.
+    def print
+      stats_to_datasets.each do |title, ds|
+        ofn = File.join(@out_dir, title + '.png')
+        plot(title, ds, ofn)
+      end
+    end
+
+    protected
+
+    # Create graph.
+    #
+    # @param title [String] title of the graph
+    # @param data [Array<Gnuplot::DataSet>] Gnuplot datasets to plot
+    # @param filename [String] path to the output image file
+    def plot(title, data, filename)
+      Gnuplot.open do |gp|
+        Gnuplot::Plot.new(gp, &plot_config(title, 'dataset', 'y', data, filename))
+      end
+      File.open(File.join(File.dirname(filename), File.basename(filename, '.png') + '.gnuplot'), 'w') do |gp|
+        Gnuplot::Plot.new(gp, &plot_config(title, 'dataset', 'y', data, filename))
+      end
+    end
+
+    # Creates Gnuplot datasets from statistics.
+    #
+    # @return [Array<Gnuplot::DataSet>] Gnuplot datasets created from the statistics.
+    def stats_to_datasets
+      graphs = @stats.values.first.values.first.first.keys
+      x_data = @stats.keys
+      datasets(graphs, x_data)
+    end
+
+    # Creates Gnuplot datasets from statistics.
+    #
+    # @param graphs [Array] array of graph titles
+    # @param x_data [Array] array of X axis values
+    def datasets(graphs, x_data)
+      graphs.each_with_object({}) do |g, gnuplot_datasets|
+        @stats.each_value do |s|
+          gnuplot_datasets[g.to_s] = s.each_key.with_object([]) do |method, o|
+            o << plot_dataset(method.to_s, x_data, @stats.map { |_, v| v[method].first[g] })
+          end
+        end
+      end
+    end
+
+    # Create dataset from provided title, X axis data and Y axis data.
+    #
+    # @param title [String] Gnuplot dataset title
+    # @param x_data [Array] Array of X values
+    # @param y_data [Array] Array of Y values
+    # @return [Gnuplot::DataSet] Gnuplot dataset.
+    def plot_dataset(title, x_data, y_data)
+      Gnuplot::DataSet.new([x_data, y_data]) { |ds| ds.title = escape_gnuplot_special_chars(title) }
+    end
+
+    # Creates Gnuplot plot configuration (configuration text lines).
+    #
+    # @param title [String] graph title
+    # @param xlabel [String] label of X axis
+    # @param ylabel [String] label of Y axis
+    # @param plot_datasets [Array<Gnuplot::DataSet>] Gnuplot datasets for plotting
+    # @param out_file [String] output file
+    # @return [lambda] Lambda for setting plot configuration.
+    def plot_config(title, xlabel, ylabel, plot_datasets, out_file)
+      lambda do |plot|
+        plot.term('png')
+        plot.output(out_file)
+        plot.title("'#{escape_gnuplot_special_chars(title)}'")
+        plot.ylabel("'#{escape_gnuplot_special_chars(ylabel)}'")
+        plot.xlabel("'#{escape_gnuplot_special_chars(xlabel)}'")
+        plot.key('outside')
+        plot.data = plot_datasets
+      end
+    end
+
+    # Escapes Gnuplot special characters.
+    #
+    # @param str [String] a string
+    # @return [Strnig] the string with Gnuplot special chars escaped
+    def escape_gnuplot_special_chars(str)
+      # underscore means subscript in Gnuplot
+      str.gsub('_', '\_')
+    end
+
+    # Gets basenames of supplied file paths.
+    #
+    # @param paths [Array<String>] path to files
+    # @return [Array<String>] basenames of the paths
+    def file_basenames(paths)
+      paths.each_with_object([]) do |path, basenames|
+        basenames << File.basename(path, File.extname(path))
+      end
+    end
+  end
+end