C      ALGORITHM 676, COLLECTED ALGORITHMS FROM ACM.
C      THIS WORK PUBLISHED IN TRANSACTIONS ON MATHEMATICAL SOFTWARE,
C      VOL. 15, NO. 4, PP. 348-364.
 Installation Manual for
 ODRPACK 1.71 -- Software for Weighted Orthogonal Distance Regression
 
 
 Direct questions to
 
      Janet R. Donaldson
      Optimization Group/Applied and Computational Mathematics Division (719)
      National Institute of Standards and Technology
      325 Broadway
      Boulder, CO 80303-3328
      (303) 497-5114
      e-mail:  internet -- jrd@alpha.bldr.nist.gov
               bitnet   -- jrd@nbs
 
 
 *** PHYSICAL CHARACTERISTICS OF TAPE
 
      A.  ASCII character set.
      B.  1600 cpi density.
      C.  Unlabeled.
      D.  17 files each repeated 3 times for a total of 51 files,
          each terminated by tapemarks.
      E.  Additional tapemark follows tapemark of last file.
      F.  Files consist of 1 or more blocks (physical records).
      G.  Files 1 to 16, 18 to 33, and 35 to 50 have blocks made up of 45
          line images (logical records) of 80 characters each.
      H.  Files 17, 34, and 51 have blocks made up of 20
          line images (logical records) of 132 characters each.
      I.  Last block of a file may contain fewer than 20 line images, in which
          case it is short, not blank filled.
 
 
 *** TAPE CONTENTS
 
 File No.  File Id.       Description
 --------  -----------    -----------
 
        1  TOC.DOC      - tape characteristics, file structure and
                          table of contents
                          (line image length = 80, block size = 3600)
 
        2  INSTALL.DOC  - the installation manual
                          (line image length = 80, block size = 3600)
        3  GUIDE.DOC    - ODRPACK user's reference guide,
                          in line printer format
                          (line image length = 80, block size = 3600)
 
 
        4  SODR.FOR     - single precision ODRPACK source code, excluding
                          LINPACK, BLAS and machine dependent subprograms
                          (line image length = 80, block size = 3600)
        5  SODRLPK.FOR  - single precision subprograms from LINPACK and BLAS
                          (line image length = 80, block size = 3600)
        6  SMPREC.FOR   - single precision machine dependent subprogram
                          (line image length = 80, block size = 3600)
 
 
        7  DODR.FOR     - double precision ODRPACK source code, excluding
                          LINPACK, BLAS and machine dependent subprograms
                          (line image length = 80, block size = 3600)
        8  DODRLPK.FOR  - double precision subprograms from LINPACK and BLAS
                          (line image length = 80, block size = 3600)
        9  DMPREC.FOR   - double precision machine dependent subprogram
                          (line image length = 80, block size = 3600)
 
 
       10  SDRIVE1.FOR  - sample driver for single precision user-callable
                          subprogram SODR
                          (line image length = 80, block size = 3600)
       11  SDRIVE2.FOR  - sample driver for single precision user-callable
                          subprogram SODRC
                          (line image length = 80, block size = 3600)
       12  DDRIVE1.FOR  - sample driver for double precision user-callable
                          subprogram DODR
                          (line image length = 80, block size = 3600)
       13  DDRIVE2.FOR  - sample driver for double precision user-callable
                          subprogram DODRC
                          (line image length = 80, block size = 3600)
 
       14  DATA1.DAT    - data set for sample drivers in files SDRIVE1.FOR,
                          SDRIVE2.FOR, DDRIVE1.FOR, and DDRIVE2.FOR.
                          (line image length = 80, block size = 3600)
 
 
       15  STEST.FOR    - driver for exercising single precision version
                          of ODRPACK
                          (line image length = 80, block size = 3600)
       16  DTEST.FOR    - driver for exercising double precision version
                          of ODRPACK
                          (line image length = 80, block size = 3600)
 
       17  TEST.TXT     - results obtained by the authors exercising the
                          double precision version of ODRPACK on a Sun 3
                          Workstation (64 bits per double precision value)
                          (line image length = 132, block size = 2640)
 
 
 18 to 34               - repeat of files 1 to 17
 
 
 35 to 51               - repeat of files 1 to 17
 
 
 
 *** INTRODUCTION
 
 ODRPACK is a portable collection of Fortran subprograms for fitting a model to
 data.  It is designed primarily for instances when the independent as well as
 the dependent 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.
 
 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 77 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
 
 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.  (Subprogram
 JAC, which is included in both source files SODR.FOR and DODR.FOR, is a dummy
 routine that is provided to prevent the occurrence of an unsatisfied external
 when finite difference derivatives are used.  Either version can be used in
 a combined library.)
 
 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.
 
 If both versions of ODRPACK have sufficient precision on the installer's
 machine, then both may be used.  When both the single and double precision
 versions are available, however, there are trade offs between them.  The
 double precision version will offer greater accuracy in results, while the
 single precision will require less storage and possibly less machine time.
 
 
 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 SODR.FOR,
 SODRLPK.FOR and SMPREC.FOR for the single precision version, and in files
 DODR.FOR, DODRLPK.FOR and DMPREC.FOR for the double precision version.
 
 Files SODR.FOR and DODR.FOR 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 SODRLPK.FOR and DODRLPK.FOR 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 SMPREC.FOR and DMPREC.FOR 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.
 
 
 Step 3.  Set Necessary Machine Dependent Values
 
 Files SMPREC.FOR and DMPREC.FOR supply the machine dependent constants used by
 ODRPACK.  Comment statements within these files document the modifications
 required.  They also list the necessary 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 before compiling and running ODRPACK.
 
 
 Step 4.  Compile ODRPACK Code and Generate Object Code Library
 
 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 a Sun 3 Workstation.  We believe it is possible to
 install ODRPACK on any system with an ANSI Fortran 77 compiler and adequate
 memory.  The authors have detected compiler bugs, however, that affect ODRPACK
 when using FTN200 Cycle 661B on the Cyber 205 and when using Profort 1.0 and
 1.19 on the IBM PC/AT.
 
 In compiling ODRPACK, we recommend that the following compiler options be used
 if available.
 
    1.  Rounded arithmetic.
 
    2.  The most extensive set of error messages possible.  (In our experience
        it is well worth hearing everything that a compiler has to say about
        imported code.)
 
 Let us emphasize that we do not expect any problems with compilation.
 
 After the ODRPACK code has been successfully compiled, a Fortran object code
 library must be created.  The term object code library here refers to whatever
 facility the target system has for satisfying external references
 automatically at load time, using a collection of previously compiled
 subprograms.
 
 
 Step 5.  Test ODRPACK
 
 The ODRPACK supplied software includes drivers and data sets for running
 ODRPACK in both single and double precision.  There are three drivers for each
 version of the code.
 
 Files SDRIVE1.FOR, SDRIVE2.FOR, DDRIVE1.FOR and DDRIVE2.FOR contain simple
 programs that users can modify to form their own ODRPACK drivers.  The data
 necessary to run these drivers are in file DATA1.DAT; the reports generated by
 these drivers are shown in the Reference Guide (file GUIDE.DOC), Section VII.
 (The name of the data file specified in the 'OPEN' statement in these two
 drivers is 'DATA1'.  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 STEST.FOR and DTEST.FOR 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 DTEST.FOR when run on a Sun 3
 Workstation using the double precision version of ODRPACK is listed in file
 TEST.TXT.  No data files are required for these two drivers.
 
 The drivers within files STEST.FOR and DTEST.FOR call subprograms SODRX and
 DODRX, respectively, as documented by the comment statements within each of
 the drivers.  These two subprograms 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
 CDC Cyber 205 under VSOS 2.3.7 PSR level 712 (124 bits per double precision
 value).  The success or failure of each test is noted individually in the
 output and is summarized for all of the data sets.
 
 The ODRPACK reports generated by these two drivers and a summary of the
 comparisons are written to files REPORT and SUMMARY, respectively.  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 and SUMMARY files indicate that the results generated by the
 target machine disagree 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 Reference Guide is supplied in line printer format in file
 GUIDE.DOC.  It is the installer's responsibility to make this documentation
 and future modifications to it available to local users.
 
 The on line documentation uses the standard Fortran conventions for printing
 formatted records.  In particular, the first character of each line is used to
 determine vertical spacing.  For correct printing, if the first character of a
 line is a blank then the printer should vertical space one line, and if the
 first character is a 1 then the printer should advance to the beginning of a
 new page.  The maximum page width is 80 columns (printer control included).
 The installer may modify the on line documentation as necessary if its format
 is not convenient.
