NAG Libraries

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.

• 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:

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 HTML und PDF-Format hinterlegt:

• Fortran 77 Library

• SMP Library

• C Library

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 C Bibliothek:

module load nagclib

die SMP-parallele Bibliothek:

module load nagsmplib

Voraussetzung für das erfolgreiche Laden der NAG-Module ist, dass die Module "intel" und "mkl" aktiv sind.

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_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.

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.

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

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.