MODULE assim_model_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: assim_model_mod.html 6380 2013-08-05 23:47:11Z nancy $

NAMELIST / INTERFACES / FILES / REFERENCES / ERRORS / PLANS / PRIVATE COMPONENTS / TERMS OF USE

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.

NOTES

A note about documentation style. Optional arguments are enclosed in brackets [like this].

[top]

NAMELIST

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.

&assim_model_nml
   write_binary_restart_files = .true.,
   netCDF_large_file_support  = .false.
  /


Item Type Description
write_binary_restart_files logical Write output state restart files in binary format (true) or ascii (false).
netCDF_large_file_support logical Use the netCDF Large File Support (LFS) format that enables individual records (i.e. all the information that has the same 'unlimited' record value) to exceed 2GB. The only downside to using this flag is compatibility with some netCDF software. Some (but not all) software is not built with 'LFS' support. Note it is, and has been, possible to create netCDF files larger than 2GB with a value of .false - which is compatible with the historical netCDF format. It is only necessary to use a value of .true. if the state vector is very large and you are outputting a large number of ensembles. Default is .false.


[top]

OTHER MODULES USED

types_mod
location_mod (model dependent choice)
time_manager_mod
utilities_mod
model_mod
netcdf
typeSizes (part of netcdf)
[top]

PUBLIC INTERFACES

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

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

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_s 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

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()

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. There are no arguments.



ncFileID = init_diag_output(FileName, global_meta_data, copies_of_field_per_time, meta_data_per_copy [, lagID])
type(netcdf_file_type)          :: init_diag_output 
character (len = *), intent(in) :: FileName 
character (len = *), intent(in) :: global_meta_data 
integer, intent(in)             :: copies_of_field_per_time 
character (len = *), intent(in) :: meta_data_per_copy(copies_of_field_per_time) 
integer, optional, intent(in)   :: lagID 

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

ncFileID Identifier for the netcdf file is returned. This is not an integer unit number, but a derived type containing additional information about the opened file.
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.
lagID If using the smoother, which lag number this output is for.


var = get_model_size()
integer :: get_model_size 

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

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).

var The closest time to which the model can be advanced is returned.
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.


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

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()

Pass through to model_mod. See model_mod documentation for arguments and description.



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

Returns time from an assim_model type.

var Returned time from assim_model
assim_model    Assim_model type from which to extract time


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

Returns the state vector component from an assim_model_type.

var 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

Copies one assim_model_type to another.

model_out    Copy.
model_in Data to be copied.


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

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

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), intent(in)                  :: state(:)

Set the state in an assim_model_type.

assim_model    Set the state vector in this assim_model_type.
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

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

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

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

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


call end_assim_model()

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

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

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

var 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

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), intent(out) :: location(model_size_out)
character(len = *)               :: meta_data_per_copy(num_copies)

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 = finalize_diag_output(ncFileID)
integer                               :: finalize_diag_output
type(netcdf_file_type), intent(inout) :: ncFileID

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

var 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),                  intent(out) :: model_state(:)
integer,                   intent(in)  :: funit
type(time_type), optional, intent(out) :: target_time

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

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).

var 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),               intent(in)    :: model_state(:)
integer, optional,      intent(in)    :: copy_index

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),                  intent(in) :: model_state(:)
integer,                   intent(in) :: funit
type(time_type), optional, intent(in) :: target_time

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()

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

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

var 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

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

var 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

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.

var 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

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

var    Returns time step of model.


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

Opens a restart file for readig.

var 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

Open a restart file for writing.

var 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

Closes a restart file.

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


call adv_1step()

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

Obtains an initial condition from models that support this option.

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


call ens_mean_for_model(ens_mean)
type(r8), intent(in) :: ens_mean(:)

An array of length model_size containing the ensemble means. This is a direct pass through to the model_mod.

ens_mean    Array of length model_size containing the mean for each entry in the state vector.


call get_close_maxdist_init(gc, maxdist)
type(get_close_type), intent(inout) :: gc
type(r8), intent(in)                :: maxdist

Sets the threshold distance. Anything closer than this is deemed to be close. This is a direct pass through to the model_mod, which in turn can pass through to the location_mod.

gc Data for efficiently finding close locations.
maxdist    Anything closer than this distance is a close location.


call get_close_obs(gc, base_obs_loc, base_obs_kind, obs, obs_kind, num_close, close_ind [, dist])
type(get_close_type), intent(in)  :: gc
type(location_type),  intent(in)  :: base_obs_loc
integer,              intent(in)  :: base_obs_kind
type(location_type),  intent(in)  :: obs(:)
integer,              intent(in)  :: obs_kind(:)
integer,              intent(out) :: num_close
integer,              intent(out) :: close_ind(:)
real(r8),  optional,  intent(out) :: dist(:)

Given a single location and a list of other locations, returns the indices of all the locations close to the single one along with the number of these and the distances for the close ones. The observation kinds are passed in to allow more sophisticated distance computations to be done if needed. This is a direct pass through to the model_mod, which in turn can pass through to the location_mod.

gc Data for efficiently finding close locations.
base_obs_loc Single given location.
base_obs_kind    Kind of the single location.
obs List of observations from which close ones are to be found.
obs_kind Kind associated with observations in obs list.
num_close Number of observations close to the given location.
close_ind Indices of those locations that are close.
dist Distance between given location and the close ones identified in close_ind.


call get_close_obs_init(gc, num, obs)
type(get_close_type), intent(inout) :: gc
integer,              intent(in)    :: num
type(location_type),  intent(in)    :: obs(:)

Initialize storage for efficient identification of locations close to a given location. Allocates storage for keeping track of which 'box' each observation in the list is in. This is a direct pass through to the model_mod, which in turn can pass through to the location_mod.

gc Data for efficiently finding close locations.
num The number of locations in the list.
obs    The location of each element in the list, not used in 1D implementation.

[top]

FILES

filename    purpose/comment
filter_restart specified in &filter_nml:restart_in_filename
filter_restart specified in &filter_nml:restart_out_filename
input.nml to read namelists
[top]

REFERENCES

[top]

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

none at this time

[top]

FUTURE PLANS

none at this time

[top]

PRIVATE COMPONENTS

N/A

[top]

Terms of Use

DART software - Copyright 2004 - 2013 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: DART core group
Revision: $Revision: 6380 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Lanai/assim_model/assim_model_mod.html $
Change Date: $Date: 2013-08-05 17:47:11 -0600 (Mon, 05 Aug 2013) $
Change history:  try "svn log" or "svn diff"