Commit 3cec1aa0 authored by Jean-Baptiste Mouret's avatar Jean-Baptiste Mouret
Browse files

working on the doc

parent 9789970f
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="13.3">
<zoom_level>7</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>539</x>
<y>231</y>
<w>133</w>
<h>35</h>
</coordinates>
<panel_attributes>BoOptimizer&lt;Params, ...&gt;
--
layer=1
bg=white
group=1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>532</x>
<y>161</y>
<w>147</w>
<h>126</h>
</coordinates>
<panel_attributes>bayes_opt
--
bg=#aaaaaa
layer=-2
group=1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>539</x>
<y>189</y>
<w>133</w>
<h>28</h>
</coordinates>
<panel_attributes>BoBase&lt;Params, ...&gt;
--
bg=#ffffff
layer=1
group=1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>588</x>
<y>210</y>
<w>21</w>
<h>42</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-
group=1</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0</additional_attributes>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>392</x>
<y>427</y>
<w>70</w>
<h>126</h>
</coordinates>
<panel_attributes>acqui
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>245</x>
<y>413</y>
<w>140</w>
<h>140</h>
</coordinates>
<panel_attributes>init
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>497</x>
<y>588</y>
<w>112</w>
<h>91</h>
</coordinates>
<panel_attributes>kernel
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>385</x>
<y>588</y>
<w>91</w>
<h>91</h>
</coordinates>
<panel_attributes>mean
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>252</x>
<y>441</y>
<w>126</w>
<h>56</h>
</coordinates>
<panel_attributes>RandomSampling
RandomSamplingGrid
GridSampling
NoInit
bg=#aaaaff
layer=1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>504</x>
<y>609</y>
<w>98</w>
<h>56</h>
</coordinates>
<panel_attributes>Exp
MaternFiveHalfs
MaternThreeHalfs
SquaredExpARD
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>399</x>
<y>448</y>
<w>56</w>
<h>35</h>
</coordinates>
<panel_attributes>UCB
GP_UCB
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>392</x>
<y>609</y>
<w>77</w>
<h>56</h>
</coordinates>
<panel_attributes>Constant
Data
FunctionARD
NullFunction
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>469</x>
<y>420</y>
<w>56</w>
<h>133</h>
</coordinates>
<panel_attributes>model
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>546</x>
<y>441</y>
<w>126</w>
<h>98</h>
</coordinates>
<panel_attributes>Cmaes
GridSearch
ParallelRepeater
Random_point
Rprop
NLOptGrad
NLOptNoGrad
NoInit
bg=#aaaaff
layer=1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>539</x>
<y>420</y>
<w>140</w>
<h>133</h>
</coordinates>
<panel_attributes>opt
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>693</x>
<y>420</y>
<w>287</w>
<h>133</h>
</coordinates>
<panel_attributes>stat
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>700</x>
<y>441</y>
<w>140</w>
<h>105</h>
</coordinates>
<panel_attributes>AggregatedObservations
BestAggregatedObservations
BestObservations
BestSamples
BlSamples
GPAcquisitions
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>994</x>
<y>441</y>
<w>98</w>
<h>42</h>
</coordinates>
<panel_attributes>ChainCriteria
MaxIterations
PredictedValue
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>987</x>
<y>420</y>
<w>112</w>
<h>133</h>
</coordinates>
<panel_attributes>stop
--
bg=#aaaaaa
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>847</x>
<y>441</y>
<w>126</w>
<h>105</h>
</coordinates>
<panel_attributes>GPKernelHParams
GPLikelihood
GPMeanHParams
GPPredictionDifferences
Observations
Sample
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>476</x>
<y>441</y>
<w>35</w>
<h>35</h>
</coordinates>
<panel_attributes>GP
bg=#aaaaff</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>392</x>
<y>546</y>
<w>105</w>
<h>56</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>130.0;10.0;10.0;60.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>497</x>
<y>546</y>
<w>35</w>
<h>56</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;30.0;60.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>259</x>
<y>280</y>
<w>287</w>
<h>147</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>390.0;10.0;10.0;190.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>399</x>
<y>280</y>
<w>168</w>
<h>161</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>220.0;10.0;15.0;210.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>483</x>
<y>280</y>
<w>105</w>
<h>154</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>130.0;10.0;10.0;200.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>630</x>
<y>280</y>
<w>105</w>
<h>154</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;130.0;200.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>560</x>
<y>280</y>
<w>56</w>
<h>154</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>60.0;10.0;10.0;200.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>672</x>
<y>273</y>
<w>343</w>
<h>161</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;470.0;210.0</additional_attributes>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>231</x>
<y>98</y>
<w>882</w>
<h>602</h>
</coordinates>
<panel_attributes>limbo
--
bg=#cccccc
layer=-2</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>434</x>
<y>371</y>
<w>210</w>
<h>84</h>
</coordinates>
<panel_attributes>lt=&lt;.&gt;
optimize acquisition function</panel_attributes>
<additional_attributes>10.0;100.0;10.0;20.0;280.0;20.0;280.0;90.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>574</x>
<y>546</y>
<w>147</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;.&gt;
optimize hyper-parameters</panel_attributes>
<additional_attributes>10.0;10.0;10.0;80.0</additional_attributes>
</element>
</diagram>
#ifndef LIMBO_ACQUI_HPP
#define LIMBO_ACQUI_HPP
///@defgroup acqui
///@defgroup acqui_defaults
#include <limbo/acqui/ucb.hpp>
#include <limbo/acqui/gp_ucb.hpp>
......
......@@ -7,15 +7,14 @@
namespace limbo {
namespace defaults {
/**
\defgroup defaults
*/
struct acqui_gpucb {
/// \ingroup defaults
/// @ingroup acqui_defaults
BO_PARAM(double, delta, 0.001);
};
}
namespace acqui {
/// @ingroup acqui
/// GP-UCB (UCB with regret)
template <typename Params, typename Model>
class GP_UCB {
public:
......
......@@ -8,11 +8,13 @@
namespace limbo {
namespace defaults {
struct acqui_ucb {
/// \ingroup defaults
/// @ingroup acqui_defaults
BO_PARAM(double, alpha, 0.5);
};
}
namespace acqui {
/// @ingroup acqui
/// Classic UCB
template <typename Params, typename Model>
class UCB {
public:
......
......@@ -100,7 +100,6 @@ namespace limbo {
This class is templated by several types with default values (thanks to boost::parameters).
\rst
+----------------+---------+---------+---------------+
|type |typedef | argument| default |
+================+=========+=========+===============+
......@@ -114,6 +113,8 @@ namespace limbo {
+----------------+---------+---------+---------------+
|stopping crit. | stop_t | stopcrit| MaxIterations |
+----------------+---------+---------+---------------+
\endrst
For GP, the default value is: ``model::GP<Params, kf_t, mean_t, opt_t>>``,
- with ``kf_t = kernel::SquaredExpARD<Params>``
......@@ -124,7 +125,6 @@ namespace limbo {
For Statistics, the default value is: ``boost::fusion::vector<stat::Samples<Params>, stat::AggregatedObservations<Params>, stat::ConsoleSummary<Params>>``
\endrst
Example of customization:
......@@ -173,22 +173,22 @@ namespace limbo {
/// copy is disabled (dangerous and useless)
BoBase& operator=(const BoBase& other) = delete;
/// @return true if the statitics are enabled (they can be disabled to avoid dumping data, e.g. for unit tests)
/// return true if the statitics are enabled (they can be disabled to avoid dumping data, e.g. for unit tests)
bool stats_enabled() const { return Params::bayes_opt_bobase::stats_enabled(); }
/// @return the name of the directory in which results (statistics) are written
/// return the name of the directory in which results (statistics) are written
const std::string& res_dir() const { return _res_dir; }
///@return the vector of points of observations (observations can be multi-dimensional, hence the VectorXd) -- f(x)
/// return the vector of points of observations (observations can be multi-dimensional, hence the VectorXd) -- f(x)
const std::vector<Eigen::VectorXd>& observations() const { return _observations; }
///@return list of the points that have been evaluated so far (x)
/// return the list of the points that have been evaluated so far (x)
const std::vector<Eigen::VectorXd>& samples() const { return _samples; }
///@return list of blacklisted points
/// return the list of blacklisted points
const std::vector<Eigen::VectorXd>& bl_samples() const { return _bl_samples; }
///@return the current iteration number
/// return the current iteration number
int current_iteration() const { return _current_iteration; }
int total_iterations() const { return _total_iterations; }
......@@ -207,7 +207,7 @@ namespace limbo {
/// Add a new blacklisted sample
void add_new_bl_sample(const Eigen::VectorXd& s) { _bl_samples.push_back(s); }
/// Evaluate a sample and add the result to the 'database' (sample / observations vectors)
/// Evaluate a sample and add the result to the 'database' (sample / observations vectors) -- it does not update the model
template <typename StateFunction>
bool eval_and_add(const StateFunction& seval, const Eigen::VectorXd& sample)
{
......
......@@ -32,6 +32,27 @@ namespace limbo {
boost::parameter::optional<tag::modelfun>> boptimizer_signature;
// clang-format off
/**
The classic Bayesian optimization algorithm.
\rst
References: :cite:`brochu2010tutorial,Mockus2013`
\endrst
This class takes the same template parameters as BoBase. It adds:
\rst
+---------------------+------------+----------+---------------+
|type |typedef | argument | default |
+=====================+============+==========+===============+
|acqui. optimizer |acqui_opt_t | acquiopt | see below |
+---------------------+------------+----------+---------------+
\endrst
The default value of acqui_opt_t is:
- ``opt::Cmaes<Params>`` libcmaes was found
- ``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)
*/
template <class Params,
class A1 = boost::parameter::void_,
class A2 = boost::parameter::void_,
......@@ -53,7 +74,7 @@ namespace limbo {
typedef opt::GridSearch<Params> acquiopt_t;
#endif
};
/// link to the corresponding BoBase (useful for typedefs)
typedef BoBase<Params, A1, A2, A3, A4, A5> base_t;
typedef typename base_t::model_t model_t;
typedef typename base_t::acquisition_function_t acquisition_function_t;
......@@ -61,6 +82,7 @@ namespace limbo {
typedef typename boptimizer_signature::bind<A1, A2, A3, A4, A5, A6>::type args;
typedef typename boost::parameter::binding<args, tag::acquiopt, typename defaults::acquiopt_t>::type acqui_optimizer_t;
/// The main function (run the Bayesian optimization algorithm)
template <typename StateFunction, typename AggregatorFunction = FirstElem>
void optimize(const StateFunction& sfun, const AggregatorFunction& afun = AggregatorFunction(), bool reset = true)
{
......@@ -94,6 +116,7 @@ namespace limbo {
}
}
/// return the best observation so far (i.e. max(f(x)))
template <typename AggregatorFunction = FirstElem>
const Eigen::VectorXd& best_observation(const AggregatorFunction& afun = AggregatorFunction()) const
{
......@@ -103,6 +126,7 @@ namespace limbo {
return this->_observations[std::distance(rewards.begin(), max_e)];
}
/// return the best sample so far (i.e. the argmax(f(x)))
template <typename AggregatorFunction = FirstElem>
const Eigen::VectorXd& best_sample(const AggregatorFunction& afun = AggregatorFunction()) const
{
......
#ifndef LIMBO_INIT_HPP
#define LIMBO_INIT_HPP
///@defgroup init
///@defgroup init_defaults
#include <limbo/init/grid_sampling.hpp>
#include <limbo/init/no_init.hpp>
#include <limbo/init/random_sampling.hpp>
......
......@@ -8,10 +8,15 @@
namespace limbo {
namespace defaults {
struct init_gridsampling {
///@ingroup init_defaults
BO_PARAM(int, bins, 5);
};
}
namespace init {
///@ingroup init
///Grid sampling.
///