ArrayLib function prototypes header file. More...

Functions
int	AL_Init (int , char **)

int	AL_Finalize ()

int	AL_Initialized ()

int	AL_Sz_init (MPI_Comm, int *)

int	AL_Sz_free (int)

int	AL_Valid_ptr (int)

int	AL_Set_comm (MPI_Comm, int)

int	AL_Set_dimensions (int, int)

int	AL_Set_global_dim (int *, int)

int	AL_Set_local_dim (int *, int)

int	AL_Set_parallel_dim (int *, int)

int	AL_Set_periodic_dim (int *, int)

int	AL_Set_staggered_dim (int *, int)

int	AL_Set_ghosts (int *, int)

int	AL_Get_size (int, int *)

int	AL_Get_comm (int, MPI_Comm *)

int	AL_Get_cart_comm (int, MPI_Comm *)

int	AL_Get_dimensions (int, int *)

int	AL_Get_buffsize (int, int *)

int	AL_Get_global_dim (int, int *)

int	AL_Get_local_dim (int, int *)

int	AL_Get_local_dim_gp (int, int *)

int	AL_Get_parallel_dim (int, int *)

int	AL_Get_periodic_dim (int, int *)

int	AL_Get_staggered_dim (int, int *)

int	AL_Get_ghosts (int, int *)

int	AL_Get_offsets (int, int *)

int	AL_Get_lbounds (int, int , int , int *, int)

int	AL_Get_gbounds (int, int , int , int *, int)

int	AL_Get_bounds (int, int , int , int *, int)

int	AL_Is_boundary (int, int , int )

int	AL_Get_stride (int, int *)

int	AL_Decompose (int, int *, int)

int	AL_Type_create_subarray (int, int , int , int , int, MPI_Datatype, MPI_Datatype )

void *	AL_Allocate_array (int)

int	AL_Exchange (void *, int)

int	AL_Exchange_dim (char , int , int)

int	AL_Exchange_periods (void vbuf, int periods, int sz_ptr)

int	AL_File_open (char *, int)

int	AL_File_close (int)

int	AL_Write_array (void *, int, int)

int	AL_Read_array (void *, int, int)

int	AL_Write_array_begin (void , int, int , int *, int)

int	AL_Write_array_end (void *, int)

int	AL_Init_stack_ ()

int	AL_Allocate_sz_ ()

int	AL_Deallocate_sz_ (int)

int	AL_Auto_Decomp_ (int, int, int , int )

int	AL_Sort_ (int, int , int )

Detailed Description

Contains the function prototypes used in the ArrayLib routines.

Author: A. Malagoli (University of Chicago); A. Mignone (migno.nosp@m.ne@p.nosp@m.h.uni.nosp@m.to.i.nosp@m.t); G. Muscianisi (g.mus.nosp@m.cian.nosp@m.isi@c.nosp@m.inec.nosp@m.a.it)

Date: Aug 16, 2012

Function Documentation

void* AL_Allocate_array ( int sz_ptr )

Allocate the local buffer for a distributed array

Parameters

[in] sz_ptr pointer to SZ array (integer)

int AL_Allocate_sz_ ( )

Return an integer pointer to an SZ stack entry.

int AL_Auto_Decomp_	(	int	nproc,
		int	npdim,
		int *	ldims,
		int *	gdims
	)

Find a "maximally cubic" processors distribution.

Parameters

[in]	nproc	number of processors
[in]	npdim	number of parallel dimensions
[out]	ldims	processor decomposition along directions
[in]	gdims	global array sizes

int AL_Deallocate_sz_ ( int sz_ptr )

Deallocate an integer pointer to an SZ stack entry.

Parameters

[in] sz_ptr Integer pointer to an entry in the SZ stack

int AL_Decompose	(	int	sz_ptr,
		int *	procs,
		int	mode
	)

Create a distributed array descriptor and compile it

Parameters

[in]	sz_ptr	integer pointer to the distributed array descriptor
[in,out]	procs	array with the processor decomposition
[in]	mode	available value: AL_AUTO_DECOMP (internal decomposition) [Only for powers of two dimensions]; AL_MPI_DECOMP (MPI decomposition); AL_USER_DECOMP (user defined)

Bug fixed on Aug 26, 2012: When the global view of the file for a staggered variable is computed, the gdims[nd] has to be computed and then passed to the function AL_Type_create_subarray.

Since gdims[nd]=s->arrdim[nd], and in s->arrdim[nd] is taking into account that the variable is staggered, we comment the line "gdims[istag]++;" because it is no more needed.

Bug fixed on Aug 26, 2012: The following "if" has been modified:

OLD version: if (s->beg[istag] == s->bg[istag]) { ldims[istag]++; }else{ starts[istag]++; }

NEW version: if (s->beg[istag] == s->bg[istag]) { }else{ starts[istag]++; ldims[istag]–; }

"ldims[istag]++;" has been cancelled from the firt part of the if for the same motivation explaned before;
"ldims[istag]–;" has been added in the second part of the if because in PLUTO the index of the staggered variables start from -1, while in the ArrayLib they start from 0.

Bugs fixed on Aug 26, 2012: The following if has been modified:

OLD version: if (s->beg[istag] == s->bg[istag]) { ldims[istag]++; starts[istag]–; }

NEW version: if (s->beg[istag] == s->bg[istag]) { }else{ ldims[istag]–; starts[istag]++; }

"ldims[istag]++;" has been cancelled from the firt part of the if because when the local subarray for the MPI_Set_write_all for a staggered variable is computed, the ldims[nd] has to be computed and then passed to the function AL_Type_create_subarray. Since ldims[nd]=s->larrdim[nd], and in s->larrdim[nd] is taking into account that the variable is staggered, we remouved the line "ldims[istag]++;" because it is no more needed;
"starts[istag]–;" has been cancelled from the first part of the if because in PLUTO the indexes for the staggered variables start locally from -1, while in ArrayLib they start from 0;
the "else" has been added to take into account the motivation explaned in the point before.

int AL_Exchange	(	void *	vbuf,
		int	sz_ptr
	)

Fill the ghost boundaries

Parameters

[in]	vbuf	pointer to buffer
[in]	sz_ptr	integer pointer to the distributed array descriptor

int AL_Exchange_dim	(	char *	buf,
		int *	dims,
		int	sz_ptr
	)

Fill the ghost boundaries along selected dimensions

Parameters

[in]	buf	pointer to buffer
[in]	dims	if dims[i]=0, do not perform the exchange in this dimension (array if int)
[in]	sz_ptr	integer pointer to the distributed array descriptor

int AL_Exchange_periods	(	void *	vbuf,
		int *	periods,
		int	sz_ptr
	)

Same as AL_Exchange, but exchanges periodic boundaries at physical domain in the dim direction only if periods[dim] = 1. If a dimension is not periodic and periods[dim] = 1 nothing changes.

Parameters

[in]	vbuf	pointer to buffer
[in]	periods
[in]	sz_ptr	integer pointer to the distributed array descriptor

int AL_File_close ( int sz_ptr )

Close a file associate with and array

Parameters

[in] sz_ptr integer pointer to array descriptor

int AL_File_open	(	char *	filename,
		int	sz_ptr
	)

Open a file associated with a distributed array

Parameters

[in]	filename	name of the file
[in]	sz_ptr	integer pointer to the distributed array descriptor

Returns: ifp pointer to integer file pointer

int AL_Finalize ( )

Finalize the AL Tool. It contains a call to MPI_Finalize()

int AL_Get_bounds	(	int	isz,
		int *	beg,
		int *	end,
		int *	gp,
		int	style
	)

Get the global indexes for the local portion of a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	beg	Array of ndim integers containing the start points
[out]	end	Array of ndim integers containing the end points
[out]	gp	Array of ndim integers containing the ghost points
[in]	style	Index style: AL_C_INDEXES or AL_FORTRAN_INDEXES

int AL_Get_buffsize	(	int	sz_ptr,
		int *	buffsize
	)

Get the local buffer size for a distributed array, including the number of elements of the ghsot regions.

Parameters

[in]	sz_ptr	Integer pointer to the input array descriptor
[out]	buffsize	Buffer size [in number of elements]

int AL_Get_cart_comm	(	int	isz,
		MPI_Comm *	cart_comm
	)

Get the cartesian communicator for a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	cart_comm	Pointer to cartesian communicator

int AL_Get_comm	(	int	isz,
		MPI_Comm *	comm
	)

Get the communicator for a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	comm	Pointer to communicator

int AL_Get_dimensions	(	int	isz,
		int *	ndim
	)

Get the dimensions of the distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	ndim	Pointer to integer number of dimensions

int AL_Get_gbounds	(	int	isz,
		int *	gbeg,
		int *	gend,
		int *	gp,
		int	style
	)

Get the global bounds of the global array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	gbeg	Array of ndim integers containing the start points
[out]	gend	Array of ndim integers containing the end points
[out]	gp	Array of ndim integers containing the ghost points
[in]	style	Index style: AL_C_INDEXES or AL_FORTRAN_INDEXES

int AL_Get_ghosts	(	int	isz,
		int *	ghosts
	)

Get the ghost points of the distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	ghost	Array of integers with size of ghost points in each dimension

int AL_Get_global_dim	(	int	isz,
		int *	gdims
	)

Get the global dimensions of the distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	gdims	Array of integers with global dimensions

int AL_Get_lbounds	(	int	isz,
		int *	lbeg,
		int *	lend,
		int *	gp,
		int	style
	)

Get the local indexes for the local portion of a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	lbeg	Array of ndim integers containing the start points
[out]	lend	Array of ndim integers containing the end points
[out]	gp	Array of ndim integers containing the ghost points
[in]	style	Index style: AL_C_INDEXES or AL_FORTRAN_INDEXES

int AL_Get_local_dim	(	int	isz,
		int *	ldims
	)

Get the local dimensions of a distributed array WITHOUT GHOST POINTS

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	ldims	Array of integers with local dimensions

int AL_Get_local_dim_gp	(	int	sz_ptr,
		int *	ldims_gp
	)

Get the local dimensions of a distributed array WITH GHOST POINTS

Parameters

[in]	sz_ptr	Integer pointer to the input array descriptor
[out]	ldims_gp	Array of integers with local dimensions (including ghost points)

int AL_Get_offsets	(	int	sz_ptr,
		int *	offset
	)

Get the offsets for the for loop index calculation

NOTE: The typical multidimensional C for loop will look like, for example:

... ;

AL_Get_offsets(sz_ptr, offset);

for(k=kbeg; k<=kend; k++){ koff = k*offset[2]; for(j=jbeg; j<=jend; j++){ joff = j*offset[1]; for(i=ibeg; i<=iend; i++){ ioff = i*offset[0]+joff+koff; a[ioff] = ... ; } } } ... ;

Where a[ioff] is a generic 3D array.

Parameters

[in]	sz_ptr	Integer pointer to the input array descriptor
[out]	offset	Array of integers with offsets

int AL_Get_parallel_dim	(	int	isz,
		int *	pardims
	)

Get the parallel dimensions of a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	pardims	Array of integers with parallel dimensions [AL_TRUE\|AL_FALSE]

int AL_Get_periodic_dim	(	int	isz,
		int *	periods
	)

Get the periodic dimensions of the distributed arrays

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	periods	Array of integers with periodic dimensions [AL_TRUE\|AL_FALSE]

int AL_Get_size	(	int	isz,
		int *	size
	)

Get the size of the communicator associated with a distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor (input)
[in]	size	Integer pointer to size (output)

int AL_Get_staggered_dim	(	int	isz,
		int *	stagger
	)

Get the staggered dimensions of the distributed array

Parameters

[in]	isz	Integer pointer to the input array descriptor
[out]	stagger	Array of integers with staggered dimensions [AL_TRUE\|AL_FALSE]

int AL_Get_stride	(	int	sz_ptr,
		int *	stride
	)

Get the strides for the for loop index calculation NOTE: The typical multidimensional C for loop will look like, for example:

... ;

AL_Get_stride(sz_ptr, stride);

for(k=kbeg; k<=kend; k++){ koff = k*stride[2]; for(j=jbeg; j<=jend; j++){ joff = j*stride[1]; for(i=ibeg; i<=iend; i++){ ioff = i*stride[0]+joff+koff; a[ioff] = ... ; } } } ... ;

Where a[ioff] is a generic 3D array.

Parameters

[in]	sz_ptr	Integer pointer to the input array descriptor
[out]	stride	Array of strides

int AL_Init	(	int *	argc,
		char ***	argv
	)

Initialize the AL Tool. It contains a call to MPI_Init().

Parameters

[in]	argc	integer pointer to number of arguments
[in]	argv	pointer to argv list

int AL_Init_stack_ ( )

Initialize the stack of SZ pointers This routine is called internally by AL_Init.

int AL_Initialized ( )

Test whether or not AL was initialized

Returns: This function returns AL_TRUE if AL is initialized, AL_FALSE otherwise.

int AL_Is_boundary	(	int	sz_ptr,
		int *	is_gbeg,
		int *	is_gend
	)

This routine is useful when implementing the physical boundary conditions on a problem. It returns two arrays that are set to AL_TRUE or AL_FALSE depending on wether or not the local beginning (ending) address for the array in each direction is actually a global one.

Parameters

[in]	sz_ptr	pointer to a distributed array descriptor (integer)
[out]	is_gbeg	int array set to AL_TRUE or AL_FALSE for global beginning
[out]	is_gend	int array set to AL_TRUE or AL_FALSE for global ending

int AL_Read_array	(	void *	va,
		int	sz_ptr,
		int	istag
	)

Read a distributed array to a file in parallel using synchronous and collective IO operations

Parameters

[in]	buffer	pointer to the buffer to write
[in]	sz_ptr	integer pointer to a distributed array descriptor
[in]	istag	set it to -1 for centred variables, set to 0,1,2 for staggered field in the x,y,z direction

Bugs fixed on Aug 26, 2012:

nelem has been declared long long in order to manage dbl and flt output 'single_file' in which each PLUTO variable is >= 4GB
the updating of nelem after the writing of a variable has been modified from ''nelem *= (long long)(s->arrdim[i] +(istag == i));'' to ''nelem *= (long long)(s->arrdim[i]);'' because when a staggered variable is written, in the sz_ptr descriptor there is the information about the really number of element of this variable. This appens because the function AL_Set_staggered_dim is called for a staggered array.

int AL_Set_comm	(	MPI_Comm	comm,
		int	isz
	)

Set the communicator for a distributed array

Parameters

[in]	comm	MPI communicator the array is associated with
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the communicator is set correctly, AL_FAILURE otherwise.

int AL_Set_dimensions	(	int	ndim,
		int	isz
	)

Set the dimensions of a distributed array

Parameters

[in]	ndim	Number of dimensions (1 to 5)
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the dimensions are set correctly, AL_FAILURE otherwise.

int AL_Set_ghosts	(	int *	ghosts,
		int	isz
	)

Set the ghost points of a distributed array

Parameters

[in]	ghost	Array of integers with size of ghost points in each dimension
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the ghost points are set correctly, AL_FAILURE otherwise.

int AL_Set_global_dim	(	int *	gdims,
		int	isz
	)

Set the global dimensions of a distributed array

Parameters

[in]	gdims	Array of integers with global dimensions
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the global dimension are set correctly, AL_FAILURE otherwise.

int AL_Set_local_dim	(	int *	ldims,
		int	isz
	)

Set the local dimensions of a distributed array

Parameters

[in]	ldims	Array of integers with local dimensions
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the local dimension are set correctly, AL_FAILURE otherwise.

int AL_Set_parallel_dim	(	int *	pardims,
		int	isz
	)

Set the parallel dimensions of a distributed array

Parameters

[in]	pardims	Array of integers with parallel dimensions [AL_TRUE\|AL_FALSE]
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the parallel dimension are set correctly, AL_FAILURE otherwise.

int AL_Set_periodic_dim	(	int *	periods,
		int	isz
	)

Set the periodic dimensions of a distributed array

Parameters

[in]	periods	Array of integers with periodic dimensions [AL_TRUE\|AL_FALSE]
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the periodic dimension are set correctly, AL_FAILURE otherwise.

int AL_Set_staggered_dim	(	int *	stagger,
		int	isz
	)

Set the staggered dimensions of a distributed array

Parameters

[in]	stagger	Array of integers with staggered dimensions [AL_TRUE\|AL_FALSE]
[out]	isz	Integer pointer to the input array descriptor

Returns: AL_SUCCESS if the staggered dimension are set correctly, AL_FAILURE otherwise.

int AL_Sort_	(	int	n,
		int *	in,
		int *	ind
	)

Sort and array of integers

This is a really simple implementation, since we do not really use this for large arrays.

Parameters

[in]	n	size of input array (integer)
[in]	in	input array
[in]	ind	array of the sorted index arrays (max to min)

int AL_Sz_free ( int sz_ptr )

Dellocate a distributed array descriptor

Parameters

[in] sz_ptr Integer pointer to the array descriptor

int AL_Sz_init	(	MPI_Comm	comm,
		int *	sz_ptr
	)

Allocate and initialize a distributed array descriptor

Parameters

[in]	comm	MPI communicator the array is associated with
[out]	sz_ptr	Integer pointer to the array descriptor

Returns: AL_SUCCESS if the array descriptor is correct initialized, AL_FAILURE otherwise.

int AL_Type_create_subarray	(	int	ndims,
		int *	array_of_sizes,
		int *	array_of_subsizes,
		int *	array_of_starts,
		int	order,
		MPI_Datatype	oldtype,
		MPI_Datatype *	newtype
	)

Creates a datatype describing a subarray of a multidimensional array NOTE: This routine has been modified from R. Thakur's ROMIO implementation of MPI_Type_create_subarry. The reason for keeping a local copy is mainly to reduce this package's dependence on ROMIO. It only affects the non I/O components of the library (e.g. AL_Allgather).

Parameters

[in]	ndims	number of array dimensions
[in]	array_of_sizes	number of elements of type oldtype in each dimension of the full array
[in]	array_of_subsizes	number of elements of type oldtype in each dimension of the subarray
[in]	array_of_starts	starting coordinates of the subarray in each dimension
[in]	order	array storage order flag
[in]	oldtype	old datatype (handle)
[out]	newtype	new datatype (handle)

int AL_Valid_ptr ( int sz_ptr )

Return AL_TRUE if the input pointer points to an allocated distributed array. Return AL_FALSE otherwise.

Parameters

[in] sz_ptr Integer pointer to an entry in the SZ stack

int AL_Write_array	(	void *	va,
		int	sz_ptr,
		int	istag
	)

Write a distributed array to a file in parallel using synchronous and collective IO operations

Parameters

[in]	buffer	pointer to the buffer to write
[in]	sz_ptr	integer pointer to the distributed array descriptor
[in]	istag	set it to -1 for centred variables, set to 0,1,2 for staggered field in the x,y,z direction

Bugs fixed on Aug 26, 2012:

nelem has been declared long long in order to manage dbl and flt output 'single_file' in which each PLUTO variable is >= 4GB
the updating of nelem after the writing of a variable has been modified from ''nelem *= (long long)(s->arrdim[i] +(istag == i));'' to ''nelem *= (long long)(s->arrdim[i]);'' because when a staggered variable is written, in the sz_ptr descriptor there is the information about the really number of element of this variable. This appens because the function AL_Set_staggered_dim is called for a staggered array.

int AL_Write_array_begin	(	void *	va,
		int	sz_ptr,
		int *	output_stag,
		int *	output_dump,
		int	output_nvar
	)

Write a distributed array to a parallel file by using asynchronous MPI-IO

Parameters

[in]	buffer	pointer to the buffer to write
[in]	sz_ptr	integer pointer to the distributed array descriptor
[in]	output_stag	vector sets to -1 for centred variables, and sets to 0,1,2 for staggered field in the x,y,z direction
[in]	output_dump	vector sets to 1 if the variable has to be dumped, 0 in the contrary case
[in]	output_nvar	total number of variables in PLUTO simulation

int AL_Write_array_end	(	void *	va,
		int	sz_ptr
	)

Completition of writing of a distributed array to a parallel file by using asynchronous MPI-IO

Parameters

[in]	buffer	pointer to the buffer to write
[in]	sz_ptr	integer pointer to the distributed array descriptor

Functions

Detailed Description

Function Documentation