WAVEWATCH

Introduction

WAVEWATCH 3 est un modèle développé par la NOAA/NCEP qui simule la formation et la dispersion de vagues et de la houle dans des eaux océaniques et côtières. Il se base sur la résolution des équations du spectre des vagues. Le modèle se caractérise par une importante modularité et la possibilité de paralléliser le calcul. La version 4.18 intègre une atténuation du spectre par la glace ainsi que la possibilité d'utiliser des grilles non structurées.

Guides d'utilisation

• Guide WAVEWATCH 3.14 (référence officielle de la version 3 publique)
• Guide WAVEWATCH 4.18 (référence officielle de la version 4 publique)
• Guide WAVEWATCH 5.16 (référence officielle de la version 5 publique)
• Guide WAVEWATCH 6.17 (référence officielle de la version 6 publique)

Tutoriels et outils

L'IFREMER Brest, qui donne une formation sur le modèle plusieurs fois par an, donne accès à un site ftp où sont réunis le code de la dernière version, des cours théoriques sur les vagues et le modèle, des tutoriels d'installation et d'utilisations avec de nombreux exemples. On y trouve aussi des outils et des scripts Matlab/Octave pour l'analyses des sorties.

Problèmes potentiels rencontrés à l'installation

Lors de l'installation du modèle, veuillez bien suivre les indications données par le guide d'utilisation, rubrique 5.3 "compiling and linking" (page 118). Trois fichiers nécessitent des modifications de la part de l'utilisateur : comp / link / switch (à modifier dans le répertoire /work) . L'utilisateur doit définir le compilateur à utiliser ainsi que les options qui en dépendent.

Fichiers comp et link

Attention, il existe plusieurs versions de ces fichiers. Avant de modifier ces fichiers, dans le répertoire /work, modifiez les liens symboliques de comp et link par :

ln -s ../bin/comp.Intel comp

ln -s ../bin/link.Intel link

À partir de maintenant, toujours dans /work, vous pouvez modifier le type de compilateur utilisé (ifort, gfortran...) et les options liées dans comp et link.

• Modifications du ficher comp (exemple avec ifort), ajoutez :

# Intel compiler on Linux ----------------------------------------------------
# 2.b.1 Build options and determine compiler name
#       Note that all but GrADS output is forced to big endian data

  opt="-c -O3 -assume byterecl -module  $path_m"
# opt="-c -list -O3 -unroll -tpp7 -Zp8 -module $path_m"
# opt="-c -g CB -list -O3 -module $path_m"  

  if [ "$name" != 'gx_outp' ] && [ "$name" != 'gx_outf' ]
  then
    opt="$opt -convert big_endian"
  fi  
 
  if [ "$mpi_mod" = 'yes' ]
  then
    comp=mpif90
  else
   comp=ifort
  fi  

• Modifications du ficher link (exemple avec ifort), ajoutez :

# Intel compiler ------------------------------------------------------------
# 3.a Build options and determine compiler name
#     No GRIB libraries for this one

  opt="-O3 -Zp8 -tpp7 -o $prog"

  if [ "$mpi_mod" = 'yes' ]
  then
    comp=mpif90
  else
    comp=ifort
  fi

Une fois cette opération effectuée, il est important d'aller dans le répertoire /bin et de créer un lien symbolique de comp et de link au sein même du répertoire. Nous avons bien modifié les fichiers comp.Intel et link.Intel à partir de /work, mais lors de la compilation, le compilateur va se servir des fichiers comp et link originaux présent dans le répertoire /bin.

• Dans /bin, renommez comp et link :

mv comp comp.original

mv link link.original

et créez un lien symbolique vers les fichiers comp.Intel et link.Intel du même répertoire

ln -s comp.Intel comp

ln -s link.Intel link

Fichier switch

Le fichier switch correspond à la liste de modules qui seront activés lors de la compilation du modèle. Il est important de vérifier quels sont les modules actifs, de les modifier au besoin (en particulier pour la réalisation des tests) et de recompiler le modèle si le fichier a été modifié.

La suite de la procédure de compilation est clairement expliquée dans le guide d'utilisateur. Plusieurs étapes sont nécessaires pour vérifier l'installation et le bon fonctionnement du modèle.

Installation sur la grappe de calcul MINGAN

Ce paragraphe propose un exemple d'installation de WAVEWATCH3 à partir d'une archive de la version du modèle utilisée à l'ISMER.

1. Décompression de l'archive tar.gz

Une fois connecté(e) sur MINGAN :

cd

tar -xzvf WW3_Mingan.tar.gz

Cette commande crée un répertoire WW3 dans votre home, contenant :

> WW3
    > cases
    > guide
    > manual
    > model
    > regtests

La suite de l'installation se déroule dans model, mais il faut avant mettre à jour le fichier bash_profile pour que tout se déroule sans problème.

2. Mise-à-jour de bash_profile

Éditer le fichier bash_profile :

vi ~/.bash_profile

pour qu'il devienne :

# bash_profile

# Get the aliases and functions
if [ -f ~/.bashrc ]; then
        . ~/.bashrc
fi

# User specific environment and startup programs
export WWATCH3_NETCDF=NC4
export NETCDF_CONFIG=/usr/bin/nc-config

module load dot

PATH=$PATH:$HOME/bin:.

export PATH

Cette étape permet de définir l'environnement NetCDF dont WAVEWATCH a besoin, ainsi que de charger le module dot, qui permet de lancer une commande depuis le répertoire courant (sans taper ./ avant). Ces modifications deviennent effectives grâce à la commande :

source ~/.bash_profile

ou en relançant le terminal.

Construction du modèle Wavewatch III

L'installation étant maintenant complétée, on doit par la suite construire et compiler le modèle Wavewatch III pour son utilisation. La construction du modèle Wavewatch III est divisée en deux étapes, soit la pré-construction des fonctions nécessaires à la compilation du modèle et, bien entendu, la compilation du modèle elle-même.

1. Mise en place de l'environnement WAVEWATCH3 et pré-construction du modèle

Pour pré-construire les fonctions nécessaires à la compilation du modèle, on doit en premier lieu se rendre dans le répertoire bin de model à l'aide de la commande

cd WW3/model/bin

La fonction w3_setup se rendera utile pour cette tâche. Cette dernière permet de faire trois choses :

- Dans votre home, elle crée le fichier .wwatch3.env qui contient les variables d'environnement nécessaires à la pré-construction du modèle. Par exemple, le fichier .wwatch3.env contient les noms des compilateurs à utiliser pour compiler les fonctions de pré-compilation en Fortran et C du répertoire \aux, comme nous verrons dans quelques instants.

- Avec ces mêmes compilateurs, elle construit et compile les fonctions de pré-compilation du répertoire \aux (ex : w3_ad3.f);

- Puis finalement, elle vous permet de définir le compilateur de modèle Wavewatch III (qui n'est pas obligé d'être le même que pour les fonctions de pré-construction) en choisissant un fichier comp, ainsi que de définir les switch du modèle en choisissant un fichier switch.

Effectuons maintenant la commande

w3_setup .. -c Intel -s test_mingan

où '..' indique le chemin du répertoire source de Wavewatch III ('..' pour répertoire supérieur). La commande -c Intel indique quel compilateur sera utilisé pour compiler le modèle (ce qui définit nos fichier comp et link comme comp.Intel et link.Intel dans le cas du compilateur Intel). Et finalement, la commande -s test_mingan indique le fichier switch à utiliser, soit switch_test_mingan dans notre cas.

Comme le fichier .wwatch3.env n'existe pas encore, la fonction w3_setup vous demandera de mettre à jour les variables d'environnement :

Setting up WAVEWATCH III
 
   Setup file /home/<username>/.wwatch3.env not found
 
   Creating new set-up :
 
      Printer for listings [printer] : 
      FORTRAN compiler for aux. [f77] : gfortran
      C compiler for aux. [cc] : gcc
      Scratch space [/tmp/<username>] : /home/<username>/WW3/model/tmp
      Save source code files (*.f)  [no] : yes
      Save listing files  [no] : yes

<username> fait référence à votre identifiant sur MINGAN.

Ceci fait, les fonctions de pré-constructions de Wavewatch III devraient avoir été créées. Nous serions ainsi hypothétiquement prêts à compiler le modèle Wavewatch III. Pour s'assurer que tout est en ordre, il est possible de vérifier si les variables d'environnement de Wavewatch III ont bien été créées en ouvrant le fichier .wwatch3.env à l'aide de n'importe quel éditeur de texte. Effectuez la commande

vi ~/.wwatch3.env

Dans votre éditeur de texte, vous devriez observer quelque chose qui ressemble à ceci :

#
# Environment variables for wavewatch III
# ---------------------------------------
#

WWATCH3_LPR      printer
WWATCH3_F77      gfortran
WWATCH3_CC       gcc
WWATCH3_DIR      /home/<username>/WW3/model
WWATCH3_TMP      /home/<username>/WW3/model/tmp
WWATCH3_SOURCE   yes
WWATCH3_LIST     yes

Ceci fait, et toujours pour éviter des erreurs embarrassantes, il faut s'assurer d'avoir les modules nécessaires à la compilation de vos fonctions Fortran et C de la grappe de calcul Mingan. Par exemple, il faut utiliser le module gcc pour compiler avec gcc... Un rappel, la commande

module list

permet de voir les modules actuellement actifs. Dans notre exemple, les modules gcc/4.9.2, intel/compilateurs et netcdf/ifort seraient nécessaires, car nous compilons les fonctions de pré-construction en Fortran et C avec gcc et nous compilons le modèle Wavewatch III avec Intel. Quoi qu’il en soit, vous devriez maintenant être prêt à compiler le modèle!

2. Compilation du modèle Wavewatch III

Sachant que tout est bien configuré, il ne reste plus qu'à compiler ! Pour ceci, placez-vous dans /model/bin et effectuer la commande :

w3_make

qui compile toutes les sous-routines de construction de wavewatch III préalablement générées et construit les exécutables correspondant dans le répertoire /model/exe, qui était auparavant vide. Ceci devrait prendre quelques minutes. S'il y a des erreurs, vérifier de nouveau si les modules de compilation sont bons. Pour vérifier que la compilation s'est déroulée correctement, rendez vous dans le répertoire /model/exe, autrefois vide, et effectuez un ls pour voir que plusieurs exécutable s'y sont ajoutés :

exec_type  gx_outf  gx_outp  ww3_bounc  ww3_bound  ww3_gint  ww3_grib  ww3_grid  ww3_gspl  ww3_multi  ww3_ounf  ww3_ounp  ww3_outf  ww3_outp  ww3_prep
ww3_prnc  ww3_sbs1  ww3_shel  ww3_strt  ww3_trck

Le modèle Wavewatch III est maintenant prèt à être utilisé!

3. Définir les dossiers sources dans le fichier d'environnement

Les scripts, les exécutables et les fichiers switch nécessaires à la compilation du code WW3 sont enregistrés dans le répertoire WW3/bin, alors que les exécutables sont enregistrés dans le répertoire WW3/exe. Afin de pouvoir compiler et exécuter le code de n'importe quel dossier de travail (p.ex. WW3/work), il importe d'ajouter le chemin d'accès de ces deux répertoires dans le fichier ~/.bash_profile. Pour ce faire, taper la commande:

vi ~/.bash_profile

ajouter sous la ligne PATH=$PATH:$HOME/bin:. les lignes

PATH=$PATH:$HOME/WW3/model/bin:.
PATH=$PATH:$HOME/WW3/model/exe:.

Après avoir édité le fichier, exécuter la commande :

source ~./bash_profile

afin de mettre à jour les chemins d'accès. Il est possible de vérifier la mise à jour à l'aide, par exemple, de la commande :

which ww3_grid

qui devrait donner le bon chemin d'accès.

Cas test

Un ensemble de cas test sont disponibles dans le répertoire WW3/regtests, lesquels peuvent être exécutés afin de vérifier le bon fonctionnement des différentes composantes du modèle. Le script regtests/bin/run_test permet d'automatiser l’exécution de ces tests en appelant les différentes routines ww3_grid, ww3_strt, ww3_shel, etc. et en gérant la création des liens symboliques. Ces liens s'avèrent nécessaires pour la lecture des fichiers d'entrée, c.-à-d. les fichiers de type WW3/regtests/test/input/*.inp, utilisés par les routines du modèle lorsque l'exécution est lancée depuis un répertoire de travail, p.ex. WW3/regtests/test/work.

Comme l'arborescence du dossier WW3/ est quelque peu différente de celle requise par le script run_test, ce dernier doit être modifié pour permettre son exécution. Dans WW3/regtests/bin, taper la commande

vi run_test

afin de modifier les lignes 219 à 221,

path_e="$path_s/model/exe"
path_a="$path_s/model/aux"
path_b="$path_s/model/bin"
   

ainsi que la ligne 310,

args="-t $path_s/model/tmp $path_s/model"

Une fois le script édité, il est dès lors possible de lancer son exécution en spécifiant le chemin d'accès du fichier d'environnement wwatch3.env. Par exemple, pour lancer le test ww3_tp2.1 depuis le répertoire WW3/regtests/,

./bin/run_test -a ~/.wwatch3.env -w work $HOME/WW3 ww3_tp2.1
 

Ce faisant, l'ensemble des fichiers de sortie générés par les exécutables seront sauvegardés dans le répertoire WW3/regtests/ww3_tp2.1/work/ (p.ex. les fichiers *.out). La commande

run_test -h

permet de détailler les différentes options disponibles pour modifier l'exécution. Par exemple, pour rouler le même test mais en mode parallèle (MPI), la ligne de commande a utilisé sera plutôt

./bin/run_test -a ~/.wwatch3.env -s PR3_UQ_MPI -p mpirun -n 3 -w work_mpi $HOME/WW3 ww3_tp2.1
 

avec les options -s PR3_UQ_MPI et -p mpirun -n 3 qui permettent respectivement de spécifier le bon fichier switch (avec DIST MPI dans l'énumération des switchs en lieu et place de SHRD) et le mode d'exécution.

Pour un premier pas avec le modèle, le guide d'apprentissage disponible à l'adresse http://polar.ncep.noaa.gov/waves/workshop/pdfs/WW3-workshop-exercises-day2-curvilinear.pdf est conseillé. Une foule de documents sont également disponibles via le site http://polar.ncep.noaa.gov/waves/workshop/pdfs/.