Index: /trunk/libIGCM/AA_job
===================================================================
--- /trunk/libIGCM/AA_job	(revision 814)
+++ /trunk/libIGCM/AA_job	(revision 815)
@@ -76,5 +76,5 @@
 #-Q- default ## DEFAULT HOST ##
 #-Q- default ##################
-#-Q- default #For MPI use, uncomment next line : 
+#-Q- default #For MPI use, uncomment next line :
 #-Q- default #BATCH_NUM_PROC_TOT=::JobNumProcTot::
 
@@ -101,9 +101,7 @@
 
 #D--------------------------------------------------------------------==
-#D--------------------------------------------------------------------==
 #D-
 #D-                      Job to launch IGCM models
 #D-
-#D--------------------------------------------------------------------==
 #D--------------------------------------------------------------------==
 #D-
@@ -112,14 +110,13 @@
 libIGCM=${MODIPSL}/libIGCM
 
+#D--------------------------------------------------------------------==
+#D- -1. PLACE FOR USER MODIFICATION
+#D-     - Job Verbosity
+#D-     - PeriodNb
+#D-     - Experience type : DEB(ug), DEV(elopment), RUN
+#D--------------------------------------------------------------------==
+
 #D- Task type (computing or post-processing)
-TaskType=computing 
-
-#D--------------------------------------------------------------------==
-#D-                   -1. User modification place
-#D-                      - Job Verbosity
-#D-                      - PeriodNb
-#D-                      - Experience type : DEB(ug), DEV(elopment), RUN 
-#D--------------------------------------------------------------------==
-
+TaskType=computing
 #D- Increased verbosity (1, 2, 3)
 Verbosity=3
@@ -131,70 +128,76 @@
 
 #D-
-# --------------------------------------------------------------------------------------------------#
-#D-                          ! Optionnal features /!\ Use with care !                               #
-# --------------------------------------------------------------------------------------------------#
+#D- --------------------------------------------------------------------------------------------------#
+#D-                          ! OPTIONNAL FEATURES /!\ USE WITH CARE !                                 #
+#D- --------------------------------------------------------------------------------------------------#
 
 
 #D- Low level debug : to bypass lib test checks and stack construction
 #D- Default=true
+#D-
 DEBUG_debug=false
 
 #D- Set DEBUG_sys to false to disable output calls of function
 #D- Default=true
+#D-
 #DEBUG_sys=false
 
 #D- Define running directory
 #D- Default=${TMPDIR} ie temporary batch directory
+#D-
 #RUN_DIR_PATH=/workdir/or/scratchdir/of/this/machine
 
 #D- Define submit directory
 #D- Default= where you launch qsub (variable from scheduler)
+#D-
 #SUBMIT_DIR=$( pwd )
 
 #D- Define input file root directory
 #D- Default=/IGCMG/common/account/of/this/machine
+#D-
 #R_IN=/u/rech/por/rpor111/DATA
 
 #D- Turn in dry run mode ? (0,1,2,3)
 #D- Default=0
+#D-
 #DRYRUN=3
-# YOU HAVE TO COMPILE YOUR EXE FILES to USE DRYRUN MODE !
-# -------------------------------------------------------------------------------------
-# | DRYRUN=  |  Date computations, | sys_Get    |  Exe    | sys_Put_Out; sys_Put_Rest |
-# |          |  Cp/Exe/param/files |            |         |                           |
-# |          |  Chmod Qsub         |            |         |                           |
-# -------------------------------------------------------------------------------------
-# |    0     |       yes           |    yes     |  yes    |      yes                  |
-# -------------------------------------------------------------------------------------
-# |    1     |       yes           |    yes     |  yes    |      no                   |
-# -------------------------------------------------------------------------------------
-# |    2     |       yes           |    yes     |  no     |      no                   |
-# -------------------------------------------------------------------------------------
-# |    3     |       yes           |    no      |  no     |      no                   |
-# -------------------------------------------------------------------------------------
+#D-# YOU HAVE TO COMPILE YOUR EXE FILES to USE DRYRUN MODE !
+#D-# -------------------------------------------------------------------------------------
+#D-# | DRYRUN=  |  Date computations, | sys_Get    |  Exe    | sys_Put_Out; sys_Put_Rest |
+#D-# |          |  Cp/Exe/param/files |            |         |                           |
+#D-# |          |  Chmod Qsub         |            |         |                           |
+#D-# -------------------------------------------------------------------------------------
+#D-# |    0     |       yes           |    yes     |  yes    |      yes                  |
+#D-# -------------------------------------------------------------------------------------
+#D-# |    1     |       yes           |    yes     |  yes    |      no                   |
+#D-# -------------------------------------------------------------------------------------
+#D-# |    2     |       yes           |    yes     |  no     |      no                   |
+#D-# -------------------------------------------------------------------------------------
+#D-# |    3     |       yes           |    no      |  no     |      no                   |
+#D-# -------------------------------------------------------------------------------------
 
 #D-
 # --------------------------------------------------------------------------------------------------#
-#D- ! End of optionnal features /!\ Do not modify anything below unless you know what you are doing #
+#D- ! END OF OPTIONNAL FEATURES /!\ DO NOT MODIFY ANYTHING BELOW UNLESS YOU KNOW WHAT YOU ARE DOING #
 # --------------------------------------------------------------------------------------------------#
 
 #D-
 #D--------------------------------------------------------------------==
-#D-                   0. System Environment 
-#D-                      - Define variables for Number of processors
-#D-                      - Define MPI variables
-#D-                      - Define batch scheduler variables
-#D-                      - Source IGCM Library
-#D-                      - Get RESOLution in .resol file (temporary)
-#D--------------------------------------------------------------------==
-
-#D--------------------------------------------------------------------==
+#D- 0. SYSTEM ENVIRONMENT
+#D-    - Define variables for Number of processors
+#D-    - Define MPI variables
+#D-    - Define batch scheduler variables
+#D-    - Source IGCM Library
+#D-    - Get RESOLution in .resol file (temporary)
+#D--------------------------------------------------------------------==
+
+#---------------------------------------------------------------------==
 
 . ${libIGCM}/libIGCM_debug/libIGCM_debug.ksh
-       ( ${DEBUG_debug} ) && IGCM_debug_Check
+( ${DEBUG_debug} ) && IGCM_debug_Check
 . ${libIGCM}/libIGCM_card/libIGCM_card.ksh
-       ( ${DEBUG_debug} ) && IGCM_card_Check
+( ${DEBUG_debug} ) && IGCM_card_Check
 . ${libIGCM}/libIGCM_date/libIGCM_date.ksh
-       ( ${DEBUG_debug} ) && IGCM_date_Check
+( ${DEBUG_debug} ) && IGCM_date_Check
 #-------
 . ${libIGCM}/libIGCM_sys/libIGCM_sys.ksh
@@ -203,5 +206,5 @@
 . ${libIGCM}/libIGCM_post/libIGCM_post.ksh
 
-#D--------------------------------------------------------------------==
+#--------------------------------------------------------------------==
 
 #-- Resolution FLAG for oasis input
@@ -210,26 +213,20 @@
 #-- Chemistrie FLAG to ease chemistries configurations management
 #CHEM="AER"
-[ -f ${SUBMIT_DIR}/../.chimie ] && eval $(grep CHEM ${SUBMIT_DIR}/../.chimie) 
-
-#D-
-#D--------------------------------------------------------------------==
-#D-           1. INITIALIZE CONFIGURATION AND THEN COMPONENTS
-#D--------------------------------------------------------------------==
+[ -f ${SUBMIT_DIR}/../.chimie ] && eval $(grep CHEM ${SUBMIT_DIR}/../.chimie)
+
+#D-
+#D--------------------------------------------------------------------==
+#D- 1. INITIALIZE CONFIGURATION
+#D-    - Simulation configuration
+#D-    - Simulation parameters
+#D-    - Execution parameter
+#D-    - Define input files directory
+#D-    - Read or initialize CumulPeriod
+#D-    - run.card
+#D---------------------------------------------------------------------==
+IGCM_config_Initialize
 
 # --------------------------------------------------------------------==
-#D- Initialize configuration : 
-#D-              - Simulation configuration
-#D-              - Simulation parameters 
-#D-              - Execution parameter
-#D-              - Define input files directory
-#D-              - Read or initialize CumulPeriod
-#D-              - run.card
-#D-
-# --------------------------------------------------------------------==
-IGCM_config_Initialize
-
-# --------------------------------------------------------------------==
-#D- Define, create and cd RUN_DIR
-#D-  
+# Define, create and cd RUN_DIR
 # --------------------------------------------------------------------==
 RUN_DIR=${RUN_DIR_PATH}/${config_UserChoices_JobName}.${$}
@@ -242,36 +239,37 @@
 IGCM_debug_Verif_Exit
 
-# --------------------------------------------------------------------==
-#D- Initialize each components taking part
-#D- into simulation configuration :
-#D-         - Define component executable
-#D-         - Define Write Frequency by component "1M" "1D" ...
-#D-         - Source ${comp}.driver
-#D-         - Define Storage Places by component
-#D-         - ${comp}_Initialize :
-#D-         - Patterns to sed
-#D-         - Variables from namelist
-#D-
-# --------------------------------------------------------------------==
+#D-
+#D---------------------------------------------------------------------==
+#D- 2. INITIALIZE ALL COMPONENT OF THE CONFIGURATION
+#D-    - Define component executable
+#D-    - Define Write Frequency by component "1M" "1D" ...
+#D-    - Source ${comp}.driver
+#D-    - Define Storage Places by component
+#D-    - ${comp}_Initialize :
+#D-    - Patterns to sed
+#D-    - Variables from namelist
+#D---------------------------------------------------------------------==
 IGCM_comp_Initialize
 
-# --------------------------------------------------------------------==
-#D- Verify compatibility of period length, write frequencies, ...
-#D- Verify compatibility of rebuild choices and post-process choices
-#D- Will stop here if something is wrong
-# --------------------------------------------------------------------==
+#D-
+#D---------------------------------------------------------------------==
+#D- 3. PERFORM GENERAL VERIFICATION
+#D-    - Verify compatibility of period length, write frequencies, ...
+#D-    - Verify compatibility of rebuild choices and post-process choices
+#D-    - Will stop here if something is wrong
+#D---------------------------------------------------------------------==
 IGCM_config_Check
 
 # ------------------------------------------------------------------
-#D- Test if all was right before entering the period loop
+# Test if all was right before entering the period loop
 # ------------------------------------------------------------------
 IGCM_debug_Verif_Exit
 
-#D--------------------------------------------------------------------==
-#D-                  2. ENTER THE DEEP EXECUTION LOOP
-#D-                  !!!! FASTEN YOUR SEAT BELTS !!!!
-#D-                  !!!!!      PLEASE.          !!!!
-#D-                  !! WE WILL CROSS TURBULENCES. !!
-#D--------------------------------------------------------------------==
+#D-
+#D---------------------------------------------------------------------==
+#D- 4. ENTER THE DEEP EXECUTION LOOP
+#D-    ! FASTEN YOUR SEAT BELTS PLEASE. !
+#D-    !   WE WILL CROSS TURBULENCES.   !
+#D---------------------------------------------------------------------==
 
 Period=1
@@ -279,5 +277,5 @@
 PeriodContinue=false
 if [ ${Period} -le ${PeriodNb} ]; then
-    PeriodContinue=true
+  PeriodContinue=true
 fi
 while ( ${PeriodContinue} ) ; do
@@ -288,17 +286,17 @@
   #D-
   # ------------------------------------------------------------------
-  #D- COMPUTE AND DEFINE DATE STUFF.
+  #D-   4.1 COMPUTE AND DEFINE DATE INFORMATION.
+  #D-       - ${PeriodDateBegin}
+  #D-       - ${PeriodDateEnd}
+  #D-       - ${CumulPeriod}
+  #D-       - ${DatesPeriod}=${PeriodDateBegin}_${PeriodDateEnd}
+  #D-       - ${PeriodLength} => JOURS=31 , 28, 29, 30 ; MOIS=0 ; ANS=0
+  #D-       - update run.card value
   # ------------------------------------------------------------------
   IGCM_config_PeriodStart
-  #D- => ${PeriodDateBegin}
-  #D- => ${PeriodDateEnd}
-  #D- => ${CumulPeriod}
-  #D- => ${DatesPeriod}=${PeriodDateBegin}_${PeriodDateEnd}
-  #D- => ${PeriodLength} => JOURS=31 , 28, 29, 30 ; MOIS=0 ; ANS=0
-  #D- => update run.card value
-
-  #D-
-  # ------------------------------------------------------------------
-  #D- BEGIN COMPUTATION ONLY IF NEEDED
+
+  #D-
+  # ------------------------------------------------------------------
+  #D-   4.2 BEGIN COMPUTATION ONLY IF NEEDED
   # ------------------------------------------------------------------
   if [ ${SimulationLengthInDays} -gt ${ExperienceLengthInDays} ] ; then
@@ -309,6 +307,6 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Optionnal function in driver 
-  #D- to set special variables used in forward lists (Param, Init or Bc).
+  #D-   4.3 CALL OPTIONNAL FUNCTION WITHIN DRIVER
+  #D-       - to set special variables used in lists (Param, Init or Bc).
   # ------------------------------------------------------------------
   IGCM_comp_PeriodStart
@@ -316,6 +314,7 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Get parameters text files updated by job (.def, namelist ...)
-  #D- READ AND USE BY GCM AT EACH EXECUTION.
+  #D-   4.4 GET PARAMETERS TEXT FILES UPDATED BY JOB
+  #D-       - (.def, namelist ...)
+  #D-       - READ AND USE BY GCM AT EACH EXECUTION.
   # ------------------------------------------------------------------
   IGCM_comp_GetInputParametersFiles
@@ -323,8 +322,9 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Get initial state (Etat0, carteveg,relief...)
-  #D- NECESSARY ONLY IF CumulPeriod= (=> NUMERO) == 1
-  #D- AND ???_Restart=NO
-  #D- READ AND USE BY GCM FOR ONLY ONE EXECUTION.
+  #D-   4.5 GET INITIAL STATE
+  #D-       - (Etat0, carteveg,relief...)
+  #D-       - NECESSARY ONLY IF CumulPeriod= (=> NUMERO) == 1
+  #D-       - AND ???_Restart=NO
+  #D-       - READ AND USE BY GCM FOR ONLY ONE EXECUTION.
   # ------------------------------------------------------------------
   IGCM_comp_GetInputInitialStateFiles
@@ -332,6 +332,7 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Get Boundaries Conditions (SST, WIND[X,Y,Z], LAI ...)
-  #D- READ AND USE BY GCM AT EACH EXECUTION.
+  #D-   4.6 GET BOUNDARIES CONDITIONS
+  #D-       - (SST, WIND[X,Y,Z], LAI ...)
+  #D-       - READ AND USE BY GCM AT EACH EXECUTION.
   # ------------------------------------------------------------------
   IGCM_comp_GetInputBoundaryFiles
@@ -339,34 +340,37 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Get SmoothFiles Conditions (SST, WIND[X,Y,Z], LAI ...)
-  #D- READ AND USE BY GCM AT EACH EXECUTION but varying in time
-  # ------------------------------------------------------------------
-  IGCM_comp_GetInputSmoothFiles 
-
-  #D-
-  # ------------------------------------------------------------------
-  #D- Get restart files (restartphy.nc, orca_restart.nc ...)
-  #D- READ AND USE BY GCM AT EACH EXECUTION.
-  #D-
-  #D- IF A COMPONENT DO NOT RESTART FROM PREVIOULSY COMPUTED RESTART
-  #D- ONLY IF CumulPeriod= (=> NUMERO) == 1
-  #D- MUST EXECUTE CREATE ETAT0_LIMIT (TYPICALLY LMDZ AND ./create_etat0_limit.e)
-  #D-
-  #D- IF CumulPeriod == 1
-  #D- AND A COMPONENT RESTART FROM PREVIOULSY COMPUTED RESTART
-  #D- MUST BRING THIS RESTART IN ${RUN_DIR_PATH}
-  #D-
-  #D- ELSE BRING RESTART FROM ${JobName} IN ${RUN_DIR_PATH}
+  #D-   4.7 GET SmoothFiles CONDITIONS
+  #D-       - (SST, WIND[X,Y,Z], LAI ...)
+  #D-       - READ AND USE BY GCM AT EACH EXECUTION
+  #D-       - Do not change at each ${Period}
+  # ------------------------------------------------------------------
+  IGCM_comp_GetInputSmoothFiles
+
+  #D-
+  # ------------------------------------------------------------------
+  #D-   4.8 GET RESTART FILES
+  #D-       - (restartphy.nc, orca_restart.nc ...)
+  #D-       - READ AND USE BY GCM AT EACH EXECUTION.
+  #D-
+  #D-       - IF A COMPONENT DO NOT RESTART FROM PREVIOULSY COMPUTED RESTART
+  #D-       - ONLY IF CumulPeriod= (=> NUMERO) == 1
+  #D-       - MUST EXECUTE CREATE ETAT0_LIMIT (TYPICALLY LMDZ AND ./create_etat0_limit.e)
+  #D-
+  #D-       - IF CumulPeriod == 1
+  #D-       - AND A COMPONENT RESTART FROM PREVIOULSY COMPUTED RESTART
+  #D-       - MUST BRING THIS RESTART IN ${RUN_DIR_PATH}
+  #D-
+  #D-       - ELSE BRING RESTART FROM ${JobName} IN ${RUN_DIR_PATH}
   # ------------------------------------------------------------------
   IGCM_comp_GetInputRestartFiles
 
-  #D-
-  # ------------------------------------------------------------------
-  #D- Test if all was right before Update
+  # ------------------------------------------------------------------
+  # Test if all was right before Update
   # ------------------------------------------------------------------
   IGCM_debug_Verif_Exit
 
-  # ------------------------------------------------------------------
-  #D- Activate running environnement variables
+  #D-
+  # ------------------------------------------------------------------
+  #D-   4.9 ACTIVATE RUNNING ENVIRONNEMENT VARIABLES
   # ------------------------------------------------------------------
   IGCM_sys_activ_variables
@@ -374,19 +378,19 @@
   #D-
   # ------------------------------------------------------------------
-  #D- UPDATE ParametersFiles (.def, namelist ...) with 
-  #D- current value of (ORCA_NIT00, ORCA_LRSTAR, RAZ_DATE, ...)
+  #D-   4.10 UPDATE ParametersFiles
+  #D-        - (.def, namelist ...)
+  #D-        - with current value of (ORCA_NIT00, ORCA_LRSTAR, RAZ_DATE, ...)
   # ------------------------------------------------------------------
   IGCM_comp_Update
 
-  #D-
-  # ------------------------------------------------------------------
-  #D- Test if all was right before execution
+  # ------------------------------------------------------------------
+  # Test if all was right before execution
   # ------------------------------------------------------------------
   IGCM_debug_Verif_Exit
 
   #D-
-  #D----------------------------------------------------------------==
-  #D-                          3. Execution
-  #D----------------------------------------------------------------==
+  #D---------------------------------------------------------------------==
+  #D- 5. EXECUTION
+  #D---------------------------------------------------------------------==
 
   echo
@@ -439,24 +443,24 @@
 
   #D-
-  # ------------------------------------------------------------------
-  #D- Desactivate running environnement variables
+  #D---------------------------------------------------------------------==
+  #D- 6. POST EXECUTION OPERATIONS
+  #D---------------------------------------------------------------------==
+
+  #D-
+  # ------------------------------------------------------------------
+  #D-   6.1. DESACTIVATE RUNNING ENVIRONNEMENT VARIABLES
   # ------------------------------------------------------------------
   IGCM_sys_desactiv_variables
 
   #D-
-  #D----------------------------------------------------------------==
-  #D-                    4. Post execution operations
-  #D----------------------------------------------------------------==
-
-  #D-
-  # ------------------------------------------------------------------
-  #D- Save on archive machine netcdf outputs, restarts
-  #D- and text files of models
+  # ------------------------------------------------------------------
+  #D-   6.2. SAVE OUTPUTS
+  #D-        - On archive/storage machine
+  #D-        - netcdf outputs, restarts and text files of models
   # ------------------------------------------------------------------
   IGCM_comp_Finalize
 
-  #D-
-  # ------------------------------------------------------------------
-  #D- Test if all was right after Finalize
+  # ------------------------------------------------------------------
+  # Test if all was right after Finalize
   # ------------------------------------------------------------------
   IGCM_debug_Verif_Exit
@@ -464,6 +468,7 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Configure asynchronous post-treatment (Level 0) when necessary (rebuild)
-  #D- Configure classic post-treatment (Level 1) when necessary (TimeSeries/Seasonal)
+  #D-   6.3. CONFIGURE POST-PROCESSING
+  #D-        - asynchronous post-treatment (Level 0) when necessary (rebuild/pack)
+  #D-        - classic post-treatment      (Level 1) when necessary (TimeSeries/Seasonal)
   # ------------------------------------------------------------------
   IGCM_post_Configure
@@ -471,5 +476,6 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Launch remote rebuild or/and post-treatment process if necessary
+  #D-   6.4. SUBMIT POST-PROCESSING
+  #D-        - remote rebuild or/and post-treatment process if necessary
   # ------------------------------------------------------------------
   IGCM_post_Submit
@@ -477,9 +483,9 @@
   #D-
   # ------------------------------------------------------------------
-  #D- Save job output
-  #D- Manage executable size to save only different binary
-  #D- Write in run.card user, system and elapse time
-  #D- Check that everything went well ! No ? then we stop.
-  #D- Determine next computed period
+  #D-   6.5. FINALYZE CURRENT LOOP AND PREPARE NEXT ONE
+  #D-        - Manage executable size to save only different binary
+  #D-        - Write in run.card user, system and elapse time
+  #D-        - Check that everything went well ! No ? then we stop.
+  #D-        - Determine next computed period
   # ------------------------------------------------------------------
   IGCM_config_PeriodEnd
@@ -500,7 +506,7 @@
 
 #D-
-#D--------------------------------------------------------------------==
-#D-     5. Submit next job or send mail if simulation over.
-#D--------------------------------------------------------------------==
+#D---------------------------------------------------------------------==
+#D- 7. SUBMIT NEXT JOB OR SEND MAIL IF SIMULATION IS OVER.
+#D---------------------------------------------------------------------==
 IGCM_config_Finalize
 
