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 |
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.
types_mod location_mod time_manager_mod utilities_mod model_mod
Optional namelist interface &assim_model_nml may be read from file input.nml.
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_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
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. |
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.
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
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. |
integer :: var
Returns the size of the model state vector. This is a direct pass through to the model_mod.
type(assim_model_type), intent(in) :: assim_model type(time_type), intent(in) :: time type(time_type) :: get_closest_state_time_to
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. |
type(assim_model_type), intent(inout) :: x
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 |
SEE model_mod for arguments and description.
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
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 | < /TR>
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 |
integer :: get_num_close_states type(location_type), intent(in) :: location real(r8), intent(in) :: radius real(r8), dimension(:), intent(in) :: x
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 |
type(assim_model_type), intent(in) :: get_model_time type(time_type) :: assim_model
Returns time from an assim_model type.
get_model_time | Time from assim_model |
assim_model | Assim_model type from which to extract time |
real(r8), dimension(model_size) :: get_model_state_vector type(assim_model_type), intent(in) :: assim_model
Returns the state vector component from an assim_model_type.
get_model_state_vector | Returned state vector |
assim_model | Input assim_model_type |
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 | Copy |
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
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. |
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 |
type(assim_model_type), intent(inout) :: assim_model real(r8), dimension(:), intent(in) :: state
Set the state in an assim_model_type.
assim_model | Set the state vector part of this. |
state | The state vector to be inserted. |
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. |
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. |
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 netCDFF file |
state | State vector and time |
copy_index | Which copy of state is to be output |
Called to clean-up at end of assim_model use. For now just passes through to model_mod.
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.< /TD> |
state | Assim_model_type to read in data. |
copy_index | Which copy of state to be read. |
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.
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 TD> | Number of copies of the state vector at each time. |
type(assim_model_type), intent(inout) :: state
Creates storage for an assim_model_type.
state | An assim_model_type that needs storage created. |
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
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 |
real(r8), pointer, dimension(:) :: get_state_vector_ptr type(assim_model_type), intent(in) :: assim_model
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. |
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.
finalize_diag_output | Returns an error value. |
ncFileID | Netcdf file id of an open file. |
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
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. |
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.
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. |
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
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 |
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
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. |
Passes through to pert_model_state in model_mod. See model_mod documentation for arguments and details.
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 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. |
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.
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. |
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.
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. |
type(time_type) :: get_model_time_step
This passes through to model_mod. See model_mod documentation for arguments and details.
get_model_time_step | Returns time step of model. |
integer :: open_restart_read character(len=*), intent(in) :: file_name
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. |
integer :: open_restart_write character(len=*), intent(in) :: file_name
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. |
integer, intent(in) :: file_unit
Closes a restart file.
file_unit | File descriptor (channel number) of open restart file. |
Advances a model by one step. Pass through to model_mod. See model_mod documentation for arguments and details.
type(assim_model_type), intent(inout) :: x
Obtains an initial condition from models that support this option.
x | assim_model into which an initial model state can be written. |
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
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. |
Routine | Message | Comment |
---|---|---|
xxxx | size of [argument] is incorrect | The size of [argument] must be 1 and 4 |
xxxx | yyyyy | bad judgement What were you thinking? |
type location_type private real(r8) :: x end type location_type