January 13, 1993 Installation notes for INTLIB. ============ ===== === ====== Nine files, totalling around 745,312 bytes are shipped with INTLIB. ==== ===== These are in the following groups: 1. INSTALL.NOT (Approx. 7,577 bytes) =========== This file. 2. SOFTPAPR.TEX (Approx. 22,648 bytes) ============ An AMS-TeX explanation of this package. This paper also will appear in the journal Interval Computations. 3. Files representing the routines in the five parts of this package: a) D1I1MACH.FOR ============ (Approx. 28,380 bytes) which contains the routines D1MACH and I1MACH from the SLATEC package. b) BASICOPS.FOR (Approx. 32,651 bytes) ============ which contains the routines for interval inclusions for the elementary arithmetic operations. These are ADD, CANCEL, IDIV, MULT, RNDOUT, SCLADD, SCLMLT and SUB. Documentation for these routines appears in their prologues. c) UTILFUNS.FOR (Approx. 28,940 bytes) ============ which contains basic utility functions for operations such as intersection of intervals, checking inclusion of one interval in another, and so on. The routines are ICAP, IDISJ, IHULL, IILEI, IILTI, IINF, IMID, IMIG, INEG, INTABS, IRLEI, IRLTI, ISUP, IVL1, IVL2 and IWID. d) ELEMFUNS.FOR (Approx. 163,618 bytes) ============ which contains routines for the elementary functions. The routines are IACOS, IACOT, IASIN, IATAN, ICOS, IEXP, IIPOWR, ILOG, ISIN, ISINH, ISQRT, AND POWER. e) MISCMACH.FOR (Approx. 29,860 bytes) ============ which contains the routine ERRTST, used to print information about error conditions. It also contains the routine SIMINI, in which global variables specifying interval inclusions for mathematical constants are set. Some assumptions on the arithmetic are given in the prologue to SIMINI. 4. TSTPROGS.FOR (Approx. 165,476 bytes) ============ The main test driver and the test subroutines for the individual functions. These are TSTDRV, TIACOS, TIACOT, TIASIN, TIATAN, TICOS, TIEXP, TIIPWR, TILOG, TINPWR, TISIN, TISINH, TISQRT, and TIUTIL. 5. INTLIBTS.OUT (Approx. 266,162 bytes) ============ An output file produced by running TSTDRV on an MS-DOS system with Microsoft Fortran compiler version 4.1. Installation consists of: ============ ======== === A. Altering D1MACH and I1MACH for the particular machine in use. As provided, these routines may be set for MS-DOS systems. They will need to be changed for other systems, as indicated in their in-line documentation. D1MACH and I1MACH are possibly already on the system; in that case, they may be deleted from the file D1I1MACH. CAUTION: ======= Use of the machine constants in D1MACH is not rigorous on machines which do not have guard digits. See Kulisch and Miranker, "A New Approach to Scientific Computation," Academic Press, 1983, pp. 5--6. On such machines (such as Cray machines), INTBIS can be made rigorous by using a larger value for D1MACH(4) (representing the largest relative distance between floating point numbers). This is analogous to choosing a larger epsilon-* in the Kulisch/Miranker analysis, and is equivalent to assuming the computer's wordlength is somewhat smaller. In effect, the technique uses part of the computer word as guard digits, to avoid the type of subtraction error illustrated in Kulisch / Miranker. Generally, only one or two such guard digits are needed. For example, on a hypothetical decimal machine with D1MACH(4) = 10**(-8), use of 10**(-7) instead should do. Input data should then be stored into intervals using the routines IVL1 and IVL2, which will round out in this lower precision. If there are any doubts, please contact R. Baker Kearfott at the address below. B. Carefully reading the assumptions in SIMINI (in item 3(e) above), and possibly altering SIMINI. C. Possibly altering the test driver TSTDRV.FOR, in item 4 above. The only items that should require alteration is the OPEN statement, the first executable statement, and the parameter IOUTUN, giving the unit number for output. D. No other files should need to be altered. Please inform us if this is not so. E. Compiling D1I1MACH, BASICOPS, UTILFUNS ELEMFUNS, and MISCMACH The object code should be made available as libraries or in other formats, so that the individual routines in these files are available to user calling programs. Note that D1I1MACH may already be installed on the system. F. Compiling TSTPROGS.FOR. G. Linking and running TSTPROGS. No input files are required. If possible, the system should be set so that execution continues after overflows and underflows. Underflows should be set to zero. H. Carefully examining the output file. The philosophy underlying the testing is explained in "INTLIB: A Portable Fortran-77 Elementary Function Library," in the file SOFTPAPR.TEX. Successful tests do not rigorously prove that the functions in the package will not ever give erroneous results (though we have done our best to ensure that they never do). An unsuccessful test may have the following causes: (i) improper installation, (ii) inaccurate elementary functions supplied with the Fortran compiler, or (iii) (heaven forbid) a bug or bugs in the package. The output file from the testing can be compared with the output files INTLIBTS.OUT. However, the output will vary from system to system, especially on the last twenty evaluations of the functions. These evaluations are at pseudo-random intervals which are scaled each individual floating point system. The provided output files should be considered a guide on what to expect. Some of the evaluations will cause error messages to be printed. This is normal, as is illustrated in the sample output files. The summary sections in the output file should be interpreted carefully. In particular, the "maximum relative error with point input" and "maximum absolute error with point input" are given. It is possible that the routines are functioning correctly, yet both of these may be large. There are two reasons for this. First, some of the "point" input is actually intervals with small relative widths. Second, in some regions of the range of some of the functions, relative error is a natural measure, whereas, in other regions, absolute error is the natural measure. For the sine and cosine functions, absolute error is natural measure. For the exponential function, relative error is a natural measure. Also, in many cases, the functions are tested very strictly, near the extremes of the particular floating point system. Of course, both relative and absolute accuracy could be improved if a higher precision data type were assumed to be available. If the package is to be used with INTBIS: == === ======= == == == ==== ==== ======= Routines in INTBIS of the same name as routines in this package should be deleted, and the new routines (in this package) should be used instead. In particular, the old versions of ADD, MULT, POWER, RNDOUT, SCLADD, SCLMLT, SIMINI, and SUB should be deleted. If optimal elementary functions are available in Fortran: == ======= ========== ========= === ========= == ======== If the return-values of the elementary functions are within one unit in the last place of the corresponding mathematical values of the function, then considerable simplification and speedup are possible. Basically, calls to routines like RCOS (routines R*) can be replaced by calls to corresponding elementary functions. If IEEE arithmetic is used: == ==== ========== == ===== Simplifications are possible in various places if IEEE arithmetic is used. If Fortran 90 operator overloading is desired: == ======= == ======== =========== == ======= A Fortran 90 module is available from the address below. No additional modifications should be necessary in order to provide an interval data type. ------------------------------------------------------------------------ We have endeavored to make this package easy to use, maintain, and modify. Please contact us with comments, questions, or problems. We would particularly like to receive suggestions for improvement. R. Baker Kearfott Department of Mathematics University of Southwestern Louisiana U. S. L. Box 4-1010 Lafayette, LA 70504-1010 USA Work phone: (318) 231-5270 Home phone: (318) 981-9744 Email: rbk@usl.edu (Internet) The easiest way to reach me is by email.