Patch: Manual: Tutorial Chapter and Part of Concepts Chapter
Jeffrey Oldham
oldham at codesourcery.com
Tue Dec 11 21:40:31 UTC 2001
This patch contains continuing work toward a Pooma manual. Most of
these changes fail into these two categories:
1) continuing work on a tutorial chapter using Doof2d implementations
to introduce Pooma concepts
2) moving material among files to yield smaller files.
2001-Dec-11 Jeffrey D. Oldham <oldham at codesourcery.com>
* glossary.xml: New file containing the glossary entries. It was
previously part of outline.xml.
* makefile: Revise to create manual.ps, not outline.ps.
* manual.xml: New file containing most of the manual. It replaces
outline.xml. Too many changes were made to be listed here. Most
of the changes have occurred in the tutorial chapter and the
concept chapter.
* outline.xml: Removed in favor of manual.xml and the files the
latter includes.
* tutorial.xml: New file containing the tutorial chapter. This
was created from outline.xml.
* figures/concepts.mp: New MetaPost file to create illustrations
for Array and Field's purposes and of the conceptual dependences
when declaring containers.
* figures/distributed.mp: Revise to make it smaller, move macros
out of the source code, and fix formatting mistake.
* figures/doof2d.mp: Revise to use macros.
* figures/macros.ltx: New file containing LaTeX macros common to
MetaPost files.
* programs/Doof2d-Array-distributed-annotated.patch: Revised to
reflect changes to programs/Doof2d-Array-distributed.cpp.
* programs/Doof2d-Array-distributed-annotated.patch: Similar.
* programs/Doof2d-Array-parallel-annotated.patch: Similar.
* programs/Doof2d-Array-stencil-annotated.patch: Similar.
* programs/Doof2d-C-element-annotated.patch: Similar.
* programs/Doof2d-Field-distributed-annotated.patch: New file
with an annotated version of Doof2d-Field-distributed.cpp.
* programs/Doof2d-Field-parallel-annotated.patch: Similar.
Applied to mainline
Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: glossary.xml
===================================================================
RCS file: glossary.xml
diff -N glossary.xml
*** /dev/null Fri Mar 23 21:37:44 2001
--- glossary.xml Tue Dec 11 13:31:06 2001
***************
*** 0 ****
--- 1,514 ----
+ <!-- Glossary -->
+
+ <glossary id="glossary">
+ <title>Glossary</title>
+
+ <!-- Write the definitions so reading
+ 1) the term
+ 2) an implicit "is (a/an)"
+ 3) the definition is a complete paragraph.
+ Thus, the beginning of the definition should not be capitalized and
+ should finish a sentence. The rest of the definition should
+ consist of complete sentences. -->
+
+ <para>ADD: Make sure all entries are indexed and perhaps point back
+ to their first use. WARNING: This is constructed by hand so it is
+ likely to be full of inconsistencies and errors.</para>
+
+ <glossdiv id="glossary-a">
+ <title>A</title>
+ <glossentry id="glossary-array">
+ <glossterm>&array;</glossterm>
+ <glossdef>
+ <para>a &pooma; container generalizing &c; arrays and mapping
+ indices to values. Constant-time access to values is supported,
+ ignoring the time to compute the values if applicable. &array;s
+ are <link linkend="glossary-first_class">first-class
+ object</link>s. <link
+ linkend="glossary-dynamicarray">&dynamicarray;</link>s and <link
+ linkend="glossary-field">&field;</link>s generalize &array;.</para>
+ <glossseealso otherterm="glossary-dynamicarray">&dynamicarray;</glossseealso>
+ <glossseealso otherterm="glossary-field">&field;</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-b">
+ <title>B</title>
+ <glossentry id="glossary-brick">
+ <glossterm>brick engine</glossterm>
+ <glossdef>
+ <para>an engine explicitly storing each of its values. Its space
+ requirements are at least the size of the engine's domain.</para>
+ <glossseealso otherterm="glossary-engine">engine</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-c">
+ <title>C</title>
+
+ <glossentry id="glossary-cell">
+ <glossterm>cell</glossterm>
+ <glossdef>
+ <para>a <link linkend="glossary-domain">domain</link> element of
+ a <link linkend="glossary-field">&field;</link>. Both <link
+ linkend="glossary-array">&array;</link> and &field; domain
+ elements are denoted by indices, but a cell exists in space. For
+ example, it might be a rectangle or rectangular
+ parallelepiped.</para>
+ <glossseealso otherterm="glossary-field">&field;</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cell_size">
+ <glossterm>cell size</glossterm>
+ <glossdef>
+ <para>specifies a &field; cell's dimensions e.g., its
+ width, height, and depth, in &space;. This is frequently
+ used to specify a mesh.</para>
+ <glossseealso otherterm="glossary-mesh">mesh</glossseealso>
+ <glossseealso otherterm="glossary-corner_position">corner position</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-computing_environment">
+ <glossterm>computing environment</glossterm>
+ <glossdef>
+ <para>computer. More precisely, a computer with its arrangement
+ of processors and associated memory, possibly shared among
+ processors.</para>
+ <glossseealso otherterm="glossary-sequential">sequential computing environment</glossseealso>
+ <glossseealso otherterm="glossary-distributed">distributed computing environment</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-container">
+ <glossterm>container</glossterm>
+ <glossdef>
+ <para>an object that stores other objects, controlling their
+ allocation, deallocation, and access. Similar to &cc; containers,
+ the most important &pooma; containers are <link
+ linkend="glossary-array">&array;</link>s and <link
+ linkend="glossary-field">&field;</link>s.</para>
+ <glossseealso otherterm="glossary-array">&array;</glossseealso>
+ <glossseealso otherterm="glossary-dynamicarray">&dynamicarray;</glossseealso>
+ <glossseealso otherterm="glossary-field">&field;</glossseealso>
+ <glossseealso otherterm="glossary-tensor">&tensor;</glossseealso>
+ <glossseealso otherterm="glossary-matrix">&matrix;</glossseealso>
+ <glossseealso otherterm="glossary-vector">&vector;</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-context">
+ <glossterm>context</glossterm>
+ <glossdef>
+ <para>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>
+ <glossseealso otherterm="glossary-distributed">distributed computing environment</glossseealso>
+ <glossseealso otherterm="glossary-layout">layout</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-context_mapper">
+ <glossterm>context mapper</glossterm>
+ <glossdef>
+ <para>indicates how a container's patches are mapped to
+ processors and shared memory. Two common choices are
+ distribution among the various processors and replication.</para>
+ <glossseealso otherterm="glossary-patch">patch</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-corner_position">
+ <glossterm>corner position</glossterm>
+ <glossdef>
+ <para>specifies the &space; point corresponding to a &field;
+ domain's lower, left corner.</para>
+ <glossseealso otherterm="glossary-mesh">mesh</glossseealso>
+ <glossseealso otherterm="glossary-cell_size">cell size</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-d">
+ <title>D</title>
+
+ <glossentry id="glossary-distributed">
+ <glossterm>distributed computing environment</glossterm>
+ <glossdef>
+ <para>computing environment with one or more processors each
+ having associated memory, possibly shared. In some contexts, it
+ refers to strictly multi-processor computation.</para>
+ <glossseealso otherterm="glossary-computing_environment">computing environment</glossseealso>
+ <glossseealso otherterm="glossary-sequential">sequential computing environment</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-domain">
+ <glossterm>domain</glossterm>
+ <glossdef>
+ <para>a set of points on which a container can define values.
+ For example, a set of discrete integral &n;-tuples in
+ &n;-dimensional space frequently serve as container domains.</para>
+ <glossseealso otherterm="glossary-container">container</glossseealso>
+ <glossseealso otherterm="glossary-interval">interval</glossseealso>
+ <glossseealso otherterm="glossary-stride">stride</glossseealso>
+ <glossseealso otherterm="glossary-range">range</glossseealso>
+ <glossseealso otherterm="glossary-region">region</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-dynamicarray">
+ <glossterm>&dynamicarray;</glossterm>
+ <glossdef>
+ <para>a &pooma; container generalizing one-dimensional <link
+ linkend="glossary-array">&array;</link>s by supporting domain
+ resizing at run-time. It maps indices to values in constant-time
+ access, ignoring the time to compute the values if applicable.
+ &dynamicarray;s are <link
+ linkend="glossary-first_class">first-class object</link>s.</para>
+ <glossseealso otherterm="glossary-array">&array;</glossseealso>
+ <glossseealso otherterm="glossary-field">&field;</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-e">
+ <title>E</title>
+
+ <glossentry id="glossary-engine">
+ <glossterm>engine</glossterm>
+ <glossdef>
+ <para>stores and, if necessary, computes a <link
+ linkend="glossary-container">container</link>'s values. These
+ can be specialized, e.g., to minimize storage when a domain has
+ few distinct values. Separating a container and its storage also
+ permits <link linkend="glossary-view">views</link> of a container.</para>
+ <glossseealso otherterm="glossary-container">&engine;</glossseealso>
+ <glossseealso otherterm="glossary-view">view of a container</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-external_guard_layer">
+ <glossterm>external guard layer</glossterm>
+ <glossdef>
+ <para><link linkend="glossary-guard_layer">guard layer</link>
+ surrounding a container's domain used to ease computation along
+ the domain's edges by permitting the same computations as for
+ more internal computations. It is an optimization, not required
+ for program correctness.</para>
+ <glossseealso otherterm="glossary-guard_layer">guard layer</glossseealso>
+ <glossseealso otherterm="glossary-internal_guard_layer">internal guard layer</glossseealso>
+ <glossseealso otherterm="glossary-patch">patch</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-f">
+ <title>F</title>
+
+ <glossentry id="glossary-field">
+ <glossterm>&field;</glossterm>
+ <glossdef>
+ <para>a &pooma; container representing an &array; with spatial
+ extent. It also supports multiple values and multiple materials
+ indexed by the same value. It maps indices to values in constant
+ time, ignoring the time to compute the values if applicable. It
+ also supports geometric computations such as the distance between
+ two <link linkend="glossary-cell">cell</link>s and normals to a
+ cell. &field;s are <link
+ linkend="glossary-first_class">first-class object</link>s.</para>
+ <glossseealso otherterm="glossary-array">&array;</glossseealso>
+ <glossseealso otherterm="glossary-dynamicarray">&dynamicarray;</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-first_class">
+ <glossterm>first-class type</glossterm>
+ <glossdef>
+ <para>a type of object with all the capabilities of the built-in
+ type with the most capabilities. For example, <type>char</type>
+ and <type>int</type> are first-class types in &cc; because they
+ may be declared anywhere, stored in automatic variables, accessed
+ anywhere, copied, and passed by both value and reference.
+ &pooma; <link linkend="glossary-array">&array;</link> and <link
+ linkend="glossary-field">&field;</link> are first-class
+ types.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-g">
+ <title>G</title>
+
+ <glossentry id="glossary-guard_layer">
+ <glossterm>guard layer</glossterm>
+ <glossdef>
+ <para>domain surrounding each patch of a container's domain. It
+ contains read-only values. <link
+ linkend="glossary-external_guard_layer">External guard
+ layer</link>s ease programming, while <link
+ linkend="glossary-internal_guard_layer">internal guard
+ layer</link>s permit each patch's computation to be occur without
+ copying values from adjacent patches. They are optimizations,
+ not required for program correctness.</para>
+ <glossseealso otherterm="glossary-external_guard_layer">external guard layer</glossseealso>
+ <glossseealso otherterm="glossary-internal_guard_layer">internal guard layer</glossseealso>
+ <glossseealso otherterm="glossary-partition">partition</glossseealso>
+ <glossseealso otherterm="glossary-patch">patch</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-i">
+ <title>I</title>
+
+ <glossentry id="glossary-index">
+ <glossterm>index</glossterm>
+ <glossdef>
+ <para>a position in a <link
+ linkend="glossary-domain">domain</link> usually denoted by an
+ ordered tuple. More than one index are called <link
+ linkend="glossary-indices">indices</link>.</para>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-indices">
+ <glossterm>indices</glossterm>
+ <glossdef>
+ <para>More than one <link linkend="glossary-index">index</link>.</para>
+ <glossseealso otherterm="glossary-index">index</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-internal_guard_layer">
+ <glossterm>internal guard layer</glossterm>
+ <glossdef>
+ <para><link linkend="glossary-guard_layer">guard layer</link>
+ containing copies of adjacent patches' values. These copies can
+ permit an individual patch's computation to occur without asking
+ adjacent patches for values. This can speed computation but are
+ not required for program correctness.</para>
+ <glossseealso otherterm="glossary-guard_layer">guard layer</glossseealso>
+ <glossseealso otherterm="glossary-external_guard_layer">external guard layer</glossseealso>
+ <glossseealso otherterm="glossary-patch">patch</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <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
+ product of one-dimensional intervals. Many containers' domains
+ consist of these sets of ordered tuples.</para>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ <glossseealso otherterm="glossary-stride">stride</glossseealso>
+ <glossseealso otherterm="glossary-range">range</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id="glossary-l">
+ <title>L</title>
+
+ <glossentry id="glossary-layout">
+ <glossterm>layout</glossterm>
+ <glossdef>
+ <para>a map from an index to processor(s) and memory used to
+ compute the container's associated value. For a uniprocessor
+ implementation, a container's layout always 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>
+ <glossseealso otherterm="glossary-container">container</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-m">
+ <title>M</title>
+
+ <glossentry id="glossary-mesh">
+ <glossterm>mesh</glossterm>
+ <glossdef>
+ <para>a &field;'s map from indices to geometric values such as
+ cell size, edge length, and cell normals. In other words, it
+ specifies a &field;'s <quote>spatial extent</quote>.</para>
+ <glossseealso otherterm="glossary-field">&field;</glossseealso>
+ <glossseealso otherterm="glossary-layout">layout</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-p">
+ <title>P</title>
+
+ <glossentry id="glossary-partition">
+ <glossterm>partition</glossterm>
+ <glossdef>
+ <para>a specification how to divide a container's domain into
+ patches for distributed computation. It can be independent of
+ the domain's size. For example, it divide each domain into
+ halves, yielding a total of eight patches in three dimensions.
+ See <xref
+ linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>
+ for an illustration.</para>
+ <glossseealso otherterm="glossary-guard_layer">guard layer</glossseealso>
+ <glossseealso otherterm="glossary-patch">patch</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-patch">
+ <glossterm>patch</glossterm>
+ <glossdef>
+ <para>
+ ERE</para>
+ <glossseealso otherterm="glossary-partition">partition</glossseealso>
+ <glossseealso otherterm="glossary-guard_layer">guard layer</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <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>
+ <glossseealso otherterm="glossary-index">index</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-r">
+ <title>R</title>
+
+ <glossentry id="glossary-range">
+ <glossterm>range</glossterm>
+ <glossdef>
+ <para>an &n;-dimensional domain formed by the tensor product of
+ &n; <link linkend="glossary-stride">stride</link>s.</para>
+ <glossseealso otherterm="glossary-stride">stride</glossseealso>
+ <glossseealso
+ otherterm="glossary-interval">interval</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-region">
+ <glossterm>region</glossterm>
+ <glossdef>
+ <para>a domain consisting of a subset of &n;-dimensional
+ continuous space.</para>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ <glossseealso otherterm="glossary-interval">interval</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-s">
+ <title>S</title>
+
+ <glossentry id="glossary-sequential">
+ <glossterm>sequential computing environment</glossterm>
+ <glossdef>
+ <para>a computing environment with one processor and associated
+ memory. Only one processor executes a program even if the
+ conmputer itself has multiple processors.</para>
+ <glossseealso otherterm="glossary-computing_environment">computing environment</glossseealso>
+ <glossseealso otherterm="glossary-distributed">distributed computing environment</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stride">
+ <glossterm>stride</glossterm>
+ <glossdef>
+ <para>a subset of regularly-spaced points in an integral
+ interval. For example, the set of points a, a+2, a+4, …,
+ b-2, b is specified by [a,b] with stride 2. It is a
+ domain.</para>
+ <glossseealso otherterm="glossary-range">range</glossseealso>
+ <glossseealso otherterm="glossary-interval">interval</glossseealso>
+ <glossseealso otherterm="glossary-domain">domain</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-suite_name">
+ <glossterm>suite name</glossterm>
+ <glossdef>
+ <para>an arbitrary string denoting a particular toolkit
+ configuration. For example, the string
+ <quote>SUNKCC-debug</quote> might indicate a configuration for
+ the <trademark>Sun</trademark> <productname>Solaris</productname>
+ operating system and the &kcc; &cc; compiler with debugging
+ support. By default, the suite name it is equal to the
+ configuration's architecture name.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-t">
+ <title>T</title>
+
+ <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>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-matrix">
+ <glossterm>&matrix;</glossterm>
+ <glossdef>
+ <para>a &pooma; container implementing two-dimensional
+ mathematical matrices as first-class objects.</para>
+ <glossseealso otherterm="glossary-tensor">&tensor;</glossseealso>
+ <glossseealso otherterm="glossary-vector">&vector;</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="glossary-v">
+ <title>V</title>
+
+ <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>
+ <glossseealso otherterm="glossary-matrix">&matrix;</glossseealso>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>view of a container</glossterm>
+ <glossdef>
+ <para>a container derived from another. The former's domain is a
+ subset of the latter's, but, where the domains intersect,
+ accessing a value through the view is the same as accessing it
+ through the original container. Only &array;s, &dynamicarray;s,
+ and &field;s support views.</para>
+ <glossseealso otherterm="glossary-container">container</glossseealso>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ </glossary>
Index: makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/makefile,v
retrieving revision 1.1
diff -c -p -r1.1 makefile
*** makefile 2001/12/04 00:07:00 1.1
--- makefile 2001/12/11 20:31:06
*************** INDEXOPTIONS= -t 'Index' -i 'index' -g
*** 23,29 ****
CXXFLAGS= -g -Wall -pedantic -W -Wstrict-prototypes -Wpointer-arith -Wbad-function-cast -Wcast-align -Wconversion -Wnested-externs -Wundef -Winline -static
! all: outline.ps
%.all: %.ps %.pdf %.html
chmod 644 $*.ps $*.pdf
--- 23,29 ----
CXXFLAGS= -g -Wall -pedantic -W -Wstrict-prototypes -Wpointer-arith -Wbad-function-cast -Wcast-align -Wconversion -Wnested-externs -Wundef -Winline -static
! all: manual.ps
%.all: %.ps %.pdf %.html
chmod 644 $*.ps $*.pdf
*************** mproof-%.ps: %.mp
*** 66,69 ****
detex $< > $@
clean:
! rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.mpx mpxerr.tex HTML.index outline.tex
--- 66,69 ----
detex $< > $@
clean:
! rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.mpx mpxerr.tex HTML.index manual.tex
Index: manual.xml
===================================================================
RCS file: manual.xml
diff -N manual.xml
*** /dev/null Fri Mar 23 21:37:44 2001
--- manual.xml Tue Dec 11 13:31:09 2001
***************
*** 0 ****
--- 1,4034 ----
+ <?xml version="1.0"?>
+
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "file://usr/lib/sgml/docbookx.dtd" [
+
+ <!-- Text to Check, Revise, Replace -->
+ <!-- FIXME: Revise before releasing. -->
+ <!-- UPDATE: Check before publishing to see if any needs changing. -->
+ <!-- ADD: Write more material. -->
+
+ <!-- Index Entity Declarations -->
+ <!ENTITY genindex.sgm SYSTEM "genindex.sgm">
+
+ <!-- General Entity Declarations -->
+
+ <!ENTITY book "book">
+ <!-- Produce a notation for the book/manual/report/WWW page. -->
+ <!-- Modify this to the desired noun. -->
+ <!ENTITY Book "Book">
+ <!-- Produce a capitalized version of &book; -->
+ <!-- Modify this to the desired noun. -->
+ <!ENTITY c "<application class='software'>C</application>">
+ <!-- Produce a notation for the C programming language. -->
+ <!-- Modify this to the desired formatting. -->
+ <!ENTITY cc "<application class='software'>C++</application>">
+ <!-- Produce a notation for the C++ programming language. -->
+ <!-- Modify this to the desired formatting. -->
+ <!ENTITY cheetah "<application class='software'>Cheetah</application>" >
+ <!-- Produce a notation for the Cheetah Library. -->
+ <!ENTITY dashdash "- -" >
+ <!-- Produce a notation for a double dash. Without this, TeX produces an en-hyphen. -->
+ <!ENTITY doof2d "<command>Doof2d</command>" >
+ <!-- Produce a notation for the Doof2d program. -->
+ <!ENTITY make "<application class='software'>Make</application>">
+ <!-- Produce a notation for the GNU Make program. -->
+ <!ENTITY mm "<application class='software'>MM</application>">
+ <!-- Produce a notation for the MM Library. -->
+ <!ENTITY mpi "<application class='software'>MPI</application>">
+ <!-- Produce a notation for the MPI package. -->
+ <!ENTITY pdt "<application class='software'>PDToolkit</application>">
+ <!-- Produce a notation for the PDT software package. -->
+ <!ENTITY pete "<application class='software'>PETE</application>">
+ <!-- Produce a notation for the PETE library. -->
+ <!ENTITY pooma "<application class='software'>POOMA</application>">
+ <!-- Produce a notation for Pooma software. -->
+ <!ENTITY poomaToolkit "<application class='software'>POOMA Toolkit</application>">
+ <!-- Produce a notation for the Pooma toolkit. -->
+ <!ENTITY purify "<application class='software'>Purify</application>">
+ <!-- Produce a notation for the Purify library. -->
+ <!ENTITY smarts "<application class='software'>Smarts</application>">
+ <!-- Produce a notation for the Smarts software package. -->
+ <!-- Modify this after capitalization is decided. -->
+ <!ENTITY stl "<application class='software'>STL</application>">
+ <!-- Produce a notation for the C++ Standard Template Library software package. -->
+ <!ENTITY tau "<application class='software'>Tau</application>">
+ <!-- Produce a notation for the Tau software package. -->
+
+ <!-- Type Entity Declarations -->
+
+ <!ENTITY array "<type>Array</type>">
+ <!-- The "Array" type. -->
+ <!ENTITY benchmark "<type>Benchmark</type>">
+ <!-- The "Benchmark" type. -->
+ <!ENTITY brick "<type>Brick</type>">
+ <!-- The "Brick" engine type. -->
+ <!ENTITY compressiblebrick "<type>CompressibleBrick</type>">
+ <!-- The "CompressibleBrick" engine type. -->
+ <!ENTITY distributedtag "<type>DistributedTag</type>">
+ <!-- The DistributedTag Layout type. -->
+ <!ENTITY domain "<type>Domain</type>">
+ <!-- The "Domain" type. -->
+ <!ENTITY double "<type>double</type>">
+ <!-- The C "double" type. -->
+ <!ENTITY dynamicarray "<type>DynamicArray</type>">
+ <!-- The "DynamicArray" type. -->
+ <!ENTITY engine "<type>Engine</type>">
+ <!-- The "Engine" type. -->
+ <!ENTITY field "<type>Field</type>">
+ <!-- The "Field" type. -->
+ <!ENTITY inform "<type>Inform</type>">
+ <!-- The "Inform" output type. -->
+ <!ENTITY interval "<type>Interval</type>">
+ <!-- The "Interval" type. -->
+ <!ENTITY layout "<type>Layout</type>">
+ <!-- The "Layout" type without template parameters. -->
+ <!ENTITY leaffunctor "<type>LeafFunctor</type>">
+ <!-- The "LeafFunctor" type. -->
+ <!ENTITY matrix "<type>TinyMatrix</type>">
+ <!-- The Pooma matrix type. -->
+ <!ENTITY multipatch "<type>MultiPatch</type>">
+ <!-- The "MultiPatch" engine without template parameters. -->
+ <!ENTITY replicatedtag "<type>ReplicatedTag</type>">
+ <!-- The ReplicatedTag Layout type. -->
+ <!ENTITY stencil "<type>Stencil</type>">
+ <!-- The "Stencil" type. -->
+ <!ENTITY tensor "<type>Tensor</type>">
+ <!-- The Pooma tensor type. -->
+ <!ENTITY vector "<type>Vector</type>">
+ <!-- The "Vector" type. -->
+
+ <!-- Mathematical Entity Declarations -->
+
+ <!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 multi-dimensional space -->
+
+ <!-- System and Operating System Entity Declarations -->
+ <!ENTITY gcc "<application>g++</application>">
+ <!-- The GNU Compiler Collection C++ compiler. -->
+ <!ENTITY kcc "<application>KCC</application>">
+ <!-- The KAI C++ compiler. -->
+ <!ENTITY linux "<application>Linux</application>">
+ <!-- The Linux operating system. -->
+
+ <!-- &pooma; URLs and Files -->
+
+ <!ENTITY poomaDownloadPage '<ulink url="http://pooma.codesourcery.com/pooma/download">http://pooma.codesourcery.com/pooma/download</ulink>'>
+ <!-- The WWW page supporting downloading the &pooma; source code. -->
+ <!-- UPDATE this URL. -->
+ <!ENTITY poomaHomePage '<ulink url="http://www.pooma.com/">http://www.pooma.com/</ulink>'>
+ <!-- The canonical Pooma home page. -->
+ <!-- UPDATE this filename. -->
+ <!ENTITY poomaSource "pooma-2.3.0">
+ <!-- The Pooma source code directory. -->
+ <!ENTITY poomaSourceFile "&poomaSource;.tgz">
+ <!-- The Pooma source code archive. -->
+ <!ENTITY poomaExampleDirectory "examples/Manual">
+ <!-- The directory holding this manual's example codes. -->
+
+ <!-- Spelling and Formatting Decisions -->
+ <!ENTITY author "author">
+ <!-- A word describing an author xor authors. -->
+ <!-- spelling: dependence, not dependency -->
+ <!-- spelling: element-wise, not elementwise -->
+ <!-- phrase: function object, not functor -->
+ <!-- spelling: multidimensional, not multi-dimensional -->
+ <!-- spelling: multiprocessor, not multi-processor -->
+ <!-- spelling: nonzero, not non-zero -->
+
+ <!-- External File Entities -->
+ <!ENTITY doof2d-c-element SYSTEM "./programs/Doof2d-C-element-annotated.cpp">
+ <!-- hand-coded Doof2d implementation -->
+ <!ENTITY doof2d-array-element SYSTEM "./programs/Doof2d-Array-element-annotated.cpp">
+ <!-- Array element-wise Doof2d implementation -->
+ <!ENTITY doof2d-array-parallel SYSTEM "./programs/Doof2d-Array-parallel-annotated.cpp">
+ <!-- Array data-parallel Doof2d implementation -->
+ <!ENTITY doof2d-array-stencil SYSTEM "./programs/Doof2d-Array-stencil-annotated.cpp">
+ <!-- Array stencil Doof2d implementation -->
+ <!ENTITY doof2d-array-distributed SYSTEM "./programs/Doof2d-Array-distributed-annotated.cpp">
+ <!-- distributed Array stencil Doof2d implementation -->
+ <!ENTITY doof2d-field-parallel SYSTEM "./programs/Doof2d-Field-parallel-annotated.cpp">
+ <!-- Field data-parallel Doof2d implementation -->
+ <!ENTITY doof2d-field-distributed SYSTEM "./programs/Doof2d-Field-distributed-annotated.cpp">
+ <!-- Field data-parallel distributed Doof2d implementation -->
+ <!ENTITY glossary-chapter SYSTEM "glossary.xml">
+ <!-- glossary -->
+ <!ENTITY tutorial-chapter SYSTEM "tutorial.xml">
+ <!-- Doof2d tutorial programs chapter -->
+ ]>
+
+ <book>
+ <bookinfo>
+ <title>&pooma;</title>
+ <subtitle>A &cc; Toolkit for High-Performance Parallel Scientific Computing</subtitle>
+ <author><firstname>Jeffrey</firstname><othername
+ role='mi'>D.</othername><surname>Oldham</surname>
+ <affiliation>
+ <orgname>CodeSourcery, LLC</orgname>
+ </affiliation>
+ </author>
+ <copyright><year>2001</year><holder>CodeSourcery, LLC (<ulink url="http://www.codesourcery.com"></ulink>)</holder></copyright>
+ <contractsponsor>Los Alamos National Laboratory<ulink url="http://www.lanl.gov"></ulink></contractsponsor>
+ <legalnotice>
+ <!-- FIXME: What is the correct legal notice? -->
+ <para>All rights reserved. This document may not be redistributed in any form without the express permission of the author.</para>
+ </legalnotice>
+ <revhistory>
+ <revision>
+ <revnumber>0.01</revnumber>
+ <date>2001 Nov 26</date>
+ <authorinitials>jdo</authorinitials>
+ <revremark>first draft</revremark>
+ </revision>
+ </revhistory>
+ </bookinfo>
+
+ <!-- FINISH: May we have a short table of contents followed by a -->
+ <!-- complete table of contents? -->
+
+ <preface id="preface">
+ <title>Preface</title>
+
+ <para>FINISH: Describe the target audience for &pooma; programs and
+ for this manual: &cc; programmers writing scientific code, possibly
+ parallel execution.</para>
+
+ <para>Assume familiarity with &cc; template programming and the
+ standard template library. FIXME: Remove this index
+ entry.<indexterm id="oldham"><primary>Oldham,
+ Jeffrey D.</primary></indexterm></para>
+
+ <section id="preface-notation">
+ <title>Notation</title>
+
+ <para>UNFINISHED</para>
+ </section>
+
+
+ <section id="preface-reading_book:">
+ <title>How to Read This &Book;</title>
+
+ <para>FINISH: Write this section in a style similar to Lamport's
+ LaTeX section 1.2. FINISH: Fix the book title and the section
+ number.</para>
+ </section>
+
+
+ <section id="preface-downloading">
+ <title>Obtaining &pooma; and Sample Programs</title>
+
+ <para>Available for free from what WWW site? Include what portions
+ of <filename class="libraryfile">LICENSE</filename>? Be sure to
+ include CVS instructions as well.</para>
+
+ <para>Which additional packages are necessary and when?</para>
+
+ </section>
+
+
+ <section id="preface-using_modifying">
+ <title>Using and Modifying &pooma;</title>
+
+ <para>&pooma; is available under open source license. It can be
+ used and modified by anyone, anywhere. Can it be sold? Include
+ <filename class="libraryfile">LICENSE</filename>.</para>
+
+ <para>QUESTION: How do developers contribute code?</para>
+
+ </section>
+
+
+ <section id="preface-acknowledgements">
+ <title>Acknowledgements</title>
+
+ <para>Mark Mitchell, Stephen Smith</para>
+ </section>
+
+ </preface>
+
+
+ <part id="programming">
+ <title>Programming with &pooma;</title>
+
+ <chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>QUESTION: Add a partintro to the part above?</para>
+
+ <para>&pooma; abbreviates <quote>Parallel Object-Oriented Methods
+ and Application</quote>.</para>
+
+ <para>This document is an introduction to &pooma; v2.1, a &cc;
+ toolkit for high-performance scientific computation. &pooma;
+ runs efficiently on single-processor desktop machines,
+ shared-memory multiprocessors, and parallel supercomputers
+ containing dozens or hundreds of processors. What's more, by making
+ extensive use of the advanced features of the ANSI/ISO &cc;
+ standard—particularly templates—&pooma; presents a
+ compact, easy-to-read interface to its users.</para>
+
+ <para>From Section of
+ <filename>papers/iscope98.pdf</filename>:</para>
+
+ <para>Scientific software developers have struggled with the need
+ to express mathematical abstractions in an elegant and maintainable
+ way without sacrificing performance. The &pooma; (Parallel
+ Object-Oriented Methods and Applications) framework, written in
+ <acronym>ANSI</acronym>/<acronym>ISO</acronym> &cc;, has
+ demonstrated both high expressiveness and high performance for
+ large-scale scientific applications on platforms ranging from
+ workstations to massively parallel supercomputers. &pooma; provides
+ high-level abstractions for multidimensional arrays, physical
+ meshes, mathematical fields, and sets of particles. &pooma; also
+ exploits techniques such as expression templates to optimize serial
+ performance while encapsulating the details of parallel
+ communication and supporting block-based data compression.
+ Consequently, scientists can quickly assemble parallel simulation
+ codes by focusing directly on the physical abstractions relevant to
+ the system under study and not the technical difficulties of
+ parallel communication and machine-specific optimization.</para>
+
+ <para>ADD: diagram of science and &pooma;. See the diagram that
+ Mark and I wrote.</para>
+
+ <para>Mention efficient evaluation of &pooma; expressions. See
+ <filename>pooma-publications/iscope98.pdf</filename>,
+ Section 4.</para>
+
+ <section id="introduction-pooma_evolution">
+ <title>Evolution of &pooma;</title>
+
+ <para>QUESTION: Is this interesting? Even if it is, it should be
+ short.</para>
+
+ <para>The file <filename>papers/SCPaper-95.html</filename>
+ describes ?&pooma;1? and its abstraction layers.</para>
+
+ <para>The "Introduction" of
+ <filename>papers/Siam0098.ps</filename> describes the DoE's
+ funding motivation for &pooma;: Accelerated Strategic Computing
+ Initiative (ASCI) and Science-based Stockpile Stewardship (SBSS),
+ pp. 1–2.</para>
+
+ <para>See list of developers on p. 1 of
+ <filename>papers/pooma.ps</filename>.</para>
+
+ <para>See list of developers on p. 1 of
+ <filename>papers/pooma.ps</filename>. See history and motivation
+ on p. 3 of <filename>papers/pooma.ps</filename>.</para>
+
+ <para>Use <filename class="libraryfile">README</filename> for
+ information.</para>
+
+ <blockquote>
+ <attribution><filename
+ class="libraryfile">introduction.html</filename></attribution>
+
+ <para>&pooma; was designed and implemented by scientists working
+ at the Los Alamos National Laboratory's Advanced Computing
+ Laboratory. Between them, these scientists have written and tuned
+ large applications on almost every commercial and experimental
+ supercomputer built in the last two decades. As the technology
+ used in those machines migrates down into departmental computing
+ servers and desktop multiprocessors, &pooma; is a vehicle for its
+ designers' experience to migrate as well. In particular,
+ &pooma;'s authors understand how to get good performance out of
+ modern architectures, with their many processors and multi-level
+ memory hierarchies, and how to handle the subtly complex problems
+ that arise in real-world applications.</para>
+ </blockquote>
+
+ </section>
+
+ </chapter>
+
+ &tutorial-chapter;
+
+
+ <chapter id="concepts">
+ <title>Overview of &pooma; Concepts</title>
+
+ <para>FIXME: How does multi-threaded computation fit into the
+ model?</para>
+
+ <para>In the previous chapter, we presented several different
+ implementations of the &doof2d; simulation program. The
+ implementations illustrate the various containers, computation
+ syntaxes, 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>
+ <entry>Container</entry>
+ <entry>Computation Syntax</entry>
+ <entry>Computation Environment</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>&array;</entry>
+ <entry>element-wise</entry>
+ <entry>sequential</entry>
+ </row>
+ <row>
+ <entry>&dynamicarray;</entry>
+ <entry>data-parallel</entry>
+ <entry>distributed</entry>
+ </row>
+ <row>
+ <entry>&field;</entry>
+ <entry>stencil-based</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>&tensor;</entry>
+ <entry>relational</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>&matrix;</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>&vector;</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ </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 syntax</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 syntax, 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 syntaxes 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">
+ <title>&pooma; Container Summary</title>
+ <tgroup cols="2" align="left">
+ <tbody>
+ <row>
+ <entry><glossterm
+ linkend="glossary-array">&array;</glossterm></entry>
+ <entry>container mapping indices to values and that may be
+ used in expressions</entry>
+ </row>
+ <row>
+ <entry><glossterm
+ linkend="glossary-dynamicarray">&dynamicarray;</glossterm></entry>
+ <entry>one-dimensional &array; whose <glossterm
+ linkend="glossary-domain">domain</glossterm> can be dynamically
+ resized</entry>
+ </row>
+ <row>
+ <entry><glossterm linkend="glossary-field">&field;</glossterm></entry>
+ <entry>container mapping indices to one or more values and
+ residing in multi-dimensional space</entry>
+ </row>
+ <row>
+ <entry><glossterm
+ linkend="glossary-tensor">&tensor;</glossterm></entry>
+ <entry>multi-dimensional mathematical tensor</entry>
+ </row>
+ <row>
+ <entry><glossterm
+ linkend="glossary-matrix">&matrix;</glossterm></entry>
+ <entry>two-dimensional mathematical matrix</entry>
+ </row>
+ <row>
+ <entry><glossterm
+ linkend="glossary-vector">&vector;</glossterm></entry>
+ <entry>multi-dimensional mathematical vector</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!-- 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. -->
+
+ <para>A &pooma; <glossterm
+ linkend="glossary-dynamicarray">&dynamicarray;</glossterm> extends
+ &array; capabilities to support a dynamically-changing domain but
+ is restricted to only one dimension. When the &dynamicarray; is
+ resized, its values are preserved.</para>
+
+ <!-- FIXME: Want firstterm around field. -->
+
+ <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. -->
+
+ <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>
+
+ <!-- FIXME: Want firstterm around matrix. -->
+
+ <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. -->
+
+ <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>
+
+ <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>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="concepts-containers-choice_table">
+ <title>Choosing a &pooma; Container</title>
+ <tgroup cols="2" align="left">
+ <tbody>
+ <row>
+ <entry>If modeling mathematical entries,</entry>
+ <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>
+ <row>
+ <entry>If there are multiple values per index,</entry>
+ <entry>use a &field;.</entry>
+ </row>
+ <row>
+ <entry>If there are multiple materials participating in the same computation,</entry>
+ <entry>use a &field;.</entry>
+ </row>
+ <row>
+ <entry>If the domain's size dynamically changes and is one-dimensional,</entry>
+ <entry>use a &dynamicarray;.</entry>
+ </row>
+ <row>
+ <entry>Otherwise</entry>
+ <entry>use an &array;.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section><!-- choosing among containers -->
+
+
+ <section id="concepts-containers-sequential_declarations">
+ <title>Declaring Sequential Containers</title>
+
+ <figure float="1" id="concepts-sequential_containers-declarations-dependences">
+ <title>Concepts For Declaring Containers</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/concepts.111" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>concepts involved in declaring containers</phrase>
+ </textobject>
+ </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>
+ <imagedata fileref="figures/concepts.101" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>maps from indices to values</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <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
+ geometric 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 geometric
+ 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>
+
+ <para>A mesh's <glossterm
+ linkend="glossary-cell_size"><firstterm>cell
+ size</firstterm></glossterm> specifies the spatial dimensions of
+ a &field; <link linkend="glossary-cell">cell</link>, e.g., its
+ 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
+ section, we concentrate on the concepts necessary to declare a
+ distributed container.</para>
+
+ <para>As we noted in <xref
+ linkend="tutorial-array_distributed"></xref>, a &pooma;
+ programmer must specify how each container's domain should be
+ distributed among the available processors and memory spaces.
+ Using this information, the Toolkit automatically distributes the
+ data among the available processors and handles any required
+ communication among them. The three concepts necessary for
+ declaring distributed containers are a partition, a guard layer,
+ and a context mapper tag.</para>
+
+ <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
+ mapper</firstterm></glossterm> indicates how a container's
+ patches are mapped to processors and shared memory. For example,
+ the &distributedtag; indicates that the patches should be
+ distributed among the processors so each patch occurs once in the
+ entire computation. The &replicatedtag; indicates that the
+ patches should be replicated among the processors so each
+ processing unit has its own copy of all the patches. While it
+ could be wasteful to have different processors perform the same
+ computation, replicating a container can reduce possibly more
+ expensive communication costs.</para>
+ </section>
+
+
+ <section>
+ <title>????Computation Syntax????</title>
+
+ <para>UNFINISHED</para>
+ </section>
+
+
+ <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. 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: the
+ programmer must declare how container domains will be
+ distributed, &pooma; must be configured to use a communications
+ library, and the &pooma; executable must be run using the
+ library. All of these were illustrated 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. <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>. More
+ detailed instructions how to run distributed &pooma; executables
+ appear in <xref linkend="parallel"></xref>. Here we present
+ three concepts for distributed computation: context, layout, and
+ a communication library.
+
+ 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>
+
+ <para>
+ HERE</para>
+
+ <!-- HERE -->
+ </section>
+
+ </section>
+
+ <section>
+ <title>Extraneous Material</title>
+
+ <para>Describe the software application layers similar to
+ <filename>papers/SCPaper-95.html</filename> and "Short Tour of
+ &pooma;" in <filename>papers/SiamOO98_paper.ps</filename>.
+ Section 2.2, "Why a Framework?," of
+ <filename>papers/pooma.ps</filename> argues why a layered approach
+ eases use. Section 3.1, "Framework Layer Description,"
+ describes the five layers.</para>
+
+ <para>FINISH: Write short glossary entries for each of these.</para>
+
+ <para>FINISH: Look through the source code to ensure all main
+ concepts are listed.</para>
+
+ <para>Here are (preliminary) &pooma; equations:</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&pooma; <quote>Equations</quote></title>
+
+ <tgroup cols="1" align="center">
+ <tbody>
+ <row>
+ <entry><para>field = data + materials + centering + layout + mesh</para></entry>
+ </row>
+ <row>
+ <entry><para>map from space to values</para></entry>
+ </row>
+ <row>
+ <entry><para>array = data + layout</para></entry>
+ </row>
+ <row>
+ <entry><para>map from indices to values</para></entry>
+ </row>
+ <row>
+ <entry><para>mesh = layout + origin + spacings</para></entry>
+ </row>
+ <row>
+ <entry><para>distribute domain through physical space</para></entry>
+ </row>
+ <row>
+ <entry><para>layout = domain + partition + context_mapper_tag (distributed/replicated)</para></entry>
+ </row>
+ <row>
+ <entry><para>distribute domain's blocks among processors/contexts</para></entry>
+ </row>
+ <row>
+ <entry><para>partition = blocks + guard layers</para></entry>
+ </row>
+ <row>
+ <entry><para>split domain into blocks</para></entry>
+ </row>
+ <row>
+ <entry><para>domain = newDomain</para></entry>
+ </row>
+ <row>
+ <entry><para>space of permissible indices</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ <para>FINISH: Following is a first try at describing the &pooma;
+ abstraction layers. See also paper illustration.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&pooma; Abstraction Layers</title>
+
+ <tgroup cols="1" align="center">
+ <tbody>
+ <row>
+ <entry><para>application program</para></entry>
+ </row>
+ <row>
+ <entry><para>&array; &field; (should have
+ <type>FieldEngine</type> under it)</para></entry>
+ </row>
+ <row>
+ <entry><para>&engine;</para></entry>
+ </row>
+ <row>
+ <entry><para>evaluators</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>FINISH: How does parallel execution fit in?</para>
+
+ <para>FINISH: Should we also name and describe each layer?</para>
+ </section>
+
+
+ <section id="concepts-data_parallel">
+ <title>Data-Parallel Statements</title>
+
+ <para>Can we use "An Overview of &pete;" from
+ <filename>papers/PETE_DDJ/ddj_article.html</filename> or is this
+ too low-level?</para>
+
+ <para>Section 3.2.1 of <filename>papers/pooma.ps</filename>
+ gives a simple example of data-parallel expression. It also has a
+ paragraph introducing data-parallel operations and selecting
+ subsets of domains. Section 3.4 describes the Chained
+ Expression Object (<acronym>CEO</acronym>), apparently a precursor
+ of &pete;. Regardless, it provides some motivation and
+ introductory material.</para>
+
+ <para>From Section 4 of
+ <filename>papers/SiamOO98_paper.ps</filename>:</para>
+
+ <para>This version of &pete; reduces compile time of user codes
+ and utilizes compile-time knowledge of expression &domain;s for
+ better optimization. For example, more efficient loops for
+ evaluating an expression can be generated if &pete; knows that the
+ &domain; has unit stride in memory.</para>
+
+ <para>Section 4, "Expressions and Evaluators", of
+ <filename>papers/iscope98.pdf</filename> has a good explanation of
+ &pooma; II's expression trees and expression engines.</para>
+
+ <para>COMMENT: <filename
+ class="libraryfile">background.html</filename> has some related
+ &pete; material.</para>
+ </section>
+
+ <section>
+ <title>Containers</title>
+
+ <section id="concepts-containers-array">
+ <title>&array;</title>
+
+ <blockquote>
+ <attribution>Section 4 "Future Improvements in
+ &pooma; II" of
+ <filename>papers/SiamOO98_paper.ps</filename></attribution>
+ <para>
+ An &array; can be thought of as a map from one &domain; to
+ another.… &array;s depend only on the interface of
+ &domain;s. Thus, a subset of view of an &array; can be
+ manipulated in all the same ways as the original &array;.
+ &array;s can perform indirect addressing because the output
+ &domain; one one &array; can be used as the input &domain; of
+ another &array;. &array;s also provide individual element
+ access.</para>
+ </blockquote>
+
+
+ <para>
+ (unformatted) From
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>:
+ The &pooma; &array; concept provides an example of how these
+ generic-programming features can lead to flexible and efficient
+ code. An Array maps a fairly arbitrary input domain to an
+ arbitrary range of outputs. When used by itself, an &array;
+ object <varname>A</varname> refers to all of the values in its
+ domain. Element-wise mathematical operations or functions can be
+ applied to an array using straightforward notation, like A + B
+ or sin(A). Expressions involving Array objects are themselves
+ Arrays. The operation A(d), where d is a domain object that
+ describes a subset of A's domain, creates a view of A that
+ refers to that subset of points. Like an array expression, a
+ view is also an Array. If d represents a single point in the
+ domain, this indexing operation returns a single value from the
+ range. Equivalently, one can index an N-dimensional Array by
+ 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
+ types. Both support the notion of views of a portion of the
+ array, known as array sections in F90. The &pooma; Array concept
+ supports more complex domains, including bounded, continuous
+ (floating-point) domains. Furthermore, Array indexing in &pooma;
+ is polymorphic; that is, the indexing operation X(i1,i2) can
+ perform the mapping from domain to range in a variety of ways,
+ depending on the particular type of the Array being
+ indexed.</para>
+
+ <para>Fortran arrays are dense and the elements are arranged
+ according to column-major conventions. Therefore, X(i1,i2)
+ refers to element number i1-1+(i2-1)*numberRowsInA. However, as
+ Fig. 1 shows, Fortran-style "Brick" storage is not the only
+ storage format of interest to scientific programmers. For
+ compatibility with C conventions, one might want to use an array
+ featuring dense, row-major storage (a C-style Brick). To save
+ memory, it might be advantageous to use an array that only
+ stores a single value if all its element values are the
+ same. Other sparse storage schemes that only store certain
+ values may also be desirable. To exploit parallelism, it is
+ convenient for an array's storage to be broken up into patches,
+ which can be processed independently by different CPUs. Finally,
+ one can imagine an array with no data at all. For example, the
+ values can be computed from an expression involving other
+ arrays, or analytically from the indices.
+ </para>
+
+ <para>The &pooma; &array; Class Template</para>
+
+ <para>Next we describe &pooma;'s model of the Array concept, the
+ Array class template. The three most important requirements from
+ the point of view of overall design are: (1) arbitrary domain,
+ (2) arbitrary range, and (3) polymorphic indexing. These express
+ themselves in the template parameters for the &pooma; Array
+ class. The template
+ <programlisting>
+ template <int Dim, class T = double, class EngineTag = Brick>
+ class Array;
+ </programlisting>
+ is a specification for creating a set of classes all named
+ Array. The template parameters Dim, T, and EngineTag determine
+ the precise type of the Array. Dim represents the dimension of
+ the array's domain. T gives the type of array elements, thereby
+ defining the output range of the array. EngineTag specifies the
+ the manner of indexing and types of the indices.</para>
+
+ <para>End From
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
+
+ <para>Section 2, "Arrays and Engines," of
+ <filename>papers/iscope98.pdf</filename> describes both &array;s
+ and &engine;s. This may or may not duplicate the material in
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>.</para>
+
+ <section id="concepts-containers-array-views">
+ <title>Views of &array;s</title>
+
+ <para>Section 3, "Domains and Views," of
+ <filename>papers/iscope98.pdf</filename> motivates the need for
+ views:
+ <blockquote>
+ <para>One of the primary uses of domains is to specify
+ subsections of &array; objects. Subarrays are a common
+ feature of array classes; however, it is often difficult to
+ make such subarrays behave like first-class objects. The
+ &pooma; II engine concept provides a clean solution to
+ this problem: subsetting an &array; with a domain object
+ creates a new &array; that has a view engine.</para>
+ </blockquote>
+ </para>
+ </section>
+ </section>
+
+ <section id="concepts-containers-field">
+ <title>&field;</title>
+
+ <para>QUESTION: Do we include boundary conditions here?
+
+ FINISH: Do we have an example that shows something not possible
+ with &array;?</para>
+
+ <para>Describe and illustrate multi-material and
+ multivalue?</para>
+
+ <para>ADD: description of meshes and guard layers.</para>
+
+ </section>
+
+
+ </section>
+
+ <section id="concepts-engines">
+ <title>Engines</title>
+
+ <para>(unformatted) From
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
+
+ <para>The Engine Concept</para>
+
+ <para>To implement polymorphic indexing, the Array class defers
+ data storage and data lookup to an engine object. The requirements
+ that the Array template places on its engine provide the
+ definition for the Engine concept. We'll describe these by
+ examining a simplified version of the Array template, shown in
+ Fig. 2.</para>
+
+ <para>First, the Array class determines and exports (makes
+ Engine_t part of Array's public interface) the type of the engine
+ class that it will use:
+ <programlisting>
+ typedef Engine<Dim, T, EngineTag> Engine_t;
+ </programlisting>
+ This statement declares Engine_t to be an alias for the type
+ Engine<Dim,T,EngineTag>. This is the first requirement
+ placed on engine classes: they must be specializations of a
+ general Engine template whose template parameters are identical to
+ those of Array. Next, the Array template determines the type of
+ scalar arguments (indices) to be used in operator(), the function
+ that implements &pooma;'s Fortran-style indexing syntax X(i1,i2):
+ <programlisting>
+ typedef typename Engine_t::Index_t Index_t;
+ </programlisting>
+ This statement defines another type alias:
+ Array<Dim,T,EngineTag>::Index_t is simply an alias for
+ Engine_t::Index_t. Engine_t::Index_t is a qualified name, which
+ means that the type Index_t is found in the class Engine_t. This
+ is the second requirement for the Engine concept: the class
+ Engine_t must define a public type called Index_t. This line will
+ not compile if that definition is not supplied. This indirection
+ is one of the ways that &pooma; supports polymorphic indexing. If
+ the Engine works with a discrete integer domain, it defines its
+ Index_t to be an integral type. If the Engine works in a
+ continuous domain, it defines its Index_t to be a floating-point
+ type.</para>
+
+ <para>The data lookup is performed in the operator() function. We
+ see that Array simply passes the indices on to its engine
+ object. Thus, we have the third requirement for the Engine
+ concept: it must provide a version of operator() that takes Dim
+ values of type Index_t.</para>
+
+ <para>Simply passing the indices on to the engine object may seem
+ odd. After all, engine(i,j) looks like we're just indexing another
+ array. There are several advantages to this extra level of
+ indirection. The Array class is as faithful a model of the Array
+ concept as possible, while the Engine class is a low-level
+ interface to a user-defined data source. As a result, Array has a
+ wide variety of constructors for user convenience, while engines
+ have but a few. Array supports a wide variety of overloaded
+ operator() functions for view creation and indexing. Engines
+ support indexing only. Array does not have direct access to the
+ data, which is managed by the engine object. Finally, Array has a
+ wide variety of overloaded mathematical operators and functions,
+ and works with the Portable Expression Template Engine (PETE) [4]
+ to provide efficient evaluation of Array expressions. Engines have
+ no such support. In general, Array is much more complex and
+ feature-laden than Engine. This is the prime advantage of the
+ separation of interface and implementation: Array only has to be
+ implemented once by the &pooma; developers. Engines are simple
+ enough to be written by users and plugged directly into the Array
+ framework.</para>
+
+ <para>Figure 3 illustrates the "Brick" specialization of the
+ Engine template, which implements Fortran-style lookup into a
+ block of memory. First, there is the general Engine template,
+ which is empty as there is no default behavior for an unknown
+ EngineTag. The general template is therefore not a model for the
+ Engine concept and Array classes attempting to use it will not
+ compile. Next, there is the definition of the Brick class, a
+ policy tag whose sole purpose is to select a particular
+ specialization of the Engine template. Finally, there is the
+ partial specialization of the Engine template. Examining its body,
+ we see the required Index_t typedef and the required operator(),
+ which follows the Fortran prescription for generating an offset
+ into the data block based on the row, column, and the number of
+ rows. All of the requirements are met, so the Brick-Engine class
+ is a model of the Engine concept.</para>
+
+ <para>End From
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
+
+ <para>(unformatted) From
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
+
+ <para>Compile-time Versus Run-Time Polymorphism</para>
+
+ <para>Encapsulating the indexing in an Engine class has important
+ advantages, both in terms of flexibility and efficiency. To
+ illustrate this point, we introduce the PolarGaussian-Engine
+ specialization in Fig. 4. This is an analytic engine that
+ calculates its values directly from its inputs. Unlike the
+ Brick-Engine, this engine is "indexed" with data of the same type
+ as its output: it maps a set of T's to a single T. Therefore, the
+ Index_t typedef selects T as the index type, as opposed to the int
+ in the Brick-Engine specialization. The operator() function also
+ differs in that it computes the return value according to an
+ analytic formula.</para>
+
+ <para>Both Engine<Dim,T,Brick> and
+ Engine<Dim,T,PolarGaussian> can be plugged in to an Array by
+ simply varying the Array's EngineTag. This is possible despite the
+ fact that the two classes exhibit dramatically different behavior
+ because they are both models of the Engine concept.</para>
+
+ <para>Notice that we have achieved polymorphic indexing without
+ the use of inheritance or virtual functions. For instance,
+ consider the following code snippet:
+ <programlisting>
+ Array<2, double, Brick> a;
+ Array<2, double, PolarGaussian> b;
+
+ double x = a(2, 3); // x = a.engine.data[2 + 3 * a.engine.numRows];
+ double y = b(2.0, 3.0); // y = exp(-(2.0*2.0+3.0*3.0) / b.engine.delta);
+ </programlisting>
+ The data lookup functions for the two Arrays perform completely
+ different operations. Since this is accomplished using static
+ types, it is known as compile-time polymorphism. Moreover,
+ everything is known at compile time, so the functions are fully
+ inlined and optimized, thereby yielding code equivalent to that
+ shown in the comments above.</para>
+
+ <para>The flexibility and efficiency of compile-time polymorphism
+ cannot be duplicated with a run-time implementation. To illustrate
+ this point, in Fig. 5, we re-implement our Array concept using the
+ classic Envelope-Letter pattern [5], with the array class,
+ RTArray, being the envelope and the run-time-engine, RTEngine,
+ being the letter. RTArray defers data lookup to the engine object
+ by invoking the engine's functions through a pointer to the
+ RTEngine base class. Figure 6 illustrates the RTEngine base class
+ and Fig. 7 illustrates two descendants: RTBrick and
+ RTPolarGaussian.</para>
+
+ <para>The run-time implementation provides the same basic
+ functionality as the compile-time implementation, but it is not as
+ flexible or as efficient. It lacks flexibility in that the return
+ type of the indexing operation must be specified in the RTEngine
+ base class and in the RTArray class. Thus, in Figs. 5 and 6,we see
+ versions of RTArray::operator() and RTEngine::index functions that
+ take both int's and T's. If the programmer wants to add another
+ index-type option, these classes must be modified. This is a
+ violation of the open-closed principle proposed by Meyer
+ [6]. Also, since RTEngine descendants will usually only implement
+ one version of index, we cannot make RTEngine an abstract base
+ class. Instead, we have the default versions of index throw an
+ exception. Thus, compile-time error checking is
+ weakened. Furthermore, since indexing is done via a virtual
+ function call, it will almost never be inlined, which is not
+ acceptable in most scientific applications.</para>
+
+ <para>There are advantages to the Envelope-Letter approach. First,
+ all RTArray objects have the same type, allowing them to be stored
+ in homogeneous collections. This can simplify the design of some
+ applications. Second, RTArray objects can change their engines at
+ runtime, and thus effectively change their types on the fly??this
+ is the primary reason for using the Envelope-Letter idiom, and can
+ be very important in some applications.</para>
+
+ <para>For most scientific applications, however, these issues are
+ minor, and maximum performance for array indexing is of paramount
+ importance. Our compile-time approach achieves this performance
+ while providing the desired polymorphic indexing.</para>
+
+ <para>From Section 4 of
+ <filename>papers/SiamOO98_paper.ps</filename>:</para>
+
+ <para>The &array; class is templated on an &engine; type that
+ handles the actual implementation of the mapping from input to
+ output. Thus, the &array; interface features are completely
+ separate from the implementation, which could be a single &c;
+ array, a function of some kind or some other mechanism. This
+ flexibility allows an expression itself to be viewed through the
+ &array; interface. Thus, one can write something like
+ <programlisting>
+ foo(A*B+C);
+ </programlisting> where <varname>A</varname>, <varname>B</varname> and
+ <varname>C</varname> are &array;s and <function>foo</function> is
+ a function taking an &array; as an argument. The expression
+ <statement><varname>A</varname>*<varname>B</varname>+<varname>C</varname></statement>
+ will only be evaluated by the expression engine as needed by
+ <function>foo</function>.</para>
+
+ <para>In fact, one can even write &engine;s which are wrappers
+ around external data structures created in non-&pooma; codes and
+ know to manipulate these structures. Once this is done, the
+ external entities have access to the entire &array; interface and
+ can utilize all of the powerful features of
+ &pooma; II.</para>
+
+ <para>Section 2, "Arrays and Engines," of
+ <filename>papers/iscope98.pdf</filename> describes both &array;s
+ and &engine;s. This may or may not duplicate the material in
+ <filename>papers/GenericProgramming_CSE/dubois.html</filename>.</para>
+
+ <para>Section 4, "Expressions and Evaluators", of
+ <filename>papers/iscope98.pdf</filename> has a good explanation of
+ &pooma; II's expression trees and expression engines.</para>
+
+ <variablelist>
+ <varlistentry><term><type>MultiPatch</type> Engine</term>
+ <listitem><para>From <filename
+ class="libraryfile">README</filename>: To actually use multiple
+ contexts effectively, you need to use the MultiPatch engine with
+ patch engines that are Remote engines. Then the data will be
+ distributed across multiple contexts instead of being copied on
+ every context. See the files in example/Doof2d for a simple
+ example that creates a MultiPatch array that can be distributed
+ across multiple contexts and performs a stencil computation on
+ that array.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+
+ <section id="concepts-relations">
+ <title>Relations</title>
+
+ <para>UNFINISHED</para>
+ </section>
+
+
+ <section id="concepts-stencils">
+ <title>Stencils</title>
+
+ <para>Section 3.5.4, "Stencil Objects," of
+ <filename>papers/pooma.ps</filename> provides a few uses of
+ stencils.</para>
+
+ <para>Section 5, "Performance," of
+ <filename>papers/iscope98.pdf</filename> motivates and explains
+ stencils.</para>
+ </section>
+
+
+ <section id="concepts-contexts">
+ <title>Contexts</title>
+
+ <blockquote>
+ <attribution><filename
+ class="libraryfile">background.html</filename></attribution>
+ <para>In order to be able to cope with the variations in machine
+ architecture noted above, &pooma;'s distributed execution model
+ is defined in terms of one or more contexts, each of which may
+ host one or more threads. A context is a distinct region of
+ memory in some computer. The threads associated with the context
+ can access data in that memory region and can run on the
+ processors associated with that context. Threads running in
+ different contexts cannot access memory in other contexts.</para>
+
+ <para>A single context may include several physical processors,
+ or just one. Conversely, different contexts do not have to be on
+ separate computers—for example, a 32-node SMP computer could
+ have up to 32 separate contexts. This release of &pooma; only
+ supports a single context for each application, but can use
+ multiple threads in the context on supported platforms. Support
+ for multiple contexts will be added in an upcoming
+ release.</para>
+ </blockquote>
+ </section>
+
+ </chapter>
+
+
+ <chapter id="sequential">
+ <title>Writing Sequential Programs</title>
+
+ <para>&pooma; can reorder computations to permit more efficient
+ computation. When running a sequential program, reordering may
+ permit omission of unneeded computations. For example, if only
+ values from a particular field are printed, only computations
+ involving the field and containers dependent on it need to occur.
+ When running a distributed program, reordering may permit
+ computation and communication among processors to overlap. &pooma;
+ automatically tracks dependences between data-parallel expressions,
+ ensuring correct ordering. It does not track statements accessing
+ particular &array; and &field; values so the programmer must
+ precede these statements with calls to
+ <function>Pooma::blockAndEvaluate()</function>. Each call forces
+ the executable to wait until all computation has completed. Thus,
+ the desired values are known to be available. In practice, some
+ calls to <function>Pooma::blockAndEvaluate</function> may not be
+ necessary, but omitting them requires knowledge of &pooma;'s
+ dependence computations, so the &author; recommends calling
+ <function>Pooma::blockAndEvaluate</function> before each access to
+ a particular value in an &array; or &field;. Omitting a necessary
+ call may lead to a race condition. See <xref
+ linkend="debugging_profiling-missing_blockandevaluate"></xref> for
+ instructions how to diagnose and eliminate these race conditions.</para>
+
+ <para>Section 3, "Domains and Views," of
+ <filename>papers/iscope98.pdf</filename> describes five types of
+ domains.</para>
+
+ <para>UNFINISHED</para>
+
+ <section id="sequential-benchmarks">
+ <title>&benchmark; Programs</title>
+
+ <para>Define a &benchmark; program vs. an example or an
+ executable. Provide a short overview of how to run these
+ programs. Provide an overview of how to write these programs.
+ See <filename
+ class="headerfile">src/Utilities/Benchmark.h</filename>.</para>
+ </section>
+
+
+ <section id="sequential-inform">
+ <title>Using <type>Inform</type>s for Output</title>
+
+ <para>UNFINISHED</para>
+ </section>
+
+
+ <section>
+ <title>Miscellaneous</title>
+
+ <para>Section 3, "Domains and Views," of
+ <filename>papers/iscope98.pdf</filename> describes five types of
+ domains.</para>
+ </section>
+ </chapter>
+
+
+ <chapter id="parallel">
+ <title>Writing Distributed Programs</title>
+
+ <para>Discuss the distributed model and guard cells. See <filename
+ class="libraryfile">docs/parallelism.html</filename>.</para>
+
+ <para>Does any of the parallel implementation described in
+ <filename>papers/SCPaper-95.html</filename> still apply?</para>
+
+ <para>?Tuning program for maximize parallel performance?</para>
+
+ <para>external references to &mpi; and threads</para>
+
+ <para>QUESTION: Are there interesting, short parallel programs in
+ any &mpi; book that we can convert to &pooma;?</para>
+
+ <section>
+ <title>Layouts</title>
+
+ <para>An out-of-date description can be found in Section 3.3,
+ especially 3.3.2, of <filename>papers/pooma.ps</filename>
+ describes the global/local interactions and parallel abstraction
+ layers.</para>
+ </section>
+
+ <section>
+ <title>Parallel Communication</title>
+
+ <para>An out-of-date description can be found in
+ Section 3.3.3 of <filename>papers/pooma.ps</filename></para>
+ </section>
+
+ <section>
+ <title>Using Threads</title>
+
+ <para>QUESTION: Where do threads fit into the manual? Do threads
+ even work?</para>
+
+ <para>From Section 4, of
+ <filename>papers/SiamOO98_paper.ps</filename></para>
+
+ <para>&pooma; II will make use of a new parallel run-time
+ system called &smarts; that is under development at the ACL.
+ &smarts; supports lightweight threads, so the evaluator will be
+ able to farm out data communication tasks and the evaluation of
+ subsets of an expression to multiple threads, thus increasing the
+ overlap of communication and computation. Threads will also be
+ available at the user level for situations in which a
+ task-parallel approach is deemed appropriate.</para>
+ </section>
+
+ </chapter>
+
+
+ <chapter id="debugging_profiling">
+ <title>Debugging and Profiling &pooma; Programs</title>
+
+ <para>Consider &dashdash;pooma-debug <replaceable>number</replaceable>.
+ See also other &pooma; options in <filename
+ class="headerfile">src/Utilities/Options.h</filename>.</para>
+
+ <para>UNFINISHED</para>
+ <section id="debugging_profiling-missing_blockandevaluate">
+ <title>Finding Race Conditions From Missing
+ <function>blockAndEvaluate</function> Calls</title>
+
+ <para>&pooma; may reorder computations so calls to
+ <function>Pooma::blockAndEvaluate()</function> are necessary
+ before accessing particular &array; and &field; values.
+ Omission of necessary calls can lead to race conditions where
+ the ordering of reads and writes to particular values is
+ incorrect. To help diagnose if calls to
+ <function>Pooma::blockAndEvaluate</function> are missing, invoke
+ a &pooma; executable with the
+ <statement>&dashdash;pooma-blocking-expressions</statement> option.
+ This automatically causes
+ <function>Pooma::blockAndEvaluate</function> to be called after
+ each statement. Doing so ensures program correctness, but it
+ may increase running times, particularly if multiple processors
+ are used, because computation and communication may not overlap
+ as much as possible. Of course, program correctness is more
+ important than execution speed.</para>
+
+ <para>If using
+ <statement>&dashdash;pooma-blocking-expressions</statement> changes a
+ program's output, it is missing one or more calls to
+ <function>Pooma::blockAndEvaluate</function>. To narrow the
+ region with a missing call, surround the region in question with
+ calls to <statement>Pooma::blockingExpressions(true)</statement>
+ and <statement>Pooma::blockingExpressions(false)</statement>,
+ but do not use the
+ <statement>&dashdash;pooma-blocking-expressions</statement> option.
+ Within the region, <function>Pooma::blockAndEvaluate</function>
+ will be invoked after each statement. Repeatedly reducing the
+ region's size should reveal where calls are missing.</para>
+ </section>
+ </chapter>
+
+ </part>
+
+ <part id="reference">
+ <title>&pooma; Reference Manual</title>
+
+ <chapter id="tmp_ref">
+ <title>TMP: This Chapter Holds These Comments But Will Be Removed</title>
+
+ <para>For each template parameter need to describe the constraints
+ on it.</para>
+
+ <para>Remove this section when the following concerns have been
+ addressed.</para>
+
+ <para>Add a partintro explaining file suffixes such as <filename
+ class="headerfile">.h</filename>, <filename
+ class="libraryfile">.cpp</filename>, <filename
+ class="libraryfile">.cmpl.cpp</filename>, <filename
+ class="libraryfile">.mk</filename>, <filename
+ class="libraryfile">.conf</filename>. Should we also explain use
+ of <literal>inline</literal> even when necessary and the template
+ model, <!-- FIXME: s/literal/keyword/ --> e.g., including <filename
+ class="libraryfile">.cpp</filename> files.</para>
+
+ <para>QUESTION: What are the key concepts around which to organize
+ the manual?</para>
+
+ <para>QUESTION: What format should the manual use?</para>
+
+ <blockquote>
+ <attribution>Musser, Derge, and Sanai, §20.0.</attribution>
+ <para>It is important to state the requirements on the components
+ as generally as possible. For example, instead of saying
+ <quote>class <type>X</type> must define a member function
+ <function>operator++()</function>,</quote> we say <quote>for any
+ object <varname>x</varname> of type <type>X</type>,
+ <classname>++x</classname> is defined.</quote></para>
+ </blockquote>
+ </chapter>
+
+
+ <chapter id="class_structure_ref">
+ <title>A Typical &pooma; Class</title>
+
+ <variablelist>
+ <title>Class Member Notation</title>
+ <varlistentry>
+ <term><fieldsynopsis>
+ <varname>*_t</varname>
+ </fieldsynopsis>
+ </term>
+ <listitem>
+ <para>type within a class. QUESTION: What is the &cc; name for
+ this?</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><fieldsynopsis>
+ <varname>*_m</varname>
+ </fieldsynopsis>
+ </term>
+ <listitem>
+ <para>data member</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <title>&pooma; Class Vocabulary</title>
+ <varlistentry>
+ <term>component</term>
+ <listitem>
+ <para>one of several values packaged together. For example, a
+ three-dimensional vector has three components, i.e., three
+ values.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>element-wise</term>
+ <listitem>
+ <para>applied to each element in the group, e.g., an array</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reduction</term>
+ <listitem>
+ <para>repeated application of a binary operator to all elements,
+ yielding one value</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>tag</term>
+ <listitem>
+ <para>an enumerated value indicating inclusion in a particular
+ semantic class. The set of values need not be explicitly
+ declared.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </chapter>
+
+
+ <chapter id="installing_configuring_ref">
+ <title>Installing and Configuring &pooma;</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Installing &pooma;.</para>
+ </listitem>
+ <listitem>
+ <para>Requirements for configuration files.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Include descriptions of using &smarts;, &cheetah;, τ,
+ &pdt;.</para>
+
+ <para>QUESTION: Does it install on windows and on mac? If so, what
+ are the instructions? See also <filename
+ class="libraryfile">INSTALL.{mac,unix,windows}.</filename></para>
+
+ <para><filename class="libraryfile">README</filename> has some
+ information on &cheetah; and threads in the <quote>Message-Based
+ Parallelism</quote> section.</para>
+
+ <para>Which additional packages are necessary and when?</para>
+
+ <para>What configure options should we list? See <filename
+ class="libraryfile">configure</filename>. Be sure to list
+ debugging option and how its output relates to <filename
+ class="libraryfile">config/LINUXgcc.suite.mk</filename>.</para>
+
+ <para><filename class="directory">config/arch</filename> has files
+ for (OS, compiler) pairs. Explain how to modify a configuration
+ file. List requirements when making a new configuration file (low
+ priority).</para>
+
+ <para><filename
+ class="libraryfile">config/LINUXgcc.suite.mk</filename> has output
+ from <filename class="libraryfile">configure</filename>. Useful to
+ relate to configuration files and <filename
+ class="libraryfile">configure</filename>'s debugging output.</para>
+
+ </chapter>
+
+
+ <chapter id="compilation_ref">
+ <title>Compilation and &make; Files</title>
+
+ <para>We assume Gnu make. Do we know what assumptions are made?</para>
+
+ <para>How do all these files interact with each other? Ala a make
+ interpreter, give an example of which files are read and
+ when.</para>
+
+ <variablelist>
+ <varlistentry><term><filename
+ class="libraryfile">config/Shared/README.make</filename></term>
+ <listitem><para>This has short descriptions of many files,
+ especially in <filename
+ class="directory">config/Shared</filename>.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">makefile</filename></term>
+ <listitem><para>These appear throughout all directories. What are
+ the equivalences classes and what are their
+ parts?</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">include.mk</filename></term>
+ <listitem><para>What does this do? Occurs in many directories:
+ when? Template seems to be <filename
+ class="libraryfile">config/Shared/include2.mk</filename>.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">subdir.mk</filename></term>
+ <listitem><para>list of subdirectories; occurs in several
+ directories: when? <filename
+ class="libraryfile">src/subdir.mk</filename> is a good
+ example.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename class="libraryfile">objfile.mk</filename></term>
+ <listitem>
+ <para>list of object files to construct, presumably from
+ <filename>*.cmpl.cpp</filename> files.
+ <filename>src/Utilities/objfile.mk</filename> is an
+ example.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">config/Shared/rules.mk</filename></term>
+ <listitem><para>most compiler rules</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">config/head.mk</filename></term>
+ <listitem><para>read at beginning of each
+ makefile?</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">config/Shared/tail.mk</filename></term>
+ <listitem><para>read at end of each makefile?</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">config/Shared/variables.mk</filename></term>
+ <listitem><para>Is this used?</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">config/Shared/compilerules.mk</filename></term>
+ <listitem><para>table of origin and target suffixes and commands
+ for conversion</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </chapter>
+
+
+ <chapter id="arrays_ref">
+ <title>&array;s</title>
+
+ <para>Include <filename
+ class="headerfile">src/Pooma/Arrays.h</filename> to use &array;s.
+ The implementation source code is in <filename
+ class="directory">src/Array</filename>.</para>
+
+ <para>FINISH: Define an array. Introduce its parts.</para>
+
+ <para>ADD: some mention of the maximum supported number of
+ dimensions somewhere.</para>
+
+ <section id="arrays_ref-array">
+ <title>The &array; Container</title>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Template Parameters</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Parameter</entry>
+ <entry>Interpretation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><varname>Dim</varname></entry>
+ <entry><para>dimension</para></entry>
+ </row>
+ <row>
+ <entry><varname>T</varname></entry>
+ <entry><para>array element type</para></entry>
+ </row>
+ <row>
+ <entry>EngineTag</entry>
+ <entry><para>type of computation engine object</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>QUESTION: How do I introduce class type definitions, when
+ they are used, i.e., compile-time or run-time, and when
+ programmers should use them?</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Compile-Time Types and Values</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Type or Value</entry>
+ <entry>Interpretation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><fieldsynopsis><varname>This_t</varname></fieldsynopsis></entry>
+ <entry><para>the &array; object's type</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>Engine_t</varname></fieldsynopsis></entry>
+ <entry><para>the &array; object's engine's type</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>EngineTag_t</varname></fieldsynopsis></entry>
+ <entry><para>indication of engine's category</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>Element_t</varname></fieldsynopsis></entry>
+ <entry><para>the type of the array elements, i.e., <type>T</type></para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>ElementRef_t</varname></fieldsynopsis></entry>
+ <entry><para>the type of a reference to an array element,
+ i.e., <type>T&</type>. Equivalently, the type to write to a
+ single element.</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>Domain_t</varname></fieldsynopsis></entry>
+ <entry><para>the array's domain's type, i.e., the type of the
+ union of all array indices</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>Layout_t</varname></fieldsynopsis></entry>
+ <entry><para>unknown</para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>dimensions</varname></fieldsynopsis></entry>
+ <entry><para>integer equalling the number of dimensions, i.e.,
+ <varname>Dim</varname></para></entry>
+ </row>
+ <row>
+ <entry><fieldsynopsis><varname>rank</varname></fieldsynopsis></entry>
+ <entry><para>integer equalling the number of dimensions, i.e.,
+ <varname>Dim</varname>; a synonym for <fieldsynopsis>
+ <varname>dimensions</varname></fieldsynopsis></para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <section id="arrays_ref-array-constructors">
+ <title>Constructors and Destructors</title>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Constructors and Destructors</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constructorsynopsis>
+ <methodname>Array</methodname>
+ <void></void>
+ </constructorsynopsis>
+ </entry>
+ <entry><para>Creates an array that will be resized
+ later.</para></entry>
+ </row>
+ <row>
+ <entry>
+ <constructorsynopsis>
+ <methodname>Array</methodname>
+ <methodparam><modifier>const</modifier> <type>Engine_t&</type>
+ <parameter>engine</parameter></methodparam>
+ </constructorsynopsis>
+ </entry>
+ <entry><para>Creates an array with an engine equivalent to
+ the <parameter>engine</parameter>. This array will have the
+ same values as <parameter>engine</parameter>. QUESTION: Why
+ would a user every want to use this
+ constructor?</para></entry>
+ </row>
+ <row>
+ <entry>
+ <constructorsynopsis>
+ <methodname>Array</methodname>
+ <methodparam>
+ <modifier>const</modifier>
+ <type> Engine<Dim2, T2, EngineTag2>&</type>
+ <parameter>engine</parameter>
+ </methodparam>
+ <methodparam>
+ <modifier>const</modifier>
+ <type>Initializer&</type> <parameter>init</parameter>
+ </methodparam>
+ </constructorsynopsis>
+ </entry>
+ <entry><para>What does this do?</para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL CONSTRUCTORS AND DESTRUCTORS.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+
+ <section id="arrays_ref-array-initializers">
+ <title>Initializers</title>
+
+ <para>Add a table.</para>
+ </section>
+
+
+ <section id="arrays_ref-array-access">
+ <title>Element Access</title>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&array; Element Access</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>Element_t</type> <methodname>read</methodname>
+ <void></void>
+ </methodsynopsis>
+ </entry>
+ <entry><para>unknown: See line 1839.</para></entry>
+ </row>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>Element_t</type> <methodname>read</methodname>
+ <methodparam>
+ <modifier>const</modifier>
+ <type>Sub1&</type> <parameter>s1</parameter>
+ </methodparam>
+ <methodparam>
+ <modifier>const</modifier>
+ <type> Sub2&</type> <parameter>s2</parameter>
+ </methodparam>
+ </methodsynopsis>
+ </entry>
+ <entry><para>How does the version with template parameters,
+ e.g., <type>Sub1</type> differ from the <type>int</type>
+ version?</para></entry>
+ </row>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>Element_t</type> <methodname>operator()</methodname>
+ <methodparam>
+ <modifier>const</modifier>
+ <type>Sub1&</type> <parameter>s1</parameter>
+ </methodparam>
+ <methodparam>
+ <modifier>const</modifier>
+ <type>Sub2&</type> <parameter>s2</parameter>
+ </methodparam>
+ </methodsynopsis>
+ </entry>
+ <entry><para>How does this differ from <statement>read(const
+ Sub1& s1, const Sub2& s2)</statement>? </para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL <function>read</function>s and
+ <function>operator()</function>s.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+
+ <section id="arrays_ref-array-component">
+ <title>Component Access</title>
+
+ <para>When an array stores elements having components, e.g., an
+ array of vectors, tensors, or arrays, the
+ <methodname>comp</methodname> returns an array consisting of the
+ specified components. The original and component array share the
+ same engine so changing the values in one affects values in the
+ other.</para>
+
+ <para>For example, if &n; × &n; array <varname>a</varname>
+ consists of three-dimensional real-valued vectors,
+ <statement>a.comp(1)</statement> returns a &n; × &n;
+ real-valued array of all the middle vector components. Assigning
+ to the component array will also modify the middle components of
+ the vectors in <varname>a</varname>.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&array; Component Access</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>UNKNOWN compute this</type> <methodname>comp</methodname>
+ <methodparam>
+ <modifier>const</modifier>
+ <type>int&</type>
+ <parameter>i1</parameter>
+ </methodparam>
+ </methodsynopsis>
+ </entry>
+ <entry><para>unknown: See line 1989.</para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL <methodname>comp</methodname>s.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="arrays_ref-array-accessors">
+ <title>Accessors</title>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&array; Accessor Methods</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>int</type> <methodname>first</methodname>
+ <methodparam>
+ <type>int</type>
+ <parameter>d</parameter>
+ </methodparam>
+ </methodsynopsis>
+ </entry>
+ <entry><para>unknown: See line 2050</para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL other accessor methods, including
+ <methodname>engine</methodname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+
+ <section id="arrays_ref-array-copying">
+ <title>Copying &array;s</title>
+
+ <para>Explain how copied arrays and views of arrays share the
+ same underlying engine so changing values in one also affects the
+ other. This is called a shallow copy.</para>
+ </section>
+
+
+ <section id="arrays_ref-array-utilities">
+ <title>Utility Methods</title>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&array; Utility Methods</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>void</type> <methodname>makeOwnCopy</methodname>
+ <void></void>
+ </methodsynopsis>
+ </entry>
+ <entry><para>unknown: See line 2044</para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL other utility methods.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+
+ <section id="arrays_ref-array-implementation">
+ <title>Implementation Details</title>
+
+ <para>As a container, an &array;'s implementation is quite
+ simple. Its <keywordname>private</keywordname>data consists of
+ an engine, and it has no <keywordname>private</keywordname>
+ functions.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&array; Implementation Data</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Data Member</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <fieldsynopsis>
+ <modifier>private</modifier>
+ <type>Engine_t</type> <varname>engine_m</varname>
+ </fieldsynopsis>
+ </entry>
+ <entry><para>engine computing the array's values</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+ </section>
+
+
+ <section id="arrays_ref-dynamicarray">
+ <title>&dynamicarray;s: Dynamically-Sized Domains</title>
+
+ <para>A DynamicArray is a read-write array with extra
+ create/destroy methods. It can act just like a regular Array, but
+ can have a dynamically-changing domain. See <filename
+ class="headerfile">src/DynamicArray/DynamicArray.h</filename>.</para>
+
+ <para>ADD: Briefly describe what the class does and an example of
+ where it is used.</para>
+
+ <para>ADD: Check that its interface is actually the same as for
+ &array;.</para>
+
+ <para>ADD: Check that the operations on dynamic arrays are
+ actually the same as for &array;. See <filename
+ class="headerfile">src/DynamicArray/DynamicArrayOperators.h</filename>,
+ <filename
+ class="headerfile">src/DynamicArray/PoomaDynamicArrayOperators.h</filename>,
+ and <filename
+ class="headerfile">src/DynamicArray/VectorDynamicArrayOperators.h</filename>.</para>
+
+
+ <section id="arrays_ref-dynamicarray-implementation">
+ <title>Implementation Details</title>
+
+ <para><type>DynamicArray</type> has no
+ <keywordname>protected</keywordname> or
+ <keywordname>private</keywordname> members.</para>
+ </section>
+ </section>
+
+
+ <section id="arrays_ref-views">
+ <title>Views of &array;s</title>
+
+ <para>UNFINISHED</para>
+ </section>
+
+
+ <section id="arrays_ref-assignment">
+ <title>&array; Assignments</title>
+
+ <para>&pooma; supports assignments to &array;s of other &array;s
+ and scalar values. QUESTION: Is the following correct? For the
+ former, the right-hand side array's domain must be at least as
+ large as the left-hand side array's domain. Corresponding values
+ are copied. Assigning a scalar value to an array ensures all the
+ array elements have the same scalar value.</para>
+
+ <para>UNFINISHED: Add a table containing assignment operators
+ found one lines 2097–2202.</para>
+ </section>
+
+
+ <section id="arrays_ref-print">
+ <title>Printing &array;s</title>
+
+ <para>&array;s support output to but not input from IO streams.
+ In particular, output to <type>ostream</type>s and file streams is
+ supported.</para>
+
+ <para>Add a table, using <filename
+ class="headerfile">src/Array/Array.h</filename>, lines
+ 2408–2421. See the implementation in <filename
+ class="headerfile">src/Array/PrintArray.h</filename>.</para>
+
+ <para>QUESTION: How does one print a &dynamicarray;.</para>
+ </section>
+
+
+ <section>
+ <title>Expressions Involving &array;s</title>
+
+ <para>In &pooma;, expressions may contain entire &array;s. That
+ is, &array;s are first-class objects with respect to expressions.
+ For example, given &array;s <varname>a</varname> and
+ <varname>b</varname>, the expression <statement>a + b</statement>
+ is equivalent to an array containing the element-wise sum of the
+ two arrays.</para>
+
+ <para>Any finite number of the operators listed below can be used
+ in an expression. The precedence and order of operation is the
+ same as with ordinary built-in types.</para>
+
+ <para>QUESTION: Do &field;s also support the same set of
+ operations?</para>
+
+ <para>QUESTION: Some operations in <filename
+ class="headerfile">src/Field/FieldOperators.h</filename> use both
+ &array; and &field;. Do we list them here or in the &field;
+ section or both or somewhere else?</para>
+
+ <para>In the table below, &array; supplants the exact return types
+ because they are complicated and rarely need to be explicitly
+ written down.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Operators on &array;</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Operator</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>Array <function>acos</function></funcdef>
+ <paramdef>const <parameter>Array<Dim,T,EngineTag>& a</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </entry>
+ <entry><para>an array containing the element-wise inverse
+ cosine of the array <parameter>a</parameter></para></entry>
+ </row>
+ <row>
+ <entry>ADD ALL other operators appearing in <filename
+ class="headerfile">src/Array/ArrayOperators.h</filename>,
+ <filename
+ class="headerfile">src/Array/ArrayOperatorSpecializations.h</filename>,
+ <filename
+ class="headerfile">src/Array/PoomaArrayOperators.h</filename>,
+ and <filename
+ class="headerfile">src/Array/VectorArrayOperators.h</filename>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>FINISH: Write one or two examples or refer to ones
+ previously in the text.</para>
+ </section>
+
+
+ <section id="arrays_ref-reductions">
+ <title>Reducing All &array; Elements to One Value</title>
+
+ <para>These reduction functions repeatedly apply a binary
+ operation to all array elements to yield a value. These functions
+ are similar to the Standard Template Library's
+ <function>accumulate</function> function. For example,
+ <function>sum</function> repeatedly applies the binary plus
+ operator to all array elements, yielding the sum of all array
+ elements.</para>
+
+ <para>FINISH: What order of operation, if any, is
+ guaranteed?</para>
+
+ <para>FINISH: Add a table of the functions in <filename
+ class="headerfile">src/Array/Reductions.h</filename>.</para>
+
+ <para>How does one use one's own binary function? See <filename
+ class="headerfile">src/Engine/Reduction.h</filename>.</para>
+ </section>
+
+
+ <section id="arrays_ref-utilities">
+ <title>Utility Functions</title>
+
+ <section id="arrays_ref-utilities-compression">
+ <title>Compressed Data</title>
+
+ <para>Add a table containing
+ <function>elementsCompressed</function>,
+ <function>compressed</function>, <function>compress</function>,
+ and <function>uncompress</function>.</para>
+ </section>
+
+
+ <section id="arrays_ref-utilities-sizes">
+ <title>Centering Sizes and Number of Materials</title>
+
+ <para>ADD: a description of <function>numMaterials</function> and
+ <function>centeringSize</function> found in <filename
+ class="headerfile">src/Field/Field.h</filename>. These functions
+ are meaningless for &array; but are provided for consistency with
+ &field;.</para>
+ </section>
+
+ <section id="arrays_ref-utilities-subfield">
+ <title>Obtaining Subfields</title>
+
+ <para>ADD: a description of <function>subField</function> found
+ in <filename class="headerfile">src/Field/Field.h</filename>.
+ This function, meaningless for &array;, is provided for
+ consistency with &field;.</para>
+ </section>
+ </section>
+
+
+ <section id="arrays_ref-tmp">
+ <title>TMP: What do we do with these …? Remove this
+ section.</title>
+
+ <para>QUESTION: Do we describe the &leaffunctor;s specialized for
+ &array;s in <filename
+ class="headerfile">src/Array/Array.h</filename> or in the &pete;
+ reference section? What about the functions in <filename
+ class="headerfile">src/Array/CreateLeaf.h</filename>?</para>
+
+ <para>QUESTION: What is an <type>EngineFunctor</type>? We
+ probably should describe it in an analogous way as for
+ &leaffunctor;s.</para>
+
+ <para>QUESTION: Where do we write about
+ <type>ExpressionTraits</type> for &array;s?</para>
+
+ <para>QUESTION: Do we describe the <type>ElementProperties</type>
+ specialization at this place or in its section?</para>
+
+ <para>QUESTION: Do we describe the <type>Patch</type>
+ specialization for &array;s (<filename
+ class="headerfile">src/Array/Array.h</filename>:1300) in this
+ place or in a section for patches?</para>
+ </section>
+ </chapter>
+
+
+ <chapter id="fields_ref">
+ <title>&field;s</title>
+
+ <para>An &array; is a set of values indexed by
+ coordinates, one value per coordinate. It models the computer
+ science idea of an array. Similarly, a &field; is a set of values
+ indexed by coordinate. It models the mathematical and physical
+ idea of a field represented by a grid of rectangular cells, each
+ having at least one value. A &field;'s functionality is a superset
+ of an &array;'s functionality because:
+ <itemizedlist>
+ <listitem>
+ <para>A &field; is distributed through space so one can compute
+ the distances between cells.</para>
+ </listitem>
+ <listitem>
+ <para>Each cell can hold multiple values. For example, a
+ rectangular cell can have one value on each of its faces.</para>
+ </listitem>
+ <listitem>
+ <para>Multiple materials can share the same cell. For example,
+ different values can be stored in the same cell for carbon,
+ oxygen, and nitrogen.</para>
+ </listitem>
+ </itemizedlist>
+ Also, &field;s' values can be related by relations. Thus, if one
+ field's values change, a dependent field's values can be
+ automatically computed when needed. FIXME: See also the unfinished
+ works chapter's entry concerning relations and arrays.</para>
+
+ <para>QUESTION: Should we add a picture comparing and contrasting
+ an array and a field?</para>
+
+ <para>QUESTION: How much structure can be copied from the &array;
+ chapter?</para>
+
+ <para>QUESTION: Where is <type>NewMeshTag</type>, defined in
+ <filename class="headerfile">src/Field/Field.h</filename>,
+ used?</para>
+
+ <para>QUESTION: Do we describe the &leaffunctor;s specialized for
+ &field;s in <filename
+ class="headerfile">src/Field/Field.h</filename> or in the &pete;
+ reference section? Use the same decision for &array;s.</para>
+
+ <para>QUESTION: What do the structure and functions in <filename
+ class="headerfile">src/Field/Mesh/PositionFunctions.h</filename>
+ do?</para>
+
+
+ <section id="fields_ref-field">
+ <title>The &field; Container</title>
+
+ <para>ADD: table of template parameters and table of compile-time
+ types and values.</para>
+
+
+ <section id="fields_ref-field-constructors">
+ <title>Constructors and Destructors</title>
+
+ <para>ADD: this section similar to &array;s's constructor and
+ destructor section.</para>
+ </section>
+
+ <section id="fields_ref-field-initializers">
+ <title>Initializers</title>
+
+ <para>Add a table.</para>
+ </section>
+
+
+ <section id="fields_ref-field-access">
+ <title>Element Access</title>
+
+ <para>ADD: a table ala &array;. Be sure to include
+ <methodname>all</methodname>.</para>
+ </section>
+
+
+ <section id="fields_ref-field-component">
+ <title>Component Access</title>
+
+ <para>ADD: a table ala &array;.</para>
+ </section>
+
+
+ <section id="fields_ref-field-subfields">
+ <title>Obtaining Subfields</title>
+
+ <para>ADD: discussion and a table listing ways to obtain
+ subfields. Although the implementation may treat subfield views
+ and other field views similarly (?Is this true?), they are
+ conceptually different ideas so we present them
+ separately.</para>
+
+ <para>See <filename
+ class="headerfile">src/Field/Field.h</filename>'s
+ <methodname>operator[]</methodname>,
+ <methodname>subField</methodname>, …,
+ <methodname>material</methodname>.</para>
+ </section>
+
+
+ <section id="fields_ref-field-relations">
+ <title>Supporting Relations</title>
+
+ <para>ADD: a table with the member functions including
+ <methodname>addRelation</methodname>,
+ <methodname>removeRelations</methodname>,
+ <methodname>applyRelations</methodname>, and
+ <methodname>setDirty</methodname>.</para>
+ </section>
+
+
+ <section id="fields_ref-field-accessors">
+ <title>Accessors</title>
+
+ <para>ADD: a table using lines like <filename
+ class="headerfile">src/Field/Field.h</filename>:1243–1333.</para>
+ </section>
+
+
+ <section id="fields_ref-field-utilities">
+ <title>Utility Methods</title>
+
+ <para>ADD: a table including
+ <methodname>makeOwnCopy</methodname>.</para>
+ </section>
+
+
+ <section id="fields_ref-field-implementation">
+ <title>Implementation Details</title>
+
+ <para>ADD: a table similar to &array;'s.</para>
+
+ </section>
+
+ </section>
+
+
+ <section id="engines_ref-views">
+ <title>Views of &field;s</title>
+
+ <para>Be sure to relate to &array; views. Note only three
+ dimensions are supported.</para>
+
+ <para>Be sure to describe <statement>f[i]</statement>. Does this
+ refer to a particular material or a particular value within a
+ cell? I do not remember. See <type>SubFieldView</type> in
+ <filename class="headerfile">src/Field/Field.h</filename>.</para>
+ </section>
+
+
+ <section id="fields_ref-assignment">
+ <title>&field; Assignments</title>
+
+ <para>ADD: Describe supported assignments, relating to &array;'s
+ assignments.</para>
+
+ <para>UNFINISHED: Add a table containing assignment operators
+ found on <filename
+ class="headerfile">src/Field/Field.h</filename>:2097–2202
+ and 1512–1611.</para>
+ </section>
+
+
+ <section id="fields_ref-print">
+ <title>Printing &field;s</title>
+
+ <para>QUESTION: How similar is this to printing &array;s?</para>
+
+ <para>&field;s support output to but not input from IO streams.
+ In particular, output to <type>ostream</type>s and file streams is
+ supported.</para>
+
+ <para>Add a table, using <filename
+ class="headerfile">src/Field/Field.h</filename>, lines
+ 1996–2009. See the implementation in <filename
+ class="headerfile">src/Field/PrintField.h</filename>.</para>
+ </section>
+
+
+ <section id="fields_ref-reductions">
+ <title>Combining &field; Elements</title>
+
+ <para>Like &array;s, &field;s support reduction of all elements to
+ one value. Additionally, the latter supports computing a field's
+ values using field stencils. QUESTION: How do I describe this
+ with a minimum of jargon?</para>
+
+ <para>ADD: something similar to &array; reductions.</para>
+
+ <para>FINISH: Add a table of the functions in <filename
+ class="headerfile">src/Field/FieldReductions.h</filename>.</para>
+
+ <para>FINISH: Add a table of the functions in <filename
+ class="headerfile">src/Field/DiffOps/FieldOffsetReductions.h</filename>.
+ QUESTION: Why is only <function>sum</function> defined?</para>
+ </section>
+
+
+ <section id="fields_ref-expressions">
+ <title>Expressions Involving &field;s</title>
+
+ <para>Do something similar to &array;'s section. See the
+ operations defined in <filename
+ class="headerfile">src/Field/FieldOperators.h</filename>,
+ <filename
+ class="headerfile">src/Field/FieldOperatorSpecializations.h</filename>,
+ <filename
+ class="headerfile">src/Field/PoomaFieldOperators.h</filename>, and
+ <filename
+ class="headerfile">src/Field/VectorFieldOperators.h</filename>.</para>
+
+ <para>Some operations involve both &array; and &field;
+ parameters. Where do we list them?</para>
+ </section>
+
+
+ <section id="fields_ref-stencils">
+ <title>&field; Stencils: Faster, Local Computations</title>
+
+ <para>ADD: a description of a stencil. Why is it needed? How
+ does a user use it? How does a user know when to use one? Add
+ documentation of the material from <filename
+ class="headerfile">src/Field/DiffOps/FieldStencil.h</filename>.</para>
+
+ <para>How is <type>FieldShiftEngine</type> used by &field;
+ stencils? Should it be described here or in the &engine; section?
+ See the the code in <filename
+ class="headerfile">src/Field/DiffOps/FieldShiftEngine.h</filename>.</para>
+ </section>
+
+
+ <section>
+ <title>Cell Volumes, Face Areas, Edge Lengths, Normals</title>
+
+ <para>ADD: a description of these functions. See <filename
+ class="headerfile">src/Field/Mesh/MeshFunctions.h</filename>.
+ These are initialized in, e.g., <filename
+ class="headerfile">src/Field/Mesh/UniformRectilinearMesh.h</filename>.
+ Note that these do not work for <type>NoMesh</type>.</para>
+ </section>
+
+
+ <section id="fields_ref-div">
+ <title>Divergence Operators</title>
+
+ <para>ADD: a table having divergence operators, explaining the
+ current restrictions imposed by what is implemented. See
+ <filename class="headerfile">src/Field/DiffOps/Div.h</filename>
+ and <filename
+ class="headerfile">src/Field/DiffOps/Div.UR.h</filename>. What
+ restrictions does <quote>UR</quote> (mesh) connote?</para>
+ </section>
+
+
+ <section id="fields_ref-utilities">
+ <title>Utility Functions</title>
+
+ <section id="fields_ref-utilities-compression">
+ <title>Compressed Data</title>
+
+ <para>Add a table containing
+ <function>elementsCompressed</function>,
+ <function>compressed</function>, <function>compress</function>,
+ and <function>uncompress</function>.</para>
+ </section>
+
+
+ <section id="fields_ref-utilities-sizes">
+ <title>Centering Sizes and Number of Materials</title>
+
+ <para>ADD: a description of <function>numMaterials</function> and
+ <function>centeringSize</function> found in <filename
+ class="headerfile">src/Field/Field.h</filename>.</para>
+
+ <para>QUESTION: How do these relate to any method functions?</para>
+ </section>
+
+
+ <section id="fields_ref-utilities-subfield">
+ <title>Obtaining Subfields</title>
+
+ <para>ADD: a description of <function>subField</function> found
+ in <filename
+ class="headerfile">src/Field/Field.h</filename>.</para>
+ </section>
+
+ </section>
+
+
+ <section id="fields_ref-centerings">
+ <title>&field; Centerings</title>
+
+ <para>DO: Describe the purpose of a centering and its definition.
+ Describe the ability to obtain canonical centerings. Explain how
+ to construct a unique centering. See <filename
+ class="headerfile">src/Field/FieldDentering.h</filename>.</para>
+ </section>
+
+
+ <section id="fields_ref-fieldoffsets">
+ <title>Relative &field; Positions</title>
+
+ <para>Permit specifying field positions relative to a field
+ location. Describe <type>FieldOffset</type> and
+ <type>FieldOffsetList</type>. See <filename
+ class="headerfile">src/Field/FieldOffset.h</filename></para>
+ </section>
+
+
+ <section id="fields_ref-nearestneighbors">
+ <title>Computing Close-by Field Positions</title>
+
+ <para>Given a field location, return the set of field locations
+ that are closest using ?Manhattan? distance. See <filename
+ class="headerfile">src/Field/NearestNeighbors.h</filename>.</para>
+ </section>
+
+
+ <section id="fields_ref-mesh">
+ <title>Mesh ???</title>
+
+ <para>Unlike &array;s, &field;s are distributed throughout space
+ so distances between values within the &field can be computed. A
+ &field;'s mesh stores this spatial distribution.</para>
+
+ <para>QUESTION: What do we need to write about meshes? What is
+ unimportant implementation and what should be described in this
+ reference section?</para>
+
+ <para>QUESTION: Where in here should emphasize vertex, not cell,
+ positions? <quote>VERTEX</quote> appears repeatedly in <filename
+ class="headerfile">src/Field/Mesh/NoMesh.h</filename>.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Mesh Types</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Mesh Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><type>NoMesh<Dim></type></entry>
+ <entry><para>no physical spacing, causing a &field; to mimic
+ an &array; with multiple engines.</para></entry>
+ </row>
+ <row>
+ <entry><type>UniformRectilinearMesh<Dim,T></type></entry>
+ <entry><para>physical spacing formed by the Cartesian product
+ of ????.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ <section id="fields_ref-mesh-accessors">
+ <title>Mesh Accessors</title>
+
+ <para>ADD: a table listing accessors, explaining the difference
+ between (physical and total) and (cell and vertex) domains. See
+ <filename class="headerfile">src/Field/Mesh/NoMesh.h</filename>.
+ Also, include <function>spacings</function> and
+ <function>origin</function> in <filename
+ class="headerfile">src/Field/Mesh/UniformRectilinearMesh.h</filename>.
+ Note <type>NoMesh</type> does not provide the latter two.</para>
+ </section>
+
+ </section>
+
+
+ <section id="fields_ref-tmp">
+ <title>TMP: What do we do with these …? Remove this
+ section.</title>
+
+ <para>QUESTION: Do we describe the <type>Patch</type>
+ specialization for &field; at this place or in some common place?
+ Follow &array;'s lead.</para>
+
+ <para>QUESTION: Where do we describe <type>CreateLeaf</type> and
+ <type>MakeFieldReturn</type> in <filename
+ class="headerfile">src/Field/FieldCreateLeaf.h</filename> and
+ <filename
+ class="headerfile">src/Field/FieldMakeReturn.h</filename>.</para>
+
+ <para>QUESTION: What do we do with <type>FieldEnginePatch</type>
+ in <filename
+ class="headerfile">src/Field/FieldEngine/FieldEnginePatch.h</filename>.</para>
+ </section>
+ </chapter>
+
+
+ <chapter id="engines_ref">
+ <title>&engine;s</title>
+
+ <para>From a user's point of view, a container makes data available
+ for reading and writing. In fact, the container's &engine; stores
+ the data or, if the data is computed, performs a computation to
+ yield the data.</para>
+
+ <para>FINISH: Introduce the various types of engines. Add a table
+ with a short description of each engine type.</para>
+
+ <para>FINISH: First, we specify a generic &engine;'s interface.
+ Then, we present &engine; specializations.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>Types of &engine;s</title>
+
+ <tgroup cols="3" align="left">
+ <thead>
+ <row>
+ <entry>Engine Type</entry>
+ <entry>Engine Tag</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Brick</para></entry>
+ <entry><para><literal>Brick</literal></para></entry>
+ <entry><para>Explicitly store all elements in, e.g., a &cc;
+ array.</para></entry>
+ </row>
+ <row>
+ <entry><para>Compressible</para></entry>
+ <entry><para><literal>CompressibleBrick</literal></para></entry>
+ <entry><para>If all values are the same, use constant storage
+ for that single value. Otherwise, explicitly store all
+ elements.</para></entry>
+ </row>
+ <row>
+ <entry><para>Constant</para></entry>
+ <entry><para><literal>ConstantFunction</literal></para></entry>
+ <entry><para>Returns the same constant value for all
+ indices.</para></entry>
+ </row>
+ <row>
+ <entry><para>Dynamic</para></entry>
+ <entry><para><literal>Dynamic</literal></para></entry>
+ <entry><para>Manages a contiguous, local, one-dimensional,
+ dynamically resizable block of data.</para></entry>
+ </row>
+ <row>
+ <entry><para>Component Forwarding</para></entry>
+ <entry><para><literal>CompFwd<EngineTag,
+ Components></literal></para></entry>
+ <entry><para>Returns the specified components from
+ <literal>EngineTag</literal>'s engine. Components are
+ <quote>pieces</quote> of multi-value elements such as vectors
+ and tensors.</para></entry>
+ </row>
+ <row>
+ <entry><para>Expression</para></entry>
+ <entry><para><literal>ExpressionTag<Expr></literal></para></entry>
+ <entry><para>Returns the value of the specified &pete;
+ expression.</para></entry>
+ </row>
+ <row>
+ <entry><para>Index Function</para></entry>
+ <entry><para><literal>IndexFunction<Functor></literal></para></entry>
+ <entry><para>Makes the function
+ <literal>Functor</literal>accepting indices mimic an
+ array.</para></entry>
+ </row>
+ <row>
+ <entry><para>MultiPatch</para></entry>
+ <entry><para><literal>MultiPatch<LayoutTag,PatchTag></literal></para></entry>
+ <entry><para>Support distributed computation using several
+ processors (???contexts???). <literal>LayoutTag</literal>
+ indicates how the entire array is distributed among the
+ processors. Each processor uses a <literal>PatchTag</literal>
+ engine.</para></entry>
+ </row>
+ <row>
+ <entry><para>Remote</para></entry>
+ <entry><para><literal>Remote<EngineTag></literal></para></entry>
+ <entry><para>unknown</para></entry>
+ </row>
+ <row>
+ <entry><para>Remote Dynamic</para></entry>
+ <entry><para><literal>Remote<Dynamic></literal></para></entry>
+ <entry><para>unknown: specialization</para></entry>
+ </row>
+ <row>
+ <entry><para>Stencil</para></entry>
+ <entry><para><literal>StencilEngine<Function,
+ Expression></literal></para></entry>
+ <entry><para>Returns values computed by applying the
+ user-specified function to sets of contiguous values in the
+ given engine or container. Compare with user function
+ engines.</para></entry>
+ </row>
+ <row>
+ <entry><para>User Function</para></entry>
+ <entry><para><literal>UserFunctionEngine<UserFunction,Expression></literal></para></entry>
+ <entry><para> Returns values computed by applying the
+ user-specified function to the given engine or container.
+ QUESTION: Is the following claim correct? For each returned
+ value, only one value from the engine or container is
+ used.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>QUESTION: Where do we describe views?</para>
+
+ <para>QUESTION: What does <type>NewEngine</type> do? Should it be
+ described when describing views? Should it be omitted as an
+ implementation detail?</para>
+
+ <para>QUESTION: Where do we describe &engine; patches found in
+ <filename class="headerfile">src/Engine/EnginePatch.h</filename>?
+ All patch data in a separate chapter or engine-specific pieces in
+ this chapter?</para>
+
+ <para>QUESTION: What is <function>notifyEngineWrite</function>?
+ See also <filename
+ class="headerfile">src/Engine/NotifyEngineWrite.h</filename>.</para>
+
+ <para>QUESTION: What aspect of MultiPatch uses <type>IsValid</type> in
+ <filename
+ class="headerfile">src/Engine/IsValidLocation.h</filename>?</para>
+
+ <para>QUESTION: Who uses intersections? Where should this be
+ described? See <filename
+ class="headerfile">src/Engine/Intersector.h</filename>, <filename
+ class="headerfile">src/Engine/IntersectEngine.h</filename>, and
+ <filename
+ class="headerfile">src/Engine/ViewEngine.h</filename>.</para>
+
+ <section id="engines_ref-compile_time_interface">
+ <title>&engine; Compile-Time Interface</title>
+
+ <para>ADD: a table of template parameters ala &array;. ADD:
+ compile-time types and values.</para>
+ </section>
+
+
+ <section id="engines_ref-constructors">
+ <title>Constructors and Destructors</title>
+
+ <para>ADD: a table of constructors and destructors ala
+ &array;'s.</para>
+ </section>
+
+
+ <section id="engines_ref-access">
+ <title>Element Access</title>
+
+ <para>ADD: a table with <methodname>read</methodname> and
+ <methodname>operator()</methodname>.</para>
+ </section>
+
+
+ <section id="engines_ref-accessors">
+ <title>Accessors</title>
+
+ <para>ADD: a table of accessors.</para>
+ </section>
+
+
+ <section id="engines_ref-assignments">
+ <title>&engine; Assignments</title>
+
+ <para>similar to &array;'s assignments. shallow copies. ADD: a
+ table with one entry</para>
+ </section>
+
+
+ <section id="engines_ref-utilities">
+ <title>Utility Methods</title>
+
+ <para>ADD: a table including
+ <methodname>makeOwnCopy</methodname>.</para>
+
+ <para>QUESTION: What are <methodname>dataObject</methodname>,
+ <methodname>isShared</methodname>, and related methods?</para>
+ </section>
+
+
+ <section id="engines_ref-implementation">
+ <title>Implementation Details</title>
+
+ <para>ADD: this section. Explain that
+ <varname>dataBlock_m</varname> and <varname>data_m</varname> point
+ to the same place. The latter speeds access, but what is the
+ purpose of the former?</para>
+ </section>
+
+
+ <section id="engines_ref-brick">
+ <title>Brick and BrickView Engines</title>
+
+ <para>ADD: description of what a brick means. ADD: whatever
+ specializations the class has, e.g.,
+ <methodname>offset</methodname>.</para>
+
+ <para>QUESTION: What does <type>DoubleSliceHelper</type> do?</para>
+ </section>
+
+
+ <section id="engines_ref-compressible">
+ <title>Compressible Brick and BrickView Engines</title>
+
+ <para>ADD this.</para>
+ </section>
+
+
+ <section id="engines_ref-dynamic">
+ <title>Dynamic and DynamicView Engines:</title>
+
+ <para>ADD this. Manages a contiguous, local, resizable, 1D block
+ of data.</para>
+ </section>
+
+
+ <section id="engines_ref-components">
+ <title>Component Engines</title>
+
+ <para>I believe these implement array component-forwarding. See
+ <filename
+ class="headerfile">src/Engine/ForwardingEngine.h</filename>.</para>
+ </section>
+
+
+ <section id="engines_ref-expressions">
+ <title>Expression Engines</title>
+
+ <para>Should this be described in the &pete; section? Unlikely.
+ See <filename
+ class="headerfile">src/Engine/ExpressionEngine.h</filename>.</para>
+ </section>
+
+
+ <section id="engines_ref-enginefunctor">
+ <title>&engine; Functors</title>
+
+ <para>QUESTION: What is an <type>EngineFunctor</type>? Should it
+ have its own section? See <filename
+ class="headerfile">src/Engine/EngineFunctor.h</filename>.</para>
+ </section>
+
+
+ <section id="engines_ref-fieldengines">
+ <title><type>FieldEngine</type>: A Hierarchy of &engine;s</title>
+
+ <para>A &field; consists of a hierarchy of materials and
+ centerings. These are implemented using a hierarchy of engines.
+ See <filename
+ class="headerfile">src/Field/FieldEngine/FieldEngine.h</filename>
+ and <filename
+ class="headerfile">src/Field/FieldEngine/FieldEngine.ExprEngine.h</filename>.</para>
+ </section>
+ </chapter>
+
+
+ <chapter id="benchmarks_ref">
+ <title>&benchmark; Programs</title>
+
+ <para>Explain how to use &benchmark; programs, especially the
+ options. Explain how to write a &benchmark; program. See also
+ <filename class="headerfile">src/Utilities/Benchmark.h</filename>
+ and <filename
+ class="libraryfile">src/Utilities/Benchmark.cmpl.cpp</filename>.</para>
+
+ </chapter>
+
+
+ <chapter id="layouts_ref">
+ <title>Layouts and Partitions: Distribute Computation Among
+ Contexts</title>
+
+ <para>What is the difference between <type>ReplicatedTag</type> and
+ <type>DistributedTag</type>?</para>
+
+ </chapter>
+
+
+ <chapter id="pete_ref">
+ <title>&pete;: Evaluating Parallel Expressions</title>
+
+ <section>
+ <title>UNKNOWN</title>
+
+ <section id="pete_ref-unknown-leaf-tags">
+ <title>Leaf Tag Classes</title>
+
+ <para><type>NotifyPreReadTag</type> indicates a term is about to
+ be read. Why is this needed? Defined in <filename
+ class="headerfile">src/Utilities/NotifyPreRead.h</filename>.</para>
+ </section>
+ </section>
+
+ </chapter>
+
+
+ <chapter id="views_ref">
+ <title>Views</title>
+
+ <para>QUESTION: Should this have its own chapter or be part of a
+ container chapter?</para>
+
+ <para>Describe <type>View0</type>, <type>View1</type>, …,
+ <type>View7</type> and <type>View1Implementation</type>.</para>
+
+ <para>QUESTION: What causes the need for <type>AltView0</type> and
+ <type>AltComponentView</type>?</para>
+
+ <para>Be sure to describe <type>ComponentView</type> in the same
+ place. This is specialized for &array;s in <filename
+ class="headerfile">src/Array/Array.h</filename>:1323–1382.</para>
+
+ <section>
+ <title><type>ViewIndexer<Dim,Dim2></type></title>
+
+ <para>Defined in <filename
+ class="headerfile">src/Utilities/ViewIndexer.h</filename>, this
+ type translates indices between a domain and a view of it.</para>
+ </section>
+ </chapter>
+
+ <chapter id="threads_ref">
+ <title>Threads</title>
+
+ <para>Perhaps include information in <filename
+ class="headerfile">src/Engine/DataObject.h</filename>.</para>
+
+ <para>&pooma; options include UNFINISHED</para>
+
+ </chapter>
+
+
+ <chapter id="utilities_ref">
+ <title>Utility Types</title>
+
+ <para>TMP: What is a good order?</para>
+
+ <section id="utilities_ref-options">
+ <title><type>Options</type>: Varying Run-Time Execution</title>
+
+ <para>Each &pooma; executable has a <type>Options</type> object,
+ created by <function>Pooma::initialize</function>, storing
+ run-time configurable values found in <varname>argv</varname>.
+ Default options are found in
+ <methodname>Options::usage</methodname>.</para>
+
+ <para>See <filename
+ class="headerfile">src/Utilities/Options.h</filename> and
+ <filename
+ class="libraryfile">src/Utilities/Options.cmpl.cpp</filename>.</para>
+
+ <para>Scatter the specific options to other parts of the
+ manual.</para>
+ </section>
+
+ <section id="utilities_ref-assertions">
+ <title>Check Correctness: <type>CTAssert</type>,
+ <type>PAssert</type>, <type>PInsist</type>,
+ <type>SameType</type></title>
+
+ <para>Assertions ensure program invariants are obeyed.
+ <type>CTAssert</type>, checked at compile time, incur no run-time
+ cost. <type>PAssert</type> and <type>PInsist</type> are checked
+ to run-time, the latter producing an explanatory message if the
+ assertion fails. Compiling with <envar>NOCTAssert</envar> and
+ <envar>NOPTAssert</envar> disable these checks. Compiling with just
+ <envar>NOPTAssert</envar> disables only the run-time checks.</para>
+
+ <para><type>SameType</type> ensures, at compile-time, two types
+ are the same.</para>
+
+ <para>These are implemented in <filename
+ class="headerfile">src/Utilities/PAssert.h</filename> and
+ <filename
+ class="libraryfile">src/Utilities/PAssert.cmpl.cpp</filename>.</para>
+ </section>
+
+ <section id="utilities_ref-clock">
+ <title><type>Clock</type>: Measuring a Program's Execution Time</title>
+
+ <para>See <filename
+ class="headerfile">src/Utilities/Clock.h</filename>.</para>
+ </section>
+
+
+ <section id="utilities_ref-smart_pointers">
+ <title>Smart Pointers: <type>RefCountedPtr</type>,
+ <type>RefCountedBlockPtr</type>, and
+ <type>DataBlockPtr</type></title>
+
+ <para>See <filename
+ class="headerfile">src/Utilities/{RefCountedPtr,RefCountedBlockPtr,DataBlockPtr}.h</filename>.
+ <filename class="headerfile">src/Utilities/RefCounted.h</filename>
+ helps implement it. <type>DataBlockPtr</type> uses
+ &smarts;.</para>
+ </section>
+
+ <section id="utilities_ref-inform">
+ <title><type>Inform</type>: Formatted Output for Multi-context
+ Execution</title>
+
+ <para>See <filename
+ class="headerfile">src/Utilities/Inform.h</filename> and <filename
+ class="libraryfile">src/Utilities/Inform.cmpl.cpp</filename>.</para>
+ </section>
+
+ <section id="utilities_ref-statistics">
+ <title><type>Statistics</type>: Report &pooma; Execution Statistics</title>
+
+ <para>Collect and print execution statistics. Defined in
+ <filename
+ class="headerfile">src/Utilities/Statistics.h</filename>.</para>
+ </section>
+
+ <section id="utilities_ref-random_numbers">
+ <title>Random Numbers: <type>Unique</type></title>
+
+ <para>See <filename
+ class="headerfile">src/Utilities/Unique.h</filename>.</para>
+ </section>
+ </chapter>
+
+
+ <chapter id="implementation_types_ref">
+ <title>Types for Implementing &pooma;</title>
+
+ <para>TMP: What is a good order?</para>
+
+ <para>Describe types defined to implement &pooma; but that users do
+ not directly use. This chapter has lower priority than other
+ chapters since users (hopefully) do not need to know about these
+ classes.</para>
+
+ <section id="implementation_types_ref-tester">
+ <title><type>Tester</type>: Check Implementation Correctness</title>
+
+ <para>&pooma; implementation test programs frequently consist of a
+ series of operations followed by correctness checks. The
+ <type>Tester</type> object supports these tests, returning a
+ boolean whether all the correctness checks yield true. Under
+ verbose output, messages are printed for each test. See <filename
+ class="headerfile">src/Utilities/Tester.h</filename>.</para>
+ </section>
+
+ <section id="implementation_types_ref-elementproperties">
+ <title><type>ElementProperties<T></type>: Properties a Type
+ Supports</title>
+
+ <para>This traits class permits optimizations in other templated
+ classes. See <filename
+ class="headerfile">src/Utilities/ElementProperties.h</filename>.</para>
+
+ </section>
+
+ <section id="implementation_types_ref-typeinfo">
+ <title><type>TypeInfo<T></type>: Print a String Describing
+ the Type</title>
+
+ <para>Print a string describing the type. Defined in <filename
+ class="headerfile">src/Utilities/TypeInfo.h</filename>. It is
+ specialized for other types in other files, e.g., <filename
+ class="headerfile">src/Engine/EngineTypeInfo.h</filename> and
+ <filename class="headerfile">src/Field/FieldTypeInfo.h</filename>.
+ Is this a compile-time version of RTTI?</para>
+ </section>
+
+ <section id="implementation_types_ref-looputils">
+ <title><type>LoopUtils</type>: Loop Computations at Compile Time</title>
+
+ <para>At compile time, <type>LoopUtils</type> supports copying
+ between arrays and computing the dot product of arrays. See
+ <filename
+ class="headerfile">src/Utilities/MetaProg.h</filename>.</para>
+ </section>
+
+ <section id="implementation_types_ref-modelelement">
+ <title><type>ModelElement<T></type>: Wrap a Type</title>
+
+ <para>A wrapper class used to differentiate overloaded functions.
+ Defined in <filename
+ class="headerfile">src/Utilities/ModelElement.h</filename>. Used
+ only by &array; and <type>DynamicArray</type>.</para>
+ </section>
+
+ <section id="implementation_types_ref-wrappedint">
+ <title><type>WrappedInt<int></type>: Wrap a Number</title>
+
+ <para>A wrapper class used to differentiate overloaded functions
+ among different integers. Defined in <filename
+ class="headerfile">src/Utilities/WrappedInt.h</filename>. Is this
+ class deprecated? Is it even necessary?</para>
+ </section>
+
+ <section id="implementation_types_ref-empty_classes">
+ <title>Supporting Empty Classes</title>
+
+ <para>The <type>NoInit</type> tag class indicates certain
+ initializations should be skipped. Defined in <filename
+ class="headerfile">src/Utilities/NoInit.h</filename>.</para>
+
+ <para>FIXME: Should be macro, not function.
+ <function>POOMA_PURIFY_CONSTRUCTORS</function> generates an empty
+ constructor, copy constructor, and destructor to avoid &purify;
+ warnings. Defined in <filename
+ class="headerfile">src/Utilities/PurifyConstructors.h</filename>.</para>
+
+ </section>
+
+ <section id="implementation_types_ref-pool">
+ <title><type>Pooled<T></type>: Fast Memory Allocation of
+ Small Blocks</title>
+
+ <para><type>Pooled<T></type> speeds allocation and
+ deallocation of memory blocks for small objects with
+ type <type>T</type>. Defined in <filename
+ class="headerfile">src/Utilities/Pooled.h</filename>, it is
+ implemented in <filename
+ class="headerfile">src/Utilities/Pool.h</filename> and <filename
+ class="libraryfile">src/Utilities/Pool.cmpl.cpp</filename>.
+ <filename class="headerfile">src/Utilities/StaticPool.h</filename>
+ no longer seems to be used.</para>
+ </section>
+
+ <section id="implementation_types_ref-uninitialized_vector">
+ <title><type>UninitializedVector<T,Dim></type>: Create
+ Without Initializing</title>
+
+ <para>This class optimizes creation of an array of objects by
+ avoiding running the default constructors. Later initialization
+ can occur, perhaps using a loop that can be unrolled. Defined in
+ <filename
+ class="headerfile">src/Utilities/UninitializedVector.h</filename>,
+ this is used only by <type>DomainTraits</type>.</para>
+ </section>
+ </chapter>
+
+ <chapter id="implementation_algorithms_ref">
+ <title>Algorithms for Implementing &pooma;</title>
+
+ <para>In <filename>src/Utilities/algorithms.h</filename>,
+ <function>copy</function>, <function>delete_back</function>, and
+ <function>delete_shiftup</function> provide additional algorithms
+ using iterators.</para>
+ </chapter>
+
+
+ <chapter id="where-place-these_ref">
+ <title>TMP: Where do we describe these files?</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename
+ class="headerfile">src/Utilities/Conform.h</filename>: tag for
+ checking whether terms in expression have conforming
+ domains</para>
+ </listitem>
+
+ <listitem>
+ <para><filename
+ class="headerfile">src/Utilities/DerefIterator.h</filename>:
+ <type>DerefIterator<T></type> and
+ <type>ConstDerefIterator<T></type> automatically
+ dereference themselves to maintain <literal>const</literal>
+ correctness. <!-- FIXME: s/literal/keyword/ --></para>
+ </listitem>
+
+ <listitem>
+ <para><filename
+ class="headerfile">src/Utilities/Observable.h</filename>,
+ <filename class="headerfile">src/Utilities/Observer.h</filename>,
+ and <filename
+ class="headerfile">src/Utilities/ObserverEvent.h</filename>:
+ <type>Observable<T></type>,
+ <type>SingleObserveable<T></type>,
+ <type>Observer<T></type>, and <type>ObserverEvent</type>
+ implement the observer pattern. What is the observer pattern?
+ Where is this used in the code?</para>
+ </listitem>
+ </itemizedlist>
+
+ </chapter>
+
+ </part>
+
+
+ <appendix id="future_development">
+ <title>Future Development</title>
+
+ <section id="future_development-particles">
+ <title>Particles</title>
+
+ <para><filename
+ class="libraryfile">docs/ParticlesDoc.txt</filename> has
+ out-of-date information.</para>
+
+ <para>See Section 3.2.3 of
+ <filename>papers/pooma.ps</filename> for an out-of-date
+ description.</para>
+
+ <para><filename>papers/jvwr.ps</filename> concerns mainly
+ particles. <filename>papers/8thSIAMPOOMAParticles.pdf</filename>,
+ by Julian Cummings and Bill Humphrey, concerns parallel particle
+ simulations. <filename>papers/iscope98linac.pdf</filename>
+ describes a particle beam simulation using &pooma;; it mainly
+ concerns particles.</para>
+
+ <section>
+ <title>Particles</title>
+
+ <para>Do we want to include such a section?</para>
+
+ <para>Section 3, "Sample Applications" of
+ <filename>papers/SiamOO98_paper.ps</filename> describes porting a
+ particle program written using High-Performance Fortran to
+ &pooma; and presumably why particles were added to &pooma;. It
+ also describes <application>MC++</application>, a Monte Carlo
+ neutron transport code.</para>
+
+ </section>
+
+ </section>
+
+
+ <section id="future_development-composition_engine">
+ <title>Composition of &engine;s</title>
+
+ <para>The i,j-th element of the composition
+ <varname>a</varname>∘<varname>b</varname> of two arrays
+ <varname>a</varname> and <varname>b</varname> equals a(b(i,j)).
+ The composition engine tagged <literal>IndirectionTag<Array1,
+ Array2></literal>, defined in <filename
+ class="headerfile">src/Engine/IndirectionEngine.h</filename> is
+ unfinished.</para>
+ </section>
+
+
+ <section id="future_development-container_consistency">
+ <title>Improving Consistency of Container Interfaces</title>
+
+ <section id="future_development-container_consistency-array_relations">
+ <title>Relations for &array;s</title>
+
+ <para>Do &array;s currently support relations? If not, why not?
+ Should they be added?</para>
+ </section>
+
+ <section id="future_development-container_consistency-dimensions">
+ <title>Supporting the Same Number of Dimensions</title>
+
+ <para>&array; and &field; should support the same maximum number
+ of dimensions. Currently, &array;s support seven dimensions and
+ &field;s support only three. By definition, &dynamicarray;
+ supports only one dimension.</para>
+
+ <para>Relations for &array;s.</para>
+
+ <para>External guards for &array;s.</para>
+
+ <para>QUESTION: What is <quote>tiny</quote> about &matrix;? Should
+ they be renamed?</para>
+ </section>
+
+ </section>
+
+
+ <section id="future_development-where">
+ <title><function>where</function> Proxies</title>
+
+ <para>QUESTION: Do we even discuss this broken
+ <quote>feature</quote>? Where is it used? Some related code is in
+ <filename>src/Array/Array.h</filename>:2511–2520.</para>
+ </section>
+
+
+ <section id="future_development-distributed_input">
+ <title>Easing Input for Distributed Programs</title>
+
+ <para>Currently, standard input to distributed programs is not
+ supported. Instead input can be passed via command-line arguments,
+ which are replicated to each context. &inform; streams support for
+ input could be added. For context 0, standard input could be
+ used. Other contexts would use a <type>RemoteProxy</type> to
+ distribute the value to the other contests. See <filename
+ class="headerfile">src/Engine/RemoteEngine.h</filename> for example
+ uses of <type>RemoteProxy</type>.</para>
+ </section>
+
+
+ <section id="future_development-cheetah_pooma_consistency">
+ <title>Improving Consistency Between &pooma; and &cheetah;</title>
+
+ <para>Improve the consistency between &cheetah;'s and &pooma;'s
+ configurations. Currently, their defaults differ regarding
+ &cc; exceptions and static/shared libraries.</para>
+ </section>
+
+
+ <section id="future_development-long_term">
+ <title>Very Long Term Development Ideas</title>
+
+ <para>Describe how to write a new configuration file.</para>
+ </section>
+
+ </appendix>
+
+
+ <appendix id="installation">
+ <title>Obtaining and Installing &pooma;</title>
+
+ <para>ADD: Write this section, including extensive instructions
+ for Unix, MS Windows, and MacOS. List the configuration options.
+ Be sure to describe configuring for parallel execution.</para>
+
+ <section id="installation-distributed_computing">
+ <title>Supporting Distributed Computation</title>
+
+ <para>To use multiple processors with &pooma; requires installing
+ the &cheetah; messaging library and an underlying messaging library
+ such as the Message Passing Interface (&mpi;) Communications
+ Library or the &mm; Shared Memory Library. In this section, we
+ first describe how to install &mm;. Read the section only if using
+ &mm;, not &mpi;. Then we describe how to install &cheetah; and
+ configure &pooma; to use it.</para>
+
+ <section id="installation-distributed_computing-mm">
+ <title>Obtaining and Installing the &mm; Shared Memory Library</title>
+
+ <para>&cheetah;, and thus &pooma;, can use Ralf Engelschall's &mm;
+ Shared Memory Library to pass messages between processors. For
+ example, the &author; uses this library on a two-processor
+ computer running &linux;. The library, available at
+ http://www.engelschall.com/sw/mm/, is available for free and has
+ been successfully tested on a variety of Unix platforms.</para>
+
+ <para>We describe how to download and install the &mm; library.
+ <orderedlist spacing="compact">
+ <listitem>
+ <para>Download the library from the &pooma; Download page
+ available off the &pooma; home page (&poomaHomePage;).</para>
+ </listitem>
+ <listitem>
+ <para>Extract the source code using <command>tar xzvf
+ mm-1.1.3.tar.gz</command>. Move into the resulting source
+ code directory <filename
+ class="directory">mm-1.1.3</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Prepare to compile the source code by configuring it
+ using the <command>configure</command> command. To change
+ the default installation directory <filename
+ class="directory">/usr/local</filename>, specify
+ <command>&dashdash;prefix=<replaceable>directory</replaceable></command>
+ option. The other configuration options can be listed by
+ specifying the <command>&dashdash;help</command> option. Since the
+ &author; prefers to keep all &pooma;-related code in his
+ <filename class="directory">pooma</filename>subdirectory, he
+ uses <command>./configure
+ &dashdash;prefix=${HOME}/pooma/mm-1.1.3</command>.</para>
+ </listitem>
+ <listitem>
+ <para>Create the library by issuing the <command>make</command>
+ command. This compiles the source code using a &c; compiler. To
+ use a different compiler than the &mm; configuration chooses, set
+ the <envar>CC</envar> to the compiler before configuring.</para>
+ </listitem>
+ <listitem>
+ <para>Optionally test the library by issuing the <command>make
+ test</command> command. If successful, the penultimate line
+ should be <computeroutput>OK - ALL TESTS SUCCESSFULLY
+ PASSED</computeroutput>.</para>
+ </listitem>
+ <listitem>
+ <para>Install the &mm; Library by issuing the <command>make
+ install</command> command. This copies the library files to the
+ installation directory. The <filename
+ class="directory">mm-1.1.3</filename> directory containing the
+ source code may now be removed.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+
+ <section id="installation-distributed_computing-cheetah">
+ <title>Obtaining and Installing the &cheetah; Messaging Library</title>
+
+ <para>The &cheetah; Library decouples communication from
+ synchronization. Using asynchronous messaging rather than
+ synchronous messaging permits a message sender to operate without
+ the cooperation of the message recipient. Thus, implementing
+ message sending is simpler and processing is more efficiently
+ overlapped with it. Remote method invocation is also supported.
+ The library was developed at the Los Alamos National Laboratory's
+ Advanced Computing Laboratory.</para>
+
+ <para>&cheetah;'s messaging is implemented using an underlying
+ messaging library such as the Message Passing Interface (&mpi;)
+ Communications Library (FIXME: xref linkend="mpi99", <ulink
+ url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) or the &mm;
+ Shared Memory Library. &mpi; works on a wide variety of platforms
+ and has achieved widespread usage. &mm; works under Unix on any
+ computer with shared memory. Both libraries are available for
+ free. The instructions below work for whichever library you
+ choose.</para>
+
+ <para>We describe how to download and install &cheetah;.
+ <orderedlist spacing="compact">
+ <listitem>
+ <para>Download the library from the &pooma; Download page
+ available off the &pooma; home page (&poomaHomePage;).</para>
+ </listitem>
+ <listitem>
+ <para>Extract the source code using <command>tar xzvf
+ cheetah-1.0.tgz</command>. Move into the resulting source code
+ directory <filename
+ class="directory">cheetah-1.0</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Edit a configuration file corresponding to your operating
+ system and compiler. These <filename
+ class="libraryfile">.conf</filename> files are located in the
+ <filename class="directory">config</filename> directory. For
+ example, to use &gcc; with the &linux; operating system, use
+ <filename
+ class="libraryfile">config/LINUXGCC.conf</filename>.</para>
+
+ <para>The configuration file usually does not need
+ modification. However, if you are using &mm;, ensure
+ <varname>shmem_default_dir</varname> specifies its location.
+ For example, the &author; modified the value to
+ <statement>"/home/oldham/pooma/mm-1.1.3"</statement>.</para>
+ </listitem>
+ <listitem>
+ <para>Prepare to compile the source code by configuring it
+ using the <command>configure</command> command. Specify the
+ configuration file using the <command>&dashdash;arch</command> option.
+ Its argument should be the configuration file's name, omitting
+ its <filename class="libraryfile">.conf</filename> suffix. For
+ example, <command>&dashdash;arch LINUXGCC</command>. Some other
+ options include
+ <variablelist>
+ <varlistentry>
+ <term>&dashdash;help</term>
+ <listitem>
+ <para>lists all the available options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;shmem &dashdash;nompi</term>
+ <listitem>
+ <para>indicates use of &mm;, not &mpi;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;mpi &dashdash;noshmem</term>
+ <listitem>
+ <para>indicates use of &mpi;, not &mm;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;opt</term>
+ <listitem>
+ <para>causes the compiler to produce optimized source code</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;noex</term>
+ <listitem>
+ <para>prevents use of &cc; exceptions</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;static</term>
+ <listitem>
+ <para>creates a static library, not a shared library</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;shared</term>
+ <listitem>
+ <para>creates a shared library, not a static library. This
+ is the default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&dashdash;prefix <replaceable>directory</replaceable></term>
+ <listitem>
+ <para>specifies the installation directory where the
+ library will be copied rather than the default.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ For example, the &author; uses <command>./configure &dashdash;arch
+ LINUXGCC &dashdash;shmem &dashdash;nompi &dashdash;noex &dashdash;static &dashdash;prefix
+ ${HOME}/pooma/cheetah-1.0 &dashdash;opt</command>. The
+ <command>&dashdash;arch LINUXGCC</command> indicates use of &gcc;
+ under a &linux; operating system. The &mm; library is used,
+ but &cc; exceptions are not. The latter choice matches
+ &pooma;'s default choice. A static library, not a shared
+ library, is created. This is also &pooma;'s default choice.
+ The library will be installed in the <filename
+ class="directory">${HOME}/pooma/cheetah-1.0</filename>.
+ Finally, the library code will be optimized, hopefully running
+ faster than unoptimized code.</para>
+ </listitem>
+ <listitem>
+ <para>Follow the directions printed by
+ <command>configure</command>: Change directories to the
+ <filename class="directory">lib</filename> subdirectory named
+ by the <command>&dashdash;arch</command> argument and then type
+ <command>make</command> to compile the source code and create
+ the library.</para>
+ </listitem>
+ <listitem>
+ <para>Optionally ensure the library works correctly by issuing
+ the <command>make tests</command> command.</para>
+ </listitem>
+ <listitem>
+ <para>Install the library by issuing the <command>make
+ install</command> command. This copies the library files to
+ the installation directory. The <filename
+ class="directory">cheetah-1.0</filename> directory containing
+ the source code may now be removed.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id="installation-distributed_computing-pooma">
+ <title>Configuring &pooma; When Using &cheetah;</title>
+
+ <para>To use &pooma; with &cheetah;, one must tell &pooma; the
+ location of the &cheetah; library using the
+ <command>&dashdash;messaging</command> configuration option. To do this,
+ <orderedlist spacing="compact">
+ <listitem>
+ <para>Set the &cheetah; directory environment variable
+ <envar>CHEETAHDIR</envar> to the directory containing the
+ installed &cheetah; library. For
+ example, <command>declare -x
+ CHEETAHDIR=${HOME}/pooma/cheetah-1.0</command> specifies the
+ installation directory used in the previous section.</para>
+ </listitem>
+ <listitem>
+ <para>When configuring &pooma;, specify the
+ <command>&dashdash;messaging</command> option. For example,
+ <command>./configure &dashdash;arch LINUXgcc &dashdash;opt
+ &dashdash;messaging</command> configures for &linux;, &gcc;, and an
+ optimized library using &cheetah;.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+ </appendix>
+
+
+ <appendix id="compilation_errors">
+ <title>Dealing with Compilation Errors</title>
+
+ <para>Base this low-priority section on <filename
+ class="libraryfile">errors.html</filename>. QUESTION: Where is
+ <filename class="libraryfile">errors.html</filename>?</para>
+
+ </appendix>
+
+
+ <appendix id="tmp_appendix">
+ <title>TMP: Notes to Myself</title>
+
+ <section id="tmp-miscellaneous">
+ <title>Miscellaneous</title>
+
+ <orderedlist>
+ <listitem>
+ <para>If there is time, present another example program, e.g., a
+ Jacobi solver.</para>
+ </listitem>
+
+ <listitem>
+ <para>If a reference manual for &pooma; implementors is written,
+ begin with a chapter <quote>Under the Hood: How &pooma;
+ Works</quote>, written from the point of view of &cc;
+ interpreter. For &pete;, use the material in
+ <filename>papers/PETE_DDJ/ddj_article.html</filename>, which
+ gives example code and descriptions of how the code works, and
+ see material in <filename
+ class="libraryfile">background.html</filename>'s
+ <quote>Expression Templates.</quote></para>
+ </listitem>
+
+ <listitem>
+ <para>QUESTION: How do &pooma; parallel concepts compare with
+ Fortran D or high-performance Fortran FINISH CITE:
+ {koelbel94:_high_perfor_fortr_handb}?</para>
+ </listitem>
+
+ <listitem>
+ <para>QUESTION: How do I know when to use a type name versus just
+ the concept? For example, when do I use <quote>array</quote>
+ versus &array;?</para>
+ </listitem>
+
+ <listitem>
+ <para>Krylov solvers are described in Section 3.5.2 of
+ <filename>papers/pooma.ps</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Section 5, "The Polygon Overlay Problem," describes
+ porting an <acronym>ANSI</acronym> &c; program to &pooma;.</para>
+ </listitem>
+
+ <listitem>
+ <para>A good example book: <emphasis>STL Tutorial and Reference
+ Guide: &cc; Programming with the Standard Template
+ Library</emphasis>, second edition, by David R. Musser,
+ Gillmer J. Derge, and Atul Sanai, ISBN 0-201-37923-6,
+ QA76.73.C153.M87 2001.</para>
+ </listitem>
+
+ <listitem>
+ <para>One STL reference book listed functions in margin notes,
+ easing finding material. Do this.</para>
+ </listitem>
+
+ <listitem>
+ <para>QUESTION: Does Berna Massingill at Trinity University have
+ any interest ior access to any parallel computers?</para>
+ </listitem>
+ </orderedlist>
+
+ </section>
+
+
+ <section id="tmp-html_tutorials">
+ <title>Existing HTML Tutorials</title>
+
+ <para>All these tutorials are out-of-date, but the ideas and text
+ may still be relevant.</para>
+
+ <variablelist>
+ <varlistentry><term><filename
+ class="libraryfile">index.html</filename></term>
+ <listitem><para>list of all tutorials. No useful
+ material.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">introduction.html</filename></term>
+ <listitem><para>data-parallel Laplace solver using Jacobi
+ iteration ala <command>Doof2d</command></para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">background.html</filename></term>
+ <listitem><para>short, indirect introduction to &pete;; parallel
+ execution model; &cc;; templates; &stl;; expression
+ templates</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-01.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">Layout.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">parallelism.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">self-test.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">threading.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-03.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-04.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-05.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-06.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-07.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-08.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-09.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-10.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-11.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-12.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ <varlistentry><term><filename
+ class="libraryfile">tut-13.html</filename></term>
+ <listitem><para>UNFINISHED</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ </appendix>
+
+
+ <!-- Bibliography -->
+
+ <bibliography id="bibliography">
+ <title>Bibliography</title>
+
+ <para>FIXME: How do I process these entries?</para>
+
+ <biblioentry>
+ <abbrev>mpi99</abbrev>
+ <authorgroup>
+ <author>
+ <firstname>William</firstname><surname>Gropp</surname>
+ </author>
+ <author>
+ <firstname>Ewing</firstname><surname>Lusk</surname>
+ </author>
+ <author>
+ <firstname>Anthony</firstname><surname>Skjellum</surname>
+ </author>
+ </authorgroup>
+ <copyright>
+ <year>1999</year>
+ <holder>Massachusetts Institute of Technology</holder>
+ </copyright>
+ <isbn>0-262-57132-3</isbn>
+ <publisher>
+ <publishername>The MIT Press</publishername>
+ <address>Cambridge, MA</address>
+ </publisher>
+ <title>Using MPI</title>
+ <subtitle>Portable Parallel Programming with the Message-Passing Interface</subtitle>
+ <edition>second edition</edition>
+ </biblioentry>
+ </bibliography>
+
+
+ &glossary-chapter;
+
+ <!-- Index -->
+
+ &genindex.sgm;
+
+ </book>
Index: outline.xml
===================================================================
RCS file: outline.xml
diff -N outline.xml
*** /tmp/cvs1ybeCp Tue Dec 11 13:31:11 2001
--- /dev/null Fri Mar 23 21:37:44 2001
***************
*** 1,4287 ****
- <?xml version="1.0"?>
-
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "file://usr/lib/sgml/docbookx.dtd" [
-
- <!-- Text to Check, Revise, Replace -->
- <!-- FIXME: Revise before releasing. -->
- <!-- UPDATE: Check before publishing to see if any needs changing. -->
- <!-- ADD: Write more material. -->
-
- <!-- Index Entity Declarations -->
- <!ENTITY genindex.sgm SYSTEM "genindex.sgm">
-
- <!-- General Entity Declarations -->
-
- <!ENTITY book "book">
- <!-- Produce a notation for the book/manual/report/WWW page. -->
- <!-- Modify this to the desired noun. -->
- <!ENTITY Book "Book">
- <!-- Produce a capitalized version of &book; -->
- <!-- Modify this to the desired noun. -->
- <!ENTITY c "<application class='software'>C</application>">
- <!-- Produce a notation for the C programming language. -->
- <!-- Modify this to the desired formatting. -->
- <!ENTITY cc "<application class='software'>C++</application>">
- <!-- Produce a notation for the C++ programming language. -->
- <!-- Modify this to the desired formatting. -->
- <!ENTITY cheetah "<application class='software'>Cheetah</application>" >
- <!-- Produce a notation for the Cheetah Library. -->
- <!ENTITY doof2d "<command>Doof2d</command>" >
- <!-- Produce a notation for the Doof2d program. -->
- <!ENTITY make "<application class='software'>Make</application>">
- <!-- Produce a notation for the GNU Make program. -->
- <!ENTITY mm "<application class='software'>MM</application>">
- <!-- Produce a notation for the MM Library. -->
- <!ENTITY mpi "<application class='software'>MPI</application>">
- <!-- Produce a notation for the MPI package. -->
- <!ENTITY pdt "<application class='software'>PDToolkit</application>">
- <!-- Produce a notation for the PDT software package. -->
- <!ENTITY pete "<application class='software'>PETE</application>">
- <!-- Produce a notation for the PETE library. -->
- <!ENTITY pooma "<application class='software'>POOMA</application>">
- <!-- Produce a notation for Pooma software. -->
- <!ENTITY poomaToolkit "<application class='software'>POOMA Toolkit</application>">
- <!-- Produce a notation for the Pooma toolkit. -->
- <!ENTITY purify "<application class='software'>Purify</application>">
- <!-- Produce a notation for the Purify library. -->
- <!ENTITY smarts "<application class='software'>Smarts</application>">
- <!-- Produce a notation for the Smarts software package. -->
- <!-- Modify this after capitalization is decided. -->
- <!ENTITY stl "<application class='software'>STL</application>">
- <!-- Produce a notation for the C++ Standard Template Library software package. -->
- <!ENTITY tau "<application class='software'>Tau</application>">
- <!-- Produce a notation for the Tau software package. -->
-
- <!-- Type Entity Declarations -->
-
- <!ENTITY array "<type>Array</type>">
- <!-- The "Array" type. -->
- <!ENTITY benchmark "<type>Benchmark</type>">
- <!-- The "Benchmark" type. -->
- <!ENTITY brick "<type>Brick</type>">
- <!-- The "Brick" engine type. -->
- <!ENTITY compressiblebrick "<type>CompressibleBrick</type>">
- <!-- The "CompressibleBrick" engine type. -->
- <!ENTITY distributedtag "<type>DistributedTag</type>">
- <!-- The DistributedTag Layout type. -->
- <!ENTITY domain "<type>Domain</type>">
- <!-- The "Domain" type. -->
- <!ENTITY double "<type>double</type>">
- <!-- The C "double" type. -->
- <!ENTITY dynamicarray "<type>DynamicArray</type>">
- <!-- The "DynamicArray" type. -->
- <!ENTITY engine "<type>Engine</type>">
- <!-- The "Engine" type. -->
- <!ENTITY field "<type>Field</type>">
- <!-- The "Field" type. -->
- <!ENTITY interval "<type>Interval</type>">
- <!-- The "Interval" type. -->
- <!ENTITY layout "<type>Layout</type>">
- <!-- The "Layout" type without template parameters. -->
- <!ENTITY leaffunctor "<type>LeafFunctor</type>">
- <!-- The "LeafFunctor" type. -->
- <!ENTITY multipatch "<type>MultiPatch</type>">
- <!-- The "MultiPatch" engine without template parameters. -->
- <!ENTITY replicatedtag "<type>ReplicatedTag</type>">
- <!-- The ReplicatedTag Layout type. -->
- <!ENTITY stencil "<type>Stencil</type>">
- <!-- The "Stencil" type. -->
- <!ENTITY vector "<type>Vector</type>">
- <!-- The "Vector" type. -->
-
- <!-- Mathematical Entity Declarations -->
-
- <!ENTITY n "n">
- <!-- the size of one dimension of an array -->
-
- <!-- System and Operating System Entity Declarations -->
- <!ENTITY gcc "<application>g++</application>">
- <!-- The GNU Compiler Collection C++ compiler. -->
- <!ENTITY kcc "<application>KCC</application>">
- <!-- The KAI C++ compiler. -->
- <!ENTITY linux "<application>Linux</application>">
- <!-- The Linux operating system. -->
-
- <!-- &pooma; URLs and Files -->
-
- <!ENTITY poomaDownloadPage '<ulink url="http://pooma.codesourcery.com/pooma/download">http://pooma.codesourcery.com/pooma/download</ulink>'>
- <!-- The WWW page supporting downloading the &pooma; source code. -->
- <!-- UPDATE this URL. -->
- <!ENTITY poomaHomePage '<ulink url="http://www.pooma.com/">http://www.pooma.com/</ulink>'>
- <!-- The canonical Pooma home page. -->
- <!-- UPDATE this filename. -->
- <!ENTITY poomaSource "pooma-2.3.0">
- <!-- The Pooma source code directory. -->
- <!ENTITY poomaSourceFile "&poomaSource;.tgz">
- <!-- The Pooma source code archive. -->
- <!ENTITY poomaExampleDirectory "examples/Manual">
- <!-- The directory holding this manual's example codes. -->
-
- <!-- Spelling and Formatting Decisions -->
- <!ENTITY author "author">
- <!-- A word describing an author xor authors. -->
- <!-- spelling: element-wise, not elementwise -->
- <!-- phrase: function object, not functor -->
- <!-- spelling: multidimensional, not multi-dimensional -->
- <!-- spelling: multiprocessor, not multi-processor -->
- <!-- spelling: nonzero, not non-zero -->
-
- <!-- External File Entities -->
- <!ENTITY doof2d-c-element SYSTEM "./programs/Doof2d-C-element-annotated.cpp">
- <!-- hand-coded Doof2d implementation -->
- <!ENTITY doof2d-array-element SYSTEM "./programs/Doof2d-Array-element-annotated.cpp">
- <!-- Array element-wise Doof2d implementation -->
- <!ENTITY doof2d-array-parallel SYSTEM "./programs/Doof2d-Array-parallel-annotated.cpp">
- <!-- Array data-parallel Doof2d implementation -->
- <!ENTITY doof2d-array-stencil SYSTEM "./programs/Doof2d-Array-stencil-annotated.cpp">
- <!-- Array stencil Doof2d implementation -->
- <!ENTITY doof2d-array-distributed SYSTEM "./programs/Doof2d-Array-distributed-annotated.cpp">
- <!-- distributed Array stencil Doof2d implementation -->
- ]>
-
- <book>
- <bookinfo>
- <title>&pooma;</title>
- <subtitle>A &cc; Toolkit for High-Performance Parallel Scientific Computing</subtitle>
- <author><firstname>Jeffrey</firstname><othername
- role='mi'>D.</othername><surname>Oldham</surname>
- <affiliation>
- <orgname>CodeSourcery, LLC</orgname>
- </affiliation>
- </author>
- <copyright><year>2001</year><holder>CodeSourcery, LLC (<ulink url="http://www.codesourcery.com"></ulink>)</holder></copyright>
- <contractsponsor>Los Alamos National Laboratory<ulink url="http://www.lanl.gov"></ulink></contractsponsor>
- <legalnotice>
- <!-- FIXME: What is the correct legal notice? -->
- <para>All rights reserved. This document may not be redistributed in any form without the express permission of the author.</para>
- </legalnotice>
- <revhistory>
- <revision>
- <revnumber>0.01</revnumber>
- <date>2001 Nov 26</date>
- <authorinitials>jdo</authorinitials>
- <revremark>first draft</revremark>
- </revision>
- </revhistory>
- </bookinfo>
-
- <!-- FINISH: May we have a short table of contents followed by a -->
- <!-- complete table of contents? -->
-
- <preface id="preface">
- <title>Preface</title>
-
- <para>FINISH: Describe the target audience for &pooma; programs and
- for this manual: &cc; programmers writing scientific code, possibly
- parallel execution.</para>
-
- <para>Assume familiarity with &cc; template programming and the
- standard template library. FIXME: Remove this index
- entry.<indexterm id="oldham"><primary>Oldham,
- Jeffrey D.</primary></indexterm></para>
-
- <section id="preface-notation">
- <title>Notation</title>
-
- <para>UNFINISHED</para>
- </section>
-
-
- <section id="preface-reading_book:">
- <title>How to Read This &Book;</title>
-
- <para>FINISH: Write this section in a style similar to Lamport's
- LaTeX section 1.2. FINISH: Fix the book title and the section
- number.</para>
- </section>
-
-
- <section id="preface-downloading">
- <title>Obtaining &pooma; and Sample Programs</title>
-
- <para>Available for free from what WWW site? Include what portions
- of <filename class="libraryfile">LICENSE</filename>? Be sure to
- include CVS instructions as well.</para>
-
- <para>Which additional packages are necessary and when?</para>
-
- </section>
-
-
- <section id="preface-using_modifying">
- <title>Using and Modifying &pooma;</title>
-
- <para>&pooma; is available under open source license. It can be
- used and modified by anyone, anywhere. Can it be sold? Include
- <filename class="libraryfile">LICENSE</filename>.</para>
-
- <para>QUESTION: How do developers contribute code?</para>
-
- </section>
-
- </preface>
-
-
- <part id="programming">
- <title>Programming with &pooma;</title>
-
- <chapter id="introduction">
- <title>Introduction</title>
-
- <para>QUESTION: Add a partintro to the part above?</para>
-
- <para>&pooma; abbreviates <quote>Parallel Object-Oriented Methods
- and Application</quote>.</para>
-
- <para>This document is an introduction to &pooma; v2.1, a &cc;
- toolkit for high-performance scientific computation. &pooma;
- runs efficiently on single-processor desktop machines,
- shared-memory multiprocessors, and parallel supercomputers
- containing dozens or hundreds of processors. What's more, by making
- extensive use of the advanced features of the ANSI/ISO &cc;
- standard—particularly templates—&pooma; presents a
- compact, easy-to-read interface to its users.</para>
-
- <para>From Section of
- <filename>papers/iscope98.pdf</filename>:</para>
-
- <para>Scientific software developers have struggled with the need
- to express mathematical abstractions in an elegant and maintainable
- way without sacrificing performance. The &pooma; (Parallel
- Object-Oriented Methods and Applications) framework, written in
- <acronym>ANSI</acronym>/<acronym>ISO</acronym> &cc;, has
- demonstrated both high expressiveness and high performance for
- large-scale scientific applications on platforms ranging from
- workstations to massively parallel supercomputers. &pooma; provides
- high-level abstractions for multidimensional arrays, physical
- meshes, mathematical fields, and sets of particles. &pooma; also
- exploits techniques such as expression templates to optimize serial
- performance while encapsulating the details of parallel
- communication and supporting block-based data compression.
- Consequently, scientists can quickly assemble parallel simulation
- codes by focusing directly on the physical abstractions relevant to
- the system under study and not the technical difficulties of
- parallel communication and machine-specific optimization.</para>
-
- <para>ADD: diagram of science and &pooma;. See the diagram that
- Mark and I wrote.</para>
-
-
- <section id="introduction-pooma_evolution">
- <title>Evolution of &pooma;</title>
-
- <para>QUESTION: Is this interesting? Even if it is, it should be
- short.</para>
-
- <para>The file <filename>papers/SCPaper-95.html</filename>
- describes ?&pooma;1? and its abstraction layers.</para>
-
- <para>The "Introduction" of
- <filename>papers/Siam0098.ps</filename> describes the DoE's
- funding motivation for &pooma;: Accelerated Strategic Computing
- Initiative (ASCI) and Science-based Stockpile Stewardship (SBSS),
- pp. 1–2.</para>
-
- <para>See list of developers on p. 1 of
- <filename>papers/pooma.ps</filename>.</para>
-
- <para>See list of developers on p. 1 of
- <filename>papers/pooma.ps</filename>. See history and motivation
- on p. 3 of <filename>papers/pooma.ps</filename>.</para>
-
- <para>Use <filename class="libraryfile">README</filename> for
- information.</para>
-
- <blockquote>
- <attribution><filename
- class="libraryfile">introduction.html</filename></attribution>
-
- <para>&pooma; was designed and implemented by scientists working
- at the Los Alamos National Laboratory's Advanced Computing
- Laboratory. Between them, these scientists have written and tuned
- large applications on almost every commercial and experimental
- supercomputer built in the last two decades. As the technology
- used in those machines migrates down into departmental computing
- servers and desktop multiprocessors, &pooma; is a vehicle for its
- designers' experience to migrate as well. In particular,
- &pooma;'s authors understand how to get good performance out of
- modern architectures, with their many processors and multi-level
- memory hierarchies, and how to handle the subtly complex problems
- that arise in real-world applications.</para>
- </blockquote>
-
- </section>
-
- </chapter>
-
-
- <chapter id="tutorial">
- <title>A Tutorial Introduction</title>
-
- <para>UPDATE: In the following paragraph, fix the cross-reference
- to the actual section.</para>
-
- <para>&pooma; provides different containers and processor
- configurations and supports different implementation styles, as
- described in <xref linkend="introduction"></xref>. In this
- chapter, we present several different implementations of the
- &doof2d; two-dimensional diffusion simulation program:
- <itemizedlist spacing="compact">
- <listitem>
- <para>a C-style implementation omitting any use of &pooma;
- computing each array element individually,</para>
- </listitem>
- <listitem>
- <para>a &pooma; &array; implementation computing each array
- element individually,</para>
- </listitem>
- <listitem>
- <para>a &pooma; &array; implementation using data-parallel
- statements,</para>
- </listitem>
- <listitem>
- <para>a &pooma; &array; implementation using stencils, which
- support local computations,</para>
- </listitem>
- <listitem>
- <para>a stencil-based &pooma; &array; implementation supporting
- computation on multiple processors</para>
- </listitem>
- <listitem>
- <para>a &pooma; &field; implementation using data-parallel
- statements, and</para>
- </listitem>
- <listitem>
- <para>a data-parallel &pooma; &field; implementation for
- multi-processor execution.</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>These illustrate the &array;, &field;, &engine;, layout,
- mesh, and domain data types. They also illustrate various
- immediate computation styles (element-wise accesses, data-parallel
- expressions, and stencil computation) and various processor
- configurations (one sequential processor and multiple
- processors).</para>
-
- <figure float="1" id="tutorial-doof2d_averagings">
- <title>&doof2d; Averagings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/doof2d.201" format="EPS" align="center"></imagedata>
- </imageobject>
- <textobject>
- <phrase>The Initial Configuration</phrase>
- </textobject>
- </mediaobject>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/doof2d.202" format="EPS"></imagedata>
- </imageobject>
- <textobject>
- <phrase>After the First Averaging</phrase>
- </textobject>
- </mediaobject>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/doof2d.203" format="EPS"></imagedata>
- </imageobject>
- <textobject>
- <phrase>After the Second Averaging</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The &doof2d; diffusion program starts with a two-dimensional
- grid of values. To model an initial density, all grid values are
- zero except for one nonzero value in the center. Each averaging,
- each grid element, except the outermost ones, updates its value by
- averaging its value and its eight neighbors. To avoid overwriting
- grid values before all their uses occur, we use two arrays, reading
- the first and writing the second and then reversing their roles
- within each iteration.</para>
-
- <para>Figure <xref linkend="tutorial-doof2d_averagings"></xref>
- illustrates the averagings. Initially, only the center element has
- nonzero value. To form the first averaging, each element's new
- value equals the average of its and its neighbors' previous values.
- Thus, the initial nonzero value spreads to a three-by-three grid.
- The averaging continues, spreading to a five-by-five grid of
- nonzero values. Values in outermost grid cells are always
- zero.</para>
-
- <para>Before presenting various implementations of %doof2d;, we
- explain how to install the &poomaToolkit;.</para>
-
- <para>REMOVE: &doof2d; algorithm and code is illustrated in
- Section 4.1 of
- <filename>pooma-publications/pooma.ps</filename>. It includes a
- figure illustrating parallel communication of data.</para>
-
- <section id="tutorial-installation">
- <title>Installing &pooma;</title>
-
- <para>ADD: How does one install &pooma; using Windows or Mac?</para>
-
- <para>UPDATE: Make a more recent &pooma; source code file
- available on &poomaDownloadPage;. For example,
- <quote>LINUXgcc.conf</quote> is not available.</para>
-
- <para>In this section, we describe how to obtain, build, and
- install the &poomaToolkit;. We focus on installing under the
- Unix operating system. Instructions for installing on computers
- running Microsoft Windows or MacOS, as well as more extensive
- instructions for Unix, appear in <xref
- linkend="installation"></xref>.</para>
-
- <para>Obtain the &pooma; source code <filename
- path="http://www.codesourcery.com/pooma/downloads_folder/">&poomaSourceFile;</filename>
- from the &pooma; download page (&poomaDownloadPage;) available off
- the &pooma; home page (&poomaHomePage;). The <quote>tgz</quote>
- indicates this is a compressed tar archive file. To extract the
- source files, use <command>tar xzvf &poomaSourceFile;</command>.
- Move into the source code directory <filename
- class="directory">&poomaSource;</filename> directory; e.g.,
- <command>cd &poomaSource;</command>.</para>
-
- <para>Configuring the source code prepares the necessary paths for
- compilation. First, determine a configuration file in
- corresponding to your operating system and compiler in the
- <filename class="directory">config/arch/</filename> directory.
- For example, <filename
- class="libraryfile">LINUXgcc.conf</filename> supports compiling
- under a &linux; operating system with &gcc; and <filename
- class="libraryfile">SGI64KCC.conf</filename> supports compiling
- under a 64-bit <application>SGI</application> Unix operating
- system with &kcc;. Then, configure the source code:
- <command>./configure --arch LINUXgcc --opt --suite
- LINUXgcc-opt</command>. The architecture argument to the
- <command>--arch</command> option is the name of the corresponding
- configuration file, omitting its <filename
- class="libraryfile">.conf</filename> suffix. The
- <command>--opt</command> indicates the &poomaToolkit; will
- contain optimized source code, which makes the code run more
- quickly but may impede debugging. Alternatively, the
- <command>--debug</command> option supports debugging. The
- <glossterm linkend="glossary-suite_name">suite name</glossterm>
- can be any arbitrary string. We chose
- <command>LINUXgcc-opt</command> to remind us of the architecture
- and optimization choice. <filename
- class="libraryfile">configure</filename> creates subdirectories
- named by the suite name <quote>LINUXgcc-opt</quote> for use when
- compiling the source files. Comments at the beginning of
- <filename
- class="libraryfile">lib/<replaceable>suiteName</replaceable>/PoomaConfiguration.h</filename>
- record the configuration arguments.</para>
-
- <para>To compile the source code, set the
- <envar>POOMASUITE</envar> environment variable to the suite name
- and then type <command>make</command>. To set the environment
- variable for the <application>bash</application> shell use
- <command>export
- POOMASUITE=<replaceable>suiteName</replaceable></command>,
- substituting the suite name's
- <replaceable>suiteName</replaceable>. For the
- <application>csh</application> shell, use <command>setenv
- POOMASUITE LINUXgcc-opt</command>. Issuing the
- <command>make</command> command compiles the &pooma; source code
- files to create the &pooma; library. The &pooma; makefiles assume
- the <trademark>GNU</trademark> &make; so substitute the proper
- command if necessary. The &pooma; library can be found in, e.g.,
- <filename
- class="libraryfile">lib/LINUXgcc-opt/libpooma-gcc.a</filename>.</para>
- </section>
-
- <section id="tutorial-hand_coded">
- <title>Hand-Coded Implementation</title>
-
- <para>Before implementing &doof2d; using the &poomaToolkit;, we
- present a hand-coded implementation of &doof2d;. See <xref
- linkend="tutorial-hand_coded-doof2d"></xref>. After querying the
- user for the number of averagings, the arrays' memory is
- allocated. Since the arrays' size is not known at compile time,
- the arrays are accesses via pointers to allocated dynamic memory.
- This memory is deallocated at the program's end to avoid memory
- leaks. The arrays are initialized with initial conditions. For
- the <varname>b</varname> array, all values except the central ones
- have nonzero values. Only the outermost values of the
- <varname>a</varname> array need be initialized to zero, but we
- instead initialize them all using the loop used by
- <varname>b</varname>.</para>
-
- <para>The simulation's kernel consists of triply nested loops.
- The outermost loop controls the number of iterations. The inner
- nested loops iterate through the arrays' elements, excepting the
- outermost elements; note the loop indices range from 1 to n-2
- while the array indices range from 0 to n-1. Each
- <varname>a</varname> value is assigned the average of its
- corresponding value in <varname>b</varname> and the latter's
- neighbors. Values in the two-dimensional grids are accessed using
- two sets of brackets, e.g., <statement>a[i][j]</statement>. After
- assigning values to <varname>a</varname>, a second averaging reads
- values in <varname>a</varname>, writing values in
- <varname>b</varname>.</para>
-
- <para>After the kernel finishes, the final central value is
- printed. If the desired number of averagings is even, the value
- in <varname>b</varname> is printed; otherwise, the value in
- <varname>a</varname> is used. Finally, the dynamically-allocated
- memory must be freed to avoid memory leaks.</para>
-
- <example id="tutorial-hand_coded-doof2d">
- <title>Hand-Coded Implementation of &doof2d;</title>
- &doof2d-c-element;
- <calloutlist>
- <callout arearefs="tutorial-hand_coded-doof2d-nuaveragings">
- <para>The user specifies the desired number of averagings.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-array_storage">
- <para>These variables point to the two-dimensional,
- dynamically-allocated grids so we use a pointer to a pointer to
- a &double;.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-grid_size">
- <para>The user enters the desired grid size. The grid will be
- a square with <varname>n</varname> by <varname
- lang="c++">n</varname> grid cells.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-allocation">
- <para>Memory for the arrays is allocated. By default, the
- array indices are zero-based.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-initialization">
- <para>Initially, all grid values are zero except for the one
- nonzero value at the center of the second array. Array
- positions are indicated using two brackets, e.g.,
- <statement>a[i][j]</statement>. A better implementation might
- initialize only the outermost values of the
- <varname>a</varname> array.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-constants">
- <para>These constants indicate the number of iterations, and
- the average weighting.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-first_write">
- <para>Each <varname>a</varname> value, except an outermost one,
- is assigned the average of its analogous <varname>b</varname>
- value and that value's neighbors. Note the loop indices ensure
- the outermost values are not changed. The
- <varname>weight</varname>'s value ensures the computation is an
- average.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-second_write">
- <para>The second averaging computes <varname>b</varname>'s
- values using values stored in <varname>a</varname>.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-answer">
- <para>After the averagings finish, the central value is printed.</para>
- </callout>
- <callout arearefs="tutorial-hand_coded-doof2d-deallocation">
- <para>The dynamically-allocated memory must be deallocated to
- avoid memory leaks.</para>
- </callout>
- </calloutlist>
- </example>
-
- <para>To compile the executable, change directories to the &pooma;
- <filename
- class="directory">&poomaExampleDirectory;/Doof2d</filename>
- directory. Ensure the <envar>POOMASUITE</envar> environment
- variable specifies the desired suite name
- <replaceable>suiteName</replaceable>, as we did when compiling
- &pooma; in the previous section <xref
- linkend="tutorial-installation"></xref>. Issuing the
- <command>make Doof2d-C-element</command> command creates the
- executable
- <command><replaceable>suiteName</replaceable>/Doof2d-C-element</command>.</para>
-
- <para>When running the executable, specify the desired a
- nonnegative number of averagings and the nonnegative number of
- grid cells along any dimension. The resulting grid has the same
- number of cells along each dimension. After the executable
- finishes, the resulting value of the central element is
- printed.</para>
- </section>
-
-
- <section id="tutorial-array_elementwise">
- <title>Element-wise &array; Implementation</title>
-
- <para>The simplest way to use the &poomaToolkit; is to
- use the &pooma; &array; class instead of &c; arrays. &array;s
- automatically handle memory allocation and deallocation, support a
- wider variety of assignments, and can be used in expressions.
- <xref linkend="tutorial-array_elementwise-doof2d"></xref>
- implements &doof2d; using &array;s and element-wise accesses.
- Since the same algorithm is used as <xref
- linkend="tutorial-hand_coded-doof2d"></xref>, we will concentrate
- on the differences.</para>
-
- <example id="tutorial-array_elementwise-doof2d">
- <title>Element-wise &array; Implementation of &doof2d;</title>
- &doof2d-array-element;
- <calloutlist>
- <callout arearefs="tutorial-array_elementwise-doof2d-header">
- <para>To use &pooma; &array;s, the <filename
- class="headerfile">Pooma/Arrays.h</filename> must be included.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-pooma_initialize">
- <para>The &poomaToolkit; structures must be constructed before
- their use.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-domain">
- <para>Before creating an &array;, its domain must be specified.
- The <varname>N</varname> interval represents the
- one-dimensional integral set {0, 1, 2, …, n-1}. An
- <type>Interval<2></type> object represents the entire
- two-dimensional index domain.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-array_creation">
- <para>An &array;'s template parameters indicate its dimension,
- its value type, and how the values will be stored or computed.
- The &brick; &engine; type indicates values will be directly
- stored. It is responsible for allocating and deallocating
- storage so <statement>new</statement> and
- <statement>delete</statement> statements are not necessary.
- The <varname>vertDomain</varname> specifies the array index
- domain.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-initialization">
- <para>The first statement initializes all &array; values to the
- same scalar value. This is possible because each &array;
- <quote>knows</quote> its domain. The second statement
- illustrates &array; element access. Indices, separated by
- commas, are surrounded by parentheses rather than surrounded by
- square brackets (<statement>[]</statement>).</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-first_write">
- <para>&array; element access uses parentheses, rather than
- square brackets</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-blockAndEvaluate">
- <para>&pooma; may reorder computation of statements. Calling
- <function>Pooma::blockAndEvaluate</function> ensures all
- computation finishes before accessing a particular array
- element.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-deallocation">
- <para>Since &array;s are first-class objects, they
- automatically deallocate any memory they require, eliminating
- memory leaks.</para>
- </callout>
- <callout arearefs="tutorial-array_elementwise-doof2d-pooma_finish">
- <para>The &poomaToolkit; structures must be destructed after
- their use.</para>
- </callout>
- </calloutlist>
- </example>
-
- <para>We describe the use of &array; and the &poomaToolkit; in
- <xref linkend="tutorial-array_elementwise-doof2d"></xref>.
- &array;s, declared in the <filename
- class="headerfile">Pooma/Arrays.h</filename>, are first-class
- objects. They <quote>know</quote> their index domain, can be used
- in expressions, can be assigned scalar and array values, and
- handle their own memory allocation and deallocation.</para>
-
- <para>The creation of the <varname>a</varname> and
- <varname>b</varname> &array;s requires an object specifying their
- index domains. Since these are two-dimensional arrays, their
- index domains are also two dimensional. The two-dimensional
- <type>Interval<2></type> object is the Cartesian product of
- two one-dimensional <type>Interval<1></type> objects, each
- specifying the integral set {0, 1, 2, …, n-1}.</para>
-
- <para>An &array;'s template parameters indicate its dimension, the
- type of its values, and how the values are stored. Both
- <varname>a</varname> and <varname>b</varname> are two-dimension
- arrays storing &double;s so their <varname>dimension</varname>
- is 2 and its element type is &double;. An &engine; stores an
- &array;'s values. For example, a &brick; &engine; explicitly
- stores all values. A &compressiblebrick; &engine; also explicitly
- stores values if more than value is present, but, if all values
- are the same, storage for just that value is required. Since an
- engine can store its values any way it desires, it might instead
- compute its values using a function or compute the values stored
- in separate engines. In practice, most explicitly specified
- &engine;s are either &brick; or &compressiblebrick;.</para>
-
- <para>&array;s support both element-wise access and scalar
- assignment. Element-wise access uses parentheses, not square
- brackets. For example, <statement>b(n/2,n/2)</statement>
- specifies the central element. The scalar assignment <statement>b
- = 0.0</statement> assigns the same 0.0 value to all array
- elements. This is possible because the array knows the extent of
- its domain.</para>
-
- <para>After the kernel finishes, the central value is printed out.
- Just prior to this &array; access, a call to
- <statement>Pooma::blockAndEvaluate()</statement> ensures all
- computation has finished. &pooma; may reorder computation or
- distribute them among various processors. Before reading an
- individual &array; value, <function>blockAndEvaluate</function>
- ensures the value has the correct value. Calling this function is
- necessary only when accessing individual array elements because
- &pooma; cannot determine when to call the function itself. For
- example, before printing an array, &pooma; will call
- <function>blockAndEvaluate</function> itself.</para>
-
- <para>Any program using the &poomaToolkit; must initialize the
- toolkit's data structures using
- <statement>Pooma::initialize(argc,argv)</statement>. This
- extracts &pooma;-specific command-line options from the
- command-line arguments in <varname>argv</varname> and initializes
- the inter-processor communication and other data structures. When
- finished, <statement>Pooma::finalize()</statement> ensures all
- computation has finished and the communication and other data
- structures are destructed.</para>
- </section>
-
-
- <section id="tutorial-data_parallel">
- <title>Data-Parallel &array; Implementation</title>
-
- <para>&pooma; supports data-parallel &array; accesses. Many
- algorithms are more easily expressed using data-parallel
- expressions. Also, the &poomaToolkit; might be able to reorder
- the data-parallel computations to be more efficient or distribute
- them among various processors. In this section, we concentrate
- the differences between the data-parallel implementation of
- &doof2d; listed in <xref
- linkend="tutorial-array_parallel-doof2d"></xref> and the
- element-wise implementation listed in the previous section <xref
- linkend="tutorial-array_elementwise"></xref>.</para>
-
- <example id="tutorial-array_parallel-doof2d">
- <title>Data-Parallel &array; Implementation of &doof2d;</title>
- &doof2d-array-parallel;
- <calloutlist>
- <callout arearefs="tutorial-array_parallel-doof2d-innerdomain">
- <para>These variables specify one-dimensional domains {1, 2,
- …, n-2}. Their Cartesian product specifies the domain
- of the array values that are modified.</para>
- </callout>
- <callout arearefs="tutorial-array_parallel-doof2d-first_write">
- <para>Data-parallel expressions replace nested loops and array
- element accesses. For example, <statement>a(I,J)</statement>
- represents the subset of the <varname>a</varname> array having
- a domain equal to the Cartesian product of <varname>I</varname>
- and <varname>J</varname>. Intervals can shifted by an additive
- or multiplicative constant.</para>
- </callout>
- </calloutlist>
- </example>
-
- <para>Data-parallel expressions apply domain objects to containers
- to indicate a set of parallel expressions. For example, in the
- program listed above, <statement>a(I,J)</statement> specifies all
- of <varname>a</varname> array excepting the outermost elements.
- The array's <varname>vertDomain</varname> domain consists of the
- Cartesian product of {0, 1, 2, …, n-1} and itself, while
- <varname>I</varname> and <varname>J</varname> each specify {1, 2,
- …, n-2}. Thus, <statement>a(I,J)</statement> is the subset
- with a domain of the Cartesian product of {1, 2, …, n-2}
- and itself. It is called a <firstterm>view</firstterm> of an
- array. It is itself an array, with a domain and supporting
- element access, but its storage is the same as
- <varname>a</varname>'s. Changing a value in
- <statement>a(I,J)</statement> also changes the same value in
- <varname>a</varname>. Changing a value in the latter also changes
- the former if the value is not one of <varname>a</varname>'s
- outermost elements. The expression
- <statement>b(I+1,J+1)</statement> indicates the subset of
- <varname>b</varname> with a domain consisting of the Cartesian
- product of {2, 3, …, n-1}, i.e., the same domain as
- <statement>a(I,J)</statement> but shifted up one unit and to the
- right one unit. Only an &interval;'s value, not its name, is
- important. Thus, all uses of <varname>J</varname> in this program
- could be replaced by <varname>I</varname> without changing the
- semantics.</para>
-
- <figure float="1" id="tutorial-array_parallel-doof2d-adding_arrays">
- <title>Adding &array;s</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/doof2d.210" format="EPS" align="center"></imagedata>
- </imageobject>
- <textobject>
- <phrase>Adding two arrays with different domains.</phrase>
- </textobject>
- <caption>
- <para>When adding arrays, values in corresponding positions are
- added even if they have different indices, indicated by the
- small numbers adjacent to the arrays.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>The statement assigning to <statement>a(I,J)</statement>
- illustrates that &array;s may participate in expressions. Each
- addend is a view of an array, which is itself an array. Each view
- has the same domain size so their sum can be formed by
- corresponding elements of each array. For example, the lower,
- left element of the result equals the sum of the lower, left
- elements of the addend arrays. For the computation, indices are
- ignored; only the relative positions within each domain are used.
- <xref
- linkend="tutorial-array_parallel-doof2d-adding_arrays"></xref>
- illustrates adding two arrays with different domain indices. The
- indices are indicated by the small numbers to the left and the
- bottom of the arrays. Even though 9 and 3 have different indices
- (1,1) and (2,0), they are added to each other because they have
- the same relative positions within the addends.</para>
- </section>
-
-
- <section id="tutorial-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
- function object and an indication of the stencil's extent.</para>
-
- <example id="tutorial-array_stencil-doof2d">
- <title>Stencil &array; Implementation of &doof2d;</title>
- &doof2d-array-stencil;
- <calloutlist>
- <callout arearefs="tutorial-array_stencil-doof2d-stencil">
- <para>A stencil is a function object implementing a local
- operation on an &array;.</para>
- </callout>
- <callout
- arearefs="tutorial-array_stencil-doof2d-stencil_operator">
- <para>&pooma; applies this function call
- <function>operator()</function> to the interior domain of an
- &array;. Although not strictly necessary, the function's
- template parameter <varname>C</varname> permits using this
- stencil with &array;s and other containers. The
- <function>read</function> &array; member function supports only
- reading values, not writing values, thus possibly permitting
- faster access.</para>
- </callout>
- <callout arearefs="tutorial-array_stencil-doof2d-stencil_extent">
- <para>These two functions indicate the stencil's size. For
- each dimension, the stencil extends one cell to the left of (or
- below) its center and also one call to the right (or above) its
- center.</para>
- </callout>
- <callout
- arearefs="tutorial-array_stencil-doof2d-stencil_creation">
- <para>Create the stencil.</para>
- </callout>
- <callout arearefs="tutorial-array_stencil-doof2d-first_write">
- <para>Applying <varname>stencil</varname> to the
- <varname>b</varname> array and a subset
- <varname>interiorDomain</varname> of its domain yields an
- array, which is assigned to a subset of <varname>a</varname>.
- The stencil's function object is applied to each position in
- the specified subset of <varname>b</varname>.</para>
- </callout>
- </calloutlist>
- </example>
-
- <para>Before we describe how to create a stencil, we describe how
- to apply a stencil to an array, yielding values. To compute the
- value associated with index position (1,3), the stencil's center
- is placed at (1,3). The stencil's
- <function>upperExtent</function> and
- <function>lowerExtent</function> functions indicate which &array;
- values the stencil's function will use. See <xref
- linkend="tutorial-array_stencil-doof2d-apply_stencil"></xref>.
- Applying the stencil's function call
- <function>operator()</function> yields the computed value. To
- compute multiple &array; values, apply a stencil to the array and
- a domain object: <statement>stencil(b,
- interiorDomain)</statement>. This applies the stencil to each
- position in the domain. The user must ensure that applying the
- stencil does not access nonexistent &array; values.</para>
-
- <figure float="1" id="tutorial-array_stencil-doof2d-apply_stencil">
- <title>Applying a Stencil to an &array;</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/doof2d.211" format="EPS" align="center"></imagedata>
- </imageobject>
- <textobject>
- <phrase>Apply a stencil to position (1,3) of an array.</phrase>
- </textobject>
- <caption>
- <para>To compute the value associated with index position (1,3)
- of an array, place the stencil's center, indicated with dashed
- lines, at the position. The computation involves the array
- values covered by the array and delineated by
- <function>upperExtent</function> and
- <function>lowerExtent</function>.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>To create a stencil object, apply the &stencil; type to a
- function object class. For example,
- <statement>Stencil<DoofNinePt> stencil</statement> declares
- the <varname>stencil</varname> object. The function object class
- must define a function call <function>operator()</function> with a
- container parameter and index parameters. The number of index
- parameters, indicating the stencil's center, must equal the
- container's dimension. For example, <type>DoofNinePt</type>
- defines <methodname>operator()(const C& c, int i, int
- j)</methodname>. We templated the container type
- <varname>C</varname> although this is not strictly necessary. The
- two index parameters <varname>i</varname> and <varname>j</varname>
- ensure the stencil works with two-dimensional containers. The
- <methodname>lowerExtent</methodname> indicates how far to the left
- (or below) the stencil extends beyond its center. Its parameter
- indicates a particular dimension. Index parameters
- <varname>i</varname> and <varname>j</varname> are in dimension 0
- and 1. <methodname>upperExtent</methodname> serves an
- analogous purpose. The &poomaToolkit; uses these functions when
- distribution computation among various processors, but it does not
- use these functions to ensure nonexistent &array; values are not
- accessed. Caveat stencil user!</para>
- </section>
-
-
- <section id="tutorial-distributed">
- <title>Distributed &array; Implementation</title>
-
- <para>A &pooma; program can execute on one or multiple processors.
- To convert a program designed for uniprocessor execution to a
- program designed for multiprocessor execution, the programmer need
- only specify how each container's domain should be split into
- <quote>patches</quote>. The &poomaToolkit; automatically
- distributes the data among the available processors and handles
- any required communication between processors.</para>
-
- <example id="tutorial-array_distributed-doof2d">
- <title>Distributed Stencil &array; Implementation of &doof2d;</title>
- &doof2d-array-distributed;
- <calloutlist>
- <callout arearefs="tutorial-array_distributed-doof2d-nuprocessors">
- <para>The number of processors executing a &pooma; program can
- be specified at run-time.</para>
- </callout>
- <callout arearefs="tutorial-array_distributed-doof2d-layout">
- <para>The <type>UniformGridPartition</type> declaration
- specifies how an array's domain will be partition, of split,
- into patches. Guard layers are an optimization that can reduce
- data communication between patches. The
- <type>UniformGridLayout</type> declaration applies the
- partition to the given domain, distributing the resulting
- patches among various processors.</para>
- </callout>
- <callout arearefs="tutorial-array_distributed-doof2d-remote">
- <para>The <type>MultiPatch</type> &engine; distributes requests
- for &array; values to the associated patch. Since a patch may
- associated with a different processor, its
- <quote>remote</quote> engine has type
- <type>Remote<Brick></type>. &pooma; automatically
- distributes the patches among available memories and
- processors.</para>
- </callout>
- <callout
- arearefs="tutorial-array_distributed-doof2d-first_write">
- <para>The stencil computation, whether for one processor or
- multiple processors, is the same.</para>
- </callout>
- </calloutlist>
- </example>
-
- <para>Supporting distributed computation requires only minor code
- changes. These changes specify how each container's domain is
- distributed among the available processors. The rest of the
- program, including all the computations, remains the same. When
- running, the &pooma; executable interacts with the run-time
- library to determine which processors are available, distributes
- the containers' domains, and automatically handles all necessary
- interprocessor communication. The same executable runs on one or
- many processors. Thus, the programmer can write one program,
- debugging it on a uniprocessor computer and running it on a
- supercomputer.</para>
-
- <figure float="1" id="tutorial-array_distributed-doof2d-distributed_model">
- <title>The &pooma; Distributed Computation Model</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/distributed.101" format="EPS" align="center"></imagedata>
- </imageobject>
- <textobject>
- <phrase>the &pooma; distributed computation model.</phrase>
- </textobject>
- <caption>
- <para>The &pooma; distributed computation model combines
- partitioning containers' domains and the computer configuration
- to create a layout.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>&pooma;'s distributed computing model separates container
- domain concepts from computer configuration concepts. See <xref
- linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>.
- The program indicates how each container's domain will be
- partitioned. This process is represented in the upper left corner
- of the figure. A user-specified partition specifies how to split
- the domain into pieces. For example, the illustrated partition
- splits the domain into three equal-sized pieces along the
- x-dimension and two equal-sized pieces along the y-dimension.
- Thus, the domain is split into <firstterm>patches</firstterm>.
- The partition also specifies external and internal guard layers.
- A <firstterm>guard layer</firstterm> is a domain surrounding a
- patch. A patch's computation only reads but does not write these
- values. An <firstterm>external guard layer</firstterm>
- conceptually surrounds the entire container domain with boundary
- values whose presence permits all domain computations to be
- performed the same way even for values along the domain's edge.
- An <firstterm>internal guard layer</firstterm> duplicates values
- from adjacent patches so communication 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 between processor. Their use
- is not required.</para>
-
- <para>The computer configuration of shared memory and processors
- is determined by the run-time system. See the upper right portion
- of <xref
- linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>.
- A <firstterm>context</firstterm> is a collection of shared memory
- and processors that can execute a program or a portion of a
- program. For example, a two-processor desktop computer might have
- memory accessible to both processors so it is a context. A
- supercomputer consisting of desktop computers networked together
- might have as many contexts as computers. The run-time system,
- e.g., the Message Passing Interface (&mpi;) Communications Library
- (FIXME: xref linkend="mpi99", <ulink
- url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) or the &mm;
- Shared Memory Library (<ulink
- url="http://www.engelschall.com/sw/mm/"></ulink>), communicates
- the available contexts to the executable. &pooma; must be
- configured for the particular run-time system. See <xref
- linkend="installation-distributed_computing"></xref>.</para>
-
- <para>A <firstterm>layout</firstterm> combines patches with
- contexts so the program can be executed. If &distributedtag; is
- specified, the patches are distributed among the available
- contexts. If &replicatedtag; is specified, each set of patches is
- replicated among each context. Regardless, the containers'
- domains are now distributed among the contexts so the program can
- run. When a patch needs data from another patch, the &pooma;
- toolkit sends messages to the desired patch uses a message-passing
- library. All such communication is automatically performed by the
- toolkit with no need for programmer or user input.</para>
-
- <para>FIXME: The two previous paragraphs demonstrate confusion
- between <quote>run-time system</quote> and <quote>message-passing
- library</quote>.</para>
-
- <para>Incorporating &pooma;'s distributed computation model into a
- program requires writing very few lines of code. <xref
- linkend="tutorial-array_distributed-doof2d"></xref> illustrates
- this. The <varname>partition</varname> declaration creates a
- <type>UniformGridPartition</type> splitting each dimension of a
- container's domain into equally-sized
- <varname>nuProcessors</varname> pieces. The first
- <type>GuardLayers</type> argument specifies each patch will have
- copy of adjacent patches' outermost values. This may speed
- computation because a patch need not synchronize its computation
- with other patches' processors. Since each value's computation
- requires knowing its surrounding neighbors, the internal guard
- layer is one layer deep. The second <type>GuardLayers</type>
- argument specifies no external guard layer. External guard layers
- simplify computing values along the edges of domains. Since the
- program already uses only the interior domain for computation, we
- do not use this feature.</para>
-
- <para>The <varname>layout</varname> declaration creates a
- <type>UniformGridLayout</type> layout. As <xref
- linkend="tutorial-array_distributed-doof2d"></xref> illustrates,
- it needs to know a container's domain, a partition, the computer's
- contexts, and a &distributedtag; or &replicatedtag;. These
- comprise <varname>layout</varname>'s three parameters; the
- contexts are implicitly supplied by the run-time system.</para>
-
- <para>To create a distributed &array;, it should be created using
- a &layout; object and have a &multipatch; engine. Prior
- implementations designed for uniprocessors constructed the
- container using a &domain; object. A distributed implementation
- uses a &layout; object, which conceptually specifies a &domain;
- object and its distribution throughout the computer. A
- &multipatch; engine supports computations using multiple patches.
- The <type>UniformTag</type> indicates the patches all have the
- same size. Since patches may reside on different contexts, the
- second template parameter is <type>Remote</type>. Its
- <type>Brick</type> template parameter specifies the engine for a
- particular patch on a particular context. Most distributed
- programs use <type>MultiPatch<UniformTag, Remote<Brick>
- ></type> or <type>MultiPatch<UniformTag,
- Remote<CompressibleBrick> ></type> engines.</para>
-
- <para>The computations for a distributed implementation are
- exactly the same as for a sequential implementation. The &pooma;
- Toolkit and a message-passing library automatically perform all
- computation.</para>
-
- <para>The command to run the programs is dependent on the run-time
- system. To use &mpi; with the Irix 6.5 operating system, one
- can use the <command>mpirun</command> command. For example,
- <statement>mpirun -np 9 Doof2d-Array-distributed -mpi
- --num-patches 3</statement> invokes the &mpi; run-time system with
- nine processors. The <statement>-mpi</statement> argument tells
- the &pooma; executable <command>Doof2d-Array-distributed</command>
- to use the &mpi; Library.
-
- HERE
-
- The command <statement>Doof2d-Array-distributed -shmem -np 2
- --num-patches 2</statement>
-
- To run <command>Doof2d-Array-distributed</command> with the &mm;
- Shared Memory Library, use
-
- HERE</para>
-
- <!-- HERE -->
-
- <para>COMMENT: See <filename
- class="libraryfile">background.html</filename> for a partial
- explanation. A <firstterm>context</firstterm> is a distinct
- region of memory in some computer. Execution thread is associated
- with each context. One or more different processors can be
- associated with the same context.</para>
-
- <para>QUESTION: How do &pooma; parallel concepts compare with
- Fortran D or high-performance Fortran FINISH CITE:
- {koelbel94:_high_perfor_fortr_handb}?</para>
-
- <para>QUESTION: What does Cheetah do for us? Must configure with
- --messaging and Cheetah library must be available. When running
- Doof2d benchmark, use --num-patches N. On LinuxKCC, use
- '--num-patches p --run-impls 14 --sim-params N 0 1'. Runtime
- system must also provide some support. How do I write about this?
- What is an example? How does one install Cheetah?</para>
-
- <!-- HERE -->
- </section>
-
-
- <section id="tutorial-relations">
- <title>Relations</title>
-
- <para>UNFINISHED</para>
-
- </section>
-
- </chapter>
-
-
- <chapter id="concepts">
- <title>Overview of &pooma; Concepts</title>
-
- <para>Describe the software application layers similar to
- <filename>papers/SCPaper-95.html</filename> and "Short Tour of
- &pooma;" in <filename>papers/SiamOO98_paper.ps</filename>.
- Section 2.2, "Why a Framework?," of
- <filename>papers/pooma.ps</filename> argues why a layered approach
- eases use. Section 3.1, "Framework Layer Description,"
- describes the five layers.</para>
-
- <para>FINISH: Write short glossary entries for each of these.</para>
-
- <para>FINISH: Look through the source code to ensure all main
- concepts are listed.</para>
-
- <para>Here are (preliminary) &pooma; equations:</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&pooma; <quote>Equations</quote></title>
-
- <tgroup cols="1" align="center">
- <tbody>
- <row>
- <entry><para>field = data + materials + centering + layout + mesh</para></entry>
- </row>
- <row>
- <entry><para>map from space to values</para></entry>
- </row>
- <row>
- <entry><para>array = data + layout</para></entry>
- </row>
- <row>
- <entry><para>map from indices to values</para></entry>
- </row>
- <row>
- <entry><para>mesh = layout + origin + spacings</para></entry>
- </row>
- <row>
- <entry><para>distribute domain through physical space</para></entry>
- </row>
- <row>
- <entry><para>layout = domain + partition + layout_tag (distributed/replicated)</para></entry>
- </row>
- <row>
- <entry><para>distribute domain's blocks among processors/contexts</para></entry>
- </row>
- <row>
- <entry><para>partition = blocks + guard layers</para></entry>
- </row>
- <row>
- <entry><para>split domain into blocks</para></entry>
- </row>
- <row>
- <entry><para>domain = newDomain</para></entry>
- </row>
- <row>
- <entry><para>space of permissible indices</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <para>FINISH: Following is a first try at describing the &pooma;
- abstraction layers. See also paper illustration.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&pooma; Abstraction Layers</title>
-
- <tgroup cols="1" align="center">
- <tbody>
- <row>
- <entry><para>application program</para></entry>
- </row>
- <row>
- <entry><para>&array; &field; (should have
- <type>FieldEngine</type> under it)</para></entry>
- </row>
- <row>
- <entry><para>&engine;</para></entry>
- </row>
- <row>
- <entry><para>evaluators</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>FINISH: How does parallel execution fit in?</para>
-
- <para>FINISH: Should we also name and describe each layer?</para>
-
- <section id="concepts-domains">
- <title>Domains</title>
-
- <blockquote>
- <attribution>Section 4 "Future Improvements in
- &pooma; II" of
- <filename>papers/SiamOO98_paper.ps</filename></attribution>
- <para>
- A &domain; is a set of discrete points in some space.…
- &domain;s provide all of the expected domain calculus
- capabilities such as subsetting and intersection.
- </para>
- </blockquote>
-
- <para>Section 3, "Domains and Views," of
- <filename>papers/iscope98.pdf</filename> describes five types of
- domains</para>
- </section>
-
-
- <section id="concepts-layouts">
- <title>Layouts</title>
-
- <para>UNFINISHED</para>
-
- <para>Also describe partitions and guard cells within here.</para>
-
- </section>
-
-
- <section id="concepts-meshes">
- <title>Meshes</title>
-
- <para>UNFINISHED</para>
- </section>
-
-
- <section id="concepts-data_parallel">
- <title>Data-Parallel Statements</title>
-
- <para>Can we use "An Overview of &pete;" from
- <filename>papers/PETE_DDJ/ddj_article.html</filename> or is this
- too low-level?</para>
-
- <para>Section 3.2.1 of <filename>papers/pooma.ps</filename>
- gives a simple example of data-parallel expression. It also has a
- paragraph introducing data-parallel operations and selecting
- subsets of domains. Section 3.4 describes the Chained
- Expression Object (<acronym>CEO</acronym>), apparently a precursor
- of &pete;. Regardless, it provides some motivation and
- introductory material.</para>
-
- <para>From Section 4 of
- <filename>papers/SiamOO98_paper.ps</filename>:</para>
-
- <para>This version of &pete; reduces compile time of user codes
- and utilizes compile-time knowledge of expression &domain;s for
- better optimization. For example, more efficient loops for
- evaluating an expression can be generated if &pete; knows that the
- &domain; has unit stride in memory.</para>
-
- <para>Section 4, "Expressions and Evaluators", of
- <filename>papers/iscope98.pdf</filename> has a good explanation of
- &pooma; II's expression trees and expression engines.</para>
-
- <para>COMMENT: <filename
- class="libraryfile">background.html</filename> has some related
- &pete; material.</para>
- </section>
-
- <section id="concepts-containers">
- <title>Containers</title>
-
- <section id="concepts-containers-array">
- <title>&array;</title>
-
- <blockquote>
- <attribution>Section 4 "Future Improvements in
- &pooma; II" of
- <filename>papers/SiamOO98_paper.ps</filename></attribution>
- <para>
- An &array; can be thought of as a map from one &domain; to
- another.… &array;s depend only on the interface of
- &domain;s. Thus, a subset of view of an &array; can be
- manipulated in all the same ways as the original &array;.
- &array;s can perform indirect addressing because the output
- &domain; one one &array; can be used as the input &domain; of
- another &array;. &array;s also provide individual element
- access.</para>
- </blockquote>
-
-
- <para>
- (unformatted) From
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>:
- The &pooma; &array; concept provides an example of how these
- generic-programming features can lead to flexible and efficient
- code. An Array maps a fairly arbitrary input domain to an
- arbitrary range of outputs. When used by itself, an &array;
- object <varname>A</varname> refers to all of the values in its
- domain. Element-wise mathematical operations or functions can be
- applied to an array using straightforward notation, like A + B
- or sin(A). Expressions involving Array objects are themselves
- Arrays. The operation A(d), where d is a domain object that
- describes a subset of A's domain, creates a view of A that
- refers to that subset of points. Like an array expression, a
- view is also an Array. If d represents a single point in the
- domain, this indexing operation returns a single value from the
- range. Equivalently, one can index an N-dimensional Array by
- 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
- types. Both support the notion of views of a portion of the
- array, known as array sections in F90. The &pooma; Array concept
- supports more complex domains, including bounded, continuous
- (floating-point) domains. Furthermore, Array indexing in &pooma;
- is polymorphic; that is, the indexing operation X(i1,i2) can
- perform the mapping from domain to range in a variety of ways,
- depending on the particular type of the Array being
- indexed.</para>
-
- <para>Fortran arrays are dense and the elements are arranged
- according to column-major conventions. Therefore, X(i1,i2)
- refers to element number i1-1+(i2-1)*numberRowsInA. However, as
- Fig. 1 shows, Fortran-style "Brick" storage is not the only
- storage format of interest to scientific programmers. For
- compatibility with C conventions, one might want to use an array
- featuring dense, row-major storage (a C-style Brick). To save
- memory, it might be advantageous to use an array that only
- stores a single value if all its element values are the
- same. Other sparse storage schemes that only store certain
- values may also be desirable. To exploit parallelism, it is
- convenient for an array's storage to be broken up into patches,
- which can be processed independently by different CPUs. Finally,
- one can imagine an array with no data at all. For example, the
- values can be computed from an expression involving other
- arrays, or analytically from the indices.
- </para>
-
- <para>The &pooma; &array; Class Template</para>
-
- <para>Next we describe &pooma;'s model of the Array concept, the
- Array class template. The three most important requirements from
- the point of view of overall design are: (1) arbitrary domain,
- (2) arbitrary range, and (3) polymorphic indexing. These express
- themselves in the template parameters for the &pooma; Array
- class. The template
- <programlisting>
- template <int Dim, class T = double, class EngineTag = Brick>
- class Array;
- </programlisting>
- is a specification for creating a set of classes all named
- Array. The template parameters Dim, T, and EngineTag determine
- the precise type of the Array. Dim represents the dimension of
- the array's domain. T gives the type of array elements, thereby
- defining the output range of the array. EngineTag specifies the
- the manner of indexing and types of the indices.</para>
-
- <para>End From
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
-
- <para>Section 2, "Arrays and Engines," of
- <filename>papers/iscope98.pdf</filename> describes both &array;s
- and &engine;s. This may or may not duplicate the material in
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>.</para>
-
- <section id="concepts-containers-array-views">
- <title>Views of &array;s</title>
-
- <para>Section 3, "Domains and Views," of
- <filename>papers/iscope98.pdf</filename> motivates the need for
- views:
- <blockquote>
- <para>One of the primary uses of domains is to specify
- subsections of &array; objects. Subarrays are a common
- feature of array classes; however, it is often difficult to
- make such subarrays behave like first-class objects. The
- &pooma; II engine concept provides a clean solution to
- this problem: subsetting an &array; with a domain object
- creates a new &array; that has a view engine.</para>
- </blockquote>
- </para>
- </section>
- </section>
-
- <section id="concepts-containers-field">
- <title>&field;</title>
-
- <para>QUESTION: Do we include boundary conditions here?
-
- FINISH: Do we have an example that shows something not possible
- with &array;?</para>
-
- <para>Describe and illustrate multi-material and
- multivalue?</para>
-
- <para>ADD: description of meshes and guard layers.</para>
-
- </section>
-
-
- <section id="concepts-containers-matrix">
- <title><type>TinyMatrix</type></title>
-
- <para>Section 3.2.2 of
- <filename>papers/pooma.ps</filename> describes &vector;s and
- matrix classes.</para>
- </section>
- </section>
-
- <section id="concepts-engines">
- <title>Engines</title>
-
- <para>(unformatted) From
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
-
- <para>The Engine Concept</para>
-
- <para>To implement polymorphic indexing, the Array class defers
- data storage and data lookup to an engine object. The requirements
- that the Array template places on its engine provide the
- definition for the Engine concept. We'll describe these by
- examining a simplified version of the Array template, shown in
- Fig. 2.</para>
-
- <para>First, the Array class determines and exports (makes
- Engine_t part of Array's public interface) the type of the engine
- class that it will use:
- <programlisting>
- typedef Engine<Dim, T, EngineTag> Engine_t;
- </programlisting>
- This statement declares Engine_t to be an alias for the type
- Engine<Dim,T,EngineTag>. This is the first requirement
- placed on engine classes: they must be specializations of a
- general Engine template whose template parameters are identical to
- those of Array. Next, the Array template determines the type of
- scalar arguments (indices) to be used in operator(), the function
- that implements &pooma;'s Fortran-style indexing syntax X(i1,i2):
- <programlisting>
- typedef typename Engine_t::Index_t Index_t;
- </programlisting>
- This statement defines another type alias:
- Array<Dim,T,EngineTag>::Index_t is simply an alias for
- Engine_t::Index_t. Engine_t::Index_t is a qualified name, which
- means that the type Index_t is found in the class Engine_t. This
- is the second requirement for the Engine concept: the class
- Engine_t must define a public type called Index_t. This line will
- not compile if that definition is not supplied. This indirection
- is one of the ways that &pooma; supports polymorphic indexing. If
- the Engine works with a discrete integer domain, it defines its
- Index_t to be an integral type. If the Engine works in a
- continuous domain, it defines its Index_t to be a floating-point
- type.</para>
-
- <para>The data lookup is performed in the operator() function. We
- see that Array simply passes the indices on to its engine
- object. Thus, we have the third requirement for the Engine
- concept: it must provide a version of operator() that takes Dim
- values of type Index_t.</para>
-
- <para>Simply passing the indices on to the engine object may seem
- odd. After all, engine(i,j) looks like we're just indexing another
- array. There are several advantages to this extra level of
- indirection. The Array class is as faithful a model of the Array
- concept as possible, while the Engine class is a low-level
- interface to a user-defined data source. As a result, Array has a
- wide variety of constructors for user convenience, while engines
- have but a few. Array supports a wide variety of overloaded
- operator() functions for view creation and indexing. Engines
- support indexing only. Array does not have direct access to the
- data, which is managed by the engine object. Finally, Array has a
- wide variety of overloaded mathematical operators and functions,
- and works with the Portable Expression Template Engine (PETE) [4]
- to provide efficient evaluation of Array expressions. Engines have
- no such support. In general, Array is much more complex and
- feature-laden than Engine. This is the prime advantage of the
- separation of interface and implementation: Array only has to be
- implemented once by the &pooma; developers. Engines are simple
- enough to be written by users and plugged directly into the Array
- framework.</para>
-
- <para>Figure 3 illustrates the "Brick" specialization of the
- Engine template, which implements Fortran-style lookup into a
- block of memory. First, there is the general Engine template,
- which is empty as there is no default behavior for an unknown
- EngineTag. The general template is therefore not a model for the
- Engine concept and Array classes attempting to use it will not
- compile. Next, there is the definition of the Brick class, a
- policy tag whose sole purpose is to select a particular
- specialization of the Engine template. Finally, there is the
- partial specialization of the Engine template. Examining its body,
- we see the required Index_t typedef and the required operator(),
- which follows the Fortran prescription for generating an offset
- into the data block based on the row, column, and the number of
- rows. All of the requirements are met, so the Brick-Engine class
- is a model of the Engine concept.</para>
-
- <para>End From
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
-
- <para>(unformatted) From
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>:</para>
-
- <para>Compile-time Versus Run-Time Polymorphism</para>
-
- <para>Encapsulating the indexing in an Engine class has important
- advantages, both in terms of flexibility and efficiency. To
- illustrate this point, we introduce the PolarGaussian-Engine
- specialization in Fig. 4. This is an analytic engine that
- calculates its values directly from its inputs. Unlike the
- Brick-Engine, this engine is "indexed" with data of the same type
- as its output: it maps a set of T's to a single T. Therefore, the
- Index_t typedef selects T as the index type, as opposed to the int
- in the Brick-Engine specialization. The operator() function also
- differs in that it computes the return value according to an
- analytic formula.</para>
-
- <para>Both Engine<Dim,T,Brick> and
- Engine<Dim,T,PolarGaussian> can be plugged in to an Array by
- simply varying the Array's EngineTag. This is possible despite the
- fact that the two classes exhibit dramatically different behavior
- because they are both models of the Engine concept.</para>
-
- <para>Notice that we have achieved polymorphic indexing without
- the use of inheritance or virtual functions. For instance,
- consider the following code snippet:
- <programlisting>
- Array<2, double, Brick> a;
- Array<2, double, PolarGaussian> b;
-
- double x = a(2, 3); // x = a.engine.data[2 + 3 * a.engine.numRows];
- double y = b(2.0, 3.0); // y = exp(-(2.0*2.0+3.0*3.0) / b.engine.delta);
- </programlisting>
- The data lookup functions for the two Arrays perform completely
- different operations. Since this is accomplished using static
- types, it is known as compile-time polymorphism. Moreover,
- everything is known at compile time, so the functions are fully
- inlined and optimized, thereby yielding code equivalent to that
- shown in the comments above.</para>
-
- <para>The flexibility and efficiency of compile-time polymorphism
- cannot be duplicated with a run-time implementation. To illustrate
- this point, in Fig. 5, we re-implement our Array concept using the
- classic Envelope-Letter pattern [5], with the array class,
- RTArray, being the envelope and the run-time-engine, RTEngine,
- being the letter. RTArray defers data lookup to the engine object
- by invoking the engine's functions through a pointer to the
- RTEngine base class. Figure 6 illustrates the RTEngine base class
- and Fig. 7 illustrates two descendants: RTBrick and
- RTPolarGaussian.</para>
-
- <para>The run-time implementation provides the same basic
- functionality as the compile-time implementation, but it is not as
- flexible or as efficient. It lacks flexibility in that the return
- type of the indexing operation must be specified in the RTEngine
- base class and in the RTArray class. Thus, in Figs. 5 and 6,we see
- versions of RTArray::operator() and RTEngine::index functions that
- take both int's and T's. If the programmer wants to add another
- index-type option, these classes must be modified. This is a
- violation of the open-closed principle proposed by Meyer
- [6]. Also, since RTEngine descendants will usually only implement
- one version of index, we cannot make RTEngine an abstract base
- class. Instead, we have the default versions of index throw an
- exception. Thus, compile-time error checking is
- weakened. Furthermore, since indexing is done via a virtual
- function call, it will almost never be inlined, which is not
- acceptable in most scientific applications.</para>
-
- <para>There are advantages to the Envelope-Letter approach. First,
- all RTArray objects have the same type, allowing them to be stored
- in homogeneous collections. This can simplify the design of some
- applications. Second, RTArray objects can change their engines at
- runtime, and thus effectively change their types on the fly??this
- is the primary reason for using the Envelope-Letter idiom, and can
- be very important in some applications.</para>
-
- <para>For most scientific applications, however, these issues are
- minor, and maximum performance for array indexing is of paramount
- importance. Our compile-time approach achieves this performance
- while providing the desired polymorphic indexing.</para>
-
- <para>From Section 4 of
- <filename>papers/SiamOO98_paper.ps</filename>:</para>
-
- <para>The &array; class is templated on an &engine; type that
- handles the actual implementation of the mapping from input to
- output. Thus, the &array; interface features are completely
- separate from the implementation, which could be a single &c;
- array, a function of some kind or some other mechanism. This
- flexibility allows an expression itself to be viewed through the
- &array; interface. Thus, one can write something like
- <programlisting>
- foo(A*B+C);
- </programlisting> where <varname>A</varname>, <varname>B</varname> and
- <varname>C</varname> are &array;s and <function>foo</function> is
- a function taking an &array; as an argument. The expression
- <statement><varname>A</varname>*<varname>B</varname>+<varname>C</varname></statement>
- will only be evaluated by the expression engine as needed by
- <function>foo</function>.</para>
-
- <para>In fact, one can even write &engine;s which are wrappers
- around external data structures created in non-&pooma; codes and
- know to manipulate these structures. Once this is done, the
- external entities have access to the entire &array; interface and
- can utilize all of the powerful features of
- &pooma; II.</para>
-
- <para>Section 2, "Arrays and Engines," of
- <filename>papers/iscope98.pdf</filename> describes both &array;s
- and &engine;s. This may or may not duplicate the material in
- <filename>papers/GenericProgramming_CSE/dubois.html</filename>.</para>
-
- <para>Section 4, "Expressions and Evaluators", of
- <filename>papers/iscope98.pdf</filename> has a good explanation of
- &pooma; II's expression trees and expression engines.</para>
-
- <variablelist>
- <varlistentry><term><type>MultiPatch</type> Engine</term>
- <listitem><para>From <filename
- class="libraryfile">README</filename>: To actually use multiple
- contexts effectively, you need to use the MultiPatch engine with
- patch engines that are Remote engines. Then the data will be
- distributed across multiple contexts instead of being copied on
- every context. See the files in example/Doof2d for a simple
- example that creates a MultiPatch array that can be distributed
- across multiple contexts and performs a stencil computation on
- that array.</para></listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-
- <section id="concepts-relations">
- <title>Relations</title>
-
- <para>UNFINISHED</para>
- </section>
-
-
- <section id="concepts-stencils">
- <title>Stencils</title>
-
- <para>Section 3.5.4, "Stencil Objects," of
- <filename>papers/pooma.ps</filename> provides a few uses of
- stencils.</para>
-
- <para>Section 5, "Performance," of
- <filename>papers/iscope98.pdf</filename> motivates and explains
- stencils.</para>
- </section>
-
-
- <section id="concepts-contexts">
- <title>Contexts</title>
-
- <blockquote>
- <attribution><filename
- class="libraryfile">background.html</filename></attribution>
- <para>In order to be able to cope with the variations in machine
- architecture noted above, &pooma;'s distributed execution model
- is defined in terms of one or more contexts, each of which may
- host one or more threads. A context is a distinct region of
- memory in some computer. The threads associated with the context
- can access data in that memory region and can run on the
- processors associated with that context. Threads running in
- different contexts cannot access memory in other contexts.</para>
-
- <para>A single context may include several physical processors,
- or just one. Conversely, different contexts do not have to be on
- separate computers—for example, a 32-node SMP computer could
- have up to 32 separate contexts. This release of &pooma; only
- supports a single context for each application, but can use
- multiple threads in the context on supported platforms. Support
- for multiple contexts will be added in an upcoming
- release.</para>
- </blockquote>
- </section>
-
-
- <section id="concepts-utilities">
- <title>Utility Types: ???TITLE??</title>
-
- <section id="concepts-containers-vector">
- <title>&vector;</title>
-
- <para>Section 3.2.2 of
- <filename>papers/pooma.ps</filename> describes &vector;s and
- matrix classes.</para>
- </section>
-
- </section>
- </chapter>
-
-
- <chapter id="sequential">
- <title>Writing Sequential Programs</title>
-
- <para>UNFINISHED</para>
-
- <section id="sequential-benchmarks">
- <title>&benchmark; Programs</title>
-
- <para>Define a &benchmark; program vs. an example or an
- executable. Provide a short overview of how to run these
- programs. Provide an overview of how to write these programs.
- See <filename
- class="headerfile">src/Utilities/Benchmark.h</filename>.</para>
- </section>
-
-
- <section id="sequential-inform">
- <title>Using <type>Inform</type>s for Output</title>
-
- <para>UNFINISHED</para>
- </section>
-
- </chapter>
-
-
- <chapter id="parallel">
- <title>Writing Distributed Programs</title>
-
- <para>Discuss the distributed model and guard cells. See <filename
- class="libraryfile">docs/parallelism.html</filename>.</para>
-
- <para>Does any of the parallel implementation described in
- <filename>papers/SCPaper-95.html</filename> still apply?</para>
-
- <para>?Tuning program for maximize parallel performance?</para>
-
- <para>external references to &mpi; and threads</para>
-
- <para>QUESTION: Are there interesting, short parallel programs in
- any &mpi; book that we can convert to &pooma;?</para>
-
- <section>
- <title>Layouts</title>
-
- <para>An out-of-date description can be found in Section 3.3,
- especially 3.3.2, of <filename>papers/pooma.ps</filename>
- describes the global/local interactions and parallel abstraction
- layers.</para>
- </section>
-
- <section>
- <title>Parallel Communication</title>
-
- <para>An out-of-date description can be found in
- Section 3.3.3 of <filename>papers/pooma.ps</filename></para>
- </section>
-
- <section>
- <title>Using Threads</title>
-
- <para>QUESTION: Where do threads fit into the manual? Do threads
- even work?</para>
-
- <para>From Section 4, of
- <filename>papers/SiamOO98_paper.ps</filename></para>
-
- <para>&pooma; II will make use of a new parallel run-time
- system called &smarts; that is under development at the ACL.
- &smarts; supports lightweight threads, so the evaluator will be
- able to farm out data communication tasks and the evaluation of
- subsets of an expression to multiple threads, thus increasing the
- overlap of communication and computation. Threads will also be
- available at the user level for situations in which a
- task-parallel approach is deemed appropriate.</para>
- </section>
-
- </chapter>
-
-
- <chapter id="under_the_hood">
- <title>Under the Hood: How &pooma; Works</title>
-
- <para>from point of view of &cc; interpreter</para>
-
- <section id="under_the_hood-PETE">
- <title>&pete;</title>
-
- <para>Use the material in
- <filename>papers/PETE_DDJ/ddj_article.html</filename>, which gives
- example code and descriptions of how the code works.</para>
-
- <para>See material in <filename
- class="libraryfile">background.html</filename>'s <quote>Expression
- Templates.</quote></para>
- </section>
-
- </chapter>
-
-
- <chapter id="debugging_profiling">
- <title>Debugging and Profiling &pooma; Programs</title>
-
- <para>UNFINISHED</para>
-
- </chapter>
-
-
- <chapter id="example">
- <title>Example Program: Jacobi Solver</title>
-
- <para>QUESTION: Is this chapter necessary? Do we have enough
- existing source code to write this chapter?</para>
-
- </chapter>
- </part>
-
- <part id="reference">
- <title>&pooma; Reference Manual</title>
-
- <chapter id="tmp_ref">
- <title>TMP: This Chapter Holds These Comments But Will Be Removed</title>
-
- <para>For each template parameter need to describe the constraints
- on it.</para>
-
- <para>Remove this section when the following concerns have been
- addressed.</para>
-
- <para>Add a partintro explaining file suffixes such as <filename
- class="headerfile">.h</filename>, <filename
- class="libraryfile">.cpp</filename>, <filename
- class="libraryfile">.cmpl.cpp</filename>, <filename
- class="libraryfile">.mk</filename>, <filename
- class="libraryfile">.conf</filename>. Should we also explain use
- of <literal>inline</literal> even when necessary and the template
- model, <!-- FIXME: s/literal/keyword/ --> e.g., including <filename
- class="libraryfile">.cpp</filename> files.</para>
-
- <para>QUESTION: What are the key concepts around which to organize
- the manual?</para>
-
- <para>QUESTION: What format should the manual use?</para>
-
- <blockquote>
- <attribution>Musser, Derge, and Sanai, §20.0.</attribution>
- <para>It is important to state the requirements on the components
- as generally as possible. For example, instead of saying
- <quote>class <type>X</type> must define a member function
- <function>operator++()</function>,</quote> we say <quote>for any
- object <varname>x</varname> of type <type>X</type>,
- <classname>++x</classname> is defined.</quote></para>
- </blockquote>
- </chapter>
-
-
- <chapter id="class_structure_ref">
- <title>A Typical &pooma; Class</title>
-
- <variablelist>
- <title>Class Member Notation</title>
- <varlistentry>
- <term><fieldsynopsis>
- <varname>*_t</varname>
- </fieldsynopsis>
- </term>
- <listitem>
- <para>type within a class. QUESTION: What is the &cc; name for
- this?</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><fieldsynopsis>
- <varname>*_m</varname>
- </fieldsynopsis>
- </term>
- <listitem>
- <para>data member</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <title>&pooma; Class Vocabulary</title>
- <varlistentry>
- <term>component</term>
- <listitem>
- <para>one of several values packaged together. For example, a
- three-dimensional vector has three components, i.e., three
- values.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>element-wise</term>
- <listitem>
- <para>applied to each element in the group, e.g., an array</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>reduction</term>
- <listitem>
- <para>repeated application of a binary operator to all elements,
- yielding one value</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>tag</term>
- <listitem>
- <para>an enumerated value indicating inclusion in a particular
- semantic class. The set of values need not be explicitly
- declared.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </chapter>
-
-
- <chapter id="installing_configuring_ref">
- <title>Installing and Configuring &pooma;</title>
-
- <orderedlist>
- <listitem>
- <para>Installing &pooma;.</para>
- </listitem>
- <listitem>
- <para>Requirements for configuration files.</para>
- </listitem>
- </orderedlist>
-
- <para>Include descriptions of using &smarts;, &cheetah;, τ,
- &pdt;.</para>
-
- <para>QUESTION: Does it install on windows and on mac? If so, what
- are the instructions? See also <filename
- class="libraryfile">INSTALL.{mac,unix,windows}.</filename></para>
-
- <para><filename class="libraryfile">README</filename> has some
- information on &cheetah; and threads in the <quote>Message-Based
- Parallelism</quote> section.</para>
-
- <para>Which additional packages are necessary and when?</para>
-
- <para>What configure options should we list? See <filename
- class="libraryfile">configure</filename>. Be sure to list
- debugging option and how its output relates to <filename
- class="libraryfile">config/LINUXgcc.suite.mk</filename>.</para>
-
- <para><filename class="directory">config/arch</filename> has files
- for (OS, compiler) pairs. Explain how to modify a configuration
- file. List requirements when making a new configuration file (low
- priority).</para>
-
- <para><filename
- class="libraryfile">config/LINUXgcc.suite.mk</filename> has output
- from <filename class="libraryfile">configure</filename>. Useful to
- relate to configuration files and <filename
- class="libraryfile">configure</filename>'s debugging output.</para>
-
- </chapter>
-
-
- <chapter id="compilation_ref">
- <title>Compilation and &make; Files</title>
-
- <para>We assume Gnu make. Do we know what assumptions are made?</para>
-
- <para>How do all these files interact with each other? Ala a make
- interpreter, give an example of which files are read and
- when.</para>
-
- <variablelist>
- <varlistentry><term><filename
- class="libraryfile">config/Shared/README.make</filename></term>
- <listitem><para>This has short descriptions of many files,
- especially in <filename
- class="directory">config/Shared</filename>.</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">makefile</filename></term>
- <listitem><para>These appear throughout all directories. What are
- the equivalences classes and what are their
- parts?</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">include.mk</filename></term>
- <listitem><para>What does this do? Occurs in many directories:
- when? Template seems to be <filename
- class="libraryfile">config/Shared/include2.mk</filename>.</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">subdir.mk</filename></term>
- <listitem><para>list of subdirectories; occurs in several
- directories: when? <filename
- class="libraryfile">src/subdir.mk</filename> is a good
- example.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><filename class="libraryfile">objfile.mk</filename></term>
- <listitem>
- <para>list of object files to construct, presumably from
- <filename>*.cmpl.cpp</filename> files.
- <filename>src/Utilities/objfile.mk</filename> is an
- example.</para>
- </listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">config/Shared/rules.mk</filename></term>
- <listitem><para>most compiler rules</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">config/head.mk</filename></term>
- <listitem><para>read at beginning of each
- makefile?</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">config/Shared/tail.mk</filename></term>
- <listitem><para>read at end of each makefile?</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">config/Shared/variables.mk</filename></term>
- <listitem><para>Is this used?</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">config/Shared/compilerules.mk</filename></term>
- <listitem><para>table of origin and target suffixes and commands
- for conversion</para></listitem>
- </varlistentry>
-
- </variablelist>
-
- </chapter>
-
-
- <chapter id="arrays_ref">
- <title>&array;s</title>
-
- <para>Include <filename
- class="headerfile">src/Pooma/Arrays.h</filename> to use &array;s.
- The implementation source code is in <filename
- class="directory">src/Array</filename>.</para>
-
- <para>FINISH: Define an array. Introduce its parts.</para>
-
- <para>ADD: some mention of the maximum supported number of
- dimensions somewhere.</para>
-
- <section id="arrays_ref-array">
- <title>The &array; Container</title>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Template Parameters</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Parameter</entry>
- <entry>Interpretation</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><varname>Dim</varname></entry>
- <entry><para>dimension</para></entry>
- </row>
- <row>
- <entry><varname>T</varname></entry>
- <entry><para>array element type</para></entry>
- </row>
- <row>
- <entry>EngineTag</entry>
- <entry><para>type of computation engine object</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>QUESTION: How do I introduce class type definitions, when
- they are used, i.e., compile-time or run-time, and when
- programmers should use them?</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Compile-Time Types and Values</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Type or Value</entry>
- <entry>Interpretation</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><fieldsynopsis><varname>This_t</varname></fieldsynopsis></entry>
- <entry><para>the &array; object's type</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>Engine_t</varname></fieldsynopsis></entry>
- <entry><para>the &array; object's engine's type</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>EngineTag_t</varname></fieldsynopsis></entry>
- <entry><para>indication of engine's category</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>Element_t</varname></fieldsynopsis></entry>
- <entry><para>the type of the array elements, i.e., <type>T</type></para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>ElementRef_t</varname></fieldsynopsis></entry>
- <entry><para>the type of a reference to an array element,
- i.e., <type>T&</type>. Equivalently, the type to write to a
- single element.</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>Domain_t</varname></fieldsynopsis></entry>
- <entry><para>the array's domain's type, i.e., the type of the
- union of all array indices</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>Layout_t</varname></fieldsynopsis></entry>
- <entry><para>unknown</para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>dimensions</varname></fieldsynopsis></entry>
- <entry><para>integer equalling the number of dimensions, i.e.,
- <varname>Dim</varname></para></entry>
- </row>
- <row>
- <entry><fieldsynopsis><varname>rank</varname></fieldsynopsis></entry>
- <entry><para>integer equalling the number of dimensions, i.e.,
- <varname>Dim</varname>; a synonym for <fieldsynopsis>
- <varname>dimensions</varname></fieldsynopsis></para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="arrays_ref-array-constructors">
- <title>Constructors and Destructors</title>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Constructors and Destructors</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Effect</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <constructorsynopsis>
- <methodname>Array</methodname>
- <void></void>
- </constructorsynopsis>
- </entry>
- <entry><para>Creates an array that will be resized
- later.</para></entry>
- </row>
- <row>
- <entry>
- <constructorsynopsis>
- <methodname>Array</methodname>
- <methodparam><modifier>const</modifier> <type>Engine_t&</type>
- <parameter>engine</parameter></methodparam>
- </constructorsynopsis>
- </entry>
- <entry><para>Creates an array with an engine equivalent to
- the <parameter>engine</parameter>. This array will have the
- same values as <parameter>engine</parameter>. QUESTION: Why
- would a user every want to use this
- constructor?</para></entry>
- </row>
- <row>
- <entry>
- <constructorsynopsis>
- <methodname>Array</methodname>
- <methodparam>
- <modifier>const</modifier>
- <type> Engine<Dim2, T2, EngineTag2>&</type>
- <parameter>engine</parameter>
- </methodparam>
- <methodparam>
- <modifier>const</modifier>
- <type>Initializer&</type> <parameter>init</parameter>
- </methodparam>
- </constructorsynopsis>
- </entry>
- <entry><para>What does this do?</para></entry>
- </row>
- <row>
- <entry>ADD ALL CONSTRUCTORS AND DESTRUCTORS.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
-
- <section id="arrays_ref-array-initializers">
- <title>Initializers</title>
-
- <para>Add a table.</para>
- </section>
-
-
- <section id="arrays_ref-array-access">
- <title>Element Access</title>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&array; Element Access</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Effect</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <methodsynopsis>
- <type>Element_t</type> <methodname>read</methodname>
- <void></void>
- </methodsynopsis>
- </entry>
- <entry><para>unknown: See line 1839.</para></entry>
- </row>
- <row>
- <entry>
- <methodsynopsis>
- <type>Element_t</type> <methodname>read</methodname>
- <methodparam>
- <modifier>const</modifier>
- <type>Sub1&</type> <parameter>s1</parameter>
- </methodparam>
- <methodparam>
- <modifier>const</modifier>
- <type> Sub2&</type> <parameter>s2</parameter>
- </methodparam>
- </methodsynopsis>
- </entry>
- <entry><para>How does the version with template parameters,
- e.g., <type>Sub1</type> differ from the <type>int</type>
- version?</para></entry>
- </row>
- <row>
- <entry>
- <methodsynopsis>
- <type>Element_t</type> <methodname>operator()</methodname>
- <methodparam>
- <modifier>const</modifier>
- <type>Sub1&</type> <parameter>s1</parameter>
- </methodparam>
- <methodparam>
- <modifier>const</modifier>
- <type>Sub2&</type> <parameter>s2</parameter>
- </methodparam>
- </methodsynopsis>
- </entry>
- <entry><para>How does this differ from <statement>read(const
- Sub1& s1, const Sub2& s2)</statement>? </para></entry>
- </row>
- <row>
- <entry>ADD ALL <function>read</function>s and
- <function>operator()</function>s.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
-
- <section id="arrays_ref-array-component">
- <title>Component Access</title>
-
- <para>When an array stores elements having components, e.g., an
- array of vectors, tensors, or arrays, the
- <methodname>comp</methodname> returns an array consisting of the
- specified components. The original and component array share the
- same engine so changing the values in one affects values in the
- other.</para>
-
- <para>For example, if &n; × &n; array <varname>a</varname>
- consists of three-dimensional real-valued vectors,
- <statement>a.comp(1)</statement> returns a &n; × &n;
- real-valued array of all the middle vector components. Assigning
- to the component array will also modify the middle components of
- the vectors in <varname>a</varname>.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&array; Component Access</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Effect</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <methodsynopsis>
- <type>UNKNOWN compute this</type> <methodname>comp</methodname>
- <methodparam>
- <modifier>const</modifier>
- <type>int&</type>
- <parameter>i1</parameter>
- </methodparam>
- </methodsynopsis>
- </entry>
- <entry><para>unknown: See line 1989.</para></entry>
- </row>
- <row>
- <entry>ADD ALL <methodname>comp</methodname>s.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="arrays_ref-array-accessors">
- <title>Accessors</title>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&array; Accessor Methods</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Effect</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <methodsynopsis>
- <type>int</type> <methodname>first</methodname>
- <methodparam>
- <type>int</type>
- <parameter>d</parameter>
- </methodparam>
- </methodsynopsis>
- </entry>
- <entry><para>unknown: See line 2050</para></entry>
- </row>
- <row>
- <entry>ADD ALL other accessor methods, including
- <methodname>engine</methodname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
-
- <section id="arrays_ref-array-copying">
- <title>Copying &array;s</title>
-
- <para>Explain how copied arrays and views of arrays share the
- same underlying engine so changing values in one also affects the
- other. This is called a shallow copy.</para>
- </section>
-
-
- <section id="arrays_ref-array-utilities">
- <title>Utility Methods</title>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&array; Utility Methods</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Effect</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <methodsynopsis>
- <type>void</type> <methodname>makeOwnCopy</methodname>
- <void></void>
- </methodsynopsis>
- </entry>
- <entry><para>unknown: See line 2044</para></entry>
- </row>
- <row>
- <entry>ADD ALL other utility methods.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
-
- <section id="arrays_ref-array-implementation">
- <title>Implementation Details</title>
-
- <para>As a container, an &array;'s implementation is quite
- simple. Its <keywordname>private</keywordname>data consists of
- an engine, and it has no <keywordname>private</keywordname>
- functions.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&array; Implementation Data</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Data Member</entry>
- <entry>Meaning</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <fieldsynopsis>
- <modifier>private</modifier>
- <type>Engine_t</type> <varname>engine_m</varname>
- </fieldsynopsis>
- </entry>
- <entry><para>engine computing the array's values</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- </section>
-
-
- <section id="arrays_ref-dynamicarray">
- <title>&dynamicarray;s: Dynamically-Sized Domains</title>
-
- <para>A DynamicArray is a read-write array with extra
- create/destroy methods. It can act just like a regular Array, but
- can have a dynamically-changing domain. See <filename
- class="headerfile">src/DynamicArray/DynamicArray.h</filename>.</para>
-
- <para>ADD: Briefly describe what the class does and an example of
- where it is used.</para>
-
- <para>ADD: Check that its interface is actually the same as for
- &array;.</para>
-
- <para>ADD: Check that the operations on dynamic arrays are
- actually the same as for &array;. See <filename
- class="headerfile">src/DynamicArray/DynamicArrayOperators.h</filename>,
- <filename
- class="headerfile">src/DynamicArray/PoomaDynamicArrayOperators.h</filename>,
- and <filename
- class="headerfile">src/DynamicArray/VectorDynamicArrayOperators.h</filename>.</para>
-
-
- <section id="arrays_ref-dynamicarray-implementation">
- <title>Implementation Details</title>
-
- <para><type>DynamicArray</type> has no
- <keywordname>protected</keywordname> or
- <keywordname>private</keywordname> members.</para>
- </section>
- </section>
-
-
- <section id="arrays_ref-views">
- <title>Views of &array;s</title>
-
- <para>UNFINISHED</para>
- </section>
-
-
- <section id="arrays_ref-assignment">
- <title>&array; Assignments</title>
-
- <para>&pooma; supports assignments to &array;s of other &array;s
- and scalar values. QUESTION: Is the following correct? For the
- former, the right-hand side array's domain must be at least as
- large as the left-hand side array's domain. Corresponding values
- are copied. Assigning a scalar value to an array ensures all the
- array elements have the same scalar value.</para>
-
- <para>UNFINISHED: Add a table containing assignment operators
- found one lines 2097–2202.</para>
- </section>
-
-
- <section id="arrays_ref-print">
- <title>Printing &array;s</title>
-
- <para>&array;s support output to but not input from IO streams.
- In particular, output to <type>ostream</type>s and file streams is
- supported.</para>
-
- <para>Add a table, using <filename
- class="headerfile">src/Array/Array.h</filename>, lines
- 2408–2421. See the implementation in <filename
- class="headerfile">src/Array/PrintArray.h</filename>.</para>
-
- <para>QUESTION: How does one print a &dynamicarray;.</para>
- </section>
-
-
- <section>
- <title>Expressions Involving &array;s</title>
-
- <para>In &pooma;, expressions may contain entire &array;s. That
- is, &array;s are first-class objects with respect to expressions.
- For example, given &array;s <varname>a</varname> and
- <varname>b</varname>, the expression <statement>a + b</statement>
- is equivalent to an array containing the element-wise sum of the
- two arrays.</para>
-
- <para>Any finite number of the operators listed below can be used
- in an expression. The precedence and order of operation is the
- same as with ordinary built-in types.</para>
-
- <para>QUESTION: Do &field;s also support the same set of
- operations?</para>
-
- <para>QUESTION: Some operations in <filename
- class="headerfile">src/Field/FieldOperators.h</filename> use both
- &array; and &field;. Do we list them here or in the &field;
- section or both or somewhere else?</para>
-
- <para>In the table below, &array; supplants the exact return types
- because they are complicated and rarely need to be explicitly
- written down.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Operators on &array;</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <funcsynopsis>
- <funcprototype>
- <funcdef>Array <function>acos</function></funcdef>
- <paramdef>const <parameter>Array<Dim,T,EngineTag>& a</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </entry>
- <entry><para>an array containing the element-wise inverse
- cosine of the array <parameter>a</parameter></para></entry>
- </row>
- <row>
- <entry>ADD ALL other operators appearing in <filename
- class="headerfile">src/Array/ArrayOperators.h</filename>,
- <filename
- class="headerfile">src/Array/ArrayOperatorSpecializations.h</filename>,
- <filename
- class="headerfile">src/Array/PoomaArrayOperators.h</filename>,
- and <filename
- class="headerfile">src/Array/VectorArrayOperators.h</filename>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>FINISH: Write one or two examples or refer to ones
- previously in the text.</para>
- </section>
-
-
- <section id="arrays_ref-reductions">
- <title>Reducing All &array; Elements to One Value</title>
-
- <para>These reduction functions repeatedly apply a binary
- operation to all array elements to yield a value. These functions
- are similar to the Standard Template Library's
- <function>accumulate</function> function. For example,
- <function>sum</function> repeatedly applies the binary plus
- operator to all array elements, yielding the sum of all array
- elements.</para>
-
- <para>FINISH: What order of operation, if any, is
- guaranteed?</para>
-
- <para>FINISH: Add a table of the functions in <filename
- class="headerfile">src/Array/Reductions.h</filename>.</para>
-
- <para>How does one use one's own binary function? See <filename
- class="headerfile">src/Engine/Reduction.h</filename>.</para>
- </section>
-
-
- <section id="arrays_ref-utilities">
- <title>Utility Functions</title>
-
- <section id="arrays_ref-utilities-compression">
- <title>Compressed Data</title>
-
- <para>Add a table containing
- <function>elementsCompressed</function>,
- <function>compressed</function>, <function>compress</function>,
- and <function>uncompress</function>.</para>
- </section>
-
-
- <section id="arrays_ref-utilities-sizes">
- <title>Centering Sizes and Number of Materials</title>
-
- <para>ADD: a description of <function>numMaterials</function> and
- <function>centeringSize</function> found in <filename
- class="headerfile">src/Field/Field.h</filename>. These functions
- are meaningless for &array; but are provided for consistency with
- &field;.</para>
- </section>
-
- <section id="arrays_ref-utilities-subfield">
- <title>Obtaining Subfields</title>
-
- <para>ADD: a description of <function>subField</function> found
- in <filename class="headerfile">src/Field/Field.h</filename>.
- This function, meaningless for &array;, is provided for
- consistency with &field;.</para>
- </section>
- </section>
-
-
- <section id="arrays_ref-tmp">
- <title>TMP: What do we do with these …? Remove this
- section.</title>
-
- <para>QUESTION: Do we describe the &leaffunctor;s specialized for
- &array;s in <filename
- class="headerfile">src/Array/Array.h</filename> or in the &pete;
- reference section? What about the functions in <filename
- class="headerfile">src/Array/CreateLeaf.h</filename>?</para>
-
- <para>QUESTION: What is an <type>EngineFunctor</type>? We
- probably should describe it in an analogous way as for
- &leaffunctor;s.</para>
-
- <para>QUESTION: Where do we write about
- <type>ExpressionTraits</type> for &array;s?</para>
-
- <para>QUESTION: Do we describe the <type>ElementProperties</type>
- specialization at this place or in its section?</para>
-
- <para>QUESTION: Do we describe the <type>Patch</type>
- specialization for &array;s (<filename
- class="headerfile">src/Array/Array.h</filename>:1300) in this
- place or in a section for patches?</para>
- </section>
- </chapter>
-
-
- <chapter id="fields_ref">
- <title>&field;s</title>
-
- <para>An &array; is a set of values indexed by
- coordinates, one value per coordinate. It models the computer
- science idea of an array. Similarly, a &field; is a set of values
- indexed by coordinate. It models the mathematical and physical
- idea of a field represented by a grid of rectangular cells, each
- having at least one value. A &field;'s functionality is a superset
- of an &array;'s functionality because:
- <itemizedlist>
- <listitem>
- <para>A &field; is distributed through space so one can compute
- the distances between cells.</para>
- </listitem>
- <listitem>
- <para>Each cell can hold multiple values. For example, a
- rectangular cell can have one value on each of its faces.</para>
- </listitem>
- <listitem>
- <para>Multiple materials can share the same cell. For example,
- different values can be stored in the same cell for carbon,
- oxygen, and nitrogen.</para>
- </listitem>
- </itemizedlist>
- Also, &field;s' values can be related by relations. Thus, if one
- field's values change, a dependent field's values can be
- automatically computed when needed. FIXME: See also the unfinished
- works chapter's entry concerning relations and arrays.</para>
-
- <para>QUESTION: Should we add a picture comparing and contrasting
- an array and a field?</para>
-
- <para>QUESTION: How much structure can be copied from the &array;
- chapter?</para>
-
- <para>QUESTION: Where is <type>NewMeshTag</type>, defined in
- <filename class="headerfile">src/Field/Field.h</filename>,
- used?</para>
-
- <para>QUESTION: Do we describe the &leaffunctor;s specialized for
- &field;s in <filename
- class="headerfile">src/Field/Field.h</filename> or in the &pete;
- reference section? Use the same decision for &array;s.</para>
-
- <para>QUESTION: What do the structure and functions in <filename
- class="headerfile">src/Field/Mesh/PositionFunctions.h</filename>
- do?</para>
-
-
- <section id="fields_ref-field">
- <title>The &field; Container</title>
-
- <para>ADD: table of template parameters and table of compile-time
- types and values.</para>
-
-
- <section id="fields_ref-field-constructors">
- <title>Constructors and Destructors</title>
-
- <para>ADD: this section similar to &array;s's constructor and
- destructor section.</para>
- </section>
-
- <section id="fields_ref-field-initializers">
- <title>Initializers</title>
-
- <para>Add a table.</para>
- </section>
-
-
- <section id="fields_ref-field-access">
- <title>Element Access</title>
-
- <para>ADD: a table ala &array;. Be sure to include
- <methodname>all</methodname>.</para>
- </section>
-
-
- <section id="fields_ref-field-component">
- <title>Component Access</title>
-
- <para>ADD: a table ala &array;.</para>
- </section>
-
-
- <section id="fields_ref-field-subfields">
- <title>Obtaining Subfields</title>
-
- <para>ADD: discussion and a table listing ways to obtain
- subfields. Although the implementation may treat subfield views
- and other field views similarly (?Is this true?), they are
- conceptually different ideas so we present them
- separately.</para>
-
- <para>See <filename
- class="headerfile">src/Field/Field.h</filename>'s
- <methodname>operator[]</methodname>,
- <methodname>subField</methodname>, …,
- <methodname>material</methodname>.</para>
- </section>
-
-
- <section id="fields_ref-field-relations">
- <title>Supporting Relations</title>
-
- <para>ADD: a table with the member functions including
- <methodname>addRelation</methodname>,
- <methodname>removeRelations</methodname>,
- <methodname>applyRelations</methodname>, and
- <methodname>setDirty</methodname>.</para>
- </section>
-
-
- <section id="fields_ref-field-accessors">
- <title>Accessors</title>
-
- <para>ADD: a table using lines like <filename
- class="headerfile">src/Field/Field.h</filename>:1243–1333.</para>
- </section>
-
-
- <section id="fields_ref-field-utilities">
- <title>Utility Methods</title>
-
- <para>ADD: a table including
- <methodname>makeOwnCopy</methodname>.</para>
- </section>
-
-
- <section id="fields_ref-field-implementation">
- <title>Implementation Details</title>
-
- <para>ADD: a table similar to &array;'s.</para>
-
- </section>
-
- </section>
-
-
- <section id="engines_ref-views">
- <title>Views of &field;s</title>
-
- <para>Be sure to relate to &array; views. Note only three
- dimensions are supported.</para>
-
- <para>Be sure to describe <statement>f[i]</statement>. Does this
- refer to a particular material or a particular value within a
- cell? I do not remember. See <type>SubFieldView</type> in
- <filename class="headerfile">src/Field/Field.h</filename>.</para>
- </section>
-
-
- <section id="fields_ref-assignment">
- <title>&field; Assignments</title>
-
- <para>ADD: Describe supported assignments, relating to &array;'s
- assignments.</para>
-
- <para>UNFINISHED: Add a table containing assignment operators
- found on <filename
- class="headerfile">src/Field/Field.h</filename>:2097–2202
- and 1512–1611.</para>
- </section>
-
-
- <section id="fields_ref-print">
- <title>Printing &field;s</title>
-
- <para>QUESTION: How similar is this to printing &array;s?</para>
-
- <para>&field;s support output to but not input from IO streams.
- In particular, output to <type>ostream</type>s and file streams is
- supported.</para>
-
- <para>Add a table, using <filename
- class="headerfile">src/Field/Field.h</filename>, lines
- 1996–2009. See the implementation in <filename
- class="headerfile">src/Field/PrintField.h</filename>.</para>
- </section>
-
-
- <section id="fields_ref-reductions">
- <title>Combining &field; Elements</title>
-
- <para>Like &array;s, &field;s support reduction of all elements to
- one value. Additionally, the latter supports computing a field's
- values using field stencils. QUESTION: How do I describe this
- with a minimum of jargon?</para>
-
- <para>ADD: something similar to &array; reductions.</para>
-
- <para>FINISH: Add a table of the functions in <filename
- class="headerfile">src/Field/FieldReductions.h</filename>.</para>
-
- <para>FINISH: Add a table of the functions in <filename
- class="headerfile">src/Field/DiffOps/FieldOffsetReductions.h</filename>.
- QUESTION: Why is only <function>sum</function> defined?</para>
- </section>
-
-
- <section id="fields_ref-expressions">
- <title>Expressions Involving &field;s</title>
-
- <para>Do something similar to &array;'s section. See the
- operations defined in <filename
- class="headerfile">src/Field/FieldOperators.h</filename>,
- <filename
- class="headerfile">src/Field/FieldOperatorSpecializations.h</filename>,
- <filename
- class="headerfile">src/Field/PoomaFieldOperators.h</filename>, and
- <filename
- class="headerfile">src/Field/VectorFieldOperators.h</filename>.</para>
-
- <para>Some operations involve both &array; and &field;
- parameters. Where do we list them?</para>
- </section>
-
-
- <section id="fields_ref-stencils">
- <title>&field; Stencils: Faster, Local Computations</title>
-
- <para>ADD: a description of a stencil. Why is it needed? How
- does a user use it? How does a user know when to use one? Add
- documentation of the material from <filename
- class="headerfile">src/Field/DiffOps/FieldStencil.h</filename>.</para>
-
- <para>How is <type>FieldShiftEngine</type> used by &field;
- stencils? Should it be described here or in the &engine; section?
- See the the code in <filename
- class="headerfile">src/Field/DiffOps/FieldShiftEngine.h</filename>.</para>
- </section>
-
-
- <section>
- <title>Cell Volumes, Face Areas, Edge Lengths, Normals</title>
-
- <para>ADD: a description of these functions. See <filename
- class="headerfile">src/Field/Mesh/MeshFunctions.h</filename>.
- These are initialized in, e.g., <filename
- class="headerfile">src/Field/Mesh/UniformRectilinearMesh.h</filename>.
- Note that these do not work for <type>NoMesh</type>.</para>
- </section>
-
-
- <section id="fields_ref-div">
- <title>Divergence Operators</title>
-
- <para>ADD: a table having divergence operators, explaining the
- current restrictions imposed by what is implemented. See
- <filename class="headerfile">src/Field/DiffOps/Div.h</filename>
- and <filename
- class="headerfile">src/Field/DiffOps/Div.UR.h</filename>. What
- restrictions does <quote>UR</quote> (mesh) connote?</para>
- </section>
-
-
- <section id="fields_ref-utilities">
- <title>Utility Functions</title>
-
- <section id="fields_ref-utilities-compression">
- <title>Compressed Data</title>
-
- <para>Add a table containing
- <function>elementsCompressed</function>,
- <function>compressed</function>, <function>compress</function>,
- and <function>uncompress</function>.</para>
- </section>
-
-
- <section id="fields_ref-utilities-sizes">
- <title>Centering Sizes and Number of Materials</title>
-
- <para>ADD: a description of <function>numMaterials</function> and
- <function>centeringSize</function> found in <filename
- class="headerfile">src/Field/Field.h</filename>.</para>
-
- <para>QUESTION: How do these relate to any method functions?</para>
- </section>
-
-
- <section id="fields_ref-utilities-subfield">
- <title>Obtaining Subfields</title>
-
- <para>ADD: a description of <function>subField</function> found
- in <filename
- class="headerfile">src/Field/Field.h</filename>.</para>
- </section>
-
- </section>
-
-
- <section id="fields_ref-centerings">
- <title>&field; Centerings</title>
-
- <para>DO: Describe the purpose of a centering and its definition.
- Describe the ability to obtain canonical centerings. Explain how
- to construct a unique centering. See <filename
- class="headerfile">src/Field/FieldDentering.h</filename>.</para>
- </section>
-
-
- <section id="fields_ref-fieldoffsets">
- <title>Relative &field; Positions</title>
-
- <para>Permit specifying field positions relative to a field
- location. Describe <type>FieldOffset</type> and
- <type>FieldOffsetList</type>. See <filename
- class="headerfile">src/Field/FieldOffset.h</filename></para>
- </section>
-
-
- <section id="fields_ref-nearestneighbors">
- <title>Computing Close-by Field Positions</title>
-
- <para>Given a field location, return the set of field locations
- that are closest using ?Manhattan? distance. See <filename
- class="headerfile">src/Field/NearestNeighbors.h</filename>.</para>
- </section>
-
-
- <section id="fields_ref-mesh">
- <title>Mesh ???</title>
-
- <para>Unlike &array;s, &field;s are distributed throughout space
- so distances between values within the &field can be computed. A
- &field;'s mesh stores this spatial distribution.</para>
-
- <para>QUESTION: What do we need to write about meshes? What is
- unimportant implementation and what should be described in this
- reference section?</para>
-
- <para>QUESTION: Where in here should emphasize vertex, not cell,
- positions? <quote>VERTEX</quote> appears repeatedly in <filename
- class="headerfile">src/Field/Mesh/NoMesh.h</filename>.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Mesh Types</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Mesh Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><type>NoMesh<Dim></type></entry>
- <entry><para>no physical spacing, causing a &field; to mimic
- an &array; with multiple engines.</para></entry>
- </row>
- <row>
- <entry><type>UniformRectilinearMesh<Dim,T></type></entry>
- <entry><para>physical spacing formed by the Cartesian product
- of ????.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <section id="fields_ref-mesh-accessors">
- <title>Mesh Accessors</title>
-
- <para>ADD: a table listing accessors, explaining the difference
- between (physical and total) and (cell and vertex) domains. See
- <filename class="headerfile">src/Field/Mesh/NoMesh.h</filename>.
- Also, include <function>spacings</function> and
- <function>origin</function> in <filename
- class="headerfile">src/Field/Mesh/UniformRectilinearMesh.h</filename>.
- Note <type>NoMesh</type> does not provide the latter two.</para>
- </section>
-
- </section>
-
-
- <section id="fields_ref-tmp">
- <title>TMP: What do we do with these …? Remove this
- section.</title>
-
- <para>QUESTION: Do we describe the <type>Patch</type>
- specialization for &field; at this place or in some common place?
- Follow &array;'s lead.</para>
-
- <para>QUESTION: Where do we describe <type>CreateLeaf</type> and
- <type>MakeFieldReturn</type> in <filename
- class="headerfile">src/Field/FieldCreateLeaf.h</filename> and
- <filename
- class="headerfile">src/Field/FieldMakeReturn.h</filename>.</para>
-
- <para>QUESTION: What do we do with <type>FieldEnginePatch</type>
- in <filename
- class="headerfile">src/Field/FieldEngine/FieldEnginePatch.h</filename>.</para>
- </section>
- </chapter>
-
-
- <chapter id="engines_ref">
- <title>&engine;s</title>
-
- <para>From a user's point of view, a container makes data available
- for reading and writing. In fact, the container's &engine; stores
- the data or, if the data is computed, performs a computation to
- yield the data.</para>
-
- <para>FINISH: Introduce the various types of engines. Add a table
- with a short description of each engine type.</para>
-
- <para>FINISH: First, we specify a generic &engine;'s interface.
- Then, we present &engine; specializations.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>Types of &engine;s</title>
-
- <tgroup cols="3" align="left">
- <thead>
- <row>
- <entry>Engine Type</entry>
- <entry>Engine Tag</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Brick</para></entry>
- <entry><para><literal>Brick</literal></para></entry>
- <entry><para>Explicitly store all elements in, e.g., a &cc;
- array.</para></entry>
- </row>
- <row>
- <entry><para>Compressible</para></entry>
- <entry><para><literal>CompressibleBrick</literal></para></entry>
- <entry><para>If all values are the same, use constant storage
- for that single value. Otherwise, explicitly store all
- elements.</para></entry>
- </row>
- <row>
- <entry><para>Constant</para></entry>
- <entry><para><literal>ConstantFunction</literal></para></entry>
- <entry><para>Returns the same constant value for all
- indices.</para></entry>
- </row>
- <row>
- <entry><para>Dynamic</para></entry>
- <entry><para><literal>Dynamic</literal></para></entry>
- <entry><para>Manages a contiguous, local, one-dimensional,
- dynamically resizable block of data.</para></entry>
- </row>
- <row>
- <entry><para>Component Forwarding</para></entry>
- <entry><para><literal>CompFwd<EngineTag,
- Components></literal></para></entry>
- <entry><para>Returns the specified components from
- <literal>EngineTag</literal>'s engine. Components are
- <quote>pieces</quote> of multi-value elements such as vectors
- and tensors.</para></entry>
- </row>
- <row>
- <entry><para>Expression</para></entry>
- <entry><para><literal>ExpressionTag<Expr></literal></para></entry>
- <entry><para>Returns the value of the specified &pete;
- expression.</para></entry>
- </row>
- <row>
- <entry><para>Index Function</para></entry>
- <entry><para><literal>IndexFunction<Functor></literal></para></entry>
- <entry><para>Makes the function
- <literal>Functor</literal>accepting indices mimic an
- array.</para></entry>
- </row>
- <row>
- <entry><para>MultiPatch</para></entry>
- <entry><para><literal>MultiPatch<LayoutTag,PatchTag></literal></para></entry>
- <entry><para>Support distributed computation using several
- processors (???contexts???). <literal>LayoutTag</literal>
- indicates how the entire array is distributed among the
- processors. Each processor uses a <literal>PatchTag</literal>
- engine.</para></entry>
- </row>
- <row>
- <entry><para>Remote</para></entry>
- <entry><para><literal>Remote<EngineTag></literal></para></entry>
- <entry><para>unknown</para></entry>
- </row>
- <row>
- <entry><para>Remote Dynamic</para></entry>
- <entry><para><literal>Remote<Dynamic></literal></para></entry>
- <entry><para>unknown: specialization</para></entry>
- </row>
- <row>
- <entry><para>Stencil</para></entry>
- <entry><para><literal>StencilEngine<Function,
- Expression></literal></para></entry>
- <entry><para>Returns values computed by applying the
- user-specified function to sets of contiguous values in the
- given engine or container. Compare with user function
- engines.</para></entry>
- </row>
- <row>
- <entry><para>User Function</para></entry>
- <entry><para><literal>UserFunctionEngine<UserFunction,Expression></literal></para></entry>
- <entry><para> Returns values computed by applying the
- user-specified function to the given engine or container.
- QUESTION: Is the following claim correct? For each returned
- value, only one value from the engine or container is
- used.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>QUESTION: Where do we describe views?</para>
-
- <para>QUESTION: What does <type>NewEngine</type> do? Should it be
- described when describing views? Should it be omitted as an
- implementation detail?</para>
-
- <para>QUESTION: Where do we describe &engine; patches found in
- <filename class="headerfile">src/Engine/EnginePatch.h</filename>?
- All patch data in a separate chapter or engine-specific pieces in
- this chapter?</para>
-
- <para>QUESTION: What is <function>notifyEngineWrite</function>?
- See also <filename
- class="headerfile">src/Engine/NotifyEngineWrite.h</filename>.</para>
-
- <para>QUESTION: What aspect of MultiPatch uses <type>IsValid</type> in
- <filename
- class="headerfile">src/Engine/IsValidLocation.h</filename>?</para>
-
- <para>QUESTION: Who uses intersections? Where should this be
- described? See <filename
- class="headerfile">src/Engine/Intersector.h</filename>, <filename
- class="headerfile">src/Engine/IntersectEngine.h</filename>, and
- <filename
- class="headerfile">src/Engine/ViewEngine.h</filename>.</para>
-
- <section id="engines_ref-compile_time_interface">
- <title>&engine; Compile-Time Interface</title>
-
- <para>ADD: a table of template parameters ala &array;. ADD:
- compile-time types and values.</para>
- </section>
-
-
- <section id="engines_ref-constructors">
- <title>Constructors and Destructors</title>
-
- <para>ADD: a table of constructors and destructors ala
- &array;'s.</para>
- </section>
-
-
- <section id="engines_ref-access">
- <title>Element Access</title>
-
- <para>ADD: a table with <methodname>read</methodname> and
- <methodname>operator()</methodname>.</para>
- </section>
-
-
- <section id="engines_ref-accessors">
- <title>Accessors</title>
-
- <para>ADD: a table of accessors.</para>
- </section>
-
-
- <section id="engines_ref-assignments">
- <title>&engine; Assignments</title>
-
- <para>similar to &array;'s assignments. shallow copies. ADD: a
- table with one entry</para>
- </section>
-
-
- <section id="engines_ref-utilities">
- <title>Utility Methods</title>
-
- <para>ADD: a table including
- <methodname>makeOwnCopy</methodname>.</para>
-
- <para>QUESTION: What are <methodname>dataObject</methodname>,
- <methodname>isShared</methodname>, and related methods?</para>
- </section>
-
-
- <section id="engines_ref-implementation">
- <title>Implementation Details</title>
-
- <para>ADD: this section. Explain that
- <varname>dataBlock_m</varname> and <varname>data_m</varname> point
- to the same place. The latter speeds access, but what is the
- purpose of the former?</para>
- </section>
-
-
- <section id="engines_ref-brick">
- <title>Brick and BrickView Engines</title>
-
- <para>ADD: description of what a brick means. ADD: whatever
- specializations the class has, e.g.,
- <methodname>offset</methodname>.</para>
-
- <para>QUESTION: What does <type>DoubleSliceHelper</type> do?</para>
- </section>
-
-
- <section id="engines_ref-compressible">
- <title>Compressible Brick and BrickView Engines</title>
-
- <para>ADD this.</para>
- </section>
-
-
- <section id="engines_ref-dynamic">
- <title>Dynamic and DynamicView Engines:</title>
-
- <para>ADD this. Manages a contiguous, local, resizable, 1D block
- of data.</para>
- </section>
-
-
- <section id="engines_ref-components">
- <title>Component Engines</title>
-
- <para>I believe these implement array component-forwarding. See
- <filename
- class="headerfile">src/Engine/ForwardingEngine.h</filename>.</para>
- </section>
-
-
- <section id="engines_ref-expressions">
- <title>Expression Engines</title>
-
- <para>Should this be described in the &pete; section? Unlikely.
- See <filename
- class="headerfile">src/Engine/ExpressionEngine.h</filename>.</para>
- </section>
-
-
- <section id="engines_ref-enginefunctor">
- <title>&engine; Functors</title>
-
- <para>QUESTION: What is an <type>EngineFunctor</type>? Should it
- have its own section? See <filename
- class="headerfile">src/Engine/EngineFunctor.h</filename>.</para>
- </section>
-
-
- <section id="engines_ref-fieldengines">
- <title><type>FieldEngine</type>: A Hierarchy of &engine;s</title>
-
- <para>A &field; consists of a hierarchy of materials and
- centerings. These are implemented using a hierarchy of engines.
- See <filename
- class="headerfile">src/Field/FieldEngine/FieldEngine.h</filename>
- and <filename
- class="headerfile">src/Field/FieldEngine/FieldEngine.ExprEngine.h</filename>.</para>
- </section>
- </chapter>
-
-
- <chapter id="benchmarks_ref">
- <title>&benchmark; Programs</title>
-
- <para>Explain how to use &benchmark; programs, especially the
- options. Explain how to write a &benchmark; program. See also
- <filename class="headerfile">src/Utilities/Benchmark.h</filename>
- and <filename
- class="libraryfile">src/Utilities/Benchmark.cmpl.cpp</filename>.</para>
-
- </chapter>
-
-
- <chapter id="layouts_ref">
- <title>Layouts and Partitions: Distribute Computation Among
- Contexts</title>
-
- <para>QUESTION: What is the difference between
- <type>ReplicatedTag</type> and <type>DistributedTag</type>?</para>
-
- </chapter>
-
-
- <chapter id="pete_ref">
- <title>&pete;: Evaluating Parallel Expressions</title>
-
- <section>
- <title>UNKNOWN</title>
-
- <section id="pete_ref-unknown-leaf-tags">
- <title>Leaf Tag Classes</title>
-
- <para><type>NotifyPreReadTag</type> indicates a term is about to
- be read. Why is this needed? Defined in <filename
- class="headerfile">src/Utilities/NotifyPreRead.h</filename>.</para>
- </section>
- </section>
-
- </chapter>
-
-
- <chapter id="views_ref">
- <title>Views</title>
-
- <para>QUESTION: Should this have its own chapter or be part of a
- container chapter?</para>
-
- <para>Describe <type>View0</type>, <type>View1</type>, …,
- <type>View7</type> and <type>View1Implementation</type>.</para>
-
- <para>QUESTION: What causes the need for <type>AltView0</type> and
- <type>AltComponentView</type>?</para>
-
- <para>Be sure to describe <type>ComponentView</type> in the same
- place. This is specialized for &array;s in <filename
- class="headerfile">src/Array/Array.h</filename>:1323–1382.</para>
-
- <section>
- <title><type>ViewIndexer<Dim,Dim2></type></title>
-
- <para>Defined in <filename
- class="headerfile">src/Utilities/ViewIndexer.h</filename>, this
- type translates indices between a domain and a view of it.</para>
- </section>
- </chapter>
-
- <chapter id="threads_ref">
- <title>Threads</title>
-
- <para>Perhaps include information in <filename
- class="headerfile">src/Engine/DataObject.h</filename>.</para>
-
- <para>&pooma; options include UNFINISHED</para>
-
- </chapter>
-
-
- <chapter id="utilities_ref">
- <title>Utility Types</title>
-
- <para>TMP: What is a good order?</para>
-
- <section id="utilities_ref-options">
- <title><type>Options</type>: Varying Run-Time Execution</title>
-
- <para>Each &pooma; executable has a <type>Options</type> object,
- created by <function>Pooma::initialize</function>, storing
- run-time configurable values found in <varname>argv</varname>.
- Default options are found in
- <methodname>Options::usage</methodname>.</para>
-
- <para>See <filename
- class="headerfile">src/Utilities/Options.h</filename> and
- <filename
- class="libraryfile">src/Utilities/Options.cmpl.cpp</filename>.</para>
-
- <para>Scatter the specific options to other parts of the
- manual.</para>
- </section>
-
- <section id="utilities_ref-assertions">
- <title>Check Correctness: <type>CTAssert</type>,
- <type>PAssert</type>, <type>PInsist</type>,
- <type>SameType</type></title>
-
- <para>Assertions ensure program invariants are obeyed.
- <type>CTAssert</type>, checked at compile time, incur no run-time
- cost. <type>PAssert</type> and <type>PInsist</type> are checked
- to run-time, the latter producing an explanatory message if the
- assertion fails. Compiling with <envar>NOCTAssert</envar> and
- <envar>NOPTAssert</envar> disable these checks. Compiling with just
- <envar>NOPTAssert</envar> disables only the run-time checks.</para>
-
- <para><type>SameType</type> ensures, at compile-time, two types
- are the same.</para>
-
- <para>These are implemented in <filename
- class="headerfile">src/Utilities/PAssert.h</filename> and
- <filename
- class="libraryfile">src/Utilities/PAssert.cmpl.cpp</filename>.</para>
- </section>
-
- <section id="utilities_ref-clock">
- <title><type>Clock</type>: Measuring a Program's Execution Time</title>
-
- <para>See <filename
- class="headerfile">src/Utilities/Clock.h</filename>.</para>
- </section>
-
-
- <section id="utilities_ref-smart_pointers">
- <title>Smart Pointers: <type>RefCountedPtr</type>,
- <type>RefCountedBlockPtr</type>, and
- <type>DataBlockPtr</type></title>
-
- <para>See <filename
- class="headerfile">src/Utilities/{RefCountedPtr,RefCountedBlockPtr,DataBlockPtr}.h</filename>.
- <filename class="headerfile">src/Utilities/RefCounted.h</filename>
- helps implement it. <type>DataBlockPtr</type> uses
- &smarts;.</para>
- </section>
-
- <section id="utilities_ref-inform">
- <title><type>Inform</type>: Formatted Output for Multi-context
- Execution</title>
-
- <para>See <filename
- class="headerfile">src/Utilities/Inform.h</filename> and <filename
- class="libraryfile">src/Utilities/Inform.cmpl.cpp</filename>.</para>
- </section>
-
- <section id="utilities_ref-statistics">
- <title><type>Statistics</type>: Report &pooma; Execution Statistics</title>
-
- <para>Collect and print execution statistics. Defined in
- <filename
- class="headerfile">src/Utilities/Statistics.h</filename>.</para>
- </section>
-
- <section id="utilities_ref-random_numbers">
- <title>Random Numbers: <type>Unique</type></title>
-
- <para>See <filename
- class="headerfile">src/Utilities/Unique.h</filename>.</para>
- </section>
- </chapter>
-
-
- <chapter id="implementation_types_ref">
- <title>Types for Implementing &pooma;</title>
-
- <para>TMP: What is a good order?</para>
-
- <para>Describe types defined to implement &pooma; but that users do
- not directly use. This chapter has lower priority than other
- chapters since users (hopefully) do not need to know about these
- classes.</para>
-
- <section id="implementation_types_ref-tester">
- <title><type>Tester</type>: Check Implementation Correctness</title>
-
- <para>&pooma; implementation test programs frequently consist of a
- series of operations followed by correctness checks. The
- <type>Tester</type> object supports these tests, returning a
- boolean whether all the correctness checks yield true. Under
- verbose output, messages are printed for each test. See <filename
- class="headerfile">src/Utilities/Tester.h</filename>.</para>
- </section>
-
- <section id="implementation_types_ref-elementproperties">
- <title><type>ElementProperties<T></type>: Properties a Type
- Supports</title>
-
- <para>This traits class permits optimizations in other templated
- classes. See <filename
- class="headerfile">src/Utilities/ElementProperties.h</filename>.</para>
-
- </section>
-
- <section id="implementation_types_ref-typeinfo">
- <title><type>TypeInfo<T></type>: Print a String Describing
- the Type</title>
-
- <para>Print a string describing the type. Defined in <filename
- class="headerfile">src/Utilities/TypeInfo.h</filename>. It is
- specialized for other types in other files, e.g., <filename
- class="headerfile">src/Engine/EngineTypeInfo.h</filename> and
- <filename class="headerfile">src/Field/FieldTypeInfo.h</filename>.
- Is this a compile-time version of RTTI?</para>
- </section>
-
- <section id="implementation_types_ref-looputils">
- <title><type>LoopUtils</type>: Loop Computations at Compile Time</title>
-
- <para>At compile time, <type>LoopUtils</type> supports copying
- between arrays and computing the dot product of arrays. See
- <filename
- class="headerfile">src/Utilities/MetaProg.h</filename>.</para>
- </section>
-
- <section id="implementation_types_ref-modelelement">
- <title><type>ModelElement<T></type>: Wrap a Type</title>
-
- <para>A wrapper class used to differentiate overloaded functions.
- Defined in <filename
- class="headerfile">src/Utilities/ModelElement.h</filename>. Used
- only by &array; and <type>DynamicArray</type>.</para>
- </section>
-
- <section id="implementation_types_ref-wrappedint">
- <title><type>WrappedInt<int></type>: Wrap a Number</title>
-
- <para>A wrapper class used to differentiate overloaded functions
- among different integers. Defined in <filename
- class="headerfile">src/Utilities/WrappedInt.h</filename>. Is this
- class deprecated? Is it even necessary?</para>
- </section>
-
- <section id="implementation_types_ref-empty_classes">
- <title>Supporting Empty Classes</title>
-
- <para>The <type>NoInit</type> tag class indicates certain
- initializations should be skipped. Defined in <filename
- class="headerfile">src/Utilities/NoInit.h</filename>.</para>
-
- <para>FIXME: Should be macro, not function.
- <function>POOMA_PURIFY_CONSTRUCTORS</function> generates an empty
- constructor, copy constructor, and destructor to avoid &purify;
- warnings. Defined in <filename
- class="headerfile">src/Utilities/PurifyConstructors.h</filename>.</para>
-
- </section>
-
- <section id="implementation_types_ref-pool">
- <title><type>Pooled<T></type>: Fast Memory Allocation of
- Small Blocks</title>
-
- <para><type>Pooled<T></type> speeds allocation and
- deallocation of memory blocks for small objects with
- type <type>T</type>. Defined in <filename
- class="headerfile">src/Utilities/Pooled.h</filename>, it is
- implemented in <filename
- class="headerfile">src/Utilities/Pool.h</filename> and <filename
- class="libraryfile">src/Utilities/Pool.cmpl.cpp</filename>.
- <filename class="headerfile">src/Utilities/StaticPool.h</filename>
- no longer seems to be used.</para>
- </section>
-
- <section id="implementation_types_ref-uninitialized_vector">
- <title><type>UninitializedVector<T,Dim></type>: Create
- Without Initializing</title>
-
- <para>This class optimizes creation of an array of objects by
- avoiding running the default constructors. Later initialization
- can occur, perhaps using a loop that can be unrolled. Defined in
- <filename
- class="headerfile">src/Utilities/UninitializedVector.h</filename>,
- this is used only by <type>DomainTraits</type>.</para>
- </section>
- </chapter>
-
- <chapter id="implementation_algorithms_ref">
- <title>Algorithms for Implementing &pooma;</title>
-
- <para>In <filename>src/Utilities/algorithms.h</filename>,
- <function>copy</function>, <function>delete_back</function>, and
- <function>delete_shiftup</function> provide additional algorithms
- using iterators.</para>
- </chapter>
-
-
- <chapter id="where-place-these_ref">
- <title>TMP: Where do we describe these files?</title>
-
- <itemizedlist>
- <listitem>
- <para><filename
- class="headerfile">src/Utilities/Conform.h</filename>: tag for
- checking whether terms in expression have conforming
- domains</para>
- </listitem>
-
- <listitem>
- <para><filename
- class="headerfile">src/Utilities/DerefIterator.h</filename>:
- <type>DerefIterator<T></type> and
- <type>ConstDerefIterator<T></type> automatically
- dereference themselves to maintain <literal>const</literal>
- correctness. <!-- FIXME: s/literal/keyword/ --></para>
- </listitem>
-
- <listitem>
- <para><filename
- class="headerfile">src/Utilities/Observable.h</filename>,
- <filename class="headerfile">src/Utilities/Observer.h</filename>,
- and <filename
- class="headerfile">src/Utilities/ObserverEvent.h</filename>:
- <type>Observable<T></type>,
- <type>SingleObserveable<T></type>,
- <type>Observer<T></type>, and <type>ObserverEvent</type>
- implement the observer pattern. What is the observer pattern?
- Where is this used in the code?</para>
- </listitem>
- </itemizedlist>
-
- </chapter>
-
- </part>
-
-
- <appendix id="future_development">
- <title>Future Development</title>
-
- <section id="future_development-particles">
- <title>Particles</title>
-
- <para><filename
- class="libraryfile">docs/ParticlesDoc.txt</filename> has
- out-of-date information.</para>
-
- <para>See Section 3.2.3 of
- <filename>papers/pooma.ps</filename> for an out-of-date
- description.</para>
-
- <para><filename>papers/jvwr.ps</filename> concerns mainly
- particles. <filename>papers/8thSIAMPOOMAParticles.pdf</filename>,
- by Julian Cummings and Bill Humphrey, concerns parallel particle
- simulations. <filename>papers/iscope98linac.pdf</filename>
- describes a particle beam simulation using &pooma;; it mainly
- concerns particles.</para>
-
- <section>
- <title>Particles</title>
-
- <para>Do we want to include such a section?</para>
-
- <para>Section 3, "Sample Applications" of
- <filename>papers/SiamOO98_paper.ps</filename> describes porting a
- particle program written using High-Performance Fortran to
- &pooma; and presumably why particles were added to &pooma;. It
- also describes <application>MC++</application>, a Monte Carlo
- neutron transport code.</para>
-
- </section>
-
- </section>
-
-
- <section id="future_development-composition_engine">
- <title>Composition of &engine;s</title>
-
- <para>The i,j-th element of the composition
- <varname>a</varname>∘<varname>b</varname> of two arrays
- <varname>a</varname> and <varname>b</varname> equals a(b(i,j)).
- The composition engine tagged <literal>IndirectionTag<Array1,
- Array2></literal>, defined in <filename
- class="headerfile">src/Engine/IndirectionEngine.h</filename> is
- unfinished.</para>
- </section>
-
-
- <section id="future_development-container_consistency">
- <title>Improving Consistency of Container Interfaces</title>
-
- <section id="future_development-container_consistency-array_relations">
- <title>Relations for &array;s</title>
-
- <para>Do &array;s currently support relations? If not, why not?
- Should they be added?</para>
- </section>
-
- <section id="future_development-container_consistency-dimensions">
- <title>Supporting the Same Number of Dimensions</title>
-
- <para>&array; and &field; should support the same maximum number
- of dimensions. Currently, &array;s support seven dimensions and
- &field;s support only three. By definition, &dynamicarray;
- supports only one dimension.</para>
-
- <para>Relations for &array;s.</para>
-
- <para>External guards for &array;s.</para>
- </section>
-
- </section>
-
-
- <section id="future_development-where">
- <title><function>where</function> Proxies</title>
-
- <para>QUESTION: Do we even discuss this broken
- <quote>feature</quote>? Where is it used? Some related code is in
- <filename>src/Array/Array.h</filename>:2511–2520.</para>
- </section>
-
-
- <section id="future_development-long_term">
- <title>Very Long Term Development Ideas</title>
-
- <para>Describe how to write a new configuration file.</para>
- </section>
-
- </appendix>
-
-
- <appendix id="installation">
- <title>Obtaining and Installing &pooma;</title>
-
- <para>ADD: Write this section, including extensive instructions
- for Unix, MS Windows, and MacOS. List the configuration options.
- Be sure to describe configuring for parallel execution.</para>
-
- <section id="installation-distributed_computing">
- <title>Supporting Distributed Computation</title>
-
- <para>To use multiple processors with &pooma; requires installing
- the &cheetah; messaging library and an underlying messaging library
- such as the Message Passing Interface (&mpi;) Communications
- Library or the &mm; Shared Memory Library. In this section, we
- first describe how to install &mm;. Read the section only if using
- &mm;, not &mpi;. Then we describe how to install &cheetah; and
- configure &pooma; to use it.</para>
-
- <section id="installation-distributed_computing-mm">
- <title>Obtaining and Installing the &mm; Shared Memory Library</title>
-
- <para>&cheetah;, and thus &pooma;, can use Ralf Engelschall's &mm;
- Shared Memory Library to pass messages between processors. For
- example, the &author; uses this library on a two-processor
- computer running &linux;. The library, available at
- http://www.engelschall.com/sw/mm/, is available for free and has
- been successfully tested on a variety of Unix platforms.</para>
-
- <para>We describe how to download and install the &mm; library.
- <orderedlist spacing="compact">
- <listitem>
- <para>Download the library from the &pooma; Download page
- available off the &pooma; home page (&poomaHomePage;).</para>
- </listitem>
- <listitem>
- <para>Extract the source code using <command>tar xzvf
- mm-1.1.3.tar.gz</command>. Move into the resulting source
- code directory <filename
- class="directory">mm-1.1.3</filename>.</para>
- </listitem>
- <listitem>
- <para>Prepare to compile the source code by configuring it
- using the <command>configure</command> command. To change
- the default installation directory <filename
- class="directory">/usr/local</filename>, specify
- <command>--prefix=<replaceable>directory</replaceable></command>
- option. The other configuration options can be listed by
- specifying the <command>--help</command> option. Since the
- &author; prefers to keep all &pooma;-related code in his
- <filename class="directory">pooma</filename>subdirectory, he
- uses <command>./configure
- --prefix=${HOME}/pooma/mm-1.1.3</command>.</para>
- </listitem>
- <listitem>
- <para>Create the library by issuing the <command>make</command>
- command. This compiles the source code using a &c; compiler. To
- use a different compiler than the &mm; configuration chooses, set
- the <envar>CC</envar> to the compiler before configuring.</para>
- </listitem>
- <listitem>
- <para>Optionally test the library by issuing the <command>make
- test</command> command. If successful, the penultimate line
- should be <computeroutput>OK - ALL TESTS SUCCESSFULLY
- PASSED</computeroutput>.</para>
- </listitem>
- <listitem>
- <para>Install the &mm; Library by issuing the <command>make
- install</command> command. This copies the library files to the
- installation directory. The <filename
- class="directory">mm-1.1.3</filename> directory containing the
- source code may now be removed.</para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
-
- <section id="installation-distributed_computing-cheetah">
- <title>Obtaining and Installing the &cheetah; Messaging Library</title>
-
- <para>The &cheetah; Library decouples communication from
- synchronization. Using asynchronous messaging rather than
- synchronous messaging permits a message sender to operate without
- the cooperation of the message recipient. Thus, implementing
- message sending is simpler and processing is more efficiently
- overlapped with it. Remote method invocation is also supported.
- The library was developed at the Los Alamos National Laboratory's
- Advanced Computing Laboratory.</para>
-
- <para>&cheetah;'s messaging is implemented using an underlying
- messaging library such as the Message Passing Interface (&mpi;)
- Communications Library (FIXME: xref linkend="mpi99", <ulink
- url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) or the &mm;
- Shared Memory Library. &mpi; works on a wide variety of platforms
- and has achieved widespread usage. &mm; works under Unix on any
- computer with shared memory. Both libraries are available for
- free. The instructions below work for whichever library you
- choose.</para>
-
- <para>We describe how to download and install &cheetah;.
- <orderedlist spacing="compact">
- <listitem>
- <para>Download the library from the &pooma; Download page
- available off the &pooma; home page (&poomaHomePage;).</para>
- </listitem>
- <listitem>
- <para>Extract the source code using <command>tar xzvf
- cheetah-1.0.tgz</command>. Move into the resulting source code
- directory <filename
- class="directory">cheetah-1.0</filename>.</para>
- </listitem>
- <listitem>
- <para>Edit a configuration file corresponding to your operating
- system and compiler. These <filename
- class="libraryfile">.conf</filename> files are located in the
- <filename class="directory">config</filename> directory. For
- example, to use &gcc; with the &linux; operating system, use
- <filename
- class="libraryfile">config/LINUXGCC.conf</filename>.</para>
-
- <para>The configuration file usually does not need
- modification. However, if you are using &mm;, ensure
- <varname>shmem_default_dir</varname> specifies its location.
- For example, the &author; modified the value to
- <statement>"/home/oldham/pooma/mm-1.1.3"</statement>.</para>
- </listitem>
- <listitem>
- <para>Prepare to compile the source code by configuring it
- using the <command>configure</command> command. Specify the
- configuration file using the <command>--arch</command> option.
- Its argument should be the configuration file's name, omitting
- its <filename class="libraryfile">.conf</filename> suffix. For
- example, <command>--arch LINUXGCC</command>. Some other
- options include
- <variablelist>
- <varlistentry>
- <term>--help</term>
- <listitem>
- <para>lists all the available options</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--shmem --nompi</term>
- <listitem>
- <para>indicates use of &mm;, not &mpi;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--mpi --noshmem</term>
- <listitem>
- <para>indicates use of &mpi;, not &mm;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--opt</term>
- <listitem>
- <para>causes the compiler to produce optimized source code</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--noex</term>
- <listitem>
- <para>prevents use of &cc; exceptions</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--prefix <replaceable>directory</replaceable></term>
- <listitem>
- <para>specifies the installation directory where the
- library will be copied rather than the default.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- For example, the &author; uses <command>./configure --arch
- LINUXGCC --shmem --nompi --noex --prefix
- ${HOME}/pooma/cheetah-1.0 --opt</command>. The
- <command>--arch LINUXGCC</command> indicates use of &gcc;
- under a &linux; operating system. The &mm; library is used,
- but &cc; exceptions are not. The latter choice matches
- &pooma;'s default choice. The library will be installed in
- the <filename
- class="directory">${HOME}/pooma/cheetah-1.0</filename>.
- Finally, the library code will be optimized, hopefully running
- faster than unoptimized code.</para>
- </listitem>
- <listitem>
- <para>Follow the directions printed by
- <command>configure</command>: Change directories to the
- <filename class="directory">lib</filename> subdirectory named
- by the <command>--arch</command> argument and then type
- <command>make</command> to compile the source code and create
- the library.</para>
- </listitem>
- <listitem>
- <para>Optionally ensure the library works correctly by issuing
- the <command>make tests</command> command.</para>
- </listitem>
- <listitem>
- <para>Install the library by issuing the <command>make
- install</command> command. This copies the library files to
- the installation directory. The <filename
- class="directory">cheetah-1.0</filename> directory containing
- the source code may now be removed.</para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="installation-distributed_computing-pooma">
- <title>Configuring &pooma; When Using &cheetah;</title>
-
- <para>To use &pooma; with &cheetah;, one must tell &pooma; the
- location of the &cheetah; library using the
- <command>--messaging</command> configuration option. To do this,
- <orderedlist spacing="compact">
- <listitem>
- <para>Set the &cheetah; directory environment variable
- <envar>CHEETAHDIR</envar> to the directory containing the
- installed &cheetah; library. For
- example, <command>declare -x
- CHEETAHDIR=${HOME}/pooma/cheetah-1.0</command> specifies the
- installation directory used in the previous section.</para>
- </listitem>
- <listitem>
- <para>When configuring &pooma;, specify the
- <command>--messaging</command> option. For example,
- <command>./configure --arch LINUXgcc --opt
- --messaging</command> configures for &linux;, &gcc;, and an
- optimized library using &cheetah;.</para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <!-- HERE -->
- </section>
- </appendix>
-
-
- <appendix id="compilation_errors">
- <title>Dealing with Compilation Errors</title>
-
- <para>Base this low-priority section on <filename
- class="libraryfile">errors.html</filename>. QUESTION: Where is
- <filename class="libraryfile">errors.html</filename>?</para>
-
- </appendix>
-
-
- <appendix id="tmp_appendix">
- <title>TMP: Notes to Myself</title>
-
- <section id="tmp-miscellaneous">
- <title>Miscellaneous</title>
-
- <orderedlist>
- <listitem>
- <para>QUESTION: How do I know when to use a type name versus just
- the concept? For example, when do I use <quote>array</quote>
- versus &array;?</para>
- </listitem>
-
- <listitem>
- <para>Krylov solvers are described in Section 3.5.2 of
- <filename>papers/pooma.ps</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Section 5, "The Polygon Overlay Problem," describes
- porting an <acronym>ANSI</acronym> &c; program to &pooma;.</para>
- </listitem>
-
- <listitem>
- <para>A good example book: <emphasis>STL Tutorial and Reference
- Guide: &cc; Programming with the Standard Template
- Library</emphasis>, second edition, by David R. Musser,
- Gillmer J. Derge, and Atul Sanai, ISBN 0-201-37923-6,
- QA76.73.C153.M87 2001.</para>
- </listitem>
-
- <listitem>
- <para>One STL reference book listed functions in margin notes,
- easing finding material. Do this.</para>
- </listitem>
-
- <listitem>
- <para>QUESTION: Does Berna Massingill at Trinity University have
- any interest ior access to any parallel computers?</para>
- </listitem>
- </orderedlist>
-
- </section>
-
-
- <section id="tmp-html_tutorials">
- <title>Existing HTML Tutorials</title>
-
- <para>All these tutorials are out-of-date, but the ideas and text
- may still be relevant.</para>
-
- <variablelist>
- <varlistentry><term><filename
- class="libraryfile">index.html</filename></term>
- <listitem><para>list of all tutorials. No useful
- material.</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">introduction.html</filename></term>
- <listitem><para>data-parallel Laplace solver using Jacobi
- iteration ala <command>Doof2d</command></para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">background.html</filename></term>
- <listitem><para>short, indirect introduction to &pete;; parallel
- execution model; &cc;; templates; &stl;; expression
- templates</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-01.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">Layout.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">parallelism.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">self-test.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">threading.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-03.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-04.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-05.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-06.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-07.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-08.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-09.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-10.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-11.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-12.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- <varlistentry><term><filename
- class="libraryfile">tut-13.html</filename></term>
- <listitem><para>UNFINISHED</para></listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- </appendix>
-
-
- <!-- Bibliography -->
-
- <bibliography id="bibliography">
- <title>Bibliography</title>
-
- <para>FIXME: How do I process these entries?</para>
-
- <biblioentry>
- <abbrev>mpi99</abbrev>
- <authorgroup>
- <author>
- <firstname>William</firstname><surname>Gropp</surname>
- </author>
- <author>
- <firstname>Ewing</firstname><surname>Lusk</surname>
- </author>
- <author>
- <firstname>Anthony</firstname><surname>Skjellum</surname>
- </author>
- </authorgroup>
- <copyright>
- <year>1999</year>
- <holder>Massachusetts Institute of Technology</holder>
- </copyright>
- <isbn>0-262-57132-3</isbn>
- <publisher>
- <publishername>The MIT Press</publishername>
- <address>Cambridge, MA</address>
- </publisher>
- <title>Using MPI</title>
- <subtitle>Portable Parallel Programming with the Message-Passing Interface</subtitle>
- <edition>second edition</edition>
- </biblioentry>
- </bibliography>
-
-
- <!-- Glossary -->
-
- <glossary id="glossary">
- <title>Glossary</title>
-
- <para>ADD: Make sure all entries are indexed and perhaps point back
- to their first use. WARNING: This is constructed by hand so it is
- likely to be full of inconsistencies and errors.</para>
-
- <glossdiv>
- <title>S</title>
-
- <glossentry id="glossary-suite_name">
- <glossterm>Suite Name</glossterm>
- <glossdef>
- <para>An arbitrary string denoting a particular toolkit
- configuration. For example, the string
- <quote>SUNKCC-debug</quote> might indicate a configuration for
- the <trademark>Sun</trademark> <productname>Solaris</productname>
- operating system and the &kcc; &cc; compiler with debugging
- support. By default, the suite name it is equal to the
- configuration's architecture name.</para>
- </glossdef>
- </glossentry>
- </glossdiv>
- </glossary>
-
-
- <!-- Index -->
-
- &genindex.sgm;
-
- </book>
--- 0 ----
Index: tutorial.xml
===================================================================
RCS file: tutorial.xml
diff -N tutorial.xml
*** /dev/null Fri Mar 23 21:37:44 2001
--- tutorial.xml Tue Dec 11 13:31:10 2001
***************
*** 0 ****
--- 1,1051 ----
+ <chapter id="tutorial">
+ <title>A Tutorial Introduction</title>
+
+ <para>UPDATE: In the following paragraph, fix the cross-reference
+ to the actual section.</para>
+
+ <para>&pooma; provides different containers and processor
+ configurations and supports different implementation styles, as
+ described in <xref linkend="introduction"></xref>. In this
+ chapter, we present several different implementations of the
+ &doof2d; two-dimensional diffusion simulation program:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>a C-style implementation omitting any use of &pooma;
+ computing each array element individually,</para>
+ </listitem>
+ <listitem>
+ <para>a &pooma; &array; implementation computing each array
+ element individually,</para>
+ </listitem>
+ <listitem>
+ <para>a &pooma; &array; implementation using data-parallel
+ statements,</para>
+ </listitem>
+ <listitem>
+ <para>a &pooma; &array; implementation using stencils, which
+ support local computations,</para>
+ </listitem>
+ <listitem>
+ <para>a stencil-based &pooma; &array; implementation supporting
+ computation on multiple processors</para>
+ </listitem>
+ <listitem>
+ <para>a &pooma; &field; implementation using data-parallel
+ statements, and</para>
+ </listitem>
+ <listitem>
+ <para>a data-parallel &pooma; &field; implementation for
+ multi-processor execution.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>These illustrate the &array;, &field;, &engine;, layout,
+ mesh, and domain data types. They also illustrate various
+ immediate computation styles (element-wise accesses, data-parallel
+ expressions, and stencil computation) and various processor
+ configurations (one sequential processor and multiple
+ processors).</para>
+
+ <figure float="1" id="tutorial-doof2d_averagings">
+ <title>&doof2d; Averagings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/doof2d.201" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>The Initial Configuration</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/doof2d.202" format="EPS"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>After the First Averaging</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/doof2d.203" format="EPS"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>After the Second Averaging</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <para>The &doof2d; diffusion program starts with a two-dimensional
+ grid of values. To model an initial density, all grid values are
+ zero except for one nonzero value in the center. Each averaging,
+ each grid element, except the outermost ones, updates its value by
+ averaging its value and its eight neighbors. To avoid overwriting
+ grid values before all their uses occur, we use two arrays, reading
+ the first and writing the second and then reversing their roles
+ within each iteration.</para>
+
+ <para>Figure <xref linkend="tutorial-doof2d_averagings"></xref>
+ illustrates the averagings. Initially, only the center element has
+ nonzero value. To form the first averaging, each element's new
+ value equals the average of its and its neighbors' previous values.
+ Thus, the initial nonzero value spreads to a three-by-three grid.
+ The averaging continues, spreading to a five-by-five grid of
+ nonzero values. Values in outermost grid cells are always
+ zero.</para>
+
+ <para>Before presenting various implementations of %doof2d;, we
+ explain how to install the &poomaToolkit;.</para>
+
+ <para>REMOVE: &doof2d; algorithm and code is illustrated in
+ Section 4.1 of
+ <filename>pooma-publications/pooma.ps</filename>. It includes a
+ figure illustrating parallel communication of data.</para>
+
+ <section id="tutorial-installation">
+ <title>Installing &pooma;</title>
+
+ <para>ADD: How does one install &pooma; using Windows or Mac?</para>
+
+ <para>UPDATE: Make a more recent &pooma; source code file
+ available on &poomaDownloadPage;. For example,
+ <quote>LINUXgcc.conf</quote> is not available.</para>
+
+ <para>In this section, we describe how to obtain, build, and
+ install the &poomaToolkit;. We focus on installing under the
+ Unix operating system. Instructions for installing on computers
+ running Microsoft Windows or MacOS, as well as more extensive
+ instructions for Unix, appear in <xref
+ linkend="installation"></xref>.</para>
+
+ <para>Obtain the &pooma; source code <filename
+ path="http://www.codesourcery.com/pooma/downloads_folder/">&poomaSourceFile;</filename>
+ from the &pooma; download page (&poomaDownloadPage;) available off
+ the &pooma; home page (&poomaHomePage;). The <quote>tgz</quote>
+ indicates this is a compressed tar archive file. To extract the
+ source files, use <command>tar xzvf &poomaSourceFile;</command>.
+ Move into the source code directory <filename
+ class="directory">&poomaSource;</filename> directory; e.g.,
+ <command>cd &poomaSource;</command>.</para>
+
+ <para>Configuring the source code prepares the necessary paths for
+ compilation. First, determine a configuration file in
+ corresponding to your operating system and compiler in the
+ <filename class="directory">config/arch/</filename> directory.
+ For example, <filename
+ class="libraryfile">LINUXgcc.conf</filename> supports compiling
+ under a &linux; operating system with &gcc; and <filename
+ class="libraryfile">SGI64KCC.conf</filename> supports compiling
+ under a 64-bit <application>SGI</application> Unix operating
+ system with &kcc;. Then, configure the source code:
+ <command>./configure &dashdash;arch LINUXgcc &dashdash;opt &dashdash;suite
+ LINUXgcc-opt</command>. The architecture argument to the
+ <command>&dashdash;arch</command> option is the name of the corresponding
+ configuration file, omitting its <filename
+ class="libraryfile">.conf</filename> suffix. The
+ <command>&dashdash;opt</command> indicates the &poomaToolkit; will
+ contain optimized source code, which makes the code run more
+ quickly but may impede debugging. Alternatively, the
+ <command>&dashdash;debug</command> option supports debugging. The
+ <glossterm linkend="glossary-suite_name">suite name</glossterm>
+ can be any arbitrary string. We chose
+ <command>LINUXgcc-opt</command> to remind us of the architecture
+ and optimization choice. <filename
+ class="libraryfile">configure</filename> creates subdirectories
+ named by the suite name <quote>LINUXgcc-opt</quote> for use when
+ compiling the source files. Comments at the beginning of
+ <filename
+ class="libraryfile">lib/<replaceable>suiteName</replaceable>/PoomaConfiguration.h</filename>
+ record the configuration arguments.</para>
+
+ <para>To compile the source code, set the
+ <envar>POOMASUITE</envar> environment variable to the suite name
+ and then type <command>make</command>. To set the environment
+ variable for the <application>bash</application> shell use
+ <command>export
+ POOMASUITE=<replaceable>suiteName</replaceable></command>,
+ substituting the suite name's
+ <replaceable>suiteName</replaceable>. For the
+ <application>csh</application> shell, use <command>setenv
+ POOMASUITE LINUXgcc-opt</command>. Issuing the
+ <command>make</command> command compiles the &pooma; source code
+ files to create the &pooma; library. The &pooma; makefiles assume
+ the <trademark>GNU</trademark> &make; so substitute the proper
+ command if necessary. The &pooma; library can be found in, e.g.,
+ <filename
+ class="libraryfile">lib/LINUXgcc-opt/libpooma-gcc.a</filename>.</para>
+ </section>
+
+ <section id="tutorial-hand_coded">
+ <title>Hand-Coded Implementation</title>
+
+ <para>Before implementing &doof2d; using the &poomaToolkit;, we
+ present a hand-coded implementation of &doof2d;. See <xref
+ linkend="tutorial-hand_coded-doof2d"></xref>. After querying the
+ user for the number of averagings, the arrays' memory is
+ allocated. Since the arrays' size is not known at compile time,
+ the arrays are accesses via pointers to allocated dynamic memory.
+ This memory is deallocated at the program's end to avoid memory
+ leaks. The arrays are initialized with initial conditions. For
+ the <varname>b</varname> array, all values except the central ones
+ have nonzero values. Only the outermost values of the
+ <varname>a</varname> array need be initialized to zero, but we
+ instead initialize them all using the loop used by
+ <varname>b</varname>.</para>
+
+ <para>The simulation's kernel consists of triply nested loops.
+ The outermost loop controls the number of iterations. The inner
+ nested loops iterate through the arrays' elements, excepting the
+ outermost elements; note the loop indices range from 1 to n-2
+ while the array indices range from 0 to n-1. Each
+ <varname>a</varname> value is assigned the average of its
+ corresponding value in <varname>b</varname> and the latter's
+ neighbors. Values in the two-dimensional grids are accessed using
+ two sets of brackets, e.g., <statement>a[i][j]</statement>. After
+ assigning values to <varname>a</varname>, a second averaging reads
+ values in <varname>a</varname>, writing values in
+ <varname>b</varname>.</para>
+
+ <para>After the kernel finishes, the final central value is
+ printed. If the desired number of averagings is even, the value
+ in <varname>b</varname> is printed; otherwise, the value in
+ <varname>a</varname> is used. Finally, the dynamically-allocated
+ memory must be freed to avoid memory leaks.</para>
+
+ <example id="tutorial-hand_coded-doof2d">
+ <title>Hand-Coded Implementation of &doof2d;</title>
+ &doof2d-c-element;
+ <calloutlist>
+ <callout arearefs="tutorial-hand_coded-doof2d-nuaveragings">
+ <para>The user specifies the desired number of averagings.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-array_storage">
+ <para>These variables point to the two-dimensional,
+ dynamically-allocated grids so we use a pointer to a pointer to
+ a &double;.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-grid_size">
+ <para>The user enters the desired grid size. The grid will be
+ a square with <varname>n</varname> by <varname
+ lang="c++">n</varname> grid cells.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-allocation">
+ <para>Memory for the arrays is allocated. By default, the
+ array indices are zero-based.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-initialization">
+ <para>Initially, all grid values are zero except for the one
+ nonzero value at the center of the second array. Array
+ positions are indicated using two brackets, e.g.,
+ <statement>a[i][j]</statement>. A better implementation might
+ initialize only the outermost values of the
+ <varname>a</varname> array.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-constants">
+ <para>These constants indicate the number of iterations, and
+ the average weighting.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-first_write">
+ <para>Each <varname>a</varname> value, except an outermost one,
+ is assigned the average of its analogous <varname>b</varname>
+ value and that value's neighbors. Note the loop indices ensure
+ the outermost values are not changed. The
+ <varname>weight</varname>'s value ensures the computation is an
+ average.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-second_write">
+ <para>The second averaging computes <varname>b</varname>'s
+ values using values stored in <varname>a</varname>.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-answer">
+ <para>After the averagings finish, the central value is printed.</para>
+ </callout>
+ <callout arearefs="tutorial-hand_coded-doof2d-deallocation">
+ <para>The dynamically-allocated memory must be deallocated to
+ avoid memory leaks.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>To compile the executable, change directories to the &pooma;
+ <filename
+ class="directory">&poomaExampleDirectory;/Doof2d</filename>
+ directory. Ensure the <envar>POOMASUITE</envar> environment
+ variable specifies the desired suite name
+ <replaceable>suiteName</replaceable>, as we did when compiling
+ &pooma; in the previous section <xref
+ linkend="tutorial-installation"></xref>. Issuing the
+ <command>make Doof2d-C-element</command> command creates the
+ executable
+ <command><replaceable>suiteName</replaceable>/Doof2d-C-element</command>.</para>
+
+ <para>When running the executable, specify the desired a
+ nonnegative number of averagings and the nonnegative number of
+ grid cells along any dimension. The resulting grid has the same
+ number of cells along each dimension. After the executable
+ finishes, the resulting value of the central element is
+ printed.</para>
+ </section>
+
+
+ <section id="tutorial-array_elementwise">
+ <title>Element-wise &array; Implementation</title>
+
+ <para>The simplest way to use the &poomaToolkit; is to
+ use the &pooma; &array; class instead of &c; arrays. &array;s
+ automatically handle memory allocation and deallocation, support a
+ wider variety of assignments, and can be used in expressions.
+ <xref linkend="tutorial-array_elementwise-doof2d"></xref>
+ implements &doof2d; using &array;s and element-wise accesses.
+ Since the same algorithm is used as <xref
+ linkend="tutorial-hand_coded-doof2d"></xref>, we will concentrate
+ on the differences.</para>
+
+ <example id="tutorial-array_elementwise-doof2d">
+ <title>Element-wise &array; Implementation of &doof2d;</title>
+ &doof2d-array-element;
+ <calloutlist>
+ <callout arearefs="tutorial-array_elementwise-doof2d-header">
+ <para>To use &pooma; &array;s, the <filename
+ class="headerfile">Pooma/Arrays.h</filename> must be included.</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-pooma_initialize">
+ <para>The &poomaToolkit; structures must be constructed before
+ their use.</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-domain">
+ <para>Before creating an &array;, its domain must be specified.
+ The <varname>N</varname> interval represents the
+ one-dimensional integral set {0, 1, 2, …, n-1}. An
+ <type>Interval<2></type> object represents the entire
+ two-dimensional index domain.</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-array_creation">
+ <para>An &array;'s template parameters indicate its dimension,
+ its value type, and how the values will be stored or computed.
+ The &brick; &engine; type indicates values will be directly
+ stored. It is responsible for allocating and deallocating
+ storage so <statement>new</statement> and
+ <statement>delete</statement> statements are not necessary.
+ The <varname>vertDomain</varname> specifies the array index
+ domain.</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-initialization">
+ <para>The first statement initializes all &array; values to the
+ same scalar value. This is possible because each &array;
+ <quote>knows</quote> its domain. The second statement
+ illustrates &array; element access. Indices, separated by
+ commas, are surrounded by parentheses rather than surrounded by
+ square brackets (<statement>[]</statement>).</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-first_write">
+ <para>&array; element access uses parentheses, rather than
+ square brackets</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-deallocation">
+ <para>Since &array;s are first-class objects, they
+ automatically deallocate any memory they require, eliminating
+ memory leaks.</para>
+ </callout>
+ <callout arearefs="tutorial-array_elementwise-doof2d-pooma_finish">
+ <para>The &poomaToolkit; structures must be destructed after
+ their use.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>We describe the use of &array; and the &poomaToolkit; in
+ <xref linkend="tutorial-array_elementwise-doof2d"></xref>.
+ &array;s, declared in the <filename
+ class="headerfile">Pooma/Arrays.h</filename>, are first-class
+ objects. They <quote>know</quote> their index domain, can be used
+ in expressions, can be assigned scalar and array values, and
+ handle their own memory allocation and deallocation.</para>
+
+ <para>The creation of the <varname>a</varname> and
+ <varname>b</varname> &array;s requires an object specifying their
+ index domains. Since these are two-dimensional arrays, their
+ index domains are also two dimensional. The two-dimensional
+ <type>Interval<2></type> object is the Cartesian product of
+ two one-dimensional <type>Interval<1></type> objects, each
+ specifying the integral set {0, 1, 2, …, n-1}.</para>
+
+ <para>An &array;'s template parameters indicate its dimension, the
+ type of its values, and how the values are stored. Both
+ <varname>a</varname> and <varname>b</varname> are two-dimension
+ arrays storing &double;s so their <varname>dimension</varname>
+ is 2 and its element type is &double;. An &engine; stores an
+ &array;'s values. For example, a &brick; &engine; explicitly
+ stores all values. A &compressiblebrick; &engine; also explicitly
+ stores values if more than value is present, but, if all values
+ are the same, storage for just that value is required. Since an
+ engine can store its values any way it desires, it might instead
+ compute its values using a function or compute the values stored
+ in separate engines. In practice, most explicitly specified
+ &engine;s are either &brick; or &compressiblebrick;.</para>
+
+ <para>&array;s support both element-wise access and scalar
+ assignment. Element-wise access uses parentheses, not square
+ brackets. For example, <statement>b(n/2,n/2)</statement>
+ specifies the central element. The scalar assignment <statement>b
+ = 0.0</statement> assigns the same 0.0 value to all array
+ elements. This is possible because the array knows the extent of
+ its domain.</para>
+
+ <para>Any program using the &poomaToolkit; must initialize the
+ toolkit's data structures using
+ <statement>Pooma::initialize(argc,argv)</statement>. This
+ extracts &pooma;-specific command-line options from the
+ command-line arguments in <varname>argv</varname> and initializes
+ the inter-processor communication and other data structures. When
+ finished, <statement>Pooma::finalize()</statement> ensures all
+ computation has finished and the communication and other data
+ structures are destructed.</para>
+ </section>
+
+
+ <section id="tutorial-array_data_parallel">
+ <title>Data-Parallel &array; Implementation</title>
+
+ <para>&pooma; supports data-parallel &array; accesses. Many
+ algorithms are more easily expressed using data-parallel
+ expressions. Also, the &poomaToolkit; might be able to reorder
+ the data-parallel computations to be more efficient or distribute
+ them among various processors. In this section, we concentrate
+ the differences between the data-parallel implementation of
+ &doof2d; listed in <xref
+ linkend="tutorial-array_parallel-doof2d"></xref> and the
+ element-wise implementation listed in the previous section <xref
+ linkend="tutorial-array_elementwise"></xref>.</para>
+
+ <example id="tutorial-array_parallel-doof2d">
+ <title>Data-Parallel &array; Implementation of &doof2d;</title>
+ &doof2d-array-parallel;
+ <calloutlist>
+ <callout arearefs="tutorial-array_parallel-doof2d-blockAndEvaluate">
+ <para>&pooma; may reorder computation of statements. Calling
+ <function>Pooma::blockAndEvaluate</function> ensures all
+ computation finishes before accessing a particular array
+ element.</para>
+ </callout>
+ <callout arearefs="tutorial-array_parallel-doof2d-innerdomain">
+ <para>These variables specify one-dimensional domains {1, 2,
+ …, n-2}. Their Cartesian product specifies the domain
+ of the array values that are modified.</para>
+ </callout>
+ <callout arearefs="tutorial-array_parallel-doof2d-first_write">
+ <para>Data-parallel expressions replace nested loops and array
+ element accesses. For example, <statement>a(I,J)</statement>
+ represents the subset of the <varname>a</varname> array having
+ a domain equal to the Cartesian product of <varname>I</varname>
+ and <varname>J</varname>. Intervals can shifted by an additive
+ or multiplicative constant.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>Data-parallel expressions apply domain objects to containers
+ to indicate a set of parallel expressions. For example, in the
+ program listed above, <statement>a(I,J)</statement> specifies all
+ of <varname>a</varname> array excepting the outermost elements.
+ The array's <varname>vertDomain</varname> domain consists of the
+ Cartesian product of {0, 1, 2, …, n-1} and itself, while
+ <varname>I</varname> and <varname>J</varname> each specify {1, 2,
+ …, n-2}. Thus, <statement>a(I,J)</statement> is the subset
+ with a domain of the Cartesian product of {1, 2, …, n-2}
+ and itself. It is called a <firstterm>view</firstterm> of an
+ array. It is itself an array, with a domain and supporting
+ element access, but its storage is the same as
+ <varname>a</varname>'s. Changing a value in
+ <statement>a(I,J)</statement> also changes the same value in
+ <varname>a</varname>. Changing a value in the latter also changes
+ the former if the value is not one of <varname>a</varname>'s
+ outermost elements. The expression
+ <statement>b(I+1,J+1)</statement> indicates the subset of
+ <varname>b</varname> with a domain consisting of the Cartesian
+ product of {2, 3, …, n-1}, i.e., the same domain as
+ <statement>a(I,J)</statement> but shifted up one unit and to the
+ right one unit. Only an &interval;'s value, not its name, is
+ important. Thus, all uses of <varname>J</varname> in this program
+ could be replaced by <varname>I</varname> without changing the
+ semantics.</para>
+
+ <figure float="1" id="tutorial-array_parallel-doof2d-adding_arrays">
+ <title>Adding &array;s</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/doof2d.210" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>Adding two arrays with different domains.</phrase>
+ </textobject>
+ <caption>
+ <para>When adding arrays, values in corresponding positions are
+ added even if they have different indices, indicated by the
+ small numbers adjacent to the arrays.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>The statement assigning to <statement>a(I,J)</statement>
+ illustrates that &array;s may participate in expressions. Each
+ addend is a view of an array, which is itself an array. Each view
+ has the same domain size so their sum can be formed by
+ corresponding elements of each array. For example, the lower,
+ left element of the result equals the sum of the lower, left
+ elements of the addend arrays. For the computation, indices are
+ ignored; only the relative positions within each domain are used.
+ <xref
+ linkend="tutorial-array_parallel-doof2d-adding_arrays"></xref>
+ illustrates adding two arrays with different domain indices. The
+ indices are indicated by the small numbers to the left and the
+ bottom of the arrays. Even though 9 and 3 have different indices
+ (1,1) and (2,0), they are added to each other because they have
+ the same relative positions within the addends.</para>
+
+ <para>Just before accessing individual &array; values, the code
+ contains calls to <function>Pooma::blockAndEvaluate</function>.
+ &pooma; may reorder computation or distribute them among various
+ processors. Before reading an individual &array; value, calling
+ the function ensures all computations affecting its value have
+ finished, i.e., it has the correct value. Calling this function
+ is necessary only when accessing individual array elements because
+ &pooma; cannot determine when to call the function itself. For
+ example, before printing an array, &pooma; will call
+ <function>blockAndEvaluate</function> itself.</para>
+ </section>
+
+
+ <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
+ function object and an indication of the stencil's extent.</para>
+
+ <example id="tutorial-array_stencil-doof2d">
+ <title>Stencil &array; Implementation of &doof2d;</title>
+ &doof2d-array-stencil;
+ <calloutlist>
+ <callout arearefs="tutorial-array_stencil-doof2d-stencil">
+ <para>A stencil is a function object implementing a local
+ operation on an &array;.</para>
+ </callout>
+ <callout
+ arearefs="tutorial-array_stencil-doof2d-stencil_operator">
+ <para>&pooma; applies this function call
+ <function>operator()</function> to the interior domain of an
+ &array;. Although not strictly necessary, the function's
+ template parameter <varname>C</varname> permits using this
+ stencil with &array;s and other containers. The
+ <function>read</function> &array; member function supports only
+ reading values, not writing values, thus possibly permitting
+ faster access.</para>
+ </callout>
+ <callout arearefs="tutorial-array_stencil-doof2d-stencil_extent">
+ <para>These two functions indicate the stencil's size. For
+ each dimension, the stencil extends one cell to the left of (or
+ below) its center and also one call to the right (or above) its
+ center.</para>
+ </callout>
+ <callout
+ arearefs="tutorial-array_stencil-doof2d-stencil_creation">
+ <para>Create the stencil.</para>
+ </callout>
+ <callout arearefs="tutorial-array_stencil-doof2d-first_write">
+ <para>Applying <varname>stencil</varname> to the
+ <varname>b</varname> array and a subset
+ <varname>interiorDomain</varname> of its domain yields an
+ array, which is assigned to a subset of <varname>a</varname>.
+ The stencil's function object is applied to each position in
+ the specified subset of <varname>b</varname>.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>Before we describe how to create a stencil, we describe how
+ to apply a stencil to an array, yielding values. To compute the
+ value associated with index position (1,3), the stencil's center
+ is placed at (1,3). The stencil's
+ <function>upperExtent</function> and
+ <function>lowerExtent</function> functions indicate which &array;
+ values the stencil's function will use. See <xref
+ linkend="tutorial-array_stencil-doof2d-apply_stencil"></xref>.
+ Applying the stencil's function call
+ <function>operator()</function> yields the computed value. To
+ compute multiple &array; values, apply a stencil to the array and
+ a domain object: <statement>stencil(b,
+ interiorDomain)</statement>. This applies the stencil to each
+ position in the domain. The user must ensure that applying the
+ stencil does not access nonexistent &array; values.</para>
+
+ <figure float="1" id="tutorial-array_stencil-doof2d-apply_stencil">
+ <title>Applying a Stencil to an &array;</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/doof2d.211" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>Apply a stencil to position (1,3) of an array.</phrase>
+ </textobject>
+ <caption>
+ <para>To compute the value associated with index position (1,3)
+ of an array, place the stencil's center, indicated with dashed
+ lines, at the position. The computation involves the array
+ values covered by the array and delineated by
+ <function>upperExtent</function> and
+ <function>lowerExtent</function>.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>To create a stencil object, apply the &stencil; type to a
+ function object class. For example,
+ <statement>Stencil<DoofNinePt> stencil</statement> declares
+ the <varname>stencil</varname> object. The function object class
+ must define a function call <function>operator()</function> with a
+ container parameter and index parameters. The number of index
+ parameters, indicating the stencil's center, must equal the
+ container's dimension. For example, <type>DoofNinePt</type>
+ defines <methodname>operator()(const C& c, int i, int
+ j)</methodname>. We templated the container type
+ <varname>C</varname> although this is not strictly necessary. The
+ two index parameters <varname>i</varname> and <varname>j</varname>
+ ensure the stencil works with two-dimensional containers. The
+ <methodname>lowerExtent</methodname> indicates how far to the left
+ (or below) the stencil extends beyond its center. Its parameter
+ indicates a particular dimension. Index parameters
+ <varname>i</varname> and <varname>j</varname> are in dimension 0
+ and 1. <methodname>upperExtent</methodname> serves an
+ analogous purpose. The &poomaToolkit; uses these functions when
+ distribution computation among various processors, but it does not
+ use these functions to ensure nonexistent &array; values are not
+ accessed. Caveat stencil user!</para>
+ </section>
+
+
+ <section id="tutorial-array_distributed">
+ <title>Distributed &array; Implementation</title>
+
+ <para>A &pooma; program can execute on one or multiple processors.
+ To convert a program designed for uniprocessor execution to a
+ program designed for multiprocessor execution, the programmer need
+ only specify how each container's domain should be split into
+ <quote>patches</quote>. The &poomaToolkit; automatically
+ distributes the data among the available processors and handles
+ any required communication among processors.</para>
+
+ <example id="tutorial-array_distributed-doof2d">
+ <title>Distributed Stencil &array; Implementation of &doof2d;</title>
+ &doof2d-array-distributed;
+ <calloutlist>
+ <callout arearefs="tutorial-array_distributed-doof2d-io">
+ <para>Multiple copies of a distributed program may
+ simultaneously run, perhaps each having its own input and
+ output. Thus, we use command-line arguments to pass input to
+ the program. Using an &inform; object ensures only one program
+ produces output.</para>
+ </callout>
+ <callout arearefs="tutorial-array_distributed-doof2d-layout">
+ <para>The <type>UniformGridPartition</type> declaration
+ specifies how an array's domain will be partition, of split,
+ into patches. Guard layers are an optimization that can reduce
+ data communication between patches. The
+ <type>UniformGridLayout</type> declaration applies the
+ partition to the given domain, distributing the resulting
+ patches among various processors.</para>
+ </callout>
+ <callout arearefs="tutorial-array_distributed-doof2d-remote">
+ <para>The <type>MultiPatch</type> &engine; distributes requests
+ for &array; values to the associated patch. Since a patch may
+ associated with a different processor, its
+ <quote>remote</quote> engine has type
+ <type>Remote<Brick></type>. &pooma; automatically
+ distributes the patches among available memories and
+ processors.</para>
+ </callout>
+ <callout
+ arearefs="tutorial-array_distributed-doof2d-first_write">
+ <para>The stencil computation, whether for one processor or
+ multiple processors, is the same.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>Supporting distributed computation requires only minor code
+ changes. These changes specify how each container's domain is
+ distributed among the available processors and how input and
+ output occurs. The rest of the program, including all the
+ computations, remains the same. When running, the &pooma;
+ executable interacts with the run-time library to determine which
+ processors are available, distributes the containers' domains, and
+ automatically handles all necessary interprocessor communication.
+ The same executable runs on one or many processors. Thus, the
+ programmer can write one program, debugging it on a uniprocessor
+ computer and running it on a supercomputer.</para>
+
+ <figure float="1" id="tutorial-array_distributed-doof2d-distributed_model">
+ <title>The &pooma; Distributed Computation Model</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/distributed.101" format="EPS" align="center"></imagedata>
+ </imageobject>
+ <textobject>
+ <phrase>the &pooma; distributed computation model.</phrase>
+ </textobject>
+ <caption>
+ <para>The &pooma; distributed computation model combines
+ partitioning containers' domains and the computer configuration
+ to create a layout.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>&pooma;'s distributed computing model separates container
+ domain concepts from computer configuration concepts. See <xref
+ linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>.
+ The program indicates how each container's domain will be
+ partitioned. This process is represented in the upper left corner
+ of the figure. A user-specified <firstterm>partition</firstterm>
+ specifies how to split the domain into pieces. For example, the
+ illustrated partition splits the domain into three equal-sized
+ pieces along the x-dimension and two equal-sized pieces along the
+ y-dimension. Thus, the domain is split into
+ <firstterm>patches</firstterm>. The partition also specifies
+ external and internal guard layers. A <firstterm>guard
+ layer</firstterm> is a domain surrounding a patch. A patch's
+ computation only reads but does not write these guarded values.
+ An <firstterm>external guard layer</firstterm> conceptually
+ surrounds the entire container domain with boundary values whose
+ presence permits all domain computations to be performed the same
+ way even for values along the domain's edge. An
+ <firstterm>internal guard layer</firstterm> duplicates values from
+ adjacent patches so communication 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>The computer configuration of shared memory and processors
+ is determined by the run-time system. See the upper right portion
+ of <xref
+ linkend="tutorial-array_distributed-doof2d-distributed_model"></xref>.
+ A <firstterm>context</firstterm> is a collection of shared memory
+ and processors that can execute a program or a portion of a
+ program. For example, a two-processor desktop computer might have
+ memory accessible to both processors so it is a context. A
+ supercomputer consisting of desktop computers networked together
+ might have as many contexts as computers. The run-time system,
+ e.g., the Message Passing Interface (&mpi;) Communications Library
+ (FIXME: xref linkend="mpi99", <ulink
+ url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) or the &mm;
+ Shared Memory Library (<ulink
+ url="http://www.engelschall.com/sw/mm/"></ulink>), communicates
+ the available contexts to the executable. &pooma; must be
+ configured for the particular run-time system. See <xref
+ linkend="installation-distributed_computing"></xref>.</para>
+
+ <para>A <firstterm>layout</firstterm> combines patches with
+ contexts so the program can be executed. If &distributedtag; is
+ specified, the patches are distributed among the available
+ contexts. If &replicatedtag; is specified, each set of patches is
+ replicated among each context. Regardless, the containers'
+ domains are now distributed among the contexts so the program can
+ run. When a patch needs data from another patch, the &pooma;
+ toolkit sends messages to the desired patch uses a message-passing
+ library. All such communication is automatically performed by the
+ toolkit with no need for programmer or user input.</para>
+
+ <para>FIXME: The two previous paragraphs demonstrate confusion
+ between <quote>run-time system</quote> and <quote>message-passing
+ library</quote>.</para>
+
+ <para>Incorporating &pooma;'s distributed computation model into a
+ program requires writing very few lines of code. <xref
+ linkend="tutorial-array_distributed-doof2d"></xref> illustrates
+ this. The <varname>partition</varname> declaration creates a
+ <type>UniformGridPartition</type> splitting each dimension of a
+ container's domain into equally-sized
+ <varname>nuProcessors</varname> pieces. The first
+ <type>GuardLayers</type> argument specifies each patch will have
+ copy of adjacent patches' outermost values. This may speed
+ computation because a patch need not synchronize its computation
+ with other patches' processors. Since each value's computation
+ requires knowing its surrounding neighbors, the internal guard
+ layer is one layer deep. The second <type>GuardLayers</type>
+ argument specifies no external guard layer. External guard layers
+ simplify computing values along the edges of domains. Since the
+ program already uses only the interior domain for computation, we
+ do not use this feature.</para>
+
+ <para>The <varname>layout</varname> declaration creates a
+ <type>UniformGridLayout</type> layout. As <xref
+ linkend="tutorial-array_distributed-doof2d"></xref> illustrates,
+ it needs to know a container's domain, a partition, the computer's
+ contexts, and a &distributedtag; or &replicatedtag;. These
+ comprise <varname>layout</varname>'s three parameters; the
+ contexts are implicitly supplied by the run-time system.</para>
+
+ <para>To create a distributed &array;, it should be created using
+ a &layout; object and have a &multipatch; engine. Prior
+ implementations designed for uniprocessors constructed the
+ container using a &domain; object. A distributed implementation
+ uses a &layout; object, which conceptually specifies a &domain;
+ object and its distribution throughout the computer. A
+ &multipatch; engine supports computations using multiple patches.
+ The <type>UniformTag</type> indicates the patches all have the
+ same size. Since patches may reside on different contexts, the
+ second template parameter is <type>Remote</type>. Its
+ <type>Brick</type> template parameter specifies the engine for a
+ particular patch on a particular context. Most distributed
+ programs use <type>MultiPatch<UniformTag, Remote<Brick>
+ ></type> or <type>MultiPatch<UniformTag,
+ Remote<CompressibleBrick> ></type> engines.</para>
+
+ <para>The computations for a distributed implementation are
+ exactly the same as for a sequential implementation. The &pooma;
+ Toolkit and a message-passing library automatically perform all
+ computation.</para>
+
+ <para>Input and output for distributed programs is different than
+ for sequential programs. Although the same instructions run on
+ each context, each context may have its own input and output
+ streams. To avoid dealing with multiple input streams, we pass
+ the input via command-line arguments, which are replicated for
+ each context. Using &inform; streams avoids having multiple
+ output streams print. Any context can print to an &inform; stream
+ but only text sent to context 0 is sent. At the beginning of
+ the program, we create an &inform; object. Throughout the rest of
+ the program, we use it instead of <varname>std::cout</varname> and
+ <varname>std::cerr</varname>.</para>
+
+ <para>The command to run the program is dependent on the run-time
+ system. To use &mpi; with the Irix 6.5 operating system, one
+ can use the <command>mpirun</command> command. For example,
+ <statement>mpirun -np 4 Doof2d-Array-distributed -mpi 2 10
+ 1000</statement> invokes the &mpi; run-time system with four
+ processors. The <statement>-mpi</statement> option tells the
+ &pooma; executable <command>Doof2d-Array-distributed</command> to
+ use the &mpi; Library. The remaining arguments specify the number
+ of processors, the number of averagings, and the array size. The
+ first and last values are used for each dimension. For example,
+ if three processors are specified, then the x-dimension will have
+ three processors and the y-dimension will have three processors,
+ totalling nine processors. The command
+ <statement>Doof2d-Array-distributed -shmem -np 4 2 10
+ 1000</statement> uses the &mm; Shared Memory Library
+ (<statement>-shmem</statement>) and four processors. As for
+ &mpi;, the remaining command-line arguments are specified on a
+ per-dimension basis for the two-dimensional program.</para>
+ </section>
+
+
+ <section id="tutorial-field_data_parallel">
+ <title>Data-Parallel &field; Implementation</title>
+
+ <para>&pooma; &array;s support many scientific computations, but
+ many scientific computations require values distributed throughout
+ space, and &array;s have no spatial extent. &pooma; &field;s,
+ supporting a superset of &array; functionality, model values
+ distributed throughout space.</para>
+
+ <para>A &field; consists of a set of cells distributed through
+ space. Like an &array; cell, each &field; cell is addressed via
+ indices. Unlike an &array; cell, each &field; cell can hold
+ 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
+ diffusion simulation program using &field;s. This simulation does
+ not require any &field;-specific features, but we chose to present
+ this program rather than one using &field;-specific features to
+ permit comparisons with the &array; versions, especially <xref
+ linkend="tutorial-array_parallel-doof2d"></xref>.</para>
+
+ <example id="tutorial-field_parallel-doof2d">
+ <title>Data-Parallel &field; Implementation of &doof2d;</title>
+ &doof2d-field-parallel;
+ <calloutlist>
+ <callout arearefs="tutorial-field_parallel-doof2d-header">
+ <para>To use &field;s, the <filename
+ class="headerfile">Pooma/Fields.h</filename> must be
+ included.</para>
+ </callout>
+ <callout arearefs="tutorial-field_parallel-doof2d-mesh">
+ <para>These statements specify the spacing and number of
+ &field; values. First, a layout is explicitly. Then, a mesh,
+ which specifies the spacing between cells, is created. The
+ &field;'s centering specifies one cell-centered value per
+ cell.</para>
+ </callout>
+ <callout arearefs="tutorial-field_parallel-doof2d-field_creation">
+ <para>&field;'s first template parameter specifies the type of
+ mesh to use. The other template parameters are similar to
+ &array;'s. The constructor arguments specify the &field;'s
+ centering, its domain of cells, and a mesh specifying the
+ cells' spatial arrangement.</para>
+ </callout>
+ <callout arearefs="tutorial-field_parallel-doof2d-first_write">
+ <para>The computation for &field;s is the same as for &array;s
+ because this example does not use any &field;-specific
+ features.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>As mentioned above, the fundamental difference between
+ &array;s and &field;s is the latter has cells and meshes. The
+ &field; declarations reflect this. To declare a &field;, the
+ <filename class="headerfile">Pooma/Fields.h</filename> header file
+ must be included. A &field;'s domain consists of a set of cells,
+ sometimes called positions when referring to &array;s. As for
+ &array;s, a &field;'s domain and its layout must be specified.
+ Since the above program is designed for uniprocessor computation,
+ specifying the domain specifies the layout. A &field;'s
+ <firstterm>mesh</firstterm> specifies its spatial extent. For
+ example, one can ask the mesh for the distance between two cells
+ or for the normals to a particular cell. Cells in a
+ <type>UniformRectilinearMesh</type> all have the same size and are
+ parallelepipeds. To create the mesh, one specifies the layout,
+ the location of the spatial point corresponding to the lower, left
+ domain location, and the size of a particular cell. Since this
+ program does not use mesh computations, our choices do not much
+ matter. We specify the domain's lower, left corner is at spatial
+ location (0.0, 0.0) and each cell's width and height is 1.
+ Thus, the middle of the cell at domain position (3,4) is (3.5,
+ 4.5).</para>
+
+ <para>A &field; cell can contain one or more values although each
+ cell must have the same arrangement. For this simulation, we
+ desire one value per cell so we place that position at the cell's
+ center, i.e., a cell centering. The
+ <function>canonicalCentering</function> function returns such a
+ centering. We defer discussion of the latter two arguments to
+ <xref linkend="sequential"></xref>.</para>
+
+ <para>A &field; declaration is analogous to an &array; declaration
+ but must also specify a centering and a mesh. In <xref
+ linkend="tutorial-array_parallel-doof2d"></xref>, the &array;
+ declaration specifies the array's dimensionality, the value type,
+ the engine type, and a layout. &field; declarations specify the
+ same values. Its first template parameter specifies the mesh's
+ type, which includes an indication of its dimensionality. The
+ second and third template parameters specify the value type and
+ the engine type. Since a &field; has a centering and a mesh in
+ addition to a layout, those arguments are also necessary.</para>
+
+ <para>&field; operations are a superset of &array; operations so
+ the &doof2d; computations are the same as for <xref
+ linkend="tutorial-array_parallel-doof2d"></xref>. &field;
+ accesses require parentheses, not square brackets, and accesses to
+ particular values should be preceded by calls to
+ <function>Pooma::blockAndEvaluate</function>.</para>
+
+ <para>To summarize, &field;s support multiple values per cell and
+ have spatial extent. Thus, their declarations must specify a
+ centering and a mesh. Otherwise, a &field; program is similar to
+ one with &array;s.</para>
+ </section>
+
+
+ <section id="tutorial-field_distributed">
+ <title>Distributed &field; Implementation</title>
+
+ <para>A &pooma; program using &field;s can execute on one or more
+ processors. In <xref
+ linkend="tutorial-array_distributed"></xref>, we demonstrated how
+ to modify a uniprocessor stencil &array; implementation to run on
+ multiple processors. In this section, we demonstrate that the
+ uniprocessor data-parallel &field; implementation of the previous
+ section can be converted. Only the container declarations change;
+ the computations do not. Since the changes are exactly analogous
+ to those in <xref linkend="tutorial-array_distributed"></xref>,
+ our exposition here will be shorter.</para>
+
+ <example id="tutorial-field_distributed-doof2d">
+ <title>Distributed Data-Parallel &field; Implementation of &doof2d;</title>
+ &doof2d-field-distributed;
+ <calloutlist>
+ <callout arearefs="tutorial-field_distributed-doof2d-io">
+ <para>Multiple copies of a distributed program may
+ simultaneously run, perhaps each having its own input and
+ output. Thus, we use command-line arguments to pass input to
+ the program. Using an &inform; stream ensures only one program
+ produces output.</para>
+ </callout>
+ <callout arearefs="tutorial-field_distributed-doof2d-layout">
+ <para>The <type>UniformGridPartition</type> declaration
+ specifies how an array's domain will be partition, of split,
+ into patches. Guard layers are an optimization that can reduce
+ data communication between patches. The
+ <type>UniformGridLayout</type> declaration applies the
+ partition to the given domain, distributing the resulting
+ patches among various processors.</para>
+ </callout>
+ <callout arearefs="tutorial-field_distributed-doof2d-mesh">
+ <para>The mesh and centering declarations are the same for
+ uniprocessor and multi-processor implementations.</para>
+ </callout>
+ <callout arearefs="tutorial-field_distributed-doof2d-remote">
+ <para>The <type>MultiPatch</type> &engine; distributes requests
+ for &array; values to the associated patch. Since a patch may
+ associated with a different processor, its
+ <quote>remote</quote> engine has type
+ <type>Remote<Brick></type>. &pooma; automatically
+ distributes the patches among available memories and
+ processors.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <para>This program can be viewed as the combination of <xref
+ linkend="tutorial-field_parallel-doof2d"></xref> and the changes
+ to form the distributed stencil-based &array; program from the
+ uniprocessor stencil-based &array; program.
+
+ <itemizedlist>
+ <listitem>
+ <para>Distributed programs may have multiple processes, each
+ with its own input and output streams. To pass input to these
+ processes, this programs uses command-line arguments, which are
+ replicated for each process. An &inform; stream accepts data
+ from any context but prints only data from
+ context 0.</para>
+ </listitem>
+ <listitem>
+ <para>A layout for a distributed program specifies a domain, a
+ partition, and a context mapper. A &distributedtag; context
+ mapper tag indicates that pieces of the domain should be
+ distributed among patches, while a &replicatedtag; context
+ mapper tag indicates the entire domain should be replicated to
+ each patch.</para>
+ </listitem>
+ <listitem>
+ <para>A &multipatch; engine supports the use of multiple
+ patches, while a <type>remote</type> engine supports
+ computation distributed among various contexts. Both are
+ usually necessary for distributed computation.</para>
+ </listitem>
+ <listitem>
+ <para>The computation for uniprocessor or distributed
+ implementations remains the same. The &pooma; toolkit
+ automatically handles all communication necessary to ensure
+ up-to-date values are available when needed.</para>
+ </listitem>
+ <listitem>
+ <para>The command to invoke a distributed program is
+ system-dependent. For example, the <statement>mpirun -np 4
+ Doof2d-Field-distributed -mpi 2 10 1000</statement> command
+ might use &mpi; communication.
+ <statement>Doof2d-Field-distributed -shmem -np 4 2 10
+ 1000</statement> might use the &mm; Shared Memory Library.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <!-- FIXME: Do I need a chapter conclusion? -->
+ </chapter>
Index: figures/concepts.mp
===================================================================
RCS file: concepts.mp
diff -N concepts.mp
*** /dev/null Fri Mar 23 21:37:44 2001
--- concepts.mp Tue Dec 11 13:31:10 2001
***************
*** 0 ****
--- 1,207 ----
+ %% Oldham, Jeffrey D.
+ %% 2001Dec04
+ %% Pooma
+
+ %% Illustrations for Pooma Concepts
+
+ %% Assumes TEX=latex.
+
+ input boxes;
+
+ verbatimtex
+ \documentclass[10pt]{article}
+ \input{macros.ltx}
+ \begin{document}
+ etex
+
+
+ %% Container Declaration Concepts and Dependences
+ beginfig(111)
+ numeric unit; unit = 0.9cm;
+ numeric horizSpace; horizSpace = unit;
+ numeric vertSpace; vertSpace = unit;
+
+ % Draw a line between two boxes.
+ vardef drawLine(expr start, stop) =
+ draw b[start].c -- b[stop].c cutbefore bpath b[start] cutafter bpath b[stop];
+ enddef;
+
+ % Create boxes for the concepts.
+ boxit.b0(btex \type{TinyMatrix} etex);
+ boxit.b1(btex \type{Vector} etex);
+ boxit.b2(btex \type{DynamicArray} etex);
+ boxit.b3(btex \type{Array} etex);
+ boxit.b4(btex \type{Field} etex);
+ boxit.b5(btex engine etex);
+ boxit.b6(btex mesh etex);
+ boxit.b7(btex centering etex);
+ boxit.b8(btex layout etex);
+ boxit.b9(btex corner position etex);
+ boxit.b10(btex cell size etex);
+ boxit.b11(btex domain etex);
+ boxit.b12(btex partition etex);
+ boxit.b13(btex context mapper tag etex);
+ boxit.b14(btex guard layer etex);
+ boxit.b15(btex empty etex);
+ boxit.b16(btex distributed only etex); % dashed box surrounding distributed computation only elements
+ boxit.b17(btex \type{Tensor} etex);
+ boxit.b18(btex view box etex);
+ for t = 0 upto 15:
+ fixsize(b[t]);
+ endfor
+ fixsize(b17);
+
+ % Position the boxes.
+ b0.c = origin;
+ % horizontal positioning
+ for u = (0,3), (8,9), (11,12):
+ for t = xpart(u) upto ypart(u):
+ b[t+1].w - b[t].e = (horizSpace,0);
+ endfor
+ endfor
+ for u = (17,0), (5,15), (15,6), (6,7):
+ b[ypart(u)].w - b[xpart(u)].e = (horizSpace,0);
+ endfor
+ % vertical positioning
+ for u = (2,5), (6,9), (8,12), (12,14):
+ b[xpart(u)].s - b[ypart(u)].n = (0,vertSpace);
+ endfor
+ % distributed (dashed) box
+ b16.sw = b14.sw;
+ b16.ne = b13.ne;
+ % container view (dashed) box
+ b18.nw = b2.nw;
+ b18.se = b4.se;
+
+ % Draw the boxes.
+ for t = 0 upto 18:
+ if unknown(b[t].c):
+ show t;
+ show b[t].c;
+ fi
+ endfor
+ for t = 0 upto 14:
+ drawunboxed(b[t]);
+ endfor
+ drawunboxed(b17);
+
+ % Draw the dependences.
+ for t = 0 upto 4: % lines to engine
+ drawLine(t,5);
+ endfor
+ drawLine(17,5);
+ for t = 2 upto 3: % lines to layout
+ drawLine(t,8);
+ endfor
+ for t = 6 upto 7: % lines from field
+ drawLine(4,t);
+ endfor
+ for t = 8 upto 10: % lines from mesh
+ drawLine(6,t);
+ endfor
+ for t = 11 upto 13: % lines from layout
+ drawLine(8,t);
+ endfor
+ drawLine(12,14); % partition - guard layer
+
+ % Draw the dashed box around the distributed dependences.
+ draw bpath b16 dashed evenly;
+ label.llft(btex \textsl{multiprocessor computation only} etex, b16.se);
+
+ % Draw the dashed box around the container view box.
+ draw bpath b18 dashed evenly;
+ label.ulft(btex \textsl{support views} etex, b18.ne);
+ endfig;
+
+
+ %% 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
+
+ % Create and layout boxes for computational Array and Field implementations.
+ numeric interBoxSpace; interBoxSpace = unit; % space between boxes
+ numeric arrowAngle; arrowAngle = 20; % angle for arrow leaving index
+ path upperArrow[];
+ for t = 0 upto 1:
+ boxit.ia[t](btex index etex);
+ boxit.la[t](btex layout etex);
+ boxit.pa[t](btex \begin{tabular}{c} processors \\ memory \end{tabular} etex);
+ boxit.ea[t](btex engine etex);
+ boxit.va[t](btex value etex);
+
+ va[t].w - ea[t].e = (interBoxSpace,0);
+ ea[t].c - ia[t].c = 4(va[t].c - ea[t].c);
+ fixsize(ia[t],ea[t],va[t]);
+ 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);
+ boxit.l7(btex \strut $\mbox{index} \mapsto \mbox{value}$ etex);
+ boxit.l9(btex \strut \type{Field}: etex);
+ boxit.l10(btex \strut $\mbox{indices} \mapsto \mbox{geometric value}$ etex);
+ fixsize(l1,l2,l3,l4,l6,l7,l9,l10);
+
+ ypart(l1.c - l2.c) = 0;
+ xpart(l2.c - 0.5[ia[0].w,va[0].e]) = 0;
+ 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;
+ ypart(l10.w - ia[2].w) = 0;
+ ypart(l9.w - l10.w) = 0;
+ xpart(l9.w - l6.w) = 0;
+
+ % Create and layout the mesh boxes.
+ boxit.ia[2](btex indices etex);
+ boxit.ea[2](btex mesh etex);
+ boxit.va[2](btex geometric value etex);
+ fixsize(ia[2],ea[2],va[2]);
+ ia[1].w - ia[2].w = 0.6(ia[0].w - ia[1].w);
+ ypart(va[2].w - ea[2].e) = ypart(ea[2].w - ia[2].e) = 0;
+ xpart(va[2].e - va[1].e) = 0;
+ xpart(ea[2].c - 0.5[ia[2].c,va[2].c]) = 0;
+
+ % Finish boxes on arrow for computational Array and Field implementations.
+ for t = 0 upto 1:
+ fixpos(ia[t],ea[t],va[t]);
+ upperArrow[t] = ia[t].c{dir arrowAngle} .. ea[t].c cutbefore bpath ia[t] cutafter bpath ea[t];
+ la[t].c = point 1/3 of upperArrow[t];
+ pa[t].c = point 2/3 of upperArrow[t];
+ endfor
+
+ %% Draw the boxes.
+ % Draw the computational Array and Field implementations.
+ for t = 0 upto 1:
+ % fixsize(ia,la,pa,ea,va); fixpos(ia,la,pa,ea,va);
+ draw ia[t].c{dir -arrowAngle} .. ea[t].c cutbefore bpath ia[t] cutafter bpath ea[t];
+ drawboxed(la[t],ea[t]);
+ drawunboxed(ia[t],pa[t],va[t]);
+ draw (subpath (0,1/3) of upperArrow[t]) cutafter bpath la[t];
+ drawarrow (subpath (1/3,2/3) of upperArrow[t]) cutbefore bpath la[t] cutafter bpath pa[t];
+ draw (subpath (2/3,1) of upperArrow[t]) cutbefore bpath pa[t] cutafter bpath ea[t];
+ drawarrow ea[t].e -- va[t].w;
+ endfor
+
+ % Draw the mesh boxes.
+ drawunboxed(ia[2],va[2]);
+ drawboxed(ea[2]);
+ draw ia[2].e -- ea[2].w cutbefore bpath ia[2] cutafter bpath ea[2];
+ drawarrow ea[2].e -- va[2].w cutbefore bpath ea[2] cutafter bpath va[2];
+
+ % Draw the text boxes.
+ for t = 1,2,3,4,6,7,9,10:
+ drawunboxed(l[t]);
+ endfor;
+
+ endfig;
+
+ bye
Index: figures/distributed.mp
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/distributed.mp,v
retrieving revision 1.1
diff -c -p -r1.1 distributed.mp
*** figures/distributed.mp 2001/12/04 00:07:00 1.1
--- figures/distributed.mp 2001/12/11 20:31:10
*************** input boxes;
*** 10,21 ****
verbatimtex
\documentclass[10pt]{article}
\begin{document}
etex
%% Parts of Distributed Computation
beginfig(101)
! numeric unit; unit = 0.9cm;
%% Create the Container Storage Partition subfigure.
numeric arrayWidth; arrayWidth = 2; % as multiple of unit
--- 10,22 ----
verbatimtex
\documentclass[10pt]{article}
+ \input{macros.ltx}
\begin{document}
etex
%% Parts of Distributed Computation
beginfig(101)
! numeric unit; unit = 0.8cm;
%% Create the Container Storage Partition subfigure.
numeric arrayWidth; arrayWidth = 2; % as multiple of unit
*************** beginfig(101)
*** 189,195 ****
%% Draw the subfigure relations structures.
drawunboxed(figurePlus,figureArrow);
! label.rt(btex DistributedTag etex, figureArrow.e);
endfig;
bye
--- 190,196 ----
%% Draw the subfigure relations structures.
drawunboxed(figurePlus,figureArrow);
! label.rt(btex \type{DistributedTag} etex, figureArrow.e);
endfig;
bye
Index: figures/doof2d.mp
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/doof2d.mp,v
retrieving revision 1.1
diff -c -p -r1.1 doof2d.mp
*** figures/doof2d.mp 2001/12/04 00:07:00 1.1
--- figures/doof2d.mp 2001/12/11 20:31:10
***************
*** 8,13 ****
--- 8,14 ----
verbatimtex
\documentclass[10pt]{article}
+ \input{macros.ltx}
\begin{document}
etex
*************** beginfig(201)
*** 64,70 ****
endfor
% Label the grid.
! labelGrid(btex Array \texttt{b}: Initial Configuration etex, nuCells, origin);
endfig;
--- 65,71 ----
endfor
% Label the grid.
! labelGrid(btex Array \varname{b}: Initial Configuration etex, nuCells, origin);
endfig;
*************** beginfig(202)
*** 93,99 ****
endfor
% Label the grid.
! labelGrid(btex Array \texttt{a}: After the first averaging etex, nuCells, origin);
endfig;
--- 94,100 ----
endfor
% Label the grid.
! labelGrid(btex Array \varname{a}: After the first averaging etex, nuCells, origin);
endfig;
*************** beginfig(203)
*** 133,139 ****
endfor
% Label the grid.
! labelGrid(btex Array \texttt{b}: After the second averaging etex, nuCells, origin);
endfig;
--- 134,140 ----
endfor
% Label the grid.
! labelGrid(btex Array \varname{b}: After the second averaging etex, nuCells, origin);
endfig;
Index: figures/macros.ltx
===================================================================
RCS file: macros.ltx
diff -N macros.ltx
*** /dev/null Fri Mar 23 21:37:44 2001
--- macros.ltx Tue Dec 11 13:31:10 2001
***************
*** 0 ****
--- 1,14 ----
+ %% Oldham, Jeffrey D.
+ %% 2001Dec05
+ %% Pooma
+
+ %% Macros for Figures
+
+ %% Consistency between these macros and the DocBook/Jade output is desired.
+
+ \newcommand{\type}[1]{\texttt{#1}}%
+ % Produce a C++ (or other programming language) type.
+ % Requires: 1. the type's name.
+ \newcommand{\varname}[1]{\texttt{#1}}%
+ % Produce a C++ (or other programming language) variable.
+ % Requires: 1. the variable's name.
Index: programs/Doof2d-Array-distributed-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d-Array-distributed-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 Doof2d-Array-distributed-annotated.patch
*** programs/Doof2d-Array-distributed-annotated.patch 2001/12/04 00:07:00 1.1
--- programs/Doof2d-Array-distributed-annotated.patch 2001/12/11 20:31:10
***************
*** 1,8 ****
! *** Doof2d-Array-distributed.cpp Wed Nov 28 07:46:56 2001
! --- Doof2d-Array-distributed-annotated.cpp Wed Nov 28 07:53:31 2001
***************
! *** 1,4 ****
! ! #include <iostream> // has std::cout, ...
! #include <stdlib.h> // has EXIT_SUCCESS
#include "Pooma/Arrays.h" // has Pooma's Array
--- 1,7 ----
! *** Doof2d-Array-distributed.cpp Wed Dec 5 14:04:36 2001
! --- Doof2d-Array-distributed-annotated.cpp Wed Dec 5 14:07:56 2001
***************
! *** 1,3 ****
! #include <stdlib.h> // has EXIT_SUCCESS
#include "Pooma/Arrays.h" // has Pooma's Array
***************
*** 13,19 ****
#include "Pooma/Arrays.h" // has Pooma's Array
***************
! *** 15,19 ****
// (i,j). The "C" template parameter permits use of this stencil
// operator with both Arrays and Fields.
! template <class C>
--- 12,18 ----
#include "Pooma/Arrays.h" // has Pooma's Array
***************
! *** 14,18 ****
// (i,j). The "C" template parameter permits use of this stencil
// operator with both Arrays and Fields.
! template <class C>
***************
*** 26,65 ****
inline
typename C::Element_t
***************
! *** 40,52 ****
! Pooma::initialize(argc,argv);
!
! ! // Ask the user for the number of processors.
long nuProcessors;
! ! std::cout << "Please enter the number of processors: ";
! ! std::cin >> nuProcessors;
! // Ask the user for the number of averagings.
long nuAveragings, nuIterations;
! ! std::cout << "Please enter the number of averagings: ";
! ! std::cin >> nuAveragings;
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
! --- 41,53 ----
! Pooma::initialize(argc,argv);
!
! ! // Ask the user for the number of processors. <co id="tutorial-array_distributed-doof2d-nuprocessors"></co>
long nuProcessors;
! ! std::cout << "Please enter the number of processors: ";
! ! std::cin >> nuProcessors;
! // Ask the user for the number of averagings.
long nuAveragings, nuIterations;
! ! std::cout << "Please enter the number of averagings: ";
! ! std::cin >> nuAveragings;
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
***************
! *** 54,67 ****
// the grid.
long n;
! ! std::cout << "Please enter the array size: ";
! ! std::cin >> n;
// Specify the arrays' domains [0,n) x [0,n).
! Interval<1> N(0, n-1);
--- 25,91 ----
inline
typename C::Element_t
***************
! *** 42,46 ****
! // canot use standard input and output. Instead we use command-line
! // arguments, which are replicated, for input, and we use an Inform
! ! // stream for output.
! Inform output;
!
! --- 44,48 ----
! // canot use standard input and output. Instead we use command-line
! // arguments, which are replicated, for input, and we use an Inform
! ! // stream for output. <co id="tutorial-array_distributed-doof2d-io"></co>
! Inform output;
!
! ***************
! *** 48,52 ****
! if (argc != 4) {
! // Incorrect number of command-line arguments.
! ! output << argv[0] << ": number-of-processors number-of-averagings number-of-values" << std::endl;
! return EXIT_FAILURE;
! }
! --- 50,54 ----
! if (argc != 4) {
! // Incorrect number of command-line arguments.
! ! output << argv[0] << ": number-of-processors number-of-averagings number-of-values" << std::endl;
! return EXIT_FAILURE;
! }
! ***************
! *** 55,63 ****
! // Determine the number of processors.
long nuProcessors;
! ! nuProcessors = strtol(argv[1], &tail, 0);
! // Determine the number of averagings.
long nuAveragings, nuIterations;
! ! nuAveragings = strtol(argv[2], &tail, 0);
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
! --- 57,65 ----
! // Determine the number of processors.
long nuProcessors;
! ! nuProcessors = strtol(argv[1], &tail, 0);
! // Determine the number of averagings.
long nuAveragings, nuIterations;
! ! nuAveragings = strtol(argv[2], &tail, 0);
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
***************
! *** 65,69 ****
! // the grid.
! long n;
! ! n = strtol(argv[3], &tail, 0);
! // The dimension must be a multiple of the number of processors
! // since we are using a UniformGridLayout.
! --- 67,71 ----
// the grid.
long n;
! ! n = strtol(argv[3], &tail, 0);
! // The dimension must be a multiple of the number of processors
! // since we are using a UniformGridLayout.
! ***************
! *** 71,80 ****
// Specify the arrays' domains [0,n) x [0,n).
! Interval<1> N(0, n-1);
***************
*** 70,80 ****
! Interval<2> interiorDomain(I,I);
// Create the distributed arrays.
! --- 55,68 ----
! // the grid.
! long n;
! ! std::cout << "Please enter the array size: ";
! ! std::cin >> n;
// Specify the arrays' domains [0,n) x [0,n).
! Interval<1> N(0, n-1);
--- 96,102 ----
! Interval<2> interiorDomain(I,I);
// Create the distributed arrays.
! --- 73,82 ----
// Specify the arrays' domains [0,n) x [0,n).
! Interval<1> N(0, n-1);
***************
*** 86,92 ****
// Create the distributed arrays.
***************
! *** 70,85 ****
// dimension. Guard layers optimize communication between patches.
// Internal guards surround each patch. External guards surround
! // the entire array domain.
--- 108,114 ----
// Create the distributed arrays.
***************
! *** 83,98 ****
// dimension. Guard layers optimize communication between patches.
// Internal guards surround each patch. External guards surround
! // the entire array domain.
***************
*** 103,109 ****
! Array<2, double, MultiPatch<UniformTag, Remote<Brick> > > b(layout);
// Set up the initial conditions.
! --- 71,86 ----
// dimension. Guard layers optimize communication between patches.
// Internal guards surround each patch. External guards surround
! // the entire array domain. <co id="tutorial-array_distributed-doof2d-layout"></co>
--- 125,131 ----
! Array<2, double, MultiPatch<UniformTag, Remote<Brick> > > b(layout);
// Set up the initial conditions.
! --- 85,100 ----
// dimension. Guard layers optimize communication between patches.
// Internal guards surround each patch. External guards surround
! // the entire array domain. <co id="tutorial-array_distributed-doof2d-layout"></co>
***************
*** 121,127 ****
// Set up the initial conditions.
***************
! *** 89,97 ****
// Create the stencil performing the computation.
! Stencil<DoofNinePt> stencil;
--- 143,149 ----
// Set up the initial conditions.
***************
! *** 104,112 ****
// Create the stencil performing the computation.
! Stencil<DoofNinePt> stencil;
***************
*** 131,137 ****
! // Read from b. Write to a.
a(interiorDomain) = stencil(b, interiorDomain);
! --- 90,98 ----
// Create the stencil performing the computation.
! Stencil<DoofNinePt> stencil;
--- 153,159 ----
! // Read from b. Write to a.
a(interiorDomain) = stencil(b, interiorDomain);
! --- 106,114 ----
// Create the stencil performing the computation.
! Stencil<DoofNinePt> stencil;
***************
*** 142,162 ****
a(interiorDomain) = stencil(b, interiorDomain);
***************
! *** 102,106 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! ! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 103,107 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! ! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 110,111 ****
! --- 111,113 ----
return EXIT_SUCCESS;
}
+ </programlisting>
--- 164,184 ----
a(interiorDomain) = stencil(b, interiorDomain);
***************
! *** 117,121 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! ! output << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 119,123 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! ! output << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 125,126 ****
! --- 127,129 ----
return EXIT_SUCCESS;
}
+ </programlisting>
Index: programs/Doof2d-Array-element-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d-Array-element-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 Doof2d-Array-element-annotated.patch
*** programs/Doof2d-Array-element-annotated.patch 2001/12/04 00:07:00 1.1
--- programs/Doof2d-Array-element-annotated.patch 2001/12/11 20:31:10
***************
*** 1,5 ****
! *** Doof2d-Array-element.cpp Tue Nov 27 11:04:04 2001
! --- Doof2d-Array-element-annotated.cpp Tue Nov 27 12:06:32 2001
***************
*** 1,5 ****
! #include <iostream> // has std::cout, ...
--- 1,5 ----
! *** Doof2d-Array-element.cpp Tue Dec 4 12:02:10 2001
! --- Doof2d-Array-element-annotated.cpp Tue Dec 4 12:24:25 2001
***************
*** 1,5 ****
! #include <iostream> // has std::cout, ...
***************
*** 58,65 ****
// Set up the initial conditions.
! // All grid values should be zero except for the central value.
! a = b = 0.0;
! b(n/2,n/2) = 1000.0;
--- 20,38 ----
// the grid.
long n;
--- 58,65 ----
// Set up the initial conditions.
! // All grid values should be zero except for the central value.
! for (int j = 1; j < n-1; j++)
! for (int i = 1; i < n-1; i++)
--- 20,38 ----
// the grid.
long n;
***************
*** 78,87 ****
// Set up the initial conditions.
! // All grid values should be zero except for the central value. <co id="tutorial-array_elementwise-doof2d-initialization"></co>
! a = b = 0.0;
! b(n/2,n/2) = 1000.0;
***************
! *** 41,49 ****
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
--- 78,87 ----
// Set up the initial conditions.
! // All grid values should be zero except for the central value. <co id="tutorial-array_elementwise-doof2d-initialization"></co>
! for (int j = 1; j < n-1; j++)
! for (int i = 1; i < n-1; i++)
***************
! *** 43,51 ****
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
***************
*** 91,97 ****
! a(i,j) = weight *
(b(i+1,j+1) + b(i+1,j ) + b(i+1,j-1) +
b(i ,j+1) + b(i ,j ) + b(i ,j-1) +
! --- 42,50 ----
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
--- 91,97 ----
! a(i,j) = weight *
(b(i+1,j+1) + b(i+1,j ) + b(i+1,j-1) +
b(i ,j+1) + b(i ,j ) + b(i ,j-1) +
! --- 44,52 ----
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
***************
*** 102,115 ****
(b(i+1,j+1) + b(i+1,j ) + b(i+1,j-1) +
b(i ,j+1) + b(i ,j ) + b(i ,j-1) +
***************
! *** 51,56 ****
// Read from a. Write to b.
! for (int j = 1; j < n-1; j++)
! for (int i = 1; i < n-1; i++)
b(i,j) = weight *
(a(i+1,j+1) + a(i+1,j ) + a(i+1,j-1) +
! --- 52,57 ----
// Read from a. Write to b.
! for (int j = 1; j < n-1; j++)
--- 102,115 ----
(b(i+1,j+1) + b(i+1,j ) + b(i+1,j-1) +
b(i ,j+1) + b(i ,j ) + b(i ,j-1) +
***************
! *** 53,58 ****
// Read from a. Write to b.
! for (int j = 1; j < n-1; j++)
! for (int i = 1; i < n-1; i++)
b(i,j) = weight *
(a(i+1,j+1) + a(i+1,j ) + a(i+1,j-1) +
! --- 54,59 ----
// Read from a. Write to b.
! for (int j = 1; j < n-1; j++)
***************
*** 117,126 ****
b(i,j) = weight *
(a(i+1,j+1) + a(i+1,j ) + a(i+1,j-1) +
***************
! *** 60,70 ****
// Print out the final central value.
- ! Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
! // The arrays are automatically deallocated.
--- 117,125 ----
b(i,j) = weight *
(a(i+1,j+1) + a(i+1,j ) + a(i+1,j-1) +
***************
! *** 62,71 ****
// Print out the final central value.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
! // The arrays are automatically deallocated.
***************
*** 129,138 ****
Pooma::finalize();
return EXIT_SUCCESS;
}
! --- 61,72 ----
// Print out the final central value.
! ! Pooma::blockAndEvaluate(); // Ensure all computation has finished. <co id="tutorial-array_elementwise-doof2d-blockAndEvaluate"></co>
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
! // The arrays are automatically deallocated. <co id="tutorial-array_elementwise-doof2d-deallocation"></co>
--- 128,137 ----
Pooma::finalize();
return EXIT_SUCCESS;
}
! --- 63,74 ----
// Print out the final central value.
! ! Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
! // The arrays are automatically deallocated. <co id="tutorial-array_elementwise-doof2d-deallocation"></co>
Index: programs/Doof2d-Array-parallel-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d-Array-parallel-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 Doof2d-Array-parallel-annotated.patch
*** programs/Doof2d-Array-parallel-annotated.patch 2001/12/04 00:07:00 1.1
--- programs/Doof2d-Array-parallel-annotated.patch 2001/12/11 20:31:10
***************
*** 1,5 ****
! *** Doof2d-Array-parallel.cpp Tue Nov 27 13:00:09 2001
! --- Doof2d-Array-parallel-annotated.cpp Tue Nov 27 14:07:07 2001
***************
*** 1,4 ****
! #include <iostream> // has std::cout, ...
--- 1,5 ----
! *** Doof2d-Array-parallel.cpp Tue Dec 4 11:49:43 2001
! --- Doof2d-Array-parallel-annotated.cpp Tue Dec 4 12:24:36 2001
***************
*** 1,4 ****
! #include <iostream> // has std::cout, ...
***************
*** 28,34 ****
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
***************
! *** 19,38 ****
// the grid.
long n;
! std::cout << "Please enter the array size: ";
--- 28,34 ----
nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
***************
! *** 19,43 ****
// the grid.
long n;
! std::cout << "Please enter the array size: ";
***************
*** 49,55 ****
! Array<2, double, Brick> b(vertDomain);
// Set up the initial conditions.
! --- 20,39 ----
// the grid.
long n;
! std::cout << "Please enter the array size: ";
--- 49,60 ----
! Array<2, double, Brick> b(vertDomain);
// Set up the initial conditions.
! // All grid values should be zero except for the central value.
! a = b = 0.0;
! ! // Ensure all data-parallel computation finishes before accessing a value.
! Pooma::blockAndEvaluate();
! b(n/2,n/2) = 1000.0;
! --- 20,44 ----
// the grid.
long n;
! std::cout << "Please enter the array size: ";
***************
*** 70,84 ****
! Array<2, double, Brick> b(vertDomain);
// Set up the initial conditions.
***************
! *** 45,50 ****
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
! // Read from b. Write to a.
a(I,J) = weight *
(b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
! --- 46,51 ----
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
--- 75,94 ----
! Array<2, double, Brick> b(vertDomain);
// Set up the initial conditions.
+ // All grid values should be zero except for the central value.
+ a = b = 0.0;
+ ! // Ensure all data-parallel computation finishes before accessing a value. <co id="tutorial-array_parallel-doof2d-blockAndEvaluate"></co>
+ Pooma::blockAndEvaluate();
+ b(n/2,n/2) = 1000.0;
***************
! *** 47,52 ****
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
! // Read from b. Write to a.
a(I,J) = weight *
(b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
! --- 48,53 ----
// Perform the simulation.
! for (int k = 0; k < nuIterations; ++k) {
***************
*** 86,106 ****
a(I,J) = weight *
(b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
***************
! *** 61,65 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 62,66 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 69,70 ****
! --- 70,72 ----
return EXIT_SUCCESS;
}
+ </programlisting>
--- 96,116 ----
a(I,J) = weight *
(b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
***************
! *** 63,67 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 64,68 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 71,72 ****
! --- 72,74 ----
return EXIT_SUCCESS;
}
+ </programlisting>
Index: programs/Doof2d-Array-stencil-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d-Array-stencil-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 Doof2d-Array-stencil-annotated.patch
*** programs/Doof2d-Array-stencil-annotated.patch 2001/12/04 00:07:00 1.1
--- programs/Doof2d-Array-stencil-annotated.patch 2001/12/11 20:31:10
***************
*** 1,5 ****
! *** Doof2d-Array-stencil.cpp Tue Nov 27 17:23:41 2001
! --- Doof2d-Array-stencil-annotated.cpp Tue Nov 27 17:36:13 2001
***************
*** 1,9 ****
! #include <iostream> // has std::cout, ...
--- 1,5 ----
! *** Doof2d-Array-stencil.cpp Tue Dec 4 11:49:39 2001
! --- Doof2d-Array-stencil-annotated.cpp Tue Dec 4 12:26:46 2001
***************
*** 1,9 ****
! #include <iostream> // has std::cout, ...
***************
*** 109,115 ****
// Set up the initial conditions.
***************
! *** 71,80 ****
b(n/2,n/2) = 1000.0;
! // Create the stencil performing the computation.
--- 109,115 ----
// Set up the initial conditions.
***************
! *** 73,82 ****
b(n/2,n/2) = 1000.0;
! // Create the stencil performing the computation.
***************
*** 120,126 ****
! // Read from b. Write to a.
a(interiorDomain) = stencil(b, interiorDomain);
! --- 72,81 ----
b(n/2,n/2) = 1000.0;
! // Create the stencil performing the computation. <co id="tutorial-array_stencil-doof2d-stencil_creation"></co>
--- 120,126 ----
! // Read from b. Write to a.
a(interiorDomain) = stencil(b, interiorDomain);
! --- 74,83 ----
b(n/2,n/2) = 1000.0;
! // Create the stencil performing the computation. <co id="tutorial-array_stencil-doof2d-stencil_creation"></co>
***************
*** 132,152 ****
a(interiorDomain) = stencil(b, interiorDomain);
***************
! *** 85,89 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 86,90 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 93,94 ****
! --- 94,96 ----
return EXIT_SUCCESS;
}
+ </programlisting>
--- 132,152 ----
a(interiorDomain) = stencil(b, interiorDomain);
***************
! *** 87,91 ****
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
! --- 88,92 ----
// Print out the final central value.
Pooma::blockAndEvaluate(); // Ensure all computation has finished.
! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
// The arrays are automatically deallocated.
***************
! *** 95,96 ****
! --- 96,98 ----
return EXIT_SUCCESS;
}
+ </programlisting>
Index: programs/Doof2d-C-element-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d-C-element-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 Doof2d-C-element-annotated.patch
*** programs/Doof2d-C-element-annotated.patch 2001/12/04 00:07:00 1.1
--- programs/Doof2d-C-element-annotated.patch 2001/12/11 20:31:10
***************
*** 75,81 ****
a[i][j] = b[i][j] = 0.0;
b[n/2][n/2] = 1000.0;
! ! // In the average, weight element with this value.
const double weight = 1.0/9.0;
// Perform the simulation.
--- 75,81 ----
a[i][j] = b[i][j] = 0.0;
b[n/2][n/2] = 1000.0;
! ! // In the average, weight elements with this value.
const double weight = 1.0/9.0;
// Perform the simulation.
***************
*** 94,100 ****
a[i][j] = b[i][j] = 0.0;
b[n/2][n/2] = 1000.0;
! ! // In the average, weight element with this value. <co id="tutorial-hand_coded-doof2d-constants"></co>
const double weight = 1.0/9.0;
// Perform the simulation.
--- 94,100 ----
a[i][j] = b[i][j] = 0.0;
b[n/2][n/2] = 1000.0;
! ! // In the average, weight elements with this value. <co id="tutorial-hand_coded-doof2d-constants"></co>
const double weight = 1.0/9.0;
// Perform the simulation.
Index: programs/Doof2d-Field-distributed-annotated.patch
===================================================================
RCS file: Doof2d-Field-distributed-annotated.patch
diff -N Doof2d-Field-distributed-annotated.patch
*** /dev/null Fri Mar 23 21:37:44 2001
--- Doof2d-Field-distributed-annotated.patch Tue Dec 11 13:31:10 2001
***************
*** 0 ****
--- 1,176 ----
+ *** Doof2d-Field-distributed.cpp Wed Dec 5 14:05:10 2001
+ --- Doof2d-Field-distributed-annotated.cpp Wed Dec 5 14:41:24 2001
+ ***************
+ *** 1,3 ****
+ ! #include <stdlib.h> // has EXIT_SUCCESS
+ #include "Pooma/Fields.h" // has Pooma's Field
+
+ --- 1,4 ----
+ ! <programlisting id="tutorial-field_distributed-doof2d-program" linenumbering="numbered" format="linespecific">
+ ! #include <stdlib.h> // has EXIT_SUCCESS
+ #include "Pooma/Fields.h" // has Pooma's Field
+
+ ***************
+ *** 12,16 ****
+ // canot use standard input and output. Instead we use command-line
+ // arguments, which are replicated, for input, and we use an Inform
+ ! // stream for output.
+ Inform output;
+
+ --- 13,17 ----
+ // canot use standard input and output. Instead we use command-line
+ // arguments, which are replicated, for input, and we use an Inform
+ ! // stream for output. <co id="tutorial-field_distributed-doof2d-io"></co>
+ Inform output;
+
+ ***************
+ *** 18,22 ****
+ if (argc != 4) {
+ // Incorrect number of command-line arguments.
+ ! output << argv[0] << ": number-of-processors number-of-averagings number-of-values" << std::endl;
+ return EXIT_FAILURE;
+ }
+ --- 19,23 ----
+ if (argc != 4) {
+ // Incorrect number of command-line arguments.
+ ! output << argv[0] << ": number-of-processors number-of-averagings number-of-values" << std::endl;
+ return EXIT_FAILURE;
+ }
+ ***************
+ *** 25,33 ****
+ // Determine the number of processors.
+ long nuProcessors;
+ ! nuProcessors = strtol(argv[1], &tail, 0);
+
+ // Determine the number of averagings.
+ long nuAveragings, nuIterations;
+ ! nuAveragings = strtol(argv[2], &tail, 0);
+ nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
+
+ --- 26,34 ----
+ // Determine the number of processors.
+ long nuProcessors;
+ ! nuProcessors = strtol(argv[1], &tail, 0);
+
+ // Determine the number of averagings.
+ long nuAveragings, nuIterations;
+ ! nuAveragings = strtol(argv[2], &tail, 0);
+ nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
+
+ ***************
+ *** 35,39 ****
+ // the grid.
+ long n;
+ ! n = strtol(argv[3], &tail, 0);
+ // The dimension must be a multiple of the number of processors
+ // since we are using a UniformGridLayout.
+ --- 36,40 ----
+ // the grid.
+ long n;
+ ! n = strtol(argv[3], &tail, 0);
+ // The dimension must be a multiple of the number of processors
+ // since we are using a UniformGridLayout.
+ ***************
+ *** 41,50 ****
+
+ // Specify the fields' domains [0,n) x [0,n).
+ ! Interval<1> N(0, n-1);
+ ! Interval<2> vertDomain(N, N);
+
+ // Set up interior domains [1,n-1) x [1,n-1) for computation.
+ ! Interval<1> I(1,n-2);
+ ! Interval<1> J(1,n-2);
+
+ // Partition the fields' domains uniformly, i.e., each patch has the
+ --- 42,51 ----
+
+ // Specify the fields' domains [0,n) x [0,n).
+ ! Interval<1> N(0, n-1);
+ ! Interval<2> vertDomain(N, N);
+
+ // Set up interior domains [1,n-1) x [1,n-1) for computation.
+ ! Interval<1> I(1,n-2);
+ ! Interval<1> J(1,n-2);
+
+ // Partition the fields' domains uniformly, i.e., each patch has the
+ ***************
+ *** 52,74 ****
+ // dimension. Guard layers optimize communication between patches.
+ // Internal guards surround each patch. External guards surround
+ ! // the entire field domain.
+ ! UniformGridPartition<2> partition(Loc<2>(nuProcessors, nuProcessors),
+ ! GuardLayers<2>(1), // internal
+ ! GuardLayers<2>(0)); // external
+ ! UniformGridLayout<2> layout(vertDomain, partition, DistributedTag());
+
+ // Specify the fields' mesh, i.e., its spatial extent, and its
+ ! // centering type.
+ ! UniformRectilinearMesh<2> mesh(layout, Vector<2>(0.0), Vector<2>(1.0, 1.0));
+ ! Centering<2> cell = canonicalCentering<2>(CellType, Continuous, AllDim);
+
+ // The template parameters indicate a mesh and a 'double'
+ // element type. MultiPatch indicates multiple computation patches,
+ // i.e., distributed computation. The UniformTag indicates the
+ ! // patches should have the same size. Each patch has Brick type.
+ ! Field<UniformRectilinearMesh<2>, double, MultiPatch<UniformTag,
+ ! Remote<Brick> > > a(cell, layout, mesh);
+ ! Field<UniformRectilinearMesh<2>, double, MultiPatch<UniformTag,
+ ! Remote<Brick> > > b(cell, layout, mesh);
+
+ // Set up the initial conditions.
+ --- 53,75 ----
+ // dimension. Guard layers optimize communication between patches.
+ // Internal guards surround each patch. External guards surround
+ ! // the entire field domain. <co id="tutorial-field_distributed-doof2d-layout"></co>
+ ! UniformGridPartition<2> partition(Loc<2>(nuProcessors, nuProcessors),
+ ! GuardLayers<2>(1), // internal
+ ! GuardLayers<2>(0)); // external
+ ! UniformGridLayout<2> layout(vertDomain, partition, DistributedTag());
+
+ // Specify the fields' mesh, i.e., its spatial extent, and its
+ ! // centering type. <co id="tutorial-field_distributed-doof2d-mesh"></co>
+ ! UniformRectilinearMesh<2> mesh(layout, Vector<2>(0.0), Vector<2>(1.0, 1.0));
+ ! Centering<2> cell = canonicalCentering<2>(CellType, Continuous, AllDim);
+
+ // The template parameters indicate a mesh and a 'double'
+ // element type. MultiPatch indicates multiple computation patches,
+ // i.e., distributed computation. The UniformTag indicates the
+ ! // patches should have the same size. Each patch has Brick type. <co id="tutorial-field_distributed-doof2d-remote"></co>
+ ! Field<UniformRectilinearMesh<2>, double, MultiPatch<UniformTag,
+ ! Remote<Brick> > > a(cell, layout, mesh);
+ ! Field<UniformRectilinearMesh<2>, double, MultiPatch<UniformTag,
+ ! Remote<Brick> > > b(cell, layout, mesh);
+
+ // Set up the initial conditions.
+ ***************
+ *** 83,87 ****
+
+ // Perform the simulation.
+ ! for (int k = 0; k < nuIterations; ++k) {
+ // Read from b. Write to a.
+ a(I,J) = weight *
+ --- 84,88 ----
+
+ // Perform the simulation.
+ ! for (int k = 0; k < nuIterations; ++k) {
+ // Read from b. Write to a.
+ a(I,J) = weight *
+ ***************
+ *** 99,103 ****
+ // Print out the final central value.
+ Pooma::blockAndEvaluate(); // Ensure all computation has finished.
+ ! output << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
+
+ // The fields are automatically deallocated.
+ --- 100,104 ----
+ // Print out the final central value.
+ Pooma::blockAndEvaluate(); // Ensure all computation has finished.
+ ! output << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
+
+ // The fields are automatically deallocated.
+ ***************
+ *** 107,108 ****
+ --- 108,110 ----
+ return EXIT_SUCCESS;
+ }
+ + </programlisting>
Index: programs/Doof2d-Field-parallel-annotated.patch
===================================================================
RCS file: Doof2d-Field-parallel-annotated.patch
diff -N Doof2d-Field-parallel-annotated.patch
*** /dev/null Fri Mar 23 21:37:44 2001
--- Doof2d-Field-parallel-annotated.patch Tue Dec 11 13:31:10 2001
***************
*** 0 ****
--- 1,120 ----
+ *** Doof2d-Field-parallel.cpp Tue Dec 4 10:01:28 2001
+ --- Doof2d-Field-parallel-annotated.cpp Tue Dec 4 11:04:26 2001
+ ***************
+ *** 1,5 ****
+ ! #include <iostream> // has std::cout, ...
+ ! #include <stdlib.h> // has EXIT_SUCCESS
+ ! #include "Pooma/Fields.h" // has Pooma's Field
+
+ // Doof2d: Pooma Fields, data-parallel implementation
+ --- 1,6 ----
+ ! <programlisting id="tutorial-field_parallel-doof2d-program" linenumbering="numbered" format="linespecific">
+ ! #include <iostream> // has std::cout, ...
+ ! #include <stdlib.h> // has EXIT_SUCCESS
+ ! #include "Pooma/Fields.h" // has Pooma's Field <co id="tutorial-field_parallel-doof2d-header"></co>
+
+ // Doof2d: Pooma Fields, data-parallel implementation
+ ***************
+ *** 12,17 ****
+ // Ask the user for the number of averagings.
+ long nuAveragings, nuIterations;
+ ! std::cout << "Please enter the number of averagings: ";
+ ! std::cin >> nuAveragings;
+ nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
+
+ --- 13,18 ----
+ // Ask the user for the number of averagings.
+ long nuAveragings, nuIterations;
+ ! std::cout << "Please enter the number of averagings: ";
+ ! std::cin >> nuAveragings;
+ nuIterations = (nuAveragings+1)/2; // Each iteration performs two averagings.
+
+ ***************
+ *** 19,44 ****
+ // the grid.
+ long n;
+ ! std::cout << "Please enter the field size: ";
+ ! std::cin >> n;
+
+ // Specify the fields' domains [0,n) x [0,n).
+ ! Interval<1> N(0, n-1);
+ ! Interval<2> vertDomain(N, N);
+
+ // Set up interior domains [1,n-1) x [1,n-1) for computation.
+ ! Interval<1> I(1,n-2);
+ ! Interval<1> J(1,n-2);
+
+ // Specify the fields' mesh, i.e., its spatial extent, and its
+ ! // centering type.
+ ! DomainLayout<2> layout(vertDomain);
+ ! UniformRectilinearMesh<2> mesh(layout, Vector<2>(0.0), Vector<2>(1.0, 1.0));
+ ! Centering<2> cell = canonicalCentering<2>(CellType, Continuous, AllDim);
+
+ // Create the fields.
+ // The template parameters indicate a mesh, a 'double' element
+ ! // type, and ordinary 'Brick' storage.
+ ! Field<UniformRectilinearMesh<2>, double, Brick> a(cell, layout, mesh);
+ ! Field<UniformRectilinearMesh<2>, double, Brick> b(cell, layout, mesh);
+
+ // Set up the initial conditions.
+ --- 20,45 ----
+ // the grid.
+ long n;
+ ! std::cout << "Please enter the field size: ";
+ ! std::cin >> n;
+
+ // Specify the fields' domains [0,n) x [0,n).
+ ! Interval<1> N(0, n-1);
+ ! Interval<2> vertDomain(N, N);
+
+ // Set up interior domains [1,n-1) x [1,n-1) for computation.
+ ! Interval<1> I(1,n-2);
+ ! Interval<1> J(1,n-2);
+
+ // Specify the fields' mesh, i.e., its spatial extent, and its
+ ! // centering type. <co id="tutorial-field_parallel-doof2d-mesh"></co>
+ ! DomainLayout<2> layout(vertDomain);
+ ! UniformRectilinearMesh<2> mesh(layout, Vector<2>(0.0), Vector<2>(1.0, 1.0));
+ ! Centering<2> cell = canonicalCentering<2>(CellType, Continuous, AllDim);
+
+ // Create the fields.
+ // The template parameters indicate a mesh, a 'double' element
+ ! // type, and ordinary 'Brick' storage. <co id="tutorial-field_parallel-doof2d-field_creation"></co>
+ ! Field<UniformRectilinearMesh<2>, double, Brick> a(cell, layout, mesh);
+ ! Field<UniformRectilinearMesh<2>, double, Brick> b(cell, layout, mesh);
+
+ // Set up the initial conditions.
+ ***************
+ *** 51,56 ****
+
+ // Perform the simulation.
+ ! for (int k = 0; k < nuIterations; ++k) {
+ ! // Read from b. Write to a.
+ a(I,J) = weight *
+ (b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
+ --- 52,57 ----
+
+ // Perform the simulation.
+ ! for (int k = 0; k < nuIterations; ++k) {
+ ! // Read from b. Write to a. <co id="tutorial-field_parallel-doof2d-first_write"></co>
+ a(I,J) = weight *
+ (b(I+1,J+1) + b(I+1,J ) + b(I+1,J-1) +
+ ***************
+ *** 67,71 ****
+ // Print out the final central value.
+ Pooma::blockAndEvaluate(); // Ensure all computation has finished.
+ ! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
+
+ // The fields are automatically deallocated.
+ --- 68,72 ----
+ // Print out the final central value.
+ Pooma::blockAndEvaluate(); // Ensure all computation has finished.
+ ! std::cout << (nuAveragings % 2 ? a(n/2,n/2) : b(n/2,n/2)) << std::endl;
+
+ // The fields are automatically deallocated.
+ ***************
+ *** 75,76 ****
+ --- 76,78 ----
+ return EXIT_SUCCESS;
+ }
+ + </programlisting>
More information about the pooma-dev
mailing list