Subject: Inquiry Intrinsics

From: Rob Schreiber <[email-masked]>
Date: Mon, 19 Oct 92 14:32:11 PDT

We are going to have a meeting on Wednesday to discuss Richard Shapiro's
proposal for inquiry intrinsics.    It may occur as early as 1:30 PM,
depending on the other committees.

Please read and review his proposal, as modified by me,
before then.   

Questions:  Should character arrays be used for outputs?  What should the char-len
be?  What should HPF_INQUIRE_DISTRIBUTION return as AXIS_INFO  in the case of 
an axis distributed with the * specification.  (*Is* there  a * specification in a
distribute?)

Here is the current draft:

\section{Distribution Inquiry Intrisics}

\subsection{Motivation}
HPF provides a rich set of data distribution directives. These directives
are advisory in nature. At some point, users will want to know to what
extent the compiler took their advice. This is especially important when a
user calls a non-HPF subroutine, since he may need to know the exact
distribution. For these reasons, HPF includes inquiry intrinsics
which describe how an array is actually mapped onto a machine.
To keep the number of intrinsics small, the inquiry intrisics are
structured as intrinsic subroutines with optional arguments.

\subsection{Alignment Inquiry Subroutine}
\def\varray{\verb+ARRAY+}

\CODE
	CALL HPF_INQUIRE_ALIGNMENT(ARRAY,LB,UB,STRIDE,AXIS_MAP,
		IDENTITY_MAP,REALIGNABLE,NUMBER_OF_COPIES)
	INTEGER,DIMENSION(7) :: LB,UB,STRIDE,AXIS_MAP
	INTEGER NUMBER_OF_COPIES
	LOGICAL IDENTITY_MAP,REALIGNABLE
\EDOC	
\begin{description}
\item[Required] ARRAY 
\item[Optional] LB,UB,STRIDE,AXIS\_MAP,
		IDENTITY\_MAP,REALIGNABLE,\\ NUMBER\_OF\_COPIES
\end{description}

The \verb+HPF_INQUIRE_ALIGNMENT+ subroutine returns information regarding
the alignment of an array to its associated template.  \verb+ARRAY+ is the
only input argument; all the remaining arguments are optional output arguments.
\begin{description}
\item[ARRAY] The array about which alignment information is requested.
\item[LB] An array containing the template coordinate
	of the first element of \varray\ along an axis.
\item[UB] An array containing the template coordinate
	of the last element of \varray\ along an axis.
\item[STRIDE] An array containing the stride used in aligning the elements
	of \varray\ along an axis.
\item[AXIS\_MAP] An array containing the template axis associated with an
	array axis. If \verb+AXIS_MAP+ is 0, the axis is a collapsed axis.
\item[IDENTITY\_MAP] A logical which will be true if the template
	associated with the array has a shape identical to \varray, the
	axes are mapped using the identity permutation, and the strides are all
        positive.
\item[REALIGNABLE] A logical which will be true if \varray\ has the 
	REALIGNABLE attribute.
\item[NUMBER\_OF\_COPIES] The product of the extents of all template axes over
        which \varray\ has been replicated.
	For a non-replicated array, for
	example, this will be 1.
\end{description}

\subsection{Template Inquiry Subroutine}

\CODE
	CALL HPF_INQUIRE_TEMPLATE(ARRAY,TEMPLATE_RANK,LB,UB,AXIS_TYPE,
		AXIS_INFO,NUMBER_ALIGNED,REDISTRIBUTABLE)	
	INTEGER,DIMENSION(MAX_TEMPLATE_RANK) :: LB,UB,AXIS_INFO
	CHARACTER*(*) AXIS_TYPE(MAX_TEMPLATE_RANK)
	INTEGER NUMBER_ALIGNED,TEMPLATE_RANK
	LOGICAL REDISTRIBUTABLE
\EDOC	

\begin{description}
\item[Required] ARRAY 
\item[Optional] LB,UB,AXIS\_TYPE,AXIS\_INFO,
		NUMBER\_ALIGNED,\\ TEMPLATE\_RANK,REDISTRIBUTABLE
\end{description}
The \verb+HPF_INQUIRE_TEMPLATE+ subroutine returns information regarding
the template associated with an array. The main difference between
\verb+HPF_INQUIRE_TEMPLATE+ and \verb+HPF_INQUIRE_ALIGNMENT+  is that the
former returns information concerning the array from the template's point
of view, while the latters returns information from the arrays point of
view. \varray\ is the
only input argument; all the remaining arguments are optional output
arguments.

\begin{description}
\item[ARRAY] The array about which template information is requested.
\item[LB] An array containing the declared template lower bound 
	for each axis.
\item[UB] An array containing the declared template upper bound 
	for each axis.
\item[AXIS\_TYPE] A character array which returns information about each
	axis of the template.  The following values are defined by HPF
	(implementations may define other values):
	
	\begin{description}
	\item['NORMAL'] The axis has an axis of \varray\ aligned to to it.
		\verb+AXIS_INFO+ contains the axis of the array aligned
		with the axis of the template.
	\item['SINGLE'] The array is aligned with a single coordinate of
		the template axis. \verb+AXIS_INFO+ contains the coordinate
		to which \varray\ is aligned.
	\item['REPLICATED'] The array is replicated along this template axis.
		\verb+AXIS_INFO+ contains the number of copies of
		\varray\ along the axis. This is an implemtation-specific
		quantity.
	\end{description}	

\item[AXIS\_INFO] See the desciption of \verb+AXIS_TYPE+ above.

         Example:
                               \CODE
                REAL A(4, 20)
         CHPF$  TEMPLATE T(30, 150, 8, 200) 
         CHPF$  ALIGN A(I,J,*) WITH T(J+5, 100, 10-2*I, *)
							\EDOC

         then 

							\CODE
         AXIS\_TYPE = ['NORMAL', 'SINGLE', 'NORMAL', 'REPLICATED'] and
         AXIS\_INFO = [2, 100, 1, 200]
							\EDOC

\item[NUMBER\_ALIGNED] The total number of arrays aligned to the template. 
	This is the number of arrays which will be moved when the template
	is redistributed.
\item[REDISTRIBUTABLE] A logical variable which will be true if the
	template is redistributable.
\item[TEMPLATE\_RANK] The number of axes in the template. This can be
	different than the number of array axes due to collapsing and
	replicating.
\end{description}

\subsection{Distribution Inquiry Subroutine}
\CODE
	CALL HPF_INQUIRE_DISTRIBUTION (ARRAY,AXIS_TYPE,AXIS_INFO,
		PROCESSORS_SHAPE,PROCESSORS_RANK)
	INTEGER AXIS_INFO(MAX_TEMPLATE_RANK),PROCESSORS_RANK
	CHARACTER*(*) AXIS_TYPE(MAX_TEMPLATE_RANK)
	INTEGER PROCESSORS_SHAPE(MAX_PROCESSORS_RANK)
\EDOC

\begin{description}
\item[Required] ARRAY 
\item[Optional] AXIS\_TYPE,AXIS\_INFO,
		PROCESSORS\_SHAPE,PROCESSORS\_RANK
\end{description}
The \verb+HPF_INQUIRE_DISTRIBUTION+ subroutine returns information regarding
the distribution of the template associated with an array.
\varray\ is the only input argument; all the remaining arguments 
are optional output arguments.

\begin{description}
\item[ARRAY] The array about whose template distribution 
	information is requested.
\item[AXIS\_TYPE] A character array which returns information about the 
	distribution of each axis of the template. 
	 The following values are defined by HPF
	(implementations may define other values):
	
	\begin{description}
	\item['BLOCK'] The axis is distributed BLOCK.
		\verb+AXIS_INFO+ contains the block size.
	\item['CYCLIC'] The axis is distributed CYCLIC.
		\verb+AXIS_INFO+ contains the block size.
	\item['COLLAPSED'] The axis is collapsed (distributed with the *
		specification)
	\end{description}	
\item[AXIS\_INFO] See the desciption of \verb+AXIS_TYPE+ above.
\item[PROCESSORS\_RANK] The rank of the processor arrangement associated
	with the array's template.
\item[PROCESSORS\_SHAPE] The shape of the processor arrangement associated
	 with the array's template.
\end{description}

\subsection{Examples}
Consider the declarations below:

\CODE
	DIMENSION A(10,10),B(20,30),C(20,40,10),D(40)
	CHPF$ TEMPLATE T(40,20)
	CHPF$REALIGNABLE A
	CHPF$ ALIGN A(I,:) WITH T(1+3*I,2:20:2)
	CHPF$ ALIGN C(I,*,J) WITH T(J,21-I)
	CHPF$ ALIGN D(I) WITH T(I,4)
	PROCESSORS P(4,2)
	CHPF$DISTRIBUTE T(BLOCK,BLOCK) ONTO P
	CHPF$DISTRIBUTE B(CYCLIC,BLOCK) ONTO P
\EDOC	

The results of \verb+HPF_INQUIRE_ALIGNMENT+ will be:
\begin{center}
\begin{tabular}{|l|c|c|c|}
\hline
& A & B & C \\ \hline \hline
LB & 4,2,... & 1,1,... & 1,N/A,1,... \\ \hline
UB & 31,20,... & 20,30,... & 20,N/A,10,... \\ \hline
STRIDE & 3,2,... & 1,1,... & -1,N/A,1,... \\ \hline
AXIS\_MAP & 1,2,... & 1,2,... & 2,0,1,... \\ \hline
IDENTITY\_MAP & .FALSE. & .TRUE. & .FALSE. \\ \hline
REALIGNABLE & .TRUE. & .FALSE. & .FALSE. \\ \hline
NUMBER\_OF\_COPIES & 1 & 1 & 1 \\ \hline
\end{tabular}\end{center}
and the result of  \verb+HPF_INQUIRE_TEMPLATE+ will be

\begin{center}
\begin{tabular}{|l|c|c|c|}
\hline
& A & C & D \\ \hline \hline
LB & 1,1,... & 1,1,... & 1,1,... \\ \hline
UB & 40,20,... & 40,20,... & 40,20,...  \\ \hline
AXIS\_TYPE & 'NORMAL','NORMAL',... &
	 'NORMAL','NORMAL',... & 'NORMAL','SINGLE',... \\ \hline
AXIS\_INFO & 1,2,... & 3,1,... & 1,4,... \\ \hline
NUM.AL. & 3 & 3 & 3 \\ \hline
TEMP. RANK& 2 & 2 & 2 \\ \hline
REDIST. & .FALSE. & .FALSE. & .FALSE. \\ \hline
\end{tabular}\end{center}

Finally  \verb+HPF_INQUIRE_DISTRIBUTION+ will produce
\begin{center}
\begin{tabular}{|l|c|c|}
\hline
& A & B \\ \hline \hline
AXIS\_TYPE & 'BLOCK','BLOCK',... &
	 'CYCLIC','BLOCK',... \\ \hline
AXIS\_INFO & 10,10,... & 1,15,... \\ \hline
PROCESSORS\_SHAPE & 4,2,... & 4,2,... \\ \hline
PROCESSORS\_RANK & 2 & 2 \\ \hline
\end{tabular}\end{center}
Note that the values of the block sizes (in \verb+AXIS_INFO+) are not
specified by HPF, but may be implementation-dependent.