CrocO technical doc

Data assimilation of snow observations with CrocO

Implementation of a Particle Filter to assimilate spatialized snow observations within SURFEX platform
Development of vortex task to perform the assimilation sequence on beaufix-hendrix, launched through a s2m (snowtools) command.
User documentation : see CrocO user doc

Cluzet et al., CrocO : a Particle Filter to assimilate snowpack observations in a spatialised framework (in prep)

Git projects :
  • Surfex_Git2, branch cen_dev
  • Vortex, branch cen_assim
  • snowtools_git, branch cen_assim

Main developments

  • Spatialized PF algorithms developped into SURFEX/SODA in global, k-localized and r-localized configurations
  • Use of ESCROC ensemblist version of Crocus (Lafaysse et al. 2017) and perturbed meteorological forcings (Charrois et al., 2016)
  • Use of Vortex (cen_assim branch) /snowtools_git to launch the assimilation sequence on beaufix and store data on hendrix (similarly as described in Run a SURFEX-Crocus experiment with vortex)

Developer name

Bertrand Cluzet

Date of start of development

January 2018

Commit number before the development

  • Surfex_Git2 : b469f610
  • Vortex : 4ab65aa3

Current status

  • Surfex_Git2: Phased in SURFEX V8.1 branch cen_dev, tag CrocO_v1.0
  • Vortex : Phased with recent (late october 2018 (commit 87922088)) cen_assim branch, tag CrocO_v1.0
  • snowtools_git : commit 53e2e16, cen_assim branch, tag CrocO_v1.0

Key technical points (SURFEX)

  • new diag variable SPECMOD to represent sow reflectance in MODIS bands, sampled from SPEC_ALB
  • writing of this diag variable into PREP file (mandatory for soda assimilation)
  • new dimension in PRO file : MODIS_bands
  • in SODA, use of a SURFEX_LIST (vector of SURFEX_TYPE) to store all members (PREP files) before the assimilation mix
  • mixing of PREP is done "manually" in PUT_ALL_VAR_PF.F90. Some fields (..._ISBA) are not mixed at the moment (no need for us.)
    Need to actualize this routine after any change in the SURFEX types and variable names and for new prognostic/cumulated variables
  • LFIX_OUTPUT (see below)
  • reading of obs. in NETCDF.
  • computing Snow Cover Fraction from SWE in PREP : implementation of a depletion curve (Zaitchik et al., 2009, De Lannoy et al., 2012)

Evaluated against SURFEX test database ?

No, in progress.

New test added in the database

No, in progress

Changes in namelist


LASSIM = .TRUE.                       ! Activate Surfex data assimilation  
LCROCO = .TRUE.                       ! Activate CrocO
CASSIM_ISBA = 'PF   '                 ! Particle Filter activation in SODA  (/!\ don't forget the '   ' ) 
CPF_CROCUS = 'GLOBAL' (default)       ! select the PF algo to perform ('GLOBAL', 'RLOCAL', 'KLOCAL')
NLOC_PF = 0 (default)                 ! set the maximal number of obs (>0) to select in the 'RLOCAL' and 'KLOCAL' algo.
NEFF_PF = 1                           ! set the targer effective sample size for the PF with inflation.
NPRINTLEV=1,                          ! verbosity
LEXTRAP_SEA=.FALSE.,                  !  |
LEXTRAP_WATER=.FALSE.,                !  |  Prevent SODA 
LEXTRAP_NATURE=.FALSE.,               !  |  from being too fancy
LWATERTG2=.TRUE.,                     !  |


NOBSTYPE = 8                 ! number of different obs. variables (up to 9)
CFILE_FORMAT_OBS="NC    "    ! daily obs. files on NETCDF file format (/!\ don't forget the '    ' ) 
COBS_M = 'B1','B2','B3','B4','B5','B6','B7','SCF'             ! Names of MODIS bands and Snow cover fraction variables in observation file. (/!\ same length as NOBSTYPE), other possible values : 'DEP', 'R51', R52', 'R53', 'R54'
NNCO = 1,1,1,1,1,1,1,1       ! select which variables to assimilate among COBS_M (/!\ same length as NOBSTYPE)
XERROBS_M = 0.00071, 0.00046, 0.00056, 0.00056, 0.002, 0.0015, 0.00078, 0.05 ! default obs.error *variances* for MODIS bands (charrois PhD manuscript pp 104.,140.), last one is a percentage of value for SCF.
XERROBS_FACTOR_M = 1,1,1,1,1,1,1,1 ! If necessary multiply the prescribed errors by some factors


NVAR=8                     ! number of different model assimilation variables (up to 9)
CVAR_M='PB1','PB2','PB3','PB4','PB5','PB6','PB7','PSB' ! model variables (7 MODIS spectral bands + bulk SWE), other possible values : 'DEP', 'R51', 'R52', 'R53', 'R54'
NNCV = 1,1,1,1,1,1,1,1   ! select which variables to assimilate among CVAR_M
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)


NENS = 1         ! number of ensemble members (overwritten by snowtools_git argument --nmembers)


LSPECMOD = .TRUE.  ! activation of MODIS spectral bands output in PREP, mandatory for assimilation
LPROBANDS = .TRUE. ! mandatory too for MODIS assimilation




LSNOWDIMNC = .TRUE. ! mandatory + activate layer/bands dimensions in PRO
CSELECT = 'SPECMOD' ! add MODIS bands to PRO file


LFIX_OUTPUT = .TRUE. !(default : .FALSE.) : force hours of output in PRO at 00h+n*timestep instead of timestart+ n*timestep (/!\ possible edge effects on cumulated diags)

local testing of SODA

SODA is the executable performing the assimilation. Provided a set of background PREP files and an observation, it produces a set of analyzed PREP files.
It is possible to test the performance of this algorithm locally, (without the use of vortex, snowtoools_git etc.)
For that, simply execute SODA in a repertory where all files are given (Namelist, PGD, PREP files, observations, etc.)
For more details, ask for support.

Other required changes


Forcing files

Spinup files

  • mandatory
  • /!\ V8.0 files are not compatible with V8.1, but it is possible to upgrade it (ask for support).

New files

Assimilation configuration file

  • mandatory
  • named s2m_<region_id>.ini
    - region_id is the safran id of the region (for ex. 12 for Grandes-Rousses)
    - region_name is the safran name of the region (for ex. grandes_rousses for Grandes-Rousses)
  • write down your data assimilation dates (see attached example)
  • some additional information on the experiment are appended to it during the run. It is then archived (see below)
  • For twin experiments and traceability : With ESCROC E1* ensemble, you can prescribe the members you'd like to run, otherwise they will be randomly drawn (and written down in the configuration file)
    ex : membersId = 505, 402, 705

Observation files

  • daily files named obs_<your_sensor>_<region_name>
    ex :
  • NETCDF format(see attached example)
    1. same geometry as PREP/PGD
    2. variables must be double
    3. variables _FillValue must be set to 1.e+20.
      • for synthetical observations, <your_sensor> is free to define.

Particle Filter sample files

  • Output from the assimilation sequence.
  • One file per assimilation date, named PART_YYYYMMDDHH.txt (see attached example, distributed assim with 187pts and 3 members)
  • FORMAT : (DISTRIBUTED assimilation, assimilation per grid point): one line per grid point, then for each line, ids of the replicated members on the corresponding point, separated by spaces
    (SEMI-DISTRIBUTED assimilation, global assimilation) : only one line, ids of the replicated members, separated by spaces

Simulation framework

Simulations are performed on beaufix-hendrix through an s2m command (see added options below).
Vortex requires a strict file storing and naming. The following lines are detailing it.

Forcing files

  • stored in a vortex path on hendrix :
    - xpid_forcing is a user-defined name (usually the name of the experiment that generated the forcings), given to s2m via -f option (see below)

Spinup files

  • named PGD_<region_name>.nc and PREP_<starting_date>.nc
  • stored in a vortex path on hendrix (xxx is "pgd" and "prep" respectively):


  • Stored on beaufix home.

Assimilation Configuration file

  • Stored on beaufix home.

Observation files

  • stored in a vortex path on hendrix :
  • for synthetical observations : do the same.

Simulation outputs storing

If the simulation has succeded :
  • all files are deleted from beaufix
  • PREP and PRO files are stored on hendrix :
    - xpid is specified through s2m -o option, see below
    - xxx is bg, an or pro for backgroud PREP, analysis PREP and PRO files respectively
  • Assimilation configuration file (useful for twin experiments and traceability) is stored in <your_home>/vortex/s2m/<region_id>/conf/
  • Base namelist is also stored in <your_home>/vortex/s2m/<region_id>/conf/ (name
  • PF sample files are stored in <your_home>/vortex/s2m/<region_id>/workSODA/ (name
  • For post-processing and dev, PREP files and the configuration file can also be fetched to sxcen (in /cnrm/cen/users/NO_SAVE/...), which has no backup and limited space (see the options below)

New s2m options/modifications

- w option is useless
- o xpid : output repertory on hendrix
--escroc E1Tartes or E1noTartes : Escroc big ensembles with Tartes only (1944 members) or no Tartes (the rest). nmembers will be randomly drawn from this ensemble between each assimilation date
--croco your_path_to_assimilation_configuration_file : activate CrocO and give the path to your conf file.
--nforcing : numbers of different forcings to use
- f xpid_forcing: xpid for your forcing files on hendrix
--openloop : activate openloop sequence (no assimilation but output at each assimilation date)
--synth mbid : assimilation of synthetic data. Remove and replace the <mbid> member (synthetic truth)
--real : assimilation of real data
--walltime : estimate for execution time on beaufix
--writesx yourpath_to_NO_SAVE_on_sxcen.cnrm: fetch output data directly to a vortex path on sxcen NO_SAVE (/cnrm/cen/users/NO_SAVE/***id***/vortex/)
--sensor your_sensor: specify the name of the sensor used to generate the observations (default :MODIS), or of your synthetical obs.