PyXAB - Python X-Armed Bandit

PyXAB is a Python open-source library for X-armed bandit algorithms, a prestigious set of optimizers for online black-box optimization and hyperparameter optimization.

PyXAB contains the implementations of 10+ optimization algorithms, including the classic ones such as Zooming, StoSOO, and HCT, and the most recent works such as GPO, StroquOOL and VHCT. PyXAB also provides the most commonly-used synthetic objectives to evaluate the performance of different algorithms and the implementations for different hierarchical partitions

PyXAB is featured for:

• User-friendly APIs, clear documentation, and detailed examples
• Comprehensive library of optimization algorithms, partitions and synthetic objectives
• High standard code quality and high testing coverage
• Low dependency for flexible combination with other packages such as PyTorch, Scikit-Learn

Reminder: The algorithms are maximization algorithms!

Quick Links

• Quick Example
• Documentations
• Installation
• Features
  • X-armed bandit algorithms
  • Hierarchical partition
  • Synthetic objectives
• Contributing
• Citations

Quick Example

PyXAB follows a natural and straightforward API design completely aligned with the online blackbox optimization paradigm. The following is a simple 6-line usage example.

First, we define the parameter domain and the algorithm to run. At every round t, call algo.pull(t) to get a point and call algo.receive_reward(t, reward) to give the algorithm the objective evaluation (reward)

domain = [[0, 1]]               # Parameter is 1-D and between 0 and 1
algo = T_HOO(rounds=1000, domain=domain) 
for t in range(1000):
    point = algo.pull(t)
    reward = 1                  #TODO: User-defined objective returns the reward
    algo.receive_reward(t, reward)

More detailed examples can be found here

Documentations

• The most up-to-date documentations

• The roadmap for our project

• Our manuscript for the library

Installation

To install via pip, run the following lines of code

pip install PyXAB                 # normal install
pip install --upgrade PyXAB       # or update if needed

To install via git, run the following lines of code

git clone https://github.com/WilliamLwj/PyXAB.git
cd PyXAB
pip install .

Features:

X-armed bandit algorithms

• Algorithm starred are meta-algorithms (wrappers)

Hierarchical partition

Synthetic objectives

• Some of these objectives can be found on Wikipedia

Objectives	Image
Garland
DoubleSine
DifficultFunc
Ackley
Himmelblau
Rastrigin

Contributing

We appreciate all forms of help and contributions, including but not limited to

• Star and watch our project
• Open an issue for any bugs you find or features you want to add to our library
• Fork our project and submit a pull request with your valuable codes

Please read the contributing instructions before submitting a pull request.

Citations

If you use our package in your research or projects, we kindly ask you to cite our work

@misc{Li2023PyXAB,
  doi = {10.48550/ARXIV.2303.04030},
  url = {https://arxiv.org/abs/2303.04030},
  author = {Li, Wenjie and Li, Haoze and Honorio, Jean and Song, Qifan},
  title = {PyXAB -- A Python Library for $\mathcal{X}$-Armed Bandit and Online Blackbox Optimization Algorithms},
  publisher = {arXiv},
  year = {2023},
}

We would also appreciate it if you could cite our related works.

@article{li2023optimumstatistical,
    title={Optimum-statistical Collaboration Towards General and Efficient Black-box Optimization},
    author={Wenjie Li and Chi-Hua Wang and Guang Cheng and Qifan Song},
    journal={Transactions on Machine Learning Research},
    issn={2835-8856},
    year={2023},
    url={https://openreview.net/forum?id=ClIcmwdlxn},
    note={}
}

@misc{li2022Federated,
  doi = {10.48550/ARXIV.2205.15268},
  url = {https://arxiv.org/abs/2205.15268}, 
  author = {Li, Wenjie and Song, Qifan and Honorio, Jean and Lin, Guang},
  title = {Federated X-Armed Bandit},
  publisher = {arXiv},
  year = {2022},
}