-
Notifications
You must be signed in to change notification settings - Fork 10
Land‐Atmosphere DAS Instructions
The GEOS land-atmosphere data assimilation system (LADAS) is an atmospheric data assimilation system (ADAS) with a weakly-coupled land analysis (Reichle et al. 2023).
This page provides an overview of how to build, set up, and run the LADAS.
The LADAS comprises the GEOS atmospheric data assimilation system (ADAS) and the GEOS land data assimilation system (LDAS), which are built by ADAS with LDAS as an external grid component. An LADAS experiment is set up by ADAS with the option of coupling to LDAS. The overall LADAS workflow is managed by the ADAS scripts. The coupling between the ADAS and the LDAS is achieved through file exchange.
The following instructions apply when the ADAS is run in Hybrid-4DEnVar mode. When the ADAS is run in 3DVar mode, ignore the instructions for the atmospheric ensemble (atmens).
Follow the instructions on “How to build GEOS ADAS”. As of April 2024, use GEOSadas tag "ADASldasGC_GEOSadas-5.30.2". The ADAS build script will build both ADAS and LDAS.
The ADAS component needs to know about the LDAS experiment name and location, and vice versa. Prior to configuring the ADAS and LDAS components, decide on ADAS and LDAS experiment names and directories. The default LDAS experiment name and location in ADAS setup script is "[ADASHOME]/lana/[ADAS_EXPID]_LDAS" and "[ADASHOME]/lana/[ADAS_EXPID]_LDAS4ens" for deterministic and ensemble coupling, respectively.
a) ADAS
Use the general instructions on “Setting up GEOS ADAS experiments" with the following additional guidance:
(i) It is highly recommended to prepare an ADAS_EXPID.input and use "runjob -l ADAS_EXPID.input" to set up an LADAS experiment. In the ADAS_EXPID.input, choose the following answers to couple the ADAS and the LDAS:
Land DAS Analysis (y/n)?
> y
Enable LDAS feedback to model y/n ?
> y
LDAS HOME ? [default: $fvhome/lana/${exp_id}_LDAS]
>
LDAS HOME for atmens ? [default: $fvhome/lana/${exp_id}_LDAS4ens]
>
Note: If the ADAS will be run with a 3DVar atmospheric analysis, the prompt of "LDAS HOME for atmens " should not be present.
(ii) Before submit runjob execution, prepare LDAS setup input files named as "det_exeinp.txt, det_batinp.txt" and "ens_exeinp.txt, ens_batinp.txt" for deterministic and ensemble coupling, respectively. These files need to be placed or symbolic-linked in the same directory with the runjob script.
(iii) After runjob (execution of setup ADAS with LDAS under [ADASHOME]/lana/ ) has completed, change the resource parameter for adding the LDAS increments into the AGCM during the Corrector segment to LDAS_INCR: 1 in the following files:
run/AGCM.rc.tmpl
run/AGCM_BOOTSTRAP.rc.tmpl
run/atmens/AGCM.rc.tmpl
fcst/AGCM.rc.tmpl
The latter two files are not relevant if the ADAS is run with a 3DVar atmospheric analysis or without forecasts, respectively.
(iv) The ADAS must write out the surface meteorological forcing data for the LDAS. To this end, edit the following HISTORY files:
run/HISTORY.rc.tmpl
run/atmens/HISTAENS.rc.tmpl
to include output of the following land forcing ("lfo") collections:
'tavg1_2d_lfo_Nx+-'
'inst1_2d_lfo_Nx+-'
with specifications as for the standard '[tavg1,inst1]_2d_lfo_Nx' collections except for:
[tavg1, inst1]_2d_lfo_Nx+-.ref_date: >>>IOBBKGD<<< ,
[tavg1, inst1]_2d_lfo_Nx+-.ref_time: >>>IOBBKGT<<< ,
[tavg1, inst1]_2d_lfo_Nx+-.end_date: >>>IOEBKGD<<< ,
[tavg1, inst1]_2d_lfo_Nx+-.end_time: >>>IOEBKGT<<< ,
Additionally, do not specify [tavg1, inst1]_2d_lfo_Nx+-.grid_label such that this output is written on the native cube-sphere grid by default.
(v) Edit the following files to include the collections for LDAS forcing of (iv) above:
run/silo.arc
run/mstorage.arc
b) LDAS
Use the general instructions on “How to Set Up (Configure) and Run GEOSldas” with the following additional guidance:
When the ADAS is using a Hybrid-4DEnVar atmospheric analysis, two separate LDAS experiments need to be configured, one that is coupled to the deterministic ("central") component and one that is coupled to the ensemble component of the Hybrid-4DEnVar ADAS. The resolution (tile space) of each LDAS instance must match that of the corresponding ADAS instance.
(i) When creating the LDAS setup input file `det_expinp.txt' which ADAS setup script will use in LADAS setup (as described in a) above), the following examples provide guidance:
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/sample_config_files/LADAS/expinp.txt.Hy4dEnVar.central
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/sample_config_files/LADAS/expinp.txt.Hy4dEnVar.atmens
The LDAS resource variable settings in the above files are specifically for the LADAS configuration. Default values can be used for resource variables not included in the above files.
(ii) Edit [ADASHOME]/lana/[ADAS_EXPID]_LDAS/run/HISTORY.rc to include output of the Catchment model analysis increments ("catch_progn_incr") collection:
For the LDAS coupled to the deterministic ADAS component: ‘catch_progn_incr’
For the LDAS coupled to the ADAS ensemble component: ‘catch_progn_incr0001’.
...,
‘catch_progn_incr0032’
Make sure that the reference time-of-day for the land analysis is centered within the land analysis windows. E.g., when using two 3-hourly analysis windows within each 6-hourly atmospheric analysis window, the land analyses should happen at 1:30z, 4:30z, ..., 22:30z, which requires:
catch_progn_incr[XXXX].reftime: 013000
The following example files can be used as guidance:
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/sample_config_files/LADAS/HISTORY.rc.central
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/sample_config_files/LADAS/HISTORY.rc.atmens
The example file HISTORY.rc.atmens was created with the following python script:
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/util/config/generate_catchincr_hist.py
a) Stage initial surface meteorological forcing files
Surface meteorological forcing files for the initial LADAS cycle must be provided. Typically, these files are available from a brief, ADAS-only spinup experiment.
For example, if the initial LADAS cycle is for 20181217 0900z-1500z, the following surface meteorological forcing files are required:
[ADAS_EXPID]_tavg1_2d_lfo_Nx+- : 20181217 0830z, 0930z, ..., 1430z
[ADAS_EXPID]_inst1_2d_lfo_Nx+- : 20181217 0900z, 1000z, ..., 1500z
These files should match the specifications of the "lfo" output in the ADAS HISTORY.rc files (see above) and must be copied to into the following directories (without year/month subdirectories):
For the LDAS coupled to the deterministic ADAS component: [ADASHOME]/lana/[ADAS_EXPID]_LDAS/input/met_forcing/
For the LDAS coupled to the ADAS ensemble component: [ADASHOME]/atmens/ensdiag/mem[XXX]/
Note that the asymmetry in the treatment of the surface meteorological forcing files for the deterministic (central) and ensemble components is a consequence of the different treatment of this output in the two components of the ADAS.
b) Consistency checks
Ensure that the following conditions are satisfied:
(i) The start date/time in the ADAS recycle/rst time tag matches that in the LDAS run/cap_restart file.
(ii) The ADAS home directory is correct in the LDAS run script(s).
(iii) The LDAS home directories are correct in the ADAS run script.
(iv) The model resolution in the deterministic component of the ADAS matches that of the corresponding LDAS instance. Likewise for the ensemble component of the ADAS and the corresponding LDAS instance.
(v) The number of ensemble members in the ensemble component of the ADAS matches that of the corresponding LDAS instance.
Execute sbatch $FVHOME/run/g5das.j to start the LADAS run.
If a crash occurs in the ADAS, follow the instructions on “Handling Crashes“ and consult the “FAQ“ in Todling and El Akkraoui (2019).
If a crash (or clean exit) occurs in the LDAS, follow the instructions on “What to Do When GEOSldas Does not Run”.
Before resuming a cycle, make sure that the ADAS and LDAS start date/time values match. The script
GEOSadas/src/Components/@GEOSldas_GridComp/GEOSldas_App/util//config/rewind_ldas.csh
can be used to rewind the LDAS to the restart date/time of the ADAS.