rdf-isomorphic 0.0.1

data/AUTHORS

@@ -0,0 +1 @@
+* Ben Lavender <blavender@gmail.com> (Lead developer)

data/README

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

data/README.md

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

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/rdf/isomorphic.rb

@@ -0,0 +1,220 @@
+require 'digest/sha1'
+require 'rdf'
+
+
+module RDF
+  ##
+  # Isomorphism for rdf.rb Enumerables
+  #
+  # RDF::Isomorphic provides the functions isomorphic_with and bijection_to for RDF::Enumerable.
+  #
+  # @see http://rdf.rubyforge.org
+  # @see http://www.hpl.hp.com/techreports/2001/HPL-2001-293.pdf
+  module Isomorphic
+
+    # Returns `true` if this RDF::Enumerable is isomorphic with another.
+    # @return [Boolean]
+    # @example
+    #     repository_a.isomorphic_with repository_b #=> true
+    def isomorphic_with(other)
+      !(bijection_to(other).nil?)
+    end
+
+    alias_method :isomorphic?, :isomorphic_with
+    alias_method :isomorphic_with?, :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.
+    # @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
+      end
+
+      unless named_statements_match
+        nil
+      else
+        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)
+        build_bijection_to blank_stmts, nodes, other_blank_stmts, other_nodes
+      end
+    end
+
+    private
+
+    # The main recursive bijection algorithm.
+    #
+    # This algorithm is very similar to the one explained by Jeremy Carroll in
+    # http://www.hpl.hp.com/techreports/2001/HPL-2001-293.pdf. Page 12 has the
+    # relevant pseudocode.
+    #
+    # Many more comments are in the method itself.
+    # @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
+
+      # see variables above
+      bijection = {}
+      bijection_hashes = hashes.dup
+
+      # We are looking for nodes such that
+      # hashes[node] == hashes[some_other_node]
+      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
+        end
+        next unless tuple
+        target = tuple.first
+        bijection_hashes.delete target
+        bijection[node] = target
+      end
+
+      # This if is the return statement, believe it or not.
+      #
+      # 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
+        bijection = nil
+        nodes.each 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]
+            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))
+          end
+          break if bijection
+        end
+        bijection
+      end
+    end
+
+    # @private
+    # @return [RDF::Node]
+    # Blank nodes appearing in given list of statements
+    def blank_nodes_in(blank_stmt_list)
+      nodes = []
+      blank_stmt_list.each do | statement |
+        nodes << statement.object if statement.object.anonymous?
+        nodes << statement.subject if statement.subject.anonymous?
+      end
+      nodes.uniq
+    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
+    # node.  Creating the hash is simply hashing a sorted list of each
+    # statement's signature, which is itself a concatenation of the string form
+    # of all grounded elements.
+    #
+    # Nodes other than the given node are considered grounded if they are a
+    # member in the given hash.
+    #
+    # Returns a tuple consisting of grounded being true or false and the String
+    # for the hash
+    # @private
+    # @return [Boolean, String]
+    def 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.subject, statement.object].each do | resource |
+            grounded = false unless grounded(resource, hashes)
+          end
+        end
+      end
+      [grounded,Digest::SHA1.hexdigest(statement_signatures.sort.to_s)]
+    end
+
+    # Provide a string signature for the given statement.
+    # @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
+    end
+
+    # Returns true if a given node is grounded
+    # @private
+    def grounded(node, hashes)
+      (!(node.anonymous?)) || (hashes.member? node)
+    end
+
+    # Provides a string for the given node for use in a string signature
+    # @private
+    def string_for_node(node, hashes)
+      if node.anonymous?
+        if hashes.member? node
+          hashes[node]
+        else
+          ""
+        end
+      else
+        node.to_s
+      end
+    end
+  end
+
+
+
+  module Enumerable 
+    include RDF::Isomorphic
+  end
+end
+

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: rdf-isomorphic
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Ben Lavender
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-01 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdf
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !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"
+email: blavender@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- AUTHORS
+- README
+- UNLICENSE
+- VERSION
+- README.md
+- lib/rdf/isomorphic.rb
+has_rdoc: false
+homepage: http://rdf.rubyforge.org/
+licenses: 
+- Public Domain
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.2
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rdf-isomorphic
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Graph bijections and isomorphic equivalence for rdf.rb
+test_files: []
+