This README file explains how to install, configure, and use the IMSL Fortran Numerical Library, and it provides additional important updated product information.
<ROGUEWAVE_DIR> the base product installation directory<VER> the version number of the product<ENV> the environment mnemonic for the installed productfnl-<VER>-<ENV>.run for users that purchased a perpetual license for the productfnl-<VER>-<ENV>_eval.run for evaluation, student and subscription usersfnl-<VER>-<ENV>.exe for users that purchased a perpetual license for the productfnl-<VER>-<ENV>_le.exe for Limited Edition usersfnl-<VER>-<ENV>_eval.exe for evaluation, student and subscription userssource <ROGUEWAVE_DIR>/imsl/fnl-<VER>/<ENV>/bin/fnlsetup.csh. <ROGUEWAVE_DIR>/imsl/fnl-<VER>/<ENV>/bin/fnlsetup.shcd <ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\bin\fnlsetup.batfnlsetup.bat are only available for the duration of the current command prompt session. They are lost once the command prompt session is ended.imsl_eval.dat (obtained via email from the Rogue Wave License Administrator) into the <ROGUEWAVE_DIR>/license/ directory.IMSL_LIC_FILE environment variable to the fully qualified path and filename of the license file.set IMSL_LICENSE_POPUP=1.imsl_eval.dat (obtained via email from the Rogue Wave License Administrator) into the <ROGUEWAVE_DIR>/license/ directory.IMSL_LIC_FILE environment variable to the fully qualified path and filename of the license file.set IMSL_LICENSE_POPUP=1.cd $FNL_EXAMPLES/validatecd %FNL_EXAMPLES%\validate<ROGUEWAVE_DIR>/imsl/fnl-<VER>/help/imsl.html or [online at] (https://help.imsl.com/fortran)The fnlsetup.csh (Linux), fnlsetup.sh (Linux), and fnlsetup.bat (Windows) files set many environment variables and shell aliases/functions. The following is a list of what is useful to the Fortran Numerical Library user. Several other variables are set that are used internally by the Fortran Numerical Library.
F90: Fortran 90 compiler.FC: Fortran compiler.F90FLAGS: Compiler options used to compile free-format Fortran source files.FFLAGS: Compiler options used to compile fixed-format Fortran source files. For environments which identify fixed-format and free-format Fortran source files by the filename extensions .f and .f90, $FFLAGS and $F90FLAGS will be identical. For those which do not, $FFLAGS and $F90FLAGS will be different.FNL_VERSION: The Fortran Numerical Library version number.FNL_COMPILER_VERSION: The compiler that the object libraries were compiled under. (An exception would be if you installed from source code and you did not update this environment variable).FNL_EXAMPLES: The directory which contains the example programs.FNL_OS_VERSION: The operating system that the object libraries were compiled under. (An exception would be if you installed from source code and you did not update this environment variable).LINK_FNL_SHARED: See Link OptionsLINK_FNL_STATIC: See Link OptionsLINK_FNL_SHARED_IMSL: See Link OptionsLINK_FNL_STATIC_IMSL: See Link OptionsLINK_FNL: See Link OptionsLINK_FNL_IMSL: See Link OptionsLINK_MPI: See Link OptionsLINK_MPI_IMSL: See Link OptionsLINK_MPIS: See Link OptionsLINK_MPIS_IMSL: See Link OptionsMPIF90: Command to compile applications which use MPI.MPIRUN: Command to run applications which use MPI.The FFLAGS and F90FLAGS variables do not include any optimization or debugging options.
It is recommended that the setup procedure(s) be executed automatically each time you login rather than doing it interactively. This is especially important if you intend to take advantage of MPI. MPI spawns processes when multiple CPUs are specified. Having the appropriate setup procedures executed automatically at login is the only way to ensure that the environment variables required by the spawned processes are set. This can be done in Linux by adding the commands (source and .) to the .cshrc (for C shell) or .profile (for sh).
To ease the creation of IMSL Libraries applications, rely on the environment variables set during installation steps:
fnlsetup.csh or fnlsetup.shfnlsetup.bat or by the installer using the Windows registryUsing any supported Fortran compiler with the desired Link Options to create the program, use the following command to compile and link an application:
$F90 -o <executable> $FFLAGS <main> $LINK_FNL%F90% %F90FLAGS% <main> %LINK_FNL%LINK_FNL can be replaced by any of the LINK_FNL* variables defined in Link Options. This is commonly used to take advantage of multiple-cpus.
Numerous options are available to the IMSL Fortran Numerical Library when building an application. To clarify which option meets your requirements each LINK option will be described in detail below.
LINK_FNL_SHARED:
LINK option will leverage the use of third-party high performance library(s) which contain the BLAS and LAPACK (see Optional Third-Party Software). The LAPACK software makes use of alternative algorithms while the BLAS are typically multi-threaded. Use of this option to link your application will usually result in increased performance especially when computer systems with multiple CPUs are being used.LINK_FNL_STATIC:
LINK_FNL_SHARED except that static libraries are used when linking.LINK_FNL: This environment variable is identical to LINK_FNL_SHARED.LINK_FNL_SHARED_IMSL:
LINK option does not rely on third-party vendor software. All software is supplied with the IMSL Fortran Numerical Library. This option links with the shared library version of the IMSL Fortran Numerical Library software.LINK_FNL_STATIC_IMSL:
LINK_FNL_SHARED_IMSL except that static libraries are used when linking.LINK_FNL_IMSL:
LINK_FNL_SHARED_IMSL.LINK_MPI_IMSL:
LINK_MPI:
LINK option has all the advantages associated with LINK_MPI_IMSL but with the added advantages leveraging the use of ScaLAPACK, BLACS, BLAS, and LAPACK.LINK_MPIS_IMSL:
LINK option allows one to use MPI in their application but not necessarily the MPI-enabled versions of the IMSL Fortran Numerical Library routines. One must be careful when using this option because the MPI-enabled code will be linked when needed and the IMSL error handler designed for use with MPI will not be used.LINK_MPIS:
LINK_MPIS_IMSL but with the added advantages leveraging the use of ScaLAPACK, BLACS, BLAS, and LAPACK.Separate subdirectories are included for each installed architecture. The environment variable FNL_EXAMPLES is defined during the setup procedure. This environment variable identifies the directory where the examples associated with your environment are located. To change to the appropriate directory enter:
cd $FNL_EXAMPLEScd %FNL_EXAMPLES%The examples directory will contain the following subdirectories:
eiat: Contains the Environment and Installation Assurance Test. The Environment and Installation Assurance Test is a set of FORTRAN subprograms designed to verify the proper installation and functioning of the IMSL Libraries in a specific computer/compiler environment. It is recommended that these tests be run if you are running in an unsupported computer/compiler environment. Refer to the README file located in the eiat directory for details on how to run these tests.manual: Contains selected native Fortran 90 examples documented in the IMSL Fortran Numerical Library User's Guide. It is recommended that these examples be run if you are running in an unsupported computer/compiler environment. These examples are also useful as templates for writing your own applications. Refer to the README file located in the manual directory for details on how to run these examples.mpi_manual: Contains the MPI examples documented in the IMSL Fortran Numerical Library User's Guide. These examples make use of the subroutines which can take advantage of MPI. An MPI library is required to run these examples. It is recommended that these examples be run if you are running in an unsupported computer/compiler environment. These examples are also useful as templates for writing your own applications. Refer to the README file located in the mpi_manual directory for details on how to run these examples.mpi_scalapack: Contains the examples documented in the IMSL Fortran Numerical Library User's Guide which demonstrate the use of ScaLAPACK. Running these examples requires MPI, ScaLAPACK and vendor supplied BLAS. See "Performance Enhancements" for more information. It is recommended that these examples be run if you are running in an unsupported computer/compiler environment. These examples are also useful as templates for writing your own applications. Refer to the README file located in the mpi_scalapack directory for details on how to run these examples.IMSL Fortran Numerical Library may utilize optional product components not provided by Rogue Wave Software. These product components are summarized below.
The IMSL Fortran Numerical Library employs both fine-grain parallelism and coarse-grain parallelism to take advantage of multiple CPUs. Both forms of parallelism are made to be transparent to the user other than setting up the system environment. No additional effort is required by the user.
Because of the overhead required by the system to spawn threads, it is not always advantageous to use SMP capabilities. In some cases where the amount of work that can be done in parallel is small when compared to the overhead, the application can actually take a performance hit due to the overhead for parallelism. If performance is a concern, benchmarking of the application should be done using different LINK options.
Once your application is linked, set the environment variable OMP_NUM_THREADS to the number of CPUs you want your application to use.
Throughout this process, <ROGUEWAVE_DIR> denotes the main IMSL installation directory. By default, this is set to C:\Program Files (x86)\RogueWave\ but may be different if you installed IMSL in a different directory.
The directory <ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\lib must be present in the environment variable PATH prior to starting Microsoft Visual Studio. This can be verified in: Control Panel -> System and Security -> System -> Advanced system settings -> Environment Variables.
<ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\bin and run the setup script fnlsetup.batdevenv.imslmp.f90 from <ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\examples\validate/F60000000<ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\include\dll to the "Additional Include Directories" list.<ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\lib to the "Additional Library Directories" list.<Roguewave_dir>\imsl\fnl-<ver>\<env>\lib to the "Additional Library Directories" list.imsl_dll.lib to the "Additional Dependencies" list.Some IMSL Fortran Numerical Library error messages are stored in an error message file. For most applications of this product, there will be no need to modify this file. There are some situations in which there may be cause to change or add messages (e.g. internationalization, adding application level error handling):
<ROGUEWAVE_DIR>/imsl/fnl-<VER>/<ENV>/bin directory (<ROGUEWAVE_DIR>\imsl\fnl-<VER>\<ENV>\bin on Windows). This directory includes:
messages.gls.messages.daf. This is the file which is actually referenced by the IMSL Fortran Numerical Library product.prepmess, which builds the error message file messages.daf from messages.gls.prepmess.f, used to build prepmess.messages.gls. Prior to changing this file, back it up in case it is necessary to restore it at a later time.
message_number=<nnnn> (where <nnnn> is an integer message number)message='message string' (where 'message string' is any valid message string not to exceed 255 characters)// or with the line continuation character &.%(i<n>) for an integer substitution, n indicating the nth integer number output in the message.%(r<n>) for a single precision real number substitution, n indicating the nth single precision number output in the message.%(d<n>) for a double precision real number substitution, n indicating the nth double precision number output in the message.messages.daf.messages.gls file, you can then generate the new error file, messages.daf, using the supplied executable program prepmessby entering prepmess > prepmess_output.Prepmess will check the validity of each error message within messages.gls. There should be no FATAL error messages within the file prepmess_output.error_post subprogram in your application using the new_unit and new_path optional arguments as described in the IMSL Fortran Numerical Library User's Guide. The new path should point to the directory where messages.daf resides.DLLEXPORT compiler directive to export user accessible variables in the interface modules. As a result, IMSL provides two versions of module files in the include directory. The dll sub-directory contains the module files for the DLL library while the static sub-directory contains the module files for the static library.
FFLAGS and F90FLAGS, to use module files for the DLL version of the IMSL Fortran Library. While this works for both the DLL and static versions of the IMSL Fortran Library, the compiler may give warning messages during linking when using the IMSL static library. If the warning messages are an annoyance, the user can change the environment variables, FFLAGS and F90FLAGS, to use the module files in either the STATIC or DLL sub-directory depending on whether they are linking with the static or dll version of the IMSL library. Care must be taken not to use the module files in the STATIC sub-directory with the DLL version of the IMSL library or a program crash may result.LINK_*_SHARED_* environment variables) and use the module files for static library when linking with the static library (for LINK_*_STATIC_* environment variables). Otherwise, your program may crash during execution.THREADPRIVATE in the interface module. A THREADPRIVATE variable cannot be declared using the !dec$attributes dllexport directive at the same time in building a DLL library. Therefore, the following example may occasionally produce wrong results.
use operation_ix
!$omp parallel do
do i=1,1000
! d_invx_options is declared as ALLOCATABLE and THREADPRIVATE in
! OPERATION_IX interface module
allocate (d_invx_options(1))
...
! use operation_ix
...
deallocate (d_invx_options)
end do
use operation_ix
!$omp parallel do
do i=1,1000
! d_invx_options is declared as ALLOCATABLE and THREADPRIVATE in
! OPERATION_IX interface module
!$omp critical
allocate (d_invx_options(1))
...
! use operation_ix
...
deallocate (d_invx_options)
!$omp end critical
end do
numerical_libraries.f90 and numerical_libraries_f90.f90, are copied to the include directory during installation. These files contain source code for the interface modules. They can be used to determine calling sequences.fnlsetup.bat), the user can enter %F90% %F90FLAGS% <main> %LINK_FNL%.LINK_FNL. Header files provide an alternative method of specifying which libraries an application uses. To use the header files, use include 'link_fnl_shared.h' in the main program. Then, enter %F90% %F90FLAGS% <main> to compile and link a program.LINK_FNL environment variable has a corresponding header file with the same filename. The header files are:
link_fnl_shared.hlink_fnl_shared_imsl.hlink_fnl_static.hlink_fnl_static_imsl.hlink_mpi.hlink_mpis.hlink_mpis_imsl.hlink_mpi_imsl.h