oooooooooooooooooooooooooo
              O                 __       O
              O   \   /  /\    /   |     O
              O    \ /  /  \  /___ |     O
              O     |  /----\ \    |     O
              O     | /      \ \__ |___  O
              O                          O
               oooooooooooooooooooooooooo 

What is it?
===========

This is a library for performing efficient basic operations, 
in particular kmeans and exhaustive nearest neighbor search function.
It offers three interfaces: C, python and matlab

Only a few function are exported in matlab, as most of the function 
provided in the library are native matlab functions. 


Legal & Contact
===============

This library has been written and is maintained by Herve Jegou and Matthijs Douze. 
Contact: herve.jegou@inria.fr and matthijs.douze@inria.fr
Copyright (C) INRIA 2009-2011
Last change to this documentation: September 2011. 

This software is governed by the CeCILL license under French law and
abiding by the rules of distribution of free software. 
See http://www.cecill.info/licences.en.html

INRIA may provide a licence for industrial applications. 
Do not hesitate to contact us. 


Prerequisites
=============

1- Blas and Lapack. 

Any implementation should work as it is
wrapped with the Fortran calling conventions. 

You might need to adjust the location of these libraries in 
the makefile.inc file (generated by configure.sh)
The LD_LIBRARY_PATH environment variable should be set accordingly

2- Python and its development libraries (python-dev). 
If only python is installed, not python-dev, you will get an error 
saying that Python.h can not be found

3- swig (swig)


These two last pre-requisites are required by the python interface 
and are not strictly mandatory. If you are not interested by this 
python interface and that you don't have python-dev and swig installed, 
you should remove the target _yael.so target in the Makefile of the 
yael core directory. 

The library is provided with a pre-compiled documentation (in doc 
subdirectory). The reference documentation is generated by doxygen 
while the reference manual is generated using sphinx. 


Installation
=============

1- ./configure.sh in the yael root directory. 
For most configurations, nothing has to be done. However you might need 
to adjust the variables defined in makefile.inc to fit your local config. 

2- make


3- Try to compile the programs in progs and test

At this point, only the core C and python library are compiled. 
If you need the matlab interface, you have to compile the mex files:

4- cd matlab ; make

The mex executable should be in the PATH. 

It is also possible to compile an version that works with Octave (see
the Makefile and octave_mex.sh)


Remarks
=============

The performance of the kmeans and of the most computationally intensive 
functions heavily depend on the version of Lapack and Blas. 
Timings might be scaled in the range from 1 to 3, depending on your choice. 

In order to obtain the best performance, you should consider testing 
the different version installed on your machine 
(e.g., in /usr/lib and /usr/lib/atlas).