Package: baybe
Homepage•User Guide•Documentation•ContributeBayBE — A Bayesian Back End for Design of ExperimentsThe Bayesian Back End (BayBE) provides a general-purpose toolbox for Bayesian Design
of Experiments, focusing on additions that enable real-world experimental campaigns.Besides functionality to perform a typical recommend-measure loop, BayBE's highlights are:Custom parameter encodings: Improve your campaign with domain knowledgeBuilt-in chemical encodings: Improve your campaign with chemical knowledgeSingle and multiple targets with min, max and match objectivesCustom surrogate models: For specialized problems or active learningHybrid (mixed continuous and discrete) spacesTransfer learning: Mix data from multiple campaigns and accelerate optimizationComprehensive backtest, simulation and imputation utilities: Benchmark and find your best settingsFully typed and hypothesis-tested: Robust code baseAll objects are fully de-/serializable: Useful for storing results in databases or use in wrappers like APIsQuick StartLet us consider a simple experiment where we control three parameters and want to
maximize a single target calledYield.First, install BayBE into your Python environment:pipinstallbaybeFor more information on this step, see ourdetailed installation instructions.Defining the Optimization ObjectiveIn BayBE's language, theYieldcan be represented as aNumericalTarget,
which we pass into anObjective.frombaybe.targetsimportNumericalTargetfrombaybe.objectiveimportObjectivetarget=NumericalTarget(name="Yield",mode="MAX",)objective=Objective(mode="SINGLE",targets=[target])In cases where we need to consider multiple (potentially competing) targets, the
role of theObjectiveis to define additional settings, e.g. how these targets should
be balanced.
InSINGLEmode, however, there are no additional settings.
For more details, seethe objective section of the user guide.Defining the Search SpaceNext, we inform BayBE about the available "control knobs", that is, the underlying
system parameters we can tune to optimize our targets. This also involves specifying
their values/ranges and other parameter-specific details.For our example, we assume that we can control three parameters –Granularity,Pressure[bar], andSolvent– as follows:frombaybe.parametersimport(CategoricalParameter,NumericalDiscreteParameter,SubstanceParameter,)parameters=[CategoricalParameter(name="Granularity",values=["coarse","medium","fine"],encoding="OHE",# one-hot encoding of categories),NumericalDiscreteParameter(name="Pressure[bar]",values=[1,5,10],tolerance=0.2,# allows experimental inaccuracies up to 0.2 when reading values),SubstanceParameter(name="Solvent",data={"Solvent A":"COC","Solvent B":"CCC",# label-SMILES pairs"Solvent C":"O","Solvent D":"CS(=O)C",},encoding="MORDRED",# chemical encoding via mordred package),]For more parameter types and their details, see theparameters sectionof the user guide.Additionally, we can define a set of constraints to further specify allowed ranges and
relationships between our parameters. Details can be found in theconstraints sectionof the user guide.
In this example, we assume no further constraints.With the parameter and constraint definitions at hand, we can now create ourSearchSpacebased on the Cartesian product of all possible parameter values:frombaybe.searchspaceimportSearchSpacesearchspace=SearchSpace.from_product(parameters)Optional: Defining the Optimization StrategyAs an optional step, we can specify details on how the optimization should be
conducted. If omitted, BayBE will choose a default setting.For our example, we combine two selection strategies:In cases where no measurements have been made prior to the interaction with BayBE,
a selection viainitial_recommenderis used.As soon as the first measurements are available, we switch torecommender.For more details on the different strategies, their underlying algorithmic
details, and their configuration settings, see thestrategies sectionof the user guide.frombaybe.recommendersimport(SequentialGreedyRecommender,FPSRecommender,TwoPhaseMetaRecommender,)strategy=TwoPhaseMetaRecommender(initial_recommender=FPSRecommender(),# farthest point samplingrecommender=SequentialGreedyRecommender(),# Bayesian model-based optimization)The Optimization LoopWe can now construct a campaign object that brings all pieces of the puzzle together:frombaybeimportCampaigncampaign=Campaign(searchspace,objective,strategy)With this object at hand, we can start our experimentation cycle.
In particular:We can ask BayBE torecommendnew experiments.We canadd_measurementsfor certain experimental settings to the campaign's
database.Note that these two steps can be performed in any order.
In particular, available measurements can be submitted at any time and also several
times before querying the next recommendations.df=campaign.recommend(batch_size=3)print(df)Granularity  Pressure[bar]    Solvent
15      medium            1.0  Solvent D
10      coarse           10.0  Solvent C
29        fine            5.0  Solvent BNote that the specific recommendations will depend on both the data
already fed to the campaign and the random number generator seed that is used.After having conducted the corresponding experiments, we can add our measured
targets to the table and feed it back to the campaign:df["Yield"]=[79.8,54.1,59.4]campaign.add_measurements(df)With the newly arrived data, BayBE can produce a refined design for the next iteration.
This loop would typically continue until a desired target value has been achieved in
the experiment.(installation)=InstallationFrom Package IndexThe easiest way to install BayBE is via PyPI:pipinstallbaybeA certain released version of the package can be installed by specifying the
corresponding version tag in the formbaybe==x.y.z.From GitHubIf you need finer control and would like to install a specific commit that has not been
released under a certain version tag, you can do so by installing BayBE directly from
GitHub via git and specifying the correspondinggit ref.For instance, to install the latest commit of the main branch, run:pipinstallgit+https://github.com/emdgroup/baybe.git@mainFrom Local CloneAlternatively, you can install the package from your own local copy.
First, clone the repository, navigate to the repository root folder, check out the
desired commit, and run:pipinstall.A developer would typically also install the package in editable mode ('-e'),
which ensures that changes to the code do not require a reinstallation.pipinstall-e.If you need to add additional dependencies, make sure to use the correct syntax
including'':pipinstall-e'.[dev]'Optional DependenciesThere are several dependency groups that can be selected during pip installation, likepipinstall'baybe[test,lint]'# will install baybe with additional dependency groups `test` and `lint`To get the most out ofbaybe, we recommend to install at leastpipinstall'baybe[chem,simulation]'The available groups are:chem: Cheminformatics utilities (e.g. for theSubstanceParameter).docs: Required for creating the documentation.examples: Required for running the examples/streamlit.lint: Required for linting and formatting.mypy: Required for static type checking.onnx: Required for using custom surrogate models inONNX format.simulation: Enabling thesimulationmodule.test: Required for running the tests.dev: All of the above plustoxandpip-audit. For code contributors.AuthorsMartin Fitzner (Merck KGaA, Darmstadt, Germany),Contact,GithubAdrian Šošić (Merck Life Science KGaA, Darmstadt, Germany),Contact,GithubAlexander Hopp (Merck KGaA, Darmstadt, Germany)Contact,GithubAlex Lee (EMD Electronics, Tempe, Arizona, USA)Contact,GithubKnown IssuesA list of know issues can be foundhere.LicenseCopyright 2022-2024 Merck KGaA, Darmstadt, Germany
and/or its affiliates. All rights reserved.Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.