From 3e67eb05f911cc5baed26e679959cbfdb8b28ca3 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Sun, 3 Aug 2025 11:14:54 +0200 Subject: [PATCH 01/51] Designing experiments checklists FAQ - unfinished --- docs/userguide/design_checklist.md | 40 ++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/userguide/design_checklist.md diff --git a/docs/userguide/design_checklist.md b/docs/userguide/design_checklist.md new file mode 100644 index 0000000000..28b581a630 --- /dev/null +++ b/docs/userguide/design_checklist.md @@ -0,0 +1,40 @@ +# Checklist for designing BayBE experiments + +- Are only some parameter values of interest/possible? + + > See how to exclude some +[parameter values](https://emdgroup.github.io/baybe/stable/userguide/getting_recommendations.html#excluding-configurations) +from being recommended, such as by defining +[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter). +or [active values for discrete parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters). + +- Are only some parameter combinations of interest/possible? + + > See how to exclude some +[parameter combinations](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) +from being considered. + +- Should be multiple target optimized simultaneously? + + > See how to use [multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). + +- Is it possible to encode discrete parameters based on domain knowledge +(e.g., ordered values, molecular fingerprints, model embeddings)? + + > See how to [encode](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) +discrete parameters or provide custom encodings. + +- Is additional data from historic or other partially-related experiments available? + + > Use [transfer learning](https://emdgroup.github.io/baybe/stable/userguide/transfer_learning.html). + +- Is the aim to reduce the overall uncertainty across different regions of the search space +rather than optimize a specific objective? + + > Use [active learning](https://emdgroup.github.io/baybe/stable/userguide/active_learning.html). + +- Will the outcome measurements of different parameter setting become available at different times? + + > Use [asynchronous workflows](https://emdgroup.github.io/baybe/stable/userguide/async.html). + + From 24559ad54c707cc6996db9cd0aad15bd18c6008d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 5 Aug 2025 12:55:49 +0200 Subject: [PATCH 02/51] Expand checklist --- docs/userguide/design_checklist.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/userguide/design_checklist.md b/docs/userguide/design_checklist.md index 28b581a630..e1173f8841 100644 --- a/docs/userguide/design_checklist.md +++ b/docs/userguide/design_checklist.md @@ -1,22 +1,26 @@ # Checklist for designing BayBE experiments +- Should be multiple target optimized simultaneously? + + > See how to use [multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). + - Are only some parameter values of interest/possible? > See how to exclude some [parameter values](https://emdgroup.github.io/baybe/stable/userguide/getting_recommendations.html#excluding-configurations) from being recommended, such as by defining -[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter). +[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter) or [active values for discrete parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters). - Are only some parameter combinations of interest/possible? > See how to exclude some -[parameter combinations](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) -from being considered. - -- Should be multiple target optimized simultaneously? - - > See how to use [multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). +parameter combinations from being considered by using +[constraints](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) or +[constrained searchspaces](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). +Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a +[dataframe](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#id3) +rather than from the product of all possible parameter combinations. - Is it possible to encode discrete parameters based on domain knowledge (e.g., ordered values, molecular fingerprints, model embeddings)? From 97857969189ebed9df198fa0b4059bb83dbf12c3 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 23 Oct 2025 16:39:08 +0200 Subject: [PATCH 03/51] Add design checklist to FAQ --- docs/faq.md | 67 ++++++++++++++++++++++++++++++ docs/userguide/design_checklist.md | 44 -------------------- 2 files changed, 67 insertions(+), 44 deletions(-) delete mode 100644 docs/userguide/design_checklist.md diff --git a/docs/faq.md b/docs/faq.md index 1d5deda9e1..a921b3d0ff 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -25,3 +25,70 @@ your campaign, depending on your settings for the {attr}`~baybe.campaign.Campaign.allow_recommending_already_recommended` flags. ``` +## Checklist for designing BayBE experiments + +### Defining targets + +- Should be target value maximized rather than minimized? + + > Specify this when +[defining the target](https://emdgroup.github.io/baybe/stable/userguide/targets.html#numericaltarget). + +- Should be multiple target optimized simultaneously? + + > See how to use +[multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). + +### Defining parameter search space + +- Are only some parameter values of interest/possible? + + > See how to exclude some +[parameter values](https://emdgroup.github.io/baybe/stable/userguide/getting_recommendations.html#excluding-configurations) +from being recommended, such as by defining +[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter) +or [active values for discrete parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters). + +- Are only some parameter combinations of interest/possible? + + > See how to exclude some +parameter combinations from being considered by using +[constraints](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) or +[constrained searchspaces](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). +Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a +[dataframe](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#id3) +rather than from the product of all possible parameter combinations. + +- Are some parameters non-numeric or allow only discrete numbers? + + > Use [discrete](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) +rather than [continuous](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#continuous-parameters) parameters. + +- Is it possible to encode discrete parameters based on domain knowledge +to capture relationships between categories +(e.g., ordered values, molecular fingerprints, model embeddings)? + + > See how to +[encode](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) +discrete parameters or provide custom encodings. + +### Account for specifics of data availability or acquisition procedure + +- Is additional data from historic or other partially-related experiments available? + + > Use [transfer learning](https://emdgroup.github.io/baybe/stable/userguide/transfer_learning.html). + +- Will the outcome measurements of different parameter setting become available at different times? + + > Use [asynchronous workflows](https://emdgroup.github.io/baybe/stable/userguide/async.html). + +### Advanced: adjust how recommendations are prioritized + +- Is the aim to reduce the overall uncertainty across different regions of the search space +rather than optimize a specific objective? + + > Use [active learning](https://emdgroup.github.io/baybe/stable/userguide/active_learning.html). + + + + diff --git a/docs/userguide/design_checklist.md b/docs/userguide/design_checklist.md deleted file mode 100644 index e1173f8841..0000000000 --- a/docs/userguide/design_checklist.md +++ /dev/null @@ -1,44 +0,0 @@ -# Checklist for designing BayBE experiments - -- Should be multiple target optimized simultaneously? - - > See how to use [multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). - -- Are only some parameter values of interest/possible? - - > See how to exclude some -[parameter values](https://emdgroup.github.io/baybe/stable/userguide/getting_recommendations.html#excluding-configurations) -from being recommended, such as by defining -[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter) -or [active values for discrete parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters). - -- Are only some parameter combinations of interest/possible? - - > See how to exclude some -parameter combinations from being considered by using -[constraints](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) or -[constrained searchspaces](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). -Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a -[dataframe](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#id3) -rather than from the product of all possible parameter combinations. - -- Is it possible to encode discrete parameters based on domain knowledge -(e.g., ordered values, molecular fingerprints, model embeddings)? - - > See how to [encode](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) -discrete parameters or provide custom encodings. - -- Is additional data from historic or other partially-related experiments available? - - > Use [transfer learning](https://emdgroup.github.io/baybe/stable/userguide/transfer_learning.html). - -- Is the aim to reduce the overall uncertainty across different regions of the search space -rather than optimize a specific objective? - - > Use [active learning](https://emdgroup.github.io/baybe/stable/userguide/active_learning.html). - -- Will the outcome measurements of different parameter setting become available at different times? - - > Use [asynchronous workflows](https://emdgroup.github.io/baybe/stable/userguide/async.html). - - From 6a4cdb7c2978a7d8405939a6a0fd6ac8e09cfb61 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 23 Oct 2025 17:04:57 +0200 Subject: [PATCH 04/51] Make introduction clearer --- README.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8c08b5f1e5..ce01974a88 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,26 @@ # BayBE โ€” A Bayesian Back End for Design of Experiments -The **Bay**esian **B**ack **E**nd (**BayBE**) is a general-purpose toolbox for Bayesian Design -of Experiments, focusing on additions that enable real-world experimental campaigns. +The **Bay**esian **B**ack **E**nd (**BayBE**) +helps to find a **good parameter setting** +within a complex parameter search space. + +```{dropdown} Example use-cases +- Find chemical reaction conditions or process parameters +- Create materials, chemical mixtures, or formulations with desired properties +- Optimize the 3D shape of a physical object +- Find model hyperparameters +- Find tasty espresso machine settings +``` + +This is achieved via **Bayesian Design of Experiments**, +which is an efficient way for navigating parameter search spaces. +It balances +exploitation of parameter space regions known to lead to good outcomes +and exploration of unknown regions. + +BayBE provides a **general-purpose toolbox** for Bayesian Design of Experiments, +focusing on making this procedure easily-accessible within real-world experimental campaigns. ## ๐Ÿ”‹ Batteries Included Besides its core functionality to perform a typical recommend-measure loop, BayBE From 22718e0397b49e9d1a243a9f30a41c223f0f67e0 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 23 Oct 2025 17:07:50 +0200 Subject: [PATCH 05/51] Format readme introduction --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index ce01974a88..ff746b5075 100644 --- a/README.md +++ b/README.md @@ -31,13 +31,12 @@ The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find a **good parameter setting** within a complex parameter search space. -```{dropdown} Example use-cases +Example use-cases: - Find chemical reaction conditions or process parameters - Create materials, chemical mixtures, or formulations with desired properties - Optimize the 3D shape of a physical object - Find model hyperparameters - Find tasty espresso machine settings -``` This is achieved via **Bayesian Design of Experiments**, which is an efficient way for navigating parameter search spaces. From 2fa2190ee7dfc0773b55565e16ead6245657f9ca Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 08:48:13 +0200 Subject: [PATCH 06/51] Simplify readme introduction language --- README.md | 32 +++++++++++++++----------------- docs/faq.md | 2 +- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ff746b5075..d9ec18ecd5 100644 --- a/README.md +++ b/README.md @@ -48,25 +48,23 @@ BayBE provides a **general-purpose toolbox** for Bayesian Design of Experiments, focusing on making this procedure easily-accessible within real-world experimental campaigns. ## ๐Ÿ”‹ Batteries Included -Besides its core functionality to perform a typical recommend-measure loop, BayBE -offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. +BayBE offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. The following provides a non-comprehensive overview: -- ๐Ÿ› ๏ธ Custom parameter encodings: Improve your campaign with domain knowledge -- ๐Ÿงช Built-in chemical encodings: Improve your campaign with chemical knowledge -- ๐ŸŽฏ Numerical and binary targets with min, max and match objectives -- โš–๏ธ Multi-target support via Pareto optimization and desirability scalarization -- ๐Ÿ” Insights: Easily analyze feature importance and model behavior -- ๐ŸŽญ Hybrid (mixed continuous and discrete) spaces -- ๐Ÿš€ Transfer learning: Mix data from multiple campaigns and accelerate optimization -- ๐ŸŽฐ Bandit models: Efficiently find the best among many options in noisy environments (e.g. A/B Testing) -- ๐Ÿ”ข Cardinality constraints: Control the number of active factors in your design -- ๐ŸŒŽ Distributed workflows: Run campaigns asynchronously with pending experiments and partial measurements -- ๐ŸŽ“ Active learning: Perform smart data acquisition campaigns -- โš™๏ธ Custom surrogate models: Enhance your predictions through mechanistic understanding -- ๐Ÿ“ˆ Comprehensive backtest, simulation and imputation utilities: Benchmark and find your best settings -- ๐Ÿ“ Fully typed and hypothesis-tested: Robust code base -- ๐Ÿ”„ All objects are fully (de-)serializable: Useful for storing results in databases or use in wrappers like APIs +- ๐Ÿ› ๏ธ Leverage **domain knowledge** for encoding categorical data, thus capturing relationships between categories. + - ๐Ÿงช BayBE also provides built-in chemical encodings. +- ๐Ÿš€ Leverage **historic data** to accelerate optimization via transfer learning. +- **Flexible** definition of target outcomes, search spaces, and optimization strategy: + - ๐ŸŽฏ Option to use numerical targets (e.g., measured outcome value) or binary targets (e.g., good/bad classification). Targets can be minimized, maximized, or matched to a target value. + - โš–๏ธ Multiple targets can be optimized at once (e.g., via Pareto optimization). + - ๐ŸŽญ Use both continuous and discrete parameters in a single search space. + - ๐Ÿ”ข Define maximal number of mixture components via cardinality constraints. + - ๐ŸŽฐ Different optimization strategies to balance exploration and exploitation, including bandit models and active learning. +- ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements via distributed workflows. +- ๐Ÿ” **Insights**: Easily analyze feature importance and model behavior. +- ๐Ÿ“ˆ Utilities for **benchmarking**, such as backtesting and simulations. +- ๐Ÿ“ **High-quality code base** with comprehensive tests and typing. +- ๐Ÿ”„ Code is designed with **database storage and API** wrappers in mind via serialization. ## โšก Quick Start diff --git a/docs/faq.md b/docs/faq.md index a921b3d0ff..54443cbe36 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -29,7 +29,7 @@ your campaign, depending on your settings for the ### Defining targets -- Should be target value maximized rather than minimized? +- Should be target value maximized rather than minimized or matched to specific value? > Specify this when [defining the target](https://emdgroup.github.io/baybe/stable/userguide/targets.html#numericaltarget). From 6d9baf3854a4c2e19dff378e6cb61bc9f8c74b55 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 08:52:16 +0200 Subject: [PATCH 07/51] Move API overview diagram into this repository --- docs/_static/baybe_overview.drawio | 261 +++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/_static/baybe_overview.drawio diff --git a/docs/_static/baybe_overview.drawio b/docs/_static/baybe_overview.drawio new file mode 100644 index 0000000000..0737716ffc --- /dev/null +++ b/docs/_static/baybe_overview.drawio @@ -0,0 +1,261 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From e74be96220324317374350937ef7e4ae3694327d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 09:49:05 +0200 Subject: [PATCH 08/51] Rename API overview drawio file --- docs/_static/{baybe_overview.drawio => api_overview.drawio} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/_static/{baybe_overview.drawio => api_overview.drawio} (100%) diff --git a/docs/_static/baybe_overview.drawio b/docs/_static/api_overview.drawio similarity index 100% rename from docs/_static/baybe_overview.drawio rename to docs/_static/api_overview.drawio From beb9b9c8ec5e40ddd309e2e79f9bb2056b290dc9 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 09:49:33 +0200 Subject: [PATCH 09/51] Make drawio template quick start diagram --- docs/_static/quick_start.drawio | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 docs/_static/quick_start.drawio diff --git a/docs/_static/quick_start.drawio b/docs/_static/quick_start.drawio new file mode 100644 index 0000000000..930a05aef0 --- /dev/null +++ b/docs/_static/quick_start.drawio @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file From d58148a932ba3423826494139bcbae5375305bfd Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 12:33:05 +0200 Subject: [PATCH 10/51] Add quick start diagram --- docs/_static/quick_start.drawio | 93 +++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/docs/_static/quick_start.drawio b/docs/_static/quick_start.drawio index 930a05aef0..98567e85db 100644 --- a/docs/_static/quick_start.drawio +++ b/docs/_static/quick_start.drawio @@ -1,11 +1,98 @@ - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 93b2e81de480a24b3461de7897d321f3ab623de9 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 13:40:03 +0200 Subject: [PATCH 11/51] Add complex searchspace drawio diagram --- docs/_static/complex_search_space.drawio | 58 ++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/_static/complex_search_space.drawio diff --git a/docs/_static/complex_search_space.drawio b/docs/_static/complex_search_space.drawio new file mode 100644 index 0000000000..eeadae3ce7 --- /dev/null +++ b/docs/_static/complex_search_space.drawio @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 6f6f4ac4d690fc94fe0dda85cb9eb07deedcdfe9 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 13:53:08 +0200 Subject: [PATCH 12/51] Update diagram --- docs/_static/complex_search_space.drawio | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/_static/complex_search_space.drawio b/docs/_static/complex_search_space.drawio index eeadae3ce7..fa415f487f 100644 --- a/docs/_static/complex_search_space.drawio +++ b/docs/_static/complex_search_space.drawio @@ -1,19 +1,19 @@ - + - - + + - + - + - + From c09a6263793c55d832ff72af0f355662aaf10500 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 16:32:49 +0200 Subject: [PATCH 13/51] Make readme more accessible for new users --- README.md | 120 +++++++++++------- .../complex_search_space_automatic.svg | 4 + docs/_static/complex_search_space_dark.svg | 4 + docs/_static/complex_search_space_light.svg | 4 + docs/_static/quick_starrt_dark.svg | 4 + docs/_static/quick_start_automatic.svg | 4 + docs/_static/quick_start_light.svg | 4 + 7 files changed, 98 insertions(+), 46 deletions(-) create mode 100644 docs/_static/complex_search_space_automatic.svg create mode 100644 docs/_static/complex_search_space_dark.svg create mode 100644 docs/_static/complex_search_space_light.svg create mode 100644 docs/_static/quick_starrt_dark.svg create mode 100644 docs/_static/quick_start_automatic.svg create mode 100644 docs/_static/quick_start_light.svg diff --git a/README.md b/README.md index d9ec18ecd5..ad29422961 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,12 @@ The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find a **good parameter setting** within a complex parameter search space. +
+ +![complex search space](docs/_static/complex_search_space_automatic.svg) + +
+ Example use-cases: - Find chemical reaction conditions or process parameters - Create materials, chemical mixtures, or formulations with desired properties @@ -45,7 +51,7 @@ exploitation of parameter space regions known to lead to good outcomes and exploration of unknown regions. BayBE provides a **general-purpose toolbox** for Bayesian Design of Experiments, -focusing on making this procedure easily-accessible within real-world experimental campaigns. +focusing on making this procedure easily-accessible for real-world experiments. ## ๐Ÿ”‹ Batteries Included BayBE offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. @@ -54,12 +60,12 @@ The following provides a non-comprehensive overview: - ๐Ÿ› ๏ธ Leverage **domain knowledge** for encoding categorical data, thus capturing relationships between categories. - ๐Ÿงช BayBE also provides built-in chemical encodings. - ๐Ÿš€ Leverage **historic data** to accelerate optimization via transfer learning. -- **Flexible** definition of target outcomes, search spaces, and optimization strategy: - - ๐ŸŽฏ Option to use numerical targets (e.g., measured outcome value) or binary targets (e.g., good/bad classification). Targets can be minimized, maximized, or matched to a target value. +- **Flexible** definition of target outcomes, parameter search spaces, and optimization strategies: + - ๐ŸŽฏ Option to use numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized, or matched to a specific value. - โš–๏ธ Multiple targets can be optimized at once (e.g., via Pareto optimization). - - ๐ŸŽญ Use both continuous and discrete parameters in a single search space. - - ๐Ÿ”ข Define maximal number of mixture components via cardinality constraints. - - ๐ŸŽฐ Different optimization strategies to balance exploration and exploitation, including bandit models and active learning. + - ๐ŸŽญ Both continuous and discrete parameters can be used within a single search space. + - ๐Ÿ”ข The maximal number of mixture components can be defined via cardinality constraints. + - ๐ŸŽฐ Different optimization strategies can be selected to balance exploration and exploitation of the search space, including bandit models and active learning. - ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements via distributed workflows. - ๐Ÿ” **Insights**: Easily analyze feature importance and model behavior. - ๐Ÿ“ˆ Utilities for **benchmarking**, such as backtesting and simulations. @@ -69,8 +75,26 @@ The following provides a non-comprehensive overview: ## โšก Quick Start -Let us consider a simple experiment where we control three parameters and want to -maximize a single target called `Yield`. +To perform Bayesian Design of Experiments with BayBE, +the users must first specify the **parameter search space** and **objective** to be optimized. +Based on this information and any **available data** about outcomes of specific parameter settings, +BayBE will **recommend the next set of parameter combinations** to be **measured**. +To inform the next recommendation cycle, the newly generated measurements can be added to BayBE. + +
+ +![quick start](docs/_static/quick_start_automatic.svg) + +
+ +From the user-perspective, the most important part is the "design" step. +If you are new to BayBE, we suggest consulting our +[design checklist](https://emdgroup.github.io/baybe/stable/faq.html#checklist-for-designing-baybe-experiments) +to help you with the design setup. + +Below we show a simple optimization procedure, starting with the design step and subsequently +performing the recommendation loop. +The provided example aims to maximize the yield of a chemical reaction by adjusting reaction parameters. First, install BayBE into your Python environment: ```bash @@ -81,7 +105,7 @@ For more information on this step, see our ### Defining the Optimization Objective -In BayBE's language, the `Yield` can be represented as a `NumericalTarget`, +In BayBE's language, the reaction yield can be represented as a `NumericalTarget`, which we wrap into a `SingleTargetObjective`: ```python @@ -91,7 +115,8 @@ from baybe.objectives import SingleTargetObjective target = NumericalTarget(name="Yield") objective = SingleTargetObjective(target=target) ``` -In cases where we are confronted with multiple (potentially conflicting) targets, +In cases where we are confronted with multiple (potentially conflicting) targets +(e.g., yield vs cost), the `ParetoObjective` or `DesirabilityObjective` can be used instead. These allow to define additional settings, such as how the targets should be balanced. For more details, see the @@ -101,11 +126,9 @@ of the user guide. ### Defining the Search Space Next, 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]`, and `Solvent` โ€“ as follows: +reaction `Parameters` we can tune (e.g., granularity, +pressure, and solvent) to optimize the yield. We also need to specify +which values individual parameters can take. ```python from baybe.parameters import ( @@ -162,20 +185,15 @@ and alternative ways of construction. ### Optional: Defining the Optimization Strategy -As an optional step, we can specify details on how the optimization should be -conducted. If omitted, BayBE will choose a default setting. +As an optional step, we can specify details on how the optimization of the experiment should be +performed. If omitted, BayBE will choose a default setting. For our example, we combine two recommenders via a so-called meta recommender named `TwoPhaseMetaRecommender`: 1. In cases where no measurements have been made prior to the interaction with BayBE, - a selection via `initial_recommender` is used. -2. As soon as the first measurements are available, we switch to `recommender`. - -For more details on the different recommenders, their underlying algorithmic -details, and their configuration settings, see the -[recommenders section](https://emdgroup.github.io/baybe/stable/userguide/recommenders.html) -of the user guide. + the parameters will be recommended with the `initial_recommender`. +2. As soon as the first measurements are available, we switch to the `recommender`. ```python from baybe.recommenders import ( @@ -190,9 +208,14 @@ recommender = TwoPhaseMetaRecommender( ) ``` +For more details on the different recommenders, their underlying algorithmic +details, and their configuration settings, see the +[recommenders section](https://emdgroup.github.io/baybe/stable/userguide/recommenders.html) +of the user guide. + ### The Optimization Loop -We can now construct a campaign object that brings all pieces of the puzzle together: +We can now construct a `Campaign` that performs the Bayesian optimization of the experiment: ```python from baybe import Campaign @@ -203,19 +226,25 @@ campaign = Campaign(searchspace, objective, recommender) With this object at hand, we can start our experimentation cycle. In particular: -* We can ask BayBE to `recommend` new experiments. -* We can `add_measurements` for certain experimental settings to the campaign's - database. +* The campaign can `recommend` new experiments. +* We can `add_measurements` of target values for the measured parameter 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. ```python -df = campaign.recommend(batch_size=3) +df = campaign.recommend(batch_size=3) # Recommend three parameter settings print(df) ``` +The below table shows the three parameter setting for which BayBE recommended to +measure the reaction yield. + +Note that the specific recommendations will depend on both the data +already fed to the campaign and the random number generator seed that is used. + ```none Granularity Pressure[bar] Solvent 15 medium 1.0 Solvent D @@ -223,32 +252,31 @@ print(df) 29 fine 5.0 Solvent B ``` -Note 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: +After having conducted the recommended experiments, we can add the newly measured +target information to the campaign: ```python -df["Yield"] = [79.8, 54.1, 59.4] +df["Yield"] = [79.8, 54.1, 59.4] # Measured yields for the three recommended parameter settings 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. +With the newly provided data, BayBE can produce a refined recommendation for the next iteration. +This loop typically continues until a desired target value is achieved in the experiment. -### Advanced Example: Chemical Substances -BayBE has several modules to go beyond traditional approaches. One such example is the -use of custom encodings for categorical parameters. Chemical encodings for substances -are a special built-in case of this that comes with BayBE. +### Inspect the progress of the experiment optimization + +The below plot shows progression of a campaign that optimized direct arylation reaction +by tuning the solvent, base and ligand +(from [Shields, B.J. et al.](https://doi.org/10.1038/s41586-021-03213-y)). +Each line shows the best target value that was measured in each experimental iteration. +Different lines show outcomes of `Campaigns` with different designs. -In the following picture you can see -the outcome for treating the solvent, base and ligand in a direct arylation reaction -optimization (from [Shields, B.J. et al.](https://doi.org/10.1038/s41586-021-03213-y)) with -chemical encodings compared to one-hot and a random baseline: ![Substance Encoding Example](./examples/Backtesting/full_lookup_light.svg) +In particular, the five `Campaigns` differ in how the chemical `Parameters` were encoded. +We can see that optimization is more efficient when +using chemical encodings (e.g., *MORDRED*) rather than encoding categories with *one-hot* encoding or *random* features. + (installation)= ## ๐Ÿ’ป Installation ### From Package Index diff --git a/docs/_static/complex_search_space_automatic.svg b/docs/_static/complex_search_space_automatic.svg new file mode 100644 index 0000000000..2f0f8f5a77 --- /dev/null +++ b/docs/_static/complex_search_space_automatic.svg @@ -0,0 +1,4 @@ + + + + 2025-10-24T13:49:33.531120 image/svg+xml Matplotlib v3.9.0, https://matplotlib.org/ \ No newline at end of file diff --git a/docs/_static/complex_search_space_dark.svg b/docs/_static/complex_search_space_dark.svg new file mode 100644 index 0000000000..aaa34141b8 --- /dev/null +++ b/docs/_static/complex_search_space_dark.svg @@ -0,0 +1,4 @@ + + + + 2025-10-24T13:49:33.531120 image/svg+xml Matplotlib v3.9.0, https://matplotlib.org/ \ No newline at end of file diff --git a/docs/_static/complex_search_space_light.svg b/docs/_static/complex_search_space_light.svg new file mode 100644 index 0000000000..1f195e5a01 --- /dev/null +++ b/docs/_static/complex_search_space_light.svg @@ -0,0 +1,4 @@ + + + + 2025-10-24T13:49:33.531120 image/svg+xml Matplotlib v3.9.0, https://matplotlib.org/ \ No newline at end of file diff --git a/docs/_static/quick_starrt_dark.svg b/docs/_static/quick_starrt_dark.svg new file mode 100644 index 0000000000..89232f2b64 --- /dev/null +++ b/docs/_static/quick_starrt_dark.svg @@ -0,0 +1,4 @@ + + + +
Define parameter searchspace for finding the best possible parameter setting
Objective to be optimized
Add measurements
Getย recommendations for parameter combinations
Measure
 \ No newline at end of file diff --git a/docs/_static/quick_start_automatic.svg b/docs/_static/quick_start_automatic.svg new file mode 100644 index 0000000000..666be18904 --- /dev/null +++ b/docs/_static/quick_start_automatic.svg @@ -0,0 +1,4 @@ + + + +
Define parameter searchspace for finding the best possible parameter setting
Objective to be optimized
Add measurements
Getย recommendations for parameter combinations
Measure
 \ No newline at end of file diff --git a/docs/_static/quick_start_light.svg b/docs/_static/quick_start_light.svg new file mode 100644 index 0000000000..babc27add6 --- /dev/null +++ b/docs/_static/quick_start_light.svg @@ -0,0 +1,4 @@ + + + +
Define parameter searchspace for finding the best possible parameter setting
Objective to be optimized
Add measurements
Getย recommendations for parameter combinations
Measure
 \ No newline at end of file From 1832a470903a8ce19df43d3aa8321fec678611bf Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 16:42:22 +0200 Subject: [PATCH 14/51] Format FAQ --- docs/faq.md | 69 ++++++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 54443cbe36..1886da629d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -29,66 +29,71 @@ your campaign, depending on your settings for the ### Defining targets -- Should be target value maximized rather than minimized or matched to specific value? +```{dropdown} Should be target value maximized rather than minimized or matched to specific value? - > Specify this when -[defining the target](https://emdgroup.github.io/baybe/stable/userguide/targets.html#numericaltarget). +Specify this when +[defining the target](userguide/targets.html#numericaltarget). +``` -- Should be multiple target optimized simultaneously? +```{dropdown} Should be multiple target optimized simultaneously? - > See how to use -[multi-target objectives](https://emdgroup.github.io/baybe/stable/userguide/objectives.html). +See how to use +[multi-target objectives](userguide/objectives.html). +``` ### Defining parameter search space -- Are only some parameter values of interest/possible? +```{dropdown} Are only some parameter values of interest/possible? - > See how to exclude some -[parameter values](https://emdgroup.github.io/baybe/stable/userguide/getting_recommendations.html#excluding-configurations) +See how to exclude some +[parameter values](userguide/getting_recommendations.html#excluding-configurations) from being recommended, such as by defining -[bounds for continuous parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#numericalcontinuousparameter) -or [active values for discrete parameters](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters). +[bounds for continuous parameters](userguide/parameters.html#numericalcontinuousparameter) +or [active values for discrete parameters](userguide/parameters.html#discrete-parameters). +``` -- Are only some parameter combinations of interest/possible? +```{dropdown} Are only some parameter combinations of interest/possible? - > See how to exclude some +See how to exclude some parameter combinations from being considered by using -[constraints](https://emdgroup.github.io/baybe/stable/userguide/constraints.html) or -[constrained searchspaces](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). +[constraints](userguide/constraints.html) or +[constrained searchspaces](userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a -[dataframe](https://emdgroup.github.io/baybe/stable/userguide/searchspace.html#id3) +[dataframe](userguide/searchspace.html#id3) rather than from the product of all possible parameter combinations. +``` -- Are some parameters non-numeric or allow only discrete numbers? +```{dropdown} Are some parameters non-numeric or allow only discrete numbers? - > Use [discrete](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) -rather than [continuous](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#continuous-parameters) parameters. + > Use [discrete](userguide/parameters.html#discrete-parameters) +rather than [continuous](userguide/parameters.html#continuous-parameters) parameters. +``` -- Is it possible to encode discrete parameters based on domain knowledge -to capture relationships between categories -(e.g., ordered values, molecular fingerprints, model embeddings)? +```{dropdown} Is it possible to encode discrete parameters based on domain knowledge to capture relationships between categories (e.g., ordered values, molecular fingerprints, model embeddings)? - > See how to -[encode](https://emdgroup.github.io/baybe/stable/userguide/parameters.html#discrete-parameters) +See how to +[encode](userguide/parameters.html#discrete-parameters) discrete parameters or provide custom encodings. +``` ### Account for specifics of data availability or acquisition procedure -- Is additional data from historic or other partially-related experiments available? +```{dropdown} Is additional data from historic or other partially-related experiments available? - > Use [transfer learning](https://emdgroup.github.io/baybe/stable/userguide/transfer_learning.html). + > Use [transfer learning](userguide/transfer_learning.html). +``` -- Will the outcome measurements of different parameter setting become available at different times? +```{dropdown} Will the outcome measurements of different parameter setting become available at different times? - > Use [asynchronous workflows](https://emdgroup.github.io/baybe/stable/userguide/async.html). + > Use [asynchronous workflows](userguide/async.html). +``` ### Advanced: adjust how recommendations are prioritized -- Is the aim to reduce the overall uncertainty across different regions of the search space -rather than optimize a specific objective? - - > Use [active learning](https://emdgroup.github.io/baybe/stable/userguide/active_learning.html). +```{dropdown} Is the aim to reduce the overall uncertainty across different regions of the search space rather than optimize a specific objective? + > Use [active learning](userguide/active_learning.html). +``` From 0e293b2295f420e07773992f3b552271a5f612ca Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Fri, 24 Oct 2025 22:33:03 +0200 Subject: [PATCH 15/51] Update changelog Updated changelog to reflect recent changes and fixes. --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52a959223b..8773630d4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -99,6 +99,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `unstructure_base` and `get_base_structure_hook` (de-)serialization utilities have been replaced with `unstructure_with_type` and `make_base_structure_hook` +### Changed +- Documentation is now more accessible for new users + ### Fixed - It is no longer possible to use identical names between parameters and targets - Random seed context is correctly set within benchmarks From 0da883e04ebd6fa108d6c5eea9459c39e0a866e7 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Mon, 27 Oct 2025 08:53:08 +0100 Subject: [PATCH 16/51] Add a few more examples --- README.md | 13 +++++++------ docs/faq.md | 7 ++++++- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ad29422961..68e2a957c7 100644 --- a/README.md +++ b/README.md @@ -57,15 +57,16 @@ focusing on making this procedure easily-accessible for real-world experiments. BayBE offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. The following provides a non-comprehensive overview: -- ๐Ÿ› ๏ธ Leverage **domain knowledge** for encoding categorical data, thus capturing relationships between categories. - - ๐Ÿงช BayBE also provides built-in chemical encodings. -- ๐Ÿš€ Leverage **historic data** to accelerate optimization via transfer learning. -- **Flexible** definition of target outcomes, parameter search spaces, and optimization strategies: +- ๐Ÿ“š Leverage **domain knowledge**. + - ๐ŸŽจ Encode categorical data to capture relationships between categories. BayBE also provides built-in chemical encodings. + - ๐Ÿ› ๏ธ Option to build-in mechanistic process understanding via custom surrogate models. +- ๐Ÿ›๏ธ Leverage **historic data** to accelerate optimization via transfer learning. +- ๐ŸŒ€ **Flexible** definition of target outcomes, parameter search spaces, and optimization strategies: - ๐ŸŽฏ Option to use numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized, or matched to a specific value. - - โš–๏ธ Multiple targets can be optimized at once (e.g., via Pareto optimization). + - ๐Ÿ‘ฅ๐Ÿ‘ฅ Multiple targets can be optimized at once (e.g., via Pareto optimization). - ๐ŸŽญ Both continuous and discrete parameters can be used within a single search space. - ๐Ÿ”ข The maximal number of mixture components can be defined via cardinality constraints. - - ๐ŸŽฐ Different optimization strategies can be selected to balance exploration and exploitation of the search space, including bandit models and active learning. + - โš–๏ธ Different optimization strategies can be selected to balance exploration and exploitation of the search space, including bandit models and active learning. - ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements via distributed workflows. - ๐Ÿ” **Insights**: Easily analyze feature importance and model behavior. - ๐Ÿ“ˆ Utilities for **benchmarking**, such as backtesting and simulations. diff --git a/docs/faq.md b/docs/faq.md index 1886da629d..3223da174a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -76,7 +76,12 @@ See how to discrete parameters or provide custom encodings. ``` -### Account for specifics of data availability or acquisition procedure +### Account for specifics of data availability or data acquisition procedure + +```{dropdown} Is no prior data available and the experiments should be done in batches? + + > Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter settings to be tested. +``` ```{dropdown} Is additional data from historic or other partially-related experiments available? From e963d6ba9e72944aa02cef490f52f213d6519ea1 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Mon, 27 Oct 2025 08:55:03 +0100 Subject: [PATCH 17/51] Fix typo --- docs/userguide/userguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/userguide.md b/docs/userguide/userguide.md index 6d50e55322..b0ede87b00 100644 --- a/docs/userguide/userguide.md +++ b/docs/userguide/userguide.md @@ -14,7 +14,7 @@ The most commonly used interface BayBE provides is the central which suggests new measurements and administers the current state of your experimental operation. The diagram below explains how the [`Campaign`](baybe.campaign.Campaign) can be used to perform -the bayesian optimization loop, how it can be configured and +the Bayesian optimization loop, how it can be configured and how the results can be post-analysed. ```{image} ../_static/api_overview_dark.svg From fddcdf095ab4fd0920415d351a93eba6991eb998 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 28 Oct 2025 10:28:38 +0100 Subject: [PATCH 18/51] Add emoji to example use cases --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 68e2a957c7..ad848509be 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,11 @@ within a complex parameter search space. Example use-cases: -- Find chemical reaction conditions or process parameters -- Create materials, chemical mixtures, or formulations with desired properties -- Optimize the 3D shape of a physical object -- Find model hyperparameters -- Find tasty espresso machine settings +- ๐Ÿงช Find chemical reaction conditions or process parameters +- ๐Ÿฅฃ Create materials, chemical mixtures, or formulations with desired properties +- โœˆ๏ธ Optimize the 3D shape of a physical object +- ๐Ÿ–ฅ๏ธ Find model hyperparameters +- ๐Ÿซ– Find tasty espresso machine settings This is achieved via **Bayesian Design of Experiments**, which is an efficient way for navigating parameter search spaces. From 3b15705610e476d584f1ac78152287dc0bcc4aae Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 28 Oct 2025 10:42:21 +0100 Subject: [PATCH 19/51] reword --- README.md | 2 +- docs/faq.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ad848509be..8a2b3575c0 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Example use-cases: - ๐Ÿงช Find chemical reaction conditions or process parameters - ๐Ÿฅฃ Create materials, chemical mixtures, or formulations with desired properties - โœˆ๏ธ Optimize the 3D shape of a physical object -- ๐Ÿ–ฅ๏ธ Find model hyperparameters +- ๐Ÿ–ฅ๏ธ Select model hyperparameters - ๐Ÿซ– Find tasty espresso machine settings This is achieved via **Bayesian Design of Experiments**, diff --git a/docs/faq.md b/docs/faq.md index 3223da174a..0d60da1500 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -29,13 +29,13 @@ your campaign, depending on your settings for the ### Defining targets -```{dropdown} Should be target value maximized rather than minimized or matched to specific value? +```{dropdown} Should the target value be maximized, minimized, or be matched to a specific value? Specify this when [defining the target](userguide/targets.html#numericaltarget). ``` -```{dropdown} Should be multiple target optimized simultaneously? +```{dropdown} Should multiple target be optimized simultaneously? See how to use [multi-target objectives](userguide/objectives.html). From f86a1c8a19448df99dc8e38d76dfef97c978d638 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 28 Oct 2025 10:52:18 +0100 Subject: [PATCH 20/51] Intro of Checklist for designing BayBE optimization campaigns --- docs/faq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 0d60da1500..06000aa433 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -25,7 +25,11 @@ your campaign, depending on your settings for the {attr}`~baybe.campaign.Campaign.allow_recommending_already_recommended` flags. ``` -## Checklist for designing BayBE experiments +## Checklist for designing BayBE optimization campaigns + +This checklist collects **common questions that you need to ask yourself** when designing a BayBE optimization campaign. It also provides documentation references that will help you with the corresponding setup. + +Note that this is not a comprehensive guide of all BayBE's functionalities, but rather a "quick start" meant to help you with the most basic design principles. ### Defining targets From 299ade32bde41706ce9e9ebe8f25763824a9ebda Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 28 Oct 2025 10:58:22 +0100 Subject: [PATCH 21/51] reword --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8a2b3575c0..a91b6b174a 100644 --- a/README.md +++ b/README.md @@ -269,7 +269,8 @@ This loop typically continues until a desired target value is achieved in the ex The below plot shows progression of a campaign that optimized direct arylation reaction by tuning the solvent, base and ligand (from [Shields, B.J. et al.](https://doi.org/10.1038/s41586-021-03213-y)). -Each line shows the best target value that was measured in each experimental iteration. +Each line shows the best target value that was cumulatively achieved after a given number of experimental iteration. + Different lines show outcomes of `Campaigns` with different designs. ![Substance Encoding Example](./examples/Backtesting/full_lookup_light.svg) From 0fa28d5f0b533294f5490b18886e6a47a9554127 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 28 Oct 2025 10:58:57 +0100 Subject: [PATCH 22/51] typo --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a91b6b174a..aa9b59f07d 100644 --- a/README.md +++ b/README.md @@ -269,7 +269,8 @@ This loop typically continues until a desired target value is achieved in the ex The below plot shows progression of a campaign that optimized direct arylation reaction by tuning the solvent, base and ligand (from [Shields, B.J. et al.](https://doi.org/10.1038/s41586-021-03213-y)). -Each line shows the best target value that was cumulatively achieved after a given number of experimental iteration. +Each line shows the best target value that was cumulatively achieved after a given number of experimental iterations. + Different lines show outcomes of `Campaigns` with different designs. From 264648ee7f65ed6ecece0b0fd5cbb3ce869cbfb5 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 29 Oct 2025 11:46:35 +0100 Subject: [PATCH 23/51] Force documentation build - TEMPORARY --- docs/scripts/build_documentation.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/scripts/build_documentation.py b/docs/scripts/build_documentation.py index 756797be50..d9c86d321c 100644 --- a/docs/scripts/build_documentation.py +++ b/docs/scripts/build_documentation.py @@ -111,11 +111,11 @@ def build_documentation( "html", "docs", build_dir, - "-n", # Being nitpicky - "-W", # Fail when encountering an error or a warning + #"-n", # Being nitpicky + #"-W", # Fail when encountering an error or a warning ] - if force: + if True: print("Force-building the documentation, ignoring errors and warnings.") # In force mode, we do not want to fail, even if an error code is returned. # Hence, we use run instead of check_call From cbc3aa3a2fb1f25ec51dd19737282d22bfd65e4c Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 29 Oct 2025 15:55:51 +0100 Subject: [PATCH 24/51] Remove offending link and thus reset workflow to original state --- README.md | 2 +- docs/scripts/build_documentation.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index aa9b59f07d..d4df4281ad 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ To inform the next recommendation cycle, the newly generated measurements can be From the user-perspective, the most important part is the "design" step. If you are new to BayBE, we suggest consulting our -[design checklist](https://emdgroup.github.io/baybe/stable/faq.html#checklist-for-designing-baybe-experiments) +[design checklist](https://emdgroup.github.io/baybe/stable/faq.html) to help you with the design setup. Below we show a simple optimization procedure, starting with the design step and subsequently diff --git a/docs/scripts/build_documentation.py b/docs/scripts/build_documentation.py index d9c86d321c..756797be50 100644 --- a/docs/scripts/build_documentation.py +++ b/docs/scripts/build_documentation.py @@ -111,11 +111,11 @@ def build_documentation( "html", "docs", build_dir, - #"-n", # Being nitpicky - #"-W", # Fail when encountering an error or a warning + "-n", # Being nitpicky + "-W", # Fail when encountering an error or a warning ] - if True: + if force: print("Force-building the documentation, ignoring errors and warnings.") # In force mode, we do not want to fail, even if an error code is returned. # Hence, we use run instead of check_call From cd17c868d731913162a05c6456644dfcf2e53765 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 29 Oct 2025 17:40:01 +0100 Subject: [PATCH 25/51] Fix the use of the word experiment --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d4df4281ad..56a9ba4a42 100644 --- a/README.md +++ b/README.md @@ -186,7 +186,7 @@ and alternative ways of construction. ### Optional: Defining the Optimization Strategy -As an optional step, we can specify details on how the optimization of the experiment should be +As an optional step, we can specify details on how the optimization of the experimental settings should be performed. If omitted, BayBE will choose a default setting. For our example, we combine two recommenders via a so-called meta recommender named @@ -216,7 +216,7 @@ of the user guide. ### The Optimization Loop -We can now construct a `Campaign` that performs the Bayesian optimization of the experiment: +We can now construct a `Campaign` that performs the Bayesian optimization of the experimental settings: ```python from baybe import Campaign @@ -224,7 +224,7 @@ from baybe import Campaign campaign = Campaign(searchspace, objective, recommender) ``` -With this object at hand, we can start our experimentation cycle. +With this object at hand, we can start our optimization cycle. In particular: * The campaign can `recommend` new experiments. @@ -264,7 +264,7 @@ campaign.add_measurements(df) With the newly provided data, BayBE can produce a refined recommendation for the next iteration. This loop typically continues until a desired target value is achieved in the experiment. -### Inspect the progress of the experiment optimization +### Inspect the progress of the experimental setting optimization The below plot shows progression of a campaign that optimized direct arylation reaction by tuning the solvent, base and ligand From 8f3f34f75aa0bd39ae1048b3d73a4167b2e0af32 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 29 Oct 2025 17:46:47 +0100 Subject: [PATCH 26/51] Use telegraph style for all headings --- README.md | 2 +- docs/faq.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 56a9ba4a42..c563b54805 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,7 @@ campaign.add_measurements(df) With the newly provided data, BayBE can produce a refined recommendation for the next iteration. This loop typically continues until a desired target value is achieved in the experiment. -### Inspect the progress of the experimental setting optimization +### Inspect the Progress of the Experimental Setting Optimization The below plot shows progression of a campaign that optimized direct arylation reaction by tuning the solvent, base and ligand diff --git a/docs/faq.md b/docs/faq.md index 06000aa433..bcc2d007c3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -25,13 +25,13 @@ your campaign, depending on your settings for the {attr}`~baybe.campaign.Campaign.allow_recommending_already_recommended` flags. ``` -## Checklist for designing BayBE optimization campaigns +## Checklist for Designing BayBE Optimization Campaigns This checklist collects **common questions that you need to ask yourself** when designing a BayBE optimization campaign. It also provides documentation references that will help you with the corresponding setup. Note that this is not a comprehensive guide of all BayBE's functionalities, but rather a "quick start" meant to help you with the most basic design principles. -### Defining targets +### Defining Targets ```{dropdown} Should the target value be maximized, minimized, or be matched to a specific value? @@ -45,7 +45,7 @@ See how to use [multi-target objectives](userguide/objectives.html). ``` -### Defining parameter search space +### Defining Parameter Search Space ```{dropdown} Are only some parameter values of interest/possible? @@ -80,7 +80,7 @@ See how to discrete parameters or provide custom encodings. ``` -### Account for specifics of data availability or data acquisition procedure +### Account for Specifics of Data Availability or Data Acquisition Procedure ```{dropdown} Is no prior data available and the experiments should be done in batches? @@ -97,7 +97,7 @@ discrete parameters or provide custom encodings. > Use [asynchronous workflows](userguide/async.html). ``` -### Advanced: adjust how recommendations are prioritized +### Advanced: Adjust how Recommendations are Prioritized ```{dropdown} Is the aim to reduce the overall uncertainty across different regions of the search space rather than optimize a specific objective? From c6cf29d95dfc4b65c113ffa245ab53e2a2a4859a Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 29 Oct 2025 17:48:07 +0100 Subject: [PATCH 27/51] reword --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c563b54805..9ec01ed251 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ In particular, available measurements can be submitted at any time and also seve times before querying the next recommendations. ```python -df = campaign.recommend(batch_size=3) # Recommend three parameter settings +df = campaign.recommend(batch_size=3) # Recommend three experimental settings to test print(df) ``` From 5584eb1fa1723be85d5c5d85aacbf87865aa3143 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 06:37:08 +0100 Subject: [PATCH 28/51] rweord --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9ec01ed251..3bdda23c84 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,8 @@ # BayBE โ€” A Bayesian Back End for Design of Experiments The **Bay**esian **B**ack **E**nd (**BayBE**) -helps to find a **good parameter setting** +helps to find a **good parameter settings** + within a complex parameter search space.
From 75718b55c6369b2174240d7330996ec79ccc5778 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 06:49:29 +0100 Subject: [PATCH 29/51] Add example use case --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3bdda23c84..66416d18ce 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,8 @@ Example use-cases: - ๐Ÿงช Find chemical reaction conditions or process parameters - ๐Ÿฅฃ Create materials, chemical mixtures, or formulations with desired properties - โœˆ๏ธ Optimize the 3D shape of a physical object -- ๐Ÿ–ฅ๏ธ Select model hyperparameters +- ๐Ÿ–ฅ๏ธ Optimize an in silico simulation +- โš™๏ธ Select model hyperparameters - ๐Ÿซ– Find tasty espresso machine settings This is achieved via **Bayesian Design of Experiments**, From b1aaa0eebfe788a4ab1be6161012f21c5d143f36 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 06:51:06 +0100 Subject: [PATCH 30/51] Remove oxford comma --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 66416d18ce..710629f160 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ within a complex parameter search space. Example use-cases: - ๐Ÿงช Find chemical reaction conditions or process parameters -- ๐Ÿฅฃ Create materials, chemical mixtures, or formulations with desired properties +- ๐Ÿฅฃ Create materials, chemical mixtures or formulations with desired properties - โœˆ๏ธ Optimize the 3D shape of a physical object - ๐Ÿ–ฅ๏ธ Optimize an in silico simulation - โš™๏ธ Select model hyperparameters @@ -63,8 +63,8 @@ The following provides a non-comprehensive overview: - ๐ŸŽจ Encode categorical data to capture relationships between categories. BayBE also provides built-in chemical encodings. - ๐Ÿ› ๏ธ Option to build-in mechanistic process understanding via custom surrogate models. - ๐Ÿ›๏ธ Leverage **historic data** to accelerate optimization via transfer learning. -- ๐ŸŒ€ **Flexible** definition of target outcomes, parameter search spaces, and optimization strategies: - - ๐ŸŽฏ Option to use numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized, or matched to a specific value. +- ๐ŸŒ€ **Flexible** definition of target outcomes, parameter search spaces and optimization strategies: + - ๐ŸŽฏ Option to use numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized or matched to a specific value. - ๐Ÿ‘ฅ๐Ÿ‘ฅ Multiple targets can be optimized at once (e.g., via Pareto optimization). - ๐ŸŽญ Both continuous and discrete parameters can be used within a single search space. - ๐Ÿ”ข The maximal number of mixture components can be defined via cardinality constraints. @@ -130,7 +130,7 @@ of the user guide. Next, we inform BayBE about the available "control knobs", that is, the underlying reaction `Parameters` we can tune (e.g., granularity, -pressure, and solvent) to optimize the yield. We also need to specify +pressure and solvent) to optimize the yield. We also need to specify which values individual parameters can take. ```python @@ -212,7 +212,7 @@ recommender = TwoPhaseMetaRecommender( ``` For more details on the different recommenders, their underlying algorithmic -details, and their configuration settings, see the +details and their configuration settings, see the [recommenders section](https://emdgroup.github.io/baybe/stable/userguide/recommenders.html) of the user guide. @@ -311,7 +311,7 @@ pip install git+https://github.com/emdgroup/baybe.git@main Alternatively, 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: +desired commit and run: ```bash pip install . From 60c8f0e5a00e5d6cce2a2e36a2e5e7490e02185d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 07:43:51 +0100 Subject: [PATCH 31/51] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 710629f160..a73e250846 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ To inform the next recommendation cycle, the newly generated measurements can be
-From the user-perspective, the most important part is the "design" step. +From the user perspective, the most important part is the "design" step. If you are new to BayBE, we suggest consulting our [design checklist](https://emdgroup.github.io/baybe/stable/faq.html) to help you with the design setup. From af543f9620b5cdd5300c4ddc0f0e346c7fd63f09 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 07:46:32 +0100 Subject: [PATCH 32/51] reword --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a73e250846..75d53d8c0f 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,8 @@ to help you with the design setup. Below we show a simple optimization procedure, starting with the design step and subsequently performing the recommendation loop. -The provided example aims to maximize the yield of a chemical reaction by adjusting reaction parameters. +The provided example aims to maximize the yield of a chemical reaction by adjusting its parameters +(also known as reaction conditions). First, install BayBE into your Python environment: ```bash From 08ee66b3ef7d3b159db73615eaee6d218aaf971d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 08:01:02 +0100 Subject: [PATCH 33/51] Fix file name typo --- docs/_static/{quick_starrt_dark.svg => quick_start_dark.svg} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/_static/{quick_starrt_dark.svg => quick_start_dark.svg} (100%) diff --git a/docs/_static/quick_starrt_dark.svg b/docs/_static/quick_start_dark.svg similarity index 100% rename from docs/_static/quick_starrt_dark.svg rename to docs/_static/quick_start_dark.svg From 8c3b9f33e5ee1229c0c4494104513d8324895614 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 08:58:10 +0100 Subject: [PATCH 34/51] Try not using svg with automatic light/dark mode --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 75d53d8c0f..18ff8717f1 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ within a complex parameter search space.
-![complex search space](docs/_static/complex_search_space_automatic.svg) +![complex search space](docs/_static/complex_search_space_light.svg)
@@ -86,7 +86,7 @@ To inform the next recommendation cycle, the newly generated measurements can be
-![quick start](docs/_static/quick_start_automatic.svg) +![quick start](docs/_static/quick_start_light.svg)
From cf01ac265d8f138cd55abd55487a618c614ec97d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 30 Oct 2025 10:04:35 +0100 Subject: [PATCH 35/51] fix image links in readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 18ff8717f1..61352fe637 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ within a complex parameter search space.
-![complex search space](docs/_static/complex_search_space_light.svg) +![complex search space](./docs/_static/complex_search_space_automatic.svg)
@@ -86,7 +86,7 @@ To inform the next recommendation cycle, the newly generated measurements can be
-![quick start](docs/_static/quick_start_light.svg) +![quick start](./docs/_static/quick_start_automatic.svg)
From 4f17ccd5e8b0c9ca194c3ee24e8bb0610049af4e Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 11:22:54 +0100 Subject: [PATCH 36/51] Remove changelog entry --- CHANGELOG.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8773630d4d..52a959223b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -99,9 +99,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `unstructure_base` and `get_base_structure_hook` (de-)serialization utilities have been replaced with `unstructure_with_type` and `make_base_structure_hook` -### Changed -- Documentation is now more accessible for new users - ### Fixed - It is no longer possible to use identical names between parameters and targets - Random seed context is correctly set within benchmarks From 2ddcf592d47c94735d2af7751850b7802f74f35a Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:05:34 +0100 Subject: [PATCH 37/51] Fix typo --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 61352fe637..5e384b44ba 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,7 @@ # BayBE โ€” A Bayesian Back End for Design of Experiments -The **Bay**esian **B**ack **E**nd (**BayBE**) -helps to find a **good parameter settings** - +The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find **good parameter settings** within a complex parameter search space.
From 16588c35c1411187c3c7ccb274f617b11e148068 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:24:07 +0100 Subject: [PATCH 38/51] Remove unnecessary wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e384b44ba..a02e7f99e8 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The following provides a non-comprehensive overview: - ๐ŸŽญ Both continuous and discrete parameters can be used within a single search space. - ๐Ÿ”ข The maximal number of mixture components can be defined via cardinality constraints. - โš–๏ธ Different optimization strategies can be selected to balance exploration and exploitation of the search space, including bandit models and active learning. -- ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements via distributed workflows. +- ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements. - ๐Ÿ” **Insights**: Easily analyze feature importance and model behavior. - ๐Ÿ“ˆ Utilities for **benchmarking**, such as backtesting and simulations. - ๐Ÿ“ **High-quality code base** with comprehensive tests and typing. From 6cf645c13c1f2dab0d85c4457338aae582c38791 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:25:29 +0100 Subject: [PATCH 39/51] Reword to match API terms properly --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a02e7f99e8..3576867905 100644 --- a/README.md +++ b/README.md @@ -128,9 +128,9 @@ of the user guide. ### Defining the Search Space Next, we inform BayBE about the available "control knobs", that is, the underlying -reaction `Parameters` we can tune (e.g., granularity, -pressure and solvent) to optimize the yield. We also need to specify -which values individual parameters can take. +reaction parameters we can tune to optimize the yield. +In this case we tune granularity, pressure and solvent, each being encoded as a `Parameter`. +We also need to specify which values individual parameters can take. ```python from baybe.parameters import ( From 186e6b44532cb7eb29fa62e24114a8b0313e6c9d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:28:56 +0100 Subject: [PATCH 40/51] Reword to properly match the API wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3576867905..c06135775e 100644 --- a/README.md +++ b/README.md @@ -277,7 +277,7 @@ Different lines show outcomes of `Campaigns` with different designs. ![Substance Encoding Example](./examples/Backtesting/full_lookup_light.svg) -In particular, the five `Campaigns` differ in how the chemical `Parameters` were encoded. +In particular, the five `Campaigns` differ in how molecules are encoded within each chemical `Parameter`. We can see that optimization is more efficient when using chemical encodings (e.g., *MORDRED*) rather than encoding categories with *one-hot* encoding or *random* features. From 12318cfb3ea0da8180d678b617094861a407a552 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Tue, 4 Nov 2025 15:45:22 +0100 Subject: [PATCH 41/51] Fix readme image links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c06135775e..7fcdc418a4 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ within a complex parameter search space.
-![complex search space](./docs/_static/complex_search_space_automatic.svg) +[![Complex Search Space](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/complex_search_space_automatic.svg)](https://github.com/emdgroup/baybe/)
@@ -84,7 +84,7 @@ To inform the next recommendation cycle, the newly generated measurements can be
-![quick start](./docs/_static/quick_start_automatic.svg) +[![Quick Start](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/quick_start_automatic.svg)](https://github.com/emdgroup/baybe/)
From 9b1c80908514301fd0abb05a271b29096ae8c93f Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:34:10 +0100 Subject: [PATCH 42/51] reword Co-authored-by: AdrianSosic --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7fcdc418a4..d69697a4f4 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ # BayBE โ€” A Bayesian Back End for Design of Experiments The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find **good parameter settings** -within a complex parameter search space. +within complex parameter search spaces.
From 522ee1d32bd2ab1e6ddda0f822068ebeb06f85f8 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:34:39 +0100 Subject: [PATCH 43/51] reword Co-authored-by: AdrianSosic --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d69697a4f4..ab3d389b66 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,8 @@ within complex parameter search spaces.
-Example use-cases: +Example use cases: + - ๐Ÿงช Find chemical reaction conditions or process parameters - ๐Ÿฅฃ Create materials, chemical mixtures or formulations with desired properties - โœˆ๏ธ Optimize the 3D shape of a physical object From 7ad39d168019760717ef4eb2e7352ca270672248 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:39:38 +0100 Subject: [PATCH 44/51] reword Co-authored-by: AdrianSosic --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ab3d389b66..2400f6b12c 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,8 @@ exploitation of parameter space regions known to lead to good outcomes and exploration of unknown regions. BayBE provides a **general-purpose toolbox** for Bayesian Design of Experiments, -focusing on making this procedure easily-accessible for real-world experiments. +focusing on making this procedure easily accessible for real-world experiments. + ## ๐Ÿ”‹ Batteries Included BayBE offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. From 451c99be9e186f4d45efdeb11e690376e900e2f6 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:39:05 +0100 Subject: [PATCH 45/51] reweord --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2400f6b12c..a77e9d987b 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Example use cases: - ๐Ÿซ– Find tasty espresso machine settings This is achieved via **Bayesian Design of Experiments**, -which is an efficient way for navigating parameter search spaces. +which helps to efficiently navigate parameter search spaces. It balances exploitation of parameter space regions known to lead to good outcomes and exploration of unknown regions. From 7bdd5a53e17bd6fceaf3cc47e060071b0eea985d Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 16:02:53 +0100 Subject: [PATCH 46/51] Reword features --- README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index a77e9d987b..2d5dc18856 100644 --- a/README.md +++ b/README.md @@ -59,21 +59,23 @@ focusing on making this procedure easily accessible for real-world experiments. BayBE offers a range of โœจ**built‑in features**โœจ crucial for real-world use cases. The following provides a non-comprehensive overview: -- ๐Ÿ“š Leverage **domain knowledge**. - - ๐ŸŽจ Encode categorical data to capture relationships between categories. BayBE also provides built-in chemical encodings. - - ๐Ÿ› ๏ธ Option to build-in mechanistic process understanding via custom surrogate models. -- ๐Ÿ›๏ธ Leverage **historic data** to accelerate optimization via transfer learning. -- ๐ŸŒ€ **Flexible** definition of target outcomes, parameter search spaces and optimization strategies: - - ๐ŸŽฏ Option to use numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized or matched to a specific value. - - ๐Ÿ‘ฅ๐Ÿ‘ฅ Multiple targets can be optimized at once (e.g., via Pareto optimization). - - ๐ŸŽญ Both continuous and discrete parameters can be used within a single search space. - - ๐Ÿ”ข The maximal number of mixture components can be defined via cardinality constraints. - - โš–๏ธ Different optimization strategies can be selected to balance exploration and exploitation of the search space, including bandit models and active learning. -- ๐ŸŒŽ Run campaigns **asynchronously** with pending experiments and partial measurements. -- ๐Ÿ” **Insights**: Easily analyze feature importance and model behavior. -- ๐Ÿ“ˆ Utilities for **benchmarking**, such as backtesting and simulations. -- ๐Ÿ“ **High-quality code base** with comprehensive tests and typing. -- ๐Ÿ”„ Code is designed with **database storage and API** wrappers in mind via serialization. +- ๐Ÿ“š Leverage **domain knowledge**: + - ๐ŸŽจ Capture relationships between categories by encoding categorical data. BayBE also provides built-in chemical encodings. + - ๐Ÿ› ๏ธ Build in mechanistic process understanding via custom surrogate models. +- ๐Ÿ›๏ธ Leverage **historic data** from similar campaigns to accelerate optimization via transfer learning. +- ๐ŸŒ€ **Flexibly** define target outcomes, parameter search spaces and optimization strategies: + - ๐ŸŽฏ Choose between numerical targets (e.g., experimental outcome values) or binary targets (e.g., good/bad classification of experimental results). Targets can be minimized, maximized or matched to a specific value. + - ๐Ÿ‘ฅ๐Ÿ‘ฅ Optimized multiple targets at once (e.g., via Pareto optimization or desirability scalarization). + - ๐ŸŽญ Use both continuous and discrete parameters can within a single search space. + - ๐Ÿ”ข Define a maximal number of mixture components via cardinality constraints. + - โš–๏ธ Choose between different optimization strategies to balance exploration and exploitation of the search space: + - ๐ŸŒ Gain the understanding of the whole search space via active learning. + - ๐ŸŽฐ Maximize total gain across a sequence of actions via bandit models. +- ๐ŸŒ Run campaigns **asynchronously** with pending experiments and partial measurements. +- ๐Ÿ” Gain **insights** about the optimization campaigns by analyzing feature importance and model behavior. +- ๐Ÿ“ˆ Conduct **benchmarks** to select between different Bayesian optimization settings via backtesting. +- ๐Ÿ”„ Connect BayBE with **database storage and API wrappers** using the serialization functionality. +- ๐Ÿ“ Rely on **high-quality code base** with comprehensive tests and typing. ## โšก Quick Start From 1d13bf084f597c9b2413854f3b33113ab2fa3b0a Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Wed, 5 Nov 2025 16:06:04 +0100 Subject: [PATCH 47/51] Reword user to you --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d5dc18856..8475616353 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ The following provides a non-comprehensive overview: ## โšก Quick Start To perform Bayesian Design of Experiments with BayBE, -the users must first specify the **parameter search space** and **objective** to be optimized. +you should first specify the **parameter search space** and **objective** to be optimized. Based on this information and any **available data** about outcomes of specific parameter settings, BayBE will **recommend the next set of parameter combinations** to be **measured**. To inform the next recommendation cycle, the newly generated measurements can be added to BayBE. From b2d38c9d5a0e97e71d0314f1b4d1cddbcfd431e2 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 6 Nov 2025 13:53:10 +0100 Subject: [PATCH 48/51] Unify wording of setting (BO method) and configuration (chosen parameter values) --- README.md | 29 ++++++++++++++--------------- docs/faq.md | 4 ++-- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 8475616353..5e15ce0a4b 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ # BayBE โ€” A Bayesian Back End for Design of Experiments -The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find **good parameter settings** +The **Bay**esian **B**ack **E**nd (**BayBE**) helps to find **good parameter configurations** within complex parameter search spaces.
@@ -82,8 +82,8 @@ The following provides a non-comprehensive overview: To perform Bayesian Design of Experiments with BayBE, you should first specify the **parameter search space** and **objective** to be optimized. -Based on this information and any **available data** about outcomes of specific parameter settings, -BayBE will **recommend the next set of parameter combinations** to be **measured**. +Based on this information and any **available data** about outcomes of specific parameter configurations, +BayBE will **recommend the next set of parameter configurations** to be **measured**. To inform the next recommendation cycle, the newly generated measurements can be added to BayBE.
@@ -99,7 +99,7 @@ to help you with the design setup. Below we show a simple optimization procedure, starting with the design step and subsequently performing the recommendation loop. -The provided example aims to maximize the yield of a chemical reaction by adjusting its parameters +The provided example aims to maximize the yield of a chemical reaction by adjusting its parameter configurations (also known as reaction conditions). First, install BayBE into your Python environment: @@ -123,8 +123,7 @@ objective = SingleTargetObjective(target=target) ``` In cases where we are confronted with multiple (potentially conflicting) targets (e.g., yield vs cost), -the `ParetoObjective` or `DesirabilityObjective` can be used instead. -These allow to define additional settings, such as how the targets should be balanced. +the `ParetoObjective` or `DesirabilityObjective` can be used to define how the targets should be balanced. For more details, see the [objectives section](https://emdgroup.github.io/baybe/stable/userguide/objectives.html) of the user guide. @@ -191,8 +190,8 @@ and alternative ways of construction. ### Optional: Defining the Optimization Strategy -As an optional step, we can specify details on how the optimization of the experimental settings should be -performed. If omitted, BayBE will choose a default setting. +As an optional step, we can specify details on how the optimization of the experimental configurations should be +performed. If omitted, BayBE will choose a default Bayesian optimization setting. For our example, we combine two recommenders via a so-called meta recommender named `TwoPhaseMetaRecommender`: @@ -215,13 +214,13 @@ recommender = TwoPhaseMetaRecommender( ``` For more details on the different recommenders, their underlying algorithmic -details and their configuration settings, see the +details and how their settings can be adjusted, see the [recommenders section](https://emdgroup.github.io/baybe/stable/userguide/recommenders.html) of the user guide. ### The Optimization Loop -We can now construct a `Campaign` that performs the Bayesian optimization of the experimental settings: +We can now construct a `Campaign` that performs the Bayesian optimization of the experimental configurations: ```python from baybe import Campaign @@ -233,7 +232,7 @@ With this object at hand, we can start our optimization cycle. In particular: * The campaign can `recommend` new experiments. -* We can `add_measurements` of target values for the measured parameter settings +* We can `add_measurements` of target values for the measured parameter configurations to the campaign's database. Note that these two steps can be performed in any order. @@ -241,11 +240,11 @@ In particular, available measurements can be submitted at any time and also seve times before querying the next recommendations. ```python -df = campaign.recommend(batch_size=3) # Recommend three experimental settings to test +df = campaign.recommend(batch_size=3) # Recommend three experimental configurations to test print(df) ``` -The below table shows the three parameter setting for which BayBE recommended to +The below table shows the three parameter configurations for which BayBE recommended to measure the reaction yield. Note that the specific recommendations will depend on both the data @@ -262,14 +261,14 @@ After having conducted the recommended experiments, we can add the newly measure target information to the campaign: ```python -df["Yield"] = [79.8, 54.1, 59.4] # Measured yields for the three recommended parameter settings +df["Yield"] = [79.8, 54.1, 59.4] # Measured yields for the three recommended parameter configurations campaign.add_measurements(df) ``` With the newly provided data, BayBE can produce a refined recommendation for the next iteration. This loop typically continues until a desired target value is achieved in the experiment. -### Inspect the Progress of the Experimental Setting Optimization +### Inspect the Progress of the Experimental Configuration Optimization The below plot shows progression of a campaign that optimized direct arylation reaction by tuning the solvent, base and ligand diff --git a/docs/faq.md b/docs/faq.md index bcc2d007c3..17da3f1733 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -84,7 +84,7 @@ discrete parameters or provide custom encodings. ```{dropdown} Is no prior data available and the experiments should be done in batches? - > Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter settings to be tested. + > Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter configurations to be tested. ``` ```{dropdown} Is additional data from historic or other partially-related experiments available? @@ -92,7 +92,7 @@ discrete parameters or provide custom encodings. > Use [transfer learning](userguide/transfer_learning.html). ``` -```{dropdown} Will the outcome measurements of different parameter setting become available at different times? +```{dropdown} Will the outcome measurements of different parameter configurations become available at different times? > Use [asynchronous workflows](userguide/async.html). ``` From e81c2c2f0c7b9f05332b52883600a375645dd889 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 6 Nov 2025 13:56:04 +0100 Subject: [PATCH 49/51] Fix rendering style --- docs/faq.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 17da3f1733..59ada9ca44 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -69,7 +69,7 @@ rather than from the product of all possible parameter combinations. ```{dropdown} Are some parameters non-numeric or allow only discrete numbers? - > Use [discrete](userguide/parameters.html#discrete-parameters) +Use [discrete](userguide/parameters.html#discrete-parameters) rather than [continuous](userguide/parameters.html#continuous-parameters) parameters. ``` @@ -84,24 +84,24 @@ discrete parameters or provide custom encodings. ```{dropdown} Is no prior data available and the experiments should be done in batches? - > Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter configurations to be tested. +Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter configurations to be tested. ``` ```{dropdown} Is additional data from historic or other partially-related experiments available? - > Use [transfer learning](userguide/transfer_learning.html). +Use [transfer learning](userguide/transfer_learning.html). ``` ```{dropdown} Will the outcome measurements of different parameter configurations become available at different times? - > Use [asynchronous workflows](userguide/async.html). +Use [asynchronous workflows](userguide/async.html). ``` ### Advanced: Adjust how Recommendations are Prioritized ```{dropdown} Is the aim to reduce the overall uncertainty across different regions of the search space rather than optimize a specific objective? - > Use [active learning](userguide/active_learning.html). +Use [active learning](userguide/active_learning.html). ``` From eb701cfb0558312c7f62300f02bdcba1cd3df9ed Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:06:45 +0100 Subject: [PATCH 50/51] reword --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e15ce0a4b..1dac5eed73 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Example use cases: - ๐Ÿงช Find chemical reaction conditions or process parameters - ๐Ÿฅฃ Create materials, chemical mixtures or formulations with desired properties - โœˆ๏ธ Optimize the 3D shape of a physical object -- ๐Ÿ–ฅ๏ธ Optimize an in silico simulation +- ๐Ÿ–ฅ๏ธ Optimize a virtual simulation - โš™๏ธ Select model hyperparameters - ๐Ÿซ– Find tasty espresso machine settings From 3d2bd0bd2b8068dc829e687a852a32c80047ee75 Mon Sep 17 00:00:00 2001 From: Karin Hrovatin <47607471+Hrovatin@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:11:50 +0100 Subject: [PATCH 51/51] Move setup guide to own section --- README.md | 4 +- docs/faq.md | 82 ----------------------------------- docs/userguide/setup_guide.md | 78 +++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 84 deletions(-) create mode 100644 docs/userguide/setup_guide.md diff --git a/README.md b/README.md index 1dac5eed73..c22e39af4c 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,8 @@ To inform the next recommendation cycle, the newly generated measurements can be From the user perspective, the most important part is the "design" step. If you are new to BayBE, we suggest consulting our -[design checklist](https://emdgroup.github.io/baybe/stable/faq.html) -to help you with the design setup. +[setup checklist](https://emdgroup.github.io/baybe/stable/setup_guide.html) +to help you with the campaign setup. Below we show a simple optimization procedure, starting with the design step and subsequently performing the recommendation loop. diff --git a/docs/faq.md b/docs/faq.md index 59ada9ca44..6e92f27611 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -24,85 +24,3 @@ your campaign, depending on your settings for the {attr}`~baybe.campaign.Campaign.allow_recommending_already_measured` and {attr}`~baybe.campaign.Campaign.allow_recommending_already_recommended` flags. ``` - -## Checklist for Designing BayBE Optimization Campaigns - -This checklist collects **common questions that you need to ask yourself** when designing a BayBE optimization campaign. It also provides documentation references that will help you with the corresponding setup. - -Note that this is not a comprehensive guide of all BayBE's functionalities, but rather a "quick start" meant to help you with the most basic design principles. - -### Defining Targets - -```{dropdown} Should the target value be maximized, minimized, or be matched to a specific value? - -Specify this when -[defining the target](userguide/targets.html#numericaltarget). -``` - -```{dropdown} Should multiple target be optimized simultaneously? - -See how to use -[multi-target objectives](userguide/objectives.html). -``` - -### Defining Parameter Search Space - -```{dropdown} Are only some parameter values of interest/possible? - -See how to exclude some -[parameter values](userguide/getting_recommendations.html#excluding-configurations) -from being recommended, such as by defining -[bounds for continuous parameters](userguide/parameters.html#numericalcontinuousparameter) -or [active values for discrete parameters](userguide/parameters.html#discrete-parameters). -``` - -```{dropdown} Are only some parameter combinations of interest/possible? - -See how to exclude some -parameter combinations from being considered by using -[constraints](userguide/constraints.html) or -[constrained searchspaces](userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). -Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a -[dataframe](userguide/searchspace.html#id3) -rather than from the product of all possible parameter combinations. -``` - -```{dropdown} Are some parameters non-numeric or allow only discrete numbers? - -Use [discrete](userguide/parameters.html#discrete-parameters) -rather than [continuous](userguide/parameters.html#continuous-parameters) parameters. -``` - -```{dropdown} Is it possible to encode discrete parameters based on domain knowledge to capture relationships between categories (e.g., ordered values, molecular fingerprints, model embeddings)? - -See how to -[encode](userguide/parameters.html#discrete-parameters) -discrete parameters or provide custom encodings. -``` - -### Account for Specifics of Data Availability or Data Acquisition Procedure - -```{dropdown} Is no prior data available and the experiments should be done in batches? - -Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter configurations to be tested. -``` - -```{dropdown} Is additional data from historic or other partially-related experiments available? - -Use [transfer learning](userguide/transfer_learning.html). -``` - -```{dropdown} Will the outcome measurements of different parameter configurations become available at different times? - -Use [asynchronous workflows](userguide/async.html). -``` - -### Advanced: Adjust how Recommendations are Prioritized - -```{dropdown} Is the aim to reduce the overall uncertainty across different regions of the search space rather than optimize a specific objective? - -Use [active learning](userguide/active_learning.html). -``` - - - diff --git a/docs/userguide/setup_guide.md b/docs/userguide/setup_guide.md new file mode 100644 index 0000000000..0d29ab2ddb --- /dev/null +++ b/docs/userguide/setup_guide.md @@ -0,0 +1,78 @@ +# Checklist for Designing BayBE Optimization Campaigns + +This checklist collects **common questions that you need to ask yourself** when designing a BayBE optimization campaign. It also provides documentation references that will help you with the corresponding setup. + +Note that this is not a comprehensive guide of all BayBE's functionalities, but rather a "quick start" meant to help you with the most basic design principles. + +## Defining Targets + +```{dropdown} Should the target value be maximized, minimized, or be matched to a specific value? + +Specify this when +[defining the target](userguide/targets.html#numericaltarget). +``` + +```{dropdown} Should multiple target be optimized simultaneously? + +See how to use +[multi-target objectives](userguide/objectives.html). +``` + +## Defining Parameter Search Space + +```{dropdown} Are only some parameter values of interest/possible? + +See how to exclude some +[parameter values](userguide/getting_recommendations.html#excluding-configurations) +from being recommended, such as by defining +[bounds for continuous parameters](userguide/parameters.html#numericalcontinuousparameter) +or [active values for discrete parameters](userguide/parameters.html#discrete-parameters). +``` + +```{dropdown} Are only some parameter combinations of interest/possible? + +See how to exclude some +parameter combinations from being considered by using +[constraints](userguide/constraints.html) or +[constrained searchspaces](userguide/searchspace.html#creating-a-simplex-bound-discrete-subspace). +Alternatively, if the aim is to use only a few specific parameter configurations the search space can be created from a +[dataframe](userguide/searchspace.html#id3) +rather than from the product of all possible parameter combinations. +``` + +```{dropdown} Are some parameters non-numeric or allow only discrete numbers? + +Use [discrete](userguide/parameters.html#discrete-parameters) +rather than [continuous](userguide/parameters.html#continuous-parameters) parameters. +``` + +```{dropdown} Is it possible to encode discrete parameters based on domain knowledge to capture relationships between categories (e.g., ordered values, molecular fingerprints, model embeddings)? + +See how to +[encode](userguide/parameters.html#discrete-parameters) +discrete parameters or provide custom encodings. +``` + +## Account for Specifics of Data Availability or Data Acquisition Procedure + +```{dropdown} Is no prior data available and the experiments should be done in batches? + +Use [clustering](userguide/recommenders.html#clustering-recommenders) or [sampling](userguide/recommenders.html#sampling-recommenders) recommenders to diversify the first batch of parameter configurations to be tested. +``` + +```{dropdown} Is additional data from historic or other partially-related experiments available? + +Use [transfer learning](userguide/transfer_learning.html). +``` + +```{dropdown} Will the outcome measurements of different parameter configurations become available at different times? + +Use [asynchronous workflows](userguide/async.html). +``` + +## Advanced: Adjust how Recommendations are Prioritized + +```{dropdown} Is the aim to reduce the overall uncertainty across different regions of the search space rather than optimize a specific objective? + +Use [active learning](userguide/active_learning.html). +```