stamina 0.4.0 → 0.5.0

data/lib/stamina/induction/rpni.rb

@@ -1,186 +0,0 @@
-module Stamina
-  module Induction
-    
-    #
-    # Implementation of the standard Regular Positive and Negative Induction (RPNI) 
-    # algorithm. From a given sample, containing positive and negative strings, RPNI
-    # computes the smallest deterministic automaton compatible with the sample.
-    #
-    # See J. Oncina and P. Garcia, Infering Regular Languages in Polynomial Update
-    # Time, In N. Perez de la Blanca, A. Sanfeliu and E. Vidal, editors, Pattern
-    # Recognition and Image Analysis, volume 1 of Series in Machines Perception and
-    # Artificial Intelligence, pages 49-61, World Scientific, 1992.
-    #
-    # Example:
-    #   # sample typically comes from an ADL file
-    #   sample = Stamina::ADL.parse_sample_file('sample.adl')
-    #
-    #   # let RPNI build the smallest dfa
-    #   dfa = Stamina::Induction::RPNI.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.
-    # - 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 RPNI
-      include Stamina::Induction::Commons
-      
-      # Union-find data structure used internally
-      attr_reader :ufds
-      
-      # Creates an algorithm instance with given options.
-      def initialize(options={})
-        raise ArgumentError, "Invalid options #{options.inspect}" unless options.is_a?(Hash)
-        @options = DEFAULT_OPTIONS.merge(options)
-      end
-
-      #
-      # Merges a state of rank j with a state of lower rank i. This merge method 
-      # includes merging for determinization.
-      #
-      # 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 true and the refined union-find correctly encodes the 
-      #   quotient automaton. Otherwise, the method returns false and the union-find
-      #   information must be considered inaccurate.
-      #
-      def merge_and_determinize(i, j)
-        # Make the union (keep additional merges to be performed in determinization)
-        # and recompute the user data attached to the new state group (new_data)
-        determinization = []
-        @ufds.union(i, j) do |d1, d2|
-          new_data = merge_user_data(d1, d2, determinization)
-          return false unless new_data
-          new_data
-        end
-        
-        # Merge for determinization
-        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 or fail
-          return false unless merge_and_determinize(pair[0], pair[1]) 
-        end
-        
-        # Everything seems ok!
-        true
-      end
-      
-      #
-      # Makes a complete merge (including determinization), or simply do nothing if 
-      # it leads accepting a negative string.
-      #
-      # 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 true and the refined union-find correctly encodes the 
-      #   quotient automaton. Otherwise, the union find has not been changed.
-      #
-      def successfull_merge_or_nothing(i,j)
-        # try a merge and determinize inside a transaction on the ufds
-        @ufds.transactional do
-          merge_and_determinize(i, j)
-        end
-      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)
-        @ufds = ufds
-        info("Starting RPNI (#{@ufds.size} states)")
-        # First loop, iterating all PTA states
-        (1...@ufds.size).each do |i|
-          # we ignore those that have been previously merged
-          next if @ufds.slave?(i) 
-          # second loop: states of lower rank, with ignore
-          (0...i).each do |j|
-            next if @ufds.slave?(j)
-            # try to merge this pair, including determinization
-            # simply break the loop if it works!
-            success = successfull_merge_or_nothing(i,j)
-            if success
-              info("#{i} and #{j} successfully merged")
-              break
-            end
-          end # j loop
-        end # i loop
-        @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 RPNI.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
-        info("Creating PTA and UnionFind structure")
-        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={})
-        RPNI.new(options).execute(sample)
-      end
-      
-    end # class RPNI
-    
-  end # module Induction
-end # module Stamina

data/lib/stamina/induction/union_find.rb

@@ -1,377 +0,0 @@
-module Stamina
-  module Induction
-    
-    #
-    # Implements an UnionFind data structure dedicated to state merging induction algorithms.
-    # For this purpose, this union-find handles mergeable user data as well as transactional 
-    # support. See Stamina::Induction::Commons about the usage of this class (and mergeable 
-    # user data in particular) by induction algorithms.
-    #
-    # == Example (probably easier than a long explanation)
-    #
-    #   # create a union-find for 10 elements
-    #   ufds = Stamina::Induction::UnionFind.new(10) do |index|
-    #     # each element will be associated with a hash with data of interest:
-    #     # smallest element, greatest element and concatenation of names
-    #     {:smallest => index, :greatest => index, :names => index.to_s}
-    #   end
-    #
-    #   # each element is its own leader
-    #   puts (0...10).all?{|s| ufds.leader?(s)} -> true
-    #
-    #   # and their respective group number are the element indices themselve
-    #   puts ufds.to_a  -> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-    #
-    #   # now, let merge 4 with 0
-    #   ufds.union(0, 4) do |d0, d4|
-    #     {:smallest => d0[:smallest] < d4[:smallest] ? d0[:smallest] : d4[:smallest],
-    #      :greatest => d0[:smallest] > d4[:smallest] ? d0[:smallest] : d4[:smallest],
-    #      :names => d0[:names] + " " + d4[:names]}
-    #   end
-    #
-    #   # let see what happens on group numbers
-    #   puts ufds.to_a -> [0, 1, 2, 3, 0, 5, 6, 7, 8, 9]
-    #
-    #   # let now have a look on mergeable_data of the group of 0 (same result for 4)
-    #   puts ufds.mergeable_data(0).inspect -> {:smallest => 0, :greatest => 4, :names => "0 4"}
-    #
-    # == Basic Union Find API
-    #
-    # A UnionFind data structure typically allows encoding a partition of elements (a 
-    # partition is a collection of disjoint sets - aka a collection of groups). Basically, 
-    # this class represents elements by successive indices (from 0 to size, the later being 
-    # excluded). The partitioning information is kept in a array, associating a group number 
-    # to each element. This group number is simply the index of the least element in the 
-    # group (which means that group numbers are not necessarily consecutive). For example, 
-    # the following arrays maps to the associated partitions:
-    #
-    #   [0, 1, 2, 3, 4, 5] -> {{0}, {1}, {2}, {3}, {4}}
-    #   [0, 0, 0, 0, 0, 0] -> {{0, 1, 2, 3, 4, 5}}
-    #   [0, 1, 1, 0, 4, 4] -> {{0, 3}, {1, 2}, {5, 5}}
-    #
-    # The API of this basic union-find data structure is composed of the following 
-    # methods:
-    # - new(size) (class method): builds an initial partition information over _size_ 
-    #   elements. This initial partition keeps each element in its own group.
-    # - find(i): returns the group number of the i-th element
-    # - union(i, j): merge the group of the i-th element with the group of the j-th 
-    #   element. Note that i and j are elements, NOT group numbers.
-    #
-    # As we use least elements as group numbers, it is also interesting to know if a 
-    # given element is that least element (aka leader element of the group) or not:
-    #
-    # - leader?(i): returns true if i is the group number of the i-th element, false
-    #   otherwise. In other words, returns true if find(i)==i
-    # - slave?(i): the negation of leader?(i).
-    #
-    # == Handling User Data
-    #
-    # Even if this class represents elements by indices, it also allows keeping user 
-    # data attached to each group. For this:
-    #
-    # - an initial user data is attached to each element at construction time by 
-    #   yielding a block (passing the element index as first argument and expecting
-    #   user data as block return value).
-    # - the union(i, j) method allows a block to be given. It passes user data of i's
-    #   and j's groups as arguments and expects the block to compute and return the 
-    #   merged user data for the new group.
-    # - mergeable_data(i) returns the current user data associated to the group of 
-    #   the i-th element.
-    # - mergeable_datas returns an array with user data attached to each group.
-    #
-    # Please note that user data are considered immutable values, and should never be
-    # changed... Only new ones can be created at union time. To ensures this good usage,
-    # user data are freezed by this class at creation time and union time.
-    #
-    # == Transactional support
-    #
-    # The main aim of this UnionFind is to make the implementation induction algorithms 
-    # Stamina::Induction::RPNI and Stamina::Induction::BlueFringe (sufficiently) efficient, 
-    # simple and readable. These algorithms rely on a try-and-error strategy are must be
-    # able to revert the changes they have made during their last try. The transaction 
-    # support implemented by this data structure helps them achieving this goal. For this
-    # we provide the following methods:
-    #
-    # - save_point: ensures that the internal state of the UnionFind can be restored if
-    #   rollback is invoked later.
-    # - commit: informs the UnionFind that changes that have been made since the last
-    #   invocation of save_point will not be reconsidered.
-    # - rollback: restores the internal state of the UnionFind that has been saved when
-    #   save_point has been called.
-    #
-    # Please note that this class does not support sub-transactions.
-    #
-    class UnionFind
-      
-      #
-      # An element of the union find, keeping the index of its leader element as well as 
-      # mergeable user data. This class is not intended to be used by external users of the 
-      # UnionFind data structure.
-      #
-      class Node
-        
-        # Index of the parent element (on the way to the leader)
-        attr_accessor :parent
-        
-        # Attached user data
-        attr_accessor :data 
-        
-        #
-        # Creates a default Node instance with a specific parent index and attached
-        # user data.
-        #
-        def initialize(parent, data)
-          @parent = parent
-          @data = data
-        end
-        
-        #
-        # Duplicates this node, ensuring that future changes will not affect the copy. 
-        # Please note that the user data itself is not duplicated and is not expected 
-        # to change. This property (not changing user data) is respected by the RPNI
-        # and BlueFringe classes as implemented in this library.
-        #
-        def dup
-          Node.new(@parent, @data)
-        end
-        
-      end # class Node
-      
-      #
-      # Number of elements in this union find
-      #
-      attr_reader :size
-      
-      #
-      # (protected) Accessor on elements array, provided for duplication
-      #
-      attr_writer :elements
-      
-      #
-      # Creates a default union find of a given size. Each element is initially in its own 
-      # group. User data attached to each group is obtained by yielding a block, passing 
-      # element index as first argument.
-      #
-      # Precondition:
-      # - size is expected to be strictly positive
-      #
-      def initialize(size)
-        @size = size
-        @elements = (0...size).collect do |i| 
-          Node.new(i, block_given? ? yield(i).freeze : nil)
-        end
-        @changed = nil
-      end
-      
-      # Union Find API ###########################################################
-      
-      #
-      # Finds the group number of the i-th element (the group number is the least
-      # element of the group, aka _leader_).
-      #
-      # Preconditions:
-      # - i is a valid element: 0 <= i < size
-      #
-      # Postconditions:
-      # - returned value _found_ is such that <code>find(found)==found</code>
-      # - the union find data structure is not modified (no compression implemented).
-      #
-      def find(i)
-        while @elements[i].parent != i
-          i = @elements[i].parent
-        end
-        i
-      end
-      
-      #
-      # Merges groups of the i-th element and j-th element, yielding a block to compute
-      # the merging of user data attached to their respective groups before merging.
-      #
-      # Preconditions:
-      # - This method allows i and j not to be leaders, but any element.
-      # - i and j are expected to be valid elements (0 <= i <= size, same for j)
-      #
-      # Postconditions:
-      # - groups of i and j have been merged. All elements of the two subgroups have 
-      #   the group number defined as <code>min(find(i),find(j))</code> (before 
-      #   merging)
-      # - if a block is provided, the user data attached to the new group is computed by 
-      #   yielding the block, passing mergable_data(i) and mergable_data(j) as arguments.
-      #   The block is ecpected to return the merged data that will be kept for the new 
-      #   group.
-      # - If a transaction is pending, all required information is saved to restore
-      #   the union-find structure if the transaction is rollbacked later.
-      #
-      def union(i, j)
-        i, j = find(i), find(j)
-        reversed = false
-        i, j, reversed = j, i, true if j<i
-        
-        # Save i and j if in transaction and not already saved
-        if @changed
-          @changed[i] = @elements[i].dup unless @changed.has_key?(i)
-          @changed[j] = @elements[j].dup unless @changed.has_key?(j)
-        end
-        
-        # Make the changes now
-        @elements[j].parent = i
-        if block_given?
-          d1, d2 = @elements[i].data, @elements[j].data
-          d1, d2 = d2, d1 if reversed
-          @elements[i].data = yield(d1, d2).freeze
-        else
-          nil
-        end
-      end
-      
-      #
-      # Checks if an element is the leader of its group.
-      #
-      # Preconditions:
-      # - i is a valid element: 0 <= i < size
-      #
-      # Postconditions:
-      # - true if find(i)==i, false otherwise.
-      #
-      def leader?(i)
-        @elements[i].parent==i
-      end
-      
-      # 
-      # Checks if an element is a slave in its group (negation of leader?).
-      #
-      # Preconditions:
-      # - i is a valid element: 0 <= i < size
-      #
-      # Postconditions:
-      # - false if find(i)==i, true otherwise.
-      #
-      def slave?(i)
-        @elements[i].parent != i
-      end
-      
-      # UserData API #############################################################
-      
-      #
-      # Returns the mergeable data of each group in an array. No order of the
-      # groups is ensured by this method.
-      #
-      def mergeable_datas
-        indices = (0...size).select {|i| leader?(i)}
-        indices.collect{|i| @elements[i].data}
-      end
-      
-      #
-      # Returns the mergeable data attached to the group of the i-th element.
-      #
-      # Preconditions:
-      # - This method allows i not to be leader, but any element.
-      # - i is a valid element: 0 <= i < size
-      #
-      def mergeable_data(i)
-        @elements[find(i)].data
-      end
-      
-      # Transactional API ########################################################
-      
-      #
-      # Makes a save point now. Internally ensures that future changes will be 
-      # tracked and that a later rollback will restore the union find to the 
-      # internal state it had before this call. This method should not be called
-      # if a transaction is already pending.
-      #
-      def save_point
-        @changed = {}
-      end
-      
-      #
-      # Terminates the pending transaction by commiting all changes that have been 
-      # done since the last save_point call. This method should not be called if no
-      # transaction is pending.
-      #
-      def commit
-        @changed = nil
-      end
-      
-      #
-      # Rollbacks all changes that have been done since the last save_point call.
-      # This method will certainly fail if no transaction is pending.
-      #
-      def rollback
-        @changed.each_pair do |index, node|
-          @elements[index] = node
-        end
-        @changed = nil
-      end
-      
-      # 
-      # Makes a save point, yields the block. If it returns false or nil, rollbacks 
-      # the transaction otherwise commits it. This method is a nice shortcut for
-      # the following piece of code
-      #
-      #   ufds.save_point
-      #   if try_something
-      #     ufds.commit
-      #   else
-      #     ufds.rollback
-      #   end
-      #
-      # which can also be expressed as:
-      #
-      #   ufds.transactional do
-      #     try_something
-      #   end
-      #
-      # This method returns the value returned by the block
-      #
-      def transactional
-        save_point
-        returned = yield
-        if returned.nil? or returned == false
-          rollback
-        else
-          commit
-        end
-        returned
-      end
-      
-      # Common utilities #########################################################
-      
-      #
-      # Duplicates this data-structure, ensuring that no change on self or on the 
-      # copy is shared. Please note that user datas themselve are not duplicated as 
-      # they are considered immutable values (and freezed at construction and union).
-      #
-      def dup
-        copy = UnionFind.new(size)
-        copy.elements = @elements.collect{|e| e.dup}
-        copy
-      end
-      
-      #
-      # Returns the partitioning information as as array with the group number of 
-      # each element.
-      #
-      def to_a
-        (0...size).collect{|i| find(i)}
-      end
-      
-      #
-      # Returns a string representation of this union find information.
-      #
-      def to_s
-        @elements.to_s
-      end
-      
-      #
-      # Returns a string representation of this union find information.
-      #
-      def inspect
-        @elements.to_s
-      end
-      
-      protected :elements=
-    end # class UnionFind
-    
-  end # module Induction
-end # module Stamina