It is strongly suggested that users force all program variables to be explicitly typed. This is done by including the line “IMPLICIT NONE” as close to the first line as possible. Study some of the examples accompanying an IMSL Fortran Library routine early on. These examples are available online as part of the product.

Each subject routine called or otherwise referenced requires the “use” statement for an interface block designed for that subject routine. The contents of this interface block are the interfaces to the separate routines available for that subject. Packaged descriptive names for option numbers that modify documented optional data or internal parameters might also be provided in the interface block. Although this seems like an additional complication, many typographical errors are avoided at an early stage in development through the use of these interface blocks. The “use” statement is required for each routine called in the user’s program.

However, if one is only using the Fortran 77 interfaces supplied for backwards compatibility then the “use” statements are not required.

IMSL Fortran Library routines have required arguments and may have optional arguments. All arguments are documented for each routine. For example, consider the routine ORDST that determines order statistics. The required arguments are X, NOS, OS, and NMISS. The input data for the problem are the X array and NOS, the number of order statistics; the output is returned in the OS array. The number of missing values is returned in NMISS. This routine has as optional arguments NOBS, IOPT, and IOS. If one wishes to calculate a different set of order statistics than the default (the first NOS order statistics) then the optional argument given by the “IOPT=” keyword should be used in the argument list. See Example 2 of ORDST in Chapter 1, “Basic Statistics” for an example of this functionality.

For compatibility with previous versions of the IMSL Libraries, the NUMERICAL_LIBRARIES interface module includes backwards compatible positional argument interfaces to all routines which existed in the Fortran 77 version of the Library. Note that it is not necessary to use “use” statements when calling these routines by themselves. Existing programs which called these routines will continue to work in the same manner as before.

The routines in the IMSL STAT LIBRARY attempt to detect and report errors and invalid input. Errors are classified and are assigned a code number. By default, errors of moderate or worse severity result in messages being automatically printed by the routine. Moreover, errors of worse severity cause program execution to stop. The severity level as well as the general nature of the error is designated by an “error type” with numbers from 0 to 5. An error type 0 is no error; types 1 through 5 are progressively more severe. In most cases, you need not be concerned with our method of handling errors. For those interested, a complete description of the error-handling system is given in the Reference Material, which also describes how you can change the default actions and access the error code numbers.

Several routines in the IMSL STAT LIBRARY have an option for printing results. These routines have an optional argument, IPRINT, to control the printing. In any routine that allows printing, if IPRINT = 0, (the default) then no printing is done (except possibly error messages). Some routines allow various amounts of printing; one value of IPRINT might result in printing only summary statistics, while another value might cause more detailed statistics or intermediate results to be printed. Other routines in the STAT LIBRARY do not print any of the results. In all routines, of course, the output is returned in FORTRAN variables, so if the routine does not do printing, or if you use the default IPRINT value, you can print the results yourself. The STAT LIBRARY contains some special routines just for printing arrays. For example, WRRRN and WRRRL are two convenient routines for printing matrices. See Chapter 19, “Utilities” for detailed descriptions of these routines.

A commonly used routine in the examples is the IMSL routine UMACH, which retrieves the FORTRAN device unit number for printing the results. Because this routine obtains device unit numbers, it can be used to redirect the input or output. The section on Machine-Dependent Constants in the Reference Material contains a description of the routine UMACH.

The IMSL Fortran Numerical Library allows users to leverage the high-performance technology of shared memory parallelism (SMP) when their environment supports it. Support for SMP systems within the IMSL Library is delivered through various means, depending upon the availability of technologies such as OpenMP, high performance LAPACK and BLAS, and hardware-specific IMSL algorithms. Use of the IMSL Fortran Numerical Library on SMP systems can be achieved by using the appropriate link environment variable when building your application. Details on the available link environment variables for your installation of the IMSL Fortran Numerical Library can be found in the online README file of the product distribution.

The IMSL Fortran Numerical Library is thread-safe in those environments that support OpenMP. This was achieved by using OpenMP directives that define global variables located in the code so they are private to the individual threads. Thread safety allows users to create instances of routines running on multiple threads and to include any routine in the IMSL Fortran Numerical Library in these threads.

Many of the routines in the IMSL STAT LIBRARY allow the data to contain missing values. These routines recognize as a missing value the special value referred to as ‘not a number,’ or NaN. The actual value is different on different computers, but it can be obtained by reference to the IMSL routines AMACH or DMACH, described in the Machine-Dependent Constants section of the Reference Material. In routines that allow missing values, two common arguments are NMISS and NRMISS. The definitions of these arguments vary somewhat depending on the specific routine. However, in a data structure where the rows represent observations and the columns represent variables, NRMISS is the number of rows containing missing values and NMISS is the total number of missing values.

The way that missing values are treated depends on the individual routine, and is described in the documentation for the routine.

Often in statistical analyses, not all of the data are available in computer memory at once. Many of the routines in the STAT LIBRARY accept a part of the data, accumulate some statistics, and continue accepting data and accumulating statistics until all of the data have been processed. The routines that allow the data to be processed a little at a time have an argument called “IDO.”

The IMSL Fortran Library allows users to leverage the high-performance technology of shared memory parallelism (SMP) when their environment supports it. Support for SMP systems within the IMSL Library is delivered through various means, depending upon the availability of technologies such as OpenMP, high performance BLAS, and hardware-specific IMSL algorithms. Use of the IMSL Fortran Library on SMP systems can be achieved by using the appropriate link environment variable when building your application. Details on the available link environment variables for your installation of the IMSL Fortran Library can be found in the online README file of the product distribution.

This introduction has acquainted you with a few general characteristics of IMSL STAT LIBRARY. If you are using the STAT LIBRARY at a computer center, the computer center consultant will provide the details necessary to use the IMSL routines on your computer system.