batch_experiment 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4d594a77b4909c00eb2c07a05dbc6c4f0cc68c9a
-  data.tar.gz: 979f0d1800486061aff5d9a1728e55790e675e34
+  metadata.gz: e6db331d43fbfee1847a2385bc1c90616433451b
+  data.tar.gz: 0b5b00e526fe8ff5d78d32991ee79e2655d24c5c
 SHA512:
-  metadata.gz: cc0d896402fc7820e7c1f2741ae9e07ffdea6ab14edc3156e9bdcd5d3f4c24b71e753087e1980fdb97c8b85006cc2c7ef1bbb3bdad3a181b0853a7c94f76ea82
-  data.tar.gz: bfde027e77f78360a9728eacca5075a00a2b59e47cd0224e692c2e44bc6118e942c93c4913a0bd65a5861612191f92deb4402052440037e416391c9433d2629c
+  metadata.gz: 41b4f4c3866c68c86677630466e88eb574ca0ccd417a55c94eaa378d55c368673f07c5bd6dfb4018ac69d1519c730e8d6b41cc8d0c9e6ac58e51e12684435322
+  data.tar.gz: babb03ca7415332843d231e21e30a9ecea32f3da5792fc48ccc5023c4c31eaf374c48091869e9a42c45e83b01f8d6647ea70e384d14fdecd511cdac9fc580be3

data/examples/bible.txt

@@ -0,0 +1,8 @@
+IN THE beginning [before all time] was the Word (Christ), and the Word was with God, and the Word was God Himself.
+He was present originally with God.
+All things were made and came into existence through Him, and without Him was not even one thing made that has come into being.
+In Him was Life, and the Life was the Light of men.
+And the Light shines on in the darkness, for the darkness has never overpowered it [put it out or absorbed it or appropriated it, and is unreceptive to it].
+There came a man sent from God, whose name was John.
+This man came to witness, that he might testify of the Light, that all men might believe in it [adhere to it, trust it, and rely upon it] through him.
+He was not the Light himself, but came that he might bear witness regarding the Light.

data/examples/example_batch.rb

@@ -0,0 +1,42 @@
+#!/bin/ruby
+
+require 'batch_experiment'
+require 'batch_experiment/sample_extractors'
+
+comms_info = [{
+  command: 'cat X',
+  pattern: 'X',
+  extractor: BatchExperiment::FirstLineExtractor,
+  prefix: 'cat',
+}, {
+  command: 'echo y',
+  pattern: 'y',
+  extractor: BatchExperiment::FirstLineExtractor,
+  prefix: 'echo',
+}, {
+  command: 'wc FILE',
+  pattern: 'FILE',
+  extractor: BatchExperiment::WcExtractor,
+  prefix: 'wc',
+}]
+
+execution_info = {
+  # IDs of the CPU cores that can be used for executing tests.
+  cpus_available: [1, 2, 3],
+  # Maximum number of seconds that a command can run. After this a kill command
+  # (TERM signal) will be issued.
+  timeout: 5,
+}
+
+conf = {
+  # The name of the file where will be written the CSV data.
+  csvfname: 'example.csv',
+  # The columns will be ordered by command. All the columns of the first
+  # command before the one from the second and so on.
+  ic_columns: false,
+}
+
+files = ['bible.txt', 'taoteching.txt']
+
+BatchExperiment::experiment(comms_info, execution_info, conf, files)
+

data/examples/sample_batch.rb

@@ -1,34 +1,16 @@
 #!/bin/ruby
 
 require 'batch_experiment'
-require 'batch_experiment/sample_extractors'
 
-comms_info = [{
-  # String with command to be executed. Must have 'pattern' as substring.
-  command: 'sleep 1 && echo X X',
-  # Substring present in 'command'. Often replaced by the instance filename.
-  pattern: 'X',
-  # Extractor object. Receives the output of the command and return
-  # the most important fields.
-  extractor: SampleExtractor.new,
-  # String used to identify the command. Will be used to prefix the return of
-  # extractor.names.
-  prefix: 'doubled',
-}, {
-  command: 'sleep 3 && echo "banana X"',
-  pattern: 'X',
-  extractor: SampleExtractor.new,
-  prefix: 'banana',
-}, {
-  command: 'sleep 100 && echo "never gonna happen X"',
-  pattern: 'X',
-  extractor: SampleExtractor.new,
-  prefix: 'timeout',
-}]
+commands = [
+  'sleep 2 && echo orange',
+  'sleep 4 && echo banana',
+  'sleep 100 && echo "never gonna happen"',
+]
 
-execution_info = {
+conf = {
   # IDs of the CPU cores that can be used for executing tests.
-  cpus_available: [1, 2, 3],
+  cpus_available: [0, 1],
   # Maximum number of seconds that a command can run. After this a kill command
   # (TERM signal) will be issued.
   timeout: 5,
@@ -37,12 +19,5 @@ execution_info = {
   post_timeout: 1,
 }
 
-conf = {
-  # The name of the file where will be written the CSV data.
-  csvfname: 'sample.csv',
-}
-
-files = ['apple', 'orange'] # Applejack would be proud
-
-BatchExperiment::experiment(comms_info, execution_info, conf, files)
+BatchExperiment::batch(commands, conf)
 

data/examples/taoteching.txt

@@ -0,0 +1,10 @@
+The tao that can be told is not the eternal Tao.
+The name that can be named is not the eternal Name.
+The unnamable is the eternally real.
+Naming is the origin of all particular things.
+Free from desire, you realize the mystery.
+Caught in desire, you see only the manifestations.
+Yet mystery and manifestations arise from the same source.
+This source is called darkness.
+Darkness within darkness.
+The gateway to all understanding.

data/examples/ukp_batch.rb

@@ -12,12 +12,12 @@ require_relative 'batch_experiment/sample_extractors'
 comms_info = [{
   command: 'pyasukpt -src INST_FILE',
   pattern: 'INST_FILE',
-  extractor: PyaExtractor.new,
+  extractor: BatchExperiment::PyaExtractor,
   prefix: 'PYAsUKP',
 }, {
   command: 'run_ukp5.out INST_FILE',
   pattern: 'INST_FILE',
-  extractor: UKP5Extractor.new,
+  extractor: BatchExperiment::UKP5Extractor,
   prefix: 'UKP5',
 }]
 

data/lib/batch_experiment.rb

@@ -1,11 +1,13 @@
 require 'childprocess'
 require 'pathname'
 
+# The main module, the two main utility methods offered are ::batch and
+# ::experiment.
 module BatchExperiment
-  # The default callable class used by batch to convert a command into a
+  # The default callable object used by #batch to convert a command into a
   # filename.
-  class FilenameSanitizer
-    def call(command)
+  module FilenameSanitizer
+    def self.call(command)
       fname = command.strip
       fname.gsub!(/[^[:alnum:]]/, '_')
       fname.gsub!(/_+/, '_')
@@ -32,55 +34,53 @@ module BatchExperiment
 
   # Takes a list of commands, execute them only on the designed core/cpus, and
   # kill them if the timeout expires, never lets a core/cpu rest for more than
-  # conf[:busy_loop_sleep] seconds between a command and another. The
-  # conf[:fname_sanitizer] is called over the commands to generate partial
-  # filenames. Appending '.out' to one of the partial filenames will give the
-  # filename were the command stdout was redirected. The analogue is valid for
-  # '.err' and stderr. The first partial filename corresponds to the first
-  # command in commands, and so on. Right before a command begans to run, a
-  # "partial_filename.#{conf[:unfinished_ext]}" file is created. After the
-  # command ends its execution this file is removed. If the command ends its
-  # execution by means of a timeout the file is also removed. The file only
-  # remains if the batch procedure is interrupted (not a specific command).
+  # a predetermined amount of seconds between a command and another. Partial
+  # filenames are derived from the commands. Appending '.out' to one of the
+  # partial filenames will give the filename were the command stdout was
+  # redirected. The analogue is valid for '.err' and stderr. Right before a
+  # command begans to run, a "partial_filename.unfinished file is created.
+  # After the command ends its execution this file is removed. If the command
+  # ends its execution by means of a timeout the file is also removed. The file
+  # only remains if the batch procedure is interrupted (script was killed,
+  # or system crashed).
   #
   # @param commands [Array<String>] The shell commands.
   # @param conf [Hash] The configurations, as follows:
-  #   :cpus_available [Array<Fixnum>] Cpu cores that can be used to run the
+  #   -- cpus_available [Array<Fixnum>] Cpu cores that can be used to run the
   #   commands. Required parameter. The cpu numbers begin at 0, despite what
-  #   htop tells you;
-  #   :timeout [Number] Number of seconds before killing a command. Required
-  #   parameter. Is the same for all the commands;
-  #   :time_fmt [String] A string in the time (external command) format. See
+  #   htop tells you.
+  #   -- timeout [Number] Number of seconds before killing a command. Required
+  #   parameter. Is the same for all the commands.
+  #   -- time_fmt [String] A string in the time (external command) format. See
   #   http://linux.die.net/man/1/time. Default: 'ext_time: %e\next_mem: %M\n'.
-  #   :busy_loop_sleep [Number] How many seconds to wait before checking if a
+  #   busy_loop_sleep [Number] How many seconds to wait before checking if a
   #   command ended execution. This is max time a cpu will be vacant between
-  #   two commands. Default: 0.1;
-  #   :post_timeout [Number] A command isn't guaranteed to end after receiving
-  #   a TERM signal. If the command hasn't stopped, waits post_timeout seconds
-  #   before sending a KILL signal (give it a chance to end gracefully).
-  #   Default: 5;
-  #   :fname_sanitizer [Callable Object] The call method of this object
+  #   two commands. Default: 0.1.
+  #   -- post_timeout [Number] A command isn't guaranteed to end after
+  #   receiving a TERM signal. If the command hasn't stopped, waits
+  #   post_timeout seconds before sending a KILL signal (give it a chance to
+  #   end gracefully). Default: 5.
+  #   -- fname_sanitizer [#call] The call method of this object
   #   should take a String and convert it (possibly losing information), to a
   #   valid filename. Used over the commands to define the output files of
-  #   commands.
-  #   Default: BatchExperiment::FilenameSanitizer.new;
-  #   :skip_done_comms [FalseClass,TrueClass] Skip any command for what a
+  #   commands. Default: BatchExperiment::FilenameSanitizer
+  #   -- skip_done_comms [FalseClass,TrueClass] Skip any command for what a
   #   corresponding '.out' file exists, except if both a '.out' and a
   #   '.unfinished' file exist, in the last case the command is executed.
-  #   Default: true;
-  #   :unfinished_ext [String] Extension to be used in place of '.unfinished'.
-  #   Default: '.unfinished';
-  #   :out_ext [String] Extension to be used in place of '.out'.
-  #   Default: '.out';
-  #   :err_ext [String] Extension to be used in place of '.err'.
-  #   Default: '.err';
+  #   Default: true.
+  #   -- unfinished_ext [String] Extension to be used in place of
+  #   '.unfinished'.  Default: '.unfinished'.
+  #   -- out_ext [String] Extension to be used in place of '.out'.
+  #   Default: '.out'.
+  #   -- err_ext [String] Extension to be used in place of '.err'.
+  #   Default: '.err'.
   # @return [String] Which commands were executed. Can be different from
   #   the 'commands' argument if commands are skipped (see :skip_done_comms).
   #
-  # @note This procedure was not designed to support equal commands (the last
-  #   equal command executed will subscribe the '.out', '.err' and '.unfinished'
-  #   files used by any previous equal command). But the parameter
-  #   conf[:fname_sanitizer] can be used to circumvent the restriction over
+  # @note If the same command is executed over the same file more than one
+  #   time, then only the last execution will be saved (because the '.out',
+  #   '.err' and '.unfinished' files will be overwritten). But the parameter
+  #   conf\[:fname_sanitizer\] can be used to circumvent the restriction over
   #   equal commands (if the object has state it can return a different
   #   filename for every time it's called with the same argument).
   # @note This procedure makes use of the following linux commands: time (not
@@ -91,13 +91,13 @@ module BatchExperiment
   #   shell).
   # @note The command is executed inside a call to "sh -c command", so it has
   #   to be a valid sh command.
-  # @note The output of the command "time -f #{conf[:time_fmt]}" will be
-  #   appended to the '.out' file of every command. If you set conf[:time_fmt]
-  #   to a empty string only a newline will be appended.
+  # @note The output of the command "time -f conf\[:time_fmt\]" will be
+  #   appended to the '.out' file of every command. If you set
+  #   conf\[:time_fmt\] to a empty string only a newline will be appended.
   def self.batch(commands, conf)
     # Throw exceptions if required configurations aren't provided.
-    fail "conf[:cpus_available] not set" unless conf[:cpus_available]
-    fail "conf[:timeout] not set" unless conf[:timeout]
+    fail 'conf[:cpus_available] not set' unless conf[:cpus_available]
+    fail 'conf[:timeout] not set' unless conf[:timeout]
 
     # Initialize optional configurations with default values if they weren't
     # provided. Don't change the conf argument, only our version of conf.
@@ -108,7 +108,7 @@ module BatchExperiment
     conf[:err_ext]          ||= '.err'
     conf[:busy_loop_sleep]  ||= 0.1
     conf[:post_timeout]     ||= 5
-    conf[:fname_sanitizer]  ||= BatchExperiment::FilenameSanitizer.new
+    conf[:fname_sanitizer]  ||= BatchExperiment::FilenameSanitizer
     conf[:skip_done_comms]    = true if conf[:skip_done_comms].nil?
 
     # Initialize main variables
@@ -227,7 +227,7 @@ module BatchExperiment
   #   command [String] A string with a sh shell command.
   #   pattern [String] A substring of command, will be replace by the strings
   #   in the paramenter 'files'.
-  #   extractor [Extractor] An object that implements the Extractor interface.
+  #   extractor [#extract,#names] Object implementing the Extractor interface.
   #   prefix [String] A string that will be used to prefix the extractor.names
   #   when they are used as column names. Improves Extractor reusability.
   # @param batch_conf [Hash] Configuration used to call batch. See the
@@ -266,7 +266,8 @@ module BatchExperiment
   # @return [NilClass,Array<String>] The return of the internal #batch
   #   call. Returns nil if conf[:skip_commands] was set to true.
   #
-  # @see BatchExperiment.batch
+  # @see BatchExperiment::batch
+  # @note This command call ::batch internally.
   def self.experiment(comms_info, batch_conf, conf, files)
     # Throw exceptions if required configurations aren't provided.
     fail 'conf[:csvfname] is not defined' unless conf[:csvfname]
@@ -283,7 +284,7 @@ module BatchExperiment
     out_ext = batch_conf[:out_ext] || '.out'
     unfinished_ext = batch_conf[:unfinished_ext] || '.unfinished'
     fname_sanitizer   = batch_conf[:fname_sanitizer]
-    fname_sanitizer ||= BatchExperiment::FilenameSanitizer.new
+    fname_sanitizer ||= BatchExperiment::FilenameSanitizer
 
     # Create commands the templates and the file list.
     comms_sets = []
@@ -291,7 +292,7 @@ module BatchExperiment
       comms_sets << gencommff(comm_info[:command], comm_info[:pattern], files)
     end
 
-    comm_list = conf[:ic_comm] ? intercalate(comms_sets) : comms_sets.flatten
+    comm_list = conf[:ic_comms] ? intercalate(comms_sets) : comms_sets.flatten
 
     # Execute the commands (or not).
     ret = batch(comm_list, batch_conf) unless conf[:skip_commands]
@@ -313,7 +314,7 @@ module BatchExperiment
       line = []
       comms_info.each_with_index do | comm_info, i |
         command =
-          if conf[:ic_comm]
+          if conf[:ic_comms]
             comm_list[(j * comms_info.size) + i]
           else
             comm_list[(i * files.size) + j]

data/lib/batch_experiment/extractor.rb

@@ -1,29 +1,69 @@
-module Extractor
-  # For when there's a field whose value is after '<field>: '.
-  def self.get_field(lines, field)
-    lines.grep(/^#{field}: .*/).each { | l | return l.match(/:[\t ]+(.*)/)[1] }
-    ''
-  end
+module BatchExperiment
+  # Module that defines the interface used for extracting info from other
+  # programs output. You don't need to include it in your object, will suffice
+  # that the object (that you will use to extract info from the output) has the
+  # ::names and ::extract methods defined.
+  module Extractor
+    # Find a line in the following format: "field: value", return value. 
+    #
+    # @param lines [Array<String>] Program output, broken in lines.
+    # @param field [String] String to be found at the lines in the following
+    # pattern: 'field: value'.
+    #
+    # @return [String] The 'value' as a string or, if 'field' isn't found, an
+    #   empty string.
+    def self.get_field(lines, field)
+      lines.grep(/^#{field}: .*/).each { | l | return l.match(/:[\t ]+(.*)/)[1] }
+      ''
+    end
 
-  # For when there's a field whose value is in the next line.
-  def self.get_hfield(lines, field)
-    if ix = lines.find_index(field) then lines[ix + 1] else '' end
-  end
+    # Find a line in the following format: "field<linebreak>value", return
+    # value.
+    #
+    # @param lines [Array<String>] Program output, broken in lines.
+    # @param field [String] String to be found at the lines in the following
+    #   pattern: 'field<lineabreak>value'. Only include the linebreak at the
+    #   field, if the lines array have linebreaks at the end of every string
+    #   element.
+    #
+    # @return [String] The 'value' as a string or, if 'field' isn't found, an
+    #   empty string.
+    def self.get_hfield(lines, field)
+      if ix = lines.find_index(field) then lines[ix + 1] else '' end
+    end
 
-  # Return the field names for each of the elements returned by
-  # extract. Ex.: ['Time', 'Max Mem Use', 'opt', ... ]
-  def names
-    fail 'This method should have been overwritten by a subclass.'
-  end
+    # Return the field names for each of the elements returned by extract. Ex.:
+    #   ['Time', 'Max Mem Use', 'opt', ... ]
+    # 
+    # @note To be on the safe side you should create a new array at each call.
+    #   If you always return a reference to the same array the array can be
+    #   modified.
+    #
+    # @return [Array<String>] The strings that will be used to make the column
+    #   names at the BatchExperiment.experiment method.
+    def names
+      fail 'This method should have been overwritten by a subclass.'
+    end
 
-  def extract(content)
-    extract_from_lines(content.lines.map! { | l | l.chomp! })
-  end
+    # Extract N values of some program output, where N is equal to #names.size.
+    # If some value isn't present, the array should remain the same size, and
+    # the value at the corresponding position should be nil.
+    # 
+    # @param content [String] Program output.
+    # @return [Array<String>] The N extracted values, as strings.
+    def extract(content)
+      extract_from_lines(content.lines.map! { | l | l.chomp! })
+    end
 
-  # Extract an array of values from the command output. This array has the same
-  # size as the one returned by field_names.
-  def extract_from_lines(lines)
-    fail 'This method should have been overwritten by a subclass.'
+    # Optionally, you can define this method instead of #extract. The #extract
+    # method will call this method if not overrided.
+    #
+    # @param lines [Array<String>] Program output, broken in lines,
+    #   and the line string elements don't end in linebreak.
+    # @return [Array<String>] The N extracted values, as strings.
+    def extract_from_lines(lines)
+      fail 'This method should have been overwritten by a subclass.'
+    end
   end
 end
 

data/lib/batch_experiment/sample_extractors.rb

@@ -1,49 +1,88 @@
-require 'require_relative'
-require_relative './extractor.rb'
+require 'batch_experiment/extractor'
 
-# Sample extractors used at https://github.com/henriquebecker91/masters, where
-# this code had its beggining. This file contains the code used to extract info
-# from the different outputs generated by UKP solving programs.
+module BatchExperiment
+  module FirstLineExtractor
+    extend Extractor
+    def self.names
+      ['first line', 'ext_time', 'ext_mem']
+    end
 
-class SampleExtractor
-  include Extractor
-  def names
-    ['first word', 'second word', 'ext_time', 'ext_mem']
+    def self.extract_from_lines(lines)
+      [ (lines[0] or ''),
+        Extractor.get_field(lines, 'ext_time'),
+        Extractor.get_field(lines, 'ext_mem')
+      ]
+    end
   end
 
-  def extract_from_lines(lines)
-    words = lines.empty? || lines[0].nil? ? ['',''] : lines[0].split().take(2)
-    words << Extractor.get_field(lines, 'ext_time')
-    words << Extractor.get_field(lines, 'ext_mem')
-    words
-  end
-end
+  module WcExtractor
+    extend Extractor
+    def self.names
+      ['lines', 'words', 'bytes', 'ext_time', 'ext_mem']
+    end
 
-class UKP5Extractor
-  include Extractor
-  def names
-    ['internal time', 'external time', 'external memory', 'opt']
+    def self.extract(content)
+      arr = content.split(' ')
+      qt_lines, words, bytes = arr[0], arr[1], arr[2]
+      lines = content.lines.map! { | l | l.chomp! }
+      [ qt_lines, words, bytes,
+        Extractor.get_field(lines, 'ext_time'),
+        Extractor.get_field(lines, 'ext_mem')
+      ]
+    end
   end
 
-  def extract_from_lines(lines)
-    ['Seconds', 'ext_time', 'ext_mem', 'opt'].map do | label |
-      Extractor.get_field(lines, label)
+  module TwoWordsExtractor
+    extend Extractor
+    def self.names
+      ['first word', 'second word', 'ext_time', 'ext_mem']
+    end
+
+    def self.extract_from_lines(lines)
+      words = lines.empty? || lines[0].nil? ? ['',''] : lines[0].split().take(2)
+      words << Extractor.get_field(lines, 'ext_time')
+      words << Extractor.get_field(lines, 'ext_mem')
+      words
     end
   end
-end
 
-class PyaExtractor
-  include Extractor
-  def names
-    ['internal time', 'external time', 'external memory', 'opt']
+  # Sample extractors used at https://github.com/henriquebecker91/masters,
+  # where this code had its beggining. This file contains the code used to
+  # extract info from the different outputs generated by UKP solving programs.
+
+  # Extractor for the output of the run_ukp5.out program available at
+  # https://github.com/henriquebecker91/masters. Not of interest for the
+  # majority of the users of this gem. Kept as example, and for this gem author
+  # personal use.
+  module UKP5Extractor
+    extend Extractor
+    def self.names
+      ['internal time', 'external time', 'external memory', 'opt']
+    end
+
+    def self.extract_from_lines(lines)
+      ['Seconds', 'ext_time', 'ext_mem', 'opt'].map do | label |
+        Extractor.get_field(lines, label)
+      end
+    end
   end
 
-  def extract_from_lines(lines)
-    values = ['Total Time ', 'ext_time', 'ext_mem'].map do | label |
-      Extractor.get_field(lines, label)
+  # Extractor for the output of the pyasukp program available at
+  # https://github.com/henriquebecker91/masters. Not of interest for the
+  # majority of the users of this gem. Kept as example, and for this gem author
+  # personal use.
+  class PyaExtractor
+    extend Extractor
+    def self.names
+      ['internal time', 'external time', 'external memory', 'opt']
+    end
+
+    def self.extract_from_lines(lines)
+      values = ['Total Time ', 'ext_time', 'ext_mem'].map do | label |
+        Extractor.get_field(lines, label)
+      end
+      opt_key = '#The optimal value for the given capacity'
+      values << Extractor.get_hfield(lines, opt_key)
     end
-    opt_key = '#The optimal value for the given capacity'
-    values << Extractor.get_hfield(lines, opt_key)
   end
 end
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: batch_experiment
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Henrique Becker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-18 00:00:00.000000000 Z
+date: 2016-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: childprocess
@@ -30,14 +30,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- examples/bible.txt
+- examples/example_batch.rb
 - examples/sample_batch.rb
+- examples/taoteching.txt
 - examples/ukp_batch.rb
 - lib/batch_experiment.rb
 - lib/batch_experiment/extractor.rb
 - lib/batch_experiment/sample_extractors.rb
 homepage: https://rubygems.org/gems/batch_experiment
 licenses:
-- Public Domain
 - Unlicense
 metadata: {}
 post_install_message: 
@@ -62,3 +64,4 @@ specification_version: 4
 summary: A ruby script that distributes system commands between cpu cores, and save
   their output.
 test_files: []
+has_rdoc: