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

MODULE ensemble_manager_mod

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

OVERVIEW

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.




OTHER MODULES USED

types_mod
utilities_mod
assim_model_mod
time_manager_mod



PUBLIC INTERFACE

use ensemble_manager_mod, only : ensemble_type
 init_ensemble_manager
 get_ensemble_member
 put_ensemble_member
 update_ens_mean
 update_ens_mean_spread
 end_ensemble_manager
 get_ensemble_region
 put_ensemble_region
 get_ensemble_time
 Aadvance_state
 get_region_by_number
 put_region_by_number
 transpose_ens_to_regions
 transpose_regions_to_ens
 is_ens_in_core
 ens
 ens_mean
 ens_spread

NOTES

Optional namelist interface &ensemble_manager_nml may be read from file input.nml.




PUBLIC COMPONENTS




type ensemble_type
   private
   logical :: null_variable
end type ensemble_type

Description

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.


call init_ensemble_manager(ens_handle, ens_size_in, model_size_in [, file_name, init_time])
 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
 

Description

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


call get_ensemble_member(ens_handle, index, member, mtime)
 type(ensemble_type), intent(in)     :: ens_handle
 integer, intent(in)                 :: index
 real(r8), dimension(:), intent(out) :: member
 type(time_type), intent(out)        :: mtime
 

Description

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


call put_ensemble_member(ens_handle, index, member, mtime)
 type(ensemble_type), intent(in)    :: ens_handle
 integer, intent(in)                :: index
 real(r8), dimension(:), intent(in) :: member
 type(time_type), intent(in)        :: mtime
 

Description

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


call update_ens_mean(ens_handle)
 type(ensemble_type), intent(in) :: ens_handle
 

Description

Updates the ensemble mean for the ensemble using the current values of the members.

ens_handle    Identifies ensemble


call update_ens_mean_spread(ens_handle)
 type(ensemble_type), intent(in) :: ens_handle
 

Description

Updates the ensemble mean and spread using the current values of the members.

ens_handle    Identifies ensemble


call end_ensemble_manager(ens_handle [, file_name])
 type(ensemble_type), intent(in)          :: ens_handle
 character(len=129), optional, intent(in) :: file_name
 

Description

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


call get_ensemble_region(ens_handle,region,rtime, [, state_vars_in, ens_members_in])
 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
 

Description

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


call put_ensemble_region(ens_handle,region,rtime [, state_vars_in, ens_members_in])
 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
 

Description

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


call get_ensemble_time(ens_handle,index,mtime)
 type(ensemble_type), intent(in) :: ens_handle
 integer, intent(in)             :: index
 type(time_type), intent(out)    :: mtime
 

Description

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


call Aadvance_state(ens_handle, target_time, asynch, adv_ens_command)
 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
 

Description

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


call get_region_by_number(ens_handle, rnum, rsize, region, region_id)
 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
 

Description

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.


call put_region_by_number(ens_handle, rnum, rsize, region, region_id)
 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
 

Description

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.


call transpose_ens_to_regions(ens_handle, num_regions, region_id, region_size)
 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
 

Description

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.


call transpose_regions_to_ens(ens_handle, num_regions, region_id, region_size)
 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
 

Description

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.


var = is_ens_in_core()

Description

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.



real(r8), allocatable :: ens(:, :), ens_mean(:), ens_spread(:)

Description

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.





NAMELIST

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                         


 

Discussion

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




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
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



KNOWN BUGS




FUTURE PLANS




PRIVATE COMPONENTS

Discussion