rdf-isomorphic 0.0.1 → 0.1.1

data/AUTHORS

@@ -1 +1,2 @@
 * Ben Lavender <blavender@gmail.com> (Lead developer)
+* Arto Bendiken <arto.bendiken@gmail.com>

data/README

@@ -1,7 +1,7 @@
 # RDF Isomorphism
 
-Provides RDF Isomorphism functionality for RDF.rb RDF::Enumerables.  That
-includes RDF::Repository, RDF::Graph, query results, and more.
+This is an RDF.rb plugin for RDF Isomorphism functionality for RDF::Enumerables.
+That includes RDF::Repository, RDF::Graph, query results, and more.
 
 For more information about RDF.rb, see <http://rdf.rubyforge.org>
 
@@ -9,42 +9,46 @@ For more information about RDF.rb, see <http://rdf.rubyforge.org>
 
     require 'rdf/isomorphic'
     require 'rdf/ntriples'
+
+
     a = RDF::Repository.load './tests/isomorphic/test1/test1-1.nt'
     a.first
-    => < RDF::Statement:0xd344c4(<http://example.org/a> <http://example.org/prop> <_:abc> .) >
+    # < RDF::Statement:0xd344c4(<http://example.org/a> <http://example.org/prop> <_:abc> .) >
     
     b = RDF::Repository.load './tests/isomorphic/test1/test1-2.nt'
     b.first
-    => < RDF::Statement:0xd3801a(<http://example.org/a> <http://example.org/prop> <_:testing> .) >
+    # < RDF::Statement:0xd3801a(<http://example.org/a> <http://example.org/prop> <_:testing> .) >
 
     a.isomorphic_with? b
-    => true
+    # true
+
     a.bijection_to b
-    => { #<RDF::Node:0xd345a0(_:abc)>=>#<RDF::Node:0xd38574(_:testing)> }
+    # { #<RDF::Node:0xd345a0(_:abc)>=>#<RDF::Node:0xd38574(_:testing)> }
+
 
 ## Algorithm
 
-More discussion on the algorithm used will be in a forthcoming blog post, but
-it is very similar to the one described by Jeremy Carroll in
-<http://www.hpl.hp.com/techreports/2001/HPL-2001-293.pdf>.
+The algorithm used here is very similar to the one described by Jeremy Carroll
+in <http://www.hpl.hp.com/techreports/2001/HPL-2001-293.pdf>.  See
+<http://blog.datagraph.org/2010/03/rdf-isomorphism>.
 
 Generally speaking, the Carroll algorithm is a very good fit for RDF graphs. It
 is a specialization of the naive factorial-time test for graph isomorphism,
-wherin non-anonymous RDF data lets us eliminate vast quantities of options well
+wherein non-anonymous RDF data lets us eliminate vast quantities of options well
 before we try them.  Pathological cases, such as graphs which only contain
-anonymous resources, will experience poor performance.
+anonymous resources, may experience poor performance.
 
 ### Equality
 
-Although it was considered to provide `==` to mean isomorphic, RDF isomorphism is a
-factorial-complexity problem and it seemed better to perhaps not overwrite such
-a commonly used method for that.  But it's really useful for specs in RDF
-libraries.  Try this:
+Although it was considered to provide `==` to mean isomorphic, RDF isomorphism
+can sometimes be a factorial-complexity problem and it seemed better to perhaps
+not overwrite such a commonly used method for that.  But it's really useful for
+specs in RDF libraries.  Try this in your tests:
 
     require 'rdf/isomorphic'
     module RDF
       module Isomorphic
-        alias_method :==, :isomorphic_with
+        alias_method :==, :isomorphic_with?
       end
     end
     
@@ -57,7 +61,8 @@ libraries.  Try this:
     end
 
 ### Information
- * Author: Ben Lavender <blavender@gmail.com>
+ * Author: Ben Lavender <blavender@gmail.com> - <http://bhuga.net>
+ * Author: Arto Bendiken <arto.bendiken@gmail.com> - <http://ar.to>
  * Source: <http://github.com/bhuga/RDF-Isomorphic>
  * Issues: <http://github.com/bhuga/RDF-Isomorphic/issues>
 
@@ -67,4 +72,6 @@ libraries.  Try this:
 
 ### "License"
 
-rdf-isomorphic is free and unemcumbered software in the public domain.  For more information, see the accompanying UNLICENSE file or <http://unlicense.org>
+rdf-isomorphic is free and unemcumbered software in the public domain.  For
+more information, see the accompanying UNLICENSE file or <http://unlicense.org>
+

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.1

data/lib/rdf/isomorphic.rb

@@ -16,39 +16,41 @@ module RDF
     # @return [Boolean]
     # @example
     #     repository_a.isomorphic_with repository_b #=> true
-    def isomorphic_with(other)
+    def isomorphic_with?(other)
       !(bijection_to(other).nil?)
     end
 
-    alias_method :isomorphic?, :isomorphic_with
-    alias_method :isomorphic_with?, :isomorphic_with
+    alias_method :isomorphic?, :isomorphic_with?
 
 
     # Returns a hash of RDF::Nodes => RDF::Nodes representing an isomorphic
-    # bijection of this RDF::Enumerable's blank nodes, or nil if a bijection
-    # cannot be found.
+    # bijection of this RDF::Enumerable's to another RDF::Enumerable's blank
+    # nodes, or nil if a bijection cannot be found.
     # @example
     #     repository_a.bijection_to repository_b
     # @param other [RDF::Enumerable]
     # @return [Hash, nil]
     def bijection_to(other)
-      named_statements_match = true
-      each_statement do |statement|
-        unless statement.has_blank_nodes?
-          named_statements_match = other.has_statement?(statement)
-        end
-        break unless named_statements_match
+
+      grounded_stmts_match = each_statement.all? do | stmt |
+        stmt.has_blank_nodes? || other.has_statement?(stmt)
       end
 
-      unless named_statements_match
-        nil
-      else
+      if grounded_stmts_match
+        # blank_stmts and other_blank_stmts are just a performance
+        # consideration--we could just as well pass in self and other.  But we
+        # will be iterating over this list quite a bit during the algorithm, so
+        # we break it down to the parts we're interested in.
         blank_stmts = find_all { |statement| statement.has_blank_nodes? }
         other_blank_stmts = other.find_all { |statement| statement.has_blank_nodes? }
-        nodes = blank_nodes_in(blank_stmts)
-        other_nodes = blank_nodes_in(other_blank_stmts)
+
+        nodes = RDF::Isomorphic.blank_nodes_in(blank_stmts)
+        other_nodes = RDF::Isomorphic.blank_nodes_in(other_blank_stmts)
         build_bijection_to blank_stmts, nodes, other_blank_stmts, other_nodes
+      else
+        nil
       end
+
     end
 
     private
@@ -60,90 +62,76 @@ module RDF
     # relevant pseudocode.
     #
     # Many more comments are in the method itself.
+    #
+    # @param [RDF::Enumerable]  anon_stmts
+    # @param [Array]            nodes
+    # @param [RDF::Enumerable]  other_anon_stmts
+    # @param [Array]            other_nodes
+    # @param [Hash]             these_grounded_hashes
+    # @param [Hash]             other_grounded_hashes
+    # @return [nil,Hash]
     # @private
-    def build_bijection_to(anon_stmts, nodes, other_anon_stmts, other_nodes, hashes = {})
-
-      # Some variable descriptions:
-      # anon_stmts, other_anon_stmts:  All statements from this and other with anonymous nodes
-      # nodes, other_nodes: All anonymous nodes from this and other
-      # hashes: hashes of signature of an anonymous nodes' relevant statements.  Only contains hashes for grounded nodes.
-      # potential_hashes: as hashes, but not limited to grounded nodes
-      # bijection: node => node mapping representing an anonymous node bijection
-      # bijection_hashes: duplicate of hashes from which we remove hashes to make sure bijection is one to one
-     
-      # A grounded node, the difference between the contents of
-      # potential_hashes and hashes, is a node which has no ungrounded
-      # anonymous neighbors in a relevant statement.
-      potential_hashes = {}
-      [ [anon_stmts,nodes], [other_anon_stmts,other_nodes] ].each do | tuple |
-        hash_needed = true
-        while hash_needed 
-          hash_needed = false
-          tuple.last.each do | node |
-            unless hashes.member? node
-              grounded, hash = node_hash_for(node, tuple.first, hashes) unless hashes.member? node
-              if grounded
-                hash_needed = true
-                hashes[node] = hash
-              end
-              potential_hashes[node] = hash
-            end
-          end
-        end
-      end
+    def build_bijection_to(anon_stmts, nodes, other_anon_stmts, other_nodes, these_grounded_hashes = {}, other_grounded_hashes = {})
+
+
+      # Create a hash signature of every node, based on the signature of
+      # statements it exists in.  
+      # We also save hashes of nodes that cannot be reliably known; we will use
+      # that information to eliminate possible recursion combinations.
+      # 
+      # Any mappings given in the method parameters are considered grounded.
+      these_hashes, these_ungrounded_hashes = RDF::Isomorphic.hash_nodes(anon_stmts, nodes, these_grounded_hashes)
+      other_hashes, other_ungrounded_hashes = RDF::Isomorphic.hash_nodes(other_anon_stmts, other_nodes, other_grounded_hashes)
 
-      # see variables above
-      bijection = {}
-      bijection_hashes = hashes.dup
 
-      # We are looking for nodes such that
-      # hashes[node] == hashes[some_other_node]
+      # Using the created hashes, map nodes to other_nodes
+      bijection = {}
       nodes.each do | node |
-        tuple = bijection_hashes.find do |k, v| 
-          (v == bijection_hashes[node]) && 
-          # eql? instead of include? since RDF.rb coincedentally-same-named identifiers will be ==
-          other_nodes.any? do | item | k.eql?(item) end
+        other_node, other_hash = other_hashes.find do | other_node, other_hash |
+          # we need to use eql?, as coincedentally-named bnode identifiers are == in rdf.rb
+          these_hashes[node].eql? other_hash
         end
-        next unless tuple
-        target = tuple.first
-        bijection_hashes.delete target
-        bijection[node] = target
+        next unless other_node
+        bijection[node] = other_node
+        
+        # we need to delete , as we don't want two nodes with the same hash
+        # to be mapped to the same other_node.
+        other_hashes.delete other_node
       end
 
-      # This if is the return statement, believe it or not.
+      # bijection is now a mapping of nodes to other_nodes.  If all are
+      # accounted for on both sides, we have a bijection.
       #
-      # First, is the anonymous node mapping 1 to 1?
-      # If so, we have a bijection and are done
-      if (bijection.keys.sort == nodes.sort) && (bijection.values.sort == other_nodes.sort)
-        bijection
-      # So we've got unhashed nodes that can't be definitively grounded.  Make
-      # a tentative bijection between two with identical ungrounded signatures
-      # in the graph and recurse.
-      else
+      # If not, we will speculatively mark pairs with matching ungrounded
+      # hashes as bijected and recurse.
+      unless (bijection.keys.sort == nodes.sort) && (bijection.values.sort == other_nodes.sort)
         bijection = nil
-        nodes.each do | node |
+        nodes.any? do | node |
+
           # We don't replace grounded nodes' hashes
-          next if hashes.member? node
-          bijectable = other_nodes.any? do | other_node |
-            # We don't replace grounded nodes' hashes
-            next if hashes.member? other_node
-            # The ungrounded signature must match for this pair to have a chance.
-            # If the signature doesn't match, skip it.
-            next unless potential_hashes[node] == potential_hashes[other_node]
+          next if these_hashes.member? node
+          other_nodes.any? do | other_node |
+
+            # We don't replace grounded other_nodes' hashes
+            next if other_hashes.member? other_node
+
+            # The ungrounded signature must match for this to potentially work
+            next unless these_ungrounded_hashes[node] == other_ungrounded_hashes[other_node]
+
             hash = Digest::SHA1.hexdigest(node.to_s)
-            test_hashes = { node => hash, other_node => hash}
-            bijection = build_bijection_to(anon_stmts, nodes, other_anon_stmts, other_nodes, hashes.merge(test_hashes))
+            bijection = build_bijection_to(anon_stmts, nodes, other_anon_stmts, other_nodes, these_hashes.merge( node => hash), other_hashes.merge(other_node => hash))
           end
-          break if bijection
+          bijection
         end
-        bijection
       end
+
+      bijection
     end
 
+    # Blank nodes appearing in given list of statements
     # @private
     # @return [RDF::Node]
-    # Blank nodes appearing in given list of statements
-    def blank_nodes_in(blank_stmt_list)
+    def self.blank_nodes_in(blank_stmt_list)
       nodes = []
       blank_stmt_list.each do | statement |
         nodes << statement.object if statement.object.anonymous?
@@ -151,7 +139,46 @@ module RDF
       end
       nodes.uniq
     end
- 
+
+    # Given a set of statements, create a mapping of node => SHA1 for a given
+    # set of blank nodes.  grounded_hashes is a mapping of node => SHA1 pairs
+    # that we will take as a given, and use those to make more specific
+    # signatures of other nodes.  
+    #
+    # Returns a tuple of hashes:  one of grounded hashes, and one of all
+    # hashes.  grounded hashes are based on non-blank nodes and grounded blank
+    # nodes, and can be used to determine if a node's signature matches
+    # another.
+    #
+    # @param [Array] statements 
+    # @param [Array] nodes
+    # @param [Hash] grounded_hashes
+    # @private
+    # @return [Hash, Hash]
+    def self.hash_nodes(statements, nodes, grounded_hashes)
+      hashes = grounded_hashes.dup
+      ungrounded_hashes = {}
+      hash_needed = true
+
+      # We may have to go over the list multiple times.  If a node is marked as
+      # grounded, other nodes can then use it to decide their own state of
+      # grounded.
+      while hash_needed 
+        hash_needed = false
+        nodes.each do | node |
+          unless hashes.member? node
+            grounded, hash = node_hash_for(node, statements, hashes)
+            if grounded
+              hash_needed = true
+              hashes[node] = hash
+            end
+            ungrounded_hashes[node] = hash
+          end
+        end
+      end
+      [hashes,ungrounded_hashes]
+    end
+
     # Generate a hash for a node based on the signature of the statements it
     # appears in.  Signatures consist of grounded elements in statements
     # associated with a node, that is, anything but an ungrounded anonymous
@@ -166,53 +193,64 @@ module RDF
     # for the hash
     # @private
     # @return [Boolean, String]
-    def node_hash_for(node,statements,hashes)
+    def self.node_hash_for(node,statements,hashes)
       statement_signatures = []
       grounded = true
       statements.each do | statement |
         if (statement.object == node) || (statement.subject == node)
-          statement_signatures << hash_string_for(statement,hashes)
+          statement_signatures << hash_string_for(statement,hashes,node)
           [statement.subject, statement.object].each do | resource |
-            grounded = false unless grounded(resource, hashes)
+            grounded = false unless grounded(resource, hashes) || resource == node
           end
         end
       end
+      # Note that we sort the signatures--without a canonical ordering, 
+      # we might get different hashes for equivalent nodes.
       [grounded,Digest::SHA1.hexdigest(statement_signatures.sort.to_s)]
     end
 
-    # Provide a string signature for the given statement.
+    # Provide a string signature for the given statement, collecting
+    # string signatures for grounded node elements.
+    # return [String]
     # @private
-    def hash_string_for(statement,hashes)
-      hash = ""
-      hash << string_for_node(statement.subject,hashes)
-      hash << statement.predicate.to_s
-      hash << string_for_node(statement.object,hashes)
-      hash
+    def self.hash_string_for(statement,hashes,node)
+      string = ""
+      string << string_for_node(statement.subject,hashes,node)
+      string << statement.predicate.to_s
+      string << string_for_node(statement.object,hashes,node)
+      string 
     end
 
     # Returns true if a given node is grounded
+    # A node is groundd if it is not a blank node or it is included
+    # in the given mapping of grounded nodes.
+    # @return [Boolean]
     # @private
-    def grounded(node, hashes)
+    def self.grounded(node, hashes)
       (!(node.anonymous?)) || (hashes.member? node)
     end
 
     # Provides a string for the given node for use in a string signature
+    # Non-anonymous nodes will return their string form.  Grounded anonymous
+    # nodes will return their hashed form.
+    # @return [String]
     # @private
-    def string_for_node(node, hashes)
-      if node.anonymous?
-        if hashes.member? node
+    def self.string_for_node(node, hashes,target)
+      case
+        when node == target
+          "itself"
+        when node.anonymous? && hashes.member?(node)
           hashes[node]
+        when node.anonymous?
+          "a blank node"
         else
-          ""
-        end
-      else
-        node.to_s
+          node.to_s
       end
     end
   end
 
 
-
+  # Extend RDF::Enumerables with these functions.
   module Enumerable 
     include RDF::Isomorphic
   end

metadata

@@ -1,48 +1,80 @@
 --- !ruby/object:Gem::Specification 
 name: rdf-isomorphic
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Ben Lavender
+- Arto Bendiken
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-02-01 00:00:00 +01:00
+date: 2010-03-12 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rdf
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
   type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rdf-spec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.0.9
-    version: 
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.2.9
-    version: 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: yard
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.5.2
-    version: 
-description: "    rdf-isomorphic provides bijections mapping blank nodes from one\n    RDF::Enumerable to another, and thus equivalence (isomorphism) testing.\n"
+        segments: 
+        - 0
+        - 5
+        - 3
+        version: 0.5.3
+  type: :development
+  version_requirements: *id004
+description: RDF.rb plugin for graph bijections and isomorphic equivalence.
 email: blavender@gmail.com
 executables: []
 
@@ -55,7 +87,6 @@ files:
 - README
 - UNLICENSE
 - VERSION
-- README.md
 - lib/rdf/isomorphic.rb
 has_rdoc: false
 homepage: http://rdf.rubyforge.org/
@@ -70,20 +101,24 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 2
       version: 1.8.2
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
-rubyforge_project: rdf-isomorphic
-rubygems_version: 1.3.5
+rubyforge_project: rdf
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: Graph bijections and isomorphic equivalence for rdf.rb
+summary: RDF.rb plugin for graph bijections and isomorphic equivalence.
 test_files: []
 

data/README.md

@@ -1,70 +0,0 @@
-# RDF Isomorphism
-
-Provides RDF Isomorphism functionality for RDF.rb RDF::Enumerables.  That
-includes RDF::Repository, RDF::Graph, query results, and more.
-
-For more information about RDF.rb, see <http://rdf.rubyforge.org>
-
-## Synopsis:
-
-    require 'rdf/isomorphic'
-    require 'rdf/ntriples'
-    a = RDF::Repository.load './tests/isomorphic/test1/test1-1.nt'
-    a.first
-    => < RDF::Statement:0xd344c4(<http://example.org/a> <http://example.org/prop> <_:abc> .) >
-    
-    b = RDF::Repository.load './tests/isomorphic/test1/test1-2.nt'
-    b.first
-    => < RDF::Statement:0xd3801a(<http://example.org/a> <http://example.org/prop> <_:testing> .) >
-
-    a.isomorphic_with? b
-    => true
-    a.bijection_to b
-    => { #<RDF::Node:0xd345a0(_:abc)>=>#<RDF::Node:0xd38574(_:testing)> }
-
-## Algorithm
-
-More discussion on the algorithm used will be in a forthcoming blog post, but
-it is very similar to the one described by Jeremy Carroll in
-<http://www.hpl.hp.com/techreports/2001/HPL-2001-293.pdf>.
-
-Generally speaking, the Carroll algorithm is a very good fit for RDF graphs. It
-is a specialization of the naive factorial-time test for graph isomorphism,
-wherin non-anonymous RDF data lets us eliminate vast quantities of options well
-before we try them.  Pathological cases, such as graphs which only contain
-anonymous resources, will experience poor performance.
-
-### Equality
-
-Although it was considered to provide `==` to mean isomorphic, RDF isomorphism is a
-factorial-complexity problem and it seemed better to perhaps not overwrite such
-a commonly used method for that.  But it's really useful for specs in RDF
-libraries.  Try this:
-
-    require 'rdf/isomorphic'
-    module RDF
-      module Isomorphic
-        alias_method :==, :isomorphic_with
-      end
-    end
-    
-    describe 'something' do
-      context 'does' do
-        it 'should be equal' do
-          repository_a.should == repository_b
-        end
-      end
-    end
-
-### Information
- * Author: Ben Lavender <blavender@gmail.com>
- * Source: <http://github.com/bhuga/RDF-Isomorphic>
- * Issues: <http://github.com/bhuga/RDF-Isomorphic/issues>
-
-### See also
- * RDF.rb: <http://rdf.rubyforge.org>
- * RDF.rb source: <http://github.com/bendiken/rdf>
-
-### "License"
-
-rdf-isomorphic is free and unemcumbered software in the public domain.  For more information, see the accompanying UNLICENSE file or <http://unlicense.org>