Add maxnorm keyword argument to SignALSH constructor (partial fix to issue #2).

Author: kernelmethod

src/hashes/sign_alsh.jl

@@ -22,21 +22,39 @@ mutable struct SignALSH{T <: Union{Float32,Float64}} <: AsymmetricLSHFunction
     P_shift :: Vector{T}
     m :: Int64
 
+    # An upper bound on the norm of the data points this hash function will
+    # process
+    maxnorm :: T
+
     # Whether or not SignALSH should round up to the next power of 2 when
     # resizing its coefficient array.
     resize_pow2 :: Bool
 end
 
 ### External SignALSH constructors
-function SignALSH{T}(n_hashes::Integer;
-                     m::Integer = 3,
-                     resize_pow2::Bool = false) where {T}
-
-    coeff_A = Matrix{T}(undef, n_hashes, 0)
-    coeff_B = randn(T, n_hashes, m)
-    P_shift = coeff_B * fill(T(1/2), m)
-
-    SignALSH(coeff_A, coeff_B, P_shift, Int64(m), resize_pow2)
+@generated function SignALSH{T}(n_hashes::Integer = 1;
+                                maxnorm::Union{Nothing,Real} = nothing,
+                                m::Integer = 3,
+                                resize_pow2::Bool = false) where {T}
+
+    if maxnorm <: Nothing
+        :("maxnorm must be specified for SignALSH" |> ErrorException |> throw)
+    else
+        quote
+            if maxnorm < 0
+                "maxnorm must be non-negative" |> ErrorException |> throw
+            elseif m ≤ 0
+                "m must be positive" |> ErrorException |> throw
+            end
+
+            coeff_A = Matrix{T}(undef, n_hashes, 0)
+            coeff_B = randn(T, n_hashes, m)
+            P_shift = coeff_B * fill(T(1/2), m)
+
+            SignALSH(coeff_A, coeff_B, P_shift, Int64(m),
+                     T(maxnorm), resize_pow2)
+        end
+    end
 end
 
 SignALSH(args...; dtype=Float32, kws...) =
@@ -86,16 +104,23 @@ function SignALSH_P(hashfn::SignALSH{T}, x::AbstractArray{T}) where {T}
     # after dividing through x by the largest norm of all of the columns
     # of x.
     norms = col_norms(x)
-    maxnorm = maximum(norms)
-    maxnorm = maxnorm == 0 ? 1 : maxnorm	# To handle some edge cases
-    norms .*= 1/maxnorm
+
+    for norm_ii in norms
+        if norm_ii > hashfn.maxnorm
+            "norm $(norm_ii) exceeds hashfn.maxnorm ($(hashfn.maxnorm))" |>
+            ErrorException |>
+            throw
+        end
+    end
+
+    norms .*= 1/hashfn.maxnorm
 
     n = size(x,1)
     if n > current_max_input_size(hashfn)
         resize!(hashfn, n)
     end
 
-    Ax = @views hashfn.coeff_A[1:end,1:n] * x .* (1/maxnorm)
+    Ax = @views hashfn.coeff_A[1:end,1:n] * x .* (1/hashfn.maxnorm)
 
     # Perform the transformation P(x) on x, except that instead of actually
     # allocating memory for it and computing it, pile it onto Ax
@@ -157,6 +182,15 @@ function SignALSH_Q(hashfn::SignALSH{T}, x::AbstractArray{T}) where {T}
 
     Ax = @views hashfn.coeff_A[1:end,1:n] * x
     norms = col_norms(x)
+
+    for norm_ii in norms
+        if norm_ii > hashfn.maxnorm
+            "norm $(norm_ii) exceeds hashfn.maxnorm ($(hashfn.maxnorm))" |>
+            ErrorException |>
+            throw
+        end
+    end
+
     map!(inv, norms, norms)
     @. Ax * norms' ≥ T(0)
 end

test/hashes/test_sign_alsh.jl

@@ -8,6 +8,28 @@ Tests
 @testset "SignALSH tests" begin
     Random.seed!(RANDOM_SEED)
 
+    @testset "Construct SignALSH" begin
+        hashfn = SignALSH(; maxnorm=1)
+        @test n_hashes(hashfn) == 1
+        @test isa(hashfn, SignALSH{Float32})
+        @test isa(hashfn, LSH.AsymmetricLSHFunction)
+        @test hashtype(hashfn) == BitArray{1}
+
+        hashfn = SignALSH(32; maxnorm=1)
+        @test n_hashes(hashfn) == 32
+
+        hashfn = SignALSH(; dtype=Float64, maxnorm=1)
+        @test isa(hashfn, SignALSH{Float64})
+
+        # maxnorm must be specified and non-negative
+        @test_throws ErrorException SignALSH()
+        @test_throws ErrorException SignALSH(; maxnorm=-1)
+
+        # m must be positive
+        @test_throws ErrorException SignALSH(; m=-1)
+        @test_throws ErrorException SignALSH(; m=0)
+    end
+
     @test_skip @testset "Can hash inputs correctly with SignALSH" begin
         input_length = 5
         n_hashes = 8
@@ -45,22 +67,33 @@ Tests
         @test simhash(Qx) == qhashes
     end
 
-    @testset "SignALSH generates collisions for large inner products" begin
-        input_length = 5; n_hashes = 128;
-        hashfn = SignALSH(n_hashes)
+    @testset "SignALSH can't hash inputs of norm > maxnorm" begin
+        hashfn = SignALSH(; maxnorm=0)
+        @test_throws ErrorException index_hash(hashfn, rand(4))
+        @test_throws ErrorException query_hash(hashfn, rand(4))
 
-        x = randn(input_length)
-        x_query_hashes = query_hash(hashfn, x)
+        # Should have no issue if norm(x) == maxnorm
+        @test index_hash(hashfn, zeros(4)) |> length == 1
+        @test query_hash(hashfn, zeros(4)) |> length == 1
+    end
 
-        # Check that SignALSH isn't just generating a single query hash
-        @test any(x_query_hashes .!= x_query_hashes[1])
+    @testset "SignALSH generates collisions for large inner products" begin
+        input_length = 5; n_hashes = 128;
 
-        # Compute the indexing hashes for a dataset with four vectors:
-        # a) 10 * x (where x is the test query vector)
+        # Compare a random vector x against four other vectors:
+        # a) 10 * x
         # b) x
         # c) A vector of all zeros
         # d) -x
-        dataset = [(10*x) x zeros(input_length) -x]
+        x = randn(input_length)
+        x2, x3, x4 = 10*x, zero(x), -x
+
+        maxnorm = (x, x2, x3, x4) .|> norm |> maximum
+        hashfn = SignALSH(n_hashes; maxnorm=maxnorm)
+
+        x_query_hashes = query_hash(hashfn, x)
+
+        dataset = [x2 x x3 x4]
         p_hashes = index_hash(hashfn, dataset)
 
         # Each collection of hashes should be different from one another
@@ -85,7 +118,7 @@ Tests
         n_inputs = 150
         n_hashes = 2
 
-        hashfn = SignALSH(n_hashes)
+        hashfn = SignALSH(n_hashes; maxnorm=4*input_size)
         x = sprandn(input_size, n_inputs, 0.2)
 
         # Mostly just need to test that the following lines don't crash
@@ -100,7 +133,7 @@ Tests
         input_size = 100
         n_inputs = 150
         n_hashes = 2
-        hashfn = SignALSH(n_hashes)
+        hashfn = SignALSH(n_hashes; maxnorm=4*input_size)
 
         ## Test 1: regular matrix adjoint
         x = randn(n_inputs, input_size)'
@@ -115,7 +148,7 @@ Tests
 
     @testset "Hash inputs of different sizes" begin
         n_hashes = 42
-        hashfn = SignALSH(n_hashes)
+        hashfn = SignALSH(n_hashes; maxnorm=100)
 
         @test size(hashfn.coeff_A) == (n_hashes, 0)
 
@@ -140,7 +173,7 @@ Tests
 
     @testset "Hash inputs of different sizes with resize_pow2 = true" begin
         n_hashes = 25
-        hashfn = SignALSH(n_hashes; resize_pow2=true)
+        hashfn = SignALSH(n_hashes; maxnorm=100, resize_pow2=true)
 
         @test size(hashfn.coeff_A) == (n_hashes, 0)
 

test/tables/test_table.jl

@@ -127,7 +127,7 @@ using Test, Random, LSH
         n_hashes = 8
 
         hashfn_mips = MIPSHash(n_hashes)
-        hashfn_sign = SignALSH(n_hashes)
+        hashfn_sign = SignALSH(n_hashes; maxnorm=input_size)
 
         for hashfn in (hashfn_mips, hashfn_sign)
             table = LSHTable(hashfn)