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 |
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.
types_mod utilities_mod assim_model_mod time_manager_mod random_seq_mod mpi_utilities_mod
Optional namelist interface &ensemble_manager_nml may be read from file input.nml.
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
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. |
type(ensemble_type), intent(out) :: ens_handle integer, intent(in) :: num_copies integer, intent(in) :: num_vars integer, optional, intent(in) :: distribution_type_in
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. |
integer, intent(in) :: var_number integer, intent(out) :: owner integer, intent(out) :: owners_index
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. |
type(ensemble_type), intent(in) :: ens1 type(ensemble_type), intent(inout) :: ens2 logical, intent(in) :: duplicate_time
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. |
integer, intent(out) :: get_my_num_copies type(ensemble_type), intent(in) :: ens_handle
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. |
integer, intent(out) :: get_my_num_vars type(ensemble_type), intent(in) :: ens_handle
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. |
type(ensemble_type), intent(in) :: ens_handle integer, intent(out) :: copies
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. |
type(ensemble_type), intent(in) :: ens_handle integer, intent(out) :: vars
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. |
type(ensemble_type), intent(inout) :: ens_handle integer, intent(in) :: start_copy integer, intent(in) :: end_copy integer, intent(in) :: mean_copy
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. |
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
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. |
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
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. |
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
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. |
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
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. |
type(ensemble_type), intent(inout) :: ens_handle
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. |
type(ensemble_type), intent(inout) :: ens_handle
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. |
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
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. |
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
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. |
type(ensemble_type), intent(in) :: ens_handle
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
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 |
Routine | Message | Comment |
---|---|---|
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. |