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

MODULE assim_model_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.4 $
Release Name: $Name: pre_hawaii $
Change Date: $Date: 2004/12/22 20:48:12 $
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 which is documented in detail in the DART views document.




OTHER MODULES USED

types_mod
location_mod
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)
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 
integer                                                               ::  ncFileID 

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                               :: var 

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(assim_model_type), intent(in)                ::  assim_model 
type(time_type), intent(in)                       ::  time
type(time_type)                                   ::  get_closest_state_time_to 

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?

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 get_initial_condition(x)
 type(assim_model_type), intent(inout) :: x
 

Description

Reads an initial time and state vector from a restart format file into an assim_model_type.

x    Contains time/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) < /em>
 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.

< /TR>
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 w as 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 en ough
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(assim_model_type), intent(in) :: get_model_time
 type(time_type)                    :: 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,cop ies_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_c opies,location,meta_data_per_copy)
 integer, intent(in)                                         :: f
 ile_id
 integer, intent(in)                                         :: m
 odel_size_out
 integer, intent(in)                                         :: n
 um_copies
 type(location_type), dimension(model_size_out), intent(out) :: l
 ocation
 character(len = *), dimension(num_copies)                   :: m
 eta_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_ti me)
 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.

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_i ndex)
 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    What's the time
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_t ime)
 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(inout) :: 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 /  &
    read_binary_restart_files, write_binary_restart_files

Discussion

This namelist is read in a file called input.nml

Contents Type Description
read_binary_restart_files logical Are input state restart files ascii (false) or unformatted (true)? Default is true. NOTE: when using parallel options to advance model states, temporary files are written out using the same interfaces. read and write options must be either both false or both true in this case.
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
xxxx size of [argument] is incorrect The size of [argument] must be 1 and 4
xxxx yyyyy bad judgement
What were you thinking?



KNOWN BUGS




FUTURE PLANS




PRIVATE COMPONENTS

type location_type
   private
   real(r8) :: x
end type location_type

Discussion