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

MODULE ensemble_manager_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.7 $
Release Name: $Name: $
Change Date: $Date: 2006/09/11 14:35:32 $
Change history: see CVS log

OVERVIEW

Manages storage and a number of operations for multiple copies of a vector. The most obvious use is to manage ensembles of model state vectors. In this case, the number of copies stored for each state vector element is the ensemble size plus one or more additional copies like the mean, variance, associated inflation values, etc. The ensemble_manager provides routines to compute the mean and variance of a subset of the copies, to track the time associated with the copies, and to write and read restart files. Most importantly, it provides a capability to do transposes between two storage representations of an ensemble. In one representation, each process stores all copies of a subset of the state variables while in the other, each process stores all of the state variables for a subset of copies. The ensemble manager is also used to manage ensembles of observation priors and quality control and ensembles of forward observation operator error status.




OTHER MODULES USED

types_mod
utilities_mod
assim_model_mod
time_manager_mod
random_seq_mod
mpi_utilities_mod



PUBLIC INTERFACE

use ensemble_manager_mod, only : ensemble_type
 init_ensemble_manager
 end_ensemble_manager
 get_ensemble_time
 duplicate_ens
 get_var_owner_index
 get_my_num_copies
 get_my_copies
 get_my_num_vars
 get_my_vars
 compute_copy_mean
 compute_copy_mean_sd
 compute_copy_mean_var
 get_copy
 put_copy
 all_vars_to_all_copies
 all_copies_to_all_vars
 read_ensemble_restart
 write_ensemble_restart

NOTES

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




PUBLIC COMPONENTS




type ensemble_type
   !!! private
   integer :: num_copies
   integer :: num_vars
   integer :: my_num_copies
   integer :: my_num_vars
   integer, pointer :: my_copies(:)
   integer, pointer :: my_vars(:)
   real(r8), pointer :: copies(:, :)
   real(r8), pointer :: vars(:, :)
   type(time_type), pointer :: time(:)
   integer :: distribution_type
end type ensemble_type

Description

Provides a handle for an ensemble that manages copies of a vector. For efficiency, the type internals are not private and direct access to the storage arrays is used throughout DART.

Component Description
num_copies Global number of copies of the vector.
num_vars Global number of elements (variables) in the vector.
my_num_copies Number of copies stored by this process.
my_num_vars Number of variables stored by this process.
my_copies Dimensioned to size my_num_copies. Contains a list of the global indices of copies stored by this process.
my_vars Dimensioned to size my_num_vars. Contains a list of the global indices of variables stored by this process.
copies Dimensioned (num_copies, my_num_vars). Storage for all copies of variables stored by this process.
vars Dimensioned (num_vars, my_num_copies). Storage for all variables of copies stored by this process.
time Dimensioned my_num_copies. A time_type that stores time associated with a given copy of the vector.
distribution_type Does nothing at present. Can be used for future releases to control the layout of different copies and variables in storage.


call init_ensemble_manager(ens_handle,num_copies,num_vars,distr ibution_type_in)
 type(ensemble_type), intent(out) :: ens_handle
 integer, intent(in)              :: num_copies
 integer, intent(in)              :: num_vars
 integer, optional, intent(in)    :: distribution_type_in
 

Description

Initializes an instance of an ensemble. Storage is allocated and the size descriptions in the ensemble_type are initialized.

ens_handle    Handle for the ensemble being initialized
num_copies    Number of copies of vector.
num_vars    Number of variables in the vector.
distribution_type_in    Controls layout of storage on pe's. Currently only option 1 is supported.


call get_var_owner_index(var_number,owner,owners_index)
 integer, intent(in)  :: var_number
 integer, intent(out) :: owner
 integer, intent(out) :: owners_index
 

Description

Given the global index of a variable in the vector, returns the process that stores this variable when all copies of a subset of variables are stored and the local storage index for this variable on that process.

var_number    Global index of a variable in the vector from an ensemble.
owner    Process (0 to num_processes) that stores this variable when each has all copies of subset of variables.
owners_index    Local storage index for this variable on the owning process.


call duplicate_ens(ens1,ens2,duplicate_time)
 type(ensemble_type), intent(in)    :: ens1
 type(ensemble_type), intent(inout) :: ens2
 logical, intent(in)                :: duplicate_time
 

Description

Copies the contents of ens1 into ens2. If the num_copies and num_vars are not consistent or if the distribution_type is not consistent, fails with an error. If duplicate_time is true, the times from ens1 are copied over the times of ens2.

ens1    Ensemble handle of ensemble to be copies into ens2.
ens2    Ensemble handle of ensemble into which ens1 is copied.
duplicate_time    If true, copy the times from ens1 into ens2, else leave ens2 times unchanged.


var = get_my_num_copies(ens_handle)
 integer, intent(out)            :: get_my_num_copies
 type(ensemble_type), intent(in) :: ens_handle
 

Description

Returns number of copies stored by this process when storing all variables for a subset of copies.

get_my_num_copies    Returns the number of copies stored by this process when storing all variables for a subset of copies.
ens_handle    Handle for an ensemble.


var = get_my_num_vars(ens_handle)
 integer, intent(out)            :: get_my_num_vars
 type(ensemble_type), intent(in) :: ens_handle
 

Description

Returns number of variables stored by this process when storing all copies of a subset of variables.

get_my_num_vars    Returns the number of vars stored by this process when storing all copies of a subset of variables.
ens_handle    Handle for an ensemble.


call get_my_copies(ens_handle,copies)
 type(ensemble_type), intent(in) :: ens_handle
 integer, intent(out)            :: copies
 

Description

Returns a list of all copies stored on this process when storing subset of copies of all variables.

ens_handle    Handle for an ensemble.
copies    List of all copies stored by this process when storing subset of copies of all variables.


call get_my_vars(ens_handle,copies)
 type(ensemble_type), intent(in) :: ens_handle
 integer, intent(out)            :: vars
 

Description

Returns a list of all variables stored on this process when storing all copies of a subset of variables.

ens_handle    Handle for an ensemble.
vars    List of all variables stored on this process when storing all copies of a subset of variables.


call compute_copy_mean(ens_handle,start_copy,end_copy,mean_copy,sd_copy)
 type(ensemble_type), intent(inout) :: ens_handle
 integer, intent(in)                :: start_copy
 integer, intent(in)                :: end_copy
 integer, intent(in)                :: mean_copy
 

Description

Computes the mean of a contiguous subset of copies starting with global index start_copy and ending with global index ens_copy. Mean is written to mean_copy.

ens_handle    Handle for an ensemble.
start_copy    Global index of first copy in mean and sd computation.
end_copy    Global index of last copy in mean and sd computation.
mean_copy    Global index of copy into which mean is written.


call compute_copy_mean_sd(ens_handle,start_copy,end_copy,mean_copy,sd_copy)
 type(ensemble_type), intent(inout) :: ens_handle
 integer, intent(in)                :: start_copy
 integer, intent(in)                :: end_copy
 integer, intent(in)                :: mean_copy
 integer, intent(in)                :: sd_copy
 

Description

Computes the mean and standard deviation of a contiguous subset of copies starting with global index start_copy and ending with global index ens_copy. Mean is written to mean_copy and standard deviation to sd_copy.

ens_handle    Handle for an ensemble.
start_copy    Global index of first copy in mean and sd computation.
end_copy    Global index of last copy in mean and sd computation.
mean_copy    Global index of copy into which mean is written.
sd_copy    Global index of copy into which standard deviation is written.


call compute_copy_mean_var(ens_handle,start_copy,end_copy,mean_copy,sd_copy)
 type(ensemble_type), intent(inout) :: ens_handle
 integer, intent(in)                :: start_copy
 integer, intent(in)                :: end_copy
 integer, intent(in)                :: mean_copy
 integer, intent(in)                :: var_copy
 

Description

Computes the mean and variance of a contiguous subset of copies starting with global index start_copy and ending with global index ens_copy. Mean is written to mean_copy and variance to var_copy.

ens_handle    Handle for an ensemble.
start_copy    Global index of first copy in mean and sd computation.
end_copy    Global index of last copy in mean and sd computation.
mean_copy    Global index of copy into which mean is written.
var_copy    Global index of copy into which variance is written.


call get_copy(receiving_pe,ens_handle,copy,vars,mtime)
 integer, intent(in)                    :: receiving_pe
 type(ensemble_type), intent(in)        :: ens_handle
 integer, intent(in)                    :: copy
 real(r8), dimension(:), intent(out)    :: vars
 type(time_type), optional, intent(out) :: mtime
 

Description

Retreives a copy of the state vector, indexed by the global index copy. The process that is to receive the copy is receiving_pe and the copy is returned in the one dimensional array vars. The time of the copy is also returned if mtime is present. This is generally used for operations, like IO, that require a single processor to do things with the entire state vector.

receiving_pe    This process ends up with the requested copy of the state vector.
ens_handle    Handle for ensemble.
copy    The global index of the copy of the state vector that is to be retreived.
vars    One dimensional array in which the requested copy of the state vector is returned.
mtime    If present returns the time of the requested copy.


call put_copy(sending_pe,ens_handle,copy,vars,mtime)
 integer, intent(in)                    :: sending_pe
 type(ensemble_type), intent(inout)     :: ens_handle
 integer, intent(in)                    :: copy
 real(r8), dimension(:), intent(in)     :: vars
 type(time_type), optional, intent(in)  :: mtime
 

Description

Sends a copy of the state vector, indexed by the global index copy, from a given process to the process that stores it. The process that is to send the copy is sending_pe which places the copy in the one dimensional array vars. The time of the copy is also sent if mtime is present. This is generally used for operations, like IO, that require a single processor to do things with the entire state vector. For instance, if a single process reads in a state vector, it can be shipped to the storing process by this subroutine.

sending_pe    This process sends the copy of the state vector.
ens_handle    Handle for ensemble.
copy    The global index of the copy of the state vector that is to be sent.
vars    One dimensional array in which the requested copy of the state vector is placed.
mtime    If present send the time of the copy.


call all_vars_to_all_copies(ens_handle)
 type(ensemble_type), intent(inout) :: ens_handle
 

Description

Transposes data from a representation in which each processor has a subset of copies of all variables to one in which each has all copies of a subset of variables. In the current implementation, storage is not released so both representations are always available. However, one representation may be current while the other is out of date.

ens_handle    The handle of the ensemble being transposed.


call all_copies_to_all_vars(ens_handle)
 type(ensemble_type), intent(inout) :: ens_handle
 

Description

Transposes data from a representation in which each processor has all copies of a subset of variables to one in which each has a subset of copies of all variables. In the current implementation, storage is not released so both representations are always available. However, one representation may be current while the other is out of date.

ens_handle    The handle of the ensemble being transposed.


call read_ensemble_restart(ens_handle,start_copy,end_copy,start _from_restart,file_name,init_time,force_single_file)
 type(ensemble_type), intent(inout)    :: ens_handle
 integer, intent(in)                   :: start_copy
 integer, intent(in)                   :: end_copy
 logical, intent(in)                   :: start_from_restart
 character(len=*), intent(in)          :: file_name
 type(time_type), optional, intent(in) :: init_time
 logical, optional, intent(in)         :: force_single_file
 

Description

Read in a set of copies of a vector from file file_name. The copies read are place into global copies start_copy:end_copy in the ens_handle. All reads are done by process 0 in the current version and then shipped to the pe that stores the copies when each process stores all variables of a subset of copies. If start_from_restart is false, then only a single copy of the vector is read from the file and then it is perturbed using routines in assim_model_mod to generate the required number of copies. The read can be from a single file that contains all needed copies or from a different file for each copy. This choice is controlled by the namelist entry single_restart_file_in. However, the optional argument force_single_file forces the read to be from a single file if it is present and true. This is used for ensembles that contain the inflation values for state space inflation. If multiple files are to be read, the file names are generated by appending integers to the input file_name.

ens_handle    Handle of ensemble.
start_copy    Global index of first of continguous set of copies to be read.
end_copy    Global index of last of contiguous set of copies to be read, copies(start_copy:end_copy).
start_from_restart    If true, read all copies from file. If false, read one copy and perturb to get required number.
file_name    Name of file from which to read.
init_time    If present, set time of all copies read to this value.
force_single_file    If present and true, force the read to be from a single file which contains all copies.


call write_ensemble_restart(ens_handle,file_name,start_copy,end_copy, force_single_file)
 type(ensemble_type), intent(inout)    :: ens_handle
 character(len=*), intent(in)          :: file_name
 integer, intent(in)                   :: start_copy
 integer, intent(in)                   :: end_copy
 logical, optional, intent(in)         :: force_single_file
 

Description

Writes a set of copies of a vector to file file_name. The copies written are from global copies start_copy:end_copy in the ens_handle. The write can be to a single file or to a different file for each copy. This choice is controlled by the namelist entry single_restart_file_out. However, the optional argument force_single_file forces the write to be to a single file if it is present and true. This is used for ensembles that contain the inflation values for state space inflation. If multiple files are to be written, the file names are generated by appending integers to the input file_name.

ens_handle    Handle of ensemble.
file_name    Name of file from which to read.
start_copy    Global index of first of continguous set of copies to be written.
end_copy    Global index of last of contiguous set of copies to be written, copies(start_copy:end_copy).
force_single_file    If present and true, force the write to be to a single file which contains all copies.


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

Description

Frees up storage associated with an ensemble.

ens_handle    Identifies ensemble




We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

 namelist / ensemble_manager_nml / 
 single_restart_file_in,single_restart_file_out,perturbation_amplitude



 

Discussion

This namelist is read in a file called input.nml

Contents Type Description
single_restart_file_in logical True if all copies read from a single file. False for one file per copy. Default: .true.
single_restart_file_out logical True if all copies written to a single file. False for one file per copy. Default: .true.
perturbation_amplitude real(r8) Perturbation standard deviation for generating ensemble members if assim_model_mod will not do it. Default: 0.2_r8




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
init_ensemble_manager only distribution type 1 is implemented For now, can't request option other than 1 for layout
read_ensemble_restart start_from_restart in filter_nml and single_restart_file_in in ensemble_manager_nml cannot both be false Doesn't make sense to specify both of these options.
get_copy Requested copy is > maximum_copy Can't ask for a copy that is greater than the maximum.
get_copy Size of vars ### Must be at least ### The vars array is not big enough to hold the returned copy of the vector.
put_copy Requested copy: ### is > maximum_copy: ### Can't ask for a copy that is greater than maximum.
put_copy Size of vars: ### Must be at least ### The vars array is not big enough to hold the state vector.
get_ensemble_time indx ### cannot exceed ### The index of the requested copy must be no greater than the maximum number of copies.
duplicate_ens num_copies ### and ### must be equal Number of copies in ensembles being copied must be the same.
duplicate_ens num_vars ### and ### must be equal Number of variables in ensembles being copied must be the same.
duplicate_ens distribution_type ### and ### must be equal. Distribution types of ensembles being copies must be the same.
get_my_copies Array copies only has size ### but must be at least ### The copies array must be large enough to hold all copies of the state vector.
get_my_vars Array vars only has size ### but must be at least ### The vars array must be large enough to hold all variables of the state vector.



KNOWN BUGS




Additional options for the layout of ensemble storage may lead to improved performance for different problem sizes on different architectures.


FUTURE PLANS




PRIVATE COMPONENTS

Discussion