{"id":30957268,"url":"https://github.com/williamlwj/pyxab","last_synced_at":"2025-09-11T13:45:11.081Z","repository":{"id":37381110,"uuid":"470722183","full_name":"WilliamLwj/PyXAB","owner":"WilliamLwj","description":"PyXAB - A Python Library for X-Armed Bandit and Online Blackbox Optimization Algorithms","archived":false,"fork":false,"pushed_at":"2024-10-24T22:54:33.000Z","size":14441,"stargazers_count":126,"open_issues_count":4,"forks_count":30,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-09-04T10:58:00.874Z","etag":null,"topics":["algorithm","automl","bandit-algorithms","blackbox-optimization","continuous-armed-bandit","data-science","hyperparameter-optimization","hyperparameter-tuning","lipschitz-bandit","machine-learning","machine-learning-algorithms","online-learning","optimization","optimization-algorithms","reinforcement-learning","x-armed-bandit"],"latest_commit_sha":null,"homepage":"https://pyxab.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WilliamLwj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-16T19:21:23.000Z","updated_at":"2025-09-02T09:35:06.000Z","dependencies_parsed_at":"2023-02-18T17:30:50.584Z","dependency_job_id":"83994b29-7f67-4677-8c94-13ae0b707ab4","html_url":"https://github.com/WilliamLwj/PyXAB","commit_stats":{"total_commits":273,"total_committers":3,"mean_commits":91.0,"dds":"0.20879120879120883","last_synced_commit":"fdf27f71b7ec5b6dadd064d9ffdc09963919ec11"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/WilliamLwj/PyXAB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamLwj%2FPyXAB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamLwj%2FPyXAB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamLwj%2FPyXAB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamLwj%2FPyXAB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WilliamLwj","download_url":"https://codeload.github.com/WilliamLwj/PyXAB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamLwj%2FPyXAB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274648319,"owners_count":25324299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","automl","bandit-algorithms","blackbox-optimization","continuous-armed-bandit","data-science","hyperparameter-optimization","hyperparameter-tuning","lipschitz-bandit","machine-learning","machine-learning-algorithms","online-learning","optimization","optimization-algorithms","reinforcement-learning","x-armed-bandit"],"created_at":"2025-09-11T13:45:08.069Z","updated_at":"2025-09-11T13:45:11.040Z","avatar_url":"https://github.com/WilliamLwj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# PyXAB - Python *X*-Armed Bandit \n\n\n\u003cp align=\"left\"\u003e\n\u003ca style=\"border-width:0\" href=\"https://doi.org/10.21105/joss.06507\"\u003e\n  \u003cimg src=\"https://joss.theoj.org/papers/10.21105/joss.06507/status.svg\" alt=\"DOI badge\" \u003e\n\u003c/a\u003e\n\u003ca href=\"https://zenodo.org/doi/10.5281/zenodo.13743085\"\u003e\n       \u003cimg src=\"https://zenodo.org/badge/470722183.svg\" alt=\"DOI\" /\u003e\n\u003c/a\u003e\n\u003ca href='https://pypi.org/project/PyXAB/'\u003e\n       \u003cimg src='https://img.shields.io/pypi/v/PyXAB.svg?color=yellow' alt='PyPI version' /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/WilliamLwj/PyXAB\" \u003e \n \u003cimg src=\"https://codecov.io/gh/WilliamLwj/PyXAB/branch/main/graph/badge.svg?token=VACRX9AQBM\"/\u003e \n \u003c/a\u003e\n\u003ca href='https://pyxab.readthedocs.io/en/latest/?badge=latest'\u003e\n    \u003cimg src='https://readthedocs.org/projects/pyxab/badge/?version=latest' alt='Documentation Status' /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/WilliamLwj/PyXAB/actions/workflows/codeql.yml\" target=\"blank\"\u003e\n\u003cimg src=\"https://github.com/WilliamLwj/PyXAB/actions/workflows/codeql.yml/badge.svg\" alt=\"Code style: black\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/WilliamLwj/PyXAB/actions/workflows/testing.yml\" target=\"blank\"\u003e\n\u003cimg src=\"https://github.com/WilliamLwj/PyXAB/actions/workflows/testing.yml/badge.svg\" alt=\"testing\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/WilliamLwj/PyXAB/fork\" target=\"blank\"\u003e\n\u003cimg src=\"https://img.shields.io/github/forks/WilliamLwj/PyXAB?\" alt=\"github-PyXAB forks\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/WilliamLwj/PyXAB/stargazers\" target=\"blank\"\u003e\n\u003cimg src=\"https://img.shields.io/github/stars/WilliamLwj/PyXAB?\" alt=\"github-PyXAB stars\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pepy.tech/project/pyxab\" target=\"blank\"\u003e\n\u003cimg src=\"https://static.pepy.tech/badge/pyxab\" alt=\"downloads\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/WilliamLwj/PyXAB/blob/main/LICENSE\" target=\"blank\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/WilliamLwj/PyXAB?color=purple\" alt=\"github-PyXAB license\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/psf/black\" target=\"blank\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code style: black\" /\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\nPyXAB is a Python open-source library for *X*-armed bandit algorithms, a prestigious set of optimizers for online black-box optimization and \nhyperparameter optimization.\n\n\n\u003cp align='center'\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/HCT_trajectory.gif\" alt=\"trajectory\" width=\"48%\"/\u003e  \n  \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/HCT_heatmap.gif\" alt=\"heatmap\" width=\"48%\"/\u003e  \n\u003c/p\u003e\n\nPyXAB contains the implementations of **10+** optimization algorithms, including the classic ones such as [Zooming](https://arxiv.org/pdf/0809.4882.pdf), \n [StoSOO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/StoSOO.py), and [HCT](https://proceedings.mlr.press/v32/azar14.html), and the most\nrecent works such as [GPO](https://proceedings.mlr.press/v98/xuedong19a.html), [StroquOOL](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/StroquOOL.py) and [VHCT](https://arxiv.org/abs/2106.09215).\nPyXAB also provides the most commonly-used synthetic objectives to evaluate the performance of different algorithms and the implementations for different hierarchical partitions\n\n**PyXAB is featured for:**\n\n- **User-friendly APIs, clear documentation, and detailed examples**\n- **Comprehensive library** of optimization algorithms, partitions and synthetic objectives\n- **High standard code quality and high testing coverage**\n- **Low dependency** for flexible combination with other packages such as PyTorch, Scikit-Learn\n\n**Reminder**: The algorithms are maximization algorithms!\n\n## Quick Links\n\n- [Quick Example](#Quick-Example)\n- [Documentations](#Documentations)\n- [Installation](#Installation)\n- [Features](#Features)\n  * [*X*-armed bandit algorithms](#Stochastic-X-armed-bandit-algorithms)\n  * [Hierarchical partition ](#Hierarchical-partition)\n  * [Synthetic objectives](#Synthetic-objectives)\n- [Contributing](#Contributing)\n- [Citations](#Citations)\n\n## Quick Example\nPyXAB follows a natural and straightforward API design completely aligned with the online blackbox\noptimization paradigm. The following is a simple 6-line usage example.\n\nFirst, we define the parameter domain and the algorithm to run. \nAt every round  `t`, call `algo.pull(t)` to get a point and call \n`algo.receive_reward(t, reward)` to give the algorithm the objective evaluation (reward)\n\n```python3\nfrom PyXAB.algos.HOO import T_HOO\n\ndomain = [[0, 1]]               # Parameter is 1-D and between 0 and 1\nalgo = T_HOO(rounds=1000, domain=domain) \nfor t in range(1000):\n    point = algo.pull(t)\n    reward = 1                  #TODO: User-defined objective returns the reward\n    algo.receive_reward(t, reward)\n```\n\nMore detailed examples can be found [here](https://pyxab.readthedocs.io/en/latest/getting_started/auto_examples/index.html)\n\n## Documentations\n\n  * The most up-to-date [documentations](https://pyxab.readthedocs.io/) \n\n  * The [roadmap](https://github.com/users/WilliamLwj/projects/1) for our project    \n  \n  * Our [manuscript](https://arxiv.org/abs/2303.04030) for the library\n\n## Installation\n\nTo install via pip, run the following lines of code\n```bash\npip install PyXAB                 # normal install\npip install --upgrade PyXAB       # or update if needed\n```\n\n\nTo install via git, run the following lines of code\n```bash\ngit clone https://github.com/WilliamLwj/PyXAB.git\ncd PyXAB\npip install .\n```\n\n\n## Features:\n\n### *X*-armed bandit algorithms\n\n* Algorithm starred are meta-algorithms (wrappers)\n\n| Algorithm                                                                           | Research Paper                                                                                                                                                                           | Year |\n|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|\n| [Zooming](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/Zooming.py)     | [Multi-Armed Bandits in Metric Spaces](https://arxiv.org/pdf/0809.4882.pdf)                                                                                                              | 2008 |\n| [T-HOO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/HOO.py)           | [*X*-Armed Bandit](https://jmlr.org/papers/v12/bubeck11a.html)                                                                                                                           | 2011 |\n| [DOO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/DOO.py)             | [Optimistic Optimization of a Deterministic Function without the Knowledge of its Smoothness](https://proceedings.neurips.cc/paper/2011/file/7e889fb76e0e07c11733550f2a6c7a5a-Paper.pdf) | 2011 |\n| [SOO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/SOO.py)             | [Optimistic Optimization of a Deterministic Function without the Knowledge of its Smoothness](https://proceedings.neurips.cc/paper/2011/file/7e889fb76e0e07c11733550f2a6c7a5a-Paper.pdf) | 2011 |\n| [StoSOO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/StoSOO.py)       | [Stochastic Simultaneous Optimistic Optimization](http://proceedings.mlr.press/v28/valko13.pdf)                                                                                          | 2013 |\n| [HCT](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/HCT.py)             | [Online Stochastic Optimization Under Correlated Bandit Feedback](https://proceedings.mlr.press/v32/azar14.html)                                                                         | 2014 |\n| [POO*](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/POO.py)            | [Black-box optimization of noisy functions with unknown smoothness](https://papers.nips.cc/paper/2015/hash/ab817c9349cf9c4f6877e1894a1faa00-Abstract.html)                               | 2015 |\n| [GPO*](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/GPO.py)            | [General Parallel Optimization Without A Metric](https://proceedings.mlr.press/v98/xuedong19a.html)                                                                                      | 2019 |\n| [PCT](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/PCT.py)             | [General Parallel Optimization Without A Metric](https://proceedings.mlr.press/v98/xuedong19a.html)                                                                                      | 2019 |\n| [SequOOL](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/SequOOL.py)     | [A Simple Parameter-free And Adaptive Approach to Optimization Under A Minimal Local Smoothness Assumption](https://arxiv.org/pdf/1810.00997.pdf)                                        | 2019 |\n| [StroquOOL](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/StroquOOL.py) | [A Simple Parameter-free And Adaptive Approach to Optimization Under A Minimal Local Smoothness Assumption](https://arxiv.org/pdf/1810.00997.pdf)                                        | 2019 |\n| [VROOM](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/VROOM.py)         | [Derivative-Free \u0026 Order-Robust Optimisation](https://arxiv.org/pdf/1910.04034.pdf)                                                                                                      | 2020 |\n| [VHCT](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/VHCT.py)           | [Optimum-statistical Collaboration Towards General and Efficient Black-box Optimization](https://openreview.net/forum?id=ClIcmwdlxn)                                                     | 2023 |\n| [VPCT](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/VPCT.py)           | N.A. ([GPO](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/GPO.py) + [VHCT](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/algos/VHCT.py))                               | N.A. |\n\n\n### Hierarchical partition \n\n| Partition                                                                                                             | Description                                                                                                        |\n|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|\n| [BinaryPartition](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/partition/BinaryPartition.py)                   | Equal-size binary partition of the parameter space, the split dimension is chosen uniform randomly                 |\n| [RandomBinaryPartition](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/partition/RandomBinaryPartition.py)       | Random-size binary partition of the parameter space, the split dimension is chosen uniform randomly                |\n| [DimensionBinaryPartition](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/partition/DimensionBinaryPartition.py) | Equal-size partition of the space with a binary split on each dimension, the number of children of one node is 2^d |\n| [KaryPartition](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/partition/KaryPartition.py)       | Equal-size K-ary partition of the parameter space, the split dimension is chosen uniform randomly                  |\n| [RandomKaryPartition](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/partition/RandomKaryPartition.py) | Random-size K-ary partition of the parameter space, the split dimension is chosen uniform randomly                 |\n\n### Synthetic objectives\n\n* Some of these objectives can be found [on Wikipedia](https://en.wikipedia.org/wiki/Test_functions_for_optimization)\n\n| Objectives \u003cimg width=200/\u003e| Image | \n| --- |--- |\n| [Garland](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/Garland.py) | \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/Garland.png\" alt=\"Garland\" width=\"100\"/\u003e |\n| [DoubleSine](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/DoubleSine.py)  | \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/DoubleSine.png\" alt=\"DoubleSine\" width=\"100\"/\u003e  |\n| [DifficultFunc](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/DifficultFunc.py) | \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/DifficultFunc.png\" alt=\"DifficultFunc\" width=\"100\"/\u003e  |\n| [Ackley](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/Ackley.py) | \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/Ackley.png\" alt=\"Ackley\" width=\"100\"/\u003e  |\n| [Himmelblau](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/Himmelblau.py) | \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/Himmelblau.png\" alt=\"Himmelblau\" width=\"100\"/\u003e  |\n| [Rastrigin](https://github.com/WilliamLwj/PyXAB/blob/main/PyXAB/synthetic_obj/Rastrigin.py) |  \u003cimg src=\"https://raw.githubusercontent.com/WilliamLwj/PyXAB/main/figs/synthetic/Rastrigin.png\" alt=\"Rastrigin\" width=\"100\"/\u003e  |\n\n\n## Contributing\n\nWe appreciate all forms of help and contributions, including but not limited to\n\n* Star and watch our project\n* Open an issue for any bugs you find or features you want to add to our library\n* Fork our project and submit a pull request with your valuable codes\n\nPlease read the [contributing instructions](https://pyxab.readthedocs.io/en/latest/info/contributing.html) before submitting\na pull request.\n\n\n## Citations\nIf you use our package in your research or projects, we kindly ask you to cite our work\n\n```text\n@article{Li2023PyXAB,\n  doi = {10.21105/joss.06507},\n  url = {https://joss.theoj.org/papers/10.21105/joss.06507},\n  author = {Li, Wenjie and Li, Haoze and Song, Qifan and Honorio, Jean},\n  title = {PyXAB -- A Python Library for $\\mathcal{X}$-Armed Bandit and Online Blackbox Optimization Algorithms},\n  journal={Journal of Open Source Software},\n  year = {2024},\n  issn={2475-9066},\n}\n```\n\nWe would also appreciate it if you could cite our related works.\n\n```text\n@article{li2023optimumstatistical,\n    title={Optimum-statistical Collaboration Towards General and Efficient Black-box Optimization},\n    author={Wenjie Li and Chi-Hua Wang and Guang Cheng and Qifan Song},\n    journal={Transactions on Machine Learning Research},\n    issn={2835-8856},\n    year={2023},\n    url={https://openreview.net/forum?id=ClIcmwdlxn},\n    note={}\n}\n```\n\n```text\n\n@article{Li2022Federated,\n  title={Federated $\\chi$-armed Bandit}, \n  volume={38}, \n  url={https://ojs.aaai.org/index.php/AAAI/article/view/29267}, \n  DOI={10.1609/aaai.v38i12.29267}, \n  number={12},\n  journal={Proceedings of the AAAI Conference on Artificial Intelligence}, \n  author={Li, Wenjie and Song, Qifan and Honorio, Jean and Lin, Guang}, \n  year={2024}, \n  month={Mar.}, \n  pages={13628-13636} \n\n}\n```\n\n\n\n```text\n\n@InProceedings{Li2024Personalized,\n  title = \t {Personalized Federated $\\chi$-armed Bandit},\n  author =       {Li, Wenjie and Song, Qifan and Honorio, Jean},\n  booktitle = \t {Proceedings of The 27th International Conference on Artificial Intelligence and Statistics},\n  pages = \t {37--45},\n  year = \t {2024},\n  editor = \t {Dasgupta, Sanjoy and Mandt, Stephan and Li, Yingzhen},\n  volume = \t {238},\n  series = \t {Proceedings of Machine Learning Research},\n  month = \t {02--04 May},\n  publisher =    {PMLR},\n  pdf = \t {https://proceedings.mlr.press/v238/li24a/li24a.pdf},\n  url = \t {https://proceedings.mlr.press/v238/li24a.html},\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamlwj%2Fpyxab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamlwj%2Fpyxab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamlwj%2Fpyxab/lists"}