SURFEX

To run STRATO

Minvielle — 2026-01-26T15:54:22Z

Python scripts have been recently adapted to Python3. If your default python version is not Python3, please change "python" by "python3" in TESTS/PC/python.exe
On BELENOS, the default python is now Python3. But if in your bashrc or bash_profile you load python, please verify that you load python3 version.
For a run on PC, cp TESTS/PC/script_all.sh in the run directory: cp TESTS/PC/script_all.sh .
For a run on BELENOS, cp TESTS/BEAUFIX/script_all.sh in run directory: cp TESTS/BEAUFIX/script_all.sh .
run it: ./script_all.sh
NB : you can also type:
nohup ./script_all.sh &
so that you can close you session and the output is written in a nohup.out file instead of screen.
If you want to run the base of tests of a PC that has less than 4 processors, you can unactivate the parallel tests in a simple way:

go into directory TESTS and do:
- cp -f script_exec.sh script_exec_parall.sh
- cp -f script_exec.sh script_exec_omp_pgd.sh
- cp -f script_exec_restart.sh script_exec_restart_parall.sh
- cp -f script_exec.sh script_exec_pgd_parall.sh
- cp -f script_exec.sh script_exec_all_parall.sh
=> scripts that run with MPI and OPEN-MP are replaced by generic scripts and no parallelization happens.

STRATO data

Minvielle — 2026-01-26T15:45:44Z

Download the data package for STRATO:

STRATO-data-9-1-0.tar.gz

To install the base of test cases (starting with SURFEX 9.1.0)

Minvielle — 2026-01-26T14:33:56Z

The STRATO tests base is included in the GIT repository, in the directory STRATO/TESTS/

1. Choose two surfex versions ("old" and "new") to test

2. Choose a run directory, for example /home/username/run_base_test
In this run directory, you need to link:
- $SRC_SURFEX/MY_RUN/ECOCLIMAP/*.bin
- executables for the old version of the SURFEX code to be compared: pgd_old.exe, prep_old.exe, soda_old.exe, offline_old.exe
- executables for the new version of the SURFEX code to be compared: pgd_new.exe, prep_new.exe, soda_new.exe, offline_new.exe
- In the run directory, copy the directory TESTS/ from the surfex GIT repository.

3. open and modify:
- TESTS/PC/script_all.sh (on a standard PC) or TESTS/BEAUFIX/script_all.sh (on belenos): 3 first lines:
  dir_run="/home/username/run_base_test" (type your own rundir name)
  exec_new="_new" (type your own extension for new executables)
  exec_old="_old" (type your own extension for old executables)
- TESTS/PYTHON/compR.cfg:
  verN="name of your new version, for output files"
  verO="name of your old version, for output files"
  basedir="/home/faroux/run_base_test/" (type your own rundir name)
  CAUTION: there must be a "/" at the end of basedir.

4. Data to run STRATO: Since version V9.1.0 and code management under GitHub, only scripts of STRATO are stored in the Git repository. All additional data used for the various tests are not included anymore in the repository.
So you need to:
- Download the package with the data corresponding to your version of SURFEX
- Untar this package where you want (/home/username/STRATO-DATA in this exemple)
- Open script-link-data.sh
- Modify the two first lines to indicate where are located :
  - your STRATO (/home/username/run_base_test in this exemple)
  - your package with STRATO data (/home/username/STRATO-DATA in this exemple)
- Execute script-link-data.sh

9. Ending remarks and prospects

2013-10-15T15:34:16Z

1). The parallel tests performed by the base use all resources for a classic 4 processors PC.

=> Consequently, seeing added execution times, in case of a will to run the test base not during a week-end (nor during an interval of time longer than 2 days when the PC isn't used), it's advised to divide script_all.sh into 3 parts :

script_all1.sh : calls from script_pgd_grid.sh to script_flake.sh
script_all2.sh : script_isba.sh
script_all3.sh : from script_teb.sh to script_cas_parts.sh

Then you can launch them during night, one by one along 3 consecutive days.

2). The script that compares SURFEX outputs for old and new versions of the code and writes output comparison files is coded in PYTHON. It is written by S. Dasprez.

3). The base was also tested and validated on Beaufix (Bull ifort architecture).

8. Detailed numbers of tests cases and execution times

2013-10-15T14:57:38Z

script_pgd_grid.sh : 25 test cases - 55 minutes
script_pgd_physio.sh : 13 test cases - 4 minutes
script_pgd_ecoclimap.sh : 51 test cases - 14 minutes
script_prep.sh : 34 test cases – 39 minutes
script_sea.sh : 334 test cases – 3 h 26 minutes
script_water.sh : 56 test cases – 15 minutes
script_flake.sh : 128 test cases – 42 minutes
script_isba.sh : 968 test cases – 18 h 08 minutes
script_teb.sh : 528 test cases – 10 h 43 minutes
script_offline.sh : 80 test cases – 3 h 28 minutes
script_csts.sh : 302 test cases – 4 h 32 minutes
script_cas_parts.sh : 39 test cases – 1 h 14 minutes

Total : 2558 test cases – 44 h 58 minutes

7. One means to analyse results (proposition)

2013-10-15T11:26:38Z

One means to analyse results is to :

first, see which test cases finished anormally, through the PLANTE_....txt files.
second, identify the test cases that give different results results, through the SYNN file, and go to the RPT corresponding files to get more details about the differences.
Have a look at the NCH file to detect possible peculiarities in the counts of output fields.

In the case of test cases not finishing normally or giving different results, it is greatly useful to launch again only the focused problematic test case. That's why namelists for all test cases are saved, gradually, in the run directory, under the names :

OPTIONS.nam_[name of the test case]

=> You can then copy the namelist of the case you want to re-run in OPTIONS.nam, and launch manually the executables of one or the other versions of the SURFEX code.

6. Output files produced by the base of tests

2013-10-15T11:09:06Z

NB: The following output files are not overwritten if the base of automatic tests is run a second or a third time. To run again the tests with blank files, you will need to suppress the output files manually before.

Two types of output files are produced :

Synthesis files:

The tests are divided into 12 main categories: PGD_GRID, PGD_PHYSIO, PGD_ECOCLIMAP, PREP, SEA, WATER, FLAKE, ISBA, TEB, CSTS, OFFLINE, CAS_PARTS.
- For each category, in the run directory, 3 files are produced :
  - INFO_[name of the category].txt :contains the ordinary screen output of the run, with names of the test cases included
  - PLANTE_[name of the category].txt : contains the list of the test cases that finished anormally
  - END_[name of the category].txt : contains the list of the test cases that finished correctly
- In directory TESTS/PYTHON/results , 3 more synthesis files are written :
  expe2d_NEW_PREP_and_TRUNK_73_conf.nch / syno / synn
  (following upper example for the name of the file)
  - The NCH file, following the nomenclature of the LOG files, contains, for each test case, one line by case : listN, listO, listM, listnMN, listnMO (numbers only, without lists of fields).
  - The SYNO file contains the names of the test cases that give exactly the same results (for fields common to the old and new versions)
  - The SYNN file contains the names of the test cases that don't give the same results, with the numbers of fields that give different results.

=> All these synthesis output files are updated at the end of each test case.

Detailed outputs for each test cases :

for each part of PGD, PREP, OFFLINE, SURFOUT, 3 files are created in directory : TESTS/PYTHON/results
- The names of these output files are composed of :
  [name of the last directory of the run path directory]_[name of the new version]_and_[name of the old version]_conf_[name of the test case].log / .nan / .rpt
  Example : PGD/PREP//OUT_expe2d_NEW_PREP_AND_TRUNK_73_conf_TEB_SIMPLE.log
- The LOG file contains the comparison between the numbers of fields found in output NETCDF files for old and new versions :
  - listN : number of fields found in the new version output files
  - listO : number of fields found in the old version output files
  - listM : number of fields found in both versions
  - listnMN : fields found in the new version but not in the old one, with for each field the name of the file it is in
  - listnMO : fields found in the old version but not in the new one, with for each field the name fo the file it is in
- The NAN file contains the list of the fields found in the two versions outputs, if they are constant or if naN values are present in the old or in the new ones. In this file, columns are :
  number of the field in the list, [ naN found in the new outputs ?, naN found in the old outputs ?, maximum value of the new output minus minimum value of the old one, [name of the field, name of the corresponding file]]
- The RPT file contains, for each field found in both output lists, old and new :
  the number of the field in the list,
  [ the maximum percentage of error between the two versions, the maximum difference, the corresponding new value, the corresponding old value, the average of the differences,
  [the name of the field, the name of the associated file]]
  => In this RPT files, fields are ordered by decreasing percentages of error.

=> All these synthesis output files are updated at the end of each test case.

To install the base of test cases (before SURFEX 9.1.0)

2013-10-15T10:31:49Z

The STRATO tests base is included in the GIT repository, in the directory STRATO/TESTS/

1. Choose two surfex versions ("old" and "new") to test

2. Choose a run directory, for example /home/username/run_base_test
In this run directory, you need to link:
- $SRC_SURFEX/MY_RUN/ECOCLIMAP/*.bin
- executables for the old version of the SURFEX code to be compared: pgd_old.exe, prep_old.exe, soda_old.exe, offline_old.exe
- executables for the new version of the SURFEX code to be compared: pgd_new.exe, prep_new.exe, soda_new.exe, offline_new.exe
- In the run directory, copy the directory TESTS/ from the surfex GIT repository.

3. open and modify:
- TESTS/PC/script_all.sh (on a standard PC) or TESTS/BEAUFIX/script_all.sh (on belenos): 3 first lines:
  dir_run="/home/username/run_base_test" (type your own rundir name)
  exec_new="_new" (type your own extension for new executables)
  exec_old="_old" (type your own extension for old executables)
- TESTS/PYTHON/compR.cfg:
  verN="name of your new version, for output files"
  verO="name of your old version, for output files"
  basedir="/home/faroux/run_base_test/" (type your own rundir name)
  CAUTION: there must be a "/" at the end of basedir.

4. physiographic big files are not delivered with the test base. So you need to:
1. download:
  gtopo30.dir & gtopo30.hdr, topo_index.dir & topo_index.hdr here,
  clay_fao.dir & clay_fao.hdr, sand_fao.dir & sand_fao.hdr, soc_top.dir & soc_top.hdr, soc_sub.dir & soc_sub.hdr here,
  sand_6layers_mean_int.tgz, clay_6layers_mean_int.tgz here,
  ECOCLIMAP_I_GLOBAL.dir & ECOCLIMAP_I_GLOBAL.hdr, ECOCLIMAP_II_EUROP.dir & ECOCLIMAP_II_EUROP.hdr (take latest versions and rename them), perm_glo_10km.dir & perm_glo_10km.hdr here,
  GlobalLakeDepth.dir & GlobalLakeDepth.hdr, GlobalLakeStatus.dir & GlobalLakeStatus.hdr, LAKE_LTA_NEW.nc here,
  etopo2.nc here.
2. unzip all these files and put them in directory TESTS/PGD/FILES, except for LAKE_LTA_NEW.nc that you put in TESTS/PREP/FILES.

Principle of operating, for the base of tests

2013-10-01T11:56:55Z

The base relies on a sort of "over-namelist" containing about all the possible switches and options for SURFEX. This namelist is called OPTIONS.nam_000.

The procedure is divided into two parts:

shell scripts are successively called to run SURFEX with different options. They define all test cases to be run. For that, they modify the namelist OPTIONS.nam_000 through some “sed” commands. The two versions to compare are run, and output NETCDF files for these two versions are stored in two different directories.
Then, for each test case, a python program compares the two series of output files, and gives results in the form of text summary files. important note: scripts have recently been adapted to Python3. Please verify that by default, python3 is used when you run STRAO.

Note that :

the base of tests only compares NETCDF output files. So, it can't be used to validate the effective contents of output files in other formats (LFI, FA, ASCII, BINARY, TEXTE). If some changes are performed in the writing part of the code associated to these other formats, the developer will have to design his own strategy of testing it.
new versions of the code often bring changes in namelist blocks. Therefore, testing a new branch will inevitably lead to adapt, would it be just a bit, the base namelist, OPTIONS.nam_000. If names of namelist entries are changed, possible associated “sed” commands in shell scripts will need to be adapted too.

so, in the case he tests a new version of the code, the developer has to:
- think if his modifications could lead to propose a new test case to enter the base. In this case, he can propose a new test case to the SURFEX team and it will be included in the next version of the base of tests.
Another point is that often, the “old” version tested has not exactly the same namelist blocks as the new one. For this purpose, a script named script_to_old.sh is delivered inside the base. This script needs to be adapted too: OPTIONS.nam_000 contains namelists blocks for the new version tested, and script_to_old.sh allows to go back to the old ones. script_to_old.sh is composed of “sed” commands.

Concretely, each tester will have its own version of the base of tests, corresponding to the options or modifications of existing blocks he introduced in the namelist with his new version.

At the end of the process of building a new official version of SURFEX, the SURFEX team will take charge of merging the versions of the base of tests coming from the different contributers.

Principle of use for the base of tests

2013-10-01T09:50:33Z

The purpose of the base is to compare two versions of the code for various configurations and options, in order to detect, for example, developments that can have an unexpected impact in other parts of the code. In general, the base aims at:

precisely evaluating the differences introduced by a development version, compared to the official version it's based on.
consolidating this development version by testing it in a large range of SURFEX configurations.

We ask that each developer runs the base of tests on its own branch, during or at the end of its development time, as he prefers. Before he can propose its development to enter a new official version he has to provide a text document that:

sums up the results of the run of the base of tests: list of the test cases that give results different in the two versions.
explains and justifies the origin of these differences for each concerned test case.

An example and framework for such a document is proposed here:

Once the branch of the developer is validated through the base of tests, it can be included in the building process of the next official version, and a Pull Request can be done on the SURFEX GitHub repository.

At the end of the call for contributions, the SURFEX team will review the different Pull Requests, merge them and solve the eventual conflicts (depend on the content of the PRs), and will run the base of tests for a last time.
The SURFEX team will use the documents containing information about changes in results, provided by developers, to summarize the scientific input of the new version to be published.