better-optimize 0.2.1__tar.gz → 0.3.1__tar.gz

{better_optimize-0.2.1 → better_optimize-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.2.1
+Version: 0.3.1
 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
@@ -21,6 +21,9 @@ License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: scipy>=1.15
 Requires-Dist: rich
+Requires-Dist: threadpoolctl
+Requires-Dist: joblib
+Requires-Dist: pandas
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -146,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.2.1 → better_optimize-0.3.1}/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.2.1 → better_optimize-0.3.1}/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"]
+__all__ = ["minimize", "root", "basinhopping", "multi_optimize"]

{better_optimize-0.2.1 → better_optimize-0.3.1}/better_optimize/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-03-02T01:36:39+0100",
+ "date": "2026-03-20T00:48:11+0100",
  "dirty": false,
  "error": null,
- "full-revisionid": "14b8b75021dd22fa3d38135eee74b2ab95c30a06",
- "version": "0.2.1"
+ "full-revisionid": "0478ed4b401b74272d06dee5e904e77be2916235",
+ "version": "0.3.1"
 }
 '''  # END VERSION_JSON
 

{better_optimize-0.2.1 → better_optimize-0.3.1}/better_optimize/basinhopping.py

@@ -21,6 +21,7 @@ from scipy.optimize._basinhopping import (
     check_random_state,
 )
 
+from better_optimize.constants import CONSOLE_WIDTH
 from better_optimize.minimize import minimize
 from better_optimize.utilities import (
     LRUCache1,
@@ -60,7 +61,11 @@ def initialize_progress_bar(progressbar, use_jac=True, use_hess=False):
         ]
 
     return ToggleableProgress(
-        *columns, expand=False, disable=not progressbar, console=Console(width=100), transient=True
+        *columns,
+        expand=False,
+        disable=not progressbar,
+        console=Console(width=CONSOLE_WIDTH),
+        transient=True,
     )
 
 

{better_optimize-0.2.1 → better_optimize-0.3.1}/better_optimize/constants.py

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