Changes between Initial Version and Version 1 of Branches/Assimilation/Implementation

Timestamp:

2013-03-27T12:29:57+01:00 (11 years ago)

Author:

mmaipsl

Comment:

--

Branches/Assimilation/Implementation

@@ +1 @@
+
+== Utlisation d'ORCHIDEE pour l'assimilation ==
+
+== 1. Contexte ==
+
+Pour l'assimiltion des données avec le modèle ORCHIDEE (e.g., carbone, flux de surface,  etc..), le différentiateur automatique TAF est utilisé. 
+TAF ne permettant pas la dérivation des sources de la version standard d'ORCHIDEE, un travail préalable important a été effectué. Ce travail permet de rendre le 
+code ORCHIDEE compatible à TAF. En effet, pour TAF, un modèle (ici ORCHIDEE) doit lui être passé comme une fonction/subroutine ayant pour arguments d'entrée 
+le nombre de paramètres pour lesquels on cherche à calculer les sensibilités (on appelera par la suite les paramètres à optimiser), le vecteur décrivant les valeurs de ces paramètres et en 
+sortie la fonction coût calculée sur les variables auxquelles dépendent ces paramètres. Afin donc de rendre ORCHIDEE compatible pour TAF et aussi de minimiser 
+ces développements lors de nouvelles mises à jour d'ORCHIDEE, nous avons: 
+ -  crée de nouveaux drivers/modules qui permetlent de gérer les paramètres 
+ -  mis au format les subroutines/fonctions d'ORCHIDEE standard pour TAF de façon automatique à partir d'un script shell. 
+
+ 
+L'objectif de ce document est de lister dans un premier temps (point 2 ci-après) les actions qu'un utilisateur aura à effectuer pour mettre au format une version d'ORCHIDEE pour TAF, autrement dit pour 
+la génération des codes dérivés (i.e., tangent linéaire et adjoint) pour l'assimilation. Ensuite, nous décrivons en détails les nouveaux drivers/modules 
+développés ainsi que les différentes étapes pour la mise au format automatique du code ORCHIDEE standard respectivelment aux points 3 et 4. 
+Enfin, nos questions et réflexions pour une amélioration de cette procédure de la mise en compatibilité du code ORCHIDEE pour TAF sont présentées au point 5.
+
+
+
+== 2. Actions pour la mise au format d'ORCHIDEE pour l'assimilation == 
+
+
+== ''2.1: Note importante''   ==
+Pour la mise au format d'ORCHIDEE pour TAF, les modules d'initialisation/allocation dans les répertoires sechiba (i.e., sechiba_init_alloc.f90) et stomate (stomate_init_alloc.f90) d'ORCHIDEE sont automatiquement générés.
+La création automatique de ces deux modules permet de considérer aisément toutes mises à jour d'ORCHIDEE pour l'assimilation sans un travail supplémentaire important. Pour la création de ces modules d'initialisation/alloctaion, 
+nous avons mis dans chaque module dans ces répertoires après la commande CONTAINS, la liste des subroutines/fonctions qui ont un lien avec les fichiers d'initislisation. 
+La nomemclature adoptée est donnée ci-après pour le cas de la subroutine routing.f90 dans ORCHIDEE/src_sechiba:
+{{{
+! List of subroutines for initialization :
+!- routing_init
+!- routing_clear
+!- routing_diagnostic_p
+!- routing_diagnostic
+!- routing_basins_p
+!- routing_basins
+!- routing_getgrid
+!- routing_sortcoord
+!- routing_findbasins
+!- routing_simplify
+!- routing_cutbasin
+!- routing_hierarchy
+!- routing_findrout
+!- routing_globalize
+!- routing_linkup
+!- routing_fetch
+!- routing_truncate
+!- routing_killbas
+!- routing_names
+!- routing_irrigmap
+}}}
+   
+Il faut noter que désormais les tags/trunk d'ORCHIDEE comprennent déjà cette liste. Ainsi, s'il y a des ajouts de subroutines/fonctions dans de nouveaux modules d'ORCHIDEE qui ont un lien 
+avec les modules d'initialisation/allocation, il faut les ajouter à liste existante ou créer cette liste dans les nouveaux modules concernés. 
+
+
+
+== '' 2.2: Mise au format d'ORCHIDEE pour TAF et/ou exécution des codes obtenus '' == 
+ L'utilsateur doit exécuter les commandes décrites dans les 3 étapes suivantes pour avoir un code mis au format pour l'assimilation. 
+
+    === Etape 1 : Chargement des routines d’ORCHIDEE/IOIPSL/TAF pertinents pour l’optimisation ===
+
+       - lancer la commande model dans le répertoire util pour le code ORCHIDEE que vous souhaitez utiliser pour l'assimilation. On note $model-name cette configuration (Tapez model -h pour avoir la liste 
+des modèles disponibles). Lancer donc:
+ 
+        {{{
+        util> model -h $model-name
+        }}}   
+       - Récupérer le tags d'IOIPSL que vous souhaitez   
+       - Récupérer le tags/trunk d'ORCHIDEE que vous souhaitez         
+       - Récupèrer éventuellement un tag/trunk d'ORCHIDEE_OL. Seul le fichier weather.f90 sera utilisé.
+           - Déplacer le fichier weather.f90 dans le répertoire ASSIMILATION (EK: A faire automatiquement par makeorchidee_fcm ???)
+       - Mettre le répertoire NETCDF contenant les fichiers NetCDF dont TAF a besoin dans le répertoire ASSIMILATION (EK: comment faire pour avoir ce répertoire pour tout le monde !!!!)
+ 
+
+ === Etape 2: Mise au format du tag/trunk d'ORCHIDEE pour TAF  ===
+    Deux principales taches sont effectuées par un script shell '''makeorchidee_fcm''':
+        - la mise au format du tags/trunk d'ORCHIDEE pour TAF 
+        - le regroupement de tous les codes (i.e., ORCHIDEE, IOPSL), les nouveaux drivers/modules crées pour TAF et la subroutine weather.f90 dans ORCHIDEE_OL dans le répertoire ASSIMILATION 
+ 
+   Pour cela, il faut: 
+     - Aller dans le répertoire ORCHIDEE et exécuter: 
+      {{{
+      ORCHIDEE> makeorchidee_fcm -[d]optim 
+      }}} 
+     avec [d] pour debug.[[BR]]
+      Le script makeorchidee_fcm qui est décrit plus en détails au point 4) : 
+        - Crée un répertoire de travail temporaire modeles_optim_temp à partir du répertoire ASSIMILATION 
+        - Met le répertoire ORCHIDEE dans modeles_optim_temp
+        - Crée les fichiers d'initialisation/allocation dans ORCHIDEE/src_sechiba et ORCHIDEE/src_stomate   
+        - Met dans le répertoire ASSIMILATION toutes les sources de tous les répertoires d'ORCHIDEE dans modeles_optim_temp  
+        - Met dans le répertoire ASSIMILATION toutes les sources du répertoire IOPSL 
+
+
+=== Etape 3 : Application de TAF pour la dérivation des codes === 
+Toutes les sources des codes pour l'assimilation sont désormais dans le répertoire ASSIMILATION. 
+Se placer dans le répertoire ASSIMILATION pour effectuer la différentiation souhaitée.On note tangent linéaire (TL), tangent linéaire vectoriel (VTL), et adjoint (AD). Assurez-vous que vous avez le droit d'exécuter le script staf de TAF pertinent pour la différentiation.
+Dans le cas échéant, contacter la personne en charge du code pour l'assimilation pour faire le nécessaire.
+Le Makefile dans le répertoire ASSIMILATION permet d'effectuer ces actions ci-dessous (pour détails, l'éditer):
+    - Si vous souhaitez avoir juste les codes dérivés par TAF pour:
+         - le tangent linéaire TL dont les sources portent l'extension _tl.f90, lancer:   
+           {{{
+           gmake ctl
+           }}}
+         - le tangent vectoriel VTL dont les sources portent l'extension _vtl.f90, lancer:
+           {{{
+           gmake cvtl
+           }}}
+         - l'adjoint AD dont les sources portent l'extension _ad.f90, lancer :
+           {{{
+           gmake cadj  (n'existe pas encore!!!)
+           }}}
+           Les codes dérivés sont mis dans le répertoire spécifique relatif à la différentiation que vous souhaitez faire:
+            - TANGEANT pour les codes TL avec extension _tl.f90 
+            - TANGEANT_VTL pour les cdoes VTL avec extension _vtl.f90 
+            - ADJOINT pour les codes AD avec extension _ad.f90 
+        
+
+   - Si voulez compiler les codes d'ORCHIDEE mis au format TAF en mode direct (i.e., l'exécutable doit donner les mêmes résultats que le code ORCHIDEE standard), lancer:
+    {{{
+    gmake 
+    }}}
+     L'exécutable s'appelle orchidee_tl et se trouve dans le répertoire bin 
+
+
+   - Si vous souhaitez générer à la fois les codes dérivés par TAF et/ou les compiler pour:
+         - le tangeant linéaire TL (exécutable orchidee_tl mis dans le répertoire bin et les codes dérivés sont (ou seront mis) dans TANGEANT)), lancer: 
+          {{{
+          gmake tl 
+          }}}  
+         - le tangent vectoriel VTL (exécutable orchidee_vtl dans le répertoire bin et les codes dérivés sont (ou seront mis dans TANGEANT_VTL)), lancer: 
+         {{{
+         gmake vtl
+         }}}
+         - l'adjoint AD (exécutable orchidee_adj !!! dans le répertoire bin), lancer: 
+         {{{
+         gmake adj  ( n'existe pas encore !!!)
+         }}}
+
+        Pour plus détails, voir le Makefile dans le répertoire ASSIMILATION
+
+ 
+
+== 3. Description des nouveaux drivers/modules pertinents pour la dérivation du code d'ORICHIDEE par TAF et son exécution ==
+
+Le logiciel TAF n’est pas capable de générer les codes dérivés d’ORCHIDEE sans une mise au format du code ORCHIDEE au préalable. Comme mentionné au poin 1., il faut passer
+à TAF une subroutine/fonction appelée e.g., model(n,x,f) avec n et x les arguments d'entrée et f étant l'argurment de sortie. On note: 
+n, le nombre de paramètres pour lesquels on veut calculer les sensibilités,  x, le vecteur décrivant les valeurs des paramètres  et f, la fonction coût construite sur les variables 
+du modèle auxquelles dépendent ces paramètres. 
+ 
+Pour ORCHIDEE, nous avons développé le modèle model(n,x,f) à passer à TAF en se basant sur le programme principal d'ORCHIDEE dim2_driver.f90 et qui s'appelle: 
+{{{
+model.f90  (EK: A changer de nom ou OK??? )
+}}}
+  La subroutine model.f90 permet d'effectuer grosso modo les opérations suivantes:
+    - Allocation et/ou initialisation de la plupart des variables SAVE d'ORCHIDEE à partir du module:     
+    {{{
+    init_model.f90 ( A voir si on modifie ce nom !!)
+    }}}
+    - Simulation d'ORCHIDEE en bouclant sur le temps par appel à:  
+    {{{
+    intersurf_main_2D du module intersurf.f90 
+    }}}
+   - Calcul de la fonction coût à la fin de la boucle de temps à partir du module: 
+    {{{
+    mo_cost.f90
+    }}}
+
+La subroutine model.f90 que l'on doit passer à TAF doit avoir au moins en entrée n le nombre de paramètres à optimiser et leurs valeurs 
+mises dans un vecteur x. Le code ORCHIDEE dans sa forme standard n'est pas conçue de cette façon. En effet, les paramètres sont utilisés en dur dans 
+les différéntes subroutines/fonctions du modèle. Nous avons donc crée de nouveaux modules qui permettent d'avoir des informations sur les paramètres nécessaires 
+à fournir à model.f90. Ces modules qui sont décrits ci-après et qui sont mis dans le répertoire ASSIMILATION, permettent:
+ - d'avoir des informations sur le dimensionnement de la simulation du modèle ORCHIDEE, i.e., dimensions temporelle et spatiale
+ - d'avoir des informations sur le nombre de paramètres d'ORCHIDEE à optimiser  
+ - de mettre les valeurs des paramètres d'ORCHIDEE avec leurs noms spécifiques dans un vecteur 
+ - de remettre les valeurs des paramètres mis dans le vecteur aux noms des paramètres tels que décrits dans ORCHIDEE 
+
+Les modules relatifs à ces opérations ci-dessus sont décrites aux points a-c. D'autres modules qui sont plus spécifiques soit pour TAF ou pour 
+la compilation du code mis au format TAF sont détaillés au point d. Il faut également noter que certains de ces modules ont été développés par François Delage et Cedric Bacour (i.e., *_optim.f90)
+
+
+
+a) Informations sur le dimensionnement de la simulation d'ORCHIDEE
+
+Nous avons créé un nouveau module basé sur le module readdim2.f90 d'ORCHIDEE standard. Ce nouveau module s'appelle:
+{{{
+mo_process.f90   (nom sans doute à changer !!!)
+}}}
+
+
+b) Informations sur les paramètres d'ORCHIDEE à optimiser
+
+Les modules suivants ont été développés pour:
+  - l'initialisation des constantes et des paramètres pour l'optimisation
+  {{{
+  constantes_optim.f90
+  parameters_optim.f90 
+  }}}
+  - l'interfaçage des paramètres à optimiser avec le code d'ORCHIDEE   
+  {{{
+   interface_optim.f90   
+  }}}
+
+c) Information sur le nombre de paramètres et la mise en vecteur des paramètres pour TAF/ORCHIDEE (vice/versa)
+
+Pour l'accès au nombre de paramètres, la mise en vecteur de leurs valeurs, nous avons développé le module suivant: 
+{{{
+paramtransfo.f90
+}}}
+Ce module permet également de remettre les valeurs des paramètres du vecteur aux noms des paramètres dans ORCHIDEE.
+
+
+d) Autres modules pour l'exécution d'ORCHIDEE mis au format pour TAF [[BR]]
+Pour la construction des exécutables du code ORCHIDEE mis au format pour TAF en mode direct et/ou des codes dérivés (i.e., TL, VTL, AD), 
+nous avons développé de nouveaux modules: 
+
+ - Appel des subroutines/fonctions pour les initialisations des paramètres (nombre et vecteur) par  
+{{{
+initparam.f90
+}}}
+
+
+ - Compilation des différents codes:
+    - Code direct, i.e., ORCHIDEE standard mis au format pour TAF: 
+    {{{
+     direct.f90
+    }}}
+    - Code tangeant linéaire (TL):
+    {{{
+      tangeant.f90
+    }}}
+    - Code tangent linéaire vectoriel (VTL):
+    {{{
+    tangeant_vtl.f90
+    }}} 
+    - Code adjoint 
+    {{{
+    adjoint.f90  (N'existe pas encore !!!=)
+    }}}
+ 
+
+== 4. Description de la mise en format automatique du code ORCHIDEE pour l'assimilation par le script makeorchidee_fcm  ==
+ 
+Dans le but de profiter des développements futurs d’ORCHIDEE pour l’assimilation des données, nous avons développé des outils de transformation (scripts shell) 
+pour la mise au format automatique du code d’ORCHIDEE pour TAF. La démarche pour cette mise au format se fait en trois étapes suivantes et ces différentes 
+étapes sont effectuées en une seule fois par l'utilisateur par le ancement du sccript makeorchidee_fcm dans le répertoire ORCHIDEE (voir point 2.2): 
+{{{
+ORCHIDEE> makeorchidee_fcm -[d]optim 
+}}}
+Toutes les opérations effecutées par ce script sont détaillées en trois étapes:
+
+=== Etape 1 : Chargement des routines d’ORCHIDEE/IOIPSL/TAF pertinents pour l’optimisation que l'on veut réaliser  ===
+  - Crée un répertoire de travail temporaire modeles_optim_temp à partir du répertoire ASSIMILATION
+  - Met le répertoire d’ORCHIDEE dans le répertoire modeles_optim_temp 
+
+
+=== Etape 2 : Préparation des routines d’ORCHIDEE pour la mise au format pour TAF  ===
+
+makeorchidee_fcm se place dans modeles_optim_temp:
+ - configure le Makefile pour enlever les pré-compilations PARALLEL et ASSIMIL (EK: Pas clair si c'est fait ici !!)
+ - Crée les modules d’allocation/initialisation dans les répertoires où existe un fichier init_alloc. Ce nouveau fichier s’appelle ${rep}_init_alloc.f90 (par exemple sechiba_init_alloc.f90) et la procédure pour sa création est décrite dans l'étape suivante 3 : 
+ 
+
+===  Etape 3 : Création des routines pour TAF === 
+
+Boucler sur le/les fichiers sources de chaque répertoire deux fois avec deux scripts awk 
+ - script 1 : ASSIMILATION/TOOLS/variables.awk 
+    - Avant IMPLICIT NONE : 
+      - Garder les USE dans le fichier $rep_init_alloc  ( => à voir ... )
+    - Entre IMPLICIT NONE et CONTAINS :
+      - Garder les INTERFACE. Gestion particulière ? En effet, TAF n’arrive pas à les gérer proprement sans l’utilisation de directives. En particulier, la gestion des INTERFACE des codes IOIPSL se fait via le fichier taf_directives.f90 qui est inclus dans model.f90 et dans le Makefile dans ASSIMILATION
+      - Couper les variables globales SAVE. Mettre ces variables dans le fichier $rep_init_alloc.Il faut noter que pour l’assimilation, toutes ces variables sont désormais PUBLIC.     
+    - Couper les variables SAVE locales (dans les subroutines/fonctions) dans les fichiers $rep_init_alloc du répertoire traité.
+    - Mettre ces variables dans le fichier $rep_init_alloc. Aussi, toutes ces variables sont désormais PUBLIC.
+     Attention à se conformer à la règle de programmation pour éviter la redondance !!!. (EK: Pour cela, on pourrait remplacer les variables locales "var" par $nommodule_nomfonction_var). En effet, on met des variables "var" locales à une fonction "nomfonction" depuis un module "nommodule" en SAVE global dans $rep_init_alloc. Le risque ici c'est d'avoir des noms $nommodule_nomfonction_var trop longs !!!
+    - Ajouter CONTAINS à la suite dans le fichier $rep_init_alloc       
+
+ - script 2 : ASSIMILATION/TOOLS/subroutines.awk
+   - Lire la phrase " List of subroutines for initialization :" » et construire un tableau init_functions qui lit chaque ligne commençant par "!-". Voir un exemple de cette liste pour routing.f90 au point 2.1.
+   - Couper les fonctions init dans init_alloc pour inclusion dans $rep_init_alloc
+   - Gérer/simplifier les appels du module d'optimisation depuis intersurf.f90 (A discuter ???)
+   - Retravailler les parties driver/readdim2.f90 pour rendre plus rapide cette partie pour l'initialisation (EK ???) 
+   - Copier toutes les  sources de modeles_optim_temp dans le répertoire ASSIMILATION 
+   - Supprimer modeles_optim_temp  
+
+
+ == 5. Questions et Réflexions == 
+   - Il faudra dans les tags/trunk ORCHIDEE : construire et maintenir de la liste des subroutines/fonctions d’initialisation par module (pas d'autres implications des développeurs "standard" 
+     pour conserver les optimisations dans les futures développements) 
+ 
+   
+   - Gestion des « includes » des directives TAF: Il faut noter que cela se fait dans model.f90 et dans le Makefile du répertoire ASSIMILATION. Néanmoins, les directives TAF doivent être spécifiques à chaque version d'ORCHIDEE pour l’optimisation et aussi à la version de IOIPSL. Ce n'est pas simple de gérer automatiquement ces directives TAF parce qu'on n'a pas trouvé de façon claire les raisons pour lesquelles certaines variables SAVE ou fonctions/subroutines ne sont pas analysées par TAF. Pour l'instant, nous gérons ces directives à la main dans le fichier taf_directives.f90 et ceci en fonction des problèmes rencontrés lors de l'exécution des codes dérivés générés par TAF. On pourrait faire une gestion automatique en appliquant des directives à toutes les fonctions/subroutines dans le fichier taf_directives.f90 !!! A titre d'exemple, voici ci-après les directives pour le cas simple de la subroutine ymds2ju du module calendar.f90 de la librairie IOIPSL. Il faut noter que sans ces directives, TAF ne considère pas l'appel de la subroutine ymds2ju dans le code dérivé e.g., model_tl.f90. On note les numéros des arguments d'entrée de la subroutine dans la commande INPUT et dans OUTPUT ceux des arguments de sortie. Enfin, la commande REQUIRED permet de dire à TAF de considérer cette subroutine lors de la génération des codes dérivés. Après une analyse approfondie de ce cas, nous n'avons pas compris les raisons pour lesquelles TAF ne considère pas cette subroutine dans le code dérivé model_tl.f90. Pour plus de détails sur les directives TAF, il faut consulter la documentation d'utilisation du logiciel qui est fourni. 
+{{{
+!$TAF SUBROUTINE calendar::ymds2ju INPUT  = 1,2,3,4
+!$TAF SUBROUTINE calendar::ymds2ju OUTPUT = 5
+!$TAF SUBROUTINE calendar::ymds2ju REQUIRED
+}}}  
+
+   - Gestion de l’interdépendance des USE: On considère actuellement tous les USE dans chaque modules/subroutines/fonctions. Dans la configuration actuelle, il y peut avoir une redondance des USE. En effet, un module appelant déjà un USE est appelé en USE avec les appels des USE qui sont dans ce module. A titre d'exemple, le module iopsl appelle en USE certains modules et souvent le module ioipsl est appelé en USE avec certains des modules de iopsl. Difficile à gérer automatiquement, mais cela peut être géré lors de la programmation !!
+              
+   - Gestion des INTERFACE: TAF n'arrive pas à les gérer donc on les gère à la main dans le fichier taf_directives.f90 ou on considère directement dans le code ORCHIDEE la subroutine/fonction qui est effectivement utilisée pour l'assimilation. A titre d'exemple, on a remplacé l'INTERFACE suivante:
+    {{{
+    INTERFACE intersurf_main
+    MODULE PROCEDURE intersurf_main_2d, intersurf_main_1d, intersurf_gathered, intersurf_gathered_2m
+    END INTERFACE
+    }}}
+     par l'expression suivante ou la subroutine intersurf_main_2d qui est principalement utilisée dans model.f90 lors de l'assimilation est rendue PUBLIC:
+    {{{
+   PUBLIC :: intersurf_main_2d, stom_define_history, intsurf_time, intsurf_restart,l_first_intersurf
+    }}}
+       
+ 
+   - les sources NetCDF: TAF a besoin de certaines sources NEtCDF. On met ces sources dans le répertoire ASSIMILTION/NETCDF tel que décrit au point 2.2. Pour leurs utilisations par TAF, voir le Makefile dans le répertoire ASSIMILATION. Voici la liste de ces sources:
+    {{{
+    netcdf_attributes.f90
+    netcdf_dims.f90
+    netcdf_expanded_modif.f90
+    netcdf.f90
+    netcdf_overloads.f90
+    netcdf_text_variables_modif.f90
+    netcdf_visibility.f90
+    netcdf_constants.f90
+    netcdf_expanded.f90
+    netcdf_externals.f90
+    netcdf_file.f90
+    netcdf_text_variables.f90
+    netcdf_variables.f90
+    typeSizes.f90
+    }}}  
+   Comment gérer ces sources NetCDF? Les commettre ??
+
+   - Gestion de  la liste des modules. La faire dans le AA_make du répertoire ASSIMILATION ?
+   - Conformité aux règles de programmation ???
+   - Unicité des variables dans les différents modules ???
+
+
+
+== 6. Autres == 
+Afin de pouvoir appeler model.f90 plusieurs fois dans une boucle FORTRAN et ceci dans la perspective d'une optimisation dans un environnement FORTRAN, des adapations on été faites dans les sources de IOIPSL. Ces adapations qui sont déjà dans le tags/trunk d'IOIPSL ont été principalement effectuées dans:
+les modules suivants:
+{{{
+histcom.f90   
+flincom.f90
+}}}
+
+Cela a permis de fermer les fichiers et de reinitialiser les variables liées à ces fichiers à la fin d'un appel de la subroutine model.f90. Ceci est obtenu par appel des subroutines histclo et flinclo à la fin de model.f90. Il faut noter que histclo et flinclo sont dans les modules histcom.f90 et flincom.f90, respectivement. 
+Commentaires EK; Martial, n'hésite pas à y ajouter d'autres adaptations effectuées. 
+
+[[BR]]
+[[BR]]
+
+