.. _DASystem: *************************************************** Land Data Assimilation System *************************************************** This chapter describes the configuration of the offline Land :term:`Data Assimilation` (DA) System, which utilizes the UFS Noah-MP component together with the ``jedi-bundle`` (Skylab v4.0) to enable cycled model forecasts. The data assimilation framework applies the Local Ensemble Transform Kalman Filter-Optimal Interpolation (LETKF-OI) algorithm to combine the state-dependent background error derived from an ensemble forecast with the observations and their corresponding uncertainties to produce an analysis ensemble (:cite:t:`HuntEtAl2007`, 2007). Joint Effort for Data Assimilation Integration (JEDI) ******************************************************** .. attention:: Users are encouraged to visit the `JEDI Documentation `__. Much of the information in this chapter is drawn directly from there with modifications to clarify JEDI's use specifically in the context of the Land DA System. The Joint Effort for Data assimilation Integration (:term:`JEDI`) is a unified and versatile :term:`data assimilation` (DA) system for Earth System Prediction that can be run on a variety of platforms. JEDI is developed by the Joint Center for Satellite Data Assimilation (`JCSDA `__) and partner agencies, including NOAA. The core feature of JEDI is separation of concerns. The data assimilation update, observation selection and processing, and observation operators are all coded with no knowledge of or dependency on each other or on the forecast model. The NOAH-MP offline Land DA System uses three JEDI components: * The Object-Oriented Prediction System (:ref:`OOPS `) for the data assimilation algorithm * The Interface for Observation Data Access (`IODA `__) for the observation formatting and processing * The Unified Forward Operator (`UFO `__) for comparing model forecasts and observations JEDI's Unified Forward Operator (UFO) links observation operators with the Object Oriented Prediction System (OOPS) to compute a simulated observation given a known model state. It does not restrict observation operators based on model-specific code structures or requirements. The UFO code structure provides generic classes for observation bias correction and quality control. Within this system, IODA converts the observation data into model-specific formats to be ingested by each model's data assimilation system. This involves model-specific data conversion efforts. Object-Oriented Prediction System (OOPS) =========================================== A data assimilation experiment requires a ``.yaml`` configuration file that specifies the details of the data assimilation and observation processing. OOPS provides the core set of data assimilation algorithms in JEDI by combining the generic building blocks required for the algorithms. The OOPS system does not require knowledge of any specific application model implementation structure or observation data information. In the Noah-MP offline Land DA System, OOPS reads the model forecast states from the restart files generated by the Noah-MP model. JEDI UFO contains generic quality control options and filters that can be applied to each observation system, without coding at certain model application levels. More information on the key concepts of the JEDI software design can be found in :cite:t:`Tremolet&Auligne2020` (2020), :cite:t:`HoldawayEtAl2020` (2020), and :cite:t:`HoneyagerEtAl2020` (2020). JEDI Configuration Files & Parameters ---------------------------------------- To create the DA experiment, the user should create or modify an experiment-specific configuration ``.yaml`` file. This ``.yaml`` file should contain certain fundamental components: geometry, window begin, window length, background, driver, local ensemble DA, output increment, and observations. These components can be implemented differently for different models and observation types, so they frequently contain distinct parameters and variable names depending on the use case. Therefore, this section of the User's Guide focuses on assisting users with understanding and customizing these top-level configuration items in order to run Land DA experiments. Users may also reference the `JEDI Documentation `__ for additional information. Users may find the following example ``GHCN.yaml`` configuration file to be a helpful starting point. A similar file (with user-appropriate modifications) is required by JEDI for snow data assimilation. The following subsections will explain the variables within each top-level item of the ``.yaml`` file. The ``GHCN.yaml`` file for the |latestr| release can be found within the cloned repository at ``DA_update/jedi/fv3-jedi/yaml_files/psl_develop/GHCN.yaml``. .. code-block:: yaml geometry: fms initialization: namelist filename: Data/fv3files/fmsmpp.nml field table filename: Data/fv3files/field_table akbk: Data/fv3files/akbk64.nc4 npx: 49 npy: 49 npz: 64 field metadata override: Data/fieldmetadata/gfs-land.yaml time invariant fields: state fields: datetime: 2019-12-21T00:00:00Z filetype: fms restart skip coupler file: true state variables: [orog_filt] datapath: /scratch2/NAGAPE/epic/UFS_Land-DA/inputs/forcing/era5/orog_files filename_orog: oro_C96.mx100.nc window begin: 2019-12-21T00:00:00Z window length: PT24H background: date: &date 2019-12-21T00:00:00Z members: - datetime: 2019-12-21T00:00:00Z filetype: fms restart state variables: [snwdph,vtype,slmsk] datapath: mem_pos/ filename_sfcd: 20191221.000000.sfc_data.nc filename_cplr: 20191221.000000.coupler.res - datetime: 2019-12-21T00:00:00Z filetype: fms restart state variables: [snwdph,vtype,slmsk] datapath: mem_neg/ filename_sfcd: 20191221.000000.sfc_data.nc filename_cplr: 20191221.000000.coupler.res driver: save posterior mean: false save posterior mean increment: true save posterior ensemble: false run as observer only: false local ensemble DA: solver: LETKF inflation: rtps: 0.0 rtpp: 0.0 mult: 1.0 output increment: filetype: fms restart filename_sfcd: xainc.sfc_data.nc observations: observers: - obs space: name: SnowDepthGHCN distribution: name: Halo halo size: 250e3 simulated variables: [totalSnowDepth] obsdatain: engine: type: H5File obsfile: GHCN_2019122100.nc obsdataout: engine: type: H5File obsfile: output/DA/hofx/letkf_hofx_ghcn_2019122100.nc obs operator: name: Identity obs error: covariance model: diagonal obs localizations: - localization method: Horizontal SOAR lengthscale: 250e3 soar horizontal decay: 0.000021 max nobs: 50 - localization method: Vertical Brasnett vertical lengthscale: 700 obs filters: - filter: Bounds Check # negative / missing snow filter variables: - name: totalSnowDepth minvalue: 0.0 - filter: Domain Check # missing station elevation (-999.9) where: - variable: name: MetaData/height minvalue: -999.0 - filter: Domain Check # land only where: - variable: name: GeoVaLs/slmsk minvalue: 0.5 maxvalue: 1.5 # GFSv17 only. #- filter: Domain Check # no sea ice # where: # - variable: # name: fraction_of_ice@GeoVaLs # maxvalue: 0.0 - filter: RejectList # no land-ice where: - variable: name: GeoVaLs/vtype minvalue: 14.5 maxvalue: 15.5 - filter: Background Check # gross error check filter variables: - name: totalSnowDepth threshold: 6.25 action: name: reject .. note:: Any default values indicated in the sections below are the defaults set in ``letkfoi_snow.yaml`` or ``GHCN.yaml`` (found within the ``DA_update/jedi/fv3-jedi/yaml_files/psl_develop`` directory). Geometry ^^^^^^^^^^^ The ``geometry:`` section is used in JEDI configuration files to specify the model grid's parallelization across compute nodes (horizontal and vertical). ``fms initialization`` This section contains two parameters, ``namelist filename`` and ``field table filename``. ``namelist filename`` Specifies the path for the namelist filename. ``field table filename`` Specifies the path for the field table filename. ``akbk`` Specifies the path to a file containing the coefficients that define the hybrid sigma-pressure vertical coordinate used in FV3. Files are provided with the repository containing ``ak`` and ``bk`` for some common choices of vertical resolution for GEOS and GFS. ``npx`` Specifies the number of grid cells in the east-west direction. ``npy`` Specifies the number of grid cells in the north-south direction. ``npz`` Specifies the number of vertical layers. ``field metadata override`` Specifies the path for file metadata. ``time invariant state fields`` This parameter contains several subparameters listed below. ``datetime`` Specifies the time in YYYY-MM-DDTHH:00:00Z format, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. ``filetype`` Specifies the type of file. Valid values include: ``fms restart`` ``skip coupler file`` Specifies whether to enable skipping coupler file. Valid values are: ``true`` | ``false`` +--------+-----------------+ | Value | Description | +========+=================+ | true | enable | +--------+-----------------+ | false | do not enable | +--------+-----------------+ ``state variables`` Specifies the list of state variables. Valid values include: ``[orog_filt]`` ``datapath`` Specifies the path for state variables data. ``filename_orog`` Specifies the name of orographic data file. Window begin, Window length ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These two items define the assimilation window for many applications, including Land DA. ``window begin:`` Specifies the beginning time window. The format is YYYY-MM-DDTHH:00:00Z, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. ``window length:`` Specifies the time window length. The form is PTXXH, where XX is a 1- or 2-digit hour. For example: ``PT6H`` Background ^^^^^^^^^^^^^^ The ``background:`` section includes information on the analysis file(s) (also known as "members") generated by the previous cycle. ``date`` Specifies the background date. The format is ``&date YYYY-MM-DDTHH:00:00Z``, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. For example: ``&date 2019-12-21T00:00:00Z`` ``members`` Specifies information on analysis file(s) generated by a previous cycle. ``datetime`` Specifies the date and time. The format is YYYY-MM-DDTHH:00:00Z, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. ``filetype`` Specifies the type of file. Valid values include: ``fms restart`` ``state variables`` Specifies a list of state variables. Valid values: ``[snwdph,vtype,slmsk]`` ``datapath`` Specifies the path for state variables data. Valid values: ``mem_pos/`` | ``mem_neg/``. (With default experiment values, the full path will be ``workdir/mem000/jedi/$datapath``.) ``filename_sfcd`` Specifies the name of the surface data file. This usually takes the form ``YYYYMMDD.HHmmss.sfc_data.nc``, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour, mm is a valid 2-digit minute and ss is a valid 2-digit second. For example: ``20191221.000000.sfc_data.nc`` ``filename_cprl`` Specifies the name of file that contains metadata for the restart. This usually takes the form ``YYYYMMDD.HHmmss.coupler.res``, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour, mm is a valid 2-digit minute and ss is a valid 2-digit second. For example: ``20191221.000000.coupler.res`` Driver ^^^^^^^^^ The ``driver:`` section describes optional modifications to the behavior of the LocalEnsembleDA driver. For details, refer to :ref:`Local Ensemble Data Assimilation in OOPS ` in the JEDI Documentation. ``save posterior mean`` Specifies whether to save the posterior mean. Valid values: ``true`` | ``false`` +--------+-----------------+ | Value | Description | +========+=================+ | true | save | +--------+-----------------+ | false | do not save | +--------+-----------------+ ``save posterior mean increment`` Specifies whether to save the posterior mean increment. Valid values: ``true`` | ``false`` +--------+-----------------+ | Value | Description | +========+=================+ | true | enable | +--------+-----------------+ | false | do not enable | +--------+-----------------+ ``save posterior ensemble`` Specifies whether to save the posterior ensemble. Valid values: ``true`` | ``false`` +--------+-----------------+ | Value | Description | +========+=================+ | true | enable | +--------+-----------------+ | false | do not enable | +--------+-----------------+ ``run as observer only`` Specifies whether to run as observer only. Valid values: ``true`` | ``false`` +--------+-----------------+ | Value | Description | +========+=================+ | true | enable | +--------+-----------------+ | false | do not enable | +--------+-----------------+ Local Ensemble DA ^^^^^^^^^^^^^^^^^^^^^ The ``local ensemble DA:`` section configures the local ensemble DA solver package. ``solver`` Specifies the type of solver. Currently, ``LETKF`` is the only available option. See :cite:t:`HuntEtAl2007` (2007). ``inflation`` Describes ensemble inflation methods. ``rtps``: (Default: ``0.0``) Relaxation to prior spread (:cite:t:`Whitaker&Hamill2012`, 2012). ``rtpp``: (Default: ``0.0``) Relaxation to prior perturbation (:cite:t:`ZhangEtAl2004`, 2004). ``mult``: (Default: ``1.0``) Parameter of multiplicative inflation. Output Increment ^^^^^^^^^^^^^^^^^^^ ``output increment:`` ``filetype`` Type of file provided for the output increment. Valid values include: ``fms restart`` ``filename_sfcd`` Name of the file provided for the output increment. For example: ``xainc.sfc_data.nc`` Observations ^^^^^^^^^^^^^^^ The ``observations:`` item describes one or more types of observations, each of which is a multi-level YAML/JSON object in and of itself. Each of these observation types is read into JEDI as an ``eckit::Configuration`` object (see :ref:`JEDI Documentation ` for more details). ``obs space:`` ```````````````` The ``obs space:`` section of the ``.yaml`` comes under the ``observations.observers:`` section and describes the configuration of the observation space. An observation space handles observation data for a single observation type. ``name`` Specifies the name of observation space. The Land DA System uses ``Simulate`` for the default case. ``distribution:`` ``name`` Specifies the name of distribution. Valid values include: ``Halo`` ``halo size`` Specifies the size of the halo distribution. Format is e-notation. For example: ``250e3`` ``simulated variables`` Specifies the list of variables that need to be simulated by observation operator. Valid values: ``[totalSnowDepth]`` ``obsdatain`` This section specifies information about the observation input data. ``engine`` This section specifies parameters required for the file matching engine. ``type`` Specifies the type of input observation data. Valid values: ``H5File`` | ``OBS`` ``obsfile`` Specifies the input filename. ``obsdataout`` This section contains information about the observation output data. ``engine`` This section specifies parameters required for the file matching engine. ``type`` Specifies the type of output observation data. Valid values: ``H5File`` ``obsfile`` Specifies the output file path. ``obs operator:`` ```````````````````` The ``obs operator:`` section describes the observation operator and its options. An observation operator is used for computing H(x). ``name`` Specifies the name in the ``ObsOperator`` and ``LinearObsOperator`` factory, defined in the C++ code. Valid values include: ``Identity``. See :ref:`JEDI Documentation ` for more options. ``obs error:`` `````````````````` The ``obs error:`` section explains how to calculate the observation error covariance matrix and gives instructions (required for DA applications). The key covariance model, which describes how observation error covariances are created, is frequently the first item in this section. For diagonal observation error covariances, only the diagonal option is currently supported. ``covariance model`` Specifies the covariance model. Valid values include: ``diagonal`` ``obs localizations:`` ```````````````````````` ``obs localizations:`` ``localization method`` Specifies the observation localization method. Valid values include: ``Horizontal SOAR`` +--------------------+--------------------------------------------------+ | Value | Description | +====================+==================================================+ | Horizontal SOAR | Second Order Auto-Regressive localization in | | | the horizontal direction. | +--------------------+--------------------------------------------------+ | Vertical Brasnett | Vertical component of the localization scheme | | | defined in :cite:t:`Brasnett1999` (1999) | | | and used in the snow DA. | +--------------------+--------------------------------------------------+ ``lengthscale`` Radius of influence (i.e., maximum distance of observations from the location being updated) in meters. Format is e-notation. For example: ``250e3`` ``soar horizontal decay`` Decay scale of SOAR localization function. Recommended value: ``0.000021``. Users may adjust based on need/preference. ``max nobs`` Maximum number of observations used to update each location. ``obs filters:`` `````````````````` Observation filters are used to define Quality Control (QC) filters. They have access to observation values and metadata, model values at observation locations, simulated observation value, and their own private data. See :ref:`Observation Filters ` in the JEDI Documentation for more detail. The ``obs filters:`` section contains the following fields: ``filter`` Describes the parameters of a given QC filter. Valid values include: ``Bounds Check`` | ``Background Check`` | ``Domain Check`` | ``RejectList``. See descriptions in the JEDI's `Generic QC Filters `__ Documentation for more. +--------------------+--------------------------------------------------+ | Filter Name | Description | +====================+==================================================+ | Bounds Check | Rejects observations whose values lie outside | | | specified limits: | +--------------------+--------------------------------------------------+ | Background Check | This filter checks for bias-corrected distance | | | between the observation value and model-simulated| | | value (*y* - *H(x)*) and rejects observations | | | where the absolute difference is larger than | | | the ``absolute threshold`` or the | | | :math:`threshold * observation error` or the | | | :math:`threshold * background error`. | +--------------------+--------------------------------------------------+ | Domain Check | This filter retains all observations selected by | | | the ``where`` statement and rejects all others. | +--------------------+--------------------------------------------------+ | RejectList | This is an alternative name for the BlackList | | | filter, which rejects all observations selected | | | by the ``where`` statement. The status of all | | | others remains the same. Opposite of Domain | | | Check filter. | +--------------------+--------------------------------------------------+ ``filter variables`` Limit the action of a QC filter to a subset of variables or to specific channels. ``name`` Name of the filter variable. Users may indicate additional filter variables using the ``name`` field on consecutive lines (see code snippet below). Valid values include: ``totalSnowDepth`` .. code-block:: yaml filter variables: - name: variable_1 - name: variable_2 ``minvalue`` Minimum value for variables in the filter. ``maxvalue`` Maximum value for variables in the filter. ``threshold`` This variable may function differently depending on the filter it is used in. In the `Background Check Filter `__, an observation is rejected when the difference between the observation value (*y*) and model simulated value (*H(x)*) is larger than the ``threshold`` * *observation error*. ``action`` Indicates which action to take once an observation has been flagged by a filter. See :ref:`Filter Actions ` in the JEDI documentation for a full explanation and list of valid values. ``name`` The name of the desired action. Valid values include: ``accept`` | ``reject`` ``where`` By default, filters are applied to all filter variables listed. The ``where`` keyword applies a filter only to observations meeting certain conditions. See the :ref:`Where Statement ` section of the JEDI Documentation for a complete description of valid ``where`` conditions. ``variable`` A list of variables to check using the ``where`` statement. ``name`` Name of a variable to check using the ``where`` statement. Multiple variable names may be listed under ``variable``. The conditions in the where statement will be applied to all of them. For example: .. code-block:: yaml filter: Domain Check # land only where: - variable: name: variable_1 name: variable_2 minvalue: 0.5 maxvalue: 1.5 ``minvalue`` Minimum value for variables in the ``where`` statement. ``maxvalue`` Maximum value for variables in the ``where`` statement. .. _IODA: Interface for Observation Data Access (IODA) =============================================== *This section references Honeyager, R., Herbener, S., Zhang, X., Shlyaeva, A., and Trémolet, Y., 2020: Observations in the Joint Effort for Data assimilation Integration (JEDI) - UFO and IODA. JCSDA Quarterly, 66, Winter 2020.* The Interface for Observation Data Access (IODA) is a subsystem of JEDI that can handle data processing for various models, including the Land DA System. Currently, observation data sets come in a variety of formats (e.g., netCDF, BUFR, GRIB) and may differ significantly in structure, quality, and spatiotemporal resolution/density. Such data must be pre-processed and converted into model-specific formats. This process often involves iterative, model-specific data conversion efforts and numerous cumbersome ad-hoc approaches to prepare observations. Requirements for observation files and I/O handling often result in decreased I/O and computational efficiency. IODA addresses this need to modernize observation data management and use in conjunction with the various components of the Unified Forecast System (:term:`UFS`). IODA provides a unified, model-agnostic method of sharing observation data and exchanging modeling and data assimilation results. The IODA effort centers on three core facets: (i) in-memory data access, (ii) definition of the IODA file format, and (iii) data store creation for long-term storage of observation data and diagnostics. The combination of these foci enables optimal isolation of the scientific code from the underlying data structures and data processing software while simultaneously promoting efficient I/O during the forecasting/DA process by providing a common file format and structured data storage. The IODA file format represents observational field variables (e.g., temperature, salinity, humidity) and locations in two-dimensional tables, where the variables are represented by columns and the locations by rows. Metadata tables are associated with each axis of these data tables, and the location metadata hold the values describing each location (e.g., latitude, longitude). Actual data values are contained in a third dimension of the IODA data table; for instance: observation values, observation error, quality control flags, and simulated observation (H(x)) values. Since the raw observational data come in various formats, a diverse set of "IODA converters" exists to transform the raw observation data files into IODA format. While many of these Python-based IODA converters have been developed to handle marine-based observations, users can utilize the "IODA converter engine" components to develop and implement their own IODA converters to prepare arbitrary observation types for data assimilation within JEDI. (See https://github.com/NOAA-PSL/land-DA_update/blob/develop/jedi/ioda/imsfv3_scf2ioda_obs40.py for the Land DA IMS IODA converter.) Input Files ****************************** The Land DA System requires grid description files, observation files, and restart files to perform snow DA. Grid Description Files ========================= The grid description files appear in :numref:`Section %s ` and are also used as input files to the Vector-to-Tile Converter and the UFS land component. See :numref:`Table %s ` for a description of these files. .. _observation-data: Observation Data ==================== Observation data from 2000 and 2019 are provided in NetCDF format for the |latestr| release. Instructions for downloading the data are provided in :numref:`Section %s `, and instructions for accessing the data on :ref:`Level 1 Systems ` are provided in :numref:`Section %s `. Currently, data is taken from the `Global Historical Climatology Network `__ (GHCN), but eventually, data from the U.S. National Ice Center (USNIC) Interactive Multisensor Snow and Ice Mapping System (`IMS `__) will also be available for use. Observation Types -------------------- GHCN Snow Depth Files ^^^^^^^^^^^^^^^^^^^^^^^^ Snow depth observations are taken from the `Global Historical Climatology Network `__, which provides daily climate summaries sourced from a global network of 100,000 stations. NOAA's `NCEI `__ provides access to these snow depth and snowfall measurements through daily-generated individual station ASCII files or GZipped tar files of full-network observations on the NCEI server or Climate Data Online. Alternatively, users may acquire yearly tarballs via ``wget``: .. code-block:: console wget https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/by_year/{YYYY}.csv.gz where ``${YYYY}`` should be replaced with the year of interest. Note that these yearly tarballs contain all measurement types from the daily GHCN output, and thus, snow depth must be manually extracted from this broader data set. These raw snow depth observations need to be converted into IODA-formatted netCDF files for ingestion into the JEDI LETKF system. However, this process was preemptively handled outside of the Land DA workflow, and the 2019 GHCN IODA files were provided by NOAA PSL (Clara Draper). The IODA-formatted GHCN files are available in the ``inputs/DA/snow_depth/GHCN/data_proc/v3/`` directory and are structured as follows (using 20191221 as an example): .. code-block:: console netcdf ghcn_snwd_ioda_20191221 { dimensions: Location = 9379 ; variables: int Location(Location) ; Location:suggested_chunk_dim = 9379LL ; // global attributes: string :_ioda_layout = "ObsGroup" ; :_ioda_layout_version = 0 ; string :converter = "ghcn_snod2ioda_newV2.py" ; string :date_time_string = "2019-12-21T18:00:00Z" ; :nlocs = 9379 ; :history = "Fri Aug 12 20:27:37 2022: ncrename -O -v altitude,height ./data_proc_test/nc4_ghcn_snwd_ioda_20191221.nc ./data_proc_Update/ghcn_snwd_ioda_20191221.nc" ; :NCO = "netCDF Operators version 4.9.1 (Homepage = http://nco.sf.net, Code = http://github.com/nco/nco)" ; group: MetaData { variables: int64 dateTime(Location) ; dateTime:_FillValue = -2208988800LL ; string dateTime:units = "seconds since 1970-01-01T00:00:00Z" ; float height(Location) ; height:_FillValue = 9.96921e+36f ; float latitude(Location) ; latitude:_FillValue = 9.96921e+36f ; string latitude:units = "degrees_north" ; float longitude(Location) ; longitude:_FillValue = 9.96921e+36f ; string longitude:units = "degrees_east" ; string stationIdentification(Location) ; string stationIdentification:_FillValue = "" ; } // group MetaData group: ObsError { variables: float totalSnowDepth(Location) ; totalSnowDepth:_FillValue = 9.96921e+36f ; string totalSnowDepth:coordinates = "longitude latitude" ; string totalSnowDepth:units = "mm" ; } // group ObsError group: ObsValue { variables: float totalSnowDepth(Location) ; totalSnowDepth:_FillValue = 9.96921e+36f ; string totalSnowDepth:coordinates = "longitude latitude" ; string totalSnowDepth:units = "mm" ; } // group ObsValue group: PreQC { variables: int totalSnowDepth(Location) ; totalSnowDepth:_FillValue = -2147483647 ; string totalSnowDepth:coordinates = "longitude latitude" ; } // group PreQC } The primary observation variable is ``totalSnowDepth``, which, along with the metadata fields of ``datetime``, ``latitude``, ``longitude``, and ``height`` is defined along the ``nlocs`` dimension. Also present are ``ObsError`` and ``PreQC`` values corresponding to each ``totalSnowDepth`` measurement on ``nlocs``. These values were attributed during the IODA conversion step (not supported for this release). The magnitude of ``nlocs`` varies between files; this is due to the fact that the number of stations reporting snow depth observations for a given day can vary in the GHCN. Observation Location and Processing -------------------------------------- GHCN ^^^^^^ GHCN files for 2000 and 2019 are already provided in IODA format for the |latestr| release. :numref:`Table %s ` indicates where users can find data on NOAA :term:`RDHPCS` platforms. Tar files containing the 2000 and 2019 data are located in the publicly-available `Land DA Data Bucket `__. Once untarred, the snow depth files are located in ``/inputs/DA/snow_depth/GHCN/data_proc/{YEAR}``. The 2019 GHCN IODA files were provided by Clara Draper (NOAA PSL). Each file follows the naming convention of ``ghcn_snwd_ioda_${YYYY}${MM}${DD}.nc``, where ``${YYYY}`` is the four-digit cycle year, ``${MM}`` is the two-digit cycle month, and ``${DD}`` is the two-digit cycle day. In each experiment, the ``DA_config`` file sets the name of the experiment configuration file. This configuration file is typically named ``settings_DA_test``. Before assimilation, if "GHCN" was specified as the observation type in the ``DA_config`` file, the ``ghcn_snwd_ioda_${YYYY}${MM}${DD}.nc`` file corresponding to the specified cycle date is soft-linked to the JEDI working directory (``${JEDIWORKDIR}``) with a naming-convention change (i.e., ``GHCN_${YYYY}${MM}${DD}${HH}.nc``). Here, the GHCN IODA file is appended with the cycle hour, ``${HH}`` which is extracted from the ``${STARTDATE}`` variable defined in the relevant ``DA_config`` file. Prior to ingesting the GHCN IODA files via the LETKF at the DA analysis time, the observations are further quality controlled and checked using ``letkf_land.yaml`` (itself a concatenation of ``GHCN.yaml`` and ``letkfoi_snow.yaml``; see the `GitHub yaml files `__ for more detail). The GHCN-specific observation filters, domain checks, and quality control parameters from ``GHCN.yaml`` ensure that only snow depth observations which meet specific criteria are assimilated (the rest are rejected). The contents of ``GHCN.yaml`` are listed below: .. code-block:: yaml - obs space: name: SnowDepthGHCN distribution: name: Halo halo size: 250e3 simulated variables: [totalSnowDepth] obsdatain: engine: type: H5File obsfile: GHCN_XXYYYYXXMMXXDDXXHH.nc obsdataout: engine: type: H5File obsfile: output/DA/hofx/letkf_hofx_ghcn_XXYYYYXXMMXXDDXXHH.nc obs operator: name: Identity obs error: covariance model: diagonal obs localizations: - localization method: Horizontal SOAR lengthscale: 250e3 soar horizontal decay: 0.000021 max nobs: 50 - localization method: Vertical Brasnett vertical lengthscale: 700 obs filters: - filter: Bounds Check # negative / missing snow filter variables: - name: totalSnowDepth minvalue: 0.0 - filter: Domain Check # missing station elevation (-999.9) where: - variable: name: MetaData/height minvalue: -999.0 - filter: Domain Check # land only where: - variable: name: GeoVaLs/slmsk minvalue: 0.5 maxvalue: 1.5 # GFSv17 only. #- filter: Domain Check # no sea ice # where: # - variable: # name: fraction_of_ice@GeoVaLs # maxvalue: 0.0 - filter: RejectList # no land-ice where: - variable: name: GeoVaLs/vtype minvalue: 14.5 maxvalue: 15.5 - filter: Background Check # gross error check filter variables: - name: totalSnowDepth threshold: 6.25 action: name: reject Viewing NetCDF Files ----------------------- Users can view file information and notes for NetCDF files using the instructions in :numref:`Section %s `. For example, on Orion: .. code-block:: console # Load modules: module load intel/2022.1.2 impi/2022.1.2 netcdf/4.7.4 ncdump -h /work/noaa/epic/UFS_Land-DA/inputs/DA/snow_depth/GHCN/data_proc/v3/2019/ghcn_snwd_ioda_20191221.nc to see the contents of the 2019-12-21 GHCN file on Hera. Users may need to modify the module load command and the file path to reflect module versions/file paths that are available on their system. Restart Files ================ To restart the UFS land driver successfully after land model execution, all parameters, states, and fluxes used for a subsequent time iteration are stored in a restart file. This restart file is named ``ufs_land_restart.{FILEDATE}.nc`` where ``FILEDATE`` is in YYYY-MM-DD_HH-mm-SS format (e.g., ``ufs_land_restart.2019-12-21_00-00-00.nc``). The restart file contains all the model fields and their values at a specific point in time; this information can be used to restart the model immediately to run the next cycle. The Land DA System reads the states from the restart file and replaces them after the DA step with the updated analysis. :numref:`Table %s ` lists the fields in the Land DA restart file. Within the UFS land driver (submodule ``ufs-land-driver-emc-dev``), read/write of the restart file is performed in ``ufsLandNoahMPRestartModule.f90``. .. _RestartFiles: .. table:: Files Included in ufs_land_restart.{FILEDATE}.nc +--------------------------+-----------------------------------+-----------------------+ | Variable | Long name | Unit | +==========================+===================================+=======================+ | time | time | "seconds since | | | | 1970-01-01 00:00:00" | +--------------------------+-----------------------------------+-----------------------+ | timestep | time step | "seconds" | +--------------------------+-----------------------------------+-----------------------+ | vegetation_fraction | Vegetation fraction | "-" | +--------------------------+-----------------------------------+-----------------------+ | emissivity_total | surface emissivity | "-" | +--------------------------+-----------------------------------+-----------------------+ | albedo_direct_vis | surface albedo - direct visible | "-" | +--------------------------+-----------------------------------+-----------------------+ | albedo_direct_nir | surface albedo - direct NIR | "-" | +--------------------------+-----------------------------------+-----------------------+ | albedo_diffuse_vis | surface albedo - diffuse visible | "-" | +--------------------------+-----------------------------------+-----------------------+ | albedo_diffuse_nir | surface albedo - diffuse NIR | "-" | +--------------------------+-----------------------------------+-----------------------+ | temperature_soil_bot | deep soil temperature | "K" | +--------------------------+-----------------------------------+-----------------------+ | cm_noahmp | surface exchange coefficient | "m/s" | | | for momentum | | +--------------------------+-----------------------------------+-----------------------+ | ch_noahmp | surface exchange coefficient | "m/s" | | | heat & moisture | | +--------------------------+-----------------------------------+-----------------------+ | forcing_height | height of forcing | "m" | +--------------------------+-----------------------------------+-----------------------+ | max_vegetation_frac | maximum fractional coverage of | "fraction" | | | vegetation | | +--------------------------+-----------------------------------+-----------------------+ | albedo_total | grid composite albedo | "fraction" | +--------------------------+-----------------------------------+-----------------------+ | snow_water_equiv | snow water equivalent | "mm" | +--------------------------+-----------------------------------+-----------------------+ | snow_depth | snow depth | "m" | +--------------------------+-----------------------------------+-----------------------+ | temperature_radiative | surface radiative temperature | "K" | +--------------------------+-----------------------------------+-----------------------+ | soil_moisture_vol | volumetric moisture content in | "m3/m3" | | | soil level | | +--------------------------+-----------------------------------+-----------------------+ | temperature_soil | temperature in soil | "K" | | | level | | +--------------------------+-----------------------------------+-----------------------+ | soil_liquid_vol | volumetric liquid | "m3/m3" | | | content in soil level | | +--------------------------+-----------------------------------+-----------------------+ | canopy_water | canopy moisture | "m" | | | content | | +--------------------------+-----------------------------------+-----------------------+ | transpiration_heat | plant transpiration |"W/m2" | +--------------------------+-----------------------------------+-----------------------+ | friction_velocity | friction velocity | "m/s" | +--------------------------+-----------------------------------+-----------------------+ | z0_total | surface roughness | "m" | +--------------------------+-----------------------------------+-----------------------+ | snow_cover_fraction | snow cover fraction | "fraction" | +--------------------------+-----------------------------------+-----------------------+ | spec_humidity_surface | diagnostic specific humidity at | "kg/kg" | | | surface | | +--------------------------+-----------------------------------+-----------------------+ | ground_heat_total | soil heat flux | "W/m2" | +--------------------------+-----------------------------------+-----------------------+ | runoff_baseflow | drainage runoff | "mm/s" | +--------------------------+-----------------------------------+-----------------------+ | latent_heat_total | latent heat flux | "W/m2" | +--------------------------+-----------------------------------+-----------------------+ | sensible_heat_flux | sensible heat flux | "W/m2" | +--------------------------+-----------------------------------+-----------------------+ | evaporation_potential | potential evaporation | "mm/s" | +--------------------------+-----------------------------------+-----------------------+ | runoff_surface | surface runoff | "mm/s" | +--------------------------+-----------------------------------+-----------------------+ | latent_heat_ground | direct soil latent heat flux | "W/m2" | +--------------------------+-----------------------------------+-----------------------+ | latent_heat_canopy | canopy water latent heat flux | "W/m2" | +--------------------------+-----------------------------------+-----------------------+ | snow_sublimation | sublimation/deposit from snowpack | "mm/s" | +--------------------------+-----------------------------------+-----------------------+ | soil_moisture_total | total soil column moisture | "mm" | | | content | | +--------------------------+-----------------------------------+-----------------------+ | precip_adv_heat_total | precipitation advected heat - | "W/m2" | | | total | | +--------------------------+-----------------------------------+-----------------------+ | cosine_zenith | cosine of zenith angle | "-" | +--------------------------+-----------------------------------+-----------------------+ | snow_levels | active snow levels | "-" | +--------------------------+-----------------------------------+-----------------------+ | temperature_leaf | leaf temperature | "K" | +--------------------------+-----------------------------------+-----------------------+ | temperature_ground | ground temperature | "K" | +--------------------------+-----------------------------------+-----------------------+ | canopy_ice | canopy ice | "mm" | +--------------------------+-----------------------------------+-----------------------+ | canopy_liquid | canopy liquid | "mm" | +--------------------------+-----------------------------------+-----------------------+ | vapor_pres_canopy_air | water vapor pressure in canopy | "Pa" | | | air space | | +--------------------------+-----------------------------------+-----------------------+ | temperature_canopy_air | temperature in canopy air space | "K" | +--------------------------+-----------------------------------+-----------------------+ | canopy_wet_fraction | fraction of canopy covered by | "-" | | | water | | +--------------------------+-----------------------------------+-----------------------+ | snow_water_equiv_old | snow water equivalent - before | "mm" | | | integration | | +--------------------------+-----------------------------------+-----------------------+ | snow_albedo_old | snow albedo - before integration | "-" | +--------------------------+-----------------------------------+-----------------------+ | snowfall | snowfall | "mm/s" | +--------------------------+-----------------------------------+-----------------------+ | lake_water | depth of water in lake | "mm" | +--------------------------+-----------------------------------+-----------------------+ | depth_water_table | depth to water table | "m" | +--------------------------+-----------------------------------+-----------------------+ | aquifer_water | aquifer water content | "mm" | +--------------------------+-----------------------------------+-----------------------+ | saturated_water | aquifer + saturated soil water | "mm" | | | content | | +--------------------------+-----------------------------------+-----------------------+ | leaf_carbon | carbon in leaves | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | root_carbon | carbon in roots | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | stem_carbon | carbon in stems | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | wood_carbon | carbon in wood | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | soil_carbon_stable | stable carbon in soil | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | soil_carbon_fast | fast carbon in soil | "g/m2" | +--------------------------+-----------------------------------+-----------------------+ | leaf_area_index | leaf area index | "m2/m2" | +--------------------------+-----------------------------------+-----------------------+ | stem_area_index | stem area index | "m2/m2" | +--------------------------+-----------------------------------+-----------------------+ | snow_age | BATS non-dimensional snow age | "-" | +--------------------------+-----------------------------------+-----------------------+ | soil_moisture_wtd | soil water content between bottom | "m3/m3" | | | of the soil and water table | | +--------------------------+-----------------------------------+-----------------------+ | deep_recharge | deep recharge for runoff_option 5 | "m" | +--------------------------+-----------------------------------+-----------------------+ | recharge | recharge for runoff_option 5 | "m" | +--------------------------+-----------------------------------+-----------------------+ | temperature_2m | grid diagnostic temperature at 2 | "K" | | | meters | | +--------------------------+-----------------------------------+-----------------------+ | spec_humidity_2m | grid diagnostic specific humidity | "kg/kg" | | | at 2 meters | | +--------------------------+-----------------------------------+-----------------------+ | eq_soil_water_vol | equilibrium soil water content | "m3/m3" | +--------------------------+-----------------------------------+-----------------------+ | temperature_snow | snow level temperature | "K" | +--------------------------+-----------------------------------+-----------------------+ | interface_depth | layer-bottom depth from snow | "m" | | | surface | | +--------------------------+-----------------------------------+-----------------------+ | snow_level_ice | ice content of snow levels | "mm" | +--------------------------+-----------------------------------+-----------------------+ | snow_level_liquid | liquid content of snow levels | "mm" | +--------------------------+-----------------------------------+-----------------------+ The restart files also include one text file, ``${FILEDATE}.coupler.res``, which contains metadata for the restart. Example of ``${FILEDATE}.coupler.res``: .. code-block:: console 2 (Calendar: no_calendar=0, thirty_day_months=1, julian=2, gregorian=3, noleap=4) 2019 12 22 0 0 0 Model start time: year, month, day, hour, minute, second 2019 12 22 0 0 0 Current model time: year, month, day, hour, minute, second DA Workflow Overview ************************ The cycling Noah-MP offline DA run is initiated using ``do_submit_cycle.sh`` to call the ``submit_cycle.sh`` script. ``submit_cycle.sh`` calls a third script (``do_landDA.sh``) if DA has been activated in the experiment. .. note:: The offline Noah-MP model runs in vector space, whereas a cycling Noah-MP offline DA job uses JEDI's tiled cubed-sphere (:term:`FV3`) format. :numref:`Section %s ` describes the Vector-to-Tile Converter that maps between these two formats. ``do_submit_cycle.sh`` ========================= The ``do_submit_cycle.sh`` script sets up the cycling job based on the user's input settings. :numref:`Figure %s ` illustrates the steps in this process. .. _DoSubmitCyclePng: .. figure:: https://github.com/ufs-community/land-DA_workflow/wiki/do_submit_cycle.png :alt: The do submit cycle shell script starts by loading configuration files and modules. Then it proceeds to set executables, read in dates, compute forecast run variables, and setup work and output directories for the model. If a restart directory is available in the model output directory, it creates the dates file and submits the submit cycle shell script. If there is no output file, the script will try to copy restart files from an initial conditions directory before creating the dates file and submitting the submit cycle shell script. *Flowchart of 'do_submit_cycle.sh'* First, ``do_submit_cycle.sh`` reads in a configuration file for the cycle settings. This file contains the information required to run the cycle: the experiment name, start date, end date, the paths of the working directory (i.e., ``workdir``) and output directories, the length of each forecast, atmospheric forcing data, the Finite-Volume Cubed-Sphere Dynamical Core (:term:`FV3`) resolution and its paths, the number of cycles per job, the directory with initial conditions, a namelist file for running Land DA, and different DA options. Then, the required modules are loaded, and some executables are set for running the cycle. The restart frequency and running day/hours are computed from the inputs, and directories are created for running DA and saving the DA outputs. If restart files are not in the experiment output directory, the script will try to copy the restart files from the ``ICSDIR`` directory, which should contain initial conditions files if restart files are not available. Finally, the script creates the dates file (``analdates.sh``) and submits the ``submit_cycle.sh`` script, which is described in detail in the next section. ``submit_cycle.sh`` ====================== The ``submit_cycle.sh`` script first exports the required paths and loads the required modules. Then, it reads the dates file and runs through all the steps for submitting a cycle if the count of dates is less than the number of cycles per job (see :numref:`Figure %s `). .. _SubmitCyclePng: .. figure:: https://github.com/ufs-community/land-DA_workflow/wiki/submit_cycle.png :alt: The submit cycle shell script starts by exporting paths and loading required modules. Then it starts a loop for the cycle. For each cycle in the experiment, it gets the data assimilation settings and date/time info; computes the restart frequency, run days, and run hours; and copies the restarts into the work directory. If the user is running a DA experiment, the script updates and submits the vector to tile namelists and submits the snow data assimilation. Then it submits the tile to vector namelists and saves the analysis restart. Regardless of whether DA is being used, the script runs the forecast model, updates the model namelist, and submits the land surface model. It checks existing model output, and then the loop ends. If there are more cycles to run, the script will run through this loop until they are complete. *Flowchart of 'submit_cycle.sh'* As the script loops through the steps in the process for each cycle, it reads in the DA settings and selects a run type --- either DA or ``openloop`` (which skips DA). Required DA settings include: DA algorithm choice, directory paths for JEDI, Land_DA (where the ``do_landDA.sh`` script is located), JEDI's input observation options, DA window length, options for constructing ``.yaml`` files, etc. Next, the system designates work and output directories and copies restart files into the working directory. If the DA option is selected, the script calls the ``vector2tile`` function and tries to convert the format of the Noah-MP model in vector space to the JEDI tile format used in :term:`FV3` cubed-sphere space. After the ``vector2tile`` is done, the script calls the data assimilation job script (``do_landDA.sh``) and runs this script. Then, the ``tile2vector`` function is called and converts the JEDI output tiles back to vector format. The converted vector outputs are saved, and the forecast model is run. Then, the script checks the existing model outputs. Finally, if the current date is less than the end date, this same procedure will be processed for the next cycle. .. note:: The |latestr| release of Land DA does not support ensemble runs. Thus, the first ensemble member (``mem000``) is the only ensemble member. Here is an example of a configuration settings file, ``settings_DA_cycle_era5``, for the ``submit_cycle.sh`` script: .. code-block:: console # experiment name export exp_name=DA_ERA5_test #export BASELINE=hera.internal STARTDATE=2019122100 ENDDATE=2019122200 # Get commmon variables source ./release.environment ############################ #forcing options: gswp3, era5 export atmos_forc=era5 # for LETKF, this is size of ensemble. # for LETKF-OI pseudo ensemble, or non-ensemble runs use 1 export ensemble_size=1 # length of each forecast export FCSTHR=24 #FV3 resolution export RES=96 if [[ $BASELINE =~ 'hera.internal' ]]; then export TPATH=/scratch2/NCEPDEV/land/data/fix/C96.mx100_frac/ else export TPATH="$LANDDA_INPUTS/forcing/${atmos_forc}/orog_files/" fi export TSTUB="oro_C96.mx100" # file stub for orography files in $TPATH # oro_C${RES} for atm only, oro_C${RES}.mx100 for atm/ocean. # number of cycles to submit in a single job export cycles_per_job=1 # directory with initial conditions # can find some here:/scratch2/BMC/gsienkf/Clara.Draper/DA_test_cases/land-offline_workflow/offline_ICS/single export ICSDIR=$LANDDAROOT/inputs/forcing/${atmos_forc}/orog_files/ # namelist for do_landDA.sh # set to "openloop" to not call do_landDA.sh export DA_config="settings_DA_test" # if want different DA at different times, list here. export DA_config00=${DA_config} export DA_config06=${DA_config} export DA_config12=${DA_config} export DA_config18=${DA_config} Parameters for ``submit_cycle.sh`` ------------------------------------- ``exp_name`` Specifies the name of experiment. ``STARTDATE`` Specifies the experiment start date. The form is YYYYMMDDHH, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. ``ENDDATE`` Specifies the experiment end date. The form is YYYYMMDDHH, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. ``WORKDIR`` Specifies the path to a temporary directory from which the experiment is run. ``OUTDIR`` Specifies the path to a directory where experiment output is saved. ``ensemble_size`` Specifies the size of the ensemble (i.e., number of ensemble members). Use ``1`` for non-ensemble runs. ``FCSTHR`` Specifies the length of each forecast in hours. ``atmos_forc`` Specifies the name of the atmospheric forcing data. Valid values include: ``gdas`` | ``era5`` ``RES`` Specifies the resolution of FV3. Valid values: ``C96`` .. note:: Other resolutions are possible but not supported for this release. ``TPATH`` Specifies the path to the directory containing the orography files. ``TSTUB`` Specifies the file stub/name for orography files in ``TPATH``. This file stub is named ``oro_C${RES}`` for atmosphere-only orography files and ``oro_C{RES}.mx100`` for atmosphere and ocean orography files. ``cycles_per_job`` Specifies the number of cycles to submit in a single job. ``ICSDIR`` Specifies the path to a directory containing initial conditions data. ``DA_config`` Configuration setting file for ``do_landDA.sh``. Set ``DA_config`` to ``openloop`` to skip data assimilation (and prevent a call ``do_landDA.sh``). ``DA_configXX`` Configuration setting file for ``do_landDA.sh`` at ``XX`` hr. If users want to perform DA experiment at different times, list these in the configuration setting file. Set to ``openloop`` to skip data assimilation (and prevent a call ``do_landDA.sh``). ``do_landDA.sh`` =================== The ``do_landDA.sh`` runs the data assimilation job inside the ``sumbit_cycle.sh`` script. Currently, the only DA option is the snow Local Ensemble Transform Kalman Filter-Optimal Interpolation (LETKF-OI, :cite:t:`FrolovEtAl2022`, 2022). :numref:`Figure %s ` describes the workflow of this script. .. _DoLandDAPng: .. figure:: https://github.com/ufs-community/land-DA_workflow/wiki/do_landDA.png :alt: The do land da shell script starts by reading in the configuration file and setting up directories. Then it formats date strings, stages restart files, and prepares the observation files. It constructs yaml files based on requested JEDI type and then proceeds to create the background ensembles using LETKF-OI. Next, the script runs JEDI and applies the increment to use restarts. Lastly, it performs clean-up operations. *Flowchart of 'do_landDA.sh'* First, to run the DA job, ``do_landDA.sh`` reads in the configuration file and sets up the directories. The date strings are formatted for the current date and previous date. For each tile, restarts are staged to apply the JEDI update. In this stage, all files will get directly updated. Then, the observation files are read and prepared for this job. Once the JEDI type is determined, ``.yaml`` files are constructed. Note that if the user specifies a ``.yaml`` file, the script uses that one. Otherwise, the script builds the ``.yaml`` files. For LETKF-OI, a pseudo-ensemble is created by running the python script (``letkf_create_ens.py``). Once the ensemble is created, the script runs JEDI and applies increment to UFS restarts. Below, users can find an excerpt of a configuration settings file, ``settings_DA_template``, for the ``do_landDA.sh`` script: .. code-block:: console LANDDADIR=${CYCLEDIR}/DA_update/ ############################ # DA options OBS_TYPES=("GHCN") JEDI_TYPES=("DA") WINLEN=24 # YAMLS YAML_DA=construct YAML_HOFX=construct # JEDI DIRECTORIES #JEDI_EXECDIR= # JEDI FV3 build directory #IODA_BUILD_DIR= # JEDI IODA-converter source directory #fv3bundle_vn= # date for JEDI fv3 bundle checkout (used to select correct yaml) ``LANDDADIR`` Specifies the path to the ``do_landDA.sh`` script. ``OBS_TYPES`` Specifies the observation type. Format is "Obs1" "Obs2". Currently, only GHCN observation data is available. ``JEDI_TYPES`` Specifies the JEDI call type for each observation type above. Format is "type1" "type2". Valid values: ``DA`` | ``HOFX`` +--------+--------------------------------------------------------+ | Value | Description | +========+========================================================+ | DA | Data assimilation | +--------+--------------------------------------------------------+ | HOFX | A generic application for running the model forecast | | | (or reading forecasts from file) and computing H(x) | +--------+--------------------------------------------------------+ ``WINLEN`` Specifies the DA window length. It is generally the same as the ``FCSTLEN``. ``YAML_DA`` Specifies whether to construct the ``.yaml`` name based on requested observation types and their availabilities. Valid values: ``construct`` | *desired YAML name* +--------------------+--------------------------------------------------------+ | Value | Description | +====================+========================================================+ | construct | Enable constructing the YAML | +--------------------+--------------------------------------------------------+ | desired YAML name | Will not test for availability of observations | +--------------------+--------------------------------------------------------+ ``JEDI_EXECDIR`` Specifies the JEDI FV3 build directory. If using different JEDI version, users will need to edit the ``.yaml`` files with the desired directory path. ``fv3bundle_vn`` Specifies the date for JEDI ``fv3-bundle`` checkout (used to select correct ``.yaml``).