The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Introduction

GOTM (General Ocean Turbulence Model) est un modèle libre qui simule les processus physique d'une colonne d'eau lacustre ou océanique en solutionnant les équations du transport moyen et turbulent sur la verticale. Il a été développé à l'origine par Hans Burchard, Karsten Bolding, Manuel Ruiz-Villareal et Pierre-Philippe Mathieu et hébergé à l'Institute of Oceanography in Hambourg d'où l'on peut obtenir le code source (www.gotm.net). Depuis 2008, Dany Dumont et plusieurs étudiants et collaborateurs ont utilisé ce code riche et versatile dans plusieurs projets. Pour faciliter la collaboration interne et pour tirer parti des modifications apportées, une branche du code gotm-4.0.0 a été déposée dans un dépôt svn sur les serveurs du POLR (ISMER) sous le nom de gotm_ismer. Ce dépôt a été créé afin de partager et de documenter à l'interne les avancées faites par chacun. Lorsque le code évolue significativement, les modifications sont proposées à l'équipe de développeurs qui les incorporent dans la version officielle, profitant ainsi à toute la communauté GOTM.

Guide d'utilisation

Obtenir le code gotm_ismer

Le code gotm_ismer est en fait une copie du code gotm-4.0.0 qui a subit quelques modifications somme toute assez superficielles associées aux modèles biogéochimiques. Dans un futur pas très lointain, l'objectif est de migrer vers FABM (Framework for Aquatic Biogeochemical Models), un code traitant les modèles biogéochimiques de manière modulaire et donc beaucoup plus flexible, couplés à gotm-4.1.

Pour obtenir le code gotm_ismer, vous devez d'abord avoir obtenu un accès à gitlasso, le gestionnaire de version décentralisé du POLR.

Dans votre répertoire /home, exécutez la commande suivante:

git clone https://gitlasso.uqar.ca/dumoda01/gotm_ismer.git

Si le téléchargement a été effectué avec succès, vous devriez retrouver les répertoires suivants:

compilers/  ! Contient les informations permettant de compiler le modèle sur votre ordinateur
doc/        ! Documentation originale LaTeX
include/    ! Définitions de pré-compilation
nml/        ! Modèles de namelists (fichiers de contrôle ou de paramétrage des simulations)
scripts/    ! Fonctions et scripts pertinents
src/        ! Code source
templates/  ! Modèles de routines
test_cases/ ! Cas test

Compiler le code

La compilation du code consiste à lire, interpréter, lier et condenser les routines fortran dans un fichier exécutable ou programme dont on se servira pour exécuter le modèle. Le code source se trouve dans le répertoire src/ qui contient les routines fortran (.F90) qui sont classées dans des sous-répertoires représentant certaines sections du code.

gotm/         ! Contient le programme principal.
observations/ ! ...
meanflow/     ! ...
airsea/       ! ...
turbulence/   ! ...
util/         ! ...
extras/       ! ...

Rules.make

Le répertoire src/ contient également le fichier Makefile, qui fixe les règles de compilation qui ne doivent pas être modifiées (à moins que vous ne décidiez de faire certaines modifications avancées au code), et le fichier Rules.make.template qui contient les règles de compilation et les variables d'environnement propres à l'utilisateur et qui elles doivent être modifiées par l'utilisateur. Pour effectuer cette étape, faite une copie du fichier modèle Rules.make.template en le nommant Rules.make.

cp Rules.make.template Rules.make

Modifiez ensuite les variables d'environnement en fonction de votre profil et de votre plate-forme.

brandypot.uqar.ca

Pour compiler avec ifort sur brandypot:

Spécifier le compilateur à utiliser. Cette variable servira à pointer vers un fichier compiler.$FORTRAN_COMPILER qui doit exister et se trouver dans le répertoire compilers/:

FORTRAN_COMPILER=IFORT

Indiquer l'emplacement des librairies NetCDF:

NETCDFINC    = /opt/local/netcdf-3.6.1/include
NETCDFLIBDIR = /opt/local/lib

Déterminer quelles portions du code vous voulez compiler. Dans l'exemple suivant, le code correspondant aux modules sediment et seagrass (qu'on retrouve dans le répertoire src/extras/) ne sera pas compilé alors que le module bio et le module netcdf, qui permet de sauvegarder les sorties du modèle en format NetCDF, le sera:

# What do we include in this compilation
NetCDF=true
SEDIMENT=false
SEAGRASS=false
BIO=true

mingan.uqar.ca

Pour compiler avec gfortran sur mingan (la compilation avec ifort sera décrite bientôt), modifier les lignes suivantes de Rules.make:

FORTRAN_COMPILER=GFORTRAN

NETCDFINC    = /usr/include
NETCDFLIBDIR = /usr/lib64

NETCDFLIB = -lnetcdff

Sur mingan, assurez-vous d'avoir chargé les modules nécessaires. Il n'y a pas de module associé à ifort. Pour l'utiliser, faites la commandes suivante, que vous pouvez ajouter dans le .bashrc

source /share/apps/intel/bin/ifortvars.sh intel64

Une fois le fichier Rules.make correctement modifié, vous pouvez compiler le code en faisant:

make realclean
make

À la fin de la compilation, l'exécutable gotm_prod_GFORTRAN est créé. Le terme prod indique que la compilation a été faite en mode production, option que l'on détermine dans le fichier Rules.make (l'autre option disponible est debug), et le terme GFORTRAN indique qu'elle a été réalisée avec le compilateur GFORTRAN utilisant le fichier de configuration compilers/compiler.GFORTRAN. En cas de problème, consultez la page dépannage.

Configurer une expérience

Si vous arrivez à compiler le code avec succès, c'est que vous êtes maintenant prêts à construire votre propre expérience. Vous pouvez pour cela vous inspirer des cas test (voir prochaine section), ou bien suivre les indications de cette section. Mettre en place une expérience nécessite d'abord de créer un répertoire de travail à partir duquel vous exécuterai le modèle. La pratique commune est de mettre toutes vos expérience (vous risquez d'en faire plus d'une) dans un répertoire exp/ que vous pouvez créer dans un endroit où vous avez suffisamment d'espace disque. Sur brandypot, il est commun d'utiliser la partition /sas/usagers pour y mettre ce répertoire, comme par exemple /sas/usagers/dumoda01/gotm/exp. Afin de simplifier l'exécution du code, il est conseillé de faire un lien symbolique de exp/ dans /home/dumoda01/gotm_ismer en faisant la commande:

cd gotm_ismer
ln -s /sas/usagers/dumoda01/gotm/exp .

De cette manière, le répertoire sera accessible aisément à partir du répertoire racine, mais les données parfois volumineuses seront stockées dans un endroit où il y a suffisamment d'espace. Dans exp/, créez un répertoire portant le nom de votre expérience (ex. potter_cove_1/). À ce stade-ci, vous avez besoin de trois ingrédients principaux pour réaliser votre expérience: 1) l'exécutable (gotm_prod_IFORT, que vous avez déjà), 2) des fichiers de paramètres namelist (*.nml) et 3) des fichiers intrants (*.dat).

La façon la plus sûre d'obtenir le premier est de créer une lien symbolique de l'exécutable se trouvant dans src/ dans le répertoire de l'expérience:

cd potter_cove_1
ln -s /home/dumoda01/gotm_ismer/src/gotm_prod_IFORT .

De cette façon, toute modification au code sera prise en compte automatiquement. Les fichiers namelist correspondant à la dernière version du code sont situés dans le répertoire gotm_ismer/nml/. Chaque fichier contient plusieurs namelists associées aux routines du code dont certains paramètres peuvent être affectés. Les namelists permettent de modifier des variables ou des paramètres sans avoir à recompiler le code. Chacun des paramètres sont documentés dans les fichiers. Certains fichiers sont obligatoires alors que d'autres dépendent des modules que l'on désire utiliser. En voici la liste complète:

# Mandatory namelist files
gotmrun.nml
gotmmean.nml
gotmturb.nml
airsea.nml
obs.nml
kpp.nml

# Module-dependent namelist files
bio.nml
bio_fasham.nml
bio_npzd.nml
bio_iow.nml

C'est à travers les namelist que l'on gère les intrants au modèle. Par exemple, on peut demander au modèle de lire les variables météorologiques ou des profils de température et de salinité à partir de fichiers. Dans un tel cas, il faut donc fournir ces fichiers et ce dans un format texte spécifique. C'est le troisième et dernier ingrédient à mettre dans la soupe. Pour de l'aide sur la façon de formater ces fichiers, consultez le fichier GOTM_HOWTO_observations.txt situé dans le répertoire racine. Les sections suivantes décrivent différentes façon de générer ces fichiers selon l'origine des données.

meteo.dat

Tel qu'indiqué dans GOTM_HOWTO_observations.txt, le fichier meteo.dat doit être formaté de la manière suivante:

1957-09-01 00:00:00   2.46    6.80 1011.1   12.13   10.20 0.61
1957-09-01 06:00:00   0.46    6.32 1011.2   13.85   11.04 0.63
1957-09-01 12:00:00  -0.16    6.20 1010.8   15.38   10.72 0.88
1957-09-01 18:00:00  -0.56    4.41 1010.2   13.56   10.50 0.83
1957-09-02 00:00:00   1.83    3.43 1009.8   13.31   10.65 0.40
1957-09-02 06:00:00   3.70    6.76 1009.1   13.08   10.86 1.00
1957-09-02 12:00:00   5.24    7.13 1009.5   14.33   12.49 0.98
1957-09-02 18:00:00   5.67    8.07 1009.7   15.06   12.09 0.71
1957-09-03 00:00:00   5.15    6.46 1010.4   14.68   12.88 0.83
1957-09-03 06:00:00   1.17    3.47 1010.4   14.78   13.42 0.69

Ajout d'un modèle biologique

Avant de se lancer dans l'ajout d'un modèle biologique, il peut être intéressant de comprendre la structure générale de GOTM et comment les modules (.mod) et sous-routine (.F90) sont liés entre eux, afin de comprendre comment modifier le code pour que nos ajouts/corrections soient pris en considération. Une présentation schématique est disponible ici : [1].

Il existe actuellement plusieurs modèles biologiques disponibles, répertoriés dans la namelist bio.nml:

1: NPZD                     (4 variables)
2: IOW-ERGOM                (9 variables)
3: Suspended matter only    (1 variable)
4: Fasham et al. 1990       (7 variables)
5: IOW-ERGOM MaBenE version (9 variables)
6: ISMER model              (9 variables)
7: GSJ model                (11 variables)
8: Ariadna Nocera's model   (tbd)
9: North water polynya's model   (tbd)

Selon vos besoins vous pourriez avoir envie de construire votre propre modèle de réaction afin de répondre à votre question de recherche. Voici les étapes à suivre pour ajouter un nouveau modèle à partir d'un modèle existant:

model_name.F90

L'ensemble des fichiers avec l'extension .F90 se trouvent dans le répertoire /gotm_ismer/src/extras/bio. Choisissez parmi les modèles biologiques déjà disponibles, celui se rapprochant le plus de celui que vous souhaitez développer. Faite une copie de ce fichier en le renommant avec le nom de votre modèle:

mv /gotm_ismer/src/extras/bio/initial_model_name.F90 /gotm_ismer/src/extras/bio/final_model_name.F90

Il s'agira par la suite dans ce fichier final_model_name.F90 de renommer partout l’ancien nom du modèle par le nouveau. Exemple:

Fichier initial : bio_fasham.F90 
Fichier final   : bio_polynow.F90
Dans bio_fasham.F90 remplacer tous les lieux ou sera écrit "fasham" par "polynow".

Par la suite dans ce fichier final_model_name.F90 vous pourrez librement construire ou améliorer votre modèle biologique.

Note: dans ce fichier .F90, la routine var_info_modelname spécifie le numéro de chaque variable. Il peut être par la suite utilisé par d'autres routines. Par exemple il est important de noter la valeur de l'indice attribué au nitrate et à l'ammonium pour les référencer correctement dans les fichiers ammonium.F90 et nitrates.F90.

Dans le fichier bio_polynow.F90, sous-routine var_info_polynow:
  var_names(5) = 'nit'  ! indice du nitrate = 5
  var_units(5) = 'mmol/m**3'
  var_long(5)  = 'nitrate'
  var_names(6) = 'amm'  ! indice de l'ammonium = 6
  var_units(6) = 'mmol/m**3'
  var_long(6)  = 'ammonium'

Dans le fichier nitrates.F90:
  else if (bio_model.eq.9) then  !! Le 9 ici fait référence au modèle sélectionné (voir section bio.F90)
     do i=1,nlev
        nit(i) = cc(5,i)
    end do
Dans le fichier ammonium.F90:
else if (bio_model.eq.9) then  
     do i=1,nlev
        amm(i) = cc(6,i)
     end do

bio.F90

Ce fichier permet de répertorier l'ensemble des modèles biologiques disponibles et de sélectionner parmi eux (d'après le choix par l'utilisateur via la namelist bio.nml) celui à prendre en compte lorsque l'on fera tourner le modèle. Il s'agira donc de répertorier ici votre nouveau modèle biologique à 3 endroits différents:

* Dans la partie déclaration du module:
  use bio_polynow,  only : init_bio_polynow,init_var_polynow,var_info_polynow  
  use bio_polynow,  only : light_polynow,do_bio_polynow

*Dans la partie déclaration de la sous-routine init_bio
case (9)  
call init_bio_polynow(namlst,'bio_polynow.nml',unit)
call allocate_memory(nlev)
call init_var_polynow(nlev)
call var_info_polynow()
Ici le numéro fait référence aux modèles biologiques comme numérotés dans la namelist bio.nml.
Notre modèle bio_polynow est donc le 9eme modèle associé à GOTM dans les répertoires de l'ismer, et celui de Fasham par exemple est référencé comme le numéro 4.

*Dans la partie déclaration de la sous-routine do_bio
case (9)                                                         
call light_polynow(nlev,bioshade_feedback)                     
call ode_solver(ode_method,numc,nlev,dt_eff,cc,do_bio_polynow)

Makefile

Ajoutez dans ce fichier votre modèle (lignes à insérer de manière similaire à celles référençant les autres modèles ) :

bio_polynow.F90		\
${LIB}(bio_polynow.o)	\

bio.nml

Dans la namelist bio.nml (disponible dans le répertoire /gotm_ismer/nml) ajoutez votre modèle dans la partie description.

 9: North water polynya's model   (tbd)

bio_polynow.nml

Il faut ajouter une namelist au nom de votre modèle dans le répertoire /gotm_ismer/exp/nom_exp/ , pour que le modèle se réfère aux valeurs des paramètres mentionnées par l'utilisateur. Une simple copie de la nml du modèle d'après lequel vous construisez votre modèle suffit.

mv /../exp/bio_nocera.nml /../exp/bio_polynow.nml

Une fois le fichier copier ne pas oublier de modifier dans le fichier le nom de la namelist.

gedit bio_polynow.nml 
&bio_polynow_nml

Une fois toutes ces étapes réalisées, vous pourrez aller dans le dossier /src et recompiler le modèle comme mentionné précédemment à l'aide des commandes :

make realclean
make

Si vous avez réalisé un lien symbolique vers gotm_prod_IFORT alors la sortie de modèle aura pris en compte les modifications que vous aurez réalisé dans le code.

Ajout d'une constante dans le modèle biologique

Lors de l'élaboration de votre modèle biologique vous pouvez être amené à utiliser des constantes dans vos équations. Pour ce faire il y a quelques étapes à respecter. Nous prendrons ici l'exemple de l'équation de la nitrification et donc l'ajout de la constante de nitrification, mu5.

bio_polynow.F90

Dans votre fichier .F90 contenant le code de votre modèle, situé (/gotm_ismer/src/extras/bio) vous devrez ajouter votre constante mu5 :

Dans la définition des paramètres du module
REALTYPE                  ::  mu5      = 0.1     

Dans la sous-routine init_bio_polynow
  namelist /bio_polynow_nml/ numc, &
                       p_initial,z_initial,b_initial,d_initial,           &
                       l_initial,p0,z0,b0,vp,alpha,k1,k2,mu1,k5,          &
                       gamma,w_p,gmax,k3,beta,mu2,k6,delta,epsi,r1,r2,r3, &
                       vb,k4,mu3,eta,mu4,w_d,mu5,kc,                      &    
                       I_opt,inib,                                        &    
                       theta,w_pmax,w_pmin

Dans la sous-routine do_bio_polynow
     dd(a,n,ci)=mu5*cc(a,ci)

bio_polynow.nml

Il faudra ensuite modifier la namelist bio_polynow.nml et y référencer le taux de nitrification:

Dans la description de la namelist   
!  mu5     = nitrification rate                                  [1/day]    
Dans la liste des paramètres que l'utilisateur spécifie
   mu5     = 0.1

Une fois ces changements effectués, ne pas oublier de re-compiler le modèle.

Exécuter en mode batch

Les scripts batch_airsea.sh et batch_bio.sh permettent de lancer en série plusieurs simulations avec des valeurs de paramètres différents. Le script batch_airsea.sh permet de faire varier les forçages en surface alors que batch_bio.sh permet de varier les paramètres des modèles biologiques. Ils sont situés dans le répertoire gotm_ismer/scripts/shell/.

batch_bio.sh

Ce script prend en argument le nom du modèle biologique sui sera utilisé, tel que spécifié dans bio.nml. Par exemple, si on utilise le modèle de Fasham (bio_model=4), on écrit:

./batch_bio.sh fasham

Si le répertoire gotm_ismer/script/shell est dans votre PATH, vous pouvez appeler le script sans le ./:

batch_bio.sh fasham

Deux fichiers sont nécessaires, bio_$model.mal et gotmrun.mal, qui sont en fait les fichiers namelists qui seront lus par le script pour générer les .nml correspond qui eux seront utilisés par le modèle. Dans gotmrun.mal, le paramètre qui spécifie le nom du fichier de sortie out doit être experiment_name. Dans bio_$model.mal ($model est l'argument du script, e.g. fasham, npzd ou ismer), les paramètres dont on veut varier les valeurs pour chacune des simulation de la batch doivent prendre les valeurs param1, param2, param3, etc. Vous pouvez attribuer ces valeurs à autant de paramètres que vous le voulez. Une fois que ce choix est fait, vous devrez modifier le script batch_bio.sh pour tenir compte de ces choix.

Pour illustrer cette étape, procédons par un exemple. Supposons qu'on veuille faire ving-cinq simulations en variant deux paramètres, vp et alpha qui prendront chacun cinq valeurs différentes. Ceci doit être spécifié de la manière suivante:

# Parameters for the biological model
vp="0.02 0.08 0.24 0.48 0.72"
alpha="0.01 0.04 0.16 0.32 0.48"

Ensuite, il faut ajuster la portion suivante du script afin de respecter le nombre de paramètres:

...
count=0
for a in $vp
do
for b in $alpha
do
count=`expr $count + 1`
count=`expr 000$count | tail -8c`
echo $count
if [ -f bio_fasham.nml ] then
  rm -f bio_fasham.nml
fi
cat bio_fasham.mal | sed \
  -e "s/param1/$a/g" \
  -e "s/param2/$b/g" \
  > bio_fasham.nml
if [ -f bio_fasham.nml ] then
  echo "   bio_fasham.nml created"
fi

if [ -f gotmrun.nml ] then
  rm -f gotmrun.nml
fi
cat gotmrun.mal | sed \
  -e "s/experiment_name/$count/g" \
  > gotmrun.nml
if [ -f gotmrun.nml ] then
  echo "   gotmrun.nml    created"
fi
strt=`date +%H:%M:%S`
echo "   started at "$strt
./gotm_prod_IFORT >& $count.out
end=`date +%H:%M:%S`
echo "   ended   at "$end
done
done
...

Dans cet exemple, le fichier bio_fasham.mal devra contenir les lignes suivantes:

...
vp    = param1
alpha = param2
...

Le script remplacera successivement param1 et param2 par les valeurs spécifiées, écrira la namelist et exécutera le modèle.

batch_airsea.sh

Le script batch_airsea.sh est utile pour lancer un ensemble de simulations avec des fichiers de forçage distincts pour chacune des simulations. Il fonctionne de manière très similaire à batch_bio.sh en remplaçant créant un fichier airsea.nml à partir d'un fichier airsea.mal où les paramètres à remplacer sont les noms des fichiers contenant les différents forçages atmosphériques. Pour cela, il faut d'abord créer ces fichiers. Comme chacune des simulations porte un numéro, il est commode d'inclure un numéro dans le nom du fichier, comme dans l'exemple suivant:

momentum_flux_001.dat
momentum_flux_002.dat
momentum_flux_003.dat
momentum_flux_004.dat
momentum_flux_005.dat
momentum_flux_006.dat
...

De cette manière, la liste des fichiers formées dans la boucle du script sera ordonnée et la simulation 001.nc correspondra au forçage momemtum_flux_001.dat. Le fichier gotmrun.mal doit exister et être configuré tel que décrit dans la section batch_bio.sh.

...
count=0
for file in narr_momentum_*.dat
do
count=`expr $count + 1`
count=`expr 000$count | tail -3c`
echo $count
if [ -f airsea.nml ] then
  rm -f airsea.nml
fi
cat airsea.mal | sed \
  -e "s/heatfile/narr_heatflux_2008_$count/g" \
  > airsea.nml
if [ -f airsea.nml ] then
  echo "   airsea.nml created"
fi
if [ -f gotmrun.nml ] then
  rm -f gotmrun.nml
fi
cat gotmrun.mal | sed \
  -e "s/experiment_name/$count/g" \
  > gotmrun.nml
if [ -f gotmrun.nml ] then
  echo "   gotmrun.nml    created"
fi
strt=`date +%H:%M:%S`
echo "   started at "$strt
./gotm_prod_IFORT >& $count.out
end=`date +%H:%M:%S`
echo "   ended   at "$end
done
...

Cas test

À venir ...

Visualisation des résultats

Pour visualiser les sorties du modèle, le logiciel Ferret constitue une option extrêmement intéressante. Ce programme permet de produire des figures très simplement en tenant compte des méta-données contenues dans les fichiers NetCDF. Pour se familiariser avec le logiciel et obtenir de l'aide, consultez le site [2]. Dans cette section sont présentés des exemples de scripts permettant de visualiser des quantités importantes pour l'interprétation d'une simulation couplée. Les scripts ferret (*.jnl) sont en fait une liste de commandes Ferret qu'on peut exécuter avec la commande suivante:

ferret -gif -script scriptname.jnl

L'option -gif dit à ferret de ne pas afficher les figures à l'écran pendant l'exécution du script. Les figures seront plutôt produites et sauvegardées par la commande

frame/file=figure.gif

qui apparaît dans le script. Voici donc quelques exemples appliqués à une simulation couplée représentant le golfe d'Amundsen avec le modèle biologique de type Fasham et al. (1990).

GOTM - General Ocean Turbulence Model

Sommaire