stamina-induction 0.5.0

data/lib/stamina-induction/stamina/induction/commons.rb

@@ -0,0 +1,156 @@
+module Stamina
+  module Induction
+
+    #
+    # Defines common utilities used by rpni and blue_fringe. About acronyms:
+    # - _pta_ stands for Prefix Tree Acceptor
+    # - _ufds_ stands for Union-Find Data Structure
+    #
+    # Methods pta2ufds 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 ufds2dfa 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
+
+      DEFAULT_OPTIONS = {
+        :verbose    => false,
+        :verbose_io => $stderr
+      }
+
+      # Additional options of the algorithm
+      attr_reader :options
+
+      # Is the verbose mode on ?
+      def verbose?
+        @verbose ||= !!options[:verbose]
+      end
+
+      def verbose_io
+        @verbose_io ||= options[:verbose_io] || $stderr
+      end
+
+      # Display an information message (when verbose)
+      def info(msg)
+        if verbose?
+          verbose_io << msg << "\n"
+          verbose_io.flush
+        end
+      end
+
+      #
+      # 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)
+        sample.to_pta
+      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/stamina/induction/rpni.rb

@@ -0,0 +1,186 @@
+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/stamina/induction/union_find.rb

@@ -0,0 +1,377 @@
+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