PROGRAM dart_to_wrf

PROGRAM wrf_to_dart

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: dart_to_wrf.html 6382 2013-08-07 20:45:16Z nancy $

NAMELIST / MODULES / FILES / REFERENCES / ERRORS / PLANS / TERMS OF USE

Overview

This document describes both of the two programs that convert WRF netCDF input files into DART format, and vice versa.

For the sake of convenience, we will use wrfinput_d01 to mean the WRF input file - no matter how many domains are used.

These programs are used in two different places during an assimilation. One is to set up initial condition files for DART, or to convert the final files from an assimilation run into initial condition files for WRF to continue a free forecast run. The other is internally during the execution of an assimilation run, when DART needs to execute WRF to advance the model state between observation assimilation phases. There are slight differences in the requirements for the namelist settings between these two cases, which will be described below.

The wrf_to_dart Program

The wrf_to_dart program reads the &model_nml namelist item wrf_state_variables to determine which fields in the WRF netCDF input file (typically wrfinput_d01) to read and put into the DART state vector. The order of the fields in the state vector is determined by the order the fields are listed in the namelist, so they must remain consistent between running this utility and executing an assimilation with DART. The default output filename is dart_wrf_vector. The file can be renamed afterwards to be something like filter_ics or filter_restart.####, or changed by a setting in the &wrf_to_dart_nml namelist. The input filename for the filter program is a namelist setting in &filter_nml. Control of whether DART expects a single input file with all ensemble member data or a single file per ensemble member is controlled by namelist settings in the &ensemble_manager_nml namelist. For WRF it is more common to have a single file per ensemble member because of the sizes of the files.

When explicitly called by the user, or by a user-written script, this program is usually creating initial condition files for the start of an assimilation run.

wrf_to_dart is also called by the advance_model.csh script on files generated by the filter program, using filenames the user typically does not see, e.g. assim_model_state_ud.####, where #### is the ensemble member number. The script takes care of renaming the output from wrf_to_dart to be what filter expects to see. If the assimilation is working, these files are usually removed by the scripts and are transparent to the user.

The dart_to_wrf Program

The dart_to_wrf program reads the &model_nml namelist item wrf_state_variables to determine which fields are in the DART state vector so it can copy them to the right location in the WRF netCDF output file (typically wrfinput_d01). The order of the fields in the state vector is determined by the order the fields are listed in the namelist, so they must remain consistent between running this utility and executing an assimilation with DART. Note that the WRF netCDF file contains much more information than is in the DART state vector, so the file needs to be the correct one for running WRF, having consistent data outside of the state variables.

dart_to_wrf also has an additional namelist in the input.nml file, &dart_to_wrf_nml. The input filename is set there, with a default of dart_wrf_vector. The output filename is always wrfinput_d01 for a single domain. If the DART state vector contains multiple domains, files wrfinput_d02, wrfinput_d03, etc are opened and updated.

To copy the data from a DART restart/output file into a WRF input file to start a free forecast run at the end of an assimilation, the namelist needs to be set so model_advance_file is .FALSE., which is not the default, and the DART restart file can either be renamed to 'dart_wrf_vector' or the input filename can be set in the namelist. In this usage, adv_mod_command is unused.

During an assimilation when dart_to_wrf is called by the advance_model.csh script the namelist values must have their original settings to function correctly. This program is used to put the updated DART state information into the WRF input file, and to set up the WRF namelists so the model runs for the correct amount of time before the next assimilation cycle.

[top]

NAMELIST

This namelist is read from the file input.nml. Namelists start with an ampersand '&' and terminate with a slash '/'. Character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the namelist.

&dart_to_wrf_nml
   model_advance_file = .true.,
   dart_restart_name = 'dart_wrf_vector',
   adv_mod_command   = './wrf.exe',
   print_data_ranges = .false.,
   debug             = .false.,
/

&wrf_to_dart_nml
    dart_restart_name = "dart_wrf_vector", 
    print_data_ranges = .false., 
    debug             = .false.
/

&model_nml
   default_state_variables     = .true.,
   wrf_state_variables         = 'NULL',
   wrf_state_bounds            = 'NULL',
   num_domains                 = 1,
   output_state_vector         = .false.,
/
(partial list)


Both converters have their own namelist, and additionally read the WRF model namelist. See the description of the model namelist in the WRF model_mod documentation. The dart_to_wrf program uses the namelist dart_to_wrf_nml, and the wrf_to_dart program uses the namelist wrf_to_dart_nml. All namelists are read from a file called input.nml.

The wrf_to_dart_nml contains:

Item Type Description
model_advance_file logical Set this to .true. to work with the advance_model.csh script during an assimilation run, where it converts the temporary/intermediary assim_model_state_ic files. To insert the information from a DART restart/initial conditions file into wrfinput_d01 set this to .false. (i.e. for a free run of WRF). The dart_to_wrf program is able to convert both types of DART restart files: those with two timestamp records followed by the model state, and those with a single timestamp record followed by the model state (the type most commonly encountered if the assimilation is successful).
dart_restart_name character(len=128) Set this to the default value of 'dart_wrf_vector' to work with the advance_model.csh script. To read the input information from a DART restart file with a different name set this to another value, e.g. 'filter_ics'. Remember to change model_advance_file to .false. if the input file is a DART restart or initial conditions file.
adv_mod_command character(len=128) Set this to './wrf.exe' to work with the advance_model.csh script. If model_advance_file is false. this value is ignored. If .true. this string along with the necessary time information is written into a file called 'wrf.info'. This value used to be set in the WRF &model_nml namelist, but has moved to here.
print_data_ranges logical The default value of this is .false. to minimize the amount of output printed during the conversion of each ensemble member's data from DART format to WRF. Setting this to .true. will allow you to examine the data min and max of each type of data as it is converted (e.g. U, V, T, Q, etc). This is useful for diagnosing problems when data values go outside expected ranges. In the &model_nml namelist there are options to set data limits during this conversion so if the assimilation has pushed data outside the legal bounds (e.g. 0.0-1.0), the conversion can quit or set out-of-range values to the legal limits. If this namelist item is true, both the original and new data limits will be printed.
debug logical If .true. more information will be printed about the sizes of each type of data, the offset into the linearized state vector, the data time information, etc. It is recommended to be used only when diagnosing problems.

The wrf_to_dart_nml contains:

Item Type Description
dart_restart_name character(len=128) Set this to 'dart_wrf_vector' to work with the advance_model.csh script. To write the state information to a DART restart file with a different name set this to another value, e.g. 'filter_ics'.
print_data_ranges logical Set to .false. to minimize the amount of output printed during the conversion of each ensemble member's data from WRF to DART format. Setting this to .true. will allow you to examine the data min and max of each type of data as it is converted (e.g. U, V, T, Q, etc). This is useful for diagnosing problems when data values go outside expected ranges.
debug logical If set to .true. print more output about the sizes of each type of data, the offset into the linearized state vector, the data time information, etc. It is recommended to be used only when diagnosing problems.


[top]

MODULES DIRECTLY USED

types_mod
time_manager_mod
utilities_mod
models/wrf/WRF_DART_utilities/wrf_data_module
assim_model_mod

MODULES INDIRECTLY USED

models/wrf/model_mod
models/wrf/module_map_utils
obs_kind_mod
location/threed_sphere/location_mod
random_seq_mod
random_nr_mod
[top]

FILES

File formats

During the model advances within an assimilation run, in the conversion from DART to WRF, the dart_wrf_vector file is usually one of the assim_model_state_ic# that the filter writes out to advance the ensemble. As input, the dart_wrf_vector includes the target time in addition to the valid time at the beginning of the file. As output, the dart_wrf_vector includes only the valid time at the beginning of the file and is usually renamed as assim_model_state_ud# as input to the filter for the next assimilation cycle.

The file wrf.info contains the target DART time, the valid DART time, the valid date, the number of domains, and the command used to executed the WRF model. The file wrf.info is created in the conversion from DART to WRF. In the conversion from WRF back to DART, the target time is read from the file wrf.info, which should then be the valid time. This will be the time written to the DART vector file. The rest of the information in the file wrf.info is only used by the program ensemble_init and by the script advance_model.csh.

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
trans_2d nx, ny, not compatible Dimensions nx, ny incompatible with incoming array a2d.
trans_3d nx, ny, nz, not compatible Dimensions nx, ny, nz incompatible with incoming array a3d.

KNOWN BUGS

none

[top]

FUTURE PLANS

none.

[top]

Terms of Use

DART software - Copyright 2004 - 2013 UCAR.
This open source software is provided by UCAR, "as is",
without charge, subject to all terms of use at
http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: Hui Liu, David Dowell
Revision: $Revision: 6382 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Lanai/models/wrf/WRF_DART_utilities/dart_to_wrf.html $
Change Date: $Date: 2013-08-07 14:45:16 -0600 (Wed, 07 Aug 2013) $
Change history:  try "svn log" or "svn diff"