Manual Patch: Some Concepts Changes
Jeffrey Oldham
oldham at codesourcery.com
Fri Dec 14 05:19:26 UTC 2001
2001-Dec-13 Jeffrey D. Oldham <oldham at codesourcery.com>
These changes mainly represent wordsmithing of the concepts
chapter and some preliminary work on the "Writing Sequential
Programs" chapter.
* concepts.xml: Wordsmithing and a little rearrangement.
* glossary.xml (interval): Improve wording.
* makefile (manual.dvi): Improve dependence information.
* manual.xml: Add planning material for the "Writing Sequential
Programs" chapter.
* tutorial.xml: Fix an article.
* figures/concepts.mp: Shrink the figure's horizontal extent.
Applied to mainline
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: concepts.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/concepts.xml,v
retrieving revision 1.1
diff -c -p -r1.1 concepts.xml
*** concepts.xml 2001/12/13 04:04:05 1.1
--- concepts.xml 2001/12/14 04:12:54
***************
*** 6,20 ****
<para>In the previous chapter, we presented several different
implementations of the &doof2d; simulation program. The
! implementations illustrate the various containers, computation
! modes, and computation environments that &pooma; supports. In this
! chapter, we describe the concepts associated with each of these
! three categories. Specific details needed by programmers are
! deferred to later chapters.</para>
<table frame="none" colsep="0" rowsep="0" tocentry="1"
orient="port" pgwide="0" id="concepts-table">
! <title>&pooma; Implementation Concepts</title>
<tgroup cols="3" align="center">
<thead>
<row>
--- 6,55 ----
<para>In the previous chapter, we presented several different
implementations of the &doof2d; simulation program. The
! implementations illustrate the various containers, computation modes,
! and computation environments that &pooma; supports. In this chapter,
! we describe the concepts associated with each of these three
! categories. Specific details needed for their use are deferred to
! later chapters.</para>
+ <para>The most important &pooma; concepts can be grouped into three
+ separate categories:
+ <variablelist>
+ <varlistentry>
+ <term>container</term>
+ <listitem>
+ <para>data structure holding one or more values and addressed
+ by indices</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>computation modes</term>
+ <listitem>
+ <para>styles of expressing computations and accesses to container
+ values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>computation environment</term>
+ <listitem>
+ <para>description of resources for computing, e.g., single
+ processor or multi-processor.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ See <xref linkend="concepts-table"></xref>. Many &pooma; programs
+ select one possibility from each column. For example, <xref
+ linkend="tutorial-array_stencil-doof2d"></xref> used &array;
+ containers and stencils for sequential computation, while <xref
+ linkend="tutorial-field_distributed-doof2d"></xref> used &field;
+ containers and data-parallel statements with distributed
+ computation. A program may use multiple containers and various
+ computation modes, but the computation environment is either
+ distributed or not.</para>
+
<table frame="none" colsep="0" rowsep="0" tocentry="1"
orient="port" pgwide="0" id="concepts-table">
! <title>&pooma; Concepts</title>
<tgroup cols="3" align="center">
<thead>
<row>
***************
*** 57,134 ****
</tbody>
</tgroup>
</table>
-
- <para>The most important &pooma; concepts can be grouped into three
- separate categories:
- <variablelist>
- <varlistentry>
- <term>container</term>
- <listitem>
- <para>data structure holding one or more values and addressed
- by indices</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>computation modes</term>
- <listitem>
- <para>styles of expressing computations</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>computation environment</term>
- <listitem>
- <para>description of resources for computing, e.g., single
- processor or multi-processor</para>
- </listitem>
- </varlistentry>
- </variablelist>
- See <xref linkend="concepts-table"></xref>. Many &pooma; programs
- select one possibility from each column. For example, <xref
- linkend="tutorial-array_stencil-doof2d"></xref> used a &array;
- container and stencils for sequential computation, while <xref
- linkend="tutorial-field_distributed-doof2d"></xref> used a &field;
- container and data-parallel statements with distributed
- computation. A program may use multiple containers and various
- computation modes, but the computation environment either has
- distributed processors or not.</para>
! <para>In the rest of this chapter, we explore these three
! categories. First, we describe &pooma; containers, illustrating
! the purposes of each, and explaining the concepts needed to declare
! them. Then, we describe the different computation modes and
! finally distributed computation concepts.</para>
<section id="concepts-containers">
<title>&pooma; Containers</title>
! <para>Most &pooma; programs use <firstterm>containers</firstterm>
! to store groups of values. &pooma; containers are objects that
! store other objects. They control allocation and deallocation of
! and access to these objects. They are a generalization of &c;
! arrays, but &pooma; containers are first-class objects so they can
! be used directly in expressions. They are similar to &cc;
! containers such as <type>vector</type>, <type>list</type>, and
! <type>stack</type>. See <xref
linkend="concepts-containers-table"></xref> for a summary of the
containers.</para>
! <para>This chapter describes many concepts, not all of which are
! needed to begin programming with the &pooma; Toolkit. Below we
! introduce the different categories of concepts. After that, we
! introduce the different &pooma;'s containers and describe how to
! choose the appropriate one for a particular task. <xref
linkend="concepts-sequential_containers-declarations-dependences"></xref>
indicates which concepts must be understood when declaring a
! particular container. All of these concepts are described in
! <xref
linkend="concepts-containers-sequential_declarations"></xref> and
<xref
! linkend="concepts-containers-distributed_declarations"></xref>.
! Use this figure to decide which concepts in the former are
! relevant. Reading the latter section is necessary only if
! computing using multiple processors. The programs in the previous
! chapter illustrate many of these concepts.</para>
<table frame="none" colsep="0" rowsep="0" tocentry="1"
orient="port" pgwide="0" id="concepts-containers-table">
--- 92,133 ----
</tbody>
</tgroup>
</table>
! <para>In the rest of this chapter, we explore these three categories.
! First, we describe &pooma; containers, illustrating the purposes of
! each, and explaining the concepts needed to declare them. Then, we
! describe the different computation modes and distributed computation
! concepts.</para>
<section id="concepts-containers">
<title>&pooma; Containers</title>
! <para>Most &pooma; programs use <firstterm>containers</firstterm> to
! store groups of values. &pooma; containers are objects that store
! other objects such as numbers or vectors. They control allocation
! and deallocation of and access to these stored objects. They are a
! generalization of &c; arrays, but &pooma; containers are first-class
! objects so they can be used directly in expressions. They are
! similar to &cc; containers such as <type>vector</type>,
! <type>list</type>, and <type>stack</type>. See <xref
linkend="concepts-containers-table"></xref> for a summary of the
containers.</para>
! <para>This section describes many concepts, but one need not
! understand them all to begin programming with the &pooma; Toolkit.
! First, we introduce the different &pooma;'s containers and describe
! how to choose an appropriate one for a particular task. <xref
linkend="concepts-sequential_containers-declarations-dependences"></xref>
indicates which concepts must be understood when declaring a
! particular container. All of these concepts are described in <xref
linkend="concepts-containers-sequential_declarations"></xref> and
<xref
! linkend="concepts-containers-distributed_declarations"></xref>. Use
! this figure to decide which concepts in the former are relevant.
! Reading the latter section is necessary only if computing using
! multiple processors. The programs in the previous chapter
! illustrate many of these concepts.</para>
<table frame="none" colsep="0" rowsep="0" tocentry="1"
orient="port" pgwide="0" id="concepts-containers-table">
***************
*** 175,191 ****
<!-- FIXME: Want firstterm around array. -->
<para>A &pooma; <glossterm
! linkend="glossary-array">array;</glossterm>, generalizing a &c;
! array, maps indices to values. Given a index or position in an
&array;'s domain, it returns the associated value, either by
returning a stored value or by computing it. The use of indices,
which are usually ordered tuples, permits constant-time access
! although computing a particular value may require significant
! time. In addition to the functionality provided by &c; arrays,
! the &array; class automatically handles memory allocation and
! deallocation, supports a wider variety of assignments, and can be
! used in expressions. For example, the addition of two arrays can
! be assigned to an array and the product of a scalar element and an
array is permissible.</para>
<!-- FIXME: Want firstterm around dynamicarray. -->
--- 174,190 ----
<!-- FIXME: Want firstterm around array. -->
<para>A &pooma; <glossterm
! linkend="glossary-array">&array;</glossterm> generalizes a &c; array
! and maps indices to values. Given an index or position in an
&array;'s domain, it returns the associated value, either by
returning a stored value or by computing it. The use of indices,
which are usually ordered tuples, permits constant-time access
! although computing a particular value may require significant time.
! In addition to the functionality provided by &c; arrays, the &array;
! class automatically handles memory allocation and deallocation,
! supports a wider variety of assignments, and can be used in
! expressions. For example, the addition of two arrays can be
! assigned to an array and the product of a scalar element and an
array is permissible.</para>
<!-- FIXME: Want firstterm around dynamicarray. -->
***************
*** 200,215 ****
<para>A &pooma; <glossterm>&field;</glossterm> is an &array; with
spatial extent. Each domain consists of <glossterm
! linkend="glossary-cell"><firstterm>cell</firstterm></glossterm>s
! in one-, two-, or three-dimensional space. Although indexed
! similarly to &array;s, each cell may contain multiple values and
! multiple materials. A &field;'s <glossterm
linkend="glossary-mesh">mesh</glossterm> stores its spatial
! characteristics and can map yield, e.g., a point contained in a
! cell, the distance between two cells, and a cell's normals. A
&field; should be used whenever geometric or spatial computations
! are needed, multiple values per index are desired, or a
! computation involves more than one material.</para>
<!-- FIXME: Want firstterm around tensor. -->
--- 199,214 ----
<para>A &pooma; <glossterm>&field;</glossterm> is an &array; with
spatial extent. Each domain consists of <glossterm
! linkend="glossary-cell"><firstterm>cell</firstterm></glossterm>s in
! one-, two-, or three-dimensional space. Although indexed similarly
! to &array;s, each cell may contain multiple values and multiple
! materials. A &field;'s <glossterm
linkend="glossary-mesh">mesh</glossterm> stores its spatial
! characteristics and can map yield, e.g., the cell at a particular
! point, the distance between two cells, or a cell's normals. A
&field; should be used whenever geometric or spatial computations
! are needed, multiple values per index are desired, or a computation
! involves more than one material.</para>
<!-- FIXME: Want firstterm around tensor. -->
***************
*** 222,229 ****
<para>A <glossterm linkend="glossary-matrix">&matrix;</glossterm>
implements a two-dimensional mathematical matrix. Since it is a
! first-class type, it can be used in expressions such as
! multiplying matrices and assignments to matrices.</para>
<!-- FIXME: Want firstterm around vector. -->
--- 221,228 ----
<para>A <glossterm linkend="glossary-matrix">&matrix;</glossterm>
implements a two-dimensional mathematical matrix. Since it is a
! first-class type, it can be used in expressions such as assignments
! to matrices and multiplying matrices.</para>
<!-- FIXME: Want firstterm around vector. -->
***************
*** 234,259 ****
multiplying a &matrix; and a &vector;.</para>
<para>The data of an &array;, &dynamicarray;, or &field; can be
! viewed using more than one container by taking a view. A
! <glossterm
linkend="glossary-view"><firstterm>view</firstterm></glossterm> of
an existing container &container; is a container whose domain
! is a subset of &container;. The subset can equal the
! original domain. A view acts like a reference in that changing
! any of the view's values also changes the original container's and
! vice versa. While users sometimes explicitly create views, they
! are perhaps more frequently created as temporaries in expressions.
! For example, if <varname>A</varname> is an &array; and
! <varname>I</varname> is a domain, <statement>A(I) -
! A(I-1)</statement> forms the difference between adjacent
! values.</para>
<section id="concepts-containers-choosing">
<title>Choosing a Container</title>
<para>The two most commonly used &pooma; containers are &array;s
! and &field;s. <xref
linkend="concepts-containers-choice_table"></xref> contains a
decision tree describing how to choose an appropriate
container.</para>
--- 233,257 ----
multiplying a &matrix; and a &vector;.</para>
<para>The data of an &array;, &dynamicarray;, or &field; can be
! viewed using more than one container by taking a view. A <glossterm
linkend="glossary-view"><firstterm>view</firstterm></glossterm> of
an existing container &container; is a container whose domain
! is a subset of &container;. The subset can equal the original
! domain. A view acts like a reference in that changing any of the
! view's values also changes the original container's and vice versa.
! While users sometimes explicitly create views, they are perhaps more
! frequently created as temporaries in expressions. For example, if
! <varname>A</varname> is an &array; and <varname>I</varname> is a
! domain, <statement>A(I) - A(I-1)</statement> uses two views to form
! the difference between adjacent values.</para>
<section id="concepts-containers-choosing">
<title>Choosing a Container</title>
<para>The two most commonly used &pooma; containers are &array;s
! and &field;s, while &vector;, &matrix;, or &tensor; frequently
! represent mathematical objects. <xref
linkend="concepts-containers-choice_table"></xref> contains a
decision tree describing how to choose an appropriate
container.</para>
***************
*** 298,303 ****
--- 296,307 ----
<section id="concepts-containers-sequential_declarations">
<title>Declaring Sequential Containers</title>
+ <para>In the previous sections, we introduced the &pooma;
+ containers and described how to choose one appropriate for a
+ given task. In this section, we describe the concepts involved
+ in declaring them. Concepts specific to distributed computation
+ are described in the next section.</para>
+
<figure float="1" id="concepts-sequential_containers-declarations-dependences">
<title>Concepts For Declaring Containers</title>
<mediaobject>
***************
*** 310,347 ****
</mediaobject>
</figure>
- <para>In the previous sections, we introduced the &pooma;
- containers and described how to choose one appropriate for a
- given task. In this section, we describe the concepts involved
- in declaring them. Concepts specific to distributed computation
- are described in the next section.</para>
-
<para><xref
linkend="concepts-sequential_containers-declarations-dependences"></xref>
illustrates the containers and the concepts involved in their
declarations. The containers are listed in the top row. Lines
connect these containers to the components necessary for their
declarations. For example, an &array; declaration requires an
! engine and a layout. These, in turn, depend on other &pooma;
concepts. Declarations necessary only for distributed, or
! multiprocessor, computation are surrounded by dashed lines. You
! can use these dependences to indicate the concepts needed for a
! particular container.</para>
<para>An <glossterm
linkend="glossary-engine"><firstterm>engine</firstterm></glossterm>
stores and, if necessary, computes a container's values. A
container has one or more engines. The separation of a container
! and its storage permits optimizing a program's space
requirements. For example, a container returning the same value
for all indices can use a constant engine, which need only store
one value for the entire domain. A &compressiblebrick; engine
reduces its space requirements to a constant whenever all its
values are the same. The separation also permits taking <link
! linkend="glossary-view">view</link>s of containers without
! copying storage.</para>
! <figure float="1" id="concepts-containers-declarations-computational_implementation">
<title>&array; and &field; Mathematical and Computational Concepts</title>
<mediaobject>
<imageobject>
--- 314,345 ----
</mediaobject>
</figure>
<para><xref
linkend="concepts-sequential_containers-declarations-dependences"></xref>
illustrates the containers and the concepts involved in their
declarations. The containers are listed in the top row. Lines
connect these containers to the components necessary for their
declarations. For example, an &array; declaration requires an
! engine and a layout. These, in turn, can depend on other &pooma;
concepts. Declarations necessary only for distributed, or
! multiprocessor, computation are surrounded by dashed lines. These
! dependences to indicate the concepts needed for a particular
! container.</para>
<para>An <glossterm
linkend="glossary-engine"><firstterm>engine</firstterm></glossterm>
stores and, if necessary, computes a container's values. A
container has one or more engines. The separation of a container
! from its storage permits optimizing a program's space and time
requirements. For example, a container returning the same value
for all indices can use a constant engine, which need only store
one value for the entire domain. A &compressiblebrick; engine
reduces its space requirements to a constant whenever all its
values are the same. The separation also permits taking <link
! linkend="glossary-view">view</link>s of containers without copying
! storage.</para>
! <figure float="1" pgwide="1" id="concepts-containers-declarations-computational_implementation">
<title>&array; and &field; Mathematical and Computational Concepts</title>
<mediaobject>
<imageobject>
***************
*** 356,387 ****
<para>A <glossterm
linkend="glossary-layout"><firstterm>layout</firstterm></glossterm>
maps <link linkend="glossary-domain">domain</link> indices to the
! processors and computer memory used by a container's engines.
! See <xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
! A computer computes a container's values using a processor and
! memory. The layout specifies the processor(s) and memory to use
! for each particular index. A container's layout for a
! uniprocessor implementation consists of its domain, the
! processor, and its memory. For a multi-processor implementation,
! the layout maps portions of the domain to (possibly different)
! processors and memory.</para>
<para>A &field;'s <glossterm
linkend="glossary-mesh"><firstterm>mesh</firstterm></glossterm>
maps <link linkend="glossary-domain">domain</link> indices to
! spatial values in &space; such as distance between cells, edge
lengths, and normals to cells. In other words, it provides a
&field;'s spatial extent. See also <xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
! Different mesh types may support different spatial
! values.</para>
<para>A mesh's <glossterm
linkend="glossary-corner_position"><firstterm>corner
position</firstterm></glossterm> specifies the <link
linkend="glossary-point">point</link> in &space; corresponding to
! the lower, left corner of its <link
linkend="glossary-domain">domain</link>. Combining this, the
domain, and the cell size fully specifies the mesh's map from
indices to &space;.</para>
--- 354,408 ----
<para>A <glossterm
linkend="glossary-layout"><firstterm>layout</firstterm></glossterm>
maps <link linkend="glossary-domain">domain</link> indices to the
! processors and computer memory used by a container's engines. See
! <xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
! A program computes a container's values using a processor and
! memory. The layout specifies the processors and memory to use for
! each particular index. A container's layout for a uniprocessor
! implementation consists of its domain, the processor, and its
! memory. For a multi-processor implementation, the layout maps
! portions of the domain to (possibly different) processors and
! memory.</para>
+ <para>A <glossterm
+ linkend="glossary-domain"><firstterm>domain</firstterm></glossterm>
+ is a set of points on which a container can define values. There
+ are several different types of domains. An <glossterm
+ linkend="glossary-interval"><firstterm>interval</firstterm></glossterm>
+ consists of all integral points between two endpoints. It is
+ frequently represented using mathematical interval notation [a,b]
+ even though it contains only the integral points, e.g., a, a+1,
+ a+2, …, b. The concept is generalized to multiple
+ dimensions by forming tensor product of intervals, i.e., all the
+ integral tuples in an &n;-dimensional space. For example, the
+ two-dimensional containers in the previous chapter are defined on a
+ two-dimensional domain with the both dimensions' spanning the
+ interval [0,n). A domain need not contain all integral points
+ between its endpoints. A <glossterm
+ linkend="glossary-stride"><firstterm>stride</firstterm></glossterm>
+ is a subset of an interval consisting of regularly-spaced points.
+ A <glossterm
+ linkend="glossary-range"><firstterm>range</firstterm></glossterm>
+ is a subset of an interval formed by the tensor product of strides.
+ A <glossterm
+ linkend="glossary-region"><firstterm>region</firstterm></glossterm>
+ represents a continuous &n;-dimensional domain.</para>
+
<para>A &field;'s <glossterm
linkend="glossary-mesh"><firstterm>mesh</firstterm></glossterm>
maps <link linkend="glossary-domain">domain</link> indices to
! spatial values in &space; such as distances between cells, edge
lengths, and normals to cells. In other words, it provides a
&field;'s spatial extent. See also <xref
linkend="concepts-containers-declarations-computational_implementation"></xref>.
! Different mesh types may support different spatial values.</para>
<para>A mesh's <glossterm
linkend="glossary-corner_position"><firstterm>corner
position</firstterm></glossterm> specifies the <link
linkend="glossary-point">point</link> in &space; corresponding to
! the cell in the lower, left corner of its <link
linkend="glossary-domain">domain</link>. Combining this, the
domain, and the cell size fully specifies the mesh's map from
indices to &space;.</para>
***************
*** 393,434 ****
width, height, and depth, in &space;. Combining this, the
domain, and the corner position fully specifies the mesh's map
from indices to &space;.</para>
-
- <para>A <glossterm
- linkend="glossary-domain"><firstterm>domain</firstterm></glossterm>
- is a set of points on which a container can define values. An
- <glossterm
- linkend="glossary-interval"><firstterm>interval</firstterm></glossterm>
- consists of all integral points between two values. It is
- frequently represented using mathematical interval notation [a,b]
- even though it contains only the integral points, e.g., a, a+1,
- a+2, …, b. The concept is generalized to multiple
- dimensions by forming tensor product of intervals, i.e., all the
- integral tuples in an &n;-dimensional space. For example, the
- two-dimensional containers in the previous chapter are defined on
- a two-dimensional domain with the both dimensions' spanning the
- interval [0,n). A <glossterm
- linkend="glossary-stride"><firstterm>stride</firstterm></glossterm>
- is a subset of an interval consisting of regularly-spaced
- points. A <glossterm
- linkend="glossary-range"><firstterm>range</firstterm></glossterm>
- is a subset of an interval formed by the tensor product of strides.
- A <glossterm
- linkend="glossary-region"><firstterm>region</firstterm></glossterm>
- represents a continuous &n;-dimensional domain.</para>
</section>
<section id="concepts-containers-distributed_declarations">
<title>Declaring Distributed Containers</title>
! <para>In the previous section, we introduced the concepts
! important when declaring containers for use on uniprocessor
! computers. When using multi-processor computers, we augment
! these concepts with those for distributed computation. Reading
! this section is important only for running the same program on
! multiple processors. Many of these concepts were introduced in
! <xref linkend="tutorial-array_distributed"></xref> and <xref
linkend="tutorial-field_distributed"></xref>. <xref
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
illustrates the &pooma; distributed computation model. In this
--- 414,432 ----
width, height, and depth, in &space;. Combining this, the
domain, and the corner position fully specifies the mesh's map
from indices to &space;.</para>
</section>
<section id="concepts-containers-distributed_declarations">
<title>Declaring Distributed Containers</title>
! <para>In the previous section, we introduced the concepts important
! when declaring containers for use on uniprocessor computers. When
! using multi-processor computers, we augment these concepts with
! those for distributed computation. Reading this section is
! important only for running a program on multiple processors. Many
! of these concepts were introduced in <xref
! linkend="tutorial-array_distributed"></xref> and <xref
linkend="tutorial-field_distributed"></xref>. <xref
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
illustrates the &pooma; distributed computation model. In this
***************
*** 447,480 ****
<para>A <glossterm
linkend="glossary-partition"><firstterm>partition</firstterm></glossterm>
! specified how to divide a container's domain into distributed
pieces. For example, the partition illustrated in <xref
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
would divide a two-dimensional domain into three equally-sized
! pieces along the x-dimension and two equally-sized pieces along
! the y-dimension. Partitions can be independent of the size of
! container's domain. The example partition will work on any
! domain as long as the size of its x-dimension is a multiple of
! three. A domain is separated into disjoint <link
linkend="glossary-patch">patch</link>es.</para>
! <para>A <glossterm
! linkend="glossary-guard_layer"><firstterm>guard
! layer</firstterm></glossterm> is <quote>extra</quote> domain
! surrounding each patch. This region has read-only values. An
! <glossterm
linkend="glossary-external_guard_layer"><firstterm>external guard
layer</firstterm></glossterm> specifies values surrounding the
! domain. Its presence eases computation along the domain's edges
! by permitting the same computations as for more internal
computations. An <glossterm
linkend="glossary-internal_guard_layer"><firstterm>internal guard
layer</firstterm></glossterm> duplicates values from adjacent
patches so communication with adjacent patches need not occur
during a patch's computation. The use of guard layers is an
optimization; using external guard layers eases programming and
! using internal guard layers reduces communication among
! processors. Their use is not required.</para>
<para>A <glossterm
linkend="glossary-context_mapper"><firstterm>context
--- 445,476 ----
<para>A <glossterm
linkend="glossary-partition"><firstterm>partition</firstterm></glossterm>
! specifies how to divide a container's domain into distributed
pieces. For example, the partition illustrated in <xref
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
would divide a two-dimensional domain into three equally-sized
! pieces along the x-dimension and two equally-sized pieces along the
! y-dimension. Partitions can be independent of the size of
! container's domain. The example partition will work on any domain
! as long as the size of its x-dimension is a multiple of three. A
! domain is separated into disjoint <link
linkend="glossary-patch">patch</link>es.</para>
! <para>A <glossterm linkend="glossary-guard_layer"><firstterm>guard
! layer</firstterm></glossterm> surrounds each patch with read-only
! values. An <glossterm
linkend="glossary-external_guard_layer"><firstterm>external guard
layer</firstterm></glossterm> specifies values surrounding the
! entire domain. Its presence eases computation along the domain's
! edges by permitting the same computations as for more internal
computations. An <glossterm
linkend="glossary-internal_guard_layer"><firstterm>internal guard
layer</firstterm></glossterm> duplicates values from adjacent
patches so communication with adjacent patches need not occur
during a patch's computation. The use of guard layers is an
optimization; using external guard layers eases programming and
! using internal guard layers reduces communication among processors.
! Their use is not required.</para>
<para>A <glossterm
linkend="glossary-context_mapper"><firstterm>context
***************
*** 496,512 ****
<title>Computation Modes</title>
<para>&pooma; computations can be expressed using a variety of
! modes. Most of &pooma; computations involve &array; or &field;
containers, but how their values are accessed and the associated
! algorithms using them varies. Element-wise computation involves
! explicitly accessing values. A data-parallel computation uses
! expressions to represent larger subsets of a container's values.
! Stencil-based computations write a computation as repeatedly
! applying a local computation to each element of an array. A
! relation among containers establishes a dependency between them so
! the values of one container are updated whenever any other's
! values change. A program may use any or all of these styles,
! described below.</para>
<para><glossterm
linkend="glossary-element_wise"><firstterm>Element-wise</firstterm></glossterm>
--- 492,508 ----
<title>Computation Modes</title>
<para>&pooma; computations can be expressed using a variety of
! modes. Many &pooma; computations involve &array; or &field;
containers, but how their values are accessed and the associated
! algorithms using them varies. For example, element-wise computation
! involves explicitly accessing a container's values. A data-parallel
! computation uses expressions to represent larger subsets of a
! container's values. Stencil-based computations express a
! computation as repeatedly applying a local computation to each
! element of an array. A relation among containers establishes a
! dependency among them so the values of one container are updated
! whenever any other's values change. A program may use any or all of
! these styles, which are described below.</para>
<para><glossterm
linkend="glossary-element_wise"><firstterm>Element-wise</firstterm></glossterm>
***************
*** 515,521 ****
container &container; might be referenced as
<statement>&container(3,4)</statement> or
<statement>&container(i,j+1)</statement>. This is the usual
! notation for languages without objects such as &c;.</para>
<para><glossterm
linkend="glossary-data_parallel"><firstterm>Data-parallel</firstterm></glossterm>
--- 511,517 ----
container &container; might be referenced as
<statement>&container(3,4)</statement> or
<statement>&container(i,j+1)</statement>. This is the usual
! notation for non-object-oriented languages such as &c;.</para>
<para><glossterm
linkend="glossary-data_parallel"><firstterm>Data-parallel</firstterm></glossterm>
***************
*** 523,529 ****
values. For example, in <xref
linkend="tutorial-array_parallel-doof2d"></xref>,
<statement>a(I,J)</statement> represents the subset of &array;
! <varname>a</varname>'s values with coordinates in the domain
specified by the one-dimensional &interval;s <varname>I</varname>
and <varname>J</varname>. Using data-parallel expressions
frequently eliminates the need for writing explicit loops in
--- 519,525 ----
values. For example, in <xref
linkend="tutorial-array_parallel-doof2d"></xref>,
<statement>a(I,J)</statement> represents the subset of &array;
! <varname>a</varname>'s values having coordinates in the domain
specified by the one-dimensional &interval;s <varname>I</varname>
and <varname>J</varname>. Using data-parallel expressions
frequently eliminates the need for writing explicit loops in
***************
*** 532,555 ****
<para>A <glossterm
linkend="glossary-stencil"><firstterm>stencil</firstterm></glossterm>
computes a container's value using neighboring data values. Each
! stencil consists of an indication of which neighboring values to
read and a function using those values. For example, an averaging
! stencil may access all neighbors, averaging them. In &pooma;, we
! represent a stencil using a function object having functions
! indicating which neighboring values are used. Stencil
! computations are frequently used in solving partial differential
! equations, image processing, and geometric modeling.</para>
<para>A <glossterm
linkend="glossary-relation"><firstterm>relation</firstterm></glossterm>
! is a dependence among containers so the dependent container's
! values are updated when its values are needed and any of its
! related containers' values have changed. A relation is specified
! by a dependent container, independent containers, and a function
computing the dependent container's values using the independent
containers' values. To avoid excess computation, the dependent
! container's values are computed only when needed, e.g., for
! printing or for computing the values of another dependent
container. Thus, this computation is sometimes called <quote>lazy
evaluation</quote>.</para>
</section>
--- 528,552 ----
<para>A <glossterm
linkend="glossary-stencil"><firstterm>stencil</firstterm></glossterm>
computes a container's value using neighboring data values. Each
! stencil consists of a specification of which neighboring values to
read and a function using those values. For example, an averaging
! stencil may access all its adjacent neighbors, averaging them. In
! &pooma;, we represent a stencil using a function object with
! additional functions indicating which neighboring values are used.
! Stencil computations are frequently used in solving partial
! differential equations, image processing, and geometric
! modeling.</para>
<para>A <glossterm
linkend="glossary-relation"><firstterm>relation</firstterm></glossterm>
! is a dependence among containers such the dependent container's
! values are updated when its values are needed and any of its related
! containers' values have changed. A relation is specified by a
! dependent container, independent containers, and a function
computing the dependent container's values using the independent
containers' values. To avoid excess computation, the dependent
! container's values are computed only when needed, e.g., for printing
! the container or for computing the values of another dependent
container. Thus, this computation is sometimes called <quote>lazy
evaluation</quote>.</para>
</section>
***************
*** 558,589 ****
<section id="concepts-computation_environment">
<title>Computation Environment</title>
! <para>A &pooma; program can execute on a wide variety of
! computers. The default <glossterm
linkend="glossary-sequential"><firstterm>sequential computing
environment</firstterm></glossterm> consists of one processor and
! associated memory, as found on a personal computer. In contrast,
! a <glossterm
linkend="glossary-distributed"><firstterm>distributed computing
environment</firstterm></glossterm> may have multiple processors
and multiple distributed or shared memories. For example, some
desktop computers have dual processors and shared memory, while a
! large supercomputer may have thousands of processors, perhaps
! with groups of eight sharing the same memory.</para>
<para>Using distributed computation requires three things:
<orderedlist>
<listitem>
! <para>the programmer must declare how container domains will
! be distributed,</para>
</listitem>
<listitem>
<para>&pooma; must be configured to use a communications
! library, and </para>
</listitem>
<listitem>
! <para>the &pooma; executable must be run using the
! library.</para>
</listitem>
</orderedlist>
All of these were illustrated in <xref
--- 555,585 ----
<section id="concepts-computation_environment">
<title>Computation Environment</title>
! <para>A &pooma; program can execute on a wide variety of computers.
! The default <glossterm
linkend="glossary-sequential"><firstterm>sequential computing
environment</firstterm></glossterm> consists of one processor and
! its associated memory, as found on a personal computer. In
! contrast, a <glossterm
linkend="glossary-distributed"><firstterm>distributed computing
environment</firstterm></glossterm> may have multiple processors
and multiple distributed or shared memories. For example, some
desktop computers have dual processors and shared memory, while a
! large supercomputer may have thousands of processors, perhaps with
! groups of eight sharing the same memory.</para>
<para>Using distributed computation requires three things:
<orderedlist>
<listitem>
! <para>The program must declare how container domains will
! be distributed.</para>
</listitem>
<listitem>
<para>&pooma; must be configured to use a communications
! library.</para>
</listitem>
<listitem>
! <para>The &pooma; executable must be run using the library.</para>
</listitem>
</orderedlist>
All of these were illustrated in <xref
***************
*** 592,604 ****
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
illustrates the &pooma; distributed computation model. <xref
linkend="concepts-containers-distributed_declarations"></xref>
! described how to declare containers with distributed domains.
! Detailed instructions how to configure &pooma; for distributed
! computation appear in <xref linkend="installation"></xref>.
! Detailed instructions how to run distributed &pooma; executables
! appear in <xref linkend="parallel"></xref>. Here we present
! three concepts for distributed computation: patches, context, and
! a communication library.</para>
<para>A partition divides a container's domain into disjoint
<glossterm
--- 588,596 ----
linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
illustrates the &pooma; distributed computation model. <xref
linkend="concepts-containers-distributed_declarations"></xref>
! described how to declare containers with distributed domains. Here
! we present three concepts for distributed computation: patches,
! context, and a communication library.</para>
<para>A partition divides a container's domain into disjoint
<glossterm
***************
*** 611,618 ****
<para>A <glossterm
linkend="glossary-context"><firstterm>context</firstterm></glossterm>
! is a collection of shared memory and processors that can execute
! a program of a portion of a program. It can have one or more
processors, but all these processors must access the same shared
memory. Usually the computer and its operating system, not the
programmer, determine the available contexts.</para>
--- 603,610 ----
<para>A <glossterm
linkend="glossary-context"><firstterm>context</firstterm></glossterm>
! is a collection of shared memory and processors that can execute a
! program or a portion of a program. It can have one or more
processors, but all these processors must access the same shared
memory. Usually the computer and its operating system, not the
programmer, determine the available contexts.</para>
***************
*** 625,630 ****
user. &pooma; works with the Message Passing Interface (&mpi;)
Communications Library (FIXME: xref linkend="mpi99", <ulink
url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) and the &mm;
! Shared Memory Library.</para>
</section>
</chapter>
--- 617,623 ----
user. &pooma; works with the Message Passing Interface (&mpi;)
Communications Library (FIXME: xref linkend="mpi99", <ulink
url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) and the &mm;
! Shared Memory Library. See <xref
! linkend="installation-distributed_computing"></xref> for details.</para>
</section>
</chapter>
Index: glossary.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/glossary.xml,v
retrieving revision 1.2
diff -c -p -r1.2 glossary.xml
*** glossary.xml 2001/12/13 04:04:05 1.2
--- glossary.xml 2001/12/14 04:12:54
***************
*** 341,347 ****
<glossentry id="glossary-interval">
<glossterm>interval</glossterm>
<glossdef>
! <para>a set of integral points between two values. This domain
is frequently represented using mathematical interval notation
[a,b] even though it contains only the integral points, e.g., a,
a+1, a+2, …, b. It is also generalized to the tensor
--- 341,347 ----
<glossentry id="glossary-interval">
<glossterm>interval</glossterm>
<glossdef>
! <para>a set of integral points between two endpoints. This domain
is frequently represented using mathematical interval notation
[a,b] even though it contains only the integral points, e.g., a,
a+1, a+2, …, b. It is also generalized to the tensor
Index: makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/makefile,v
retrieving revision 1.2
diff -c -p -r1.2 makefile
*** makefile 2001/12/11 20:36:13 1.2
--- makefile 2001/12/14 04:12:54
*************** CXXFLAGS= -g -Wall -pedantic -W -Wstrict
*** 25,30 ****
--- 25,32 ----
all: manual.ps
+ manual.dvi: manual.xml concepts.xml tutorial.xml
+
%.all: %.ps %.pdf %.html
chmod 644 $*.ps $*.pdf
mv $*.ps $*.pdf $*
Index: manual.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/manual.xml,v
retrieving revision 1.2
diff -c -p -r1.2 manual.xml
*** manual.xml 2001/12/13 04:04:05 1.2
--- manual.xml 2001/12/14 04:12:57
***************
*** 356,365 ****
<chapter id="sequential">
<title>Writing Sequential Programs</title>
! <para>QUESTIONS: How do I arrange this section? What material do I
! include? What other books or models can I follow?</para>
<!-- HERE -->
<para>&pooma; can reorder computations to permit more efficient
computation. When running a sequential program, reordering may
--- 356,529 ----
<chapter id="sequential">
<title>Writing Sequential Programs</title>
! <para>Proposed order. Basically follow the order in the proposed
! reference section.
! <orderedlist>
! <listitem><para>starting, stopping</para></listitem>
! <listitem><para>&array;</para></listitem>
! <listitem><para>&dynamicarray;</para></listitem>
! <listitem><para>&field;</para></listitem>
! <listitem><para>&vector;</para></listitem>
! <listitem><para>&matrix;</para></listitem>
! <listitem><para>&tensor;</para></listitem>
! <listitem><para>engine</para></listitem>
! <listitem><para>domain</para></listitem>
! <listitem><para>correctness, e.g., <function>PAssert</function></para></listitem>
! <listitem><para>&pooma; command-line options</para></listitem>
! </orderedlist>
! Include views of containers in the appropriate sections.</para>
<!-- HERE -->
+
+ <para><emphasis>&c;: A Reference Manual</emphasis> uses this
+ structure for &c; libraries:
+ <orderedlist>
+ <listitem>
+ <para>function declarations, separated by rules from rest of text</para>
+ </listitem>
+ <listitem>
+ <para>text explanation</para>
+ </listitem>
+ <listitem>
+ <para>table of structure members if appropriate</para>
+ </listitem>
+ <listitem>
+ <para>example</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para><emphasis>STL Tutorial and Reference Guide</emphasis>, second
+ edition, uses this structure for STL functions:
+ <orderedlist>
+ <listitem>
+ <para>text description with declaration mixed in</para>
+ </listitem>
+ <listitem>
+ <para>example program mixed into text. It is an entire program,
+ not a program fragment.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>A tutorial chapter for containers has
+ <orderedlist>
+ <listitem>
+ <para>explanation of template types</para>
+ </listitem>
+ <listitem>
+ <para>bulleted list of container types</para>
+ </listitem>
+ <listitem>
+ <para>example constructors</para>
+ </listitem>
+ <listitem>
+ <para>example programs</para>
+ </listitem>
+ <listitem>
+ <para>member and related functions with example programs</para>
+ </listitem>
+ <listitem>
+ <para>list of accessors and relation functions</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>The reference chapter for containers has
+ <orderedlist>
+ <listitem>
+ <para>a section listing common members and types for all containers</para>
+ </listitem>
+ <listitem>
+ <para>a section listing common member functions for all containers</para>
+ </listitem>
+ <listitem>
+ <para>requirements for various container specialties</para>
+ </listitem>
+ </orderedlist>
+ The section describing <type>vector</type>s contains
+ <orderedlist>
+ <listitem>
+ <para>files (header files)</para>
+ </listitem>
+ <listitem>
+ <para>class declaration</para>
+ </listitem>
+ <listitem>
+ <para>description</para>
+ </listitem>
+ <listitem>
+ <para>type definitions</para>
+ </listitem>
+ <listitem>
+ <para>constructors, destructors, and related functions</para>
+ </listitem>
+ <listitem>
+ <para>comparison operators</para>
+ </listitem>
+ <listitem>
+ <para>element access member functions</para>
+ </listitem>
+ <listitem>
+ <para>insert and erase member functions</para>
+ </listitem>
+ <listitem>
+ <para>notes</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>Josuttis's <emphasis>The &cc; Standard Library: A Tutorial
+ and Reference</emphasis> uses this structure for its STL container
+ chapter:
+ <orderedlist>
+ <listitem>
+ <para>short introduction</para>
+ </listitem>
+ <listitem>
+ <para>common container abilities</para>
+ </listitem>
+ <listitem>
+ <para>common container operations (with table)</para>
+ </listitem>
+ <listitem>
+ <para>vector abilities</para>
+ </listitem>
+ <listitem>
+ <para>vector operations:
+ <orderedlist>
+ <listitem>
+ <para>create, copy, and destroy operations (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>nonmodifying operations (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>assignments (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>element access (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>iterator functions (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>inserting and removing elements (mostly table)</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>using vectors as ordinary arrays</para>
+ </listitem>
+ <listitem>
+ <para>exception handling</para>
+ </listitem>
+ <listitem>
+ <para>example program</para>
+ </listitem>
+ </orderedlist>
+ </para>
<para>&pooma; can reorder computations to permit more efficient
computation. When running a sequential program, reordering may
Index: tutorial.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/tutorial.xml,v
retrieving revision 1.1
diff -c -p -r1.1 tutorial.xml
*** tutorial.xml 2001/12/11 20:36:13 1.1
--- tutorial.xml 2001/12/14 04:12:58
***************
*** 518,524 ****
<section id="tutorial-array_stencil">
<title>Stencil &array; Implementation</title>
! <para>Many computations are local, computing a &array;'s value by
using close-by &array; values. Encapsulating this computation in
a stencil can yield faster code because the compiler can determine
all accesses come from the same array. Each stencil consists of a
--- 518,524 ----
<section id="tutorial-array_stencil">
<title>Stencil &array; Implementation</title>
! <para>Many computations are local, computing an &array;'s value by
using close-by &array; values. Encapsulating this computation in
a stencil can yield faster code because the compiler can determine
all accesses come from the same array. Each stencil consists of a
Index: figures/concepts.mp
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/concepts.mp,v
retrieving revision 1.2
diff -c -p -r1.2 concepts.mp
*** figures/concepts.mp 2001/12/13 04:04:05 1.2
--- figures/concepts.mp 2001/12/14 04:12:58
*************** endfig;
*** 116,122 ****
%% Comparisons Between Mathematical Concept And Computational Implementation of Arrays and Fields
beginfig(101)
! numeric unit; unit = 0.9cm;
numeric vertSpace; vertSpace = 2.6unit; % vertical space between sections
numeric horizSpace; horizSpace = 8unit; % horizontal space between sections
--- 116,122 ----
%% Comparisons Between Mathematical Concept And Computational Implementation of Arrays and Fields
beginfig(101)
! numeric unit; unit = 0.8cm;
numeric vertSpace; vertSpace = 2.6unit; % vertical space between sections
numeric horizSpace; horizSpace = 8unit; % horizontal space between sections
*************** beginfig(101)
*** 137,144 ****
endfor
% Create and layout text boxes.
! boxit.l1(btex \strut mathematical concept etex);
! boxit.l2(btex \strut computational implementation etex);
boxit.l3(btex \strut \type{Array}: etex);
boxit.l4(btex \strut $\mbox{index} \mapsto \mbox{value}$ etex);
boxit.l6(btex \strut \type{Field}: etex);
--- 137,144 ----
endfor
% Create and layout text boxes.
! boxit.l1(btex \strut \underline{mathematical concept} etex);
! boxit.l2(btex \strut \underline{computational implementation} etex);
boxit.l3(btex \strut \type{Array}: etex);
boxit.l4(btex \strut $\mbox{index} \mapsto \mbox{value}$ etex);
boxit.l6(btex \strut \type{Field}: etex);
*************** beginfig(101)
*** 152,158 ****
l1.w - l3.w = l4.w - l7.w = (0,vertSpace);
l4.w - l3.e = l7.nw - l6.ne = (0,0);
for t = 0 upto 1:
! xpart(ia[t].w - l[3+3t].e) = 0.65horizSpace;
ypart(ia[t].w - l[3+3t].c) = 0;
endfor
xpart(l10.w - l7.w) = 0;
--- 152,158 ----
l1.w - l3.w = l4.w - l7.w = (0,vertSpace);
l4.w - l3.e = l7.nw - l6.ne = (0,0);
for t = 0 upto 1:
! xpart(ia[t].w - l[3+3t].e) = 0.6horizSpace;
ypart(ia[t].w - l[3+3t].c) = 0;
endfor
xpart(l10.w - l7.w) = 0;
More information about the pooma-dev
mailing list