turbonss/README.t2t

CMPH - C Minimal Perfect Hashing Library


%!includeconf: CONFIG.t2t

-------------------------------------------------------------------

==Motivation==

A perfect hash function maps a static set of n keys into a set of m integer numbers without collisions, where m is greater than or equal to n. If m is equal to n, the function is called minimal.

[Minimal perfect hash functions concepts.html] are widely used for memory efficient storage and fast retrieval of items from static sets, such as words in natural languages, reserved words in programming languages or interactive systems, universal resource locations (URLs) in Web search engines, or item sets in data mining techniques. Therefore, there are applications for minimal perfect hash functions in information retrieval systems, database systems, language translation systems, electronic commerce systems, compilers, operating systems, among others.

The use of minimal perfect hash functions is, until now, restricted to scenarios where the set of keys being hashed is small, because of the limitations of current algorithms. But in many cases, to deal with huge set of keys is crucial. So, this project gives to the free software community an API that will work with sets in the order of billion of keys.

Probably, the most interesting application for minimal perfect hash functions is its use as an indexing structure for databases. The most popular data structure used as an indexing structure in databases is the B+ tree. In fact, the B+ tree is very used for dynamic applications with frequent insertions and deletions of records. However, for applications with sporadic modifications and a huge number of queries the B+ tree is not the best option, because practical deployments of this structure are extremely complex, and perform poorly with very large sets of keys such as those required for the new frontiers [database applications http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=299].

For example, in the information retrieval field, the work with huge collections is a daily task. The simple assignment of ids to web pages of a collection can be a challenging task. While traditional databases simply cannot handle more traffic once the working set of web page urls does not fit in main memory anymore, minimal perfect hash functions can easily scale to hundred of millions of entries, using stock hardware.

As there are lots of applications for minimal perfect hash functions, it is important to implement memory and time efficient algorithms for constructing such functions. The lack of similar libraries in the free software world has been the main motivation to create the C Minimal Perfect Hashing Library ([gperf is a bit different gperf.html], since it was conceived to create very fast perfect hash functions for small sets of keys and CMPH Library was conceived to create minimal perfect hash functions for very large sets of keys). C Minimal Perfect Hashing Library is a portable LGPLed library to generate and to work with very efficient minimal perfect hash functions.

-------------------------------------------------------------------

==Description==

The CMPH Library encapsulates the newest and more efficient algorithms in an easy-to-use, production-quality, fast API. The library was designed to work with big entries that cannot fit in the main memory. It has been used successfully for constructing minimal perfect hash functions for sets with more than 100 million of keys, and we intend to expand this number to the order of billion of keys. Although there is a lack of similar libraries, we can point out some of the distinguishable features of the CMPH Library:

- Fast.
- Space-efficient with main memory usage carefully documented.
- The best modern algorithms are available (or at least scheduled for implementation :-)).
- Works with in-disk key sets through of using the adapter pattern.
- Serialization of hash functions.
- Portable C code (currently works on GNU/Linux and WIN32 and is reported to work in OpenBSD and Solaris).
- Object oriented implementation.
- Easily extensible.
- Well encapsulated API aiming binary compatibility through releases.
- Free Software.


----------------------------------------

==Supported Algorithms==

 
%html% - [BDZ Algorithm bdz.html].
%txt% - BDZ Algorithm.
  The fastest algorithm to build PHFs and MPHFs. It is based on random 3-graphs. A 3-graph is a 
  generalization of a graph where each edge connects 3 vertices instead of only 2. The 
  resulting functions are not order preserving and can be stored in only //(2 + x)cn// 
  bits, where //c// should be larger than or equal to //1.23// and //x// is a constant 
  larger than //0// (actually, x = 1/b and b is a parameter that should be larger than 2). 
  For //c = 1.23// and //b = 8//, the resulting functions are stored in approximately 2.6 bits per key.
%html% - [BMZ Algorithm bmz.html].
%txt% - BMZ Algorithm.
  A very fast algorithm based on cyclic random graphs to construct minimal
  perfect hash functions in linear time. The resulting functions are not order preserving and
  can be stored in only //4cn// bytes, where //c// is between 0.93 and 1.15. 
%html% - [BRZ Algorithm brz.html].
%txt% - BRZ Algorithm.
  A very fast external memory based algorithm for constructing minimal perfect hash functions
  for sets in the order of billion of keys in linear time. The resulting functions are not order preserving and
  can be stored using just 8.1 bits per key.
%html% - [CHM Algorithm chm.html].
%txt% - CHM Algorithm.
  An algorithm based on acyclic random graphs to construct minimal
  perfect hash functions in linear time. The resulting functions are order preserving and
  are stored in //4cn// bytes, where //c// is greater than 2.
%html% - [FCH Algorithm fch.html].
%txt% - FCH Algorithm.
  An algorithm to construct minimal perfect hash functions that require 
  less than 4 bits per key to be stored. Although the resulting MPHFs are 
  very compact, the algorithm is only efficient for small sets.
  However, it is used as internal algorithm in the BRZ algorithm for efficiently solving 
  larger problems and even so to generate MPHFs that require approximately 
  4.1 bits per key to be stored. For that, you just need to set the parameters -a to brz and
  -c to a value larger than or equal to 2.6.


----------------------------------------

==News for version 0.8 (Coming soon)==

- [An algorithm to generate MPHFs that require around 2.6 bits per key to be stored bdz.html], which is referred to as BDZ algorithm. The algorithm is the fastest one available in the literature for sets that can be treated in internal memory.
- [An algorithm to generate PHFs with range m = cn, for c > 1.22 bdz.html], which is referred to as BDZ_PH algorithm. It is actually the BDZ algorithm without the ranking step. The resulting functions can be stored in 1.95 bits per key for //c = 1.23// and are considerably faster than the MPHFs generated by the BDZ algorithm.
- The hash functions djb2, fnv and sdbm were removed because they do not use random seeds and therefore are not useful for MPHFs algorithms.
- All reported bugs and suggestions have been corrected and included as well.


==News for version 0.7==

- Added man pages and a pkgconfig file.


[News log newslog.html]
----------------------------------------

==Examples==

Using cmph is quite simple. Take a look.


```
#include <cmph.h>
#include <string.h>
// Create minimal perfect hash function from in-memory vector
int main(int argc, char **argv)
{
	// Creating a filled vector
	const char *vector[] = {"aaaaaaaaaa", "bbbbbbbbbb", "cccccccccc", "dddddddddd", "eeeeeeeeee",
				"ffffffffff", "gggggggggg", "hhhhhhhhhh", "iiiiiiiiii", "jjjjjjjjjj"};
	unsigned int nkeys = 10;
	// Source of keys
	cmph_io_adapter_t *source = cmph_io_vector_adapter((char **)vector, nkeys);
	
	//Create minimal perfect hash function using the default (chm) algorithm.
	cmph_config_t *config = cmph_config_new(source);
	cmph_t *hash = cmph_new(config);
	cmph_config_destroy(config);
	
	//Find key
	const char *key = "jjjjjjjjjj";
	unsigned int id = cmph_search(hash, key, strlen(key));
	fprintf(stderr, "Id:%u\n", id);
	//Destroy hash
	cmph_destroy(hash);
	cmph_io_vector_adapter_destroy(source);
	return 0;
}
```
Download [vector_adapter_ex1.c examples/vector_adapter_ex1.c]. This example does not work in version 0.3. You need to update the sources from CVS to make it works.
-------------------------------

```
#include <cmph.h>
#include <stdio.h>
#include <string.h>
 // Create minimal perfect hash function from in-disk keys using BMZ algorithm
int main(int argc, char **argv)
{
	//Open file with newline separated list of keys
	FILE * keys_fd = fopen("keys.txt", "r");
	cmph_t *hash = NULL;
	if (keys_fd == NULL)
	{
		fprintf(stderr, "File \"keys.txt\" not found\n");
		exit(1);
	}
	// Source of keys
	cmph_io_adapter_t *source = cmph_io_nlfile_adapter(keys_fd);
	
	cmph_config_t *config = cmph_config_new(source);
	cmph_config_set_algo(config, CMPH_BMZ);
	hash = cmph_new(config);
	cmph_config_destroy(config);
	
	//Find key
	const char *key = "jjjjjjjjjj";
	unsigned int id = cmph_search(hash, key, strlen(key));
	fprintf(stderr, "Id:%u\n", id);
	//Destroy hash
	cmph_destroy(hash);
	cmph_io_nlfile_adapter_destroy(source);
	fclose(keys_fd);
	return 0;
}
```
Download [file_adapter_ex2.c examples/file_adapter_ex2.c] and [keys.txt examples/keys.txt]
--------------------------------------

==The cmph application==

cmph is the name of both the library and the utility
application that comes with this package. You can use the cmph
application for constructing minimal perfect hash functions from the command line. 
The cmph utility
comes with a number of flags, but it is very simple to create and to query 
minimal perfect hash functions:

```
 $ # Using the chm algorithm (default one) for constructing a mphf for keys in file keys_file
 $ ./cmph -g keys_file
 $ # Query id of keys in the file keys_query
 $ ./cmph -m keys_file.mph keys_query
```

The additional options let you set most of the parameters you have
available through the C API. Below you can see the full help message for the 
utility.


```
usage: cmph [-v] [-h] [-V] [-k nkeys] [-f hash_function] [-g [-c value][-s seed] ] 
            [-a algorithm] [-M memory_in_MB] [-b BRZ_parameter] [-d tmp_dir] 
            [-m file.mph] keysfile
Minimum perfect hashing tool

  -h     print this help message
  -c     c value determines:
           the number of vertices in the graph for the algorithms BMZ and CHM
           the number of bits per key required in the FCH algorithm
  -a     algorithm - valid values are
          * bmz
          * bmz8
          * chm
          * brz
          * fch
          * bdz
          * bdz_ph
  -f     hash function (may be used multiple times) - valid values are
          * jenkins
  -V     print version number and exit
  -v     increase verbosity (may be used multiple times)
  -k     number of keys
  -g     generation mode
  -s     random seed
  -m     minimum perfect hash function file 
  -M     main memory availability (in MB)
  -d     temporary directory used in brz algorithm 
  -b     the meaning of this parameter depends on the algorithm used.
         If BRZ algorithm is selected in -a option, than it is used
         to make the maximal number of keys in a bucket lower than 256.
         In this case its value should be an integer in the range [64,175].
         If BDZ algorithm is selected in option -a, than it is used to
         determine the size of some precomputed rank information and
         its value should be an integer in the range [3,10]
  keysfile       line separated file with keys
```

==Additional Documentation==

[FAQ faq.html]

==Downloads==

Use the project page at sourceforge: http://sf.net/projects/cmph


==License Stuff==

Code is under the LGPL and the MPL 1.1. 
----------------------------------------

%!include: FOOTER.t2t

%!include(html): ''LOGO.t2t''
Last Updated: %%date(%c)