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 ----
+
+ &array; Containers
+
+ 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.
+
+
+
+ Containers
+
+ A container class
+ expression is a class with the main
+ purpose of holding objects. These stored objects, called
+ container
+ values or more simply
+ values or elements, may be accessed
+ and changed, usually using indices. Container
+ class is usually abbreviated
+ container.
+
+ 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.
+
+ &c; has built-in arrays, and the &cc; Standard Library
+ provides maps, vectors,
+ stacks, 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 .
+
+
+
+
+ &array;s
+
+ 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.
+
+ &pooma; &array;s are first-class
+ types 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
+ a = a + b; adds corresponding elements of
+ &array;s a and b, assigning
+ the sums to the &array; a. 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 . &array;s also handle their own
+ memory allocation and deallocation. For example, the &array;
+ declaration Array<2, double, Brick>
+ a(vertDomain) creates an
+ &array; a, allocating whatever memory it
+ needs. When a 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.
+
+ Individual &array; values can be accessed using parentheses,
+ not square brackets, as for &cc; arrays. For example,
+ a(3,4) yields the value at position (3,4)
+ of a's two-dimensional domain.
+
+
+
+
+ &domain;s
+
+ A domain
+ 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.
+
+ In &pooma;, &domain;s implement domains. There are four
+ different categories:
+
+
+ &loc;
+
+ &domain; with a single point.
+
+
+
+ &interval;
+
+ &domain; with an integral interval [a,b].
+
+
+
+ ⦥
+
+ &domain; with an integral interval [a,b] and an integral
+ stride s indicating the gap between indices: {a, a+s,
+ a+2s, …, b}.
+
+
+
+ &grid;
+
+ &domain; with an ascending or descending sequence of
+ integral values. The sequence elements must be individually
+ specified.
+
+
+
+ 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).
+
+ Many domains can be represented using domain triplets. A
+ domain
+ triplet
+ [begin:end:stride]
+ represents the mathematical set {begin, begin + stride, begin +
+ 2stride, …, end}, where end is in the
+ set only if it equals begin plus some integral
+ multiple of stride. If the
+ stride is negative, its beginning index
+ begin should at least be as large as
+ end if the interval is to be nonempty. The
+ stride can be zero only if begin and
+ end 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).
+
+ 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 Loc<1>(7). Multidimensional
+ &loc;s are similarly represented. For example,
+ [0:0:1,10:10:1,2:2:1] represents
+ Loc<3>(0,10,2), 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].
+
+ &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,
+ Interval<2>(Interval<1>(2,3),
+ Interval<1>(4,5)) 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.
+
+ 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, Interval<3> a(Loc<2>(1,2),
+ Interval<1>(3,5)) 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,
+ Loc<2>(1,2) is first converted to an
+ &interval;.
+
+ &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;
+ d1 < &interval; d2 if the
+ length of d1's interval is less than
+ d2'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 and .
+
+ 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.
+
+
+
+
+ Declaring &domain;s
+
+ Since &domain;s are mainly used to declare container
+ domains, we focus on declaring &domain;s. Arithmetic operations
+ with &domain;s are described in .
+
+ All &domain; declarations require a dimension template
+ parameter &dim;. 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.
+
+ To declare a &domain;, one must include the
+ Pooma/Domains.h header
+ file. However, most &pooma; programs declare &domain;s to use them
+ when constructing containers. The container header files
+ automatically include Pooma/Domains.h so no explicit
+ inclusion is usually necessary.
+
+
+ &loc;s
+
+ A Loc<&dim;> is a &domain; with just a single
+ &dim;-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.
+
+
+ Declaring One-Dimensional &loc;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &domaintemplate;1, &domaintemplate;2, and
+ &domaintemplate;3 are template parameters.
+
+
+
+
+
+ Loc<1>()
+ points to zero.
+
+
+ Loc<1>(const Pooma::NoInit& no)
+ creates an uninitialized &locone;, to be assigned a value later.
+
+
+ Loc<1>(const &domaintemplate;1& t1)
+ creates a &locone; with the integer converted from t1.
+
+
+ Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &locone; with the integer converted from
+ t1. t2 must equal
+ t1.
+
+
+ Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &locone; with the integer converted from
+ t1. t2 must equal
+ t1, and t3 is
+ ignored.
+
+
+
+
+
+ Constructors for one-dimensional &loc;s appear in .
+ The empty constructor yields the zero point. The constructor
+ taking a Pooma::Init 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 &domaintemplate;1 converts this argument to
+ an integer to specify the point. The template
+ type &domaintemplate;1 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.
+
+
+ Declaring Multidimensional &loc;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &dim; indicates the &loc;'s dimension.
+ &domaintemplate;1, &domaintemplate;2, … are
+ template parameters.
+
+
+
+
+ Loc<&dim;>()
+ points to zero.
+
+
+ Loc<&dim;>(const Pooma::NoInit& no)
+ creates an uninitialized &loc;, to be assigned a value later.
+
+
+ Loc<&dim;>(const &domaintemplate;1& t1)
+ creates a &loc; using the given &domain; object.
+
+
+ Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &loc; using the given &domain; objects.
+
+
+ Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &loc; using the given &domain; objects.
+
+
+ Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)
+ creates a &loc; using the given &domain; objects.
+
+
+ Loc<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)
+ creates a &loc; using the given &domain; objects.
+
+
+ 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)
+ creates a &loc; using the given &domain; objects.
+
+
+ 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)
+ creates a &loc; using the given &domain; objects.
+
+
+
+
+
+ Constructors for multidimensional &loc;s appear in .
+ &dim; 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 &domaintemplate;1, …, &domaintemplate;7, 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 &dim;. For example,
+ Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
+ Interval<1>(4,4)) 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.
+
+
+
+
+ &interval;s
+
+ A one-dimensional &interval; represents a set of integers
+ within a mathematical interval.
+ 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.
+
+
+ Declaring One-Dimensional &interval;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &domaintemplate;1, &domaintemplate;2, and
+ &domaintemplate;3 are template parameters.
+
+
+
+
+
+ Interval<1>()
+ creates an empty, uninitialized interval.
+
+
+ Interval<1>(const Pooma::NoInit& no)
+ creates an uninitialized &intervalone;, to be assigned a value later.
+
+
+ Interval<1>(const &domaintemplate;1& t1)
+ creates a &intervalone;. See the text for an explanation.
+
+
+ Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &intervalone; with the integers converted from
+ t1 and t2.
+
+
+ Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &intervalone; with the integers converted from
+ t1 and t2.
+ t3 must equal 1.
+
+
+
+
+
+ &intervalone; constructors are patterned on &locone;
+ constructors except that &intervalone;s can have differing
+ beginning and ending points. See .
+ 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 e 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
+ b and e, specifying the
+ interval [b:e:1]. The three-parameter constructor is similar,
+ with the third argument specifying a stride, which must be
+ one.
+
+
+ Declaring Multidimensional &interval;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &dim; indicates the &interval;'s dimension.
+ &domaintemplate;1, &domaintemplate;2, … are
+ template parameters.
+
+
+
+
+ Interval<&dim;>()
+ creates an empty, uninitialized &interval;, to be assigned a value later.
+
+
+ Interval<&dim;>(const Pooma::NoInit& no)
+ creates an empty, uninitialized &interval;, to be assigned a value later.
+
+
+ Interval<&dim;>(const &domaintemplate;1& t1)
+ creates a &interval; using the given &domain; object.
+
+
+ Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &interval; using the given &domain; objects.
+
+
+ Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &interval; using the given &domain; objects.
+
+
+ Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)
+ creates a &interval; using the given &domain; objects.
+
+
+ Interval<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)
+ creates a &interval; using the given &domain; objects.
+
+
+ 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)
+ creates a &interval; using the given &domain; objects.
+
+
+ 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)
+ creates a &interval; using the given &domain; objects.
+
+
+
+
+
+ Constructors for multidimensional &interval;s closely
+ follow constructors for multidimensional &loc;s. See .
+ &dim; 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 &domaintemplate;1, …,
+ &domaintemplate;7, 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 &dim;. 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 &dim;, the intervals for the final
+ dimensions are unspecified. See the last paragraph of for an
+ analogous example. Note that the &intervalone; constructors
+ taking two and three parameters treat these arguments differently
+ than the multidimensional constructors do.
+
+
+
+
+ ⦥s
+
+ A one-dimensional ⦥ generalizes an &interval; by
+ permitting a non-unit stride between integral members. A
+ range
+ 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 &dim; dimensions using the
+ direct product of one-dimensional ranges.
+
+
+ Declaring One-Dimensional ⦥s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &domaintemplate;1, &domaintemplate;2, and
+ &domaintemplate;3 are template parameters.
+
+
+
+
+
+ Range<1>()
+ creates an empty, uninitialized range.
+
+
+ Range<1>(const Pooma::NoInit& no)
+ creates an uninitialized &rangeone;, to be assigned a value later.
+
+
+ Range<1>(const &domaintemplate;1& t1)
+ creates a &rangeone;. See the text for an explanation.
+
+
+ Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &rangeone; with an interval specified by the
+ integers converted from t1 and
+ t2.
+
+
+ Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &rangeone; by converting the arguments to
+ integers i1, i2, and
+ i3 and then making a range [i1:i2:i3].
+
+
+
+
+
+ &rangeone; constructors are the same as &intervalone;
+ constructors except they create ranges, not intervals. See .
+ 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 e 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 b and
+ e, specifying the range [b:e:1]. The
+ three-parameter constructor is similar, with the third argument
+ specifying a stride.
+
+
+ Declaring Multidimensional ⦥s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &dim; indicates the ⦥'s dimension.
+ &domaintemplate;1, &domaintemplate;2, … are
+ template parameters.
+
+
+
+
+ Range<&dim;>()
+ creates an empty, uninitialized ⦥, to be assigned a value later.
+
+
+ Range<&dim;>(const Pooma::NoInit& no)
+ creates an empty, uninitialized ⦥, to be assigned a value later.
+
+
+ Range<&dim;>(const &domaintemplate;1& t1)
+ creates a ⦥ using the given &domain; object.
+
+
+ Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a ⦥ using the given &domain; objects.
+
+
+ Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a ⦥ using the given &domain; objects.
+
+
+ Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)
+ creates a ⦥ using the given &domain; objects.
+
+
+ Range<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)
+ creates a ⦥ using the given &domain; objects.
+
+
+ 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)
+ creates a ⦥ using the given &domain; objects.
+
+
+ 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)
+ creates a ⦥ using the given &domain; objects.
+
+
+
+
+
+ Constructors for multidimensional ⦥s are the same as
+ multidimensional &interval; constructors except they create
+ ranges, not intervals. See .
+ &dim; 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 &domaintemplate;1,
+ …, &domaintemplate;7, 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 &dim;.
+ 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 &dim;, the ranges for the final
+ dimensions are unspecified. See the last paragraph of for an
+ analogous example. Note that the &rangeone; constructors taking
+ two and three parameters treat these arguments differently than
+ the multidimensional constructors do.
+
+
+
+
+ &grid;s
+
+ &loc;s, &interval;s, and ⦥s all have regularly spaced
+ integral values so they can be represented using domain triplets.
+ 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.
+
+ &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.
+
+
+ Declaring One-Dimensional &grid;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &domaintemplate;1, &domaintemplate;2, and
+ &domaintemplate;3 are template parameters.
+
+
+
+
+
+ Grid<1>()
+ creates an empty, uninitialized grid.
+
+
+ Grid<1>(const &domaintemplate;1& t1)
+ creates a &gridone;. See the text for an explanation.
+
+
+ Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &gridone; from the interval specified by the
+ integers converted from t1 and
+ t2.
+
+
+ Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &gridone; from the domain triplet specified
+ by the integers converted from t1,
+ t2, and t3.
+
+
+
+
+
+ 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
+ and the text explanations following
+ or .
+
+ &gridone;s with irregularly spaced points can be
+ constructed using &indirectionlistint;s. For example,
+
+ IndirectionList<int> list(4);
+ list(0) = 2;
+ list(1) = 5;
+ list(2) = 6;
+ list(3) = 9;
+ Grid<1> g(list);
+ 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:
+
+ 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);
+ 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.
+
+
+ Declaring Multidimensional &grid;s
+
+
+
+
+ constructor
+ result
+
+
+
+
+ &dim; indicates the &grid;'s
+ dimension. &domaintemplate;1,
+ &domaintemplate;2, … are template
+ parameters.
+
+
+
+
+ Grid<&dim;>()
+ creates an empty, uninitialized &grid;, to be assigned a value later.
+
+
+ Grid<&dim;>(const &domaintemplate;1& t1)
+ creates a &grid; using the given &domain; object.
+
+
+ Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)
+ creates a &grid; using the given &domain; objects.
+
+
+ Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)
+ creates a &grid; using the given &domain; objects.
+
+
+ Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)
+ creates a &grid; using the given &domain; objects.
+
+
+ Grid<&dim;>(const &domaintemplate;1& t1, const
+ &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
+ t5)
+ creates a &grid; using the given &domain; objects.
+
+
+ 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)
+ creates a &grid; using the given &domain; objects.
+
+
+ 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)
+ creates a &grid; using the given &domain; objects.
+
+
+
+
+
+ Constructors for multidimensional &grid;s are the same as
+ multidimensional &interval; constructors except they create
+ &grid;s, not intervals. See .
+ &dim; 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 &domaintemplate;1, …,
+ &domaintemplate;7, 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 &dim;. 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 &dim;, the grids for the final
+ dimensions are unspecified. See the last paragraph of for an
+ analogous example. Note that the &gridone; constructors taking
+ two and three parameters treat these arguments differently than
+ the multidimensional constructors do.
+
+
+
+
+
+ Declaring &array;s
+
+ 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.
+
+ &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 (). To avoid being verbose
+ in this chapter, when we discuss stored values, the values might
+ instead be computed.
+
+ 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 view. The
+ subset is specified via a &domain; so it is a run-time value.
+ Views are presented in .
+
+ An &array;'s first template parameter specifies its
+ dimensionality. This positive
+ integer &dim; 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 &dim; 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.
+
+ 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.
+
+ 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
+ ConstantFunction. 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
+ ConstantFunction &engine; returns the same value for
+ all indices.
+
+ 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 for more information.) Subsets of
+ &array; values, frequently used in data-parallel statements, can
+ be obtained. (See 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 .
+
+ The engine parameter's default value is usually &brick;, but
+ it may be changed when the &poomatoolkit; is configured.
+
+ 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 Interval<&dim;>, where &dim; matches
+ the &array;'s first template parameter. Since an &interval;
+ domain with its unit strides is used, there are no unaccessed
+ gaps 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
+ . 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.
+
+
+ Declaring &array;s
+
+
+
+
+ &array; declaration
+ result
+
+
+
+
+ Template parameters &dim;,
+ T, and E indicates the
+ &array;'s dimension, value type, and &engine; type,
+ respectively. DT1, …,
+ DT7 indicate domain types or
+ integers.
+
+
+
+
+ Array<&dim;,T,E>()
+ creates an empty, uninitialized &array; which must be
+ initialize()d before use.
+
+
+
+
+ Array<&dim;,T,E>(const DT1& t1)
+ creates an &array; using the given &domain; object or integer.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const DT2& t2)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ 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)
+ creates an &array; using the given &domain; objects and integers.
+
+
+ Array<&dim;,T,E>(const DT1& t1,
+ const ModelElement<T>& model)
+ creates an &array; using the given &domain; object or
+ integer and
+ then initializes all entries using model.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const DT2& t2,
+ const ModelElement<T>& model)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3,
+ const ModelElement<T>& model)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4,
+ const ModelElement<T>& model)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+ Array<&dim;,T,E>(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5,
+ const ModelElement<T>& model)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+ 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)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+ 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)
+ creates an &array; using the given &domain; objects and
+ integers and
+ then initializes all entries using model.
+
+
+
+
+
+ &array; constructors are listed in . An &array;s'
+ three template parameters for dimensionality, value type, and
+ engine type are abbreviated D,
+ T, and E. Template
+ parameters for domain types are named DT1,
+ …, DT7. 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 initialize 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
+
+ and the following text.) The domain objects, having types
+ &domaintemplate;1, …,
+ &domaintemplate;7, 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
+ equal&dim;, unlike
+ &interval; construction which permits total dimensionality less
+ than or equal to &dim;. 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 ModelElement.
+ These constructors use the given domain objects the same way as
+ the preceding constructors but assign model to
+ every &array; value. model's type
+ ModelElement<T> rather than
+ T to differentiate it from an ∫, which can
+ also be used to specify a domain object.
+ ModelElement just stores an element of any type
+ T, which must match the &array;'s value
+ type.
+
+ We illustrate creating &array;s. To create a
+ three-dimensional &array; a explicitly
+ storing &double; floating-point values, use
+
+ Interval<1> D(6);
+ Interval<3> I3(D,D,D);
+ Array<3,double,Brick> a(I3);.
+ 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 Interval<3>
+ 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:
+
+ Array<3,double> a_duplicate1(I3);
+ Array<3> a_duplicate2(I3);.
+ To create a similar &array; with a domain of
+ [0:1:1, 0:2:1, 0:0:1], use
+
+ Array<3> b(2,3,1);.
+ Specifying an integer i
+ indicates a one-dimensional zero-based &interval; [0:i-1:1]. To
+ store &bool;s, specify &bool; as the second template argument:
+
+ Array<2,bool> c(2,3);.
+ To specify a default &array; value of &true;, use
+ ModelElement<bool>(true):
+
+ Array<2,bool> c(2,3, ModelElement<bool>(true));.
+ To create a one-dimensional &array; containing
+ seven &double;s all equaling π, use
+
+ Array<1,double,CompressibleBrick> d(7, ModelElement<double>(4.0*atan(1.0)));.
+ 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.
+
+
+ Initializing &array;s' Domains
+
+
+
+
+ An &array;'s initialize member
+ functions sets its domain and should be invoked only for an
+ array created without a domain. It returns nothing.
+
+
+ initialize declaration
+ result
+
+
+
+
+ Template parameters DT1, …,
+ DT7 indicate domain types or
+ integers.
+
+
+
+
+
+
+ initialize(const DT1& t1)
+ creates the &array;'s domain using the given &domain;
+ object or integer.
+
+
+ initialize(const DT1& t1, const DT2& t2)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1, const DT2& t2, const DT3& t3)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6, const DT7& t7)
+ creates the &array;'s domain using the given &domain; objects and integers.
+
+
+ initialize(const DT1& t1,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; object and
+ then initializes all entries using model.
+
+
+ initialize(const DT1& t1, const DT2& t2,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+ initialize(const DT1& t1, const DT2& t2, const DT3& t3,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+ initialize(const DT1& t1, const
+ DT2& t2, const DT3& t3, const DT4& t4, const DT5&
+ t5, const DT6& t6,
+ const ModelElement<T>& model)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+ 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)
+ creates the &array;'s domain using the given &domain; objects and
+ then initializes all entries using model.
+
+
+
+
+
+ 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
+ new (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 initialize
+ functions accept the same set of domain object specifications and
+ model elements that the &array; constructors do, creating the
+ specified domain. See .
+ For example, both a and b
+ are two-dimensional &array;s of &float;s with a [2:7:1,-2:4:1]
+ domains:
+
+ // 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));.
+ Invoking initialize on an
+ &array; with an existing domain is unspecified. All &array;
+ values may be lost and memory may be leaked.
+
+
+
+
+ Using &array;s
+
+ 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 , we explain
+ how to use entire &array;s in data-parallel statements, including
+ how to print them. In , we extend
+ this capability to work on subsets.
+
+ 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:
+
+ 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;
+ 4 and then
+ 5 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.
+
+ For read-only access to a value, use the
+ read member function, which takes the
+ same index notation as its nameless read-write counterpart:
+
+ std::cout &openopen; a.read(2,-2) &openopen; std::endl;
+ Using read sometimes
+ permits the optimizer to produce faster executing code.
+
+
+ Copying &array;s
+ &array-copy;
+
+
+ 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. illustrates this
+ behavior. Initially, all values in the array a
+ are 4. The b array is initialized using
+ a so it shares the same values as
+ a. 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
+ changeValue function changes the value with
+ index (0,0) of both its function argument
+ and a.
+
+ 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.
+
+ Array assignment does not have reference semantics. Thus,
+ the assignment a = b ensures that all of
+ a's values are the same as b
+ at the time of assignment only. Subsequent changes to
+ a's values do not change b's
+ values or vice versa.
+
+
+ &array; Internal Type Definitions and Compile-Time Constants
+
+
+
+
+ internal type or compile-time constant
+ meaning
+
+
+
+
+ This_t
+ the &array;'s type Array<&dim;,T,E>.
+
+
+ Engine_t
+ the &array;'s &engine; type Engine<&dim;,T,E>.
+
+
+ EngineTag_t
+ the &array;'s &engine;'s tag E.
+
+
+ Element_t
+ the type T of values stored in the &array;.
+
+
+ ElementRef_t
+ the type of references to values stored in the &array;
+ (usually T&).
+
+
+ Domain_t
+ the type of the &array;'s domain.
+
+
+ Layout_t
+ the type of the &array;'s layout.
+
+
+
+ const
+ int
+ dimensions
+ the number &dim; of dimensions of the &array;.
+
+
+
+ const
+ int
+ rank
+ synonym for dimensions.
+
+
+
+
+
+ The &array; class has internal type definitions and
+ constants useful for both compile-time and run-time computations.
+ See .
+ These may be accessed using the &array;'s type and the scope
+ resolution operator (::). The table begins
+ with a list of internal type definitions, e.g.,
+ Array<&dim;,T,E>::Domain_t. Member
+ functions use some of these types. A layout maps a domain index
+ to a particular processor and memory used to compute the
+ associated value. The two internal enumerations
+ dimensions and
+ rank both record
+ the &array;'s dimension.
+
+
+ &array; Accessors
+
+
+
+
+ &array; member function
+ result
+
+
+
+
+ Internal type definitions, e.g., Domain_t,
+ are listed without a class type prefix
+ Array<&dim;,T,E>::.
+
+
+
+
+ Domain_t domain()
+ returns the &array;'s domain.
+
+
+ Domain_t physicalDomain()
+ returns the &array;'s domain.
+
+
+ Domain_t totalDomain()
+ returns the &array;'s domain.
+
+
+ int first(int dim)
+ returns the first (smallest) index value for the
+ specified dimension.
+
+
+ int last(int dim)
+ returns the last (largest) index value for the
+ specified dimension.
+
+
+ int length(int dim)
+ returns the number of indices (including endpoints) for
+ the specified dimension.
+
+
+ Loc<Dim> firsts()
+ returns the first (smallest) index values for all the
+ dimensions.
+
+
+ Loc<Dim> lasts()
+ returns the last (largest) index values for all the
+ specified dimensions.
+
+
+ Loc<Dim> lengths()
+ returns the numbers of indices (including endpoints)
+ for all the specified dimensions.
+
+
+ long size()
+ returns the total number of indices in the domain.
+
+
+ Layout_t layout()
+ returns the &array;'s domain.
+
+
+ Engine_t engine()
+ returns the &array;'s engine.
+
+
+ const Engine_t engine()
+ returns the &array;'s engine.
+
+
+
+
+
+ The &array; class has several member functions easing access
+ to its domain and engine. The first ten functions listed in ease access to
+ &array; domains. The first three functions are synonyms all
+ returning the &array;'s domain, which has type
+ Array<&dim;,T,E>::Domain_t, abbreviated
+ Domain_t in the table. The next seven functions
+ query the domain. first,
+ last, and length
+ return the smallest, largest, and number of indices for the
+ specified dimension. The domain's dimensions are numbered 0, 1,
+ …,
+ Array<&dim;,T,E>::dimensions-1. If
+ these values are needed for all dimensions, use
+ firsts, lasts,
+ and lengths. The returned
+ Loc<&dim;>s have &dim; entries, one for each
+ dimension. size returns the total number
+ of indices in the entire domain. This is the product of all the
+ dimensions' lengths. The
+ layout member function returns the
+ &array;'s layout, which specifies the mapping of indices to
+ processors and memory. The last two functions return the
+ &array;'s engine.
+
+
+ Using &array; Member Functions
+ &array-size;
+
+
+ The size is invoked by
+ prepending the &array;'s name followed by a period. This
+ assertion is unnecessary, but the
+ computeArraySize function further
+ illustrates using member functions.
+
+
+ These template parameters, used in the &array;
+ parameter's type, permit the function to work with any
+ &array;.
+
+
+ We invoke these three member functions using the
+ &array;'s name a, a period, and the
+ functions' names. These functions return &loc;s.
+
+
+ lens[d] returns a
+ Loc<1> for
+ dimension d's length. Invoking
+ Loc<1>firstmethod
+ yields its value.
+
+
+ This comparison is unnecessary but further illustrates
+ using member functions.
+
+
+
+
+ We illustrate using &array; member functions in . The program
+ computes the total number of &array;'s indices, comparing the
+ result with invoking its size method.
+ Since the &array;'s name is a,
+ a.size() returns its size.
+ computeArraySize 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
+ Loc<&dim>lens,
+ lens[d] is a Loc<1>, for
+ which its first extracts the length. The
+ length &array; member function is used in
+ the PAssert.
+
+
+
+
+ An &array; Implementation of &doof2d;
+
+ mostly copy pp.35-38 from tutorial chapter
+
+
+
+
+ Implementing &array;s
+
+ 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.
+
+
+
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 ****
&array;
! container mapping indices to values and that may be
used in expressions
--- 134,140 ----
&array;
! container mapping indices to values and that may be
used in expressions
***************
*** 146,152 ****
&field;
! container mapping indices to one or more values and
residing in multi-dimensional space
--- 146,152 ----
&field;
! container mapping indices to one or more values and
residing in multi-dimensional space
***************
*** 172,178 ****
A &pooma; &array; 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 ----
A &pooma; &array; 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
***************
*** 350,356 ****
A layout
! maps domain indices to the
processors and computer memory used by a container's engines. See
.
--- 350,356 ----
A layout
! maps domain indices to the
processors and computer memory used by a container's engines. See
.
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 ****
!
C">
--- 15,21 ----
!
C">
***************
*** 32,37 ****
--- 32,39 ----
+
+
Doof2d" >
Fortran">
***************
*** 89,94 ****
--- 91,98 ----
Domain">
+
+
double">
DynamicArray">
***************
*** 100,105 ****
--- 104,111 ----
Field">
+ float">
+
Grid">
Grid<1>">
***************
*** 193,198 ****
--- 199,206 ----
+
+
***************
*** 228,233 ****
--- 236,245 ----
+
+
+
+
***************
*** 285,291 ****
! How to Read This &bookCap;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 ----
! How to Read This &bookcap;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;
-
-
-
- &array; Containers
-
- 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.
-
-
-
- Containers
-
- A container class
- expression is a class with the main
- purpose of holding objects. These stored objects, called
- container
- values or more simply
- values or elements, may be accessed
- and changed, usually using indices. Container
- class is usually abbreviated
- container.
-
- 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.
-
- &c; has built-in arrays, and the &cc; Standard Library
- provides maps, vectors,
- stacks, 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 .
-
-
-
-
- &array;s
-
- 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.
-
- &pooma; &array;s are first-class
- types 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
- a = a + b; adds corresponding elements of
- &array;s a and b, assigning
- the sums to the &array; a. 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 . &array;s also handle their own
- memory allocation and deallocation. For example, the &array;
- declaration Array<2, double, Brick>
- a(vertDomain) creates an
- &array; a, allocating whatever memory it
- needs. When a 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.
-
- Individual &array; values can be accessed using parentheses,
- not square brackets, as for &cc; arrays. For example,
- a(3,4) yields the value at position (3,4)
- of a's two-dimensional domain.
-
-
-
-
- &domain;s
-
- A domain
- 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.
-
- In &pooma;, &domain;s implement domains. There are four
- different categories:
-
-
- &loc;
-
- &domain; with a single point.
-
-
-
- &interval;
-
- &domain; with an integral interval [a,b].
-
-
-
- ⦥
-
- &domain; with an integral interval [a,b] and an integral
- stride s indicating the gap between indices: {a, a+s,
- a+2s, …, b}.
-
-
-
- &grid;
-
- &domain; with an ascending or descending sequence of
- integral values. The sequence elements must be individually
- specified.
-
-
-
- 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).
-
- Many domains can be represented using domain triplets. A
- domain
- triplet
- [begin:end:stride]
- represents the mathematical set {begin, begin + stride, begin +
- 2stride, …, end}, where end is in the
- set only if it equals begin plus some integral
- multiple of stride. If the
- stride is negative, its beginning index
- begin should at least be as large as
- end if the interval is to be nonempty. The
- stride can be zero only if begin and
- end 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).
-
- 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 Loc<1>(7). Multidimensional
- &loc;s are similarly represented. For example,
- [0:0:1,10:10:1,2:2:1] represents
- Loc<3>(0,10,2), 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].
-
- &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,
- Interval<2>(Interval<1>(2,3),
- Interval<1>(4,5)) 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.
-
- 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, Interval<3> a(Loc<2>(1,2),
- Interval<1>(3,5)) 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,
- Loc<2>(1,2) is first converted to an
- &interval;.
-
- &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;
- d1 < &interval; d2 if the
- length of d1's interval is less than
- d2'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 and .
-
- 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.
-
-
!
! Declaring &domain;s
- Since &domain;s are mainly used to declare container
- domains, we focus on declaring &domain;s. Arithmetic operations
- with &domain;s are described in .
-
- All &domain; declarations require a dimension template
- parameter &dim;. 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.
-
- To declare a &domain;, one must include the
- Pooma/Domains.h header
- file. However, most &pooma; programs declare &domain;s to use them
- when constructing containers. The container header files
- automatically include Pooma/Domains.h so no explicit
- inclusion is usually necessary.
-
-
- &loc;s
-
- A Loc<&dim;> is a &domain; with just a single
- &dim;-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.
-
-
- Declaring One-Dimensional &loc;s
-
-
-
-
- constructor
- result
-
-
-
-
- T1, T2, and
- T3 are template parameters.
-
-
-
-
-
- Loc<1>()
- points to zero.
-
-
- Loc<1>(const Pooma::NoInit& no)
- creates an uninitialized &locone;, to be assigned a value later.
-
-
- Loc<1>(const T1& t1)
- creates a &locone; with the integer converted from t1.
-
-
- Loc<1>(const T1& t1, const T2& t2)
- creates a &locone; with the integer converted from
- t1. t2 must equal
- t1.
-
-
- Loc<1>(const T1& t1, const T2& t2, const T3& t3)
- creates a &locone; with the integer converted from
- t1. t2 must equal
- t1, and t3 is
- ignored.
-
-
-
-
-
- Constructors for one-dimensional &loc;s appear in .
- The empty constructor yields the zero point. The constructor
- taking a Pooma::Init 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 T1 converts this argument to
- an integer to specify the point. The template
- type T1 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.
-
-
- Declaring Multidimensional &loc;s
-
-
-
-
- constructor
- result
-
-
-
-
- &dim; indicates the &loc;'s dimension.
- T1, T2, … are
- template parameters.
-
-
-
-
- Loc<&dim;>()
- points to zero.
-
-
- Loc<&dim;>(const Pooma::NoInit& no)
- creates an uninitialized &loc;, to be assigned a value later.
-
-
- Loc<&dim;>(const T1& t1)
- creates a &loc; using the given &domain; object.
-
-
- Loc<&dim;>(const T1& t1, const T2& t2)
- creates a &loc; using the given &domain; objects.
-
-
- Loc<&dim;>(const T1& t1, const T2& t2, const T3& t3)
- creates a &loc; using the given &domain; objects.
-
-
- Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)
- creates a &loc; using the given &domain; objects.
-
-
- Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)
- creates a &loc; using the given &domain; objects.
-
-
- Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)
- creates a &loc; using the given &domain; objects.
-
-
- Loc<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)
- creates a &loc; using the given &domain; objects.
-
-
-
-
-
- Constructors for multidimensional &loc;s appear in .
- &dim; 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 T1, …, T7, 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 &dim;. For example,
- Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
- Interval<1>(4,4)) 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.
-
-
-
-
- &interval;s
-
- A one-dimensional &interval; represents a set of integers
- within a mathematical interval.
- 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.
-
-
- Declaring One-Dimensional &interval;s
-
-
-
-
- constructor
- result
-
-
-
-
- T1, T2, and
- T3 are template parameters.
-
-
-
-
-
- Interval<1>()
- creates an empty, uninitialized interval.
-
-
- Interval<1>(const Pooma::NoInit& no)
- creates an uninitialized &intervalone;, to be assigned a value later.
-
-
- Interval<1>(const T1& t1)
- creates a &intervalone;. See the text for an explanation.
-
-
- Interval<1>(const T1& t1, const T2& t2)
- creates a &intervalone; with the integers converted from
- t1 and t2.
-
-
- Interval<1>(const T1& t1, const T2& t2, const T3& t3)
- creates a &intervalone; with the integers converted from
- t1 and t2.
- t3 must equal 1.
-
-
-
-
-
- &intervalone; constructors are patterned on &locone;
- constructors except that &intervalone;s can have differing
- beginning and ending points. See .
- 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 e 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
- b and e, specifying the
- interval [b:e:1]. The three-parameter constructor is similar,
- with the third argument specifying a stride, which must be
- one.
-
-
- Declaring Multidimensional &interval;s
-
-
-
-
- constructor
- result
-
-
-
-
- &dim; indicates the &interval;'s dimension.
- T1, T2, … are
- template parameters.
-
-
-
-
- Interval<&dim;>()
- creates an empty, uninitialized &interval;, to be assigned a value later.
-
-
- Interval<&dim;>(const Pooma::NoInit& no)
- creates an empty, uninitialized &interval;, to be assigned a value later.
-
-
- Interval<&dim;>(const T1& t1)
- creates a &interval; using the given &domain; object.
-
-
- Interval<&dim;>(const T1& t1, const T2& t2)
- creates a &interval; using the given &domain; objects.
-
-
- Interval<&dim;>(const T1& t1, const T2& t2, const T3& t3)
- creates a &interval; using the given &domain; objects.
-
-
- Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)
- creates a &interval; using the given &domain; objects.
-
-
- Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)
- creates a &interval; using the given &domain; objects.
-
-
- Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)
- creates a &interval; using the given &domain; objects.
-
-
- Interval<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)
- creates a &interval; using the given &domain; objects.
-
-
-
-
-
- Constructors for multidimensional &interval;s closely
- follow constructors for multidimensional &loc;s. See .
- &dim; 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
- T1, …, T7, 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 &dim;. 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 &dim;, the intervals for the final
- dimensions are unspecified. See the last paragraph of for an
- analogous example. Note that the &intervalone; constructors
- taking two and three parameters treat these arguments differently
- than the multidimensional constructors do.
-
-
-
-
- ⦥s
-
- A one-dimensional ⦥ generalizes an &interval; by
- permitting a non-unit stride between integral members. A
- range
- 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 &dim; dimensions using the
- direct product of one-dimensional ranges.
-
-
- Declaring One-Dimensional ⦥s
-
-
-
-
- constructor
- result
-
-
-
-
- T1, T2, and
- T3 are template parameters.
-
-
-
-
-
- Range<1>()
- creates an empty, uninitialized range.
-
-
- Range<1>(const Pooma::NoInit& no)
- creates an uninitialized &rangeone;, to be assigned a value later.
-
-
- Range<1>(const T1& t1)
- creates a &rangeone;. See the text for an explanation.
-
-
- Range<1>(const T1& t1, const T2& t2)
- creates a &rangeone; with an interval specified by the
- integers converted from t1 and
- t2.
-
-
- Range<1>(const T1& t1, const T2& t2, const T3& t3)
- creates a &rangeone; by converting the arguments to
- integers i1, i2, and
- i3 and then making a range [i1:i2:i3].
-
-
-
-
-
- &rangeone; constructors are the same as &intervalone;
- constructors except they create ranges, not intervals. See .
- 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 e 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 b and
- e, specifying the range [b:e:1]. The
- three-parameter constructor is similar, with the third argument
- specifying a stride.
-
-
- Declaring Multidimensional ⦥s
-
-
-
-
- constructor
- result
-
-
-
-
- &dim; indicates the ⦥'s dimension.
- T1, T2, … are
- template parameters.
-
-
-
-
- Range<&dim;>()
- creates an empty, uninitialized ⦥, to be assigned a value later.
-
-
- Range<&dim;>(const Pooma::NoInit& no)
- creates an empty, uninitialized ⦥, to be assigned a value later.
-
-
- Range<&dim;>(const T1& t1)
- creates a ⦥ using the given &domain; object.
-
-
- Range<&dim;>(const T1& t1, const T2& t2)
- creates a ⦥ using the given &domain; objects.
-
-
- Range<&dim;>(const T1& t1, const T2& t2, const T3& t3)
- creates a ⦥ using the given &domain; objects.
-
-
- Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)
- creates a ⦥ using the given &domain; objects.
-
-
- Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)
- creates a ⦥ using the given &domain; objects.
-
-
- Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)
- creates a ⦥ using the given &domain; objects.
-
-
- Range<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)
- creates a ⦥ using the given &domain; objects.
-
-
-
-
-
- Constructors for multidimensional ⦥s are the same as
- multidimensional &interval; constructors except they create
- ranges, not intervals. See .
- &dim; 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 T1,
- …, T7, 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 &dim;.
- 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 &dim;, the ranges for the final
- dimensions are unspecified. See the last paragraph of for an
- analogous example. Note that the &rangeone; constructors taking
- two and three parameters treat these arguments differently than
- the multidimensional constructors do.
-
-
-
-
- &grid;s
-
- &loc;s, &interval;s, and ⦥s all have regularly spaced
- integral values so they can be represented using domain triplets.
- 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.
-
- &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.
-
-
- Declaring One-Dimensional &grid;s
-
-
-
-
- constructor
- result
-
-
-
-
- T1, T2, and
- T3 are template parameters.
-
-
-
-
-
- Grid<1>()
- creates an empty, uninitialized grid.
-
-
- Grid<1>(const T1& t1)
- creates a &gridone;. See the text for an explanation.
-
-
- Grid<1>(const T1& t1, const T2& t2)
- creates a &gridone; from the interval specified by the
- integers converted from t1 and
- t2.
-
-
- Grid<1>(const T1& t1, const T2& t2, const T3& t3)
- creates a &gridone; from the domain triplet specified
- by the integers converted from t1,
- t2, and t3.
-
-
-
-
-
- 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
- and the text explanations following
- or .
-
- &gridone;s with irregularly spaced points can be
- constructed using &indirectionlistint;s. For example,
-
- IndirectionList<int> list(4);
- list(0) = 2;
- list(1) = 5;
- list(2) = 6;
- list(3) = 9;
- Grid<1> g(list);
- 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:
-
- 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);
- 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.
-
-
- Declaring Multidimensional &grid;s
-
-
-
-
- constructor
- result
-
-
-
-
- &dim; indicates the &grid;'s dimension.
- T1, T2, … are
- template parameters.
-
-
-
-
- Grid<&dim;>()
- creates an empty, uninitialized &grid;, to be assigned a value later.
-
-
- Grid<&dim;>(const T1& t1)
- creates a &grid; using the given &domain; object.
-
-
- Grid<&dim;>(const T1& t1, const T2& t2)
- creates a &grid; using the given &domain; objects.
-
-
- Grid<&dim;>(const T1& t1, const T2& t2, const T3& t3)
- creates a &grid; using the given &domain; objects.
-
-
- Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4)
- creates a &grid; using the given &domain; objects.
-
-
- Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5)
- creates a &grid; using the given &domain; objects.
-
-
- Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6)
- creates a &grid; using the given &domain; objects.
-
-
- Grid<&dim;>(const T1& t1, const
- T2& t2, const T3& t3, const T4& t4, const T5&
- t5, const T6& t6, const T7& t7)
- creates a &grid; using the given &domain; objects.
-
-
-
-
-
- Constructors for multidimensional &grid;s are the same as
- multidimensional &interval; constructors except they create
- &grid;s, not intervals. See .
- &dim; 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 T1, …,
- T7, 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 &dim;. 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 &dim;, the grids for the final
- dimensions are unspecified. See the last paragraph of for an
- analogous example. Note that the &gridone; constructors taking
- two and three parameters treat these arguments differently than
- the multidimensional constructors do.
-
-
-
-
-
- Declaring and Using &array;s
-
- 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.
-
- &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 (). To avoid being verbose
- in this chapter, when we discuss stored values, the values might
- instead be computed.
-
- 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 view. The
- subset is specified via a &domain; so it is a run-time value.
- Views are presented in .
-
- An &array;'s first template parameter specifies its
- dimensionality. This positive
- integer &dim; 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 &dim; 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.
-
- 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.
-
- 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
- ConstantFunction. 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
- ConstantFunction &engine; returns the same value for
- all indices.
-
- 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 for more information.) Subsets of
- &array; values, frequently used in data-parallel statements, can
- be obtained. (See 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 .
-
- 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 Interval<&dim;>, where &dim; matches
- the &array;'s first template parameter. Since an &interval;
- domain with its unit strides is used, there are no unaccessed
- gaps 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
- . 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.
-
-
- Declaring &array;s
-
-
-
-
- &array; declaration
- result
-
-
-
-
- Template parameters &dim;,
- T, and E indicates the
- &array;'s dimension, value type, and &engine; type,
- respectively, as do D1,
- T1, and E1.
- DT1, …, DT7
- indicate domain types.
-
-
-
-
- Array<&dim;,T,E>()
- creates an empty, uninitialized &array;, which must be
- initialize()d before use.
-
-
-
- Array<&dim;,T,E>(const Array<D1,T1,E1>& a)
- creates an &array; by copying another one.
-
-
- Array<&dim;,T,E>(const
- Array<D1,T1,E1>& a, const Dom& d)
- creates an &array; by copying another one but using the
- specified domain.
-
-
- Array<&dim;,T,E>(const DT1& t1)
- creates an &array; using the given &domain; object.
-
-
- Array<&dim;,T,E>(const DT1& t1, const DT2& t2)
- creates a &array; using the given &domain; objects.
-
-
- Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3)
- creates a &array; using the given &domain; objects.
-
-
- Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4)
- creates a &array; using the given &domain; objects.
-
-
- Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5)
- creates a &array; using the given &domain; objects.
-
-
- Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5, const DT6& t6)
- creates a &array; using the given &domain; objects.
-
-
- 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)
- creates a &array; using the given &domain; objects.
-
-
- Array<&dim;,T,E>(const DT1& t1,
- const ModelElement<T>& model)
- creates an &array; using the given &domain; object and
- then initializes all entries using model.
-
-
- Array<&dim;,T,E>(const DT1& t1, const DT2& t2,
- const ModelElement<T>& model)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
- Array<&dim;,T,E>(const DT1& t1, const DT2& t2, const DT3& t3,
- const ModelElement<T>& model)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
- Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4,
- const ModelElement<T>& model)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
- Array<&dim;,T,E>(const DT1& t1, const
- DT2& t2, const DT3& t3, const DT4& t4, const DT5&
- t5,
- const ModelElement<T>& model)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
- 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)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
- 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)
- creates a &array; using the given &domain; objects and
- then initializes all entries using model.
-
-
-
-
-
- &array; constructors are listed in . An &array;s' three
- template parameters for dimensionality, value type, and engine
- type are abbreviated D, T,
- and E. D1,
- T1, and E1 are analogous.
- Template parameters for &domain; types
-
- HERE
-
- list ?all? possible declarations
- perhaps this involves copying all possible domain declarations
-
- table of initialize() 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
-
-
-
-
- An &array; Implementation of &doof2d;
-
- mostly copy pp.35-38 from tutorial chapter
- HERE
-
-
-
-
- Implementing &array;s
-
- 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
-
-
-
-
-
-
-
Engines
!
! HERE
&data-parallel-chapter;
--- 350,365 ----
&tutorial-chapter;
&concepts-chapter;
! &arrays-chapter;
Engines
! UNFINISHED
+
&data-parallel-chapter;
*************** HERE
*** 1584,1590 ****
Be sure to list the various arithmetic operations on domains
that can be used. This was deferred from the &array; and domain
! chapter.
--- 368,374 ----
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 comp function.
*************** HERE
*** 1592,1605 ****
Writing Sequential Programs
! FIXME: Explain the chapter's purpose.
! HERE
! FIXME: Explain the format of each section.
! HERE
! FIXME: Explain the order of the sections.
! HEREProposed order. Basically follow the order in the proposed
reference section.
--- 376,386 ----
Writing Sequential Programs
! FIXME: Explain the chapter's purpose.
! FIXME: Explain the format of each section.
! FIXME: Explain the order of the sections.Proposed order. Basically follow the order in the proposed
reference section.
*************** HERE
*** 1772,1778 ****
Beginning and Ending &pooma; ProgramsEvery &pooma; program must begin with a call to
! initialize and end with a call to
finalize. These functions respectively
prepare and shut down &pooma;'s run-time structures.
--- 553,559 ----
Beginning and Ending &pooma; ProgramsEvery &pooma; program must begin with a call to
! initialize and end with a call to
finalize. These functions respectively
prepare and shut down &pooma;'s run-time structures.
*************** HERE
*** 1822,1828 ****
DescriptionBefore its use, the &poomatoolkit; must be initialized by a
! call to initialize. This usually occurs in
the main function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments argv and
--- 603,609 ----
DescriptionBefore its use, the &poomatoolkit; must be initialized by a
! call to initialize. This usually occurs in
the main function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments argv and
*************** HERE
*** 1844,1850 ****
architecture-specific initialization. The function always
returns &true;.
! initialize's alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
argv and argc and stored in
--- 625,631 ----
architecture-specific initialization. The function always
returns &true;.
! initialize's alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
argv and argc and stored in
*************** HERE
*** 1872,1878 ****
Example ProgramSince every &pooma; program must call
! initialize and
finalize, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.
--- 653,659 ----
Example ProgramSince every &pooma; program must call
! initialize and
finalize, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.
*************** HERE
*** 1908,1914 ****
&inform; pwarn
! HERE output stream used to print informative messages to the
user while the program executes. The stream accepts a
superset of standard output operations.
--- 689,695 ----
&inform; pwarn
! FIXME: output stream used to print informative messages to the
user while the program executes. The stream accepts a
superset of standard output operations.
*************** HERE
*** 1918,1925 ****
-
-
&pooma; Command-line Options
--- 699,704 ----
*************** UNFINISHED
*** 1944,1961 ****
executes.
!
FIXME: Be sure to list default values.
!
!
-
-
-
-
--- 723,736 ----
executes.
!
FIXME: Be sure to list default values.
!
!