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

MODULE model_mod

Contact: Kevin Raeder
Reviewers:  
Revision: $Revision: 1.3 $
Change Date: $Date: 2006/06/15 21:29:40 $
Change history: see CVS log

OVERVIEW

The 13 public interfaces in model_mod 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.

This is the DART interface module for the stand-alone CAM model, using the Eulerian dynamical core. It is designed to work for versions of CAM starting with 2.0.1, by specifying the version number in the model_mod namelist. This implementation of DART-CAM uses the CAM (and CLM) initial files for transferring the model state to/from the filter/CAM.

In principle any variable in the initial file can be included in the definition of the state vector via model_mod namelist entries. This may include quantities the model considers to be parameters, although ongoing research is being conducted into the difficulties and meaning of assimilating model parameters of various kinds. The CLM incorporated in the stand-alone CAM is currently (6/16/2006) treated as a parameterization. That is, none of its variables are incorporated into the DART state vector.

Expected observations on pressure, height or model levels can be requested from model_interpolate. Surface observations can not yet be interpolated, due to the difference between the model surface and the earth's surface where the observations are made. Model_interpolate can be queried for any (non-surface) variable in the state vector, which are variables native to CAM, plus pressure on height levels. The default state vector is (PS), T, U, V, Q, CLDLIQ, CLDICE. Other variables can be added, but minor modifications to model_mod.f90 will be necessary. Use the existing code for the current state variables as a template. In particular add the TYPE_s in the declarations at the beginning of the module, and see subroutines order_state_fields and obs_field_location, where those TYPE_s are used. Modify CAM to write the new fields to the initial files, and modify the model_mod_nml (in input.nml) to include the new state vector components. In the namelist the vertical coordinate type of the new fields must also be specified. See which_vert in location_mod

Links to information about setting up assimilation experiments using CAM and parallel architecture computers, including:


OTHER MODULES USED

       netcdf
       obs_kind_mod
       random_nr_mod
       random_seq_mod
       threed_sphere/location_mod
       time_manager_mod
       types_mod
       utilities_mod

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 CAM model only advances by executing the program cam (via script run-pc.csh). Thus the last 4 interfaces only appear as stubs in the CAM module.

The interface pert_model_state is provided for CAM, and it allows each field of the state vector to be randomly perturbed using a separate standard deviation. Even this may not be flexible enough to handle variables such as specific humidity, which can vary by orders of magnitude from the surface to the top of the model.

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




PUBLIC COMPONENTS

The list of interfaces above is the complete public list for this module.


model_size = get_model_size( )
integer                               ::  get_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] )
integer,                  intent(in)    ::  index_in 
type(location_type),      intent(out)   ::  location 
integer, optional,        intent(out)   ::  var_type 

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.

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.

Notes


call model_interpolate(x, location, obs_type, interp_val, istatus)
real(r8), dimension(:),   intent(in)  ::  x 
type(location_type),      intent(in)  ::  location 
integer,                  intent(in)  ::  obs_type 
real(r8),                 intent(out) ::  interp_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. Currently observation types: KIND_U_WIND_COMPONENT, KIND_V_WIND_COMPONENT, KIND_SURFACE_PRESSURE, KIND_TEMPERATURE, KIND_SPECIFIC_HUMIDITY, KIND_PRESSURE are supported, but others can be added. KIND_PRESSURE does not have a corresponding field on CAM initial files, but is routinely calculated in CAM using its own subroutines. Interpolation of this field has been incorporated in order to facilitate assimilations of observations which require it, such as GPS radio occultation. If the interpolation is valid, istatus = 0. In the case where the observational operator is not defined at the given location (e.g. the observation is below the lowest model level or above the top level), interp_val is returned as 0.0 and istatus = 1. CAM is highly damped in the upper levels of the model, which has required the exclusion of otherwise valid observations above a certain level, which can be specified in the model_mod namelist variable highest_obs_pressure_mb. Such cases return istatus = 2, and also do the interpolation and return the value, which is NOT used by filter. Eventually such quality control may be moved to another module, but for now is performed in subroutine get_val_pressure.

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

Notes


var = get_model_time_step( )
type(time_type)                       ::  get_model_time_step 

Description

Returns the forecast length to be used as the "model base time step" in the filter. The choice of initial files instead of restart files restricts the assimilation from using "time steps" which are too small. This is because CAM uses a leapfrog time scheme, but the initial files store only a single timestep. The initial forecast step is a simple forward step, so if repeated short forecasts (< ~9 model time steps) are made, the model becomes unstable. 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_mod namelist parameters, sets the calendar type (the GREGORIAN calendar is used with the CAM model), and determines the dart vector length, among other things. This subroutine requires that caminput.nc (or the name in namelist variable model_config_file) be present in the working directory to retrieve model information (grid dimensions and spacing including the vertical hybrid coordinate coefficients, time step, and Gaussian weights, etc).

Notes


call model_get_close_states(o_loc, radius, nfound, indices, dist, x)
type(location_type),      intent(in)    ::  o_loc 
real(r8),                 intent(in)    ::  radius 
real(r8), dimension(:),   intent(in)    ::  x 
integer,                  intent(out)   ::  nfound 
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 CAM model and the units for the radius are radians. The physical horizontal distance is obtained by multiplying by the earth's radius and is the great circle distance. The indices into the long state vector as well as the distances 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.
nfound 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

The vertical distance calculation is not fully implemented yet. CAM uses a hybrid vertical coordinate, which requires the surface pressure beneath a point in order to determine the point's vertical coordinate. When the model state vector is divided up among several regions during parallelization, surface pressure points from other regions become unavailable. The (temporary) fix is to hard-wire the surface pressure to be 100000 Pa. Due to the damping at high levels (see model_interpolate) there is also code which reduces the influence of observations on model points above some altitude. Currently namelist variables highest_obs_{pressure_mb,height_m,level} control this for observations with pressure, height, and level vertical coordinates, respectively. The influence declines to 0 above model level 6 for highest_obs_pressure_mb = 150.


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 ensemble initial 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 wrong. This implementation allows each field in the state vector to be randomly perturbed with a separate standard deviation. The fields to be perturbed, and the associated standard deviations are specified in the model_mod namelist using state_names_pert and state_names_sd. The entries in state_names_pert should be in the same order as those in state_names_#d (# = 0,1,2,3 in that order). As in the default, the perturbations sd*N[0,1] are added onto the basic state field, so sd should not be a percentage of the basic state field, but an actual physical size. This subroutine is also used by trans_pv_sv_pert0 for the off-line perturbation of fields the model considers to be parameters. In this use a new random sequence seed must be provided via an input file ("ens_member") for each ensemble member, since trans_pv_sv_pert0 is executed once for each member and can't keep a series of different seeds intact.

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 CAM 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 CAM 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 CAM model.

Notes


call init_time(time)
type(time_type),          intent(in)    ::  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 CAM 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 CAM model it's just a stub because 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 , model_version , model_config_file          &  
                     ,state_num_0d   ,state_num_1d   ,state_num_2d   ,state_num_3d     &
                     ,state_names_0d ,state_names_1d ,state_names_2d ,state_names_3d   &
                                     ,which_vert_1d  ,which_vert_2d  ,which_vert_3d    &
		     ,state_names_pert ,state_names_sd ,max_obs_lat_degree             &
		     ,highest_obs_pressure_mb ,highest_obs_height_m ,highest_obs_level &
                     ,Time_step_seconds ,Time_step_days

    

Discussion

This namelist is read in a file called input.nml The specification of lists of names and numbers for the various dimensions enables the very flexible definition of the state vector. It can be done via the namelist, instead of recompiling DART for each different set. One hurdle that still remains is that distinct filter_ics are necessary for each separate set of fields which compose the state vector.

The dimension of these lists is hardwired to size 20, which will become a problem when long lists of chemical species are to be assimilated. We intend to fix this by specifying 2 namelists for model_mod. The first will list the numbers of fields to be incorporated into the state vector. Those will be used to dimension the lists of names, vertical types, etc. Then the second namelist will fill the lists, etc.

The values for which_vert_#d is described in DART/location/threed_sphere/location_mod.html.

The names of the fields to put into the state vector come from the CAM initial file field names.

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 (gridded data) for easier plotting (recommended).
model_version character(len=128) The number of the CAM version being used, i.e. '3.0.7'. (no letters allowed, so rename cam3_0_p1) Default = '3.0' .
model_config_file character(len=128) CAM initial file used to provide configuration information. Default 'caminput.nc'.
state_num_#d, #=0,1,2,3 integer Numbers of fields of various dimensions to put into the state vector. Defaults state_num_0d=0, _1d=0, _2d=1, _3d=4 .
state_names_#d, #=0,1,2,3 character(len=8), dimension(20) Names of fields of various dimensions to put into the state vector. Defaults
state_names_0d='        ', state_names_1d='        ', 
state_names_2d='PS      ' 
state_names_3d='T       ','U       ','V       ','Q       '  
which_vert_#d, #=1,2,3 integer, dimension(20) Vertical location types of fields in state_names_#d. Defaults
  • which_vert_1d = state_num_1d*-2,
  • which_vert_2d = state_num_2d*-1,
  • which_vert_3d = state_num_3d* 1
state_names_pert character(len=8) dimension(20) Names of the state vector fields to perturb. Defaults
state_names_pert='        ' 
max_obs_lat_degree real(r8) Observations closer to the poles than this latitude will be ignored. Default 90 degrees
highest_obs_pressure_mb real(r8) Observations higher than this pressure are ignored. Influence of all obs on model points higher than this is reduced. Default 30. hPa
highest_obs_height_m real(r8) Observations higher than this height are ignored. Influence of all obs on model points higher than this is reduced. Default 30000 m
highest_obs_level integer Observations higher than this level are ignored. Influence of all obs on model points higher than this is reduced. Default 11
Time_step_seconds real(r8) Forecast duration (the part < 1 day) Default 21600 sec
Time_step_days real(r8) Forecast duration (the part > 24*3600 sec) Default 0 days



FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
read_cam_init_size
read_cam_init
write_cam_init
nc_read_model_atts
nc_write_model_atts
nc_write_model_vars
read_cam_coord
read_cam_scalar
Various NetCDF-f90 interface error messages From one of the NetCDF calls in the named routine
prog_var_to_vector
vector_to_prog_var
get_state_meta_data
get_val
model_get_close_states
scalar and 1-D vector components of state vector are not coded into this routine Only 2D and 3D fields can be part of state vector so far.
prog_var_to_vector
vector_to_prog_var
indx # and model_size # must be equal indx was tallied during insertion of fields into state vector
model_get_close_states which_vert = # not handled in model_get_close_states See which_vert description in location/threed_sphere/location_mod.html
nc_write_model_atts Time dimension ID # must match Unlimited Dimension ID # NetCDF file writing error
order_state_fields nfld = #, nflds = # must be equal Mismatch(es) of state_names_#d and state_num_#d in model_mod_nml



KNOWN BUGS

See description of timestep limitation in get_model_time_step.

See description of dealing with highly damped top layers in CAM in model_interpolate and model_get_close_states.




FUTURE PLANS




PRIVATE COMPONENTS

use model_mod, only : read_cam_init_size
 read_cam_init
 read_cam_coord
 read_cam_scalar
 nc_read_model_atts
 check
 write_cam_init
 prog_var_to_vector
 vector_to_prog_var
 init_model_instance
 end_model_instance
 plevs_cam
 get_val_pressure
 get_val_height
 get_val_level
 get_val
 grid_close_states2
 lon_search
 get_closest_lat_index
 get_closest_lon_index
 order_state_fields
 size_coord
 obs_field_location
 model_heights
 dcz2
 gravity
 gph2gmh


call read_cam_init_size(file_name,num_lons,num_lats,num_levs)
 character(len, intent(in) :: file_name
 integer, intent(out)      :: num_lons
 integer, intent(out)      :: num_lats
 integer, intent(out)      :: num_levs
 

Description

Gets the number of lons, lats and levels from a netcdf CAM initial file

file_name    CAM initial file.
num_lons    Number of longitudes in this CAM resolution.
num_lats    Number of latitudes.
num_levs    Number of data levels.


call read_cam_init(file_name,var)
 character(len, intent(in)     :: file_name
 type(model_type), intent(out) :: var
 

Description

Reads state vector fields from a CAM initial file. Fields are specified in model_mod.nml.

file_name    CAM initial file name.
var    Structure to hold the state vector fields read from file_name.


call read_cam_coord(var,idim,cfield)
 real(r8), dimension(:), intent(out) :: var
 integer, intent(in)                 :: idim
 character, intent(in)               :: cfield
 

Description

Reads a coordinate array from a CAM initial file.

var    A coordinate array from a CAM initial file.
idim    Length of var.
cfield    Name of var, as found on the CAM initial file.


call read_cam_scalar(var,cfield)
 real(r8), intent(out) :: var
 character, intent(in) :: cfield
 

Description

Reads a scalar parameter from a CAM initial file.

var    Scalar to be read from a CAM initial file.
cfield    The name of the scalar to read.


call nc_read_model_atts(att,att_vals,nflds)
 character, intent(in)                :: att
 character, dimension(:), intent(out) :: att_vals
 integer, intent(in)                  :: nflds
 

Description

Reads the value of an attribute for each of the fields in cflds.

att    The name of an attribute of the fields on a CAM initial file.
att_vals    The values which that attribute has for each of the nflds fields needed for the state vector.
nflds    The number of fields in the state vector.


call check(istatus)
 integer, intent(in) :: istatus
 

Description

Checks the error status of the NetCDF function call and calls error_handler if the status is non-0.

istatus    The error status returned from a NetCDF function call.


call write_cam_init(file_name,var)
 character, intent(in)                     :: file_name
 type(model_type), allocatable, intent(in) :: var
 

Description

Write fields that have been updated by assimilation to the CAM 'initial' file.

file_name    Name of CAM initial file to which var will be written.
var    Structure containing all the fields of the state vector.


call prog_var_to_vector(var,x)
 type(model_type), allocatable, intent(in)        :: var
 real(r8), allocatable, dimension(:), intent(out) :: x
 

Description

Insert CAM fields (N-D) into DART state vector array (1-D)

var    Structure containing all the fields of the state vector.
x    DART state vector.


call vector_to_prog_var(x,var)
 real(r8), allocatable, dimension(:), intent(in) :: x
 type(model_type), allocatable, intent(out)      :: var
 

Description

Extract CAM fields (N-D) from state vector (1-D).

x    DART state vector.
var    Structure containing all the fields of the state vector.


call init_model_instance(var)
 type(model_type), allocatable, intent(out) :: var
 

Description

Initializes an instance of a cam model state variable; all the fields specified for the state vector.

var    Structure which contains all the fields of various dimensions which are in the DART state vector.


call end_model_instance(var)
 type(model_type), allocatable, intent(inout) :: var
 

Description

Ends an instance of a cam model state variable

var    Structure which contains all the fields included in the state vector.


call plevs_cam(ncol,ncold,ps,pmid)
 integer, intent(in)                 :: ncol
 integer, intent(in)                 :: ncold
 real(r8), dimension(:), intent(in)  :: ps
 real(r8), dimension(:), intent(out) :: pmid
 

Description

Define the pressures of the CAM data levels (layer midpoints) from the coordinate definitions and the surface pressure.

ncol    Number of columns of pressures to calculate (DART-CAM uses 1)
ncold    Dimension of ps.
ps    Surface pressure at this latitude and longitude (Pa).
pmid    Pressures at the CAM "midpoint" levels.


call get_val_pressure(val,x,lon_index,lat_index,pressure, obs_kind,istatus)
 real(r8), intent(out)                           :: val
 real(r8), allocatable, dimension(:), intent(in) :: x
 integer, intent(in)                             :: lon_index
 integer, intent(in)                             :: lat_index
 real(r8), intent(in)                            :: pressure
 integer, intent(in)                             :: obs_kind
 integer0, intent(out)                           :: istatus
 

Description

Gets the vertically interpolated value on pressure for variable obs_kind at the lon_index, lat_index horizontal grid point. Some quality control of observations is done here, but may be moved later. For now, observations above the lower of highest_obs_pressure_mb and the model's highest level, and below the lowest model level are excluded.

val    The value of the obs_kind variable interpolated from state vector x.
x    DART state vector.
lon_index    Index of longitude of this val.
lat_index    Index of latitude of this val.
pressure    The pressure to which this obs_kind must be interpolated.
obs_kind    The kind of variable being interpolated, i.e. T.
istatus    Flag containing the status of the interpolation. 0=all good, 1=can't interpolate, 2=can interpolate but don't use the value.


call get_val_height(val,x,lon_index,lat_index,height, obs_kind,istatus)
 real(r8), intent(out)                           :: val
 real(r8), allocatable, dimension(:), intent(in) :: x
 integer, intent(in)                             :: lon_index
 integer, intent(in)                             :: lat_index
 real(r8), intent(in)                            :: height
 integer, intent(in)                             :: obs_kind
 integer, intent(out)                            :: istatus
 

Description

Gets the vertically interpolated value on height for variable obs_kind at the lon_index, lat_index horizontal grid point. Some quality control of observations is done here, but may be moved later. For now, observations above the lower of highest_obs_height_m and the model's highest level, and below the lowest model level are excluded. So are PS and Q observations.

val    The value of the obs_kind variable interpolated from state vector x.
x    DART state vector.
lon_index    Index of longitude of this val.
lat_index    Index of latitude of this val.
height    The height to which this obs_kind must be interpolated.
obs_kind    The kind of variable being interpolated, i.e. T.
istatus    Flag containing the status of the interpolation. 0=all good, 1=can't interpolate, 2=can interpolate but don't use the value.


call get_val_level(val,x,lon_index,lat_index,level, obs_kind,istatus)
 real(r8), intent(out)                           :: val
 real(r8), allocatable, dimension(:), intent(in) :: x
 integer, intent(in)                             :: lon_index
 integer, intent(in)                             :: lat_index
 integer, intent(in)                             :: level
 integer, intent(in)                             :: obs_kind
 integer, intent(out)                            :: istatus
 

Description

Gets the value on the model level for variable obs_kind at the lon_index, lat_index horizontal grid point. Some quality control of observations is done here, but may be moved later. For now, observations above the lower of highest_obs_level and the models highest level, and below the lowest model level are excluded. So are PS and Q observations.

val    The value of the obs_kind variable interpolated from state vector x.
x    DART state vector.
lon_index    Index of longitude of this val.
lat_index    Index of latitude of this val.
level    The level for which this obs_kind must be retrieved.
obs_kind    The kind of variable being interpolated, i.e. T.
istatus    Flag containing the status of the interpolation. 0=all good, 1=can't interpolate, 2=can interpolate but don't use the value.


call get_val(val,x,lon_index,lat_index,level,obs_kind,istatus)
 real(r8), intent(out)                           :: val
 real(r8), allocatable, dimension(:), intent(in) :: x
 integer, intent(in)                             :: lon_index
 integer, intent(in)                             :: lat_index
 integer, intent(in)                             :: level
 integer, intent(in)                             :: obs_kind
 integer, intent(out)                            :: istatus
 

Description

Extracts the value of a field at a specified location from the DART state vector.

val    The value of the obs_kind variable at a grid point, from state vector x.
x    DART state vector.
lon_index    Index of longitude of this val.
lat_index    Index of latitude of this val.
level    The level of the obs_kind variable desired.
obs_kind    The kind of variable being interpolated, i.e. T.
istatus    Flag containing the status of the interpolation. 0=all good, 1=can't in terpolate, 2=can interpo but don't use the value.


call grid_close_states2(o_loc,lons,lats,nlon,nlat,radius,num,cl ose_lon_ind,close_lat_ind,close_dist)
 type(location_type), intent(in)                    :: o_loc
 real(r8), dimension(:), intent(in)                 :: lons
 real(r8), dimension(:), intent(in)                 :: lats
 integer, intent(in)                                :: nlon
 integer, intent(in)                                :: nlat
 real(r8), intent(in)                               :: radius
 integer, intent(inout)                             :: num
 integer, dimension(:), intent(inout)               :: close_lon_
 ind
 integer, allocatable, dimension(:), intent(inout)  :: close_lat_
 ind
 real(r8), allocatable, dimension(:), intent(inout) :: close_dist
 
 

Description

Finds close state points from a particular grid; Just uses horizontal distance by setting pressure of state location to same as observation.

o_loc    Observation location.
lons    Values of model longitudes.
lats    Values of model latitudes
nlon    Number of model longitudes.
nlat    Number of model latitudes
radius    Distance within which a model point is considered to be close to the ob servation.
num    Number of model points within radius of o_loc.
close_lon_ind    Indices of the longitudes of the close points.
close_lat_ind    Indices of the latitudes of the close points.
close_dist    Distances of the close points from o_loc.


call lon_search(glat,glev,blon_ind,o_loc,radius,lons,close_lon_ ind,close_dist,num)
 real(r8), intent(in)                             :: glat
 real(r8), intent(in)                             :: glev
 integer, intent(in)                              :: blon_ind
 type(location_type), intent(in)                  :: o_loc
 real(r8), intent(in)                             :: radius
 real(r8), allocatable, dimension(:), intent(in)  :: lons
 integer, allocatable, dimension(:), intent(out)  :: close_lon_in
 d
 real(r8), allocatable, dimension(:), intent(out) :: close_dist
 integer, intent(out)                             :: num
 

Description

Given an observation location and radius and a latitude row from a grid, searches to find all longitude points in this row that are within radius of the observation location and returns their latitude index, longitude index, and the distance between them and the observation.

glat    The latitude to search for closeness to o_loc.
glev    The level at which to search for closeness to o_loc. Currently unused.
blon_ind    Longitude closest to o_loc.
o_loc    The location of the observation.
radius    The distance within which a model point is considered close to o_loc.
lons    Values of the model grid longitudes.
close_lon_ind    Longitudes of the model points which are close to o_loc.
close_dist    Distances of the close model points from o_loc.
num    Number of model points at this latitude which are close to o_loc.


call get_closest_lat_index(o_lat,lats,nlat)
 real(r8), intent(in)               :: o_lat
 real(r8), dimension(:), intent(in) :: lats
 integer, intent(in)                :: nlat
 

Description

Finds the latitude of the grid point closest to the observation.

o_lat    Latitude of the observation.
lats    Model grid latitudes.
nlat    Number of model grid latitudes.


call get_closest_lon_index(o_lon,lons,nlon)
 real(r8), intent(in)               :: o_lon
 real(r8), dimension(:), intent(in) :: lons
 integer, intent(in)                :: nlon
 

Description

Finds the longitude of the grid point closest to the observation.

o_lon    Longitude of the observation.
lons    Longitudes of the CAM grid.
nlon    Number of longitudes of the CAM grid.


call order_state_fields(cflds,nflds)
 character, dimension(:), intent(out) :: cflds
 integer, intent(in)                  :: nflds
 

Description

Fills cflds with state_names for use in I/O of caminput.nc Also assigns field TYPE_ variables for use by get_state_meta_data, and other routines.

cflds    Master list of CAM fields to be incorporated in the DART state vector.
nflds    Number of CAM fields in the state vector.


call size_coord(coord_3d,coord_2d,coord_order)
 integer, dimension(:), intent(out) :: coord_3d
 integer, dimension(:), intent(out) :: coord_2d
 integer, intent(out)               :: coord_order
 

Description

Figure out the order of the coordinates (lon, lat, lev) for the 3-D fields on the CAM initial file, based on the CAM version from model_mod.nml, which has form #.#[.#[.#]] The order changed from (lon,lev,lat) to (lon,lat,lev) around CAM3.0.3.

coord_3d    The order of the coordinates for 3-D fields on the CAM initial file for this version of CAM.
coord_2d    Similarly for 2-D fields.
coord_order    Flag saying whether the coordinate orders are for pre- or post- CAM3.0.3, when the levs and lats were exchanged.


call obs_field_location(obs_loc_in_sv)
 integer, dimension(:), intent(out) :: obs_loc_in_sv 
 

Description

Makes an array of 'locations within the state vector' of all the available obs kinds that come from obs_kind_mod. The obs kind that's needed will be the index into this array, the corresponding array value will be the position of that field (not individual variable) within the state vector according to state_names_Xd. There will be lots of empty array elements, since KIND_x has a lot of "missing" values. This subroutine will be called from static_init_model, so it will not have to be recomputed for every obs.

obs_loc_in_sv    Array of locations of obs *fields* (not individual variables) within th e state vector.

NEW


call model_heights( x,lon_index,lat_index,model_h,istatus)
 real(r8), dimension(:), intent(in)              :: x
 integer, intent(in)                             :: lon_index
 integer, intent(in)                             :: lat_index
 real(r8), intent(out)                           :: model_h
 integer, intent(out)                            :: istatus
 

Description

This routine calculates geometrical height (m) at mid-layers of the CAM model

x    DART state vector.
lon_index    Index of longitude of this val.
lat_index    Index of latitude of this val.
model_h    geometrical height at midlayer (m).


call dcz2(ps,phis0,tv,hprb,hyba,hybb,kmax,idim,imax,pmln, & hypdln,hyalph,pterm,z2)
 real(r8), dimension(idim,kmax), intent(out)     :: z2
 real(r8), dimension(idim), intent(in)           :: ps
 real(r8), dimension(idim), intent(in)           :: phis0
 real(r8), dimension(idim,kmax), intent(in)      :: tv
 real(r8), intent(in)                            :: hprb
 real(r8), dimension(2,kmax+1), intent(in)      :: hyba
 real(r8), dimension(2,kmax+1), intent(in)      :: hybb
 integer, intent(in)                             :: kmax
 integer, intent(in)                             :: idim
 integer, intent(in)                             :: imax
 real(r8), dimension(idim,kmax+1), intent(in)      :: pmln
 real(r8), dimension(idim,kmax), intent(in)      :: hypdln
 real(r8), dimension(idim,kmax), intent(in)      :: hyalph
 real(r8), dimension(idim,kmax), intent(in)      :: pterm
 

Description

To compute geopotential height for a CCM2 hybrid coordinate vertical slice. Since the vertical integration matrix is a function of latitude and longitude, it is not explicitly computed as for sigma coordinates. The integration algorithm is derived from Boville's mods in the ibm file hybrid 1mods (6/17/88). All vertical slice arrays are oriented top to bottom as in CCM2. This field is on full model levels (aka "midpoints") not half levels. See code for more history.

z2    Geopotential height, top to bottom.
ps    Surface pressure (pascals).
phis0    Surface geoptential.
tv    Virtual temperature, top to bottom.
hprb    Hybrid base pressure (pascals).
hyba    Hybrid coord coeffs for base pressure.
hybb    Hybrid coord coeffs for surf pressure (in same format as hyba).
kmax    Number of vertical levels.
idim    Longitude dimension.
imax    Num of longitude points to compute.
pmln    Vertical slice scratch space used to hold logs of midpoint pressures.
hpdln    Vertical slice scratch space used to hold log p layer thickness.
hyalph    Vertical slice scratch space used to hold distance from interface to level during vertical integration.
pterm    Vertical scratch space.


gph2gmh = gph2gmh(h, lat)
 real(r8), intent(out)                           :: gph2gmh
 real(r8), intent(in)                            :: h
 real(r8), intent(in)                            :: lat
 

Description

Convert a geopotential altitude to mean sea level altitude.

gph2gmh    MSL altitude, in km.
h    geopotential altitude (in km).
lat    latitude in degrees.


call gravity (xlat,alt,galt)
 real(r8), intent(out)                           :: galt
 real(r8), intent(in)                            :: xlat
 real(r8), intent(in)                            :: alt
 

Description

This subroutine computes the Earth's gravity at any altitude and latitude. The model assumes the Earth is an oblate spheriod rotating at a the Earth's spin rate. The model was taken from "Geophysical Geodesy, Kurt Lambeck, 1988". Compute acceleration due to the Earth's gravity at any latitude/altitude author Bill Schreiner 5/95

galt    gravity at the given lat and alt, cm/sec.
xlat    latitude in radians.
alt    altitude above the reference ellipsiod, km.