Index: /NEMO/branches/2019/fix_sette_ticket2239/README
===================================================================
--- /NEMO/branches/2019/fix_sette_ticket2239/README	(revision 10818)
+++ /NEMO/branches/2019/fix_sette_ticket2239/README	(revision 10819)
@@ -1,98 +1,78 @@
 usage of SETTE package:
 
+INSTALLATION:
+The sette directory have to be located in the main directory (at the same level as src/ or cfg/).
+
 PRINCIPAL SCRIPT: sette.sh 
- * sette.sh is a simple wrapper running test on the reference configuration, test cases and generate the report at the end.
- * sette.sh is able to take a list of configuration in argument (sette.sh -t "CFG1 CFG2 CFG3"). The list of available configurations is available in running ./sette_list_avail_cfg.sh.
-   The default for sette is to run all of the reference and test configurations.
- * User need to set up the param.cfg file correctly and download input file before running the script.
+ * sette.sh is a simple wrapper that runs tests on the reference configurations, test cases and generates the report at the end.
+ * sette.sh is able to take a list of configurations in argument (sette.sh -t "CFG1 CFG2 CFG3"). 
+       - The list of available configurations is available in running ./sette_list_avail_cfg.sh.
+       - The default for sette is to run all of the reference and test configurations.
+ * Users need to set up the param.cfg file correctly and download input files before running the script.
 
 SECONDARY SCRIPT
  * sette_reference-configuration.sh: run sette tests on the reference configurations
  * sette_test-cases.sh             : run sette tests on test cases
- * sette_rpt.sh                    : generate the sette report on reproducibility, restartability and compare result with a reference (if there is one specified in param.cfg). 
-                                     See below in USER MODIFICATIONS the usage of the script
- * sette_list_avail_rev.sh         : generate a listing on all the revision available in the validation directory for each configuration.
+ * sette_list_avail_rev.sh         : generate a listing on all the revisions available in the validation directory for each configuration.
  * sette_list_avail_cfg.sh         : generate a listing of all the available configurations.
 
-VERY IMPORTANT : for a verbose debug do:
-./sette.sh 2>&1 | tee out.sette
-this create out.sette file in ${SETTE_DIR}
-
-USER MODIFICATIONS
- * in sette_reference-configuration.sh and sette_test-cases.sh script :
-               OPTIONAL ARGUMENT : compiler among those available in NEMOGCM/ARCH (if nothing will use the one specified in paramd.cfg)
-	       BATCH_COMMAND_PAR : command for job submission in batch mode parallel (MMIÂ) specified in param.cfg
-	       BATCH_COMMAND_SEQ : command for job submission in batch mode sequential (NB_PROC = 1)
-                                   default value is the BATCH_COMMAND_PAR value
-	       INTERACT_FLAG : "yes" if you want to run in interactive mode 
-	       		       "no" if you want to run in batch mode
-	       MPIRUN_FLAG   : "yes" if you want to run in parallel (MPI)
-			       "no" if you want to run in sequential mode (NB_PROC = 1)
-
-               makenemo -m : machine (compilator); see ./makenemo -m help (in NEMOGCM/CONFIG directory)
-                        -n : config name (in examples config_name_nproci_nprocj), see ./makenemo -n help
-                        -r : reference configuration (if you don't give it you have to choise directories to install)
-                        add_key : to add list of keys
-                        del_key : to del list of keys
-               and for more details and options of makenemo see ./makenemo -h
-
-	       set_namelist : to set namelist values 
-			(example : to set 75 time steps for one test : namelist nn_itend 75)
-			(        : to change cn_icerst_in name : namelist_ice cn_icerst_in  \"test_00101231_restart_icemod\")
-			(  	 : to activate control print : namelist ln_ctl false )
-	       prepare_exe_dir.sh creates execution directory for each test
-	       			  : NOTE for EACH JOB EXECUTION it is needed to set TEST_NAME variable
-				    TEST_NAME variable gives name to execution directory (created in prepare_exe_dir.sh)
-				    IT is mandatory to have different TEST_NAME for each job run if not existing files are re-written (for example namelist)
-
-               prepare_job.sh generates the script to be executed 
-			input: INPUT_FILE_CONFIG_NAME NUMBER_PROC TEST_NAME MPIRUN_FLAG JOB_FILE
-
-               fcm_job.sh needs input: TOTAL_NUMBER_OF_PROCS_used JOB_FILE_NAME INTERACT_FLAG MPIRUN_FLAG 
-			(for example if you run with 4 procs JOB_FILE batch parallel 
-			and only run short test ===> ./fcm_job 4 SHORT no    yes   )
-
+USER SETUP (recommended)
  * in param.cfg :
+      - variables (COMPILER, NEMO_VALIDATION_REF, NEMO_REV_REF) have to be specified in param.cfg
+      - variables (BATCH_CMD, BATCH_STAT, BATCH_NAME, FORCING_DIR, SVN_CMD, ADD_NOSIGNEDZERO)
+           can be exported from your shell startup files. It is advise to setup the default value in your startup file if it doesn't fit your need.
+           If you prefer not doing so, you need to update the default initialisation
+      - variable NEMO_VALIDATION_DIR is sette by default in MAIN_DIR/NEMO_VALIDATION (this is to avoid overwritting results when running sette on different branches).
+      - description of variables listed in param.cfg:
                COMPILER            : compiler among those available in NEMOGCM/ARCH
-               FORCING_DIR 	   : directory in which will be found input.tar file (same name in input_CONFIG_NAME.cfg)
-               INPUT_DIR   	   : directory in which store input files (tar file)
-                                     reference configuration input tar file could be found here : https://zenodo.org/record/1472245
-               TEST_CONFIGS        : the list of all the configuration to test in sette.sh (without any arguments)
-               TMPDIR      	   : temporary directory NEEDED ONLY FOR IBM machines (put EXP00 directory)
-	       NEMO_VALIDATION_DIR : directory in which create NEMO_VALIDATION tree, and store restart, run.stat, tracer.stat and ocean.output files in
-      			             tree NEMO_VALIDATION_DIR/WCONFIG_NAME/WCOMPILER_NAME/TEST_NAME/REVISION_NUMBER(or DATE)
-               BATCH_CMD           : command for job submission in batch mode
-               SVN_CMD             : svn command use to do svn info (default svn). Could be useful if you are using git svn
+               #
+               # reference version for bit reproducibility results
                NEMO_VALIDATION_REF : reference directory
                NEMO_REV_REF        : reference revision
-                                     reference directory for result comparison will be NEMO_VALIDATION_REF/COMPILER/NEMO_REV_REF
+               #
+               # batch command needed
+               BATCH_CMD           : command for job submission in batch mode
+               BATCH_STAT          : command to check job status
+               BATCH_NAME          : generic sette job name (as it appears with $BATCH_STAT command)
+               #
+               # file storing
+               FORCING_DIR         : directory in which will be found input.tar file (same name in input_CONFIG_NAME.cfg)
+                                     reference configuration input tar file could be found here : https://zenodo.org/record/1472245
+               NEMO_VALIDATION_DIR : directory in which will be stored restart, run.stat, tracer.stat and ocean.output files for each configuration
+                                     ( NEMO_VALIDATION_DIR/WCONFIG_NAME/WCOMPILER_NAME/TEST_NAME/REVISION_NUMBER(or DATE) )
+               INPUT_DIR           : directory in which store input files (DO NOT CHANGE IT)
+               #
+               # misc.
+               SVN_CMD             : svn command use to do svn info (default svn). Could be useful if you are using git svn
+                                   : Reference directory for result comparison will be NEMO_VALIDATION_REF/COMPILER/NEMO_REV_REF
                ADD_NODIGNEDZERO    : set "yes" if you need key_nosignedzero to run nemo
-               As a lot of this settings are user dependent or computer dependant, it is possible to set by default most of these value in your .bashrc 
-               (it facilitates the installation of sette for a new branch)
 
- * in fcm_job.sh :
-               IMPORTANT : control that name of tar file in FORCING directory
-               is the same of that in input_REF_CONFIG.cfg, if not change one.
+USAGE of main scripts:
+ * sette.sh                : it is a simple wrapper to run tests on the reference configurations, test-cases and generate the report at the end.
+          - if no argument is given, sette run all the reference configurations and test cases 
+          - if a list of argument is provided (sette.sh -t "CFG1 CFG2 CFG3"), sette will only run these configurations. 
+             The list of available configurations is available in running ./sette_list_avail_cfg.sh.
+          - user need to set up the param.cfg file correctly and download input file before running the script.
+ * sette_rpt.sh            : it generates the sette report.
+          - if no argument is given, the report will be generated on the last changed revision.
+          - if an argument is given (revision number) the report will be generated for this revision only
+          - if 'old' is given as argument the former behavior is applied (the latest revision is check whatever the current revision
+          - it is possible to retreive all the available revision test using sette_list_avail_rev.sh
+          - it is NOT possible to run sette_rpt.sh for a single configuration.
+ * sette_list_avail_rev.sh : generate a listing on all the revisions available in the validation directory for each configuration.
+          - no argument needed
+ * sette_list_avail_cfg.sh : generate a listing of all the available configurations.
+          - no argument needed
 
-               change in "RUN OPA" if [ ${INTERACT_FLAG} == "yes" ] mpirun command line (some examples are already written)
-	       NOTE: if INTERACT_FLAG="no" it is needed a batch_file (see below to create a new one)
-
- * in sette_rpt.sh : - if no argument are given, the report will be generated on the last changed revision.
-                     - if an argument is given (revision number) the report will be generated for this revision
-                     - if 'old' is given as argument the former behavior is applied (the latest revision is check whatever the current revision
-                     - it is possible to retreive all the available revision test using sette_list_avail_rev.sh
-
-NOTE:
-in case of error you can remove you NEW_CONF directory and all files doing :
-./makenemo -n MY_CONFIG clean_config
-
-if you want recompile nemo but before you want to clean compiled code do :
-./makenemo clean
-
-and if you have already compiled you can re-run all sette.sh and compilation part will be by-passed.
-
-NOTE 2: 
-if you want a completly verbose makenemo you can uncomment "set -x" in makenemo script
-and then launch ./sette.sh 2>&1 | tee out.sette
+NOTES:
+ * compilation issues:
+   - in case of error you can remove you NEW_CONF directory and all files doing :
+     ./makenemo -n MY_CONFIG clean_config
+   - if you want recompile nemo but before you want to clean compiled code do :
+     ./makenemo clean
+   - if you have already compiled you can re-run all sette.sh and compilation part will be by-passed.
+ * verbose sette output:
+   - if you want a completly verbose makenemo you can uncomment "set -x" in makenemo script
+     and then launch ./sette.sh 2>&1 | tee out.sette . This creates out.sette file in ${SETTE_DIR}
 
 TO ADD NEW CONFIGURATION:
@@ -100,4 +80,6 @@
 2. makenemo -n NEW_CONFIG -r REF_CONFIG (if it is based on another reference configuration)
 3. for fcm_job.sh creates a new input_NEW_CONFIG.cfg if you need tar file (if you use same tar file of GYRE, ORCA2_LIM or ORCA2_LIM_PISCES you can use it)
+4. add a bloc in one of the sette_reference-configuration.sh or sette_test-cases.sh script 
+5. add your configuration to the list in param.cfg
 
 TO ADD NEW MACHINE:
@@ -110,2 +92,41 @@
 2. create you own batch file like: batch-${COMPILER}
    (note: sette_test-cases.sh and sette_cfg-ref.sh will copy it in job_batch_template if you run tests in INTERACT_FLAG="no")
+
+
+
+
+
+USER MODIFICATIONS (sequential/parrallel (default), interacive or not (default) and mpi (default) or not )
+ * in sette_cfg-ref.sh and sette_test-cases.sh script :
+	  - BATCH_COMMAND_PAR is the command for job submission in batch mode parallel (MMIÂ) specified in param.cfg
+	  - BATCH_COMMAND_SEQ is the command for job submission in batch mode sequential (NB_PROC = 1)
+                                 the default value is the BATCH_COMMAND_PAR value
+          - INTERACT_FLAG : "yes" if you want to run in interactive mode 
+                            "no"  if you want to run in batch mode (default)     
+	  - MPIRUN_FLAG   : "yes" if you want to run in parallel (MPI) (default)
+		            "no"  if you want to run in sequential mode (NB_PROC = 1)
+
+USAGE of internal function/script
+ * makenemo -m : machine (compilator); see ./makenemo -m help (in NEMOGCM/CONFIG directory)
+            -n : config name (in examples config_name_nproci_nprocj), see ./makenemo -n help
+            -r : reference configuration (if you don't give it you have to choise directories to install)
+       add_key : to add list of keys
+       del_key : to del list of keys
+       and for more details and options of makenemo see ./makenemo -h
+ * set_namelist       : to set namelist values
+                          (example : to set 75 time steps for one test : namelist nn_itend 75)
+                          (        : to change cn_icerst_in name : namelist_ice cn_icerst_in  \"test_00101231_restart_icemod\")
+                          (        : to activate control print : namelist ln_ctl false )
+ * prepare_exe_dir.sh : creates execution directory for each test
+                          - for EACH JOB EXECUTION it is needed to set TEST_NAME variable
+                          - TEST_NAME variable gives name to execution directory (created in prepare_exe_dir.sh)
+                          - It is mandatory to have different TEST_NAME for each job run if not existing files are re-written (for example namelist)
+ * prepare_job.sh     : generates the script to be executed
+                          - input arguments are INPUT_FILE_CONFIG_NAME NUMBER_PROC TEST_NAME MPIRUN_FLAG JOB_FILE
+ * fcm_job.sh         : input arguments are TOTAL_NUMBER_OF_PROCS_used JOB_FILE_NAME INTERACT_FLAG MPIRUN_FLAG
+                        (for example if you run with 4 procs JOB_FILE batch parallel
+                        and only run short test ===> ./fcm_job 4 SHORT no    yes   )
+                          - IMPORTANT control that name of tar file in FORCING directory
+                            is the same of that in input_REF_CONFIG.cfg, if not change one.
+                          - change in "RUN OPA" if [ ${INTERACT_FLAG} == "yes" ] mpirun command line (some examples are already written)
+                          - if INTERACT_FLAG="no" it is needed a batch_file (see below to create a new one)
Index: /NEMO/branches/2019/fix_sette_ticket2239/param.cfg
===================================================================
--- /NEMO/branches/2019/fix_sette_ticket2239/param.cfg	(revision 10818)
+++ /NEMO/branches/2019/fix_sette_ticket2239/param.cfg	(revision 10819)
@@ -1,3 +1,3 @@
-# Computer dependant variable needed to run sette
+# Computer/user dependant variable needed to run sette
 #
 # Compiler among those in NEMOGCM/ARCH
@@ -9,6 +9,12 @@
 NEMO_REV_REF=0000
 #
-# IF SETTE_* variable mentioned below are exported from your initialisation, nothing to do
-# otherwise, please update the default iniitialisation or overwrite it
+# ------------------------------------------------------------------------------------------
+# IMPORTANT:
+# variables (BATCH_CMD, BATCH_STAT, BATCH_NAME, FORCING_DIR, SVN_CMD, ADD_NOSIGNEDZERO)
+# can be exported from your shell startup files. 
+# If it is the case, nothing to do
+# otherwise, you need to update the default initialisation
+#
+# ADVISE: setup the default value in your startup file if it doesn't fit your need.
 #
 # BATCH command
@@ -17,26 +23,28 @@
 # command to check job status
 BATCH_STAT=${SETTE_BATCH_STAT:-llq}
-# generic sette job name
+# generic sette job name (as it appears with $BATCH_STAT command)
 BATCH_NAME=${SETTE_BATCH_NAME:-sette}
-# List of test configurations
-TEST_CONFIGS=${SETTE_TEST_CONFIGS:-"ORCA2_ICE_PISCES ORCA2_OFF_PISCES AMM12 AGRIF SPITZ12 GYRE_PISCES SAS ORCA2_ICE_OBS ICE_AGRIF OVERFLOW LOCK_EXCHANGE VORTEX ISOMIP"}
 #
-#- FORCING files storing
+#
+# FILES STORING
+# forcing files storing
 FORCING_DIR=${SETTE_FORCING_DIR:-$WORKDIR/FORCING}
+# validation files storing
+NEMO_VALIDATION_DIR=${WORKDIR:-$MAIN_DIR}/NEMO_VALIDATION
+# input files storing (namelist, iodef ...) (DO NOT CHANGE)
+INPUT_DIR=${CONFIG_DIR}/${NEW_CONF}/EXP00
 #
-# CMD for svn (some people use git svn) 
+#
+# MISCELENIOUS
+# command for svn (some people use git svn) 
 # used in sette_rpt and in all_function to display revision and build correct repository name
 SVN_CMD=${SETTE_SVN_CMD:-svn}
-#
+# add key key_nosignedzero at the compilation step
+ADD_NOSIGNEDZERO=${SETTE_ADD_NOSIGNEDZERO:-"yes"}
 #- only for IBM
 #TMPDIR=${CONFIG_DIR}/${NEW_CONF}/EXP00
 #
-#- key_nosignedzero
-ADD_NOSIGNEDZERO=${SETTE_ADD_NOSIGNEDZERO:-"yes"}
 #
-#- INPUT files storing
-INPUT_DIR=${CONFIG_DIR}/${NEW_CONF}/EXP00
-#
-#- VALIDATION files storing
-NEMO_VALIDATION_DIR=${WORKDIR:-$MAIN_DIR}/NEMO_VALIDATION
-#
+# LIST OF CONFIGURATIONS
+# to be updated if you added an new configuration in sette_test-cases.sh or sette_reference-configuration.sh
+TEST_CONFIGS=${SETTE_TEST_CONFIGS:-"ORCA2_ICE_PISCES ORCA2_OFF_PISCES AMM12 AGRIF SPITZ12 GYRE_PISCES SAS ORCA2_ICE_OBS ICE_AGRIF OVERFLOW LOCK_EXCHANGE VORTEX ISOMIP"}
