10.8 Collected_Array Class

The Collected_Array Class is used to describe a collected array (existing across all the processors) in the CÆSAR Code Package. A Collected_Array is part of the overall data structure strategy in CÆSAR, which is made up of the following classes: Base_Structure, Data_Index, Assembled_Vector, Distributed_Vector, Overlapped_Vector, and Collected_Array. A description of the overall data structure strategy can be found in the Data_Structures Module.

The form of a Collected_Array object is given by:

  Array ( [dim1, [dim2, [dim3,]]] One_Axis [, Many_Axis] )

or

  Array ( dim_ragged_right, One_Axis [, Many_Axis] )
  --> not implemented

where One_Axis refers to the axis which is spread across the processors.

Collected_Array public procedures:

	Fundamental procedures
	Initialize		Initializes a Collected_Array object.
	Finalize		Finalizes a Collected_Array object.
	Valid_State		Returns false iff a Collected_Array object is in an invalid state.
	Initialized		Returns true iff a Collected_Array object has been initialized.
	Operations
	Collect		Collects the values from an Overlapped Vector and stores them in a Collected Array.
	Combine_with_Op		Combines the values from a Collected Array, to form a Distributed Vector. The resultant Distributed Vector is distributed according to the One Structure of the Collected Array. A combination operator, to be put in the place of ``Op'', must be specified. Allowed values for ``Op'' are: Average, MAX, MIN, or SUM. Combine_with_SUM also has an assignment interface.
	Gather		Does the communication necessary to set a Collected Array from a Distributed Vector (also has an assignment interface).
	Gather_and_Collect		Another name for Gather.
	Get_Values		Accesses the values from a Collected_Array object and returns them in a Bare Naked Array (also has an assignment interface).
	Many_Locus		Returns the Many Structure locus of the Collected_Array object.
	Name		Returns the name of the Collected_Array object.
	One_Locus		Returns the One Structure locus of the Collected_Array object.
	Output		Writes out the Collected_Array object.
	Set_Values		Sets the values of the Collected_Array object to a Bare Naked Array (also has an assignment interface).
	Set_Version		Sets the version number of the Collected_Array object (also has an assignment interface).
	Version		Returns the version number of the Collected_Array object.

Collected_Array public defined type:

	Collected_Array type
	A_Dimensionality		The actual number of dimensions that the ``array'' has, including the dimension that is spread over the processors (the One_Axis), and also including the Many_Axis, if it is present. ``Ragged_Right'' indices are signified by a Dimensionality of -1. (Ragged_Right is not yet implemented.)
	Dimensionality		The number of dimensions that the ``array'' has, including the dimension that is spread over the processors (the One_Axis), but not including the Many_Axis, if it is present. ``Ragged_Right'' indices are signified by a Dimensionality of -1. (Ragged_Right is not yet implemented.)
	Dimensions		The extents of the dimensions that the ``array'' has, including the dimensions for the One_Axis and the Many_Axis.
	Initialized		Initialization status.
	Many_of_One_Index		The Index that is used to translate between the Distributed Vectors.
	Many_Structure		Basic data structure which corresponds to the structure of the Distributed Vector that this Collected Array is based on.
	Name		The name for this variable (especially useful in a vector of Collected Arrays).
	One_Structure		Basic data structure which corresponds to the way that this Collected Array has been formed. If this Collected Array were to be combined, it would result in a Distributed Vector with a One_Structure basis.
	Values{n}		Values in the array, that are stored locally, with a different length on each PE. Values may have either 1, 2, 3, 4, or 5 dimensions (n = 1, 2, 3, 4, or 5), or be a ragged right array (n = RR). The last dimension is the dimension that is spread across the processors, if the Many_of_One_Index is a vector index. Otherwise, the penultimate axis will be spread across the processors. Only one of the variables will be allocated for a given object. Ragged right arrays have not been implemented yet.
	Version		Version number which is incremented every time the array is modified, or is synced with the version number of a data structure that it depends on when it is updated.

The Collected_Array Class code listing contains additional documentation. The Collected_Array Class also contains a Unit Test Program.