| Contact: | Jeff Anderson |
| Reviewers: | |
| Revision: | $Revision: 1.7 $ |
| Release Name: | $Name: HEAD $ |
| Change Date: | $Date: 2005/06/08 17:05:10 $ |
| 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.
types_mod location_mod (model dependent choice) 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.
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
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 :: get_model_size
Returns the size of the model state vector. This is a direct pass through to the model_mod.
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).
| 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(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 |
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 |
| 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 |
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(time_type) :: get_model_time type(assim_model_type), intent(in) :: 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 | 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) :: 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
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. 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. |
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 | 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 |
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(out) :: 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 |
|---|---|---|
| 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. |