Manual Patch: DynamicArrays and Part of Engines
Jeffrey Oldham
oldham at codesourcery.com
Tue Jan 22 15:55:42 UTC 2002
This patch mainly adds a description of DynamicArrays, an unfinished
section on simple Domain accessors, and an unfinished chapter on
Engines. (Mark, I was working on the Engines chapter, but the Dynamic
Engine led me back to the Arrays chapter. Sorry.)
2002-Jan-22 Jeffrey D. Oldham <oldham at codesourcery.com>
* arrays.xml: Add (unfinished) Domain use section, making Domain
declarations section a subsection of 'Domains' section. Add
DynamicArray section.
* concepts.xml: s/multi-dimensional/multidimensional/g
* glossary.xml (function object): New definition.
s/multi-dimensional/multidimensional/g
* manual.xml: Add unfinished Engines chapter, explaining the
concepts, a table of Engines, and descriptions of Brick and
CompressibleBrick.
s/<methodname>initialize</methodname>/<function>initialize</function>/
as appropriate.
* tutorial.xml: s/multi-dimensional/multidimensional/g
Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: arrays.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/arrays.xml,v
retrieving revision 1.1
diff -c -p -r1.1 arrays.xml
*** arrays.xml 2002/01/16 00:50:27 1.1
--- arrays.xml 2002/01/22 15:37:14
***************
*** 233,968 ****
scientific computations use one, two, or three dimensions, this is
usually sufficient. If more dimensions are needed, they can be
added to the source code.</para>
- </section>
-
- <section id="arrays-domains_declarations">
- <title>Declaring &domain;s</title>
! <para>Since &domain;s are mainly used to declare container
! domains, we focus on declaring &domain;s. Arithmetic operations
! with &domain;s are described in <xref
! linkend="views"></xref>.</para>
!
! <para>All &domain; declarations require a dimension template
! parameter <varname>&dim;</varname>. This positive integer
! specifies the number of dimensions, i.e., rank, of the &domain; and
! determines the length of the tuples for points in the &domain;. For
! example, a three-dimensional &domain; contains ordered triples,
! while a one-dimensional &domain; contains singletons, or just
! integers. Multidimensional &domain;s are just the direct products
! of one-dimensional &domain;s so the techniques for declaring
! one-dimensional &domain;s carry over to multi-dimensional
! ones.</para>
!
! <para>To declare a &domain;, one must include the
! <filename class="headerfile">Pooma/Domains.h</filename> header
! file. However, most &pooma; programs declare &domain;s to use them
! when constructing containers. The container header files
! automatically include <filename
! class="headerfile">Pooma/Domains.h</filename> so no explicit
! inclusion is usually necessary.</para>
!
! <section id="arrays-domains_declarations-loc">
! <title>&loc;s</title>
!
! <para>A <type>Loc<&dim;></type> is a &domain; with just a single
! <varname>&dim;</varname>-dimensional point. Although it is
! infrequently used as a container's domain, it is used to refer to
! a single point within another domain. Its beginning and ending
! points are the same, and its stride is one. One-dimensional
! &loc;s and integers are frequently interchanged.</para>
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-loc-one_d_table">
! <title>Declaring One-Dimensional &loc;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Loc<1>()</statement></entry>
! <entry>points to zero.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &locone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &locone; with the integer converted from <varname>t1</varname>.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &locone; with the integer converted from
! <varname>t1</varname>. <varname>t2</varname> must equal
! <varname>t1</varname>.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &locone; with the integer converted from
! <varname>t1</varname>. <varname>t2</varname> must equal
! <varname>t1</varname>, and <varname>t3</varname> is
! ignored.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for one-dimensional &loc;s appear in <xref
! linkend="arrays-domains_declarations-loc-one_d_table"></xref>.
! The empty constructor yields the zero point. The constructor
! taking a <type>Pooma::Init</type> object does not initialize the
! resulting &loc; to any particular value. Presumably, the value
! will be assigned later. For small &domain;s such as &loc;s, the
! time savings from not initializing is small, but the
! functionality is still available. The constructor taking one
! argument with type <type>&domaintemplate;1</type> converts this argument to
! an integer to specify the point. The template
! type <type>&domaintemplate;1</type> may be any type that can be converted
! to an integer, e.g., &bool;, &char;, ∫, or &double;. The
! constructors taking two and three arguments of templatized types
! facilitate converting an &interval; and a ⦥ into a &loc;.
! Since a &loc; represents a single point, the &interval;'s or
! ⦥'s first two arguments must be equal. The stride is
! ignored. Again, the templatized types may be any type that can
! be converted into an integer.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-loc-multi_d_table">
! <title>Declaring Multidimensional &loc;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &loc;'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Loc<&dim;>()</statement></entry>
! <entry>points to zero.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &loc;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &loc; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &loc;s appear in <xref
! linkend="arrays-domains_declarations-loc-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &loc;'s dimension. The
! first two constructors are similar to &locone;'s first two
! constructors, returning a representation of the zero point and
! returning an uninitialized point. The seven other constructors
! create a &loc; using other &domain; objects. These &domain; objects,
! having types <type>&domaintemplate;1</type>, …, <type>&domaintemplate;7</type>, can have
! any type that can be converted into an integer, to a &locone;, or
! to a multidimensional &domain; object that itself can be converted
! into a &loc;. The total dimensionality of all the arguments'
! types should be at most <varname>&dim;</varname>. For example,
! <statement>Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
! Interval<1>(4,4))</statement> creates a five-dimensional &loc;
! [2,2,3,4,1] using a one-dimensional ⦥, a two-dimensional
! &loc;, and a one-dimensional &interval;. The final fifth
! dimension has an unspecified value, in this case 1. The
! one-dimensional ⦥ is converted into the single integer two;
! its beginning and ending points must be the same. The
! two-dimensional &loc; contributes values for the next two
! dimensions, while the &interval; contributes its beginning point,
! which must be the same as its ending point. Note that the
! &locone; constructors taking two and three parameters ignore
! their second and third arguments, but this is not true for the
! multidimensional constructors.</para>
</section>
-
- <section id="arrays-domains_declarations-intervals">
- <title>&interval;s</title>
-
- <para>A one-dimensional &interval; represents a set of integers
- within a mathematical <glossterm
- linkend="glossary-interval">interval</glossterm>.
- Multidimensional &interval;s represent their multidimensional
- generalization, i.e., the direct product of one-dimensional
- intervals. &interval;s are arguably the most commonly used
- &pooma; &domain;. A one-dimensional &interval; has integral
- beginning and ending points and a unit stride.</para>
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-interval-one_d_table">
! <title>Declaring One-Dimensional &interval;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Interval<1>()</statement></entry>
! <entry>creates an empty, uninitialized interval.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &intervalone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &intervalone;. See the text for an explanation.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &intervalone; with the integers converted from
! <varname>t1</varname> and <varname>t2</varname>.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &intervalone; with the integers converted from
! <varname>t1</varname> and <varname>t2</varname>.
! <varname>t3</varname> must equal 1.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>&intervalone; constructors are patterned on &locone;
! constructors except that &intervalone;s can have differing
! beginning and ending points. See <xref
! linkend="arrays-domains_declarations-interval-one_d_table"></xref>.
! The default constructor creates an empty, uninitialized interval,
! which should not be used before assigning it values. If the
! one-parameter constructor's argument is a &domain; object, it must
! be a one-dimensional &domain; object which is copied into an
! &interval; if possible; for example, it must have unit stride.
! If the one-parameter constructor's argument is not a &domain;
! object, it must be convertible to an
! integer <varname>e</varname> and an interval [0:e-1:1]
! starting at zero is constructed. If two arguments are specified,
! they are assumed to be convertible to integers
! <varname>b</varname> and <varname>e</varname>, specifying the
! interval [b:e:1]. The three-parameter constructor is similar,
! with the third argument specifying a stride, which must be
! one.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-intervals-multi_d_table">
! <title>Declaring Multidimensional &interval;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &interval;'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Interval<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &interval; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &interval;s closely
! follow constructors for multidimensional &loc;s. See <xref
! linkend="arrays-domains_declarations-intervals-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &interval;'s
! dimension. The first two constructors both return empty,
! uninitialized intervals. The seven other constructors create an
! &interval; using &domain; objects. These &domain; objects,
! having types <type>&domaintemplate;1</type>, …,
! <type>&domaintemplate;7</type>, can have any type that can be
! converted into an integer, into a single-dimensional &domain;
! object that can be converted into a single-dimensional
! &interval;, or to a multidimensional &domain; object that itself
! can be converted into an &interval;. The total dimensionality of
! all the arguments' types should be at
! most <varname>&dim;</varname>. One-dimensional &domain;
! objects that can be converted into one-dimensional &interval;s
! include &locone;s, &intervalone;s, and &rangeone;s with unit
! strides. If the sum of the objects' dimensions is less
! than <varname>&dim;</varname>, the intervals for the final
! dimensions are unspecified. See the last paragraph of <xref
! linkend="arrays-domains_declarations-loc"></xref> for an
! analogous example. Note that the &intervalone; constructors
! taking two and three parameters treat these arguments differently
! than the multidimensional constructors do.</para>
! </section>
!
!
! <section id="arrays-domains_declarations-ranges">
! <title>⦥s</title>
!
! <para>A one-dimensional ⦥ generalizes an &interval; by
! permitting a non-unit stride between integral members. A
! <glossterm
! linkend="glossary-range"><firstterm>range</firstterm></glossterm>
! is a set of integers in a mathematical interval [b,e] with a
! stride s between them: {a, a+s, a+2s, …, b}. Ranges
! are generalized to <varname>&dim;</varname> dimensions using the
! direct product of one-dimensional ranges.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-range-one_d_table">
! <title>Declaring One-Dimensional ⦥s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Range<1>()</statement></entry>
! <entry>creates an empty, uninitialized range.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &rangeone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &rangeone;. See the text for an explanation.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &rangeone; with an interval specified by the
! integers converted from <varname>t1</varname> and
! <varname>t2</varname>.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &rangeone; by converting the arguments to
! integers <varname>i1</varname>, <varname>i2</varname>, and
! <varname>i3</varname> and then making a range [i1:i2:i3].</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
! <para>&rangeone; constructors are the same as &intervalone;
! constructors except they create ranges, not intervals. See <xref
! linkend="arrays-domains_declarations-range-one_d_table"></xref>.
! The default constructor creates an empty, uninitialized range,
! which should not be used before assigning it values. If the
! one-parameter constructor's argument is a &domain; object, it must
! be a one-dimensional &domain; object which is copied into a ⦥
! if possible. If the one-parameter constructor's argument is not
! a &domain; object, it must be convertible to an
! integer <varname>e</varname> and a range [0:e-1:1] starting
! at zero is constructed. If two arguments are specified, they are
! assumed to be convertible to integers <varname>b</varname> and
! <varname>e</varname>, specifying the range [b:e:1]. The
! three-parameter constructor is similar, with the third argument
! specifying a stride.</para>
<table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-ranges-multi_d_table">
! <title>Declaring Multidimensional ⦥s</title>
<tgroup cols="2" align="left">
<thead>
<row>
! <entry>constructor</entry>
<entry>result</entry>
</row>
</thead>
<tfoot>
<row>
! <entry><varname>&dim;</varname> indicates the ⦥'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
</row>
</tfoot>
<tbody>
! <row>
! <entry><statement>Range<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a ⦥ using the given &domain; object.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
<row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
</row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Constructors for multidimensional ⦥s are the same as
- multidimensional &interval; constructors except they create
- ranges, not intervals. See <xref
- linkend="arrays-domains_declarations-ranges-multi_d_table"></xref>.
- <varname>&dim;</varname> indicates the ⦥'s dimension. The
- first two constructors return empty, uninitialized ranges.
- The seven other constructors create an ⦥ using &domain;
- objects. These &domain; objects, having types <type>&domaintemplate;1</type>,
- …, <type>&domaintemplate;7</type>, can have any type that can be
- converted into an integer, into a single-dimensional &domain;
- object that can be converted into a single-dimensional ⦥,
- or to a multidimensional &domain; object that itself can be
- converted into an ⦥. The total dimensionality of all the
- arguments' types should be at most <varname>&dim;</varname>.
- One-dimensional &domain; objects that can be converted into
- one-dimensional ⦥s include &locone;s, &intervalone;s, and
- &rangeone;s. If the sum of the objects' dimensions is less
- than <varname>&dim;</varname>, the ranges for the final
- dimensions are unspecified. See the last paragraph of <xref
- linkend="arrays-domains_declarations-loc"></xref> for an
- analogous example. Note that the &rangeone; constructors taking
- two and three parameters treat these arguments differently than
- the multidimensional constructors do.</para>
- </section>
-
-
- <section id="arrays-domains_declarations-grids">
- <title>&grid;s</title>
-
- <para>&loc;s, &interval;s, and ⦥s all have regularly spaced
- integral values so they can be represented using <glossterm
- linkend="glossary-domain_triplet">domain triplets</glossterm>.
- One-dimensional &grid; integral domains contain ascending or
- descending sequences of integers, with no fixed stride. For
- example, a &gridone; may represent {-13, 1, 4, 5, 34}. &gridone;
- is generalized to multidimensional &grid;s using the direct
- product of &gridone; &domain;s.</para>
-
- <para>&grid;s that can be represented using domain triplets can
- be constructed using techniques similar to other &domain;s, but
- irregularly spaced domains can be constructed using
- &indirectionlistint;s.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="arrays-domains_declarations-grid-one_d_table">
- <title>Declaring One-Dimensional &grid;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
<row>
! <entry>constructor</entry>
! <entry>result</entry>
</row>
- </thead>
- <tfoot>
<row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
</row>
- </tfoot>
- <tbody>
- <row>
- <entry><statement>Grid<1>()</statement></entry>
- <entry>creates an empty, uninitialized grid.</entry>
- </row>
- <row>
- <entry><statement>Grid<1>(const &domaintemplate;1& t1)</statement></entry>
- <entry>creates a &gridone;. See the text for an explanation.</entry>
- </row>
<row>
! <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &gridone; from the interval specified by the
! integers converted from <varname>t1</varname> and
! <varname>t2</varname>.</entry>
</row>
- <row>
- <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
- <entry>creates a &gridone; from the domain triplet specified
- by the integers converted from <varname>t1</varname>,
- <varname>t2</varname>, and <varname>t3</varname>.</entry>
- </row>
</tbody>
</tgroup>
</table>
! <para>To construct a &gridone; that can also be represented by a
! domain triplet, use a &gridone; constructor similar to those for
! &intervalone; and &rangeone;. See <xref
! linkend="arrays-domains_declarations-grid-one_d_table"></xref>
! and the text explanations following <xref
! linkend="arrays-domains_declarations-range-one_d_table"></xref>
! or <xref
! linkend="arrays-domains_declarations-interval-one_d_table"></xref>.</para>
! <para>&gridone;s with irregularly spaced points can be
! constructed using &indirectionlistint;s. For example,
! <programlisting>
! IndirectionList<int> list(4);
! list(0) = 2;
! list(1) = 5;
! list(2) = 6;
! list(3) = 9;
! Grid<1> g(list);
! </programlisting> constructs an empty &indirectionlistint;, fills it
! with ascending values, and then creates a &gridone; containing
! {2, 5, 6, 9}. When creating a list, its size must be specified.
! Subsequently, its values can be assigned. &indirectionlist;s can
! also be initialized using one-dimensional &array;s:
! <programlisting>
! Array<1,int,Brick> a1(Interval<1>(0,3));
! a1(0) = 2; a1(1) = 5; a1(2) = 6; a1(3) = 9;
! IndirectionList<int> il(a1);
! Grid<1> g1(il);
! </programlisting> The &array; stores the integral points to include
! in the &gridone; and is used to create the &indirectionlistint;,
! which itself is used to create the &gridone;. Since the points
! are integers, the &array;'s type is ∫. Either a &brick; or
! &compressiblebrick; &engine; should be used.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains_declarations-grids-multi_d_table">
! <title>Declaring Multidimensional &grid;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &grid;'s
! dimension. <varname>&domaintemplate;1</varname>,
! <varname>&domaintemplate;2</varname>, … are template
! parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Grid<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized &grid;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &grid; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &grid;s are the same as
! multidimensional &interval; constructors except they create
! &grid;s, not intervals. See <xref
! linkend="arrays-domains_declarations-grids-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &grid;'s dimension. The
! first constructor returns empty, uninitialized grids. The seven
! other constructors create an &grid; using &domain; objects. These
! &domain; objects, having types <type>&domaintemplate;1</type>, …,
! <type>&domaintemplate;7</type>, can have any type that can be converted into an
! integer, into a single-dimensional &domain; object that can be
! converted into a single-dimensional &grid;, or to a
! multidimensional &domain; object that itself can be converted into
! an &grid;. The total dimensionality of all the arguments' types
! should be at most <varname>&dim;</varname>. One-dimensional
! &domain; objects that can be converted into one-dimensional &grid;s
! include &locone;s, &intervalone;s, &rangeone;s, and &gridone;s.
! If the sum of the objects' dimensions is less
! than <varname>&dim;</varname>, the grids for the final
! dimensions are unspecified. See the last paragraph of <xref
! linkend="arrays-domains_declarations-loc"></xref> for an
! analogous example. Note that the &gridone; constructors taking
! two and three parameters treat these arguments differently than
! the multidimensional constructors do.</para>
! </section>
</section>
<section id="arrays-arrays_declarations">
<title>Declaring &array;s</title>
<para>A &pooma; &array; maps indices from its &domain; to values.
! In this section, we describe first describe how to declare
! &array;s. In the next section, we explain how to access
! individual values stored within an &array; and &array; copy
! semantics.</para>
<para>&array; values need not just be stored values, as &c; arrays
have. They can also be computed using its engine. We defer
--- 233,1063 ----
scientific computations use one, two, or three dimensions, this is
usually sufficient. If more dimensions are needed, they can be
added to the source code.</para>
! <section id="arrays-domains-declarations">
! <title>Declaring &domain;s</title>
! <para>Since &domain;s are mainly used to declare container
! domains, we focus on declaring &domain;s. We describe a few
! &domain; operations but most, including arithmetic operations with
! &domain;s, are described in <xref linkend="views"></xref>.</para>
!
! <para>All &domain; declarations require a dimension template
! parameter <varname>&dim;</varname>. This positive integer
! specifies the number of dimensions, i.e., rank, of the &domain; and
! determines the length of the tuples for points in the &domain;. For
! example, a three-dimensional &domain; contains ordered triples,
! while a one-dimensional &domain; contains singletons, or just
! integers. Multidimensional &domain;s are just the direct products
! of one-dimensional &domain;s so the techniques for declaring
! one-dimensional &domain;s carry over to multidimensional
! ones.</para>
!
! <para>To declare a &domain;, one must include the
! <filename class="headerfile">Pooma/Domains.h</filename> header
! file. However, most &pooma; programs declare &domain;s to use them
! when constructing containers. The container header files
! automatically include <filename
! class="headerfile">Pooma/Domains.h</filename> so no explicit
! inclusion is usually necessary.</para>
!
!
! <section id="arrays-domains-declarations-loc">
! <title>&loc;s</title>
!
! <para>A <type>Loc<&dim;></type> is a &domain; with just a single
! <varname>&dim;</varname>-dimensional point. Although it is
! infrequently used as a container's domain, it is used to refer to
! a single point within another domain. Its beginning and ending
! points are the same, and its stride is one. One-dimensional
! &loc;s and integers are frequently interchanged.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-loc-one_d_table">
! <title>Declaring One-Dimensional &loc;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Loc<1>()</statement></entry>
! <entry>points to zero.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &locone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &locone; with the integer converted from <varname>t1</varname>.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &locone; with the integer converted from
! <varname>t1</varname>. <varname>t2</varname> must equal
! <varname>t1</varname>.</entry>
! </row>
! <row>
! <entry><statement>Loc<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &locone; with the integer converted from
! <varname>t1</varname>. <varname>t2</varname> must equal
! <varname>t1</varname>, and <varname>t3</varname> is
! ignored.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for one-dimensional &loc;s appear in <xref
! linkend="arrays-domains-declarations-loc-one_d_table"></xref>.
! The empty constructor yields the zero point. The constructor
! taking a <type>Pooma::Init</type> object does not initialize the
! resulting &loc; to any particular value. Presumably, the value
! will be assigned later. For small &domain;s such as &loc;s, the
! time savings from not initializing is small, but the
! functionality is still available. The constructor taking one
! argument with type <type>&domaintemplate;1</type> converts this argument to
! an integer to specify the point. The template
! type <type>&domaintemplate;1</type> may be any type that can be converted
! to an integer, e.g., &bool;, &char;, ∫, or &double;. The
! constructors taking two and three arguments of templatized types
! facilitate converting an &interval; and a ⦥ into a &loc;.
! Since a &loc; represents a single point, the &interval;'s or
! ⦥'s first two arguments must be equal. The stride is
! ignored. Again, the templatized types may be any type that can
! be converted into an integer.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-loc-multi_d_table">
! <title>Declaring Multidimensional &loc;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &loc;'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Loc<&dim;>()</statement></entry>
! <entry>points to zero.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &loc;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &loc; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Loc<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &loc; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &loc;s appear in <xref
! linkend="arrays-domains-declarations-loc-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &loc;'s dimension. The
! first two constructors are similar to &locone;'s first two
! constructors, returning a representation of the zero point and
! returning an uninitialized point. The seven other constructors
! create a &loc; using other &domain; objects. These &domain; objects,
! having types <type>&domaintemplate;1</type>, …, <type>&domaintemplate;7</type>, can have
! any type that can be converted into an integer, to a &locone;, or
! to a multidimensional &domain; object that itself can be converted
! into a &loc;. The total dimensionality of all the arguments'
! types should be at most <varname>&dim;</varname>. For example,
! <statement>Loc<5>(Range<1>(2,2,2), Loc<2>(2,3),
! Interval<1>(4,4))</statement> creates a five-dimensional &loc;
! [2,2,3,4,1] using a one-dimensional ⦥, a two-dimensional
! &loc;, and a one-dimensional &interval;. The final fifth
! dimension has an unspecified value, in this case 1. The
! one-dimensional ⦥ is converted into the single integer two;
! its beginning and ending points must be the same. The
! two-dimensional &loc; contributes values for the next two
! dimensions, while the &interval; contributes its beginning point,
! which must be the same as its ending point. Note that the
! &locone; constructors taking two and three parameters ignore
! their second and third arguments, but this is not true for the
! multidimensional constructors.</para>
! </section>
!
!
! <section id="arrays-domains-declarations-intervals">
! <title>&interval;s</title>
!
! <para>A one-dimensional &interval; represents a set of integers
! within a mathematical <glossterm
! linkend="glossary-interval">interval</glossterm>.
! Multidimensional &interval;s represent their multidimensional
! generalization, i.e., the direct product of one-dimensional
! intervals. &interval;s are arguably the most commonly used
! &pooma; &domain;. A one-dimensional &interval; has integral
! beginning and ending points and a unit stride.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-interval-one_d_table">
! <title>Declaring One-Dimensional &interval;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Interval<1>()</statement></entry>
! <entry>creates an empty, uninitialized interval.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &intervalone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &intervalone;. See the text for an explanation.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &intervalone; with the integers converted from
! <varname>t1</varname> and <varname>t2</varname>.</entry>
! </row>
! <row>
! <entry><statement>Interval<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &intervalone; with the integers converted from
! <varname>t1</varname> and <varname>t2</varname>.
! <varname>t3</varname> must equal 1.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>&intervalone; constructors are patterned on &locone;
! constructors except that &intervalone;s can have differing
! beginning and ending points. See <xref
! linkend="arrays-domains-declarations-interval-one_d_table"></xref>.
! The default constructor creates an empty, uninitialized interval,
! which should not be used before assigning it values. If the
! one-parameter constructor's argument is a &domain; object, it must
! be a one-dimensional &domain; object which is copied into an
! &interval; if possible; for example, it must have unit stride.
! If the one-parameter constructor's argument is not a &domain;
! object, it must be convertible to an
! integer <varname>e</varname> and an interval [0:e-1:1]
! starting at zero is constructed. If two arguments are specified,
! they are assumed to be convertible to integers
! <varname>b</varname> and <varname>e</varname>, specifying the
! interval [b:e:1]. The three-parameter constructor is similar,
! with the third argument specifying a stride, which must be
! one.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-intervals-multi_d_table">
! <title>Declaring Multidimensional &interval;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &interval;'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Interval<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an empty, uninitialized &interval;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &interval; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Interval<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &interval; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &interval;s closely
! follow constructors for multidimensional &loc;s. See <xref
! linkend="arrays-domains-declarations-intervals-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &interval;'s
! dimension. The first two constructors both return empty,
! uninitialized intervals. The seven other constructors create an
! &interval; using &domain; objects. These &domain; objects,
! having types <type>&domaintemplate;1</type>, …,
! <type>&domaintemplate;7</type>, can have any type that can be
! converted into an integer, into a single-dimensional &domain;
! object that can be converted into a single-dimensional
! &interval;, or to a multidimensional &domain; object that itself
! can be converted into an &interval;. The total dimensionality of
! all the arguments' types should be at
! most <varname>&dim;</varname>. One-dimensional &domain;
! objects that can be converted into one-dimensional &interval;s
! include &locone;s, &intervalone;s, and &rangeone;s with unit
! strides. If the sum of the objects' dimensions is less
! than <varname>&dim;</varname>, the intervals for the final
! dimensions are unspecified. See the last paragraph of <xref
! linkend="arrays-domains-declarations-loc"></xref> for an
! analogous example. Note that the &intervalone; constructors
! taking two and three parameters treat these arguments differently
! than the multidimensional constructors do.</para>
! </section>
!
!
! <section id="arrays-domains-declarations-ranges">
! <title>⦥s</title>
!
! <para>A one-dimensional ⦥ generalizes an &interval; by
! permitting a non-unit stride between integral members. A
! <glossterm
! linkend="glossary-range"><firstterm>range</firstterm></glossterm>
! is a set of integers in a mathematical interval [b,e] with a
! stride s between them: {a, a+s, a+2s, …, b}. Ranges
! are generalized to <varname>&dim;</varname> dimensions using the
! direct product of one-dimensional ranges.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-range-one_d_table">
! <title>Declaring One-Dimensional ⦥s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Range<1>()</statement></entry>
! <entry>creates an empty, uninitialized range.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an uninitialized &rangeone;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &rangeone;. See the text for an explanation.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &rangeone; with an interval specified by the
! integers converted from <varname>t1</varname> and
! <varname>t2</varname>.</entry>
! </row>
! <row>
! <entry><statement>Range<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &rangeone; by converting the arguments to
! integers <varname>i1</varname>, <varname>i2</varname>, and
! <varname>i3</varname> and then making a range [i1:i2:i3].</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>&rangeone; constructors are the same as &intervalone;
! constructors except they create ranges, not intervals. See <xref
! linkend="arrays-domains-declarations-range-one_d_table"></xref>.
! The default constructor creates an empty, uninitialized range,
! which should not be used before assigning it values. If the
! one-parameter constructor's argument is a &domain; object, it must
! be a one-dimensional &domain; object which is copied into a ⦥
! if possible. If the one-parameter constructor's argument is not
! a &domain; object, it must be convertible to an
! integer <varname>e</varname> and a range [0:e-1:1] starting
! at zero is constructed. If two arguments are specified, they are
! assumed to be convertible to integers <varname>b</varname> and
! <varname>e</varname>, specifying the range [b:e:1]. The
! three-parameter constructor is similar, with the third argument
! specifying a stride.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-ranges-multi_d_table">
! <title>Declaring Multidimensional ⦥s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the ⦥'s dimension.
! <varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, … are
! template parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Range<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const Pooma::NoInit& no)</statement></entry>
! <entry>creates an empty, uninitialized ⦥, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a ⦥ using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Range<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a ⦥ using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional ⦥s are the same as
! multidimensional &interval; constructors except they create
! ranges, not intervals. See <xref
! linkend="arrays-domains-declarations-ranges-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the ⦥'s dimension. The
! first two constructors return empty, uninitialized ranges.
! The seven other constructors create an ⦥ using &domain;
! objects. These &domain; objects, having types <type>&domaintemplate;1</type>,
! …, <type>&domaintemplate;7</type>, can have any type that can be
! converted into an integer, into a single-dimensional &domain;
! object that can be converted into a single-dimensional ⦥,
! or to a multidimensional &domain; object that itself can be
! converted into an ⦥. The total dimensionality of all the
! arguments' types should be at most <varname>&dim;</varname>.
! One-dimensional &domain; objects that can be converted into
! one-dimensional ⦥s include &locone;s, &intervalone;s, and
! &rangeone;s. If the sum of the objects' dimensions is less
! than <varname>&dim;</varname>, the ranges for the final
! dimensions are unspecified. See the last paragraph of <xref
! linkend="arrays-domains-declarations-loc"></xref> for an
! analogous example. Note that the &rangeone; constructors taking
! two and three parameters treat these arguments differently than
! the multidimensional constructors do.</para>
! </section>
!
!
! <section id="arrays-domains-declarations-grids">
! <title>&grid;s</title>
!
! <para>&loc;s, &interval;s, and ⦥s all have regularly spaced
! integral values so they can be represented using <glossterm
! linkend="glossary-domain_triplet">domain triplets</glossterm>.
! One-dimensional &grid; integral domains contain ascending or
! descending sequences of integers, with no fixed stride. For
! example, a &gridone; may represent {-13, 1, 4, 5, 34}. &gridone;
! is generalized to multidimensional &grid;s using the direct
! product of &gridone; &domain;s.</para>
!
! <para>&grid;s that can be represented using domain triplets can
! be constructed using techniques similar to other &domain;s, but
! irregularly spaced domains can be constructed using
! &indirectionlistint;s.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-grid-one_d_table">
! <title>Declaring One-Dimensional &grid;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&domaintemplate;1</varname>, <varname>&domaintemplate;2</varname>, and
! <varname>&domaintemplate;3</varname> are template parameters.</entry>
! <entry></entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Grid<1>()</statement></entry>
! <entry>creates an empty, uninitialized grid.</entry>
! </row>
! <row>
! <entry><statement>Grid<1>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &gridone;. See the text for an explanation.</entry>
! </row>
! <row>
! <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &gridone; from the interval specified by the
! integers converted from <varname>t1</varname> and
! <varname>t2</varname>.</entry>
! </row>
! <row>
! <entry><statement>Grid<1>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &gridone; from the domain triplet specified
! by the integers converted from <varname>t1</varname>,
! <varname>t2</varname>, and <varname>t3</varname>.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>To construct a &gridone; that can also be represented by a
! domain triplet, use a &gridone; constructor similar to those for
! &intervalone; and &rangeone;. See <xref
! linkend="arrays-domains-declarations-grid-one_d_table"></xref>
! and the text explanations following <xref
! linkend="arrays-domains-declarations-range-one_d_table"></xref>
! or <xref
! linkend="arrays-domains-declarations-interval-one_d_table"></xref>.</para>
!
! <para>&gridone;s with irregularly spaced points can be
! constructed using &indirectionlistint;s. For example,
! <programlisting>
! IndirectionList<int> list(4);
! list(0) = 2;
! list(1) = 5;
! list(2) = 6;
! list(3) = 9;
! Grid<1> g(list);
! </programlisting> constructs an empty &indirectionlistint;, fills it
! with ascending values, and then creates a &gridone; containing
! {2, 5, 6, 9}. When creating a list, its size must be specified.
! Subsequently, its values can be assigned. &indirectionlist;s can
! also be initialized using one-dimensional &array;s:
! <programlisting>
! Array<1,int,Brick> a1(Interval<1>(0,3));
! a1(0) = 2; a1(1) = 5; a1(2) = 6; a1(3) = 9;
! IndirectionList<int> il(a1);
! Grid<1> g1(il);
! </programlisting> The &array; stores the integral points to include
! in the &gridone; and is used to create the &indirectionlistint;,
! which itself is used to create the &gridone;. Since the points
! are integers, the &array;'s type is ∫. Either a &brick; or
! &compressiblebrick; &engine; should be used.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-declarations-grids-multi_d_table">
! <title>Declaring Multidimensional &grid;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>constructor</entry>
! <entry>result</entry>
! </row>
! </thead>
! <tfoot>
! <row>
! <entry><varname>&dim;</varname> indicates the &grid;'s
! dimension. <varname>&domaintemplate;1</varname>,
! <varname>&domaintemplate;2</varname>, … are template
! parameters.</entry>
! </row>
! </tfoot>
! <tbody>
! <row>
! <entry><statement>Grid<&dim;>()</statement></entry>
! <entry>creates an empty, uninitialized &grid;, to be assigned a value later.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1)</statement></entry>
! <entry>creates a &grid; using the given &domain; object.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const &domaintemplate;2& t2, const &domaintemplate;3& t3)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! <row>
! <entry><statement>Grid<&dim;>(const &domaintemplate;1& t1, const
! &domaintemplate;2& t2, const &domaintemplate;3& t3, const &domaintemplate;4& t4, const &domaintemplate;5&
! t5, const &domaintemplate;6& t6, const &domaintemplate;7& t7)</statement></entry>
! <entry>creates a &grid; using the given &domain; objects.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>Constructors for multidimensional &grid;s are the same as
! multidimensional &interval; constructors except they create
! &grid;s, not intervals. See <xref
! linkend="arrays-domains-declarations-grids-multi_d_table"></xref>.
! <varname>&dim;</varname> indicates the &grid;'s dimension. The
! first constructor returns empty, uninitialized grids. The seven
! other constructors create an &grid; using &domain; objects. These
! &domain; objects, having types <type>&domaintemplate;1</type>, …,
! <type>&domaintemplate;7</type>, can have any type that can be converted into an
! integer, into a single-dimensional &domain; object that can be
! converted into a single-dimensional &grid;, or to a
! multidimensional &domain; object that itself can be converted into
! an &grid;. The total dimensionality of all the arguments' types
! should be at most <varname>&dim;</varname>. One-dimensional
! &domain; objects that can be converted into one-dimensional &grid;s
! include &locone;s, &intervalone;s, &rangeone;s, and &gridone;s.
! If the sum of the objects' dimensions is less
! than <varname>&dim;</varname>, the grids for the final
! dimensions are unspecified. See the last paragraph of <xref
! linkend="arrays-domains-declarations-loc"></xref> for an
! analogous example. Note that the &gridone; constructors taking
! two and three parameters treat these arguments differently than
! the multidimensional constructors do.</para>
! </section>
</section>
! <section id="arrays-domains-use">
! <title>Using &domain;s</title>
! <para>Since an &array; can be queried for its domain, we briefly
! describe some &domain; operations. A fuller description,
! including arithmetic operations, occur in <xref
! linkend="views"></xref>.</para>
<table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="arrays-domains-use-table">
! <title>Some &domain; Accessors</title>
<tgroup cols="2" align="left">
<thead>
<row>
! <entry>&domain; member function</entry>
<entry>result</entry>
</row>
</thead>
<tfoot>
<row>
! <entry>Other &domain; accessors are described in <xref
! linkend="views"></xref>.</entry>
</row>
</tfoot>
<tbody>
! <row rowsep="1">
! <entry>Multidimensional &domain; Accessors</entry>
</row>
<row>
! <entry><statement>long size()</statement></entry>
! <entry>returns the total number of indices.</entry>
</row>
<row>
! <entry><statement>bool empty()</statement></entry>
! <entry>returns &true; if and only if the &domain; has no indices.</entry>
</row>
<row>
! <entry><statement>D<1> operator[](int dimension)</statement></entry>
! <entry>returns the one-dimensional &domain; for the specified
! dimension. The return type is a one-dimensional version of
! the &domain;.</entry>
</row>
! <row rowsep="1">
! <entry>One-dimensional &domain; Accessors</entry>
</row>
<row>
! <entry><statement>long length()</statement></entry>
! <entry>returns the number of indices.</entry>
</row>
<row>
! <entry><statement>int first()</statement></entry>
! <entry>returns the beginning of the domain.</entry>
</row>
<row>
! <entry><statement>int last()</statement></entry>
! <entry>returns the ending of the domain.</entry>
</row>
<row>
! <entry><statement>int min()</statement></entry>
! <entry>returns the minimum index in the domain.</entry>
</row>
<row>
! <entry><statement>int max()</statement></entry>
! <entry>returns the maximum index in the domain.</entry>
</row>
<row>
! <entry><statement>D<1>::iterator begin()</statement></entry>
! <entry>returns a bidirectional iterator pointing to the
! beginning domain index.</entry>
</row>
<row>
! <entry><statement>D<1>::iterator end()</statement></entry>
! <entry>returns a bidirectional iterator pointing to the ending
! domain index.</entry>
</row>
</tbody>
</tgroup>
</table>
! <para>&domain; member functions are listed in <xref
! linkend="arrays-domains-use-table"></xref>. Functions applicable
! to one-dimensional and multidimensional &domain;s are listed
! before functions that only applicable to one-dimensional
! &domain;s. The <methodname>size</methodname> member function
! yields the total number of indices in a given &domain;. If and
! only if this number is zero, <methodname>empty</methodname> will
! yield &true;. A multidimensional
! <type>domain<&dim;></type> is the direct product of &dim;
! one-dimensional &domain;s.
! HERE</para>
</section>
+ </section>
<section id="arrays-arrays_declarations">
<title>Declaring &array;s</title>
<para>A &pooma; &array; maps indices from its &domain; to values.
! In this section, we first describe how to declare &array;s. In
! the next section, we explain how to access individual values
! stored within an &array; and &array; copy semantics.</para>
<para>&array; values need not just be stored values, as &c; arrays
have. They can also be computed using its engine. We defer
*************** Grid<1> g1(il);
*** 1195,1201 ****
compute the resulting &array;'s domain. These are combined in the
same way that multidimensional &interval;s are constructed. (See
<xref
! linkend="arrays-domains_declarations-intervals-multi_d_table"></xref>
and the following text.) The domain objects, having types
<type>&domaintemplate;1</type>, …,
<type>&domaintemplate;7</type>, can have any type that can be
--- 1290,1296 ----
compute the resulting &array;'s domain. These are combined in the
same way that multidimensional &interval;s are constructed. (See
<xref
! linkend="arrays-domains-declarations-intervals-multi_d_table"></xref>
and the following text.) The domain objects, having types
<type>&domaintemplate;1</type>, …,
<type>&domaintemplate;7</type>, can have any type that can be
*************** std::cout &openopen; a.read(2,-2) &openo
*** 1715,1720 ****
--- 1810,2129 ----
which its <methodname>first</methodname> extracts the length. The
<methodname>length</methodname> &array; member function is used in
the <function>PAssert</function>.</para>
+ </section>
+
+
+ <section id="arrays-dynamic_arrays">
+ <title>&dynamicarray;s: Dynamically Changing Domain Sizes</title>
+
+ <para>&array;s have fixed domains so the set of valid indices
+ remains fixed after declaration. The &dynamicarray; class
+ supports one-dimensional domains that can be resized even while
+ the array is used.</para>
+
+ <para>&dynamicarray;'s interface extends the one-dimensional
+ interface of an &array; by adding member functions to change the
+ domain's size. It is declared in <filename
+ class="libraryfile">Pooma/DynamicArrays.h</filename>. A
+ &dynamicarray; has two, not three, template parameters, omitting
+ the array's dimensionality. The first
+ parameter <type>T</type> specifies the type of stored values.
+ Its default value is usually &double;, but it may be changed when
+ the &poomatoolkit; is configured. The second parameter specifies
+ an &engine; via a tag. The engine must support a domain with
+ dynamic resizing. For example, the &dynamic; &engine; is
+ analogous to a one-dimensional &brick; &engine; supporting a
+ dynamically-resizable domain. It is also usually the default
+ value for this tag. For example, <statement>DynamicArray<>
+ d0(1);</statement>, <statement>DynamicArray<double>
+ d1(1);</statement>, and <statement>DynamicArray<double,
+ Dynamic> d2(1);</statement> all declare the same
+ &dynamicarray;s explicitly storing one &double; value. A
+ &dynamicarray; automatically allocates its initial memory and
+ deallocates its final memory, just as an &array; does.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-dynamic_arrays-change_size">
+ <title>Changing a &dynamicarray;'s Domain</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>&dynamicarray; member function</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry>This table omits member functions designed for
+ distributed computation.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>void create(int num)</statement></entry>
+ <entry>extend the current domain by the requested number of
+ elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(const Dom& killList)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ given &domain; argument. <quote>Backfill</quote> moves
+ elements from the end of the domain to replace the deleted
+ elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(Iter killBegin, Iter killEnd)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ container range [begin,end) specified by the random-access
+ iterators. <quote>Backfill</quote> moves elements from the
+ end of the domain to replace the deleted elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(const Dom& killList, const
+ DeleteMethod& method)</statement></entry>
+
+ <entry>remove the elements specified by the indices in the
+ given &domain; argument. Deleted elements can be replaced by
+ <type>BackFill</type>'ing, i.e., moving data from the domain's
+ end to fill removed elements, or by <type>ShiftUp</type>'ing,
+ i.e., compacting all data but maintaining relative ordering.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(Iter killBegin, Iter killEnd,
+ const DeleteMethod& method)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ container range [begin,end) specified by the random-access
+ iterators. Deleted elements can be replaced by
+ <type>BackFill</type>'ing, i.e., moving data from the domain's
+ end to fill removed elements, or by <type>ShiftUp</type>'ing,
+ i.e., compacting all data but maintaining relative ordering.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The <methodname>create</methodname> and
+ <methodname>destroy</methodname> member functions permit changing
+ a &dynamicarray;'s domain. <xref
+ linkend="arrays-dynamic_arrays-change_size"></xref> lists these member
+ functions but omits functions exclusively used in distributed
+ computation. When making the domain larger, new indices are added
+ to the end of the one-dimensional domain and the corresponding
+ values are initialized with the default value
+ for <type>T</type>. Existing values are copied.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-dynamic_arrays-table">
+ <title>Changing a &dynamicarray;'s Domain</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>&dynamicarray; member function</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry>This table omits member functions designed for
+ distributed computation.</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry><statement>void create(int num)</statement></entry>
+ <entry>extend the current domain by the requested number of
+ elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(const Dom& killList)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ given &domain; argument. <quote>Backfill</quote> moves
+ elements from the end of the domain to replace the deleted
+ elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(Iter killBegin, Iter killEnd)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ container range [begin,end) specified by the random-access
+ iterators. <quote>Backfill</quote> moves elements from the
+ end of the domain to replace the deleted elements.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(const Dom& killList, const
+ DeleteMethod& method)</statement></entry>
+
+ <entry>remove the elements specified by the indices in the
+ given &domain; argument. Deleted elements can be replaced by
+ <type>BackFill</type>'ing, i.e., moving data from the domain's
+ end to fill removed elements, or by <type>ShiftUp</type>'ing,
+ i.e., compacting all data but maintaining relative ordering.</entry>
+ </row>
+ <row>
+ <entry><statement>void destroy(Iter killBegin, Iter killEnd,
+ const DeleteMethod& method)</statement></entry>
+ <entry>remove the elements specified by the indices in the
+ container range [begin,end) specified by the random-access
+ iterators. Deleted elements can be replaced by
+ <type>BackFill</type>'ing, i.e., moving data from the domain's
+ end to fill removed elements, or by <type>ShiftUp</type>'ing,
+ i.e., compacting all data but maintaining relative ordering.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The <methodname>destroy</methodname> deletes specified
+ indices. The indices may be specified using either a &domain;
+ object (<type>Interval<1></type>,
+ <type>Range<1></type>, or <type>IndirectionList</type>) or
+ in a container specified using random-access iterators. For
+ example, every other element from a ten-element
+ array <varname>d</varname> might be removed using
+ <statement>Range<1>(0,9,2)</statement>. Alternatively,
+ <programlisting>
+ int killList[] = {0, 2, 4, 6, 8};
+ d.destroy(killList, killList+5);
+ </programlisting> performs the same deletions. As indices are
+ removed, other indices are moved into their positions. Using the
+ <type>BackFill</type> method moves the last index and its
+ associated value into deleted index's position. Thus, the total
+ number of indices is decreased by one, but the indices can be
+ reordered. Using the <type>ShiftUp</type> method ensures the
+ indices' orders are maintained by <quote>shifting</quote> all
+ elements left (or up) so all <quote>gaps</quote> between indices
+ disappear. For example, consider removing the first index from a
+ domain.
+ <informaltable frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-dynamic_arrays-destroy_example">
+ <tgroup cols="2" align="left">
+ <tbody>
+ <row>
+ <entry>original indices:</entry>
+ <entry>0 1 2 3</entry>
+ </row>
+ <row>
+ <entry><methodname>destroy</methodname> using <type>BackFill</type></entry>
+ <entry>3 1 2</entry>
+ </row>
+ <row>
+ <entry><methodname>destroy</methodname> using <type>ShiftUp</type></entry>
+ <entry>1 2 3</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ The <type>BackFill</type> moves the rightmost index 3 into
+ the removed index 0's position. The <type>ShiftUp</type>
+ moves all the indices one position to the left. This illustrates
+ that <type>BackFill</type> moves exactly as many indices as are
+ deleted, while <type>ShiftUp</type> can shift all indices in a
+ domain. Thus, <type>BackFill</type> is the default method. When
+ multiple indices are deleted, they are deleted from the largest to
+ the smallest. When using the <type>BackFill</type> method, some
+ indices may be moved repeatedly. For example, consider removing
+ indices 0 and 2 from original indices of 0 1 2 3. Removing 2
+ yields 0 1 3. Removing 0 yields 3 1. Using an object with the
+ desired type to indicate which fill method is desired, i.e.,
+ <statement>BackFill()</statement> or
+ <statement>ShiftUp()</statement>.</para>
+
+ <example id="arrays-dynamic_arrays-example">
+ <title>Example Using &dynamicarray;s</title>
+
+ &dynamicarray-example;
+ <calloutlist>
+ <callout arearefs="arrays-dynamic_arrays-example-header">
+ <para>This header file declares &dynamicarray;s.</para>
+ </callout>
+ <callout arearefs="arrays-dynamic_arrays-example-identical_declarations">
+ <para>These three declarations yield equivalent
+ &dynamicarray;s, storing one &double; value.</para>
+ </callout>
+ <callout arearefs="arrays-dynamic_arrays-example-extension">
+ <para>This <methodname>create</methodname> member function adds
+ five indices to the end of the domain.</para>
+ </callout>
+ <callout arearefs="arrays-dynamic_arrays-example-access">
+ <para>&dynamicarray; values are accessed the same way as
+ &array; values.</para>
+ </callout>
+ <callout arearefs="arrays-dynamic_arrays-example-destroy_range">
+ <para>The ⦥ object specifies that every other index
+ should be removed. The <statement>BackFill()</statement>
+ object is unnecessary since it is the default replacement
+ method.</para>
+ </callout>
+ <callout arearefs="arrays-dynamic_arrays-example-destroy_iterators">
+ <para>This <methodname>destroy</methodname> call is equivalent
+ to the previous one but uses iterators.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>We illustrate &dynamicarray; resizing in <xref
+ linkend="arrays-dynamic_arrays-example"></xref>. &dynamicarray;s
+ are declared in <filename
+ class="headerfile">Pooma/DynamicArrays.h</filename>, not <filename
+ class="headerfile">Pooma/Arrays.h</filename>. Their declarations
+ require two, not three, template arguments because the array must
+ be one-dimensional. The three arrays, each having one &double;
+ value, are equivalent. (The &poomatoolkit; can be configured to
+ support different default values.) Invoking
+ <varname>d0</varname>'s <methodname>create</methodname> with an
+ argument of five increases its domain size from one to six. The
+ additional indices are added to the end of the domain so the value
+ at index 0 is not changed. To illustrate which indices are
+ removed and which indices are reordered, the program first sets
+ all values equal to their indices. This illustrates that
+ &dynamicarray; values are accessed the same way as &array; values.
+ For example, <statement>d0(i)</statement> accesses the
+ <varname>i</varname>th value. The
+ <methodname>destroy</methodname> removes every other index from
+ the array. The one-dimensional ⦥ specifies these indices by
+ specifying the domain's entire interval and a stride of 2.
+ The <statement>BackFill</statement> function call creates a
+ <type>BackFill</type> object indicating the <type>BackFill</type>
+ method should be used. We illustrate the steps of this method:
+ <informaltable frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="arrays-dynamic_arrays-program_example">
+ <tgroup cols="2" align="left">
+ <tbody>
+ <row>
+ <entry>original indices:</entry>
+ <entry>0 1 2 3 4 5</entry>
+ </row>
+ <row>
+ <entry>delete index 4</entry>
+ <entry>0 1 2 3 5</entry>
+ </row>
+ <row>
+ <entry>delete index 2</entry>
+ <entry>0 1 5 3</entry>
+ </row>
+ <row>
+ <entry>delete index 0</entry>
+ <entry>3 1 5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Since multiple indices are specified, the rightmost one is removed
+ first, i.e., index 4. The rightmost index 5 is moved
+ into 4's position. When removing index 2, the index
+ originally at 5 is moved again into 2's position. Finally,
+ index 0 is replaced by index 3. The rest of the program
+ repeats the computation, using the random-access iterator version
+ of <methodname>destroy</methodname>. Since this &dynamicarray;'s
+ indices are specified using ∫s, the
+ <varname>killList</varname> explicitly lists the indices to
+ remove. The <methodname>destroy</methodname> call uses pointers
+ to the beginning and end of the <varname>killList</varname> array
+ to specify which of its indices to use. Since no replacement
+ method is specified, the default <type>BackFill</type> method is
+ used. All the &dynamicarray;s' unallocated memory is
+ deallocated.</para>
</section>
Index: concepts.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/concepts.xml,v
retrieving revision 1.6
diff -c -p -r1.6 concepts.xml
*** concepts.xml 2002/01/16 00:50:27 1.6
--- concepts.xml 2002/01/22 15:37:14
***************
*** 147,158 ****
<row>
<entry><glossterm linkend="glossary-field">&field;</glossterm></entry>
<entry>container mapping <glossterm linkend="glossary-index">indices</glossterm> to one or more values and
! residing in multi-dimensional space</entry>
</row>
<row>
<entry><glossterm
linkend="glossary-tensor">&tensor;</glossterm></entry>
! <entry>multi-dimensional mathematical tensor</entry>
</row>
<row>
<entry><glossterm
--- 147,158 ----
<row>
<entry><glossterm linkend="glossary-field">&field;</glossterm></entry>
<entry>container mapping <glossterm linkend="glossary-index">indices</glossterm> to one or more values and
! residing in multidimensional space</entry>
</row>
<row>
<entry><glossterm
linkend="glossary-tensor">&tensor;</glossterm></entry>
! <entry>multidimensional mathematical tensor</entry>
</row>
<row>
<entry><glossterm
***************
*** 162,168 ****
<row>
<entry><glossterm
linkend="glossary-vector">&vector;</glossterm></entry>
! <entry>multi-dimensional mathematical vector</entry>
</row>
</tbody>
</tgroup>
--- 162,168 ----
<row>
<entry><glossterm
linkend="glossary-vector">&vector;</glossterm></entry>
! <entry>multidimensional mathematical vector</entry>
</row>
</tbody>
</tgroup>
***************
*** 210,216 ****
<!-- FIXME: Want firstterm around tensor. -->
<para>A <glossterm linkend="glossary-tensor">&tensor;</glossterm>
! implements a multi-dimensional mathematical tensor. Since it is a
first-class type, it can be used in expressions such as
adding two &tensor;s.</para>
--- 210,216 ----
<!-- FIXME: Want firstterm around tensor. -->
<para>A <glossterm linkend="glossary-tensor">&tensor;</glossterm>
! implements a multidimensional mathematical tensor. Since it is a
first-class type, it can be used in expressions such as
adding two &tensor;s.</para>
***************
*** 224,230 ****
<!-- FIXME: Want firstterm around vector. -->
<para>A <glossterm linkend="glossary-vector">&vector;</glossterm>
! implements a multi-dimensional mathematical vector, which is an
ordered tuple of components. Since it is a first-class type, it
can be used in expressions such as adding two &vector;s and
multiplying a &matrix; and a &vector;.</para>
--- 224,230 ----
<!-- FIXME: Want firstterm around vector. -->
<para>A <glossterm linkend="glossary-vector">&vector;</glossterm>
! implements a multidimensional mathematical vector, which is an
ordered tuple of components. Since it is a first-class type, it
can be used in expressions such as adding two &vector;s and
multiplying a &matrix; and a &vector;.</para>
***************
*** 263,269 ****
<entry>use a &vector;, &matrix;, or &tensor;.</entry>
</row>
<row>
! <entry>If indices and values reside in multi-dimensional space
&space;,</entry>
<entry>use a &field;.</entry>
</row>
--- 263,269 ----
<entry>use a &vector;, &matrix;, or &tensor;.</entry>
</row>
<row>
! <entry>If indices and values reside in multidimensional space
&space;,</entry>
<entry>use a &field;.</entry>
</row>
Index: glossary.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/glossary.xml,v
retrieving revision 1.6
diff -c -p -r1.6 glossary.xml
*** glossary.xml 2002/01/14 17:33:34 1.6
--- glossary.xml 2002/01/22 15:37:16
***************
*** 369,374 ****
--- 369,384 ----
</glossdef>
</glossentry>
+ <glossentry id="glossary-function_object">
+ <glossterm>function object</glossterm>
+ <glossdef>
+ <para>object that can behave as a function. The object can store
+ values that the function uses. If its function is called
+ <methodname>operator()</methodname>, the object can be invoked as
+ a function.</para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-function_template">
<glossterm>function template</glossterm>
<glossdef>
***************
*** 547,553 ****
<glossentry id="glossary-point">
<glossterm>point</glossterm>
<glossdef>
! <para>a location in multi-dimensional space &space;.
In contrast, indices specify positions in container domains.</para>
<glossseealso otherterm="glossary-field">&field;</glossseealso>
<glossseealso otherterm="glossary-mesh">mesh</glossseealso>
--- 557,563 ----
<glossentry id="glossary-point">
<glossterm>point</glossterm>
<glossdef>
! <para>a location in multidimensional space &space;.
In contrast, indices specify positions in container domains.</para>
<glossseealso otherterm="glossary-field">&field;</glossseealso>
<glossseealso otherterm="glossary-mesh">mesh</glossseealso>
***************
*** 694,700 ****
<glossentry id="glossary-tensor">
<glossterm>&tensor;</glossterm>
<glossdef>
! <para>a &pooma; container implementing multi-dimensional
mathematical tensors as first-class objects.</para>
<glossseealso otherterm="glossary-matrix">&matrix;</glossseealso>
<glossseealso otherterm="glossary-vector">&vector;</glossseealso>
--- 704,710 ----
<glossentry id="glossary-tensor">
<glossterm>&tensor;</glossterm>
<glossdef>
! <para>a &pooma; container implementing multidimensional
mathematical tensors as first-class objects.</para>
<glossseealso otherterm="glossary-matrix">&matrix;</glossseealso>
<glossseealso otherterm="glossary-vector">&vector;</glossseealso>
***************
*** 750,756 ****
<glossentry id="glossary-vector">
<glossterm>&vector;</glossterm>
<glossdef>
! <para>a &pooma; container implementing multi-dimensional
mathematical vectors, i.e., an ordered tuple of components, as
first-class objects.</para>
<glossseealso otherterm="glossary-tensor">&tensor;</glossseealso>
--- 760,766 ----
<glossentry id="glossary-vector">
<glossterm>&vector;</glossterm>
<glossdef>
! <para>a &pooma; container implementing multidimensional
mathematical vectors, i.e., an ordered tuple of components, as
first-class objects.</para>
<glossseealso otherterm="glossary-tensor">&tensor;</glossseealso>
Index: manual.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/manual.xml,v
retrieving revision 1.7
diff -c -p -r1.7 manual.xml
*** manual.xml 2002/01/16 00:50:27 1.7
--- manual.xml 2002/01/22 15:37:19
***************
*** 95,100 ****
--- 95,102 ----
<!-- A domain template parameter. -->
<!ENTITY double "<type>double</type>">
<!-- The C "double" type. -->
+ <!ENTITY dynamic "<type>Dynamic</type>">
+ <!-- The "Dynamic" Engine type. -->
<!ENTITY dynamicarray "<type>DynamicArray</type>">
<!-- The "DynamicArray" type. -->
<!ENTITY engine "<type>Engine</type>">
***************
*** 156,167 ****
<!ENTITY container "C">
<!-- an abbreviation for a canonical container -->
- <!ENTITY dim "D">
- <!-- the number of dimensions of an array, domain, etc. -->
<!ENTITY n "n">
<!-- the size of one dimension of an array -->
<!ENTITY space "ℜ<superscript>d</superscript>">
! <!-- a notation for multi-dimensional space -->
<!-- System and Operating System Entity Declarations -->
<!ENTITY gcc "<application>g++</application>">
--- 158,167 ----
<!ENTITY container "C">
<!-- an abbreviation for a canonical container -->
<!ENTITY n "n">
<!-- the size of one dimension of an array -->
<!ENTITY space "ℜ<superscript>d</superscript>">
! <!-- a notation for multidimensional space -->
<!-- System and Operating System Entity Declarations -->
<!ENTITY gcc "<application>g++</application>">
***************
*** 234,245 ****
<!-- Field data-parallel distributed Doof2d implementation -->
<!-- Sequential Programs -->
- <!ENTITY initialize-finalize SYSTEM "./programs/examples/Sequential/initialize-finalize-annotated.cpp">
- <!-- Illustrate initialize() and finalize(). -->
<!ENTITY array-copy SYSTEM "./programs/examples/Sequential/array-copy-annotated.cpp">
<!-- Illustrate Array reference semantics. -->
<!ENTITY array-size SYSTEM "./programs/examples/Sequential/array-size-annotated.cpp">
<!-- Illustrate Array member functions. -->
<!-- Template Programs -->
<!ENTITY pairs-untemplated SYSTEM "./programs/examples/Templates/pairs-untemplated-annotated.cpp">
--- 234,247 ----
<!-- Field data-parallel distributed Doof2d implementation -->
<!-- Sequential Programs -->
<!ENTITY array-copy SYSTEM "./programs/examples/Sequential/array-copy-annotated.cpp">
<!-- Illustrate Array reference semantics. -->
<!ENTITY array-size SYSTEM "./programs/examples/Sequential/array-size-annotated.cpp">
<!-- Illustrate Array member functions. -->
+ <!ENTITY dynamicarray-example SYSTEM "./programs/examples/Sequential/dynamicarray-annotated.cpp">
+ <!-- Illustrate using DynamicArray class. -->
+ <!ENTITY initialize-finalize SYSTEM "./programs/examples/Sequential/initialize-finalize-annotated.cpp">
+ <!-- Illustrate initialize() and finalize(). -->
<!-- Template Programs -->
<!ENTITY pairs-untemplated SYSTEM "./programs/examples/Templates/pairs-untemplated-annotated.cpp">
***************
*** 353,362 ****
&arrays-chapter;
<chapter id="engines">
<title>Engines</title>
! <para>UNFINISHED</para>
</chapter>
--- 355,692 ----
&arrays-chapter;
+
<chapter id="engines">
<title>Engines</title>
! <para>Each container has one or more &engine;s to store or compute
! its values. As we mentioned in <xref
! linkend="arrays-arrays_declarations"></xref>, a container's role is
! high-level, supporting access to groups of values, and an engine's
! role is low-level, storing or computing values and supporting
! access to individual values. This separation permits optimizing
! space and computation requirements.</para>
!
! <para>We begin this chapter by introducing the concept of an engine
! and how it is used. Then, we describe the various &engine;s that
! &pooma; provides, separating them into engines that store values
! and engines that compute values. Finally, we describe how the
! &engine;s are implemented, using tags to differentiate engines and
! reference-counted pointers to their underlying data.</para>
!
!
! <section id="engines-concept">
! <title>The Concept</title>
!
! <para>An engine performs the low-level value storage, computation,
! and element-wise access for a container. The &pooma; &engine;
! class and its specializations implement the concept. An engine
! has a domain and accessor functions returning individual elements.
! Given an index within the domain, an engine's
! <methodname>operator()</methodname> function returns the
! associated value, which can be used or changed. Its
! <methodname>read</methodname> returns the same value for only use,
! not modification. The acceptable indices are determined by each
! &engine;. Most accept indices specified using ∫ and
! <type>Loc<&dim;></type> parameters, but an &engine; might
! accept string or floating-point parameters. An &engine;'s layout
! specifies maps its domain indices to the processors and memory
! used to store and compute the associated values.</para>
!
! <para>Since an engine's main role is to return the individual
! values associated with specific domain indices, any implementation
! performing this task is an engine. &pooma; &engine;s fall into
! three categories:
! <itemizedlist>
! <listitem>
! <para>&engine;s that store values.</para>
! </listitem>
! <listitem>
! <para>&engine;s that compute their values using other &engine;s'
! values.</para>
! </listitem>
! <listitem>
! <para>&engine;s that support distributed computation.</para>
! </listitem>
! </itemizedlist>
! For example, the &brick; &engine; explicitly stores all its
! values, while the &compressiblebrick; engine adds the feature of
! reducing its storage requirements if all these values are
! identical. A <type>UserFunction</type> &engine; yields values by
! applying a <glossterm linkend="glossary-function_object">function
! object</glossterm> to each value returned by another &engine;. A
! <type>CompFwd</type> &engine; projects components from another
! &engine;. For example, <type>CompFwd</type> will use the second
! components of each vector in an &array; to form its own &array;.
! Since each container has one or more &engine;s, we can also
! describe the latter category as containers that compute their
! values using other containers' values. A <type>MultiPatch</type>
! &engine; distributes its domain among various processors and
! memory spaces, each responsible for computing values associated
! with a portion, or patch, of the domain.</para>
!
! <para>Just as multiple containers can use the same engine,
! multiple &engine;s can use the same underlying data. As we
! mentioned in <xref linkend="arrays-arrays_use"></xref>, &engine;s
! have reference semantics. So a copy of an &engine; has a
! reference-counted pointer to an &engine;'s data (if any exists).
! Thus, copying an &engine; or a container requires little execution
! time. If an &engine; has the same data as another &engine; but it
! needs its own data to modify, the
! <methodname>makeOwnCopy</methodname> creates such a copy.</para>
!
! <para>&engine;s are rarely explicitly declared. Instead a
! container is declared using an &engine; tag, and the container,
! creates the specified &engine; to deal with its values. For
! example, a &brick; &engine; is explicitly declared as
! <type>Engine<&dim;,T,Brick></type>, but they are more
! frequently created by containers, e.g.,
! <type>Array<&dim;,T,Brick></type>. The first two template
! parameters specify the domain's dimensionality and the value type,
! as described in <xref
! linkend="arrays-arrays_declarations"></xref>. Unlike container
! declarations, the third template parameter, the &engine; tag,
! specifies which &engine; specialization to use. For example, the
! &brick; engine tag indicates a brick &engine; should be used.
! Some &engine;s, such as <type>CompFwd</type>, are rarely declared
! even using &engine; tags. Instead the &array;'s
! <methodname>comp</methodname> and
! <methodname>readComp</methodname> methods return views of
! containers using <type>CompFwd</type> &engine;s.</para>
! </section>
!
!
! <section id="engines-types">
! <title>Types of &engine;s</title>
!
! <para>In this section, we describe the different types of
! &engine;s and illustrate their creation, when appropriate. First,
! we describe &engine;s that explicitly store values and then
! &engine;s that compute values.</para>
!
! <table frame="none" colsep="0" rowsep="0" tocentry="1"
! orient="port" pgwide="0" id="engines-types-table">
! <title>Types of &engine;s</title>
!
! <tgroup cols="2" align="left">
! <thead>
! <row>
! <entry>&engine; tag</entry>
! <entry>description</entry>
! </row>
! </thead>
! <tbody>
! <row rowsep="1">
! <entry>&engine;s That Store</entry>
! </row>
! <row>
! <entry>&brick;</entry>
! <entry>explicitly stores all values; similar to &c; arrays.</entry>
! </row>
! <row>
! <entry>&compressiblebrick;</entry>
! <entry>stores all values, reducing storage requirements when
! all values are the same.</entry>
! </row>
! <row>
! <entry>&dynamic;</entry>
! <entry>is a one-dimensional &brick; with dynamically
! resizable domain. HERE ever explicitly declare these?</entry>
! </row>
! <row rowsep="1">
! <entry>&engine;s That Compute</entry>
! </row>
! <row>
! <entry><type>CompFwd</type></entry>
! <entry>extracts specified components of an engine's vectors,
! tensors, arrays, etc.; usually created using
! <methodname>comp</methodname> container function.</entry>
! </row>
! <row>
! <entry><type>ConstantFunction</type></entry>
! <entry>makes a scalar value behave like a container.</entry>
! </row>
! <row>
! <entry><type>IndexFunction<FunctionObject></type></entry>
! <entry>makes the <type>FunctionObject</type> function of
! indices behave like a container.</entry>
! </row>
! <row>
! <entry><type>ExpressionTag<Expr></type></entry>
! <entry>evaluates an expression tree; usually created by
! data-parallel expressions.</entry>
! </row>
! <row>
! <entry><type>Stencil<Function,
! Expression></type></entry>
! <entry>applies a stencil computation (<type>Function</type>)
! to its input (<type>Expression</type>), usually a container;
! usually created by applying a <type>Stencil</type> object to
! a container. A stencil computation can use multiple
! neighboring input values.</entry>
! </row>
! <row>
! <entry><type>UserFunctionEngine<Function,
! Expression></type></entry>
! <entry>applies the given function (or <glossterm
! linkend="glossary-function_object">function
! object</glossterm>) to its input (<type>Expression</type>),
! usually a container; usually created by applying a
! <type>UserFunction</type> object to a container. The
! function implements a one-to-one mapping from its input to
! values.</entry>
! </row>
! <row rowsep="1">
! <entry>&engine;s for Distributed Computation</entry>
! </row>
! <row>
! <entry><type>MultiPatch<LayoutTag,EngineTag></type></entry>
! <entry>runs a separate <type>EngineTag</type> &engine; on
! each context (patch) specified by the given layout. This is
! the usual &engine; for distributed computation.</entry>
! </row>
! <row>
! <entry><type>Remote<EngineTag></type></entry>
! <entry>runs the &engine; specified by <type>EngineTag</type>
! on a specified context.</entry>
! </row>
! <row>
! <entry><type>Remote<Dynamic></type></entry>
! <entry>runs a <type>Dynamic</type> one-dimensional, resizable
! &engine; on a specified context. This is a specialization of
! <type>Remote</type>.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>&brick; &engine;s explicitly store values just like &c;
! arrays. &compressiblebrick; &engine;s optimize their storage
! requirements when all values are the same. Most &array;s use one
! of these two &engine;s. &brick;s are the default &engine;s for
! &array; and &field; containers because each of their values are
! explicitly stored. Explicitly storing all an engine's value can
! require a large amount of space, particularly if all these values
! are the same. If all a compressible brick &engine;'s values are
! the same, the engine stores that one value rather than many, many
! copies of the same value. These engines can both save time as
! well as space. Initializing a compressible engine requires
! setting only one value, not every value. Using less storage space
! may permit more useful values to be stored in cache, improving
! cache performance. Reading a value in a compressed &engine; using
! <methodname>read</methodname> is as fast as reading a value in a
! &brick; &engine;, but writing a value always requires an
! additional <keywordname>if</keywordname> conditional. Thus, if an
! &engine; occasionally has multiple different values during its
! life time, a &compressiblebrick; &engine; may be faster than a
! &brick; &engine;. If an &engine; is created and its values are
! mostly read, not written, a &compressiblebrick; &engine; may also
! be faster. Otherwise, a &brick; &engine; may be preferable.
! Timing the same program using the two different &engine; types
! will reveal which is faster for a particular situation.</para>
!
! <para>In distributed computing, many &engine;s may have few
! nonzero values so &compressiblebrick; &engine;s may be preferable.
! For distributed computing, a container's domain is partitioned
! into regions each computed by a separate processor and &engine;.
! If the computation is concentrated in sections of the domain, many
! &engine;s may have few, if any, nonzero values. Thus,
! &compressiblebrick; &engine;s may be preferable for distributed
! computing.</para>
!
! <para>Both &brick; and &compressiblebrick; &engine;s have
! <methodname>read</methodname> and
! <methodname>operator()</methodname> members with ∫ and &loc;
! parameters. The parameters should match the &array;'s
! dimensionality. For example, if &array; <varname>a</varname> has
! dimensionality 3, <function>a.read(int, int, int)</function>
! and <function>a(int, int, int)</function> should be used. The
! former returns a value that cannot be modified, while the latter
! can be changed. Using the <methodname>read</methodname> can lead
! to faster code. Alternatively, an index can be specified using a
! &loc;. For example,
! <statement>a.read(Loc<3>(1,-2,5))</statement> and
! <statement>a(Loc<3>(1,-2,5))</statement> are equivalent to
! <statement>a.read(1,-2,5))</statement> and
! <statement>a(1,-2,5)</statement>.</para>
!
! <para>The &dynamic; &engine; supports changing domain sizes while
! a program is executing. It is basically a one-dimensional
! &brick;, explicitly storing values, but permitting the number and
! order of stored values to change. Thus, it supports the same
! interface as &brick; except that all member functions are
! restricted to their one-dimensional versions. For example,
! <methodname>read</methodname> and
! <methodname>operator()</methodname> take <type>Loc<1></type>
! or one ∫ parameter. In addition, the one-dimensional domain
! can be dynamically resized using <methodname>create</methodname>
! and <methodname>destroy</methodname>; see .
!
! HERE Dynamic. How does one change the domain size? What is the model?</para>
!
! <!-- HERE: Array cannot forward domain size changes to underlying Dynamic Engine. -->
!
! <para>Types of &engine;s:
! Brick - explicitly store values
! CompressibleBrick - explicitly store values but store only one if all the same
! ConstantFunction - convert scalar into an array
! DynamicEngine - contiguous, local, resizable, 1D block
! ExpressionEngine - evaluate PETE expression
! CompFwd - array formed by extracted components from array
! ForwardEngine
! tut-02.html: use .comp() or .readComp()
! IndexFunctionEngine - convert function of indices into an array
! IndirectionEngine - incomplete
! MultiPatch - ?How do I describe this?
! RemoteDynamic - run a Dynamic engine on a specified context
! Remote - permit computations on specified context
! should discuss with MultiPatch
! Stencil - apply a stencil to an array, returning a new Array with the results
! UserFunction - Array = apply function to an Array
! </para>
!
! <para>How do I organize these engines into understandable
! categories?
!
! storage
! Brick
! CompressibleBrick
! Dynamic - resizable 1D block
! RemoteDynamic
! MultiPatch - ?WHAT?
! Remote
!
! computation
! CompFwd: project(array)->array
! .comp() and .readComp()
! view, not a copy
! ConstantFunction: scalar(array)->array
! explicitly use
! IndexFunctionEngine: function(indices)->array
! explicitly use
! ExpressionEngine: expression(array)->array
! created by data-parallel expression
! Stencil: stencil(array)->array
! implicitly used
! explicitly use Stencil<...> type
! UserFunction: function(array)->array
! explicitly use
! </para>
!
! <para>
! Element_t read(Loc<&dim;>)
! ElementRef_t operator()(Loc<&dim;>)
! Element_t read(int+)
! ElementRef_t operator()(int+)
! </para>
!
! <para>Explain the concept of an engine. How does an engine
! interact with a container or an &array;? Explain the different
! types of engines likely to be used by &pooma; programmers and how
! to declare containers using them. Should I list the other engines
! that are automatically created?</para>
!
! </section>
</chapter>
***************
*** 553,559 ****
<title>Beginning and Ending &pooma; Programs</title>
<para>Every &pooma; program must begin with a call to
! <methodname>initialize</methodname> and end with a call to
<function>finalize</function>. These functions respectively
prepare and shut down &pooma;'s run-time structures.</para>
--- 883,889 ----
<title>Beginning and Ending &pooma; Programs</title>
<para>Every &pooma; program must begin with a call to
! <function>initialize</function> and end with a call to
<function>finalize</function>. These functions respectively
prepare and shut down &pooma;'s run-time structures.</para>
***************
*** 603,609 ****
<bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
<para>Before its use, the &poomatoolkit; must be initialized by a
! call to <methodname>initialize</methodname>. This usually occurs in
the <function>main</function> function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments <varname>argv</varname> and
--- 933,939 ----
<bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
<para>Before its use, the &poomatoolkit; must be initialized by a
! call to <function>initialize</function>. This usually occurs in
the <function>main</function> function. The first form removes
and processes any &pooma;-specific arguments from the
command-line arguments <varname>argv</varname> and
***************
*** 625,631 ****
architecture-specific initialization. The function always
returns &true;.</para>
! <para><methodname>initialize</methodname>'s alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
<varname>argv</varname> and <varname>argc</varname> and stored in
--- 955,961 ----
architecture-specific initialization. The function always
returns &true;.</para>
! <para><function>initialize</function>'s alternative form
assumes the &pooma;-specific and architecture-specific
command-line arguments have already been removed from
<varname>argv</varname> and <varname>argc</varname> and stored in
***************
*** 653,659 ****
<bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
<para>Since every &pooma; program must call
! <methodname>initialize</methodname> and
<function>finalize</function>, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.</para>
--- 983,989 ----
<bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
<para>Since every &pooma; program must call
! <function>initialize</function> and
<function>finalize</function>, the simplest &pooma; program also
must call them. This program also illustrates their usual
use.</para>
*************** UNFINISHED</para>
*** 862,868 ****
specifying N indices, which collectively specify a single point
in the input domain: A(i1, i2, ..., iN).</para>
! <para>The &pooma; multi-dimensional Array concept is similar to
the &fortran; 90 array facility, but extends it in several
ways. Both &pooma; and &fortran; arrays can have up to seven
dimensions, and can serve as containers for arbitrary
--- 1192,1198 ----
specifying N indices, which collectively specify a single point
in the input domain: A(i1, i2, ..., iN).</para>
! <para>The &pooma; multidimensional Array concept is similar to
the &fortran; 90 array facility, but extends it in several
ways. Both &pooma; and &fortran; arrays can have up to seven
dimensions, and can serve as containers for arbitrary
Index: tutorial.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/tutorial.xml,v
retrieving revision 1.5
diff -c -p -r1.5 tutorial.xml
*** tutorial.xml 2002/01/14 17:33:34 1.5
--- tutorial.xml 2002/01/22 15:37:20
***************
*** 856,862 ****
multiple values. Like &array;s, &field;s can be accessed via
data-parallel expressions and stencils and may be distributed
across processors. Unlike &array; cells, &field; cells exist in a
! multi-dimensional volume so, e.g., distances between cells and
normals to cells can be computed.</para>
<para>In this section, we implement the &doof2d; two-dimensional
--- 856,862 ----
multiple values. Like &array;s, &field;s can be accessed via
data-parallel expressions and stencils and may be distributed
across processors. Unlike &array; cells, &field; cells exist in a
! multidimensional volume so, e.g., distances between cells and
normals to cells can be computed.</para>
<para>In this section, we implement the &doof2d; two-dimensional
More information about the pooma-dev
mailing list