Add Batch Sampler: coordinate parallel workers into jointly-selected batches by sign-of-fourier · Pull Request #376 · optuna/optunahub-registry

sign-of-fourier · 2026-05-20T14:26:00Z

Summary

Adds BatchSampler, an Optuna BaseSampler that solves the coordination problem when running study.optimize(n_jobs=q).
With default samplers, concurrent workers each see the same incomplete trial history and suggest independently, producing near-duplicate configurations. BatchSampler uses a shared lock so one worker calls a user-supplied suggest_fn to obtain q suggestions jointly, then hands them out one at a time to the waiting workers.
suggest_fn is a plain Python callable — the sampler makes no HTTP calls and has no dependency on any external service. Users can plug in BoTorch, a local GP, or any batch acquisition function.
The example uses fantasize_suggest from the quantecarlo package (PyPI), a self-contained sequential kriging function that requires no external service.

Test plan

ruff check package/samplers/batch_sampler/ passes
mypy package/samplers/batch_sampler/ --ignore-missing-imports passes
pip install quantecarlo && python package/samplers/batch_sampler/example.py runs to completion

Adds package/samplers/q_ei_sampler — a batch Bayesian optimisation sampler that delegates GP fitting and q-EI candidate scoring to a remote HTTP endpoint, with random-search fallback during startup. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

y0z · 2026-06-04T09:30:42Z

@sawa3030 Could you review this PR?

sawa3030

Thank you for the PR! I've left a few comments. PTAL!

sawa3030 · 2026-06-09T06:31:56Z

+                return {}
+
+            X = [[float(t.params[n]) for n in param_names] for t in usable]
+            # Negate values: q-EI maximises, Optuna minimises.


As you showed in the example, Optuna can define the optimization direction explicitly. For example, the user can make Optuna maximize the objective by writing:

study = optuna.create_study(direction="maximize", sampler=sampler)

In addition, I believe the optimization direction of the remote optimizer depends on its implementer or user. Therefore, it is not necessarily true that remote optimizer always maximizes the objective.
How about leaving it to the user to align the optimization directions between the remote optimizer and Optuna?

Got it. Don't negate it and the user will align. If neither direction nor directions is chosen, then the default is minimize. So, here just leave it out because this part doesn't depend on a particular backend. It will follow expected, normal Optuna behavior.

sawa3030 · 2026-06-09T06:48:57Z

@@ -0,0 +1,145 @@
+---
+author: Mark Shipman
+title: Remote GP q-EI Sampler


I believe this sampler could also be useful for optimization methods other than Bayesian optimization, even though it certainly works well in the Bayesian optimization setting.
If this understanding is correct, would it make sense to make the explanations and naming a bit more general so that the sampler can cover a broader range of optimizers?

Makes sense. Something like "Remote Sampler", but then for the example, describe q-EI as an example.

sawa3030 · 2026-06-11T05:50:34Z

+### Backend endpoint
+
+You must supply an `api_url` that implements the contract above. Two options:
+
+**Use the hosted endpoint** (no setup required):
+
+```
+https://markshipman4273--bo-gp-service-gp-suggest.modal.run
+```
+
+This is a publicly available Modal deployment. Pass it directly as `api_url`.
+
+**Deploy your own** using the open-source backend at
+[sign-of-fourier/quantecarlo](https://github.com/sign-of-fourier/quantecarlo),
+or implement the request/response contract on any HTTP server.


Could you please remove this information from the documentation?

As we do not officially support calling third-party APIs in this context, I think it may be better not to include this example here.

Thank you very much for your understanding.

Yes, I will remove. I'll change the language to explain q-EI as an example as to why one would need to use a remote source for this computation and describe what it would do, but I'll leave out any actual link.

sign-of-fourier · 2026-06-11T12:37:45Z

Thank you all for taking the time to look at this PR. I will make these changes by next week.

- Rename package directory and class (qEISampler → BatchSampler) - Replace api_url with suggest_fn: Callable[[X, y, search_space, q], candidates] - Remove all HTTP code, negation, and debug mode — sampler is backend-agnostic - Update README: general framing, callable contract, quantecarlo example - Update example to use fantasize_suggest from quantecarlo (local GP, no external service) - Bump requirements to optuna>=4.0.0

sign-of-fourier · 2026-06-13T16:59:39Z

Thanks everyone for your feedback. Hopefully, I've addressed everything

Naming convention changed so that the package is more general. The main purpose is to use try, ask to suggest batches when n_thread > 1 rather than run suggestions independently. The actual acquisition is separate. I can create a PR to include that logic as well but I think it should be it's own module. A module to do this logic already exists elsewhere.
The negative was removed. I think that was there because I was doing a maximization task in the test and the default is to minimize.
Any reference to an API is removed. As mentioned in point 1, there is already logic to do the GPR and batch acquisition elsewhere. This module has an option to not use any 3rd party API or endpoint. I changed the example so that there is no 3rd party API call.

Add Remote GP q-EI Sampler

5b0469a

Adds package/samplers/q_ei_sampler — a batch Bayesian optimisation sampler that delegates GP fitting and q-EI candidate scoring to a remote HTTP endpoint, with random-search fallback during startup. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

y0z assigned sawa3030 Jun 4, 2026

sawa3030 reviewed Jun 9, 2026

View reviewed changes

sawa3030 reviewed Jun 11, 2026

View reviewed changes

sign-of-fourier changed the title ~~Add Remote GP q-EI Sampler~~ Add Batch Sampler: coordinate parallel workers into jointly-selected batches Jun 13, 2026

Fix ruff-format and mdformat pre-commit failures

9c4f97a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Batch Sampler: coordinate parallel workers into jointly-selected batches#376

Add Batch Sampler: coordinate parallel workers into jointly-selected batches#376
sign-of-fourier wants to merge 3 commits into
optuna:mainfrom
sign-of-fourier:add-q-ei-sampler

sign-of-fourier commented May 20, 2026 •

edited

Loading

Uh oh!

y0z commented Jun 4, 2026

Uh oh!

sawa3030 left a comment

Uh oh!

sawa3030 Jun 9, 2026

Uh oh!

sign-of-fourier Jun 11, 2026

Uh oh!

sawa3030 Jun 9, 2026

Uh oh!

sign-of-fourier Jun 11, 2026

Uh oh!

sawa3030 Jun 11, 2026

Uh oh!

sign-of-fourier Jun 11, 2026

Uh oh!

sign-of-fourier commented Jun 11, 2026

Uh oh!

sign-of-fourier commented Jun 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

sign-of-fourier commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

y0z commented Jun 4, 2026

Uh oh!

sawa3030 left a comment

Choose a reason for hiding this comment

Uh oh!

sawa3030 Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

sign-of-fourier Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

sawa3030 Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

sign-of-fourier Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

sawa3030 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

sign-of-fourier Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

sign-of-fourier commented Jun 11, 2026

Uh oh!

sign-of-fourier commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sign-of-fourier commented May 20, 2026 •

edited

Loading

sign-of-fourier commented Jun 13, 2026 •

edited

Loading