NAG Fortran Library, Mark 24

FLW6I24DDL - License Managed

Microsoft Windows x64, 64-bit integers, Intel Fortran

Users' Note



Contents


1. Introduction

This document is essential reading for every user of the NAG Fortran Library implementation specified in the title. It provides implementation-specific detail that augments the information provided in the NAG Mark 24 Library Manual (which we will refer to as the Library Manual). Wherever that manual refers to the "Users' Note for your implementation", you should consult this note.

In addition, NAG recommends that before calling any Library routine you should read the following reference material (see Section 5):

(a) Essential Introduction
(b) Chapter Introduction
(c) Routine Document

The libraries supplied with this implementation have been compiled in a manner that facilitates the use of multiple threads.

2. Post Release Information

Please check the following URL:

http://www.nag.co.uk/doc/inun/fl24/w6iddl/postrelease.html

for details of any new information related to the applicability or usage of this implementation.

3. General Information

For best performance, we recommend that you use one of the variants of the NAG Fortran Library which is based on the supplied Intel ® Math Kernel Library (MKL), i.e. nag_mkl_MT.lib, nag_mkl_MD.lib or FLW6I24DD_mkl.lib/FLW6I24DD_mkl.dll. However if you use a version of the MKL different from the version used in creating this implementation and you have problems when calling a NAG routine, we suggest that you use one of the above libraries with the supplied MKL, or one of the self-contained libraries nag_nag_MT.lib, nag_nag_MD.lib or FLW6I24DD_nag.lib/FLW6I24DD_nag.dll.

Which static variant of the NAG Library you should use will also depend on how you wish to link to the Microsoft run-time libraries. For example, if you are linking with the multithreaded static run-time libraries, you should use nag_mkl_MT.lib or nag_nag_MT.lib, whereas if you are linking with the multithreaded dynamic link run-time libraries, you should use nag_mkl_MD.lib or nag_nag_MD.lib. Alternatively, if you wish to call a dynamic link library (DLL) variant of the NAG Library, you should link with the import library FLW6I24DD_mkl.lib or FLW6I24DD_nag.lib (and, at run time, make sure that the corresponding DLL, FLW6I24DD_mkl.dll or FLW6I24DD_nag.dll, is on your path). For more details, see Section 3.1.1.

3.1. Accessing the Library

The NAG Fortran Library has been built using the version of Intel Fortran described in the Installer's Note. To call the DLLs from a program compiled with a different version of Intel Fortran, you may need to move or rename the files libifcoremd.dll, libmmd.dll and svml_dispmd.dll in the install dir\bin folder, so that the correct Intel Fortran runtime DLLs are picked up. To facilitate this, the batch file hide_ifort_rtls.bat has been provided in the install dir\bin folder. This file will rename the Intel Fortran run-time libraries libifcoremd.dll, libmmd.dll and svml_dispmd.dll in that folder. The file expose_ifort_rtls.bat, also in that folder, is provided to convert the names back again. (Note that appropriate access permissions may need to be in place for these batch files to work.)

In this section we assume that the Library has been installed in the default folder:

  c:\Program Files\NAG\FL24\flw6i24ddl
If this folder does not exist, please consult the system manager (or the person who did the installation). In some of the following subsections, this folder is referred to as install dir.

We also assume that the default shortcut for the Library command prompt is placed in the Start Menu under:

  Start|All Programs|NAG|FL24|NAG Fortran Library - Intel Fortran (FLW6I24DDL)

If this shortcut does not exist, please consult the system manager (or the person who did the installation). (Other shortcuts created as part of the Library installation procedure are also assumed to be in this location.)

(Under Windows 8, the shortcuts appear under the list of all applications. To find this, right-click on the background of the Start screen and select All apps from the bottom right hand corner of the screen. The shortcuts are listed under the NAG section.)

If you are using one of the DLL forms of the Library (see Section 3.1.1), you need to ensure that the NAG DLL (FLW6I24DD_mkl.dll or FLW6I24DD_nag.dll) is accessible at run time; therefore the install dir\bin folder must be on the path. If an MKL-based version of the Library is to be used, the install dir\MKL_intel64_11.0\bin folder must also be on the path, but should appear later in the path than the install dir\bin folder, since the NAG versions of a few Basic Linear Algebra Subprograms (BLAS) / Linear Algebra PACKage (LAPACK) routines are included in the NAG Libraries to avoid problems with the vendor versions. (See Section 4 for details.)

To check the accessibility of the NAG DLLs, run the program NAG_Fortran_DLL_info.exe which is available from the Start Menu shortcut

  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|Check NAG DLL Accessibility for FLW6I24DDL
See Section 4.2.3 of the Installer's Note for details of this utility.

3.1.1. From a command window

To access this implementation from a command window some environment variables need to be set.

The shortcut:

  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|FLW6I24DDL Command Prompt

may be used to start a command prompt window with the correct settings for the INCLUDE, LIB and PATH environment variables for the Library and the supplied MKL.

If the shortcut is not used, you can set the environment variables by running the batch file envvars.bat for this implementation. The default location of this file is:

  c:\Program Files\NAG\FL24\flw6i24ddl\batch\envvars.bat
If the file is not in the default location, you can locate it by searching for the file envvars.bat containing flw6i24ddl.

You may then compile and link to the NAG Fortran Library on the command line using one of the following commands:

  ifort /MT /4I8 driver.f90 nag_mkl_MT.lib user32.lib mkl_intel_ilp64.lib
      mkl_intel_thread.lib mkl_core.lib libiomp5md.lib

  ifort /MT /4I8 driver.f90 nag_nag_MT.lib user32.lib

  ifort /MD /4I8 driver.f90 nag_mkl_MD.lib user32.lib mkl_intel_ilp64_dll.lib
      mkl_intel_thread_dll.lib mkl_core_dll.lib libiomp5md.lib

  ifort /MD /4I8 driver.f90 nag_nag_MD.lib user32.lib

  ifort /MD /4I8 driver.f90 FLW6I24DD_mkl.lib

  ifort /MD /4I8 driver.f90 FLW6I24DD_nag.lib
where driver.f90 is your application program.

Note that the /4I8 switch tells the compiler to use 64-bit integer and logical types instead of the default 32-bits.

The order of the libraries is important because certain parts of the MKL should not be used (see Section 4).

The first two commands use libraries compiled with the /MT option. The first command will use the static library without the NAG version of the BLAS/LAPACK procedures (nag_mkl_MT.lib) in addition to the MKL static libraries. (N.B. newer versions of the Intel compiler no longer have the MT version of the OMP run-time library libiomp5mt.lib, so it is necessary to link to libiomp5md.lib instead).

The second command will use the library containing the NAG version of the BLAS/LAPACK procedures (nag_nag_MT.lib). The option /MT must be used to ensure linking with the correct run-time libraries (multithreaded static run-time libraries in this case).

The third and fourth commands use static libraries compiled with the /MD option. The third command will use the static library without the NAG version of the BLAS/LAPACK procedures (nag_mkl_MD.lib) in addition to the MKL DLLs. The fourth command will use the library containing the NAG version of the BLAS/LAPACK procedures (nag_nag_MD.lib). The option /MD must be used to ensure linking with the correct run-time libraries (multithreaded dynamic link run-time libraries in this case).

The last two commands use DLL import libraries compiled with the /MD option. The fifth command will use the DLL without the NAG version of the BLAS/LAPACK procedures (FLW6I24DD_mkl.lib) in addition to the MKL DLLs. It is not necessary to add the path to the MKL import libraries here, since the BLAS and LAPACK symbols are exported from the NAG import library (FLW6I24DD_mkl.lib) in this instance. (Note that this behaviour may be different from some other NAG library implementations.) The last command will use the DLL containing the NAG version of the BLAS/LAPACK procedures (FLW6I24DD_nag.lib). The option /MD must be used to ensure linking with the correct run-time libraries.

Note that /MT is equivalent to specifying /libs:static /threads and /MD is equivalent to specifying /libs:dll /threads.

Please note that the Intel Visual Fortran compiler environment variables must be set in the command window. For more details refer to the User's Guide for the compiler.

3.1.2. From MS Visual Studio .NET

The instructions given here are for Visual Studio .NET 2005/2008/2010 with Intel Fortran Compiler 13.0. Other versions may vary.

To ensure that the NAG DLLs are accessible at runtime, the PATH environment variable must be set such that the location of the NAG DLLs, specifically the folder install dir\bin, is on the path. If the MKL version of the DLL is required, the location of the MKL DLLs, install dir\MKL_intel64_11.0\bin must also be on the path, but should appear after the install dir\bin folder.

Once Visual Studio has been opened, it is possible to set up the directories for use with Intel Fortran in this and all subsequent projects which use this compiler. One way to do so is:

  1. Select the Tools pull down menu, and click on Options.

  2. In the Options window, click on Intel(R) Fortran (or Intel(R) Visual Fortran) and then choose Compilers in the left window pane. (In some versions of Visual Studio you may need to click on Show all settings to see the Intel compiler options.)

  3. In the right window pane, click on the '...' to the right of the Libraries panel.

  4. Add the path to the NAG DLL import library to the Set Directory List window. The default location is:
      c:\Program Files\NAG\FL24\flw6i24ddl\lib
    

  5. In this implementation, for the DLL version of the library there is no need to add the path to the MKL import libraries, since the BLAS and LAPACK symbols are exported from the NAG import library (FLW6I24DD_mkl.lib). (Note that this behaviour may be different from some other NAG library implementations.) However, any MKL library folders in the Libraries path must come after the path to the NAG Library, as it is important that these are not picked up before the NAG Library, as explained in Section 3.1.

  6. Click on the OK button in the Set Directory List window.

  7. In the right window pane, click on the '...' to the right of the Includes panel.

  8. Add the path to the NAG interface blocks to the Set Directory List window. The default location is:
      c:\Program Files\NAG\FL24\flw6i24ddl\nag_interface_blocks
    

  9. Click on the OK button in the Set Directory List window.

  10. Click on the OK button in the Options window.

Having done this, if an Intel Fortran project requires a library or NAG interface block during the compilation and linking process then the full path to the library and interface block do not need to be specified.

Whilst the above changes will apply to every Intel Fortran project, the following tasks need to be performed for each individual Intel Fortran project.

The library is intended to be run in fully optimised mode, so to avoid any warning messages, you might decide to set the active configuration to Release. You can do this from the Toolbar or alternatively via the Build|Configuration Manager menus. Note that if you work in Debug mode, you may receive a warning message about conflicting C run-time libraries.

There are a number of ways to add the NAG Library to the project. We describe just two; choose the one that most suits you.

If the Solution Explorer window is open then make sure that the group project (the first line) is NOT selected. From the Project menu, choose the project Properties item. (Alternatively right-click on a specific single project in the Solution Explorer and choose Properties.)

From the form, click Linker in the leftmost panel and then choose Input. The right hand panel will now have an Additional Dependencies entry, and you need to type nag_mkl_MT.lib user32.lib mkl_intel_ilp64.lib mkl_intel_thread.lib mkl_core.lib libiomp5md.lib in this location to use the nag_mkl_MT.lib library and MKL. Please note that the six libraries are separated by a space only and that nag_mkl_MT.lib must be the first one. Press the OK button. If you wish to use the self-contained NAG Library nag_nag_MT.lib then you need to add nag_nag_MT.lib user32.lib instead of the six libraries above. Similary, to use one of the other NAG Libraries, insert the appropriate library or libraries (as detailed in Section 3.1.1) in the Additional Dependencies field.

Before you can compile the project you need to specify the correct run-time library needed.

From the Properties Window, click Fortran in the leftmost panel and then choose Libraries. The right hand panel will now have a Runtime Library entry, and you need to select Multithreaded if your project uses one of the two libraries nag_nag_MT.lib or nag_mkl_MT.lib. If your projects uses any of the other NAG libraries you need to select Multithreaded DLL. After you select the correct run-time library press the OK button.

The Properties information may also be accessed via the Toolbar. With the project selected in Solution Explorer, choose the Properties Window button on the Toolbar. In the ensuing window choose then the rightmost Property Pages icon. Select the appropriate settings as detailed in the paragraphs above.

In summary, the setting of the project Additional Dependencies, the project Runtime Library and the PATH environment variable must be consistent as follows:

Since this version of the NAG library uses 64-bit integer and logical types, it is important that your program should do the same. By default, Fortran integer and logical types are 32-bit. You must either explicitly declare your variables like this:

  integer (kind=8) i, j, k
  logical (kind=8) p
or you can set the appropriate compiler flag to promote the types automatically. This can be done by going to the project properties page under Fortran / Data, and setting Default Integer KIND to 8 (/integer_size64).

Important: in the Visual Studio "Configuration Manager", ensure the Active Solution Platform is set to x64 (to ensure compatibility with this 64-bit implementation of the NAG Library). If x64 is not shown in the list of available platforms, choose New... and type or choose x64, copying settings from Win32. Failure to set the platform to x64 will result in linker errors when you build your project.

The project should now compile and link using the appropriate choice from the Build menu.

To run a program that does not require input or output redirected from standard input or standard output, from within the Microsoft Development Environment, the program may be executed via the Debug menu (by selecting Start Without Debugging, for example).

If a data file needs to be attached to the standard input or the output of a program needs to be redirected to the standard output, we recommend that you run the executable from a command prompt window to avoid the limitations of Visual Studio .NET.

3.1.3. From Visual Basic for Applications 7 / Excel

The Fortran DLLs provided in this implementation are ideally suited for use within an Excel spreadsheet. The routines may be called from Visual Basic for Applications 7.0 (VBA7) code. The information here applies to 64-bit versions of Excel.

Examples of use of the DLLs from within Excel are given in the install dir\samples\excel64_examples folder. The folder install dir\samples\excel64_examples\linear_algebra contains the file xls_demo_64.html. This file gives some hints about using NAG DLLs from within Excel spreadsheets.

Key information:

This has been tested using Microsoft Office Excel 2010.

3.1.4. From Visual Basic .NET

Many of the library routines are callable from Visual Basic .NET (VB.NET). Examples of use of the DLLs from VB.NET are given in the install dir\samples\vb.net64_examples folder. (These examples were created using Visual Studio 2005; if loaded into Visual Studio 2008 or later, the solution and project files will be converted by the Visual Studio Conversion Wizard.)

Key information:

This has been tested using Visual Studio 2005, 2008 and 2010.

3.1.5. Calling the Library from Microsoft or Intel C or C++

With care, the NAG Fortran Library may be used from within a C or C++ environment. To assist the user make the mapping between Fortran and C types, a C/C++ header file (nagmk24.h) is provided. It is recommended that users wishing to use a Fortran Library routine either copy and paste the relevant section of the file into their C or C++ application (making sure that the relevant #defines etc. are also copied from the top of the file) or simply include the header file with their application.

Examples of the use of the DLLs from C and C++ are given in the install dir\samples\c_examples and install dir\samples\cpp_examples folders.

A document, techdoc.html, giving more detailed advice on calling the DLLs from C and C++ is available in install dir\c_headers. There is also a shortcut to this document on the Start Menu under

  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|Calling FLW6I24DDL from C & C++
by default. Note that some changes will be needed if you paste code from one of the C examples given there into a C++ file since, if __cplusplus is defined, the header file provided uses C++ reference arguments for scalars, and therefore the "address of" operator should not be used. See Section 3 of the techdoc.html document for more details.

Key information:

Assuming that the folder containing the libraries has been added to the LIB environment variable, you may compile and link your C application program to the DLL version of the NAG Fortran Library on the command line in the following manner (assuming you are using Microsoft C):
  cl driver.c FLW6I24DD_mkl.lib
or
  cl driver.c FLW6I24DD_nag.lib
where driver.c is your application program. This assumes that the folder containing the header file has been added to the INCLUDE environment variable. If not, you could use:
  cl /I"install dir\c_headers" driver.c FLW6I24DD_mkl.lib
or
  cl /I"install dir\c_headers" driver.c FLW6I24DD_nag.lib
To link to one of the static libraries instead of a DLL, you will also need access to the compiler run-time library directory install dir\rtl. It is most convenient if you add that directory to your LIB environment variable, then use, for example:
  cl /MD /I"install dir\c_headers" driver.c nag_nag_MD.lib user32.lib
or
  cl /MT /I"install dir\c_headers" driver.c nag_nag_MT.lib user32.lib
The Intel C compiler icl may be used in the same way as the Microsoft compiler cl, though it may not be necessary to add the rtl directory to your LIB environment variable.

3.1.6. Calling the Library from Microsoft C#

With care, the NAG Fortran Library may also be used from within a C# environment. To assist the user make the mapping between Fortran and C# types, a C# header file (flcsdnet64.cs) is provided, in folder install dir\cs_headers. It is recommended that users wishing to use a Fortran Library routine copy and paste the relevant sections of the file into their C# application.

Examples of the use of the DLLs from C# are given in the install dir\samples\cs_examples folder. At a command line prompt, these can easily be compiled using the C# compiler csc like this:

  csc driver.cs
where driver.cs is the name of any of the example programs.

For further information, see also http://www.nag.co.uk/numeric/csharpinfo.asp.

3.1.7. Calling the Library from NAG Fortran Builder

It is possible to link to the DLL versions of the NAG library using nagfor, the Fortran Compiler which comes with NAG Fortran Builder. Interface blocks for use with version 5.3 of Fortran Builder are supplied in folder install dir\nag_interface_blocks_nagfor. It is important to note that you must link to the DLL itself, not the associated import library.

From a DOS command prompt, first make sure that the PATH environment variable is correctly set, as described in Section 3.1.1.

You may then compile and link to the NAG Fortran Library on the command line using one of the following commands:

  nagfor -i8 -I"install dir\nag_interface_blocks_nagfor" driver.f90
         "install dir\bin\FLW6I24DD_mkl.dll" -o driver.exe
  nagfor -i8 -I"install dir\nag_interface_blocks_nagfor" driver.f90
         "install dir\bin\FLW6I24DD_nag.dll" -o driver.exe
depending on whether you wish to link to the MKL version of the library or the all-NAG version. Note that the -i8 switch promotes integer and logical types to 64-bit instead of the default 32-bit, in order to maintain compatibility with this NAG library implementation.

Using the DLLs from within the Fortran Builder IDE itself is also easy, following steps like these:

Note that if you build your project in Debug mode (the default), it is not possible to use the Undefined variables option which is accessible on the Fortran Compiler / Runtime Check tab of Project Settings. This is because the NAG Library was not compiled with this option. Trying to use it will cause a compile-time error in Fortran Builder, showing an "Incompatible option setting" when using the NAG interface blocks.

3.1.8. Accessibility Check

To check whether the DLLs included in this library implementation are accessible from the current environment, run the program NAG_Fortran_DLL_info.exe which is available from the Start Menu shortcut
  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|Check NAG DLL Accessibility for FLW6I24DDL
See Section 4.2.3 of the Installer's Note for details of this utility.

3.2. Interface Blocks

The NAG Fortran Library interface blocks define the type and arguments of each user callable NAG Fortran Library routine. These are not essential to calling the NAG Fortran Library from Fortran programs. However, they are required if the supplied examples are used. Their purpose is to allow the Fortran compiler to check that NAG Fortran Library routines are called correctly. The interface blocks enable the compiler to check that:

(a) subroutines are called as such;
(b) functions are declared with the right type;
(c) the correct number of arguments are passed; and
(d) all arguments match in type and structure.

The NAG Fortran Library interface block files are organised by Library chapter. They are aggregated into one module named

  nag_library

The modules are supplied in pre-compiled form (.mod files) for use by the Intel Fortran compiler, ifort.

If you use the Library command prompt shortcut or set the environment variables by running the batch file envvars.bat for this implementation (see Section 3.1.1), and the Intel ifort compiler, you can use any of the commands described in Section 3.1.1 to access these modules since the environment variable INCLUDE will be set.

The .mod module files were compiled with the compiler shown in Section 2.1 of the Installer's Note. Such module files are compiler-dependent, so if you wish to use the NAG example programs, or use the interface blocks in your own programs, when using a compiler that is incompatible with these modules, you will first need to create your own module files, as described here.

Create a folder named nag_interface_blocks_original in a location of your choice (the exact folder name is not important), and copy the contents of nag_interface_blocks to nag_interface_blocks_original, thus saving the original set of interface blocks.

Then in folder nag_interface_blocks recompile all the .f90 files into objects using your compiler. Because the interface blocks contain some inter-dependencies, the order of compilation is important, but the following compilation order should work:

  ifort /4I8 -c nag_precisions.f90
  ifort /4I8 -c nag_a_ib.f90
  ifort /4I8 -c nag_blast_ib.f90
  ifort /4I8 -c nag_blas_consts.f90
  ifort /4I8 -c nag_blas_ib.f90
  ifort /4I8 -c nag_c_ib.f90
  ifort /4I8 -c nag_d_ib.f90
  ifort /4I8 -c nag_e_ib.f90
  ifort /4I8 -c nag_f_ib.f90
  ifort /4I8 -c nag_g_ib.f90
  ifort /4I8 -c nag_h_ib.f90
  ifort /4I8 -c nag_lapack_ib.f90
  ifort /4I8 -c nag_m_ib.f90
  ifort /4I8 -c nag_omp_ib.f90
  ifort /4I8 -c nag_s_ib.f90
  ifort /4I8 -c nag_w_ib.f90
  ifort /4I8 -c nag_x_ib.f90
  ifort /4I8 -c nag_long_names.f90
  ifort /4I8 -c nag_library.f90
The object files generated by the compilation may be discarded - only the module files are needed.

You should now be able to use the newly compiled module files in the usual way.

3.3. Example Programs

The example results distributed were generated at Mark 24, using the software described in Section 2.2 of the Installer's Note. These example results may not be exactly reproducible if the example programs are run in a slightly different environment (for example, a different Fortran compiler, a different compiler library, or a different set of BLAS or LAPACK routines). The results which are most sensitive to such differences are: eigenvectors (which may differ by a scalar multiple, often -1, but sometimes complex); numbers of iterations and function evaluations; and residuals and other "small" quantities of the same order as the machine precision.

The distributed example results are those obtained with the DLL library FLW6I24DD_mkl.lib, (i.e. using the MKL BLAS and LAPACK routines).

Note that the example material has been adapted, if necessary, from that published in the Library Manual, so that programs are suitable for execution with this implementation with no further changes. The distributed example programs should be used in preference to the versions in the Library Manual wherever possible.

The example programs are most easily accessed by one of the following batch files:

nag_mkl_MT.lib and nag_nag_MT.lib use the static multithreaded run-time library, whilst nag_mkl_MD.lib, nag_nag_MD.lib, FLW6I24DD_mkl.lib and FLW6I24DD_nag.lib use the multithreaded DLL run-time library.

The batch files need the environment variable NAG_FLW6I24DDL.

As mentioned in Section 3.1.1, the installation procedure provides a shortcut which starts a Command Prompt with local environment variables. The environment variables include NAG_FLW6I24DDL. This shortcut is, by default, placed in the Start Menu under

  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|FLW6I24DDL Command Prompt
If the shortcut is not used, you need to set this environment variable. It can be set by running the batch file envvars.bat for this implementation. The default location of this file is:
  c:\Program Files\NAG\FL24\flw6i24ddl\batch\envvars.bat
If the file is not in the default location, you can locate it by searching for the file envvars.bat containing flw6i24ddl.

Each of the nag_example* batch files mentioned above will provide you with a copy of an example program (and its data and options file, if any), compile the program and link it with the appropriate libraries (showing you the compile command so that you can recompile your own version of the program). Finally, the executable program will be run with appropriate arguments specifying data, options and results files as needed.

The example program concerned is specified by the argument to the command, e.g.

  nag_example_mkl_MT e04nrf
will copy the example program and its data and options files (e04nrfe.f90, e04nrfe.d and e04nrfe.opt) into the current folder and process them to produce the example program results in the file e04nrfe.r.

3.4. Fortran Types and Interpretation of Bold Italicised Terms

This implementation of the NAG Fortran Library uses 64-bit integers.

The NAG Library and documentation use parameterized types for floating-point variables. Thus, the type

      REAL(KIND=nag_wp)
appears in documentation of all NAG Fortran Library routines, where nag_wp is a Fortran KIND parameter. The value of nag_wp will vary between implementations, and its value can be obtained by use of the nag_library module. We refer to the type nag_wp as the NAG Library "working precision" type, because most floating-point arguments and internal variables used in the library are of this type.

In addition, a small number of routines use the type

      REAL(KIND=nag_rp)
where nag_rp stands for "reduced precision type". Another type, not currently used in the library, is
      REAL(KIND=nag_hp)
for "higher precision type" or "additional precision type".

For correct use of these types, see almost any of the example programs distributed with the Library.

For this implementation, these types have the following meanings:

      REAL (kind=nag_rp)      means REAL (i.e. single precision)
      REAL (kind=nag_wp)      means DOUBLE PRECISION
      COMPLEX (kind=nag_rp)   means COMPLEX (i.e. single precision complex)
      COMPLEX (kind=nag_wp)   means double precision complex (e.g. COMPLEX*16)

In addition, the Manual has adopted a convention of using bold italics to distinguish some terms.

One important bold italicised term is machine precision, which denotes the relative precision to which DOUBLE PRECISION floating-point numbers are stored in the computer, e.g. in an implementation with approximately 16 decimal digits of precision, machine precision has a value of approximately 1.0D-16.

The precise value of machine precision is given by the routine X02AJF. Other routines in Chapter X02 return the values of other implementation-dependent constants, such as the overflow threshold, or the largest representable integer. Refer to the X02 Chapter Introduction for more details.

The bold italicised term block size is used only in Chapters F07 and F08. It denotes the block size used by block algorithms in these chapters. You only need to be aware of its value when it affects the amount of workspace to be supplied – see the parameters WORK and LWORK of the relevant routine documents and the Chapter Introduction.

3.5. Explicit Output from NAG Routines

Certain routines produce explicit error messages and advisory messages via output units which have default values that can be reset by using X04AAF for error messages and X04ABF for advisory messages. (The default values are given in Section 4.)

4. Routine-specific Information

Any further information which applies to one or more routines in this implementation is listed below, chapter by chapter.
  1. F06, F07, F08 and F16

    In Chapters F06, F07, F08 and F16, alternate routine names are available for BLAS and LAPACK derived routines. For details of the alternate routine names please refer to the relevant Chapter Introduction. Note that applications should reference routines by their BLAS/LAPACK names, rather than their NAG-style names, for optimum performance.

    Many LAPACK routines have a "workspace query" mechanism which allows a caller to interrogate the routine to determine how much workspace to supply. Note that LAPACK routines from the MKL may require a different amount of workspace from the equivalent NAG versions of these routines. Care should be taken when using the workspace query mechanism.

    In this implementation calls to the NAG version of the following BLAS and LAPACK routines are included in the libraries nag_mkl_MT.lib, nag_mkl_MD.lib and FLW6I24DD_mkl.dll to avoid problems with the vendor version:

      DGERFS     DGGEVX     DGGGLM     DSBEV      DSBEVX
      DSBTRD     ZGEESX     ZHBEV      ZHBEVX     ZHBTRD
      ZTRSEN
    

  2. G02

    The value of ACC, the machine-dependent constant mentioned in several documents in the chapter, is 1.0D-13.

  3. S07 - S21

    Functions in these Chapters will give error messages if called with illegal or unsafe arguments.

    The constants referred to in the Library Manual have the following values in this implementation:

    S07AAF  F_1 = 1.0E+13
            F_2 = 1.0E-14
    
    S10AAF  E_1 = 1.8715E+1
    S10ABF  E_1 = 7.080E+2
    S10ACF  E_1 = 7.080E+2
    
    S13AAF  x_hi = 7.083E+2
    S13ACF  x_hi = 1.0E+16
    S13ADF  x_hi = 1.0E+17
    
    S14AAF  IFAIL = 1 if X > 1.70E+2
            IFAIL = 2 if X < -1.70E+2
            IFAIL = 3 if abs(X) < 2.23E-308
    S14ABF  IFAIL = 2 if X > x_big = 2.55E+305
    
    S15ADF  x_hi = 2.65E+1
    S15AEF  x_hi = 2.65E+1
    S15AFF  underflow trap was necessary
    S15AGF  IFAIL = 1 if X >= 2.53E+307
            IFAIL = 2 if 4.74E+7 <= X < 2.53E+307
            IFAIL = 3 if X < -2.66E+1
    
    S17ACF  IFAIL = 1 if X > 1.0E+16
    S17ADF  IFAIL = 1 if X > 1.0E+16
            IFAIL = 3 if 0 < X <= 2.23E-308
    S17AEF  IFAIL = 1 if abs(X) > 1.0E+16
    S17AFF  IFAIL = 1 if abs(X) > 1.0E+16
    S17AGF  IFAIL = 1 if X > 1.038E+2
            IFAIL = 2 if X < -5.7E+10
    S17AHF  IFAIL = 1 if X > 1.041E+2
            IFAIL = 2 if X < -5.7E+10
    S17AJF  IFAIL = 1 if X > 1.041E+2
            IFAIL = 2 if X < -1.9E+9
    S17AKF  IFAIL = 1 if X > 1.041E+2
            IFAIL = 2 if X < -1.9E+9
    S17DCF  IFAIL = 2 if abs(Z) < 3.92223E-305
            IFAIL = 4 if abs(Z) or FNU+N-1 > 3.27679E+4
            IFAIL = 5 if abs(Z) or FNU+N-1 > 1.07374E+9
    S17DEF  IFAIL = 2 if AIMAG(Z) > 7.00921E+2
            IFAIL = 3 if abs(Z) or FNU+N-1 > 3.27679E+4
            IFAIL = 4 if abs(Z) or FNU+N-1 > 1.07374E+9
    S17DGF  IFAIL = 3 if abs(Z) > 1.02399E+3
            IFAIL = 4 if abs(Z) > 1.04857E+6
    S17DHF  IFAIL = 3 if abs(Z) > 1.02399E+3
            IFAIL = 4 if abs(Z) > 1.04857E+6
    S17DLF  IFAIL = 2 if abs(Z) < 3.92223E-305
            IFAIL = 4 if abs(Z) or FNU+N-1 > 3.27679E+4
            IFAIL = 5 if abs(Z) or FNU+N-1 > 1.07374E+9
    
    S18ADF  IFAIL = 2 if 0 < X <= 2.23E-308
    S18AEF  IFAIL = 1 if abs(X) > 7.116E+2
    S18AFF  IFAIL = 1 if abs(X) > 7.116E+2
    S18DCF  IFAIL = 2 if abs(Z) < 3.92223E-305
            IFAIL = 4 if abs(Z) or FNU+N-1 > 3.27679E+4
            IFAIL = 5 if abs(Z) or FNU+N-1 > 1.07374E+9
    S18DEF  IFAIL = 2 if REAL(Z) > 7.00921E+2
            IFAIL = 3 if abs(Z) or FNU+N-1 > 3.27679E+4
            IFAIL = 4 if abs(Z) or FNU+N-1 > 1.07374E+9
    
    S19AAF  IFAIL = 1 if abs(X) >= 5.04818E+1
    S19ABF  IFAIL = 1 if abs(X) >= 5.04818E+1
    S19ACF  IFAIL = 1 if X > 9.9726E+2
    S19ADF  IFAIL = 1 if X > 9.9726E+2
    
    S21BCF  IFAIL = 3 if an argument < 1.583E-205
            IFAIL = 4 if an argument >= 3.765E+202
    S21BDF  IFAIL = 3 if an argument < 2.813E-103
            IFAIL = 4 if an argument >= 1.407E+102
    

  4. X01

    The values of the mathematical constants are:
    X01AAF (pi) = 3.1415926535897932
    X01ABF (gamma) = 0.5772156649015328
    

  5. X02

    The values of the machine constants are:

    The basic parameters of the model

    X02BHF   = 2
    X02BJF   = 53
    X02BKF   = -1021
    X02BLF   = 1024
    

    Derived parameters of the floating-point arithmetic

    X02AJF   = 1.11022302462516E-16
    X02AKF   = 2.22507385850721E-308
    X02ALF   = 1.79769313486231E+308
    X02AMF   = 2.22507385850721E-308
    X02ANF   = 2.22507385850721E-308
    

    Parameters of other aspects of the computing environment

    X02AHF   = 1.42724769270596E+45
    X02BBF   = 9223372036854775807
    X02BEF   = 15
    

  6. X04

    The default output units for error and advisory messages for those routines which can produce explicit output are both Fortran Unit 6.

5. Documentation

The Library Manual is available as a separate installation, via download from the NAG website, or from the distribution CD if you have one. It is also available directly on the CD. The most up-to-date version of the documentation is accessible via the NAG website at http://www.nag.co.uk/numeric/FL/FLdocumentation.asp.

The Library Manual is supplied in the following formats:

The following main index files have been provided for these formats:

	nagdoc_fl24\html\FRONTMATTER\manconts.html
	nagdoc_fl24\pdf\FRONTMATTER\manconts.pdf
	nagdoc_fl24\pdf\FRONTMATTER\manconts.html
If the Library Manual has been installed locally, these index files are available from the Start Menu under
  Start|All Programs|NAG|Mark 24 Manual|
      NAG Library Manual Mk24 (HTML5)
  Start|All Programs|NAG|Mark 24 Manual|
      NAG Library Manual Mk24 (PDF)
  Start|All Programs|NAG|Mark 24 Manual|
      NAG Library Manual Mk24 (PDF + HTML Index)
respectively, by default. Use your web browser to navigate from here. For convenience, a master index file containing links to the above files has been provided at
	nagdoc_fl24\index.html

Advice on viewing and navigating the formats available can be found in the Online Documentation document.

The Library Manual is also available as an HTML Help file. In order to display the mathematical expressions correctly, you will need to install Design Science's MathPlayer plug-in. MathPlayer may optionally be installed with this NAG Library product, or may be downloaded from Design Science's website:

  http://www.dessci.com/en/products/mathplayer/download.htm

The HTML Help version of the Library Manual is available from the Start Menu under

  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|NAG Library Manual Mk24 HTML Help
If the NAG Library materials have been installed on a network drive, you may need to copy the HTML Help file (nagdoc_fl24.chm) to a local drive. If you still have trouble seeing the correct help file materials, e.g. if you see a message such as
  Navigation to the webpage was canceled
the file might have been blocked by security updates in Windows or Internet Explorer. Right-click on nagdoc_fl24.chm in Windows Explorer and select Properties from the pop-up menu. If there is an Unblock button at the bottom click on it to unblock the file and then click on OK to close the Properties dialog box.

In addition the following are provided:

The latter is available from the Start Menu under
  Start|All Programs|NAG|FL24|NAG Fortran Library -
      Intel Fortran (FLW6I24DDL)|FLW6I24DDL Users' Note
by default.

6. Support from NAG

(a) Contact with NAG

Queries concerning this document or the implementation generally should be directed to NAG at one of the addresses given in the Appendix. Users subscribing to the support service are encouraged to contact one of the NAG Response Centres (see below).

(b) NAG Response Centres

The NAG Response Centres are available for general enquiries from all users and also for technical queries from sites with an annually licensed product or support service.

The Response Centres are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times.

When contacting a Response Centre, it helps us deal with your enquiry quickly if you can quote your NAG site reference or account number and NAG product code (in this case FLW6I24DDL).

(c) NAG Websites

The NAG websites provide information about implementation availability, descriptions of products, downloadable software, product documentation and technical reports. The NAG websites can be accessed at the following URLs:

http://www.nag.co.uk/, http://www.nag.com/, http://www.nag-j.co.jp/ or http://www.nag-gc.com/

(d) NAG Electronic Newsletter

If you would like to be kept up to date with news from NAG then please register to receive our free electronic newsletter, which will alert you to announcements about new products or product/service enhancements, technical tips, customer stories and NAG's event diary. You can register via one of our websites, or by contacting us at nagnews@nag.co.uk.

(e) Product Registration

To ensure that you receive information on updates and other relevant announcements, please register this product with us. For NAG Library products this may be accomplished by filling in the online registration form at http://www.nag.co.uk/numeric/Library_Registration.asp.

7. User Feedback

Many factors influence the way that NAG's products and services evolve, and your ideas are invaluable in helping us to ensure that we meet your needs. If you would like to contribute to this process, we would be delighted to receive your comments. Please contact any of the NAG Response Centres (shown below).

Appendix - Contact Addresses

NAG Ltd
Wilkinson House
Jordan Hill Road
OXFORD  OX2 8DR                         NAG Ltd Response Centre
United Kingdom                          email: support@nag.co.uk

Tel: +44 (0)1865 511245                 Tel: +44 (0)1865 311744
Fax: +44 (0)1865 310139                 Fax: +44 (0)1865 310139

NAG Inc
801 Warrenville Road
Suite 185
Lisle, IL  60532-4332                   NAG Inc Response Center
USA                                     email: support@nag.com

Tel: +1 630 971 2337                    Tel: +1 630 971 2337
Fax: +1 630 971 2706                    Fax: +1 630 971 2706

Nihon NAG KK
Hatchobori Frontier Building 2F
4-9-9
Hatchobori
Chuo-ku
Tokyo 104-0032                          Nihon NAG Response Centre
Japan                                   email: support@nag-j.co.jp

Tel: +81 3 5542 6311                    Tel: +81 3 5542 6311
Fax: +81 3 5542 6312                    Fax: +81 3 5542 6312

NAG Taiwan Branch Office
5F.-5, No.36, Sec.3
Minsheng E. Rd.
Taipei City 10480                       NAG Taiwan Response Centre
Taiwan                                  email: support@nag-gc.com

Tel: +886 2 25093288                    Tel: +886 2 25093288
Fax: +886 2 25091798                    Fax: +886 2 25091798