SURFEX

Course Material

Patrick LE MOIGNE — 2026-03-30T07:55:59Z

PRESENTATIONS
- Surfex General presentation
- SURFEX installation and compilation
- ECOCLIMAP and PGD
- PREP
- ISBA
- TEB
- Water scheme

PRACTICAL EXERCISES
Exercises

CORRECTIONS
- ISBA
- ISBA_snow
- TEB
- FLake
- 2D case

Libraries package

Minvielle — 2026-02-02T16:35:39Z

LIB-SURFEX-9-1-0.tar.gz

Install an run a pre-defined experiment

Minvielle — 2026-01-29T15:30:54Z

How to install a pre-defined experiment:

in new terminal, in src/ directory
export VER_USER=FORC
run ./configure
./configure
execute the profile file corresponding to this user version of surfex
. ../conf/profile_surfex-LXgfortran-SFX-V9-1-0-FORC-MPIAUTO-O2-X0
run make user and make installuser to create the specific executables in directory exe/
make user
make installuser
go into MY_RUN/FORCING directory and run prepare_forcing.bash with a name of experiment as argument. For example, here, the experiment 'hapex'
./prepare_forcing.bash hapex
A namelist MY_PARAM.nam will open (vi editor). For the first time, it's not necessary to modify this namelist. So, you can simply quit (use command :q)
Some information will then be written on the screen and should look like:
— namelist NAM_MY_PARAM read
> ==========================================
> PREP_INPUT_EXPERIMENT: YEXPER = HAPEX
> PREP_INPUT_EXPERIMENT: INI = 1
> PREP_INPUT_EXPERIMENT: INPTS = 17521
> PREP_INPUT_EXPERIMENT: JNPTS = 17521
> PREP_INPUT_EXPERIMENT: ZTSTEPFRC = 1800.
> PREP_INPUT_EXPERIMENT: YFORCING_FILETYPE = NETCDF
> ===========================================
YFILE_FORCIN=../DATA/hapex/HAPEX.DAT.30
– rw-r—r— 1 lemoigne mc2 1543644 jui 22 16:51 /home/lemoigne/surfex/open_SURFEX_V8_1/MY_RUN/FORCING/FORCING.nc
==============================================
> input files moved to /home/lemoigne/surfex/open_SURFEX_V8_1/MY_RUN/KTEST/hapex
==============================================
Once the installation is done, go to $SRC_SURFEX/MY_RUN/KTEST/hapex directory and launch successively:
./pgd.exe
./prep.exe
./offline.exe
If you code is correctly installed and compiled, PGD, PREP and OFFLINE PGD should run correctly, and you should get .TXT output files in your run directory.

Practical changes

Minvielle — 2026-01-29T08:52:49Z

On a practical point of view, the following differences are noted between version 8_0 and version 8_1:

New developments in SURFEX V8.1.0

Minvielle — 2026-01-29T08:50:05Z

This version contains the following novelties:

Changes in namelists in SURFEX V9.1.0

Minvielle — 2026-01-28T16:50:38Z

Changes are detailed by contribution.
- New keys are in black
- Keys removed in red
- Keys modified (new options, options removed, changes of default values, name changed, change of namelist) in orange
- New namelist in green

NAM_ISBA
- NSAND_LAYER: number of sand layers. Equal to 1 if CISBA = "2-L" or "3-L". Must be equal to 1 or to the number of ground layers if CISBA="DIF".
- NCLAY_LAYER: number of clay layers. Equal to 1 if CISBA = "2-L" or "3-L". Must be equal to 1 or to the number of ground layers if CISBA="DIF".
- CGNDRES : to activate baresoil evaporation resistance options

NAM_MEB_ISBA :
- LMEB_GNDRES is removed (replaced by CMEB_GNDRES)
- CMEB_GNDRES : Activates baresoil evaporation resistance options
- LMEB_TALL_VEG : To use vegetation height as a major variable to calculate maximum snow load on trees and turbulent fluxes.
- LMEB_INT_PLUN : If True, to use the (Lundquist et al., 2021) intercepted snow melt formulation. The snow intercepted by the trees melts faster than using the classical config.
- LMEB_INT_ULUN : If True, to use the snow unloading scheme of (Lundquist et al., 2021). This scheme is globally slowing the solid unloading, which favors snowmelt and sublimation of the intercepted snow as it stays a bit longer on the branches.
- LMEB_INT_USFC : To separate snow unloading from snowfalls in Crocus fresh snow incorporation.

NAM_ISBAn
- CZ0HEAT : roughness length for heat
- XZ0HEAT : factor to calculate Z0H when CZ0HEAT="Z95"

NAM_PREP_ISBA
- XHUG_SURF is removed (replaced by XUNIF_HUG_SOIL)
- XHUG_ROOT is removed (replaced by XUNIF_HUG_SOIL)
- XHUG_DEEP is removed (replaced by XUNIF_HUG_SOIL)
- XHUGI_SURF is removed (replaced by XUNIF_HUGI_SOIL)
- XHUGI_ROOT is removed (replaced by XUNIF_HUGI_SOIL)
- XHUGI_DEEP is removed (replaced by XUNIF_HUGI_SOIL)
- CFILE_HUG_SURF is removed (replaced by CFILE_HUG_SOIL)
- CFILE_HUG_ROOT is removed (replaced by CFILE_HUG_SOIL)
- CFILE_HUG_DEEP is removed (replaced by CFILE_HUG_SOIL)
- XTG_SURF is removed (replaced by XUNIF_TG_SOIL)
- XTG_ROOT is removed (replaced by XUNIF_TG_SOIL)
- XTG_DEEP is removed (replaced by XUNIF_TG_SOIL)
- CFILE_TG_SURF is removed (replaced by CFILE_TG_SOIL)
- CFILE_TG_ROOT is removed (replaced by CFILE_TG_SOIL)
- CFILE_TG_DEEP is removed (replaced by CFILE_TG_SOIL)
- XUNIF_HUG_SOIL : uniform prescribed value for soil wetness index profile
- XUNIF_HUGI_SOIL : uniform prescribed value for ice soil water index profile
- XUNIF_TG_SOIL : uniform prescribed value for soil temperature profile
- CFILE_HUG_SOIL : input file name for Wg, Wgi. The dimension of this key is (NVEGTYPE, NGROUND_LAYER)
- CFILE_TG_SOIL :input file name for TG. The dimension of this key is (NVEGTYPE, NGROUND_LAYER)

NAM_DIAG_FLAKEn
- LSEDIM_PROFIL : flag for sediment diagnostics
- XZSED_PROFILE : depth of output levels (m) in namelist
- LFLKFLUX : flag for heat and radiative diagnostics
- LFLKWATER : flag for water budget P-E diagnostics

NAM_IO_OFFLINE
- CSPECSNOW (removed, replaced by CSPECSNOW)
- LSPECSNOW (before CSPECSNOW)
- LFIX_OUTPUT : logical to force diags output each day at hours that are multiple from the XSTEP_OUTPUT

NAM_SURF_SNOW_CSTS
- XPERCENTAGEPORE_FRZ
- XIMPUR_WET : corresponds to the initial amount of Light-Absorbing Particles (LAP) present in the falling snow (wet deposition) for each impurity type
- XIMPUR_DRY : corresponds to the dry deposition coefficient (always activated) at top of snowpack (in g/m2/s) for black carbon (XIMPUR_DRY(1)), dust (XIMPUR_DRY(2)), and other types of impurities (XIMPUR_DRY(3:5))
- XIMPUR_INIT removed
- XIMPUR_COEF removed
- XPR_A : Adjustable coefficients depending on snow-gun type (Hanzer et al., 2014).
- XPR_B : Adjustable coefficients depending on snow-gun type (Hanzer et al., 2014).
- XPT : Water consumption threshold during base-layer generation production period
- XPP_D1 : Day of beginning of base-layer generation production period. For CROCUS resort only.
- XPP_D2 : Day of end of base-layer generation production period. For CROCUS resort only.
- XPP_D3 : Day of end of reinforcement production period. For CROCUS resort only.
- XPP_H1 : Hour of beginning of base-layer generation production period (in seconds, from midnight). For CROCUS resort only.
- XPP_H2 : Hour of end of base-layer generation production period (in seconds, from midnight). For CROCUS resort only.
- XPP_H3 : Hour of beginning of reinforcement production period (in seconds, from midnight). For CROCUS resort only.
- XPP_H4 : Hour of end of reinforcement production period (in seconds, from midnight). For CROCUS resort only.
- XWT : Wind speed threshold for snowmaking (m/s)
- XPTR : Total (natural+machine-made) snow height threshold during reinforcement production period (m)
- XSCAVEN_COEF : percentage of impurity leaving with percolating water
- XAGELIMPAPPUS : maximum age (days) of snow layer for which wind speed threshold is set to fresh threshold wind speed
- XWINDTHRFRESH : 5m wind speed threshold for transport of freshly fallen (or deposited) snow
- XRHODEPPAPPUS : density (kg.m^-3) of wind blown deposited snow
- XDIAMDEPPAPPUS : optical diameter (m) of wind blown deposited snow
- XSPHDEPPAPPUS : sphericity of wind blown deposited snow
- XLFETCHPAPPUS : constant fetch distance applied to all points for snowpappus blowing snow flux calculation (m)
- XAGELIMPAPPUS2 : maximum age (in days) of snow for using Naaim96 formulation of terminall fall speed in snowpappus
- XDEMAXVFALL : maximum dendricity to have pure young snow fall speed, when option MIXT is chosen for terminal fall speed calculation
- XCROCOEF_FF: to have the possibility to change the coefficient for gust diagnosis from average wind

NAM_ISBA_SNOW
- CSNOWMOB : To choose the way threshold wind speed is computed in SnowPappus when surface snow age is superior to the threshold value XAGELIMPAPPUS
- LSNOWPAPPUS : key to activate SnowPappus option.
- CSNOWPAPPUSERODEPO : determines how the deposition flux is computed.
- CSNOWFPAPPUS : overcomes 'CSNOWDRIFT' to select falling snow microstructure.
- CPAPPUSSUBLI : to choose different parameterizations of blowing snow sublimation rate in SnowPappus
- CSALTPAPPUS : option for saltation transport in SnowPappus
- CLIMVFALL : option to decide what is old or new snow for fall speed calculation
- OPAPPULIMTFLUX : if True, snow transport flux limitation activated.
- OPAPPUDEBUG : if True, triggers snowpappus debug mode.

NAM_DIAG_ISBAn
- LSPECMOD : flag fot snow modis spectral bands diagnostic

NAM_ASSIM
- CASSIM_ISBA : new option 'PF' (for Particle Filter activation in SODA)
- LCROCO : Activation of assimilation for snow scheme Crocus
- CPF_CROCUS : Select the PF (Particle Filter) algo
- NEFF_P : set the target effective sample size for the PF with inflation
- XDLOC_PF : localisation distance (degrees) for the RLOCAL particle filter
- LLOO_PF : activate leave-one-out experiments with the PF (exclude local observations)

NAM_VAR
- XTAUSCF : value for the tau parameter of the depletion curve used to retrieve model SCF from bulk SWE (default=4)
- XCEILSCF : value for the ceil SWE of the depletion curve (default=20mm)

NAM_OBS
- COBS_M : new options possible
- XERROBS_FACTOR_M : magnification factor for obs errors in PF

New developments in SURFEX V9.1.0

Minvielle — 2026-01-28T16:50:14Z

CEN - Crocus

Particle filter in SODA : assimilation of snow depth, optical reflectance, wet snow product (Cluzet et al., 2021, 2022 ; Deschamps-Berger et al., 2022)
Externalization of Crocus with other surface schemes (SVS2, Woolley et al., in review ; FSM2, Mazzotti et al., in review)
Technical optimizations (loops) and cleaning (snow3L_isba), Crocus tests in STRATO
NetCDF4 outputs and compression (optional)
New snow metamorphism B21 (Baron, 2023 ; Lafaysse et al., 2025)
Ice formation when freezing rain (Quéno et al., 2018)
SnowPappus blowing snow transport model for 2D offline simulations (with MPI communications)
(Baron et al., 2024 ; Haddjeri et al., 2024)
Adaptation of snow interception, melt and unloading in MEB for mid-latitudes. Improvement of MEB-Crocus coupling.

SURFACE

MEB : new physics option for ISBA and ISBA-MEB. The addition of an option for both ISBA and ISBA-MEB to include a baresoil resistance for the baresoil evaporation computation. See Marti et al. (2025) for details.
MEB : MEB can be used now for all covers (including low vegetation) except for ROCK, BARESOIL and PERMANENT SNOW patches. Before it was limited to forest patches only.
MEB bugfix : A bugfix of the call to cotwores.F90 from isba_meb.F90 was corrected which caused patch memory to be lost (when using MEB). This redundancy lead to some bugs. This has no impact on results except with MEB-it avoids a bug.
Multi-level initialization for ISBA : it's now possible to initialize temperature and water content for each soil level, and not only SURF/ROOT/DEEP. For exemple, if DIF is used, is now possible to give a value of TG and WG for each of the 14 soil levels. This development leads to a modification of the keys to initialize ISBA. Please refer to the section dedicated to changes of namelist.
Multi-layer texture : possibility to give sand and clay fractions for different soil levels
Ags revision
Landuse/landcover revision
Add of some FLake diagnostics
Optimization
some technical modifications (for MASCOT project) without impact for the user
modifications to prepare possible compilation with cmake without impact for the user
bugfixes

About the types from SURFEX V8.0

Minvielle — 2026-01-27T11:07:46Z

Let's take coupling_isban.F90, beginning like that:

 SUBROUTINE COUPLING_ISBA_n (DTCO, UG, U, USS, IM, DTGD, DTGR, TGRO, DST, SLT, &

You can further see in the declaration of arguments of the routine:

 TYPE(ISBA_MODEL_t), INTENT(INOUT) :: IM TYPE(DATA_COVER_t), INTENT(INOUT) :: DTCO TYPE(SURF_ATM_GRID_t), INTENT(INOUT) :: UG TYPE(SURF_ATM_t), INTENT(INOUT) :: U TYPE(SURF_ATM_SSO_t), INTENT(INOUT) :: USS TYPE(DATA_TEB_GARDEN_t), INTENT(INOUT) :: DTGD TYPE(DATA_TEB_GREENROOF_t), INTENT(INOUT) :: DTGR TYPE(TEB_GREENROOF_OPTIONS_t), INTENT(INOUT) :: TGRO TYPE(DST_t), INTENT(INOUT) :: DST TYPE(SLT_t), INTENT(INOUT) :: SLT

What tells you the correspondence between the reduced name of the type (ex. IM) and its full name (ex. ISBA_MODEL_t).

Then, if you want to find a more precise description of the contents of each type, you can see upper in the routine:

 USE MODD_SURFEX_n, ONLY : ISBA_MODEL_t ! USE MODD_DATA_COVER_n, ONLY : DATA_COVER_t USE MODD_SURF_ATM_GRID_n, ONLY : SURF_ATM_GRID_t USE MODD_SURF_ATM_n, ONLY : SURF_ATM_t USE MODD_SURF_ATM_SSO_n, ONLY : SURF_ATM_SSO_t USE MODD_DATA_TEB_GARDEN_n, ONLY : DATA_TEB_GARDEN_t USE MODD_DATA_TEB_GREENROOF_n, ONLY : DATA_TEB_GREENROOF_t USE MODD_TEB_GREENROOF_OPTION_n, ONLY : TEB_GREENROOF_OPTIONS_t USE MODD_DST_n, ONLY : DST_t USE MODD_SLT_n, ONLY : SLT_t

So you can then open, for example, modd_surfexn.F90, and see the definition of the type ISBA_MODEL_t:

 TYPE ISBA_MODEL_t ! TYPE(AGRI_t) :: AG TYPE(CH_ISBA_t) :: CHI TYPE(DATA_ISBA_t) :: DTI TYPE(DIAG_EVAP_ISBA_t) :: DGEI TYPE(DIAG_ISBA_t) :: DGI TYPE(DIAG_MISC_ISBA_t) :: DGMI TYPE(GR_BIOG_t) :: GB TYPE(ISBA_CANOPY_t) :: ICP TYPE(ISBA_GRID_t) :: IG TYPE(ISBA_t) :: I TYPE(PACK_CH_ISBA_t) :: PKCI TYPE(PACK_DIAG_ISBA_t) :: PKDI TYPE(PACK_ISBA_t) :: PKI ! END TYPE ISBA_MODEL_t

Then, same way, upper in modd_surfexn.F90, for example:

 USE MODD_PACK_ISBA, ONLY : PACK_ISBA_t

And finally, opening modd_pack_isba.F90:

 TYPE PACK_ISBA_t ! INTEGER :: NSIZE_LSIMPLE INTEGER :: NSIZE_L0 INTEGER :: NSIZE_NSIMPLE (...) REAL, POINTER, DIMENSION(:) :: XP_FFLOOD ! Grdi-cell flood fraction (-) REAL, POINTER, DIMENSION(:) :: XP_PIFLOOD ! Floodplains potential infiltration (kg/m2/s) REAL, POINTER, DIMENSION(:) :: XP_CPS, XP_LVTT, XP_LSTT ! END TYPE PACK_ISBA_t

Normally, the reduced names of the types are always the same, in all routines where they appear as arguments.

These reduced names are all listed in modd_surfexn.F90.

Documentation provided by developers

Minvielle — 2026-01-27T10:41:35Z

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.