Commits

Ruben Martinez-Cantin committed d80ed94

Initial commit

Comments (0)

Files changed (1)

-== Welcome ==
+==  BAYESIAN-OPTIMIZATION ==
 
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
-
-=== Wiki features ===
-
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
-
-The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
-
-Go ahead and try:
+This is an efficient, C++ implementation of the Bayesian optimization
+algorithm presented in the papers:
 
 {{{
-$ hg clone http://bitbucket.org/rmcantin/bayesian-optimization/wiki
+Ruben Martinez-Cantin, Nando de Freitas, Arnaud Doucet and Jose Castellanos.
+Active Policy Learning for Robot Planning and Exploration under Uncertainty 
+Robotics: Science and Systems. 2007
+
+Ruben Martinez-Cantin, Nando de Freitas, Eric Brochu, Jose Castellanos and 
+Arnaud Doucet (2009) A Bayesian Exploration-Exploitation Approach for 
+Optimal Online Sensing and Planning with a Visually Guided Mobile Robot. 
+Autonomous Robots - Special Issue on Robot Learning, Part B, 27(3):93-103.
+}}}
+ 
+Basically, it uses the active learning strategy to optimize an "arbitrary" 
+funtion using few iterations.
+
+
+=== 1 - INSTALL: ===
+
+
+Libkrigging uses standard C/C++ code, standard libraries and it can
+be compiled in different platforms using CMake.
+
+Linux or Mac OS:
+{{{
+>> cmake . 
+>> make
+>> sudo make install
 }}}
 
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
+Using ccmake instead of cmake you will access a interface to select features 
+such as debug mode, which version of DIRECT to use (see below) and if you want
+to use shared libraries or not. Shared libraries are required to use the 
+Python interface.
 
-=== Syntax highlighting ===
+If you have doxygen installed on your computer, you can compile the
+documentation directly using cmake. 
 
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
-
-Here's an example of some Python code:
-
+You just need to download UseDoxygen.cmake
 {{{
-#!python
-
-def wiki_rocks(text):
-	formatter = lambda t: "funky"+t
-	return formatter(text)
+>> darcs get http://tobias.rautenkranz.ch/cmake/doxygen
+>> cd doxygen
+>> cmake . && make install
 }}}
 
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
+Then, in the directy where bayesian-optimization is, use:
+{{{
+>> cmake .
+>> make
+>> make doc
+>> make install
+}}}
 
-Have fun!
+The documentation will appear on the doc subdirectory.
+
+Windows:
+It can be compilled using CMake and MinGW compilers.
+
+
+=== 2 - USAGE: ===
+
+Jointly with bayesian-optimization, the test program krigtest will be compiled.
+It can be used as an example of the interfaces that bayesian-optimization provide.
+There are three kind of interfaces.
+
+2.1 - C functional usage
+------------------------
+
+This interface is fully functional from C and C++. It resembles the classic 
+NLOPT interface, therefore, NLOPT manual can used as well. We just need to 
+define a function pointer to the function that we need to evaluate. The 
+function pointer must agree with the template provided in krigwpr.h
+
+Note that the gradient has been included for future compatibility, although
+in the current implementation, it is not used. You can just use a NULL pointer.
+
+
+2.2 - C++ polymorphic usage
+---------------------------
+
+The second way to use the function is by creating an object that inherits 
+from the Krigging object defined in krigging.hpp
+
+Then, we just need to define the virtual function evaluateSample, which 
+has interfaces both for C arrays and uBlas vectors. You can just redefine
+your favorite interface.
+
+Note that the checkReachability function has been included for future 
+compatibility, although in the current implementation, it is not used.
+
+2.3 - Python functional usage
+-----------------------------
+
+The file bin/test.py provides an example of the Python interface. It is similar
+the C interface. The parameters must be defined as a Python dictionary.
+
+
+=== 3 -  DEPENDENCIES: ===
+
+3.1 - BOOST:
+------------
+
+This code uses Boost libraries for matrix operations (uBlas) and random
+number generation. They can be found in standard linux distributions or
+it can be downloaded from (www.boost.org). Since they are pure template
+libraries, they do not require compilation. Just make sure the headers are
+on the include path.
+
+They are not very efficient, so it may change in future versions.
+
+
+3.2 - DIRECT:
+-------------
+
+This library requires some other nonlinear optimization library 
+(e.g.: DIRECT). 
+
+
+a) Using Fortran DIRECT:
+
+For completeness, it includes a Fortran 77 implementation of the
+DIRECT-L algorithm by J. Gablonsky
+
+J. M. Gablonsky and C. T. Kelley, "A locally-biased form of the DIRECT 
+algorithm," J. Global Optimization, vol. 21 (1), p. 27-37 (2001). 
+
+The original code can be downloaded from 
+[[http://www4.ncsu.edu/~ctk/SOFTWARE/DIRECTv204.tar.gz|here]],
+which includes some parallel processing functions that are not yet 
+supported in bayesian-optimization.
+
+This code has only been tested using gcc and libgfortran. Due to some
+limitations of the F77 compiler, it doesn't work in 64bit OS.
+
+b) Using NLOPT (default):
+
+We recommend the use of NLOPT for the inner loop optimization. The latest
+version can be downloaded from 
+
+http://ab-initio.mit.edu/wiki/index.php/NLopt
+
+NLOPT does not require external libraries and it is compatible with 
+Windows and Mac. Although compiling it in Windows is tricky.
+
+3.3 - PYTHON:
+-------------
+
+The library has been tested with Python 2.6.
+
+
+
+
+
+********************
+* 4. KNOWN ISSUES  *
+********************
+
+- In some systems, the linker is not able to find the shared libraries. You
+just need to point the LD_LIBRARY_PATH and PYTHONPATH to the corresponding
+folder (by default: /usr/local/lib)
+
+- I have found that in some versions of Linux, NLOPT callback procedure
+fails when using the Python interface of bayesian-optimization.
+