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.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 douse 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 donumerical_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