INTERFACE / PUBLIC COMPONENTS / NAMELIST / FILES / REFERENCES / ERRORS / BUGS / PLANS / PRIVATE COMPONENTS

MODULE model_mod (wrf)

Contact: Alain Caya
Reviewers:  
Revision: $Revision: 1.7 $
Release Name: $Name: pre_iceland $
Change Date: $Date: 2005/10/20 01:34:28 $
Change history: see CVS log

OVERVIEW

DART interface module for the WRF model. The 13 public interfaces are standardized for all DART compliant models. These interfaces allow DART to advance the model, get the model state and metadata describing this state, find state variables that are close to a given location, and do spatial interpolation for a variety of variables required in observational operators.




OTHER MODULES USED

types_mod
time_manager_mod
threed_sphere/location_mod
utilities_mod
obs_kind_mod
map_utils
netcdf
typesizes



PUBLIC INTERFACE

use model_mod, only : get_model_size
 get_state_meta_data
 model_interpolate
 get_model_time_step
 static_init_model
 model_get_close_states
 nc_write_model_atts
 nc_write_model_vars
 pert_model_state
 adv_1step
 end_model
 init_time
 init_conditions

NOTES

The last 4 interfaces are only required for low-order models where advancing the model can be done by a call to a subroutine. The WRF model only advances by executing the program wrf.exe. Thus the last 4 interfaces only appear as stubs in the wrf module.

The interface pert_model_state is presently not provided for WRF. The initial ensemble has to be generated off-line. If coherent structures are not required, the filter can generate an ensemble with uncorrelated random Gaussian noise of 0.002. This is of course not appropriate for a model like WRF which has variables expressed in a wide range of scales. It is thus recommended to generate the initial ensemble off-line, perhaps with the tools provided in models/wrf/PERTURB/3DVAR-COVAR.

Optional namelist interface &model_mod may be read from file input.nml.




PUBLIC COMPONENTS

All and only 13 above interfaces are public.


model_size = get_model_size( )
integer ::  model_size 

Description

Returns the length of the model state vector as an integer. This includes all nested domains.


call get_state_meta_data (index_in, location [, var_type, id] )
integer,                  intent(in)    ::  index_in 
type(location_type),      intent(out)   ::  location 
integer, optional,        intent(out)   ::  var_type, id

Description

Returns metadata about a given element, indexed by index_in, in the model state vector. The location defines where the state variable is located while the type of the variable (for instance temperature, or u wind component) is returned by var_type. The integer values used to indicate different variable types in var_type are themselves defined as public interfaces to model_mod if required. The last optional argument is the wrf domain identification number.

index_in Index into the long state vector.
location Returns location of indexed state variable. The location should use a location_mod that is appropriate for the model domain. For realistic atmospheric models, for instance, a three-dimensional spherical location module that can represent height in a variety of ways is provided.
var_type Returns the type of the indexed state variable as an optional argument.
id Returns the wrf domain identification number of the indexed state variable as an optional argument.

Notes


call model_interpolate(x, location, obs_kind, obs_val, istatus)
real(r8), dimension(:),   intent(in)  ::  x 
type(location_type),      intent(in)  ::  location 
integer,                  intent(in)  ::  obs_kind 
real(r8),                 intent(out) ::  obs_val 
integer,                  intent(out) ::  istatus 

Description

Given model state, returns the value of observation type interpolated to a given location by a method of the model's choosing. All observation kinds defined in obs_kind_mod are supported. In the case where the observational operator is not defined at the given location (e.g. the observation is below the model surface or outside the domain), obs_val is returned as -888888.0 and istatus = 1. Otherwise, istatus = 0. The interpolation is performed in the domain with the highest resolution containing the observation.

x     Model state vector.
location Location to which to interpolate.
obs_kind Integer indexing which type of observation is to be interpolated.
obs_val Value interpolated to location.
istatus Integer flag indicating the result of the interpolation.

Notes

As of September 9, 2004 the reflectivity observational operator is still not available (obs_kind = KIND_REF in obs_kind_mod).


model_time_step = get_model_time_step( )
type(time_type)                       ::  get_model_time_step

Description

Returns the model base time step as a time_type. For the model wrf, it returns the time step used for domain 1 (usually the largest time step among all domains because domain 1 is the coarser grid). The time step is read from namelist.input. In the long run, a more general extended interface may be required that specifies the models range of time stepping possibilities.

Notes


call static_init_model( )

Description

Used for runtime initialization of the model. This is the first call made to the model by any DART compliant assimilation routine. It reads the model namelist parameters, set the calendar type (the GREGORIAN calendar is used with the WRF model), and determine the dart vector length. This subroutine requires that wrfinput_d01, wrfinput_d02, ... (one file for each domain) be present in the working directory to retrieve model information (grid dimensions and spacing, time step, pressure at the top of the model, map projection parameters, etc).

Notes


call model_get_close_states(o_loc, radius, num_total, indices, dist, x)
type(location_type),      intent(in)    ::  o_loc 
real(r8),                 intent(in)    ::  radius 
real(r8), dimension(:),   intent(in)    ::  x 
integer,                  intent(out)   ::  num_total 
integer, dimension(:),    intent(out)   ::  indices 
real(r8), dimension(:),   intent(out)   ::  dist 

Description

Returns the number of state variables that are within a given radius of an observation at location o_loc. The units for the radius depend upon the location_mod module being used by the model. The threed_sphere location module is used with the WRF model and the units for the radius are radians. The physical distance is obtained by multiplying by the earth's radius and is the great circle distance. The indices in the long state vector as well as the distance between each close state variable and the observation are also returned, provided there is sufficient storage available for them in the arrays indices and dist.

o_loc Location of observation.
radius Maximum distance between state and observation.
x Model state vector.
num_total Number of close state variables.
indices Indices of close state variables found in long model state vector. If allocated size of this array is too small, only a subset of the close indices is returned. The filter increases the size of this array and calls model_get_close_states until the array is large enough to contain all close model state variables.
dist Distance between observation and state variables indexed in indices array.

Notes

All WRF domains are scanned for possible update by the filter.


ierr = nc_write_model_atts(ncFileId)
integer,                              ::  nc_write_model_atts

integer,                  intent(in)  ::  ncFileId 

Description

Function to write model specific attributes to a netCDF file. At present, DART is using the NetCDF format to output diagnostic information. This is not a requirement, and models could choose to provide output in other formats. This function writes the metadata associated with the model to a NetCDF file opened to a file identified by ncFileID.

ncFileId     Integer file descriptor opened to NetCDF file.
ierr Returned error code.

Notes


ierr = nc_write_model_vars(ncFileID, statevec, copyindex, timeindex)
integer                               ::  nc_write_model_vars

integer,                  intent(in)  ::  ncFileID 
real(r8), dimension(:),   intent(in)  ::  statevec 
integer,                  intent(in)  ::  copyindex
integer,                  intent(in)  ::  timeindex 

Description

Writes a copy of the state variables to a NetCDF file. Multiple copies of the state for a given time are supported, allowing, for instance, a single file to include multiple ensemble estimates of the state.

ncFileID     Integer file descriptor opened to NetCDF file.
statevec State vector.
copyindex Integer index to which copy is to be written.
timeindex Integer index of which time in the file is being written.
ierr Returned error code.

Notes


call pert_model_state(state, pert_state, interf_provided)
real(r8), dimension(:),   intent(in)    ::  state 
real(r8), dimension(:),   intent(out)   ::  pert_state 
logical,                  intent(out)   ::  interf_provided

Description

Given a model state, produces a perturbed model state. This is used to generate initial ensemble conditions perturbed around some control trajectory state when one is preparing to spin-up ensembles. A DART compliant model can choose not to provide an implementation of this algorithm and use the default mechanism in DART by simply returning .false. as a returned value for the interf_provided argument. In this case, DART perturbs the state to generate ensemble members by adding a random sample from a N(0.0, 0.002) distribution independently to each state variable. Models should override this if some structure is required for perturbations or if the magnitude of perturbations in DART is too large. It is thus recommended to generate the initial ensemble off-line, perhaps with the tools provided in models/wrf/PERTURB/3DVAR-COVAR.

state State vector to be perturbed.
pert_state Perturbed state vector is returned.
interf_provided Return false to have DART perturb state .


call adv_1step(x, time)
real(r8), dimension(:),   intent(inout) ::  x 
type(time_type),          intent(in)    ::  time 

Description

This operation is not defined for the WRF model. This interface is only required if `synchronous' model state advance is supported (the model is called directly as a Fortran90 subroutine from the assimilation programs). This is generally not the preferred method for large models and a stub for this interface is provided for the WRF model.

x State vector of length model_size.
time Gives time of the initial model state. Needed for models that have real time state requirements, for instance the computation of radiational parameters. Note that DART provides a time_manager_mod module that is used to support time computations throughout the facility.

Notes


call end_model( )

Description

Called when use of a model is completed to clean up storage, etc. A stub is provided for the WRF model.

Notes


call init_time(i_time)
type(time_type),        intent(in)  ::  i_time 

Description

Returns the time at which the model will start if no input initial conditions are to be used. This is frequently used to spin-up models from rest, but is not meaningfully supported for the WRF model.

Notes


call init_conditions( x )
real(r8), dimension(:), intent(out) ::  x 

Description

Returns default initial conditions for model; generally used for spinning up initial model states. For the WRF model just return 0's since initial state is always to be provided from input files.

x Model state vector.

Notes




NAMELIST

We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

namelist / model_nml /  &
    output_state_vector, num_moist_vars, num_domains, calendar_type, surf_obs,
    h_diab, adv_mod_command

Discussion

This namelist is read in a file called input.nml

Contents Type Description
output_state_vector logical Controls the output to netCDF files. If .true., output the raw dart state vector. Otherwise, output the prognostic flavor (grided data) for easier plotting (recommended).
num_moist_vars integer Number of moist variables in the state vector [0,...,7].
num_domains integer Total number of WRF domains, including the nest.
calendar_type integer Calendar type. We recommend (GREGORIAN = 3) for WRF, which is the default.
surf_obs logical If true, includes U10, V10, T2, Q2, and PS in the state vector. The resulting extended state vector permits simpler observational operators for these variables. With this strategy, the surface scheme can be changed without the requirement of changing the observational operators in DART.
h_diab logical If true, includes H_DIABATIC in the state vector. This produces a smoother restart and reduces the spinup problem during the assimilation. This is especially useful for convective scale assimilations.
adv_mod_command character(len=32) For single-threaded, set to 'wrf.exe'. For MPI, supports nesting, set to something like, for example, 'mpirun -np number-of-prcessors wrf.exe' (this depends on the platform).



FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
static_init_model
nc_write_model_vars
num_moist_vars is too large The maximum number of moist variable in WRFV2.1 is 7
static_init_model 'Please put wrfinput_d0'//idom//' in the work directory.' One of the wrfinput_d0# is missing in the work directory
static_init_model Map projection no supported Try PROJ_LATLON(0), PROJ_LC(1), PROJ_PS(2), PROJ_MERC(3)
static_init_model
nc_write_model_atts
nc_write_model_vars
Various NetCDF-f90 interface error messages From one of the NetCDF calls in the named routine
get_state_meta_data dart index out of range Unlikely. Would indicate a serious bug in the code
model_interpolate
get_dist_wrf
wrong option for which_vert See which_vert description in location/threed_sphere/location_mod.html
model_interpolate 'do not recognize obs kind ',obs_kind See list in 'use obs_kind_mod' statement in model_mod.f90
get_wrf_index 'Indices ',i,j,k,' exceed grid dimensions: ',#1,#2,#3 One of the grid indices exceeds the corresponding dimension for the var_type input. Unlikely to happen but would indicate a serious bug in the code
get_dist_wrf Unable to define vloc The vertical location is below the model surface or above the model lid
nc_write_model_atts Time dimension ID # must match Unlimited Dimension ID # NetCDF file writing error
read_dt_from_wrf_nml Please put namelist.input in the work directory The file namelist.input is missing in the work directory
read_dt_from_wrf_nml 'max_dom in namelist.input = ',max_dom'num_domains in input.nml = ',num_domains'Make them consistent.' The number of WRF domains in namelist.input and in input.nml do not match



KNOWN BUGS

Only the Lambert projection (MAP_PROJ = 1) is working. Other map projections (0=none, 2=polar, 3=Mercator) are likely to break the code.




FUTURE PLANS




PRIVATE COMPONENTS


ind = get_wrf_index(i,j,k,var_type,id)
integer                               ::  get_wrf_index 
integer,                  intent(in)  ::  i,j,k,var_type,id

Description

Given grid indices, variable type, and domain identification number, returns the index in the model state vector as an integer.


call grid_close_states( o_loc, radius_in, id, close_lon_ind, close_lat_ind, close_vert_ind, close_dist, u_pts, v_pts, p_pts, w_pts, x )
type(location_type),      intent(in)    ::  o_loc 
real(r8),                 intent(in)    ::  radius_in 
integer,                  intent(in)    ::  id 
real(r8), dimension(:),   intent(in)    ::  x 
integer, dimension(:),    intent(out)   ::  close_lon_ind,
close_lat_ind, close_vert_ind 
real(r8), dimension(:),   intent(out)   ::  close_dist 
integer,                  intent(out)   ::  u_pts, v_pts, p_pts,
w_pts 

Description

Called only once by model_get_close_states. Returns the number of grid points that are within a given radius of an observation at location o_loc for u-, v-, w-, and p-grid. The grid indices as well as the distance between each grid points and the observation are also returned. In the case where the horiz_dist_only location module parameter is true, the distances are only calculated at one level. The horizontal distance to the observation is the same at all levels.


dist = get_dist_wrf( i, j, k, var_type, o_loc, id, x )
real(r8)                              ::  get_dist_wrf 
integer,                  intent(in)  ::  i,j,k,var_type,id

type(location_type),      intent(in)  ::  o_loc 
real(r8), dimension(:),   intent(in)  ::  x 

Description

Given grid indices, variable type, and domain identification number, computes the distance to the observation at location o_loc.


call get_wrf_horizontal_location( i, j, var_type, id, long, lat )
integer,                  intent(in)  ::  i,j,var_type,id 
real(r8),                 intent(out) ::  long, lat 

Description

Given horizontal grid indices, variable type, and domain identification number, returns the longitude and latitude in degrees.


call toGrid (x, j, dx, dxm)
real(r8),                 intent(in)  ::  x 
real(r8),                 intent(out) ::  dx, dxm 
integer ,                 intent(out) ::  j 

Description

Given position x, find nearest grid point j (but smaller than or equal to x) and calculate its distance to grid j and j+1.


call pres_to_zk(pres, mdl_v, n3, zk)
real(r8),                  intent(in)  ::  pres 
integer                    intent(in)  ::  n3 
real(r8), dimension(0:n3), intent(in)  ::  mdl_v 
real(r8),                  intent(out) ::  zk 

Description

Calculate the position zk on half (mass) levels in the profile mdl_v corresponding to pressure location pres.


call height_to_zk(obs_v, mdl_v, n3, zk)
real(r8),                  intent(in)  ::  obs_v 
integer                    intent(in)  ::  n3 
real(r8), dimension(0:n3), intent(in)  ::  mdl_v 
real(r8),                  intent(out) ::  zk 

Description

Calculate the position zk on half (mass) levels in the profile mdl_v corresponding to height location obs_v.


call get_model_pressure_profile(i,j,dx,dy,dxm,dym,n,x,id,v_p)
integer                   intent(in)  ::  i,j,n,id 
real(r8),                 intent(in)  ::  dx,dy,dxm,dym 
real(r8), dimension(:),   intent(in)  ::  x 
real(r8), dimension(0:n), intent(out) ::  v_p 

Description

Extract the pressure profile at position (i+dx, j+dy) on the non-staggered vertical grid (half (mass) levels).


vloc = model_pressure(i,j,k,id,var_type,x)
real(r8),                             ::  model_pressure 
integer                   intent(in)  ::  i,j,k,id,var_type

real(r8), dimension(:),   intent(in)  ::  x 

Description

Calculate the pressure at grid point (i,j,k), domain id. The grid is defined according to var_type.


pres = model_pressure_t(i,j,k,id,x)
real(r8)                              ::  model_pressure_t 
integer                   intent(in)  ::  i,j,k,id 
real(r8), dimension(:),   intent(in)  ::  x 

Description

Calculate the pressure at grid point (i,j,k), domain id, on mass point (half (mass) levels, T-point).


rho = model_rho_t(i,j,k,id,x)
real(r8)                              ::  model_rho_t 
integer                   intent(in)  ::  i,j,k,id 
real(r8), dimension(:),   intent(in)  ::  x 

Description

Calculate the total density at grid point (i,j,k), domain id, on mass point (half (mass) levels, T-point).


call get_model_height_profile(i,j,dx,dy,dxm,dym,n,x,id,fld)
integer                   intent(in)  ::  i,j,n,id 
real(r8),                 intent(in)  ::  dx,dy,dxm,dym 
real(r8), dimension(:),   intent(in)  ::  x 
real(r8), dimension(n),   intent(out) ::  fld 

Description

Extract the height profile at position (i+dx, j+dy) on the non-staggered vertical grid.


vloc = model_height(i,j,k,id,var_type,x)
real(r8)                              ::  model_height 
integer                   intent(in)  ::  i,j,k,id,var_type

real(r8), dimension(:),   intent(in)  ::  x 

Description

Calculate the height at grid point (i,j,k), domain id. The grid is defined according to var_type.


call read_dt_from_wrf_nml( )

Description

Read the wrf model time step from namelist.input for all domains.