Recommended Free Tools
scipy.optimize.leastsq fits a nonlinear model by minimizing the sum of squared residuals between observed values and model predictions. Give it a function that returns one residual per observation, an initial parameter guess, and any fixed data the function needs. The method is a local iterative solver: the starting guess and model formulation matter, and you should check its termination status rather than treating every returned parameter vector as a successful fit.
What `leastsq` minimizes
For a parameter vector x, your function returns a vector of residuals. SciPy seeks parameters that minimize the sum of those residuals squared. For data fitting, a residual is commonly the observed value minus the model prediction:
As an Amazon Associate I earn from qualifying purchases.
residual = observed - model(xdata, parameters)
Return the residual vector itself—not a scalar sum of squares and not a vector you have already squared. The routine performs the squaring and summation. It expects floating-point residuals without NaNs, and the number of residuals, M, must be at least the number of unknown parameters, N.
Fit a nonlinear model step by step
This example fits an exponential model, y = a * exp(b * t) + c, to measured values. The parameter vector contains a, b, and c; time and observations are fixed data passed through args.
#1 Best Overall
- Import the solver and prepare the observations.
import numpy as np from scipy.optimize import leastsq t = np.array([0.0, 1.0, 2.0, 3.0, 4.0]) y_observed = np.array([1.1, 2.0, 3.5, 6.1, 10.8]) - Define the model and return one residual per observation.
def model(t, a, b, c): return a * np.exp(b * t) + c def residuals(params, t, y): a, b, c = params return y - model(t, a, b, c)The parameter vector is the first argument to the residual function. Additional fixed values belong in
args. - Choose an initial estimate and call the solver.
x0 = np.array([1.0, 0.5, 0.0]) result = leastsq( residuals, x0, args=(t, y_observed), full_output=True, ) params, cov_x, infodict, mesg, ier = result print(params) print(ier, mesg)x0is the starting estimate, not a constraint or a guarantee of the final answer. The example illustrates the API; whether a particular fit is appropriate depends on the data and model. - Check the termination result before using the fit.
The documented solution-found status values are
ierequal to 1, 2, 3, or 4. Readmesgand inspect diagnostics ininfodictas well. If the call fails, the returned parameter vector is the last iterate, not a confirmed solution.Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Supply a Jacobian when appropriate
You can pass Dfun to provide the Jacobian of the residual function, replacing SciPy’s numerical estimation. The Jacobian must correspond to the residuals your function returns. The col_deriv option indicates whether derivatives are supplied down columns rather than across rows; set it to match the orientation of your Jacobian. An orientation mismatch can produce incorrect results or errors.
Rank #3
Set stopping and evaluation options deliberately
The SciPy v1.18.0 reference documents these controls. They govern stopping behavior and scaling, not a promise that the fitted parameters are accurate.
ftolsets a stopping criterion based on change in the objective function.xtolsets a stopping criterion based on change in the solution.gtolsets a criterion based on residual/Jacobian orthogonality.maxfevlimits function evaluations. Its documented default is200 * (N + 1)whenDfunis not supplied, and100 * (N + 1)when it is supplied.diagaccepts positive scale factors for the variables. Scaling can matter when parameters have very different magnitudes.factorcontrols the initial step bound and should be in the interval(0.1, 100).
Defaults and behavior can change between SciPy releases; check the API reference matching the version installed in your environment. These details refer to the SciPy v1.18.0 reference.
Rank #4
Interpret the returned values and covariance estimate
Without full_output=True, the routine returns the solution and an integer termination flag. With that option enabled, it also returns cov_x, infodict, mesg, and ier, as shown above. Use the status and message to distinguish a successful termination from a last iterate returned after failure.
cov_x is an inverse-Hessian/Jacobian-based approximation, not by itself a parameter covariance matrix. SciPy’s reference says to multiply it by the residual variance to obtain a covariance estimate. If cov_x is None, the approximation is unavailable because the curvature is numerically flat in at least one parameter direction. This calculation is not a general guarantee of parameter uncertainty.
When to use another SciPy fitting API
| Task | API | Why it may fit better |
|---|---|---|
| Unbounded residual least squares with the MINPACK interface | leastsq |
A focused wrapper around MINPACK’s lmdif and lmder algorithms. |
| Parameter bounds or robust loss functions | least_squares |
Supports bounds and selectable methods and loss functions; its lm method is also MINPACK-based. |
Fit a named model function to observed xdata and ydata |
curve_fit |
Provides a higher-level model-fitting interface with parameter guesses, bounds, and method selection. Its lm method routes to leastsq; other methods route to least_squares. |
These API distinctions and the defaults above are documented in SciPy’s v1.18.0 online reference; consult the documentation for your installed release when relying on specific options or defaults.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
