Commit 5bbf6b33 authored by Jean-Baptiste Mouret's avatar Jean-Baptiste Mouret
Browse files

improve documentation

parent ad905e40
......@@ -2,9 +2,9 @@ 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) corresponds to changing a template parameter of the optimizer.
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.
For the parameters of the algorithms themselves (e.g. an epsilon), they are given by a template class (usually called Params in our code, and always the first argument). See :doc:`parameters` for details.
The parameters of the algorithms (e.g. an epsilon) are given by a template class (usually called Params in our code, and always the first argument). See :doc:`parameters` for details.
To avoid defining each component of an optimizer manually, Limbo provides sensible defaults. In addition, Limbo relies on `Boost.Parameter <http://www.boost.org/doc/libs/1_60_0/libs/parameter/doc/html/index.html>`_ to make it easy to customize a single part. This Boost library allows us to write classes that accept template argument (user-defined custom classes) by name. For instance, to customize the stopping criteria:
......@@ -34,7 +34,16 @@ Class Structure
Click on the image to see it bigger.
Every class is paremetrized by a :ref:`Params <params-guide>` class that contains all the parameters.
There is almost no explicit inheritance in Limbo because polymorphism is not used. However, each kind of class follow a similar template (or 'concept'), that is, they have to implement the same methods. For instance, every initialization function must implement a `()` method:
.. code-block:: cpp
template <typename StateFunction, typename AggregatorFunction, typename Opt>
void operator()(const StateFunction& seval, const AggregatorFunction&, Opt& opt) const
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 graph
---------------
......
......@@ -8,13 +8,29 @@
namespace limbo {
namespace defaults {
struct acqui_gpucb {
/// @ingroup acqui_defaults
BO_PARAM(double, delta, 0.001);
/// @ingroup acqui_defaults
BO_PARAM(double, delta, 0.1);
};
}
namespace acqui {
/// @ingroup acqui
/// GP-UCB (UCB with regret)
/** @ingroup acqui
\rst
GP-UCB (Upper Confidence Bound). See :cite:`brochu2010tutorial`, p. 15. See also: http://arxiv.org/abs/0912.3995
.. math::
UCB(x) = \mu(x) + \kappa \sigma(x).
with:
.. math::
\kappa = \sqrt{2 \log{(\frac{n^{D/2+2}\pi^2}{3 \delta})}}
where :math:`n` is the number of past evaluations of the objective function and :math:`D` the dimensionality of the parameters (dim_in).
Parameters:
- `double delta` (a small number in [0,1], e.g. 0.1)
\endrst
*/
template <typename Params, typename Model>
class GP_UCB {
public:
......
......@@ -13,8 +13,17 @@ namespace limbo {
};
}
namespace acqui {
/// @ingroup acqui
/// Classic UCB
/** @ingroup acqui
\rst
Classic UCB (Upper Confidence Bound). See :cite:`brochu2010tutorial`, p. 14
.. math::
UCB(x) = \mu(x) + \alpha \sigma(x).
Parameters:
- ``double alpha``
\endrst
*/
template <typename Params, typename Model>
class UCB {
public:
......
......@@ -134,9 +134,6 @@ namespace limbo {
- ``typedef acqui::UCB<Params, GP_t> Acqui_t;``
- ``bayes_opt::BOptimizer<Params, modelfun<GP_t>, acquifun<Acqui_t>> opt;``
@see limbo::bayes_opt::Boptimizer
*/
class BoBase {
public:
......
......@@ -49,9 +49,9 @@ namespace limbo {
\endrst
The default value of acqui_opt_t is:
- ``opt::Cmaes<Params>`` libcmaes was found
- ``opt::Cmaes<Params>`` if libcmaes was found in `waf configure`
- ``opt::NLOptNoGrad<Params, nlopt::GN_DIRECT_L_RAND>`` if NLOpt was found but libcmaes was not found
- ``opt::GridSearch<Params>`` otherwise (please do not use this)
- ``opt::GridSearch<Params>`` otherwise (please do not use this: the algorithm will not work at all!)
*/
template <class Params,
class A1 = boost::parameter::void_,
......
Supports Markdown
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