[11140] | 1 | ====================== |
---|
| 2 | usage of SETTE package |
---|
| 3 | ====================== |
---|
[3520] | 4 | |
---|
[11140] | 5 | INSTALLATION |
---|
| 6 | ============ |
---|
| 7 | * checkout the code as follow: |
---|
| 8 | .. code-block:: console |
---|
[10819] | 9 | |
---|
[11140] | 10 | $ svn checkout http://forge.ipsl.jussieu.fr/nemo/svn/utils/CI/sette sette |
---|
| 11 | |
---|
| 12 | * The sette directory have to be located in the main directory (at the same level as ``src/`` or ``cfg/``). |
---|
| 13 | |
---|
| 14 | MASTER SCRIPT: sette.sh |
---|
| 15 | ======================= |
---|
| 16 | * ``sette.sh`` is a simple wrapper that runs tests on the reference configurations, test cases and generates the report at the end. |
---|
[11153] | 17 | * ``sette.sh`` is able n option, to take a list of configurations in argument (sette.sh -t "CFG1 CFG2 CFG3"). |
---|
[10819] | 18 | - The list of available configurations is available in running ./sette_list_avail_cfg.sh. |
---|
| 19 | - The default for sette is to run all of the reference and test configurations. |
---|
[11140] | 20 | * Users need to set up the ``param.cfg`` file correctly and download input files before running the script. |
---|
[10687] | 21 | |
---|
[10732] | 22 | SECONDARY SCRIPT |
---|
[11140] | 23 | ================ |
---|
[11153] | 24 | * ``sette_reference-configuration.sh`` runs sette tests on the reference configurations. |
---|
| 25 | * ``sette_test-cases.sh`` runs sette tests on test cases. |
---|
| 26 | * ``sette_list_avail_rev.sh`` generates a listing on all the revisions available in the validation directory for each configuration. |
---|
[11140] | 27 | * ``sette_list_avail_cfg.sh`` generates a listing of all the available configurations. |
---|
[11153] | 28 | * ``sette_rpt.sh`` generates the report. |
---|
[10732] | 29 | |
---|
[10819] | 30 | USER SETUP (recommended) |
---|
[11140] | 31 | ======================== |
---|
| 32 | * in ``param.cfg`` : |
---|
| 33 | - variables (NEMO_VALIDATION_REF, NEMO_REV_REF) have to be specified in param.cfg |
---|
| 34 | - variables SETTE_(COMPILER, USING_XIOS, USING_MPMD, JOB_PREFIX_MPMD, JOB_PREFIX_NOMPMD, BATCH_CMD, BATCH_STAT, BATCH_NAME, FORCING_DIR, SVN_CMD, NEMO_VALIDATION_DIR, ADD_NOSIGNEDZERO) |
---|
| 35 | 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. |
---|
| 36 | If you prefer not doing so, you need to update the default initialisation |
---|
[10819] | 37 | - 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). |
---|
[11140] | 38 | - description of variables listed in param.cfg (SETTE_): |
---|
| 39 | |
---|
| 40 | # reference version for bit reproducibility results |
---|
| 41 | | NEMO_VALIDATION_REF : reference directory |
---|
| 42 | | NEMO_REV_REF : reference revision |
---|
| 43 | |
---|
| 44 | # compiler information |
---|
| 45 | | COMPILER : compiler among those available in NEMOGCM/ARCH |
---|
| 46 | |
---|
| 47 | # XIOS management |
---|
| 48 | | USING_XIOS : flag to control the activation of key_iomput. |
---|
| 49 | "yes" to compile using key_iomput and link to the external XIOS library. |
---|
| 50 | "no" to compile without key_iomput and link to the old IOIPSL library. |
---|
| 51 | | USING_MPMD : flag to control the use of stand-alone IO servers |
---|
| 52 | (requires USING_XIOS="yes"). |
---|
| 53 | "yes" to run in MPMD (detached) mode with stand-alone IO servers. |
---|
| 54 | "no" to run in SPMD (attached) mode without separate IO servers. |
---|
| 55 | # generique batch scrip prefix name if MPMD set to true/false |
---|
| 56 | | JOB_PREFIX_MPMD |
---|
| 57 | | JOB_PREFIX_NOMPMD |
---|
| 58 | |
---|
| 59 | # batch command needed |
---|
| 60 | | BATCH_CMD : command for job submission in batch mode |
---|
| 61 | | BATCH_STAT : command to check job status |
---|
| 62 | | BATCH_NAME : generic sette job name (as it appears with $BATCH_STAT command) |
---|
| 63 | |
---|
| 64 | # file storing |
---|
| 65 | | FORCING_DIR : directory where is stored input.tar file (same name in input_CONFIG_NAME.cfg) |
---|
| 66 | reference configuration input tar file could be found here : https://zenodo.org/record/1472245 |
---|
| 67 | | NEMO_VALIDATION_DIR : directory where is stored restarts, run.stat, tracer.stat and ocean.output files for each configuration |
---|
| 68 | ( NEMO_VALIDATION_DIR/WCONFIG_NAME/WCOMPILER_NAME/TEST_NAME/REVISION_NUMBER(or DATE) ) |
---|
| 69 | | INPUT_DIR : directory where is stored input files (DO NOT CHANGE IT) |
---|
| 70 | |
---|
| 71 | # misc. |
---|
| 72 | | SVN_CMD : svn command use to do svn info (default svn). Could be useful if you are using git svn |
---|
| 73 | : Reference directory for result comparison will be NEMO_VALIDATION_REF/COMPILER/NEMO_REV_REF |
---|
| 74 | | ADD_NODIGNEDZERO : set "yes" if you need key_nosignedzero to run nemo |
---|
[10687] | 75 | |
---|
[11140] | 76 | USAGE of main scripts |
---|
| 77 | ===================== |
---|
| 78 | * ``sette.sh`` : it is a simple wrapper to run tests on the reference configurations, test-cases and generate the report at the end. |
---|
[10819] | 79 | - if no argument is given, sette run all the reference configurations and test cases |
---|
| 80 | - if a list of argument is provided (sette.sh -t "CFG1 CFG2 CFG3"), sette will only run these configurations. |
---|
| 81 | The list of available configurations is available in running ./sette_list_avail_cfg.sh. |
---|
| 82 | - user need to set up the param.cfg file correctly and download input file before running the script. |
---|
[12569] | 83 | - user can enforce synchronisation (-s option) of the existing CFG_ST with the REF configuration (EXPREF and MY_SRC). |
---|
| 84 | - user can enforce cleaning of the CFG_ST configuration (use of makenemo -n CFG_ST clean) (-c option) |
---|
[11140] | 85 | * ``sette_rpt.sh`` : it generates the sette report. |
---|
[10819] | 86 | - if no argument is given, the report will be generated on the last changed revision. |
---|
| 87 | - if an argument is given (revision number) the report will be generated for this revision only |
---|
| 88 | - if 'old' is given as argument the former behavior is applied (the latest revision is check whatever the current revision |
---|
| 89 | - it is possible to retreive all the available revision test using sette_list_avail_rev.sh |
---|
[11153] | 90 | - XXXXX+ means sette results for revision XXXXX contain local modification in src/cfgs/test |
---|
[10819] | 91 | - it is NOT possible to run sette_rpt.sh for a single configuration. |
---|
[11140] | 92 | * ``sette_list_avail_rev.sh`` : generate a listing on all the revisions available in the validation directory for each configuration. |
---|
[10819] | 93 | - no argument needed |
---|
[11153] | 94 | - XXXXX+ means sette results for revision XXXXX contain local modification in src/cfgs/test |
---|
[11140] | 95 | * ``sette_list_avail_cfg.sh`` : generate a listing of all the available configurations. |
---|
[10819] | 96 | - no argument needed |
---|
[3520] | 97 | |
---|
[11140] | 98 | NOTES |
---|
| 99 | ===== |
---|
| 100 | * compilation issues: |
---|
| 101 | - in case of error you can remove your NEW_CONF directory and all files doing : |
---|
| 102 | |
---|
| 103 | :: |
---|
| 104 | |
---|
| 105 | $ ./makenemo -n MY_CONFIG clean_config |
---|
| 106 | |
---|
[10819] | 107 | - if you want recompile nemo but before you want to clean compiled code do : |
---|
[11140] | 108 | |
---|
| 109 | :: |
---|
| 110 | |
---|
[10819] | 111 | ./makenemo clean |
---|
[11140] | 112 | |
---|
[10819] | 113 | - if you have already compiled you can re-run all sette.sh and compilation part will be by-passed. |
---|
[3520] | 114 | |
---|
[11140] | 115 | * verbose sette output: |
---|
| 116 | - if you want a completly verbose makenemo you can uncomment `set -x` in makenemo script |
---|
| 117 | and then launch `./sette.sh 2>&1 | tee out.sette` . This creates out.sette file in ${SETTE_DIR} |
---|
[3520] | 118 | |
---|
[11140] | 119 | TO ADD NEW CONFIGURATION |
---|
| 120 | ========================= |
---|
| 121 | 1. 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) |
---|
| 122 | 2. add a bloc in one of the ``sette_reference-configuration.sh`` or ``sette_test-cases.sh`` script |
---|
| 123 | 3. add your configuration to the list in ``param.cfg`` |
---|
| 124 | |
---|
| 125 | TO ADD NEW MACHINE |
---|
| 126 | =================== |
---|
| 127 | 1. add ``arch-compiler.fcm`` in ``NEMOGCM/ARCH`` directory |
---|
[3520] | 128 | 2. makenemo -m new_compiler (see makenemo -h for help) |
---|
[10750] | 129 | 3. add new batch-file |
---|
[3520] | 130 | |
---|
[11140] | 131 | TO ADD NEW BATCH-FILE |
---|
| 132 | ====================== |
---|
| 133 | 1. see in ``SETTE/BATCH_TEMPLATE`` directory existing examples |
---|
| 134 | 2. create you own batch file like: ``batch-${COMPILER}`` file |
---|
| 135 | (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") |
---|
[10819] | 136 | |
---|
[11140] | 137 | EXTRA SETTING POSSIBLE |
---|
| 138 | ====================== |
---|
| 139 | Among the setting that can be modified by the user in sette_cfg-ref.sh and sette_test-cases.sh script, |
---|
| 140 | there are: sequential/parrallel (default), interacive or not (default) and mpi (default) or not. |
---|
| 141 | - | BATCH_COMMAND_PAR is the command for job submission in batch mode parallel (specified in param.cfg). |
---|
| 142 | - | BATCH_COMMAND_SEQ is the command for job submission in batch mode sequential (NB_PROC = 1). |
---|
| 143 | the default value is the BATCH_COMMAND_PAR value. |
---|
| 144 | - | INTERACT_FLAG : "yes" if you want to run in interactive mode. |
---|
| 145 | "no" if you want to run in batch mode (default). |
---|
| 146 | - | MPIRUN_FLAG : "yes" if you want to run in parallel (MPI) (default). |
---|
| 147 | "no" if you want to run in sequential mode (NB_PROC = 1). |
---|