deodorant.core

Core functions of Deodorant.

bo-acquire

(bo-acquire X Y acq-optimizer scaling-funcs & {:keys [cov-fn-form grad-cov-fn-hyper-form mean-fn-form gp-hyperprior-form hmc-step-size hmc-num-leapfrog-steps hmc-num-mcmc-steps hmc-num-opt-steps hmc-num-chains hmc-burn-in-proportion hmc-max-gps verbose debug-folder plot-aq b-deterministic], :or {}})
Performs the acquisition step in Bayesian optimization. Accepts a
sequence inputs and outputs and returns the next point x-next to
evaluate, the index of the point from those previously evaluated
that is considered to be the best, and the predicted mean and std-dev
of the evaluated points.  Note this std-dev is in the estimate of the
'true' function value at this point and does not include the noise involved
in evaluating this function.

Accepts:
  X - matrix of input points, first dimension represents differnt points
    second dimension the different input dimensions
  Y - a vector of associated outputs
  acq-optimizer - a function that takes in the acquistion function as
    input and returns a point in the space of x that is the estimated
    optimum of the acquisition function, subject to the constraints of
    the model.
  scaling-funcs - scaling function object ouput from sf/setup-scaling-funcs

Options (each of these is provide as a key value pair, defaults are
             not provided as these are set by deodorant which calls this
             function which should be consulted for further info)
    cov-fn-form grad-cov-fn-hyper-form mean-fn-form
    gp-hyperprior-form hmc-step-size hmc-num-leapfrog-steps
    hmc-num-mcmc-steps hmc-num-opt-steps hmc-num-chains
    hmc-burn-in-proportion hmc-max-gps verbose debug-folder plot-aq]

Returns:
  x-next - point that should be evaluated next (optimum of the acquistion
           function)
  i-best - index of the point expected to be most optimal under the mixture
           of GPs posterior
  means - estimated mean value for each point in X.
  std-devs - estimated standard deviation for each point in X.

deodorant

(deodorant f aq-optimizer theta-sampler & {:keys [initial-points num-scaling-thetas num-initial-points cov-fn-form grad-cov-fn-hyper-form mean-fn-form gp-hyperprior-form b-deterministic hmc-step-size hmc-num-leapfrog-steps hmc-num-mcmc-steps hmc-num-opt-steps hmc-num-chains hmc-burn-in-proportion hmc-max-gps verbose debug-folder plot-aq], :or {b-deterministic false, debug-folder nil, hmc-step-size 0.01, hmc-num-chains 4, cov-fn-form cf/matern32-plus-matern52-K, hmc-num-leapfrog-steps 2, num-scaling-thetas 1000, verbose false, hmc-num-opt-steps 10, gp-hyperprior-form dp/default-double-matern-hyperprior, hmc-num-mcmc-steps 20, num-initial-points 5, mean-fn-form dp/default-mean-fn-form, hmc-burn-in-proportion 0.5, plot-aq false, hmc-max-gps 20, initial-points nil, grad-cov-fn-hyper-form cf/matern32-plus-matern52-grad-K}})
Deodorant: solving the problems of Bayesian optimization.

Deodorant is a Bayesian optimization (BO) package with three core features:
  1) Domain scaling to exploit problem independent GP hyperpriors
  2) A non-stationary mean function to allow unbounded optimization
  3) External provision of the acquisition function optimizer so that this
     can incorporate the constraints of the problem (inc equality constraints)
     and ensure that no invalid points are evaluated.

The main intended use of the package at present is as the BO component
for BOPP (Bayesian Optimiation for Probabilistic Programs. Rainforth T, Le TA,
van de Meent J-W, Osborne MA, Wood F. In NIPS 2016) which provides all the
required inputs automatically given a program.  Even when the intention is
simply optimization, using BOPP rather than Deodorant directly is currently
recommended.  The rational of providing Deodorant as its own independent
package is to seperate out the parts of BOPP that are Anglican dependent and
those that are not.  As such, one may wish to intergrate Deodorant into
another similar package that provides all the required inputs.

For details on the working of Deodorant, the previously referenced paper and
its supplementary material should be consulted.

Accepts:
  f - target function.  Takes in a single input x and returns a pair
      [f(x), other-outputs(x)].  Here other-outputs allows for additional x
      dependent variables to be returned.  For example, in BOPP then
      other-outputs(x) is a vector of program outputs from the calling the
      marginal query, with one component for each sample output from
      this marginal query.
  acq-optimizer - a function that takes in the acquistion function as
      input and returns a point in the space of x that is the estimated
      optimum of the acquisition function, subject to the constraints of
      the model.
  theta-sampler - charecterization of the input variables which can be
      sampled from to generate example inputs and initialize the scaling.
      Should be a function that takes no inputs and results valid examples
      of the input variables.  Note that the input variables are currently
      called x in the inner functions.

Optional Inputs: (defined with key value pairs, default values shown below
                  in brackets)
  Initialization options:
    :initial-points - Points to initialize BO in addition to those sampled
                     by theta-sampler
      [nil]
    :num-scaling-thetas - Number of points used to initialize scaling
      [50]
    :num-initial-points - Number of points to initialize BO
      [5]

  GP options:
    :cov-fn-form - covariance function with unset hyperparameters
      [cp/matern32-plus-matern52-K]
    :grad-cov-fn-hyper - grad of the above with respect to the hyperparameters
      [cp/matern32-plus-matern52-grad-K]
    :mean-fn-form - mean function with unset dimensionality
      [dp/default-mean-fn-form]
    :gp-hyperprior-form - constructor for the gp hyperparameter hyperprior
      [dp/default-double-matern-hyperprior]
    :b-deterministic - whether to include noise in the GP
      [false]

  HMC options:
    :hmc-step-size - HMC step size
      [0.3]
    :hmc-num-leapfrog-steps - Number of HMC leap-frog steps
      [5]
    :hmc-num-chains - Number of samplers run in parallel
      [50]
    :hmc-burn-in-proportion - Proportion of samples to throw away as burn in
      [8]
    :hmc-max-gps - Maximum number of unique GPs to keep at the end so that
                   optimization of the acqusition function does not become
                   too expensive.
      [50]
  Debug options:
    :verbose - Allow debug print outs
      [false]
    :debug-folder - Path for the debug folder.  No output generated if path
              not  provided.  These outputs include alphas (gp hyper paramters),
              gp-weights (weights for each hyperparameter sample) etc
      [empty]
    :bo-plot-aq - Generate debugging csv of acquisition functions
      [false]

Returns:
  Lazy list of increasingly optimal triples
  (theta, main output of f, other outputs of f).