rwl / optimization Goto Github PK

Nonlinear Optimization Java Package
-----------------------------------

(see http://ws13.fpl.fs.fed.us/optimization.html for
an html version of this document)

Currently (as of 2/6/02) this package contains Java translations
of the 1-dimensional minimization routine, fmin, the 
multi-dimensional minimization routine UNCMIN, the MINPACK 
nonlinear least squares routines (lmder1, lmder, lmdif1, and lmdif), 
and the SLATEC 1-dimensional zero-finding routine, dfzero.  
Eventually (sometime in 2002?), the package will also contain 
Java translations of some of the MINPACK nonlinear equation
solvers.

The 1-dimensional minimization routine is an unofficial
Java translation of the FORTRAN version of the public domain 
fmin routine that can be found at http://www.netlib.org/go/fmin.f.

The multi-dimensional minimization routine is an unofficial 
Java translation of the FORTRAN version of the public domain 
UNCMIN package that can be found at http://gams.nist.gov.

The nonlinear least squares routines are unofficial 
Java translations of the FORTRAN versions of the public domain 
MINPACK nonlinear least squares routines that can be found
at http://www.netlib.org/minpack.

The 1-dimensional zero-finding routine is an unofficial
Java translation of the FORTRAN version of the public domain 
SLATEC dfzero routine that can be found at netlib.  Either go to
http://www.netlib.org and do a search for dfzero.f, or go to 
http://www.netlib.org/slatec and download the entire SLATEC library.


Warning!!!
----------

1.) These routines were translated by a user of numerical analysis
routines rather than a developer.  When Java optimization routines
written by professional numerical analysts become
available, they should be used.

2.) I have tried to be careful with the coding and have done some
simple testing (see the FminTest, UncminTest_f77, LmderTest_f77,
LmdifTest_f77, and FzeroTest applications).  
However, it is quite possible that I have introduced
errors into the routines in the course of the translations.
If you detect bugs in fmin, UNCMIN, MINPACK, or fzero,
PLEASE contact me (Steve Verrill at [email protected] 
or 608-231-9375).  Note that for "pathological" problems, 
results can depend upon programming details or the version 
of the Java Developer's Kit. See
http://ws13.fpl.fs.fed.us/minpack.prob.html for details.

3.) Uncmin_f77.java, UncminTest_f77.java, Minpack_f77.java,
LmderTest_f77.java, and LmdifTest_f77.java make use of FORTRAN style
indexing.  In these you will tend to see

   for (i = 1; i <= n; i++)

rather than

   for (i = 0; i < n; i++)

To use the "_f77" routines you will have to declare your vectors
and matrices to be one element larger (e.g., v[101] rather than
v[100], and a[101][101] rather than a[100][100]), and you will have
to fill elements 1 through n rather than elements 0 through n - 1.
See, for example, UncminTest_f77.java.

Eventually, classes that make use of Java/C style indexing might be
made available (actually, this is unlikely).


DISCLAIMER OF WARRANTIES
------------------------

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. 
THE AUTHOR/TRANSLATOR DOES NOT WARRANT, GUARANTEE OR MAKE ANY 
REPRESENTATIONS REGARDING THE SOFTWARE OR DOCUMENTATION IN TERMS 
OF THEIR CORRECTNESS, RELIABILITY, CURRENTNESS, OR OTHERWISE.
THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE 
IS ASSUMED BY YOU. IN NO CASE WILL ANY PARTY INVOLVED WITH THE
CREATION OR DISTRIBUTION OF THE SOFTWARE BE LIABLE FOR ANY DAMAGE 
THAT MAY RESULT FROM THE USE OF THIS SOFTWARE.

Sorry about that.


Documentation
-------------

The documentation generated by javadoc for these routines can be
viewed at

http://www1.fpl.fs.fed.us/Package-optimization.html

and

http://www1.fpl.fs.fed.us/Package-linear_algebra.html

Also see 
1.) the source code of Uncmin_f77.java
2.) the source code of Minpack_f77.java
3.) R.B. Schnabel, J.E. Koontz, and B.E. Weiss,
"A Modular System of Algorithms for Unconstrained Minimization," 
Report CU-CS-240-82, Comp. Sci. Dept., University of Colorado at
Boulder, 1982 
4.) J.E. Dennis and R.B. Schnabel, Numerical Methods 
for Unconstrained Optimization and Nonlinear Equations, 1983


Installation
------------

After you have uncompressed and untarred the
src.tar.Z file you should have 35 new files:

1.) This README file.
2.) Fmin_methods.java
3.) Fmin.java
4.) FminTest.java
5.) Uncmin_methods.java
6.) Uncmin_f77.java
7.) UncminTest_f77.java
8.) Lmder_fcn.java
9.) LmderTest_f77.java
10.) Lmdif_fcn.java
11.) LmdifTest_f77.java
12.) Minpack_f77.java
13.) Fzero_methods.java
14.) Fzero.java
15.) FzeroTest.java
16.) Blas_f77.java
17.) Console.java
18.) Fmin_methods.class
19.) Fmin.class
20.) FminTest.class
21.) Uncmin_methods.class
22.) Uncmin_f77.class
23.) UncminTest_f77.class
24.) Lmder_fcn.class
25.) LmderTest_f77.class
26.) Lmdif_fcn.class
27.) LmdifTest_f77.class
28.) Minpack_f77.class
29.) Fzero_methods.class
30.) Fzero.class
31.) FzeroTest.class
32.) Blas_f77.class
33.) Console.class
34.) disclaimer
35.) copyright

Please read the disclaimer and copyright files.

Given the manner in which the routines are currently written,
you will need to import them (see the beginning of 
UncminTest_f77.java).  All of the classes will have to be placed
in subdirectories of a directory in your CLASSPATH.
For the optimization classes, this subdirectory will 
have to be called optimization.  For the Blas_f77 class, this
subdirectory will have to be called linear_algebra.
Console.class will have to be placed in a 
subdirectory called corejava.

Note that if you install the software in this manner,
then to run, for example, FminTest you will have to issue the command:

java optimization.FminTest

Alternatively,you could remove the package and import statements
(other than import java.lang.*) in the source code,
and compile all of the necessary files in the same directory.

To run Fmin you will need to write a driver
class such as FminTest that implements the Fmin_methods
interface.  This class will have to include an f_to_minimize method.

To run Uncmin_f77 you will need to write a driver
class such as UncminTest_f77 that implements the Uncmin_methods
interface.  This class will have to include an f_to_minimize method
and, at the least, dummy gradient and hessian methods.

To run Minpack_f77 you will need to write a driver
class such as LmderTest_f77 or LmdifTest_f77 that implements
the Lmder_fcn or Lmdif_fcn
interface.  This class will have to include an fcn method.

To run Fzero you will need to write a driver
class such as FzeroTest that implements the Fzero_methods
interface.  This class will have to include an f_to_zero method.


Console.java
------------

Console.java is software described in Cornell
and Horstmann's Core Java (SunSoft Press/Prentice-Hall).
(I like this book.)  It may be used for non-commerical purposes.  
I only make use of it in the testing routines.


Support
-------

If you have questions about this software,
or suggestions for improvement, please contact me 
(Steve Verrill) at [email protected]
or 608-231-9375. 


Last modified on 2/6/02.