README

"fast_hammer" is a fast hamming distance calculator and synchronous SHA1
calculator for @engineyard's contest.

The latest version runs over 830,000 calculations per second on a single
core of a 2.2 GHz Core Duo running OS X 10.4.

If you have nvidia GPUs, you may be interested in using this instead:

    http://forums.nvidia.com/index.php?showtopic=102349

=======

License:  Use is governed by a two-clause BSD license.  Please see the
LICENSE file for details.

Note that the SHA1 code used by fast_hammer is in the public domain.

Prior to and during the contest, the license terms also required the
following tweet to be made to give me attribution:

    I'm using @cosine's fast_hammer for @engineyard's contest! http://tr.im/t35s

Since the close of the contest, only the two-clause BSD license terms
are required.

=======

Installation:

    gem install cosine-fast_hammer --source=http://gems.github.com/

=======

How to use:

The main entry point to fast_hammer is FastHammer.multi_sha1:

    require 'fast_hammer'
    require 'sha1'

    FastHammer.multi_sha1(
        SHA1.digest("string to compare hashed value to"),
        "prefix string with up to 12 words @engineyard provides",
        nil, nil, nil)
        # Last 3 arguments are not presently implemented, so are
        # ignored.

    Return value is a Hash:
        {
          :best_string => "prefix string with up to 12 words @engineyard provides ab123",
          :hamming_distance => 30
        }
        # The hash includes other key-value pairs that are non-sense
        # until more of the program is implemented.

    You can optionally pass FastHammer.multi_sha1 a block.  If you do
    the block is yielded to with a similar hash to that as above
    whenever there is a status update (i.e. a lower hamming distance has
    been found):

    FastHammer.multi_sha1(
        SHA1.digest("string to compare hashed value to"),
        "prefix string with up to 12 words @engineyard provides",
        nil, nil, nil) \
    do |update_hash|
      puts "New best string: #{update_hash[:best_string]}"
      puts "New best hammer: #{update_hash[:hamming_distance]}"
    end

The FastHammer.multi_sha1 method takes just under 3 hours to complete on
a 2.2 GHz CPU running OS X 10.4, where it was developed.

Another entry point into fast_hammer is the FastHammer.fast_hammer
method.  It just calculates the hamming distance between two hashes:

    FastHammer.fast_hammer(SHA1.digest("a"), SHA1.digest("b"))
    Return value is a Fixnum:  76