fzd: parallelize Python-function model evaluations when calculators>1

[yannrichet-asnr]

Summary

fzd(..., model=<callable>, calculators=N) previously accepted N only for API compatibility: evaluations always ran sequentially, one call at a time, in the calling thread, regardless of its value. This was deliberate (see _run_function_model_design's original docstring): a Python-side ThreadPoolExecutor always dispatches to a worker thread — even with max_workers=1 — which crashes callables that are only safe to invoke from the thread that created them (e.g. an R closure bridged in via reticulate).

This PR makes calculators=N>1 actually parallelize evaluations for an ordinary, thread-safe Python function, while preserving the safe default:

• calculators=1 (the default): unchanged — strictly sequential, one call at a time, in the calling thread, no thread pool at all.
• calculators=N>1: dispatches evaluations to a concurrent.futures.ThreadPoolExecutor with N worker threads, running them concurrently. Only use this for a model function that is safe to call from arbitrary threads.
• If any point raises while evaluated in parallel, the whole batch aborts immediately with an explicit fz.FunctionModelParallelError (a RuntimeError subclass) naming the offending point, the calculators value, and suggesting a retry with calculators=1 — instead of silently downgrading it to a per-point failure like sequential mode does for ordinary model errors. A thread-safety problem can otherwise surface as sporadic, hard-to-diagnose per-point failures, so failing the whole run loudly is safer than continuing with partially-corrupted results.
• calculators must now be a positive int in function-model mode (raises ValueError for calculators <= 0).
• FunctionModelParallelError is exported from the top-level fz package.

Why

fzd is documented/used with calculators=N as if it parallelizes function-model evaluations (see e.g. the BuildingOpt_fz.ipynb notebook in yannrichet/OptimHome), but until now that parameter was silently ignored in that mode. This PR makes the parameter do what users reasonably expect for plain Python functions, without weakening the existing safety guarantee for non-thread-safe callables (still opt-in via calculators=1, the default).

Companion change

Funz/fz.R needs a matching update (see companion PR): now that calculators>1 has a real effect on this side, the R wrapper must unconditionally force calculators=1 when model is an R function (R closures bridged in via reticulate are not safe to call from a worker thread), instead of merely warning that the parameter had no effect.

Testing

• Added tests/test_fzd_function_model_parallel.py: unit tests for _run_function_model_design (sequential-in-calling-thread, parallel-uses-multiple-threads, parallel-error-aborts-with-explicit-error, result-order preserved) plus end-to-end fzd() tests (default calculators=1, calculators>1 parallelizes, calculators<=0 rejected, non-int rejected, parallel error propagates as FunctionModelParallelError).
• Full existing fzd suite still green: tests/test_fzd.py, tests/test_fzd_vector_outputs.py, tests/test_fzd_multiobjective.py, tests/test_fzd_calculator_discovery.py (65 passed).

[Copilot]

Pull request overview

This PR updates fz.fzd(..., model=<callable>, calculators=N) so that Python-function model evaluations can actually run in parallel when calculators > 1, while preserving the safe default behavior (calculators=1 runs sequentially in the calling thread). It also introduces a dedicated exception type to make parallel-evaluation failures explicit and fatal for the whole batch.

Changes:

• Implement parallel execution for function-model designs via ThreadPoolExecutor when calculators > 1, and keep calculators <= 1 strictly sequential in the calling thread.
• Add and export fz.FunctionModelParallelError to surface parallel evaluation failures as fatal (rather than per-point failures).
• Add a new test module covering sequential semantics, parallel semantics, error propagation, ordering, and calculators validation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
fz/core.py	Implements parallel function-model evaluation, adds FunctionModelParallelError, tightens calculators validation, and updates fzd docstrings/behavior.
fz/__init__.py	Exports FunctionModelParallelError at the top-level fz package.
tests/test_fzd_function_model_parallel.py	Adds unit + end-to-end tests for function-model parallelization behavior and validation.

Suppressed comments (1)

fz/core.py:2282

• The calculators validation treats bools as ints (since bool is a subclass of int), so callers can pass calculators=True/False and it will be accepted (True behaves like 1, False triggers the “< 1” ValueError). Given calculators is a user-facing API parameter, it’s better to reject bool explicitly to avoid surprising behavior.

            if calculators is None:
                function_workers = 1
            elif isinstance(calculators, int):
                if calculators < 1:
                    raise ValueError(
                        f"calculators must be a positive int when model is a Python callable, got {calculators}"
                    )
                function_workers = calculators
            else:
                raise TypeError("calculators must be an int (number of parallel calls) when model is a Python callable")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.