better-optimize 0.3__tar.gz → 0.3.2__tar.gz

{better_optimize-0.3 → better_optimize-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.3
+Version: 0.3.2
 Summary: A drop-in replacement for scipy optimize functions with quality of life improvements
 License: MIT License
 Project-URL: Homepage, https://github.com/jessegrabowski/better_optimize
@@ -149,6 +149,54 @@ Many sub-computations are repeated between the objective, gradient, and hessian
 fused value_and_grad function, but `better_optimize` also lets you pass a triple-fused value_grad_and_hess function.
 This avoids redundant computation and speeds up the optimization process.
 
+### Parallel Optimization from Multiple Starting Points
+
+Real-world objectives often have multiple local minima. A common workaround is to throw many random starting points at
+the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
+
+```python
+from better_optimize import minimize, multi_optimize
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+result = multi_optimize(
+    solver=minimize,
+    solver_kwargs=dict(f=rosenbrock, method="L-BFGS-B", tol=1e-10),
+    x0=np.zeros(5),
+    n_runs=16,
+    init_strategy="uniform",
+    bounds=(-5, 5),
+    backend="loky",
+    n_jobs=-1,
+    seed=42,
+    progressbar=True,
+)
+
+print(result.best)       # Best OptimizeResult
+print(result.x_best)     # Best parameter vector
+print(result.fun_best)   # Best objective value
+result.summary()          # Rich table of all runs, ranked
+```
+
+`multi_optimize` works with **any** solver that follows the `(x0, **kwargs) → OptimizeResult` signature — that includes
+`minimize`, `root`, `basinhopping`, or your own custom wrapper. It just calls `solver(x0=x0_i, **solver_kwargs)` for
+each starting point; it never inspects the solver internals.
+
+A few highlights:
+
+- **Initialization strategies** — `"uniform"`, `"normal"`, `"sobol"`, `"lhs"`, or pass your own callable. Bounded
+  strategies (`uniform`, `sobol`, `lhs`) require a `bounds` argument; `"normal"` perturbs around `x0` with a
+  configurable `init_scale`. Or just pass an explicit `list[np.ndarray]` as `x0` and skip the generation entirely.
+- **Parallel backends** — `"sequential"` (for debugging), `"loky"` (CPU-bound work, default), or `"threading"`
+  (GIL-releasing code). Under the hood this is `joblib`, so the usual `n_jobs=-1` convention works.
+- **BLAS thread control** — When many workers each spawn a full BLAS/OpenMP thread pool, you get noisy-neighbor
+  over-subscription. The `blas_cores` argument (default `"auto"`) caps the total thread budget so workers don't
+  fight over the same cores.
+
+The returned `MultiStartResult` gives you `best`, `top_k(k)`, `ranked()`, `success_rate`, a `summary()` table, and
+`to_dataframe()` for further analysis.
+
 
 ## Contributing
 

{better_optimize-0.3 → better_optimize-0.3.2}/README.md

@@ -117,6 +117,54 @@ Many sub-computations are repeated between the objective, gradient, and hessian
 fused value_and_grad function, but `better_optimize` also lets you pass a triple-fused value_grad_and_hess function.
 This avoids redundant computation and speeds up the optimization process.
 
+### Parallel Optimization from Multiple Starting Points
+
+Real-world objectives often have multiple local minima. A common workaround is to throw many random starting points at
+the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
+
+```python
+from better_optimize import minimize, multi_optimize
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+result = multi_optimize(
+    solver=minimize,
+    solver_kwargs=dict(f=rosenbrock, method="L-BFGS-B", tol=1e-10),
+    x0=np.zeros(5),
+    n_runs=16,
+    init_strategy="uniform",
+    bounds=(-5, 5),
+    backend="loky",
+    n_jobs=-1,
+    seed=42,
+    progressbar=True,
+)
+
+print(result.best)       # Best OptimizeResult
+print(result.x_best)     # Best parameter vector
+print(result.fun_best)   # Best objective value
+result.summary()          # Rich table of all runs, ranked
+```
+
+`multi_optimize` works with **any** solver that follows the `(x0, **kwargs) → OptimizeResult` signature — that includes
+`minimize`, `root`, `basinhopping`, or your own custom wrapper. It just calls `solver(x0=x0_i, **solver_kwargs)` for
+each starting point; it never inspects the solver internals.
+
+A few highlights:
+
+- **Initialization strategies** — `"uniform"`, `"normal"`, `"sobol"`, `"lhs"`, or pass your own callable. Bounded
+  strategies (`uniform`, `sobol`, `lhs`) require a `bounds` argument; `"normal"` perturbs around `x0` with a
+  configurable `init_scale`. Or just pass an explicit `list[np.ndarray]` as `x0` and skip the generation entirely.
+- **Parallel backends** — `"sequential"` (for debugging), `"loky"` (CPU-bound work, default), or `"threading"`
+  (GIL-releasing code). Under the hood this is `joblib`, so the usual `n_jobs=-1` convention works.
+- **BLAS thread control** — When many workers each spawn a full BLAS/OpenMP thread pool, you get noisy-neighbor
+  over-subscription. The `blas_cores` argument (default `"auto"`) caps the total thread budget so workers don't
+  fight over the same cores.
+
+The returned `MultiStartResult` gives you `best`, `top_k(k)`, `ranked()`, `success_rate`, a `summary()` table, and
+`to_dataframe()` for further analysis.
+
 
 ## Contributing
 

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize/__init__.py

@@ -3,6 +3,7 @@ import logging
 from better_optimize._version import get_versions
 from better_optimize.basinhopping import basinhopping
 from better_optimize.minimize import minimize
+from better_optimize.multi_optimize import multi_optimize
 from better_optimize.root import root
 
 _log = logging.getLogger(__name__)
@@ -15,4 +16,4 @@ if not logging.root.handlers:
 
 
 __version__ = get_versions()["version"]
-__all__ = ["minimize", "root", "basinhopping", "MultiStart", "MultiStartResult"]
+__all__ = ["minimize", "root", "basinhopping", "multi_optimize"]

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-03-19T20:00:42+0100",
+ "date": "2026-03-20T19:57:42+0100",
  "dirty": false,
  "error": null,
- "full-revisionid": "7c17be556adeb26794fee1e150f9b149cfa3d95c",
- "version": "0.3"
+ "full-revisionid": "2c8f4f7afbc2b54fa1e8aa8827b4be15e6ea87a9",
+ "version": "0.3.2"
 }
 '''  # END VERSION_JSON
 

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize/basinhopping.py

@@ -1,3 +1,5 @@
+import sys
+
 from collections.abc import Callable, Sequence
 
 import numpy as np
@@ -64,7 +66,7 @@ def initialize_progress_bar(progressbar, use_jac=True, use_hess=False):
         *columns,
         expand=False,
         disable=not progressbar,
-        console=Console(width=CONSOLE_WIDTH),
+        console=Console(file=sys.stderr, width=CONSOLE_WIDTH),
         transient=True,
     )
 

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize/constants.py

@@ -31,7 +31,7 @@ root_method = Literal[
 ]
 
 TOLERANCES = ["xtol", "ftol", "gtol", "fatol", "xatol"]
-CONSOLE_WIDTH = 120
+CONSOLE_WIDTH = 100
 
 MINIMIZE_MODE_KWARGS = {
     "nelder-mead": {

better_optimize-0.3/better_optimize/multistart.py → better_optimize-0.3.2/better_optimize/multi_optimize.py

@@ -2,6 +2,7 @@ import contextlib
 import logging
 import multiprocessing as mp
 import pickle
+import sys
 import threading
 
 from collections.abc import Callable
@@ -12,14 +13,15 @@ import numpy as np
 import pandas as pd
 
 from rich.console import Console
-from rich.progress import BarColumn, MofNCompleteColumn, TaskID, TextColumn, TimeElapsedColumn
-from rich.table import Column, Table
+from rich.progress import TaskID
+from rich.table import Table
 from scipy.optimize import OptimizeResult
 from scipy.stats import qmc
 from threadpoolctl import threadpool_limits
 
-from better_optimize.constants import CONSOLE_WIDTH
+from better_optimize.constants import MINIMIZE_MODE_KWARGS, ROOT_MODE_KWARGS
 from better_optimize.utilities import ToggleableProgress
+from better_optimize.wrapper import build_progress_bar
 
 _log = logging.getLogger(__name__)
 
@@ -175,8 +177,22 @@ def _run_single(
         if blas_cores_per_worker is not None
         else contextlib.nullcontext()
     )
-    with limiter:
-        result = solver(x0=x0, progressbar=progress, progress_task=task_id, **solver_kwargs)
+    try:
+        with limiter:
+            result = solver(x0=x0, progressbar=progress, progress_task=task_id, **solver_kwargs)
+    except Exception as exc:
+        _log.warning(
+            "Run %d failed with %s: %s",
+            run_index,
+            type(exc).__name__,
+            exc,
+        )
+        result = OptimizeResult(
+            x=x0,
+            fun=np.inf,
+            success=False,
+            message=f"Solver raised {type(exc).__name__}: {exc}",
+        )
 
     result.run_index = run_index
     result.x0 = x0
@@ -248,7 +264,7 @@ class MultiStartResult:
 
         for rank, res in enumerate(display, 1):
             table.add_row(*self._format_result_row(rank, res))
-        Console().print(table)
+        Console(file=sys.stderr).print(table)
 
     def _result_to_dict(self, rank: int, res: OptimizeResult) -> dict:
         """Convert a single ``OptimizeResult`` into a flat dict for DataFrame export."""
@@ -268,41 +284,8 @@ class MultiStartResult:
         )
 
 
-class MultiStart:
-    """Run a solver from many starting points and collect the results.
-
-    Parameters
-    ----------
-    solver
-        Any callable with signature ``(x0, **kwargs) → OptimizeResult``.
-    x0
-        A single starting point (used as center for ``init_strategy``) or an explicit
-        list of starting points (in which case ``n_runs`` and ``init_strategy`` are ignored).
-    solver_kwargs
-        Forwarded verbatim to ``solver`` on every call.
-    sort_key
-        Function mapping an ``OptimizeResult`` to a float used for ranking.
-    n_runs
-        Number of random restarts.  Ignored when ``x0`` is a list.
-    init_strategy
-        How to generate starting points from ``x0``.
-    bounds
-        ``(low, high)`` arrays or scalars, used by bounded init strategies.
-    init_scale
-        Standard deviation for ``"normal"`` init strategy.
-    backend
-        ``"sequential"``, ``"loky"``, or ``"threading"``.
-    n_jobs
-        Number of parallel workers (``-1`` = all cores).
-    seed
-        Random seed for reproducible starting points.
-    progressbar
-        Whether to display per-run progress bars.
-    mp_ctx
-        Explicit ``multiprocessing`` context (``spawn`` / ``fork`` / ``forkserver``).
-    blas_cores
-        Total BLAS/OpenMP thread budget.  ``"auto"`` = ``n_jobs``, ``None`` = unlimited.
-    """
+class _MultiStart:
+    """Implementation behind :func:`multistart`. Not part of the public API."""
 
     def __init__(
         self,
@@ -384,7 +367,8 @@ class MultiStart:
         progress = self._build_progress()
         task_ids = self._register_tasks(progress)
 
-        queue: mp.Queue = mp.Queue()
+        manager = mp.Manager()
+        queue = manager.Queue()
         stop = threading.Event()
         listener = threading.Thread(
             target=_drain_progress_queue,
@@ -394,20 +378,23 @@ class MultiStart:
 
         with blas_config.limiter(), progress:
             listener.start()
-            results = Parallel(n_jobs=self._n_jobs, backend=self._backend)(
-                delayed(_run_single)(
-                    run_index=i,
-                    x0=x0_i,
-                    solver=self._solver,
-                    solver_kwargs=self._solver_kwargs,
-                    progress=ProgressProxy(queue, task_id),
-                    task_id=task_id,
-                    blas_cores_per_worker=blas_config.per_worker,
+            try:
+                results = Parallel(n_jobs=self._n_jobs, backend=self._backend)(
+                    delayed(_run_single)(
+                        run_index=i,
+                        x0=x0_i,
+                        solver=self._solver,
+                        solver_kwargs=self._solver_kwargs,
+                        progress=ProgressProxy(queue, task_id),
+                        task_id=task_id,
+                        blas_cores_per_worker=blas_config.per_worker,
+                    )
+                    for i, (x0_i, task_id) in enumerate(zip(self._starting_points, task_ids))
                 )
-                for i, (x0_i, task_id) in enumerate(zip(self._starting_points, task_ids))
-            )
-            stop.set()
-            listener.join(timeout=1.0)
+            finally:
+                stop.set()
+                listener.join(timeout=1.0)
+                manager.shutdown()
 
         return MultiStartResult(results=results, sort_key=self._sort_key)
 
@@ -422,31 +409,123 @@ class MultiStart:
         name = getattr(self._solver, "__name__", "")
         return self._SOLVER_LABELS.get(name, name.title() or "Optimizing")
 
+    @property
+    def _is_root(self) -> bool:
+        return getattr(self._solver, "__name__", "") == "root"
+
     def _build_progress(self) -> ToggleableProgress:
-        columns = [
-            BarColumn(bar_width=None, table_column=Column(self._task_description, ratio=2)),
-            TimeElapsedColumn(table_column=Column("Elapsed", ratio=1)),
-            MofNCompleteColumn(table_column=Column("Iteration")),
-            TextColumn("{task.fields[f_value]:0.8f}", table_column=Column("Objective", ratio=1)),
-            TextColumn("{task.fields[grad_norm]:0.8f}", table_column=Column("||grad||", ratio=1)),
-        ]
-        return ToggleableProgress(
-            *columns,
-            expand=False,
-            disable=not self._progressbar,
-            console=Console(width=CONSOLE_WIDTH),
+        method = self._solver_kwargs.get("method", "")
+
+        if self._is_root:
+            mode_info = ROOT_MODE_KWARGS.get(method, {})
+            use_jac = mode_info.get("uses_jac", False) or "jac" in self._solver_kwargs
+            use_hess = False
+        else:
+            mode_info = MINIMIZE_MODE_KWARGS.get(method, {})
+            use_jac = mode_info.get("uses_grad", False) or "jac" in self._solver_kwargs
+            use_hess = (
+                mode_info.get("uses_hess", False)
+                or "hess" in self._solver_kwargs
+                or "hessp" in self._solver_kwargs
+            )
+
+        return build_progress_bar(
+            description=self._task_description,
+            progressbar=self._progressbar,
+            root=self._is_root,
+            use_jac=use_jac,
+            use_hess=use_hess,
         )
 
     def _register_tasks(self, progress: ToggleableProgress) -> list[TaskID | None]:
+        # Include all possible fields so columns never hit a missing key.
+        # Unused fields (e.g. hess_norm when no hess column) are silently ignored.
         return [
             progress.add_task(
                 description=self._task_description,
                 total=None,
                 f_value=0.0,
                 grad_norm=0.0,
+                hess_norm=0.0,
             )
             for _ in self._starting_points
         ]
 
 
-__all__ = ["MultiStart", "MultiStartResult", "generate_starts"]
+def multi_optimize(
+    solver: Callable[..., OptimizeResult],
+    x0: np.ndarray | list[np.ndarray],
+    solver_kwargs: dict | None = None,
+    sort_key: Callable[[OptimizeResult], float] | None = None,
+    n_runs: int = 16,
+    init_strategy: InitStrategy = "normal",
+    bounds: tuple[np.ndarray, np.ndarray] | None = None,
+    init_scale: float = 1.0,
+    backend: Literal["sequential", "loky", "threading"] = "loky",
+    n_jobs: int = -1,
+    seed: int | None = None,
+    progressbar: bool = True,
+    mp_ctx: mp.context.BaseContext | None = None,
+    blas_cores: int | None | Literal["auto"] = "auto",
+) -> MultiStartResult:
+    """
+    Run a solver from many starting points and return the collected results.
+
+    Parameters
+    ----------
+    solver: Callable
+        Any solver with signature (x0, **kwargs) -> OptimizeResult, such as minimize or root
+    x0: np.ndarray or list of np.ndarray
+        A single starting point used as the center for init_strategy, or an explicit list of
+        starting points. When a list is provided, n_runs and init_strategy are ignored.
+    solver_kwargs: dict, optional
+        Keyword arguments forwarded verbatim to solver on every call
+    sort_key: Callable, optional
+        Function mapping an OptimizeResult to a float used for ranking. Defaults to
+        lambda res: res.fun, which ranks results by their optimized objective value.
+    n_runs: int
+        Number of random restarts. Ignored when x0 is a list.
+    init_strategy: str or Callable
+        How to generate starting points from x0. One of "uniform", "normal", "sobol", "lhs",
+        or a callable with signature (x0, n_runs, rng) → list of arrays.
+    bounds: tuple, optional
+        (low, high) arrays or scalars, required by bounded init strategies
+    init_scale: float
+        Standard deviation for the "normal" init strategy
+    backend: str
+        Execution backend. One of "sequential", "loky", or "threading".
+    n_jobs: int
+        Number of parallel workers. -1 means all cores.
+    seed: int, optional
+        Random seed for reproducible starting points
+    progressbar: bool
+        Whether to display per-run progress bars
+    mp_ctx: multiprocessing context, optional
+        Explicit multiprocessing context (spawn, fork, or forkserver)
+    blas_cores: int, str, or None
+        Total BLAS/OpenMP thread budget. "auto" splits evenly across workers, None is unlimited.
+
+    Returns
+    -------
+    result: MultiStartResult
+        Collected results with ranking, summary, and export utilities
+    """
+    return _MultiStart(
+        solver=solver,
+        x0=x0,
+        solver_kwargs=solver_kwargs,
+        sort_key=sort_key,
+        n_runs=n_runs,
+        init_strategy=init_strategy,
+        bounds=bounds,
+        init_scale=init_scale,
+        backend=backend,
+        n_jobs=n_jobs,
+        seed=seed,
+        progressbar=progressbar,
+        mp_ctx=mp_ctx,
+        blas_cores=blas_cores,
+    ).run()
+
+
+__all__ = ["multi_optimize", "MultiStartResult", "generate_starts"]

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize/wrapper.py

@@ -1,4 +1,5 @@
 import logging
+import sys
 
 from collections.abc import Callable
 from functools import partial
@@ -24,6 +25,47 @@ from better_optimize.utilities import ToggleableProgress
 _log = logging.getLogger(__name__)
 
 
+def build_progress_bar(
+    *,
+    description: str = "Minimizing",
+    progressbar: bool = True,
+    root: bool = False,
+    use_jac: bool = False,
+    use_hess: bool = False,
+) -> ToggleableProgress:
+    """Create a ``ToggleableProgress`` bar with columns matching the solver configuration.
+
+    Used by both :class:`ObjectiveWrapper` (standalone) and :class:`MultiStart` (shared bar).
+    """
+    bar_column = BarColumn(bar_width=None, table_column=Column(description, ratio=1))
+    time_column = TimeElapsedColumn(table_column=Column("Elapsed", ratio=1))
+    n_iters = MofNCompleteColumn(table_column=Column("Iteration"))
+
+    objective_name = "Objective" if not root else "Residual"
+    obj_column = TextColumn(
+        "{task.fields[f_value]:0.8f}", table_column=Column(objective_name, ratio=1)
+    )
+
+    columns = [bar_column, time_column, n_iters, obj_column]
+
+    if use_jac:
+        grad_name = "||grad||" if not root else "||jac||"
+        columns.append(
+            TextColumn("{task.fields[grad_norm]:0.8f}", table_column=Column(grad_name, ratio=1))
+        )
+    if use_hess:
+        columns.append(
+            TextColumn("{task.fields[hess_norm]:0.8f}", table_column=Column("||hess||", ratio=1))
+        )
+
+    return ToggleableProgress(
+        *columns,
+        expand=False,
+        disable=not progressbar,
+        console=Console(file=sys.stderr, width=CONSOLE_WIDTH),
+    )
+
+
 class ObjectiveWrapper:
     def __init__(
         self,
@@ -151,6 +193,9 @@ class ObjectiveWrapper:
         if self.n_eval == 0 and self.task is None:
             verb = "Minimizing" if not self.root else "Finding Roots"
             self.task = self.progress.add_task(verb, total=self.maxeval, refresh=True, **value_dict)
+        elif self.n_eval == 0:
+            # Task was pre-registered (e.g. by MultiStart) without a known total.
+            self.progress.update(self.task, total=self.maxeval, **value_dict)
 
         if not completed:
             self.progress.update(self.task, advance=self.update_every, **value_dict)
@@ -160,36 +205,13 @@ class ObjectiveWrapper:
             )
 
     def initialize_progress_bar(self):
-        # text_column = TextColumn("{task.description}", table_column=Column(ratio=1))
         description = "Minimizing" if not self.root else "Finding Roots"
-        bar_column = BarColumn(bar_width=None, table_column=Column(description, ratio=1))
-        time_column = TimeElapsedColumn(table_column=Column("Elapsed", ratio=1))
-        n_iters = MofNCompleteColumn(table_column=Column("Iteration"))
-
-        objective_name = "Objective" if not self.root else "Residual"
-        obj_column = TextColumn(
-            "{task.fields[f_value]:0.8f}", table_column=Column(objective_name, ratio=1)
-        )
-
-        columns = [bar_column, time_column, n_iters, obj_column]
-
-        if self.use_jac:
-            grad_name = "||grad||" if not self.root else "||jac||"
-            columns += [
-                TextColumn("{task.fields[grad_norm]:0.8f}", table_column=Column(grad_name, ratio=1))
-            ]
-        if self.use_hess:
-            columns += [
-                TextColumn(
-                    "{task.fields[hess_norm]:0.8f}", table_column=Column("||hess||", ratio=1)
-                )
-            ]
-
-        return ToggleableProgress(
-            *columns,
-            expand=False,
-            disable=not self.progressbar,
-            console=Console(width=CONSOLE_WIDTH),
+        return build_progress_bar(
+            description=description,
+            progressbar=self.progressbar,
+            root=self.root,
+            use_jac=self.use_jac,
+            use_hess=self.use_hess,
         )
 
 
@@ -213,20 +235,40 @@ def optimizer_early_stopping_wrapper(f_optim: partial):
                 "prematurely.",
             )
         except Exception as e:
-            raise e
-
-        outputs = objective.step(final_value)
-
-        if not objective.use_jac and not objective.use_hess:
-            value = outputs
-            grad = None
-            hess = None
-        elif objective.use_jac and not objective.use_hess:
-            value, grad = outputs
-            hess = None
-        else:
-            value, grad, hess = outputs
+            # Catch any runtime errors from the optimizer (e.g. nan/inf) and return a failed
+            # result instead of crashing.
+            _log.warning("Optimizer raised %s: %s", type(e).__name__, e)
+            final_value = objective.previous_x
+            x0 = f_optim.keywords.get("x0")
+            if final_value is None:
+                final_value = x0
+            res = OptimizeResult(
+                x=final_value,
+                fun=np.inf,
+                success=False,
+                message=f"Optimizer raised {type(e).__name__}: {e}",
+            )
 
-        objective.update_progressbar(value, grad, hess, completed=True)
+        # Guard against final_value being None (can happen if no finite
+        # iterate was ever recorded and no x0 was available).
+        if final_value is not None:
+            try:
+                outputs = objective.step(final_value)
+
+                if not objective.use_jac and not objective.use_hess:
+                    value = outputs
+                    grad = None
+                    hess = None
+                elif objective.use_jac and not objective.use_hess:
+                    value, grad = outputs
+                    hess = None
+                else:
+                    value, grad, hess = outputs
+
+                objective.update_progressbar(value, grad, hess, completed=True)
+            except Exception:
+                # If the final evaluation itself fails (e.g. NaN inputs),
+                # just mark the progress bar as complete.
+                _log.debug("Final evaluation failed; skipping progress-bar update.", exc_info=True)
 
     return res

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.3
+Version: 0.3.2
 Summary: A drop-in replacement for scipy optimize functions with quality of life improvements
 License: MIT License
 Project-URL: Homepage, https://github.com/jessegrabowski/better_optimize
@@ -149,6 +149,54 @@ Many sub-computations are repeated between the objective, gradient, and hessian
 fused value_and_grad function, but `better_optimize` also lets you pass a triple-fused value_grad_and_hess function.
 This avoids redundant computation and speeds up the optimization process.
 
+### Parallel Optimization from Multiple Starting Points
+
+Real-world objectives often have multiple local minima. A common workaround is to throw many random starting points at
+the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
+
+```python
+from better_optimize import minimize, multi_optimize
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+result = multi_optimize(
+    solver=minimize,
+    solver_kwargs=dict(f=rosenbrock, method="L-BFGS-B", tol=1e-10),
+    x0=np.zeros(5),
+    n_runs=16,
+    init_strategy="uniform",
+    bounds=(-5, 5),
+    backend="loky",
+    n_jobs=-1,
+    seed=42,
+    progressbar=True,
+)
+
+print(result.best)       # Best OptimizeResult
+print(result.x_best)     # Best parameter vector
+print(result.fun_best)   # Best objective value
+result.summary()          # Rich table of all runs, ranked
+```
+
+`multi_optimize` works with **any** solver that follows the `(x0, **kwargs) → OptimizeResult` signature — that includes
+`minimize`, `root`, `basinhopping`, or your own custom wrapper. It just calls `solver(x0=x0_i, **solver_kwargs)` for
+each starting point; it never inspects the solver internals.
+
+A few highlights:
+
+- **Initialization strategies** — `"uniform"`, `"normal"`, `"sobol"`, `"lhs"`, or pass your own callable. Bounded
+  strategies (`uniform`, `sobol`, `lhs`) require a `bounds` argument; `"normal"` perturbs around `x0` with a
+  configurable `init_scale`. Or just pass an explicit `list[np.ndarray]` as `x0` and skip the generation entirely.
+- **Parallel backends** — `"sequential"` (for debugging), `"loky"` (CPU-bound work, default), or `"threading"`
+  (GIL-releasing code). Under the hood this is `joblib`, so the usual `n_jobs=-1` convention works.
+- **BLAS thread control** — When many workers each spawn a full BLAS/OpenMP thread pool, you get noisy-neighbor
+  over-subscription. The `blas_cores` argument (default `"auto"`) caps the total thread budget so workers don't
+  fight over the same cores.
+
+The returned `MultiStartResult` gives you `best`, `top_k(k)`, `ranked()`, `success_rate`, a `summary()` table, and
+`to_dataframe()` for further analysis.
+
 
 ## Contributing
 

{better_optimize-0.3 → better_optimize-0.3.2}/better_optimize.egg-info/SOURCES.txt

@@ -7,7 +7,7 @@ better_optimize/_version.py
 better_optimize/basinhopping.py
 better_optimize/constants.py
 better_optimize/minimize.py
-better_optimize/multistart.py
+better_optimize/multi_optimize.py
 better_optimize/root.py
 better_optimize/utilities.py
 better_optimize/wrapper.py

{better_optimize-0.3 → better_optimize-0.3.2}/tests/test_multistart.py

@@ -13,14 +13,15 @@ from numpy.testing import assert_allclose
 from scipy.optimize import OptimizeResult
 
 from better_optimize.minimize import minimize
-from better_optimize.multistart import (
-    MultiStart,
+from better_optimize.multi_optimize import (
     MultiStartResult,
     ProgressProxy,
     _drain_progress_queue,
     _is_pickle_error,
+    _MultiStart,
     _run_single,
     generate_starts,
+    multi_optimize,
     setup_blas_cores,
 )
 from better_optimize.root import root
@@ -30,17 +31,6 @@ def rosenbrock(x):
     return float(np.sum(100 * (x[1:] - x[:-1] ** 2) ** 2 + (1 - x[:-1]) ** 2))
 
 
-def rosenbrock_fused(x):
-    f = float(np.sum(100 * (x[1:] - x[:-1] ** 2) ** 2 + (1 - x[:-1]) ** 2))
-    g = np.zeros_like(x)
-    g[0] = -400 * x[0] * (x[1] - x[0] ** 2) - 2 * (1 - x[0])
-    g[-1] = 200 * (x[-1] - x[-2] ** 2)
-    g[1:-1] = (
-        200 * (x[1:-1] - x[:-2] ** 2) - 400 * x[1:-1] * (x[2:] - x[1:-1] ** 2) - 2 * (1 - x[1:-1])
-    )
-    return f, g
-
-
 def simple_system(x):
     return np.array([x[0] ** 2 + x[1] - 1, x[0] - x[1] ** 2 + 1])
 
@@ -73,9 +63,14 @@ def test_normal_starts_centered_on_x0(rng):
 
 
 @pytest.mark.parametrize("strategy", ["uniform", "sobol", "lhs"])
-def test_bounded_strategies_respect_bounds(strategy, rng):
+@pytest.mark.parametrize(
+    "bounds",
+    [(-5.0, 5.0), (np.array([-10.0, 0.0, -1.0]), np.array([0.0, 5.0, 1.0]))],
+    ids=["scalar", "array"],
+)
+def test_bounded_strategies_respect_bounds(strategy, bounds, rng):
     n_params, n_runs = 3, 16
-    low, high = -5.0, 5.0
+    low, high = bounds
     starts = generate_starts(
         np.zeros(n_params),
         n_runs,
@@ -110,23 +105,6 @@ def test_lhs_stratification(rng):
         assert len(set(bins)) == n_runs
 
 
-def test_generate_starts_with_array_bounds(rng):
-    low = np.array([-10.0, 0.0, -1.0])
-    high = np.array([0.0, 5.0, 1.0])
-    starts = generate_starts(
-        np.zeros(3),
-        64,
-        "uniform",
-        bounds=(low, high),
-        init_scale=1.0,
-        rng=rng,
-    )
-
-    stacked = np.stack(starts)
-    assert np.all(stacked >= low)
-    assert np.all(stacked <= high)
-
-
 def test_callable_strategy_dispatches_to_user_function(rng):
     x0 = np.array([1.0, 2.0])
 
@@ -179,12 +157,6 @@ def test_progress_proxy_serializes_action_to_queue(action):
     assert received_kwargs == payload
 
 
-def test_progress_proxy_add_task_returns_stored_id():
-    queue = multiprocessing.Queue()
-    proxy = ProgressProxy(queue, task_id=99)
-    assert proxy.add_task("ignored", total=100) == 99
-
-
 def test_drain_thread_exits_when_stop_is_set():
     queue = multiprocessing.Queue()
     stop = threading.Event()
@@ -223,14 +195,18 @@ def test_drain_thread_dispatches_queued_messages():
     progress.reset.assert_called_once_with(1, visible=False)
 
 
-def test_setup_blas_cores_auto_divides_evenly():
-    config = setup_blas_cores("auto", n_jobs=4, mp_ctx=None)
-    assert config.per_worker == 1
-
-
-def test_setup_blas_cores_explicit_budget():
-    config = setup_blas_cores(8, n_jobs=4, mp_ctx=None)
-    assert config.per_worker == 2
+@pytest.mark.parametrize(
+    "blas_cores, n_jobs, expected_per_worker",
+    [
+        ("auto", 4, 1),
+        (8, 4, 2),
+        (1, 8, 1),  # floors to 1
+    ],
+    ids=["auto", "explicit", "floors-to-one"],
+)
+def test_setup_blas_cores_per_worker(blas_cores, n_jobs, expected_per_worker):
+    config = setup_blas_cores(blas_cores, n_jobs=n_jobs, mp_ctx=None)
+    assert config.per_worker == expected_per_worker
 
 
 def test_setup_blas_cores_none_disables_limiting():
@@ -253,11 +229,6 @@ def test_setup_blas_cores_invalid_string_raises():
         setup_blas_cores("bogus", n_jobs=4, mp_ctx=None)
 
 
-def test_setup_blas_cores_per_worker_floors_to_one():
-    config = setup_blas_cores(1, n_jobs=8, mp_ctx=None)
-    assert config.per_worker == 1
-
-
 def test_setup_blas_cores_negative_n_jobs():
     config = setup_blas_cores("auto", n_jobs=-1, mp_ctx=None)
     assert config.per_worker == 1
@@ -292,61 +263,27 @@ def test_run_single_attaches_metadata():
     assert_allclose(result.x0, x0)
 
 
-def test_run_single_forwards_solver_kwargs():
-    received = {}
-
-    def capturing_solver(x0, **kwargs):
-        received.update(kwargs)
-        return OptimizeResult(x=x0, fun=0.0, success=True)
-
-    _run_single(
-        run_index=0,
-        x0=np.array([1.0]),
-        solver=capturing_solver,
-        solver_kwargs={"method": "L-BFGS-B", "tol": 1e-8},
-        progress=MagicMock(),
-        task_id=0,
-    )
-    assert received["method"] == "L-BFGS-B"
-    assert received["tol"] == 1e-8
-
-
-def test_run_single_applies_blas_thread_limit():
-    from threadpoolctl import threadpool_info
-
-    observed_limits = []
+def test_run_single_catches_solver_exception():
+    """Solver exceptions are caught and returned as failed OptimizeResults."""
 
-    def inspecting_solver(x0, **kwargs):
-        for lib in threadpool_info():
-            observed_limits.append(lib["num_threads"])
-        return OptimizeResult(x=x0, fun=0.0, success=True)
+    def exploding_solver(x0, **kwargs):
+        raise RuntimeError("NaN encountered")
 
-    _run_single(
-        run_index=0,
-        x0=np.array([1.0]),
-        solver=inspecting_solver,
+    x0 = np.array([1.0, 2.0])
+    result = _run_single(
+        run_index=3,
+        x0=x0,
+        solver=exploding_solver,
         solver_kwargs={},
         progress=MagicMock(),
         task_id=0,
-        blas_cores_per_worker=1,
     )
-    if observed_limits:
-        assert all(n <= 1 for n in observed_limits)
-
-
-def test_run_single_propagates_solver_exception():
-    def exploding_solver(x0, **kwargs):
-        raise RuntimeError("solver exploded")
-
-    with pytest.raises(RuntimeError, match="solver exploded"):
-        _run_single(
-            run_index=0,
-            x0=np.zeros(2),
-            solver=exploding_solver,
-            solver_kwargs={},
-            progress=MagicMock(),
-            task_id=0,
-        )
+    assert not result.success
+    assert result.fun == np.inf
+    assert "RuntimeError" in result.message
+    assert result.run_index == 3
+    assert_allclose(result.x0, x0)
+    assert_allclose(result.x, x0)
 
 
 class TestMultiStartResult:
@@ -420,18 +357,19 @@ class TestMultiStartResult:
 )
 def test_task_description_for_known_solvers(solver_name, expected_label):
     stub = MagicMock(__name__=solver_name)
-    ms = MultiStart(solver=stub, x0=[np.zeros(2)], progressbar=False)
+    ms = _MultiStart(solver=stub, x0=[np.zeros(2)], progressbar=False)
     assert ms._task_description == expected_label
 
 
 def test_task_description_falls_back_for_unknown_solver():
     stub = MagicMock(__name__="my_custom_opt")
-    ms = MultiStart(solver=stub, x0=[np.zeros(2)], progressbar=False)
+    ms = _MultiStart(solver=stub, x0=[np.zeros(2)], progressbar=False)
     assert ms._task_description == "My_Custom_Opt"
 
 
-def test_multistart_finds_rosenbrock_minimum():
-    result = MultiStart(
+@pytest.mark.parametrize("backend", ["sequential", "loky"])
+def test_multistart_finds_rosenbrock_minimum(backend):
+    result = multi_optimize(
         solver=minimize,
         solver_kwargs=dict(f=rosenbrock, method="L-BFGS-B"),
         x0=np.zeros(3),
@@ -439,8 +377,11 @@ def test_multistart_finds_rosenbrock_minimum():
         init_strategy="uniform",
         bounds=(-2, 2),
         seed=7913,
+        backend=backend,
+        n_jobs=2,
         progressbar=False,
-    ).run()
+        blas_cores=None,
+    )
 
     assert len(result.results) == 8
     assert_allclose(result.x_best, np.ones(3), atol=1e-3)
@@ -449,12 +390,12 @@ def test_multistart_finds_rosenbrock_minimum():
 
 def test_multistart_with_explicit_starting_points():
     x0_list = [np.array([1.3, 0.7, 0.8]), np.array([0.5, 0.5, 0.5])]
-    result = MultiStart(
+    result = multi_optimize(
         solver=minimize,
         solver_kwargs=dict(f=rosenbrock, method="L-BFGS-B"),
         x0=x0_list,
         progressbar=False,
-    ).run()
+    )
 
     assert len(result.results) == 2
     for result_i, expected_x0 in zip(result.results, x0_list):
@@ -462,7 +403,7 @@ def test_multistart_with_explicit_starting_points():
 
 
 def test_multistart_with_root_solver():
-    result = MultiStart(
+    result = multi_optimize(
         solver=root,
         solver_kwargs=dict(f=simple_system, method="hybr"),
         sort_key=lambda res: float(np.linalg.norm(res.fun)),
@@ -472,38 +413,11 @@ def test_multistart_with_root_solver():
         init_scale=2.0,
         seed=9173,
         progressbar=False,
-    ).run()
+    )
 
     assert result.fun_best < 1e-6
 
 
-def test_multistart_x0_list_ignores_n_runs():
-    result = MultiStart(
-        solver=minimize,
-        solver_kwargs=dict(f=rosenbrock, method="nelder-mead"),
-        x0=[np.zeros(2), np.ones(2)],
-        n_runs=999,
-        progressbar=False,
-    ).run()
-
-    assert len(result.results) == 2
-
-
-def test_multistart_with_fused_objective():
-    result = MultiStart(
-        solver=minimize,
-        solver_kwargs=dict(f=rosenbrock_fused, method="L-BFGS-B"),
-        x0=np.zeros(3),
-        n_runs=4,
-        init_strategy="uniform",
-        bounds=(-2, 2),
-        seed=3917,
-        progressbar=False,
-    ).run()
-
-    assert_allclose(result.x_best, np.ones(3), atol=1e-3)
-
-
 def test_multistart_pickle_fallback(caplog):
     def unpicklable_closure():
         return None
@@ -513,15 +427,46 @@ def test_multistart_pickle_fallback(caplog):
         return OptimizeResult(x=x0, fun=float(np.sum(x0**2)), success=True)
 
     with caplog.at_level("WARNING", logger="better_optimize.multistart"):
-        result = MultiStart(
+        result = multi_optimize(
             solver=solver_with_closure,
             x0=[np.zeros(2), np.ones(2)],
             backend="loky",
             n_jobs=2,
             progressbar=False,
             blas_cores=None,
-        ).run()
+        )
 
     # Fallback may or may not trigger depending on environment,
     # but either way we must get valid results.
     assert len(result.results) == 2
+
+
+def test_multistart_survives_crashing_solver():
+    """A solver that raises for some starting points should not kill the campaign."""
+    call_count = 0
+
+    def sometimes_exploding_solver(x0, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count % 2 == 0:
+            raise RuntimeError("NaN in trust region subproblem")
+        return OptimizeResult(x=x0, fun=float(np.sum(x0**2)), success=True)
+
+    x0_list = [np.ones(2) * i for i in range(4)]
+    result = multi_optimize(
+        solver=sometimes_exploding_solver,
+        x0=x0_list,
+        backend="sequential",
+        progressbar=False,
+        blas_cores=None,
+    )
+
+    assert len(result.results) == 4
+    n_success = sum(r.success for r in result.results)
+    n_failed = sum(not r.success for r in result.results)
+    assert n_success == 2
+    assert n_failed == 2
+    for r in result.results:
+        if not r.success:
+            assert r.fun == np.inf
+            assert "RuntimeError" in r.message

{better_optimize-0.3 → better_optimize-0.3.2}/tests/test_wrapper.py

@@ -43,7 +43,8 @@ def test_early_return_from_keyboard_interrupt(root, method):
 
 
 @pytest.mark.parametrize("root", [True, False], ids=["root", "minimize"])
-def test_execption_breaks_optimization(root, monkeypatch):
+def test_exception_returns_failed_result(root, monkeypatch):
+    """Exceptions raised inside the optimizer should be caught and returned as a failed result."""
     N_EXEC = 0
 
     def f(x: np.ndarray):
@@ -64,9 +65,9 @@ def test_execption_breaks_optimization(root, monkeypatch):
         callback=objective.callback,
     )
 
-    # Non-KeyboardInterrupt exceptions should break execution.
-    with pytest.raises(Exception, match="Simulated error"):
-        optimizer_early_stopping_wrapper(f_optim)
+    result = optimizer_early_stopping_wrapper(f_optim)
+    assert not result.success
+    assert "Simulated error" in result.message
 
 
 def func2(x, a, b):