HPJava index ranges

<h1>Ranges</h1>

A range is a map from the integer interval <tt>0,...,N-1</tt> into
some process dimension (ie, some dimension of a process grid).
Ranges are used to parametrize distributed arrays and the
<tt>overall</tt> distributed loop.

<p>

In HPJava ranges are represented by objects of class <tt>Range</tt>.
The most common way to create one is to use the constructor for one of
the subclasses representing a ranges with specific <i>distribution
formats</i>.  A class hierarchy of ranges is given below:

<p>
<img src="ranges.gif">
<p>

The simple block distribution format implemented by <tt>BlockRange</tt>
was used directly in the matrix multiplication example.  
The standard constructor for <tt>BlockRange</tt> has interface
<font color=Blue>
<pre>
  public BlockRange(int N, DimRange d)
</pre>
</font>
In passing we also mentioned <tt>CollapsedRange</tt>.  Members of this
class describe sequential, undistributed dimensions of HPJava arrays.
Constructors for <tt>CollapsedRange</tt> are not usually called explicitly,
but in fact the standard constructor has interface
<font color=Blue>
<pre>
  public CollapsedRange(int N)
</pre>
</font>

<p>

<tt>CyclicRange</tt> is a distribution format from High Performance
Fortran.  The interval is mapped to the process dimension in wraparound
mode, as in this example involving three processes:

<p>
<img src="cyclic.gif">
<p>

The standard constructor for <tt>CyclicRange</tt> has interface
<font color=Blue>
<pre>
  public CyclicRange(int N, DimRange d)
</pre>
</font>

<p>

<tt>BlockCyclicRange</tt> is another distribution format from HPF.
The interval is divided into blocks of some specified size which are
then mapped to the process dimension in wraparound fashion.  For example,
with block size 2:

<p>
<img src="bcyclic.gif">
<p>

The standard constructor for <tt>CyclicRange</tt> has interface
<font color=Blue>
<pre>
  public BlockCyclicRange(int N, DimRange d,
                          int blockSize)
</pre>
</font>

<p>

A <tt>DimRange</tt> represents the range of coordinates of a process
dimension, as in:

<p>
<img src="dim.gif">
<p>

Instances of the <tt>DimRange</tt> class are usually
obtained from a <tt>Procs</tt> object through the inquiry <tt>dim</tt>:
<font color=Blue>
<pre>
  public class Procs extends Group {
    ...
    public DimRange dim(int r) {...}
  }
</pre>
</font>
rather than through a constructor.

<p>

Some of the range classes have extra constructors providing special
options.  For example there is a <tt>BlockRange</tt> constructor that
takes extra arguments defining widths of ``ghost extensions'' for
arrays created using the range.

<p>

<b>Next:</b>
<a href="arrays.html">Distributed arrays</a>

