This README file explains how to install the IMSL C Numerical Library, and it provides additional important updated product information.
The IMSL C Numerical Library is comprised of the products IMSL C Math Library and IMSL C Stat Library. In this document the IMSL C Math Library and IMSL C Stat Library will be referred to collectively as the IMSL C Numerical Library.
<ROGUEWAVE_DIR>
the base product installation directory<VER>
the version number of the product<ENV>
the environment mnemonic for the installed productDownload the distribution file from the Rogue Wave Customer Support portal. Be sure to download the distribution that matches your platform. The file name will specify the product code, version number, platform mnemonic, and installation type.
cnl-<VER>-<ENV>.run
for users with a valid license keycnl-<VER>-<ENV>_eval.run
for evaluation userscnl-<VER>-<ENV>_src.run
to compile from source codecnl-<VER>-<ENV>.exe
for users with a valid license keycnl-<VER>-<ENV>_eval.exe
for evaluation userscnl-<VER>-<ENV>_src.exe
to compile from source codeInstallation Steps:
Start the installer and follow the prompts to install the product files.
Users of cnl-<VER>-<ENV>_src.run
or cnl-<VER>-<ENV>_src.exe
installers follow instructions to compile source code at the end of this document here before continuing with the installation process.
Set up the IMSL C Numerical Library Environment by executing the following commands:
source <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/cnlsetup.csh
. <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/cnlsetup.sh
cd <ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\bin\
cnlsetup.bat
NOTE: Environment variables set by cnlsetup.bat
, cnlsetup.sh
, or cnlsetup.csh
are only available for the duration of the current command prompt or shell session. They are lost once the session is ended.
Set Up License (Evaluation, Student and Subscription Users Only)
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.Validate the Installation:
%CNL_EXAMPLES%\validate
$CNL_EXAMPLES/validate
After installation, reference additional sections of the README included below for information on configuring and using the IMSL C Numerical Library.
Access IMSL C Numerical Library documentation in <ROGUEWAVE_DIR>/imsl/cnl-<VER>/help/imsl.html
or online. On Windows platforms a Start menu item is present if installation of documentation is selected during installation.
Linux
Before using the IMSL C Numerical Library you must define certain environment variables. After product installation is completed, the files cnlsetup.csh
(for C shell users) and cnlsetup.sh
(for Bourne and Korn shell users) are created in the <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin
directory
C shell users should enter the following command:
source <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/cnlsetup.csh
Bourne and Korn shell users should enter the following command:
. <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/cnlsetup.sh
The cnlsetup.csh
and cnlsetup.sh
files set many environment variables and shell aliases/functions.
Windows
The installation procedure creates the file cnlsetup.bat
in the <ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\bin
directory which makes working from the command prompt a simpler task.
Environment variables set by cnlsetup.bat
are only available for the duration of the current command prompt session. They are lost once the command prompt session is ended.
To run cnlsetup.bat
, type this command in the C command prompt window:
<ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\bin\cnlsetup.bat
where <ROGUEWAVE_DIR>
is the top level directory in which you have installed IMSL C Numerical Library and <ENV>
is the environment mnemonic of the product you installed.
List of Environmental Variables
The cnlsetup.csh
(Linux), cnlsetup.sh
(Linux), and cnlsetup.bat
(Windows) files set many environment variables and shell aliases/functions. The following is a list of what is useful to the IMSL C Numerical Library user. Several other variables are set that are used internally by the IMSL C Numerical Library.
CC
: C compiler.
CFLAGS
: C Compiler Options.
CNL_VERSION
: The IMSL C Numerical Library version number.
CNL_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).
CNL_EXAMPLES
: The directory which contains the example programs.
CNL_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).
IMSLERRPATH
: The pathname to the IMSL C Math Library error file (imslerr.bin). The pathname must be terminated by a path separator, i.e., /
on Linux or \
on Windows.
IMSLSERRPATH
: The pathname to the IMSL C Stat Library error file (imsls_e.bin). The pathname must be terminated by a path separator, i.e., /
on Linux or \
on Windows.
LINK_CNL_SHARED
: Link options required to link with the shared libraries version of the IMSL C Numerical Library. For most installations this option links with the supported vendor BLAS and LAPACK libraries. If the installer chose to not install the vendor library enhanced version of IMSL C Numerical Library this environment variable will be set to LINK_CNL_SHARED_IMSL
(see below). See "Performance Enhancements" for additional information.
LINK_CNL_STATIC
: Link options required to link with the static libraries version of the IMSL C Numerical Library. For most installations this option links with the supported vendor BLAS and LAPACK libraries. If the installer chose to not install the vendor library enhanced version of IMSL C Numerical Library this environment variable will be set to LINK_CNL_STATIC_IMSL
(see below). See "Performance Enhancements" for additional information.
LINK_CNL_SHARED_IMSL
: Link options required to link with the shared libraries version of the IMSL C Numerical Library. This option does not use any externally supplied software.
LINK_CNL_STATIC_IMSL
: Link options required to link with the static libraries version of the IMSL C Numerical Library. This option does not use any externally supplied software.
LINK_CNL
: By default, set to LINK_CNL_SHARED
.
LINK_CNL_IMSL
: By default, set to LINK_CNL_SHARED_IMSL
.
CNL_LICENSE_NUMBER
: Contains your license number.
Note: The CFLAGS variable does not include any optimization or debugging compiler options.
Use of the environment variables set via the cnlsetup.csh
and cnlsetup.sh
(Linux) or cnlsetup.bat
(Windows) files is recommended to ease the creation of IMSL C Numerical Library applications. Use the supported C compiler with the desired link options to create the program.
The following command will compile and link an application program:
Linux
$CC -o <executable> $CFLAGS <main> $LINK_CNL
Windows
%CC% <main> %LINK_CNL%
In the above command, LINK_CNL can easily be replaced by any of the LINK_CNL* variables. Refer to "Environment Variables" for a list of the available LINK_CNL* options.
Optional Third-Party Software
Performance increases can be realized by taking advantage of vendor supplied BLAS, FFT and LAPACK functions. Intel (R) Math Kernel Library is included with Windows distributions and Linux distributions designed for use with GCC compiler for this purpose. Intel (R) Math Kernel Library is bundled with the Intel(R) C compiler, and is therefore not included with IMSL C Numerical Library distributions designed for use with the Intel(R) C compiler. For Windows, the Intel threading model of MKL is used within the MKL Library. On Linux, the GNU threading model of MKL is used within the MKL Library.
Note that MKL is not covered by the IMSL License Agreement. Go to www.intel.com to obtain more information on Intel's MKL License Agreement.
You can still link with the IMSL versions of these functions by using the following environment variables when linking your application:
LINK_CNL_SHARED_IMSL
(to link with the shared library)
LINK_CNL_STATIC_IMSL
(to link with the static library)
Basic Linear Algebra Subprograms (BLAS)
The BLAS are high quality "building block" routines for performing basic vector and matrix operations. Level 1 BLAS do vector-vector operations, Level 2 BLAS do matrix-vector operations, and Level 3 BLAS do matrix-matrix operations. Because the BLAS are efficient, portable, and widely available, they are commonly used in the development of high quality linear algebra software.
Linear Algebra PACKage (LAPACK)
LAPACK provides routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems. The associated matrix factorizations (LU, Cholesky, QR, SVD, Schur, generalized Schur) are also provided, as are related computations such as reordering of the Schur factorizations and estimating condition numbers.
Fast Fourier Transforms (FFT)
Rogue Wave Software has incorporated the use of some specific third-party FFTs with the IMSL C Numerical Library.
Parallelism in the IMSL C Numerical Library
The IMSL C Numerical Library employs both fine-grain and coarse-grain parallelism to take advantage of multiple CPUs.
Fine Grain
Fine-grain parallelism occurs within a function and is limited to shared-memory(SMP) systems, i.e. one system with multiple CPUs. This parallelism is done at the for loop level.
Fine-grain parallelism is utilized by the IMSL C Numerical Library in one of two ways:
Using BLAS and FFTs within vendor supplied high-performance libraries. These codes are marked in the documentation by a High Performance Computing icon. Consult the vendor library documentation for specifics about the vendor's implementation of parallelism.
Using OpenMP parallelization pragmas within the IMSL C Numerical Library code. These codes are marked in the documentation by an OpenMP icon.
Default configuration for SMP support with MKL installed:
Note: OpenMP and High Performance refer to icons in the IMSL C Numerical Library User's Guide. The OpenMP icon implies that OpenMP directives are used within the function. The High Performance icon implies that vendor supplied BLAS, FFTs, and/or LAPACK functions are used with the function.
OpenMP | High Performance | |
---|---|---|
LINK_CNL_SHARED | yes | yes |
LINK_CNL_STATIC | yes | yes |
LINK_CNL_SHARED_IMSL | yes | no |
LINK_CNL_STATIC_IMSL | yes | no |
Coarse Grain
Coarse-grain parallelism occurs at the function level to parallelize the evaluation of user-supplied functions in routines that use them, e.g. in numerical integration routines. When the user asserts that a user supplied function is appropriately thread-safe (using one of the functions imsl_omp_options or imsls_omp_options), the supplied functions are called in parallel. The coarse-grain parallelism implemented in the IMSL C Numerical Library is limited to a single system with multiple CPUs. These codes are marked in the documentation by an OpenMP icon.
Refer to the IMSL C Numerical Library User Guide for more information on omp_options and OpenMP Usage (Introduction).
To utilize multiple CPUs the OMP_NUM_THREADS environment variable is used to specify the number of CPUs which are to be used during execution. To set this environment variable use the following command:
SET OMP_NUM_THREADS=<n>
where <n>
is the number of CPUs to be used.
If you do not set OMP_NUM_THREADS, the number of threads used is determined by the system. To avoid an excess number of threads from being created the OMP_NESTED environment variable is set to FALSE if it has not already been set by the user. On platforms using Intel MKL 2020 or newer, this variable has been deprecated. On these platforms, the OMP_MAX_ACTIVE_LEVELS environment variable is set to 1 if not set by the user.
IMSL Codes Taking Advantage of LAPACK
Many of the codes in the IMSL C Numerical Library are based on LINPACK, Dongarra et al. (1979), and EISPACK, Smith et al. (1976), collections of subroutines designed in the 1970s and early 1980s. LAPACK, Anderson et al. (1999), was designed to make the linear solvers and eigensystem routines run more efficiently on high-performance computers. For a number of IMSL routines, the user of the IMSL C Numerical Library has the option of linking to code which is based on either the legacy routines or the more efficient LAPACK routines.
The table below lists the IMSL functions that make use of LAPACK codes. The intent is to obtain improved performance for IMSL codes by using LAPACK codes that have good performance by virtue of using BLAS with good performance. To obtain improved performance we recommend linking with High Performance versions of LAPACK and BLAS, if available. The names of the LAPACK codes used are listed opposite the names of the IMSL functions which use them.
Single Precision Name of IMSL Function | LAPACK Routines used when Linking with High Performance Libraries |
---|---|
imsl_c_eig_herm | ?heevx_, ?=c/z |
imsl_c_geneig | ?ggev_, ?=c/z |
imsl_c_lin_sol_gen | ?getrs_, ?getrf_, ?gecon_, ?getri_, ?=c/z |
imsl_c_lin_sol_gen_band | ?gbcon_, ?gbtrf_, ?gbtrs_, ?=c/z |
imsl_c_lin_sol_posdef | ?potri_, ?potrf_, ?pocon_, ?potrs_, ?=c/z |
imsl_c_lin_sol_posdef_band | ?pbcon_, ?pbtrf_, ?pbtrs_, ?=c/z |
imsl_c_lin_svd_gen | ?gesvd_, ?gesdd_, ?=c/z |
imsl_f_bounded_least_squares | ?ormqr_, ?=s/d |
imsl_f_eig_gen | ?geevx_, ?=s/d |
imsl_f_eig_sym | ?syevx_, ?=s/d |
imsls_f_eig_sym | ?syevx_, ?=s/d |
imsl_f_eig_symgen | ?sygv_, ?=s/d |
imsls_f_factor_analysis | ?syevx_, ?=s/d |
imsl_f_geneig | ?ggev_, ?=s/d |
imsl_f_lin_least_squares_gen | ?orgqr_, ?geqrf_, ?geqp3_,?ormqr_, ?trsm_, ?=s/d |
imsl_f_lin_sol_gen | ?getrs_, ?getrf_, ?gecon_, ?getri_, ?=s/d |
imsl_f_lin_sol_gen_band | ?gbcon_, ?gbtrf_, ?gbtrs_, ?=s/d |
imsl_f_lin_sol_posdef | ?pocon_, ?potrf_, ?potri_, ?=s/d |
imsl_f_lin_svd_gen | ?gesvd_, ?gesdd_, ?=s/d |
imsl_f_nonlin_least_squares | ?ormqr_, ?=s/d |
imsl_f_pde_1d_mg_mgr | ?gbtrf_, ?=s/d |
imsls_f_hw_time_series | ?ormqr_, ?=s/d |
imsls_f_logistic_regression | ?pocon_, ?potrf_, ?potri_, ?=s/d |
imsls_f_logistic_reg_predict | ?pocon_, ?potrf_, ?potri_, ?=s/d |
References
Anderson et al.
Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, (1999), LAPACK Users Guide, Third Edition, SIAM, Philadelphia.
Users of cnl-<VER>-<ENV>_src.run
or cnl-<VER>-<ENV>_src.exe
installers only, follow these instructions to compile source code
Linux Compilation Instructions
After logging into the same username used to install the product, enter the following commands to compile the source code:
<ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/cmath_source
src_install
cd <ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/cstat_source
src_install
The output is directed to the file src_install.output in each of the directories specified above.
Windows Compilation Instructions
Enter the following commands in a Visual Studio Command Prompt Window to compile the source code:
cd <ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\cmath_source
src_install.bat
cd <ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\cstat_source
src_install.bat
The output is directed to the file src_install.output in each of the directories specified above.
For some environments, the high-performance version of the IMSL C Numerical Library is not built by default. To build the high performance version of the IMSL C Numerical Library you must do the following:
1. Obtain your own copy of the vendor's high-performance library and associated files. The library and version number should match the supported version documented in the Platforms document.
2. Modify files
Linux
- Modify the files
<ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/cstat_source/src_install.<ENV>
and
<ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/cmath_source/src_install.<ENV>
as follows:
- Initialize HPC_BUILD
to "true"
- Set <PROD>_DIR
to the location of high performance library installation. Here <PROD>
is a mnemonic representing the name of the supported high-performance library, for example MKL_DIR. In some cases, it may not be clear where the environment variable <PROD>_DIR
should point. Refer to the script to verify the directory to which <PROD>_DIR
should point.
- Modify the files
<ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/<ENV>.csh
and
<ROGUEWAVE_DIR>/imsl/cnl-<VER>/<ENV>/bin/<ENV>.sh
as follows:
- Set <PROD>_DIR
to the location of high performance product libraries.
Windows
- Modify the files
<ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\cstat_source\src_install_<ENV>.bat
and
<ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\cmath_source\src_install_<ENV>.bat
as follows:
- Set <PROD>_DIR
to the location of high performance library installation. Here <PROD>
is a mnemonic representing the name of the supported high-performance library, for example MKL_DIR. In some cases, it may not be clear where the environment variable <PROD>_DIR
should point. Refer to the script to verify the directory to which <PROD>_DIR
should point.
- Modify the file
<ROGUEWAVE_DIR>\imsl\cnl-<VER>\<ENV>\bin\<ENV>.bat
as follows:
- Set <PROD>_DIR
to the location of high performance product libraries. Here <PROD>
is a mnemonic representing the name of high-performance library (for example MKL_DIR).
- Note, <PROD>_DIR\<LIB>
, the fully qualified path to the <LIB>
files, should be added to the LIB environment variable if they are to be used in an integrated development environment (e.g. Microsoft Visual Studio).
- Note, <PROD>_DIR\<BIN>
, the fully qualified path to the binary files, should be added to the PATH environment variable if they are to be used in an integrated development environment (e.g. Microsoft Visual Studio).