![]() |
Jump to DART Documentation Main Index |
DART radar observation module, including the observation operators for the
two primary radar-observation types -- Doppler velocity and reflectivity --
plus other utility subroutines and functions. A number of simplifications
are employed for the observation operators. Most notably, the model state
is mapped to a "point" observation, whereas a real radar observation is a
volumetric sample. The implications of this approximation have not been
investigated fully, so in the future it might be worth developing and testing
more sophisticated observation operators that produce volumetric power-
weighted samples.
This module is able to compute reflectivity and precipitation fall speed
(needed for computing Doppler radial velocity) from the prognostic model
fields only for simple single-moment microphysics schemes such as the Kessler
and Lin schemes. If a more complicated microphysics scheme is used, then
reflectivity and fall speed must be accessible instead as diagnostic fields
in the model state.
Author and Contact information:
For users of previous versions of the radar obs_def code, here are a list of changes beginning with subversion revision 3616 which are not backward compatible:
types_mod utilities_mod location_mod (threed_sphere) assim_model_mod obs_kind_mod
use obs_def_radar_mod, only : | read_radar_ref |
get_expected_radar_ref | |
read_radial_vel | |
write_radial_vel | |
interactive_radial_vel | |
get_expected_radial_vel | |
get_obs_def_radial_vel | |
set_radial_vel |
Namelist interface &obs_def_radar_mod_nml is read from file input.nml.
A note about documentation style. Optional arguments are enclosed in brackets [like this].
real(r8), intent(inout) :: obsvalue integer, intent(out) :: refkey
Reflectivity observations have no auxiliary data to read or write, but there are namelist options that can alter the observation value at runtime. This routine tests the observation value and alters it if required.
obsvalue | Observation value. |
refkey | Set to 0 to avoid uninitialized values, but otherwise unused. |
real(r8), intent(in) :: state_vector(:) type(location_type), intent(in) :: location real(r8), intent(out) :: ref integer, intent(out) :: istatus
Given a location and the state vector from one of the ensemble members,
compute the model-predicted radar reflectivity that would be observed
at that location. The returned value is in dBZ.
If apply_ref_limit_to_fwd_op is .TRUE. in the namelist,
reflectivity values less than
reflectivity_limit_fwd_op
will be set to lowest_reflectivity_fwd_op.
state_vector | A one dimensional representation of the model state vector |
location | Location of this observation |
ref | The returned radar reflectivity value |
istatus | Returned integer status code describing problems with applying forward operator. 0 is a good value; any positive value indicates an error; negative values are reserved for internal DART use only. |
integer, intent(out) :: velkey integer, intent(in) :: ifile character(len=*), optional, intent(in) :: fform
Reads the additional auxiliary information associated with a radial velocity observation. This includes the location of the radar source, the beam direction, and the nyquist velocity.
velkey | Unique identifier associated with this radial velocity observation. In this code it is an integer index into module local arrays which hold the additional data. This routine increments it and returns the new value. |
ifile | File unit descriptor for input file |
fform | File format specifier: FORMATTED or UNFORMATTED; default FORMATTED |
integer, intent(in) :: velkey integer, intent(in) :: ifile character(len=*), optional, intent(in) :: fform
Writes the additional auxiliary information associated with a radial velocity observation. This includes the location of the radar source, the beam direction, and the nyquist velocity.
velkey | Unique identifier associated with this radial velocity observation. In this code it is an integer index into module local arrays which hold the additional data. This routine uses the value to select the appropriate data to write for this observation. |
ifile | File unit descriptor for output file |
fform | File format specifier: FORMATTED or UNFORMATTED; default FORMATTED |
integer, intent(in) :: velkey type(location_type), intent(out) :: radar_location real(r8), intent(out) :: beam_direction(3) real(r8), intent(out) :: nyquist_velocity
Returns the auxiliary information associated with a given radial velocity observation.
velkey | Unique identifier associated with this radial velocity observation. In this code it is an integer index into module local arrays which hold the additional data. This routine uses the value to select the appropriate data to return. |
radar_location | Location of the radar. |
beam_orientation | Orientation of the radar beam at the observation location. The three values are: sin(azimuth)*cos(elevation), cos(azimuth)*cos(elevation), and sin(elevation). |
nyquist_velocity | Nyquist velocity at the observation point in meters/second. |
integer, intent(out) :: velkey type(location_type), intent(in) :: radar_location real(r8), intent(in) :: beam_direction(3) real(r8), intent(in) :: nyquist_velocity
Sets the auxiliary information associated with a radial velocity observation. This routine increments and returns the new key associated with these values.
velkey | Unique identifier associated with this radial velocity observation. In this code it is an integer index into module local arrays which hold the additional data. This routine returns the incremented value associated with this data. |
radar_location | Location of the radar. |
beam_orientation | Orientation of the radar beam at the observation location. The three values are: sin(azimuth)*cos(elevation), cos(azimuth)*cos(elevation), and sin(elevation). |
nyquist_velocity | Nyquist velocity at the observation point in meters/second. |
integer, intent(out) :: velkey
Prompts the user for the auxiliary information needed for a radial velocity observation, and returns the new key associated with this data.
velkey | Unique identifier associated with this radial velocity observation. In this code it is an integer index into module local arrays which hold the additional data. This routine returns the incremented value associated with this data. |
real(r8), intent(in) :: state_vector(:) type(location_type), intent(in) :: location integer, intent(in) :: velkey real(r8), intent(out) :: radial_vel integer, intent(out) :: istatus
Given a location and the state vector from one of the ensemble members,
compute the model-predicted radial velocity in meters/second
that would be observed at that location. velkey
is the unique index for this particular radial velocity observation.
The value is returned in radial_vel,
istatus is the return code.
The along-beam component of the 3-d air velocity is computed from the
u, v, and w fields plus the beam_direction. The along-beam component
of power-weighted precipitation fall velocity is added to the result.
state_vector | A one dimensional representation of the model state vector |
location | Location of this observation |
velkey | Unique identifier associated with this radial velocity observation |
radial_vel | The returned radial velocity value in meters/second |
istatus | Returned integer status code describing problems with applying forward operator. 0 is a good value; any positive value indicates an error; negative values are reserved for internal DART use only. |
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.
&obs_def_radar_mod_nml apply_ref_limit_to_obs = .false., reflectivity_limit_obs = -10.0, lowest_reflectivity_obs = -10.0, apply_ref_limit_to_fwd_op = .false., reflectivity_limit_fwd_op = -10.0, lowest_reflectivity_fwd_op = -10.0, max_radial_vel_obs = 1000000, allow_wet_graupel = .false., microphysics_type = 2 , allow_dbztowt_conv = .false., dielectric_factor = 0.224, n0_rain = 8.0e6, n0_graupel = 4.0e6, n0_snow = 3.0e6, rho_rain = 1000.0, rho_graupel = 400.0, rho_snow = 100.0 /
Item | Type | Description |
---|---|---|
apply_ref_limit_to_obs | logical | If .TRUE. replace all reflectivity values less than "reflectivity_limit_obs" with "lowest_reflectivity_obs" value. If .FALSE. leave all values as-is. |
reflectivity_limit_obs | real(r8) | The threshold value. Observed reflectivity values less than this threshold will be set to the "lowest_reflectivity_obs" value. Units are dBZ. |
lowest_reflectivity_obs | real(r8) | The 'set-to' value. Observed reflectivity values less than the threshold will be set to this value. Units are dBZ. |
apply_ref_limit_to_fwd_op | logical | Same as "apply_ref_limit_to_obs", but for the forward operator. |
reflectivity_limit_fwd_op | real(r8) | Same as "reflectivity_limit_obs", but for the forward operator values. |
lowest_reflectivity_fwd_op | real(r8) | Same as "lowest_reflectivity_obs", but for the forward operator values. |
max_radial_vel_obs | integer | Maximum number of observations of this type to support at run time. This is combined total of all obs_seq files, for example the observation diagnostic program potentially opens multiple obs_seq.final files, or the obs merge program can also open multiple obs files. |
allow_wet_graupel | logical | It is difficult to predict/diagnose whether graupel/hail has a wet or dry surface. Even when the temperature is above freezing, evaporation and/or absorption can still result in a dry surface. This issue is important because the reflectivity from graupel with a wet surface is significantly greater than that from graupel with a dry surface. Currently, the user has two options for how to compute graupel reflectivity. If allow_wet_graupel is .false. (the default), then graupel is always assumed to be dry. If allow_wet_graupel is .true., then graupel is assumed to be wet (dry) when the temperature is above (below) freezing. A consequence is that a sharp gradient in reflectivity will be produced at the freezing level. In the future, it might be better to provide the option of having a transition layer. |
microphysics_type | integer | If the state vector contains the reflectivity or the power
weighted fall speed, interpolate directly from those regardless of
the setting of this item. If the state vector does not
contain the fields, this value should be set to be
compatible with whatever microphysical scheme is being
used by the model. If the model is using a different
microphysical scheme but has compatible fields to the ones
listed below, setting this value will select the scheme to use.
|
allow_dbztowt_conv | logical | Flag to enable use of the dbztowt routine where reflectivity is available, but not the power-weighted fall velocity. This scheme uses emperical relations between reflectivity and fall velocity, with poor accuracy for highly reflective, low density particles (such as water coated snow aggregates). Expect questionable accuracy in radial velocity from the forward operator with high elevation angles where ice is present in the model state. |
dielectric_factor | real(r8) | According to Smith (1984), there are two choices for the dielectric factor depending on how the snow particle sizes are specified. If melted raindrop diameters are used, then the factor is 0.224. If equivalent ice sphere diameters are used, then the factor is 0.189. The default is set to use the common convention of melted raindrop diameters. |
n0_rain | real(r8) | Intercept parameters (m^-4) for size distributions of each hydrometeor. The default of 8.0e6 is for the Lin et al. microphysics scheme with the Hobbs settings for graupel/hail. (The Hobbs graupel settings are also the default for the Lin scheme in WRF 2.2 and 3.0.) |
n0_graupel | real(r8) | Intercept parameters (m^-4) for size distributions of each hydrometeor. The default of 4.0e6 is for the Lin et al. microphysics scheme with the Hobbs settings for graupel/hail. (The Hobbs graupel settings are also the default for the Lin scheme in WRF 2.2 and 3.0.) |
n0_snow | real(r8) | Intercept parameters (m^-4) for size distributions of each hydrometeor. The default of 3.0e6 is for the Lin et al. microphysics scheme with the Hobbs settings for graupel/hail. (The Hobbs graupel settings are also the default for the Lin scheme in WRF 2.2 and 3.0.) |
rho_rain | real(r8) | Density (kg m^-3) of each hydrometeor type. The default of 1000.0 is for the Lin et al. microphysics scheme with the Hobbs setting for graupel/hail. |
rho_graupel | real(r8) | Density (kg m^-3) of each hydrometeor type. The default of 400.0 is for the Lin et al. microphysics scheme with the Hobbs setting for graupel/hail. |
rho_snow | real(r8) | Density (kg m^-3) of each hydrometeor type. The default of 100.0 is for the Lin et al. microphysics scheme with the Hobbs setting for graupel/hail. |
Routine | Message | Comment |
---|---|---|
initialize_module | initial allocation failed for radial vel obs data, itemcount = (max_radial_vel_obs) | Need to increase max_radial_vel_obs count in namelist |
read_radial_vel | Expected location header "platform" in input file | The format of the input file is not consistent. |
velkey_out_of_range | velkey (val) exceeds max_radial_vel_obs (maxval) | The number of radial velocity observations exceeds the array size allocated in the module. Need to increase max_radial_vel_obs count in namelist. |
read_nyquist_velocity | bad value for nyquist velocity | The format of the input obs_seq file is not consistent. |
read_beam_direction | beam_direction value must be between -1 and 1, got () | The format of the input obs_seq file is not consistent. |
read_beam_direction | Expected orientation header "dir3d" in input file | The format of the input obs_seq file is not consistent. |
none at this time
none at this time
Reads the namelist, allocates space for the auxiliary data associated wtih radial velocity observations, initializes the constants used in subsequent computations (possibly altered by values in the namelist), and prints out the list of constants and the values in use. These may need to change depending on which microphysics scheme is being used.
real(r8), dimension(3) :: read_beam_direction integer, intent(in) :: ifile logical, intent(in) :: is_asciiformat
Reads the beam direction at the observation location. Auxiliary data for doppler radial velocity observations.
read_beam_direction | Returns three real values for the radar beam orientation |
ifile | File unit descriptor for input file |
is_asciiformat | File format specifier: .TRUE. if file is formatted/ascii, or .FALSE. if unformatted/binary. Default .TRUE. |
real(r8), :: read_nyquist_velocity integer, intent(in) :: ifile logical, intent(in) :: is_asciiformat
Reads nyquist velocity for a doppler radial velocity observation.
read_nyquist_velocity | Returns a real value for the nyquist velocity value |
ifile | File unit descriptor for input file |
is_asciiformat | File format specifier: .TRUE. if file is formatted/ascii, or .FALSE. if unformatted/binary. Default .TRUE. |
integer, intent(in) :: ifile real(r8), dimension(3), intent(in) :: beam_direction logical, intent(in) :: is_asciiformat
Writes the beam direction at the observation location. Auxiliary data for doppler radial velocity observations.
ifile | File unit descriptor for output file |
beam_direction | Three components of the radar beam orientation |
is_asciiformat | File format specifier: .TRUE. if file is formatted/ascii, or .FALSE. if unformatted/binary. Default .TRUE. |
integer, intent(in) :: ifile real(r8), intent(in) :: nyquist_velocity logical, intent(in) :: is_asciiformat
Writes nyquist velocity for a doppler radial velocity observation.
ifile | File unit descriptor for output file |
nyquist_velocity | The nyquist velocity value for this observation |
is_asciiformat | File format specifier: .TRUE. if file is formatted/ascii, or .FALSE. if unformatted/binary. Default .TRUE. |
real(r8), dimension(3), intent(out) :: beam_direction
Prompts the user for input for the azimuth and elevation of the radar beam at the observation location. Will be converted to the three values actually stored in the observation sequence file.
beam_direction | Three components of the radar beam orientation |
real(r8), intent(out) :: nyquist_velocity
Prompts the user for input for the nyquist velocity value associated with a doppler radial velocity observation.
nyquist_velocity | Nyquist velocity value for the observation. |
real(r8), intent(in) :: qr real(r8), intent(in) :: qg real(r8), intent(in) :: qs real(r8), intent(in) :: rho real(r8), intent(in) :: temp real(r8), intent(out) :: ref
Computes the equivalent radar reflectivity factor in mm6 m-3 for simple single-moment microphysics schemes such as Kessler and Lin, et al. See the references for more details.
qr | Rain water content (kg kg-1) |
qg | Graupel/hail content (kg kg-1) |
qs | Snow content (kg kg-1) |
rho | Air density (kg m-3) |
temp | Air temperature (K) |
ref | The returned radar reflectivity value |
real(r8), intent(in) :: qr real(r8), intent(in) :: qg real(r8), intent(in) :: qs real(r8), intent(in) :: rho real(r8), intent(in) :: temp real(r8), intent(out) :: precip_fall_speed
Computes power-weighted precipitation fall speed in m s-1 for simple single-moment microphysics schemes such as Kessler and Lin, et al. See the references for more details.
qr | Rain water content (kg kg-1) |
qg | Graupel/hail content (kg kg-1) |
qs | Snow content (kg kg-1) |
rho | Air density (kg m-3) |
temp | Air temperature (K) |
precip_fall_speed | The returned precipitation vall speed |
Set values for a collection of constants used throughout the module during the various calculations. These are set once in this routine and are unchanged throughout the rest of the execution. They cannot be true Fortran parameters because some of the values can be overwritten by namelist entries, but once they are set they are treated as read-only parameters.
Print out the names and values of all constant parameters used by this module. The error handler message facility is used to print the message, which by default goes to both the DART log file and to the standard output of the program.
real(r8), intent(in) :: c_val character(len=*), intent(in) :: c_str
Calls the DART error handler routine to print out a string label and a real value to both the log file and to the standard output.
Value of constant | A real value. |
Name of constant | A character string. |
integer, intent(in) :: velkey
Range check key and trigger a fatal error if larger than the allocated array for observation auxiliary data.
velkey | Integer key into a local array of auxiliary observation data. |
logical, intent(in) :: apply_ref_limit_to_obs real(r8), intent(in) :: reflectivity_limit_obs real(r8), intent(in) :: lowest_reflectivity_obs logical, intent(in) :: apply_ref_limit_to_fwd_op real(r8), intent(in) :: reflectivity_limit_fwd_op real(r8), intent(in) :: lowest_reflectivity_fwd_op
Check the values set in the namelist for consistency. Print out a message if the limits and set-to values are different; this may be intentional but is not generally expected to be the case. In all cases below, see the namelist documentation for a fuller explanation of each value.
apply_ref_limit_to_obs | Logical. See namelist. |
reflectivity_limit_obs | Real value. See namelist. |
lowest_reflectivity_obs | Real value. See namelist. |
apply_ref_limit_to_fwd_op | Logical. See namelist. |
reflectivity_limit_fwd_op | Real value. See namelist. |
lowest_reflectivity_fwd_op | Real value. See namelist. |
logical :: ascii_file_format character(len=*), intent(in), optional :: fform
Should be moved to DART utility module at some point. Returns .TRUE. if the optional argument is missing or if it is not one of the following values: "unformatted", "UNFORMATTED", "unf", "UNF".
ascii_file_format | Return value. Logical. Default is .TRUE. |
fform | Character string file format. |
DART software - Copyright 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: | Nancy Collins, David Dowell, Jeff Anderson |
Revision: | $Revision$ |
Source: | $URL$ |
Change Date: | $Date$ |
Change history: | try "svn log" or "svn diff" |