NONLINPK
NESOLVE and UMSOLVE
Release 1.1, August 31, 1990
This file contains important information about the Matlab nonlinear
equations solver NESOLVE and the unconstrained minimization function
UMSOLVE, distributed together as NONLINPK.
***CAUTION*******CAUTION*******CAUTION*******CAUTION*******CAUTION****
*
*
*
The file NELNSRCH.M is an update to the version released by
*
* MathWorks with Matlab version 3.5. The old version only works for *
* nonlinear equations (FSOLVE or NESOLVE) and WILL NOT WORK for
*
* unconstrained minimization (UMSOLVE). You must replace the old
*
* version with the new one, or at least make sure that the new
*
* version of NELNSRCH is ahead of the old one in the Matlab search
*
* path. See section (4) below for more details.
*
*
*
***CAUTION*******CAUTION*******CAUTION*******CAUTION*******CAUTION****
(1) GETTING STARTED
If you receive the nonlinpk package in bundled form (the way it
comes from the user group, in one big file) you should begin by
unbundling it. This job is best handled by the "unbundle" utility
available through the Matlab User Group (direct inquiries to Internet
address "matlab-users-request@mcs.anl.gov". Put the unbundled M-files
in the subdirectory of your choice, and make sure that subdirectory
is included in the Matlab search path (system dependent). I like to
keep "third-party" M-files separate from those supplied by the
MathWorks. The following files comprise the NONLINPK package,
release 1.1 (sizes may be approximate):
FILENAME
BYTES
-------------NEBROYUF M
860
NECHDCMP M
1984
NECONEST M
1379
NEDEMO
M
2511
NEFDJAC M
1369
NEFN
M
698
NEHELP
M
8628
NEHOOK
M
4349
NEINCK
M
1890
NELNSRCH M
3560
NEMODEL M
1817
NEQRDCMP M
1271
NEQRSOLV M
680
NERSOLV M
655
NESOLVE M
8066
NESTOP
M
1397
NETESTF1 M
536
NETRUST
UMBFGSU
UMDEMO
UMFDGRAD
UMFDHESF
UMFDHESG
NONLINPK
UMINCK
UMINITHU
UMMODEL
UMSOLVE
UMSTOP
UMTESTF5
UMHELP
M
M
M
M
M
M
DOC
M
M
M
M
M
M
M
3502
991
2646
1275
2145
863
15274
1897
628
2066
7130
1327
482
10330
Next, deal with the NELNSRCH problem mentioned in the caution
above. I would do this by removing all the old NE*.M files.
Test the installation and begin familiarizing yourself with the
unconstrained minimization function by running UMDEMO. There is also
NEDEMO for the nonlinear equations function.
Now you are ready to use UMSOLVE. You can of course enter 'help
umsolve' to get some basic info on using it. For more in-depth info
try invoking the M-file UMHELP, examining UMSOLVE.M, or consulting
the book from which the algorithms were taken, "Numerical Methods for
Unconstrained Optimization and Nonlinear Equations" by J. E. Dennis, Jr.
and Robert B. Schnabel, Prentice-Hall, 1983.
(2) UMSOLVE versus FMINS
Matlab comes with a function called FMINS that does the same thing
as UMSOLVE, so why should you use UMSOLVE? I suggest you compare the
performance on your own applications, but here are the results of my
tests. To compare the two minimization functions I used two test
functions: FITFUN which is used in the FMINS demo called FITDEMO, and
UMTESTF5 which is used in the UMSOLVE demo called UMDEMO. I used all the
default tolerances and options, and the same starting points as in the
demos. The functions were invoked with lines like:
x = fmins(fname,x0)
x = umsolve(fname,x0)
To minimize FITFUN, FMINS required 73,102 flops (as counted by
Matlab) while UMSOLVE required only 35,896. The number of function
evaluations made by FMINS was 79, while UMSOLVE made only 36. To top
it off, the value of the objective function (FITFUN) where UMSOLVE
stopped was .3843, smaller than the .3844 for FMINS. Consider also
that UMSOLVE's parameter passing capability could have been used
for the data points in FITFUN, eliminating the need for a global
variable.
What about UMTESTF5?
FMINS stopped without finding the minimum
at all.
UMSOLVE was able to find the minimum from both the original
starting point and the point where FMINS terminated.
(3) HISTORY OF FSOLVE, NESOLVE AND UMSOLVE
FSOLVE has been distributed by the MathWorks as part of Matlab
version 3.5. I (Rick Behrens) coded the Dennis & Schnabel algorithms
under the supervision of Schnabel, and supplied the Matlab code to the
MathWorks. The FSOLVE function was originally called NESOLVE (for
Nonlinear Equations SOLVEr), but in their release MathWorks changed the
name. Their name is probably better, but it does break the pattern of
names beginning with NE for all functions associated with the nonlinear
equations package. I have changed the name back to NESOLVE in this
release.
Then came UMSOLVE, the companion set of algorithms for unconstrained
minimization. MathWorks has now decided not to distribute UMSOLVE, and
to work towards removing FSOLVE from their distribution in the future
so that the entire package can be distributed by the user's group. Two
email notes from Cleve Moler reveal their attitude:
From mathworks!moler@apple.com Tue Aug 21 15:28 MDT 1990
To: behrens@dsp.Colorado.EDU
Subject: User's Group
Hi Rick-- Good to hear from you. I think the user's group is the
right place for the rest of your stuff. I'd like to see more
code available through the group. I'm going to send some of my
own stuff there any day now.
--Cleve
From mathworks!moler@apple.com Thu Aug 23 20:11 MDT 1990
To: behrens@dsp.Colorado.EDU
Subject: FSOLVE and UMSOLVE
Rick-- Let's handle them all through the user group, new routines
and updates to old routines. In fact, let's head for the
situation where your stuff is removed from the MathWorks
distribution. I'm afraid it is lost there today, and I'd like
to see some good, small, packages of M-files distributed by
the users group. Yours would be a good place to start.
-- Cleve
(4) INTERDEPENDENCE BETWEEN NESOLVE AND UMSOLVE
All the new subfunctions used only by UMSOLVE have names beginning
with UM, but UMSOLVE also makes use of some of the NESOLVE subfunctions.
A dependence graph should make the situation clear:
NESOLVE --+->
|->
|->
|->
|
|
|
|->
|->
|->
NEFN
NEINCK
NEFDJAC
NEMODEL ---+->
|->
|->
|->
NELNSRCH ---->
NEBROYUF
NESTOP
UMSOLVE --+->
|->
|->
|->
|->
|->
|->
|->
|->
UMINCK
UMFDGRAD
UMFDHESG ----> NEFDJAC
UMFDHESF
UMINITHU
UMMODEL -----> NECHDCMP
UMSTOP
UMBFGSU
NELNSRCH
NEQRDCMP
NECONEST ----> NERSOLV
NECHDCMP
NEQRSOLV ----> NERSOLV
NEFN
Unfortunately, the graph doesn't tell the whole story. NELNSRCH
was modified slightly to make it work with UMSOLVE in addition to its
duties under NESOLVE. Therefore, the version of NELNSRCH bundled with
nonlinpk supercedes the version distributed in Matlab version 3.5. To
be sure that UMSOLVE gets ahold of the right version of NELNSRCH, I
would recommend replacing the old one entirely.
(5) CRITICISMS OF THE IMPLEMENTATION
There are some things about the entire package (NESOLVE and UMSOLVE)
that ought to be changed. Maybe some day I will get it done. These are
only things I have thought of myself . . . I'm sure others could add to
the list. Part of the reason things are the way they are is that the
algorithms in Dennis & Schnabel were followed rather slavishly even
though they not written with Matlab's strengths and weaknesses in mind.
Here are my criticisms:
1) The code is divided into too many functions. A perfect
example of a function that should be integrated into its
calling function is UMINITHU.
2) Matlab's internal QR decomposition should be used instead
of NEQRDCMP. The latter is used now because its output is
coded in the way the other functions expect it, which is
not the same as the output from QR.
3) The function NERSOLV should be ommited, it job being done
by Matlab's \ operator. Again the difficulty is the way
the output from NEQRDCMP is coded.
4) Further vectorization is possible in some parts of the code.
5) Matlab's internal Cholesky decomposition should be used
instead of NECHDCMP in some instances. NECHDCMP is a
"perturbed" Cholesky decomposition, so it must still be used
in cases where the matrix is not guaranteed to be positive
definite.
6) Specifying a gradient, Jacobian, or Hessian function file
name should automatically cause it to be used. Currently it
is also necessary to set the appropriate flags in the DETAILS
vector.
(6) THE HOOKSTEP OPTION
The most recent addition to the package is the "hookstep" option.
The hookstep is an alternative to the line-search as a method of
improving the convergence of Newton's method from poor starting points.
The hookstep is a trust-region based method, and better reflects the
state-of-the-art in optimization. In many cases the line-search and
the hookstep are about equally effective, but in some situations the
hookstep requires significantly fewer iterations and/or function
evaluations than the line-search.
Two new M-files implement
with NELNSRCH they can be used
the hookstep option required a
so the older MathWorks version
hookstep.
the hookstep: NEHOOK and NETRUST. As
by either NESOLVE or UMSOLVE. Adding
minor update to the main NESOLVE file,
(FSOLVE) cannot be used with the
(7) SHAREWARE REGISTRATION
The UMSOLVE files are distributed as Shareware (but NESOLVE is
public domain). This means that if you find the functions useful, I'd
like a little something for my trouble of writing and debugging them.
You can use them and evaluate them first, then decide whether or not to
register. If you do find UMSOLVE useful on a continuing basis, please
register your copy by sending $20 (or $10 for full-time students) to:
Richard T. Behrens
Rt. 4, Box 3F
Bishop, CA 93514
I will acknowledge and keep a record of all registrations. Regestered
users will find me more helpful when they need help with the package.
Whether or not you regester your copy, you are free to keep it and
encouraged to pass it around to all your MATLABing friends. All I
ask is that you distribute it unmodified and complete with all files.
(8) FSOLVE USER'S GUIDE ERRATA
There are a few mistakes and ambiguities in the Matlab user's
guide (February 3, 1989 edition) in the entry for FSOLVE:
1) The manual says, "To supply an optional argument such as
FPARAM, all optional arguments preceeding it in the input
argument list must also be specified." This is true, but
they may be specified as empty matrices to hold the position.
-->
2) In the table describing the elements of DETAILS, the
description for entry 12 (FDIGITS) is wrong. FDIGITS is how
you tell FSOLVE the accuracy it can expect from the function
it is solving. There is no guarantee regarding the accuracy
of the solution out of FSOLVE.
3) In order for a function specified by JACOB to be used, the
flag DETAILS(4) must be set to 1.
(9) SUPPORT
Here is how you can contact me if you need to:
email:
behrens@dsp.colorado.edu
US-mail:
Richard T. Behrens
Rt. 4, Box 3F
Bishop, CA 93514
The US-mail address belongs to my parents, who are less likely
to move than I am. They will get your letter to me.
Please let me know if you think you have found a bug, or if you
have suggestions for improving the package. Keep in mind that nonideal
behavior (such as convergenge to an undesired local minimum) does not
necessarily constitute a bug. For other types of problems, such as
application assistance, I will probably be more inclined to help
registered users (see section (7) above).
*******ADVERTISEMENT*******ADVERTISEMENT*******ADVERTISEMENT*********
*
*
*
A scientific calculator program for MS-DOS/PC-DOS computers is *
* available as Shareware from the author of UMSOLVE and NESOLVE.
*
* Features include:
*
*
+ Reverse Polish Notation (RPN), like many HP calculators.
*
*
+ TSR capability (optional) with 'Hot Key' activation.
*
*
+ 5 element stack shown on screen.
*
*
+ 10 memories, can be shown on screen.
*
*
+ Stack and memories maintained while resident as a TSR.
*
*
+ Scientific notation or fixed decimal display.
*
*
+ Trigonometric functions and inverses (degrees or radians).
*
*
+ Logarithmic functions and exponentials.
*
*
+ Additional mathematical and stack functions.
*
*
+ 6-byte floating point (about 11 digit internal accuracy).
*
*
+ Pi key (3.14159 . . .).
*
*
+ On line help, and a documentation file.
*
*
+ TSR can be removed from memory without re-booting.
*
*
*
*
This calculator is handy for quick calculations when you are
*
* not in Matlab, or even while a Matlab job is running. For your
*
* own copy, send your request along with $3 for postage and media
*
* (specify diskette size) to Richard T. Behrens at the address in
*
* section (9) above. The program is also available on CompuServe
*
* in the IBMSYS forum. The registration fee is $10 for satisfied
*
* users, or you can preregister by sending the fee with your order *
* (total $13).
*
*
*
*******ADVERTISEMENT*******ADVERTISEMENT*******ADVERTISEMENT*********