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

MODULE assim_model_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.8 $
Release Name: $Name: post_iceland $
Change Date: $Date: 2005/10/17 19:46:14 $
Change history: see CVS log

OVERVIEW

This module acts as an intermediary between DART compliant models and the filter. At one time the assim_model_type, which combines a state vector and a time_type, was envisioned as being fundamental to how DART views model states. This paradigm is gradually being abandoned so that model state vectors and times are handled as separate data types. It is important to call static_init_assim_model before using routines in assim_model_mod. Interfaces to work with model time stepping, restart files, and computations about the locations of model state variables and the distance between observations and state variables. Many of the interfaces are passed through nearly directly to the model_mod.




OTHER MODULES USED

types_mod
location_mod (model dependent choice)
time_manager_mod
utilities_mod
model_mod



PUBLIC INTERFACE

use assim_model_mod, only : assim_model_type
 netcdf_file_type
 static_init_assim_model
 init_diag_output
 get_model_size
 get_closest_state_time_to
 aget_initial_condition
 get_state_meta_data
 get_close_states
 get_num_close_states
 get_model_time
 get_model_state_vector
 copy_assim_model
 interpolate
 set_model_time
 set_model_state_vector
 write_state_restart
 read_state_restart
 output_diagnostics
 end_assim_model
 init_diag_input
 input_diagnostics
 get_diag_input_copy_meta_data
 init_assim_model
 get_state_vector_ptr
 finalize_diag_output
 aoutput_diagnostics
 aread_state_restart
 aget_closest_state_time_to
 awrite_state_restart
 pert_model_state
 nc_append_time
 nc_write_calendar_atts
 nc_get_tindex
 get_model_time_step
 open_restart_read
 open_restart_write
 close_restart
 adv_1step
 get_initial_condition

NOTES

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




PUBLIC COMPONENTS





type assim_model_type
   private
   real(r8), pointer   :: state_vector(:) 
   type(time_type)     :: time
   integer             :: model_size
   integer             :: copyID
end type assim_model_type

Description

This type is used to represent both the state and time of a state from a model.

Component Description
state_vector A one dimensional representation of the model state vector.
time The time of the model state.
model_size Size of the model state vector.
copyID Not used in present implementation.



type netcdf_file_type
   integer             :: ncid
   integer             :: Ntimes
   integer             :: NtimesMAX
   real(r8), pointer   :: rtimes(:)
   type(time_type), pointer :: times(:)
   character(len = 80)      :: fname
end type netcdf_file_type

Description

Basically, we want to keep a local mirror of the unlimited dimension coordinate variable (i.e. time) because dynamically querying it causes unacceptable performance degradation over "long" integrations.

Component Description
ncid The netcdf file unit id.
Ntimes The current working length.
NtimesMAX Allocated length.
rtimes Times as real (r8).
times Times as time_types.
fname Netcdf file name.


call static_init_assim_model()

Description

Initializes the assim_model class. Must be called before any other assim_model_mod interfaces are used. Also calls the static initialization for the underlying model.

Notes


ncFileID = init_diag_output(FileName, global_meta_data, copies_of_field_per_time, meta_data_per_copy)
integer                                        ::  init_diag_output 
character (len = *)                            ::  FileName 
character (len = *)                            ::  global_meta_data 
integer, intent(in)                            ::  copies_of_field_per_time 
character (len = *), intent(in), &
          dimension(copies_of_field_per_time)  ::  meta_data_per_copy 

Description

Initializes a netCDF file for output of state space diagnostics. A handle to the channel on which the file is opened is returned.

FileName     Name of file to open.
global_meta_data Global metadata that describes the contents of this file.
copies_of_field_per_time Number of copies of data to be written at each time. For instance, these could be the prior ensemble members, prior ensemble mean, prior ensemble spread, posterior ensemble members, posterior spread and mean, etc..
meta_data_per_copy Metadata describing each of the copies.
ncFileID Channel number on which file is opened.


var = get_model_size()
integer                               :: get_model_size 

Description

Returns the size of the model state vector. This is a direct pass through to the model_mod.



var = get_closest_state_time_to(assim_model, time)
type(time_type)                                   ::  get_closest_state_time_to 
type(assim_model_type), intent(in)                ::  assim_model 
type(time_type), intent(in)                       ::  time

Description

Returns the closest time that a model is capable of advancing a given state to a specified time. For instance, what is the closest time to 12GMT 01 January, 2004 that a model state at 00GMT 01 January, 2004 can be advanced? If the model time is past the time, the model time is returned (new feature in releases after Hawaii).

assim_model     A model state vector and time that might be advanced.
time A time that one would like to get close to with the model.
var The closest time to which the model can be advanced is returned.


call aget_initial_condition(time,x)
 type(time_type), intent(out) :: time
 type(r8), intent(out) :: x
 

Description

Reads an initial time and state vector from a restart format file into a real time and real array, which are put into an assim_model_type.

time    Contains time of input state vector on return
x    Contains state of input state vector on return


call get_state_meta_data()
 

Description

SEE model_mod for arguments and description.



call get_close_states(location,radius,numinds,indices,dist,x)
 type(location_type), intent(in)     :: location
 real(r8), intent(in)                :: radius
 integer, intent(out)                :: numinds
 integer, dimension(:), intent(out)  :: indices
 real(r8), dimension(:), intent(out) :: dist
 real(r8), dimension(:), intent(in)  :: x
 

Description

Returns the number of state variables within radius of location along with the distances. If a call to model_get_close_states returns -1, a naive search is done. Otherwise, the results from model_get_close_states are used. If the size of indices is too small to hold the number of close states, the number of states found is multiplied by -1 and returned in numinds. The model state vector is needed to determine state variable location in some cases, sigma models for instance, and is passed along.

location    A location around which close model state variables are to be found
radius    Radius within which a model state is said to be close to location
numinds    Returns number of close states; number is multiplied by -1 if indices was too small
indices    Indices for the close states, not set if it is not big enough
dist    Distance to each close state from location, not set if it is not big enough
x    Model state vector; needed to determine location in some cases


var = get_num_close_states(location,radius,x)
 integer                            :: get_num_close_states
 type(location_type), intent(in)    :: location
 real(r8), intent(in)               :: radius
 real(r8), dimension(:), intent(in) :: x
 

Description

Finds number of model state variables within radius of location.

get_num_close_states    Number of states variables close to location.
location    Location around which to find close states
radius    Anything closer than radius is close
x    Model state, sometimes needed for computing locations


var = get_model_time(assim_model)
 type(time_type)                    :: get_model_time
 type(assim_model_type), intent(in) :: assim_model
 

Description

Returns time from an assim_model type.

get_model_time    Time from assim_model
assim_model    Assim_model type from which to extract time


var = get_model_state_vector(assim_model)
 real(r8), dimension(model_size)    :: get_model_state_vector
 type(assim_model_type), intent(in) :: assim_model
 

Description

Returns the state vector component from an assim_model_type.

get_model_state_vector    Returned state vector
assim_model    Input assim_model_type


call copy_assim_model(model_out,model_in)
 type(assim_model_type), intent(out) :: model_out
 type(assim_model_type), intent(in)  :: model_in
 

Description

Copies one assim_model_type to another.

model_out    Copy
model_in    Copy


call interpolate(x,location,loctype,obs_vals,istatus)
 real(r8), intent(in), dimension(:) :: x
 type(location_type), intent(in)    :: location
 integer, intent(in)                :: loctype
 real(r8), intent(out)              :: obs_vals
 integer, intent(out)               :: istatus
 

Description

Interpolates a given model state variable type to a location given the model state vector. Nearly direct call to model_interpolate in model_mod. See model_mod for the error return values in istatus.

x    Model state vector.
location    Location to which to interpolate.
loctype    Type of variable to interpolate.
obs_vals    Returned interpolated value.
istatus    Returned as 0 if all is well, else various errors.


call set_model_time(assim_model,time)
 type(assim_model_type), intent(inout) :: assim_model
 type(time_type), intent(in)           :: time
 

Description

Sets the time in an assim_model_type.

assim_model    Set the time in this assim_model_type.
time    Set to this time


call set_model_state_vector(assim_model,state)
 type(assim_model_type), intent(inout) :: assim_model
 real(r8), dimension(:), intent(in)    :: state
 

Description

Set the state in an assim_model_type.

assim_model    Set the state vector part of this.
state    The state vector to be inserted.


call write_state_restart(assim_model,funit[,target_time])
 type(assim_model_type), intent(in)    :: assim_model
 integer, intent(in)                   :: funit
 type(time_type), optional, intent(in) :: target_time
 

Description

Writes a restart from an assim_model_type with an optional target_time.

assim_model    Write a restart from this assim_model_type.
funit    Integer file unit id open for output of restart files.
target_time    If present, put this target time at the front of the restart file.


call read_state_restart(assim_model,funit[,target_time])
 type(assim_model_type), intent(out)    :: assim_model
 integer, intent(in)                    :: funit
 type(time_type), optional, intent(out) :: target_time
 

Description

Read a state restart file into assim_model_type. Optionally read a prepended target time.

assim_model    Read the time and state vector from restart into this.
funit    File id that has been opened for reading restart files.
target_time    If present, read a target time from the front of the file into this.


call output_diagnostics(ndFileID,state,copy_index)
 type(netcdf_file_type), intent(inout) :: ndFileID
 type(assim_model_type), intent(in)    :: state
 integer, optional, intent(in)         :: copy_index
 

Description

Writes one copy of the state time and vector to a netCDF file.

ndFileID    An identifier for a netCDFF file
state    State vector and time
copy_index    Which copy of state is to be output


call end_assim_model()
 

Description

Called to clean-up at end of assim_model use. For now just passes through to model_mod.



call input_diagnostics(file_id,state,copy_index)
 integer, intent(in)                   :: file_id
 type(assim_model_type), intent(inout) :: state
 integer, intent(out)                  :: copy_index
 

Description

Used to read in a particular copy of the state vector from an open state diagnostics file.

file_id    Integer descriptor (channel number) for a diagnostics file being read.< /TD>
state    Assim_model_type to read in data.
copy_index    Which copy of state to be read.


var = init_diag_input(file_name, global_meta_data, model_size, copies_of_field_per_time)
 integer                       :: init_diag_input
 character(len=*), intent(in)  :: file_name
 character(len=*), intent(out) :: global_meta_data
 integer, intent(out)          :: model_size
 integer, intent(out)          :: copies_of_field_per_time
 

Description

Opens a state diagnostic file and reads the global meta data, model size, and number of data copies.

init_diag_input    Returns the unit number on which the file is open.
file_name    File name of state diagnostic file.
global_meta_data    Global metadata string from file.
model_size    Size of model.
copies_of_field_per_time    Number of copies of the state vector at each time.


call init_assim_model(state)
 type(assim_model_type), intent(inout) :: state
 

Description

Creates storage for an assim_model_type.

state    An assim_model_type that needs storage created.


call get_diag_input_copy_meta_data(file_id,model_size_out, num_copies,location,meta_data_per_copy)
 integer, intent(in)                                         :: file_id
 integer, intent(in)                                         :: model_size_out
 integer, intent(in)                                         :: num_copies
 type(location_type), dimension(model_size_out), intent(out) :: location
 character(len = *), dimension(num_copies)                   :: meta_data_per_copy
 

Description

Reads meta-data describing state vectors in a state diagnostics file. Given the file, the model_size, and the number of copies, returns the locations of each state variable and the text description of each copy.

file_id    Integer channel open to state diagostic file being read
Model_size_out    model size
num_copies    Number of copies of state in file
location    Returned locations for state vector
meta_data_per_copy    Meta data describing what is in each copy of state vector


var = get_state_vector_ptr(assim_model)
 real(r8), pointer, dimension(:)    :: get_state_vector_ptr
 type(assim_model_type), intent(in) :: assim_model
 

Description

Return a pointer to the state part of an assim_model_type. This routine is unlikely to be supported in the future.

get_state_vector_ptr    A pointer to just the state vector of an assim_model_type.
assim_model    An assim_model_type whose state is to be pointed to.


var = finalize_diag_output(ncFileID)
 integer                               :: finalize_diag_output
 type(netcdf_file_type), intent(inout) :: ncFileID
 

Description

Used to complete writing on and open netcdf file. An error return is provided for passing to the netcdf error handling routines.

finalize_diag_output    Returns an error value.
ncFileID    Netcdf file id of an open file.


call aread_state_restart(model_time,model_state,funit [target_time])
 type(time_type), intent(out)           :: model_time
 real(r8), dimension(:), intent(out)    :: model_state
 integer, intent(in)                    :: funit
 type(time_type), optional, intent(out) :: target_time
 

Description

Reads a model time and state, and optionally a prepended target time, from a state restart file.

model_time    Returned time of model state
model_state    Returned model state.
funit    Channel open for reading a state restart file.
target_time    If present, this time is read from the front of the restart file.


var = aget_closest_state_time_to (model_time, time)
 type(time_type)             :: aget_closest_state_time_to
 type(time_type), intent(in) :: model_time
 type(time_type), intent(in) :: time
 

Description

Computes the closest time to which a model can advance given the current model time and a target time. If the target time is earlier than the model time, the model time is returned (new feature in post Hawaii releases).

aget_closest_state_time_to    The closest model accessible time to time.
model_time    The current time of the model state.
time    The time we want to get close to.


call aoutput_diagnostics(ncFileID,model_time,model_state,copy_index)
 type(netcdf_file_type), intent(inout) :: ncFileID
 type(time_type), intent(in)           :: model_time
 real(r8), dimension(:), intent(in)    :: model_state
 integer, optional, intent(in)         :: copy_index
 

Description

Write a state vector to a state diagnostics netcdf file.

ncFileID    Unit for a state vector netcdf file open for output.
model_time    The time of the state to be output
model_state    A model state vector to be output.
copy_index    Which copy of state vector is to be written, default is copy 1


call awrite_state_restart(model_time,model_state,funit [,target_time])
 type(time_type), intent(in)           :: model_time
 real(r8), dimension(:), intent(in)    :: model_state
 integer, intent(in)                   :: funit
 type(time_type), optional, intent(in) :: target_time
 

Description

Writes a model time and state vector to a restart file and optionally prepends a target time.

model_time    Time of model state.
model_state    Model state vector.
funit    Channel of file open for restart output.
target_time    If present, time to be prepended to state time / vector.


call pert_model_state()
 

Description

Passes through to pert_model_state in model_mod. See model_mod documentation for arguments and details.



var = nc_append_time(ncFileID,time)
 integer                               :: nc_append_time
 type(netcdf_file_type), intent(inout) :: ncFileID
 type(time_type), intent(in)           :: time
 

Description

Appends the time to the time coordinate variable of the netcdf file. The new lenght of the time variable is returned. Requires that time is a coordinate variable AND it is the unlimited dimension.

nc_append_time    Returns new length of time variable.
ncFileID    Points to open netcdf file.
time    The next time to be added to the file.


var = nc_write_calendar_atts(ncFileID,TimeVarID)
 integer                            :: nc_write_calendar_atts
 type(netcdf_file_type), intent(in) :: ncFileID
 integer, intent(in)                :: TimeVarID
 

Description

Sets up the metadata for the appropriate calendar being used in the time manager an writes it to a netcdf file.

nc_write_calendar_atts    Returns a netcdf error code.
ncFileID    Netcdf file id pointing to a file open for writing.
TimeVarID    The index of the time variable in the netcdf file.


var = nc_get_tindex(ncFileID,statetime)
 integer                               :: nc_get_tindex
 type(netcdf_file_type), intent(inout) :: ncFileID
 type(time_type), intent(in)           :: statetime
 

Description

Returns the index of a time from the time variable in a netcdf file. This function has been replaced with more efficient approaches and may be deleted from future releases.

nc_get_tindex    The index of the time in the netcdf file.
ncFileID    File id for an open netcdf file.
statetime    The time to be found in the netcdf file.


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

Description

This passes through to model_mod. See model_mod documentation for arguments and details.

get_model_time_step    Returns time step of model.


var = open_restart_read(file_name)
 integer                      :: open_restart_read
 character(len=*), intent(in) :: file_name
 

Description

Opens a restart file for readig.

open_restart_read    Returns a file descriptor (channel number).
file_name    Name of restart file to be open for reading.


var = open_restart_write(file_name)
 integer                      :: open_restart_write
 character(len=*), intent(in) :: file_name
 

Description

Open a restart file for writing.

open_restart_write    Returns a file descriptor (channel) for a restart file.
file_name    File name of restart file to be opened.


call close_restart(file_unit)
 integer, intent(in) :: file_unit
 

Description

Closes a restart file.

file_unit    File descriptor (channel number) of open restart file.


call adv_1step()
 

Description

Advances a model by one step. Pass through to model_mod. See model_mod documentation for arguments and details.



call get_initial_condition(x)
 type(assim_model_type), intent(out) :: x
 

Description

Obtains an initial condition from models that support this option.

x    assim_model into which an initial model state can be written.




NAMELIST

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

namelist / assim_model_nml /  &
    write_binary_restart_files

Discussion

This namelist is read in a file called input.nml

Contents Type Description
write_binary_restart_files logical Are output state restart files ascii (false) or unformatted (true)? Default is true.



FILES




REFERENCES


ERROR CODES and CONDITIONS

-->
RoutineMessageComment
init_diag_output Compiler does not support required kinds of variables. NetCDF-f90 interface function byteSizeOK returned FALSE
init_diag_output and various nc_XXX various NetCDF-f90 messages Returned by one of the NetCDF calls in this subroutine. Consult the NetCDF manual.
get_diag_input_copy_meta_data expected to read "locat" got ... The header of the metadata for the copies of the data in diagnostic input file is not = 'locat'
set_model_state_vector state vector has length # model size (#) does not match. Check your model resolution and fields included in the state vector.
aread_state_restart read error is : # Unable to read model state from assim_model_state_ic# file. # is error condition retured by read statement.
open_restart_read OPEN status was # Failed to open file listed for reason #.
aoutput_diagnostics model time (d,s) (#,#) is index # in ncFileID # Time index for file listed is < 0
ainput_diagnostics expected "copy", got _____' Trying to read diagnostic state output header.
nc_append_time "time" expected to be rank-1 ndims /= 1
The time array of the NetCDF file should be 1-dimensional
nc_append_time unlimited dimension expected to be slowest-moving dimids(1) /= unlimitedDimID
nc_append_time time mirror and netcdf file time dimension out-of-sync lngth /= ncFileId%Ntimes
nc_append_time various NetCDF-f90 error messages Returned from one of the NetCDF calls in this subroutine. Consult the NetCDF manual.
nc_get_tindex trouble deep ... can go no farther. Stopping. timeindex < -1
nc_get_tindex Model time preceeds earliest netCDF time. Time of current assim_model is earlier than all the times on the NetCDF file to which the state is to be written by aoutput_diagnostics.
nc_get_tindex subsequent netCDF time (days, seconds) # # Time of current assim_model is in the midst of the times on the NetCDF file to which the state is to be written by aoutput_diagnostics, but doesn't match any of them. Very bad.
nc_get_tindex various NetCDF-f90 error messages Returned from one of the NetCDF calls in this subroutine. Consult the NetCDF manual.
nc_write_calendar_atts various NetCDF-f90 error messages Returned from one of the NetCDF calls in this subroutine. Consult the NetCDF manual.



KNOWN BUGS




FUTURE PLANS




PRIVATE COMPONENTS