batch_experiment 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2281f50d62e17b6584f76c6ee3a06b15ad3f95e
-  data.tar.gz: 6e75c67a2776de460de325dff16620cf5e1297b4
+  metadata.gz: e1ffe7ede1b2dec3d9e0a7b6bdff96bf19a93e53
+  data.tar.gz: eb3c74ba400a0e67b71130853353465054877d3e
 SHA512:
-  metadata.gz: 697c5f3cb314baed7e726e03c9627d76c3cb5f47709d666d48169b9f9bb6f79bd4c3f713e10ab738bb35bd312fa5ab9be2cce290da0fc701ccbb2157fb09826a
-  data.tar.gz: de6fa0170a1d52371e9b5799432e9915f9e9256eb76c425a520a27e217e90fa6c0e3d3709212acf3b4b52fc6244a1c6ec9b06eac321e617f42caecf184452e23
+  metadata.gz: 21a826a0f697e447331c5d0f806d8688411f1bc43967d85f42ba60de3b36123e85f2f9191850bf6539b58dfeb7aa6004deb6383ba26d52f0ca7a1b6b8390fbef
+  data.tar.gz: a0ec49f73d2601aaefa16fbc580d723e46de2bbf500ecea22fad76a6b8691cc1ee9ea017ae4de7946ca5cd6c17d50fa585b836784cf1e58b2f6bbce7db6cab88

data/lib/batch_experiment/extractor.rb

@@ -8,7 +8,7 @@ module BatchExperiment
     #
     # @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'.
+    #   pattern: 'field: value'.
     #
     # @return [String] The 'value' as a string or, if 'field' isn't found, an
     #   empty string.

data/lib/batch_experiment/sample_extractors.rb

@@ -1,12 +1,17 @@
 require 'batch_experiment/extractor'
 
 module BatchExperiment
+  # A very simple sample extractor that extracts the first line of the
+  # command output, the run time and the memory usage (the last two are
+  # automatically added to any command output by ::batch and ::experiment).
   module FirstLineExtractor
     extend Extractor
+    # (see BatchExperiment::Extractor#names)
     def self.names
       ['first line', 'ext_time', 'ext_mem']
     end
 
+    # (see BatchExperiment::Extractor#extract_from_lines)
     def self.extract_from_lines(lines)
       [ (lines[0] or ''),
         Extractor.get_field(lines, 'ext_time'),
@@ -19,16 +24,19 @@ module BatchExperiment
   # where this code had its beggining. This file contains the code used to
   # extract info from the different outputs generated by UKP solving programs.
 
+  # @private
   # 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
+    # (see BatchExperiment::Extractor#names)
     def self.names
       ['internal time', 'external time', 'external memory', 'opt']
     end
 
+    # (see BatchExperiment::Extractor#extract_from_lines)
     def self.extract_from_lines(lines)
       ['Seconds', 'ext_time', 'ext_mem', 'opt'].map do | label |
         Extractor.get_field(lines, label)
@@ -36,16 +44,19 @@ module BatchExperiment
     end
   end
 
+  # @private
   # 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
+    # (see BatchExperiment::Extractor#names)
     def self.names
       ['internal time', 'external time', 'external memory', 'opt']
     end
 
+    # (see BatchExperiment::Extractor#extract_from_lines)
     def self.extract_from_lines(lines)
       values = ['Total Time ', 'ext_time', 'ext_mem'].map do | label |
         Extractor.get_field(lines, label)

data/lib/batch_experiment.rb

@@ -13,6 +13,12 @@ module BatchExperiment
   # multiple instances of the same command different names (by suffixing with
   # numbers).
   module FnameSanitizer
+    # Returns a copy of the argument where each sequence of non-alphanumeric
+    # characters were changed to one single underscore ('_'), remove
+    # trailing underscores at the beggining and the end of the string.
+    #
+    # @param command [String] A command to be sanitized.
+    # @return [String] The sanitized command.
     def self.call(command)
       fname = command.strip
       fname.gsub!(/[^[:alnum:]]/, '_')
@@ -64,20 +70,24 @@ module BatchExperiment
       fname.clone
     end
 
+    # Used to guarantee that a clone of Comm2FnameConverter will not
+    # share relevant state with the original. So calls to #call
+    # on a clone don't affect the state of original (and vice versa).
     def initialize_clone(old)
       @num_times_seen = old.num_times_seen.clone
     end
 
-    # To allow the initialize_clone implementation.
+    # Needed by the initialize_clone implementation.
     protected
     attr_reader :num_times_seen
   end
 
+  # @!visibility private
   # INTERNAL USE ONLY.
   # Remove any finished commands from comms_running, insert the cpus
   # freed by the commands termination to the free_cpus, insert the
   # terminated commands on comms_executed.
-  def self.update_finished(free_cpus, comms_running, comms_executed)
+  def self.update_finished(free_cpus, comms_running, comms_executed) #:nodoc
     comms_running.delete_if do | job |
       # Don't call '#exited?' twice, store value at variable. If you call
       # it twice it's possible to remove it from the list of running commands
@@ -92,64 +102,68 @@ module BatchExperiment
     end
   end
 
-  # 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
-  # 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). This '.unfinished' file will contain the process pid,
-  # if the corresponding process started with success.
+  # Execute a list of sh commands, one per specified core, kill them if the
+  # timeout expires, when a command ends (naturally or by timeout) put the
+  # next on the freed core, save all commands output to files.
+  #
+  # The output filenames are derived from the commands. The ones with '.out'
+  # are the ones with the command standard output. The analogue is valid for
+  # '.err' and standard error. Right before starting a command, a '.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). This '.unfinished' file
+  # will contain the process pid, if the corresponding process started with
+  # success.
   #
   # @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
-  #   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
-  #   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 command ended execution. This time will be very close to the max time a
-  #   cpu will remain vacant between two commands. Default: 0.1 (1/10 second).
-  #   -- 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.
-  #   -- converter [#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::Comm2FnameConverter.new.
-  #   -- 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 always
-  #   executed. If false, execute all commands and overwrite all ".out".
-  #   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'.
-  #   -- cwd [String] Command Working Directory. The path from where the
-  #   commands will be executed. Default: './' (i.e. the same directory from
-  #   where the ruby script was run).
-  #   -- output_dir [String] The folder used to save the
-  #   '.out'/'.err'/'.unfinished' files. Default: './' (i.e. the same directory
-  #   from where the ruby script was run).
+  #   * 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. Maybe you will want to disable hyperthreading.
+  #   * 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 command ended execution. This time will be very close to the max time
+  #     a cpu will remain vacant between two commands. Default: 0.1 (1/10
+  #     second).
+  #   * 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.
+  #   * converter [#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::Comm2FnameConverter.new.
+  #   * skip_done_comms [FalseClass,TrueClass] Skip any command for what a
+  #     corresponding '.out' file exists, except if both a '.out' and a
+  #     '.unfinished' file exists, in the last case the command is always
+  #     be executed. If false, execute all commands and overwrite any previous
+  #     outputs. 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'.
+  #   * cwd [String] Command Working Directory. The path from where the
+  #     commands will be executed. Default: './' (i.e. the same directory from
+  #     where the ruby script was run).
+  #   * output_dir [String] The folder used to save the output files.
+  #     Default: './' (i.e. the same directory from where the ruby script
+  #     was run).
   #
-  # @return [String] Which commands were executed. Can be different from
+  # @return [Array<String>] Which commands were executed. Can be different from
   #   the 'commands' argument if commands are skipped (see :skip_done_comms).
+  #   The order of this array will match the order of the argument one.
   #
   # @note If the same command is executed over the same file more than one
   #   time, then any run besides the first will have a numeric suffix.
-  #   Example: "sleep 1" -> "sleep_1", "sleep 1" -> "sleep_1.2".
-  #   For more info see the parameter conf\[:fname_sanitizer\], and its
+  #   Example: "sleep 1" -> "sleep_1.out", "sleep 1" -> "sleep_1.2.out".
+  #   For more info see the parameter conf's :fname_sanitizer, and its
   #   default value BatchExperiment::Comm2FnameConverter.new.
   # @note This procedure makes use of the following linux commands: time (not
   #   the bash internal one, but the package one, i.e.
@@ -159,9 +173,9 @@ 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
+  # @note The output of the command "time -f conf's :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.
+  #   conf's :time_fmt to an empty string only a newline will be appended.
   def self.batch(commands, conf)
     # Throw exceptions if required configurations aren't provided.
     if !conf[:cpus_available] then
@@ -256,7 +270,8 @@ module BatchExperiment
     comms_executed
   end
 
-  # INTERNAL USE ONLY. gencommff: GENerate COMMands For Files.
+  # @!visibility private
+  # gencommff: GENerate COMMands For Files.
   # Creates a hash with the generated commands as keys, and store (as the
   # respective value) the comm_info hash and the file (using a { comm_info: X,
   # filename: Y } structure).
@@ -267,7 +282,7 @@ module BatchExperiment
   #   comm_info[:pattern] at a copy of comm_info[:command].
   # @return [Hash<String, Hash>] A hash on the following format
   #   { expanded_command => { comm_info: comm_info, filename: f }, ...}
-  def self.gencommff(comm_info, files)
+  def self.gencommff(comm_info, files)  #:nodoc
     ret = {}
     comm = comm_info[:command]
     patt = comm_info[:pattern]
@@ -277,15 +292,15 @@ module BatchExperiment
     ret
   end
 
-  # INTERNAL USE ONLY. Intercalate a variable number of variable sized arrays
-  # in one array.
+  # @!visibility private
+  # Intercalate a variable number of variable sized arrays in one array.
   #
   # @param [Array<Array<Object>>] xss An array of arrays.
   # @return [Array<Object>] An array of the same size as the sum of the size
   #   of all inner arrays. The values are the same (not copies) as the values
   #   of the array. Example: intercalate([[1, 4, 6, 7], [], [2, 5], [3]])
   #   returns [1, 2, 3, 4, 5, 6, 7].
-  def self.intercalate(xss)
+  def self.intercalate(xss)  #:nodoc
     ret = []
     xss = xss.map { | xs | xs.reverse }
     until xss.empty? do
@@ -299,17 +314,26 @@ module BatchExperiment
     ret
   end
 
+  # Exception class raised when multiple extractor objects passed to
+  # ::experiment (by the comms_info parameter) disagree on the content of the
+  # columns. Ex.: If we call ::experiment with different extractor objects, all
+  # arrays returned by the #names method of those extractors should be equal or
+  # a prefix of the biggest array. Ex.: ['a', 'b'], ['a', 'b'], ['a'] and
+  # ['a', 'b', 'c'] works, but adding ['a', 'c'] will end the program with
+  # this exception. This is made to avoid making the mistake of generating a
+  # csv where the same column has a different meaning for each row.
   class ColumnSpecError < ArgumentError; end
 
-  # INTERNAL USE ONLY. Check if the headers can be combined, if they can
-  # return a shallow copy of the biggest header, otherwise throw an exception.
+  # @!visibility private
+  # Check if the headers can be combined, if they can return a shallow copy of
+  # the biggest header, otherwise throw an exception.
   #
-  # @param headers [Array<Array<Comparable>>] An array of arrays of strings
+  # @param headers [Array<Array<Object>>] An array of arrays of strings
   #   (or any object that implements '!=').
   # @return A shallow copy of the biggest inner array in headers. Only returns
   #   if for each position on the biggest inner array has the same value as
   #   that position on all the other arrays with at least that size.
-  def self.merge_headers(headers)
+  def self.merge_headers(headers)  #:nodoc
     mer_size = headers.map { | h | h.size }.max
     merged_h = Array.new(mer_size)
     mer_size.times do | i |
@@ -331,57 +355,56 @@ module BatchExperiment
     merged_h
   end
 
-  # Takes N shell commands and M files/parameters, execute each command of the
-  # N commands over the M files, save the output of each command/file
-  # combination, use objects provided with the command to extract relevant
-  # information from the output file, and group those information in a CSV
-  # file. Easier to understand seeing the sample_batch.rb example in action.
+  # Uses ::batch to execute N commands over M files Q times for each
+  # command/file, save their output, inspect their output using provided
+  # extractors, save the extracted data in a CSV file; easier to understand
+  # seeing the sample_batch.rb example in action.
   #
   # @param comms_info [Array<Hash>] An array of hashs, each with the config
   #   needed to know how to deal with the command. Four required fields
   #   (all keys are symbols):
-  #   command [String] A string with a sh shell command.
-  #   pattern [String] A substring of command, will be replaced by the strings
-  #   in the paramenter 'files'.
-  #   extractor [#extract,#names] Object implementing the Extractor interface.
-  #   prefix [String] A string that will be used on the 'algorithm' column
-  #   to identify the used command.
+  #   * command [String] A string with a sh shell command.
+  #   * pattern [String] A substring of command, will be replaced by the strings
+  #     in the paramenter 'files'.
+  #   * extractor [#extract,#names] Object implementing the Extractor interface.
+  #   * prefix [String] A string that will be used on the 'algorithm' column
+  #     to identify the used command.
   # @param batch_conf [Hash] Configuration used to call batch. See the
   #   explanation for parameter 'conf' on the documentation of the batch
   #   method. There are required fields for this hash parameter. Also, note
-  #   that the batch_conf\[:converter\] should allow cloning without sharing
+  #   that batch_conf's :converter should allow cloning without sharing
   #   mutable state. A converter clone is used by #experiment internally, it
   #   has to obtain the same results as the original copy (that is passed to
   #   BatchExperiment::batch).
   # @param conf [Hash] Lots of parameters. Here's a list:
-  #   -- csvfname [String] The filename/filepath for the file that will contain
-  #   the CSV data. Required field.
-  #   separator [String] The separator used at the CSV file. Default: ';'.
-  #   -- qt_runs [NilClass,Integer] If nil or one then each command is
-  #   executed once. If is a number bigger than one, the command is executed
-  #   that number of times. The batch_conf[:converter] will define the name
-  #   that will be given to each run. Every file will appear qt_runs times on
-  #   the filename column and, for the same file, the values on the run_number
-  #   column will be the integer numbers between 1 and qt_runs (both
-  #   inclusive). Default: nil.
-  #   -- comms_order [:by_comm,:by_file,:random] The order the
-  #   commands will be executed. Case by_comm: will execute the first command
-  #   over all the files (using the files order), then will execute the
-  #   second command over all files, and so on. Case by_file: will execute
-  #   all the commands (using the comms_info order) over the first file,
-  #   then will execute all the comands over the second file, and so on.
-  #   Case random: will expand all the command/file combinations (replicating
-  #   the same command qt_run times) and then will apply shuffle to this array,
-  #   using the object passed to the rng parameter. This last option is the
-  #   most adequate for statistical testing.
-  #   -- rng [Nil,#rand] An object that implements the #rand method (behaves
-  #   like an instance of the core Random class). If comms_order is random and
-  #   rng is nil, will issue a warning remembering the default that was used.
-  #   Default: Random.new(42).
-  #   skip_commands [TrueClass, FalseClass] If true, will not execute the
-  #   commands and assume that the outputs are already saved (on ".out" files).
-  #   Will only execute the extractors over the already saved outputs, and
-  #   create the CSV file from them. Default: false.
+  #   * csvfname [String] The filename/filepath for the file that will contain
+  #     the CSV data. Required field.
+  #   * separator [String] The separator used at the CSV file. Default: ';'.
+  #   * qt_runs [NilClass,Integer] If nil or one then each command is
+  #     executed once. If is a number bigger than one, the command is executed
+  #     that number of times. The batch_conf's :converter will define the name
+  #     that will be given to each run. Every file will appear qt_runs times on
+  #     the filename column and, for the same file, the values on the
+  #     run_number column will be the integer numbers between 1 and qt_runs
+  #     (both inclusive). Default: nil.
+  #   * comms_order [:by_comm,:by_file,:random] The order the
+  #     commands will be executed. Case by_comm: will execute the first command
+  #     over all the files (using the files order), then will execute the
+  #     second command over all files, and so on. Case by_file: will execute
+  #     all the commands (using the comms_info order) over the first file, then
+  #     will execute all the comands over the second file, and so on. Case
+  #     random: will expand all the command/file combinations (replicating the
+  #     same command qt_run times) and then will apply shuffle to this array,
+  #     using the object passed to the rng parameter. This last option is the
+  #     most adequate for statistical testing.
+  #   * rng [Nil,#rand] An object that implements the #rand method (behaves
+  #     like an instance of the core Random class). If comms_order is random
+  #     and rng is nil, will issue a warning remembering the default that was
+  #     used. Default: Random.new(42).
+  #   * skip_commands [TrueClass, FalseClass] If true, will not execute the
+  #     commands and assume that the outputs are already saved (on ".out"
+  #     files). Will only execute the extractors over the already saved
+  #     outputs, and create the CSV file from them. Default: false.
   #
   # @param files [Array<Strings>] The strings that will replace the :pattern
   #   on :command, for every element in comms_info. Can be a filename, or
@@ -389,10 +412,9 @@ module BatchExperiment
   #   refer to them as files for simplicity and uniformity.
   #
   # @return [NilClass,Array<String>] The return of the internal #batch
-  #   call. Returns nil if conf[:skip_commands] was set to true.
+  #   call. Returns nil if conf's :skip_commands was set to true.
   #
   # @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]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: batch_experiment
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Henrique Becker
@@ -45,7 +45,8 @@ licenses:
 - Unlicense
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--no-private"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -66,3 +67,4 @@ specification_version: 4
 summary: A ruby script that distributes system commands between cpu cores, and save
   their output.
 test_files: []
+has_rdoc: