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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.3.2
+Version: 0.4
 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
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Mathematics
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy

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

@@ -2,9 +2,11 @@ import logging
 
 from better_optimize._version import get_versions
 from better_optimize.basinhopping import basinhopping
+from better_optimize.differential_evolution import differential_evolution
 from better_optimize.minimize import minimize
 from better_optimize.multi_optimize import multi_optimize
 from better_optimize.root import root
+from better_optimize.sequential_optimize import sequential_optimize
 
 _log = logging.getLogger(__name__)
 
@@ -16,4 +18,11 @@ if not logging.root.handlers:
 
 
 __version__ = get_versions()["version"]
-__all__ = ["minimize", "root", "basinhopping", "multi_optimize"]
+__all__ = [
+    "basinhopping",
+    "differential_evolution",
+    "minimize",
+    "multi_optimize",
+    "root",
+    "sequential_optimize",
+]

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

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-03-20T19:57:42+0100",
+ "date": "2026-04-21T12:33:06-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "2c8f4f7afbc2b54fa1e8aa8827b4be15e6ea87a9",
- "version": "0.3.2"
+ "full-revisionid": "f195a9db17359043c86b3be5f33a34494f635e58",
+ "version": "0.4"
 }
 '''  # END VERSION_JSON
 

better_optimize-0.4/better_optimize/basinhopping/__init__.py

@@ -0,0 +1,11 @@
+from better_optimize.basinhopping.core import basinhopping
+from better_optimize.basinhopping.runner import (
+    AllowFailureBasinHoppingRunner,
+    AllowFailureStorage,
+)
+
+__all__ = [
+    "AllowFailureBasinHoppingRunner",
+    "AllowFailureStorage",
+    "basinhopping",
+]

better_optimize-0.3.2/better_optimize/basinhopping.py → better_optimize-0.4/better_optimize/basinhopping/core.py

@@ -1,105 +1,27 @@
-import sys
-
 from collections.abc import Callable, Sequence
 
 import numpy as np
 
-from rich.console import Console
-from rich.progress import (
-    BarColumn,
-    MofNCompleteColumn,
-    TextColumn,
-    TimeElapsedColumn,
-)
-from rich.table import Column
 from scipy.optimize import OptimizeResult
 from scipy.optimize._basinhopping import (
     AdaptiveStepsize,
-    BasinHoppingRunner,
     Metropolis,
     MinimizerWrapper,
     RandomDisplacement,
-    Storage,
     check_random_state,
 )
 
-from better_optimize.constants import CONSOLE_WIDTH
+from better_optimize.basinhopping.progress import initialize_progress_bar
+from better_optimize.basinhopping.runner import AllowFailureBasinHoppingRunner
 from better_optimize.minimize import minimize
 from better_optimize.utilities import (
     LRUCache1,
-    ToggleableProgress,
     check_f_is_fused_minimize,
     determine_maxiter,
     validate_provided_functions_minimize,
 )
 
 
-def initialize_progress_bar(progressbar, use_jac=True, use_hess=False):
-    description = "Process"
-    name_column = TextColumn("{task.fields[name]}", table_column=Column(description, ratio=2))
-    bar_column = BarColumn(bar_width=None, table_column=Column("", ratio=2))
-    time_column = TimeElapsedColumn(table_column=Column("Elapsed", ratio=1))
-    n_iters = MofNCompleteColumn(table_column=Column("Iteration"))
-
-    step_size = TextColumn("{task.fields[step_size]:0.3f}", table_column=Column("Step", ratio=1))
-    accept_rate = TextColumn(
-        "{task.fields[accept_rate]:0.3f}", table_column=Column("Accept Rate", ratio=1)
-    )
-
-    objective_name = "Objective"
-    obj_column = TextColumn(
-        "{task.fields[f_value]:0.5f}", table_column=Column(objective_name, ratio=1)
-    )
-
-    columns = [name_column, bar_column, time_column, n_iters, step_size, accept_rate, obj_column]
-
-    if use_jac:
-        columns += [
-            TextColumn("{task.fields[grad_norm]:0.5f}", table_column=Column("||grad||", ratio=1))
-        ]
-    if use_hess:
-        columns += [
-            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),
-        transient=True,
-    )
-
-
-class AllowFailureStorage(Storage):
-    """
-    Subclass of Storage that allows the minimizer to fail, but still updates the global minimum
-    if the new point is better than the current global minimum.
-    """
-
-    def update(self, minres):
-        if minres.fun < self.minres.fun:
-            self._add(minres)
-            return True
-        else:
-            return False
-
-
-class AllowFailureBasinHoppingRunner(BasinHoppingRunner):
-    """
-    A subclass of BasinHoppingRunner that allows the minimizer to fail, but still updates the
-    global minimum if the new point is better than the current global minimum.
-    """
-
-    def __init__(
-        self, x0, minimizer, step_taking, accept_tests, accept_on_minimizer_fail=False, disp=False
-    ):
-        super().__init__(x0, minimizer, step_taking, accept_tests, disp=disp)
-
-        if accept_on_minimizer_fail:
-            self.storage = AllowFailureStorage(self.storage.minres)
-
-
 def basinhopping(
     func: Callable[..., float | np.ndarray],
     x0: Sequence[float],
@@ -281,7 +203,6 @@ def basinhopping(
         else:
             take_step_wrapped = take_step
     else:
-        # use default
         displace = RandomDisplacement(stepsize=stepsize, rng=rng)
         take_step_wrapped = AdaptiveStepsize(
             displace,

better_optimize-0.4/better_optimize/basinhopping/progress.py

@@ -0,0 +1,53 @@
+import sys
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Column
+
+from better_optimize.constants import CONSOLE_WIDTH
+from better_optimize.utilities import ToggleableProgress
+
+
+def initialize_progress_bar(progressbar, use_jac=True, use_hess=False):
+    description = "Process"
+    name_column = TextColumn("{task.fields[name]}", table_column=Column(description, ratio=2))
+    bar_column = BarColumn(bar_width=None, table_column=Column("", ratio=2))
+    time_column = TimeElapsedColumn(table_column=Column("Elapsed", ratio=1))
+    n_iters = MofNCompleteColumn(table_column=Column("Iteration"))
+
+    step_size = TextColumn("{task.fields[step_size]:0.3f}", table_column=Column("Step", ratio=1))
+    accept_rate = TextColumn(
+        "{task.fields[accept_rate]:0.3f}", table_column=Column("Accept Rate", ratio=1)
+    )
+
+    objective_name = "Objective"
+    obj_column = TextColumn(
+        "{task.fields[f_value]:0.5f}", table_column=Column(objective_name, ratio=1)
+    )
+
+    columns = [name_column, bar_column, time_column, n_iters, step_size, accept_rate, obj_column]
+
+    if use_jac:
+        columns += [
+            TextColumn("{task.fields[grad_norm]:0.5f}", table_column=Column("||grad||", ratio=1))
+        ]
+    if use_hess:
+        columns += [
+            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),
+        transient=True,
+    )
+
+
+__all__ = ["initialize_progress_bar"]

better_optimize-0.4/better_optimize/basinhopping/runner.py

@@ -0,0 +1,33 @@
+from scipy.optimize._basinhopping import BasinHoppingRunner, Storage
+
+
+class AllowFailureStorage(Storage):
+    """
+    Subclass of Storage that allows the minimizer to fail, but still updates the global minimum
+    if the new point is better than the current global minimum.
+    """
+
+    def update(self, minres):
+        if minres.fun < self.minres.fun:
+            self._add(minres)
+            return True
+        else:
+            return False
+
+
+class AllowFailureBasinHoppingRunner(BasinHoppingRunner):
+    """
+    A subclass of BasinHoppingRunner that allows the minimizer to fail, but still updates the
+    global minimum if the new point is better than the current global minimum.
+    """
+
+    def __init__(
+        self, x0, minimizer, step_taking, accept_tests, accept_on_minimizer_fail=False, disp=False
+    ):
+        super().__init__(x0, minimizer, step_taking, accept_tests, disp=disp)
+
+        if accept_on_minimizer_fail:
+            self.storage = AllowFailureStorage(self.storage.minres)
+
+
+__all__ = ["AllowFailureBasinHoppingRunner", "AllowFailureStorage"]

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

@@ -33,6 +33,23 @@ root_method = Literal[
 TOLERANCES = ["xtol", "ftol", "gtol", "fatol", "xatol"]
 CONSOLE_WIDTH = 100
 
+DE_STRATEGY_OPTIONS = (
+    "best1bin",
+    "best1exp",
+    "rand1bin",
+    "rand1exp",
+    "randtobest1bin",
+    "randtobest1exp",
+    "currenttobest1bin",
+    "currenttobest1exp",
+    "best2bin",
+    "best2exp",
+    "rand2bin",
+    "rand2exp",
+)
+
+DE_INIT_OPTIONS = ("sobol", "halton", "latinhypercube", "random")
+
 MINIMIZE_MODE_KWARGS = {
     "nelder-mead": {
         "uses_grad": False,

better_optimize-0.4/better_optimize/differential_evolution.py

@@ -0,0 +1,245 @@
+import contextlib
+import logging
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+
+from rich.progress import TaskID
+from scipy.optimize import OptimizeResult
+from scipy.optimize import differential_evolution as sp_differential_evolution
+
+from better_optimize.constants import DE_INIT_OPTIONS, DE_STRATEGY_OPTIONS
+from better_optimize.utilities import LRUCache1, check_f_is_fused_minimize
+from better_optimize.wrapper import build_progress_bar
+
+_log = logging.getLogger(__name__)
+
+
+def _nullcontext():
+    return contextlib.nullcontext()
+
+
+def _bounds_to_array(bounds) -> np.ndarray:
+    arr = np.asarray(bounds, dtype=np.float64)
+    if arr.ndim != 2 or arr.shape[1] != 2:
+        raise ValueError(
+            f"bounds must be a sequence of (low, high) pairs or an (n, 2) array; "
+            f"got shape {arr.shape}"
+        )
+    if np.any(arr[:, 0] > arr[:, 1]):
+        raise ValueError("bounds low > high for at least one dimension")
+    return arr
+
+
+def _sample_x_from_bounds(bounds_arr: np.ndarray) -> np.ndarray:
+    """Generate one midpoint within bounds for fused-function sniffing."""
+    return 0.5 * (bounds_arr[:, 0] + bounds_arr[:, 1])
+
+
+def _default_maxiter(d: int) -> int:
+    return max(1000, 200 * d)
+
+
+def differential_evolution(
+    f: Callable,
+    bounds: Sequence[tuple[float, float]] | np.ndarray,
+    args: tuple = (),
+    strategy: str | Callable = "best1bin",
+    maxiter: int | None = None,
+    popsize: int = 15,
+    tol: float = 0.01,
+    mutation: float | tuple[float, float] = (0.5, 1.0),
+    recombination: float = 0.7,
+    callback: Callable | None = None,
+    init: str | np.ndarray = "sobol",
+    atol: float = 0.0,
+    updating: str = "immediate",
+    workers: int | Callable = 1,
+    constraints: tuple = (),
+    x0: Sequence[float] | np.ndarray | None = None,
+    integrality: Sequence[bool] | np.ndarray | None = None,
+    vectorized: bool = False,
+    progressbar: bool = True,
+    progress_task: TaskID | None = None,
+    verbose: bool = False,
+    rng: int | np.random.Generator | None = None,
+) -> OptimizeResult:
+    """Differential evolution with progress bar, graceful failure, and fused-function support.
+
+    See scipy's :func:`scipy.optimize.differential_evolution` documentation for parameter
+    semantics. Polish customization (method choice, tolerance) is not exposed here by design —
+    chain a dedicated ``minimize`` stage via :func:`sequential_optimize` instead.
+
+    Parameters
+    ----------
+    f : Callable
+        Scalar objective, or fused ``(f, grad)`` / ``(f, grad, hess)``.
+    bounds : sequence of (low, high) or (d, 2) array
+        Search region per dimension. Required.
+    progressbar : bool or ToggleableProgress
+        If True, show a live rich progress bar with best-so-far each generation. If a
+        ``ToggleableProgress`` instance is passed (e.g. from ``sequential_optimize``), reuse
+        it instead of creating a new one.
+    progress_task : TaskID, optional
+        When ``sequential_optimize`` pre-registers a task on the shared progress and passes
+        the id here, that task is updated instead of creating a new one. Ignored for
+        standalone calls.
+    rng : int, numpy.random.Generator, or None
+        Seed / generator for reproducibility. Forwarded to scipy as the ``rng`` kwarg.
+
+    Returns
+    -------
+    scipy.optimize.OptimizeResult
+        The usual scipy result. On internal failure, ``success=False`` and ``fun=np.inf``.
+    """
+    bounds_arr = _bounds_to_array(bounds)
+    d = bounds_arr.shape[0]
+
+    if isinstance(strategy, str) and strategy not in DE_STRATEGY_OPTIONS:
+        raise ValueError(
+            f"strategy must be one of {DE_STRATEGY_OPTIONS} or a callable; got {strategy!r}"
+        )
+    if isinstance(init, str) and init not in DE_INIT_OPTIONS:
+        raise ValueError(f"init must be one of {DE_INIT_OPTIONS} or an array; got {init!r}")
+
+    if maxiter is None:
+        maxiter = _default_maxiter(d)
+
+    sample_x = (
+        np.asarray(x0, dtype=np.float64) if x0 is not None else _sample_x_from_bounds(bounds_arr)
+    )
+
+    has_fused_f_and_grad, has_fused_f_grad_hess = check_f_is_fused_minimize(f, sample_x, args or ())
+    f_returns_list = has_fused_f_and_grad or has_fused_f_grad_hess
+    f_cached = LRUCache1(
+        f,
+        f_returns_list=f_returns_list,
+        copy_x=False,
+        dtype=sample_x.dtype.name if sample_x.dtype != object else None,
+    )
+
+    owns_progress = not isinstance(progressbar, object.__class__) and isinstance(progressbar, bool)
+    if isinstance(progressbar, bool):
+        progress = build_progress_bar(
+            description="Differential Evolution",
+            progressbar=progressbar,
+            root=False,
+            use_jac=False,
+            use_hess=False,
+        )
+        owns_progress = True
+    else:
+        progress = progressbar
+        owns_progress = False
+
+    if progress_task is None:
+        de_task = progress.add_task(
+            description="Differential Evolution",
+            total=maxiter,
+            f_value=float("inf"),
+            grad_norm=0.0,
+            hess_norm=0.0,
+        )
+    else:
+        de_task = progress_task
+        progress.update(de_task, total=maxiter, f_value=float("inf"))
+
+    iter_counter = [0]
+    best_fun_seen = [float("inf")]
+
+    def progress_callback(intermediate_result):
+        """Drive progress bar + forward to user's callback.
+
+        scipy passes an OptimizeResult-like object since scipy 1.13 (or (xk, convergence)
+        in older versions). Support both.
+        """
+        if hasattr(intermediate_result, "x"):
+            xk = np.asarray(intermediate_result.x, dtype=np.float64)
+            convergence = float(getattr(intermediate_result, "convergence", 0.0))
+        else:  # legacy tuple-style
+            xk = np.asarray(intermediate_result, dtype=np.float64)
+            convergence = 0.0
+
+        try:
+            f_val = float(f_cached.value(xk))
+        except Exception:
+            f_val = best_fun_seen[0]
+
+        if f_val < best_fun_seen[0]:
+            best_fun_seen[0] = f_val
+
+        iter_counter[0] += 1
+        progress.update(de_task, advance=1, f_value=best_fun_seen[0], refresh=True)
+
+        if callback is not None:
+            user_stop = callback(xk, convergence=convergence)
+            if user_stop:
+                raise StopIteration("user callback returned True")
+        return False
+
+    scipy_kwargs: dict[str, Any] = {
+        "args": args,
+        "strategy": strategy,
+        "maxiter": maxiter,
+        "popsize": popsize,
+        "tol": tol,
+        "mutation": mutation,
+        "recombination": recombination,
+        "rng": rng,
+        "callback": progress_callback,
+        "disp": False,
+        "polish": False,
+        "init": init,
+        "atol": atol,
+        "updating": updating,
+        "workers": workers,
+        "constraints": constraints,
+        "integrality": integrality,
+        "vectorized": vectorized,
+    }
+    if x0 is not None:
+        scipy_kwargs["x0"] = np.asarray(x0, dtype=np.float64)
+
+    fallback_x = np.asarray(x0, dtype=np.float64) if x0 is not None else sample_x
+
+    progress_ctx = progress if owns_progress else _nullcontext()
+    with progress_ctx:
+        try:
+            res = sp_differential_evolution(f_cached.value, bounds_arr, **scipy_kwargs)
+        except (KeyboardInterrupt, StopIteration) as e:
+            _log.warning("differential_evolution interrupted: %s", e)
+            res = OptimizeResult(
+                x=fallback_x,
+                fun=best_fun_seen[0],
+                success=False,
+                message=f"interrupted: {type(e).__name__}",
+                nit=iter_counter[0],
+                nfev=f_cached.cache_misses,
+            )
+        except (FloatingPointError, ArithmeticError, np.linalg.LinAlgError) as e:
+            _log.warning("differential_evolution raised %s: %s", type(e).__name__, e)
+            res = OptimizeResult(
+                x=fallback_x,
+                fun=float("inf"),
+                success=False,
+                message=f"differential_evolution raised {type(e).__name__}: {e}",
+                nit=iter_counter[0],
+                nfev=f_cached.cache_misses,
+            )
+        else:
+            progress.update(de_task, completed=maxiter, f_value=float(res.fun), refresh=True)
+
+    if verbose:
+        _log.info(
+            "differential_evolution finished: fun=%.6e, nit=%d, success=%s",
+            float(getattr(res, "fun", float("inf"))),
+            int(getattr(res, "nit", 0) or 0),
+            bool(getattr(res, "success", False)),
+        )
+
+    return res
+
+
+__all__ = ["differential_evolution"]

{better_optimize-0.3.2 → better_optimize-0.4}/better_optimize/minimize.py

@@ -98,6 +98,7 @@ def minimize(
         f=f_cached.value_and_grad if has_fused_f_and_grad else f_cached.value,
         jac=jac,
         hess=hess if use_hess else None,
+        hessp=hessp if use_hessp else None,
         args=args,
         progressbar=progressbar,
         progressbar_update_interval=progressbar_update_interval,

{better_optimize-0.3.2 → better_optimize-0.4}/better_optimize/multi_optimize.py

@@ -419,34 +419,31 @@ class _MultiStart:
         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
+            use_rayleigh = 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
-            )
+            has_hess = "hess" in self._solver_kwargs or "hessp" in self._solver_kwargs
+            use_rayleigh = use_jac and has_hess
 
         return build_progress_bar(
             description=self._task_description,
             progressbar=self._progressbar,
             root=self._is_root,
             use_jac=use_jac,
-            use_hess=use_hess,
+            use_rayleigh=use_rayleigh,
         )
 
     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.
+        # Unused fields (e.g. rayleigh when no curvature 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,
+                rayleigh=0.0,
             )
             for _ in self._starting_points
         ]