source: NEMO/branches/2019/fix_sette_ticket2239/README @ 10769

usage of SETTE package:

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.

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_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   )

 * 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
               NEMO_VALIDATION_REF : reference directory
               NEMO_REV_REF        : reference revision
                                     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.

               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

TO ADD NEW CONFIGURATION:
1. makenemo -n NEW_CONFIG (see makenemo -h for help) OR
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)

TO ADD NEW MACHINE:
1. add arch-compiler.fcm in NEMOGCM/ARCH directory
2. makenemo -m new_compiler  (see makenemo -h for help)
3. add new batch-file

TO ADD NEW BATCH-FILE:
1. see in SETTE/BATCH_TEMPLATE directory existing examples
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")