Launching simulations on MF HPC

This section contains all necessary information to launch simulations on HPC.

Code organisation in applications and configurations

The “Crocus” application

Research SURFEX/Crocus simulations based on FORCING file(s) of any origin.

Associated configurations:

The Crocus ‘deterministic’ configuration

Any deterministic SURFEX/Crocus simulation involving a single meteorological FORCING and Crocus configuration

Workflow:

  1. Generation of a PGD.nc file with pgd.job

  2. Generation of an init_TG file with init_TG.job

  3. Generation of a PREP.nc file with prep.job

4. Generation of a spinup with spinup.job. If necessary, the PGD.nc and PREP.nc files will be created. :wq

  1. Launch a SURFEX/Crocus simulation with surfex.job. If necessary, the PGD.nc and PREP.nc files will be created.

The Crocus ‘escroc’ configuration

Crocus multiphysics simulations based on a single or an ensemble of meteorological forcing file(s).

Currently, the generation of PGD.nc and PREP.nc files is done in the “deterministic” configuration.

The Crocus ‘assim’ configuration

SURFEX/Crocus simulations based on an ensemble of meteorological forcing from any origin, and optionaly different physics, with the assimilation of snow observations.

The “s2m” application

SAFRAN-SURFEX/Crocus-MEPRA simulations in a standard “SAFRAN-massif” geometry.

Associated configurations:

The s2m “reanalysis” configuration

SAFRAN-SURFEX/Crocus-Mepra (S2M) reanalysis simulations, including the reference dataset and research SURFEX simulations based on the reference SAFRAN reanalysis on standard S2M geometries.

Workflow:

Before launching the S2M reanalysis, ensure that all input data are available on the archive disk with a prestaging request. A file with the necessary prestaging request is available under $SNOWTOOLS_DIR/vortex_cen/s2m/reanalysis/prestaging_ERA5-S2M_reanalysis.MIG. On a HPC login node, create a copy of this 3-lines file and change the first line with your email adress, then do :

ftp hendrix
> cd /DemandeMig/ChargeEnEspaceRapide
> put prestaging_ERA5-S2M_reanalysis.MIG

You will receive receive a first email with a “HENDRIX Prestaging Initial Mail” object to inform you that your prestaging request has been taken into account, then a second one few hours later with an “HENDRIX Prestaging Final Mail” to inform you that all input data have been move on the quick-acess archive storage. At this point you can start the following pipeline.

  1. SAFRAN inputs

  • obs_safran : Generation of SAFRAN-compatible reconstructed hourly surface observation time series (only once, when you want to add a new year to the dataset)

  • prepsafran : Generation of SAFRAN guess files (only once, when you want to add a new year to the dataset)

  1. FORCING generation

  • safran : Generation of “raw” SAFRAN meteorological forcing files (“flat” geometry and 1 “postes” FORCING file per domain). For the entire period:

mkjob -c /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/s2m/reanalysis/jobs/safran.jobs -a datebegin=1940080106 dateend=2025080106
For the addition of a new year only:

mkjob -c /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/s2m/reanalysis/jobs/safran.jobs -a da tebegin=2025080106 dateend=2026080106

  • add_slopes : Add slopes and aspects to the raw “flat” SAFRAN meteorological forcing files

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/add_slopes.jobs -a datebegin=1940080106 dateend=2025080106 -n addslopes_vog

Note

To launch all 6 domains, remove “-n addslopes_vog” from the previous command line

  • concatenation_postes : Concatenate “postes” forcing files from all domains into a single FORCING file and add solar masks

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/concatenation.jobs -a datebegin=1940080106 dateend=2025080106

  1. Generation of PGD.nc and PREP.nc files (only once)

  • Generation of ground physiography :

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/pgd.jobs -a forcing_datebegin=1950080106 forcing_dateend=1951080106 -n pgd_postes

Note

You need to add the produced PGD.nc file in your uenv to be able to use it in the next steps

  • Generation of an initial ground temperature

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/init_TG.jobs -a forcing_datebegin=1950080106 forcing_dateend=1951080106 -n init_tg_vog

Note

You need to add the produced init_TG.nc file in your uenv to be able to use it in the next steps. TODO : check if really necessary

  • Generation of an initial snowpack state (PREP.nc file) for the spinup step

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/prep.jobs -a prep_datevalidity=1950080106 datebegin=1950080106 dateend=1951080106 -n prep_vog

  • Spinup : generation of more physical initial conditions to use to initialise the actual reanalysis (use prep generated by the previous “prep” step)

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/spinup.jobs -a datebegin=1940080106 dateend=1950080106 -n spinup_vog

  1. SURFEX

Generation of SURFEX/Crocus snowpack simulations on “allslopes” and “postes” geometries (use prep generated by the spinup step)

  • Entire simulation period :

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/surfex.jobs -a datebegin=1940080106 dateend=2025080106 -n surfex_reanalysis_vog

  • To add only one year (use prep generated by the last execution of surfex)

mkjob -c ~/snowtools/vortex_cen/s2m/reanalysis/conf/release_2026.ini -f ~/snowtools/vortex_cen/s2m/reanalysis/jobs/surfex.jobs -a prep_datevalidity=2025080106 prep_block=offline datebegin=2025080106 dateend=2026080106 -n surfex_reanalysis_vog

The s2m “reforecast” configuration

Production of a SAFRAN-SURFEX/Crocus-MEPRA (S2M) reforecast for the training of operationnal new snow forecasts post-processing algorithm

Workflow :

  1. SAFRAN inputs

    • prepsafran : Generation of SAFRAN guess files

  2. SURFEX inputs

    • safran : Generation of “raw” SAFRAN meteorological forcing files (“flat” geometry and 1 “postes” FORCING file per domain)

    • [init_TG] : Generation of an initial ground temperature]

    • dailyprep : Generation of daily initial snowpack state from the SAFRAN reanalysis

    • [pgd] : Generation of ground physiography

  3. FORCING modification

    • add_slopes : Add slopes and aspects to the raw “flat” SAFRAN meteorological forcing files

    • concatenation_postes : Concatenate “postes” forcing files from all domains into a single FORCING file and add solar masks

  4. SURFEX

    • surfex_massifs : Generation of SURFEX/Crocus snowpack simulations on an “allslopes” geometry

    • surfex_postes : Generation of SURFEX/Crocus snowpack simulations on the “postes” geometry

The s2m “oper” configuration

Operational SAFRAN-SURFEX/Crocus-MEPRA (S2M) model chain. The actual alp, pyr, cor, mac, vog, jur operational configurations derive from the “oper” configuration : * “oper” contains the drivers (common to all domains) and “prepsafran” jobs (common to all domains) * [alp|pyr|cor|mac|vog|jur] contains the domain-specific jobs and configuration files

Workflow :

  1. SAFRAN inputs

  • prepsafran_analyse : Generation of SAFRAN guess files from NWP analyses

  • prepsafran_prevision : Generation of SAFRAN guess files from NWP forecasts

  • prepsafran_reanlayse : Generation of archives of SAFRAN guess files from the previous 01/08 until the 18th day of each month (runs on the 22nd day of the month)

  • [refill_guess_safran] : Offline generation of an archive of SAFRAN guess files to restart the real-time chain

  1. SAFRAN

  • safran_analyse_ensemble : Ensemble (runs 3H, 6H, 9H) or detterministic (run 12H) SAFRAN analyses (generation of “flat” FORCING files)

  • safran_analysei_prevision : Ensemble SAFRAN forecasts (generation of “flat” FORCING files)

  1. SURFEX

  • [cold_start_surfex] : Deterministic SURFEX/Crocus snowpack simulation from the previous 01/08 with “custom” initial condition after a geometry or SURFEX version update. For example, to start the 2026 new S2M oper chain with initial conditions from the 2026 release of the ERA5-S2M reanalysis valid on 1st August 2025 :

s2m_oper -j cold_start_surfex -d 2026091412 -a prep_xpid=release_2026 prep_user=vernaym prep_datevalidity=2025080106 prep_block=offline prep_vapp=s2m prep_vconf=reanalysis

  • ensemble_surfex_tasks_analysis : Update raw SAFRAN forcing files (add slopes and solar masks) + ensemble SURFEX/Crocus snowpack simulations

  • ensemble_surfex_tasks_forecast : Update raw SAFRAN forcing files (add slopes and solar masks) + ensemble SURFEX/Crocus snowpack simulations

  • monthly_surfex_reanalysis : Deterministic SURFEX/Crocus snowpack simulation from the previous 01/08 until the 18th day of each month (runs on the 22nd day of the month)

  • monthly_surfex_reanalysis_sytron : Deterministic SURFEX/Crocus snowpack simulation from the previous 01/08 with the SYTRON snow drift module activated

  1. Post-processing

  • hydro_task : Hydrological post-processing

  • postprocess_forecast : Post-processing for the 4 seasons bulletin

The “edelweiss” application

Ensemble, distributed snowpack simulations at 250m resolution with the assimilation of snow observations.

Associated configurations:

  • prafr: Operational Edelweiss configuration for avalanche danger forecasting over France

  • reanalysis: Edelweiss reanalysis

  • reforecast Edelweiss reforecast

Code organisation for a given configuration

All configurations follow the following directory structure :

vortex_cen/
    vapp/
        vconf/
            drivers/
            conf/
            jobs/

The drivers repository contains all the drivers (a sequence of unit tasks) related to a given configuration.

The conf repository contains configuration files associated to specific experiments. A configuration file contains all the relevant variable values for a specific set of tasks relating to a particular experiment. Default configuration files can also provide the minimum set of variable values required to perform specific tasks, such as launching SURFEX/Crocus simulations.

The jobs repository contains files that provide the information needed to carry out one or several specific job(s) (the minimal information beiing the job(s) name(s) and the associated driver(s)). The use of these files is optional, but it is recommended because it allows to set default CEN-specific launcher variables.

Launching HPC simulations

The mkjob launcher

This section provides an overview of the mkjob launcher from a CEN perspective. The full mkjob package documentation is available here: https://cnrm-gmap.gitlab.meteo.fr/mkjob/index.html

Note

The source code is available on git.meteo.fr : https://git.meteo.fr/cnrm-gmap/vortex/-/tree/main/mkjob?ref_type=heads

Mkjob is a job script generator. It combines a job templates and a user-defined configuration file to produce and launch jobs on MF’s HPC. Although several job types (“profiles”) are available (see https://cnrm-gmap.gitlab.meteo.fr/mkjob/configuration.html), only the “rd-belenos-mt” profile is used at CEN. This profile is based on the MTOOL tool that splits the execution in separate job submissions (called “steps”):

  • step.01: on a transfert node to fetch the input files from a remote server

  • step.02: on a compute node to do the actual computation

  • step.03: on a transfert node to archive the output files on aremote server

Here is an overview of the mkjob launcher arguments used at CEN (see also “mkjob -h” for more information):

  • -c [mandatory]: Set the absolute path to the configuration file

  • -f [optional but recommended]: Absolute path or filename of the job description file (in which the job name and associated task name, as well as the profile=rd-belenos-mt information must be provided). The job description file can contain several job descriptions (one description per line). In this case, all the jobs will be launched.

  • -a [optional]: Additionnal user defined command line variables (format “arg1=XXX arg2=YYY […]”) with the highest level of priority (the values provided after the “-a” option overwrite both the values provided in the “job” file and the configuration file). These additionnal values apply to all jobs described in the job description file. Although this argument is optional, it should be used to set variables such as datebegin, dateend or geometry.

  • -n [optional]: In case the job description file (-f argument) provides several job decriptions, the -n argument allows to choose a subset of jobs to launch based on the jobs names.

  • -l [info]: Return the list of job descriptions in the job description file (for example to find a specific job name to launch with option -n)

The following example of an mkjob command line allows to launch a SURFEX simulation with the minimal default configuration variables:

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/default_conf.ini -a xpid=first_test datebegin=2020080106 dateend=2021080106 geometry=cor2_allslopes

If the job description file contains several jobs and you want to launch only a subset, il is possible to access the list of available job names with option -l. For example :

> mkjob -f $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/jobs/safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -l
{'name': 'safran_reanalysis_alp', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'alp27_flat'}
{'name': 'safran_reanalysis_pyr', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'pyr24_flat'}
{'name': 'safran_reanalysis_cor', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'cor2_flat'}
{'name': 'safran_reanalysis_mac', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'mac11_flat'}
{'name': 'safran_reanalysis_jur', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'jur4_flat'}
{'name': 'safran_reanalysis_vog', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'vog3_flat'}

Then you can choose a subset of jobs to launch with the “-n” option :

mkjob -f $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -n safran_reanalysis_alp safran_reanalysis_pyr safran_reanalysis_cor -a datebegin=... dateend=... xpid=...

If the job description file contains several jobs and you want to launch only a subset, il is possible to access the list of available job names with option -l :

> mkjob -f $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/jobs/safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -l
{'name': 'safran_reanalysis_alp', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'alp27_flat'}
{'name': 'safran_reanalysis_pyr', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'pyr24_flat'}
{'name': 'safran_reanalysis_cor', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'cor2_flat'}
{'name': 'safran_reanalysis_mac', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'mac11_flat'}
{'name': 'safran_reanalysis_jur', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'jur4_flat'}
{'name': 'safran_reanalysis_vog', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'vog3_flat'}

Then you can choose a subset of jobs to launch with the “-n” option :

mkjob -f $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -n safran_reanalysis_alp safran_reanalysis_pyr safran_reanalysis_cor -a datebegin=... dateend=... xpid=...

Configuration files

The “mkjob” configuration files have 3 levels of reading : the “DEFAULT” level, the “job” level and the “task” level.

  • Configuration variables provided in the [DEFAULT] section are made available at each use of the configuration file.

  • Configuration variables provided in the [job] sections are made available only for the corresponding job. These sections must contain the configuration variables of the job itself (partition, nnodes, walltime,…) and the potential variables with a common value for all tasks associated to the job. The variables already provided in the [DEFAULT] section are overwritten.

  • Configuration variables provided in the [task] sections are made available only for the corresponding task. The variables already provided in the [DEFAULT] and [job] sections are overwritten.

Note

  • The names of the job sections is the name of the job as provided in the “job” files (name=<jobname>) or directly in the mkjob command line

  • The names of the task sections is the tag of the task in the driver of tasks. If a given task is used in different drivers or several times in a single driver, different tags must be given

If the job description file contains several jobs and you want to launch only a subset, il is possible to access the jobname wit option -l :

> mkjob -f safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -l
{'name': 'safran_reanalysis_alp', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'alp27_flat'}
{'name': 'safran_reanalysis_pyr', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'pyr24_flat'}
{'name': 'safran_reanalysis_cor', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'cor2_flat'}
{'name': 'safran_reanalysis_mac', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'mac11_flat'}
{'name': 'safran_reanalysis_jur', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'jur4_flat'}
{'name': 'safran_reanalysis_vog', 'package': 'drivers', 'task': 'safran', 'profile': 'rd-belenos-mt', 'geometry': 'vog3_flat'}

Then you can choose a subset of jobs to launch with the “-n” option :

mkjob -f safran.jobs -c $SNOWTOOLS_CEN/vortex_cen/s2m/reanalysis/conf/s2m_reanalysis.ini -n safran_reanalysis_alp safran_reanalysis_pyr safran_reanalysis_cor -a datebegin=... dateend=... xpid=...

Note

A configuration file should contain all configuration variables associated to a given scientific experiment. It is strongly recomended to name your configuration files after the associated experiment identifier (xpid).

The only command-line configuration variables that can be parsed to the “-a” argument of mkjob are:

  • The datebegin and dateend of the simulation

  • The geometry of the simulation

  • debug=True to ensure that the working directory is preserved at the end of the job

  • test=True to get a quick report on the job execution status under /scratch/mtool/<username> without having to dig in the log

  • allow_path=True to allow parsing absolute path for the surfex namelist and executables input

  • diff_xpid, diff_user, diff_block and diff_vortex1 for reproducibility checks with reference data

  • The job’s sbatch information (walltime, nnodes, partition). However it is recomended to leave that information in the configuration file whenever possible.

The mkjob helper

An mkjob command launches a job associated to a specific driver. From a user point of view, the first question that arises is : what are the possible configuration variables associated to this scpecific driver ? The “mkjob-help” command line is provided to answer this question.

There are two possible usage of the mkjob help command :

  1. provide directly the absolute path to the driver to document with the “-p” argument

  2. provide the target application (“-a” argument), configuration (“-c” argument) and driver name (“-d” argument)

By default, the information displayed include: * The driver’s documentation * The driver’s tree (the sequence of tasks) * A compact list of mandatory and optional configuration variables for this specific driver

Two additionnal arguments allow to refine the information to display :

  • “–bytask” displays the list of mandatory and optional configuration variables for each individual task of the driver

  • “–verbose” displays additional information such as the individual task’s documentation and the full list of mandatory and optional configuration variables

Note

  • If no argument is provided, the general documentation of available applications in the vortex-cen package is displayed.

  • If only the target application (“-a” argument) is provided, the general documentation of this specific application is displayed

  • If only the target application (“-a” argument) and configuration (“-c” argument) are provided, the general documentation of this specific configuration is displayed

Tutorial (user)

Launch a SURFEX/Crocus experiment

Deterministic SURFEX/Crocus simulations can be launched with the following job description file (“-f” argument of the mkjob launcher) : $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job

Note

If they do not exists, the PGD.nc and/or the PREP.nc files will be created. It is possible to force the generation of these files with the job description files ‘pgd.job’ and ‘init_TG.job’ + ‘prep.job’. For more realistic initial conditions, a spinup can be run with the ‘spinup.job’ job description file.

For more information, see Code organisation in applications and configurations

Default SAFRAN-based simulations

A default configuration file is available (“-c” argument of the mkjob command : $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/default_conf.ini) This default SURFEX/Crocus simulation use FORCING files from the S2M-reanalysis dataset and the minimum information to provide is:

  • the simulation’s experiment identifier : xpid can be any string of length different from 4

  • the simulation’s period : datebegin and dateend must be between 01/08/1940 and 01/08/2025 in case default S2M reanalysis FORCING files are used

  • the simulation’s geometry must be a valid S2M-reanalysis geometry in case default S2M reanalysis FORCING files are used

NB it is recomended to add all your configuration variables other than datebegin, dateend and geometry in a configuration file (in the “conf” directory of the configuration) named after your experiment identifier (xpid). See section ref:configuration_files.

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/default_conf.ini -a xpid=first_test datebegin=2020080106 dateend=2021080106 geometry=cor2_allslopes

Reproductible simulations with a user-controlled SURFEX/Crocus configuration

The default SURFEX/Crocus simulations described on the sections above are based on reference SURFEX/Crocus executables and namelists. You can use your own SURFEX executables, either by adding them in an existing uenv (Modifying an existing UEnv), either in a separate user environment as described bellow.

In order to produce reproducible simulations, it is recomended to compile SURFEX with the “compile_surfex_hpc.sh” script (under cenutils). This script compiles the SURFEX binaries and put them in a proper, ready-to-use User Environment (uenv). The only mandatory argument is the target SURFEX repository (–surfex_dir). The MPI compilation option and the optimisation level can additionaly be provided with the –ver_mpi (“MPI” by default, or “NOMPI”) and –optlevel (“O2” by default or “DEBUG”) arguments respectively.

The uenv containing the compiled binaries is automatically created with a standard name “surfex_executables_${VER_MPI}_${surfex_commit}” (which is displayed on screen at the end of the comilation script). You can use this uenv in your simulations by adding the following configuration variable in your configuration file:

surfex_uenv=uenv:<new_env_name>@<your_username>

Note

The “compile_surfex_hpc.sh” final message specify the configuration variables to add to your configuration file to use the produced executables.

When possible, the associated SURFEX commit number is added directly into the binaries and uenv names with the following rules:

  • Compiling directly from a Git repository ensures that the compiled binaries can be associated with a SURFEX commit, and checks whether this commit is present in the remote Git repository. Uncommitted local changes are signaled with an additional “uncommitted_local_changes” suffix.

  • Compiling from a ‘mirror’ directory synchronised with a Git repository using the ‘cenutils/put’ script enables tracking of the most recent SURFEX commit. However, uncommitted local changes cannot be detected, so the commit will be tagged as ‘uncertain’.

  • Compiling from a directory with no information on the SURFEX commit will produce executables tagged as “Unknown”

If you want to add these executables to a uenv <new_uenv> containing other constant files, first create the <new_uenv> from an existing <old_uenv> owen by user <uenv_owner>:

uget hack <old_uenv>@<uenv_owner> into <new_uenv>@<your_username>

Then remove the lines refering to SURFEX executables in your <new_uenv> (if any):

Finaly, copy the lines from file file surfex_executables_${VER_MPI}_${surfex_commit} into the file <new_uenv>:

Your uenv <new_uenv> is now ready to use in your simulations with the following configuration variable in your configuration file:

uenv=uenv:<new_uenv>@<username>

Once your uenv is comlete, archive it with:

uget push env <new_uenv>@<your_username>

Reproductible simulations with custom SURFEX namelists

You can use your own namelists by creating a new user environment from an existing one (Modifying an existing UEnv).

To do so, put your SURFEX namelists in the $HOME/.vortexrc/hack/uget/<your_username>/data/namelists_surfex_vXX directory, and replace the line starting with “NAMELIST_SURFEX” in the file $HOME/.vortexrc/hack/uget/<your_username>/env/<new_env_name> with :

NAMELIST_SURFEX="uget:namelists_surfex_vXX.tar@<your_username>"

You can now use your own namelists by adding the “namelist_surfex_uenv=uenv:<new_env_name>@<your_username>” configuration variable to your configuration file. Specify the name of your target namelist from your pool of namelists with the namelist_source variable. For example if your $HOME/.vortexrc/hack/uget/<your_username>/data/namelists_surfex_vXX directory contains two namelists named “OPTIONS_PAPPUS.nam” and “OPTIONS_NO_PAPPUS.nam”, you can choose to use the “OPTIONS_PAPPUS.nam” namelist with the following lines in your configuration file “first_test.ini”:

[surfex]
namelist_surfex_uenv=uenv:new_env_name@<your_username>
namelist_source=OPTIONS_PAPPUS.nam

and the associated mkjob command line would be :

mkjob -f surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/first_test.ini -a xpid=first_test datebegin=2020080106 dateend=2021080106 geometry=cor2_allslopes

This allows you to clearly identify the specific SURFEX configuration associated with your xpid, and to keep a written and traceable record of your different simulations.

Note

To fine-tune your configurations, use the ‘mkjob-help -a Crocus -c deterministic -d surfex –bytask’ command. This will tell you the list of possible configuration variables for each task of the surfex driver.

Simulations based on other FORCING files

If you want to use a FORCING file not coming from the S2M reanalysis, you have to provide some of the following variables :

  • the forcing_vapp : providing the vapp level of the target FORCING file (optional, by default the simulation’s vapp : “Crocus”)

  • the forcing_vconf : providing the vconf level of the target FORCING file (optional, by default the simulation’s vconf : “determinitic”)

  • the forcing_xpid : providing the xpid level of the target FORCING file (optional, by default the simulation’s xpid)

  • the forcing_user : providing the name of the user who produced the FORCING file (optional if you produced the FORCING file yourself)

  • the forcing_block : providing the block level of the target FORCING file (optional, by default “meteo”)

You can also provide additional information, such as:

  • the forcing_member providing a specific member value if the target FORCING file is part of an ensemble

  • the forcing_source_app and/or forcing_source_conf, if relevant

Note

The geometry of the FORCING file should be the same as the simulation’s geometry, but you can make this explicit by setting the forcing_geometry variable. IMPORTANT : this geometry must be properly described in your “geometries.ini” file in case it is a custom geometry.

Note

If the target FORCING file was produced before the migration to the version 2 of vortex, you also have to add “forcing_vortex1=True”

The following example illustrates the launch of a SURFEX/Crocus simulation with a 2D FORCING file from the ensemble “ALPAGA” experiment.

First, create a copy of “default_conf.ini” into a “first_test.ini” configuration file.

cd $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf
cp default_conf.ini first_test.ini

The add the target forcing description and your surfex uenv informations to the “first_test.ini” configuration file:

[surfex]
surfex_uenv=new_env_name
namelist_source=OPTIONS_PAPPUS.nam
forcing_xpid=ALPAGA
forcing_user=vernaym
forcing_member=0  # or member = 0 if you want the output file stored in a "mb000" sub-directory.
forcing_vapp=edelweiss
forcing_vconf=grandesrousses250m
forcing_vortex1=True

Then launch mkjob with the “first_test.ini” configuration file in the “-c” argument

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/first_test.ini -a xpid=first_test datebegin=2021080107 dateend=2022080106 geometry=GrandesRousses250m

Configuring your job

You can set your job configuration with the following variables :

  • time : the job’s wall time (default : “0:20:00”, 20 minutes)

  • nnodes : the number of nodes to allocate to the job (default : 1)

  • partition : the target partition (default : normal256)

For example, to increase your job’s wall time to 1 hour, add “time=1:00:00” to your first_test.ini configuration file:

[surfex]
surfex_uenv=new_env_name
namelist_source=OPTIONS_PAPPUS.nam
forcing_xpid=ALPAGA
forcing_user=vernaym
forcing_member=0  # or member = 0 if you want the output file stored in a "mb000" sub-directory.
forcing_vapp=edelweiss
forcing_vconf=grandesrousses250m
forcing_vortex1=True
time=1:00:00

Reproductibility check

In certain situations, you may wish to verify that the files produced are identical to the reference files produced by a previous experiment that you are attempting to replicate. In this case, simply provide the reference experiment identifier in the “diff_xpid” configuration variable (and optionaly the username of the owner of this experiment in the “diff_user” configuration variable and the block in the “diff_block” configuration variable) :

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/default_conf.ini -a xpid=first_test datebegin=2020080106
dateend=2021080106 geometry=cor2_allslopes diff_xpid=<reference_xpid> [diff_user=<username>] [diff_block=<block_of_reference_file>]

Note

the diff_* variables can be parsed directly in the mkjob command line since they don’t affect the simulation’s output

Debug mode

In certain situations, you may wish to check the state of your simulation’s working directory, even if your simulation did not crash (in this case the working directory is removed at the end). To do so, you can add “debug=True” to the ‘-a’ option of your mkjob command line :

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/default_conf.ini -a xpid=first_test datebegin=2020080106
dateend=2021080106 geometry=cor2_allslopes debug=True

This will force the simulation to crash at the very end to ennsure that the working directory is preserved under /scratch/mtool/<username>/abort.

Reproduce s2m test cases

S2M reanalysis test case

s2m command:

s2m research -r alp_allslopes -b 20220801 -e 20230801 -m safran -f reanalysis2020.2 -o reanalysis_test -n $SNOWTOOLS_CEN/snowtools/DATA/OPTIONS_V9_reanalysis.nam

Equivalent command in snowtools3 :

mkjob -c $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/conf/s2m_reanalysis_testcase.ini -f $SNOWTOOLS_CEN/vortex_cen/Crocus/deterministic/jobs/surfex.job -a datebegin=2022080106 dateend=2023080106 geometry=alp_allslopes test=True

S2M ESCROC test case

s2m command:

s2m research -r cdp -b 1994100101 -e 2014100100 -x 2014100100 -m ESM-SnowMIP -f obs@lafaysse -o E2_test --task=escroc --escroc=E2

Equivalent command in snowtools3:

mkjob -c $SNOWTOOLS_CEN/vortex_cen/Crocus/escroc/conf/s2m_escroc_testcase.ini -f $SNOWTOOLS_CEN/vortex_cen/Crocus/escroc/jobs/escroc.job -a datebegin=1994100101 dateend=2014100100 geometry=cdp test=True

Stochastic perturbations test case

s2m command (seems to work only for user lafaysse):

s2m research -r cor_flat -b 20200801 -e 20210801 -m s2m -f reanalysis2020.2 -o perturb --task='croco_perturb' --nmembers=80

Equivalent command in snowtools3:

mkjob -c $SNOWTOOLS_CEN/vortex_cen/meteo/semidistributed/conf/s2m_stochastic_perturbation_test_case.ini -f $SNOWTOOLS_CEN/vortex_cen/meteo/semidistributed/jobs/perturbations.jobs -a datebegin=2020080106 dateend=2021080106 geometry=cor_flat test=True

Croco openloop test case

The following s2m unit test fails because of missing SURFEX executables under /home/cnrm_other/cen/mrns/lafaysse/SURFEX/cen/exe_mpi:

# before running this test case, please define postes_12_csv geometry in $HOME/.vortexrc/geometries.ini as in ~lafaysse/.vortexrc/geometries.ini

s2m research -r postes_12_csv -b 2013080106 -e 2014063006 -x 20160801 -m safran -f forcing_20132014B_31D_11_t1500_160@fructusm -o testopenloop -n ~lafaysse/croco/OPTIONS_MOTHER_DEP.nam --task='croco' --croco='openloop' --escroc=E1notartes --nmembers=35 --nforcing=35 --conf=/home/lafaysse/croco/conf.ini -s ~lafaysse/SURFEX/cen/exe_mpi
# snowtools.utils.FileException.FileNameException: Unknown file : /home/cnrm_other/cen/mrns/lafaysse/SURFEX/cen/exe_mpi/PGD

The following command works at the time this documentation is writen, with no guarantee that it will continue to work in the future:

s2m research -r grandesrousses -b 2019080106 -e 2020080106 -m s2m -f perturb.reanalysis2020.2@lafaysse -o testopenloop -n /home/cnrm_other/cen/mrns/vernaym/.vortexrc/hack/uget/vernaym/data/s2m_testcase_namelists/OPTIONS_croco_openloop.nam --task='croco' --croco='openloop' --escroc=E1notartes --nmembers=35 --nforcing=35 --conf=/home/cnrm_other/cen/mrns/vernaym/tmp/croco_openloop/conf.ini -s /home/cnrm_other/cen/mrns/vernaym/tmp/croco_openloop

Equivalent command in snowtools3:

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/assim/jobs/croco_openloop.job -c /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/Crocus/assim/conf/s2m_croco_test_case.ini -a datebegin=2019080106 dateend=2020080106 geometry=grandesrousses test=True

Note

This test crashes with SURFEX executables corresponding to tag “crocus3.0.2”

Croco test case with assim of real observations

s2m unit test:

s2m research -r postes_12_csv -b 2013080106 -e 2014063006 -x 20160801 -m safran -f forcing_20132014B_31D_11_t1500_160@fructusm -o test0l -n ~lafaysse/croco/OPTIONS_MOTHER_DEP.nam --task='croco' --croco='real' --escroc=E1notartes --nmembers=35 --nforcing=35 --conf=/home/lafaysse/croco/conf.ini -s ~lafaysse/SURFEX/cen/exe_mpi --obsxpid=obs@lafaysse --sensor=bdclim

Note

This test fails because executables under ~lafaysse/SURFEX/cen/exe_mpi are missing

Croco-assim command in snowtools3 :

mkjob -f $SNOWTOOLS_CEN/vortex_cen/Crocus/assim/jobs/croco_assim.job -c /home/cnrm_other/cen/mrns/vernaym/snowtools/vortex_cen/Crocus/assim/conf/s2m_croco_test_case.ini -a datebegin=2019080106 dateend=2020080106 geometry=grandesrousses test=True

Replay operational analysis and forecast

s2m unit test (fail)

s2m oper -b 2025091503 -r alp --dev
s2m oper -b 2025091503 -r alp --task='forecast' --dev

Equivalent commands in snowtools3 :

s2m_oper -j surfex_ana -d 2026080603 -r alp
s2m_oper -j surfex_prv -d 2026080603 -r alp

Building of reforecast initial conditions test case

s2m unit test:

s2m research -r vog3_allslopes -b 20000801 -e 20010801 -a 400 -m s2m -f reanalysis_era5.2023 -p reanalysis_era5.2025.2 -o initialconditions_test -n $SNOWTOOLS_CEN/snowtools/DATA/OPTIONS_V9_reanalysis_forprep.nam --task='surfex_dailyprep' --walltime='00:45:00'

Equivalent command in snowtools3 : TODO : voir avec Sabine

Reforecast test case

s2m unit test:

s2m research -b 20000302 -e 20000327 -r vog3_allslopes -n /home/cnrm_other/cen/mrns/lafaysse/PycharmProjects/snowtools_git/snowtools/DATA/OPTIONS_reforecast.nam --task='reforecast' -m safran -f reforecast_2023 --nmembers=11 -p initdaily_era5.2025.2@lafaysse -o reforecast_test

Equivalent command in snowtools3: TODO : voir avec Sabine quand ça sera prêt

Specific launchers

The s2m_reanalysis launcher

This script is designed to launch Surfex simulations based on the SAFRAN reanalysis with a dynamic walltime depending on the simulation’s geometry and duration.

It takes the following arguments :

  • A configuration file (‘-c’ shortcut) similar to the ‘-c’ argument of mkjob, but allowing to provide a file name instead of an absolute path

  • The simulation’s datebegin with a “-b” alias. If not provided, the datebegin’s hour is set to 6h.

  • The simulation’s dateend with a “-e” alias. If not provided, the datebegin’s hour is set to 6h.

  • The simulation’s geometry with a “-g” alias. The geometries values are limited to the standard SAFRAN-reanalysis geometries

  • A “-a” argument to parse additional command-line arguments as in mkjob

Unlike mkjob, this script allowss to avoid setting the walltime of the job explicitly. It is instead computed as a multiplication between the number of simulation years and the standard walltime for a 1-year simulation in the given geometry and with a standard SURFEX parametrisation.

Usage example :

s2m_reanalysis -b 20200801 -e 20250801 -g cor2_allslopes -c s2m_reanalysis.ini

To overwrite the automatic walltime, use the standard mkjob command or the “-a” argument :

s2m_reanalysis -b 20200801 -e 20250801 -g cor2_allslopes -c s2m_reanalysis.ini -a time=2:00:00

The s2m_oper launcher

This script is designed to launch the real-time S2M chain.

It takes the following arguments :

  • The simulation’s rundate (wich entirely defines the simulation period)

  • The target job description file

Additional arguments are available for development use only :

  • The simulation’s region (which defines both the “geometry” and the “vconf”). By default, simulations are launched for all operationnal regions.

  • A “-a” argument to parse additional command-line arguments as in mkjob

Standard usage example:

s2m_oper -j surfex_ana -d 2026081306

Usage example in a development context (simulation over one region only):

s2m_oper -j surfex_ana -d 2026081306 -r cor

Note

The s2m_oper script is used to operate the S2M real time chain. The scheduling of the different elements of the chain can be done by installing the cron provided in the file vortex_cen/s2m/oper/cron.txt

The assim launcher

This script allows to launch a SURFEX/Crocus experiment with snow data assimilation.

Such an experiment is a loop over the following sequence of actions over a set of assimilation dates:

  1. Run an ensemble of SURFEX/Crocus simulations (OFFLINE executable) with an MPI parallelisation until an assimilation date. All simulation members are initialised with the same initial conditions (PREP file). –> Associated task : “offline_openloop”

  2. Assimilate an available snow observation at the assimilation date with a Particle Filter (SODA executable)

  3. Run an ensemble of SURFEX/Crocus simulations (OFFLINE executable) with an MPI parallelisation from the last assimilation date, until the next assimilaiton date (or the date of end simiulation). The difference with the execution of step 1 is that this time, each simulation member is initialised by specific initial conditions (PREP file) coming from step 2 (SODA analysis). –> Associated task : “offline_assim”