DOCSEARCHbyAlgolia
Submit Docs

BayBE

repository·main·Indexed 19 days ago

https://github.com/emdgroup/baybe

A Bayesian Back End for Design of Experiments providing a toolbox to navigate complex parameter search spaces for optimization tasks in chemistry, materials science, and simulation. It supports hybrid search spaces, multi-target optimization, chemical encodings, and transfer learning to balance exploration and exploitation in finding optimal parameter configurations.

Tokens
43.3K
Snippets
119
Records
174
Agent score
66%

What's inside baybe

  1. What is BayBE?

    main
    BayBE (Bayesian Back End) is a general-purpose toolbox for Bayesian Design of Experiments. It is designed to help find optimal parameter configurations within complex search spaces by balancing the exploitation of known good regions with the exploration of unknown regions. It is applicable to various real-world optimization problems including chemical reaction optimization, material formulation, physical object shape optimization, virtual simulations, and hyperparameter selection.

  2. What is a Campaign in BayBE?

    main

    A Campaign (via the baybe.campaign.Campaign class) is the central orchestration component in BayBE. It manages the entire Bayesian optimization lifecycle, including:

    • Handling experimental data.
    • Making recommendations for new experiments.
    • Adding measurements from completed experiments.
    • Providing predictive statistics.

    It acts as the primary interface for users to interact with the optimization process.

  3. What is Active Learning in BayBE?

    main

    Active learning is a guided approach to selecting experiments (e.g., for data acquisition in machine learning) by iteratively measuring points based on a criterion that reflects the current model's uncertainty.

    In BayBE, active learning is implemented as a special case of Bayesian optimization. You construct a probabilistic model of the measurement process to quantify uncertainty via a posterior distribution, then use an uncertainty-based acquisition function to guide the exploration process.

  4. Overview of BayBE built-in features

    main

    BayBE provides several advanced features for managing experimental design and optimization:

    Modeling Options

    • Hybrid Search Spaces: Use both continuous and discrete parameters simultaneously.
    • Constraints: Exclude undesired or impossible parameter configurations.
    • Optimization Strategies: Choose between active learning for model building or bandit models for AB testing.
    • Target Transformations: Specify desired target values via transformations.
    • Multi-target Optimization: Optimize multiple targets using Pareto optimization or desirability scalarization.

    Leveraging Additional Information

    • Custom Encodings: Capture relationships between categories for categorical data.
    • Chemical Encodings: Built-in support for chemistry-related parameters.
    • Custom Surrogates: Incorporate mechanistic process understanding via custom surrogate models.
    • Transfer Learning: Use data from similar previous campaigns to accelerate current optimization.

    Advanced Workflows & Evaluation

    • Asynchronous Campaigns: Run campaigns with partial measurements and pending experiments.
    • Serialization: Store BayBE objects and use API wrappers for persistence.
    • Insights: Analyze model behavior and feature importance to understand optimization campaigns.
    • Backtesting: Conduct benchmarks to select optimal Bayesian optimization settings via simulation.

  5. How BayBE components work together

    main

    BayBE uses a modular design where individual components are composed to build an optimization workflow. This modularity allows for two main workflows:

    1. High-level orchestration: Newcomers typically interact with the Campaign object. A Campaign acts as a high-level container that defines an optimization problem, suggests new measurements, and manages the state of the experimental operation.
    2. Low-level customization: Advanced users can swap individual components (like Surrogates, Recommenders, or Search Spaces) in a plug-and-play fashion to compare different setups or fine-tune the optimization loop.

    The Campaign integrates various components into the Bayesian optimization loop to drive the experimental process.

  6. Define a custom Benchmark

    main

    A Benchmark object combines all data required for a performance test. It requires:

    • name: A unique identifier. Note that this name is used for storing Result objects; changing the name will be treated as a new benchmark.
    • function: A callable that performs the code being benchmarked. The __doc__ of this function is automatically used as the benchmark's description.

    To parameterize a benchmark, extend the BenchmarkSettings abstract base class. The only mandatory attribute is random_seed, which ensures reproducibility by seeding the entire benchmark call.

  7. Core components of a BayBE optimization workflow

    main

    A basic BayBE optimization workflow consists of two primary components:

    1. Campaign: The top-level container that manages the optimization process, including the search space, the objective function, and the history of experiments.
    2. Recommender: The optimization strategy (algorithm) that suggests the next configuration to test based on the data collected in the Campaign.

    To perform an optimization, you must set up a Campaign and configure a Recommender to guide the search.

  8. Choose between stateful and stateless recommendation methods

    main

    BayBE provides two ways to generate recommendations depending on whether you want to maintain a persistent state or perform a one-off calculation:

    1. Stateful: Use the Campaign.recommend method. This is used when you are managing an ongoing experimental campaign.
    2. Stateless: Use the RecommenderProtocol.recommend method. This is used for one-off recommendations without the overhead of a campaign object.

    For guidance on which to choose, refer to the getting recommendations concept guide.

    # Stateful recommendation (requires a Campaign instance)
recommendation = campaign.recommend()

# Stateless recommendation (requires an object implementing RecommenderProtocol)
recommendation = recommender.recommend(data)

  9. How the Gaussian Process (GP) surrogate works

    main
    The Gaussian Process (GP) is the default surrogate in BayBE. It is highly effective for Bayesian optimization because it provides a closed-form joint posterior distribution (mean and covariance), is data-efficient, and is non-parametric, allowing it to adapt to complex, unknown function shapes. It also offers mathematical conveniences like closed-form gradients and analytic marginal likelihoods for hyperparameter tuning.

  10. Difference between Minimization and Negated Maximization

    main

    While minimizing a target and maximizing its negation are numerically equivalent (they yield the same objective values), they are semantically different in BayBE.

    • Minimization: Created via NumericalTarget(name="...", minimize=True).
    • Negated Maximization: Created via NumericalTarget(name="...", transformation=AffineTransformation(factor=-1)).

    These two approaches result in different Target objects (t1 != t2), even if t1.to_objective().transform(df) produces the same values as t2.to_objective().transform(df).

    import numpy as np
import pandas as pd
from pandas.testing import assert_frame_equal

from baybe.targets import NumericalTarget
from baybe.transformations import AffineTransformation

# Target 1: "Minimize" cost
t1 = NumericalTarget(name="Cost", minimize=True)

# Target 2: "Maximize" the quantity obtained from negating cost measurements
t2 = NumericalTarget(name="Cost", transformation=AffineTransformation(factor=-1))

# Although both targets yield the same objective values ...
s = pd.Series(np.linspace(0, 10), name="Cost")
df = s.to_frame()
assert_frame_equal(
    t1.to_objective().transform(df),
    t2.to_objective().transform(df),
)

# ... the targets themselves are not equal ...
assert t1 != t2

  11. Handle discrepancies between recommendations and experimental actions

    main

    BayBE recommendations are advisory. You are not required to perform the exact experiment recommended by the model. The measurements you feed back into BayBE do not need to be related to the original recommendation.

    Requesting recommendations and adding data are independent actions. However, be aware that your settings for the following Campaign flags can affect how subsequent recommendations are generated based on your previous actions:

    • allow_recommending_already_measured: Controls if the model can recommend points that have already been measured.
    • allow_recommending_already_recommended: Controls if the model can recommend points that were previously recommended but not yet measured.

  12. Understand BayBE's backwards compatibility policy

    main
    BayBE is under active development, and interfaces or objects may change in ways that break existing code. The project aims to provide backwards support for deprecated code for the last three minor versions. After this period, old code is generally removed. Deprecation notices and expiration dates are documented in the project changelog.