Commit e1bf1f65 authored by Konstantinos Chatzilygeroudis's avatar Konstantinos Chatzilygeroudis
Browse files

Better index doc? [ci skip]

parent cd8be66f
API
============
====
.. highlight:: c++
Limbo follows a `policy-based design <https://en.wikipedia.org/wiki/Policy-based_design>`_, which allows users to combine high flexibility (almost every part of Limbo can be substituted by a user-defined part) with high performance (the abstraction do not add any overhead, contrary to classic OOP design). These two features are critical for researchers who want to experiment new ideas in Bayesian optimization. This means that changing a part of limbo (e.g. changing the kernel functions) usually corresponds to changing a template parameter of the optimizer.
......@@ -46,7 +46,7 @@ However, there is no need to inherit from a particular 'abstract' class.
Every class is parametrized by a :ref:`Params <params-guide>` class that contains all the parameters.
Sequence diagram
---------------
-----------------
.. figure:: pics/limbo_sequence_diagram.png
:alt: Sequence diagram
:target: _images/limbo_sequence_diagram.png
......@@ -56,7 +56,7 @@ Sequence diagram
File Structure
--------------
---------------
(see below for a short explanation of the concepts)
.. highlight:: none
......@@ -149,7 +149,7 @@ Template
}
Available initializers
^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^
.. doxygengroup:: init
:undoc-members:
......@@ -272,7 +272,7 @@ Not all the algorithms support bounded optimization and/or initial point:
Available optimizers
^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^
.. doxygengroup:: opt
:undoc-members:
......@@ -283,7 +283,7 @@ Default parameters
Models / Gaussian processes (model)
---------------
------------------------------------
Currently, Limbo only includes Gaussian processes as models. More may come in the future.
.. doxygenclass:: limbo::model::GP
......@@ -304,7 +304,7 @@ Kernel functions (kernel)
.. _kernel-api:
Template
^^^^^^^^
^^^^^^^^^
.. code-block:: cpp
template <typename Params>
......@@ -329,14 +329,14 @@ Default parameters
Mean functions (mean)
--------------------------
----------------------
.. _mean-api:
Mean functions capture the prior about the function to be optimized.
Template
^^^^^^^^
^^^^^^^^^
.. code-block:: cpp
......@@ -353,7 +353,7 @@ Template
};
Available mean functions
^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygengroup:: mean
:members:
......@@ -370,12 +370,12 @@ Internals
Stopping criteria (stop)
---------------------------------
-------------------------
Stopping criteria are used to stop the Bayesian optimizer algorithm.
Template
^^^^^^^^
^^^^^^^^^
.. code-block:: cpp
template <typename Params>
......@@ -388,7 +388,7 @@ Template
};
Available stopping criteria
^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygengroup:: stop
:members:
......@@ -406,12 +406,12 @@ Internals
.. _statistics-stats:
Statistics (stats)
--------------------------
-------------------
Statistics are used to report informations about the current state of the algorithm (e.g., the best observation for each iteration). They are typically chained in a `boost::fusion::vector<>`.
Template
^^^^^^^^
^^^^^^^^^
.. code-block:: cpp
template <typename Params>
......@@ -427,7 +427,7 @@ Template
.. doxygenstruct:: limbo::stat::StatBase
Available statistics
^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^
.. doxygengroup:: stat
:members:
......@@ -437,12 +437,12 @@ Default parameters
:undoc-members:
Parallel tools (par)
-----------------------
---------------------
.. doxygennamespace:: limbo::tools::par
.. doxygengroup:: par_tools
:members:
Misc tools (tools)
-------------------------------
.. doxygennamespace:: limbo::tools
-------------------
.. doxygengroup:: tools
:members:
......@@ -57,3 +57,77 @@
pages = {503--507},
file = {Cully et al. - 2015 - Robots that can adapt like animals.pdf:/Users/jbm/Documents/zotero_bib/storage/WQ9SQZX3/Cully et al. - 2015 - Robots that can adapt like animals.pdf:application/pdf;Cully et al_2015_Robots that can adapt like animals.pdf:/Users/jbm/Documents/zotero_bib/storage/ADZPNDPM/Cully et al_2015_Robots that can adapt like animals.pdf:application/pdf}
}
@inproceedings{chatzilygeroudis2017,
TITLE = {{Black-Box Data-efficient Policy Search for Robotics}},
AUTHOR = {Chatzilygeroudis, Konstantinos and Rama, Roberto and Kaushik, Rituraj and Goepp, Dorian and Vassiliades, Vassilis and Mouret, Jean-Baptiste},
URL = {https://hal.inria.fr/hal-01576683},
BOOKTITLE = {{IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}},
ADDRESS = {Vancouver, Canada},
YEAR = {2017},
video={https://www.youtube.com/watch?v=kTEyYiIFGPM},
src={https://github.com/resibots/blackdrops},
MONTH = Sep,
KEYWORDS = {Data-Efficient Learning, learning, robotics, resilience},
PDF = {https://hal.inria.fr/hal-01576683/file/medrops-final.pdf},
HAL_ID = {hal-01576683},
HAL_VERSION = {v1},
}
@article{chatzilygeroudis2018resetfree,
title={{Reset-free Trial-and-Error Learning for Robot Damage Recovery}},
author={Konstantinos Chatzilygeroudis and Vassilis Vassiliades and Jean-Baptiste Mouret},
journal={{Robotics and Autonomous Systems}},
year={2018}
}
@inproceedings{tarapore2016,
TITLE = {{How Do Different Encodings Influence the Performance of the MAP-Elites Algorithm?}},
AUTHOR = {Tarapore, Danesh and Clune, Jeff and Cully, Antoine and Mouret, Jean-Baptiste},
BOOKTITLE = {{The 18th Annual conference on Genetic and evolutionary computation ({GECCO'14})}},
YEAR = {2016},
publisher={{ACM}},
keywords={illumination, evolution, resilience, robotics, encodings},
DOI = {10.1145/2908812.2908875},
URL = {https://hal.inria.fr/hal-01302658},
PDF = {https://hal.inria.fr/hal-01302658/document},
SRC={https://github.com/resibots/tarapore_2016_gecco},
HAL_ID = {hal-01302658},
HAL_VERSION = {v1},
X-PROCEEDINGS = {yes},
X-INTERNATIONAL-AUDIENCE = {yes},
X-EDITORIAL-BOARD = {yes},
X-INVITED-CONFERENCE = {no},
X-SCIENTIFIC-POPULARIZATION = {no},
}
@inproceedings{chatzilygeroudis2018using,
title={Using Parameterized Black-Box Priors to Scale Up Model-Based Policy Search for Robotics},
author={Konstantinos Chatzilygeroudis and Jean-Baptiste Mouret},
year={2018},
booktitle={{International Conference on Robotics and Automation (ICRA)}}
}
@inproceedings{pautrat2018bayesian,
title={Bayesian Optimization with Automatic Prior Selection for Data-Efficient Direct Policy Search},
author={Rémi Pautrat and Konstantinos Chatzilygeroudis and Jean-Baptiste Mouret},
year={2018},
booktitle={{International Conference on Robotics and Automation (ICRA).}},
journal={A short version of the paper was accepted at the non-archival track of the 1st Conference on Robot Learning (CoRL) 2017}
}
@book{alexandrescu2001modern,
title={Modern {C++} design: generic programming and design patterns applied},
author={Alexandrescu, Andrei},
year={2001},
publisher={Addison-Wesley}
}
@article{martinezcantin14a,
author = {Ruben Martinez-Cantin},
title = {{BayesOpt:} A {Bayesian} Optimization Library for Nonlinear Optimization, Experimental Design and Bandits},
journal = {Journal of Machine Learning Research},
year = {2014},
volume = {15},
pages = {3915-3919},
}
......@@ -8,21 +8,17 @@
Limbo's documentation
=================================
Limbo is a lightweight framework for Bayesian Optimization, a powerful approach for global optimization of expensive, non-convex functions. Github page (to report issues and/or help us to improve the library): `[Github repository] <http://github.com/resibots/limbo>`_
Limbo (LIbrary for Model-Based Optimization) is an open-source C++11 library for Gaussian Processes and data-efficient optimization (e.g., Bayesian optimization, see :cite:`b-brochu2010tutorial,b-Mockus2013`) that is designed to be both highly flexible and very fast. It can be used as a state-of-the-art optimization library or to experiment with novel algorithms with "plugin" components. Limbo is currently mostly used for data-efficient policy search in robot learning :cite:`b-lizotte2007automatic` and online adaptation because computation time matters when using the low-power embedded computers of robots. For example, Limbo was the key library to develop a new algorithm that allows a legged robot to learn a new gait after a mechanical damage in about 10-15 trials (2 minutes) :cite:`b-cully_robots_2015`, and a 4-DOF manipulator to learn neural networks policies for goal reaching in about 5 trials :cite:`b-chatzilygeroudis2017`.
The development of Limbo is funded by the `ERC project ResiBots <http://www.resibots.eu>`_.
The implementation of Limbo follows a policy-based design :cite:`b-alexandrescu2001modern` that leverages C++ templates: this allows it to be highly flexible without the cost induced by classic object-oriented designs (cost of virtual functions). `The regression benchmarks <http://www.resibots.eu/limbo/reg_benchmarks.html>`_ show that the query time of Limbo's Gaussian processes is several orders of magnitude better than the one of GPy (a state-of-the-art `Python library for Gaussian processes <https://sheffieldml.github.io/GPy/>`_) for a similar accuracy (the learning time highly depends on the optimization algorithm chosen to optimize the hyper-parameters). The `black-box optimization benchmarks <http://www.resibots.eu/limbo/bo_benchmarks.html>`_ demonstrate that Limbo is about 2 times faster than BayesOpt (a C++ library for data-efficient optimization, :cite:`b-martinezcantin14a`) for a similar accuracy and data-efficiency. In practice, changing one of the components of the algorithms in Limbo (e.g., changing the acquisition function) usually requires changing only a template definition in the source code. This design allows users to rapidly experiment and test new ideas while keeping the software as fast as specialized code.
Limbo shares many ideas with `Sferes2 <http://github.com/sferes2>`_, a similar framework for evolutionary computation.
Limbo takes advantage of multi-core architectures to parallelize the internal optimization processes (optimization of the acquisition function, optimization of the hyper-parameters of a Gaussian process) and it vectorizes many of the linear algebra operations (via the `Eigen 3 library <http://eigen.tuxfamily.org/>`_ and optional bindings to Intel's MKL).
The library is distributed under the `CeCILL-C license <http://www.cecill.info/index.en.html>`_ via a `Github repository <http://github.com/resibots/limbo>`_. The code is standard-compliant but it is currently mostly developed for GNU/Linux and Mac OS X with both the GCC and Clang compilers. New contributors can rely on a full API reference, while their developments are checked via a continuous integration platform (automatic unit-testing routines).
Main features
--------------
Limbo is currently used in the `ERC project ResiBots <http://www.resibots.eu>`_, which is focused on data-efficient trial-and-error learning for robot damage recovery, and in the `H2020 projet PAL <http://www.pal4u.eu/>`_, which uses social robots to help coping with diabetes. It has been instrumental in many scientific publications since 2015 :cite:`b-cully_robots_2015,b-chatzilygeroudis2018resetfree,b-tarapore2016,b-chatzilygeroudis2017,b-pautrat2018bayesian,b-chatzilygeroudis2018using`.
- Implementation of the classic algorithms (Bayesian optimization, many kernels, likelihood maximization, etc.)
- Modern C++-11
- Generic framework (template-based / policy-based design), which allows for easy customization, to test novel ideas
- Experimental framework that allows user to easily test variants of experiments, compare treatments, submit jobs to clusters (OAR scheduler), etc.
- High performance (in particular, Limbo can exploit multicore computers via Intel TBB and vectorize some operations via Eigen3)
- Purposely small to be easily maintained and quickly understood
Limbo shares many ideas with `Sferes2 <http://github.com/sferes2>`_, a similar framework for evolutionary computation.
Contents:
......@@ -52,3 +48,10 @@ Contents:
.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`
-----
.. bibliography:: guides/refs.bib
:style: plain
:cited:
:keyprefix: b-
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment