stamina 0.3.0

data/lib/stamina/command/redblue_command.rb

@@ -0,0 +1,58 @@
+require 'stamina/command/stamina_command'
+require 'stamina/induction/redblue'
+module Stamina
+  module Command
+    
+    # Implementation of the redblue command line tool
+    class RedBlueCommand < StaminaCommand
+    
+      # Creates a score command instance
+      def initialize
+        super("redblue", "[options] sample.adl",
+              "Executes RedBlue (Regular Positive and Negative Inference) on a ADL sample and\n"\
+              "flushes the induced DFA on the standard output in ADL format as well")
+      end
+      
+      # Installs additional options
+      def options
+        super do |opt|
+          opt.on("-v", "--verbose", "Verbose mode") do
+            @verbose = true
+          end
+          opt.on("-o", "--output=OUTPUT",
+                 "Flush induced DFA in output file") do |value|
+            assert_writable_file(value)
+            @output_file = value
+          end
+        end
+      end
+      
+      # Sets the sample file
+      def sample_file=(file)
+        assert_readable_file(file)
+        puts "Parsing sample and building PTA" if @verbose
+        @sample = Stamina::ADL.parse_sample_file(file)
+      rescue Stamina::ADL::ParseError
+        raise ArgumentError, "#{file} is not a valid ADL sample file"
+      end
+      
+      # Executes the command
+      def main(argv)
+        parse(argv, :sample_file)
+        t1 = Time.now
+        dfa = Stamina::Induction::RedBlue.execute(@sample, {:verbose => @verbose})
+        t2 = Time.now
+        if @output_file 
+          File.open(@output_file, 'w') do |file|
+            Stamina::ADL.print_automaton(dfa, file)
+          end
+        else
+          Stamina::ADL.print_automaton(dfa, STDOUT)
+        end          
+        puts "Executed in #{t2-t1} sec" if @verbose
+      end
+      
+    end # class ScoreCommand
+    
+  end # module Command
+end # module Stamina

data/lib/stamina/command/rpni_command.rb

@@ -0,0 +1,58 @@
+require 'stamina/command/stamina_command'
+require 'stamina/induction/rpni'
+module Stamina
+  module Command
+    
+    # Implementation of the rpni command line tool
+    class RPNICommand < StaminaCommand
+    
+      # Creates a score command instance
+      def initialize
+        super("rpni", "[options] sample.adl",
+              "Executes RPNI (Regular Positive and Negative Inference) on a ADL sample and\n"\
+              "flushes the induced DFA on the standard output in ADL format as well")
+      end
+      
+      # Installs additional options
+      def options
+        super do |opt|
+          opt.on("-v", "--verbose", "Verbose mode") do
+            @verbose = true
+          end
+          opt.on("-o", "--output=OUTPUT",
+                 "Flush induced DFA in output file") do |value|
+            assert_writable_file(value)
+            @output_file = value
+          end
+        end
+      end
+      
+      # Sets the sample file
+      def sample_file=(file)
+        assert_readable_file(file)
+        puts "Parsing sample and building PTA" if @verbose
+        @sample = Stamina::ADL.parse_sample_file(file)
+      rescue Stamina::ADL::ParseError
+        raise ArgumentError, "#{file} is not a valid ADL sample file"
+      end
+      
+      # Executes the command
+      def main(argv)
+        parse(argv, :sample_file)
+        t1 = Time.now
+        dfa = Stamina::Induction::RPNI.execute(@sample, {:verbose => @verbose})
+        t2 = Time.now
+        if @output_file 
+          File.open(@output_file, 'w') do |file|
+            Stamina::ADL.print_automaton(dfa, file)
+          end
+        else
+          Stamina::ADL.print_automaton(dfa, STDOUT)
+        end          
+        puts "Executed in #{t2-t1} sec" if @verbose
+      end
+      
+    end # class ScoreCommand
+    
+  end # module Command
+end # module Stamina

data/lib/stamina/command/stamina_command.rb

@@ -0,0 +1,79 @@
+require 'stamina'
+require 'optparse'
+module Stamina
+  module Command
+    
+    # Helper to create stamina commands
+    class StaminaCommand
+      
+      # Command name
+      attr_reader :name
+      
+      # Command description
+      attr_reader :description
+      
+      # Command usage
+      attr_reader :usage
+      
+      # Creates a command with a name, usage and description
+      def initialize(name, usage, description)
+        @name = name
+        @usage = usage
+        @description = description
+      end
+      
+      # Creates options
+      def options(&block)
+        OptionParser.new do |opt|
+          opt.program_name = name
+          opt.version = Stamina::VERSION
+          opt.release = nil
+          opt.summary_indent = ' ' * 4
+          banner = <<-EOF
+            # usage: #{opt.program_name} #{usage}
+            # #{description}
+          EOF
+          opt.banner = banner.gsub(/[ \t]+# /, "")
+          block.call(opt) if block
+          opt.on_tail("-h", "--help", "Show this message") do
+            puts opt
+            exit
+          end
+        end
+      end
+      
+      # Prints usage (and optionnaly exits)
+      def show_usage(and_exit=true)
+        puts options
+        Kernel.exit if and_exit
+      end
+      
+      # Checks that a given file is readable or raises an ArgumentError
+      def assert_readable_file(file)
+        raise ArgumentError, "File #{file} does not exists" unless File.exists?(file)
+        raise ArgumentError, "File #{file} cannot be read" unless File.readable?(file)
+      end
+      
+      # Checks that a given file is writable or raises an ArgumentError
+      def assert_writable_file(file)
+        raise ArgumentError, "File #{file} cannot be written" \
+          unless not(File.exists?(file)) or File.writable?(file)
+      end
+      
+      # Parses arguments and install last argument as instance variables
+      def parse(argv, *variables)
+        rest = options.parse(argv)
+        show_usage(true) unless rest.size==variables.size
+        variables.each_with_index do |var,i|
+          self.send("#{var}=".to_sym, rest[i])
+        end
+      rescue ArgumentError => ex
+        puts ex.message
+        puts
+        show_usage(true)
+      end
+      
+    end # class StaminaCommand
+    
+  end # module Command
+end # module Stamina

data/lib/stamina/errors.rb

@@ -0,0 +1,20 @@
+module Stamina
+  
+  # Main class of all stamina errors.
+  class StaminaError < StandardError; end
+  
+  # Raised by samples implementations and other induction algorithms
+  # when a sample is inconsistent (same string labeled as being both 
+  # positive and negative)
+  class InconsistencyError < StaminaError; end
+  
+  # Specific errors of the ADL module.
+  module ADL
+    
+    # Raised by the ADL module when an automaton, string or sample
+    # format is violated at parsing time.
+    class ParseError < StaminaError; end
+  
+  end
+
+end # module Stamina

data/lib/stamina/induction/commons.rb

@@ -0,0 +1,170 @@
+module Stamina
+  module Induction
+    
+    #
+    # Defines common utilities used by rpni and redblue. About acronyms: 
+    # - _pta_ stands for Prefix Tree Acceptor
+    # - _ufds_ stands for Union-Find Data Structure
+    #
+    # Methods pta2ufds, sample2pta and sample2ufds are simply conversion methods used
+    # when the induction algorithm starts (executed on a sample, it first built a pta 
+    # then convert it to a union find). Method ufds2pta is used when the algorithm ends, 
+    # to convert refined union find to a dfa.
+    #
+    # The merge_user_data method is probably the most important as it actually computes 
+    # the merging of two states and build information about merging for determinization.
+    #
+    module Commons
+      
+      #
+      # Factors and returns a UnionFind data structure from a PTA, keeping natural order 
+      # of its states for union-find elements. The resulting UnionFind contains a Hash as 
+      # mergeable user data, presenting the following keys:
+      # - :initial, :accepting and :error flags of each state
+      # - :master indicating the index of the state in the PTA
+      # - :delta a delta function through a Hash {symbol => state_index}
+      #
+      # In this version, other user data attached to PTA states is lost during the 
+      # conversion.
+      #
+      def pta2ufds(pta)
+        Stamina::Induction::UnionFind.new(pta.state_count) do |i|
+          state = pta.ith_state(i)
+          data = {:initial => state.initial?,
+                  :accepting => state.accepting?,
+                  :error => state.error?,
+                  :master => i,
+                  :delta => {}}
+          state.out_edges.each {|edge| data[:delta][edge.symbol] = edge.target.index}
+          data
+        end
+      end
+      
+      #
+      # Converts a Sample to an (augmented) prefix tree acceptor. This method ensures 
+      # that the states of the PTA are in lexical order, according to the <code><=></code>
+      # operator defined on symbols. States reached by negative strings are tagged as
+      # non accepting and error.
+      #
+      def sample2pta(sample)
+        Automaton.new do |pta|
+          initial_state = add_state(:initial => true, :accepting => false)
+
+          # Fill the PTA with each string
+          sample.each do |str|
+            # split string using the dfa
+            parsed, reached, remaining = pta.dfa_split(str, initial_state)
+      
+            # remaining symbols are not empty -> build the PTA
+            unless remaining.empty?
+              remaining.each do |symbol|
+                newone = pta.add_state(:initial => false, :accepting => false, :error => false)
+                pta.connect(reached, newone, symbol)
+                reached = newone
+              end
+            end
+      
+            # flag state      
+            str.positive? ? reached.accepting! : reached.error!
+            
+            # check consistency, should not arrive as Sample does not allow
+            # inconsistencies. Should appear only if _sample_ is not a Sample
+            # instance but some other enumerable.
+            raise(InconsistencyError, "Inconsistent sample on #{str}", caller)\
+              if (reached.error? and reached.accepting?)
+          end
+
+          # Reindex states by applying BFS
+          to_index, index = [initial_state], 0
+          until to_index.empty?
+            state = to_index.shift
+            state[:__index__] = index
+            state.out_edges.sort{|e,f| e.symbol<=>f.symbol}.each {|e| to_index << e.target} 
+            index += 1 
+          end
+          # Force the automaton to reindex
+          pta.order_states{|s0,s1| s0[:__index__]<=>s1[:__index__]}
+          # Remove marks
+          pta.states.each{|s| s.remove_mark(:__index__)}
+        end
+      end
+
+      #
+      # Converts a Sample instance to a 'ready to refine' union find data structure.
+      # This method is simply a shortcut for <code>pta2ufds(sample2pta(sample))</code>.
+      #
+      def sample2ufds(sample)
+        pta2ufds(sample2pta(sample))
+      end
+
+      # 
+      # Computes the quotient automaton from a refined UnionFind data structure.
+      #
+      # In this version, only accepting and initial flags are taken into account
+      # when creating quotient automaton states. Other user data is lost during 
+      # the conversion.
+      #
+      def ufds2dfa(ufds)
+        Automaton.new(false) do |fa|
+          mergeable_datas = ufds.mergeable_datas
+          mergeable_datas.each do |data|
+            state_data = data.reject {|key,value| [:master, :count, :delta].include?(key)}
+            state_data[:name] = data[:master].to_s
+            state_data[:error] = false
+            fa.add_state(state_data)
+          end
+          mergeable_datas.each do |data|
+            source = fa.get_state(data[:master].to_s)
+            data[:delta].each_pair do |symbol, target|
+              target = fa.get_state(ufds.find(target).to_s)
+              fa.connect(source, target, symbol)
+            end
+          end
+        end
+      end
+      
+      #
+      # Merges two user data hashes _d1_ and _d2_ according to rules defined
+      # below. Also fills a _determinization_ array with pairs of state indices
+      # that are reached from d1 and d2 through the same symbol and should be 
+      # merged for determinization. This method does NOT ensure that those pairs
+      # correspond to distinguish states according to the union find. In other
+      # words state indices in these pairs do not necessarily corespond to master
+      # states (see UnionFind for this term).
+      #
+      # Returns the resulting data if the merge is successful (does not lead to
+      # merging an error state with an accepting one), nil otherwise.
+      #
+      # The merging procedure for the different hash keys is as follows:
+      # - result[:initial]   =  d1[:initial]   or d2[:initial]
+      # - result[:accepting] =  d1[:accepting] or d2[:accepting]
+      # - result[:error]     =  d1[:error]     or d2[:error]
+      # - result[:master]    =  min(d1[:master], d2[:master])
+      # - result[:delta]     =  merging of delta hashes, keeping smaller target index 
+      #   on key collisions.
+      #
+      def merge_user_data(d1, d2, determinization)
+        # we compute flags first
+        new_data = {:initial => d1[:initial] || d2[:initial], 
+                    :accepting => d1[:accepting] || d2[:accepting],
+                    :error => d1[:error] || d2[:error],
+                    :master => d1[:master] < d2[:master] ? d1[:master] : d2[:master]}
+                
+        # merge failure if accepting and error states are merged
+        return nil if new_data[:accepting] and new_data[:error]
+                
+        # we recompute the delta function of the resulting state
+        # keeping merging for determinization as pairs in _determinization_
+        new_data[:delta] = d1[:delta].merge(d2[:delta]) do |symbol, t1, t2|
+          determinization << [t1, t2]
+          t1 < t2 ? t1 : t2
+        end
+        
+        # returns merged data
+        new_data
+      end
+      
+    end # module Commons
+    
+  end # module Induction
+end # module Stamina

data/lib/stamina/induction/redblue.rb

@@ -0,0 +1,264 @@
+module Stamina
+  module Induction
+    
+    #
+    # Implementation of the RedBlue variant of the RPNI algorithm (with the blue-fringe
+    # heuristics).
+    #
+    # See Lang, K., B. Pearlmutter, andR. Price. 1998. Results of the Abbadingo One DFA
+    # Learning Competition and a New Evidence-Driven State Merging Algorithm, In Grammatical 
+    # Inference, pp. 1–12. Ames, IO: Springer-Verlag.
+    #
+    # Example:
+    #   # sample typically comes from an ADL file
+    #   sample = Stamina::ADL.parse_sample_file('sample.adl')
+    #
+    #   # let RedBlue build the smallest dfa
+    #   dfa = Stamina::Induction::RedBlue.execute(sample, {:verbose => true})
+    #
+    # Remarks:
+    # - Constructor and instance methods of this class are public but not intended 
+    #   to be used directly. They are left public for testing purposes only.
+    # - Having read the Stamina::Induction::RedBlue base algorithm may help undertanding
+    #   this variant.
+    # - This class intensively uses the Stamina::Induction::UnionFind class and 
+    #   methods defined in the Stamina::Induction::Commons module which are worth
+    #   reading to understand the algorithm implementation.
+    #
+    class RedBlue
+      include Stamina::Induction::Commons
+      
+      # Union-find data structure used internally
+      attr_reader :ufds
+      
+      # Additional options of the algorithm
+      attr_reader :options
+      
+      #
+      # Creates an algorithm instance with specific options
+      #
+      def initialize(options={})
+        @options = options
+      end
+      
+      #
+      # Computes the score of a single (group) merge. Returned value is 1 if both are 
+      # accepting states or both are error states and 0 otherwise. Note that d1 and d2
+      # are expected to be merge compatible as this method does not distinguish this 
+      # case.  
+      #
+      def merge_score(d1, d2)
+        # Score of 1 if both accepting or both error
+        ((d1[:accepting] and d2[:accepting]) or (d1[:error] and d2[:error])) ? 1 : 0
+      end
+      
+      #
+      # Merges a state of rank j with a state of lower rank i. This merge method 
+      # includes merging for determinization. It returns nil if the merge is 
+      # incompatible, a merge score otherwise.
+      #
+      # Preconditions:
+      # - States denoted by i and j are expected leader states (non merged ones)
+      # - States denoted by i and j are expected to be different
+      #
+      # Postconditions:
+      # - Union find is refined, states i and j having been merged, as well as all
+      #   state pairs that need to be merged to ensure the deterministic property
+      #   of the quotient automaton.
+      # - If the resulting quotient automaton is consistent with the negative sample, 
+      #   this method returns the number of accepting pairs + the number of error pairs 
+      #   that have been merged. The refined union-find correctly encodes the quotient 
+      #   automaton. Otherwise, the method returns nil and the union-find information 
+      #   must be considered inaccurate.
+      #
+      def merge_and_determinize(i, j)
+        # Make the union (keep merging score as well as additional merges to be performed
+        # in score and determinization, respectively). Recompute the user data attached to 
+        # the new state group (new_data)
+        determinization, score = [], nil
+        @ufds.union(i, j) do |d1, d2|
+          # states are incompatible if new_data cannot be created because it would
+          # lead to merge and error and an accepting state. We simply return nil in this
+          # case...
+          return nil unless (new_data = merge_user_data(d1, d2, determinization))
+          # otherwise, we score
+          score = merge_score(d1, d2)
+          # and we let the union find keep the new_data for the group
+          new_data
+        end
+        
+        # Merge for determinization starts here, based on the determinization array
+        # computed as a side effect of merge_user_data
+        determinization.each do |pair|
+          # we take the leader states of the pair to merge
+          pair = pair.collect{|i| @ufds.find(i)} 
+          # do nothing if already the same leader state
+          next if pair[0]==pair[1]
+          # otherwise recurse and keep subscore
+          subscore = merge_and_determinize(pair[0], pair[1]) 
+          # failure if merging for determinization led to merge error and accepting 
+          # states
+          return nil if subscore.nil?
+          # this is the new score
+          score += subscore
+        end
+
+        score
+      end
+      
+      #
+      # Evaluates the score of merging states i and j. Returns nil if the states are
+      # cannot be merged, a positive score otherwise.
+      #
+      # Preconditions:
+      # - States denoted by i and j are expected leader states (non merged ones)
+      # - States denoted by i and j are expected to be different
+      #
+      # Postconditions:
+      # - Returned value is nil if the quotient automaton would be incompatible with 
+      #   the sample. Otherwise a positive number is returned, encoding the number of
+      #   interresting pairs that have been merged (interesting = both accepting or both
+      #   error)
+      # - The union find is ALWAYS restored to its previous value after merging has 
+      #   been evaluated and is then seen unchanged by the caller.
+      #
+      def merge_and_determinize_score(i, j)
+        # score the merging, always rollback the transaction
+        score = nil
+        @ufds.transactional do
+          score = merge_and_determinize(i, j)
+          false
+        end
+        score
+      end
+
+      #
+      # Computes the fringe given the current union find. The fringe is returned as an
+      # array of state indices.
+      #
+      # Postconditions:
+      # - Returned array contains indices of leader states only.
+      # - Returned array is disjoint with the kernel.
+      #
+      def fringe
+        fringe = []
+        @kernel.each do |k1|
+          delta = @ufds.mergeable_data(k1)[:delta]
+          delta.each_pair{|symbol, target| fringe << @ufds.find(target)}
+        end
+        (fringe - @kernel).sort
+      end
+      
+      #
+      # Main method of the algorithm. Refines the union find passed as first argument 
+      # by merging well chosen state pairs. Returns the refined union find.
+      #
+      # Preconditions:
+      # - The union find _ufds_ is correctly initialized (contains :initial, :accepting,
+      #   and :error boolean flags as well as a :delta sub hash)
+      #
+      # Postconditions:
+      # - The union find has been refined. It encodes a quotient automaton (of the PTA
+      #   it comes from) such that all positive and negative strings of the underlying
+      #   sample are correctly classified by it.
+      #
+      def main(ufds)
+        puts "Starting RedBlue (#{ufds.size} states)" if @options[:verbose]
+        @ufds, @kernel = ufds, [0]
+        
+        # we do it until the fringe is empty (compute it only once each step)
+        until (the_fringe=fringe).empty?
+          # state to consolidate (if any)
+          to_consolidate = nil
+          # best candidate [source index, target index, score]
+          best = [nil, nil, -1]
+          
+          # for each state on the fringe as merge candidate
+          the_fringe.each do |candidate|
+            to_consolidate = candidate
+            
+            # evaluate score of merging candidate with each kernel state
+            @kernel.each do |target|
+              score = merge_and_determinize_score(candidate, target)
+              unless score.nil?
+                # if a score has been found, the candidate will not be 
+                # consolidated. We keep it as best if its better than the
+                # previous one
+                to_consolidate = nil
+                best = [candidate, target, score] if score > best[2]
+              end
+            end
+            
+            # No possible target, break the loop (will consolidate right now)!
+            break unless to_consolidate.nil?
+          end
+          
+          # If not found, the last candidate must be consolidated. Otherwise, we 
+          # do the best merging
+          unless to_consolidate.nil?
+            puts "Consolidation of #{to_consolidate}" if @options[:verbose]
+            @kernel << to_consolidate
+          else
+            puts "Merging #{best[0]} and #{best[1]} [#{best[2]}]" if @options[:verbose]
+            # this one should never fail because its score was positive before
+            raise "Unexpected case" unless merge_and_determinize(best[0], best[1])
+          end
+          
+          # redblue does not guarantee that it will not merge a state of lower rank
+          # with a kernel state. The kernel should then be update at each step to keep
+          # lowest indices for the whole kernel, and we sort it
+          @kernel = @kernel.collect{|k| @ufds.find(k)}.sort
+        end
+        
+        # return the refined union find now
+        @ufds
+      end
+      
+      #
+      # Build the smallest DFA compatible with the sample given as input.
+      #
+      # Preconditions:
+      # - The sample is consistent (does not contains the same string both labeled as
+      #   positive and negative) and contains at least one string.
+      # 
+      # Postconditions:
+      # - The returned DFA is the smallest DFA that correctly labels the learning sample
+      #   given as input.
+      #
+      # Remarks:
+      # - This instance version of RedBlue.execute is not intended to be used directly and
+      #   is mainly provided for testing purposes. Please use the class variant of this 
+      #   method if possible.
+      #
+      def execute(sample)
+        # create union-find
+        puts "Creating PTA and UnionFind structure" if @options[:verbose]
+        ufds = sample2ufds(sample)
+        # refine it
+        ufds = main(ufds)
+        # compute and return quotient automaton
+        ufds2dfa(ufds)
+      end
+      
+      #
+      # Build the smallest DFA compatible with the sample given as input.
+      #
+      # Options (the _options_ hash):
+      # - :verbose can be set to true to trace algorithm execution on standard output.
+      #
+      # Preconditions:
+      # - The sample is consistent (does not contains the same string both labeled as
+      #   positive and negative) and contains at least one string.
+      # 
+      # Postconditions:
+      # - The returned DFA is the smallest DFA that correctly labels the learning sample
+      #   given as input.
+      #
+      def self.execute(sample, options={})
+        RedBlue.new(options).execute(sample)
+      end
+      
+    end # class RedBlue
+    
+  end # module Induction
+end # module Stamina