Manual Patch: Formatting Changes
Jeffrey D . Oldham
oldham at codesourcery.com
Thu Jan 31 21:23:24 UTC 2002
2002-Jan-31 Jeffrey D. Oldham <oldham at codesourcery.com>
This patch continues the formatting to prepare the manual for delivery.
No substantive semantic changes were made.
* Makefile: Generalize to support any top-level name. Fix
mistakes in PostScript and PDF rules.
* arrays.xml: Reformat and reword to avoid bad line breaks and
incursions into the right margin.
* data-parallel.xml: Reformat to avoid bad line breaks and
incursions into the right margin.
* html.dsl: New file controlling conversion of DocBook into HTML.
* jadetex.cfg: New file controlling jadetex, which converts TeX to
PostScript and PDF. The changes support better line breaking for
URLs and pathnames.
* manual.xml: Renamed pooma.xml.
* pooma.xml: New file moved from manual.xml.
* print.dsl: New file controlling conversion of DocBook into
PostScript and PDF.
* template.xml: Fix parameter type.
* tutorial.xml: Reformat and reword to avoid bad line breaks and
incursions into the right margin.
Applied to mainline.
Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/Makefile,v
retrieving revision 1.3
diff -c -p -r1.3 Makefile
*** Makefile 2002/01/30 23:09:06 1.3
--- Makefile 2002/01/31 21:10:37
*************** HTMLDOCBOOKDSL= html.dsl # html/docbook
*** 13,27 ****
XML= dtds/decls/xml.dcl
INDEXOPTIONS= -t 'Index' -i 'index' -g -p
! XMLSOURCES= manual.xml introduction.xml template.xml tutorial.xml \
concepts.xml arrays.xml data-parallel.xml glossary.xml \
bibliography.xml
## HERE How do I include dependences on programs?
! all: manual.ps manual.pdf manual.html
! manual.dvi manual.pdf manual.html: $(XMLSOURCES) figures
figures:
$(MAKE) -C figures
--- 13,28 ----
XML= dtds/decls/xml.dcl
INDEXOPTIONS= -t 'Index' -i 'index' -g -p
! MANUALNAME= pooma
! XMLSOURCES= $(MANUALNAME).xml introduction.xml template.xml tutorial.xml \
concepts.xml arrays.xml data-parallel.xml glossary.xml \
bibliography.xml
## HERE How do I include dependences on programs?
! all: $(MANUALNAME).ps $(MANUALNAME).pdf $(MANUALNAME).html
! $(MANUALNAME).dvi $(MANUALNAME).pdf $(MANUALNAME).html: $(XMLSOURCES) figures
figures:
$(MAKE) -C figures
*************** genindex.sgm:
*** 33,54 ****
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) $(XML) $<
# This rule assumes index creation.
! %.dvi: %.xml genindex.sgm print.dsl
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) -V html-index $(XML) $<
perl collateindex.pl $(INDEXOPTIONS) -o genindex.sgm HTML.index
jade -D$(JADEDIR) -t tex -d $(PRINTDOCBOOKDSL) -V tex-backend -V use-eps $(XML) $<
! jadetex $*.tex
! jadetex $*.tex
! jadetex $*.tex
# This rule assumes index creation.
! %.pdf: %.xml genindex.sgm print.dsl
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) -V html-index $(XML) $<
perl collateindex.pl $(INDEXOPTIONS) -o genindex.sgm HTML.index
jade -D$(JADEDIR) -t tex -d $(PRINTDOCBOOKDSL) $(XML) $<
! pdfjadetex $*.tex
! pdfjadetex $*.tex
! pdfjadetex $*.tex
clean:
! rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.html *.mpx mpxerr.tex HTML.index manual.tex genindex.sgm pooma-html.manifest
--- 34,58 ----
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) $(XML) $<
# This rule assumes index creation.
! $(MANUALNAME).dvi: $(XMLSOURCES) genindex.sgm print.dsl
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) -V html-index $(XML) $<
perl collateindex.pl $(INDEXOPTIONS) -o genindex.sgm HTML.index
jade -D$(JADEDIR) -t tex -d $(PRINTDOCBOOKDSL) -V tex-backend -V use-eps $(XML) $<
! jadetex $(MANUALNAME).tex
! jadetex $(MANUALNAME).tex
! jadetex $(MANUALNAME).tex
+ %.ps: %.dvi
+ dvips -t letter $< -o
+
# This rule assumes index creation.
! $(MANUALNAME).pdf: $(XMLSOURCES) genindex.sgm print.dsl
jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) -V html-index $(XML) $<
perl collateindex.pl $(INDEXOPTIONS) -o genindex.sgm HTML.index
jade -D$(JADEDIR) -t tex -d $(PRINTDOCBOOKDSL) $(XML) $<
! pdfjadetex $(MANUALNAME).tex
! pdfjadetex $(MANUALNAME).tex
! pdfjadetex $(MANUALNAME).tex
clean:
! rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.html *.mpx mpxerr.tex HTML.index $(MANUALNAME).tex genindex.sgm pooma-html.manifest
Index: arrays.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/arrays.xml,v
retrieving revision 1.7
diff -c -p -r1.7 arrays.xml
*** arrays.xml 2002/01/30 23:51:45 1.7
--- arrays.xml 2002/01/31 21:10:38
***************
*** 156,162 ****
interval [2,9]. Its indices are ordered pairs such as (0,2),
(0,3), (1,2), (1,9), and (3,7).</para>
! <para>Many domains can be represented using domain triplets. A
<glossterm linkend="glossary-domain_triplet"><firstterm>domain
triplet</firstterm></glossterm>
[<varname>begin</varname>:<varname>end</varname>:<varname>stride</varname>]
--- 156,163 ----
interval [2,9]. Its indices are ordered pairs such as (0,2),
(0,3), (1,2), (1,9), and (3,7).</para>
! <para>Many domains can be represented using domain triplets. That
! is, a
<glossterm linkend="glossary-domain_triplet"><firstterm>domain
triplet</firstterm></glossterm>
[<varname>begin</varname>:<varname>end</varname>:<varname>stride</varname>]
*************** Array<1,double,CompressibleBrick>
*** 1420,1431 ****
domains:
<programlisting>
// Create an Array and its domain.
! Array<2,float,Brick> a(Interval<1>(2,7), Interval<1>(-2,4));
// Create an Array without a domain and then specify
// its domain.
! Array<2,float,Brick> b();
! b.initialize(Interval<1>(2,7), Interval<1>(-2,4));.
</programlisting> Invoking <literal>initialize</literal> on an
&array; with an existing domain yields unspecified behavior. All
&array; values may be lost and memory may be leaked.</para>
--- 1421,1433 ----
domains:
<programlisting>
// Create an Array and its domain.
! Array<2,float,Brick> a(Interval<1>(2,7),
! Interval<1>(-2,4));
// Create an Array without a domain and then specify
// its domain.
! Array<2,float,Brick> b();
! b.initialize(Interval<1>(2,7), Interval<1>(-2,4));.
</programlisting> Invoking <literal>initialize</literal> on an
&array; with an existing domain yields unspecified behavior. All
&array; values may be lost and memory may be leaked.</para>
*************** object or integer.</entry>
*** 1570,1576 ****
following code prints the initial value at index (2,-2) and
increments its value, printing the new value:
<programlisting>
! Array<2,int,Brick> a(Interval<1>(0,3), Interval<1>(-2,4),
ModelElement<int>(4));
std::cout &openopen; a(2,-2) &openopen; std::endl;
++a(2,-2);
--- 1572,1579 ----
following code prints the initial value at index (2,-2) and
increments its value, printing the new value:
<programlisting>
! Array<2,int,Brick> a(Interval<1>(0,3),
! Interval<1>(-2,4),
ModelElement<int>(4));
std::cout &openopen; a(2,-2) &openopen; std::endl;
++a(2,-2);
Index: data-parallel.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/data-parallel.xml,v
retrieving revision 1.6
diff -c -p -r1.6 data-parallel.xml
*** data-parallel.xml 2002/01/30 23:51:45 1.6
--- data-parallel.xml 2002/01/31 21:10:40
*************** Expression<UnaryNode<OpMinus,Ar&cl
*** 977,985 ****
</programlisting> The binary nodes continue the construction process yielding a
parse tree object for the entire right-hand side and having type
<programlisting>
! Expression<BinaryNode<OpAdd,
! UnaryNode<OpMinus, Ar>,
! BinaryNode<OpMultiply<Scalar<int>,Ar&closecloseclose;
</programlisting> Evaluating the left-hand side yields an object
representing <varname>A</varname>.</para>
--- 977,986 ----
</programlisting> The binary nodes continue the construction process yielding a
parse tree object for the entire right-hand side and having type
<programlisting>
! Expression<
! BinaryNode<OpAdd,
! UnaryNode<OpMinus, Ar>,
! BinaryNode<OpMultiply<Scalar<int>,Ar&closecloseclose;
</programlisting> Evaluating the left-hand side yields an object
representing <varname>A</varname>.</para>
*************** forEach(const Expression& e, const L
*** 1218,1224 ****
nodes, it combines the results using the <type>CombineTag</type>
operator <varname>c</varname>. It inlines into a call to
<programlisting>
! ForEach<Expression, LeafTag, CombineTag>::apply(e, f, c).
</programlisting> The <function>apply</function> function continues
the traversal through the tree. For our example,
<type>LeafTag</type> equals <type>EvalLeaf<1></type>, and
--- 1219,1225 ----
nodes, it combines the results using the <type>CombineTag</type>
operator <varname>c</varname>. It inlines into a call to
<programlisting>
! ForEach<Expression, LeafTag, CombineTag>::apply(e, f, c)
</programlisting> The <function>apply</function> function continues
the traversal through the tree. For our example,
<type>LeafTag</type> equals <type>EvalLeaf<1></type>, and
*************** ForEach<Expression, LeafTag, CombineT
*** 1236,1246 ****
template<class Op, class A, class FTag, class CTag>
struct ForEach<UnaryNode<Op, A>, FTag, CTag>
{
! typedef typename ForEach<A, FTag, CTag>::Type_t TypeA_t;
! typedef typename Combine1<TypeA_t, Op, CTag>::Type_t Type_t;
inline static
! Type_t apply(const UnaryNode<Op, A> &expr, const FTag &f,
! const CTag &c)
{
return Combine1<TypeA_t, Op, CTag>::
combine(ForEach<A, FTag, CTag>::
--- 1237,1248 ----
template<class Op, class A, class FTag, class CTag>
struct ForEach<UnaryNode<Op, A>, FTag, CTag>
{
! typedef typename ForEach<A,FTag,CTag>::Type_t TypeA_t;
! typedef typename
! Combine1<TypeA_t,Op,CTag>::Type_t Type_t;
inline static
! Type_t apply(const UnaryNode<Op,A>&expr,const FTag&f,
! const CTag& c)
{
return Combine1<TypeA_t, Op, CTag>::
combine(ForEach<A, FTag, CTag>::
*************** struct ForEach<UnaryNode<Op, A>
*** 1264,1272 ****
template<class Expr, class FTag, class CTag>
struct ForEach
{
! typedef typename LeafFunctor<Expr, FTag>::Type_t Type_t;
inline static
! Type_t apply(const Expr &expr, const FTag &f, const CTag &)
{
return LeafFunctor<Expr, FTag>::apply(expr, f);
}
--- 1266,1275 ----
template<class Expr, class FTag, class CTag>
struct ForEach
{
! typedef typename
! LeafFunctor<Expr, FTag>::Type_t Type_t;
inline static
! Type_t apply(const Expr&expr,const FTag&f,const CTag&)
{
return LeafFunctor<Expr, FTag>::apply(expr, f);
}
*************** struct ForEach
*** 1286,1292 ****
<programlisting>
int end = A.domain[0].first() + A.domain[0].length();
for (int i = A.domain[0].first(); i < end; ++i)
! A.engine(i) += -A.engine.read(i) + 2 * B.engine.read(i);
</programlisting> The loop iterates through <varname>A</varname>'s
domain, using &array;'s engines to obtain values and assigning
values. Notice there is no use of the run-time parse tree so the
--- 1289,1295 ----
<programlisting>
int end = A.domain[0].first() + A.domain[0].length();
for (int i = A.domain[0].first(); i < end; ++i)
! A.engine(i) += -A.engine.read(i)+2*B.engine.read(i);
</programlisting> The loop iterates through <varname>A</varname>'s
domain, using &array;'s engines to obtain values and assigning
values. Notice there is no use of the run-time parse tree so the
Index: html.dsl
===================================================================
RCS file: html.dsl
diff -N html.dsl
*** /dev/null Fri Mar 23 21:37:44 2001
--- html.dsl Thu Jan 31 14:10:40 2002
***************
*** 0 ****
--- 1,82 ----
+ <!-- DSSSL style sheet for generating HTML from DocBook documents. -->
+
+ <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+ <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
+ ]>
+
+ <!-- This DSSSL stylesheet formats the POOMA manual, written in
+ DocBook, as converted to HTML.
+
+ Jeffrey D. Oldham
+ 2002 January 29 -->
+
+ <style-sheet>
+ <style-specification use="docbook">
+ <style-specification-body>
+
+ ;; $Id: plain.dsl,v 1.2 2000/09/28 12:50:20 ndw Exp $
+ ;;
+ ;; This file is part of the Modular DocBook Stylesheet distribution.
+ ;; See ../README or http://www.berkshire.net/~norm/dsssl/
+ ;;
+ ;; Example of a customization layer on top of the modular docbook style
+ ;; sheet. Definitions inserted in this file take precedence over
+ ;; definitions in the 'use'd stylesheet(s).
+
+ ;; Use the extension .html for output files.
+ (define %html-ext% ".html")
+
+ ;; The main file is named index.
+ (define %root-filename% "pooma")
+
+ ;; Number chapters and sections.
+ (define %chapter-autolabel% #t)
+ (define %section-autolabel% #t)
+
+ ;; Don't place the first section of each chapter in the same chunk as
+ ;; the chapter head.
+ (define (chunk-skip-first-element-list) (list))
+
+ ;; Write a manifest of created files to pooma-html.manifest.
+ (define html-manifest #t)
+ (define html-manifest-filename "pooma-html.manifest")
+
+ ;; Use element ids to generate chunk filenames
+ (define %use-id-as-filename% #t)
+
+ ;; Support block elements inside para.
+ (define %fix-para-wrappers% #t)
+
+ ;; Avoid a hack to force 'correct' vertical spacing.
+ (define %spacing-para% #f)
+
+ ;; Prevent verbatim text from being displayed at a different size.
+ (define %verbatim-size-factor% 1.1)
+
+ ;; Change the default presentation for various tags.
+ ; Use mono-space font for computer items.
+ (element command ($mono-seq$))
+ (element envar ($mono-seq$))
+ (element errorname ($mono-seq$))
+ (element errortype ($mono-seq$))
+ (element keywordname ($mono-seq$)) ; new tag aded by Oldham
+ (element methodname ($mono-seq$)) ; new tag aded by Oldham
+ (element operator ($mono-seq$)) ; new tag aded by Oldham
+ (element statement ($mono-seq$)) ; new tag aded by Oldham
+ (element symbol ($mono-seq$))
+ (element token ($mono-seq$))
+ (element type ($mono-seq$))
+
+ ; Center figures.
+ (element mediaobject
+ (make element gi: "DIV"
+ attributes: (list (list "CLASS" (gi)) (list "ALIGN" "center"))
+ (make element gi: "P"
+ ($mediaobject$))))
+
+ </style-specification-body>
+ </style-specification>
+
+ <external-specification id="docbook" document="docbook.dsl">
+
+ </style-sheet>
Index: jadetex.cfg
===================================================================
RCS file: jadetex.cfg
diff -N jadetex.cfg
*** /dev/null Fri Mar 23 21:37:44 2001
--- jadetex.cfg Thu Jan 31 14:10:41 2002
***************
*** 0 ****
--- 1,6 ----
+ %% Support better hyphenation for URLs and paths.
+ %% Idea taken from http://cyberelk.net/tim/docbook/selfdocbook/jadetex.cfg.htm
+ \usepackage{url}
+ \tolerance=2000
+ \hypersetup{colorlinks=false}
+ \hyphenation{block-And-Eval-u-ate}
Index: manual.xml
===================================================================
RCS file: manual.xml
diff -N manual.xml
*** /tmp/cvsWATf4H Thu Jan 31 14:10:46 2002
--- /dev/null Fri Mar 23 21:37:44 2001
***************
*** 1,4220 ****
- <?xml version="1.0"?>
- <!-- FIXME: Index this file. -->
-
- <!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. -->
-
- <!-- Conditional Inclusion Entity Declarations -->
- <!ENTITY % unfinished "IGNORE">
- <!-- Unfinished sections should not be included in published versions. -->
- <!ENTITY % temporary "INCLUDE">
- <!-- Temporary sections to be included in published versions until the final version is written. -->
-
- <!-- 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 bookcap "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 closeclose ">⪆>" >
- <!-- Produce a notation for ">>", which frequently occurs with templates. Without this, TeX produces a shift symbol. -->
- <!ENTITY closecloseclose ">⪆>⪆>" >
- <!-- Produce a notation for ">>>", which infrequently occurs with templates. Without this, TeX produces a shift symbol. -->
- <!ENTITY dashdash "-⪆-" >
- <!-- Produce a notation for a double dash. Without this, TeX produces an en-hyphen. -->
- <!ENTITY dim "D">
- <!-- the number of dimensions of an array, domain, etc. -->
- <!ENTITY doof2d "<command>Doof2d</command>" >
- <!-- Produce a notation for the Doof2d program. -->
- <!ENTITY fortran "<application class='software'>Fortran</application>">
- <!-- Produce a notation for the Fortran programming language. -->
- <!ENTITY gap " ">
- <!-- Produce a small gap so TeX will not combine the two characters. -->
- <!-- FIXME: Choose something that will work for TeX and also in HTML. -->
- <!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 openopen "<⪆<" >
- <!-- Produce a notation for "<<", which frequently occurs with output. Without this, TeX produces a shift symbol. -->
- <!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 framework. -->
- <!ENTITY pooma "<application class='software'>POOMA</application>">
- <!-- Produce a notation for Pooma software. -->
- <!ENTITY poomatoolkit "<application class='software'>POOMA &toolkitcap;</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. -->
- <!ENTITY toolkit "toolkit">
- <!-- Produce a notation for the name of the Pooma software. -->
- <!ENTITY toolkitcap "Toolkit">
- <!-- Produce a capitalized version of &toolkit;. -->
-
- <!-- Type Entity Declarations -->
-
- <!ENTITY array "<type>Array</type>">
- <!-- The "Array" type. -->
- <!ENTITY benchmark "<type>Benchmark</type>">
- <!-- The "Benchmark" type. -->
- <!ENTITY bool "<type>bool</type>">
- <!-- The C++ boolean type. -->
- <!ENTITY brick "<type>Brick</type>">
- <!-- The "Brick" engine type. -->
- <!ENTITY char "<type>char</type>">
- <!-- The C char type. -->
- <!ENTITY complex "<type>complex</type>">
- <!-- The C++ "complex" 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 domaintemplate "DT">
- <!-- A domain template parameter. -->
- <!ENTITY double "<type>double</type>">
- <!-- The C "double" type. -->
- <!ENTITY dynamic "<type>Dynamic</type>">
- <!-- The "Dynamic" Engine type. -->
- <!ENTITY dynamicarray "<type>DynamicArray</type>">
- <!-- The "DynamicArray" type. -->
- <!ENTITY engine "<type>Engine</type>">
- <!-- The "Engine" type. -->
- <!ENTITY false "<literal>false</literal>">
- <!-- The false Boolean value. -->
- <!-- Modify its tag to the appropriate one. -->
- <!ENTITY field "<type>Field</type>">
- <!-- The "Field" type. -->
- <!ENTITY float "<type>float</type>">
- <!-- The C "float" type. -->
- <!ENTITY grid "<type>Grid</type>">
- <!-- The "Grid" domain type. -->
- <!ENTITY gridone "<type>Grid<1></type>">
- <!-- The "Grid<1>" one-dimensional domain type. -->
- <!ENTITY indirectionlist "<type>IndirectionList</type>">
- <!-- The "IndirectionList" (domain-helper) type. -->
- <!ENTITY indirectionlistint "<type>IndirectionList<int></type>">
- <!-- The "IndirectionList<int>" (domain-helper) type. -->
- <!ENTITY inform "<type>Inform</type>">
- <!-- The "Inform" output type. -->
- <!ENTITY int "<type>int</type>">
- <!-- The C "int" type. -->
- <!ENTITY interval "<type>Interval</type>">
- <!-- The "Interval" type. -->
- <!ENTITY intervalone "<type>Interval<1></type>">
- <!-- The "Interval<1>" one-dimensional domain type. -->
- <!ENTITY layout "<type>Layout</type>">
- <!-- The "Layout" type without template parameters. -->
- <!ENTITY leaffunctor "<type>LeafFunctor</type>">
- <!-- The "LeafFunctor" type. -->
- <!ENTITY loc "<type>Loc</type>">
- <!-- The "Loc" domain type. -->
- <!ENTITY locone "<type>Loc<1></type>">
- <!-- The "Loc<1>" one-dimensional domain type. -->
- <!ENTITY matrix "<type>TinyMatrix</type>">
- <!-- The Pooma matrix type. -->
- <!ENTITY multipatch "<type>MultiPatch</type>">
- <!-- The "MultiPatch" engine without template parameters. -->
- <!ENTITY options "<type>Options</type>">
- <!-- The &pooma; options type. -->
- <!ENTITY range "<type>Range</type>">
- <!-- The "Range" domain type. -->
- <!ENTITY rangeone "<type>Range<1></type>">
- <!-- The "Range<1>" one-dimensional domain type. -->
- <!ENTITY remote "<type>Remote</type>">
- <!-- The "Remote" engine type. -->
- <!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 true "<literal>true</literal>">
- <!-- The true Boolean value. -->
- <!-- Modify its tag to the appropriate one. -->
- <!ENTITY vector "<type>Vector</type>">
- <!-- The "Vector" type. -->
-
- <!-- Mathematical Entity Declarations -->
-
- <!ENTITY container "C">
- <!-- an abbreviation for a canonical container -->
- <!ENTITY containerdomain "D">
- <!-- an abbreviation for a canonical container domain -->
- <!ENTITY n "n">
- <!-- the size of one dimension of an array -->
- <!ENTITY space "ℜ<superscript>d</superscript>">
- <!-- a notation for multidimensional space -->
-
- <!-- System and Operating System Entity Declarations -->
- <!ENTITY gcc "<application>g++</application>">
- <!-- 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.codesourcery.com/pooma/pooma/">http://www.codesourcery.com/pooma/pooma/</ulink>'>
- <!-- The canonical Pooma home page. -->
- <!-- UPDATE this filename. -->
- <!ENTITY poomasource "pooma-2.3.0">
- <!-- The Pooma source code directory. -->
- <!-- UPDATE this filename. -->
- <!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. -->
- <!ENTITY naive "naïve">
- <!-- The word "na\"{\i}ve." -->
- <!ENTITY naivecap "Naïve">
- <!-- The word "Na\"{\i}ve," i.e., the capitalized &naive;. -->
- <!-- The Pooma source code directory. -->
- <!-- spelling: dependence, not dependency -->
- <!-- spelling: element-wise, not elementwise -->
- <!-- phrase: function object, not functor -->
- <!-- spelling: interprocessor, not inter-processor -->
- <!-- spelling: multidimensional, not multi-dimensional -->
- <!-- spelling: multiprocessor, not multi-processor -->
- <!-- spelling: nonzero, not non-zero -->
- <!-- formatting: for sets, no spaces between brackets and entries but spaced between entries -->
-
- <!-- External Chapters -->
- <!ENTITY arrays-chapter SYSTEM "arrays.xml">
- <!-- Pooma Arrays chapter -->
- <!ENTITY bibliography-chapter SYSTEM "bibliography.xml">
- <!-- bibliography -->
- <!ENTITY concepts-chapter SYSTEM "concepts.xml">
- <!-- Pooma concepts chapter -->
- <!ENTITY data-parallel-chapter SYSTEM "data-parallel.xml">
- <!-- data-parallel expressions chapter -->
- <!ENTITY glossary-chapter SYSTEM "glossary.xml">
- <!-- glossary -->
- <!ENTITY introductory-chapter SYSTEM "introduction.xml">
- <!-- Doof2d introductory chapter -->
- <!ENTITY template-chapter SYSTEM "template.xml">
- <!-- Doof2d template programming chapter -->
- <!ENTITY tutorial-chapter SYSTEM "tutorial.xml">
- <!-- Doof2d tutorial programs chapter -->
-
- <!-- External File Entities -->
- <!-- Doof2d Programs -->
- <!ENTITY doof2d-c-element SYSTEM "./programs/examples/Doof2d/Doof2d-C-element-annotated.cpp">
- <!-- hand-coded Doof2d implementation -->
- <!ENTITY doof2d-array-element SYSTEM "./programs/examples/Doof2d/Doof2d-Array-element-annotated.cpp">
- <!-- Array element-wise Doof2d implementation -->
- <!ENTITY doof2d-array-parallel SYSTEM "./programs/examples/Doof2d/Doof2d-Array-parallel-annotated.cpp">
- <!-- Array data-parallel Doof2d implementation -->
- <!ENTITY doof2d-array-stencil SYSTEM "./programs/examples/Doof2d/Doof2d-Array-stencil-annotated.cpp">
- <!-- Array stencil Doof2d implementation -->
- <!ENTITY doof2d-array-distributed SYSTEM "./programs/examples/Doof2d/Doof2d-Array-distributed-annotated.cpp">
- <!-- distributed Array stencil Doof2d implementation -->
- <!ENTITY doof2d-field-parallel SYSTEM "./programs/examples/Doof2d/Doof2d-Field-parallel-annotated.cpp">
- <!-- Field data-parallel Doof2d implementation -->
- <!ENTITY doof2d-field-distributed SYSTEM "./programs/examples/Doof2d/Doof2d-Field-distributed-annotated.cpp">
- <!-- Field data-parallel distributed Doof2d implementation -->
-
- <!-- Sequential Programs -->
- <!ENTITY array-copy SYSTEM "./programs/examples/Sequential/array-copy-annotated.cpp">
- <!-- Illustrate Array reference semantics. -->
- <!ENTITY array-size SYSTEM "./programs/examples/Sequential/array-size-annotated.cpp">
- <!-- Illustrate Array member functions. -->
- <!ENTITY dynamicarray-example SYSTEM "./programs/examples/Sequential/dynamicarray-annotated.cpp">
- <!-- Illustrate using DynamicArray class. -->
- <!ENTITY initialize-finalize SYSTEM "./programs/examples/Sequential/initialize-finalize-annotated.cpp">
- <!-- Illustrate initialize() and finalize(). -->
-
- <!-- Template Programs -->
- <!ENTITY pairs-untemplated SYSTEM "./programs/examples/Templates/pairs-untemplated-annotated.cpp">
- <!-- Illustrate defining classes with pairs of values of the same type. -->
- <!ENTITY pairs-templated SYSTEM "./programs/examples/Templates/pairs-templated-annotated.cpp">
- <!-- Illustrate defining a template class with pairs of values of the same type. -->
- ]>
-
- <book>
- <bookinfo>
- <title>&pooma;</title>
- <subtitle>A &cc; &toolkitcap; 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>2002</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>1.00</revnumber>
- <date>2002 Jan 23</date>
- <authorinitials>jdo</authorinitials>
- <revremark>First publication.</revremark>
- </revision>
- </revhistory>
- </bookinfo>
-
- <!-- FINISH: May we have a short table of contents followed by a -->
- <!-- complete table of contents? -->
-
- <![%unfinished;[
- <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 &bookcap;</title>
-
- <para>FINISH: Write this section in a style similar to Lamport's
- LaTeX section 1.2. FINISH: Fix the book title and the section
- 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>
- ]]> <!-- end unfinished -->
-
- <![%temporary;[
- <preface id="acknowledgements">
- <title>Acknowledgements</title>
- ]]> <!-- end temporary -->
-
- <para>This &book; would not have been completed without the help
- and encouragement of a lot of people and organizations. Los Alamos
- National Laboratory funded the writing of this manual and the
- development of the &poomatoolkit;. John Reynders conceived,
- advocated, and headed &pooma; development in its early days, and
- Scott Haney continued the leadership. Susan Atlas, Subhankar
- Banerjee, Timothy Cleland, Julian Cummings, James Crotinger, David
- Forslund, Salman Habib, Scott Haney, Paul Hinker, William Humphrey,
- Steve Karmesin, Graham Mark, Jeffrey D. Oldham, Ji Qiang, John
- Reynders, Robert Ryne, Stephen Smith, M. Srikant, Marydell
- Tholburn, and Timothy Williams all helped develop &pooma;. Rod
- Oldehoeft and Jeff Brown of Los Alamos National Laboratory
- supported CodeSourcery's and Proximation's work, including the
- development of this manual. John Hall, Don Marshall, Jean
- Marshall, and the rest of the BLANCA team at Los Alamos worked
- closely with the developers and provided valuable suggestions for
- improvements.</para>
-
- <para>I am grateful to James Crotinger, Mark Mitchell, and Stephen
- Smith who answered my many questions during the writing of this
- &book;.</para>
-
- <!-- We cheat and abuse an epigraph here. -->
- <epigraph>
- <attribution>Jeffrey D. Oldham, 2002 January</attribution>
- <para></para>
- </epigraph>
-
- <![%temporary;[
- </preface>
- ]]> <!-- end temporary -->
-
- <![%unfinished;[
- </section>
-
- </preface>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
- <part id="programming">
- <title>Programming with &pooma;</title>
-
- <!-- FIXME: Add a partintro to the part above? -->
- ]]> <!-- end unfinished -->
-
- &introductory-chapter;
-
- &template-chapter;
-
- &tutorial-chapter;
-
- &concepts-chapter;
-
- &arrays-chapter;
-
-
- <chapter id="engines">
- <title>Engines</title>
-
- <para>Each container has one or more &engine;s to store or compute
- its values. As we mentioned in <xref
- linkend="arrays-arrays_declarations"></xref>, a container's role is
- high-level, supporting access to groups of values, and an engine's
- role is low-level, storing or computing values and supporting
- access to individual values. This separation permits optimizing
- space and computation requirements.</para>
-
- <para>We begin this chapter by introducing the concept of an engine
- and how it is used. Then, we describe the various &engine;s that
- &pooma; provides, separating them into engines that store values
- and engines that compute values.
- <![%unfinished;[
- Finally, we describe how the
- &engine;s are implemented, using tags to differentiate engines and
- reference-counted pointers to their underlying data.
- ]]> <!-- end unfinished -->
- </para>
-
-
- <section id="engines-concept">
- <title>The Concept</title>
-
- <para>An engine performs the low-level value storage, computation,
- and element-wise access for a container. An engine has a domain
- and accessor functions returning individual elements. The &pooma;
- &engine; class and its specializations implement the engine
- concept. Given an index within the domain, an &engine;'s
- <literal>operator()</literal> function returns the
- associated value, which can be used or changed. Its
- <literal>read</literal> member function returns the same
- value but permitting only use, not modification. The acceptable
- indices are determined by each &engine;. Most accept indices
- specified using ∫ and <type>Loc<&dim;></type>
- parameters, but an &engine; might accept string or floating-point
- parameters. An &engine;'s layout specifies maps its domain
- indices to the processors and memory used to store and compute the
- associated values.</para>
-
- <para>Since an engine's main role is to return the individual
- values associated with specific domain indices, any implementation
- performing this task is an engine. &pooma; &engine;s fall into
- three categories:
- <itemizedlist>
- <listitem>
- <para>&engine;s that store values.</para>
- </listitem>
- <listitem>
- <para>&engine;s that compute their values using other &engine;s'
- values.</para>
- </listitem>
- <listitem>
- <para>&engine;s that support distributed computation.</para>
- </listitem>
- </itemizedlist>
- For example, the &brick; &engine; explicitly stores all its
- values, while the &compressiblebrick; engine adds the feature of
- reducing its storage requirements if all these values are
- identical. A <type>UserFunction</type> &engine; yields values by
- applying a <glossterm linkend="glossary-function_object">function
- object</glossterm> to each value returned by another &engine;. A
- <type>CompFwd</type> &engine; projects components from another
- &engine;. For example, <type>CompFwd</type> will use the second
- components of each &vector; in an &array; to form its own &array;.
- Since each container has at least one &engine;, we can also
- describe the latter category as containers that compute their
- values using other containers' values. A &multipatch; &engine;
- distributes its domain among various processors and memory spaces,
- each responsible for computing values associated with a portion,
- or patch, of the domain. The &remote; &engine; also supports
- distributed computation.</para>
-
- <para>Just as multiple containers can use the same engine,
- multiple &engine;s can use the same underlying data. As we
- mentioned in <xref linkend="arrays-arrays_use"></xref>, &engine;s
- have <glossterm linkend="glossary-reference_semantics">reference
- semantics</glossterm>. A copy of an &engine; has a
- reference-counted pointer to the &engine;'s data (if any exists).
- Thus, copying an &engine; or a container requires little execution
- time. If an &engine; has the same data as another &engine; but it
- needs its own data to modify, the
- <literal>makeOwnCopy</literal> member function creates such
- a copy.</para>
-
- <para>&engine;s are rarely explicitly declared. Instead a
- container is declared using an &engine; tag, and the container
- creates the specified &engine; to deal with its values. For
- example, a &brick; &engine; is explicitly declared as
- <type>Engine<&dim;,T,Brick></type>, but they are more
- frequently created by containers, e.g.,
- <type>Array<&dim;,T,Brick></type>. An &engine;'s first two
- template parameters specify the domain's dimensionality and the
- value type, as described in <xref
- linkend="arrays-arrays_declarations"></xref>. Unlike container
- declarations, the third template parameter, the &engine; tag,
- specifies which &engine; specialization to use. For example, the
- &brick; &engine; tag indicates a &brick; &engine; should be used.
- Some &engine;s, such as <type>CompFwd</type>, are rarely declared
- even using &engine; tags. Instead the &array;'s
- <literal>comp</literal> and
- <literal>readComp</literal> member functions return views of
- containers using <type>CompFwd</type> &engine;s.</para>
- </section>
-
-
- <section id="engines-types">
- <title>Types of &engine;s</title>
-
- <para>In this section, we describe the different types of
- &engine;s and illustrate their creation, when appropriate. First,
- we describe &engine;s that explicitly store values and then
- &engine;s that compute values. See <xref
- linkend="engines-types-table"></xref>.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0" id="engines-types-table">
- <title>Types of &engine;s</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>&engine; tag</entry>
- <entry>description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row rowsep="1">
- <entry>&engine;s That Store</entry>
- </row>
- <row>
- <entry>&brick;</entry>
- <entry>explicitly stores all values; similar to &c; arrays.</entry>
- </row>
- <row>
- <entry>&compressiblebrick;</entry>
- <entry>stores all values, reducing storage requirements when
- all values are identical.</entry>
- </row>
- <row>
- <entry>&dynamic;</entry>
- <entry>is a one-dimensional &brick; with dynamically
- resizable domain. This should be used with &dynamicarray;,
- not &array;.</entry>
- </row>
- <row rowsep="1">
- <entry>&engine;s That Compute</entry>
- </row>
- <row>
- <entry><type>CompFwd</type></entry>
- <entry>extracts specified components of an engine's vectors,
- tensors, arrays, etc.; usually created using the
- <literal>comp</literal> container function.</entry>
- </row>
- <row>
- <entry><type>ConstantFunction</type></entry>
- <entry>makes a scalar value behave like a container.</entry>
- </row>
- <row>
- <entry><type>IndexFunction<FunctionObject></type></entry>
- <entry>makes the <type>FunctionObject</type>'s function of
- indices behave like a container.</entry>
- </row>
- <row>
- <entry><type>ExpressionTag<Expr></type></entry>
- <entry>evaluates an expression tree; usually created by
- data-parallel expressions.</entry>
- </row>
- <row>
- <entry><type>Stencil<Function, Expression></type></entry>
- <entry>applies a stencil computation (<type>Function</type>)
- to its input (<type>Expression</type>) which is usually a
- container; usually created by applying a <type>Stencil</type>
- object to a container. A stencil computation can use
- multiple neighboring input values.</entry>
- </row>
- <row>
- <entry><type>UserFunctionEngine<Function,
- Expression></type></entry>
- <entry>applies the given function (or <glossterm
- linkend="glossary-function_object">function
- object</glossterm>) to its input (<type>Expression</type>)
- which is usually a container; usually created by applying a
- <type>UserFunction</type> object to a container. The
- function implements a one-to-one mapping from its input to
- values.</entry>
- </row>
- <row rowsep="1">
- <entry>&engine;s for Distributed Computation</entry>
- </row>
- <row>
- <entry><type>MultiPatch<LayoutTag,EngineTag></type></entry>
- <entry>runs a separate <type>EngineTag</type> &engine; on
- each context (patch) specified by the given layout. This is
- the usual &engine; for distributed computation.</entry>
- </row>
- <row>
- <entry><type>Remote<EngineTag></type></entry>
- <entry>runs the &engine; specified by <type>EngineTag</type>
- on a specified context.</entry>
- </row>
- <row>
- <entry><type>Remote<Dynamic></type></entry>
- <entry>runs a <type>Dynamic</type> one-dimensional, resizable
- &engine; on a specified context. This is a specialization of
- <type>Remote</type>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- FIXME: Place in firstterm. -->
- <para><glossterm linkend="glossary-brick">&brick;
- &engine;s</glossterm> explicitly store values just like &c;
- arrays. &compressiblebrick; &engine;s optimize their storage
- requirements when all values are identical. Many &array;s use one
- of these two &engine;s. &brick;s are the default &engine;s for
- &array; and &field; containers because they explicitly store each
- value. This explicit storage can require a large amount of space,
- particularly if all these values are the same. If all a
- compressible brick &engine;'s values are identical, the &engine;
- stores that one value rather than many, many copies of the same
- value. These engines can both save time as well as space.
- Initializing a compressible engine requires setting only one
- value, not every value. Using less storage space may also permit
- more useful values to be stored in cache, improving cache
- performance. Reading a value in a compressed &engine; using the
- <literal>read</literal> member function is as fast as
- reading a value in a &brick; &engine;, but writing a value always
- requires executing an additional <literal>if</literal>
- conditional. Thus, if an &engine; infrequently has multiple
- different values during its life time, a &compressiblebrick;
- &engine; may be faster than a &brick; &engine;. If an &engine; is
- created and its values are mostly read, not written, a
- &compressiblebrick; &engine; may also be faster. Otherwise, a
- &brick; &engine; may be preferable. Timing the same program using
- the two different &engine; types will reveal which is faster for a
- particular situation. In distributed computing, many &engine;s
- may have few nonzero values so &compressiblebrick; &engine;s may
- be preferable. For distributed computing, a container's domain is
- partitioned into regions each computed by a separate processor and
- &engine;. If the computation is concentrated in sections of the
- domain, many &engine;s may have few, if any, nonzero values.
- Thus, &compressiblebrick; &engine;s may be preferable for
- distributed computing.</para>
-
- <para>Both &brick; and &compressiblebrick; &engine;s have
- <literal>read</literal> and
- <literal>operator()</literal> member functions taking ∫
- and &loc; parameters. The parameters should match the &array;'s
- dimensionality. For example, if &array; <varname>a</varname> has
- dimensionality 3, <function>a.read(int, int, int)</function>
- and <function>a(int, int, int)</function> should be used. The
- former returns a value that cannot be modified, while the latter
- can be changed. Using the <literal>read</literal> member
- function can lead to faster code. Alternatively, an index can be
- specified using a &loc;. For example,
- <literal>a.read(Loc<3>(1,-2,5))</literal> and
- <literal>a(Loc<3>(1,-2,5))</literal> are equivalent to
- <literal>a.read(1,-2,5))</literal> and
- <literal>a(1,-2,5)</literal>.</para>
-
- <para>The &dynamic; &engine; supports changing domain sizes while
- a program is executing. It is basically a one-dimensional
- &brick;, explicitly storing values, but permitting the number and
- order of stored values to change. Thus, it supports the same
- interface as &brick; except that all member functions are
- restricted to their one-dimensional versions. For example,
- <literal>read</literal> and
- <literal>operator()</literal> take <type>Loc<1></type>
- or one ∫ parameter. In addition, the one-dimensional domain
- can be dynamically resized using <literal>create</literal>
- and <literal>destroy</literal>.
- <![%unfinished;[
- ; see .
-
- HERE Dynamic. How does one change the domain size? What is the model?
- ]]> <!-- end unfinished -->
- </para>
-
- <![%unfinished;[
- <!-- HERE: Array cannot forward domain size changes to underlying Dynamic Engine. -->
-
- <para>Types of &engine;s:
- Brick - explicitly store values
- CompressibleBrick - explicitly store values but store only one if all the same
- ConstantFunction - convert scalar into an array
- DynamicEngine - contiguous, local, resizable, 1D block
- ExpressionEngine - evaluate PETE expression
- CompFwd - array formed by extracted components from array
- ForwardEngine
- tut-02.html: use .comp() or .readComp()
- IndexFunctionEngine - convert function of indices into an array
- IndirectionEngine - incomplete
- MultiPatch - ?How do I describe this?
- RemoteDynamic - run a Dynamic engine on a specified context
- Remote - permit computations on specified context
- should discuss with MultiPatch
- Stencil - apply a stencil to an array, returning a new Array with the results
- UserFunction - Array = apply function to an Array
- </para>
-
- <para>How do I organize these engines into understandable
- categories?
-
- storage
- Brick
- CompressibleBrick
- Dynamic - resizable 1D block
- RemoteDynamic
- MultiPatch - ?WHAT?
- Remote
-
- computation
- CompFwd: project(array)->array
- .comp() and .readComp()
- view, not a copy
- ConstantFunction: scalar(array)->array
- explicitly use
- IndexFunctionEngine: function(indices)->array
- explicitly use
- ExpressionEngine: expression(array)->array
- created by data-parallel expression
- Stencil: stencil(array)->array
- implicitly used
- explicitly use Stencil<...> type
- UserFunction: function(array)->array
- explicitly use
- </para>
-
- <para>
- Element_t read(Loc<&dim;>)
- ElementRef_t operator()(Loc<&dim;>)
- Element_t read(int+)
- ElementRef_t operator()(int+)
- </para>
-
- <para>Explain the concept of an engine. How does an engine
- interact with a container or an &array;? Explain the different
- types of engines likely to be used by &pooma; programmers and how
- to declare containers using them. Should I list the other engines
- that are automatically created?</para>
- ]]> <!-- end unfinished -->
-
- </section>
- </chapter>
-
-
- &data-parallel-chapter;
-
-
- <chapter id="views">
- <title>Container Views</title>
-
- <indexterm zone="views">
- <primary>container</primary>
- <secondary>view</secondary>
- </indexterm>
- <indexterm>
- <primary>view of a container</primary>
- <see>container, view.</see>
- </indexterm>
-
- <![%temporary;[
-
- <para>A <glossterm linkend="glossary-view"><firstterm>view of a
- container</firstterm></glossterm> is a container accessing a subset
- of &container;'s domain and values. The subset can include all of
- the container's domain. A <quote>view</quote> is so named because
- it is a different way to access, or view, another container's
- values. Both the container and its view share the same underlying
- engine so changing values in one also changes them in the
- other.</para>
-
- <para>A view is created by following a container's name by
- parentheses containing a domain. For example, consider this code
- extracted from <xref
- linkend="tutorial-array_parallel-doof2d"></xref> in <xref
- linkend="tutorial-array_data_parallel"></xref>.
- <programlisting>
- Interval<1> N(0, n-1);
- Interval<2> vertDomain(N, N);
- Interval<1> I(1,n-2);
- Interval<1> J(1,n-2);
- Array<2, double, Brick> a(vertDomain);
- Array<2, double, Brick> b(vertDomain);
- a(I,J) = (1.0/9.0) *
- (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) +
- b(I-1,J+1) + b(I-1,J ) + b(I-1,J-1));
- </programlisting> The last statement creates ten views. For example,
-
- <literal>a(I,J)</literal> creates a view of
- <varname>a</varname> using the smaller domain specified by
- <varname>I</varname> and <varname>J</varname>. This omits the
- outermost rows of columns of <varname>a</varname>. The views
- of <varname>b</varname> illustrate the use of views in
- data-parallel statements. <literal>b(I-1,J-1)</literal> has a
- subset shifted up one row and left one column compared with
- <literal>b(I,J)</literal>.</para>
- ]]> <!-- end temporary -->
- <![%unfinished;[
- <para>Be sure to list the various arithmetic operations on domains
- that can be used. This was deferred from the &array; and domain
- chapter. Explain &array;'s <function>comp</function> function.</para>
-
- <!-- FIXME: Finish this chapter. -->
- ]]> <!-- end unfinished -->
- </chapter>
-
-
- <![%unfinished;[
- <chapter id="sequential">
- <title>Writing Sequential Programs</title>
-
- <para>FIXME: Explain the chapter's purpose.</para>
-
- <para>FIXME: Explain the format of each section.</para>
-
- <para>FIXME: Explain the order of the sections.</para>
-
- <para>Proposed order. Basically follow the order in the proposed
- reference section.
- <orderedlist>
- <listitem><para>starting, stopping</para></listitem>
- <listitem><para>&array;</para></listitem>
- <listitem><para>&dynamicarray;</para></listitem>
- <listitem><para>&field;</para></listitem>
- <listitem><para>&vector;</para></listitem>
- <listitem><para>&matrix;</para></listitem>
- <listitem><para>&tensor;</para></listitem>
- <listitem><para>&engine;</para></listitem>
- <listitem><para>domain</para></listitem>
- <listitem><para>correctness, e.g., <function>PAssert</function></para></listitem>
- <listitem><para>&pooma; command-line options</para></listitem>
- </orderedlist>
- Include views of containers in the appropriate sections.</para>
-
- <para><emphasis>&c;: A Reference Manual</emphasis> uses this
- structure for &c; libraries:
- <orderedlist>
- <listitem>
- <para>function declarations, separated by rules from rest of text</para>
- </listitem>
- <listitem>
- <para>text explanation</para>
- </listitem>
- <listitem>
- <para>table of structure members if appropriate</para>
- </listitem>
- <listitem>
- <para>example</para>
- </listitem>
- </orderedlist>
- </para>
-
- <para><emphasis>STL Tutorial and Reference Guide</emphasis>, second
- edition, uses this structure for STL functions:
- <orderedlist>
- <listitem>
- <para>text description with declaration mixed in</para>
- </listitem>
- <listitem>
- <para>example program mixed into text. It is an entire program,
- not a program fragment.</para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>A tutorial chapter for containers has
- <orderedlist>
- <listitem>
- <para>explanation of template types</para>
- </listitem>
- <listitem>
- <para>bulleted list of container types</para>
- </listitem>
- <listitem>
- <para>example constructors</para>
- </listitem>
- <listitem>
- <para>example programs</para>
- </listitem>
- <listitem>
- <para>member and related functions with example programs</para>
- </listitem>
- <listitem>
- <para>list of accessors and relation functions</para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>The reference chapter for containers has
- <orderedlist>
- <listitem>
- <para>a section listing common members and types for all containers</para>
- </listitem>
- <listitem>
- <para>a section listing common member functions for all containers</para>
- </listitem>
- <listitem>
- <para>requirements for various container specialties</para>
- </listitem>
- </orderedlist>
- The section describing <type>vector</type>s contains
- <orderedlist>
- <listitem>
- <para>files (header files)</para>
- </listitem>
- <listitem>
- <para>class declaration</para>
- </listitem>
- <listitem>
- <para>description</para>
- </listitem>
- <listitem>
- <para>type definitions</para>
- </listitem>
- <listitem>
- <para>constructors, destructors, and related functions</para>
- </listitem>
- <listitem>
- <para>comparison operators</para>
- </listitem>
- <listitem>
- <para>element access member functions</para>
- </listitem>
- <listitem>
- <para>insert and erase member functions</para>
- </listitem>
- <listitem>
- <para>notes</para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>Josuttis's <emphasis>The &cc; Standard Library: A Tutorial
- and Reference</emphasis> uses this structure for its STL container
- chapter:
- <orderedlist>
- <listitem>
- <para>short introduction</para>
- </listitem>
- <listitem>
- <para>common container abilities</para>
- </listitem>
- <listitem>
- <para>common container operations (with table)</para>
- </listitem>
- <listitem>
- <para>vector abilities</para>
- </listitem>
- <listitem>
- <para>vector operations:
- <orderedlist>
- <listitem>
- <para>create, copy, and destroy operations (mostly table)</para>
- </listitem>
- <listitem>
- <para>non-modifying operations (mostly table)</para>
- </listitem>
- <listitem>
- <para>assignments (mostly table)</para>
- </listitem>
- <listitem>
- <para>element access (mostly table)</para>
- </listitem>
- <listitem>
- <para>iterator functions (mostly table)</para>
- </listitem>
- <listitem>
- <para>inserting and removing elements (mostly table)</para>
- </listitem>
- </orderedlist>
- </para>
- </listitem>
- <listitem>
- <para>using vectors as ordinary arrays</para>
- </listitem>
- <listitem>
- <para>exception handling</para>
- </listitem>
- <listitem>
- <para>example program</para>
- </listitem>
- </orderedlist>
- </para>
-
- <section id="sequential-begin_end">
- <title>Beginning and Ending &pooma; Programs</title>
-
- <para>Every &pooma; program must begin with a call to
- <function>initialize</function> and end with a call to
- <function>finalize</function>. These functions respectively
- prepare and shut down &pooma;'s run-time structures.</para>
-
- <bridgehead id="sequential-begin_end-files" renderas="sect2">Files</bridgehead>
-
- <programlisting>
- #include "Pooma/Pooma.h" // or "Pooma/Arrays.h" or "Pooma/Fields.h" or ...
- </programlisting>
-
- <bridgehead id="sequential-begin_end-declarations" renderas="sect2">Declarations</bridgehead>
-
- <funcsynopsis>
- <funcprototype>
- <funcdef>bool <function>Pooma::initialize</function></funcdef>
- <paramdef>
- <parameter class="function">int &argc,</parameter>
- <parameter class="function">char ** &argv,</parameter>
- <parameter class="function">bool initRTS = true,</parameter>
- <parameter class="function">bool getCLArgsArch = true,</parameter>
- <parameter class="function">bool initArch = true</parameter>
- </paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>bool <function>Pooma::initialize</function></funcdef>
- <paramdef>
- <parameter class="function">Pooma::Options &opts,</parameter>
- <parameter class="function">bool initRTS = true,</parameter>
- <parameter class="function">bool initArch = true</parameter>
- </paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>bool <function>Pooma::finalize</function></funcdef>
- <void></void>
- </funcprototype>
-
- <funcprototype>
- <funcdef>bool <function>Pooma::finalize</function></funcdef>
- <paramdef>
- <parameter class="function">bool quitRTS,</parameter>
- <parameter class="function">bool quitArch</parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
-
- <bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
-
- <para>Before its use, the &poomatoolkit; must be initialized by a
- call to <function>initialize</function>. This usually occurs in
- the <function>main</function> function. The first form removes
- and processes any &pooma;-specific arguments from the
- command-line arguments <varname>argv</varname> and
- <varname>argc</varname>. <xref
- linkend="sequential-options"></xref> describes these options.
- The third, fourth, and fifth arguments all have a default value
- of &true;. If <parameter class="function">initRTS</parameter> is
- &true;, the run-time system is initialized. E.g., the contexts
- are prepared for use. If <parameter
- class="function">getCLArgsArch</parameter> is &true,
- architecture-specific command-line arguments are removed from
- <varname>argv</varname> and <varname>argc</varname>.
- Architecture-specific initialization occurs if <parameter
- class="function">getCLArgsArch</parameter> is &true;. An <link
- linkend="glossary-architecture">architecture</link> is specified
- by a hardware interface, e.g., processor type, but frequently is
- also associated with an operating system or compiler. For
- example, Metrowerks for the Macintosh has an
- architecture-specific initialization. The function always
- returns &true;.</para>
-
- <para><function>initialize</function>'s alternative form
- assumes the &pooma;-specific and architecture-specific
- command-line arguments have already been removed from
- <varname>argv</varname> and <varname>argc</varname> and stored in
- <parameter class="function">opts</parameter>. Its other two
- parameters have the same meaning, and the two functions'
- semantics are otherwise the same.</para>
-
- <para>After its use, the &poomatoolkit; should be shut down using
- a call to <function>finalize</function>. This usually occurs in
- the <function>main</function> function. The former, and more
- frequently used, form first prints any statistics and turns off
- all default &pooma; streams. Then it shuts down the run-time
- system if it was previously initialized and then shuts down
- architecture-specific objects if they were previously
- initialized. The latter form gives provides explicit control
- whether the run-time system (<parameter
- class="function">quitRTS</parameter>) and architecture-specific
- objects (<parameter class="function">quitArch</parameter>) are
- shut down. Both functions always returns &true;.</para>
-
- <para>Including almost any &pooma; header file, rather than just
- <filename class="headerfile">Pooma/Pooma.h</filename> suffices
- since most other &pooma; header files include it.</para>
-
- <bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
-
- <para>Since every &pooma; program must call
- <function>initialize</function> and
- <function>finalize</function>, the simplest &pooma; program also
- must call them. This program also illustrates their usual
- use.</para>
-
- &initialize-finalize;
-
- </section><!-- end sequential-begin_end -->
-
-
- <section id="sequential-global">
- <title>Global Variables</title>
-
- <para>&pooma; makes a few global variables available after
- initialization.</para>
-
- <table frame="none" colsep="0" rowsep="0" tocentry="1"
- orient="port" pgwide="0">
- <title>&pooma; Global Variables</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>variable</entry>
- <entry>description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>&inform; <varname>pinfo</varname></entry>
- <entry>output stream used to print informative messages to the
- user while the program executes. The stream accepts a
- superset of standard output operations.</entry>
- </row>
- <row>
- <entry>&inform; <varname>pwarn</varname></entry>
- <entry>FIXME: output stream used to print informative messages to the
- user while the program executes. The stream accepts a
- superset of standard output operations.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="sequential-options">
- <title>&pooma; Command-line Options</title>
-
- <para>Every &pooma; program accepts a set of &pooma;-specific
- command-line options to set values at run-time.</para>
-
- <para>QUESTION: Should I defer documenting &options; to the
- reference manual, instead just listing commonly used options in
- the previous section?
-
- UNFINISHED</para>
-
- <section id="sequential-options-list">
- <title>Options Summary</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter class="option">&dashdash;pooma-info</parameter></term>
- <listitem>
- <para>enable use of the <varname>pinfo</varname>, used to
- print informative messages to the user while the program
- executes.</para>
- </listitem>
- </varlistentry>
- <!-- UNFINISHED -->
- </variablelist>
-
- <para>FIXME: Be sure to list default values.</para>
- <!-- FIXME: need to describe the pinfo, pwarn, and perr streams somewhere. To do so requires describing informs.-->
- <!-- FIXME: Which streams are buffered and which are not? -->
-
- </section>
-
- </section><!-- end sequential-options -->
-
- <section>
- <title>TMP: Place these somewhere.</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.
- <![%unfinished;[
- See <xref
- linkend="debugging_profiling-missing_blockandevaluate"></xref> for
- instructions how to diagnose and eliminate these race
- conditions.
- ]]> <!-- end unfinished -->
- </para>
-
- <para>Where talk about various &pooma; streams?</para>
-
- <para>UNFINISHED</para>
-
- </section>
-
-
- <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>
- <title>Miscellaneous</title>
-
- <para>Section 3, "Domains and Views," of
- <filename>papers/iscope98.pdf</filename> describes four types of
- domains.</para>
-
- <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; multidimensional Array concept is similar to
- the &fortran; 90 array facility, but extends it in several
- ways. Both &pooma; and &fortran; arrays can have up to seven
- dimensions, and can serve as containers for arbitrary
- 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 &array;s 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
- <literal><varname>A</varname>*<varname>B</varname>+<varname>C</varname></literal>
- 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>&multipatch; 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>
- </chapter>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
- <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>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
- <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
- <literal>&dashdash;pooma-blocking-expressions</literal> 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
- <literal>&dashdash;pooma-blocking-expressions</literal> 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 <literal>Pooma::blockingExpressions(true)</literal>
- and <literal>Pooma::blockingExpressions(false)</literal>,
- but do not use the
- <literal>&dashdash;pooma-blocking-expressions</literal> 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>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
- </part>
- ]]> <!-- end unfinished -->
-
- <![%unfinished;[
- <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, 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 valign="top">
- <row>
- <entry><varname>Dim</varname></entry>
- <entry><para>dimension</para></entry>
- </row>
- <row>
- <entry><type>T</type></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 valign="top">
- <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 valign="top">
- <row>
- <entry>
- <constructorsynopsis>
- <literal>Array</literal>
- <void></void>
- </constructorsynopsis>
- </entry>
- <entry><para>Creates an array that will be resized
- later.</para></entry>
- </row>
- <row>
- <entry>
- <constructorsynopsis>
- <literal>Array</literal>
- <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>
- <literal>Array</literal>
- <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 valign="top">
- <row>
- <entry>
- <methodsynopsis>
- <type>Element_t</type> <literal>read</literal>
- <void></void>
- </methodsynopsis>
- </entry>
- <entry><para>unknown: See line 1839.</para></entry>
- </row>
- <row>
- <entry>
- <methodsynopsis>
- <type>Element_t</type> <literal>read</literal>
- <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> <literal>operator()</literal>
- <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 <literal>read(const
- Sub1& s1, const Sub2& s2)</literal>? </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
- <literal>comp</literal> 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,
- <literal>a.comp(1)</literal> 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 valign="top">
- <row>
- <entry>
- <methodsynopsis>
- <type>UNKNOWN compute this</type> <literal>comp</literal>
- <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 <literal>comp</literal>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 valign="top">
- <row>
- <entry>
- <methodsynopsis>
- <type>int</type> <literal>first</literal>
- <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
- <literal>engine</literal>.</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 valign="top">
- <row>
- <entry>
- <methodsynopsis>
- <type>void</type> <literal>makeOwnCopy</literal>
- <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 <literal>private</literal>data consists of
- an engine, and it has no <literal>private</literal>
- 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 valign="top">
- <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
- <literal>protected</literal> or
- <literal>private</literal> 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 <literal>a + b</literal>
- 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 valign="top">
- <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>
-
- <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>
-
- <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
- <literal>all</literal>.</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
- <literal>operator[]</literal>,
- <literal>subField</literal>, …,
- <literal>material</literal>.</para>
- </section>
-
-
- <section id="fields_ref-field-relations">
- <title>Supporting Relations</title>
-
- <para>ADD: a table with the member functions including
- <literal>addRelation</literal>,
- <literal>removeRelations</literal>,
- <literal>applyRelations</literal>, and
- <literal>setDirty</literal>.</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
- <literal>makeOwnCopy</literal>.</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 <literal>f[i]</literal>. 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 valign="top">
- <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 valign="top">
- <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 <literal>read</literal> and
- <literal>operator()</literal>.</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
- <literal>makeOwnCopy</literal>.</para>
-
- <para>QUESTION: What are <literal>dataObject</literal>,
- <literal>isShared</literal>, 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.,
- <literal>offset</literal>.</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
- <literal>Options::usage</literal>.</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.</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>
-
-
- <chapter id="needed_reference_items_ref">
- <title>TMP: Items to Discuss in Reference Manual</title>
-
- <itemizedlist>
- <listitem>
- <para>Discuss &options; and related material. Add developer
- command-line options listed in <filename
- class="libraryfile">Utilities/Options.cmpl.cpp</filename> and also
- possibly <parameter class="option">&dashdash;pooma-threads
- <replaceable>n</replaceable></parameter>.</para>
- </listitem>
- </itemizedlist>
- </chapter>
- </part>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
- <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>
- ]]> <!-- end unfinished -->
-
-
- <appendix id="installation">
- <title>Obtaining and Installing &pooma;</title>
-
- <![%temporary;[
- <para>In <xref linkend="tutorial-installation"></xref>, we described
- how to install &pooma;. In the following section, we describe how
- to install &pooma; to support distributed computation.</para>
- ]]> <!-- end temporary -->
-
- <![%unfinished;[
- <para>ADD: Write this section, including extensive instructions
- for Unix-like, MS Windows, and MacOS. List the configuration options.
- Be sure to describe configuring for parallel execution.</para>
- ]]> <!-- end unfinished -->
-
- <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 the following
- section, we first describe how to install &mm;. Read it 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 <ulink
- url="http://www.engelschall.com/sw/mm/">http://www.engelschall.com/sw/mm/</ulink>,
- is available at no cost and has been successfully tested on a
- variety of Unix-like 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
- (&poomadownloadpage;) 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>. Change directories 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
- <programlisting>
- ./configure &dashdash;prefix=${HOME}/pooma/mm-1.1.3
- </programlisting></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>
- environment variable to the desired 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
- <![%unfinished;[
- (FIXME: xref linkend="mpi99", <ulink
- url="http://www-unix.mcs.anl.gov/mpi/"></ulink>)
- ]]> <!-- end unfinished -->
- or the &mm; Shared Memory Library. &mpi; works on a wide variety
- of platforms and has achieved widespread usage. &mm; works under
- Unix-like operating systems on any computer with shared memory. Both libraries are
- available at no cost. 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
- (&poomadownloadpage;) available off the &pooma; home page
- (&poomahomepage;).</para>
- </listitem>
- <listitem>
- <para>Extract the source code using <command>tar xzvf
- cheetah-1.0.tgz</command>. Change directories 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
- <literal>"/home/oldham/pooma/mm-1.1.3"</literal>.</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,
- <programlisting>
- declare -x CHEETAHDIR=${HOME}/pooma/cheetah-1.0
- </programlisting> specifies the
- installation directory used in the previous section. If using
- the <application>csh</application> shell, use <command>setenv
- CHEETAHDIR ${HOME}/pooma/cheetah-1.0</command>.</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>
-
-
- <![%unfinished;[
- <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>Section 5, "Performance," of
- <filename>papers/iscope98.pdf</filename> motivates and explains
- stencils.</para>
- </listitem>
-
- <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>
- ]]> <!-- end unfinished -->
-
-
- &bibliography-chapter;
-
- &glossary-chapter;
-
- <!-- Index -->
-
- <![%unfinished;[
- &genindex.sgm;
- ]]> <!-- end unfinished -->
-
- </book>
--- 0 ----
Index: pooma.xml
===================================================================
RCS file: pooma.xml
diff -N pooma.xml
*** /dev/null Fri Mar 23 21:37:44 2001
--- pooma.xml Thu Jan 31 14:10:44 2002
***************
*** 0 ****
--- 1,4223 ----
+ <?xml version="1.0"?>
+ <!-- FIXME: Index this file. -->
+
+ <!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. -->
+
+ <!-- Conditional Inclusion Entity Declarations -->
+ <!ENTITY % unfinished "IGNORE">
+ <!-- Unfinished sections should not be included in published versions. -->
+ <!ENTITY % temporary "INCLUDE">
+ <!-- Temporary sections to be included in published versions until the final version is written. -->
+
+ <!-- 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 bookcap "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 closeclose ">⪆⪆>" >
+ <!-- Produce a notation for ">>", which frequently occurs with templates. Without this, TeX produces a shift symbol. -->
+ <!ENTITY closecloseclose ">⪆⪆>⪆⪆>" >
+ <!-- Produce a notation for ">>>", which infrequently occurs with templates. Without this, TeX produces a shift symbol. -->
+ <!ENTITY dashdash "-⪆-" >
+ <!-- Produce a notation for a double dash. Without this, TeX produces an en-hyphen. -->
+ <!ENTITY dim "D">
+ <!-- the number of dimensions of an array, domain, etc. -->
+ <!ENTITY doof2d "<command>Doof2d</command>" >
+ <!-- Produce a notation for the Doof2d program. -->
+ <!ENTITY fortran "<application class='software'>Fortran</application>">
+ <!-- Produce a notation for the Fortran programming language. -->
+ <!ENTITY gap " ">
+ <!-- Produce a small gap so TeX will not combine the two characters. -->
+ <!-- FIXME: Choose something that will work for TeX and also in HTML. -->
+ <!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 openopen "<⪆<" >
+ <!-- Produce a notation for "<<", which frequently occurs with output. Without this, TeX produces a shift symbol. -->
+ <!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 framework. -->
+ <!ENTITY pooma "<application class='software'>POOMA</application>">
+ <!-- Produce a notation for Pooma software. -->
+ <!ENTITY poomatoolkit "<application class='software'>POOMA &toolkitcap;</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. -->
+ <!ENTITY toolkit "toolkit">
+ <!-- Produce a notation for the name of the Pooma software. -->
+ <!ENTITY toolkitcap "Toolkit">
+ <!-- Produce a capitalized version of &toolkit;. -->
+
+ <!-- Type Entity Declarations -->
+
+ <!ENTITY array "<type>Array</type>">
+ <!-- The "Array" type. -->
+ <!ENTITY benchmark "<type>Benchmark</type>">
+ <!-- The "Benchmark" type. -->
+ <!ENTITY bool "<type>bool</type>">
+ <!-- The C++ boolean type. -->
+ <!ENTITY brick "<type>Brick</type>">
+ <!-- The "Brick" engine type. -->
+ <!ENTITY char "<type>char</type>">
+ <!-- The C char type. -->
+ <!ENTITY complex "<type>complex</type>">
+ <!-- The C++ "complex" 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 domaintemplate "DT">
+ <!-- A domain template parameter. -->
+ <!ENTITY double "<type>double</type>">
+ <!-- The C "double" type. -->
+ <!ENTITY dynamic "<type>Dynamic</type>">
+ <!-- The "Dynamic" Engine type. -->
+ <!ENTITY dynamicarray "<type>DynamicArray</type>">
+ <!-- The "DynamicArray" type. -->
+ <!ENTITY engine "<type>Engine</type>">
+ <!-- The "Engine" type. -->
+ <!ENTITY false "<literal>false</literal>">
+ <!-- The false Boolean value. -->
+ <!-- Modify its tag to the appropriate one. -->
+ <!ENTITY field "<type>Field</type>">
+ <!-- The "Field" type. -->
+ <!ENTITY float "<type>float</type>">
+ <!-- The C "float" type. -->
+ <!ENTITY grid "<type>Grid</type>">
+ <!-- The "Grid" domain type. -->
+ <!ENTITY gridone "<type>Grid<1></type>">
+ <!-- The "Grid<1>" one-dimensional domain type. -->
+ <!ENTITY indirectionlist "<type>IndirectionList</type>">
+ <!-- The "IndirectionList" (domain-helper) type. -->
+ <!ENTITY indirectionlistint "<type>IndirectionList<int></type>">
+ <!-- The "IndirectionList<int>" (domain-helper) type. -->
+ <!ENTITY inform "<type>Inform</type>">
+ <!-- The "Inform" output type. -->
+ <!ENTITY int "<type>int</type>">
+ <!-- The C "int" type. -->
+ <!ENTITY interval "<type>Interval</type>">
+ <!-- The "Interval" type. -->
+ <!ENTITY intervalone "<type>Interval<1></type>">
+ <!-- The "Interval<1>" one-dimensional domain type. -->
+ <!ENTITY layout "<type>Layout</type>">
+ <!-- The "Layout" type without template parameters. -->
+ <!ENTITY leaffunctor "<type>LeafFunctor</type>">
+ <!-- The "LeafFunctor" type. -->
+ <!ENTITY loc "<type>Loc</type>">
+ <!-- The "Loc" domain type. -->
+ <!ENTITY locone "<type>Loc<1></type>">
+ <!-- The "Loc<1>" one-dimensional domain type. -->
+ <!ENTITY matrix "<type>TinyMatrix</type>">
+ <!-- The Pooma matrix type. -->
+ <!ENTITY multipatch "<type>MultiPatch</type>">
+ <!-- The "MultiPatch" engine without template parameters. -->
+ <!ENTITY options "<type>Options</type>">
+ <!-- The &pooma; options type. -->
+ <!ENTITY range "<type>Range</type>">
+ <!-- The "Range" domain type. -->
+ <!ENTITY rangeone "<type>Range<1></type>">
+ <!-- The "Range<1>" one-dimensional domain type. -->
+ <!ENTITY remote "<type>Remote</type>">
+ <!-- The "Remote" engine type. -->
+ <!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 true "<literal>true</literal>">
+ <!-- The true Boolean value. -->
+ <!-- Modify its tag to the appropriate one. -->
+ <!ENTITY vector "<type>Vector</type>">
+ <!-- The "Vector" type. -->
+
+ <!-- Mathematical Entity Declarations -->
+
+ <!ENTITY container "C">
+ <!-- an abbreviation for a canonical container -->
+ <!ENTITY containerdomain "D">
+ <!-- an abbreviation for a canonical container domain -->
+ <!ENTITY n "n">
+ <!-- the size of one dimension of an array -->
+ <!ENTITY space "ℜ<superscript>d</superscript>">
+ <!-- a notation for multidimensional space -->
+
+ <!-- System and Operating System Entity Declarations -->
+ <!ENTITY gcc "<application>g++</application>">
+ <!-- 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.codesourcery.com/pooma/pooma/">http://www.codesourcery.com/pooma/pooma/</ulink>'>
+ <!-- The canonical Pooma home page. -->
+ <!-- UPDATE this filename. -->
+ <!ENTITY poomasource "pooma-2.3.0">
+ <!-- The Pooma source code directory. -->
+ <!-- UPDATE this filename. -->
+ <!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. -->
+ <!ENTITY naive "naïve">
+ <!-- The word "na\"{\i}ve." -->
+ <!ENTITY naivecap "Naïve">
+ <!-- The word "Na\"{\i}ve," i.e., the capitalized &naive;. -->
+ <!-- The Pooma source code directory. -->
+ <!-- spelling: dependence, not dependency -->
+ <!-- spelling: element-wise, not elementwise -->
+ <!-- phrase: function object, not functor -->
+ <!-- spelling: interprocessor, not inter-processor -->
+ <!-- spelling: multidimensional, not multi-dimensional -->
+ <!-- spelling: multiprocessor, not multi-processor -->
+ <!-- spelling: nonzero, not non-zero -->
+ <!-- formatting: for sets, no spaces between brackets and entries but spaced between entries -->
+
+ <!-- External Chapters -->
+ <!ENTITY arrays-chapter SYSTEM "arrays.xml">
+ <!-- Pooma Arrays chapter -->
+ <!ENTITY bibliography-chapter SYSTEM "bibliography.xml">
+ <!-- bibliography -->
+ <!ENTITY concepts-chapter SYSTEM "concepts.xml">
+ <!-- Pooma concepts chapter -->
+ <!ENTITY data-parallel-chapter SYSTEM "data-parallel.xml">
+ <!-- data-parallel expressions chapter -->
+ <!ENTITY glossary-chapter SYSTEM "glossary.xml">
+ <!-- glossary -->
+ <!ENTITY introductory-chapter SYSTEM "introduction.xml">
+ <!-- Doof2d introductory chapter -->
+ <!ENTITY template-chapter SYSTEM "template.xml">
+ <!-- Doof2d template programming chapter -->
+ <!ENTITY tutorial-chapter SYSTEM "tutorial.xml">
+ <!-- Doof2d tutorial programs chapter -->
+
+ <!-- External File Entities -->
+ <!-- Doof2d Programs -->
+ <!ENTITY doof2d-c-element SYSTEM "./programs/examples/Doof2d/Doof2d-C-element-annotated.cpp">
+ <!-- hand-coded Doof2d implementation -->
+ <!ENTITY doof2d-array-element SYSTEM "./programs/examples/Doof2d/Doof2d-Array-element-annotated.cpp">
+ <!-- Array element-wise Doof2d implementation -->
+ <!ENTITY doof2d-array-parallel SYSTEM "./programs/examples/Doof2d/Doof2d-Array-parallel-annotated.cpp">
+ <!-- Array data-parallel Doof2d implementation -->
+ <!ENTITY doof2d-array-stencil SYSTEM "./programs/examples/Doof2d/Doof2d-Array-stencil-annotated.cpp">
+ <!-- Array stencil Doof2d implementation -->
+ <!ENTITY doof2d-array-distributed SYSTEM "./programs/examples/Doof2d/Doof2d-Array-distributed-annotated.cpp">
+ <!-- distributed Array stencil Doof2d implementation -->
+ <!ENTITY doof2d-field-parallel SYSTEM "./programs/examples/Doof2d/Doof2d-Field-parallel-annotated.cpp">
+ <!-- Field data-parallel Doof2d implementation -->
+ <!ENTITY doof2d-field-distributed SYSTEM "./programs/examples/Doof2d/Doof2d-Field-distributed-annotated.cpp">
+ <!-- Field data-parallel distributed Doof2d implementation -->
+
+ <!-- Sequential Programs -->
+ <!ENTITY array-copy SYSTEM "./programs/examples/Sequential/array-copy-annotated.cpp">
+ <!-- Illustrate Array reference semantics. -->
+ <!ENTITY array-size SYSTEM "./programs/examples/Sequential/array-size-annotated.cpp">
+ <!-- Illustrate Array member functions. -->
+ <!ENTITY dynamicarray-example SYSTEM "./programs/examples/Sequential/dynamicarray-annotated.cpp">
+ <!-- Illustrate using DynamicArray class. -->
+ <!ENTITY initialize-finalize SYSTEM "./programs/examples/Sequential/initialize-finalize-annotated.cpp">
+ <!-- Illustrate initialize() and finalize(). -->
+
+ <!-- Template Programs -->
+ <!ENTITY pairs-untemplated SYSTEM "./programs/examples/Templates/pairs-untemplated-annotated.cpp">
+ <!-- Illustrate defining classes with pairs of values of the same type. -->
+ <!ENTITY pairs-templated SYSTEM "./programs/examples/Templates/pairs-templated-annotated.cpp">
+ <!-- Illustrate defining a template class with pairs of values of the same type. -->
+ ]>
+
+ <book>
+ <bookinfo>
+ <title>&pooma;</title>
+ <subtitle>A &cc; &toolkitcap; 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>2002</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>1.00</revnumber>
+ <date>2002 Jan 31</date>
+ <authorinitials>jdo</authorinitials>
+ <revremark>First publication.</revremark>
+ </revision>
+ </revhistory>
+ </bookinfo>
+
+ <!-- FINISH: May we have a short table of contents followed by a -->
+ <!-- complete table of contents? -->
+
+ <![%unfinished;[
+ <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 &bookcap;</title>
+
+ <para>FINISH: Write this section in a style similar to Lamport's
+ LaTeX section 1.2. FINISH: Fix the book title and the section
+ 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>
+ ]]> <!-- end unfinished -->
+
+ <![%temporary;[
+ <preface id="acknowledgements">
+ <title>Acknowledgements</title>
+ ]]> <!-- end temporary -->
+
+ <para>This &book; would not have been completed without the help
+ and encouragement of a lot of people and organizations. Los Alamos
+ National Laboratory funded the writing of this manual and the
+ development of the &poomatoolkit;. John Reynders conceived,
+ advocated, and headed &pooma; development in its early days, and
+ Scott Haney continued the leadership. Susan Atlas, Subhankar
+ Banerjee, Timothy Cleland, Julian Cummings, James Crotinger, David
+ Forslund, Salman Habib, Scott Haney, Paul Hinker, William Humphrey,
+ Steve Karmesin, Graham Mark, Jeffrey D. Oldham, Ji Qiang, John
+ Reynders, Robert Ryne, Stephen Smith, M. Srikant, Marydell
+ Tholburn, and Timothy Williams all helped develop &pooma;. Rod
+ Oldehoeft and Jeff Brown of Los Alamos National Laboratory
+ supported CodeSourcery's and Proximation's work, including the
+ development of this manual. John Hall, Don Marshall, Jean
+ Marshall, and the rest of the BLANCA team at Los Alamos worked
+ closely with the developers and provided valuable suggestions for
+ improvements.</para>
+
+ <para>I am grateful to James Crotinger, Mark Mitchell, and Stephen
+ Smith who answered my many questions during the writing of this
+ &book;.</para>
+
+ <!-- We cheat and abuse an epigraph here. -->
+ <epigraph>
+ <attribution>Jeffrey D. Oldham, 2002 January</attribution>
+ <para></para>
+ </epigraph>
+
+ <![%temporary;[
+ </preface>
+ ]]> <!-- end temporary -->
+
+ <![%unfinished;[
+ </section>
+
+ </preface>
+ ]]> <!-- end unfinished -->
+
+
+ <![%unfinished;[
+ <part id="programming">
+ <title>Programming with &pooma;</title>
+
+ <!-- FIXME: Add a partintro to the part above? -->
+ ]]> <!-- end unfinished -->
+
+ &introductory-chapter;
+
+ &template-chapter;
+
+ &tutorial-chapter;
+
+ &concepts-chapter;
+
+ &arrays-chapter;
+
+
+ <chapter id="engines">
+ <title>Engines</title>
+
+ <para>Each container has one or more &engine;s to store or compute
+ its values. As we mentioned in <xref
+ linkend="arrays-arrays_declarations"></xref>, a container's role is
+ high-level, supporting access to groups of values, and an engine's
+ role is low-level, storing or computing values and supporting
+ access to individual values. This separation permits optimizing
+ space and computation requirements.</para>
+
+ <para>We begin this chapter by introducing the concept of an engine
+ and how it is used. Then, we describe the various &engine;s that
+ &pooma; provides, separating them into engines that store values
+ and engines that compute values.
+ <![%unfinished;[
+ Finally, we describe how the
+ &engine;s are implemented, using tags to differentiate engines and
+ reference-counted pointers to their underlying data.
+ ]]> <!-- end unfinished -->
+ </para>
+
+
+ <section id="engines-concept">
+ <title>The Concept</title>
+
+ <para>An engine performs the low-level value storage, computation,
+ and element-wise access for a container. An engine has a domain
+ and accessor functions returning individual elements. The &pooma;
+ &engine; class and its specializations implement the engine
+ concept. Given an index within the domain, an &engine;'s
+ <literal>operator()</literal> function returns the
+ associated value, which can be used or changed. Its
+ <literal>read</literal> member function returns the same
+ value but permitting only use, not modification. The acceptable
+ indices are determined by each &engine;. Most accept indices
+ specified using ∫ and <type>Loc<&dim;></type>
+ parameters, but an &engine; might accept string or floating-point
+ parameters. An &engine;'s layout specifies maps its domain
+ indices to the processors and memory used to store and compute the
+ associated values.</para>
+
+ <para>Since an engine's main role is to return the individual
+ values associated with specific domain indices, any implementation
+ performing this task is an engine. &pooma; &engine;s fall into
+ three categories:
+ <itemizedlist>
+ <listitem>
+ <para>&engine;s that store values.</para>
+ </listitem>
+ <listitem>
+ <para>&engine;s that compute their values using other &engine;s'
+ values.</para>
+ </listitem>
+ <listitem>
+ <para>&engine;s that support distributed computation.</para>
+ </listitem>
+ </itemizedlist>
+ For example, the &brick; &engine; explicitly stores all its
+ values, while the &compressiblebrick; engine adds the feature of
+ reducing its storage requirements if all these values are
+ identical. A <type>UserFunction</type> &engine; yields values by
+ applying a <glossterm linkend="glossary-function_object">function
+ object</glossterm> to each value returned by another &engine;. A
+ <type>CompFwd</type> &engine; projects components from another
+ &engine;. For example, <type>CompFwd</type> will use the second
+ components of each &vector; in an &array; to form its own &array;.
+ Since each container has at least one &engine;, we can also
+ describe the latter category as containers that compute their
+ values using other containers' values. A &multipatch; &engine;
+ distributes its domain among various processors and memory spaces,
+ each responsible for computing values associated with a portion,
+ or patch, of the domain. The &remote; &engine; also supports
+ distributed computation.</para>
+
+ <para>Just as multiple containers can use the same engine,
+ multiple &engine;s can use the same underlying data. As we
+ mentioned in <xref linkend="arrays-arrays_use"></xref>, &engine;s
+ have <glossterm linkend="glossary-reference_semantics">reference
+ semantics</glossterm>. A copy of an &engine; has a
+ reference-counted pointer to the &engine;'s data (if any exists).
+ Thus, copying an &engine; or a container requires little execution
+ time. If an &engine; has the same data as another &engine; but it
+ needs its own data to modify, the
+ <literal>makeOwnCopy</literal> member function creates such
+ a copy.</para>
+
+ <para>&engine;s are rarely explicitly declared. Instead a
+ container is declared using an &engine; tag, and the container
+ creates the specified &engine; to deal with its values. For
+ example, a &brick; &engine; is explicitly declared as
+ <type>Engine<&dim;,T,Brick></type>, but they are more
+ frequently created by containers, e.g.,
+ <type>Array<&dim;,T,Brick></type>. An &engine;'s first two
+ template parameters specify the domain's dimensionality and the
+ value type, as described in <xref
+ linkend="arrays-arrays_declarations"></xref>. Unlike container
+ declarations, the third template parameter, the &engine; tag,
+ specifies which &engine; specialization to use. For example, the
+ &brick; &engine; tag indicates a &brick; &engine; should be used.
+ Some &engine;s, such as <type>CompFwd</type>, are rarely declared
+ even using &engine; tags. Instead the &array;'s
+ <literal>comp</literal> and
+ <literal>readComp</literal> member functions return views of
+ containers using <type>CompFwd</type> &engine;s.</para>
+ </section>
+
+
+ <section id="engines-types">
+ <title>Types of &engine;s</title>
+
+ <para>In this section, we describe the different types of
+ &engine;s and illustrate their creation, when appropriate. First,
+ we describe &engine;s that explicitly store values and then
+ &engine;s that compute values. See <xref
+ linkend="engines-types-table"></xref>.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0" id="engines-types-table">
+ <title>Types of &engine;s</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>&engine; tag</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row rowsep="1">
+ <entry>&engine;s That Store</entry>
+ </row>
+ <row>
+ <entry>&brick;</entry>
+ <entry>explicitly stores all values; similar to &c; arrays.</entry>
+ </row>
+ <row>
+ <entry>&compressiblebrick;</entry>
+ <entry>stores all values, reducing storage requirements when
+ all values are identical.</entry>
+ </row>
+ <row>
+ <entry>&dynamic;</entry>
+ <entry>is a one-dimensional &brick; with dynamically
+ resizable domain. This should be used with &dynamicarray;,
+ not &array;.</entry>
+ </row>
+ <row rowsep="1">
+ <entry>&engine;s That Compute</entry>
+ </row>
+ <row>
+ <entry><type>CompFwd</type></entry>
+ <entry>extracts specified components of an engine's vectors,
+ tensors, arrays, etc.; usually created using the
+ <literal>comp</literal> container function.</entry>
+ </row>
+ <row>
+ <entry><type>ConstantFunction</type></entry>
+ <entry>makes a scalar value behave like a container.</entry>
+ </row>
+ <row>
+ <entry><type>IndexFunction<FunctionObject></type></entry>
+ <entry>makes the <type>FunctionObject</type>'s function of
+ indices behave like a container.</entry>
+ </row>
+ <row>
+ <entry><type>ExpressionTag<Expr></type></entry>
+ <entry>evaluates an expression tree; usually created by
+ data-parallel expressions.</entry>
+ </row>
+ <row>
+ <entry><type>Stencil<Function, Expression></type></entry>
+ <entry>applies a stencil computation (<type>Function</type>)
+ to its input (<type>Expression</type>) which is usually a
+ container; usually created by applying a <type>Stencil</type>
+ object to a container. A stencil computation can use
+ multiple neighboring input values.</entry>
+ </row>
+ <row>
+ <entry><type>UserFunctionEngine<Function,
+ Expression></type></entry>
+ <entry>applies the given function (or <glossterm
+ linkend="glossary-function_object">function
+ object</glossterm>) to its input (<type>Expression</type>)
+ which is usually a container; usually created by applying a
+ <type>UserFunction</type> object to a container. The
+ function implements a one-to-one mapping from its input to
+ values.</entry>
+ </row>
+ <row rowsep="1">
+ <entry>&engine;s for Distributed Computation</entry>
+ </row>
+ <row>
+ <entry><type>MultiPatch<LayoutTag,EngineTag></type></entry>
+ <entry>runs a separate <type>EngineTag</type> &engine; on
+ each context (patch) specified by the given layout. This is
+ the usual &engine; for distributed computation.</entry>
+ </row>
+ <row>
+ <entry><type>Remote<EngineTag></type></entry>
+ <entry>runs the &engine; specified by <type>EngineTag</type>
+ on a specified context.</entry>
+ </row>
+ <row>
+ <entry><type>Remote<Dynamic></type></entry>
+ <entry>runs a <type>Dynamic</type> one-dimensional, resizable
+ &engine; on a specified context. This is a specialization of
+ <type>Remote</type>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!-- FIXME: Place in firstterm. -->
+ <para><glossterm linkend="glossary-brick">&brick;
+ &engine;s</glossterm> explicitly store values just like &c;
+ arrays. &compressiblebrick; &engine;s optimize their storage
+ requirements when all values are identical. Many &array;s use one
+ of these two &engine;s. &brick;s are the default &engine;s for
+ &array; and &field; containers because they explicitly store each
+ value. This explicit storage can require a large amount of space,
+ particularly if all these values are the same. If all a
+ compressible brick &engine;'s values are identical, the &engine;
+ stores that one value rather than many, many copies of the same
+ value. These engines can both save time as well as space.
+ Initializing a compressible engine requires setting only one
+ value, not every value. Using less storage space may also permit
+ more useful values to be stored in cache, improving cache
+ performance. Reading a value in a compressed &engine; using the
+ <literal>read</literal> member function is as fast as
+ reading a value in a &brick; &engine;, but writing a value always
+ requires executing an additional <literal>if</literal>
+ conditional. Thus, if an &engine; infrequently has multiple
+ different values during its life time, a &compressiblebrick;
+ &engine; may be faster than a &brick; &engine;. If an &engine; is
+ created and its values are mostly read, not written, a
+ &compressiblebrick; &engine; may also be faster. Otherwise, a
+ &brick; &engine; may be preferable. Timing the same program using
+ the two different &engine; types will reveal which is faster for a
+ particular situation. In distributed computing, many &engine;s
+ may have few nonzero values so &compressiblebrick; &engine;s may
+ be preferable. For distributed computing, a container's domain is
+ partitioned into regions each computed by a separate processor and
+ &engine;. If the computation is concentrated in sections of the
+ domain, many &engine;s may have few, if any, nonzero values.
+ Thus, &compressiblebrick; &engine;s may be preferable for
+ distributed computing.</para>
+
+ <para>Both &brick; and &compressiblebrick; &engine;s have
+ <literal>read</literal> and
+ <literal>operator()</literal> member functions taking ∫
+ and &loc; parameters. The parameters should match the &array;'s
+ dimensionality. For example, if &array; <varname>a</varname> has
+ dimensionality 3, <function>a.read(int, int, int)</function>
+ and <function>a(int, int, int)</function> should be used. The
+ former returns a value that cannot be modified, while the latter
+ can be changed. Using the <literal>read</literal> member
+ function can lead to faster code. Alternatively, an index can be
+ specified using a &loc;. For example,
+ <literal>a.read(Loc<3>(1,-2,5))</literal> and
+ <literal>a(Loc<3>(1,-2,5))</literal> are equivalent to
+ <literal>a.read(1,-2,5))</literal> and
+ <literal>a(1,-2,5)</literal>.</para>
+
+ <para>The &dynamic; &engine; supports changing domain sizes while
+ a program is executing. It is basically a one-dimensional
+ &brick;, explicitly storing values, but permitting the number and
+ order of stored values to change. Thus, it supports the same
+ interface as &brick; except that all member functions are
+ restricted to their one-dimensional versions. For example,
+ <literal>read</literal> and
+ <literal>operator()</literal> take <type>Loc<1></type>
+ or one ∫ parameter. In addition, the one-dimensional domain
+ can be dynamically resized using <literal>create</literal>
+ and <literal>destroy</literal>.
+ <![%unfinished;[
+ ; see .
+
+ HERE Dynamic. How does one change the domain size? What is the model?
+ ]]> <!-- end unfinished -->
+ </para>
+
+ <![%unfinished;[
+ <!-- HERE: Array cannot forward domain size changes to underlying Dynamic Engine. -->
+
+ <para>Types of &engine;s:
+ Brick - explicitly store values
+ CompressibleBrick - explicitly store values but store only one if all the same
+ ConstantFunction - convert scalar into an array
+ DynamicEngine - contiguous, local, resizable, 1D block
+ ExpressionEngine - evaluate PETE expression
+ CompFwd - array formed by extracted components from array
+ ForwardEngine
+ tut-02.html: use .comp() or .readComp()
+ IndexFunctionEngine - convert function of indices into an array
+ IndirectionEngine - incomplete
+ MultiPatch - ?How do I describe this?
+ RemoteDynamic - run a Dynamic engine on a specified context
+ Remote - permit computations on specified context
+ should discuss with MultiPatch
+ Stencil - apply a stencil to an array, returning a new Array with the results
+ UserFunction - Array = apply function to an Array
+ </para>
+
+ <para>How do I organize these engines into understandable
+ categories?
+
+ storage
+ Brick
+ CompressibleBrick
+ Dynamic - resizable 1D block
+ RemoteDynamic
+ MultiPatch - ?WHAT?
+ Remote
+
+ computation
+ CompFwd: project(array)->array
+ .comp() and .readComp()
+ view, not a copy
+ ConstantFunction: scalar(array)->array
+ explicitly use
+ IndexFunctionEngine: function(indices)->array
+ explicitly use
+ ExpressionEngine: expression(array)->array
+ created by data-parallel expression
+ Stencil: stencil(array)->array
+ implicitly used
+ explicitly use Stencil<...> type
+ UserFunction: function(array)->array
+ explicitly use
+ </para>
+
+ <para>
+ Element_t read(Loc<&dim;>)
+ ElementRef_t operator()(Loc<&dim;>)
+ Element_t read(int+)
+ ElementRef_t operator()(int+)
+ </para>
+
+ <para>Explain the concept of an engine. How does an engine
+ interact with a container or an &array;? Explain the different
+ types of engines likely to be used by &pooma; programmers and how
+ to declare containers using them. Should I list the other engines
+ that are automatically created?</para>
+ ]]> <!-- end unfinished -->
+
+ </section>
+ </chapter>
+
+
+ &data-parallel-chapter;
+
+
+ <chapter id="views">
+ <title>Container Views</title>
+
+ <indexterm zone="views">
+ <primary>container</primary>
+ <secondary>view</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>view of a container</primary>
+ <see>container, view.</see>
+ </indexterm>
+
+ <![%temporary;[
+
+ <para>A <glossterm linkend="glossary-view"><firstterm>view of a
+ container</firstterm></glossterm> is a container accessing a subset
+ of &container;'s domain and values. The subset can include all of
+ the container's domain. A <quote>view</quote> is so named because
+ it is a different way to access, or view, another container's
+ values. Both the container and its view share the same underlying
+ engine so changing values in one also changes them in the
+ other.</para>
+
+ <para>A view is created by following a container's name by
+ parentheses containing a domain. For example, consider this code
+ extracted from <xref
+ linkend="tutorial-array_parallel-doof2d"></xref> in <xref
+ linkend="tutorial-array_data_parallel"></xref>.
+ <programlisting>
+ Interval<1> N(0, n-1);
+ Interval<2> vertDomain(N, N);
+ Interval<1> I(1,n-2);
+ Interval<1> J(1,n-2);
+ Array<2, double, Brick> a(vertDomain);
+ Array<2, double, Brick> b(vertDomain);
+ a(I,J) = (1.0/9.0) *
+ (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) +
+ b(I-1,J+1) + b(I-1,J ) + b(I-1,J-1));
+ </programlisting> The last statement creates ten views. For example,
+
+ <literal>a(I,J)</literal> creates a view of
+ <varname>a</varname> using the smaller domain specified by
+ <varname>I</varname> and <varname>J</varname>. This omits the
+ outermost rows of columns of <varname>a</varname>. The views
+ of <varname>b</varname> illustrate the use of views in
+ data-parallel statements. <literal>b(I-1,J-1)</literal> has a
+ subset shifted up one row and left one column compared with
+ <literal>b(I,J)</literal>.</para>
+ ]]> <!-- end temporary -->
+ <![%unfinished;[
+ <para>Be sure to list the various arithmetic operations on domains
+ that can be used. This was deferred from the &array; and domain
+ chapter. Explain &array;'s <function>comp</function> function.</para>
+
+ <!-- FIXME: Finish this chapter. -->
+ ]]> <!-- end unfinished -->
+ </chapter>
+
+
+ <![%unfinished;[
+ <chapter id="sequential">
+ <title>Writing Sequential Programs</title>
+
+ <para>FIXME: Explain the chapter's purpose.</para>
+
+ <para>FIXME: Explain the format of each section.</para>
+
+ <para>FIXME: Explain the order of the sections.</para>
+
+ <para>Proposed order. Basically follow the order in the proposed
+ reference section.
+ <orderedlist>
+ <listitem><para>starting, stopping</para></listitem>
+ <listitem><para>&array;</para></listitem>
+ <listitem><para>&dynamicarray;</para></listitem>
+ <listitem><para>&field;</para></listitem>
+ <listitem><para>&vector;</para></listitem>
+ <listitem><para>&matrix;</para></listitem>
+ <listitem><para>&tensor;</para></listitem>
+ <listitem><para>&engine;</para></listitem>
+ <listitem><para>domain</para></listitem>
+ <listitem><para>correctness, e.g., <function>PAssert</function></para></listitem>
+ <listitem><para>&pooma; command-line options</para></listitem>
+ </orderedlist>
+ Include views of containers in the appropriate sections.</para>
+
+ <para><emphasis>&c;: A Reference Manual</emphasis> uses this
+ structure for &c; libraries:
+ <orderedlist>
+ <listitem>
+ <para>function declarations, separated by rules from rest of text</para>
+ </listitem>
+ <listitem>
+ <para>text explanation</para>
+ </listitem>
+ <listitem>
+ <para>table of structure members if appropriate</para>
+ </listitem>
+ <listitem>
+ <para>example</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para><emphasis>STL Tutorial and Reference Guide</emphasis>, second
+ edition, uses this structure for STL functions:
+ <orderedlist>
+ <listitem>
+ <para>text description with declaration mixed in</para>
+ </listitem>
+ <listitem>
+ <para>example program mixed into text. It is an entire program,
+ not a program fragment.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>A tutorial chapter for containers has
+ <orderedlist>
+ <listitem>
+ <para>explanation of template types</para>
+ </listitem>
+ <listitem>
+ <para>bulleted list of container types</para>
+ </listitem>
+ <listitem>
+ <para>example constructors</para>
+ </listitem>
+ <listitem>
+ <para>example programs</para>
+ </listitem>
+ <listitem>
+ <para>member and related functions with example programs</para>
+ </listitem>
+ <listitem>
+ <para>list of accessors and relation functions</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>The reference chapter for containers has
+ <orderedlist>
+ <listitem>
+ <para>a section listing common members and types for all containers</para>
+ </listitem>
+ <listitem>
+ <para>a section listing common member functions for all containers</para>
+ </listitem>
+ <listitem>
+ <para>requirements for various container specialties</para>
+ </listitem>
+ </orderedlist>
+ The section describing <type>vector</type>s contains
+ <orderedlist>
+ <listitem>
+ <para>files (header files)</para>
+ </listitem>
+ <listitem>
+ <para>class declaration</para>
+ </listitem>
+ <listitem>
+ <para>description</para>
+ </listitem>
+ <listitem>
+ <para>type definitions</para>
+ </listitem>
+ <listitem>
+ <para>constructors, destructors, and related functions</para>
+ </listitem>
+ <listitem>
+ <para>comparison operators</para>
+ </listitem>
+ <listitem>
+ <para>element access member functions</para>
+ </listitem>
+ <listitem>
+ <para>insert and erase member functions</para>
+ </listitem>
+ <listitem>
+ <para>notes</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>Josuttis's <emphasis>The &cc; Standard Library: A Tutorial
+ and Reference</emphasis> uses this structure for its STL container
+ chapter:
+ <orderedlist>
+ <listitem>
+ <para>short introduction</para>
+ </listitem>
+ <listitem>
+ <para>common container abilities</para>
+ </listitem>
+ <listitem>
+ <para>common container operations (with table)</para>
+ </listitem>
+ <listitem>
+ <para>vector abilities</para>
+ </listitem>
+ <listitem>
+ <para>vector operations:
+ <orderedlist>
+ <listitem>
+ <para>create, copy, and destroy operations (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>non-modifying operations (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>assignments (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>element access (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>iterator functions (mostly table)</para>
+ </listitem>
+ <listitem>
+ <para>inserting and removing elements (mostly table)</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>using vectors as ordinary arrays</para>
+ </listitem>
+ <listitem>
+ <para>exception handling</para>
+ </listitem>
+ <listitem>
+ <para>example program</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <section id="sequential-begin_end">
+ <title>Beginning and Ending &pooma; Programs</title>
+
+ <para>Every &pooma; program must begin with a call to
+ <function>initialize</function> and end with a call to
+ <function>finalize</function>. These functions respectively
+ prepare and shut down &pooma;'s run-time structures.</para>
+
+ <bridgehead id="sequential-begin_end-files" renderas="sect2">Files</bridgehead>
+
+ <programlisting>
+ #include "Pooma/Pooma.h" // or "Pooma/Arrays.h" or "Pooma/Fields.h" or ...
+ </programlisting>
+
+ <bridgehead id="sequential-begin_end-declarations" renderas="sect2">Declarations</bridgehead>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>Pooma::initialize</function></funcdef>
+ <paramdef>
+ <parameter class="function">int &argc,</parameter>
+ <parameter class="function">char ** &argv,</parameter>
+ <parameter class="function">bool initRTS = true,</parameter>
+ <parameter class="function">bool getCLArgsArch = true,</parameter>
+ <parameter class="function">bool initArch = true</parameter>
+ </paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::initialize</function></funcdef>
+ <paramdef>
+ <parameter class="function">Pooma::Options &opts,</parameter>
+ <parameter class="function">bool initRTS = true,</parameter>
+ <parameter class="function">bool initArch = true</parameter>
+ </paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::finalize</function></funcdef>
+ <void></void>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::finalize</function></funcdef>
+ <paramdef>
+ <parameter class="function">bool quitRTS,</parameter>
+ <parameter class="function">bool quitArch</parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <bridgehead id="sequential-begin_end-description" renderas="sect2">Description</bridgehead>
+
+ <para>Before its use, the &poomatoolkit; must be initialized by a
+ call to <function>initialize</function>. This usually occurs in
+ the <function>main</function> function. The first form removes
+ and processes any &pooma;-specific arguments from the
+ command-line arguments <varname>argv</varname> and
+ <varname>argc</varname>. <xref
+ linkend="sequential-options"></xref> describes these options.
+ The third, fourth, and fifth arguments all have a default value
+ of &true;. If <parameter class="function">initRTS</parameter> is
+ &true;, the run-time system is initialized. E.g., the contexts
+ are prepared for use. If <parameter
+ class="function">getCLArgsArch</parameter> is &true,
+ architecture-specific command-line arguments are removed from
+ <varname>argv</varname> and <varname>argc</varname>.
+ Architecture-specific initialization occurs if <parameter
+ class="function">getCLArgsArch</parameter> is &true;. An <link
+ linkend="glossary-architecture">architecture</link> is specified
+ by a hardware interface, e.g., processor type, but frequently is
+ also associated with an operating system or compiler. For
+ example, Metrowerks for the Macintosh has an
+ architecture-specific initialization. The function always
+ returns &true;.</para>
+
+ <para><function>initialize</function>'s alternative form
+ assumes the &pooma;-specific and architecture-specific
+ command-line arguments have already been removed from
+ <varname>argv</varname> and <varname>argc</varname> and stored in
+ <parameter class="function">opts</parameter>. Its other two
+ parameters have the same meaning, and the two functions'
+ semantics are otherwise the same.</para>
+
+ <para>After its use, the &poomatoolkit; should be shut down using
+ a call to <function>finalize</function>. This usually occurs in
+ the <function>main</function> function. The former, and more
+ frequently used, form first prints any statistics and turns off
+ all default &pooma; streams. Then it shuts down the run-time
+ system if it was previously initialized and then shuts down
+ architecture-specific objects if they were previously
+ initialized. The latter form gives provides explicit control
+ whether the run-time system (<parameter
+ class="function">quitRTS</parameter>) and architecture-specific
+ objects (<parameter class="function">quitArch</parameter>) are
+ shut down. Both functions always returns &true;.</para>
+
+ <para>Including almost any &pooma; header file, rather than just
+ <filename class="headerfile">Pooma/Pooma.h</filename> suffices
+ since most other &pooma; header files include it.</para>
+
+ <bridgehead id="sequential-begin_end-example" renderas="sect2">Example Program</bridgehead>
+
+ <para>Since every &pooma; program must call
+ <function>initialize</function> and
+ <function>finalize</function>, the simplest &pooma; program also
+ must call them. This program also illustrates their usual
+ use.</para>
+
+ &initialize-finalize;
+
+ </section><!-- end sequential-begin_end -->
+
+
+ <section id="sequential-global">
+ <title>Global Variables</title>
+
+ <para>&pooma; makes a few global variables available after
+ initialization.</para>
+
+ <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ orient="port" pgwide="0">
+ <title>&pooma; Global Variables</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>variable</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry>&inform; <varname>pinfo</varname></entry>
+ <entry>output stream used to print informative messages to the
+ user while the program executes. The stream accepts a
+ superset of standard output operations.</entry>
+ </row>
+ <row>
+ <entry>&inform; <varname>pwarn</varname></entry>
+ <entry>FIXME: output stream used to print informative messages to the
+ user while the program executes. The stream accepts a
+ superset of standard output operations.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section id="sequential-options">
+ <title>&pooma; Command-line Options</title>
+
+ <para>Every &pooma; program accepts a set of &pooma;-specific
+ command-line options to set values at run-time.</para>
+
+ <para>QUESTION: Should I defer documenting &options; to the
+ reference manual, instead just listing commonly used options in
+ the previous section?
+
+ UNFINISHED</para>
+
+ <section id="sequential-options-list">
+ <title>Options Summary</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter class="option">&dashdash;pooma-info</parameter></term>
+ <listitem>
+ <para>enable use of the <varname>pinfo</varname>, used to
+ print informative messages to the user while the program
+ executes.</para>
+ </listitem>
+ </varlistentry>
+ <!-- UNFINISHED -->
+ </variablelist>
+
+ <para>FIXME: Be sure to list default values.</para>
+ <!-- FIXME: need to describe the pinfo, pwarn, and perr streams somewhere. To do so requires describing informs.-->
+ <!-- FIXME: Which streams are buffered and which are not? -->
+
+ </section>
+
+ </section><!-- end sequential-options -->
+
+ <section>
+ <title>TMP: Place these somewhere.</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.
+ <![%unfinished;[
+ See <xref
+ linkend="debugging_profiling-missing_blockandevaluate"></xref> for
+ instructions how to diagnose and eliminate these race
+ conditions.
+ ]]> <!-- end unfinished -->
+ </para>
+
+ <para>Where talk about various &pooma; streams?</para>
+
+ <para>UNFINISHED</para>
+
+ </section>
+
+
+ <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>
+ <title>Miscellaneous</title>
+
+ <para>Section 3, "Domains and Views," of
+ <filename>papers/iscope98.pdf</filename> describes four types of
+ domains.</para>
+
+ <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; multidimensional Array concept is similar to
+ the &fortran; 90 array facility, but extends it in several
+ ways. Both &pooma; and &fortran; arrays can have up to seven
+ dimensions, and can serve as containers for arbitrary
+ 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 &array;s 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
+ <literal><varname>A</varname>*<varname>B</varname>+<varname>C</varname></literal>
+ 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>&multipatch; 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>
+ </chapter>
+ ]]> <!-- end unfinished -->
+
+
+ <![%unfinished;[
+ <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>
+ ]]> <!-- end unfinished -->
+
+
+ <![%unfinished;[
+ <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
+ <literal>&dashdash;pooma-blocking-expressions</literal> 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
+ <literal>&dashdash;pooma-blocking-expressions</literal> 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 <literal>Pooma::blockingExpressions(true)</literal>
+ and <literal>Pooma::blockingExpressions(false)</literal>,
+ but do not use the
+ <literal>&dashdash;pooma-blocking-expressions</literal> 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>
+ ]]> <!-- end unfinished -->
+
+
+ <![%unfinished;[
+ </part>
+ ]]> <!-- end unfinished -->
+
+ <![%unfinished;[
+ <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, 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 valign="top">
+ <row>
+ <entry><varname>Dim</varname></entry>
+ <entry><para>dimension</para></entry>
+ </row>
+ <row>
+ <entry><type>T</type></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 valign="top">
+ <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 valign="top">
+ <row>
+ <entry>
+ <constructorsynopsis>
+ <literal>Array</literal>
+ <void></void>
+ </constructorsynopsis>
+ </entry>
+ <entry><para>Creates an array that will be resized
+ later.</para></entry>
+ </row>
+ <row>
+ <entry>
+ <constructorsynopsis>
+ <literal>Array</literal>
+ <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>
+ <literal>Array</literal>
+ <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 valign="top">
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>Element_t</type> <literal>read</literal>
+ <void></void>
+ </methodsynopsis>
+ </entry>
+ <entry><para>unknown: See line 1839.</para></entry>
+ </row>
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>Element_t</type> <literal>read</literal>
+ <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> <literal>operator()</literal>
+ <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 <literal>read(const
+ Sub1& s1, const Sub2& s2)</literal>? </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
+ <literal>comp</literal> 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,
+ <literal>a.comp(1)</literal> 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 valign="top">
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>UNKNOWN compute this</type> <literal>comp</literal>
+ <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 <literal>comp</literal>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 valign="top">
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>int</type> <literal>first</literal>
+ <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
+ <literal>engine</literal>.</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 valign="top">
+ <row>
+ <entry>
+ <methodsynopsis>
+ <type>void</type> <literal>makeOwnCopy</literal>
+ <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 <literal>private</literal>data consists of
+ an engine, and it has no <literal>private</literal>
+ 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 valign="top">
+ <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
+ <literal>protected</literal> or
+ <literal>private</literal> 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 <literal>a + b</literal>
+ 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 valign="top">
+ <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>
+
+ <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>
+
+ <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
+ <literal>all</literal>.</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
+ <literal>operator[]</literal>,
+ <literal>subField</literal>, …,
+ <literal>material</literal>.</para>
+ </section>
+
+
+ <section id="fields_ref-field-relations">
+ <title>Supporting Relations</title>
+
+ <para>ADD: a table with the member functions including
+ <literal>addRelation</literal>,
+ <literal>removeRelations</literal>,
+ <literal>applyRelations</literal>, and
+ <literal>setDirty</literal>.</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
+ <literal>makeOwnCopy</literal>.</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 <literal>f[i]</literal>. 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 valign="top">
+ <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 valign="top">
+ <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 <literal>read</literal> and
+ <literal>operator()</literal>.</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
+ <literal>makeOwnCopy</literal>.</para>
+
+ <para>QUESTION: What are <literal>dataObject</literal>,
+ <literal>isShared</literal>, 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.,
+ <literal>offset</literal>.</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
+ <literal>Options::usage</literal>.</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.</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>
+
+
+ <chapter id="needed_reference_items_ref">
+ <title>TMP: Items to Discuss in Reference Manual</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Discuss &options; and related material. Add developer
+ command-line options listed in <filename
+ class="libraryfile">Utilities/Options.cmpl.cpp</filename> and also
+ possibly <parameter class="option">&dashdash;pooma-threads
+ <replaceable>n</replaceable></parameter>.</para>
+ </listitem>
+ </itemizedlist>
+ </chapter>
+ </part>
+ ]]> <!-- end unfinished -->
+
+
+ <![%unfinished;[
+ <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>
+ ]]> <!-- end unfinished -->
+
+
+ <appendix id="installation">
+ <title>Obtaining and Installing &pooma;</title>
+
+ <![%temporary;[
+ <para>In <xref linkend="tutorial-installation"></xref>, we described
+ how to install &pooma;. In the following section, we describe how
+ to install &pooma; to support distributed computation.</para>
+ ]]> <!-- end temporary -->
+
+ <![%unfinished;[
+ <para>ADD: Write this section, including extensive instructions
+ for Unix-like, MS Windows, and MacOS. List the configuration options.
+ Be sure to describe configuring for parallel execution.</para>
+ ]]> <!-- end unfinished -->
+
+ <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 the following
+ section, we first describe how to install &mm;. Read it 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 <ulink
+ url="http://www.engelschall.com/sw/mm/">http://www.engelschall.com/sw/mm/</ulink>,
+ is available at no cost and has been successfully tested on a
+ variety of Unix-like 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
+ (&poomadownloadpage;) 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>. Change directories 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
+ <programlisting>
+ ./configure &dashdash;prefix=${HOME}/pooma/mm-1.1.3
+ </programlisting></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>
+ environment variable to the desired 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
+ <![%unfinished;[
+ (FIXME: xref linkend="mpi99", <ulink
+ url="http://www-unix.mcs.anl.gov/mpi/"></ulink>)
+ ]]> <!-- end unfinished -->
+ or the &mm; Shared Memory Library. &mpi; works on a wide variety
+ of platforms and has achieved widespread usage. &mm; works under
+ Unix-like operating systems on any computer with shared memory. Both libraries are
+ available at no cost. 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
+ (&poomadownloadpage;) available off the &pooma; home page
+ (&poomahomepage;).</para>
+ </listitem>
+ <listitem>
+ <para>Extract the source code using <command>tar xzvf
+ cheetah-1.0.tgz</command>. Change directories 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
+ <literal>"/home/oldham/pooma/mm-1.1.3"</literal>.</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
+ <programlisting>
+ ./configure &dashdash;arch LINUXGCC &dashdash;shmem &dashdash;nompi
+ &dashdash;noex &dashdash;static &dashdash;prefix ${HOME}/pooma/cheetah-1.0
+ &dashdash;opt
+ </programlisting> 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,
+ <programlisting>
+ declare -x CHEETAHDIR=${HOME}/pooma/cheetah-1.0
+ </programlisting> specifies the
+ installation directory used in the previous section. If using
+ the <application>csh</application> shell, use <command>setenv
+ CHEETAHDIR ${HOME}/pooma/cheetah-1.0</command>.</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>
+
+
+ <![%unfinished;[
+ <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>Section 5, "Performance," of
+ <filename>papers/iscope98.pdf</filename> motivates and explains
+ stencils.</para>
+ </listitem>
+
+ <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>
+ ]]> <!-- end unfinished -->
+
+
+ &bibliography-chapter;
+
+ &glossary-chapter;
+
+ <!-- Index -->
+
+ <![%unfinished;[
+ &genindex.sgm;
+ ]]> <!-- end unfinished -->
+
+ </book>
Index: print.dsl
===================================================================
RCS file: print.dsl
diff -N print.dsl
*** /dev/null Fri Mar 23 21:37:44 2001
--- print.dsl Thu Jan 31 14:10:44 2002
***************
*** 0 ****
--- 1,320 ----
+ <!-- DSSSL stylesheet for generating TeX from DocBook documents. -->
+
+ <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+ <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
+ ]>
+
+ <!-- This DSSSL stylesheet formats the POOMA manual, written in
+ DocBook, as converted to PostScript and PDF. When producing
+ PostScript, be sure to define 'use-eps' on the jade command line:
+ jade ... -V use-eps
+ This ensures EPS graphics files can be used.
+
+ Jeffrey D. Oldham
+ 2002 January 29 -->
+
+ <style-sheet>
+ <style-specification use="docbook">
+ <style-specification-body>
+
+ ;; $Id: plain.dsl,v 1.2 2000/09/28 12:50:20 ndw Exp $
+ ;;
+ ;; This file is part of the Modular DocBook Stylesheet distribution.
+ ;; See ../README or http://www.berkshire.net/~norm/dsssl/
+ ;;
+ ;; Example of a customization layer on top of the modular docbook style
+ ;; sheet. Definitions inserted in this file take precedence over
+ ;; definitions in the 'use'd stylesheet(s).
+
+ ;; Number chapters and sections.
+ (define %chapter-autolabel% #t)
+ (define %section-autolabel% #t)
+
+ ;; Use a readable font size.
+ (define %visual-acuity% "presbyopic")
+ ;; Prevent verbatim text from being displayed at a different size.
+ (define %verbatim-size-factor% 1.1)
+
+ ;; Indent program listings four spaces
+ (define %indent-programlisting-lines% " ")
+
+ ;; Support two-sided printing.
+ (define %two-side% #t) ;; does not have any effect
+
+ ;; Produce justified text and hyphenation.
+ (define %default-quadding% 'justify)
+ (define %hyphenation% #t)
+
+ ;; Produce footnotes at the bottom of the page, not section end.
+ (define bop-footnotes #t)
+
+ ;; Use EPS for PS generation and PNG for PDF generation.
+ ;; Use '-V use-eps' to use EPS files.
+ (define use-eps #f)
+ (define %graphic-extensions%
+ (if use-eps
+ '("eps" "epsf" "gif" "tif" "tiff" "jpg" "jpeg" "png")
+ '("gif" "tif" "tiff" "jpg" "jpeg" "png")))
+ ; modified from stylesheets/docbook/print/db31.dsl
+ (define preferred-mediaobject-notations
+ (if use-eps
+ (list "EPS" "PS" "JPG" "JPEG" "PNG" "linespecific")
+ (list "JPG" "JPEG" "PNG" "linespecific")))
+ (define preferred-mediaobject-extensions
+ (if use-eps
+ (list "eps" "ps" "jpg" "jpeg" "png")
+ (list "jpg" "jpeg" "png")))
+
+ ;; Layout variable lists in a reasonable way.
+ ;; does not work well (define %may-format-variablelist-as-table% #t)
+ ;; (define %always-format-variablelist-as-table #t) ;; does not work at all
+
+ ;; Float tables and examples.
+ (define formal-object-float #f)
+ ;(define %example-rules% #t) Uncomment if use floats.
+ ;(define %figure-rules% %example-rules%)
+ ;(define %table-rules% %example-rules%)
+
+ ;; Fix space breaking for xref text. I tried modifying
+ ;; en-xref-strings from docbook/common/dbl1en.dsl, but I could not get
+ ;; it to work because the entities in this list are not defined.
+
+ ;; Change the default presentation for various tags.
+ ; Use mono-space font for computer items.
+ (element command ($mono-seq$))
+ (element envar ($mono-seq$))
+ (element errorname ($mono-seq$))
+ (element errortype ($mono-seq$))
+ (element keywordname ($mono-seq$)) ; new tag aded by Oldham
+ (element methodname ($mono-seq$)) ; new tag aded by Oldham
+ (element operator ($mono-seq$)) ; new tag aded by Oldham
+ (element statement ($mono-seq$)) ; new tag aded by Oldham
+ (element symbol ($mono-seq$))
+ (element token ($mono-seq$))
+ (element type ($mono-seq$))
+
+ ; Number all pages sequentially, rather than separate numbering for
+ ; various pieces of the preface.
+ ; Copied from stylesheets/docbook/print/dbdivis.dsl.
+ (element book
+ (let* ((bookinfo (select-elements (children (current-node))
+ (normalize "bookinfo")))
+ (dedication (select-elements (children (current-node))
+ (normalize "dedication")))
+ (nl (titlepage-info-elements (current-node) bookinfo)))
+ (make sequence
+ (if %generate-book-titlepage%
+ (make sequence
+ (book-titlepage nl 'recto)
+ (book-titlepage nl 'verso))
+ (empty-sosofo))
+
+ (if (node-list-empty? dedication)
+ (empty-sosofo)
+ (with-mode dedication-page-mode
+ (process-node-list dedication)))
+
+ (if (not (generate-toc-in-front))
+ (process-children)
+ (empty-sosofo))
+
+ (if %generate-book-toc%
+ (make simple-page-sequence
+ page-n-columns: %page-n-columns%
+ page-number-restart?: #f ; changed from #t
+ page-number-format: ($page-number-format$ (normalize "toc"))
+ use: default-text-style
+ left-header: ($left-header$ (normalize "toc"))
+ center-header: ($center-header$ (normalize "toc"))
+ right-header: ($right-header$ (normalize "toc"))
+ left-footer: ($left-footer$ (normalize "toc"))
+ center-footer: ($center-footer$ (normalize "toc"))
+ right-footer: ($right-footer$ (normalize "toc"))
+ input-whitespace-treatment: 'collapse
+ (build-toc (current-node)
+ (toc-depth (current-node))))
+ (empty-sosofo))
+
+ (let loop ((gilist ($generate-book-lot-list$)))
+ (if (null? gilist)
+ (empty-sosofo)
+ (if (not (node-list-empty?
+ (select-elements (descendants (current-node))
+ (car gilist))))
+ (make simple-page-sequence
+ page-n-columns: %page-n-columns%
+ page-number-format: ($page-number-format$ (normalize "lot"))
+ use: default-text-style
+ left-header: ($left-header$ (normalize "lot"))
+ center-header: ($center-header$ (normalize "lot"))
+ right-header: ($right-header$ (normalize "lot"))
+ left-footer: ($left-footer$ (normalize "lot"))
+ center-footer: ($center-footer$ (normalize "lot"))
+ right-footer: ($right-footer$ (normalize "lot"))
+ input-whitespace-treatment: 'collapse
+ (build-lot (current-node) (car gilist))
+ (loop (cdr gilist)))
+ (loop (cdr gilist)))))
+
+ (if (generate-toc-in-front)
+ (process-children)
+ (empty-sosofo)))))
+ ; Copied from stylesheets/docbook/print/dbcompon.dsl.
+ (define ($component$)
+ (make simple-page-sequence
+ page-n-columns: %page-n-columns%
+ page-number-restart?: #f ; changed
+ page-number-format: ($page-number-format$)
+ use: default-text-style
+ left-header: ($left-header$)
+ center-header: ($center-header$)
+ right-header: ($right-header$)
+ left-footer: ($left-footer$)
+ center-footer: ($center-footer$)
+ right-footer: ($right-footer$)
+ start-indent: %body-start-indent%
+ input-whitespace-treatment: 'collapse
+ quadding: %default-quadding%
+ (make sequence
+ ($component-title$)
+ (process-children))
+ (make-endnotes)))
+
+ ; Center figures.
+ (element mediaobject
+ (make paragraph
+ quadding: 'center ; added
+ ($mediaobject$)))
+
+ ;; Display verbatim block environments with smaller font.
+ ; Copied from stylesheets/docbook/print/dbverb.dsl.
+ (define ($verbatim-display$ indent line-numbers?)
+ (let* ((width-in-chars (if (attribute-string (normalize "width"))
+ (string->number (attribute-string (normalize "width")))
+ %verbatim-default-width%))
+ (fsize (lambda () (if (or (attribute-string (normalize "width"))
+ (not %verbatim-size-factor%))
+ (/ (/ (- %text-width% (inherited-start-indent))
+ width-in-chars)
+ 0.7)
+ (inherited-font-size)))) ; changed
+ (vspace (if (INBLOCK?)
+ 0pt
+ (if (INLIST?)
+ %para-sep%
+ %block-sep%))))
+ (make paragraph
+ use: verbatim-style
+ space-before: (if (and (string=? (gi (parent)) (normalize "entry"))
+ (absolute-first-sibling?))
+ 0pt
+ vspace)
+ space-after: (if (and (string=? (gi (parent)) (normalize "entry"))
+ (absolute-last-sibling?))
+ 0pt
+ vspace)
+ font-size: (fsize)
+ line-spacing: (* (fsize) %line-spacing-factor%)
+ start-indent: (if (INBLOCK?)
+ (inherited-start-indent)
+ (+ %block-start-indent% (inherited-start-indent)))
+ (if (or indent line-numbers?)
+ ($linespecific-line-by-line$ indent line-numbers?)
+ (process-children)))))
+
+ ;; Remove initial and final spaces before programlisting embedded
+ ;; within a para.
+ (define ($verbatim-display-embedded$ indent line-numbers?)
+ (let* ((width-in-chars (if (attribute-string (normalize "width"))
+ (string->number (attribute-string (normalize "width")))
+ %verbatim-default-width%))
+ (fsize (lambda () (if (or (attribute-string (normalize "width"))
+ (not %verbatim-size-factor%))
+ (/ (/ (- %text-width% (inherited-start-indent))
+ width-in-chars)
+ 0.7)
+ (inherited-font-size))))) ; changed
+ (make paragraph
+ use: verbatim-style
+ space-before: 0pt
+ space-after: 0pt
+ min-pre-line-spacing: 0pt
+ min-post-line-spacing: 0pt
+ keep-with-previous?: #t
+ keep-with-next?: #t
+ font-size: (fsize)
+ line-spacing: (* (fsize) %line-spacing-factor%)
+ start-indent: (if (INBLOCK?)
+ (inherited-start-indent)
+ (+ %block-start-indent% (inherited-start-indent)))
+ (if (or indent line-numbers?)
+ ($linespecific-line-by-line$ indent line-numbers?)
+ (process-children)))))
+ (element (para programlisting) ; process the programlisting, not para
+ ($verbatim-display-embedded$
+ %indent-programlisting-lines%
+ %number-programlisting-lines%))
+
+ ;; Remove initial and final spaces before itemizedlist embedded
+ ;; within a para.
+ (define ($list-embedded$)
+ (make display-group
+ start-indent: (if (INBLOCK?)
+ (inherited-start-indent)
+ (+ %block-start-indent% (inherited-start-indent)))
+ space-after: 0pt
+ space-before: 0pt
+ min-pre-line-spacing: 0pt
+ min-post-line-spacing: 0pt
+ keep-with-previous?: #t
+ keep-with-next?: #t))
+ (element (para itemizedlist)
+ ($list-embedded$))
+ (element (para orderedlist)
+ ($list-embedded$))
+
+ ;;; From http://cyberelk.net/tim/docbook/selfdocbook/selfdocbook.dsl.html:
+ ;;; To make URLs line wrap we use the TeX 'url' package.
+ ;;; See also: jadetex.cfg
+ ;; First we need to declare the 'formatting-instruction' flow class.
+ (declare-flow-object-class formatting-instruction
+ "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")
+ ;; Then redefine ulink to use it.
+ (element ulink
+ (make sequence
+ (if (node-list-empty? (children (current-node)))
+ ; ulink url="...", /ulink
+ (make formatting-instruction
+ data: (string-append "\\url{"
+ (attribute-string (normalize "url"))
+ "}"))
+ (if (equal? (attribute-string (normalize "url"))
+ (data-of (current-node)))
+ ; ulink url="http://...", http://..., /ulink
+ (make formatting-instruction
+ data: (string-append "\\url{"
+ (attribute-string (normalize "url"))
+ "}"))
+ ; ulink url="http://...", some text, /ulink
+ (make sequence
+ ($charseq$)
+ (literal " (")
+ (make formatting-instruction data:
+ (string-append "\\url{"
+ (attribute-string (normalize "url"))
+ "}"))
+ (literal ")"))))))
+ ;;; And redefine filename to use it too.
+ (element filename
+ (make formatting-instruction
+ data: (string-append "\\path{" (data-of (current-node)) "}")))
+
+ ;; We use ten callouts and only special symbols for nine are permitted.
+ (define %callout-fancy-bug% #f)
+
+ </style-specification-body>
+ </style-specification>
+
+ <external-specification id="docbook" document="docbook.dsl">
+
+ </style-sheet>
Index: template.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/template.xml,v
retrieving revision 1.5
diff -c -p -r1.5 template.xml
*** template.xml 2002/01/30 23:51:45 1.5
--- template.xml 2002/01/31 21:10:45
***************
*** 212,218 ****
<callout
arearefs="template_programming-template_use-templated_pair_program-constructor">
<para>The constructor has two parameters of
! type <varname>T</varname>.</para>
</callout>
<callout
arearefs="template_programming-template_use-templated_pair_program-members">
--- 212,218 ----
<callout
arearefs="template_programming-template_use-templated_pair_program-constructor">
<para>The constructor has two parameters of
! type <type>const T&</type>.</para>
</callout>
<callout
arearefs="template_programming-template_use-templated_pair_program-members">
Index: tutorial.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/tutorial.xml,v
retrieving revision 1.10
diff -c -p -r1.10 tutorial.xml
*** tutorial.xml 2002/01/30 23:51:45 1.10
--- tutorial.xml 2002/01/31 21:10:46
***************
*** 436,443 ****
of the array values that are modified.</para>
</callout>
<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>
--- 436,442 ----
of the array values that are modified.</para>
</callout>
<callout arearefs="tutorial-array_parallel-doof2d-blockAndEvaluate">
! <para>&pooma; may reorder computation. <function>Pooma::blockAndEvaluate</function> ensures all
computation finishes before accessing a particular array
element.</para>
</callout>
***************
*** 506,521 ****
</mediaobject>
</figure>
! <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
! this 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. For
! example, before the data-parallel operation of printing an array,
! &pooma; will call <function>blockAndEvaluate</function>
! itself.</para>
</section>
--- 505,519 ----
</mediaobject>
</figure>
! <para>&pooma; may reorder computation or distribute them among
! various processors so, before accessing individual values,
! the code calls <function>Pooma::blockAndEvaluate</function>. Before
! reading an individual &array; value, calling this 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. For example, before the
! data-parallel operation of printing an array, &pooma; will call
! <function>blockAndEvaluate</function> itself.</para>
</section>
*************** MultiPatch<UniformTag, Remote<Comp
*** 1057,1064 ****
system-dependent. For example, the <command>mpirun -np 4
Doof2d-Field-distributed -mpi 2 10 1000</command> command
might use &mpi; communication.
! <command>Doof2d-Field-distributed -shmem -np 4 2 10
! 1000</command> might use the &mm; Shared Memory Library.</para>
</listitem>
</itemizedlist>
</para>
--- 1055,1063 ----
system-dependent. For example, the <command>mpirun -np 4
Doof2d-Field-distributed -mpi 2 10 1000</command> command
might use &mpi; communication.
! <programlisting>
! Doof2d-Field-distributed -shmem -np 4 2 10 1000
! </programlisting> might use the &mm; Shared Memory Library.</para>
</listitem>
</itemizedlist>
</para>
More information about the pooma-dev
mailing list