Mercurial > octave-antonio

comparison scripts/optimization/fsolve.m @ 20165:f1d0f506ee78 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Update more docstrings to have one sentence summary as first line. Reviewed optimization, polynomial, signal script directories. * scripts/optimization/fminbnd.m, scripts/optimization/fminsearch.m, scripts/optimization/fminunc.m, scripts/optimization/fsolve.m, scripts/optimization/fzero.m, scripts/optimization/glpk.m, scripts/optimization/lsqnonneg.m, scripts/optimization/pqpnonneg.m, scripts/optimization/qp.m, scripts/optimization/sqp.m, scripts/polynomial/compan.m, scripts/polynomial/mkpp.m, scripts/polynomial/mpoles.m, scripts/polynomial/pchip.m, scripts/polynomial/poly.m, scripts/polynomial/polyaffine.m, scripts/polynomial/polyder.m, scripts/polynomial/polyeig.m, scripts/polynomial/polyfit.m, scripts/polynomial/polygcd.m, scripts/polynomial/polyint.m, scripts/polynomial/polyout.m, scripts/polynomial/polyval.m, scripts/polynomial/ppder.m, scripts/polynomial/ppint.m, scripts/polynomial/ppjumps.m, scripts/polynomial/ppval.m, scripts/polynomial/residue.m, scripts/polynomial/roots.m, scripts/polynomial/spline.m, scripts/polynomial/splinefit.m, scripts/polynomial/unmkpp.m, scripts/signal/arch_fit.m, scripts/signal/arch_rnd.m, scripts/signal/arma_rnd.m, scripts/signal/autoreg_matrix.m, scripts/signal/bartlett.m, scripts/signal/blackman.m, scripts/signal/detrend.m, scripts/signal/diffpara.m, scripts/signal/durbinlevinson.m, scripts/signal/fftconv.m, scripts/signal/fftfilt.m, scripts/signal/fftshift.m, scripts/signal/filter2.m, scripts/signal/freqz.m, scripts/signal/hamming.m, scripts/signal/hanning.m, scripts/signal/hurst.m, scripts/signal/ifftshift.m, scripts/signal/periodogram.m, scripts/signal/sinc.m, scripts/signal/sinetone.m, scripts/signal/sinewave.m, scripts/signal/spectral_adf.m, scripts/signal/spectral_xdf.m, scripts/signal/spencer.m, scripts/signal/stft.m, scripts/signal/synthesis.m, scripts/signal/unwrap.m, scripts/signal/yulewalker.m: Update more docstrings to have one sentence summary as first line.
author Rik <rik@octave.org>
date Mon, 04 May 2015 21:50:57 -0700
parents 9fc020886ae9
children
comparison
equal deleted inserted replaced
20164:df437a52bcaf 20165:f1d0f506ee78
20 20
21 ## -*- texinfo -*- 21 ## -*- texinfo -*-
22 ## @deftypefn {Function File} {} fsolve (@var{fcn}, @var{x0}, @var{options}) 22 ## @deftypefn {Function File} {} fsolve (@var{fcn}, @var{x0}, @var{options})
23 ## @deftypefnx {Function File} {[@var{x}, @var{fvec}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@var{fcn}, @dots{}) 23 ## @deftypefnx {Function File} {[@var{x}, @var{fvec}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@var{fcn}, @dots{})
24 ## Solve a system of nonlinear equations defined by the function @var{fcn}. 24 ## Solve a system of nonlinear equations defined by the function @var{fcn}.
25 ##
25 ## @var{fcn} should accept a vector (array) defining the unknown variables, 26 ## @var{fcn} should accept a vector (array) defining the unknown variables,
26 ## and return a vector of left-hand sides of the equations. Right-hand sides 27 ## and return a vector of left-hand sides of the equations. Right-hand sides
27 ## are defined to be zeros. 28 ## are defined to be zeros. In other words, this function attempts to
28 ## In other words, this function attempts to determine a vector @var{x} such 29 ## determine a vector @var{x} such that @code{@var{fcn} (@var{x})} gives
29 ## that @code{@var{fcn} (@var{x})} gives (approximately) all zeros. 30 ## (approximately) all zeros.
31 ##
30 ## @var{x0} determines a starting guess. The shape of @var{x0} is preserved 32 ## @var{x0} determines a starting guess. The shape of @var{x0} is preserved
31 ## in all calls to @var{fcn}, but otherwise it is treated as a column vector. 33 ## in all calls to @var{fcn}, but otherwise it is treated as a column vector.
32 ## @var{options} is a structure specifying additional options. 34 ##
33 ## Currently, @code{fsolve} recognizes these options: 35 ## @var{options} is a structure specifying additional options. Currently,
36 ## @code{fsolve} recognizes these options:
34 ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"}, 37 ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
35 ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}, 38 ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"},
36 ## @qcode{"Jacobian"}, @qcode{"Updating"}, @qcode{"ComplexEqn"} 39 ## @qcode{"Jacobian"}, @qcode{"Updating"}, @qcode{"ComplexEqn"}
37 ## @qcode{"TypicalX"}, @qcode{"AutoScaling"} and @qcode{"FinDiffType"}. 40 ## @qcode{"TypicalX"}, @qcode{"AutoScaling"} and @qcode{"FinDiffType"}.
38 ## 41 ##
39 ## If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}, 42 ## If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}, called
40 ## called with 2 output arguments, also returns the Jacobian matrix 43 ## with 2 output arguments also returns the Jacobian matrix of right-hand sides
41 ## of right-hand sides at the requested point. @qcode{"TolX"} specifies 44 ## at the requested point. @qcode{"TolX"} specifies the termination tolerance
42 ## the termination tolerance in the unknown variables, while 45 ## in the unknown variables, while @qcode{"TolFun"} is a tolerance for
43 ## @qcode{"TolFun"} is a tolerance for equations. Default is @code{1e-7} 46 ## equations. Default is @code{1e-7} for both @qcode{"TolX"} and
44 ## for both @qcode{"TolX"} and @qcode{"TolFun"}. 47 ## @qcode{"TolFun"}.
45 ## 48 ##
46 ## If @qcode{"AutoScaling"} is on, the variables will be automatically scaled 49 ## If @qcode{"AutoScaling"} is on, the variables will be automatically scaled
47 ## according to the column norms of the (estimated) Jacobian. As a result, 50 ## according to the column norms of the (estimated) Jacobian. As a result,
48 ## TolF becomes scaling-independent. By default, this option is off, because 51 ## TolF becomes scaling-independent. By default, this option is off because
49 ## it may sometimes deliver unexpected (though mathematically correct) results. 52 ## it may sometimes deliver unexpected (though mathematically correct) results.
50 ## 53 ##
51 ## If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use 54 ## If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use
52 ## @nospell{Broyden} updates to update the Jacobian, in order to reduce the 55 ## @nospell{Broyden} updates to update the Jacobian, in order to reduce the
53 ## amount of Jacobian calculations. If your user function always calculates the 56 ## amount of Jacobian calculations. If your user function always calculates the
54 ## Jacobian (regardless of number of output arguments), this option provides 57 ## Jacobian (regardless of number of output arguments) then this option provides
55 ## no advantage and should be set to false. 58 ## no advantage and should be set to false.
56 ## 59 ##
57 ## @qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve 60 ## @qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve
58 ## complex equations in complex variables, assuming that the equations possess a 61 ## complex equations in complex variables, assuming that the equations possess
59 ## complex derivative (i.e., are holomorphic). If this is not what you want, 62 ## a complex derivative (i.e., are holomorphic). If this is not what you want,
60 ## should unpack the real and imaginary parts of the system to get a real 63 ## you should unpack the real and imaginary parts of the system to get a real
61 ## system. 64 ## system.
62 ## 65 ##
63 ## For description of the other options, see @code{optimset}. 66 ## For description of the other options, see @code{optimset}.
64 ## 67 ##
65 ## On return, @var{fval} contains the value of the function @var{fcn} 68 ## On return, @var{fval} contains the value of the function @var{fcn}
66 ## evaluated at @var{x}, and @var{info} may be one of the following values: 69 ## evaluated at @var{x}.
70 ##
71 ## @var{info} may be one of the following values:
67 ## 72 ##
68 ## @table @asis 73 ## @table @asis
69 ## @item 1 74 ## @item 1
70 ## Converged to a solution point. Relative residual error is less than 75 ## Converged to a solution point. Relative residual error is less than
71 ## specified by TolFun. 76 ## specified by TolFun.
85 ## 90 ##
86 ## Note: If you only have a single nonlinear equation of one variable, using 91 ## Note: If you only have a single nonlinear equation of one variable, using
87 ## @code{fzero} is usually a much better idea. 92 ## @code{fzero} is usually a much better idea.
88 ## 93 ##
89 ## Note about user-supplied Jacobians: 94 ## Note about user-supplied Jacobians:
90 ## As an inherent property of the algorithm, Jacobian is always requested for a 95 ## As an inherent property of the algorithm, a Jacobian is always requested for
91 ## solution vector whose residual vector is already known, and it is the last 96 ## a solution vector whose residual vector is already known, and it is the last
92 ## accepted successful step. Often this will be one of the last two calls, but 97 ## accepted successful step. Often this will be one of the last two calls, but
93 ## not always. If the savings by reusing intermediate results from residual 98 ## not always. If the savings by reusing intermediate results from residual
94 ## calculation in Jacobian calculation are significant, the best strategy is to 99 ## calculation in Jacobian calculation are significant, the best strategy is to
95 ## employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is 100 ## employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is
96 ## called with that vector, then the intermediate results should be saved for 101 ## called with that vector, then the intermediate results should be saved for