NAG-Bibliotheken

Kurzbeschreibung

Dieser Abschnitt gibt eine kurze Beschreibung der auf den HPC Plattformen am LRZ verfügbaren NAG-Bibliotheken. Hierzu zählen im Einzelnen:

  • Fortran Library:
    Fortran 77 kompatible Aufrufschnittstelle. Für Fortran 90 werden Schnittstellenblöcke als Moduldateien für den jeweils unterstützten Compiler mitgeliefert.

  • Fortran SMP Library:
    Fortran 77 kompatible Aufrufschnittstelle zur Nutzung mehrerer CPUs in einem shared-Memory System. Kann ggf. einen etwas geringeren Anteil an Funktionalität als die Fortran Library enthalten. Die Aufrufschnittstelle ist jedoch kompatibel zur Fortran Library.

  • Fortran 90 Library:
    Eine Teilmenge der Fortran Library Funktionalität, unter Verbesserung der Benutzerschnittstelle in Fortran 90 neu implementiert. Es ist zu beachten, dass zur Einbindung in eigene Programme Fortran 90 Modulinformationsdateien schon beim Übersetzen benötigt werden.

  • Parallel Library:
    Eine Teilmenge der Fortran Library Funktionalität, die auf distributed-memory Parallelrechnern mittels MPI kommuniziert. Die Aufrufschnittstelle ist nicht kompatibel zu der der Fortran 77 bzw. 90 Libraries. Anmerkung: die parallel Library ist derzeit auf den HPC Systemen nicht verfügbar.

  • C Library:
    Eine Teilmenge der Fortran-Funktionalität ist auch als C-basierte Bibliothek verfügbar.

Die aktuell installierten Bibliotheken sind für die einzelnen Rechensysteme in folgender Tabelle zusammengefasst:

Plattform/Compiler

Bibliothek/Release

Bemerkungen

Intel64 / AMD Opteron Linux

Intel Version 12.1+

Fortran 77 Mark 23

Intel MKL 10.3 wird hinzugelinkt

Intel64 / AMD Opteron Linux

Intel Version 12.1+

SMP Bibliothek Mark 23

Intel MKL 10.3 wird hinzugelinkt

Intel64 Linux

Intel Version 8.1+

Fortran 90 Release 4

Intel MKL wird hinzugelinkt

Intel64 / AMD Opteron Linux / Intel Version 11.0+ C Library Mark 9 ACML wird hinzugelinkt - shared libraries unter SLES10 nicht nutzbar

In dieser Tabelle nicht aufgeführte Versionen sind z. T. noch installiert, werden aber durch das LRZ nicht mehr unterstützt. Probleme sind vor einer Meldung an das LRZ Support-Team bitte zuerst mit einer unterstützten Konfiguration zu reproduzieren.

Dokumentation

Web-basierte Dokumentation

Detail-Informationen zu den einzelnen Routinen sind auf dem NAG Web-Server als Dateien im PDF-Format hinterlegt:

Release bzw. User Notes

Diese beschreiben plattform-spezifische Eigenheiten und sind auf einer Web-Seite bei NAG verfügbar.

Beispiele

In den Installationsverzeichnissen ($NAG_BASE bzw. $NAG_C_BASE, $NAG_F90_BASE etc) stehen im Verzeichnis examples Beispiele zu jedem NAG Aufruf zur Verfügung.

Einbinden der NAG Bibliotheken

Das Einbinden der NAG Bibliotheken erfolgt im Prinzip beim Linken der Objekte zu einer ausführbaren Datei. Bei Verwendung von C oder der Fortran 90 Bibliothek müssen außerdem beim Übersetzen entweder die Header-Dateien oder die Fortran Modulinformationsdateien dem Compiler bekannt sein. Die notwendige Information wird durch Laden eines geeigneten Environment Moduls in Umgebungsvariablen bereitgestellt. Im Einzelnen für

die Fortran 77 Bibliothek:

module load nagf77lib

die Fortran 90 Bibliothek

module load nagf90lib

und für die C Bibliothek

module load nagclib

die SMP-parallele Bibliothek:

module load nagsmplib

In Abhängigkeit vom geladenen Compiler-Modul (fortran, ccomp) werden automatisch die dafür passende Bibliothek sowie die optimierte Hersteller-BLAS geladen. Ändert man also die Compiler-Umgebung, so muss auch das entsprechende NAG Modul neu geladen werden.

Achtung: Bei Verwendung der shared libraries muss vor dem Laufenlassen des Programms ebenfalls das Modul geladen werden werden, damit die Bibliotheken zur Laufzeit gefunden werden (Setzung von LD_LIBRARY_PATH). Die hierbei erzeugten Umgebungsvariablen sind:

  • NAG_LIB (NAG_SHLIB): Für Anschluss der (shared) Fortran 77 Bibliothek

  • NAG_INC: Schnittstellendefinition für Fortran 77 Bibliothek

  • NAG_F90_INC: Für Fortran 90 Modulinformationsdateien

  • NAG_F90_LIB (NAG_F90_SHLIB): Für Anschluss der (shared) Fortran 90 Bibliothek

  • NAG_C_INC: Für C Headerdateien

  • NAG_C_LIB (NAG_C_SHLIB): Für Anschluss der (shared) C Bibliothek

  • NAG_SMP_LIB: Für Anschluss der SMP Bibliothek

Enthält eine Umgebungsvariable keinen Wert zugewiesen, ist die entsprechende Konfiguration nicht unterstützt. Je nach geladenem Modul werden auch zusätzlich benötigte Systembibliotheken mit eingetragen. Ausserdem werden die Umgebungsvariablen PATH und LD_LIBRARY_PATH in geeigneter Weise ergänzt, falls auf der Rechenplattform shared libraries verwendet werden können.

Achtung:

  • Bei Nutzung der SMP Library muss man dem Compiler zur Aktivierung von OpenMP erforderlichen switch mitgeben. Näheres hierzu ist in der OpenMP Beschreibung zu erfahren.

  • Bei Nutzung der parallelen Library sollte man das MPI wrapper Skript für den jeweils verwendeten Compiler benutzen (mpif90 oder mpicc genannt).

Im Folgenden ist das für die einzelnen Bibliotheken beschrieben; für den Compiler wird als generische Abkürzung $F90 (Fortran 77 oder 90) oder $CC (C) verwendet.

Fortran 77 Bibliothek

Optional kann man die Schnittstellendefinitionen in eigene Fortran 90 Programme mit USE einbinden; dann muss man die Programme mit

$F90 -c <options> $NAG_INC foo.f90

übersetzen. Zu einer ausführbaren Datei gebunden werden die Objekte dann mit

$F90 -o myprog.exe <linkage-options> myprog.o ... foo.o ... $NAG_LIB

SMP Bibliothek

Übersetzen:

$F90 -c <options> $NAG_SMP_INC foo.f90

Binden:

$F90 -o -parallel myprog.exe <linkage-options> myprog.o ... foo.o ... $NAG_SMP_LIB

Man beachte, dass beim Binden der Compiler-Schalter -parallel zu spezifizieren ist. Falls die eigenen Programm-Einheiten ebenfalls von OpenMP Gebrauch machen, ist der Schalter -openmp auch beim Übersetzen anzugeben.

MPI-parallele Bibliothek (derzeit nicht verfügbar)

Übersetzen (für die MPI Bibliothek gibt es keine Fortran 90 Schnittstellenblöcke, also auch keine entsprechende Modulinformationsdatei):

mpif90 -c <options> foo.f90

Binden:

mpif90 -o myprog.exe <linkage-options> myprog.o ... foo.o ... $NAG_MPI_LIB

Man beachte, dass beim Binden der Compiler-Schalter -parallel zu spezifizieren ist. Falls die eigenen Programm-Einheiten ebenfalls von OpenMP Gebrauch machen, ist der Schalter -openmp auch beim Übersetzen anzugeben. Es sollte auch funktionieren, die parallele Bibliothek von C aus zu nutzen; beim Übersetzen ist dann mpicc zu verwenden, beim Binden mpif90 -nofor_main. Dies wurde jedoch LRZ-seits nicht getestet.

Fortran 90 Bibliothek

Die Modulinformationsdatei muss man ins eigene Fortran 90 Programme mit USE einbinden; dann muss man die Programme mit

$F90 -c <options> $NAG_F90_INC foo.f90

übersetzen. Zu einer ausführbaren Datei gebunden werden die Objekte dann mit

$F90 -o myprog.exe <linkage-options> myprog.o ... foo.o ... $NAG_F90_LIB

C Bibliothek

Das C Programm ist mit

$CC -c <options> $NAG_C_INC foo.c

zu übersetzen. Zu einer ausführbaren Datei gebunden werden die Objekte dann mit

$CC -o myprog.exe <linkage-options> myprog.o ... foo.o ... $NAG_C_LIB

NAG MATLAB Toolbox

Viele Routinen der Fortran 77 Bibliothek können jetzt aus MATLAB heraus genutzt werden, da neuerdings die NAG MATLAB Toolbox auf den x86_64 basierten Linux-Systemen verfügbar ist. Man starte MATLAB mit den Shell-Befehlen

module load matlab

matlab

und führe dann beispielsweise auf der MATLAB Kommandozeile die Sequenz

a=[1,1,2; 2,1,2; 3,1,1]
n=int32(3)
[a, det, ifail] = f03aa(a, 'n', n)

aus. Hier wird dann etwa die Determinante der Matrix berechnet, und die Matrix durch ihre LU Faktorisierung überschrieben. Die Schnittstelle ist nicht identisch zu der der Fortran 77 Bibliothek, da viele Argumente implizit sind und daher nicht angegeben werden müssen.

Die Dokumentation aller verfügbaren Aufrufe ist über den oben angegebenen Link zur Toolbox erreichbar.

Ergänzende Bemerkungen

Fehlerbehandlung

Zur Fehlerbehandlung sind üblicherweise drei Fragen zu beantworten:

  1. Was wird im Fehlerfall getan? (Fehlermeldung ausgeben? Programmausführung abbrechen?)

  2. Wohin werden gegebenenfalls die Fehlermeldungen geschrieben?

  3. Wie erfährt das aufrufende Programm, ob und welche Fehler vorliegen?

NAG verwendet dazu die Routinen X04AAF, X04ABF (Kanalnummern für Meldungen setzen oder abfragen) und das Argument IFAIL.

Fast alle NAG-Routinen haben ein Argument IFAIL. Dieses Argument hat eine doppelte Aufgabe:

  • Der Wert von IFAIL beim Aufruf bestimmt die Art der Fehlerbehandlung.

  • Der Wert von IFAIL beim Rücksprung gibt den Fehlercode an.

Vor dem Aufruf ist IFAIL üblicherweise mit 0, 1 oder -1 zu besetzen. Dabei bedeutet:

  • IFAIL=0: Hard Fail. Im Fehlerfall wird eine Fehlermeldung geschrieben und das Programm mit STOP beendet.

  • IFAIL=-1: Noisy Fail. Fehlermeldung wird geschrieben. Programmausfürung wird fortgesetzt. Das aufrufende Programm wird durch den Parameter IFAIL über den Fehler informiert.

  • IFAIL=1: Silent Fail. Fehlermeldung wird nicht geschrieben. Ansonsten sind "Noisy Fail" und "Silent Fail" gleich.

Einzelheiten hierzu im NAG-Manual, Kapitel P01.

NAG unterscheidet zwei Arten von Ausgaben:

  • Fehlermeldungen ("error messages") und

  • Ratschläge ("advisory messages").

Die Kanalnummern werden von den Routinen X04AAF (für Fehler) und X04ABF (für Ratschläge) verwaltet.
Die aktuelle Einstellung der Kanalnummern kann abgefragt werden mit

         CALL X04AAF (0, NERR)
         PRINT *,   'KANAL FUER FEHLERMELDUNGEN = ', NERR
         CALL X04ABF (0, NADV)
         PRINT *,   'KANAL FUER RATSCHLAEGE     = ', NADV

Die Voreinstellung für Fehlermeldungen ist Kanal 0, die für Ratschläge Kanal 6.

Die Kanalnummern können geändert werden durch

         NEUERR = <neue Kanalnummer für Fehlermeldungen>
         CALL X04AAF (1, NEUERR)
         NEUADV = <neue Kanalnummer für Ratschläge>
         CALL X04ABF (1, NEUADV)

Einzelheiten hierzu im NAG-Manual, Kapitel X04.

Die erforderliche Information ist für alle am LRZ installierten NAG-Bibliotheken über die Dokumentation abrufbar.
Auf der Einstiegsseite muss man aus der Inhaltsübersicht den Abschnitt "Essential Introduction to the NAG Library" auswählen.
Im sich öffnenden PDF suche man dann in der Inhaltsübersicht einen Punkt "NAG Error Handling and the IFAIL Parameter" (oder so ähnlich).

Hinweise zu verwendeten Datentypen

Für alle LRZ Rechensysteme ist die NAG-Bibliothek als Double-Precision-Version installiert, d. h. der in der Dokumentation verwendete Pseudo-Typ Real ist als DOUBLE PRECISION zu interpretieren. Werden nicht alle Parameter der NAG-Subroutinen, insbesondere auch die NAG-Funktionen, entsprechend für die Double-Precision-Version deklariert, können falsche Ergebnisse erzielt werden, ohne dass Fehlermeldungen auftreten! Daher wird empfohlen, die NAG Schnittstellendefinitionen explizit mit USE einzubinden. Für ganzzahlige Datentypen wird übrigens (wenn in der API nicht explizit anders festgelegt) der Default INTEGER Typ eingesetzt.