Package: dragonfly-opt
Dragonfly is an open source python library for scalable Bayesian optimisation.Bayesian optimisation is used for optimising black-box functions whose evaluations are
usually expensive. Beyond vanilla optimisation techniques, Dragonfly provides an array of tools to
scale up Bayesian optimisation to expensive large scale problems.
These include features/functionality that are especially suited for
high dimensional optimisation (optimising for a large number of variables),
parallel evaluations in synchronous or asynchronous settings (conducting multiple
evaluations in parallel), multi-fidelity optimisation (using cheap approximations
to speed up the optimisation process), and multi-objective optimisation (optimising
multiple functions simultaneously).Dragonfly is compatible with Python2 (>= 2.7) and Python3 (>= 3.5) and has been tested
on Linux, macOS, and Windows platforms.
For documentation, installation, and a getting started guide, see ourreadthedocs page. For more details, see
ourpaper.InstallationSeeherefor detailed instructions on installing Dragonfly and its dependencies.Quick Installation:If you have done this kind of thing before, you should be able to install
Dragonfly viapip.$sudoapt-getinstallpython-devpython3-devgfortran# On Ubuntu/Debian$pipinstallnumpy
$pipinstalldragonfly-opt-vTesting the Installation:
You can import Dragonfly in python to test if it was installed properly.
If you have installed via source, make sure that you move to a different directory
to avoid naming conflicts.$python
>>>fromdragonflyimportminimise_function
>>># The first argument below is the function, the second is the domain, and the third is the budget.>>>min_val,min_pt,history=minimise_function(lambdax:x**4-x**2+0.1*x,[[-10,10]],10);...
>>>min_val,min_pt(-0.32122746026750953,array([-0.7129672]))Due to stochasticity in the algorithms, the above values formin_val,min_ptmay be
different. If you run it for longer (e.g.min_val, min_pt, history = minimise_function(lambda x: x ** 4 - x**2 + 0.1 * x, [[-10, 10]], 100)),
you should get more consistent values for the minimum.If the installation fails or if there are warning messages, see detailed instructionshere.Quick StartDragonfly can be
used directly in the command line by callingdragonfly-script.pyor be imported in python code via themaximise_functionfunction in the main library
or inask-tellmode.
To help get started, we have provided some examples in theexamplesdirectory.
See our readthedocs getting started pages
(command line,Python,Ask-Tell)
for examples and use cases.Command line:
Below is an example usage in the command line.$cdexamples
$dragonfly-script.py--configsynthetic/branin/config.json--optionsoptions_files/options_example.txtIn Python code:
The main APIs for Dragonfly are defined indragonfly/apis.
For their definitions and arguments, seedragonfly/apis/opt.pyanddragonfly/apis/moo.py.
You can import the main API in python code via,fromdragonflyimportminimise_function,maximise_functionfunc=lambdax:x**4-x**2+0.1*xdomain=[[-10,10]]max_capital=100min_val,min_pt,history=minimise_function(func,domain,max_capital)print(min_val,min_pt)max_val,max_pt,history=maximise_function(lambdax:-func(x),domain,max_capital)print(max_val,max_pt)Here,funcis the function to be maximised,domainis the domain over whichfuncis to be optimised,
andmax_capitalis the capital available for optimisation.
The domain can be specified via a JSON file or in code.
Seehere,here,here,here,here,here,here,here,here,here,
andherefor more detailed examples.In Ask-Tell Mode:
Ask-tell mode provides you more control over your experiments where you can supply past results
to our API in order to obtain a recommendation.
See thefollowing examplefor more details.For a comprehensive list of uses cases, including multi-objective optimisation,
multi-fidelity optimisation, neural architecture search, and other optimisation
methods (besides Bayesian optimisation), see our readthe docs pages
(command line,Python,Ask-Tell)).ContributorsKirthevasan Kandasamy:github,webpageKarun Raju Vysyaraju:github,linkedinAnthony Yu:github,linkedinWillie Neiswanger:github,webpageBiswajit Paria:github,webpageChris Collins:github,webpageAcknowledgementsResearch and development of the methods in this package were funded by
DOE grant DESC0011114, NSF grant IIS1563887, the DARPA D3M program, and AFRL.CitationIf you use any part of this code in your work, please cite ourJMLR paper.@article{JMLR:v21:18-223,
  author  = {Kirthevasan Kandasamy and Karun Raju Vysyaraju and Willie Neiswanger and Biswajit Paria and Christopher R. Collins and Jeff Schneider and Barnabas Poczos and Eric P. Xing},
  title   = {Tuning Hyperparameters without Grad Students: Scalable and Robust Bayesian Optimisation with Dragonfly},
  journal = {Journal of Machine Learning Research},
  year    = {2020},
  volume  = {21},
  number  = {81},
  pages   = {1-27},
  url     = {http://jmlr.org/papers/v21/18-223.html}
}LicenseThis software is released under the MIT license. For more details, please referLICENSE.txt.For questions, please emailkandasamy@cs.cmu.edu."Copyright 2018-2019 Kirthevasan Kandasamy"