Badger: The Go-To Optimizer in ACR
| Documentation | Package | Downloads | Version | Platforms | Tests |
|---|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
Introduction
Badger is an optimization interface tailored for the Accelerator Control Room (ACR)1. It places a strong emphasis on extensibility, easily expandable through the plugin system, and flexibility, offering complete GUI, CLI, and API support.
The primary goal of Badger is to establish a user-friendly interface bridging the gap between users and the machines undergoing optimization. Users only need to define an environment for each machine or simulation, allowing Badger to take charge of tasks such as connecting the problem and optimization algorithm, implementing control logic, visualizing progress, and archiving data.
Internally, Badger leverages the Xopt optimization library to drive the optimization process. This grants users the advantage of utilizing a variety of optimization algorithms available through Xopt.
Badger boasts a range of features designed to enhance your optimization experience:
- Plugin System: Easily add your optimization problem in just a few minutes.
- Versatile Modes: Enjoy full support for three modes: GUI, CLI2, and API, allowing you to use Badger according to your preferences.
- Efficient Rerun: With a single click or command2, rerun optimization tasks swiftly -- ideal for daily machine operation routines.
- History Exploration: Browse through past runs effortlessly.
- Optimal Solution Navigation: Jump to or set optimal solutions.
- State Recovery: Easily recover machine states after an optimization run.
- Constraint Support: Accommodate both soft and hard constraints.
- Data Preservation: Preserve all raw data for comprehensive analysis.
- Advanced Extensions: Benefit from extensions for sophisticated optimization data analysis and visualization.
For additional details about Badger and its capabilities, please refer to Badger's online documentation.
Installation
Using conda
conda install -c conda-forge badger-opt
or pip
pip install badger-opt
Currently, Badger only officially supports Linux. Badger on MacOS and Windows could be potentially unstable.
Thread configuration
Badger caps numeric library threads (OMP_NUM_THREADS, MKL_NUM_THREADS, OPENBLAS_NUM_THREADS) to 4 by default. This prevents performance degradation on high-core-count machines where the default (one thread per core) causes contention for the relatively small matrix operations in Bayesian Optimization workloads.
To override the default, set the environment variable before launching Badger:
export OMP_NUM_THREADS=8
Any value you set explicitly will be respected. Badger only fills in the cap when the variable is unset.
Run an optimization
Once Badger is installed, launch the GUI by running the following command in the terminal:
badger -g
Then following this simple GUI tutorial to run your first optimizaion in Badger within a couple of minutes!
Citation
If you use Badger for your research, please consider adding the following citation to your publications.
Zhang, Z., et al. "Badger: The missing optimizer in ACR",
in Proc. IPAC'22, Bangkok. doi:10.18429/JACoW-IPAC2022-TUPOST058
BibTex entry:
@inproceedings{Badger,
author = {Z. Zhang and M. Böse and A.L. Edelen and J.R. Garrahan and Y. Hidaka and C.E. Mayes and S.A. Miskovich and D.F. Ratner and R.J. Roussel and J. Shtalenkova and S. Tomin and G.M. Wang},
title = {{Badger: The Missing Optimizer in ACR}},
booktitle = {Proc. IPAC'22},
pages = {999--1002},
eid = {TUPOST058},
language = {english},
keywords = {interface, controls, GUI, operation, framework},
venue = {Bangkok, Thailand},
series = {International Particle Accelerator Conference},
number = {13},
publisher = {JACoW Publishing, Geneva, Switzerland},
month = {07},
year = {2022},
issn = {2673-5490},
isbn = {978-3-95450-227-1},
doi = {10.18429/JACoW-IPAC2022-TUPOST058},
url = {https://jacow.org/ipac2022/papers/tupost058.pdf},
}
Developers
Clone this repository:
git clone https://github.com/xopt-org/badger.git
Create a fresh Python environment, for example using conda:
conda create -n badger-env python=3.12
Install Badger as editable:
conda activate badger-env
pip install -e ".[dev]"
You'll also need to install ruff and pre-commit to be able to
pass the linting and formatting checks:
pip install ruff pre-commit
Then install the pre-commit hooks:
pre-commit install
You can also do a run at any time to check your progress:
pre-commit run --all-files
GUI guide
There is also a GUI component guide for your convenience. It shows all in-use components and their corresponding python script locations and brief descriptions. Check it out if you get lost in the non-ideal namings of the component files.
Issues or questions?
Please check out current Badger issues here before opening a new one. Alternatively, you are welcome to shoot us an email, or join our Slack channel if you are a SLACer.
-
Draws limited inspiration from Ocelot the optimizer. ↩
-
In version v1.3.0 we only support part of the CLI capabilities but would add them back with future updates. ↩ ↩2
1 maintainer
Metadata
1 maintainer
Release files for badger-opt 1.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| badger_opt-1.6.0.tar.gz | 17.1 MB | With provenance | Details |
Release files / badger_opt-1.6.0.tar.gz
| Download URL | badger_opt-1.6.0.tar.gz |
|---|---|
| Size | 17.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc8ad40fb4be5726e2589943e2d14743ba1fb95200a66a42b060c48eccf040f3
|
|
BLAKE2b-256 checksum How to use checksums |
bb46050c497bd24ce308b3d42e8e203b0efc3de0c9077026aa65507645ae1fdb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logSecurity for badger-opt 1.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 1 file in this release has been uploaded with provenance metadata.
Attestation for badger_opt-1.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
