Atlas

atlas is a Python package for Bayesian optimization in the experimental science. At its core, the package provides high-performing, easy-to-use Bayesian optimization based on Gaussian processes (with help from the GPyTorch and BoTorch libraries). atlas attempts to cater directly to the needs of researchers in the experimental sciences, and provides additional optimization capabilities to tackle problems typically encountered in such disciplines. These capabilities include optimization of categorical, discrete, and mixed parameter spaces, multi-objective optimization, noisy optimization (noise on input parameters and objective measurements), constrained optimization (known and unknown constraints on the parameter space), multi-fidelity optimization, meta-learning optimization, data-driven search space expansion/contraction, and more!

atlas is intended serve as the brain or experiment planner for self-driving laboratories.

You can find more details about atlas in our documentation.

You can see the peer-reviewed publication in our publication at RSC Digital Discovery.

atlas is proudly developed in 🇨🇦 at the University of Toronto and the Vector Institute for Artificial Intelligence.

Installation

Currently, atlas does not work with Python>=3.11, and we recommend using 3.9 or 3.10. This will be fixed in later updates. You can install atlas from source in edit mode by executing the following commands

bash git clone git@github.com:aspuru-guzik-group/atlas.git cd atlas pip install -e . pip install -r requirements.txt

If you require olympus resources, you can install it from source by doing bash git clone -b olympus-atlas --single-branch git@github.com:aspuru-guzik-group/olympus.git cd olympus pip install -e .

Usage

This section gives minimal code examples showcasing some of the primary features of atlas. You can also familiarize yourself with the package by checking out the following Google colab notebook.

Here we provide a minimal code example in which the GPPlanner from atlas is used to minimize the Branin-Hoo surface $f : \mathcal{X} \in \mathbb{R}^2 \mapsto \mathbb{R}$. "Ask-tell" experimentation proceeds iteratively by generating parameters to be measured using the planner's recommend() method, and informing the olympus Campaign instance about the corresponding measurement using its add_observation() method. We opt to use a flexible "ask-tell" interface in order to remain SDL application-agnostic. Measurement steps usually involve calls to specialized robotic laboratory equipment or computational simulation packages, which can be fully customized by the user.

```python from olympus import Surface, Campaign from atlas.planners.gp.planner import GPPlanner

surface = Surface(kind='Branin') # instantiate 2d Branin-Hoo objective function

campaign = Campaign() # define Olympus campaign object campaign.setparamspace(surface.param_space)

planner = GPPlanner(goal='minimize', numinitdesign=5) # instantiate Atlas planner planner.setparamspace(surface.param_space)

while len(campaign.observations.getvalues()) < 30: samples = planner.recommend(campaign.observations) # ask planner for batch of parameters for sample in samples: measurement = surface.run(sample) # measure Branin-Hoo function campaign.addobservation(sample, measurement) # tell planner about most recent observation ```

License

Distributed under the MIT license. See LICENSE for more information.

Contact

Academic collaborations and extensions/improvements to the code by the community are encouraged. Please reach out to Riley or Gary by email if you have questions.

Citation

atlas is an academic research software. If you use atlas in a scientific publication, please cite the following article.

@misc{hickman_atlas_2025, title={Atlas: a brain for self-driving laboratories}, author={Hickman, Riley J and Sim, Malcolm and Pablo-Garc{\'\i}a, Sergio and Tom, Gary and Woolhouse, Ivan and Hao, Han and Bao, Zeqing and Bannigan, Pauric and Allen, Christine and Aldeghi, Matteo and Aspuru-Guzik, Al{\'a}n}}, journal={Digital Discovery}, volume={4}, number={4}, pages={1006--1029}, year={2025}, publisher={Royal Society of Chemistry} }

olympus works hand-in-hand with atlas. We would be grateful for citations of the following publications as well.

``` @article{haseolympus2021, author = {H{\"a}se, Florian and Aldeghi, Matteo and Hickman, Riley J. and Roch, Lo{\"\i}c M. and Christensen, Melodie and Liles, Elena and Hein, Jason E. and Aspuru-Guzik, Al{\'a}n}, doi = {10.1088/2632-2153/abedc8}, issn = {2632-2153}, journal = {Machine Learning: Science and Technology}, month = jul, number = {3}, pages = {035021}, title = {Olympus: a benchmarking framework for noisy optimization and experiment planning}, volume = {2}, year = {2021} }

@misc{hickmanolympus2023, author = {Hickman, Riley and Parakh, Priyansh and Cheng, Austin and Ai, Qianxiang and Schrier, Joshua and Aldeghi, Matteo and Aspuru-Guzik, Al{\'a}n}, doi = {10.26434/chemrxiv-2023-74w8d}, language = {en}, month = may, publisher = {ChemRxiv}, shorttitle = {Olympus, enhanced}, title = {Olympus, enhanced: benchmarking mixed-parameter and multi-objective optimization in chemistry and materials science}, urldate = {2023-06-21}, year = {2023}, } ```