1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<html lang="en">
<head>
<title>nonlin_residmin - optim_doc</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="optim_doc">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Residual-optimization.html#Residual-optimization" title="Residual optimization">
<link rel="next" href="nonlin_005fcurvefit.html#nonlin_005fcurvefit" title="nonlin_curvefit">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Additional documentation for the optim package for Octave.
Copyright (C) <Olaf Till <i7tiol@t-online.de>>
You can redistribute this documentation and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation; either version 3 of the License, or (at your option) any
later version.
This documentation is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this documentation; if not, see <http://www.gnu.org/licenses/>.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="nonlin_residmin"></a>
<a name="nonlin_005fresidmin"></a>
<p>
Next: <a rel="next" accesskey="n" href="nonlin_005fcurvefit.html#nonlin_005fcurvefit">nonlin_curvefit</a>,
Up: <a rel="up" accesskey="u" href="Residual-optimization.html#Residual-optimization">Residual optimization</a>
<hr>
</div>
<h3 class="section">2.1 Frontend nonlin_residmin for non-linear residual minimization</h3>
<p><a name="index-nonlin_005fresidmin-30"></a>
<!-- include function help here -->
<!-- nonlin_residmin ../inst/nonlin_residmin.m -->
<a name="XREFnonlin_005fresidmin"></a>
<div class="defun">
— Function File: [<var>p</var>, <var>resid</var>, <var>cvg</var>, <var>outp</var>] = <b>nonlin_residmin</b> (<var>f, pin</var>)<var><a name="index-nonlin_005fresidmin-31"></a></var><br>
— Function File: [<var>p</var>, <var>resid</var>, <var>cvg</var>, <var>outp</var>] = <b>nonlin_residmin</b> (<var>f, pin, settings</var>)<var><a name="index-nonlin_005fresidmin-32"></a></var><br>
<blockquote><p>Frontend for nonlinear minimization of residuals returned by a model
function.
<p>The functions supplied by the user have a minimal
interface; any additionally needed constants (e.g. observed values)
can be supplied by wrapping the user functions into anonymous
functions.
<p>The following description applies to usage with vector-based
parameter handling. Differences in usage for structure-based
parameter handling will be explained separately.
<p><var>f</var>: function returning the array of residuals. It gets a column
vector of real parameters as argument. In gradient determination,
this function may be called with an informational second argument,
whose content depends on the function for gradient determination.
<p><var>pin</var>: real column vector of initial parameters.
<p><var>settings</var>: structure whose fields stand for optional settings
referred to below. The fields can be set by <code>optimset()</code>.
<p>The returned values are the column vector of final parameters
<var>p</var>, the final array of residuals <var>resid</var>, an integer
<var>cvg</var> indicating if and how optimization succeeded or failed, and
a structure <var>outp</var> with additional information, curently with the
fields: <code>niter</code>, the number of iterations and
<code>user_interaction</code>, information on user stops (see settings).
The backend may define additional fields. <var>cvg</var> is greater than
zero for success and less than or equal to zero for failure; its
possible values depend on the used backend and currently can be
<code>0</code> (maximum number of iterations exceeded), <code>2</code> (parameter
change less than specified precision in two consecutive iterations),
or <code>3</code> (improvement in objective function – e.g. sum of squares
– less than specified), or <code>-1</code> (algorithm aborted by a user
function).
<!-- The following block will be cut out in the package info file. -->
<p class="noindent"><strong>See also:</strong> <a href="XREFnonlin_005fcurvefit.html#XREFnonlin_005fcurvefit">nonlin_curvefit</a>.
</blockquote></div>
<h4 class="subheading">Settings</h4>
<p>The fields of the <var>settings</var> structure can be set with
<a href="../octave/XREFoptimset.html#XREFoptimset">optimset</a>.
<p>For settings common to all frontends (including these for statistics)
see
<a href="Common-frontend-options.html#Common-frontend-options">Common frontend options</a>.
<p>For additional settings common to all optimization frontends
see
<a href="Common-optimization-options.html#Common-optimization-options">Common optimization options</a>.
<h5 class="subsubheading">Specific defaults:</h5>
<p><table summary=""><tr align="left"><td valign="top"><code>Algorithm</code>:
</td><td valign="top">"lm_svd_feasible"
<br></td></tr></table>
<h5 class="subsubheading">Additional settings:</h5>
<dl>
<dt><code>weights</code><dd>Array of weights for the residuals. Dimensions must match.
<a name="XREFoptiondfdp"></a><br><dt><code>dfdp</code><dd>Function computing the Jacobian of the residuals with respect to the
parameters, assuming residuals are reshaped to a column vector.
Default: real finite differences. Will be called with the column vector
of parameters and an informational structure as arguments. If
<code>dfdp</code> was specified by the user, the informational structure has
the fields <code>f</code>: value of residuals for current parameters, reshaped
to a column vector, <code>fixed</code>: logical vector indicating which
parameters are not optimized, so these partial derivatives need not be
computed and can be set to zero, <code>diffp</code>, <code>diff_onesided</code>,
<code>lbound</code>, <code>ubound</code>: identical to the user settings of this
name, <code>plabels</code>: 1-dimensional cell-array of column-cell-arrays,
each column with labels for all parameters; the first column contains
the numerical indices of the parameters; the second and third columns,
present for structure based parameter handling, see
<a href="Parameter-structures.html#Parameter-structures">Parameter structures</a>, contain the names of the parameters and the subindices of
the parameters, see
<a href="Non_002dscalar-parameters.html#Non_002dscalar-parameters">Non-scalar parameters</a>, respectively. The default
jacobian function will call the model function with the second argument
set with fields <code>f</code>: as the <code>f</code> passed to the jacobian
function, <code>plabels</code>: cell-array of 1x1 cell-arrays with the entries
of the column-cell-arrays of <code>plabels</code> as passed to the jacobian
function corresponding to current parameter, <code>side</code>: <code>0</code> for
one-sided interval, <code>1</code> or <code>2</code>, respectively, for the sides of
a two-sided interval, and <code>parallel</code>: logical scalar indicating
parallel computation of partial derivatives. This information can be
useful if the model function can omit some computations depending on the
currently computed partial derivative.
<br><dt><code>complex_step_derivative_f</code><dd>Logical scalar, default: <code>false</code>. Estimate Jacobian of model
function with complex step derivative approximation. Use only if you
know that your model function is suitable for this. No user function for
the Jacobian (<code>dfdp</code>) must be specified.
<br><dt><code>plot_cmd</code><dd>Function enabling backend to plot results or intermediate results. Will
be called with current computed residuals. Default: plot nothing. This
setting is deprecated and will disappear. Please use
<code>user_interaction</code> instead (see
<a href="Common-optimization-options.html#Common-optimization-options">Common optimization options</a>).
</dl>
<h4 class="subheading">Structure based parameter handling</h4>
<p>Please see
<a href="Parameter-structures.html#Parameter-structures">Parameter structures</a>.
<h4 class="subheading">Backend information</h4>
<p>Please see
<a href="Residual-optimization.html#Residual-optimization">Residual optimization</a> and choose backend from menu under
`Optimization backends'.
<!-- -->
</body></html>
|
