Getting started with the NAG Library

Trial Process GraphicNAG Library algorithms are inherently flexible – they can be called from many languages, including C and C++, VBA, Python, Java, .NET and Fortran.

Follow the steps below to get started with the NAG Library including downloads for your chosen configuration, how to obtain a trial licence, product-specific documentation, and accessing technical support.

If you have any questions, contact us using the on-page chat facility or via the Technical Support Service.

To find and download your version of the NAG Library, select your programming language or environment, and operating system below.


C/C++ NAG CPP Fortran Python MATLAB® Java
 

The NAG Library provides ISO C standard API so can be used from C and C++. If you are using C++ you might be interested in the NAG CPP Interface which is a subset of C++ interfaces for the NAG® Library. If you aim to interface the Library from any other language we highly recommend using the Fortran Interface which also provides ISO C standard API but its simpler interface is often easier to work with.

The NAG Library provides a standard set of interfaces that utilise only simple types, making them suitable for calling from a wide range of languages, including Fortran, C, C++, VBA, .NET and others. These interfaces include NAG's traditional Fortran Library interfaces.

The NAG CPP Interface is a set of C++ interfaces for the NAG® Library supplied as a series of header files. Currently, only interfaces for a small subset of routines from the NAG® Library are available in this form. These interfaces are automatically generated, and their primary purpose is to elicit feedback on their design before rolling the process out across the whole Library.

The licence-managed package is served from a NAG-hosted repository. Hence by using pip to install the software as documented below, the latest version of the appropriate package for the system you are running pip on is downloaded and installed in one combined operation.

Add further mathematical and statistical functionality to your applications with the NAG Toolbox for MATLAB.

The world's largest collection of robust, documented, tested and maintained numerical algorithms for users of the Java programming language.

Windows Linux Mac
 

The following system setup is expected

System: Windows 64-bit
Compilers: Intel C++ 64-bit v.2021.4.0 or compatible
or Microsoft 64-bit C/C++ v.19.10 or compatible
Using Visual Studio 2019 or compatible

System: Windows 64-bit
Compilers: Intel Fortran v.2021.4.0 or compatible
Using Visual Studio 2019 or compatible

For details of other system setups for the Win64 version, see Supplementary Information.

or

System: Windows 32-bit
Compilers: Intel C 32-bit v.2021.4.0 or compatible
or Microsoft 32-bit C/C++ v.19.27 or compatible
Using Visual Studio 2019 or compatible

or

System: Windows 32-bit
Compilers: Intel Fortran v.2021.4.0 or compatible
Using Visual Studio 2019 or compatible

For details of other system setups for the Win32 version, see Supplementary Information.

System: Windows 64-bit
MATLAB: version 8.5 (R2015a) or later

System: Windows 64-bit
Java: version 7 or later

The following system setup is expected

System: glibc 2.17 or compatible (implemented on Fedora 24)
Compilers: Intel C++ v.2021.4.0 or compatible
or GNU C (gcc) v.7.3 or compatible
ABI: C++11

System: glibc 2.17 or compatible (implemented on Fedora 24)
Compilers: Intel Fortran v.2021.4.0 or compatible

For details of other system setups for Linux C++11 ABI version, see Supplementary Information.

or

System: glibc 2.17 or compatible (implemented on Centos 7)
Compilers: Intel C++ v.2021.4.0 or compatible
or GNU C (gcc) v.7.3 or compatible
ABI: C++98

or

System: glibc 2.17 or compatible (implemented on Centos 7)
Compilers: Intel Fortran v.2021.4.0 or compatible

For details of other system setups for Linux C++98 ABI version, see Supplementary Information.

System: Linux 64-bit
MATLAB: version 8.5.1 (R2015a SP1) or later

System: glibc 2.17 or compatible (implemented on Fedora 24)
Java: version 7 or later

The following system setup is expected

System: macOS 10.13 or compatible
Compilers: Intel C++ 64-bit v.19.0.3 or compatible
or Apple LLVM (clang) v9.0 (GCC equivalent) or compatible

System: macOS 10.13 or compatible
Compilers: Intel Fortran v.19.0.3 or compatible

For details of other system setups for the Intel compiler version, see Supplementary Information.

or

System: macOS 10.14 or compatible
Compilers: GNU gcc v.8.3 or compatible

or

System: macOS 10.14 or compatible
Compilers: GNU gfortran v.8.3 or compatible

For details of other system setups for the GNU compiler version, see Supplementary Information.

System: Apple Intel Mac 64-bit
MATLAB: version 8.5 (R2015a) or later

Dependencies

A valid licence for this product
64-bit Python, 3.7 or later
NumPy 1.15 or newer

The full range of NAG Library implementations can be viewed here.


Download the Software

Given your selection, your NAG Library download is:

the Win64 version Download Download or the Win32 version Download

the Linux C++11 ABI version Download Download or, for older systems, Linux C++98 ABI version Download

the macOS version for use with either the Intel C++ compiler Intel Fortran compiler Download or the GNU gcc compiler GNU gfortran compiler Download

Given your selection, your download is the NAG Toolbox for MATLAB® for Windows Download. Linux Download. macOS Download

Install the Software

After download, run the self-extracting executable (e.g. nlw6i293el_setup.exe) (nlw6i293el_setup.exe) to start the NAG Library installation.

A typical installation will be straightforward (follow the prompts on the Windows setup Wizard and press Next) or see the Installer's Note Installer's Note which explains all aspects of setting up the product.

The NAG Library materials are downloaded from our website as a tar gzip file (nll6i293bl.tgz) (nll6i293bl.tgz); cd to the directory where the file is located and extract the installation materials using the following command:

tar xvzf nll6i293bl.tgz
tar xvzf nll6i293bl.tgz

This will extract the files install.sh, nl29.tgz, nag_tsandcs.txt, in.html and un.html and the directory styles. Then run

./install.sh

By default, the materials will be installed under $HOME/NAG/, or if the directory $HOME does not exist, under /opt/NAG/. However, you may choose a different location.

The NAG Library materials are downloaded from our website as a Disk Image file (nlmi627dbl.dmg); double click on the file to mount the disk image.

Double click on INSTALL.command in Finder and follow the instructions. By default, the materials will be installed under $HOME/NAG/, or if the directory $HOME does not exist, under /opt/NAG/. However, you may choose a different location.

MATLAB must be installed first.

After download, run the self-extracting executable (e.g. mbw6i25ddl_setup.exe) to start the NAG Toolbox installation.

A typical installation will be straightforward (follow the prompts on the Windows setup Wizard and press Next) or see the Installer's Note which explains all aspects of setting up the product.

The NAG Toolbox for MATLAB materials are downloaded from our website as a tar gzip file (mbl6i25dnl.tgz); cd to the directory where the file is located and extract the installation materials and run the installer using the following commands:

mkdir nagtmp
cd nagtmp
tar -xzf ../mbl6i25dnl.tgz
sh INSTALL

By default, the materials will be installed under /opt/NAG/ or, if the directory /opt does not exist, under /usr/local/NAG. However, you may choose a different location.

A typical installation will be straightforward (follow the prompts from the installer) or see the Installer's Note which explains all aspects of setting up the product.

The NAG Library materials are downloaded from our website as a Disk Image file (mbmi625dcl.dmg); double click on the file to mount the disk image.

Double click on INSTALL.command in Finder and follow the instructions. By default, the materials will be installed under $HOME/NAG/, or if the directory $HOME does not exist, under /opt/NAG/. However, you may choose a different location.

Download and Install the Software

Downloading and installing the NAG Library is done using the pip package manager.

Open a Command Prompt window and create a Python virtual environment in which to install and test the NAG Library

python -m venv nag3
.\nag3\Scripts\activate

Open a terminal with Bash and create a Python 3 virtual environment in which to install and test the NAG Library

python3 -m venv nag3
. nag3/bin/activate

Now use pip to install the NAG Library for Python

python -m pip install --extra-index-url https://www.nag.com/downloads/py/naginterfaces_nag naginterfaces

or if you prefer the version of the package that relies on Intel MKL for optimized linear algebra routines, then use

python -m pip install --extra-index-url https://www.nag.com/downloads/py/naginterfaces_mkl naginterfaces

Obtain a Licence - Including a Trial Licence

After downloading your NAG Library version, simply complete the linked form below that corresponds with your download to receive your trial licence direct to your inbox.

Complete either the Win64 version trial licence key form trial licence key form trial licence key form trial licence key form Linux C++11 ABI version trial licence key form trial licence key form trial licence key form trial licence key form macOS version for use with the Intel compiler trial licence key form trial licence key form or the Win32 version trial licence key form trial licence key form Linux C++98 ABI version trial licence key form trial licence key form GNU compiler trial licence key form trial licence key form

Alternatively, request a trial licence key via the Kusari Licence Installer, accessible at the end of the software installation procedure. Click 'Request New Licence'. Complete the form and select 'Generate Licence Request'. Paste the generated information into your email client and send it to the NAG address given at the top of the generated information. Note your key is not sent automatically via this route.

After downloading your NAG Library version, simply complete this form this form this form this form this form this form to request a trial licence.

Alternatively, request a trial licence via the Kusari Licence Installer, accessible at the end of the software installation procedure. Click 'Request New Licence'. Complete the form and select 'Generate Licence Request'. Paste the generated information into your email client and send it to the NAG address given at the top of the generated information. Note your key is not sent automatically via this route

Install the Licence

You will receive your requested trial licence key by email containing one or more lines like the following:

<PRODUCT_CODE> TRIAL <EXPIRY_DATE> "EMnxidA3oeoj0F1Yvi5ibxPjB7"

Once you have obtained the above licence key, the Kusari Licence Installer can be used to install the key in the Windows Registry. Open the installer via the Start Menu or All apps shortcut NAG NLW6I293EL Licence, Request or Install. Paste the key into the edit box on the main dialogue and click 'Install Licence Key'.

Once you have obtained the above licence key, the key_gui can be used to install the key in the Windows Registry.

python -m naginterfaces.kusari

Paste the key into the edit box on the main dialogue and then click on the Install Licence Key button to install it.

Once you have obtained the above licence key, the easiest way to install it is to store the text in a file,

$HOME/nag.key

or

/opt/NAG/nag.key

It is possible to store the licence file in a different location, see the Installer's Note Installer's Note Installer's Note for details.

It is possible to store the licence file in a different location, see the Installer's Note Installer's Note for details.


As a basic verification that the package is ready to use, the 'quick check' function, callable via

python -c "from naginterfaces import quick_check; quick_check()"

will confirm availability of a licence and go on to perform a small check that the underlying compiled libraries load correctly.

Install the NAG CPP Interfaces

The NAG CPP Interfaces file will be emailed to you together with your trial licence.

Unzip the NAG CPP Interfaces file (nagcpp_latest.zip) into the directory of your choice, referred to here as '[NAGCPP_INSTALL_DIR]'.

Install the Java Interfaces

A link to the Java Interfaces file will be emailed to you together with your trial licence. If you already hold a licence for the NAG Library and have not requested a trial licence, you can download the Java Interfaces from here.

Unzip the Java Interfaces file (nagjava_29.3.zip) into the directory of your choice, referred to here as '[my_nagjava_dir]'.

Solve your First Problem

The example programs are most easily accessed using the batch files nag_example_DLL.bat, nag_example_static_MT.bat and nag_example_static_MD.bat, which can be found in the C:\Program Files\NAG\NL29\nlw6i293el\batch\ folder.

These batch files require that the environment variables for your C/C++ Fortran compiler and the NAG Library are set. In particular, the environment variable NAG_NLW6I293EL needs to be set to the location of the NAG Library.

The shortcut:

NAG NLW6I293EL Command Prompt

should be used to start a Command Prompt window with the correct settings for the INCLUDE, LIB and PATH environment variables for the NAG Library and the supplied MKL. The environment variable NAG_NLW6I293EL, which is needed by the nag_example_*.bat batch files, is also set.

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

C:\Program Files\NAG\NL29\nlw6i293el\batch\envvars.bat

If this file is not in the default location, you can locate it by searching for the file envvars.bat containing 'nlw6i293el'.

An example program is specified by an argument to the command, e.g.

nag_example_DLL a00adc
nag_example_DLL a00adf

This will copy the example program and any data and/or options files (a00adce.c (a00adfe.f90 in this case) into the current folder, compile and link the program and run it to produce the example program results in the file a00adce.ra00adfe.r.

The example programs are most easily accessed by using the script nag_example, which is located in the directory [INSTALL_DIR]/scripts.

By default, nag_example selects to use 32-bit integers and static linking to the self-contained libnag_nag.a Library.

The nag_example script demonstrates use of the nagvars script, which can be used to set NAG-specific environment variables to assist with compiling and linking applications that call any of the NAG routines. They also amend the standard environment variables PATH and LD_LIBRARY_PATH DYLD_LIBRARY_PATH so that NAG executable programs and libraries can be found at compile, link and run time.

See the Users' Note for the macOS version for use with either the Linux C++11 ABI version Intel C++ compiler or the Linux C++98 ABI version GNU gcc compiler for a full description of these scripts.

An example program is specified by an argument to the command, e.g.

nag_example a00adc
nag_example a00adf

This will copy the example program and any data and/or options files (a00adce.c (a00adfe.f90 in this case) into the current directory, compile and link the program and run it to produce the example program results in the file a00adce.ra00adfe.r.

Assuming that you have the NAG Library installed at C:\Program Files\NAG\NL29\nlw6i293el and are using the Intel C++ Compiler, v.19 or above, here’s how to obtain the C++ wrappers and compile one of the examples

REM Set up the environment for the NAG Library 
"C:\Program Files\NAG\NL29\nlw6i293el\batch\envvars.bat"

REM Navigate to examples and compile
cd [NAGCPP_INSTALL_DIR]
icl.exe -I include examples\ex_a00ad.cpp /EHs /MD /Qstd=c++17 nag_nag_MD.lib user32.lib -o ex_a00ad.exe

REM Run compiled example
ex_a00ad.exe

Assuming that you have NAG Library installed at /opt/NAG/nll6i293bl/ and are using the Bash shell and gcc, v.6.3.1 or above, here’s how to obtain the C++ wrappers and compile one of the examples

# Set up the environment for the NAG Library
# 64 bit Integers using vendor provided (MKL) BLAS, dynamic linking
source /opt/NAG/nll6i293bl/scripts/nagvars.sh int64 vendor dynamic

# Navigate to examples and compile
cd [NAGCPP_INSTALL_DIR]/examples/
g++ ex_a00ad.cpp -I../include ${NAGLIB_INCLUDE} ${NAGLIB_LINK} -o ex_a00ad

#Run compiled example
  ./ex_a00ad

In the above, -I../include is the relative path to the NAG C++ include directory from the examples directory. You will need to include the full path to this directory if you compile from anywhere else. ${NAGLIB_INCLUDE} and ${NAGLIB_LINK} are include and link flags set by the nagvars.sh script for the main Library.

Each example file for the package can be run as a Python module, invocable via for instance

python -m naginterfaces.library.examples.info.impl_details_ex

Running

python -m pydoc naginterfaces.library.examples.info.impl_details_ex

will confirm the installation location of the associated file. All examples can be run as standard Python ‘main’ scripts from the Command Prompt, by executing for instance

python path/to/naginterfaces/library/examples/info/impl_details_ex.py

A quick test that the software has been correctly installed is to type a00aa at the MATLAB prompt, which should print some implementation details. If this does not work correctly and you see messages such as "The referenced assembly is not installed on your system." then it may be necessary to reboot your computer so that MATLAB picks up the correct support libraries.

To test that a valid license is available, type a00ac at the MATLAB prompt. This will return 1 if a valid license is found, or 0 otherwise.

You should access the NAG Toolbox documentation as follows. On starting the MATLAB documentation browser you should see a heading labelled Supplemental Software. This should have a NAG Toolbox link; clicking on that will give access to the NAG Toolbox demos and documentation (which includes runnable examples for each routine). From here, you can open the example text in the MATLAB editor and then run it via the MATLAB Run button.

For example, select the "D01 - quadrature" link from the Contents list, then select "d01ah" from the main panel. This will open the documentation for the d01ah routine. From within this document, click on Example from the Contents list, then click on the d01ah_example link next to "Open in the MATLAB editor". Then, from the Editor tab in the main MATLAB window, click on the Run button to run the example and display the results in the MATLAB Command Window.

Make sure that the folder containing the file nag_jni293.dll is on your PATH, as well as the bin and rtl\bin folders of the underlying Library NLW6I293EL. For example, your PATH environment variable should include

C:\path\to\my_nagjava_dir\NAGJava\win64;C:\Program Files\NAG\NL29\nlw6i293el\bin;C:\Program Files\NAG\NL29\nlw6i293el\rtl\bin

where C:\path\to\my_nagjava_dir is the folder in which you unzipped the Java materials and the NAG Library is assumed to have been installed in the default location.

We also recommend that you add NAGJava.jar to your CLASSPATH, e.g. your CLASSPATH environment variable would contain

.;C:\path\to\my_nagjava_dir\NAGJava\jar\NAGJava.jar

From a Command Prompt window go to the NAGJava\diagnostic folder and run the commands

javac NAGJavaDiagnostic.java
java NAGJavaDiagnostic

Make sure that the directory containing the file nag_jni293.so is on your PATH, as well as the lp64/lib and rtl/lib/intel64 directories of the underlying Library NLL6I293BL. For example, your PATH environment variable should include

/path/to/my_nagjava_dir/NAGJava/linux_x64:$HOME/NAG/nll6i293b/lp64/lib:$HOME/NAG/nll6i293b/rtl/lib/intel64

where /path/to/my_nagjava_dir is the directory in which you unzipped the Java materials and the NAG Library is assumed to have been installed in the default location.

We also recommend that you add NAGJava.jar to your CLASSPATH, e.g. your CLASSPATH environment variable would contain

.:/path/to/my_nagjava_dir/NAGJava/jar/NAGJava.jar

From a Command Prompt window go to the NAGJava/diagnostic directory and run the commands

javac NAGJavaDiagnostic.java
java NAGJavaDiagnostic

Further Reading

The following documentation is recommended to guide your next steps:

The Users' Note for either the Win64 version or the Win32 version - details how to access different variants of the NAG Library with different compilers.

The Users' Note for the Win64 version - details how to access different variants of the NAG Library with different compilers.

The Users' Note for either the Linux C++11 ABI version or the Linux C++98 ABI version - details how to access different variants of the NAG Library with different compilers.

The Users' Note for the Linux C++11 ABI version - details how to access different variants of the NAG Library with different compilers.

The Users' Note for the macOS version for use with either the Intel C++ compiler or the GNU gcc compiler - details how to access different variants of the NAG Library with different compilers.

The Users' Note - further details of how to call the NAG Library for Java.

The Users' Note - further details of how to call the NAG Library for Java.

The NAG Library Manual - the principal documentation for the NAG Library with all the information to support this interface.

NAG CL Interface Introduction.

NAG CPP Interface Introduction.

NAG FL Interface Introduction.

Following a successful deployment of the naginterfaces materials, it is recommended that you review the full documentation for the Python package before use.

To access the documentation from a Command Prompt execute

python -m pydoc naginterfaces

The NAG Toolbox Manual - the principal documentation for the NAG Toolbox for MATLAB.

This is also available from within MATLAB under Documentation [Supplemental Software] NAG Toolbox.

The NAG Library Manual - the principal documentation for the NAG Library.

Technical Support Service

Even with a trial licence, you have full access to our Technical Support Service. If you experience any difficulty, we are ready to help you. Contact us using the on-page chat facility or via the Technical Support Service.