better-optimize 0.4.1__tar.gz → 0.4.2__tar.gz

{better_optimize-0.4.1 → better_optimize-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.4.1
+Version: 0.4.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
@@ -89,6 +89,19 @@ All optimization routines in `better_optimize` can display a rich, informative p
 - Optionally accepts and stores failed minimizer results if they improve the global minimum.
 - Useful for noisy or non-smooth objective functions where local minimization may occasionally fail.
 
+### 6. Uniform Callback API
+
+scipy passes callbacks a different argument for almost every method: `callback(xk)`, `callback(xk, state)`,
+`callback(intermediate_result)`, or `callback(x, f)` for root finding. `better_optimize` normalizes them to a single
+`callback(res)`, where `res` is an `OptimizeResult` with the current `res.x`, `res.fun`, and `res.nit` — plus `res.jac`
+when a gradient is available, and solver-specific fields like `res.accept` (basinhopping) or `res.convergence`
+(differential evolution).
+
+- The return value is ignored, so a callback can report a value (an ELBO, a logged loss) without stopping the run.
+- Raise `StopOptimization` to stop early; the best result so far is returned with `success=False`.
+- The same callback works across `minimize`, `root`, `basinhopping`, and `differential_evolution`. `hybr` and `lm` are
+  the exception — scipy never calls a callback for them, so it is ignored with a warning.
+
 ---
 
 ## Example Usage
@@ -96,6 +109,7 @@ All optimization routines in `better_optimize` can display a rich, informative p
 ### Simple Example
 
 ```python
+import numpy as np
 from better_optimize import minimize
 
 def rosenbrock(x):
@@ -103,7 +117,7 @@ def rosenbrock(x):
 
 result = minimize(
     rosenbrock,
-    x0=[-1, 2],
+    x0=np.array([-1.0, 2.0]),
     method="L-BFGS-B",
     tol=1e-6,
     maxiter=1000,
@@ -119,6 +133,36 @@ result = minimize(
 
 The result object is a standard `OptimizeResult` from `scipy.optimize`, so there are no surprises there!
 
+### Callbacks and Early Stopping
+
+Pass a `callback` and it runs after each iteration with an `OptimizeResult`. Its return value is ignored; raise
+`StopOptimization` to stop and return the best result so far.
+
+```python
+import numpy as np
+from better_optimize import minimize, StopOptimization
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+history = []
+
+def callback(res):
+    history.append(res.fun)  # res.x, res.fun, res.nit; res.jac when available
+    if res.fun < 1e-8:
+        raise StopOptimization
+
+result = minimize(
+    rosenbrock,
+    x0=np.array([-1.0, 2.0]),
+    method="L-BFGS-B",
+    callback=callback,
+)
+```
+
+The same callback works for `root` (`res.fun` is the residual vector), `basinhopping` (`res.accept`), and
+`differential_evolution` (`res.convergence`).
+
 ### Triple-Fused Function using Pytensor
 
 ```python
@@ -155,6 +199,7 @@ Real-world objectives often have multiple local minima. A common workaround is t
 the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
 
 ```python
+import numpy as np
 from better_optimize import minimize, multi_optimize
 
 def rosenbrock(x):
@@ -179,6 +224,9 @@ print(result.fun_best)   # Best objective value
 result.summary()          # Rich table of all runs, ranked
 ```
 
+> The `loky` (process) backend needs an `if __name__ == "__main__":` guard when run as a script on macOS or Windows.
+> Notebooks and the `threading`/`sequential` backends don't.
+
 `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.

{better_optimize-0.4.1 → better_optimize-0.4.2}/README.md

@@ -57,6 +57,19 @@ All optimization routines in `better_optimize` can display a rich, informative p
 - Optionally accepts and stores failed minimizer results if they improve the global minimum.
 - Useful for noisy or non-smooth objective functions where local minimization may occasionally fail.
 
+### 6. Uniform Callback API
+
+scipy passes callbacks a different argument for almost every method: `callback(xk)`, `callback(xk, state)`,
+`callback(intermediate_result)`, or `callback(x, f)` for root finding. `better_optimize` normalizes them to a single
+`callback(res)`, where `res` is an `OptimizeResult` with the current `res.x`, `res.fun`, and `res.nit` — plus `res.jac`
+when a gradient is available, and solver-specific fields like `res.accept` (basinhopping) or `res.convergence`
+(differential evolution).
+
+- The return value is ignored, so a callback can report a value (an ELBO, a logged loss) without stopping the run.
+- Raise `StopOptimization` to stop early; the best result so far is returned with `success=False`.
+- The same callback works across `minimize`, `root`, `basinhopping`, and `differential_evolution`. `hybr` and `lm` are
+  the exception — scipy never calls a callback for them, so it is ignored with a warning.
+
 ---
 
 ## Example Usage
@@ -64,6 +77,7 @@ All optimization routines in `better_optimize` can display a rich, informative p
 ### Simple Example
 
 ```python
+import numpy as np
 from better_optimize import minimize
 
 def rosenbrock(x):
@@ -71,7 +85,7 @@ def rosenbrock(x):
 
 result = minimize(
     rosenbrock,
-    x0=[-1, 2],
+    x0=np.array([-1.0, 2.0]),
     method="L-BFGS-B",
     tol=1e-6,
     maxiter=1000,
@@ -87,6 +101,36 @@ result = minimize(
 
 The result object is a standard `OptimizeResult` from `scipy.optimize`, so there are no surprises there!
 
+### Callbacks and Early Stopping
+
+Pass a `callback` and it runs after each iteration with an `OptimizeResult`. Its return value is ignored; raise
+`StopOptimization` to stop and return the best result so far.
+
+```python
+import numpy as np
+from better_optimize import minimize, StopOptimization
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+history = []
+
+def callback(res):
+    history.append(res.fun)  # res.x, res.fun, res.nit; res.jac when available
+    if res.fun < 1e-8:
+        raise StopOptimization
+
+result = minimize(
+    rosenbrock,
+    x0=np.array([-1.0, 2.0]),
+    method="L-BFGS-B",
+    callback=callback,
+)
+```
+
+The same callback works for `root` (`res.fun` is the residual vector), `basinhopping` (`res.accept`), and
+`differential_evolution` (`res.convergence`).
+
 ### Triple-Fused Function using Pytensor
 
 ```python
@@ -123,6 +167,7 @@ Real-world objectives often have multiple local minima. A common workaround is t
 the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
 
 ```python
+import numpy as np
 from better_optimize import minimize, multi_optimize
 
 def rosenbrock(x):
@@ -147,6 +192,9 @@ print(result.fun_best)   # Best objective value
 result.summary()          # Rich table of all runs, ranked
 ```
 
+> The `loky` (process) backend needs an `if __name__ == "__main__":` guard when run as a script on macOS or Windows.
+> Notebooks and the `threading`/`sequential` backends don't.
+
 `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.

{better_optimize-0.4.1 → better_optimize-0.4.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.differential_evolution import differential_evolution
+from better_optimize.exceptions import StopOptimization
 from better_optimize.minimize import minimize
 from better_optimize.multi_optimize import multi_optimize
 from better_optimize.root import root
@@ -19,6 +20,7 @@ if not logging.root.handlers:
 
 __version__ = get_versions()["version"]
 __all__ = [
+    "StopOptimization",
     "basinhopping",
     "differential_evolution",
     "minimize",

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-04-21T14:03:17-0500",
+ "date": "2026-05-23T05:38:17+0200",
  "dirty": false,
  "error": null,
- "full-revisionid": "ac00b49724e28bdbe53d12fcd222d003decfbd67",
- "version": "0.4.1"
+ "full-revisionid": "8613524a4578ba95c931ea6cf3091963c35f7a8f",
+ "version": "0.4.2"
 }
 '''  # END VERSION_JSON
 

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/basinhopping/core.py

@@ -67,7 +67,10 @@ def basinhopping(
         Accept the new point even if the minimizer fails. Will also update the global minimum if the point is
         better than the current global minimum, even if the minimizer fails.
     callback: Callable, optional
-        User-supplied function to call after each iteration
+        Function called after each iteration as ``callback(res)``, where ``res`` is an
+        ``OptimizeResult`` carrying the trial minimum ``res.x``, its objective value ``res.fun``,
+        ``res.nit``, and ``res.accept`` (whether the step was accepted). The return value is
+        ignored; raise ``StopOptimization`` to stop early. Default None.
     interval: int
         Interval for how often to update the step size
     progressbar: bool
@@ -237,12 +240,20 @@ def basinhopping(
 
     # The wrapped minimizer is called once during construction of
     # BasinHoppingRunner, so run the callback
+    early_stop = False
     if callable(callback):
-        callback(bh.storage.minres.x, bh.storage.minres.fun, True)
+        try:
+            callback(
+                OptimizeResult(x=bh.storage.minres.x, fun=bh.storage.minres.fun, nit=0, accept=True)
+            )
+        except StopIteration:
+            early_stop = True
 
     # start main iteration loop
     count, i = 0, 0
     message = ["requested number of basinhopping iterations completed" " successfully"]
+    if early_stop:
+        message = ["callback requested early stop"]
 
     grad_norm_at_min = 0.0
     if use_jac:
@@ -261,6 +272,8 @@ def basinhopping(
 
     with progress:
         for i in range(niter):
+            if early_stop:
+                break
             if progressbar:
                 progress.reset(minimize_task, visible=True)
             new_global_min = bh.one_cycle()
@@ -277,12 +290,12 @@ def basinhopping(
             )
 
             if callable(callback):
-                # should we pass a copy of x?
-                val = callback(bh.xtrial, bh.energy_trial, bh.accept)
-                if val is not None:
-                    if val:
-                        message = ["callback function requested stop early by" "returning True"]
-                        break
+                res = OptimizeResult(x=bh.xtrial, fun=bh.energy_trial, nit=i + 1, accept=bh.accept)
+                try:
+                    callback(res)  # return ignored; raise StopOptimization to stop early
+                except StopIteration:
+                    message = ["callback requested early stop"]
+                    break
 
             count += 1
             if new_global_min:

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/constants.py

@@ -50,6 +50,9 @@ DE_STRATEGY_OPTIONS = (
 
 DE_INIT_OPTIONS = ("sobol", "halton", "latinhypercube", "random")
 
+# SciPy's direct solvers ignore the callback argument; the iterative root finders honor it.
+ROOT_METHODS_WITHOUT_CALLBACK = frozenset({"hybr", "lm"})
+
 MINIMIZE_MODE_KWARGS = {
     "nelder-mead": {
         "uses_grad": False,

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/differential_evolution.py

@@ -86,6 +86,11 @@ def differential_evolution(
         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.
+    callback : Callable, optional
+        Function called once per generation as ``callback(res)``, where ``res`` is an
+        ``OptimizeResult`` carrying the current best ``res.x`` and ``res.fun``, plus ``res.nit`` and
+        ``res.convergence``. The return value is ignored; raise ``StopOptimization`` to stop early.
+        Default None.
     rng : int, numpy.random.Generator, or None
         Seed / generator for reproducibility. Forwarded to scipy as the ``rng`` kwarg.
 
@@ -173,9 +178,8 @@ def differential_evolution(
         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")
+            res = OptimizeResult(x=xk, fun=f_val, nit=iter_counter[0], convergence=convergence)
+            callback(res)  # return ignored; raise StopOptimization to stop early
         return False
 
     scipy_kwargs: dict[str, Any] = {

better_optimize-0.4.2/better_optimize/exceptions.py

@@ -0,0 +1,10 @@
+class StopOptimization(StopIteration):
+    """Raise from inside a callback to request a graceful early stop.
+
+    Subclasses :class:`StopIteration` so that both SciPy's callback machinery and
+    ``better_optimize``'s own early-stopping wrapper halt on it. When raised, the solver returns
+    the best point seen so far with ``success=False``.
+    """
+
+
+__all__ = ["StopOptimization"]

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/minimize.py

@@ -17,7 +17,11 @@ from better_optimize.utilities import (
     kwargs_to_options,
     validate_provided_functions_minimize,
 )
-from better_optimize.wrapper import ObjectiveWrapper, optimizer_early_stopping_wrapper
+from better_optimize.wrapper import (
+    ObjectiveWrapper,
+    _compose_callback,
+    optimizer_early_stopping_wrapper,
+)
 
 
 def minimize(
@@ -32,6 +36,7 @@ def minimize(
     progressbar_update_interval: int = 1,
     verbose: bool = False,
     args: tuple | None = None,
+    callback: Callable[..., bool | None] | None = None,
     **optimizer_kwargs,
 ) -> OptimizeResult:
     """
@@ -61,6 +66,11 @@ def minimize(
     verbose: bool
         If True, warnings about the provided configuration are displayed. These warnings are intended to help users
         understand potential configuration issues that may affect the optimization process, but can be safely ignored.
+    callback: Callable, optional
+        Function called after each iteration as ``callback(res)``, where ``res`` is an
+        ``OptimizeResult`` carrying the current ``res.x``, ``res.fun``, and ``res.nit`` (plus
+        ``res.jac`` when a gradient is available). The return value is ignored; raise
+        ``StopOptimization`` to stop early. Default None.
     optimizer_kwargs
         Additional keyword arguments to pass to the optimizer
 
@@ -115,7 +125,7 @@ def minimize(
         jac=True if has_fused_f_and_grad or jac is not None else None,
         hess=None if not use_hess else lambda x: hess(x, *args),
         hessp=None if not use_hessp else lambda x, p: hessp(x, p, *args),
-        callback=objective.callback,
+        callback=_compose_callback(objective.callback, objective.callback_result, callback),
         **optimizer_kwargs,
     )
 

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/multi_optimize.py

@@ -476,7 +476,9 @@ def multi_optimize(
         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
+        Keyword arguments forwarded verbatim to solver on every call. Pass a per-iteration callback here (e.g.
+        ``solver_kwargs={"callback": fn}``); it fires on every run, and under the ``loky`` backend that run is a
+        separate process, so the callback and anything it closes over must be picklable.
     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.

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/root.py

@@ -1,3 +1,5 @@
+import logging
+
 from collections.abc import Callable
 from functools import partial
 
@@ -7,7 +9,7 @@ from rich.progress import Progress, TaskID
 from scipy.optimize import OptimizeResult
 from scipy.optimize import root as sp_root
 
-from better_optimize.constants import root_method
+from better_optimize.constants import ROOT_METHODS_WITHOUT_CALLBACK, root_method
 from better_optimize.utilities import (
     LRUCache1,
     check_f_is_fused_root,
@@ -17,7 +19,13 @@ from better_optimize.utilities import (
     kwargs_to_options,
     validate_provided_functions_root,
 )
-from better_optimize.wrapper import ObjectiveWrapper, optimizer_early_stopping_wrapper
+from better_optimize.wrapper import (
+    ObjectiveWrapper,
+    _compose_callback,
+    optimizer_early_stopping_wrapper,
+)
+
+_log = logging.getLogger(__name__)
 
 
 def root(
@@ -30,6 +38,7 @@ def root(
     progressbar_update_interval: int = 1,
     verbose: bool = False,
     args: tuple | None = None,
+    callback: Callable[..., bool | None] | None = None,
     **optimizer_kwargs,
 ) -> OptimizeResult:
     """
@@ -59,6 +68,11 @@ def root(
     verbose: bool
         If True, warnings about the provided configuration are displayed. These warnings are intended to help users
         understand potential configuration issues that may affect the optimization process, but can be safely ignored.
+    callback: Callable, optional
+        Function called after each iteration as ``callback(res)``, where ``res`` is an
+        ``OptimizeResult`` carrying the current ``res.x``, ``res.fun`` (the residual vector), and
+        ``res.nit``. The return value is ignored; raise ``StopOptimization`` to stop early. The
+        direct solvers ``hybr`` and ``lm`` ignore the callback and warn. Default None.
     optimizer_kwargs
         Additional keyword arguments to pass to the optimizer
 
@@ -93,12 +107,27 @@ def root(
         task=progress_task,
     )
 
+    if callback is not None and method in ROOT_METHODS_WITHOUT_CALLBACK:
+        _log.warning(
+            f"Method {method} does not support callbacks; the provided callback will be ignored."
+        )
+        callback = None
+
+    # Passing callback=None matches SciPy's default, so the direct methods never trigger SciPy's
+    # "does not accept callback" warning.
+    root_callback = (
+        _compose_callback(objective.callback, objective.callback_result, callback)
+        if callback is not None
+        else None
+    )
+
     f_optim = partial(
         sp_root,
         fun=objective,
         x0=x0,
         method=method,
         jac=True if has_fused_f_and_grad or jac is not None else None,
+        callback=root_callback,
         **optimizer_kwargs,
     )
 

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/sequential_optimize.py

@@ -265,7 +265,8 @@ def sequential_optimize(
         Initial guess for the first stage (unless the stage overrides via its own ``"x0"``).
     stages : list of dict
         Each dict must contain ``"solver": Callable`` and may include ``"name": str`` plus
-        any kwargs the solver accepts (e.g. ``"method"``, ``"bounds"``).
+        any kwargs the solver accepts (e.g. ``"method"``, ``"bounds"``, or a per-stage
+        ``"callback"`` forwarded to that stage's solver when it accepts one).
     args : tuple
         Extra positional args forwarded identically to every stage's objective call.
     progressbar : bool

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize/wrapper.py

@@ -114,6 +114,9 @@ class ObjectiveWrapper:
 
         self.use_rayleigh = self.use_jac and (self.use_hess or self.use_hessp)
 
+        # Counts iterations for the uniform OptimizeResult handed to user callbacks.
+        self.n_iter = 0
+
         self.previous_x = None
         if isinstance(progressbar, bool):
             self.progressbar = progressbar
@@ -189,6 +192,54 @@ class ObjectiveWrapper:
         if self.interrupted:
             raise StopIteration
 
+    def callback_result(self, *args) -> OptimizeResult:
+        """Build the uniform ``OptimizeResult`` handed to a user callback.
+
+        SciPy passes callbacks several different argument shapes depending on the method (``xk``;
+        ``xk, state``; an ``intermediate_result``; or ``x, f`` for root finding); collapse them into
+        one result with ``x``, ``fun``, and ``nit``. ``fun`` is the scalar objective for
+        minimization and the residual vector for root finding. ``jac`` is present when a fused
+        value-and-gradient objective supplies it.
+        """
+        self.n_iter += 1
+
+        state = None
+        fun = None
+        if len(args) == 1 and isinstance(args[0], OptimizeResult):
+            state = args[0]  # minimize new-protocol intermediate_result
+            x = np.asarray(state.x, dtype=float)
+        elif len(args) >= 2 and isinstance(args[1], OptimizeResult):
+            state = args[1]  # trust-constr legacy (xk, state)
+            x = np.asarray(args[0], dtype=float)
+        elif self.root and len(args) >= 2:
+            x = np.asarray(args[0], dtype=float)
+            fun = np.asarray(args[1], dtype=float)  # residual vector
+        else:
+            x = np.asarray(args[0], dtype=float)
+
+        nit = self.n_iter
+        jac = None
+        if state is not None:
+            # Prefer SciPy's own numbers when it gave us a populated result.
+            fun = getattr(state, "fun", fun)
+            nit = int(getattr(state, "nit", nit))
+            jac = getattr(state, "jac", None)
+
+        if fun is None:
+            out = self.f(x)
+            if self.has_fused_f_and_grad:
+                fun, grad = out
+                if jac is None and not self.root:
+                    jac = grad
+            else:
+                fun = out
+            fun = fun if self.root else float(np.asarray(fun).reshape(()))
+
+        res = OptimizeResult(x=x, fun=fun, nit=nit)
+        if jac is not None:
+            res.jac = jac
+        return res
+
     def update_progressbar(
         self, value: float, grad: np.float64 = None, rayleigh: float | None = None, completed=False
     ) -> None:
@@ -247,6 +298,38 @@ class ObjectiveWrapper:
         )
 
 
+def _compose_callback(
+    internal: Callable[..., None],
+    result_builder: Callable[..., OptimizeResult],
+    user: Callable | None,
+) -> Callable:
+    """Bundle the internal early-stop hook with an optional user-supplied callback.
+
+    The internal hook runs first, so ``maxeval`` and ``KeyboardInterrupt`` halting stays intact.
+    The user callback then receives a uniform ``OptimizeResult`` built by ``result_builder`` from
+    whatever SciPy passed. Its return value is ignored; it requests an early stop by raising
+    :class:`~better_optimize.exceptions.StopOptimization` (or any ``StopIteration``).
+
+    Parameters
+    ----------
+    internal : callable
+        The :meth:`ObjectiveWrapper.callback` early-stop hook.
+    result_builder : callable
+        Normalizes SciPy's per-method callback arguments into a uniform ``OptimizeResult``
+        (typically :meth:`ObjectiveWrapper.callback_result`).
+    user : callable or None
+        The user-supplied callback. When None, ``internal`` is returned unchanged.
+    """
+    if user is None:
+        return internal
+
+    def composite(*args):
+        internal(*args)
+        user(result_builder(*args))
+
+    return composite
+
+
 def optimizer_early_stopping_wrapper(f_optim: partial):
     objective = f_optim.keywords["fun"]
 

{better_optimize-0.4.1 → better_optimize-0.4.2}/better_optimize.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better_optimize
-Version: 0.4.1
+Version: 0.4.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
@@ -89,6 +89,19 @@ All optimization routines in `better_optimize` can display a rich, informative p
 - Optionally accepts and stores failed minimizer results if they improve the global minimum.
 - Useful for noisy or non-smooth objective functions where local minimization may occasionally fail.
 
+### 6. Uniform Callback API
+
+scipy passes callbacks a different argument for almost every method: `callback(xk)`, `callback(xk, state)`,
+`callback(intermediate_result)`, or `callback(x, f)` for root finding. `better_optimize` normalizes them to a single
+`callback(res)`, where `res` is an `OptimizeResult` with the current `res.x`, `res.fun`, and `res.nit` — plus `res.jac`
+when a gradient is available, and solver-specific fields like `res.accept` (basinhopping) or `res.convergence`
+(differential evolution).
+
+- The return value is ignored, so a callback can report a value (an ELBO, a logged loss) without stopping the run.
+- Raise `StopOptimization` to stop early; the best result so far is returned with `success=False`.
+- The same callback works across `minimize`, `root`, `basinhopping`, and `differential_evolution`. `hybr` and `lm` are
+  the exception — scipy never calls a callback for them, so it is ignored with a warning.
+
 ---
 
 ## Example Usage
@@ -96,6 +109,7 @@ All optimization routines in `better_optimize` can display a rich, informative p
 ### Simple Example
 
 ```python
+import numpy as np
 from better_optimize import minimize
 
 def rosenbrock(x):
@@ -103,7 +117,7 @@ def rosenbrock(x):
 
 result = minimize(
     rosenbrock,
-    x0=[-1, 2],
+    x0=np.array([-1.0, 2.0]),
     method="L-BFGS-B",
     tol=1e-6,
     maxiter=1000,
@@ -119,6 +133,36 @@ result = minimize(
 
 The result object is a standard `OptimizeResult` from `scipy.optimize`, so there are no surprises there!
 
+### Callbacks and Early Stopping
+
+Pass a `callback` and it runs after each iteration with an `OptimizeResult`. Its return value is ignored; raise
+`StopOptimization` to stop and return the best result so far.
+
+```python
+import numpy as np
+from better_optimize import minimize, StopOptimization
+
+def rosenbrock(x):
+    return sum(100.0*(x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)
+
+history = []
+
+def callback(res):
+    history.append(res.fun)  # res.x, res.fun, res.nit; res.jac when available
+    if res.fun < 1e-8:
+        raise StopOptimization
+
+result = minimize(
+    rosenbrock,
+    x0=np.array([-1.0, 2.0]),
+    method="L-BFGS-B",
+    callback=callback,
+)
+```
+
+The same callback works for `root` (`res.fun` is the residual vector), `basinhopping` (`res.accept`), and
+`differential_evolution` (`res.convergence`).
+
 ### Triple-Fused Function using Pytensor
 
 ```python
@@ -155,6 +199,7 @@ Real-world objectives often have multiple local minima. A common workaround is t
 the optimizer and keep the best result. `better_optimize` makes this painless with `multi_optimize`:
 
 ```python
+import numpy as np
 from better_optimize import minimize, multi_optimize
 
 def rosenbrock(x):
@@ -179,6 +224,9 @@ print(result.fun_best)   # Best objective value
 result.summary()          # Rich table of all runs, ranked
 ```
 
+> The `loky` (process) backend needs an `if __name__ == "__main__":` guard when run as a script on macOS or Windows.
+> Notebooks and the `threading`/`sequential` backends don't.
+
 `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.