*Last updated Monday, 22 May 2017.*

=====================================================================================================

**What is GPyOpt?****Installation and setup****First steps with GPyOpt and Bayesian Optimization****Alternative GPyOpt interfaces: Standard, Modular and Spearmint****What can I do with GPyOpt?**- Bayesian optimization with arbitrary restrictions.
- Parallel Bayesian optimization.
- Mixing different types of variables.
- Armed bandits problems.
- Tuning Scikit-learn models.
- Integrating model hyperparameters.
- Input warping.
- Using various cost evaluations functions.
- Contextual variables.
- External objective evaluation.

**Currently supported models, acquisitions and initial designs**- Supported initial designs.
- Implementing new models.
- Implementing new acquisistion.

=====================================================================================================

GPyOpt is a tool for optimization (minimization) of black-box functions using Gaussian processes. It has been implemented in Python by the group of Machine Learning (at SITraN) of the University of Sheffield.

GPyOpt is based on GPy, a library for Gaussian process modeling in Python. Here you can also find some notebooks about GPy functionalities. GPyOpt is a tool for Bayesian Optimization but we also use it for academic dissemination in Gaussian Processes Summer Schools, where you can find some extra labs and a variety of talks on Gaussian processes and Bayesian optimization.

The purpose of this manual is to provide a guide to use GPyOpt. The framework is BSD-3 licensed and we welcome collaborators to develop new functionalities. If you have any question or suggestions about the notebooks, please write an issue in the GitHub repository.

The simplest way to install GPyOpt is using pip. Ubuntu users can do:

```
sudo apt-get install python-pip
pip install gpyopt
```

If you'd like to install from source, or want to contribute to the project (e.g. by sending pull requests via github), read on. Clone the repository in GitHub and add it to your $PYTHONPATH.

```
git clone [email protected]:SheffieldML/GPyOpt.git ~/SheffieldML
echo 'PYTHONPATH=$PYTHONPATH:~/SheffieldML' >> ~/.bashrc
```

There are a number of dependencies that you may need to install. Three of them are needed to ensure the good behaviour of the package. These are, GPy, numpy and scipy. Other dependencies, such as DIRECT, cma and pyDOE are optional and only are required for in some options of the module. All of them are pip installable.

The tutorial Introduction to Bayesian Optimization with GPyOpt reviews some basic concepts on Bayesian optimization and shows some basic GPyOpt functionalities. It is a manual for beginners who want to start using the package.

GPyOpt has different interfaces oriented to different types of users. Apart from the general interface (detailed in the introductory manual) you can use GPyOpt in a modular way: you can implement and use your some elements of the optimization process, such us a new model or acquisition function, but still use the main backbone of the package. You can check the GPyOpt: Modular Bayesian Optimization notebook if you are interested on using GPyOpt this way.

Also, we have developed and GPyOpt interface with Spearmint but this only covers some general features that are available in GPyOpt.

There are several options implemented in GPyOpt that allows to cover a wide range of specific optimization problems. We have implemented a collection of notebooks to explain these functionalities separately but they can be easily combined.

With GPyOpt you can solve optimization problems with arbitrary non trivial restrictions. Have a look to the notebook GPyOpt: Bayesian Optimization with fixed constraints if you want to know more about how to use GPyOpt in these type of problems.

The main bottleneck when using Bayesian optimization is the cost of evaluating the objective function. In the notebook GPyOpt: parallel Bayesian Optimization you can learn more about the different parallel methods currently implemented in GPyOpt.

In GPyOpt you can easily combine different types of variables in the optimization. Currently you can use discrete an continuous variables. The way GPyOpt handles discrete variables is by marginally optimizing the acquisition functions over combinations of feasible values. This may slow down the optimization if many discrete variables are used but it avoids rounding errors. See the notebook entitled GPyOpt: mixing different types of variables for further details.

Armed bandits optimization problems are a particular case of Bayesian Optimization that appear when the domain of the function to optimize is entirely discrete. This has several advantages with respect to optimize in continuous domains. The most remarkable is that the optimization of the acquisition function can be done by taking the $arg min$ of all candidate points while the rest of the BO theory applies. In the notebook GPyOpt: armed bandits optimization you can check how to use GPyOpt in these types of problems.

Scikit-learn is a very popular library with a large variety of useful methods in Machine Learning. Have a look to the notebook GPyOpt: configuring Scikit-learn methods to learn how learn the parameters of Scikit-learn methods using GPyOpt. You will learn how to automatically tune the parameters of a Support Vector Regression.

Maximum Likelihood estimation can be a very instable choice to tune the surrogate model hyper parameters, especially in the fist steps of the optimization. When using a GP model as a surrogate of your function you can integrate the most common acquisition functions with respect to the parameters of the model. Check the notebook GPyOpt: integrating model hyperparameters to check how to use this option.

TODO

The cost of evaluating the objective can be a crucial factor in the optimization process. Check the notebook GPyOpt: dealing with cost functions to learn how to use arbitrary cost functions, including the objective evaluation time.

During the optimization phase, you may want to fix the value of some of the variables. These variables are called context as they are part of the objective but are fixed when the aquisition is optimized, you can learn how to use them in this notebook.

If you cannot define your objective function in Python, you have an option of evaluating it externally, and calling GPyOpt to suggest the next locations to evaluate. This approach is illustrated here.

Currently, you can initialize your model with three types of initial designs:

- Random,
- Latin Hypercubes and
- Sobol sequences.

Check this notebook to check how these designs look in a small example.

The currently available acquisition functions in GPyOpt are:

- Expected Improvement.
- Maximum Probability of Improvement.
- Lower Confidence Bound.

On top of this, if you want to implement your own model you can learn how to that in this notebook.