Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/optimize/__init__.py: 100%
29 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-12 06:31 +0000
1"""
2=====================================================
3Optimization and root finding (:mod:`scipy.optimize`)
4=====================================================
6.. currentmodule:: scipy.optimize
8SciPy ``optimize`` provides functions for minimizing (or maximizing)
9objective functions, possibly subject to constraints. It includes
10solvers for nonlinear problems (with support for both local and global
11optimization algorithms), linear programing, constrained
12and nonlinear least-squares, root finding, and curve fitting.
14Common functions and objects, shared across different solvers, are:
16.. autosummary::
17 :toctree: generated/
19 show_options - Show specific options optimization solvers.
20 OptimizeResult - The optimization result returned by some optimizers.
21 OptimizeWarning - The optimization encountered problems.
24Optimization
25============
27Scalar functions optimization
28-----------------------------
30.. autosummary::
31 :toctree: generated/
33 minimize_scalar - Interface for minimizers of univariate functions
35The `minimize_scalar` function supports the following methods:
37.. toctree::
39 optimize.minimize_scalar-brent
40 optimize.minimize_scalar-bounded
41 optimize.minimize_scalar-golden
43Local (multivariate) optimization
44---------------------------------
46.. autosummary::
47 :toctree: generated/
49 minimize - Interface for minimizers of multivariate functions.
51The `minimize` function supports the following methods:
53.. toctree::
55 optimize.minimize-neldermead
56 optimize.minimize-powell
57 optimize.minimize-cg
58 optimize.minimize-bfgs
59 optimize.minimize-newtoncg
60 optimize.minimize-lbfgsb
61 optimize.minimize-tnc
62 optimize.minimize-cobyla
63 optimize.minimize-slsqp
64 optimize.minimize-trustconstr
65 optimize.minimize-dogleg
66 optimize.minimize-trustncg
67 optimize.minimize-trustkrylov
68 optimize.minimize-trustexact
70Constraints are passed to `minimize` function as a single object or
71as a list of objects from the following classes:
73.. autosummary::
74 :toctree: generated/
76 NonlinearConstraint - Class defining general nonlinear constraints.
77 LinearConstraint - Class defining general linear constraints.
79Simple bound constraints are handled separately and there is a special class
80for them:
82.. autosummary::
83 :toctree: generated/
85 Bounds - Bound constraints.
87Quasi-Newton strategies implementing `HessianUpdateStrategy`
88interface can be used to approximate the Hessian in `minimize`
89function (available only for the 'trust-constr' method). Available
90quasi-Newton methods implementing this interface are:
92.. autosummary::
93 :toctree: generated/
95 BFGS - Broyden-Fletcher-Goldfarb-Shanno (BFGS) Hessian update strategy.
96 SR1 - Symmetric-rank-1 Hessian update strategy.
98Global optimization
99-------------------
101.. autosummary::
102 :toctree: generated/
104 basinhopping - Basinhopping stochastic optimizer.
105 brute - Brute force searching optimizer.
106 differential_evolution - Stochastic optimizer using differential evolution.
108 shgo - Simplicial homology global optimizer.
109 dual_annealing - Dual annealing stochastic optimizer.
110 direct - DIRECT (Dividing Rectangles) optimizer.
112Least-squares and curve fitting
113===============================
115Nonlinear least-squares
116-----------------------
118.. autosummary::
119 :toctree: generated/
121 least_squares - Solve a nonlinear least-squares problem with bounds on the variables.
123Linear least-squares
124--------------------
126.. autosummary::
127 :toctree: generated/
129 nnls - Linear least-squares problem with non-negativity constraint.
130 lsq_linear - Linear least-squares problem with bound constraints.
132Curve fitting
133-------------
135.. autosummary::
136 :toctree: generated/
138 curve_fit -- Fit curve to a set of points.
140Root finding
141============
143Scalar functions
144----------------
145.. autosummary::
146 :toctree: generated/
148 root_scalar - Unified interface for nonlinear solvers of scalar functions.
149 brentq - quadratic interpolation Brent method.
150 brenth - Brent method, modified by Harris with hyperbolic extrapolation.
151 ridder - Ridder's method.
152 bisect - Bisection method.
153 newton - Newton's method (also Secant and Halley's methods).
154 toms748 - Alefeld, Potra & Shi Algorithm 748.
155 RootResults - The root finding result returned by some root finders.
157The `root_scalar` function supports the following methods:
159.. toctree::
161 optimize.root_scalar-brentq
162 optimize.root_scalar-brenth
163 optimize.root_scalar-bisect
164 optimize.root_scalar-ridder
165 optimize.root_scalar-newton
166 optimize.root_scalar-toms748
167 optimize.root_scalar-secant
168 optimize.root_scalar-halley
172The table below lists situations and appropriate methods, along with
173*asymptotic* convergence rates per iteration (and per function evaluation)
174for successful convergence to a simple root(*).
175Bisection is the slowest of them all, adding one bit of accuracy for each
176function evaluation, but is guaranteed to converge.
177The other bracketing methods all (eventually) increase the number of accurate
178bits by about 50% for every function evaluation.
179The derivative-based methods, all built on `newton`, can converge quite quickly
180if the initial value is close to the root. They can also be applied to
181functions defined on (a subset of) the complex plane.
183+-------------+----------+----------+-----------+-------------+-------------+----------------+
184| Domain of f | Bracket? | Derivatives? | Solvers | Convergence |
185+ + +----------+-----------+ +-------------+----------------+
186| | | `fprime` | `fprime2` | | Guaranteed? | Rate(s)(*) |
187+=============+==========+==========+===========+=============+=============+================+
188| `R` | Yes | N/A | N/A | - bisection | - Yes | - 1 "Linear" |
189| | | | | - brentq | - Yes | - >=1, <= 1.62 |
190| | | | | - brenth | - Yes | - >=1, <= 1.62 |
191| | | | | - ridder | - Yes | - 2.0 (1.41) |
192| | | | | - toms748 | - Yes | - 2.7 (1.65) |
193+-------------+----------+----------+-----------+-------------+-------------+----------------+
194| `R` or `C` | No | No | No | secant | No | 1.62 (1.62) |
195+-------------+----------+----------+-----------+-------------+-------------+----------------+
196| `R` or `C` | No | Yes | No | newton | No | 2.00 (1.41) |
197+-------------+----------+----------+-----------+-------------+-------------+----------------+
198| `R` or `C` | No | Yes | Yes | halley | No | 3.00 (1.44) |
199+-------------+----------+----------+-----------+-------------+-------------+----------------+
201.. seealso::
203 `scipy.optimize.cython_optimize` -- Typed Cython versions of zeros functions
205Fixed point finding:
207.. autosummary::
208 :toctree: generated/
210 fixed_point - Single-variable fixed-point solver.
212Multidimensional
213----------------
215.. autosummary::
216 :toctree: generated/
218 root - Unified interface for nonlinear solvers of multivariate functions.
220The `root` function supports the following methods:
222.. toctree::
224 optimize.root-hybr
225 optimize.root-lm
226 optimize.root-broyden1
227 optimize.root-broyden2
228 optimize.root-anderson
229 optimize.root-linearmixing
230 optimize.root-diagbroyden
231 optimize.root-excitingmixing
232 optimize.root-krylov
233 optimize.root-dfsane
235Linear programming / MILP
236=========================
238.. autosummary::
239 :toctree: generated/
241 milp -- Mixed integer linear programming.
242 linprog -- Unified interface for minimizers of linear programming problems.
244The `linprog` function supports the following methods:
246.. toctree::
248 optimize.linprog-simplex
249 optimize.linprog-interior-point
250 optimize.linprog-revised_simplex
251 optimize.linprog-highs-ipm
252 optimize.linprog-highs-ds
253 optimize.linprog-highs
255The simplex, interior-point, and revised simplex methods support callback
256functions, such as:
258.. autosummary::
259 :toctree: generated/
261 linprog_verbose_callback -- Sample callback function for linprog (simplex).
263Assignment problems
264===================
266.. autosummary::
267 :toctree: generated/
269 linear_sum_assignment -- Solves the linear-sum assignment problem.
270 quadratic_assignment -- Solves the quadratic assignment problem.
272The `quadratic_assignment` function supports the following methods:
274.. toctree::
276 optimize.qap-faq
277 optimize.qap-2opt
279Utilities
280=========
282Finite-difference approximation
283-------------------------------
285.. autosummary::
286 :toctree: generated/
288 approx_fprime - Approximate the gradient of a scalar function.
289 check_grad - Check the supplied derivative using finite differences.
292Line search
293-----------
295.. autosummary::
296 :toctree: generated/
298 bracket - Bracket a minimum, given two starting points.
299 line_search - Return a step that satisfies the strong Wolfe conditions.
301Hessian approximation
302---------------------
304.. autosummary::
305 :toctree: generated/
307 LbfgsInvHessProduct - Linear operator for L-BFGS approximate inverse Hessian.
308 HessianUpdateStrategy - Interface for implementing Hessian update strategies
310Benchmark problems
311------------------
313.. autosummary::
314 :toctree: generated/
316 rosen - The Rosenbrock function.
317 rosen_der - The derivative of the Rosenbrock function.
318 rosen_hess - The Hessian matrix of the Rosenbrock function.
319 rosen_hess_prod - Product of the Rosenbrock Hessian with a vector.
321Legacy functions
322================
324The functions below are not recommended for use in new scripts;
325all of these methods are accessible via a newer, more consistent
326interfaces, provided by the interfaces above.
328Optimization
329------------
331General-purpose multivariate methods:
333.. autosummary::
334 :toctree: generated/
336 fmin - Nelder-Mead Simplex algorithm.
337 fmin_powell - Powell's (modified) level set method.
338 fmin_cg - Non-linear (Polak-Ribiere) conjugate gradient algorithm.
339 fmin_bfgs - Quasi-Newton method (Broydon-Fletcher-Goldfarb-Shanno).
340 fmin_ncg - Line-search Newton Conjugate Gradient.
342Constrained multivariate methods:
344.. autosummary::
345 :toctree: generated/
347 fmin_l_bfgs_b - Zhu, Byrd, and Nocedal's constrained optimizer.
348 fmin_tnc - Truncated Newton code.
349 fmin_cobyla - Constrained optimization by linear approximation.
350 fmin_slsqp - Minimization using sequential least-squares programming.
352Univariate (scalar) minimization methods:
354.. autosummary::
355 :toctree: generated/
357 fminbound - Bounded minimization of a scalar function.
358 brent - 1-D function minimization using Brent method.
359 golden - 1-D function minimization using Golden Section method.
361Least-squares
362-------------
364.. autosummary::
365 :toctree: generated/
367 leastsq - Minimize the sum of squares of M equations in N unknowns.
369Root finding
370------------
372General nonlinear solvers:
374.. autosummary::
375 :toctree: generated/
377 fsolve - Non-linear multivariable equation solver.
378 broyden1 - Broyden's first method.
379 broyden2 - Broyden's second method.
381Large-scale nonlinear solvers:
383.. autosummary::
384 :toctree: generated/
386 newton_krylov
387 anderson
389 BroydenFirst
390 InverseJacobian
391 KrylovJacobian
393Simple iteration solvers:
395.. autosummary::
396 :toctree: generated/
398 excitingmixing
399 linearmixing
400 diagbroyden
402"""
404from ._optimize import *
405from ._minimize import *
406from ._root import *
407from ._root_scalar import *
408from ._minpack_py import *
409from ._zeros_py import *
410from ._lbfgsb_py import fmin_l_bfgs_b, LbfgsInvHessProduct
411from ._tnc import fmin_tnc
412from ._cobyla_py import fmin_cobyla
413from ._nonlin import *
414from ._slsqp_py import fmin_slsqp
415from ._nnls import nnls
416from ._basinhopping import basinhopping
417from ._linprog import linprog, linprog_verbose_callback
418from ._lsap import linear_sum_assignment
419from ._differentialevolution import differential_evolution
420from ._lsq import least_squares, lsq_linear
421from ._constraints import (NonlinearConstraint,
422 LinearConstraint,
423 Bounds)
424from ._hessian_update_strategy import HessianUpdateStrategy, BFGS, SR1
425from ._shgo import shgo
426from ._dual_annealing import dual_annealing
427from ._qap import quadratic_assignment
428from ._direct_py import direct
429from ._milp import milp
431# Deprecated namespaces, to be removed in v2.0.0
432from . import (
433 cobyla, lbfgsb, linesearch, minpack, minpack2, moduleTNC, nonlin, optimize,
434 slsqp, tnc, zeros
435)
437__all__ = [s for s in dir() if not s.startswith('_')]
439from scipy._lib._testutils import PytestTester
440test = PytestTester(__name__)
441del PytestTester