Coverage for /usr/lib/python3/dist-packages/scipy/optimize/__init__.py: 100%
29 statements
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-14 15:55 +0200
1"""
2=====================================================
3Optimization and root finding (:mod:`scipy.optimize`)
4=====================================================
6.. currentmodule:: scipy.optimize
8.. toctree::
9 :hidden:
11 optimize.cython_optimize
13SciPy ``optimize`` provides functions for minimizing (or maximizing)
14objective functions, possibly subject to constraints. It includes
15solvers for nonlinear problems (with support for both local and global
16optimization algorithms), linear programing, constrained
17and nonlinear least-squares, root finding, and curve fitting.
19Common functions and objects, shared across different solvers, are:
21.. autosummary::
22 :toctree: generated/
24 show_options - Show specific options optimization solvers.
25 OptimizeResult - The optimization result returned by some optimizers.
26 OptimizeWarning - The optimization encountered problems.
29Optimization
30============
32Scalar functions optimization
33-----------------------------
35.. autosummary::
36 :toctree: generated/
38 minimize_scalar - Interface for minimizers of univariate functions
40The `minimize_scalar` function supports the following methods:
42.. toctree::
44 optimize.minimize_scalar-brent
45 optimize.minimize_scalar-bounded
46 optimize.minimize_scalar-golden
48Local (multivariate) optimization
49---------------------------------
51.. autosummary::
52 :toctree: generated/
54 minimize - Interface for minimizers of multivariate functions.
56The `minimize` function supports the following methods:
58.. toctree::
60 optimize.minimize-neldermead
61 optimize.minimize-powell
62 optimize.minimize-cg
63 optimize.minimize-bfgs
64 optimize.minimize-newtoncg
65 optimize.minimize-lbfgsb
66 optimize.minimize-tnc
67 optimize.minimize-cobyla
68 optimize.minimize-slsqp
69 optimize.minimize-trustconstr
70 optimize.minimize-dogleg
71 optimize.minimize-trustncg
72 optimize.minimize-trustkrylov
73 optimize.minimize-trustexact
75Constraints are passed to `minimize` function as a single object or
76as a list of objects from the following classes:
78.. autosummary::
79 :toctree: generated/
81 NonlinearConstraint - Class defining general nonlinear constraints.
82 LinearConstraint - Class defining general linear constraints.
84Simple bound constraints are handled separately and there is a special class
85for them:
87.. autosummary::
88 :toctree: generated/
90 Bounds - Bound constraints.
92Quasi-Newton strategies implementing `HessianUpdateStrategy`
93interface can be used to approximate the Hessian in `minimize`
94function (available only for the 'trust-constr' method). Available
95quasi-Newton methods implementing this interface are:
97.. autosummary::
98 :toctree: generated/
100 BFGS - Broyden-Fletcher-Goldfarb-Shanno (BFGS) Hessian update strategy.
101 SR1 - Symmetric-rank-1 Hessian update strategy.
103Global optimization
104-------------------
106.. autosummary::
107 :toctree: generated/
109 basinhopping - Basinhopping stochastic optimizer.
110 brute - Brute force searching optimizer.
111 differential_evolution - Stochastic optimizer using differential evolution.
113 shgo - Simplicial homology global optimizer.
114 dual_annealing - Dual annealing stochastic optimizer.
115 direct - DIRECT (Dividing Rectangles) optimizer.
117Least-squares and curve fitting
118===============================
120Nonlinear least-squares
121-----------------------
123.. autosummary::
124 :toctree: generated/
126 least_squares - Solve a nonlinear least-squares problem with bounds on the variables.
128Linear least-squares
129--------------------
131.. autosummary::
132 :toctree: generated/
134 nnls - Linear least-squares problem with non-negativity constraint.
135 lsq_linear - Linear least-squares problem with bound constraints.
137Curve fitting
138-------------
140.. autosummary::
141 :toctree: generated/
143 curve_fit -- Fit curve to a set of points.
145Root finding
146============
148Scalar functions
149----------------
150.. autosummary::
151 :toctree: generated/
153 root_scalar - Unified interface for nonlinear solvers of scalar functions.
154 brentq - quadratic interpolation Brent method.
155 brenth - Brent method, modified by Harris with hyperbolic extrapolation.
156 ridder - Ridder's method.
157 bisect - Bisection method.
158 newton - Newton's method (also Secant and Halley's methods).
159 toms748 - Alefeld, Potra & Shi Algorithm 748.
160 RootResults - The root finding result returned by some root finders.
162The `root_scalar` function supports the following methods:
164.. toctree::
166 optimize.root_scalar-brentq
167 optimize.root_scalar-brenth
168 optimize.root_scalar-bisect
169 optimize.root_scalar-ridder
170 optimize.root_scalar-newton
171 optimize.root_scalar-toms748
172 optimize.root_scalar-secant
173 optimize.root_scalar-halley
177The table below lists situations and appropriate methods, along with
178*asymptotic* convergence rates per iteration (and per function evaluation)
179for successful convergence to a simple root(*).
180Bisection is the slowest of them all, adding one bit of accuracy for each
181function evaluation, but is guaranteed to converge.
182The other bracketing methods all (eventually) increase the number of accurate
183bits by about 50% for every function evaluation.
184The derivative-based methods, all built on `newton`, can converge quite quickly
185if the initial value is close to the root. They can also be applied to
186functions defined on (a subset of) the complex plane.
188+-------------+----------+----------+-----------+-------------+-------------+----------------+
189| Domain of f | Bracket? | Derivatives? | Solvers | Convergence |
190+ + +----------+-----------+ +-------------+----------------+
191| | | `fprime` | `fprime2` | | Guaranteed? | Rate(s)(*) |
192+=============+==========+==========+===========+=============+=============+================+
193| `R` | Yes | N/A | N/A | - bisection | - Yes | - 1 "Linear" |
194| | | | | - brentq | - Yes | - >=1, <= 1.62 |
195| | | | | - brenth | - Yes | - >=1, <= 1.62 |
196| | | | | - ridder | - Yes | - 2.0 (1.41) |
197| | | | | - toms748 | - Yes | - 2.7 (1.65) |
198+-------------+----------+----------+-----------+-------------+-------------+----------------+
199| `R` or `C` | No | No | No | secant | No | 1.62 (1.62) |
200+-------------+----------+----------+-----------+-------------+-------------+----------------+
201| `R` or `C` | No | Yes | No | newton | No | 2.00 (1.41) |
202+-------------+----------+----------+-----------+-------------+-------------+----------------+
203| `R` or `C` | No | Yes | Yes | halley | No | 3.00 (1.44) |
204+-------------+----------+----------+-----------+-------------+-------------+----------------+
206.. seealso::
208 `scipy.optimize.cython_optimize` -- Typed Cython versions of root finding functions
210Fixed point finding:
212.. autosummary::
213 :toctree: generated/
215 fixed_point - Single-variable fixed-point solver.
217Multidimensional
218----------------
220.. autosummary::
221 :toctree: generated/
223 root - Unified interface for nonlinear solvers of multivariate functions.
225The `root` function supports the following methods:
227.. toctree::
229 optimize.root-hybr
230 optimize.root-lm
231 optimize.root-broyden1
232 optimize.root-broyden2
233 optimize.root-anderson
234 optimize.root-linearmixing
235 optimize.root-diagbroyden
236 optimize.root-excitingmixing
237 optimize.root-krylov
238 optimize.root-dfsane
240Linear programming / MILP
241=========================
243.. autosummary::
244 :toctree: generated/
246 milp -- Mixed integer linear programming.
247 linprog -- Unified interface for minimizers of linear programming problems.
249The `linprog` function supports the following methods:
251.. toctree::
253 optimize.linprog-simplex
254 optimize.linprog-interior-point
255 optimize.linprog-revised_simplex
256 optimize.linprog-highs-ipm
257 optimize.linprog-highs-ds
258 optimize.linprog-highs
260The simplex, interior-point, and revised simplex methods support callback
261functions, such as:
263.. autosummary::
264 :toctree: generated/
266 linprog_verbose_callback -- Sample callback function for linprog (simplex).
268Assignment problems
269===================
271.. autosummary::
272 :toctree: generated/
274 linear_sum_assignment -- Solves the linear-sum assignment problem.
275 quadratic_assignment -- Solves the quadratic assignment problem.
277The `quadratic_assignment` function supports the following methods:
279.. toctree::
281 optimize.qap-faq
282 optimize.qap-2opt
284Utilities
285=========
287Finite-difference approximation
288-------------------------------
290.. autosummary::
291 :toctree: generated/
293 approx_fprime - Approximate the gradient of a scalar function.
294 check_grad - Check the supplied derivative using finite differences.
297Line search
298-----------
300.. autosummary::
301 :toctree: generated/
303 bracket - Bracket a minimum, given two starting points.
304 line_search - Return a step that satisfies the strong Wolfe conditions.
306Hessian approximation
307---------------------
309.. autosummary::
310 :toctree: generated/
312 LbfgsInvHessProduct - Linear operator for L-BFGS approximate inverse Hessian.
313 HessianUpdateStrategy - Interface for implementing Hessian update strategies
315Benchmark problems
316------------------
318.. autosummary::
319 :toctree: generated/
321 rosen - The Rosenbrock function.
322 rosen_der - The derivative of the Rosenbrock function.
323 rosen_hess - The Hessian matrix of the Rosenbrock function.
324 rosen_hess_prod - Product of the Rosenbrock Hessian with a vector.
326Legacy functions
327================
329The functions below are not recommended for use in new scripts;
330all of these methods are accessible via a newer, more consistent
331interfaces, provided by the interfaces above.
333Optimization
334------------
336General-purpose multivariate methods:
338.. autosummary::
339 :toctree: generated/
341 fmin - Nelder-Mead Simplex algorithm.
342 fmin_powell - Powell's (modified) conjugate direction method.
343 fmin_cg - Non-linear (Polak-Ribiere) conjugate gradient algorithm.
344 fmin_bfgs - Quasi-Newton method (Broydon-Fletcher-Goldfarb-Shanno).
345 fmin_ncg - Line-search Newton Conjugate Gradient.
347Constrained multivariate methods:
349.. autosummary::
350 :toctree: generated/
352 fmin_l_bfgs_b - Zhu, Byrd, and Nocedal's constrained optimizer.
353 fmin_tnc - Truncated Newton code.
354 fmin_cobyla - Constrained optimization by linear approximation.
355 fmin_slsqp - Minimization using sequential least-squares programming.
357Univariate (scalar) minimization methods:
359.. autosummary::
360 :toctree: generated/
362 fminbound - Bounded minimization of a scalar function.
363 brent - 1-D function minimization using Brent method.
364 golden - 1-D function minimization using Golden Section method.
366Least-squares
367-------------
369.. autosummary::
370 :toctree: generated/
372 leastsq - Minimize the sum of squares of M equations in N unknowns.
374Root finding
375------------
377General nonlinear solvers:
379.. autosummary::
380 :toctree: generated/
382 fsolve - Non-linear multivariable equation solver.
383 broyden1 - Broyden's first method.
384 broyden2 - Broyden's second method.
386Large-scale nonlinear solvers:
388.. autosummary::
389 :toctree: generated/
391 newton_krylov
392 anderson
394 BroydenFirst
395 InverseJacobian
396 KrylovJacobian
398Simple iteration solvers:
400.. autosummary::
401 :toctree: generated/
403 excitingmixing
404 linearmixing
405 diagbroyden
407""" # noqa: E501
409from ._optimize import *
410from ._minimize import *
411from ._root import *
412from ._root_scalar import *
413from ._minpack_py import *
414from ._zeros_py import *
415from ._lbfgsb_py import fmin_l_bfgs_b, LbfgsInvHessProduct
416from ._tnc import fmin_tnc
417from ._cobyla_py import fmin_cobyla
418from ._nonlin import *
419from ._slsqp_py import fmin_slsqp
420from ._nnls import nnls
421from ._basinhopping import basinhopping
422from ._linprog import linprog, linprog_verbose_callback
423from ._lsap import linear_sum_assignment
424from ._differentialevolution import differential_evolution
425from ._lsq import least_squares, lsq_linear
426from ._constraints import (NonlinearConstraint,
427 LinearConstraint,
428 Bounds)
429from ._hessian_update_strategy import HessianUpdateStrategy, BFGS, SR1
430from ._shgo import shgo
431from ._dual_annealing import dual_annealing
432from ._qap import quadratic_assignment
433from ._direct_py import direct
434from ._milp import milp
436# Deprecated namespaces, to be removed in v2.0.0
437from . import (
438 cobyla, lbfgsb, linesearch, minpack, minpack2, moduleTNC, nonlin, optimize,
439 slsqp, tnc, zeros
440)
442__all__ = [s for s in dir() if not s.startswith('_')]
444from scipy._lib._testutils import PytestTester
445test = PytestTester(__name__)
446del PytestTester