Mercurial > hg > octave-lyh

comparison scripts/optimization/fsolve.m @ 9051:1bf0ce0930be

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Grammar check TexInfo in all .m files Cleanup documentation sources to follow a few consistent rules. Spellcheck was NOT done. (but will be in another changeset)
author Rik <rdrider0-list@yahoo.com>
date Fri, 27 Mar 2009 22:31:03 -0700
parents 187a9d9c2f04
children 8207b833557f
comparison
equal deleted inserted replaced
9044:656ad518f385 9051:1bf0ce0930be
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 ## @var{fcn} should accepts a vector (array) defining the unknown variables, 25 ## @var{fcn} should accepts a vector (array) defining the unknown variables,
26 ## and return a vector of left-hand sides of the equations. Right-hand sides 26 ## and return a vector of left-hand sides of the equations. Right-hand sides
27 ## are defined to be zeros. 27 ## are defined to be zeros.
28 ## In other words, this function attempts to determine a vector @var{x} such 28 ## In other words, this function attempts to determine a vector @var{x} such
29 ## that @code{@var{fcn} (@var{x})} gives (approximately) all zeros. 29 ## that @code{@var{fcn} (@var{x})} gives (approximately) all zeros.
30 ## @var{x0} determines a starting guess. The shape of @var{x0} is preserved 30 ## @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. 31 ## in all calls to @var{fcn}, but otherwise it is treated as a column vector.
32 ## @var{options} is a structure specifying additional options. 32 ## @var{options} is a structure specifying additional options.
33 ## Currently, @code{fsolve} recognizes these options: 33 ## Currently, @code{fsolve} recognizes these options:
34 ## @code{"FunValCheck"}, @code{"OutputFcn"}, @code{"TolX"}, 34 ## @code{"FunValCheck"}, @code{"OutputFcn"}, @code{"TolX"},
35 ## @code{"TolFun"}, @code{"MaxIter"}, @code{"MaxFunEvals"}, 35 ## @code{"TolFun"}, @code{"MaxIter"}, @code{"MaxFunEvals"},
37 ## 37 ##
38 ## If @code{"Jacobian"} is @code{"on"}, it specifies that @var{fcn}, 38 ## If @code{"Jacobian"} is @code{"on"}, it specifies that @var{fcn},
39 ## called with 2 output arguments, also returns the Jacobian matrix 39 ## called with 2 output arguments, also returns the Jacobian matrix
40 ## of right-hand sides at the requested point. @code{"TolX"} specifies 40 ## of right-hand sides at the requested point. @code{"TolX"} specifies
41 ## the termination tolerance in the unknown variables, while 41 ## the termination tolerance in the unknown variables, while
42 ## @code{"TolFun"} is a tolerance for equations. Default is @code{1e-7} 42 ## @code{"TolFun"} is a tolerance for equations. Default is @code{1e-7}
43 ## for both @code{"TolX"} and @code{"TolFun"}. 43 ## for both @code{"TolX"} and @code{"TolFun"}.
44 ## If @code{"Updating"} is "on", the function will attempt to use Broyden 44 ## If @code{"Updating"} is "on", the function will attempt to use Broyden
45 ## updates to update the Jacobian, in order to reduce the amount of jacobian 45 ## updates to update the Jacobian, in order to reduce the amount of jacobian
46 ## calculations. 46 ## calculations.
47 ## If your user function always calculates the Jacobian (regardless of number 47 ## If your user function always calculates the Jacobian (regardless of number
48 ## of output arguments), this option provides no advantage and should be set to 48 ## of output arguments), this option provides no advantage and should be set to
49 ## false. 49 ## false.
50 ## 50 ##
51 ## @code{"ComplexEqn"} is @code{"on"}, @code{fsolve} will attempt to solve 51 ## @code{"ComplexEqn"} is @code{"on"}, @code{fsolve} will attempt to solve
52 ## complex equations in complex variables, assuming that the equations posess a 52 ## complex equations in complex variables, assuming that the equations posess a
53 ## complex derivative (i.e. are holomorphic). If this is not what you want, 53 ## complex derivative (i.e., are holomorphic). If this is not what you want,
54 ## should unpack the real and imaginary parts of the system to get a real 54 ## should unpack the real and imaginary parts of the system to get a real
55 ## system. 55 ## system.
56 ## 56 ##
57 ## For description of the other options, see @code{optimset}. 57 ## For description of the other options, see @code{optimset}.
58 ## 58 ##
59 ## On return, @var{fval} contains the value of the function @var{fcn} 59 ## On return, @var{fval} contains the value of the function @var{fcn}
60 ## evaluated at @var{x}, and @var{info} may be one of the following values: 60 ## evaluated at @var{x}, and @var{info} may be one of the following values:
61 ## 61 ##
62 ## @table @asis 62 ## @table @asis
63 ## @item 1 63 ## @item 1
64 ## Converged to a solution point. Relative residual error is less than specified 64 ## Converged to a solution point. Relative residual error is less than specified
65 ## by TolFun. 65 ## by TolFun.
66 ## @item 2 66 ## @item 2
67 ## Last relative step size was less that TolX. 67 ## Last relative step size was less that TolX.
68 ## @item 3 68 ## @item 3
69 ## Last relative decrease in residual was less than TolF. 69 ## Last relative decrease in residual was less than TolF.
78 ## @seealso{fzero, optimset} 78 ## @seealso{fzero, optimset}
79 ## 79 ##
80 ## Note about user-supplied jacobians: 80 ## Note about user-supplied jacobians:
81 ## As an inherent property of the algorithm, jacobian is always requested for a 81 ## As an inherent property of the algorithm, jacobian is always requested for a
82 ## solution vector whose residual vector is already known, and it is the last 82 ## solution vector whose residual vector is already known, and it is the last
83 ## accepted successful step. Often this will be one of the last two calls, but 83 ## accepted successful step. Often this will be one of the last two calls, but
84 ## not always. If the savings by reusing intermediate results from residual 84 ## not always. If the savings by reusing intermediate results from residual
85 ## calculation in jacobian calculation are significant, the best strategy is to 85 ## calculation in jacobian calculation are significant, the best strategy is to
86 ## employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is 86 ## employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is
87 ## called with that vector, then the intermediate results should be saved for 87 ## called with that vector, then the intermediate results should be saved for
88 ## future jacobian evaluation, and should be kept until a jacobian evaluation 88 ## future jacobian evaluation, and should be kept until a jacobian evaluation
89 ## is requested or until outputfcn is called with a different vector, in which 89 ## is requested or until outputfcn is called with a different vector, in which
90 ## case they should be dropped in favor of this most recent vector. A short 90 ## case they should be dropped in favor of this most recent vector. A short
91 ## example how this can be achieved follows: 91 ## example how this can be achieved follows:
92 ## 92 ##
93 ## @example 93 ## @example
94 ## @group
94 ## function [fvec, fjac] = my_optim_func (x, optimvalues, state) 95 ## function [fvec, fjac] = my_optim_func (x, optimvalues, state)
95 ## persistent sav = [], sav0 = []; 96 ## persistent sav = [], sav0 = [];
96 ## if (nargin == 1) 97 ## if (nargin == 1)
97 ## ## evaluation call 98 ## ## evaluation call
98 ## if (nargout == 1) 99 ## if (nargout == 1)
108 ## endif 109 ## endif
109 ## ## maybe output iteration status etc. 110 ## ## maybe output iteration status etc.
110 ## endif 111 ## endif
111 ## endfunction 112 ## endfunction
112 ## 113 ##
113 ## ## .... 114 ## ## @dots{}.
114 ## 115 ##
115 ## fsolve (@@my_optim_func, x0, optimset ("OutputFcn", @@my_optim_func, @dots{})) 116 ## fsolve (@@my_optim_func, x0, optimset ("OutputFcn", @@my_optim_func, @dots{}))
117 ## @end group
116 ## @end example 118 ## @end example
117 ### 119 ###
118 ## @end deftypefn 120 ## @end deftypefn
119 121
120 ## PKG_ADD: __all_opts__ ("fsolve"); 122 ## PKG_ADD: __all_opts__ ("fsolve");