Contact: | Jeff Anderson |
Reviewers: | |
Revision: | $Revision: 1.5 $ |
Release Name: | $Name: pre_iceland $ |
Change Date: | $Date: 2005/06/08 17:08:09 $ |
Change history: | see CVS log |
Module that manages storage and a number of basic operations for ensembles of DART model state vectors. Provides options to minimize storage by keeping most copies of the ensemble on disk. Allows access to subsets of ensembles. Computes ensemble mean and spread and allows ensembles to be advanced in time by the model.
types_mod utilities_mod assim_model_mod time_manager_mod
Optional namelist interface &ensemble_manager_nml may be read from file input.nml.
type ensemble_type private logical :: null_variable end type ensemble_type
The H-release implementation of the ensemble manager only allows for a single ensemble to be in use at any time. However, it is likely that future versions may wish to manage more than one ensemble at a time, for instance ensembles for two coupled but independently assimilating models. The ensemble_type would provide a 'handle' that would allow more than one ensemble to be in use at given time. At present, this type does nothing but must be passed as an argument to the ensemble manager calls.
Component | Description |
---|---|
null_variable | does nothing at present. |
type(ensemble_type), intent(out) :: ens_handle integer, intent(in) :: ens_size_in integer, intent(in) :: model_size_in character(len=129), optional, intent(in) :: file_name type(time_type), optional, intent(in) :: init_time
Initializes an instance of an ensemble. The returned ensemble_type is used to allow access to this ensemble. The ens_size and model_size are specified. Storage is allocated as required for either in-core or out-of-core implementation of an ensemble. If the file_name argument is present, the values of the ensemble are read from this file. If the init_time argument is present, the time in the file is replaced with this time.
ens_handle | Identifies ensemble: provides future capability to manager multiple ensembles |
ens_size_in | Number of ensemble members |
model_size_in | Size of model state vector |
file_name | If present, read in ensemble from this file |
init_time | If present, set initial ensemble time to this value |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: index real(r8), dimension(:), intent(out) :: member type(time_type), intent(out) :: mtime
Returns the values and time of the given ensemble member. If index is between 1 and the ensemble size, returns the corresponding ensemble member. If index is 0 returns the ensemble mean; if index is -1 returns the ensemble spread. The mean and spread are NOT updated if retrieved; this must be done separately.
ens_handle | Identifies ensemble. |
index | Index of ensemble member to be returned. 0=mean, -1=spread. |
member | Returned value of the ensemble member (model_size) |
mtime | Returned time of ensemble member |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: index real(r8), dimension(:), intent(in) :: member type(time_type), intent(in) :: mtime
Sets the values and time of an ensemble member. If index is between 1 and the ensemble size, sets the corresponding ensemble member. If index is 0 sets the ensemble mean; if index is -1 sets the ensemble spread.
ens_handle | Identifies ensemble |
index | Which ensemble member should be set. 0=mean, -1=spread |
member | Input values to which ensemble member should be set |
mtime | Time to set for ensemble member |
type(ensemble_type), intent(in) :: ens_handle
Updates the ensemble mean for the ensemble using the current values of the members.
ens_handle | Identifies ensemble |
type(ensemble_type), intent(in) :: ens_handle
Updates the ensemble mean and spread using the current values of the members.
ens_handle | Identifies ensemble |
type(ensemble_type), intent(in) :: ens_handle character(len=129), optional, intent(in) :: file_name
Frees up storage associated with an ensemble and writes a restart file if requested by the presence of a file name.
ens_handle | Identifies ensemble |
file_name | Name of restart file to be written if present |
type(ensemble_type), intent(in) :: ens_handle real(r8), dimension(:, :), intent(out) :: region type(time_type), dimension(:), intent(out) :: rtime integer, optional, dimension(:), intent(in) :: state_vars_in integer, optional, dimension(:), intent(in) :: ens_members_in
Returns a subset of the state variables for a subset of the ensemble members. The state variables to be returned are identified by the integer values in argument state_vars_in. If state_vars_in is not present, all state variables are returned. The ensemble members to be returned are identified by the integers in ens_members_in. If ens_members_in is not present, all ensemble members (but not the mean or spread) are returned. The mean and spread can be returned by including indices 0 or 1 in the ens_members_in list. The returned data is in the (ens, state) array region. There is no check to make sure that region is sufficiently large.
ens_handle | Identifies ensemble |
region | Returned (ens_members, state_var_members) array of values |
rtime | Time of the returned ensemble members |
state_vars_in | Indices of the state variables to be returned |
ens_members_in | Indices of the ensemble members to be returned |
type(ensemble_type), intent(in) :: ens_handle real(r8), dimension(:, :), intent(in) :: region type(time_type), dimension(:), intent(in) :: rtime integer, optional, dimension(:), intent(in) :: state_vars_in integer, optional, dimension(:), intent(in) :: ens_members_in
Sets a subset of the state variables for a subset of the ensemble members. The state variables to be set are identified by the integer values in argument state_vars_in. If state_vars_in is not present, all state variables are set. The ensemble members to be set are identified by the integers in ens_members_in. If ens_members_in is not present, all ensemble members (but not the mean or spread) are set. The mean and spread can be set by including indices 0 or 1 in the ens_members_in list. The input data is in the (ens, state) array region. There is no check to make sure that region is of proper size.
ens_handle | Identifies ensemble |
region | Input (ens_members, state_var_members) array of values |
rtime | Time of the input ensemble members |
state_vars_in | Indices of the state variables to be set |
ens_members_in | Indices of the ensemble members to be set |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: index type(time_type), intent(out) :: mtime
Returns the time for the ensemble member index. If index=0 returns time of mean; if index = -1 returns time of spread.
ens_handle | Identifies ensemble |
index | Which ensemble member |
mtime | Returned time for this ensemble member |
type(ensemble_type), intent(in) :: ens_handle type(time_type), intent(in) :: target_time integer, intent(in) :: asynch character(len=129), intent(in) :: adv_ens_command
Uses model to advance all ensemble members to the target time. The method for advancing is controlled by the asynch flag and by the adv_ens_command (for certain asynch options). Details can be found in general documentation, in the model_mod template documentation, and in the documentation of the advance_ens.csh and filter_server.csh scripts.
ens_handle | Identifies ensemble |
target_time | Time to which model should be advanced |
asynch | Controls whether model is advanced by this executable or through shell |
adv_ens_command | Command to be used if shell is used for advance |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: rnum integer, intent(in) :: rsize real(r8), dimension(ens_size, rsize), intent(out) :: region integer, dimension(rsize), intent(in) :: region_id
Returns all ensemble members of a particular subset of the state variables. If the ensemble is being stored in core, the integer array region_id contains the state vector index of all state variables to be returned. If the ensemble is not being stored in core, it is assumed that the ensemble has been transposed to files that contain all ensemble members for each region (a call to transpose_ens_to_regions has been made). In this case, all ensemble members of the region indexed by rnum are returned.
ens_handle | Identifies an ensemble, not in use. |
rnum | Number of the region to be retrieved. |
rsize | Size of the region to be retrieved. |
region | Returns the values of all ensemble members of state variables in a region. |
region_id | Integer indices of state variables in region, only used if ensemble is in core. |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: rnum integer, intent(in) :: rsize real(r8), dimension(ens_size, rsize), intent(in) :: region integer, dimension(rsize), intent(in) :: region_id
Stores all ensemble members of a particular subset of the state variables. If the ensemble is being stored in core, the integer array region_id contains the state vector index of all state variables in the region. If the ensemble is not being stored in core, it is assumed that the ensemble has been transposed to files that contain all ensemble members for each region (a call to transpose_ens_to_regions has been made). In this case, all ensemble members of the region indexed by rnum are stored.
ens_handle | Identifies an ensemble, not in use. |
rnum | Number of the region to be stored. |
rsize | Size of the region to be stored. |
region | Stores all ensemble members of state variables in a region. |
region_id | Integer indices of state variables in region, only used if ensemble is in core. |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: num_regions integer, dimension(model_size), intent(in) :: region_id integer, dimension(num_regions), intent(in) :: region_size
Transposes ensembles that are not stored in core from a format in which each ensemble member is in one file to a format in which all ensemble members for each of a specified set of regions is in one file. The region in which each state variable is located is determined by the values in the array region_id.
ens_handle | Identifies an ensemble, not in use. |
num_regions | Number of regions. |
region_id | Identifies which region each state variable is in. |
region_size | Sizes of the regions. |
type(ensemble_type), intent(in) :: ens_handle integer, intent(in) :: num_regions integer, dimension(model_size), intent(in) :: region_id integer, dimension(num_regions), intent(in) :: region_size
Transposes ensembles that are not stored in core from a format in which all ensemble members for each of a specified set of regions are in one file to a format in which each ensemble member is in its own file. The region in which each state variable is located is determined by the values in the array region_id.
ens_handle | Identifies an ensemble, not in use. |
num_regions | Number of regions. |
region_id | Identifies which region each state variable is in. |
region_size | Sizes of the regions. |
Returns true if the ensemble is stored in core and false otherwise. Used to determine if it is okay to make direct access to the ensemble, ensemble mean, and ensemble spread for efficiency.
These three arrays are managed by the ensemble_manager. If the ensemble is being stored in core (in_core = .true.), then these arrays can be accessed directly to avoid the added overhead of a copy when they need to be used. This is purely for efficiency and is not a very safe programming practice.
We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.
namelist / ensemble_manager_nml / & in_core,single_restart_file_in,single_restart_file_out
Options control the memory useage and size of files used. The in_core option determines whether the entire ensemble should be stored in memory at all times or whether most members should reside on disk. The single_restart arguments select whether all ensemble members should get their own restart files or whether a single file should contain all ensemble members.
This namelist is read in a file called input.nml
Contents | Type | Description |
---|---|---|
in_core | logical | Keep whole ensemble in memory? Default: true |
single_restart_file_in | logical | Read all members from single file? Default: true |
single_restart_file_out | logical | Write all members to single file? Default: true |
Routine | Message | Comment |
---|---|---|
get_ensemble_member, put_ensemble_member, get_ensemble_time | index out of range | Ensemble index must be between -1 and ensemble size |
Aadvance_state | target time secs:days is before model_time secs:days | Don't know how to move model backwards |
Aadvance_state | Use less than 10000 model states | Code must be modified to do ensembles larger than 10000 |
Aadvance_state | input.nml - async is #, must be 0, 1, 2, or 3 | Other values of asynch not implemented |