relibc_openlibm/slatec/guide

 
 
 
 
           *********************************************************
           *                                                       *
           *    Guide to the SLATEC Common Mathematical Library    *
           *                                                       *
           *********************************************************
 
 
                                 Kirby W. Fong
                 National Magnetic Fusion Energy Computer Center
                     Lawrence Livermore National Laboratory
 
 
                              Thomas H. Jefferson
                           Operating Systems Division
                     Sandia National Laboratories Livermore
 
 
                               Tokihiko Suyehiro
                   Computing and Mathematics Research Division
                     Lawrence Livermore National Laboratory
 
 
                                   Lee Walton
                           Network Analysis Division
                    Sandia National Laboratories Albuquerque
 
                                   July 1993
 
 
 
 
*******************************************************************************
 
                               Table of Contents
 
 
SECTION 1.  ABSTRACT
SECTION 2.  BACKGROUND
SECTION 3.  MEMBERS OF THE SLATEC COMMON MATHEMATICAL LIBRARY SUBCOMMITTEE
SECTION 4.  OBTAINING THE LIBRARY
SECTION 5.  CODE SUBMISSION PROCEDURES
SECTION 6.  CODING GUIDELINES--GENERAL REQUIREMENTS FOR SLATEC
SECTION 7.  SOURCE CODE FORMAT
SECTION 8.  PROLOGUE FORMAT FOR SUBPROGRAMS
SECTION 9.  EXAMPLES OF PROLOGUES
SECTION 10. SLATEC QUICK CHECK PHILOSOPHY
SECTION 11. SPECIFIC PROGRAMMING STANDARDS FOR SLATEC QUICK CHECKS
SECTION 12. QUICK CHECK DRIVERS (MAIN PROGRAMS)
SECTION 13. QUICK CHECK SUBROUTINE EXAMPLE
SECTION 14. QUICK CHECK MAIN PROGRAM EXAMPLE
 
APPENDIX A.  GAMS (AND SLATEC) CLASSIFICATION SCHEME
APPENDIX B.  MACHINE CONSTANTS
APPENDIX C.  ERROR HANDLING
APPENDIX D.  DISTRIBUTION FILE STRUCTURE
APPENDIX E.  SUGGESTED FORMAT FOR A SLATEC SUBPROGRAM
 
ACKNOWLEDGEMENT
REFERENCES
 
 
 
 
*******************************************************************************
 
SECTION 1.  ABSTRACT
 
This document is a guide to the SLATEC Common Mathematical Library (CML) [1].
The SLATEC CML is written in FORTRAN 77 (ANSI standard FORTRAN as defined by
ANSI X3.9-1978, reference [6]) and contains general purpose mathematical and
statistical routines.  Included in this document are a Library description,
code submission procedures, and a detailed description of the source file
format.  This report serves as a guide for programmers who are preparing codes
for inclusion in the library.  It also provides the information needed to
process the source file automatically for purposes such as extracting
documentation or inserting usage monitoring calls.  This guide will be updated
periodically, so be sure to contact a SLATEC CML subcommittee member to ensure
you have the latest version.
 
 
 
 
*******************************************************************************
 
SECTION 2.  BACKGROUND
 
SLATEC is the acronym for the Sandia, Los Alamos, Air Force Weapons Laboratory
Technical Exchange Committee.  This organization was formed in 1974 by the
computer centers of Sandia National Laboratories Albuquerque, Los Alamos
National Laboratory, and Air Force Weapons Laboratory to foster the exchange of
technical information.  The parent committee established several subcommittees
to deal with various computing specialties.  The SLATEC Common Mathematical
Library (CML) Subcommittee decided in 1977 to construct a mathematical FORTRAN
subprogram library that could be used on a variety of computers at the three
sites. A primary impetus for the library development was to provide portable,
non-proprietary, mathematical software for member sites' supercomputers.
 
In l980 the computer centers of Sandia National Laboratories Livermore and the
Lawrence Livermore National Laboratory were admitted as members of the parent
committee and subcommittees. Lawrence Livermore National Laboratory, unlike the
others, has two separate computer centers: the National Magnetic Fusion Energy
Computer Center (NMFECC) and the Livermore Computer Center (LCC).  In 1981 the
National Bureau of Standards (now the National Institute of Standards and
Technology) and the Oak Ridge National Laboratory were invited to participate
in the math library subcommittee because of their great interest in the
project.
 
Version 1.0 of the CML was released in April 1982 with 114,328 records and 491
user-callable routines.  In May 1984 Version 2.0, with 151,864 records and 646
user-callable routines was released.  This was followed in April 1986 by
Version 3.0 with 196,013 records and 704 user-callable routines.  Version 3.1
followed in August 1987 with 197,931 records and 707 user-callable routines
and Version 3.2 in August 1989 with 203,587 records and 709 user-callable
routines.  The committee released Version 4.0 in December 1992 with 298,954
records and 901 user-callable routines.  Finally, on July 1, 1993, Version 4.1
was released with 290,907 records and 902 user-callable routines.
 
The sole documentation provided by SLATEC for the routines of the SLATEC
Library is via comment lines in the source code.  Although the library comes
with portable documentation programs to help users access the documentation in
the source code, various installations may wish to use their own documentation
programs.  To facilitate automatic extraction of documentation or further
processing by other computer programs, the source file for each routine must
be arranged in a precise format.  This document describes that format for the
benefit of potential library contributors and for those interested in
extracting library documentation from the source code.
 
 
 
 
*******************************************************************************
 
SECTION 3.  MEMBERS OF THE SLATEC COMMON MATHEMATICAL LIBRARY SUBCOMMITTEE
 
Current member sites and voting members of the subcommittee are the
following.
 
 
Air Force Phillips Laboratory, Kirtland (PLK)          Reginald Clemens
 
Lawrence Livermore National Laboratory (LCC)           Fred N. Fritsch
 
Lawrence Livermore National Laboratory (NERSC)         Steve Buonincontri
 
Los Alamos National Laboratory (LANL)                  W. Robert Boland
                                                       (Chairman)
 
National Institute of Standards and Technology (NIST)  Daniel W. Lozier
 
Oak Ridge National Laboratory (ORNL)                   Thomas H. Rowan
 
Sandia National Laboratories/California (SNL/CA)       Thomas H. Jefferson
 
Sandia National Laboratories/New Mexico (SNL/NM)       Sue Goudy
 
 
 
 
*******************************************************************************
 
SECTION 4.  OBTAINING THE LIBRARY
 
The Library is in the public domain and distributed by the Energy Science
and Technology Software Center.
 
               Energy Science and Technology Software Center
               P.O. Box 1020
               Oak Ridge, TN  37831
 
               Telephone  615-576-2606
               E-mail  estsc%a1.adonis.mrouter@zeus.osti.gov
 
 
 
*******************************************************************************
 
SECTION 5.  CODE SUBMISSION PROCEDURES
 
The SLATEC Library is continuously searching for portable high-quality routines
written in FORTRAN 77 that would be of interest to the member sites.  The
subcommittee meets several times annually with the member sites rotating as
meeting hosts.  At these meetings new routines are introduced, discussed, and
eventually voted on for inclusion in the library.  Some of the factors that are
considered in deciding whether to accept a routine into the Library are the
following:
 
 
1.  Usefulness.  Does the routine fill a void in the Library?  Will the routine
    have widespread appeal?  Will it add a new capability?
 
2.  Robustness.  Does the routine give accurate results over a wide range of
    problems?  Does it diagnose errors?  Is the routine well tested?
 
3.  Maintainability.  Is the author willing to respond to bugs in the routine?
    Does the source code follow good programming practices?
 
4.  Adherence to SLATEC standards and coding guidelines.  These standards
    are described further in this guide and include such things as the order
    of subprogram arguments, the presence of a correctly formatted prologue at
    the start of each routine, and the naming of routines.
 
5.  Good documentation.  Is clear, concise computer readable documentation
    built into the source code?
 
6.  Freely distributable.  Is the program in the public domain?
 
 
A typical submission procedure begins with contact between an author and a
Library committee member.  Preliminary discussions with the member are
encouraged for initial screening of any code and to gain insight into the
workings of SLATEC.  This member champions the routine to be considered.  The
code is introduced at a meeting where the author or committee member describes
the code and explains why it would be suitable for SLATEC.  Copies of the code
are distributed to all committee members.  Hopefully, the code already adheres
to SLATEC standards.  However, most codes do not.  At this first formal
discussion, the committee members are able to provide some useful suggestions
for improving the code and revising it for SLATEC.
 
Between meetings, changes are made to the code and the modified code is
distributed in machine readable format for testing.  The code is then
considered at a subsequent meeting, to be voted on and accepted. However,
because committee members and authors do not always see eye to eye, and because
time constraints affect all, the code is usually discussed at several meetings.
 
If codes adhered to the programming practices and formatting described in this
guide, the time for acceptance could be greatly reduced.
 
 
 
 
*******************************************************************************
 
SECTION 6.  CODING GUIDELINES--GENERAL REQUIREMENTS FOR SLATEC
 
A software collection of the size of the SLATEC Library that is designed to run
on a variety of computers demands uniformity in handling machine dependencies,
in handling error conditions, and in installation procedures.  Thus, while the
decision to add a new subroutine to the library depends mostly on its quality
and whether it fills a gap in the library, these are not the only
considerations.  Programming style must also be considered, so that the library
as a whole behaves in a consistent manner.  We now list the stylistic and
documentational recommendations and requirements for routines to be
incorporated into the library.
 
 
1.  The SLATEC Library is intended to have no restriction on its distribution;
    therefore, new routines must be in the public domain.  This is generally
    not a problem since most authors are proud of their work and would like
    their routines to be used widely.
 
2.  Routines must be written in FORTRAN 77 (ANSI standard FORTRAN as
    defined by ANSI X3.9-1978, reference [6]).  Care must be taken so that
    machine dependent features are not used.
 
3.  To enhance maintainability codes are to be modular in structure.  Codes
    must be composed of reasonably small subprograms which in turn are made
    up of easily understandable blocks.
 
4.  Equivalent routines of different precision are to look the same where
    possible.  That is, the logical structure, statement numbers, variable
    names, etc. are to be as close to identical as possible.  This implies
    that generic intrinsics must be used instead of specific intrinsics.
    Extraneous use of INT, REAL and DBLE are strongly discouraged;  use
    mixed-mode expressions in accordance with the Fortran 77 standard.
 
5.  New routines must build on existing routines in the Library, unless
    there are compelling reasons to do otherwise.  For example, the SLATEC
    Library contains the LINPACK and EISPACK routines, so new routines
    should use the existing linear system and eigensystem routines rather
    than introduce new ones.
 
6.  System or machine dependent values must be obtained by calling routines
    D1MACH, I1MACH, and R1MACH.  The SLATEC Library has adopted these routines
    from the Bell Laboratories' PORT Library [2] [3].  See Appendix B
    for a description of these machine dependent routines.
 
7.  The SLATEC Library has a set of routines for handling error messages.
    Each user-callable routine, if it can detect errors, must have as one
    of its arguments an error flag, whose value upon exiting the routine
    indicates the success or failure of the routine. It is acceptable for a
    routine to set the error flag and RETURN; however, if the routine wishes
    to write an error message, it must call XERMSG (see Appendix C) rather
    than use WRITE or PRINT statements.  In general, all errors (even serious
    ones) should be designated as "recoverable" rather than "fatal," and the
    routine should RETURN to the user.  This permits the user to try an
    alternate strategy if a routine decides a particular calculation is
    inappropriate.  A description of the entire original error handling
    package appears in reference [4].
 
8.  Each user-callable routine (and subsidiary routine if appropriate) must
    have a small demonstration routine that can be used as a quick check. This
    demonstration routine can be more exhaustive, but in general, it should be
    structured to provide a "pass" or "fail" answer on whether the library
    routine appears to be functioning properly.  A more detailed description
    of the required format of the quick checks appears later in this document.
 
9.  Common blocks and SAVEd variables must be avoided.  Use subprogram
    arguments for interprogram communication.  The use of these constructs
    often obstructs multiprocessing.
 
    Variables that are statically allocated in memory and are used as
    working storage cannot be used simultaneously by several processors.
    SAVEd variables and common block variables are most likely to fall into
    this category.  Such variables are acceptable if they are DATA loaded or
    set at run time to values that are to be read (but not written) since it
    does not matter in what order multiple processors read the values.
    However, such variables should not be used as working storage since no
    processor can use the work space while some other processor is using it.
    Library routines should ask the user to provide any needed work space
    by passing it in as an argument.  The user is then responsible for
    giving each processor a different work space even though each processor
    may be executing the same library routine.
 
10. Complete self-contained documentation must be supplied as comments in
    user-callable routines.  This documentation must be self-contained because
    SLATEC provides no other documentation for using the routines.  This
    documentation is called the "prologue" for the routine.  The rigid prologue
    format for user-callable routines is described below.  The prologue must
    tell the user how to call the routine but need not go into algorithmic
    details since such explanations often require diagrams or non-ASCII
    symbols.  Subsidiary routines are those called by other library routines
    but which are not intended to be called directly by the user.  Subsidiary
    routines also have prologues, but these prologues are considerably less
    elaborate than those of user-callable routines.
 
11. No output should be printed.  Instead, information should be returned
    to the user via the subprogram arguments or function values.  If there is
    some overriding reason that printed output is necessary, the user must be
    able to suppress all output by means of a subprogram input variable.
 
 
 
 
*******************************************************************************
 
SECTION 7.  SOURCE CODE FORMAT
 
In this section and the two sections on prologues, we use the caret (^)
character to indicate a position in which a single blank character must
appear. Upper case letters are used for information that appears literally.
Lower case is used for material specific to the routine.
 
1.  The first line of a subprogram must start with one of:
 
    SUBROUTINE^name^(arg1,^arg2,^...argn)
    FUNCTION^name^(arg1,^arg2,^...argn)
    COMPLEX^FUNCTION^name^(arg1,^arg2,^...argn)
    DOUBLE^PRECISION^FUNCTION^name^(arg1,^arg2,^...argn)
    INTEGER^FUNCTION^name^(arg1,^arg2,^...argn)
    REAL^FUNCTION^name^(arg1,^arg2,^...argn)
    LOGICAL^FUNCTION^name^(arg1,^arg2,^...argn)
    CHARACTER[*len]^FUNCTION^name^(arg1,^arg2,^...argn)
 
    Each of the above lines starts in column 7.  If there is an argument
    list, then there is exactly one blank after the subprogram name and
    after each comma (except if the comma appears in column 72).  There is
    no embedded blank in any formal parameter, after the leading left
    parenthesis, before the trailing right parenthesis,  or before any
    comma. Formal parameters are never split across lines. Any line to be
    continued must end with a comma.
 
    For continuation lines, any legal continuation character may be used in
    column 6, columns 7-9 must be blank and arguments or formal parameters
    start in column 10 of a continuation line and continue up to the right
    parenthesis (or comma if another continuation line is needed).  The
    brackets in the CHARACTER declaration do not appear literally but
    indicate the optional length specification described in the FORTRAN 77
    standard.
 
2.  The author must supply a prologue for each subprogram.  The prologue
    must be in the format that will subsequently be described.  The
    prologue begins with the first line after the subprogram declaration
    (including continuation lines for long argument lists).
 
3.  Except for the "C***" lines (to be described) in the prologue and
    the "C***" line marking the first executable statement, no other line
    may begin with "C***".
 
4.  The first line of the prologue is the comment line
 
    C***BEGIN^PROLOGUE^^name
 
    where "name", starting in column 21, is the name of the subprogram.
 
5.  The last line of a subprogram is the word "END" starting in column 7.
 
6.  All alphabetic characters, except for those on comment lines or in
    character constants, must be upper case, as specified by the FORTRAN 77
    standard (see [6]).
 
7.  In the prologue, the comment character in column 1 must be the upper
    case "C".
 
8.  All subprogram, common block, and any formal parameter names mentioned in
    the prologue must be in upper case.
 
9.  Neither FORTRAN statements nor comment lines can extend beyond column 72.
    Columns 73 through 80 are reserved for identification or sequence numbers.
 
10. Before the first executable statement of every subprogram, user-callable
    or not, is the line
 
    C***FIRST^EXECUTABLE^STATEMENT^^name
 
    where "name" (starting in column 33) is the name of the subprogram.
    Only comment lines may appear between the C***FIRST EXECUTABLE
    STATEMENT line and the first executable statement.
 
11. The subprogram name consists of a maximum of six characters.  Authors
    should choose unusual and distinctive subprogram names to minimize
    possible name conflicts.  Double precision routines should begin with
    "D".  Subprograms of type complex should begin with "C".  The letter "Z"
    is reserved for future use by possible double precision complex
    subprograms.  No other subprograms should begin with either "D", "C", or
    "Z".
 
12. The recommended order for the formal parameters is:
 
    1.  Names of external subprograms.
 
    2.  Input variables.
 
    3.  Variables that are both input and output (except error flags).
 
    4.  Output variables.
 
    5.  Work arrays.
 
    6.  Error flags.
 
    However, array dimensioning parameters should immediately follow the
    associated array name.
 
 
 
 
*******************************************************************************
 
SECTION 8.  PROLOGUE FORMAT FOR SUBPROGRAMS
 
Each subprogram has a section called a prologue that gives standardized
information about the routine.  The prologue consists of comment lines only.  A
subsidiary subprogram is one that is usually called by another SLATEC Library
subprogram only and is not meant to be called by a user's routine.  The
prologue for a user-callable subprogram is more extensive than the prologue for
a subsidiary subprogram.  The prologue for a user-callable subprogram has up to
14 sections, of which 12 are required and one is required if and only if a
common block is present.  Several of these sections are optional in subsidiary
programs and in the quick check routines.  The sections are always in the
order described in the table below.
 
 
          Section           User-callable      Subsidiary     Quick Checks
 
   1.   BEGIN PROLOGUE        Required         Required       Required
   2.   SUBSIDIARY            Not present      Required         Optional
   3.   PURPOSE               Required         Required       Required
   4.   LIBRARY   SLATEC      Required         Required       Required
   5.   CATEGORY              Required           Optional       Optional
   6.   TYPE                  Required         Required       Required
   7.   KEYWORDS              Required           Optional       Optional
   8.   AUTHOR                Required         Required       Required
   9.   DESCRIPTION           Required           Optional       Optional
  10.   SEE ALSO                Optional         Optional       Optional
  11.   REFERENCES            Required           Optional       Optional
  12.   ROUTINES CALLED       Required         Required       Required
  13.   COMMON BLOCKS         Required***      Required***    Required***
  14.   REVISION HISTORY      Required         Required       Required
  15.   END PROLOGUE          Required         Required       Required
 
    ***Note:  The COMMON BLOCKS section appears in a subprogram prologue
              if and only if the subprogram contains a common block.
 
In the prologue section descriptions that follow, the caret (^)
character is used for emphasis to indicate a required blank character.
 
 
1.  BEGIN PROLOGUE
    This section is a single line that immediately follows the subprogram
    declaration and its continuation lines.  It is
 
    C***BEGIN^PROLOGUE^^name
 
    where "name" (beginning in column 21) is the name of the subprogram.
 
2.  SUBSIDIARY
    This section is the single line
 
    C***SUBSIDIARY
 
    and indicates the routine in which this appears is not intended to be
    user-callable.
 
3.  PURPOSE
    This  section gives one to six lines of information on the purpose of the
    subprogram.  The letters may be in upper or lower case.  There are no blank
    lines in the purpose section; i.e., there are no lines consisting solely of
    a "C" in column 1.  The format for the first line and any continuation
    lines is
 
    C***PURPOSE^^information
    C^^^^^^^^^^^^more information
 
    Information begins in column 14 of the first line and no earlier than
    column 14 of continuation lines.
 
4.  LIBRARY   SLATEC
    The section is a single line used to show that the routine is a part
    of the SLATEC library and, optionally, to indicate other libraries,
    collections, or packages (sublibraries) of which the routine is a part
    or from which the routine has been derived.    The format is
 
    C***LIBRARY^^^SLATEC
            or
    C***LIBRARY^^^SLATEC^(sublib1,^sublib2,^...sublibn)
 
    The leading left parenthesis is immediately followed by the first member
    of the list.  Each member, except for the last, is immediately followed by
    a comma and a single blank.  The last member is immediately followed by
    the trailing right parenthesis.
 
5.  CATEGORY
    This section is a list of classification system categories to which
    this subprogram might reasonably be assigned.  There must be at least
    one list item.  The first category listed is termed the primary
    category, and others, if given, should be listed in monotonically
    decreasing order of importance.  Categories must be chosen from the
    classification scheme listed in Appendix A.  The required format for the
    initial line and any continuation lines is
 
    C***CATEGORY^^cat1,^cat2,^cat3,^...catn,
    C^^^^^^^^^^^^^continued list
 
    All alphabetic characters are in upper case.
 
    Items in the list are separated by the two characters, comma and space.
    If the list will not fit on one line, the line may be ended at a comma
    (with zero or more trailing spaces), and be continued on the next line.
    The list and any continuations of the list begin with a nonblank character
    in column 15.
 
6.  TYPE
    This section gives the datatype of the routine and indicates which
    routines, including itself,  are equivalent (except possibly for type) to
    the routine. The format for this section is
 
    C***TYPE^^^^^^routine_type^(equivalence list
    C^^^^^^^^^^^^^continued equivalence list
    C^^^^^^^^^^^^^continued equivalence list)
 
    Routine_type, starting in column 15, is the data type of the routine,
    and is either SINGLE PRECISION, DOUBLE PRECISION, COMPLEX, INTEGER,
    CHARACTER, LOGICAL, or ALL.  ALL is a pseudo-type given to routines that
    could not reasonably be converted to some other type.  Their purpose is
    typeless.  An example would be the SLATEC routine that prints error
    messages.
 
    Equivalence list is a list of the routines (including this one) that are
    equivalent to this one, but perhaps of a different type.  Each item in the
    list consists of a routine name followed by the "-" character and then
    followed by the first letter of the type (except use "H" for type
    CHARACTER) of the equivalent routine.  The order of the items is S, D, C,
    I, H, L and A.
 
    The initial item in the list is immediately preceded by a blank and a
    left parenthesis and the final item is immediately followed by a right
    parenthesis.  Items in the list are separated by the two characters,
    comma and space.  If the list will not fit on one line, the line may be
    ended at a comma (with zero or more trailing spaces), and be continued
    on the next line.  The list and any continuations of the list begin with
    a nonblank character in column 15.
 
    All alphabetic characters in this section are in upper case.
 
    Example
 
    C***TYPE      SINGLE PRECISION (ACOSH-S, DACOSH-D, CACOSH-C)
 
7.  KEYWORDS
    This section gives keywords or keyphrases that can be used by
    information retrieval systems to identify subprograms that pertain to
    the topic suggested by the keywords.  There must be at least one
    keyword.  Keywords can have embedded blanks but may not have leading or
    trailing blanks.  A keyword cannot be continued on the next line;  it
    must be short enough to fit on one line. No keyword can have an embedded
    comma. Characters are limited to the FORTRAN 77 character set (in
    particular, no lower case letters).  There is no comma after the last
    keyword in the list.  It is suggested that keywords be in either
    alphabetical order or decreasing order of importance.  The format for
    the initial line and any continuation lines is
 
    C***KEYWORDS^^list
    C^^^^^^^^^^^^^continued list
 
    Items in the list are separated by the two characters, comma and space.
    If the list will not fit on one line, the line may be ended at a comma
    (with zero or more trailing spaces), and be continued on the next line.
    The list and any continuations of the list begin with a nonblank character
    in column 15.
 
8.  AUTHOR
    This required section gives the author's name.  There must be at least one
    author, and there may be coauthors.  At least the last name of the author
    must be given.  The first name (or initials) is optional.  The company,
    organization, or affiliation of the author is also optional.  The brackets
    below indicate optional information.  Note that if an organization is to be
    listed, the remainder of the author's name must also be given.  If the
    remainder of the author's name is given, the last name is immediately
    followed by a comma.  If the organization is given, the first name (or
    initials) is immediately followed by a comma.  The remainder of the name
    and the organization name may have embedded blanks.  The remainder of the
    name may not have embedded commas.  This makes it possible for an
    information retrieval system to count commas to identify the remainder of
    the name and the name of an organization. Additional information about the
    author (e.g., address or telephone number) may be given on subsequent
    lines.  The templates used are
 
    C***AUTHOR^^last-name[,^first-name[,^(org)]]
    C^^^^^^^^^^^^^more information
    C^^^^^^^^^^^^^more information
        .
        .
        .
    C^^^^^^^^^^^last-name[,^first-name[,^(org)]]
    C^^^^^^^^^^^^^more information
        .
        .
        .
 
    Each author's name starts in column 13.  Continued information starts in
    column 15.
 
9.  DESCRIPTION
    This section is a description giving the program abstract, method used,
    argument descriptions, dimension information, consultants, etc.  The
    description of the arguments is in exactly the same order in which the
    arguments appear in the calling sequence.  The description section may use
    standard, 7-bit ASCII graphic characters, i.e., the 94 printing characters
    plus the blank.  Names of subprograms, common blocks, externals, and formal
    parameters are all in upper case.  Names of variables are also in upper
    case.  The first line of this section is "C***DESCRIPTION" starting in
    column 1.  All subsequent lines in this section start with a "C" in column
    1 and no character other than a blank in column 2.  Lines with only a "C"
    in column 1 may be used to improve the appearance of the description.
 
    A suggested format for the DESCRIPTION section is given in Appendix E.
 
10. SEE ALSO
    This section is used for listing other SLATEC routines whose prologues
    contain documentation on the routine in which this section appears.
    The form is
 
    C***SEE ALSO^^name,^name,^name
 
    where each "name" is the name of a user-callable SLATEC CML subprogram
    whose prologue provides a description of this routine. The names are
    given as a list (starting in column 15), with successive names separated
    by a comma and a single blank.
 
11. REFERENCES
    This section is for references.  Any of the 94 ASCII printing characters
    plus the blank may be used. There may be more than one reference.  If there
    are no references, the section will consist of the single line
 
    C***REFERENCES^^(NONE)
 
    If there are references, they will be in the following format:
 
    C***REFERENCES^^reference 1
    C^^^^^^^^^^^^^^^^^continuation of reference 1
        .
        .
        .
    C^^^^^^^^^^^^^^^reference 2
    C^^^^^^^^^^^^^^^^^continuation of reference 2
        .
        .
        .
 
    Information starts in column 17 of the first line of a reference and no
    earlier than column 19 of continuation lines.
 
    References should be listed in either alphabetical order by last name or
    order of citation.  They should be in upper and lower case, have initials
    or first names ahead of last names, and (for multiple authors) have
    "and" ahead of the last author's name instead of just a comma.  The first
    word of the title of journal articles should be capitalized as should all
    important words in titles of books, pamphlets, research reports, and
    proceedings.  Titles should be given without quotation marks.  The names
    of journals should be spelled out completely, or nearly so, because
    software users may not be familiar with them.
 
    A complete example of a journal reference is:
 
    C               F. N. Fritsch and R. E. Carlson, Monotone piecewise
    C                 cubic interpolation, SIAM Journal on Numerical Ana-
    C                 lysis, 17 (1980), pp. 238-246.
 
    A complete example of a book reference is:
 
    C               Carl de Boor, A Practical Guide to Splines, Applied
    C                 Mathematics Series 27, Springer-Verlag, New York,
    C                 1978.
 
12. ROUTINES CALLED
    This section gives the names of routines in the SLATEC Common Mathematical
    Library that are either directly referenced or declared in an EXTERNAL
    statement and passed as an argument to a subprogram.  Note that the FORTRAN
    intrinsics and other formal parameters that represent externals are not
    listed.  A list is always given for routines called; however, if no routine
    is called, the list will be the single item "(NONE)" where the parentheses
    are included.  If there are genuine items in the list, the items are in
    alphabetical order.  The collating sequence has "0" through "9" first, then
    "A" through "Z".  The format is
 
    C***ROUTINES^CALLED^^name,^name,^name,^name,
    C^^^^^^^^^^^^^^^^^^^^name,^name,^name
 
    Items in the list are separated by the two characters, comma and space.
    If the list will not fit on one line, the line may be ended at a comma
    (with zero or more trailing spaces), and be continued on the next line.
    The list and any continuations of the list begin with a nonblank character
    in column 22.
 
13. COMMON BLOCKS
    This section, that may or may not be required, tells what common blocks are
    used by this subprogram.  If this subprogram uses no common blocks, this
    section does not appear.  If this subprogram does use common blocks, this
    section must appear.  The list of common blocks is in exactly the same
    format as the list of routines called and uses the same collating sequence.
    In addition, the name of blank common is "(BLANK)" where the parentheses
    are included.  Blank common should be last in the list if it appears. The
    format for this section is
 
    C***COMMON^BLOCKS^^^^name,^name,^name,^name,
    C^^^^^^^^^^^^^^^^^^^^name,^name,^name^
 
    The list starts in column 22.
 
14. REVISION HISTORY
    This section provides a summary of the revisions made to this code.
    Revision dates and brief reasons for revisions are given.  The format is
 
    C***REVISION^HISTORY^^(YYMMDD)
    C^^^yymmdd^^DATE^WRITTEN
    C^^^yymmdd^^revision description
    C^^^^^^^^^^^more revision description
    C^^^^^^^^^^^...
    C^^^yymmdd^^revision description
    C^^^^^^^^^^^more revision description
    C^^^^^^^^^^^...
    C^^^^^^^^^^^...
 
    where, for each revision,  "yy" (starting in column 5) is the last two
    digits of the year, "mm" is the month (01, 02, ..., 12), and "dd" is the
    day of the month (01, 02, ..., 31).  Because this ANSI standard form for
    the date may not be familiar to some people, the character string
    "(YYMMDD)" (starting in column 23) is included in the first line of the
    section to assist in interpreting the sequence of digits.  Each line of the
    revision descriptions starts in column 13.  The second line of this section
    contains the date the routine was written, with the characters "DATE
    WRITTEN" beginning in column 13.  These items must be in chronological
    order.
 
15. END PROLOGUE
    The last section is the single line
 
    C***END^PROLOGUE^^name
 
    where "name" is the name of the subprogram.
 
 
 
 
*******************************************************************************
 
SECTION 9.  EXAMPLES OF PROLOGUES
 
This section contains examples of prologues for both user-callable
and subsidiary routines.  The routines are not from the SLATEC CML and
should be used only as guidelines for preparing routines for SLATEC.
Note that the C***DESCRIPTION sections follow the suggested LDOC format that
is described in Appendix E.  Following the suggested LDOC format with its
"C *"subsections helps to ensure that all necessary descriptive information is
provided.
 
      SUBROUTINE ADDXY (X, Y, Z, IERR)
C***BEGIN PROLOGUE  ADDXY
C***PURPOSE  This routine adds two single precision numbers together
C            after forcing both operands to be stored in memory.
C***LIBRARY   SLATEC
C***CATEGORY  A3A
C***TYPE      SINGLE PRECISION (ADDXY-S, DADDXY-D)
C***KEYWORDS  ADD, ADDITION, ARITHMETIC, REAL, SUM,
C             SUMMATION
C***AUTHOR  Fong, K. W., (NMFECC)
C             Mail Code L-560
C             Lawrence Livermore National Laboratory
C             Post Office Box 5509
C             Livermore, CA  94550
C           Jefferson, T. H., (SNLL)
C             Org. 8235
C             Sandia National Laboratories Livermore
C             Livermore, CA  94550
C           Suyehiro, T., (LLNL)
C             Mail Code L-316
C             Lawrence Livermore National Laboratory
C             Post Office Box 808
C             Livermore, CA  94550
C***DESCRIPTION
C
C *Usage:
C
C     INTEGER IERR
C     REAL X, Y, Z
C
C     CALL ADDXY (X, Y, Z, IERR)
C
C *Arguments:
C
C  X :IN   This is one of the operands to be added.  It will not
C          be modified by ADDXY.
C
C  Y :IN   This is the other operand to be added.  It will not be
C          modified by ADDXY.
C
C  Z :OUT  This is the sum of X and Y.  In case of an error,
C          this argument will not be modified.
C
C  IERR:OUT  This argument will be set to 0 if ADDXY added the two
C          operands.  It will be set to 1 if it appears the addition
C          would generate a result that might overflow.
C
C *Description:
C
C  ADDXY first divides X and Y by the largest single precision number
C  and then adds the quotients.  If the absolute value of the sum is
C  greater than 1.0, ADDXY returns with IERR set to 1.  Otherwise
C  ADDXY stores X and Y into an internal array and calls ADDZZ to add
C  them.  This increases the probability (but does not guarantee) that
C  operands and result are stored into memory to avoid retention of
C  extra bits in overlength registers or cache.
C
C***REFERENCES  W. M. Gentleman and S. B. Marovich, More on algorithms
C                 that reveal properties of floating point arithmetic
C                 units, Communications of the ACM, 17 (1974), pp.
C                 276-277.
C***ROUTINES CALLED  ADDZZ, R1MACH, XERMSG
C***REVISION HISTORY  (YYMMDD)
C   831109  DATE WRITTEN
C   880325  Modified to meet new SLATEC prologue standards.  Only
C           comment lines were modified.
C   881103  Brought DESCRIPTION section up to Appendix E standards.
C   921215  REFERENCE section modified to reflect recommended style.
C***END PROLOGUE  ADDXY
      DIMENSION R(3)
C***FIRST EXECUTABLE STATEMENT  ADDXY
      BIG = R1MACH( 2 )
C
C  This is an example program, not meant to be taken seriously.  The
C  following illustrates the use of XERMSG to send an error message.
C
      IF ( (ABS((X/BIG)+(Y/BIG))-1.0) .GT. 0.0 ) THEN
         IERR = 1
         CALL XERMSG ( 'SLATEC', 'ADDXY', 'Addition of the operands '//
     *      'is likely to cause overflow', IERR, 1 )
      ELSE
         IERR = 0
         R(1) = X
         R(2) = Y
         CALL ADDZZ( R )
         Z    = R(3)
      ENDIF
      RETURN
      END
      SUBROUTINE ADDZZ (R)
C***BEGIN PROLOGUE  ADDZZ
C***SUBSIDIARY
C***PURPOSE  This routine adds two single precision numbers.
C***LIBRARY   SLATEC
C***AUTHOR  Fong, K. W., (NMFECC)
C             Mail Code L-560
C             Lawrence Livermore National Laboratory
C             Post Office Box 5509
C             Livermore, CA  94550
C           Jefferson, T. H., (SNLL)
C             Org. 8235
C             Sandia National Laboratories Livermore
C             Livermore, CA  94550
C           Suyehiro, T., (LLNL)
C             Mail Code L-316
C             Lawrence Livermore National Laboratory
C             Post Office Box 808
C             Livermore, CA  94550
C***SEE ALSO  ADDXY
C***ROUTINES CALLED  (NONE)
C***REVISION HISTORY  (YYMMDD)
C   831109  DATE WRITTEN
C   880325  Modified to meet new SLATEC prologue standards.  Only
C           comment lines were modified.
C***END PROLOGUE  ADDZZ
      DIMENSION R(3)
C***FIRST EXECUTABLE STATEMENT  ADDZZ
      R(3) = R(1) + R(2)
      RETURN
      END
 
 
 
 
*******************************************************************************
 
 
SECTION 10. SLATEC QUICK CHECK PHILOSOPHY
 
The SLATEC Library is distributed with a set of test programs that may be used
as an aid to insure that the Library is installed correctly.  This set of test
programs is known as the SLATEC quick checks.  The quick checks are not meant
to provide an exhaustive test of the Library.  Instead they are designed to
protect against gross errors, such as an unsatisfied external.  Because the
SLATEC Library runs on a great variety of computers, the quick checks often
detect arithmetic difficulties with either particular Library routines or with
a particular computational environment.
 
A list of the quick check guidelines follows.
 
1.  A quick check should test a few problems successfully solved by a
    particular library subprogram.  It is not intended to be an extensive
    test of a subprogram.
 
2.  A quick check should provide consistent and minimal output in most
    cases, including a "PASS" or "FAIL" indicator.  However, more detailed
    output should be available on request to help track down problems in the
    case of failures.
 
3.  Some reasonable error conditions should be tested by the quick check by
    purposefully referencing the routine incorrectly.
 
4.  A quick check subprogram is expected to execute correctly on any machine
    with an ANSI Fortran 77 compiler and library.  No test should have to be
    skipped to avoid an abort on a particular machine.
 
5.  As distributed on the SLATEC tape, the quick check package consists of a
    number of quick check main programs and a moderate number of subprograms.
    Each quick check main program, more frequently called a quick check driver,
    calls one or more quick check subprograms.  Usually, a given driver
    initiates the tests for a broadly related set of subprograms, e.g. for the
    single precision Basic Linear Algebra Subprograms (BLAS).  Each quick
    check subprogram will test one or more closely related library routines of
    the same precision.  For example, single precision routines and their
    double precision equivalents are not to be tested in the same quick check
    subprogram.
 
6.  The format of the quick check package does not rigidly dictate how it
    must be executed on a particular machine.  For example, memory size of the
    machine might preclude loading all quick check modules at once.
 
 
 
 
*******************************************************************************
 
SECTION 11. SPECIFIC PROGRAMMING STANDARDS FOR SLATEC QUICK CHECKS
 
Just as the routines in the SLATEC Common Mathematical Library must meet
certain standards, so must the quick checks.  These standards are meant to
ensure that the quick checks adhere to the SLATEC quick check philosophy and
to enhance maintainability.  The list of these quick check standards follow.
 
 
1.  Each module must test only a few related library subprograms.
 
2.  Each module must be in the form of a subroutine with three arguments.
    For example:
 
                SUBROUTINE ADTST (LUN, KPRINT, IPASS)
 
    The first is an input argument giving the unit number to which any output
    should be written.  The second is an input argument specifying the amount
    of printing to be done by the quick check subroutine.  The third is an
    output flag indicating passage or failure of the subroutine.
 
    LUN         Unit number to which any output should be written.
 
    KPRINT = 0  No printing is done (pass/fail is presumably monitored at a
                higher level, i.e. in the driver).  Error messages will not be
                printed since the quick check driver sets the error handling
                control flag to 0, using CALL XSETF(0) when KPRINT = 0 or 1.
 
           = 1  No printing is done for tests which pass; a short message
                (e.g., one line) is printed for tests which fail.  Error
                messages will not be printed since the quick check driver sets
                the error handling control flag to 0, using CALL XSETF(0)
                when KPRINT = 0 or 1.
 
           = 2  A short message is printed for tests which pass; more detailed
                information is printed for tests which fail.  Error messages
                describing the reason for failure should be printed.
 
           = 3  (Possibly) quite detailed information is printed for all tests.
                Error messages describing the reason for failure should be
                printed.
 
    IPASS  = 0  Indicates failure of the quick check subroutine (i.e., at least
                one test failed).
 
           = 1  Indicates that all tests passed in the quick check subroutine.
 
    In the case of a subroutine whose purpose is to produce output (e.g., a
    printer-plotter), output of a more detailed nature might be produced for
    KPRINT >= 1.
 
    The quick check must execute correctly and completely using each value
    of KPRINT.  KPRINT is used only to control the printing and does not
    affect the tests made of the SLATEC routine.
 
3.  The quick check subprograms must be written in ANSI Fortran 77 and
    must make use of I1MACH, R1MACH, and D1MACH for pass/fail tolerances.
 
4.  Where possible, compute constants in a machine independent fashion.  For
    example, PI = 4. * ATAN(1.0)
 
5.  Using one library routine to test another is permitted, though this should
    be done with care.
 
6.  Known solutions can be stored using DATA or PARAMETER statements.  Some
    subprograms return a "solution" which is more than one number - for
    example, the eigenvalues of a matrix.  In these cases, take special care
    that the quick check test passes for ALL orderings of the output which are
    mathematically correct.
 
7.  Where subprograms are required by a routine being tested, they
    should accompany the quick check.  However, care should be taken so that
    no two such subprograms have the same name. Choosing esoteric or odd
    names is a good idea.  It is extremely desirable that each such
    subprogram contain comments indicating which quick check needed it
    (a C***SEE ALSO line should be used).
 
8.  Detailed output should be self-contained yet concise.  No external
    reference material or additional computations should be required to
    determine what, for example, the correct solution to the problem really is.
 
9.  For purposes of tracking down the cause of a failure, external reference
    material or the name of a (willing) qualified expert should be listed in
    the comment section of the quick check.
 
10. Quick checks must have SLATEC prologues and be adequately commented
    and cleanly written so that the average software librarian has some hope
    of tracking down problems.  For example, if a test problem is known to
    be tricky or if difficulties are expected for short word length
    machines, an appropriate comment would be helpful.
 
11. After deliberately calling a library routine with incorrect arguments,
    invoke the function IERR=NUMXER(NERR) to verify that the correct error
    number was set.  (NUMXER is a function in the SLATEC error handling
    package that returns the number of the most recent error via both the
    function value and the argument.)  Then CALL XERCLR to clear it before
    this (or the next) quick check makes another error.
 
12. A quick check should be written in such a way that it will execute
    identically if called several times in the same program.  In particular,
    there should be no modification of DATA loaded variables which cause the
    quick check to start with the wrong values on subsequent calls.
 
 
 
 
*******************************************************************************
 
SECTION 12. QUICK CHECK DRIVERS (MAIN PROGRAMS)
 
Many people writing quick checks are not aware of the environment in which the
individual quick check is called.  The following aspects of the quick check
drivers are illustrated by the example driver in Section 14.
 
1.  Each quick check driver will call one or more quick check subprograms.
 
2.  The input and output units for the tests are set in the driver.
 
            LIN = I1MACH(1)        the input unit
            LUN = I1MACH(2)        the output unit
 
    The output unit is communicated to the quick check subprograms
    through the argument list.  All output should be directed to the unit LUN
    that is in the argument list.
 
3.  Each quick check has three arguments LUN, KPRINT, and IPASS.  The
    meaning of these arguments within the quick checks is detailed
    thoroughly in the previous section.
 
    a.  The quick check driver reads in KPRINT without a prompt, and
        passes KPRINT as an argument to each quick check it calls.  KPRINT must
        not be changed by any driver or quick check.  The driver uses KPRINT to
        help determine what output to write.
 
    b.  The variable IPASS must be set to 0 (for fail) or to 1 (for pass) by
        each quick check before returning to the driver.  Within the driver,
        the variable NFAIL is set to 0.  If IPASS = 0 upon return to the
        driver, then NFAIL is incremented.  After calling all the quick checks,
        NFAIL will then have the number of quick checks which failed.
 
    c.  Quick check driver output should follow this chart:
 
                NFAIL        OUTPUT
                -----        ------
 
                not 0        driver writes fail message
                  0          driver writes pass message
 
4.  There are calls to three SLATEC error handler routines in each quick check
    driver:
 
 
            CALL XSETUN(LUN)       Selects unit LUN as the unit to which
                                      error messages will be sent.
            CALL XSETF(1)          Only fatal (not recoverable) error messages
              or XSETF(0)             will cause an abort.  XSETF sets the
                                      KONTROL variable for the error handler
                                      routines to the value of the XSETF
                                      argument.  A value of either 0 or 1 will
                                      make only fatal errors cause a program
                                      abort.  A value of 1 will allow printing
                                      of error messages, while a value of zero
                                      will print only fatal error messages.
            CALL XERMAX(1000)      Increase the number of times any
                                      single message may be printed.
 
 
 
 
*******************************************************************************
 
SECTION 13. QUICK CHECK SUBROUTINE EXAMPLE
 
The following program provides a very minimal check of the sample routine
from Section 9.
 
 
      SUBROUTINE ADTST (LUN, KPRINT, IPASS)
C***BEGIN PROLOGUE  ADTST
C***SUBSIDIARY
C***PURPOSE  Quick check for SLATEC routine ADDXY
C***LIBRARY   SLATEC
C***CATEGORY  A3A
C***TYPE      SINGLE PRECISION (ADTST-S, DADTST-D)
C***KEYWORDS  QUICK CHECK, ADDXY,
C***AUTHOR  Suyehiro, Tok, (LLNL)
C           Walton, Lee, (SNL)
C***ROUTINES CALLED  ADDXY, R1MACH
C***REVISION HISTORY  (YYMMDD)
C   880511  DATE WRITTEN
C   880608  Revised to meet new prologue standards.
C***END PROLOGUE  ADTST
C
C***FIRST EXECUTABLE STATEMENT  ADTST
      IF ( KPRINT .GE. 2 ) WRITE (LUN,99999)
99999 FORMAT ('OUTPUT FROM ADTST')
      IPASS = 1
C
C EXAMPLE PROBLEM
      X = 1.
      Y = 2.
      CALL ADDXY(X, Y, Z, IERR)
      EPS = R1MACH(4)
      IF( (ABS(Z-3.) .GT. EPS)  .OR.  (IERR .EQ. 1) ) IPASS = 0
      IF ( KPRINT .GE. 2 ) THEN
      WRITE (LUN,99995)X, Y, Z
99995 FORMAT (/' EXAMPLE PROBLEM ',/' X = ',E20.13,' Y = ',E20.13,' Z = ',
     *   E20.13)
      ENDIF
      IF ( (IPASS .EQ. 1 ) .AND. (KPRINT .GT. 1) ) WRITE (LUN,99994)
      IF ( (IPASS .EQ. 0 ) .AND. (KPRINT .NE. 0) ) WRITE (LUN,99993)
99994 FORMAT(/' ***************ADDXY  PASSED ALL TESTS***************')
99993 FORMAT(/' ***************ADDXY  FAILED SOME TESTS***************')
      RETURN
      END
 
 
 
 
*******************************************************************************
 
SECTION 14. QUICK CHECK MAIN PROGRAM EXAMPLE
 
The following is an example main program which should be used to drive a quick
check.  The names of the quick check subroutines it calls, ADTST and DADTST,
should be replaced with the name or names of real quick checks.  The dummy
names of the SLATEC routines being tested, ADDXY and DADDXY, should be
replaced with the names of the routines which are actually being tested.
 
 
      PROGRAM TEST00
C***BEGIN PROLOGUE  TEST00
C***SUBSIDIARY
C***PURPOSE  Driver for testing SLATEC subprograms
C            ADDXY    DADDXY
C***LIBRARY   SLATEC
C***CATEGORY  A3
C***TYPE      ALL (TEST00-A)
C***KEYWORDS  QUICK CHECK DRIVER, ADDXY, DADDXY
C***AUTHOR  Suyehiro, Tok, (LLNL)
C           Walton, Lee, (SNL)
C***DESCRIPTION
C
C *Usage:
C     One input data record is required
C         READ (LIN,990) KPRINT
C     990 FORMAT (I1)
C
C *Arguments:
C     KPRINT = 0  Quick checks - No printing.
C                 Driver       - Short pass or fail message printed.
C              1  Quick checks - No message printed for passed tests,
C                                short message printed for failed tests.
C                 Driver       - Short pass or fail message printed.
C              2  Quick checks - Print short message for passed tests,
C                                fuller information for failed tests.
C                 Driver       - Pass or fail message printed.
C              3  Quick checks - Print complete quick check results.
C                 Driver       - Pass or fail message printed.
C
C *Description:
C     Driver for testing SLATEC subprograms
C        ADDXY    DADDXY
C
C***REFERENCES  (NONE)
C***ROUTINES CALLED  ADTST, DADTST, I1MACH, XERMAX, XSETF, XSETUN
C***REVISION HISTORY  (YYMMDD)
C   880511  DATE WRITTEN
C   880608  Revised to meet the new SLATEC prologue standards.
C   881103  Brought DESCRIPTION section up to Appendix E standards.
C***END PROLOGUE  TEST00
C
C***FIRST EXECUTABLE STATEMENT  TEST00
      LUN   = I1MACH(2)
      LIN   = I1MACH(1)
      NFAIL = 0
C
C   Read KPRINT parameter
C
      READ (LIN,990) KPRINT
  990 FORMAT (I1)
      CALL XSETUN(LUN)
      IF ( KPRINT .LE. 1 ) THEN
         CALL XSETF(0)
      ELSE
         CALL XSETF(1)
      ENDIF
      CALL XERMAX(1000)
C
C   Test ADDXY
C
      CALL ADTST(LUN, KPRINT, IPASS)
      IF ( IPASS .EQ. 0 ) NFAIL = NFAIL + 1
C
C   Test DADDXY
C
      CALL DADTST(LUN, KPRINT, IPASS)
      IF ( IPASS .EQ. 0 ) NFAIL = NFAIL + 1
C
      IF ( NFAIL .GT. 0 ) WRITE (LUN,980) NFAIL
  980 FORMAT (/' ************* WARNING -- ', I5,
     * ' TEST(S) FAILED IN PROGRAM TEST00 *************' )
      IF ( NFAIL .EQ. 0 ) WRITE (LUN,970)
  970 FORMAT
     * (/' --------------TEST00  PASSED ALL TESTS----------------')
      END
 
 
 
 
*******************************************************************************
 
APPENDIX A.  GAMS (AND SLATEC) CLASSIFICATION SCHEME
 
SLATEC has adopted the GAMS (Guide to Available Mathematical Software)
Classification Scheme for Mathematical and Statistical Software,
reference [5].
 
 
                     GAMS (and SLATEC) Classification Scheme
                                     for
                     Mathematical and Statistical Software
 
 
                           Version 1.2 October 1983
 
 
 
 
A.  Arithmetic, error analysis
A1.  Integer
A2.  Rational
A3.  Real
A3A.  Single precision
A3B.  Double precision
A3C.  Extended precision
A3D.  Extended range
A4.  Complex
A4A.  Single precision
A4B.  Double precision
A4C.  Extended precision
A4D.  Extended range
A5.  Interval
A5A.  Real
A5B.  Complex
A6.  Change of representation
A6A.  Type conversion
A6B.  Base conversion
A6C.  Decomposition, construction
A7.  Sequences (e.g., convergence acceleration)
B.  Number theory
C.  Elementary and special functions (search also class L5)
C1.  Integer-valued functions (e.g., floor, ceiling, factorial, binomial
     coefficient)
C2.  Powers, roots, reciprocals
C3.  Polynomials
C3A.  Orthogonal
C3A1.  Trigonometric
C3A2.  Chebyshev, Legendre
C3A3.  Laguerre
C3A4.  Hermite
C3B.  Non-orthogonal
C4.  Elementary transcendental functions
C4A.  Trigonometric, inverse trigonometric
C4B.  Exponential, logarithmic
C4C.  Hyperbolic, inverse hyperbolic
C4D.  Integrals of elementary transcendental functions
C5.  Exponential and logarithmic integrals
C6.  Cosine and sine integrals
C7.  Gamma
C7A.  Gamma, log gamma, reciprocal gamma
C7B.  Beta, log beta
C7C.  Psi function
C7D.  Polygamma function
C7E.  Incomplete gamma
C7F.  Incomplete beta
C7G.  Riemann zeta
C8.  Error functions
C8A.  Error functions, their inverses, integrals, including the normal
      distribution function
C8B.  Fresnel integrals
C8C.  Dawson's integral
C9.  Legendre functions
C10.  Bessel functions
C10A.  J, Y, H-(1), H-(2)
C10A1.  Real argument, integer order
C10A2.  Complex argument, integer order
C10A3.  Real argument, real order
C10A4.  Complex argument, real order
C10A5.  Complex argument, complex order
C10B.  I, K
C10B1.  Real argument, integer order
C10B2.  Complex argument, integer order
C10B3.  Real argument, real order
C10B4.  Complex argument, real order
C10B5.  Complex argument, complex order
C10C.  Kelvin functions
C10D.  Airy and Scorer functions
C10E.  Struve, Anger, and Weber functions
C10F.  Integrals of Bessel functions
C11.  Confluent hypergeometric functions
C12.  Coulomb wave functions
C13.  Jacobian elliptic functions, theta functions
C14.  Elliptic integrals
C15.  Weierstrass elliptic functions
C16.  Parabolic cylinder functions
C17.  Mathieu functions
C18.  Spheroidal wave functions
C19.  Other special functions
D.  Linear Algebra
D1.  Elementary vector and matrix operations
D1A.  Elementary vector operations
D1A1.  Set to constant
D1A2.  Minimum and maximum components
D1A3.  Norm
D1A3A.  L-1 (sum of magnitudes)
D1A3B.  L-2 (Euclidean norm)
D1A3C.  L-infinity (maximum magnitude)
D1A4.  Dot product (inner product)
D1A5.  Copy or exchange (swap)
D1A6.  Multiplication by scalar
D1A7.  Triad (a*x+y for vectors x,y and scalar a)
D1A8.  Elementary rotation (Givens transformation)
D1A9.  Elementary reflection (Householder transformation)
D1A10.  Convolutions
D1B.  Elementary matrix operations
D1B1.  Set to zero, to identity
D1B2.  Norm
D1B3.  Transpose
D1B4.  Multiplication by vector
D1B5.  Addition, subtraction
D1B6.  Multiplication
D1B7.  Matrix polynomial
D1B8.  Copy
D1B9.  Storage mode conversion
D1B10.  Elementary rotation (Givens transformation)
D1B11.  Elementary reflection (Householder transformation)
D2.  Solution of systems of linear equations (including inversion, LU and
     related decompositions)
D2A.  Real nonsymmetric matrices
D2A1.  General
D2A2.  Banded
D2A2A.  Tridiagonal
D2A3.  Triangular
D2A4.  Sparse
D2B.  Real symmetric matrices
D2B1.  General
D2B1A.  Indefinite
D2B1B.  Positive definite
D2B2.  Positive definite banded
D2B2A.  Tridiagonal
D2B4.  Sparse
D2C.  Complex non-Hermitian matrices
D2C1.  General
D2C2.  Banded
D2C2A.  Tridiagonal
D2C3.  Triangular
D2C4.  Sparse
D2D.  Complex Hermitian matrices
D2D1.  General
D2D1A.  Indefinite
D2D1B.  Positive definite
D2D2.  Positive definite banded
D2D2A.  Tridiagonal
D2D4.  Sparse
D2E.  Associated operations (e.g., matrix reorderings)
D3.  Determinants
D3A.  Real nonsymmetric matrices
D3A1.  General
D3A2.  Banded
D3A2A.  Tridiagonal
D3A3.  Triangular
D3A4.  Sparse
D3B.  Real symmetric matrices
D3B1.  General
D3B1A.  Indefinite
D3B1B.  Positive definite
D3B2.  Positive definite banded
D3B2A.  Tridiagonal
D3B4.  Sparse
D3C.  Complex non-Hermitian matrices
D3C1.  General
D3C2.  Banded
D3C2A.  Tridiagonal
D3C3.  Triangular
D3C4.  Sparse
D3D.  Complex Hermitian matrices
D3D1.  General
D3D1A.  Indefinite
D3D1B.  Positive definite
D3D2.  Positive definite banded
D3D2A.  Tridiagonal
D3D4.  Sparse
D4.  Eigenvalues, eigenvectors
D4A.  Ordinary eigenvalue problems (Ax = (lambda) * x)
D4A1.  Real symmetric
D4A2.  Real nonsymmetric
D4A3.  Complex Hermitian
D4A4.  Complex non-Hermitian
D4A5.  Tridiagonal
D4A6.  Banded
D4A7.  Sparse
D4B.  Generalized eigenvalue problems (e.g., Ax = (lambda)*Bx)
D4B1.  Real symmetric
D4B2.  Real general
D4B3.  Complex Hermitian
D4B4.  Complex general
D4B5.  Banded
D4C.  Associated operations
D4C1.  Transform problem
D4C1A.  Balance matrix
D4C1B.  Reduce to compact form
D4C1B1.  Tridiagonal
D4C1B2.  Hessenberg
D4C1B3.  Other
D4C1C.  Standardize problem
D4C2.  Compute eigenvalues of matrix in compact form
D4C2A.  Tridiagonal
D4C2B.  Hessenberg
D4C2C.  Other
D4C3.  Form eigenvectors from eigenvalues
D4C4.  Back transform eigenvectors
D4C5.  Determine Jordan normal form
D5.  QR decomposition, Gram-Schmidt orthogonalization
D6.  Singular value decomposition
D7.  Update matrix decompositions
D7A.  LU
D7B.  Cholesky
D7C.  QR
D7D.  Singular value
D8.  Other matrix equations (e.g., AX+XB=C)
D9.  Overdetermined or underdetermined systems of equations, singular systems,
     pseudo-inverses (search also classes D5, D6, K1a, L8a)
E.  Interpolation
E1.  Univariate data (curve fitting)
E1A.  Polynomial splines (piecewise polynomials)
E1B.  Polynomials
E1C.  Other functions (e.g., rational, trigonometric)
E2.  Multivariate data (surface fitting)
E2A.  Gridded
E2B.  Scattered
E3.  Service routines (e.g., grid generation, evaluation of fitted functions)
     (search also class N5)
F.  Solution of nonlinear equations
F1.  Single equation
F1A.  Smooth
F1A1.  Polynomial
F1A1A.  Real coefficients
F1A1B.  Complex coefficients
F1A2.  Nonpolynomial
F1B.  General (no smoothness assumed)
F2.  System of equations
F2A.  Smooth
F2B.  General (no smoothness assumed)
F3.  Service routines (e.g., check user-supplied derivatives)
G.  Optimization (search also classes K, L8)
G1.  Unconstrained
G1A.  Univariate
G1A1.  Smooth function
G1A1A.  User provides no derivatives
G1A1B.  User provides first derivatives
G1A1C.  User provides first and second derivatives
G1A2.  General function (no smoothness assumed)
G1B.  Multivariate
G1B1.  Smooth function
G1B1A.  User provides no derivatives
G1B1B.  User provides first derivatives
G1B1C.  User provides first and second derivatives
G1B2.  General function (no smoothness assumed)
G2.  Constrained
G2A.  Linear programming
G2A1.  Dense matrix of constraints
G2A2.  Sparse matrix of constraints
G2B.  Transportation and assignments problem
G2C.  Integer programming
G2C1.  Zero/one
G2C2.  Covering and packing problems
G2C3.  Knapsack problems
G2C4.  Matching problems
G2C5.  Routing, scheduling, location problems
G2C6.  Pure integer programming
G2C7.  Mixed integer programming
G2D.  Network (for network reliability search class M)
G2D1.  Shortest path
G2D2.  Minimum spanning tree
G2D3.  Maximum flow
G2D3A.  Generalized networks
G2D3B.  Networks with side constraints
G2D4.  Test problem generation
G2E.  Quadratic programming
G2E1.  Positive definite Hessian (i.e. convex problem)
G2E2.  Indefinite Hessian
G2F.  Geometric programming
G2G.  Dynamic programming
G2H.  General nonlinear programming
G2H1.  Simple bounds
G2H1A.  Smooth function
G2H1A1.  User provides no derivatives
G2H1A2.  User provides first derivatives
G2H1A3.  User provides first and second derivatives
G2H1B.  General function (no smoothness assumed)
G2H2.  Linear equality or inequality constraints
G2H2A.  Smooth function
G2H2A1.  User provides no derivatives
G2H2A2.  User provides first derivatives
G2H2A3.  User provides first and second derivatives
G2H2B.  General function (no smoothness assumed)
G2H3.  Nonlinear constraints
G2H3A.  Equality constraints only
G2H3A1.  Smooth function and constraints
G2H3A1A.  User provides no derivatives
G2H3A1B.  User provides first derivatives of function and constraints
G2H3A1C.  User provides first and second derivatives of function and
          constraints
G2H3A2.  General function and constraints (no smoothness assumed)
G2H3B.  Equality and inequality constraints
G2H3B1.  Smooth function and constraints
G2H3B1A.  User provides no derivatives
G2H3B1B.  User provides first derivatives of function and constraints
G2H3B1C.  User provides first and second derivatives of function and
          constraints
G2H3B2.  General function and constraints (no smoothness assumed)
G2I.  Global solution to nonconvex problems
G3.  Optimal control
G4.  Service routines
G4A.  Problem input (e.g., matrix generation)
G4B.  Problem scaling
G4C.  Check user-supplied derivatives
G4D.  Find feasible point
G4E.  Check for redundancy
G4F.  Other
H.  Differentiation, integration
H1.  Numerical differentiation
H2.  Quadrature (numerical evaluation of definite integrals)
H2A.  One-dimensional integrals
H2A1.  Finite interval (general integrand)
H2A1A.  Integrand available via user-defined procedure
H2A1A1.  Automatic (user need only specify required accuracy)
H2A1A2.  Nonautomatic
H2A1B.  Integrand available only on grid
H2A1B1.  Automatic (user need only specify required accuracy)
H2A1B2.  Nonautomatic
H2A2.  Finite interval (specific or special type integrand including weight
       functions, oscillating and singular integrands, principal value
       integrals, splines, etc.)
H2A2A.  Integrand available via user-defined procedure
H2A2A1.  Automatic (user need only specify required accuracy)
H2A2A2.  Nonautomatic
H2A2B.  Integrand available only on grid
H2A2B1.  Automatic (user need only specify required accuracy)
H2A2B2.  Nonautomatic
H2A3.  Semi-infinite interval (including e**(-x) weight function)
H2A3A.  Integrand available via user-defined procedure
H2A3A1.  Automatic (user need only specify required accuracy)
H2A3A2.  Nonautomatic
H2A4.  Infinite interval (including e**(-x**2)) weight function)
H2A4A.  Integrand available via user-defined procedure
H2A4A1.  Automatic (user need only specify required accuracy)
H2A4A2.  Nonautomatic
H2B.  Multidimensional integrals
H2B1.  One or more hyper-rectangular regions
H2B1A.  Integrand available via user-defined procedure
H2B1A1.  Automatic (user need only specify required accuracy)
H2B1A2.  Nonautomatic
H2B1B.  Integrand available only on grid
H2B1B1.  Automatic (user need only specify required accuracy)
H2B1B2.  Nonautomatic
H2B2.  Nonrectangular region, general region
H2B2A.  Integrand available via user-defined procedure
H2B2A1.  Automatic (user need only specify required accuracy)
H2B2A2.  Nonautomatic
H2B2B.  Integrand available only on grid
H2B2B1.  Automatic (user need only specify required accuracy)
H2B2B2.  Nonautomatic
H2C.  Service routines (compute weight and nodes for quadrature formulas)
I.  Differential and integral equations
I1.  Ordinary differential equations
I1A.  Initial value problems
I1A1.  General, nonstiff or mildly stiff
I1A1A.  One-step methods (e.g., Runge-Kutta)
I1A1B.  Multistep methods (e.g., Adams' predictor-corrector)
I1A1C.  Extrapolation methods (e.g., Bulirsch-Stoer)
I1A2.  Stiff and mixed algebraic-differential equations
I1B.  Multipoint boundary value problems
I1B1.  Linear
I1B2.  Nonlinear
I1B3.  Eigenvalue (e.g., Sturm-Liouville)
I1C.  Service routines (e.g., interpolation of solutions, error handling)
I2.  Partial differential equations
I2A.  Initial boundary value problems
I2A1.  Parabolic
I2A1A.  One spatial dimension
I2A1B.  Two or more spatial dimensions
I2A2.  Hyperbolic
I2B.  Elliptic boundary value problems
I2B1.  Linear
I2B1A.  Second order
I2B1A1.  Poisson (Laplace) or Helmholz equation
I2B1A1A.  Rectangular domain (or topologically rectangular in the coordinate
          system)
I2B1A1B.  Nonrectangular domain
I2B1A2.  Other separable problems
I2B1A3.  Nonseparable problems
I2B1C.  Higher order equations (e.g., biharmonic)
I2B2.  Nonlinear
I2B3.  Eigenvalue
I2B4.  Service routines
I2B4A.  Domain triangulation (search also class P2a2c1)
I2B4B.  Solution of discretized elliptic equations
I3.  Integral equations
J.  Integral transforms
J1.  Fast Fourier transforms (search class L10 for time series analysis)
J1A.  One-dimensional
J1A1.  Real
J1A2.  Complex
J1A3.  Trigonometric (sine, cosine)
J1B.  Multidimensional
J2.  Convolutions
J3.  Laplace transforms
J4.  Hilbert transforms
K.  Approximation (search also class L8)
K1.  Least squares (L-2) approximation
K1A.  Linear least squares (search also classes D5, D6, D9)
K1A1.  Unconstrained
K1A1A.  Univariate data (curve fitting)
K1A1A1.  Polynomial splines (piecewise polynomials)
K1A1A2.  Polynomials
K1A1A3.  Other functions (e.g., rational, trigonometric, user-specified)
K1A1B.  Multivariate data (surface fitting)
K1A2.  Constrained
K1A2A.  Linear constraints
K1A2B.  Nonlinear constraints
K1B.  Nonlinear least squares
K1B1.  Unconstrained
K1B1A.  Smooth functions
K1B1A1.  User provides no derivatives
K1B1A2.  User provides first derivatives
K1B1A3.  User provides first and second derivatives
K1B1B.  General functions
K1B2.  Constrained
K1B2A.  Linear constraints
K1B2B.  Nonlinear constraints
K2.  Minimax (L-infinity) approximation
K3.  Least absolute value (L-1) approximation
K4.  Other analytic approximations (e.g., Taylor polynomial, Pade)
K5.  Smoothing
K6.  Service routines (e.g., mesh generation, evaluation of fitted functions)
     (search also class N5)
L.  Statistics, probability
L1.  Data summarization
L1A.  One univariate quantitative sample
L1A1.  Ungrouped data
L1A1A.  Location
L1A1B.  Dispersion
L1A1C.  Shape
L1A1D.  Distribution, density
L1A2.  Ungrouped data with missing values
L1A3.  Grouped data
L1A3A.  Location
L1A3B.  Dispersion
L1A3C.  Shape
L1C.  One univariate qualitative (proportional) sample
L1E.  Two or more univariate samples or one multivariate sample
L1E1.  Ungrouped data
L1E1A.  Location
L1E1B.  Correlation
L1E2.  Ungrouped data with missing values
L1E3.  Grouped data
L1F.  Two or more multivariate samples
L2.  Data manipulation (search also class N)
L2A.  Transform (search also class N6 for sorting, ranking)
L2B.  Group
L2C.  Sample
L2D.  Subset
L3.  Graphics (search also class Q)
L3A.  Histograms
L3B.  Distribution functions
L3C.  Scatter diagrams
L3C1.  Y vs. X
L3C2.  Symbol plots
L3C3.  Multiple plots
L3C4.  Probability plots
L3C4B.  Beta, binomial
L3C4C.  Cauchy, chi-squared
L3C4D.  Double exponential
L3C4E.  Exponential, extreme value
L3C4F.  F distribution
L3C4G.  Gamma, geometric
L3C4H.  Halfnormal
L3C4L.  Lambda, logistic, lognormal
L3C4N.  Negative binomial, normal
L3C4P.  Pareto, Poisson
L3C4T.  t distribution
L3C4U.  Uniform
L3C4W.  Weibull
L3C5.  Time series plots (X(i) vs. i, vertical, lag)
L3D.  EDA graphics
L4.  Elementary statistical inference, hypothesis testing
L4A.  One univariate quantitative sample
L4A1.  Ungrouped data
L4A1A.  Parameter estimation
L4A1A2.  Binomial
L4A1A5.  Extreme value
L4A1A14.  Normal
L4A1A16.  Poisson
L4A1A21.  Uniform
L4A1A23.  Weibull
L4A1B.  Distribution-free (nonparametric) analysis
L4A1C.  Goodness-of-fit tests
L4A1D.  Tests on sequences of numbers
L4A1E.  Density and distribution function estimation
L4A1F.  Tolerance limits
L4A2.  Ungrouped data with missing values
L4A3.  Grouped data
L4A3A.  Parameter estimation
L4A3A14.  Normal
L4B.  Two or more univariate quantitative samples
L4B1.  Ungrouped data
L4B1A.  Parameter estimation
L4B1A14.  Normal
L4B1B.  Distribution-free (nonparametric) analysis
L4B2.  Ungrouped data with missing values
L4B3.  Grouped data
L4C.  One univariate qualitative (proportional) sample
L4D.  Two or more univariate samples
L4E.  One multivariate sample
L4E1.  Ungrouped data
L4E1A.  Parameter estimation
L4E1A14.  Normal
L4E1B.  Distribution-free (nonparametric) analysis
L4E2.  Ungrouped data with missing values
L4E2A.  Parameter estimation
L4E2B.  Distribution-free (nonparametric) analysis
L4E3.  Grouped data
L4E3A.  Parameter estimation
L4E3A14.  Normal
L4E3B.  Distribution-free (nonparametric) analysis
L4E4.  Two or more multivariate samples
L4E4A.  Parameter estimation
L4E4A14.  Normal
L5.  Function evaluation (search also class C)
L5A.  Univariate
L5A1.  Cumulative distribution functions, probability density functions
L5A1B.  Beta, binomial
L5A1C.  Cauchy, chi-squared
L5A1D.  Double exponential
L5A1E.  Error function, exponential, extreme value
L5A1F.  F distribution
L5A1G.  Gamma, general, geometric
L5A1H.  Halfnormal, hypergeometric
L5A1K.  Kolmogorov-Smirnov
L5A1L.  Lambda, logistic, lognormal
L5A1N.  Negative binomial, normal
L5A1P.  Pareto, Poisson
L5A1T.  t distribution
L5A1U.  Uniform
L5A1W.  Weibull
L5A2.  Inverse cumulative distribution functions, sparsity functions
L5A2B.  Beta, binomial
L5A2C.  Cauchy, chi-squared
L5A2D.  Double exponential
L5A2E.  Exponential, extreme value
L5A2F.  F distribution
L5A2G.  Gamma, general, geometric
L5A2H.  Halfnormal
L5A2L.  Lambda, logistic, lognormal
L5A2N.  Negative binomial, normal, normal scores
L5A2P.  Pareto, Poisson
L5A2T.  t distribution
L5A2U.  Uniform
L5A2W.  Weibull
L5B.  Multivariate
L5B1.  Cumulative distribution functions, probability density functions
L5B1N.  Normal
L6.  Pseudo-random number generation
L6A.  Univariate
L6A2.  Beta, binomial, Boolean
L6A3.  Cauchy, chi-squared
L6A4.  Double exponential
L6A5.  Exponential, extreme value
L6A6.  F distribution
L6A7.  Gamma, general (continuous, discrete) distributions, geometric
L6A8.  Halfnormal, hypergeometric
L6A9.  Integers
L6A12.  Lambda, logical, logistic, lognormal
L6A14.  Negative binomial, normal
L6A15.  Order statistics
L6A16.  Pareto, permutations, Poisson
L6A19.  Samples, stable distribution
L6A20.  t distribution, time series, triangular
L6A21.  Uniform
L6A22.  Von Mises
L6A23.  Weibull
L6B.  Multivariate
L6B3.  Contingency table, correlation matrix
L6B13.  Multinomial
L6B14.  Normal
L6B15.  Orthogonal matrix
L6B21.  Uniform
L6C.  Service routines (e.g., seed)
L7.  Experimental design, including analysis of variance
L7A.  Univariate
L7A1.  One-way analysis of variance
L7A1A.  Parametric analysis
L7A1A1.  Contrasts, multiple comparisons
L7A1A2.  Analysis of variance components
L7A1B.  Distribution-free (nonparametric) analysis
L7A2.  Balanced multiway design
L7A2A.  Complete
L7A2A1.  Parametric analysis
L7A2A1A.  Two-way
L7A2A1B.  Factorial
L7A2A1C.  Nested
L7A2A2.  Distribution-free (nonparametric) analysis
L7A2B.  Incomplete
L7A2B1.  Parametric analysis
L7A2B1A.  Latin square
L7A2B1B.  Lattice designs
L7A2B2.  Distribution-free (nonparametric) analysis
L7A3.  Analysis of covariance
L7A4.  General linear model (unbalanced design)
L7A4A.  Parametric analysis
L7A4B.  Distribution-free (nonparametric) analysis
L7B.  Multivariate
L8.  Regression (search also classes G, K)
L8A.  Linear least squares (L-2) (search also classes D5, D6, D9)
L8A1.  Simple
L8A1A.  Ordinary
L8A1A1.  Unweighted
L8A1A1A.  No missing values
L8A1A1B.  Missing values
L8A1A2.  Weighted
L8A1B.  Through the origin
L8A1C.  Errors in variables
L8A1D.  Calibration (inverse regression)
L8A2.  Polynomial
L8A2A.  Not using orthogonal polynomials
L8A2A1.  Unweighted
L8A2A2.  Weighted
L8A2B.  Using orthogonal polynomials
L8A2B1.  Unweighted
L8A2B2.  Weighted
L8A3.  Piecewise polynomial (i.e. multiphase or spline)
L8A4.  Multiple
L8A4A.  Ordinary
L8A4A1.  Unweighted
L8A4A1A.  No missing values
L8A4A1B.  Missing values
L8A4A1C.  From correlation data
L8A4A1D.  Using principal components
L8A4A1E.  Using preference pairs
L8A4A2.  Weighted
L8A4B.  Errors in variables
L8A4D.  Logistic
L8A5.  Variable selection
L8A6.  Regression design
L8A7.  Several multiple regressions
L8A8.  Multivariate
L8A9.  Diagnostics
L8A10.  Hypothesis testing, inference
L8A10A.  Lack-of-fit tests
L8A10B.  Analysis of residuals
L8A10C.  Inference
L8B.  Biased (ridge)
L8C.  Linear least absolute value (L-1)
L8D.  Linear minimax (L-infinity)
L8E.  Robust
L8F.  EDA
L8G.  Nonlinear
L8G1.  Unweighted
L8G1A.  Derivatives not supplied
L8G1B.  Derivatives supplied
L8G2.  Weighted
L8G2A.  Derivatives not supplied
L8G2B.  Derivatives supplied
L8H.  Service routines
L9.  Categorical data analysis
L9A.  2-by-2 tables
L9B.  Two-way tables
L9C.  Log-linear model
L9D.  EDA (e.g., median polish)
L10.  Time series analysis (search also class L3c5 for time series graphics)
L10A.  Transformations, transforms (search also class J1)
L10B.  Smoothing, filtering
L10C.  Autocorrelation analysis
L10D.  Complex demodulation
L10E.  ARMA and ARIMA modeling and forecasting
L10E1.  Model and parameter estimation
L10E2.  Forecasting
L10F.  Spectral analysis
L10G.  Cross-correlation analysis
L10G1.  Parameter estimation
L10G2.  Forecasting
L11.  Correlation analysis
L12.  Discriminant analysis
L13.  Factor analysis
L13A.  Principal components analysis
L14.  Cluster analysis
L14A.  Unconstrained
L14A1.  Nested
L14A1A.  Joining (e.g., single link)
L14A1B.  Divisive
L14A2.  Non-nested
L14B.  Constrained
L14B1.  One-dimensional
L14B2.  Two-dimensional
L14C.  Display
L15.  Life testing, survival analysis
M.  Simulation, stochastic modeling (search also classes L6, L10)
M1.  Simulation
M1A.  Discrete
M1B.  Continuous (Markov models)
M2.  Queueing
M3.  Reliability
M3A.  Quality control
M3B.  Electrical network
M4.  Project optimization (e.g., PERT)
N.  Data handling (search also class L2)
N1.  Input, output
N2.  Bit manipulation
N3.  Character manipulation
N4.  Storage management (e.g., stacks, heaps, trees)
N5.  Searching
N5A.  Extreme value
N5B.  Insertion position
N5C.  On a key
N6.  Sorting
N6A.  Internal
N6A1.  Passive (i.e. construct pointer array, rank)
N6A1A.  Integer
N6A1B.  Real
N6A1B1.  Single precision
N6A1B2.  Double precision
N6A1C.  Character
N6A2.  Active
N6A2A.  Integer
N6A2B.  Real
N6A2B1.  Single precision
N6A2B2.  Double precision
N6A2C.  Character
N6B.  External
N7.  Merging
N8.  Permuting
O.  Symbolic computation
P.  Computational geometry (search also classes G, Q)
P1.  One dimension
P2.  Two dimensions
P2A.  Points, lines
P2A1.  Relationships
P2A1A.  Closest and farthest points
P2A1B.  Intersection
P2A2.  Graph construction
P2A2A.  Convex hull
P2A2B.  Minimum spanning tree
P2A2C.  Region partitioning
P2A2C1.  Triangulation
P2A2C2.  Voronoi diagram
P2B.  Polygons (e.g., intersection, hidden line problems)
P2C.  Circles
P3.  Three dimensions
P3A.  Points, lines, planes
P3B.  Polytopes
P3C.  Spheres
P4.  More than three dimensions
Q.  Graphics (search also classes L3, P)
Q1.  Line printer plotting
R.  Service routines
R1.  Machine-dependent constants
R2.  Error checking (e.g., check monotonicity)
R3.  Error handling
R3A.  Set criteria for fatal errors
R3B.  Set unit number for error messages
R3C.  Other utility programs
R4.  Documentation retrieval
S.  Software development tools
S1.  Program transformation
S2.  Static analysis
S3.  Dynamic analysis
Z.  Other
 
 
 
 
*******************************************************************************
 
APPENDIX B.  MACHINE CONSTANTS
 
The SLATEC Common Math Library uses three functions for keeping machine
constants.  In order to keep the source code for the Library as portable as
possible, no other Library routines should attempt to DATA load machine
dependent constants.  Due to the subtlety of trying to calculate machine
constants at run time in a manner that yields correct constants for all
possible computers, no Library routines should attempt to calculate them.
Routines I1MACH, R1MACH, and D1MACH in the SLATEC Common Math Library are
derived from the routines of these names in the Bell Laboratories' PORT Library
and should be called whenever machines constants are needed.  These functions
are DATA loaded with carefully determined constants of type integer, single
precision, and double precision, respectively, for a wide range of computers.
Each is called with one input argument to indicate which constant is desired.
The appropriate Fortran statements are:
 
For integer constants:
 
      INTEGER I1MACH, I
      I = I1MACH(N)                 where 1 .LE. N .LE. 16
 
For single precision constants:
 
      REAL R1MACH, R
      R = R1MACH(N)                 where 1 .LE. N .LE. 5
 
For double precision constants:
 
      DOUBLE PRECISION D1MACH, D
      D = D1MACH(N)                 where 1 .LE. N .LE. 5
 
The different constants that can be retrieved will be explained below after we
give a summary of the floating point arithmetic model which they characterize.
 
The PORT and SLATEC machine constant routines acknowledge that a computer
can have some minor flaws in how it performs arithmetic and that the purpose of
machine constant routines is to keep other library routines out of trouble.
For example, a computer may have a 48-bit coefficient, but due to round-off or
other deficiencies may be able to perform only 47-bit (or even 46-bit)
arithmetic reliably.  A machine can also misbehave at the extreme ends of its
exponent range.  The machine constants are chosen to describe a subset of the
floating point numbers of a computer on which operations such as addition,
subtraction, multiplication, reciprocation, and comparison work as your
intuition would expect.  If the actual performance of the machine is such that
results fall into the "expected" intervals of the subset floating point system,
then the usual forms of error analysis will apply.  For details, see [7].
 
The machine constants normally cannot be determined by reading a computer's
hardware reference manual.  Such manuals tell the range and representation of
floating point numbers but usually do not describe the errors in the floating
point addition, subtraction, multiplication, reciprocation, or division units.
The constants for I1MACH, R1MACH, and D1MACH are found by doing extensive
testing using operands on which the hardware is most likely to fail.  Failure
is most likely to occur at the extreme ends of the exponent range and near
powers of the number base.  If such failures are relatively minor, we can
choose machine constants for I1MACH, R1MACH, and D1MACH to restrict the domain
of floating point numbers to a subset on which arithmetic operations work.
 
The subset model of floating point arithmetic is characterized by four
parameters:
 
     B     the number base or radix.  This is usually 2 or 16.
 
     T     the number of digits in base B of the coefficient of the floating
           point number.
 
     EMIN  the smallest (most negative) exponent (power of B)
 
     EMAX  the largest exponent (power of B)
 
A floating point number is modeled as FRACTION*(B**EXP) where EXP falls between
EMIN and EMAX and the FRACTION is of the form
 
     + or - ( f(1)*B**(-1) + ... + f(T)*B**(-T) )
 
     with f(1) in the range 1 to B-1 inclusive and
          f(2) through f(T) in the range 0 to B-1 inclusive.
 
In this model the fraction has the radix point at the left end.  Some computers
have their radix point at the right end so that when their representation is
mapped onto this model, they appear to have an unbalanced exponent range (i.e.,
EMIN is not close to the negative of EMAX).  If the computer cannot correctly
calculate results near underflow, EMIN is increased to a more conservative
value.  Likewise, if the computer cannot correctly calculate results near
overflow, EMAX is decreased.  If a base 2 machine with a 48-bit fraction is
unable to calculate 48-bit results due to hardware round-off, T may be set to
47 (or even 46) to account for the loss of accuracy.
 
The complete set of machine constants (including those not related to floating
point arithmetic) are:
 
I/O Unit Numbers
----------------
 
I1MACH( 1) = the FORTRAN unit number for the standard input device.
 
I1MACH( 2) = the FORTRAN unit number for the standard output device.
 
I1MACH( 3) = the FORTRAN unit number for the standard punch device.
 
I1MACH( 4) = the FORTRAN unit number for the standard error message device.
 
Word Properties
---------------
 
I1MACH( 5) = the number of bits per integer storage unit.
 
I1MACH( 6) = the number of characters per integer storage unit.
 
Integer Arithmetic
------------------
 
I1MACH( 7) = the base or radix for integer arithmetic.
 
I1MACH( 8) = the number of digits in radix I1MACH(7) used in integer
             arithmetic.
 
I1MACH( 9) = the largest magnitude integer for which the machine and compiler
             perform the complete set of arithmetic operations.
 
Floating Point Arithmetic
-------------------------
 
I1MACH(10) = the base or radix for floating point arithmetic.  This is the B
             of the floating point model.
 
Single Precision Arithmetic
---------------------------
 
I1MACH(11) = the number of digits in radix I1MACH(10) used in single precision
             arithmetic.  This is the T in the floating point model.
 
I1MACH(12) = the most negative usable exponent short of underflow of radix
             I1MACH(10) for a single precision number.  This is the EMIN in the
             floating point model.
 
I1MACH(13) = the largest usable exponent short of overflow of radix I1MACH(10)
             for a single precision number.  This is the EMAX in the floating
             point model.
 
Double Precision Arithmetic
---------------------------
 
I1MACH(14) = the number of digits in radix I1MACH(10) used in double precision
             arithmetic.  This is the T of the floating point model.
 
I1MACH(15) = the most negative usable exponent short of underflow of radix
             I1MACH(10) for a double precision number.  This is the EMIN of
             the floating point model.
 
I1MACH(16) = the largest usable exponent short of overflow of radix I1MACH(10)
             for a double precision number.  This is the EMAX of the floating
             point model.
 
Special Single Precision Values
-------------------------------
 
R1MACH( 1) = B**(EMIN-1).  This is the smallest, positive, single precision
             number in the range for safe, accurate arithmetic.
 
R1MACH( 2) = B**EMAX*(1-B**(-T)).  This is the largest, positive, single
             precision number in the range for safe, accurate arithmetic.
 
R1MACH( 3) = B**(-T).  This is the smallest relative spacing between two
             adjacent single precision numbers in the floating point model.
             This constant is not machine epsilon; see below for machine
             epsilon.
 
R1MACH( 4) = B**(1-T).  This is the largest relative spacing between two
             adjacent single precision numbers in the floating point model.
             Any two single precision numbers that have a greater relative
             spacing than R1MACH(4) can be compared correctly (with operators
             like .EQ. or .LT.). This constant is an upper bound on theoretical
             machine epsilon.
 
R1MACH( 5) = logarithm to base ten of the machine's floating point number base.
 
Special Double Precision Values
-------------------------------
 
D1MACH( 1) = B**(EMIN-1).  This is the smallest, positive, double precision
             numbers in the range for safe, accurate arithmetic.
 
D1MACH( 2) = B**EMAX*(1-B**(-T)).  This is the largest, positive, double
             precision number in the range for safe, accurate arithmetic.
 
D1MACH( 3) = B**(-T).  This is the smallest relative spacing between two
             adjacent double precision numbers in the floating point model.
             This constant is not machine epsilon; see below for machine
             epsilon.
 
D1MACH( 4) = B**(1-T).  This is the largest relative spacing between two
             adjacent double precision numbers in the floating point model.
             Any two double precision numbers that have a greater relative
             spacing than D1MACH(4) can be compared correctly (with operators
             like .EQ. or .LT.). This constant is an upper bound on theoretical
             machine epsilon.
 
D1MACH( 5) = logarithm to base ten of the machine's floating point number base.
 
In theory, all of the R1MACH and D1MACH values can be calculated from I1MACH
values; however, they are provided (1) to save having to calculate them and (2)
to avoid rousing any bugs in the exponentiation (** operator ) or logarithm
routines.
 
Machine epsilon (the smallest number that can be added to 1.0 or 1.0D0
that yields a result different from 1.0 or 1.0D0) is not one of the special
values that comes from this model.  If the purpose of machine epsilon is to
decide when iterations have converged, the proper constants to use are
R1MACH(4) or D1MACH(4).  These may be slightly larger than machine epsilon;
however, trying to iterate to smaller relative differences may not be possible
due to hardware round-off error.
 
The Fortran standard requires that the amount of storage assigned to an INTEGER
and a REAL be the same.  Thus, the number of bits that can be used to represent
an INTEGER will almost always be larger than the number of bits in the mantissa
of a REAL.  In converting from an INTEGER to a REAL, some machines will
correctly round or truncate, but some will not.  Authors are therefore advised
to check the magnitude of INTEGERs and not attempt to convert INTEGERs to REALs
that can not be represented exactly as REALs.  Similar problems can occur when
converting INTEGERs to DOUBLEs.
 
 
 
 
*******************************************************************************
 
APPENDIX C.  ERROR HANDLING
 
Authors of Library routines must use at least the first and preferably both of
the following techniques to handle errors that their routines detect.
 
1.  One argument, preferably the last, in the calling sequence must be an
    error flag if the routine can detect errors.  This is an integer variable
    to which a value is assigned before returning to the caller.  A value of
    zero means the routine completed successfully. A positive value (preferably
    in the range 1 to 999) should be used to indicate potential, partial, or
    total failure.  Separate values should be used for distinct conditions so
    that the caller can determine the nature of the failure.  Of course, the
    possible values of this error flag and their meanings must be documented in
    the description section of the prologue of the routine.
 
2.  In addition to returning an error flag, the routine can supply more
    information by writing an error message via a call to XERMSG.  XERMSG
    has an error number as one of its arguments, and the same value that will
    be returned in the error flag argument must be used in calling XERMSG.
 
XERMSG is part of the SLATEC Common Math Library error handling package
which consists of a number of routines.  It is not necessary for authors to
learn about the entire package.  Instead we summarize here a few aspects of the
package that an author must know in order to use XERMSG correctly.
 
1.  Although XERMSG supports three levels of severity (warning, recoverable
    error, and fatal error), be sparing in the use of fatal errors.  XERMSG
    will terminate the program for fatal errors but may return for recoverable
    errors, and will definitely return after warning messages.  An error should
    be designated fatal only if returning to the caller is likely to be
    disastrous (e.g. result in an infinite loop).
 
2.  The error handling package remembers the value of the error number and has
    an entry point whereby the user can retrieve the most recent error number.
    Successive calls to XERMSG replace this retained value.  In the case of
    warning messages, it is permissible to issue multiple warnings.  In the
    case of a recoverable error, no additional calls to XERMSG must be made by
    the Library routine before returning to the caller since the caller must be
    given a chance to retrieve and clear the error number (and error condition)
    from the error handling package.  In particular, if the user calls Library
    routine X and X calls a lower level Library Y, it is permissible for Y
    to call XERMSG, but after it returns to X, X must be careful to note any
    recoverable errors detected in Y and not make any additional calls to
    XERMSG in that case.  In practice, it would be simpler if subsidiary
    routines did not call XERMSG but only returned error flags indicating a
    serious problem.  Then the highest level Library routine could call XERMSG
    just before returning to its caller.  This also allows the highest level
    routine the most flexibility in assigning error numbers and assures that
    all possible error conditions are documented in one prologue rather than
    being distributed through prologues of subsidiary routines.
 
Below we describe only subroutine XERMSG.  Other routines in the error
handling package are described in their prologues and in Reference [4].
The call to XERMSG looks like
 
Template:  CALL XERMSG (library, routine, message, errornumber, level)
 
Example:   CALL XERMSG ('SLATEC', 'MMPY',
          1   'The order of the matrix exceeds the row dimension', 3, 1)
 
where the meaning of the arguments is
 
library       A character constant (or character variable) with the name of
              the library.  This will be 'SLATEC' for the SLATEC Common Math
              Library.  The error handling package is general enough to be used
              by many libraries simultaneously, so it is desirable for the
              routine that detects and reports an error to identify the library
              name as well as the routine name.
 
routine       A character constant (or character variable) with the name of the
              routine that detected the error.  Usually it is the name of the
              routine that is calling XERMSG.  There are some instances where a
              user callable library routine calls lower level subsidiary
              routines where the error is detected.  In such cases it may be
              more informative to supply the name of the routine the user
              called rather than the name of the subsidiary routine that
              detected the error.
 
message       A character constant (or character variable) with the text of the
              error or warning message.  In the example below, the message is a
              character constant that contains a generic message.
 
                    CALL XERMSG ('SLATEC', 'MMPY',
                   *   'The order of the matrix exceeds the row dimension',
                   *   3, 1)
 
              It is possible (and is sometimes desirable) to generate a
              specific message--e.g., one that contains actual numeric values.
              Specific numeric values can be converted into character strings
              using formatted WRITE statements into character variables.  This
              is called standard Fortran internal file I/O and is exemplified
              in the first three lines of the following example.  You can also
              catenate substrings of characters to construct the error message.
              Here is an example showing the use of both writing to an internal
              file and catenating character strings.
 
                    CHARACTER*5 CHARN, CHARL
                    WRITE (CHARN,10) N
                    WRITE (CHARL,10) LDA
                 10 FORMAT(I5)
                    CALL XERMSG ('SLATEC', 'MMPY', 'The order'//CHARN//
                   *   ' of the matrix exceeds its row dimension of'//
                   *   CHARL, 3, 1)
 
              There are two subtleties worth mentioning.  One is that the //
              for character catenation is used to construct the error message
              so that no single character constant is continued to the next
              line.  This avoids confusion as to whether there are trailing
              blanks at the end of the line.  The second is that by catenating
              the parts of the message as an actual argument rather than
              encoding the entire message into one large character variable,
              we avoid having to know how long the message will be in order to
              declare an adequate length for that large character variable.
              XERMSG calls XERPRN to print the message using multiple lines if
              necessary.  If the message is very long, XERPRN will break it
              into pieces of 72 characters (as requested by XERMSG) for
              printing on multiple lines.  Also, XERMSG asks XERPRN to prefix
              each line with ' *  ' so that the total line length could be 76
              characters.  Note also that XERPRN scans the error message
              backwards to ignore trailing blanks.  Another feature is that the
              substring '$$' is treated as a new line sentinel by XERPRN.  If
              you want to construct a multiline message without having to count
              out multiples of 72 characters, just use '$$' as a separator.
              '$$' obviously must occur within 72 characters of the start of
              each line to have its intended effect since XERPRN is asked to
              wrap around at 72 characters in addition to looking for '$$'.
 
errornumber   An integer value that is chosen by the library routine's author.
              It must be in the range 1 to 999.  Each distinct error should
              have its own error number.  These error numbers should be
              described in the machine readable documentation for the routine.
              The error numbers need be unique only within each routine, so it
              is reasonable for each routine to start enumerating errors from 1
              and proceeding to the next integer.
 
level         An integer value in the range 0 to 2 that indicates the level
              (severity) of the error.  Their meanings are
 
              0  A warning message.  This is used if it is not clear that there
                 really is an error, but the user's attention may be needed.
 
              1  A recoverable error.  This is used even if the error is so
                 serious that the routine cannot return any useful answer.  If
                 the user has told the error package to return after
                 recoverable errors, then XERMSG will return to the Library
                 routine which can then return to the user's routine.  The user
                 may also permit the error package to terminate the program
                 upon encountering a recoverable error.
 
              2  A fatal error.  XERMSG will not return to its caller after it
                 receives a fatal error.  This level should hardly ever be
                 used; it is much better to allow the user a chance to recover.
                 An example of one of the few cases in which it is permissible
                 to declare a level 2 error is a reverse communication Library
                 routine that is likely to be called repeatedly until it
                 integrates across some interval.  If there is a serious error
                 in the input such that another step cannot be taken and the
                 Library routine is called again without the input error having
                 been corrected by the caller, the Library routine will
                 probably be called forever with improper input.  In this case,
                 it is reasonable to declare the error to be fatal.
 
Each of the arguments to XERMSG is input; none will be modified by XERMSG.  A
routine may make multiple calls to XERMSG with warning level messages; however,
after a call to XERMSG with a recoverable error, the routine should return to
the user.  Do not try to call XERMSG with a second recoverable error after the
first recoverable error because the error package saves the error number.  The
user can retrieve this error number by calling another entry point in the error
handling package and then clear the error number when recovering from the
error.  Calling XERMSG in succession causes the old error number to be
overwritten by the latest error number.  This is considered harmless for error
numbers associated with warning messages but must not be done for error numbers
of serious errors.  After a call to XERMSG with a recoverable error, the user
must be given a chance to call NUMXER or XERCLR to retrieve or clear the error
number.
 
 
 
 
*******************************************************************************
 
APPENDIX D.  DISTRIBUTION FILE STRUCTURE
 
The source files of the SLATEC library distribution tape are ASCII text files.
Each line image consists of exactly 80 characters.  The first file of the tape
is text file describing the contents of the tape.
 
The SLATEC source code file has the following characteristics.
 
1.  All subprograms in the file are in alphabetic order.  The collating
    sequence is 0 through 9 and then A through Z.
 
2.  Before each subprogram, of name for example XYZ, there is a line starting
    in column 1 with
 
    *DECK XYZ
 
    This allows the source file to be used as input for a source code
    maintenance program.
 
3.  No comments other than the *DECK lines appear between subprograms.
 
 
 
 
*******************************************************************************
 
APPENDIX E.  SUGGESTED FORMAT FOR A SLATEC SUBPROGRAM
 
A template embodying the suggested format for a SLATEC subprogram is given
below.  As elsewhere in this Guide, the caret (^) denotes a required blank
character.  These should be replaced with blanks AFTER filling out the
template.  The template itself begins with the *DECK line, below.  All
occurrences of "NAME" are to be replaced with the actual name of the
subprogram, of course.  Items in brackets [] are either explanations or
optional information.  Lines that do not have C or * in column 1 are
explanatory remarks that are intended to be deleted by the programmer.  In all
cases where "or" is used, exactly one of the indicated forms must occur.
 
Lines that begin with C*** are standard SLATEC lines.  These must be in the
indicated order.  See Section 8 of this Guide for information on required vs
optional lines.  In all but the C***DESCRIPTION section, the exact spacing and
punctuation are as mandated by this Guide.  Spacing within this section is only
suggestive, except as noted below.  The SLATEC standard mandates that no other
comments may begin "C***".  All other lines between the C***BEGIN^PROLOGUE
and the C***END^PROLOGUE must be comment lines with "C^" in columns 1-2.
 
Within the C***DESCRIPTION section, lines that begin with "C^*" are for the
LLNL LDOC standard [9].  If present, these lines must be exactly as given here.
They should be in the indicated order.  All other lines in this section must
have "C^^" in columns 1-3.
 
In the Arguments subsection, each argument must be followed by exactly one
argument qualifier.  The qualifier must be preceded by a colon and followed
by at least one blank.  The allowable qualifiers and their meanings follow.
 
  Qualifier     Meaning
  ---------    ---------
   :IN      input variable.  Must be set by the user prior to the call
            (unless otherwise indicated).  Must NOT be changed by the
            routine under any circumstances.
   :OUT     output variable.  Values will be set by the routine.
            Must be initialized before first usage in the routine.
   :INOUT   input/output variable.  Must be set by the user prior to
            the call (as indicated in argument description); value(s)
            may be set or changed by the routine.
   :WORK    workspace.  Simply working storage required by the routine.
            Need not be set prior to the call and will not contain
            information meaningful to the user on return.  (Some
            routines require the contents of a work array to remain
            unchanged between successive calls.  Such usage should be
            carefully explained in the argument description.)
   :EXT     external procedure.  The actual argument must be the name of
            a SUBROUTINE, FUNCTION, or BLOCK DATA subprogram.  It must
            appear in an EXTERNAL statement in the calling program.  The
            argument description following should precisely specify the
            expected calling sequence.
   :DUMMY   dummy argument.  Need not be set by user; will not be
            referenced by the routine.  [Use discouraged!]
 
To avoid potential problems with automatic formatting of argument descriptions,
none of these key words should appear anywhere else in the text immediately
preceded by a colon.
 
NOTES:
   1. Make a template by copying the following "*DECK^NAME" through
      "^^^^^^END" lines, inclusive, from this Guide.
   2. You will probably want to customize this template by filling
      in the C***AUTHOR section and adding other things you customarily
      include in your prologues.  If all of your routines are in the same
      category(ies), you may wish to fill in the C***CATEGORY and
      C***KEYWORDS sections, too.  Be sure to eliminate the brackets [].
   3. Be sure to delete the "C***SUBSIDIARY" line if this is a user-
      callable routine.
 
 
*DECK^NAME
^^^^^^SUBROUTINE^NAME[^(ARG1[,^ARG2[,^...]])]               or
^^^^^^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])                   or
^^^^^^COMPLEX^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])           or
^^^^^^DOUBLE^PRECISION^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])  or
^^^^^^INTEGER^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])           or
^^^^^^REAL^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])              or
^^^^^^LOGICAL^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])           or
^^^^^^CHARACTER[*len]^FUNCTION^NAME^(ARG1[,^ARG2[,^...]])
C***BEGIN^PROLOGUE^^NAME
C***SUBSIDIARY
C***PURPOSE^^Brief (1-6 lines) summary of the purpose of this routine.
C^^^^^^^^^^^^(To best fit LDOC standards, first line should be suitable
C^^^^^^^^^^^^for a table of contents entry for this routine.)
C***LIBRARY^^^SLATEC[^(Package)]
C***CATEGORY^^CAT1[,^CAT2]
C***TYPE^^^^^^SINGLE PRECISION^(NAME-S,^DNAME-D)
C***KEYWORDS^^KEY1[,^KEY2[,
C^^^^^^^^^^^^^MORE]]
C***AUTHOR^^Last-name[,^First-name[,^(Organization)]][
C^^^^^^^^^^^^^More information][
C^^^^^^^^^^^Second-last-name[,^First-name[,^(Organization)]][
C^^^^^^^^^^^^^More information]]
C***DESCRIPTION
C^^
C^*Usage:
C^^ This subsection should have declarations for all arguments to the
C^^   routine and a model call of the routine.  Use the actual names of
C^^   the arguments here. Ideally, arguments should be named in a way
C^^   that suggests their meaning.
C^^ The following example illustrates the use of dummy identifiers (in
C^^   lower case) to indicate that the required size of an array is
C^^   some function of the values of the other arguments.  This may not
C^^   be legal Fortran, but should be easier for a knowledgeable user
C^^   to understand than giving the required size somewhere else.
C^^
C^^      INTEGER  M, N, MDIMA, IERR
C^^      PARAMETER  (nfcns = 6, nwks = 3*nfcns+M+7)
C^^      REAL  X(nmax), A(MDIMA,nmax), FCNS(nfcns), WKS(nwks)
C^^
C^^      CALL NAME (M, N, X, A, MDIMA, FCNS, WKS, IERR)
C^^
C^*Arguments:
C^^ Arguments should be described in exactly the same order as in the
C^^   CALL list.  Include any restrictions, etc.
C^^ The following illustrates the recommended form of argument descrip-
C^^   tions for the example given above.  Note the use of qualifiers.
C^^
C^^   M :IN^    is the number of data points.
C^^
C^^   N :IN^    is the number of unknowns.  (Must have  0.lt.N.le.M .)
C^^
C^^   X :IN^    is a real array containing ...
C^^             (The dimensioned length of X must be at least N.)
C^^
C^^   A :INOUT^ should contain ... on input; will be destroyed on
C^^             return.  (The second dimension of A must be at least N.)
C^^
C^^   MDIMA:IN^ is the first dimension of array A.
C^^             (Must have  M.le.MDIMA .)
C^^
C^^   FCNS:OUT^ will contain the six summary functions based on ...
C^^
C^^   WKS:WORK^ is a real array of working storage.  Its length is a
C^^             function of the length of FCNS and the number of data
C^^             points, as indicated above.
C^^
C^^   IERR:OUT^ is an error flag with the following possible values:
C^^             Normal return:
C^^                IERR = 0  (no errors)
C^^             Warning error:
C^^                IERR > 0  means what?
C^^             "Recoverable" errors:
C^^                IERR =-1  if M < 1 or N < 1 .
C^^                IERR =-2  if M > MDIMA .
C^^                IERR =-3  means what?
C^^
C^*Function^Return^Values:
C^^ This subsection is present only in a FUNCTION subprogram.
C^^ In case of an integer- or character-valued function with a discrete
C^^   set of values, list all possible return values, with their
C^^   meanings, in the following form.  [The colon is significant.]
C^^      value : meaning
C^^   Otherwise, something of the following sort is acceptable.
C^^      SQRT : the square root of X.
C^^
C^*Description:
C^^ One or more paragraphs describing the intended routine use,
C^^   dependencies on other routines, etc.  Specific algorithm
C^^   descriptions could go here, if appropriate.
C^^ The emphasis should be on information useful to a user (as opposed
C^^   to developer or maintainer) of the routine.
C^^
C^*Examples:
C^^ Detailed examples of usage would go here, if desired.
C^^
C^*Accuracy:
C^^ This optional subsection contains notes on the accuracy or
C^^   precision of the results computed by the routine.
C^^
C^*Cautions:
C^^ List any known problems or potentially hazardous side effects
C^^   that are not otherwise described, such as not being safe for
C^^   multiprocessing or exceptional cases for arguments.
C^^   (Ideally, there should be none in a SLATEC routine!)
C^^
C^*See^Also:
C^^ This subsection would contain notes that refer to other library
C^^   routines that interrelate to this routine in important ways.
C^^   Examples include a solver for a LU factorization routine or an
C^^   evaluator for an interpolation or approximation routine.
C^^ This subsection may amplify information in the C***SEE ALSO
C^^   section, below, which should appear only if the prologue of the
C^^   listed routine(s) contains documentation for this routine.
C^^
C^*Long^Description:
C^^ An optional subsection containing much more detailed information.
C^^
C***SEE^ALSO^^RTN1[,^RTN2[,
C^^^^^^^^^^^^^RTNn]]
C***REFERENCES^^(NONE)              or
C***REFERENCES^^1. Reference 1 ...
C^^^^^^^^^^^^^^^^^Continuation of reference 1.
C^^^^^^^^^^^^^^^2. Reference 2 ...
C^^^^^^^^^^^^^^^^^Continuation of reference 2.
C***ROUTINES^CALLED^^(NONE)         or
C***ROUTINES^CALLED^^RTN1[,^RTN2[,
C^^^^^^^^^^^^^^^^^^^^RTNn]]
   [Do not include standard Fortran intrinsics or externals.]
C***COMMON^BLOCKS^^^^BLOCK1[,^BLOCK2]
C***REVISION^HISTORY^^(YYMMDD)
   [ This section should contain a record of the origin and ]
   [ modification history of this routine.                  ]
C^^^871105^^DATE^WRITTEN
C^^^880121^^Various editorial changes.       (Version 6)
C^^^881102^^Converted to new SLATEC format.  (Version 7)
C^^^881128^^Various editorial changes.       (Version 8)
C^
C***END^PROLOGUE^^NAME
C
C*Internal Notes:
C   Implementation notes that explain details of the routine's design
C     or coding, tricky dependencies that might trip up a maintainer
C     later, environmental assumptions made, alternate designs that
C     were considered but not used, etc.
C   Details on contents of common blocks referenced, locks used, etc.,
C     would go here.
C   Emphasis is on INTERNALLY useful information.
C
C**End
C
C  Additional comments that are not appropriate even for an internal
C  document, but which the programmer feels should precede declarations.
C
C  Declare arguments.
C
   < Declarations >
C
C  Declare local variables.
C
   < Declarations >
C
C***FIRST^EXECUTABLE^STATEMENT^^NAME
   < Body of NAME >
^^^^^^END
 
 
 
 
*******************************************************************************
 
ACKNOWLEDGEMENT
 
The authors wish to acknowledge the assistance provided by  Dr. Frederick N.
Fritsch of the Computing and Mathematics Research Division, Lawrence Livermore
National Laboratory, who wrote Appendix E and made corrections and comments on
the manuscript.
 
 
 
 
*******************************************************************************
 
REFERENCES
 
[1]  W. H. Vandevender and K. H. Haskell, The SLATEC mathematical subroutine
     library, SIGNUM Newsletter, 17, 3 (September 1982), pp. 16-21.
 
[2]  P. A. Fox, A. D. Hall and N. L. Schryer, The PORT mathematical subroutine
     library, ACM Transactions on Mathematical Software, 4, 2 (June 1978), pp.
     104-126.
 
[3]  P. A. Fox, A. D. Hall and N. L. Schryer, Algorithm 528: framework for a
     portable library, ACM Transactions on Mathematical Software, 4, 2 (June
     1978), pp. 177-188.
 
[4]  R. E. Jones and D. K. Kahaner, XERROR, the SLATEC error-handling package,
     Software - Practice and Experience, 13, 3 (March 1983), pp. 251-257.
 
[5]  R. F. Boisvert, S. E. Howe and D. K. Kahaner, GAMS: a framework for the
     management of scientific software, ACM Transactions on Mathematical
     Software, 11, 4 (December 1985), pp. 313-355.
 
[6]  American National Standard Programming Language FORTRAN, ANSI X3.9-1978,
     American National Standards Institute, 1430 Broadway, New York, New York
     10018, April 1978.
 
[7]  W. S. Brown, A simple but realistic model of floating point computation,
     ACM Transactions on Mathematical Software, 7, 4 (December 1981), pp.
     445-480.
 
[8]  F. N. Fritsch, SLATEC/LDOC prologue: template and conversion program,
     Report UCID-21357, Rev.1, Lawrence Livermore National Laboratory,
     Livermore, California, November 1988.