Installation Instructions for
ODRPACK 2.01 -- Software for Weighted Orthogonal Distance Regression
*******************************************************************************
* *
* If you have not already installed ODRPACK Version 2.00, then you MUST *
* follow the installation instructions below, which describe the *
* necessary steps for installing the current version, 2.01. If you *
* have already installed Version 2.00 and would prefer to only update *
* those subprograms that have changed between Version 2.00 and Version *
* 2.01, then follow the instructions in file README.UPDATE. File *
* CHANGES identifies how ODRPACK 2.01 differs from earlier releases. *
* *
*******************************************************************************
Direct questions to
Janet E. Rogers
Optimization Group/Applied and Computational Mathematics Division (881)
National Institute of Standards and Technology
325 Broadway
Boulder, CO 80303-3328
e-mail: internet -- jrogers@bldr.nist.gov
phone: (303) 497-5114
fax: (303) 497-3012
*** INTRODUCTION
ODRPACK is a portable collection of Fortran subprograms for fitting a model to
data. It is designed primarily for instances when the explanatory as well as
the response variables have significant errors, implementing a highly
efficient algorithm for solving the weighted orthogonal distance regression
problem, i.e., for minimizing the sum of the squares of the weighted
orthogonal distances between each data point and the curve described by the
model equation. It can also be used to solve the ordinary least squares
problem where all of the errors are attributed to the observations of the
dependent variable. File CHANGES identifies how the current version of
ODRPACK differs from earlier releases.
ODRPACK is written in Fortran as defined in the 1978 standard (ANSI X3.9-
1978), commonly called Fortran 77. The code has been analyzed using the PFORT
verifyer in TOOLPACK, and based on this analysis we believe that ODRPACK is
compatible with the ANSI X3.9-1978 full language standard.
*** INSTALLING ODRPACK
The following describes the necessary steps for installing ODRPACK. On most
UNIX systems, simply invoking the command
make -f makefile
will result in the creation of a library containing the ODRPACK code, and the
execution of all of the test problems. On others systems, the installer will
need to proceed with the installation "by hand."
Step 1. Select Single or Double Precision Version
ODRPACK software is available in both single and double precision versions.
Both versions are complete as they stand, and except for precision are
identical. They can be combined in a single library, if desired. ODRPACK is
sensitive to the machine precision, however, and requires approximately 14
decimal places. Somewhat fewer places should still work, but six or seven
decimal places are definitely too few for general use, since only the simplest
problems could be solved correctly at such reduced precisions. The installer
must therefore choose which version of ODRPACK to use based upon which version
supplies adequate precision on the target machine. To our knowledge, at
present only Cray and CDC machines offer sufficient precision to permit
general use of the single precision version of ODRPACK. For other machines,
we recommend the double precision version.
Note that, as supplied with the release, makefile MAKEFILE installs both
versions of the code into a single library; the changes necessary to install
only one version are documented within MAKEFILE.
Step 2: Select ODRPACK Code Necessary for Installation on the Target System
The code for each version of ODRPACK is separated into three sections to
facilitate installation. These three sections are in files D_ODR.F,
D_LPKBLS.F and D_MPREC0.F for the double precision version, and in files
S_ODR.F, S_LPKBLS.F and S_MPREC0.F for the single precision version.
* Files D_ODR.F and S_ODR.F include all subprograms written especially for
ODRPACK. The two user callable ODRPACK subprograms of each version are
listed first, followed by the remaining subprograms listed in
alphabetical order. The code in these files should not require any
modification unless the installer wishes to customize the user callable
subprograms.
* Files D_LPKBLS.F and S_LPKBLS.F include the subprograms used by ODRPACK
from the public domain packages LINPACK and BLAS, also listed in
alphabetical order. The installer can use local versions of these
packages if available. This would be particularly beneficial if the
installer's machine has specially optimized versions of LINPACK or BLAS.
* Files D_MPREC0.F and S_MPREC0.F include the only machine dependent
subprograms in ODRPACK. Changes required to these files are described in
Step 3, below.
Each ODRPACK subprogram follows the SLATEC Source File Format and provides a
standardized prologue describing the purpose of the subprogram and what other
subprograms are called, an alphabetical list of all variables referenced by
the subprogram and how they are used, as well as comments explaining the major
sections of the code. Furthermore, each ODRPACK subprogram begins with a
comment line consisting of an asterisk followed immediately by the subprogram
name, i.e., *name. This is the only use of an asterisk in column 1 of the
ODRPACK source code, and is done to aid the installer in separating the
subprograms into individual files. For example, the following Fortran program
could be used to split source code file D_ODR.F into files each consisting of
one subprogram each.
PROGRAM FSPLIT
CHARACTER TEST1*1,TEST2*6,LINE*73
INTEGER IUNIT1,IUNIT2,LAST
IUNIT1 = 30
IUNIT2 = 31
OPEN (UNIT=IUNIT1,FILE='D_ODR.F')
READ (UNIT=IUNIT1,FMT=1000,END=999) TEST1,TEST2,LINE
LAST = INDEX(TEST2,' ')-1
IF (LAST.LE.0) LAST = 6
OPEN (UNIT=IUNIT2,FILE=TEST2(1:LAST)//'.F')
WRITE (UNIT=IUNIT2,FMT=1000) TEST1,TEST2,LINE
100 READ (UNIT=IUNIT1,FMT=1000,END=999) TEST1,TEST2,LINE
IF (TEST1.EQ.'*') THEN
CLOSE (UNIT=IUNIT2)
LAST = INDEX(TEST2,' ')-1
IF (LAST.LE.0) LAST = 6
OPEN (UNIT=IUNIT2,FILE=TEST2(1:LAST)//'.F')
END IF
WRITE (UNIT=IUNIT2,FMT=1000) TEST1,TEST2,LINE
GO TO 100
999 CONTINUE
CLOSE (UNIT=IUNIT2)
1000 FORMAT (A1,A6,A73)
END
Step 3. Set Necessary Machine Dependent Values
Files D_MPREC0.F and S_MPREC0.F supply the machine dependent subprograms used
by ODRPACK. Comment statements within these files document the modifications
required. They also list the necessary machine dependent constants for a
number of common machines. If the constants for the target machine are
included, then the installer need only "uncomment" the appropriate DATA
statements. These subprograms will return an undefined value until they are
updated; the installer must update them into files D_MPREC.F and S_MPREC.F,
respectively, before compiling and running ODRPACK.
Step 4. Compile ODRPACK Code and Generate Object Code Library If Desired
ODRPACK code conforms to the ANSI X3.9-1978 full Fortran standard and has been
successfully installed on a CDC Cyber 855, CDC Cyber 205, Concurrent 3230, DEC
VAX 11/780, IBM PC/AT and IBM RS6000, and Sun 3 and Sparc2 Workstations. We
believe it is possible to install ODRPACK on any system with an ANSI Fortran
77 compiler and adequate memory.
Step 5. Test ODRPACK
The ODRPACK supplied software includes drivers and data sets for running
ODRPACK in both double and single precision. There are four drivers for each
version of the code.
* Files D_DRIVE1.F, D_DRIVE2.F, and D_DRIVE3.F, and files S_DRIVE1.F,
S_DRIVE2.F and S_DRIVE3.F, each contain simple programs that users can
modify to form their own ODRPACK drivers. The data necessary to run
these drivers are in files DATA1.DAT, DATA2.DAT and DATA3.DAT; the
reports generated by these drivers are shown in the Reference Guide (file
GUIDE.PS), Section 2.C.
The names of the data file specified in the "OPEN" statement in these
drivers are "DATA1", "DATA2", and "DATA3", respectively. The data file
name and/or the file name specified in the "OPEN" statement might have to
be changed in order for the drivers to run properly on the target
machine.
* Files D_TEST.F and S_TEST.F contain drivers that exercise ODRPACK's main
features and can be used to verify that the installation was completed
successfully. The ODRPACK output generated by D_TEST.F when run on a
Sparc2 Workstation using the double precision version of ODRPACK is
listed in file TEST.TXT. No data files are required for these two
drivers.
These two programs each call the ODRPACK user callable subprograms
several times, with each call testing one or more features of the
package. The results of each call are automatically compared to the
results obtained by the authors using the double precision version of
ODRPACK run on a Cray YMP (128 bits per double precision value). The
ODRPACK reports generated by these drivers are written to files REPORT
and SUMMARY. (When using ODRPACK's MAKEFILE, both REPORT and SUMMARY are
copied to file D_TEST.OUT after execution of D_TEST.F, and S_TEST.OUT
after executing S_TEST.F.) By running these demonstration programs and
then comparing file REPORT with TEST.TXT, the installer can easily
ascertain whether the package is performing as it should.
If the REPORT files indicate that the results generated by the target
machine disagree significantly with the expected results, the installer
should attempt to determine why. The 3 most common causes of
disagreement between the computed results and the expected results are:
1. incorrectly specified machine dependent constants (see Step 3 above);
2. use of the single precision version of ODRPACK on a target machine
that requires double precision accuracy (see Step 1 above); and
3. compiler "bugs."
We suggest that these potential problem areas be investigated before
accepting a questionable installation as adequate. If you are unable to
find the cause of the reported disagreement, please feel free to contact
the developers at the address given above.
Step 6. Distribute ODRPACK documentation
The ODRPACK User's Reference Guide, NISTIR 92-4834, is supplied in PostScript
format in file GUIDE.PS. A "hard copy" of this 100 page document can also be
obtained from the developers at the address cited above. The ODRPACK
documentation can be reproduced and distributed as necessary for local users.