Pooma Manual: Array and Domain Chapter
Jeffrey Oldham
oldham at codesourcery.com
Tue Jan 15 17:53:19 UTC 2002
This patch finishes the first draft of the Array and Domain chapter of
the Pooma manual.
2002-Jan-15 Jeffrey D. Oldham <oldham at codesourcery.com>
* arrays.xml: New file containing the Array and Domain chapter.
* concepts.xml: Add glossary links to "index" entry.
* manual.xml: Replace "bookCap" entity with "bookcap". Add "dim",
"domaintemplate", and "float" entities. Move Array (and Domain)
chapter to new file 'arrays.xml'.
Applied to mainline
Approved by me!
Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: arrays.xml
===================================================================
RCS file: arrays.xml
diff -N arrays.xml
*** /dev/null Fri Mar 23 21:37:44 2001
--- arrays.xml Tue Jan 15 17:48:34 2002
***************
*** 0 ****
--- 1,1738 ----
+ <chapter id="arrays">
+ <title>&array; Containers</title>
+
+ <para>A container is a class holding objects. &array;s are one of
+ the two most widely used &pooma; containers since they model the
+ mathematical concept of mapping indices from domains to values.
+ &pooma; &array;s extend built-in &cc; arrays by supporting a wider
+ variety of domains, automatically handling memory allocations, and
+ supporting first-class status. For example, they may be used as
+ operands and in assignments. In this chapter, we introduce the
+ concept of containers, the mathematical concept of arrays, and the
+ &pooma; concept for &array;s. Before illustrating how to declare
+ &array;s, we introduce &domain;s, which specify the sets of
+ indices. After describing how to declare the various types of
+ &domain;s, we describe how to declare and use &array;s. This is
+ illustrated in a &doof2d; implementation using &array;s. We end
+ with a description of their implementation.</para>
+
+
+ <section id="arrays-containers">
+ <title>Containers</title>
+
+ <para>A <glossterm
+ linkend="glossary-container"><firstterm>container class
+ expression</firstterm></glossterm> is a class with the main
+ purpose of holding objects. These stored objects, called
+ <glossterm linkend="glossary-container_value"><firstterm>container
+ values</firstterm></glossterm> or more simply
+ <quote>values</quote> or elements<quote></quote>, may be accessed
+ and changed, usually using indices. <quote>Container
+ class</quote> is usually abbreviated
+ <quote>container</quote>.</para>
+
+ <para>The six &pooma; containers can be categorized into two
+ groups. Mathematical containers include &tensor;s, &matrix;s, and
+ &vector;s, modeling tensors, matrices, and vectors, respectively.
+ Storage containers include &array;s, &dynamicarray;s, and
+ &field;s. In this chapter, we focus on simplest of these:
+ &array;s. The other containers will be described in subsequent
+ chapters.</para>
+
+ <para>&c; has built-in arrays, and the &cc; Standard Library
+ provides <type>map</type>s, <type>vector</type>s,
+ <type>stack</type>s, and other containers, but the &pooma;
+ containers better model scientific computing concepts and provide
+ more functionality. They automatically handle memory allocation
+ and deallocation and can be used in expressions and on the
+ left-hand side of assignments. Since &pooma; containers separate
+ the container concepts of accessing and using values from storing
+ values, value storage can be optimized to specific needs. For
+ example, if most of an &array;'s values are known to be the same
+ most of the time, a compressible engine can be used. Whenever all
+ the array's values are the same, it stores only one value. At
+ other times, it stores all the values. Engines will be discussed
+ in <xref linkend="engines"></xref>.</para>
+ </section>
+
+
+ <section id="arrays-arrays">
+ <title>&array;s</title>
+
+ <para>Mathematically, an array maps indices from a domain to
+ values. Usually, the domain consists of a one-dimensional
+ integral interval or it may be multidimensional. &pooma;'s
+ &array; container class implements this idea. Given an index,
+ i.e., a position in an &array;'s &domain;, it returns the associated
+ value, either by returning a stored value or by computing it. The
+ use of indices, which are usually integral tuples but need not be
+ zero-based or even consist of all possible integral tuples in a
+ multidimensional range. Using indices permits constant-time
+ access to values although computing a particular value may require
+ significant time.</para>
+
+ <para>&pooma; &array;s are <glossterm
+ linkend="glossary-first_class">first-class
+ types<firstterm></firstterm></glossterm> so they can be used more
+ widely than built-in &cc; arrays. For example, &array;s can be
+ used as operands and in assignment statements. The statement
+ <statement>a = a + b;</statement> adds corresponding elements of
+ &array;s <varname>a</varname> and <varname>b</varname>, assigning
+ the sums to the &array; <varname>a</varname>. The statement
+ treats each array as one object, rather than requiring the use of
+ one or more loops to access individual values. Data-parallel
+ statements are further discussed in <xref
+ linkend="data_parallel"></xref>. &array;s also handle their own
+ memory allocation and deallocation. For example, the &array;
+ declaration <statement>Array<2, double, Brick>
+ a(vertDomain)</statement> creates an
+ &array; <varname>a</varname>, allocating whatever memory it
+ needs. When <varname>a</varname> goes out of scope, it and its
+ memory is automatically deallocated. Automatic memory allocation
+ and deallocation also eases copying. As we mentioned above, an
+ &array;'s &engine; stores or computes its values so it, not the
+ &array; itself, is responsible for memory allocation and
+ deallocation. Fortunately, this distinction is usually hidden
+ from the &pooma; user.</para>
+
+ <para>Individual &array; values can be accessed using parentheses,
+ not square brackets, as for &cc; arrays. For example,
+ <statement>a(3,4)</statement> yields the value at position (3,4)
+ of <varname>a</varname>'s two-dimensional domain.</para>
+ </section>
+
+
+ <section id="arrays-domains">
+ <title>&domain;s</title>
+
+ <para>A <glossterm
+ linkend="glossary-domain"><firstterm>domain</firstterm></glossterm>
+ specifies the set of points on which an &array; can define values.
+ These indices are the arguments placed within parentheses when
+ selecting particular values, as described previously. A domain
+ supported both by &array;s and by built-in &cc; arrays is an
+ interval [0,n-1] of integers containing all integers {0, 1, 2,
+ …, n-1}. For &cc;, every integer in the interval must be
+ included, and the minimum index must be zero. &pooma; expands the
+ set of permissible domains to support intervals with nonzero
+ minimal indices and strides and by adding other choices.</para>
+
+ <para>In &pooma;, &domain;s implement domains. There are four
+ different categories:
+ <variablelist>
+ <varlistentry>
+ <term>&loc;</term>
+ <listitem>
+ <para>&domain; with a single point.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&interval;</term>
+ <listitem>
+ <para>&domain; with an integral interval [a,b].</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>⦥</term>
+ <listitem>
+ <para>&domain; with an integral interval [a,b] and an integral
+ stride s indicating the gap between indices: {a, a+s,
+ a+2s, …, b}.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&grid;</term>
+ <listitem>
+ <para>&domain; with an ascending or descending sequence of
+ integral values. The sequence elements must be individually
+ specified.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ One-dimensional and multidimensional versions of each categories
+ are supported. A multidimensional &domain; consists of the direct
+ product of one-dimensional &domain;s. For example, the first
+ dimension of a two-dimensional interval [0,3]x[2,9] is the
+ interval [0,3], and its second dimension is the
+ interval [2,9]. Its indices are ordered pairs such as (0,2),
+ (0,3), (1,2), (1,9), and (3,7).</para>
+
+ <para>Many domains can be represented using domain triplets. A
+ <glossterm linkend="glossary-domain_triplet"><firstterm>domain
+ triplet</firstterm></glossterm>
+ [<varname>begin</varname>:<varname>end</varname>:<varname>stride</varname>]
+ represents the mathematical set {begin, begin + stride, begin +
+ 2stride, …, end}, where <varname>end</varname> is in the
+ set only if it equals <varname>begin</varname> plus some integral
+ multiple of <varname>stride</varname>. If the
+ <varname>stride</varname> is negative, its beginning index
+ <varname>begin</varname> should at least be as large as
+ <varname>end</varname> if the interval is to be nonempty. The
+ stride can be zero only if <varname>begin</varname> and
+ <varname>end</varname> are equal. There are lots of ways to
+ represent an empty interval, e.g., [1:0:1] and [23,34,-1], and
+ &pooma; will accept them, but they are all equivalent. The domain
+ triplet notation is easily extended to multiple dimensions by
+ separating different dimension's intervals with commas. For
+ example, [2:4:2,6:4:-2] contains (2,6), (2,4), (4,6),
+ and (4,4).</para>
+
+ <para>All the &domain; categories listed above except &grid; can be
+ represented using domain triplet notation. Since the triplet
+ [7:7:1] represents {7}, or more simply 7, it can also
+ represent <statement>Loc<1>(7)</statement>. Multidimensional
+ &loc;s are similarly represented. For example,
+ [0:0:1,10:10:1,2:2:1] represents
+ <statement>Loc<3>(0,10,2)</statement>, but it is frequently
+ abbreviated as [0,10,2]. An &interval; [a,b] has unit stride:
+ [a:b:1], while a ⦥ has specific stride s:
+ [a:b:s].</para>
+
+ <para>&domain;s can be constructed by combining &domain;s of smaller
+ dimension. For example, since a two-dimensional &interval; is the
+ direct product of two one-dimensional &interval;s, it can be
+ specified using two one-dimensional &interval;s. For example,
+ <statement>Interval<2>(Interval<1>(2,3),
+ Interval<1>(4,5))</statement> creates a [2:3:1,4:5:1]
+ &domain;. The resulting dimensionality equals the sum of the
+ components' dimensions. For example, a four-dimension &loc; can
+ be specified using three- and one-dimension &loc;s or using four
+ one-dimension &loc;s. If fewer dimensions than the created
+ object's dimensionality, the last dimensions are unspecified and
+ uninitialized. &loc;s, &interval;s, ⦥s, and &grid;s can all
+ be composed from smaller similar components.</para>
+
+ <para>A &domain; can be composed from smaller components with
+ different types. A &loc; object can be constructed from other
+ &loc; objects and integers. &interval;s, ⦥s, and &grid;s
+ can be constructed using any of these types, &loc;s, and integers.
+ For example, <statement>Interval<3> a(Loc<2>(1,2),
+ Interval<1>(3,5))</statement> uses a two-dimensional &loc;
+ and a one-dimensional &interval; to create a [1:1:1,2:2:1,3:5:1]
+ &domain;. During creation of a &domain;, the type of each object
+ is changed to the &domain;'s type. In the example,
+ <statement>Loc<2>(1,2)</statement> is first converted to an
+ &interval;.</para>
+
+ <para>&domain;s can participate in some arithmetic and comparison
+ operations. For example, a &domain;'s triplet can be shifted two
+ units to the right by adding two. Multiplying a &domain; by two
+ multiplies its triplet's beginnings, endings, and strides by two.
+ &pooma; users rarely need to compare &domain;s, but we describe
+ operating with the less-than operator on &interval;s. &interval;
+ <varname>d1</varname> < &interval; <varname>d2</varname> if the
+ length of <varname>d1's</varname> interval is less than
+ <varname>d2</varname>'s or, if equal, its beginning value is
+ smaller. &domain; arithmetic is frequently used with data-parallel
+ statements and container views. These will be discussed in <xref
+ linkend="data_parallel"></xref> and <xref
+ linkend="views"></xref>.</para>
+
+ <para>The current &pooma; implementation supports &domain;s with
+ dimensionality between one and seven, inclusive. Since most
+ scientific computations use one, two, or three dimensions, this is
+ usually sufficient. If more dimensions are needed, they can be
+ added to the source code.</para>
+ </section>
+
+
+ <section id="arrays-domains_declarations">
+ <title>Declaring &domain;s</title>
+
+ <para>Since &domain;s are mainly used to declare container
+ domains, we focus on declaring &domain;s. Arithmetic operations
+ with &domain;s are described in <xref
+ linkend="views"></xref>.</para>
+
+ <para>All &domain; declarations require a dimension template
+ parameter <varname>&dim;</varname>. This positive integer
+ specifies the number of dimensions, i.e., rank, of the &domain; and
+ determines the length of the tuples for points in the &domain;. For
+ example, a three-dimensional &domain; contains ordered triples,
+ while a one-dimensional &domain; contains singletons, or just
+ integers. Multidimensional &domain;s are just the direct products
+ of one-dimensional &domain;s so the techniques for declaring
+ one-dimensional &domain;s carry over to multi-dimensional
+ ones.</para>
+
+ <para>To declare a &domain;, one must include the
+ <filename class="headerfile">Pooma/Domains.h</filename> header
+ file. However, most &pooma; programs declare &domain;s to use them
+ when constructing containers. The container header files
+ automatically include <filename
+ class="headerfile">Pooma/Domains.h</filename> so no explicit
+ inclusion is usually necessary.</para>
+
+ <section id="arrays-domains_declarations-loc">
+ <title>&loc;s</title>
+
+ <para>A <type>Loc<&dim;></type> is a &domain; with just a single
+ <varname>&dim;</varname>-dimensional point. Although it is
+ infrequently used as a container's domain, it is used to refer to
+ a single point within another domain. Its beginning and ending
+ points are the same, and its stride is one. One-dimensional
+ &loc;s and integers are frequently interchanged.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-loc-one_d_table">
+ <title>Declaring One-Dimensional &loc;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
+ <varname>&domaintemplate;3</varname> are template parameters.</entry>
+ <entry></entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Loc<1>()</statement></entry>
+ <entry>points to zero.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<1>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an uninitialized &locone;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<1>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &locone; with the integer converted from <varname>t1</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &locone; with the integer converted from
+ <varname>t1</varname>. <varname>t2</varname> must equal
+ <varname>t1</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &locone; with the integer converted from
+ <varname>t1</varname>. <varname>t2</varname> must equal
+ <varname>t1</varname>, and <varname>t3</varname> is
+ ignored.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Constructors for one-dimensional &loc;s appear in <xref
+ linkend="arrays-domains_declarations-loc-one_d_table"></xref>.
+ The empty constructor yields the zero point. The constructor
+ taking a <type>Pooma::Init</type> object does not initialize the
+ resulting &loc; to any particular value. Presumably, the value
+ will be assigned later. For small &domain;s such as &loc;s, the
+ time savings from not initializing is small, but the
+ functionality is still available. The constructor taking one
+ argument with type <type>&domaintemplate;1</type> converts this argument to
+ an integer to specify the point. The template
+ type <type>&domaintemplate;1</type> may be any type that can be converted
+ to an integer, e.g., &bool;, &char;, ∫, or &double;. The
+ constructors taking two and three arguments of templatized types
+ facilitate converting an &interval; and a ⦥ into a &loc;.
+ Since a &loc; represents a single point, the &interval;'s or
+ ⦥'s first two arguments must be equal. The stride is
+ ignored. Again, the templatized types may be any type that can
+ be converted into an integer.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-loc-multi_d_table">
+ <title>Declaring Multidimensional &loc;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&dim;</varname> indicates the &loc;'s dimension.
+ <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
+ template parameters.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Loc<&dim;>()</statement></entry>
+ <entry>points to zero.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an uninitialized &loc;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &loc; using the given &domain; object.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
+ <entry>creates a &loc; using the given &domain; objects.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Constructors for multidimensional &loc;s appear in <xref
+ linkend="arrays-domains_declarations-loc-multi_d_table"></xref>.
+ <varname>&dim;</varname> indicates the &loc;'s dimension. The
+ first two constructors are similar to &locone;'s first two
+ constructors, returning a representation of the zero point and
+ returning an uninitialized point. The seven other constructors
+ create a &loc; using other &domain; objects. These &domain; objects,
+ having types <type>&domaintemplate;1</type>, …, <type>&domaintemplate;7</type>, can have
+ any type that can be converted into an integer, to a &locone;, or
+ to a multidimensional &domain; object that itself can be converted
+ into a &loc;. The total dimensionality of all the arguments'
+ types should be at most <varname>&dim;</varname>. For example,
+ <statement>Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
+ Interval<1>(4,4))</statement> creates a five-dimensional &loc;
+ [2,2,3,4,1] using a one-dimensional ⦥, a two-dimensional
+ &loc;, and a one-dimensional &interval;. The final fifth
+ dimension has an unspecified value, in this case 1. The
+ one-dimensional ⦥ is converted into the single integer two;
+ its beginning and ending points must be the same. The
+ two-dimensional &loc; contributes values for the next two
+ dimensions, while the &interval; contributes its beginning point,
+ which must be the same as its ending point. Note that the
+ &locone; constructors taking two and three parameters ignore
+ their second and third arguments, but this is not true for the
+ multidimensional constructors.</para>
+ </section>
+
+
+ <section id="arrays-domains_declarations-intervals">
+ <title>&interval;s</title>
+
+ <para>A one-dimensional &interval; represents a set of integers
+ within a mathematical <glossterm
+ linkend="glossary-interval">interval</glossterm>.
+ Multidimensional &interval;s represent their multidimensional
+ generalization, i.e., the direct product of one-dimensional
+ intervals. &interval;s are arguably the most commonly used
+ &pooma; &domain;. A one-dimensional &interval; has integral
+ beginning and ending points and a unit stride.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-interval-one_d_table">
+ <title>Declaring One-Dimensional &interval;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
+ <varname>&domaintemplate;3</varname> are template parameters.</entry>
+ <entry></entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Interval<1>()</statement></entry>
+ <entry>creates an empty, uninitialized interval.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<1>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an uninitialized &intervalone;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<1>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &intervalone;. See the text for an explanation.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &intervalone; with the integers converted from
+ <varname>t1</varname> and <varname>t2</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &intervalone; with the integers converted from
+ <varname>t1</varname> and <varname>t2</varname>.
+ <varname>t3</varname> must equal 1.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>&intervalone; constructors are patterned on &locone;
+ constructors except that &intervalone;s can have differing
+ beginning and ending points. See <xref
+ linkend="arrays-domains_declarations-interval-one_d_table"></xref>.
+ The default constructor creates an empty, uninitialized interval,
+ which should not be used before assigning it values. If the
+ one-parameter constructor's argument is a &domain; object, it must
+ be a one-dimensional &domain; object which is copied into an
+ &interval; if possible; for example, it must have unit stride.
+ If the one-parameter constructor's argument is not a &domain;
+ object, it must be convertible to an
+ integer <varname>e</varname> and an interval [0:e-1:1]
+ starting at zero is constructed. If two arguments are specified,
+ they are assumed to be convertible to integers
+ <varname>b</varname> and <varname>e</varname>, specifying the
+ interval [b:e:1]. The three-parameter constructor is similar,
+ with the third argument specifying a stride, which must be
+ one.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-intervals-multi_d_table">
+ <title>Declaring Multidimensional &interval;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&dim;</varname> indicates the &interval;'s dimension.
+ <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
+ template parameters.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Interval<&dim;>()</statement></entry>
+ <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &interval; using the given &domain; object.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
+ <entry>creates a &interval; using the given &domain; objects.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Constructors for multidimensional &interval;s closely
+ follow constructors for multidimensional &loc;s. See <xref
+ linkend="arrays-domains_declarations-intervals-multi_d_table"></xref>.
+ <varname>&dim;</varname> indicates the &interval;'s
+ dimension. The first two constructors both return empty,
+ uninitialized intervals. The seven other constructors create an
+ &interval; using &domain; objects. These &domain; objects,
+ having types <type>&domaintemplate;1</type>, …,
+ <type>&domaintemplate;7</type>, can have any type that can be
+ converted into an integer, into a single-dimensional &domain;
+ object that can be converted into a single-dimensional
+ &interval;, or to a multidimensional &domain; object that itself
+ can be converted into an &interval;. The total dimensionality of
+ all the arguments' types should be at
+ most <varname>&dim;</varname>. One-dimensional &domain;
+ objects that can be converted into one-dimensional &interval;s
+ include &locone;s, &intervalone;s, and &rangeone;s with unit
+ strides. If the sum of the objects' dimensions is less
+ than <varname>&dim;</varname>, the intervals for the final
+ dimensions are unspecified. See the last paragraph of <xref
+ linkend="arrays-domains_declarations-loc"></xref> for an
+ analogous example. Note that the &intervalone; constructors
+ taking two and three parameters treat these arguments differently
+ than the multidimensional constructors do.</para>
+ </section>
+
+
+ <section id="arrays-domains_declarations-ranges">
+ <title>⦥s</title>
+
+ <para>A one-dimensional ⦥ generalizes an &interval; by
+ permitting a non-unit stride between integral members. A
+ <glossterm
+ linkend="glossary-range"><firstterm>range</firstterm></glossterm>
+ is a set of integers in a mathematical interval [b,e] with a
+ stride s between them: {a, a+s, a+2s, …, b}. Ranges
+ are generalized to <varname>&dim;</varname> dimensions using the
+ direct product of one-dimensional ranges.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-range-one_d_table">
+ <title>Declaring One-Dimensional ⦥s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
+ <varname>&domaintemplate;3</varname> are template parameters.</entry>
+ <entry></entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Range<1>()</statement></entry>
+ <entry>creates an empty, uninitialized range.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<1>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an uninitialized &rangeone;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<1>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &rangeone;. See the text for an explanation.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &rangeone; with an interval specified by the
+ integers converted from <varname>t1</varname> and
+ <varname>t2</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &rangeone; by converting the arguments to
+ integers <varname>i1</varname>, <varname>i2</varname>, and
+ <varname>i3</varname> and then making a range [i1:i2:i3].</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>&rangeone; constructors are the same as &intervalone;
+ constructors except they create ranges, not intervals. See <xref
+ linkend="arrays-domains_declarations-range-one_d_table"></xref>.
+ The default constructor creates an empty, uninitialized range,
+ which should not be used before assigning it values. If the
+ one-parameter constructor's argument is a &domain; object, it must
+ be a one-dimensional &domain; object which is copied into a ⦥
+ if possible. If the one-parameter constructor's argument is not
+ a &domain; object, it must be convertible to an
+ integer <varname>e</varname> and a range [0:e-1:1] starting
+ at zero is constructed. If two arguments are specified, they are
+ assumed to be convertible to integers <varname>b</varname> and
+ <varname>e</varname>, specifying the range [b:e:1]. The
+ three-parameter constructor is similar, with the third argument
+ specifying a stride.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-ranges-multi_d_table">
+ <title>Declaring Multidimensional ⦥s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&dim;</varname> indicates the ⦥'s dimension.
+ <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
+ template parameters.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Range<&dim;>()</statement></entry>
+ <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const Pooma::NoInit& no)</statement></entry>
+ <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; object.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
+ <entry>creates a ⦥ using the given &domain; objects.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Constructors for multidimensional ⦥s are the same as
+ multidimensional &interval; constructors except they create
+ ranges, not intervals. See <xref
+ linkend="arrays-domains_declarations-ranges-multi_d_table"></xref>.
+ <varname>&dim;</varname> indicates the ⦥'s dimension. The
+ first two constructors return empty, uninitialized ranges.
+ The seven other constructors create an ⦥ using &domain;
+ objects. These &domain; objects, having types <type>&domaintemplate;1</type>,
+ …, <type>&domaintemplate;7</type>, can have any type that can be
+ converted into an integer, into a single-dimensional &domain;
+ object that can be converted into a single-dimensional ⦥,
+ or to a multidimensional &domain; object that itself can be
+ converted into an ⦥. The total dimensionality of all the
+ arguments' types should be at most <varname>&dim;</varname>.
+ One-dimensional &domain; objects that can be converted into
+ one-dimensional ⦥s include &locone;s, &intervalone;s, and
+ &rangeone;s. If the sum of the objects' dimensions is less
+ than <varname>&dim;</varname>, the ranges for the final
+ dimensions are unspecified. See the last paragraph of <xref
+ linkend="arrays-domains_declarations-loc"></xref> for an
+ analogous example. Note that the &rangeone; constructors taking
+ two and three parameters treat these arguments differently than
+ the multidimensional constructors do.</para>
+ </section>
+
+
+ <section id="arrays-domains_declarations-grids">
+ <title>&grid;s</title>
+
+ <para>&loc;s, &interval;s, and ⦥s all have regularly spaced
+ integral values so they can be represented using <glossterm
+ linkend="glossary-domain_triplet">domain triplets</glossterm>.
+ One-dimensional &grid; integral domains contain ascending or
+ descending sequences of integers, with no fixed stride. For
+ example, a &gridone; may represent {-13, 1, 4, 5, 34}. &gridone;
+ is generalized to multidimensional &grid;s using the direct
+ product of &gridone; &domain;s.</para>
+
+ <para>&grid;s that can be represented using domain triplets can
+ be constructed using techniques similar to other &domain;s, but
+ irregularly spaced domains can be constructed using
+ &indirectionlistint;s.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-grid-one_d_table">
+ <title>Declaring One-Dimensional &grid;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
+ <varname>&domaintemplate;3</varname> are template parameters.</entry>
+ <entry></entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Grid<1>()</statement></entry>
+ <entry>creates an empty, uninitialized grid.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<1>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &gridone;. See the text for an explanation.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &gridone; from the interval specified by the
+ integers converted from <varname>t1</varname> and
+ <varname>t2</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &gridone; from the domain triplet specified
+ by the integers converted from <varname>t1</varname>,
+ <varname>t2</varname>, and <varname>t3</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>To construct a &gridone; that can also be represented by a
+ domain triplet, use a &gridone; constructor similar to those for
+ &intervalone; and &rangeone;. See <xref
+ linkend="arrays-domains_declarations-grid-one_d_table"></xref>
+ and the text explanations following <xref
+ linkend="arrays-domains_declarations-range-one_d_table"></xref>
+ or <xref
+ linkend="arrays-domains_declarations-interval-one_d_table"></xref>.</para>
+
+ <para>&gridone;s with irregularly spaced points can be
+ constructed using &indirectionlistint;s. For example,
+ <programlisting>
+ IndirectionList<int> list(4);
+ list(0) = 2;
+ list(1) = 5;
+ list(2) = 6;
+ list(3) = 9;
+ Grid<1> g(list);
+ </programlisting> constructs an empty &indirectionlistint;, fills it
+ with ascending values, and then creates a &gridone; containing
+ {2, 5, 6, 9}. When creating a list, its size must be specified.
+ Subsequently, its values can be assigned. &indirectionlist;s can
+ also be initialized using one-dimensional &array;s:
+ <programlisting>
+ Array<1,int,Brick> a1(Interval<1>(0,3));
+ a1(0) = 2; a1(1) = 5; a1(2) = 6; a1(3) = 9;
+ IndirectionList<int> il(a1);
+ Grid<1> g1(il);
+ </programlisting> The &array; stores the integral points to include
+ in the &gridone; and is used to create the &indirectionlistint;,
+ which itself is used to create the &gridone;. Since the points
+ are integers, the &array;'s type is ∫. Either a &brick; or
+ &compressiblebrick; &engine; should be used.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-domains_declarations-grids-multi_d_table">
+ <title>Declaring Multidimensional &grid;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>constructor</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry><varname>&dim;</varname> indicates the &grid;'s
+ dimension. <varname>&domaintemplate;1</varname>,
+ <varname>&domaintemplate;2</varname>, … are template
+ parameters.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Grid<&dim;>()</statement></entry>
+ <entry>creates an empty, uninitialized &grid;, to be assigned a value later.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1)</statement></entry>
+ <entry>creates a &grid; using the given &domain; object.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ <row>
+ <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
+ <entry>creates a &grid; using the given &domain; objects.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Constructors for multidimensional &grid;s are the same as
+ multidimensional &interval; constructors except they create
+ &grid;s, not intervals. See <xref
+ linkend="arrays-domains_declarations-grids-multi_d_table"></xref>.
+ <varname>&dim;</varname> indicates the &grid;'s dimension. The
+ first constructor returns empty, uninitialized grids. The seven
+ other constructors create an &grid; using &domain; objects. These
+ &domain; objects, having types <type>&domaintemplate;1</type>, …,
+ <type>&domaintemplate;7</type>, can have any type that can be converted into an
+ integer, into a single-dimensional &domain; object that can be
+ converted into a single-dimensional &grid;, or to a
+ multidimensional &domain; object that itself can be converted into
+ an &grid;. The total dimensionality of all the arguments' types
+ should be at most <varname>&dim;</varname>. One-dimensional
+ &domain; objects that can be converted into one-dimensional &grid;s
+ include &locone;s, &intervalone;s, &rangeone;s, and &gridone;s.
+ If the sum of the objects' dimensions is less
+ than <varname>&dim;</varname>, the grids for the final
+ dimensions are unspecified. See the last paragraph of <xref
+ linkend="arrays-domains_declarations-loc"></xref> for an
+ analogous example. Note that the &gridone; constructors taking
+ two and three parameters treat these arguments differently than
+ the multidimensional constructors do.</para>
+ </section>
+ </section>
+
+
+ <section id="arrays-arrays_declarations">
+ <title>Declaring &array;s</title>
+
+ <para>A &pooma; &array; maps indices from its &domain; to values.
+ In this section, we describe first describe how to declare
+ &array;s. In the next section, we explain how to access
+ individual values stored within an &array; and &array; copy
+ semantics.</para>
+
+ <para>&array; values need not just be stored values, as &c; arrays
+ have. They can also be computed using its engine. We defer
+ discussion of computing values to the next chapter discussing
+ engines (<xref linkend="engines"></xref>). To avoid being verbose
+ in this chapter, when we discuss stored values, the values might
+ instead be computed.</para>
+
+ <para>Declaring an &array; requires four arguments: the domain's
+ dimensionality, the type of values stored or computed, a
+ specification how the values are stored, and a &domain;. The
+ first three arguments are template parameters since few scientific
+ programs (and no &pooma; programs) need to change these values
+ while a program executes. For example, an &array; cannot change
+ the type of the elements it stores. Alternatively, an &array;'s
+ values can be copied into another &array; having the desired type.
+ Although scientific programs do not frequently change an array's
+ domain, they do frequently request a subset of the array's values,
+ i.e., a <glossterm linkend="glossary-view">view</glossterm>. The
+ subset is specified via a &domain; so it is a run-time value.
+ Views are presented in <xref linkend="views"></xref>.</para>
+
+ <para>An &array;'s first template parameter specifies its
+ dimensionality. This positive
+ integer <varname>&dim;</varname> specifies its rank. This is
+ the same value as its domain's dimensionality. Theoretically, an
+ &array; can have any positive integer, but the &pooma; code
+ currently supports <varname>&dim;</varname> at most seven. For
+ almost all scientific codes, a dimension of three or four is
+ sufficient, but the code can be extended to support higher
+ dimensions.</para>
+
+ <para>An &array;'s second template parameter specifies the type of
+ its stored values. Common value types include ∫, &double;,
+ &complex;, and &vector;, but any type is permissible. For
+ example, an &array;'s values might be matrices or even other
+ &array;s. The parameter's default value is usually &double;, but
+ it may be changed when the &poomatoolkit; is configured.</para>
+
+ <para>An &array;'s third parameter specifies how its data is
+ stored by an &engine; and its values accessed. The argument is a
+ tag indicating a particular type of &engine;. Permissible tags
+ include &brick;, &compressiblebrick;, and
+ <type>ConstantFunction</type>. The &brick; tag indicates all
+ &array; values will be explicitly stored, just as built-in &c;
+ arrays do. If the &array;s frequently stores exactly the same
+ value in every position, a &compressiblebrick; &engine;, which
+ reduces its space requirements to a constant whenever all its
+ values are the same, is appropriate. A
+ <type>ConstantFunction</type> &engine; returns the same value for
+ all indices.</para>
+
+ <para>Even though every &array; container has an engine to store
+ its values and permit access to individual values, an &array; is
+ conceptually separated from engines. An engine's role is
+ low-level, storing values and permitting access to individual
+ values. As we indicated above, the storage can be optimized to
+ fit specific situations such as few nonzero values and computing
+ values using a function applied to another engine's values. An
+ &array;'s role is high-level, supporting access to groups of
+ values. They handle memory allocation and deallocation. &array;s
+ can be used in data-parallel expressions, e.g., adding all the
+ values in one &array; to all the values in another. (See <xref
+ linkend="data_parallel"></xref> for more information.) Subsets of
+ &array; values, frequently used in data-parallel statements, can
+ be obtained. (See <xref linkend="views"></xref> for more
+ information.) Even though engines and &array;s are conceptually
+ separate, higher-level &array;s provide access to lower-level
+ &engine;s. Users usually have an &array; create its &engine;,
+ rarely explicitly creating &engine;s themselves. Also, &array;s
+ provide access to individual values. In short, &pooma; users use
+ &array;s, only dealing with how they are implemented (engines)
+ upon declaration. For more description of &engine;s, see <xref
+ linkend="engines"></xref>.</para>
+
+ <para>The engine parameter's default value is usually &brick;, but
+ it may be changed when the &poomatoolkit; is configured.</para>
+
+ <para>An &array;'s one constructor argument is its domain. The
+ domain specifies its extent and simultaneously how many values it
+ can return. All the provided &domain; objects are combined to
+ yield an <type>Interval<&dim;></type>, where &dim; matches
+ the &array;'s first template parameter. Since an &interval;
+ domain with its unit strides is used, there are no unaccessed
+ <quote>gaps</quote> within the domain, wasting storage space. To
+ use other domains to access an &array;, first create it using an
+ &interval; domain and then take a view of it, as described in
+ <xref linkend="views"></xref>. As we mentioned above, the current
+ &pooma; code supports up to seven dimensions so at most seven
+ &domain; objects can be provided. If more dimensions are
+ required, the &pooma; code can be extended to the desired number
+ of dimensions.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-arrays_declarations-table">
+ <title>Declaring &array;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>&array; declaration</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry>Template parameters <varname>&dim;</varname>,
+ <varname>T</varname>, and <varname>E</varname> indicates the
+ &array;'s dimension, value type, and &engine; type,
+ respectively. <varname>DT1</varname>, …,
+ <varname>DT7</varname> indicate domain types or
+ integers.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Array<&dim;,T,E>()</statement></entry>
+ <entry>creates an empty, uninitialized &array; which must be
+ <methodname>initialize</methodname>()d before use.</entry>
+ </row>
+ <!-- Omit Indirection Array because src/Engine/IndirectionEngine.h indicates it is not yet finished. -->
+ <!-- Omit the two Array<D1,T1,E1> a constructors, which
+ should not be used by users. -->
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1)</statement></entry>
+ <entry>creates an &array; using the given &domain; object or integer.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6, const DT7& t7)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; object or
+ integer and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6, const DT7& t7,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>&array; constructors are listed in <xref
+ linkend="arrays-arrays_declarations-table"></xref>. An &array;s'
+ three template parameters for dimensionality, value type, and
+ engine type are abbreviated <varname>D</varname>,
+ <varname>T</varname>, and <varname>E</varname>. Template
+ parameters for domain types are named <varname>DT1</varname>,
+ …, <varname>DT7</varname>. The first constructor, with no
+ domain arguments, creates an empty, uninitialized &array; for
+ which a domain must be specified before it is used. Specify the
+ array's domain using its <methodname>initialize</methodname> function.
+ The next seven constructors combine their domain arguments to
+ compute the resulting &array;'s domain. These are combined in the
+ same way that multidimensional &interval;s are constructed. (See
+ <xref
+ linkend="arrays-domains_declarations-intervals-multi_d_table"></xref>
+ and the following text.) The domain objects, having types
+ <type>&domaintemplate;1</type>, …,
+ <type>&domaintemplate;7</type>, can have any type that can be
+ converted into an integer, into a single-dimensional &domain;
+ object that can be converted into a single-dimensional &interval;,
+ or to a multidimensional &domain; object that itself can be
+ converted into an &interval;. The total dimensionality of all the
+ arguments' types should
+ <emphasis>equal</emphasis> <varname>&dim;</varname>, unlike
+ &interval; construction which permits total dimensionality less
+ than or equal to <varname>&dim;</varname>. One-dimensional
+ &domain; objects that can be converted into one-dimensional
+ &interval;s include &locone;s, &intervalone;s, and &rangeone;s
+ with unit strides. To initialize all of an &array; values to a
+ specific value, use one of the final seven constructors, each
+ taking a particular value, wrapped as a <type>ModelElement</type>.
+ These constructors use the given domain objects the same way as
+ the preceding constructors but assign <varname>model</varname> to
+ every &array; value. <varname>model</varname>'s type
+ <type>ModelElement<T></type> rather than
+ <varname>T</varname> to differentiate it from an ∫, which can
+ also be used to specify a domain object.
+ <type>ModelElement</type> just stores an element of any type
+ <varname>T</varname>, which must match the &array;'s value
+ type.</para>
+
+ <para>We illustrate creating &array;s. To create a
+ three-dimensional &array; <varname>a</varname> explicitly
+ storing &double; floating-point values, use
+ <programlisting>
+ Interval<1> D(6);
+ Interval<3> I3(D,D,D);
+ Array<3,double,Brick> a(I3);.
+ </programlisting> The template parameters specify its dimensionality,
+ the type of its values, and a &brick; &engine; type, which
+ explicitly stores values. Its domain, which must have three
+ dimensions, is specified by an <type>Interval<3></type>
+ object which consists of a [0,5] intervals for all its three
+ dimensions. Since &double; and &brick; are usually the default
+ template parameters, they can be omitted so these declarations are
+ equivalent:
+ <programlisting>
+ Array<3,double> a_duplicate1(I3);
+ Array<3> a_duplicate2(I3);.
+ </programlisting> To create a similar &array; with a domain of
+ [0:1:1, 0:2:1, 0:0:1], use
+ <programlisting>
+ Array<3> b(2,3,1);.
+ </programlisting> Specifying an integer <varname>i</varname>
+ indicates a one-dimensional zero-based &interval; [0:i-1:1]. To
+ store &bool;s, specify &bool; as the second template argument:
+ <programlisting>
+ Array<2,bool> c(2,3);.
+ </programlisting> To specify a default &array; value of &true;, use
+ <statement>ModelElement<bool>(true)</statement>:
+ <programlisting>
+ Array<2,bool> c(2,3, ModelElement<bool>(true));.
+ </programlisting> To create a one-dimensional &array; containing
+ seven &double;s all equaling π, use
+ <programlisting>
+ Array<1,double,CompressibleBrick> d(7, ModelElement<double>(4.0*atan(1.0)));.
+ </programlisting> We use a &compressiblebrick; &engine;, rather than
+ a &brick; &engine;, so all seven values will be stored once rather
+ than seven times when they are all the same.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-arrays_declarations-initialize_table">
+ <title>Initializing &array;s' Domains</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>An &array;'s <methodname>initialize</methodname> member
+ functions sets its domain and should be invoked only for an
+ array created without a domain. It returns nothing.</entry>
+ </row>
+ <row>
+ <entry><methodname>initialize</methodname> declaration</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry>Template parameters <varname>DT1</varname>, …,
+ <varname>DT7</varname> indicate domain types or
+ integers.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <!-- Omit Indirection Array initialize because it does not exist! -->
+ <!-- Omit the two Array<D1,T1,E1> functions, which should not be used by users. -->
+ <row>
+ <entry><statement>initialize(const DT1& t1)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain;
+ object or integer.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const DT2& t2)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const DT2& t2, const DT3& t3)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6, const DT7& t7)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and integers.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; object and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const DT2& t2,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const DT2& t2, const DT3& t3,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ <row>
+ <entry><statement>initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6, const DT7& t7,
+ const ModelElement<T>& model)</statement></entry>
+ <entry>creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using <varname>model</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>An uninitialized &array;, created using the parameter-less
+ constructor, must have a specified domain before it can be used.
+ For example, one must use the parameter-less &array; constructor
+ when creating an array of &array;s using
+ <keywordname>new</keywordname> (although it would probably be
+ better to create an &array; of &array;s since memory allocation
+ and deallocation would automatically be handled) so their domains
+ must be specified. &array;'s <methodname>initialize</methodname>
+ functions accept the same set of domain object specifications and
+ model elements that the &array; constructors do, creating the
+ specified domain. See <xref
+ linkend="arrays-arrays_declarations-initialize_table"></xref>.
+ For example, both <varname>a</varname> and <varname>b</varname>
+ are two-dimensional &array;s of &float;s with a [2:7:1,-2:4:1]
+ domains:
+ <programlisting>
+ // Create an Array and its domain.
+ Array<2,float,Brick> a(Interval<1>(2,7), Interval<1>(-2,4));
+ // Create an Array without a domain and then specify its domain.
+ Array<2,float,Brick> b();
+ b.initialize(Interval<1>(2,7), Interval<1>(-2,4));.
+ </programlisting> Invoking <methodname>initialize</methodname> on an
+ &array; with an existing domain is unspecified. All &array;
+ values may be lost and memory may be leaked.</para>
+ </section>
+
+
+ <section id="arrays-arrays_use">
+ <title>Using &array;s</title>
+
+ <para>In the previous section, we explained how to declare and
+ initialize &array;s. In this section, we explain how to access
+ individual values stored within an &array; and how to copy
+ &array;s. In <xref linkend="data_parallel"></xref>, we explain
+ how to use entire &array;s in data-parallel statements, including
+ how to print them. In <xref linkend="views"></xref>, we extend
+ this capability to work on subsets.</para>
+
+ <para>In its simplest form, an &array; stores individual values,
+ permitting access to these values. For a &cc; array, the desired
+ index is specified within square brackets following the array's
+ name. For &pooma; &array;s, the desired index is specified
+ within parentheses following the &array;'s name. The same
+ notation is used to read and write values. For example, the
+ following code prints the initial value at index (2,-2) and
+ increments its value, printing the new value:
+ <programlisting>
+ Array<2,int,Brick> a(Interval<1>(0,3), Interval<1>(-2,4),
+ ModelElement<int>(4));
+ std::cout &openopen; a(2,-2) &openopen; std::endl;
+ ++a(2,-2);
+ std::cout &openopen; a(2,-2) &openopen; std::endl;
+ </programlisting> <computeroutput>4</computeroutput> and then
+ <computeroutput>5</computeroutput> are printed. An index
+ specification for an &array; usually has as many integers as
+ dimensions, all separated by commas, but the &array;'s engine may
+ permit other notation such as using strings or floating-point
+ numbers.</para>
+
+ <para>For read-only access to a value, use the
+ <methodname>read</methodname> member function, which takes the
+ same index notation as its nameless read-write counterpart:
+ <programlisting>
+ std::cout &openopen; a.read(2,-2) &openopen; std::endl;
+ </programlisting> Using <methodname>read</methodname> sometimes
+ permits the optimizer to produce faster executing code.</para>
+
+ <example id="arrays-arrays_use-copy_example">
+ <title>Copying &array;s</title>
+ &array-copy;
+ </example>
+
+ <para>Copying &array;s requires little execution time because they
+ have reference semantics. That is, a copy of an &array; and the
+ &array; itself share the same underlying data. Changing a value
+ in one changes it in the other. <xref
+ linkend="arrays-arrays_use-copy_example"></xref> illustrates this
+ behavior. Initially, all values in the array <varname>a</varname>
+ are 4. The <varname>b</varname> array is initialized using
+ <varname>a</varname> so it shares the same values as
+ <varname>a</varname>. Thus, changing the former's value also
+ changes the latter's value. Function arguments are also
+ initialized so changing their underlying values also changes the
+ calling function's values. For example, the
+ <function>changeValue</function> function changes the value with
+ index (0,0) of both its function argument
+ and <varname>a</varname>.</para>
+
+ <para>The separation between a higher-level &array; and its
+ lower-level &engine; storage permits fast copying. An &array;'s
+ only data member is its engine, which itself has reference
+ semantics that increments a reference-counted pointer to its data.
+ Thus, copying an &array; requires creating a new object with one
+ data member and incrementing a pointer's reference count.
+ Destruction is similarly inexpensive.</para>
+
+ <para>Array assignment does not have reference semantics. Thus,
+ the assignment <statement>a = b</statement> ensures that all of
+ <varname>a</varname>'s values are the same as <varname>b</varname>
+ at the time of assignment only. Subsequent changes to
+ <varname>a</varname>'s values do not change <varname>b</varname>'s
+ values or vice versa.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-arrays_use-compile_time_table">
+ <title>&array; Internal Type Definitions and Compile-Time Constants</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>internal type or compile-time constant</entry>
+ <entry>meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><type>This_t</type></entry>
+ <entry>the &array;'s type <type>Array<&dim;,T,E></type>.</entry>
+ </row>
+ <row>
+ <entry><type>Engine_t</type></entry>
+ <entry>the &array;'s &engine; type <type>Engine<&dim;,T,E></type>.</entry>
+ </row>
+ <row>
+ <entry><type>EngineTag_t</type></entry>
+ <entry>the &array;'s &engine;'s tag <varname>E</varname>.</entry>
+ </row>
+ <row>
+ <entry><type>Element_t</type></entry>
+ <entry>the type <varname>T</varname> of values stored in the &array;.</entry>
+ </row>
+ <row>
+ <entry><type>ElementRef_t</type></entry>
+ <entry>the type of references to values stored in the &array;
+ (usually <type>T&</type>).</entry>
+ </row>
+ <row>
+ <entry><type>Domain_t</type></entry>
+ <entry>the type of the &array;'s domain.</entry>
+ </row>
+ <row>
+ <entry><type>Layout_t</type></entry>
+ <entry>the type of the &array;'s layout.</entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname>dimensions</varname></fieldsynopsis></entry>
+ <entry>the number &dim; of dimensions of the &array;.</entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname>rank</varname></fieldsynopsis></entry>
+ <entry>synonym for <varname>dimensions</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The &array; class has internal type definitions and
+ constants useful for both compile-time and run-time computations.
+ See <xref linkend="arrays-arrays_use-compile_time_table"></xref>.
+ These may be accessed using the &array;'s type and the scope
+ resolution operator (<operator>::</operator>). The table begins
+ with a list of internal type definitions, e.g.,
+ <statement>Array<&dim;,T,E>::Domain_t</statement>. Member
+ functions use some of these types. A <glossterm
+ linkend="glossary-layout">layout</glossterm> maps a domain index
+ to a particular processor and memory used to compute the
+ associated value.<!-- FIXME: Add a reference to the corresponding
+ chapter. --> The two internal enumerations
+ <fieldsynopsis><varname>dimensions</varname></fieldsynopsis> and
+ <fieldsynopsis><varname>rank</varname></fieldsynopsis> both record
+ the &array;'s dimension.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-arrays_use-accessor_table">
+ <title>&array; Accessors</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>&array; member function</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry>Internal type definitions, e.g., <type>Domain_t</type>,
+ are listed without a class type prefix
+ <statement>Array<&dim;,T,E>::</statement>.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>Domain_t domain()</statement></entry>
+ <entry>returns the &array;'s domain.</entry>
+ </row>
+ <row>
+ <entry><statement>Domain_t physicalDomain()</statement></entry>
+ <entry>returns the &array;'s domain.</entry>
+ </row>
+ <row>
+ <entry><statement>Domain_t totalDomain()</statement></entry>
+ <entry>returns the &array;'s domain.</entry>
+ </row>
+ <row>
+ <entry><statement>int first(int dim)</statement></entry>
+ <entry>returns the first (smallest) index value for the
+ specified dimension.</entry>
+ </row>
+ <row>
+ <entry><statement>int last(int dim)</statement></entry>
+ <entry>returns the last (largest) index value for the
+ specified dimension.</entry>
+ </row>
+ <row>
+ <entry><statement>int length(int dim)</statement></entry>
+ <entry>returns the number of indices (including endpoints) for
+ the specified dimension.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<Dim> firsts()</statement></entry>
+ <entry>returns the first (smallest) index values for all the
+ dimensions.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<Dim> lasts()</statement></entry>
+ <entry>returns the last (largest) index values for all the
+ specified dimensions.</entry>
+ </row>
+ <row>
+ <entry><statement>Loc<Dim> lengths()</statement></entry>
+ <entry>returns the numbers of indices (including endpoints)
+ for all the specified dimensions.</entry>
+ </row>
+ <row>
+ <entry><statement>long size()</statement></entry>
+ <entry>returns the total number of indices in the domain.</entry>
+ </row>
+ <row>
+ <entry><statement>Layout_t layout()</statement></entry>
+ <entry>returns the &array;'s domain.</entry>
+ </row>
+ <row>
+ <entry><statement>Engine_t engine()</statement></entry>
+ <entry>returns the &array;'s engine.</entry>
+ </row>
+ <row>
+ <entry><statement>const Engine_t engine()</statement></entry>
+ <entry>returns the &array;'s engine.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The &array; class has several member functions easing access
+ to its domain and engine. The first ten functions listed in <xref
+ linkend="arrays-arrays_use-accessor_table"></xref> ease access to
+ &array; domains. The first three functions are synonyms all
+ returning the &array;'s domain, which has type
+ <type>Array<&dim;,T,E>::Domain_t</type>, abbreviated
+ <type>Domain_t</type> in the table. The next seven functions
+ query the domain. <methodname>first</methodname>,
+ <methodname>last</methodname>, and <methodname>length</methodname>
+ return the smallest, largest, and number of indices for the
+ specified dimension. The domain's dimensions are numbered 0, 1,
+ …,
+ <statement>Array<&dim;,T,E>::dimensions</statement>-1. If
+ these values are needed for all dimensions, use
+ <methodname>firsts</methodname>, <methodname>lasts</methodname>,
+ and <methodname>lengths</methodname>. The returned
+ <type>Loc<&dim;></type>s have &dim; entries, one for each
+ dimension. <methodname>size</methodname> returns the total number
+ of indices in the entire domain. This is the product of all the
+ dimensions' <methodname>length</methodname>s. The
+ <methodname>layout</methodname> member function returns the
+ &array;'s layout, which specifies the mapping of indices to
+ processors and memory.<!-- FIXME: Add a reference to the
+ corresponding chapter. --> The last two functions return the
+ &array;'s engine.</para>
+
+ <example id="arrays-arrays_use-members_example">
+ <title>Using &array; Member Functions</title>
+ &array-size;
+ <calloutlist>
+ <callout arearefs="arrays-arrays_use-members-example-compare_size">
+ <para>The <methodname>size</methodname> is invoked by
+ prepending the &array;'s name followed by a period. This
+ assertion is unnecessary, but the
+ <function>computeArraySize</function> function further
+ illustrates using member functions.</para>
+ </callout>
+ <callout arearefs="arrays-arrays_use-members-example-template_parameters">
+ <para>These template parameters, used in the &array;
+ parameter's type, permit the function to work with any
+ &array;.</para>
+ </callout>
+ <callout arearefs="arrays-arrays_use-members-example-function_call">
+ <para>We invoke these three member functions using the
+ &array;'s name <varname>a</varname>, a period, and the
+ functions' names. These functions return &loc;s.</para>
+ </callout>
+ <callout arearefs="arrays-arrays_use-members-example-loc_use">
+ <para><statement>lens[d]</statement> returns a
+ <type>Loc<1></type> for
+ dimension <varname>d</varname>'s length. Invoking
+ <type>Loc<1></type> <methodname>first</methodname>method
+ yields its value.</para>
+ </callout>
+ <callout arearefs="arrays-arrays_use-members-example-check_length">
+ <para>This comparison is unnecessary but further illustrates
+ using member functions.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>We illustrate using &array; member functions in <xref
+ linkend="arrays-arrays_use-members_example"></xref>. The program
+ computes the total number of &array;'s indices, comparing the
+ result with invoking its <methodname>size</methodname> method.
+ Since the &array;'s name is <varname>a</varname>,
+ <statement>a.size()</statement> returns its size.
+ <function>computeArraySize</function> also computes the &array;'s
+ size. This templated function uses its three template parameters
+ to accept any &array;, regardless of its dimension, value type, or
+ &engine; tag. It begins by obtaining the range of indices for all
+ dimensions and their lengths. Only the latter is necessary for
+ the computation, but the former further illustrate using member
+ functions. The domain's size is the product of the length of each
+ dimension. Since the lengths are stored in the
+ <type>Loc<&dim></type> <varname>lens</varname>,
+ <statement>lens[d]</statement> is a <type>Loc<1></type>, for
+ which its <methodname>first</methodname> extracts the length. The
+ <methodname>length</methodname> &array; member function is used in
+ the <function>PAssert</function>.</para>
+ </section>
+
+
+ <section id="arrays-doof2d">
+ <title>An &array; Implementation of &doof2d;</title>
+
+ <para>mostly copy pp.35-38 from tutorial chapter<!-- UNFINISHED --></para>
+ </section>
+
+
+ <section id="arrays-implementation">
+ <title>Implementing &array;s</title>
+
+ <para>What to write?<!-- UNFINISHED -->
+
+ Do I need to describe the public interface of Domains? Do I need
+ to describe how a programmer would implement a new type of domain?
+ Probably not.</para>
+ </section>
+
+ </chapter>
Index: concepts.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/concepts.xml,v
retrieving revision 1.5
diff -c -p -r1.5 concepts.xml
*** concepts.xml 2002/01/14 17:33:33 1.5
--- concepts.xml 2002/01/16 00:48:35
***************
*** 134,140 ****
<row>
<entry><glossterm
linkend="glossary-array">&array;</glossterm></entry>
! <entry>container mapping indices to values and that may be
used in expressions</entry>
</row>
<row>
--- 134,140 ----
<row>
<entry><glossterm
linkend="glossary-array">&array;</glossterm></entry>
! <entry>container mapping <glossterm linkend="glossary-index">indices</glossterm> to values and that may be
used in expressions</entry>
</row>
<row>
***************
*** 146,152 ****
</row>
<row>
<entry><glossterm linkend="glossary-field">&field;</glossterm></entry>
! <entry>container mapping indices to one or more values and
residing in multi-dimensional space</entry>
</row>
<row>
--- 146,152 ----
</row>
<row>
<entry><glossterm linkend="glossary-field">&field;</glossterm></entry>
! <entry>container mapping <glossterm linkend="glossary-index">indices</glossterm> to one or more values and
residing in multi-dimensional space</entry>
</row>
<row>
***************
*** 172,178 ****
<para>A &pooma; <glossterm
linkend="glossary-array">&array;</glossterm> generalizes a &c; array
! and maps indices to values. Given an index or position in an
&array;'s domain, it returns the associated value, either by
returning a stored value or by computing it. The use of indices,
which are usually ordered tuples, permits constant-time access
--- 172,178 ----
<para>A &pooma; <glossterm
linkend="glossary-array">&array;</glossterm> generalizes a &c; array
! and maps <glossterm linkend="glossary-index">indices</glossterm> to values. Given an index or position in an
&array;'s domain, it returns the associated value, either by
returning a stored value or by computing it. The use of indices,
which are usually ordered tuples, permits constant-time access
***************
*** 350,356 ****
<para>A <glossterm
linkend="glossary-layout"><firstterm>layout</firstterm></glossterm>
! maps <link linkend="glossary-domain">domain</link> indices to the
processors and computer memory used by a container's engines. See
<xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
--- 350,356 ----
<para>A <glossterm
linkend="glossary-layout"><firstterm>layout</firstterm></glossterm>
! maps <link linkend="glossary-domain">domain</link> <glossterm linkend="glossary-index">indices</glossterm> to the
processors and computer memory used by a container's engines. See
<xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
Index: manual.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/manual.xml,v
retrieving revision 1.6
diff -c -p -r1.6 manual.xml
*** manual.xml 2002/01/14 17:33:34 1.6
--- manual.xml 2002/01/16 00:48:38
***************
*** 15,21 ****
<!ENTITY book "book">
<!-- Produce a notation for the book/manual/report/WWW page. -->
<!-- Modify this to the desired noun. -->
! <!ENTITY bookCap "Book">
<!-- Produce a capitalized version of &book; -->
<!-- Modify this to the desired noun. -->
<!ENTITY c "<application class='software'>C</application>">
--- 15,21 ----
<!ENTITY book "book">
<!-- Produce a notation for the book/manual/report/WWW page. -->
<!-- Modify this to the desired noun. -->
! <!ENTITY bookcap "Book">
<!-- Produce a capitalized version of &book; -->
<!-- Modify this to the desired noun. -->
<!ENTITY c "<application class='software'>C</application>">
***************
*** 32,37 ****
--- 32,39 ----
<!-- Produce a notation for ">>>", which infrequently occurs with templates. Without this, TeX produces a shift symbol. -->
<!ENTITY dashdash "-⪆-" >
<!-- Produce a notation for a double dash. Without this, TeX produces an en-hyphen. -->
+ <!ENTITY dim "D">
+ <!-- the number of dimensions of an array, domain, etc. -->
<!ENTITY doof2d "<command>Doof2d</command>" >
<!-- Produce a notation for the Doof2d program. -->
<!ENTITY fortran "<application class='software'>Fortran</application>">
***************
*** 89,94 ****
--- 91,98 ----
<!-- The DistributedTag Layout type. -->
<!ENTITY domain "<type>Domain</type>">
<!-- The "Domain" type. -->
+ <!ENTITY domaintemplate "DT">
+ <!-- A domain template parameter. -->
<!ENTITY double "<type>double</type>">
<!-- The C "double" type. -->
<!ENTITY dynamicarray "<type>DynamicArray</type>">
***************
*** 100,105 ****
--- 104,111 ----
<!-- Modify its tag to the appropriate one. -->
<!ENTITY field "<type>Field</type>">
<!-- The "Field" type. -->
+ <!ENTITY float "<type>float</type>">
+ <!-- The C "float" type. -->
<!ENTITY grid "<type>Grid</type>">
<!-- The "Grid" domain type. -->
<!ENTITY gridone "<type>Grid<1></type>">
***************
*** 193,198 ****
--- 199,206 ----
<!-- formatting: for sets, no spaces between brackets and entries but spaced between entries -->
<!-- External Chapters -->
+ <!ENTITY arrays-chapter SYSTEM "arrays.xml">
+ <!-- Pooma Arrays chapter -->
<!ENTITY bibliography-chapter SYSTEM "bibliography.xml">
<!-- bibliography -->
<!ENTITY concepts-chapter SYSTEM "concepts.xml">
***************
*** 228,233 ****
--- 236,245 ----
<!-- Sequential Programs -->
<!ENTITY initialize-finalize SYSTEM "./programs/examples/Sequential/initialize-finalize-annotated.cpp">
<!-- Illustrate initialize() and finalize(). -->
+ <!ENTITY array-copy SYSTEM "./programs/examples/Sequential/array-copy-annotated.cpp">
+ <!-- Illustrate Array reference semantics. -->
+ <!ENTITY array-size SYSTEM "./programs/examples/Sequential/array-size-annotated.cpp">
+ <!-- Illustrate Array member functions. -->
<!-- Template Programs -->
<!ENTITY pairs-untemplated SYSTEM "./programs/examples/Templates/pairs-untemplated-annotated.cpp">
***************
*** 285,291 ****
<section id="preface-reading_book:">
! <title>How to Read This &bookCap;</title>
<para>FINISH: Write this section in a style similar to Lamport's
LaTeX section 1.2. FINISH: Fix the book title and the section
--- 297,303 ----
<section id="preface-reading_book:">
! <title>How to Read This &bookcap;</title>
<para>FINISH: Write this section in a style similar to Lamport's
LaTeX section 1.2. FINISH: Fix the book title and the section
***************
*** 338,1581 ****
&tutorial-chapter;
&concepts-chapter;
-
-
- <chapter id="arrays">
- <title>&array; Containers</title>
-
- <para>A container is a class holding objects. &array;s are one of
- the two most widely used &pooma; containers since they model the
- mathematical concept of mapping indices from domains to values.
- &pooma; &array;s extend built-in &cc; arrays by supporting a wider
- variety of domains, automatically handling memory allocations, and
- supporting first-class status. For example, they may be used as
- operands and in assignments. In this chapter, we introduce the
- concept of containers, the mathematical concept of arrays, and the
- &pooma; concept for &array;s. Before illustrating how to declare
- &array;s, we introduce &domain;s, which specify the sets of
- indices. After describing how to declare the various types of
- &domain;s, we describe how to declare and use &array;s. This is
- illustrated in a &doof2d; implementation using &array;s. We end
- with a description of their implementation.</para>
-
-
- <section id="arrays-containers">
- <title>Containers</title>
-
- <para>A <glossterm
- linkend="glossary-container"><firstterm>container class
- expression</firstterm></glossterm> is a class with the main
- purpose of holding objects. These stored objects, called
- <glossterm linkend="glossary-container_value"><firstterm>container
- values</firstterm></glossterm> or more simply
- <quote>values</quote> or elements<quote></quote>, may be accessed
- and changed, usually using indices. <quote>Container
- class</quote> is usually abbreviated
- <quote>container</quote>.</para>
-
- <para>The six &pooma; containers can be categorized into two
- groups. Mathematical containers include &tensor;s, &matrix;s, and
- &vector;s, modeling tensors, matrices, and vectors, respectively.
- Storage containers include &array;s, &dynamicarray;s, and
- &field;s. In this chapter, we focus on simplest of these:
- &array;s. The other containers will be described in subsequent
- chapters.</para>
-
- <para>&c; has built-in arrays, and the &cc; Standard Library
- provides <type>map</type>s, <type>vector</type>s,
- <type>stack</type>s, and other containers, but the &pooma;
- containers better model scientific computing concepts and provide
- more functionality. They automatically handle memory allocation
- and deallocation and can be used in expressions and on the
- left-hand side of assignments. Since &pooma; containers separate
- the container concepts of accessing and using values from storing
- values, value storage can be optimized to specific needs. For
- example, if most of an &array;'s values are known to be the same
- most of the time, a compressible engine can be used. Whenever all
- the array's values are the same, it stores only one value. At
- other times, it stores all the values. Engines will be discussed
- in <xref linkend="engines"></xref>.</para>
- </section>
-
-
- <section id="arrays-arrays">
- <title>&array;s</title>
-
- <para>Mathematically, an array maps indices from a domain to
- values. Usually, the domain consists of a one-dimensional
- integral interval or it may be multidimensional. &pooma;'s
- &array; container class implements this idea. Given an index,
- i.e., a position in an &array;'s &domain;, it returns the associated
- value, either by returning a stored value or by computing it. The
- use of indices, which are usually integral tuples but need not be
- zero-based or even consist of all possible integral tuples in a
- multidimensional range. Using indices permits constant-time
- access to values although computing a particular value may require
- significant time.</para>
-
- <para>&pooma; &array;s are <glossterm
- linkend="glossary-first_class">first-class
- types<firstterm></firstterm></glossterm> so they can be used more
- widely than built-in &cc; arrays. For example, &array;s can be
- used as operands and in assignment statements. The statement
- <statement>a = a + b;</statement> adds corresponding elements of
- &array;s <varname>a</varname> and <varname>b</varname>, assigning
- the sums to the &array; <varname>a</varname>. The statement
- treats each array as one object, rather than requiring the use of
- one or more loops to access individual values. Data-parallel
- statements are further discussed in <xref
- linkend="data_parallel"></xref>. &array;s also handle their own
- memory allocation and deallocation. For example, the &array;
- declaration <statement>Array<2, double, Brick>
- a(vertDomain)</statement> creates an
- &array; <varname>a</varname>, allocating whatever memory it
- needs. When <varname>a</varname> goes out of scope, it and its
- memory is automatically deallocated. Automatic memory allocation
- and deallocation also eases copying. As we mentioned above, an
- &array;'s &engine; stores or computes its values so it, not the
- &array; itself, is responsible for memory allocation and
- deallocation. Fortunately, this distinction is usually hidden
- from the &pooma; user.</para>
-
- <para>Individual &array; values can be accessed using parentheses,
- not square brackets, as for &cc; arrays. For example,
- <statement>a(3,4)</statement> yields the value at position (3,4)
- of <varname>a</varname>'s two-dimensional domain.</para>
- </section>
-
-
- <section id="arrays-domains">
- <title>&domain;s</title>
-
- <para>A <glossterm
- linkend="glossary-domain"><firstterm>domain</firstterm></glossterm>
- specifies the set of points on which an &array; can define values.
- These indices are the arguments placed within parentheses when
- selecting particular values, as described previously. A domain
- supported both by &array;s and by built-in &cc; arrays is an
- interval [0,n-1] of integers containing all integers {0, 1, 2,
- …, n-1}. For &cc;, every integer in the interval must be
- included, and the minimum index must be zero. &pooma; expands the
- set of permissible domains to support intervals with nonzero
- minimal indices and strides and by adding other choices.</para>
-
- <para>In &pooma;, &domain;s implement domains. There are four
- different categories:
- <variablelist>
- <varlistentry>
- <term>&loc;</term>
- <listitem>
- <para>&domain; with a single point.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>&interval;</term>
- <listitem>
- <para>&domain; with an integral interval [a,b].</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>⦥</term>
- <listitem>
- <para>&domain; with an integral interval [a,b] and an integral
- stride s indicating the gap between indices: {a, a+s,
- a+2s, …, b}.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>&grid;</term>
- <listitem>
- <para>&domain; with an ascending or descending sequence of
- integral values. The sequence elements must be individually
- specified.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- One-dimensional and multidimensional versions of each categories
- are supported. A multidimensional &domain; consists of the direct
- product of one-dimensional &domain;s. For example, the first
- dimension of a two-dimensional interval [0,3]x[2,9] is the
- interval [0,3], and its second dimension is the
- interval [2,9]. Its indices are ordered pairs such as (0,2),
- (0,3), (1,2), (1,9), and (3,7).</para>
-
- <para>Many domains can be represented using domain triplets. A
- <glossterm linkend="glossary-domain_triplet"><firstterm>domain
- triplet</firstterm></glossterm>
- [<varname>begin</varname>:<varname>end</varname>:<varname>stride</varname>]
- represents the mathematical set {begin, begin + stride, begin +
- 2stride, …, end}, where <varname>end</varname> is in the
- set only if it equals <varname>begin</varname> plus some integral
- multiple of <varname>stride</varname>. If the
- <varname>stride</varname> is negative, its beginning index
- <varname>begin</varname> should at least be as large as
- <varname>end</varname> if the interval is to be nonempty. The
- stride can be zero only if <varname>begin</varname> and
- <varname>end</varname> are equal. There are lots of ways to
- represent an empty interval, e.g., [1:0:1] and [23,34,-1], and
- &pooma; will accept them, but they are all equivalent. The domain
- triplet notation is easily extended to multiple dimensions by
- separating different dimension's intervals with commas. For
- example, [2:4:2,6:4:-2] contains (2,6), (2,4), (4,6),
- and (4,4).</para>
-
- <para>All the &domain; categories listed above except &grid; can be
- represented using domain triplet notation. Since the triplet
- [7:7:1] represents {7}, or more simply 7, it can also
- represent <statement>Loc<1>(7)</statement>. Multidimensional
- &loc;s are similarly represented. For example,
- [0:0:1,10:10:1,2:2:1] represents
- <statement>Loc<3>(0,10,2)</statement>, but it is frequently
- abbreviated as [0,10,2]. An &interval; [a,b] has unit stride:
- [a:b:1], while a ⦥ has specific stride s:
- [a:b:s].</para>
-
- <para>&domain;s can be constructed by combining &domain;s of smaller
- dimension. For example, since a two-dimensional &interval; is the
- direct product of two one-dimensional &interval;s, it can be
- specified using two one-dimensional &interval;s. For example,
- <statement>Interval<2>(Interval<1>(2,3),
- Interval<1>(4,5))</statement> creates a [2:3:1,4:5:1]
- &domain;. The resulting dimensionality equals the sum of the
- components' dimensions. For example, a four-dimension &loc; can
- be specified using three- and one-dimension &loc;s or using four
- one-dimension &loc;s. If fewer dimensions than the created
- object's dimensionality, the last dimensions are unspecified and
- uninitialized. &loc;s, &interval;s, ⦥s, and &grid;s can all
- be composed from smaller similar components.</para>
-
- <para>A &domain; can be composed from smaller components with
- different types. A &loc; object can be constructed from other
- &loc; objects and integers. &interval;s, ⦥s, and &grid;s
- can be constructed using any of these types, &loc;s, and integers.
- For example, <statement>Interval<3> a(Loc<2>(1,2),
- Interval<1>(3,5))</statement> uses a two-dimensional &loc;
- and a one-dimensional &interval; to create a [1:1:1,2:2:1,3:5:1]
- &domain;. During creation of a &domain;, the type of each object
- is changed to the &domain;'s type. In the example,
- <statement>Loc<2>(1,2)</statement> is first converted to an
- &interval;.</para>
-
- <para>&domain;s can participate in some arithmetic and comparison
- operations. For example, a &domain;'s triplet can be shifted two
- units to the right by adding two. Multiplying a &domain; by two
- multiplies its triplet's beginnings, endings, and strides by two.
- &pooma; users rarely need to compare &domain;s, but we describe
- operating with the less-than operator on &interval;s. &interval;
- <varname>d1</varname> < &interval; <varname>d2</varname> if the
- length of <varname>d1's</varname> interval is less than
- <varname>d2</varname>'s or, if equal, its beginning value is
- smaller. &domain; arithmetic is frequently used with data-parallel
- statements and container views. These will be discussed in <xref
- linkend="data_parallel"></xref> and <xref
- linkend="views"></xref>.</para>
-
- <para>The current &pooma; implementation supports &domain;s with
- dimensionality between one and seven, inclusive. Since most
- scientific computations use one, two, or three dimensions, this is
- usually sufficient. If more dimensions are needed, they can be
- added to the source code.</para>
- </section>
-
! <section id="arrays-domains_declarations">
! <title>Declaring &domain;s</title>
- <para>Since &domain;s are mainly used to declare container
- domains, we focus on declaring &domain;s. Arithmetic operations
- with &domain;s are described in <xref
- linkend="views"></xref>.</para>
-
- <para>All &domain; declarations require a dimension template
- parameter <varname>&dim;</varname>. This positive integer
- specifies the number of dimensions, i.e., rank, of the &domain; and
- determines the length of the tuples for points in the &domain;. For
- example, a three-dimensional &domain; contains ordered triples,
- while a one-dimensional &domain; contains singletons, or just
- integers. Multidimensional &domain;s are just the direct products
- of one-dimensional &domain;s so the techniques for declaring
- one-dimensional &domain;s carry over to multi-dimensional
- ones.</para>
-
- <para>To declare a &domain;, one must include the
- <filename class="headerfile">Pooma/Domains.h</filename> header
- file. However, most &pooma; programs declare &domain;s to use them
- when constructing containers. The container header files
- automatically include <filename
- class="headerfile">Pooma/Domains.h</filename> so no explicit
- inclusion is usually necessary.</para>
-
- <section id="arrays-domains_declarations-loc">
- <title>&loc;s</title>
-
- <para>A <type>Loc<&dim;></type> is a &domain; with just a single
- <varname>&dim;</varname>-dimensional point. Although it is
- infrequently used as a container's domain, it is used to refer to
- a single point within another domain. Its beginning and ending
- points are the same, and its stride is one. One-dimensional
- &loc;s and integers are frequently interchanged.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-loc-one_d_table">
- <title>Declaring One-Dimensional &loc;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>T1</varname>, <varname>T2</varname>, and
- <varname>T3</varname> are template parameters.</entry>
- <entry></entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Loc<1>()</statement></entry>
- <entry>points to zero.</entry>
- </row>
- <row>
- <entry><statement>Loc<1>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an uninitialized &locone;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Loc<1>(const T1& t1)</statement></entry>
- <entry>creates a &locone; with the integer converted from <varname>t1</varname>.</entry>
- </row>
- <row>
- <entry><statement>Loc<1>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &locone; with the integer converted from
- <varname>t1</varname>. <varname>t2</varname> must equal
- <varname>t1</varname>.</entry>
- </row>
- <row>
- <entry><statement>Loc<1>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &locone; with the integer converted from
- <varname>t1</varname>. <varname>t2</varname> must equal
- <varname>t1</varname>, and <varname>t3</varname> is
- ignored.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for one-dimensional &loc;s appear in <xref
- linkend="arrays-domains_declarations-loc-one_d_table"></xref>.
- The empty constructor yields the zero point. The constructor
- taking a <type>Pooma::Init</type> object does not initialize the
- resulting &loc; to any particular value. Presumably, the value
- will be assigned later. For small &domain;s such as &loc;s, the
- time savings from not initializing is small, but the
- functionality is still available. The constructor taking one
- argument with type <type>T1</type> converts this argument to
- an integer to specify the point. The template
- type <type>T1</type> may be any type that can be converted
- to an integer, e.g., &bool;, &char;, ∫, or &double;. The
- constructors taking two and three arguments of templatized types
- facilitate converting an &interval; and a ⦥ into a &loc;.
- Since a &loc; represents a single point, the &interval;'s or
- ⦥'s first two arguments must be equal. The stride is
- ignored. Again, the templatized types may be any type that can
- be converted into an integer.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-loc-multi_d_table">
- <title>Declaring Multidimensional &loc;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>&dim;</varname> indicates the &loc;'s dimension.
- <varname>T1</varname>, <varname>T2</varname>, … are
- template parameters.</entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Loc<&dim;>()</statement></entry>
- <entry>points to zero.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an uninitialized &loc;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1)</statement></entry>
- <entry>creates a &loc; using the given &domain; object.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)</statement></entry>
- <entry>creates a &loc; using the given &domain; objects.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for multidimensional &loc;s appear in <xref
- linkend="arrays-domains_declarations-loc-multi_d_table"></xref>.
- <varname>&dim;</varname> indicates the &loc;'s dimension. The
- first two constructors are similar to &locone;'s first two
- constructors, returning a representation of the zero point and
- returning an uninitialized point. The seven other constructors
- create a &loc; using other &domain; objects. These &domain; objects,
- having types <type>T1</type>, …, <type>T7</type>, can have
- any type that can be converted into an integer, to a &locone;, or
- to a multidimensional &domain; object that itself can be converted
- into a &loc;. The total dimensionality of all the arguments'
- types should be at most <varname>&dim;</varname>. For example,
- <statement>Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
- Interval<1>(4,4))</statement> creates a five-dimensional &loc;
- [2,2,3,4,1] using a one-dimensional ⦥, a two-dimensional
- &loc;, and a one-dimensional &interval;. The final fifth
- dimension has an unspecified value, in this case 1. The
- one-dimensional ⦥ is converted into the single integer two;
- its beginning and ending points must be the same. The
- two-dimensional &loc; contributes values for the next two
- dimensions, while the &interval; contributes its beginning point,
- which must be the same as its ending point. Note that the
- &locone; constructors taking two and three parameters ignore
- their second and third arguments, but this is not true for the
- multidimensional constructors.</para>
- </section>
-
-
- <section id="arrays-domains_declarations-intervals">
- <title>&interval;s</title>
-
- <para>A one-dimensional &interval; represents a set of integers
- within a mathematical <glossterm
- linkend="glossary-interval">interval</glossterm>.
- Multidimensional &interval;s represent their multidimensional
- generalization, i.e., the direct product of one-dimensional
- intervals. &interval;s are arguably the most commonly used
- &pooma; &domain;. A one-dimensional &interval; has integral
- beginning and ending points and a unit stride.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-interval-one_d_table">
- <title>Declaring One-Dimensional &interval;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>T1</varname>, <varname>T2</varname>, and
- <varname>T3</varname> are template parameters.</entry>
- <entry></entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Interval<1>()</statement></entry>
- <entry>creates an empty, uninitialized interval.</entry>
- </row>
- <row>
- <entry><statement>Interval<1>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an uninitialized &intervalone;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Interval<1>(const T1& t1)</statement></entry>
- <entry>creates a &intervalone;. See the text for an explanation.</entry>
- </row>
- <row>
- <entry><statement>Interval<1>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &intervalone; with the integers converted from
- <varname>t1</varname> and <varname>t2</varname>.</entry>
- </row>
- <row>
- <entry><statement>Interval<1>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &intervalone; with the integers converted from
- <varname>t1</varname> and <varname>t2</varname>.
- <varname>t3</varname> must equal 1.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>&intervalone; constructors are patterned on &locone;
- constructors except that &intervalone;s can have differing
- beginning and ending points. See <xref
- linkend="arrays-domains_declarations-interval-one_d_table"></xref>.
- The default constructor creates an empty, uninitialized interval,
- which should not be used before assigning it values. If the
- one-parameter constructor's argument is a &domain; object, it must
- be a one-dimensional &domain; object which is copied into an
- &interval; if possible; for example, it must have unit stride.
- If the one-parameter constructor's argument is not a &domain;
- object, it must be convertible to an
- integer <varname>e</varname> and an interval [0:e-1:1]
- starting at zero is constructed. If two arguments are specified,
- they are assumed to be convertible to integers
- <varname>b</varname> and <varname>e</varname>, specifying the
- interval [b:e:1]. The three-parameter constructor is similar,
- with the third argument specifying a stride, which must be
- one.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-intervals-multi_d_table">
- <title>Declaring Multidimensional &interval;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>&dim;</varname> indicates the &interval;'s dimension.
- <varname>T1</varname>, <varname>T2</varname>, … are
- template parameters.</entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Interval<&dim;>()</statement></entry>
- <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1)</statement></entry>
- <entry>creates a &interval; using the given &domain; object.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)</statement></entry>
- <entry>creates a &interval; using the given &domain; objects.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for multidimensional &interval;s closely
- follow constructors for multidimensional &loc;s. See <xref
- linkend="arrays-domains_declarations-intervals-multi_d_table"></xref>.
- <varname>&dim;</varname> indicates the &interval;'s dimension.
- The first two constructors both return empty, uninitialized
- intervals. The seven other constructors create an &interval;
- using &domain; objects. These &domain; objects, having types
- <type>T1</type>, …, <type>T7</type>, can have any type
- that can be converted into an integer, into a single-dimensional
- &domain; object that can be converted into a single-dimensional
- &interval;, or to a multidimensional &domain; object that itself
- can be converted into an &interval;. The total dimensionality of
- all the arguments' types should be at
- most <varname>&dim;</varname>. One-dimensional &domain; objects
- that can be converted into one-dimensional &interval;s include
- &locone;s, &intervalone;s, and &rangeone;s with unit strides. If
- the sum of the objects' dimensions is less
- than <varname>&dim;</varname>, the intervals for the final
- dimensions are unspecified. See the last paragraph of <xref
- linkend="arrays-domains_declarations-loc"></xref> for an
- analogous example. Note that the &intervalone; constructors
- taking two and three parameters treat these arguments differently
- than the multidimensional constructors do.</para>
- </section>
-
-
- <section id="arrays-domains_declarations-ranges">
- <title>⦥s</title>
-
- <para>A one-dimensional ⦥ generalizes an &interval; by
- permitting a non-unit stride between integral members. A
- <glossterm
- linkend="glossary-range"><firstterm>range</firstterm></glossterm>
- is a set of integers in a mathematical interval [b,e] with a
- stride s between them: {a, a+s, a+2s, …, b}. Ranges
- are generalized to <varname>&dim;</varname> dimensions using the
- direct product of one-dimensional ranges.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-range-one_d_table">
- <title>Declaring One-Dimensional ⦥s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>T1</varname>, <varname>T2</varname>, and
- <varname>T3</varname> are template parameters.</entry>
- <entry></entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Range<1>()</statement></entry>
- <entry>creates an empty, uninitialized range.</entry>
- </row>
- <row>
- <entry><statement>Range<1>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an uninitialized &rangeone;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Range<1>(const T1& t1)</statement></entry>
- <entry>creates a &rangeone;. See the text for an explanation.</entry>
- </row>
- <row>
- <entry><statement>Range<1>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &rangeone; with an interval specified by the
- integers converted from <varname>t1</varname> and
- <varname>t2</varname>.</entry>
- </row>
- <row>
- <entry><statement>Range<1>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &rangeone; by converting the arguments to
- integers <varname>i1</varname>, <varname>i2</varname>, and
- <varname>i3</varname> and then making a range [i1:i2:i3].</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>&rangeone; constructors are the same as &intervalone;
- constructors except they create ranges, not intervals. See <xref
- linkend="arrays-domains_declarations-range-one_d_table"></xref>.
- The default constructor creates an empty, uninitialized range,
- which should not be used before assigning it values. If the
- one-parameter constructor's argument is a &domain; object, it must
- be a one-dimensional &domain; object which is copied into a ⦥
- if possible. If the one-parameter constructor's argument is not
- a &domain; object, it must be convertible to an
- integer <varname>e</varname> and a range [0:e-1:1] starting
- at zero is constructed. If two arguments are specified, they are
- assumed to be convertible to integers <varname>b</varname> and
- <varname>e</varname>, specifying the range [b:e:1]. The
- three-parameter constructor is similar, with the third argument
- specifying a stride.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-ranges-multi_d_table">
- <title>Declaring Multidimensional ⦥s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>&dim;</varname> indicates the ⦥'s dimension.
- <varname>T1</varname>, <varname>T2</varname>, … are
- template parameters.</entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Range<&dim;>()</statement></entry>
- <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const Pooma::NoInit& no)</statement></entry>
- <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1)</statement></entry>
- <entry>creates a ⦥ using the given &domain; object.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)</statement></entry>
- <entry>creates a ⦥ using the given &domain; objects.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for multidimensional ⦥s are the same as
- multidimensional &interval; constructors except they create
- ranges, not intervals. See <xref
- linkend="arrays-domains_declarations-ranges-multi_d_table"></xref>.
- <varname>&dim;</varname> indicates the ⦥'s dimension. The
- first two constructors return empty, uninitialized ranges.
- The seven other constructors create an ⦥ using &domain;
- objects. These &domain; objects, having types <type>T1</type>,
- …, <type>T7</type>, can have any type that can be
- converted into an integer, into a single-dimensional &domain;
- object that can be converted into a single-dimensional ⦥,
- or to a multidimensional &domain; object that itself can be
- converted into an ⦥. The total dimensionality of all the
- arguments' types should be at most <varname>&dim;</varname>.
- One-dimensional &domain; objects that can be converted into
- one-dimensional ⦥s include &locone;s, &intervalone;s, and
- &rangeone;s. If the sum of the objects' dimensions is less
- than <varname>&dim;</varname>, the ranges for the final
- dimensions are unspecified. See the last paragraph of <xref
- linkend="arrays-domains_declarations-loc"></xref> for an
- analogous example. Note that the &rangeone; constructors taking
- two and three parameters treat these arguments differently than
- the multidimensional constructors do.</para>
- </section>
-
-
- <section id="arrays-domains_declarations-grids">
- <title>&grid;s</title>
-
- <para>&loc;s, &interval;s, and ⦥s all have regularly spaced
- integral values so they can be represented using <glossterm
- linkend="glossary-domain_triplet">domain triplets</glossterm>.
- One-dimensional &grid; integral domains contain ascending or
- descending sequences of integers, with no fixed stride. For
- example, a &gridone; may represent {-13, 1, 4, 5, 34}. &gridone;
- is generalized to multidimensional &grid;s using the direct
- product of &gridone; &domain;s.</para>
-
- <para>&grid;s that can be represented using domain triplets can
- be constructed using techniques similar to other &domain;s, but
- irregularly spaced domains can be constructed using
- &indirectionlistint;s.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-grid-one_d_table">
- <title>Declaring One-Dimensional &grid;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>T1</varname>, <varname>T2</varname>, and
- <varname>T3</varname> are template parameters.</entry>
- <entry></entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Grid<1>()</statement></entry>
- <entry>creates an empty, uninitialized grid.</entry>
- </row>
- <row>
- <entry><statement>Grid<1>(const T1& t1)</statement></entry>
- <entry>creates a &gridone;. See the text for an explanation.</entry>
- </row>
- <row>
- <entry><statement>Grid<1>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &gridone; from the interval specified by the
- integers converted from <varname>t1</varname> and
- <varname>t2</varname>.</entry>
- </row>
- <row>
- <entry><statement>Grid<1>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &gridone; from the domain triplet specified
- by the integers converted from <varname>t1</varname>,
- <varname>t2</varname>, and <varname>t3</varname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>To construct a &gridone; that can also be represented by a
- domain triplet, use a &gridone; constructor similar to those for
- &intervalone; and &rangeone;. See <xref
- linkend="arrays-domains_declarations-grid-one_d_table"></xref>
- and the text explanations following <xref
- linkend="arrays-domains_declarations-range-one_d_table"></xref>
- or <xref
- linkend="arrays-domains_declarations-interval-one_d_table"></xref>.</para>
-
- <para>&gridone;s with irregularly spaced points can be
- constructed using &indirectionlistint;s. For example,
- <programlisting>
- IndirectionList<int> list(4);
- list(0) = 2;
- list(1) = 5;
- list(2) = 6;
- list(3) = 9;
- Grid<1> g(list);
- </programlisting> constructs an empty &indirectionlistint;, fills it
- with ascending values, and then creates a &gridone; containing
- {2, 5, 6, 9}. When creating a list, its size must be specified.
- Subsequently, its values can be assigned. &indirectionlist;s can
- also be initialized using one-dimensional &array;s:
- <programlisting>
- Array<1,int,Brick> a1(Interval<1>(0,3));
- a1(0) = 2; a1(1) = 5; a1(2) = 6; a1(3) = 9;
- IndirectionList<int> il(a1);
- Grid<1> g1(il);
- </programlisting> The &array; stores the integral points to include
- in the &gridone; and is used to create the &indirectionlistint;,
- which itself is used to create the &gridone;. Since the points
- are integers, the &array;'s type is ∫. Either a &brick; or
- &compressiblebrick; &engine; should be used.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-grids-multi_d_table">
- <title>Declaring Multidimensional &grid;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>constructor</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry><varname>&dim;</varname> indicates the &grid;'s dimension.
- <varname>T1</varname>, <varname>T2</varname>, … are
- template parameters.</entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Grid<&dim;>()</statement></entry>
- <entry>creates an empty, uninitialized &grid;, to be assigned a value later.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1)</statement></entry>
- <entry>creates a &grid; using the given &domain; object.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const T2& t2)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const T2& t2, const T3& t3)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)</statement></entry>
- <entry>creates a &grid; using the given &domain; objects.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for multidimensional &grid;s are the same as
- multidimensional &interval; constructors except they create
- &grid;s, not intervals. See <xref
- linkend="arrays-domains_declarations-grids-multi_d_table"></xref>.
- <varname>&dim;</varname> indicates the &grid;'s dimension. The
- first constructor returns empty, uninitialized grids. The seven
- other constructors create an &grid; using &domain; objects. These
- &domain; objects, having types <type>T1</type>, …,
- <type>T7</type>, can have any type that can be converted into an
- integer, into a single-dimensional &domain; object that can be
- converted into a single-dimensional &grid;, or to a
- multidimensional &domain; object that itself can be converted into
- an &grid;. The total dimensionality of all the arguments' types
- should be at most <varname>&dim;</varname>. One-dimensional
- &domain; objects that can be converted into one-dimensional &grid;s
- include &locone;s, &intervalone;s, &rangeone;s, and &gridone;s.
- If the sum of the objects' dimensions is less
- than <varname>&dim;</varname>, the grids for the final
- dimensions are unspecified. See the last paragraph of <xref
- linkend="arrays-domains_declarations-loc"></xref> for an
- analogous example. Note that the &gridone; constructors taking
- two and three parameters treat these arguments differently than
- the multidimensional constructors do.</para>
- </section>
- </section>
-
-
- <section id="arrays-arrays_use">
- <title>Declaring and Using &array;s</title>
-
- <para>A &pooma; &array; maps indices from its &domain; to values.
- In this section, we describe first describe how to declare
- &array;s. Then, we explain how to access individual values stored
- or computed by an &array; and their copy semantics.</para>
-
- <para>&array; values need not just be stored values, as &c; arrays
- have. They can also be computed using its engine. We defer
- discussion of computing values to the next chapter discussing
- engines (<xref linkend="engines"></xref>). To avoid being verbose
- in this chapter, when we discuss stored values, the values might
- instead be computed.</para>
-
- <para>Declaring an &array; requires four arguments: the domain's
- dimensionality, the type of values stored or computed, a
- specification how the values are stored, and a &domain;. The
- first three arguments are template parameters since few scientific
- programs (and no &pooma; programs) need to change these values
- while a program executes. For example, an &array; cannot change
- the type of the elements it stores. Alternatively, an &array;'s
- values can be copied into another &array; having the desired type.
- Although scientific programs do not frequently change an array's
- domain, they do frequently request a subset of the array's values,
- i.e., a <glossterm linkend="glossary-view">view</glossterm>. The
- subset is specified via a &domain; so it is a run-time value.
- Views are presented in <xref linkend="views"></xref>.</para>
-
- <para>An &array;'s first template parameter specifies its
- dimensionality. This positive
- integer <varname>&dim;</varname> specifies its rank. This is
- the same value as its domain's dimensionality. Theoretically, an
- &array; can have any positive integer, but the &pooma; code
- currently supports <varname>&dim;</varname> at most seven. For
- almost all scientific codes, a dimension of three or four is
- sufficient, but the code can be extended to support higher
- dimensions.</para>
-
- <para>An &array;'s second template parameter specifies the type of
- its stored values. Common value types include ∫, &double;,
- &complex;, and &vector;, but any type is permissible. For
- example, an &array;'s values might be matrices or even other
- &array;s.</para>
-
- <para>An &array;'s third parameter specifies how its data is
- stored by an &engine; and its values accessed. The argument is a
- tag indicating a particular type of &engine;. Permissible tags
- include &brick;, &compressiblebrick;, and
- <type>ConstantFunction</type>. The &brick; tag indicates all
- &array; values will be explicitly stored, just as built-in &c;
- arrays do. If the &array;s frequently stores exactly the same
- value in every position, a &compressiblebrick; &engine;, which
- reduces its space requirements to a constant whenever all its
- values are the same, is appropriate. A
- <type>ConstantFunction</type> &engine; returns the same value for
- all indices.</para>
-
- <para>Even though every &array; container has an engine to store
- its values and permit access to individual values, an &array; is
- conceptually separated from engines. An engine's role is
- low-level, storing values and permitting access to individual
- values. As we indicated above, the storage can be optimized to
- fit specific situations such as few nonzero values and computing
- values using a function applied to another engine's values. An
- &array;'s role is high-level, supporting access to groups of
- values. They handle memory allocation and deallocation. &array;s
- can be used in data-parallel expressions, e.g., adding all the
- values in one &array; to all the values in another. (See <xref
- linkend="data_parallel"></xref> for more information.) Subsets of
- &array; values, frequently used in data-parallel statements, can
- be obtained. (See <xref linkend="views"></xref> for more
- information.) Even though engines and &array;s are conceptually
- separate, higher-level &array;s provide access to lower-level
- &engine;s. Users usually have an &array; create its &engine;,
- rarely explicitly creating &engine;s themselves. Also, &array;s
- provide access to individual values. In short, &pooma; users use
- &array;s, only dealing with how they are implemented (engines)
- upon declaration. For more description of &engine;s, see <xref
- linkend="engines"></xref>.</para>
-
- <para>An &array;'s one constructor argument is its domain. The
- domain specifies its extent and simultaneously how many values it
- can return. All the provided &domain; objects are combined to
- yield an <type>Interval<&dim;></type>, where &dim; matches
- the &array;'s first template parameter. Since an &interval;
- domain with its unit strides is used, there are no unaccessed
- <quote>gaps</quote> within the domain, wasting storage space. To
- use other domains to access an &array;, first create it using an
- &interval; domain and then take a view of it, as described in
- <xref linkend="views"></xref>. As we mentioned above, the current
- &pooma; code supports up to seven dimensions so at most seven
- &domain; objects can be provided. If more dimensions are
- required, the &pooma; code can be extended to the desired number
- of dimensions.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-arrays_use-table">
- <title>Declaring &array;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>&array; declaration</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tfoot>
- <row>
- <entry>Template parameters <varname>&dim;</varname>,
- <varname>T</varname>, and <varname>E</varname> indicates the
- &array;'s dimension, value type, and &engine; type,
- respectively, as do <varname>D1</varname>,
- <varname>T1</varname>, and <varname>E1</varname>.
- <varname>DT1</varname>, …, <varname>DT7</varname>
- indicate domain types.</entry>
- </row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Array<&dim;,T,E>()</statement></entry>
- <entry>creates an empty, uninitialized &array;, which must be
- <function>initialize</function>()d before use.</entry>
- </row>
- <!-- Omit Indirection Array because src/Engine/IndirectionEngine.h indicates it is not yet finished. -->
- <row>
- <entry><statement>Array<&dim;,T,E>(const Array<D1,T1,E1>& a)</statement></entry>
- <entry>creates an &array; by copying another one.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const
- Array<D1,T1,E1>& a, const Dom& d)</statement></entry>
- <entry>creates an &array; by copying another one but using the
- specified domain.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1)</statement></entry>
- <entry>creates an &array; using the given &domain; object.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5, const DT6& t6)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5, const DT6& t6, const DT7& t7)</statement></entry>
- <entry>creates a &array; using the given &domain; objects.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates an &array; using the given &domain; object and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5, const DT6& t6,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- <row>
- <entry><statement>Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5, const DT6& t6, const DT7& t7,
- const ModelElement<T>& model)</statement></entry>
- <entry>creates a &array; using the given &domain; objects and
- then initializes all entries using <varname>model</varname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>&array; constructors are listed in <xref
- linkend="arrays-arrays_use-table"></xref>. An &array;s' three
- template parameters for dimensionality, value type, and engine
- type are abbreviated <varname>D</varname>, <varname>T</varname>,
- and <varname>E</varname>. <varname>D1</varname>,
- <varname>T1</varname>, and <varname>E1</varname> are analogous.
- Template parameters for &domain; types
-
- HERE</para>
-
- <para>list ?all? possible declarations
- perhaps this involves copying all possible domain declarations
-
- table of <function>initialize</function>() versions
-
- use: (element-wise only for now)
- how to assign and access particular elements
- use a single set of parentheses, not multiple brackets
-
- semantics of copies and references
- based on engines
-
- HERE</para>
- </section>
-
-
- <section id="arrays-doof2d">
- <title>An &array; Implementation of &doof2d;</title>
-
- <para>mostly copy pp.35-38 from tutorial chapter
- HERE</para>
- </section>
-
-
- <section id="arrays-implementation">
- <title>Implementing &array;s</title>
-
- <para>What to write?
-
- Do I need to describe the public interface of Domains? Do I need
- to describe how a programmer would implement a new type of domain?
- Probably not.
-
- HERE</para>
- </section>
-
- <!-- HERE -->
-
- </chapter>
-
-
<chapter id="engines">
<title>Engines</title>
! <para>
! HERE</para>
</chapter>
&data-parallel-chapter;
--- 350,365 ----
&tutorial-chapter;
&concepts-chapter;
! &arrays-chapter;
<chapter id="engines">
<title>Engines</title>
! <para>UNFINISHED</para>
</chapter>
+
&data-parallel-chapter;
*************** HERE</para>
*** 1584,1590 ****
<para>Be sure to list the various arithmetic operations on domains
that can be used. This was deferred from the &array; and domain
! chapter.</para>
<!-- FIXME: Finish this chapter. -->
</chapter>
--- 368,374 ----
<para>Be sure to list the various arithmetic operations on domains
that can be used. This was deferred from the &array; and domain
! chapter. Explain &array;'s <function>comp</function> function.</para>
<!-- FIXME: Finish this chapter. -->
</chapter>
*************** HERE</para>
*** 1592,1605 ****
<chapter id="sequential">
<title>Writing Sequential Programs</title>
! <para>FIXME: Explain the chapter's purpose.
! HERE</para>
! <para>FIXME: Explain the format of each section.
! HERE</para>
! <para>FIXME: Explain the order of the sections.
! HERE</para>
<para>Proposed order. Basically follow the order in the proposed
reference section.
--- 376,386 ----
<chapter id="sequential">
<title>Writing Sequential Programs</title>
! <para>FIXME: Explain the chapter's purpose.</para>
! <para>FIXME: Explain the format of each section.</para>
! <para>FIXME: Explain the order of the sections.</para>
<para>Proposed order. Basically follow the order in the proposed
reference section.
*************** HERE</para>
*** 1772,1778 ****
<title>Beginning and Ending &pooma; Programs</title>
<para>Every &pooma; program must begin with a call to
! <function>initialize</function> and end with a call to
<function>finalize</function>. These functions respectively
prepare and shut down &pooma;'s run-time structures.</para>
--- 553,559 ----
<title>Beginning and Ending &pooma; Programs</title>
<para>Every &pooma; program must begin with a call to
! <methodname>initialize</methodname> and end with a call to
<function>finalize</function>. These functions respectively
prepare and shut down &pooma;'s run-time structures.</para>
*************** HERE</para>
*** 1822,1828 ****
<bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
<para>Before its use, the &poomatoolkit; must be initialized by a
! call to <function>initialize</function>. This usually occurs in
the <function>main</function> function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments <varname>argv</varname> and
--- 603,609 ----
<bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
<para>Before its use, the &poomatoolkit; must be initialized by a
! call to <methodname>initialize</methodname>. This usually occurs in
the <function>main</function> function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments <varname>argv</varname> and
*************** HERE</para>
*** 1844,1850 ****
architecture-specific initialization. The function always
returns &true;.</para>
! <para><function>initialize</function>'s alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
<varname>argv</varname> and <varname>argc</varname> and stored in
--- 625,631 ----
architecture-specific initialization. The function always
returns &true;.</para>
! <para><methodname>initialize</methodname>'s alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
<varname>argv</varname> and <varname>argc</varname> and stored in
*************** HERE</para>
*** 1872,1878 ****
<bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
<para>Since every &pooma; program must call
! <function>initialize</function> and
<function>finalize</function>, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.</para>
--- 653,659 ----
<bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
<para>Since every &pooma; program must call
! <methodname>initialize</methodname> and
<function>finalize</function>, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.</para>
*************** HERE</para>
*** 1908,1914 ****
</row>
<row>
<entry>&inform; <varname>pwarn</varname></entry>
! <entry>HERE output stream used to print informative messages to the
user while the program executes. The stream accepts a
superset of standard output operations.</entry>
</row>
--- 689,695 ----
</row>
<row>
<entry>&inform; <varname>pwarn</varname></entry>
! <entry>FIXME: output stream used to print informative messages to the
user while the program executes. The stream accepts a
superset of standard output operations.</entry>
</row>
*************** HERE</para>
*** 1918,1925 ****
</section>
- <!-- HERE -->
-
<section id="sequential-options">
<title>&pooma; Command-line Options</title>
--- 699,704 ----
*************** UNFINISHED</para>
*** 1944,1961 ****
executes.</para>
</listitem>
</varlistentry>
! <!-- HERE -->
</variablelist>
<para>FIXME: Be sure to list default values.</para>
! <!-- HERE: need to describe the pinfo, pwarn, and perr streams somewhere. To do so requires describing informs.-->
! <!-- HERE: Which streams are buffered and which are not? -->
- <!-- HERE -->
-
</section>
-
- <!-- HERE -->
</section><!-- end sequential-options -->
--- 723,736 ----
executes.</para>
</listitem>
</varlistentry>
! <!-- UNFINISHED -->
</variablelist>
<para>FIXME: Be sure to list default values.</para>
! <!-- FIXME: need to describe the pinfo, pwarn, and perr streams somewhere. To do so requires describing informs.-->
! <!-- FIXME: Which streams are buffered and which are not? -->
</section>
</section><!-- end sequential-options -->
More information about the pooma-dev
mailing list