You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+74-22
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,18 @@ FLASH (Fast LSH Algorithm for Similarity Search Accelerated with HPC) is a libra
4
4
5
5
## Performance
6
6
7
-
We tested our system on a few large scale sparse datasets including [url](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#url), [webspam](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#webspam) and [kdd12](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#kdd2012).
8
-
9
-
The following results are from a head-to-head comparison with [NMSLIB](https://github.com/searchivarius/nmslib) v1.6 hnsw, one of the best methods available (see [ann-benchmarks](https://github.com/erikbern/ann-benchmarks)) on these datasets. In particular, we compared the timing for the construction of full knn-graph from grounds up, and the per-query timing (after building the index). We also estimated and compared the memory consumption of the index.
7
+
We tested our system on a few large scale sparse datasets including [url](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#url), [webspam](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#webspam) and [kdd12](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#kdd2012), and also a dense dataset [SIFT1M](http://corpus-texmex.irisa.fr/).
10
8
11
9
### Quality Metrtics
12
10
13
11
*R@k* is the recall of the 1-nearest neighbor in the top-k results.
14
12
*S@k* is the average cosine similarity of the top-k results concerning the query datapoint.
15
13
14
+
For the dense SIFT1M dataset, we used 1 GPU (Nvidia Tesla P100) for all the processing. We constructed the hashtable within 3 seconds and achieved R@100 = 0.659, S@1 = 0.844 and S@100 = 0.751 with per query runtime of 0.038 milliseconds.
15
+
16
+
For the testing of the sparse datasets, we present results on 2 CPUs (Intel Xeon E5 2660v4) and 2 CPUs + 1 GPU. The following results are from a head-to-head comparison with [NMSLIB](https://github.com/searchivarius/nmslib) v1.6 hnsw, one of the best methods available (see [ann-benchmarks](https://github.com/erikbern/ann-benchmarks)). In particular, we compared the timing for the construction of full knn-graph from grounds up, and the per-query timing (after building the index). We also estimated and compared the memory consumption of the index.
@@ -33,43 +36,92 @@ An active installation of OpenCL 1.1 or OpenCL 2.0 is required to support the GP
33
36
34
37
Then, install clinfo by `apt-get install clinfo` and verify the number of OpenCL platforms and devices. These information will be used in the configurations.
35
38
36
-
## Configuration and Compilation
39
+
## System Configuration
37
40
38
-
Navigate to the FLASH directory. Configure the system by editing the following section of *LSHReservoir_config.h*guided by the comments:
41
+
Navigate to the FLASH directory. First configure the system by editing the following section of *LSHReservoir_config.h*to choose the devices to use.
39
42
40
43
```
41
-
// Comment out if not using GPU.
42
-
#define USE_GPU
43
-
// Comment out if using OpenCL 1.XX. Does not matter if not usng GPU.
44
+
// Customize processing architecture.
45
+
#define OPENCL_HASHTABLE // Placing the hashtable in the OpenCL device.
46
+
#define OPENCL_HASHING // Perform hashing in the OpenCL device.
47
+
#define OPENCL_KSELECT // Perform k-selection in the OpenCL device.
48
+
49
+
// Comment out if using OpenCL 1.XX.
44
50
#define OPENCL_2XX
45
51
46
-
#define CL_GPU_PLATFORM 0 // Does not matter if not usng OpenCL-GPU.
47
-
#define CL_CPU_PLATFORM 1 // Does not matter if not usng OpenCL-CPU.
48
-
#define CL_GPU_DEVICE 0 // Does not matter if not usng OpenCL-GPU.
49
-
#define CL_CPU_DEVICE 0 // Does not matter if not usng OpenCL-CPU.
52
+
// Select the id of the desired platform and device, only relevant when using OpenCl.
53
+
// An overview of the platforms and devices can be queried through the OpenCL framework.
54
+
// On Linux, a package "clinfo" is also capable of outputing the platform and device information.
55
+
#define CL_PLATFORM_ID 0
56
+
#define CL_DEVICE_ID 0
50
57
```
58
+
For dense datasets:
59
+
1. GPU only
51
60
52
-
Fill in CL_GPU_PLATFORM / CL_GPU_PLATFORM according to the order that the cpu/gpu platforms appear in the output of clinfo (make sure that for gpu is correct, OpenCL for cpu is currently experimental and is not required). If multiple devices exist, fill in CL_GPU_DEVICE / CL_CPU_DEVICE to choose the desired device according to their order in the output of clinfo.
53
-
54
-
Save and close the file. Type in terminal:
61
+
```
62
+
// Customize processing architecture.
63
+
#define OPENCL_HASHTABLE // Placing the hashtable in the OpenCL device.
64
+
#define OPENCL_HASHING // Perform hashing in the OpenCL device.
65
+
#define OPENCL_KSELECT // Perform k-selection in the OpenCL device.
66
+
```
67
+
For sparse datasets:
68
+
1. CPU + GPU
55
69
56
70
```
57
-
make
71
+
// Customize processing architecture.
72
+
//#define OPENCL_HASHTABLE // Placing the hashtable in the OpenCL device.
73
+
//#define OPENCL_HASHING // Perform hashing in the OpenCL device.
74
+
#define OPENCL_KSELECT // Perform k-selection in the OpenCL device.
75
+
```
76
+
2. CPU only
58
77
```
78
+
// Customize processing architecture.
79
+
//#define OPENCL_HASHTABLE // Placing the hashtable in the OpenCL device.
80
+
//#define OPENCL_HASHING // Perform hashing in the OpenCL device.
81
+
//#define OPENCL_KSELECT // Perform k-selection in the OpenCL device.
82
+
```
83
+
Install clinfo by `apt-get install clinfo`. Fill in CL_PLATFORM_ID / CL_DEVICE_ID to choose the desired platform and device based on to the order that the GPU platforms and devices appear in the output of clinfo. Comment out `OPENCL_2XX` if using OpenCL 1.X. Save and close the file.
59
84
60
-
The compilation is complete if no errors appear.
85
+
Complete the dataset setup as detailed in the **Tutorial** section (or any customized usage, please refer to our [documentation](https://github.com/RUSH-LAB/Flash/blob/master/doc.pdf)), and compile the program:
86
+
```
87
+
make clean; make
88
+
```
89
+
The compilation is complete if no errors appear. Run the program by:
90
+
```
91
+
./runme
92
+
```
61
93
62
94
## Tutorial
63
95
64
-
The current example code in the main() function verifies one of the results presented in [our paper](https://arxiv.org/pdf/1709.01190.pdf) on the Webspam dataset. Download the dataset from [libsvm](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#webspam), and rename the libsvm-format file as trigram.svm. Download the groundtruths from this [link](https://github.com/wangyiqiu/webspam). Place the dataset and groundtruth files in the FLASH directory. Run the program from the terminal:
96
+
We will present very detailed steps to replicate one result presented in [our paper](https://arxiv.org/pdf/1709.01190.pdf), in particular the webspam dataset. Other results can be replicated in a very similar manner. For customized usage, please refer to our [documentation](https://github.com/RUSH-LAB/Flash/blob/master/doc.pdf) generated by [doxygen](http://www.stack.nl/~dimitri/doxygen/).
97
+
98
+
Download the dataset from [libsvm](https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html#webspam), and the groundtruths from this [link](https://github.com/wangyiqiu/webspam). Place the dataset and groundtruth files in a directory you like.
99
+
100
+
Open `benchmarking.h` and follow the following configuration. Make sure to set the **path** of the dataset and groundtruth files correctly under `#elif defined WEBSPAM_TRI`.
65
101
66
102
```
67
-
./runme
68
-
```
103
+
/* Select a dataset below by uncommenting it.
104
+
Then modify the file location and parameters below in the Parameters section. */
105
+
106
+
//#define SIFT1M
107
+
//#define URL
108
+
#define WEBSPAM_TRI
109
+
//#define KDD12
110
+
111
+
...
69
112
70
-
The test program builds multiple hash tables for the dataset and query 10,000 test vectors followed by quality evaluations. The program will run with console outputs, indicating the progress and performance. The parameters, such as L, K and R can be edited in main.cpp. A re-compilation is required after changing the parameters. Please note that the time for parsing the dataset from disk might take about 5-10 minutes.
Configure the system for **sparse data**, CPU or CPU + GPU and run the program (if not already done, see **System Configuration** above).
71
123
72
-
A basic [documentation](https://github.com/RUSH-LAB/Flash/blob/master/doc.pdf) of the API generated by [doxygen](http://www.stack.nl/~dimitri/doxygen/)is available. Tutorial codes in main.cpp could be used as a reference.
124
+
The test program builds multiple hash tables for the dataset and query 10,000 test vectors followed by quality evaluations. The program will run with console outputs, indicating the progress and performance. `make clean; make`is required after changing the parameters. Please note that the time for parsing the webspam dataset from disk might take about 5-10 minutes.
0 commit comments