Fast Exact Search in Hamming Space with Multi-Index Hashing

Multi Index Hashing (MIH) ======= An implementation of *"Fast Exact Search in Hamming Space with Multi-Index Hashing, M. Norouzi, A. Punjani, D. J. Fleet, IEEE TPAMI 2014"*. See http://www.cs.toronto.edu/~norouzi/research/mih/. This algorithm performs fast exact nearest neighbor search in Hamming distance on binary codes. Using this code, one can re-run the experiments described in the paper. For best results, consider using *libhugetlbfs* with multi-index hashing. ### Compilation You need make, cmake, hdf5 library, hdf5-dev package to build this project. To compile, create a folder called `build`, and run: ``` cd build rm * -rf cmake .. make ``` This should generate two binary files: `mih` and `linscan` ### Datasets An example binary code dataset with 1 million 64-bit codes from SIFT is stored in the data folder. To generate larger binary code datasets, one should download raw data which can be converted to binary codes using hashing techniques (e.g., LSH or MLH). For example, download the INRIA bigann dataset (1 billion SIFT features) from http://corpus-texmex.irisa.fr/ and store it under data/inria/. You can also download the Tiny images dataset (80 million GIST descriptors) from http://horatio.cs.nyu.edu/mit/tiny/data/index.html and store it under data/tiny. By running create_lsh_codes.m (a matlab snippet) one can generate binary codes from the above datasets using random projections (LSH, "Similarity estimation techniques from rounding algorithms, M. Charikar, STOC. 2002"). By changing the first few lines of create_lsh_codes, you can control the parameters of the matlab snippet. The output is in matlab (version 7.3) format, which is essentially hdf5 format. Hence, we use hdf5 library to read the binary code datasets. ### Usage `RUN.sh` is a bash script showing an example run of the program 64-bit codes. Set the parameters `nb`, `HUGE`, `hashfunc`, etc. to change the setting. `RUN.sh` includes suggested values for `m`: number of hash tables. ##### Linear scan `linscan` provides an efficient implementation of exhaustive linear scan for kNN in Hamming distance on binary codes. This serves as a good baseline. ``` linscan <infile> <outfile> [options] Options: -N <number> Set the number of binary codes from the beginning of the dataset file to be used -B <number> Set the number of bits per code, default autodetect -Q <number> Set the number of query points to use from <infile>, default all -K <number> Set number of nearest neighbors to be retrieved ``` Examples: ``` ./build/linscan data/lsh_64_sift_1M.mat linscan_64_1M.h5 -N 100000 -B 64 -Q 1000 -K 100 ./build/linscan data/lsh_64_sift_1M.mat linscan_64_1M.h5 -N 1000000 -B 64 -Q 1000 -K 100 ``` Assuming that a dataset of 128-bit binary codes is stored at `codes/lsh_64_sift_1M.mat`, running the above lines will create an output file `linscan_64_1M.h5`, which stores the results and timings for 100-NN search on 100K and 1M binary codes. If the output file does not exist (the first time), the output file is created. If the output file exists (since the second time), the file is appended with the new results. ##### Multi Index Hashing `mih` provides an implementation of multi-index hashing for fast exact kNN in Hamming distance on binary codes. ``` mih <infile> <outfile> [options] Options: -N <number> Set the number of binary codes from the beginning of the dataset file to be used -B <number> Set the number of bits per code, default autodetect -Q <number> Set the number of query points to use from <infile>, default all -m <number> Set the number of chunks to use, default 1 -K <number> Set number of nearest neighbors to be retrieved -R <number> Set the number of codes (in Millions) to use in computing the optimal bit reordering, default OFF (0) ``` Examples: ``` ./build/mih data/lsh_64_sift_1M.mat mih_64_1M.h5 -N 100000 -B 64 -m 5 -Q 10000 -K 100 ./build/mih data/lsh_64_sift_1M.mat mih_64_1M.h5 -N 1000000 -B 64 -m 4 -Q 10000 -K 100 ``` The mih's options are very similar to linscan. It has an additional argument (-m) to determine the number of hash tables. It also has a flag (-R) to determine whether the assignment of bits to the substrings should be optimized. ### FAQs Q: I have tried your code with some of my datasets. It works well when I used small datasets, but it does not perform well with large datasets. A: Did you try decreasing the number of hash tables (by the -m switch) as you increased the size of the database? My experience is that with the correct choice of m, the speedup on larger datasets should be much better. In the RUN.sh file, I have a set of suggestions for the values of m for different number of codes in the datasets. ### License Copyright (c) 2012, Mohammad Norouzi [<mohammad.n@gmail.com>] and Ali Punjani [<alipunjani@cs.toronto.edu>]. This is a free software; for license information please refer to license.txt file. ### TODO - Automatic suggestion for the m parameter. - Multi-core functionality. - Improve SparseHashtable insertion speed. It is currently very slow, but can be improved in different ways.