parallel_arrays_gbl::p2d_array_obj Type Reference

This is an array object which is used to store the atomic and molecular integrals in memory. The primary data structure is the 2D array thisa(1:thisd1,1:thisd2). The object may use the auxiliary integer array thisblock_offset(1:thisno_blocks) as in the case of computation of the atomic integrals in the MPI regime. The use of the block_offset array is controled by the initialization routine init. Each column of thisa has a name which is contained in thiscolumn_descriptor(1:thisd2). The intention is that the different types of integrals (e.g. overlap, kinetic energy, etc.) are kept in different columns of the array thisa. More...

Public Member Functions
procedure	init (this, n, d2_end, no_blocks, column_descriptor, scratch_opt)
	Initializes the object. Arguments:
procedure	final (this)
	Deallocates all arrays and restores the object to an uninitialized state. It is a blocking routine.
procedure	set_block_offset (this, block_offset)
	If the array is initialized with no_blocks > 0 this routine can be used to copy the contents of an external integer array to the array thisblock_offset which must have the same size.
procedure	get_array_dim (this, d1, d2, no_blocks)
	Returns the values d1,d2,no_blocks.
procedure	sort_array_with_keys (this, n, d2, keys, sort_method)
	Sorts the array 'a' using keys given as an array of integers of the same dimension as 'a'. It is a non-blocking routine.
procedure	print (this, only_non_zero, out_unit)
	Prints out the non-zero contents of the array thisa (and thisblock_offset, if thisno_blocks > 0). It is a non-blocking routine. If optional integer parameter out_unit is present, the contents are written into that unit instead of level2.
procedure	write (this, lunit, record_start, position_after_write, rank)
	Writes to the disk the arrays thisa,thisblock_offset from the process specified. It is a blocking routine.
procedure	read (this, file_name, lunit, record_start, position_after_read)
	The arrays thisa,thisblock_offset are read-in from the disk by the master task and redistributed to other processes. If shared-memory MPI is used then each NODE keeps only one copy of the arrays thisa,thisblock_offset otherwise the array is kept by every MPI task. It is a blocking routine.
procedure	reduce_a_local (this)
	In-place reduction of the local arrays thisa on all processes using MPI_ALLREDUCE. It is a blocking routine.
procedure	reduce_a_to_master (this)
	Reduction of the local arrays thisa on all processes to the array kept by the master. It is a blocking routine.
procedure	merge_indexed_array_from_all_tasks (this, sendcount, d2, split_within_block)
	Merges (gathers) indexed arrays with equal number of blocks from all tasks into a single indexed array on each task. The same array this % a is used for sends and receives: this assumes that the block of data of size sendcount sent by the process with rank j is located in the (j+1)st block of this % a. We assume that the block_offsets supplied on input by the process j have been adjusted before to point to the rank j's data in the merged array this % a. I.e. this routine doesn't perform any shifts of the pointers to the data in this % a.
procedure	have_offsets (this)
	Logical function: does the object contain the array thisblock_offset? It is a non-blocking routine.
procedure	find_column_matching_name (this, column_name)
	Returns the column index in the array thisa corresponding to the name of the column specified on input.
procedure	get_column_descriptor (this, column_descriptor)
	Returns the character array column_descriptor.
procedure	combine_columns (this, col1, op, col2, col3)
	Combines two columns of thisa into a third one using a given operation: '+','-','*','/'.
procedure	multiply_column (this, col, fac)
	Multiplies a given column of thisa by a real number.

Public Attributes
real(kind=cfp), dimension(:,:), pointer	a => null()
	Local portion of the global array 'a': a_loc(my_start:my_end,1:d2). In the local mode my_start = 1 on all processes. The array can be shared on a single node in order to reduce memory usage in MPI-Scatci (Ahmed's implementation).
integer, dimension(:), allocatable	block_offset
	Pointers to start of blocks of data within the array 'a'. block_offset has dimension no_blocks.

Detailed Description

This is an array object which is used to store the atomic and molecular integrals in memory. The primary data structure is the 2D array thisa(1:thisd1,1:thisd2). The object may use the auxiliary integer array thisblock_offset(1:thisno_blocks) as in the case of computation of the atomic integrals in the MPI regime. The use of the block_offset array is controled by the initialization routine init. Each column of thisa has a name which is contained in thiscolumn_descriptor(1:thisd2). The intention is that the different types of integrals (e.g. overlap, kinetic energy, etc.) are kept in different columns of the array thisa.

There are multiple possible locations where the main two-dimensional data array is stored, which are governed by features enabled during compilation of the library and by arguments passed to the init routine:

1. If a non-empty argument scratch is given in the call to init and mapping is enabled by file_mapping_gbl::map, the data array will be stored on disk and accessed by file memory mapping. Upon destruction of this object, the file will be deleted.
2. Otherwise, if MPI-3 shared memory is enabled via mpi_gbl::shared_enabled, the array will be allocated only once per node. In this case it is the caller's responsibility to assure that all processes on a node expect the same layout of the memory.
3. If neither of the above holds, the array is allocated by each process as specified by the dimensions in the call.

Alternatively, the routine init can be skipped and the reading routine read called directly. Then the data will be either mapped to memory (if map is enabled; this time no scratch is needed), or shared on a node (if shared_enabled is on), or simply duplicated on each process. There is no parallel distribution of data on reading.

Member Function/Subroutine Documentation

combine_columns()

procedure parallel_arrays_gbl::p2d_array_obj::combine_columns	(	class(p2d_array_obj)	this,
		integer, intent(in)	col1,
		character(len=1), intent(in)	op,
		integer, intent(in)	col2,
		integer, intent(in)	col3 )

Combines two columns of thisa into a third one using a given operation: '+','-','*','/'.

final()

procedure parallel_arrays_gbl::p2d_array_obj::final

(

class(p2d_array_obj)

this

)

Deallocates all arrays and restores the object to an uninitialized state. It is a blocking routine.

find_column_matching_name()

procedure parallel_arrays_gbl::p2d_array_obj::find_column_matching_name	(	class(p2d_array_obj)	this,
		character(len=*), intent(in)	column_name )

Returns the column index in the array thisa corresponding to the name of the column specified on input.

get_array_dim()

procedure parallel_arrays_gbl::p2d_array_obj::get_array_dim	(	class(p2d_array_obj)	this,
		integer, intent(out)	d1,
		integer, intent(out)	d2,
		integer, intent(out)	no_blocks )

Returns the values d1,d2,no_blocks.

get_column_descriptor()

procedure parallel_arrays_gbl::p2d_array_obj::get_column_descriptor	(	class(p2d_array_obj)	this,
		character(len=line_len), dimension(:), allocatable	column_descriptor )

Returns the character array column_descriptor.

have_offsets()

procedure parallel_arrays_gbl::p2d_array_obj::have_offsets

(

class(p2d_array_obj)

this

)

Logical function: does the object contain the array thisblock_offset? It is a non-blocking routine.

init()

procedure parallel_arrays_gbl::p2d_array_obj::init	(	class(p2d_array_obj)	this,
		integer, intent(in)	n,
		integer, intent(in)	d2_end,
		integer, intent(in)	no_blocks,
		character(len=line_len), dimension(:), intent(in)	column_descriptor,
		character(len=*), intent(in), optional	scratch_opt )

Initializes the object. Arguments:

Parameters

[in]	n	n is integer: number of rows of thisa
[in]	d2_end	d2_end is integer: the number of columns of thisa
[in]	no_blocks	no_blocks is integer: number of elements of thisblock_offset
[in]	column_descriptor	column_descriptor is a character array of dimension d2_end: contains descriptions of the values stored in the columns of thisa.

merge_indexed_array_from_all_tasks()

procedure parallel_arrays_gbl::p2d_array_obj::merge_indexed_array_from_all_tasks	(	class(p2d_array_obj)	this,
		integer, intent(in)	sendcount,
		integer, intent(in)	d2,
		logical, intent(in)	split_within_block )

Merges (gathers) indexed arrays with equal number of blocks from all tasks into a single indexed array on each task. The same array this % a is used for sends and receives: this assumes that the block of data of size sendcount sent by the process with rank j is located in the (j+1)st block of this % a. We assume that the block_offsets supplied on input by the process j have been adjusted before to point to the rank j's data in the merged array this % a. I.e. this routine doesn't perform any shifts of the pointers to the data in this % a.

Parameters

[in]	sendcount	Number of elements in this % a(:, d2) that this process sends. This number may differ accross processes.
[in]	d2	Index in the 2nd dimenstion of this % a in which the merge will be done.
[in]	split_within_block	If .true. then it is assumed that the values from each block have been redistributed among the tasks, i.e. if a non-zero value appears in within a block it should be kept by a single task only.

multiply_column()

procedure parallel_arrays_gbl::p2d_array_obj::multiply_column	(	class(p2d_array_obj)	this,
		integer, intent(in)	col,
		real(kind=cfp), intent(in)	fac )

Multiplies a given column of thisa by a real number.

print()

procedure parallel_arrays_gbl::p2d_array_obj::print	(	class(p2d_array_obj)	this,
		logical, intent(in)	only_non_zero,
		integer, intent(in), optional	out_unit )

Prints out the non-zero contents of the array thisa (and thisblock_offset, if thisno_blocks > 0). It is a non-blocking routine. If optional integer parameter out_unit is present, the contents are written into that unit instead of level2.

read()

procedure parallel_arrays_gbl::p2d_array_obj::read	(	class(p2d_array_obj)	this,
		character(len=*), intent(in)	file_name,
		integer, intent(in)	lunit,
		integer, intent(in)	record_start,
		integer, intent(out)	position_after_read )

The arrays thisa,thisblock_offset are read-in from the disk by the master task and redistributed to other processes. If shared-memory MPI is used then each NODE keeps only one copy of the arrays thisa,thisblock_offset otherwise the array is kept by every MPI task. It is a blocking routine.

reduce_a_local()

procedure parallel_arrays_gbl::p2d_array_obj::reduce_a_local

(

class(p2d_array_obj)

this

)

In-place reduction of the local arrays thisa on all processes using MPI_ALLREDUCE. It is a blocking routine.

reduce_a_to_master()

procedure parallel_arrays_gbl::p2d_array_obj::reduce_a_to_master

(

class(p2d_array_obj)

this

)

Reduction of the local arrays thisa on all processes to the array kept by the master. It is a blocking routine.

set_block_offset()

procedure parallel_arrays_gbl::p2d_array_obj::set_block_offset	(	class(p2d_array_obj)	this,
		integer, dimension(:), intent(in)	block_offset )

If the array is initialized with no_blocks > 0 this routine can be used to copy the contents of an external integer array to the array thisblock_offset which must have the same size.

sort_array_with_keys()

procedure parallel_arrays_gbl::p2d_array_obj::sort_array_with_keys	(	class(p2d_array_obj)	this,
		integer, intent(in)	n,
		integer, intent(in)	d2,
		integer, dimension(n,d2), intent(inout)	keys,
		integer, intent(in)	sort_method )

Sorts the array 'a' using keys given as an array of integers of the same dimension as 'a'. It is a non-blocking routine.

write()

procedure parallel_arrays_gbl::p2d_array_obj::write	(	class(p2d_array_obj)	this,
		integer, intent(in)	lunit,
		integer, intent(in)	record_start,
		integer, intent(out)	position_after_write,
		integer, intent(in)	rank )

Writes to the disk the arrays thisa,thisblock_offset from the process specified. It is a blocking routine.

Todo

the 'rank' parameter should be allowed to be < 0 in which case all processes write equal portion of the integrals array thereby speeding up the write on Lustre system.

Member Data Documentation

a

real(kind=cfp), dimension(:,:), pointer parallel_arrays_gbl::p2d_array_obj::a => null()

Local portion of the global array 'a': a_loc(my_start:my_end,1:d2). In the local mode my_start = 1 on all processes. The array can be shared on a single node in order to reduce memory usage in MPI-Scatci (Ahmed's implementation).

Warning

Never change the dimensions of this array by hand: if you need to do it then implement a method for this object otherwise you're making the d1,d2,my_start,etc. values inconsistent.

The type of this array variable cannot be real(kind=cfp), allocatable, target" since that is not allowed by Fortran 2003 standard. \warning Therefore if MPI 3.0 is to be used this object must be rewritten to work with array a(:,:) as an external input declared with the </tt>target" attribute or using module-local variables.

I.e. the type-bound array a(:,:) should be replaced by ``real(kind=cfp), pointer :: a(:,:)" and the pointer associated when <tt>init" or read" is called.

block_offset

integer, dimension(:), allocatable parallel_arrays_gbl::p2d_array_obj::block_offset

Pointers to start of blocks of data within the array 'a'. block_offset has dimension no_blocks.

---

The documentation for this type was generated from the following file:

• /scratch.ssd/codes/ukrmol-in-git/source/gbtolib/source/parallel_arrays.f90