From oldham at codesourcery.com  Fri Feb  1 00:29:35 2002
From: oldham at codesourcery.com (Jeffrey)
Date: Thu, 31 Jan 2002 16:29:35 -0800
Subject: Manual Patch: Programs Tidying 2 of x
Message-ID: <20020131162935.B29944@vaio.codesourcery.com>

This is the second of x patches to tidying the programs written for
the POOMA manual.

2002-Jan-31  Jeffrey D. Oldham  <oldham at codesourcery.com>

	* Sequential/include.mk: New file supporting Pooma compilation.
	* Sequential/makefile: Basically unchanged.
	* Templates/pairs-templated.cpp: This file was moved to Sequential/.
	* Templates/pairs-untemplated.cpp: Likewise.

Applied to mainline.

Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: Sequential/include.mk
===================================================================
RCS file: include.mk
diff -N include.mk
*** /dev/null	Fri Mar 23 21:37:44 2001
--- include.mk	Thu Jan 31 17:23:22 2002
***************
*** 0 ****
--- 1,59 ----
+ # Generated by mm.pl: Mon Mar  9 13:58:39 MST 1998
+ # ACL:license
+ #  ----------------------------------------------------------------------
+ #  This software and ancillary information (herein called "SOFTWARE")
+ #  called POOMA (Parallel Object-Oriented Methods and Applications) is
+ #  made available under the terms described here.  The SOFTWARE has been
+ #  approved for release with associated LA-CC Number LA-CC-98-65.
+ #  
+ #  Unless otherwise indicated, this SOFTWARE has been authored by an
+ #  employee or employees of the University of California, operator of the
+ #  Los Alamos National Laboratory under Contract No. W-7405-ENG-36 with
+ #  the U.S. Department of Energy.  The U.S. Government has rights to use,
+ #  reproduce, and distribute this SOFTWARE. The public may copy, distribute,
+ #  prepare derivative works and publicly display this SOFTWARE without 
+ #  charge, provided that this Notice and any statement of authorship are 
+ #  reproduced on all copies.  Neither the Government nor the University 
+ #  makes any warranty, express or implied, or assumes any liability or 
+ #  responsibility for the use of this SOFTWARE.
+ #  
+ #  If SOFTWARE is modified to produce derivative works, such modified
+ #  SOFTWARE should be clearly marked, so as not to confuse it with the
+ #  version available from LANL.
+ #  
+ #  For more information about POOMA, send e-mail to pooma at acl.lanl.gov,
+ #  or visit the POOMA web page at http://www.acl.lanl.gov/pooma/.
+ #  ----------------------------------------------------------------------
+ # ACL:license
+ 
+ 
+ # Wrap make components from SHARED_ROOT and the current directory in the 
+ # proper order so that variables like ODIR have the correct directory-specific 
+ # value at the right moment.  See the included files for details of what they 
+ # are doing. This file should NOT be manually edited.
+ 
+ # Set NEXTDIR, THISDIR and DIR_LIST
+ include $(SHARED_ROOT)/include1.mk
+ 
+ # Include list of subdirectories to process
+ -include $(THISDIR)/subdir.mk
+ 
+ # Set ODIR, PROJECT_INCLUDES, UNIQUE
+ include $(SHARED_ROOT)/include2.mk
+ 
+ # Set list of object files, relative to ODIR
+ -include $(THISDIR)/objfile.mk
+ 
+ # Set rules for the ODIR directory 
+ include $(SHARED_ROOT)/compilerules.mk
+ 
+ # Remove current dir from DIR_LIST
+ DIR_LIST :=$(filter-out $(firstword $(DIR_LIST)), $(DIR_LIST))
+ 
+ 
+ # ACL:rcsinfo
+ #  ----------------------------------------------------------------------
+ #  $RCSfile: include.mk,v $   $Author: oldham $
+ #  $Revision: 1.1 $   $Date: 2001/12/04 00:07:00 $
+ #  ----------------------------------------------------------------------
+ # ACL:rcsinfo
Index: Sequential/makefile
===================================================================
RCS file: /home/pooma/Repository/r2/examples/Manual/Sequential/makefile,v
retrieving revision 1.1
diff -c -p -r1.1 makefile
*** Sequential/makefile	2002/01/25 03:45:54	1.1
--- Sequential/makefile	2002/02/01 00:23:22
*************** include $(PROJECT_ROOT)/config/head.mk
*** 33,39 ****
  
  PASS=APP
  
! default:: array-copy array-size data-parallel dynamicarray initialize-finalize
  
  .PHONY: array-copy
  
--- 33,39 ----
  
  PASS=APP
  
! default:: array-copy array-size data-parallel dynamicarray initialize-finalize 
  
  .PHONY: array-copy
  
Index: Templates/pairs-templated.cpp
===================================================================
RCS file: pairs-templated.cpp
diff -N pairs-templated.cpp
*** /tmp/cvsEDeBEL	Thu Jan 31 17:23:22 2002
--- /dev/null	Fri Mar 23 21:37:44 2001
***************
*** 1,15 ****
- // Declare a template class storing a pair of values with the same type.
- template <typename T>
- struct pair {
-   pair(const int& left, const int& right)
-     : left_(left), right_(right) {}
- 
-   T left_;
-   T right_;
- };
- 
- // Use a class storing a pair of integers.
- pair<int> pair1;
- 
- // Use a class storing a pair of doubles;
- pair<double> pair2;
--- 0 ----
Index: Templates/pairs-untemplated.cpp
===================================================================
RCS file: pairs-untemplated.cpp
diff -N pairs-untemplated.cpp
*** /tmp/cvsKxdfh5	Thu Jan 31 17:23:22 2002
--- /dev/null	Fri Mar 23 21:37:44 2001
***************
*** 1,17 ****
- // Declare a class storing a pair of integers.
- struct pairOfInts {
-   pairOfInts(const int& left, const int& right)
-     : left_(left), right_(right) {}
- 
-   int left_;
-   int right_;
- };
- 
- // Declare a class storing a pair of doubles.
- struct pairOfDoubles {
-   pairOfDoubles(const double& left, const double& right)
-     : left_(left), right_(right) {}
- 
-   double left_;
-   double right_;
- };
--- 0 ----

From oldham at codesourcery.com  Fri Feb  1 02:03:50 2002
From: oldham at codesourcery.com (Jeffrey)
Date: Thu, 31 Jan 2002 18:03:50 -0800
Subject: Manual Patch: Automate Builds
Message-ID: <20020131180350.C29944@vaio.codesourcery.com>

2002-Jan-31  Jeffrey D. Oldham  <oldham at codesourcery.com>

These changes help automate construction of the POOMA manual.
	
	* Makefile: Update 'figure', 'program', and 'clean' targets to
	support recursive builds.
	* makefile: Remove this file in favor of 'Makefile'.
	* pooma.xml: Change the locations of annotated source files.
	* programs/Doof2d/Makefile: Modify to use patch using remote
	source files.
	* programs/Sequential/Makefile: Likewise.

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.4
diff -c -p -r1.4 Makefile
*** Makefile	2002/01/31 21:20:26	1.4
--- Makefile	2002/02/01 01:53:36
*************** XMLSOURCES= $(MANUALNAME).xml introducti
*** 18,32 ****
              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:
  	perl collateindex.pl $(INDEXOPTIONS) -N -o $@
  
--- 18,38 ----
              concepts.xml arrays.xml data-parallel.xml glossary.xml \
              bibliography.xml 
  
! # Create all versions of the manual.
  all: $(MANUALNAME).ps $(MANUALNAME).pdf $(MANUALNAME).html
  
! $(MANUALNAME).dvi $(MANUALNAME).pdf $(MANUALNAME).html: $(XMLSOURCES) figure \
! 							program
  
! # Create the figures for the manual.
! figure:
  	$(MAKE) -C figures
  
+ # Create the annotated programs for the manual.
+ program:
+ 	$(MAKE) -C programs/Doof2d
+ 	$(MAKE) -C programs/Sequential
+ 
  genindex.sgm:
  	perl collateindex.pl $(INDEXOPTIONS) -N -o $@
  
*************** $(MANUALNAME).pdf: $(XMLSOURCES) geninde
*** 55,58 ****
--- 61,67 ----
  	pdfjadetex $(MANUALNAME).tex
  
  clean:
+ 	$(MAKE) -C programs/Doof2d clean
+ 	$(MAKE) -C programs/Sequential clean
+ 	$(MAKE) -C figures 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: makefile
===================================================================
RCS file: makefile
diff -N makefile
*** /tmp/cvsARpksG	Thu Jan 31 18:53:43 2002
--- /dev/null	Fri Mar 23 21:37:44 2001
***************
*** 1,71 ****
- ### Oldham, Jeffrey D.
- ### 1997 Dec 26
- ### misc
- ###
- ### LaTeX -> PostScript/PDF/WWW
- ### XML -> TeX/DVI/PS/PDF
- 
- # Definitions for PostScript and WWW Creation
- TEX=		latex
- WWWHOMEDIR=	/u/oldham/www
- LATEX2HTML=	latex2html
- BASICLATEX2HTMLOPTIONS=	-info "" -no_footnode -no_math -html_version 3.2,math
- #LATEX2HTMLOPTIONS=	-local_icons -split +1 $(BASICLATEX2HTMLOPTIONS)
- LATEX2HTMLOPTIONS=	-no_navigation -split 0 $(BASICLATEX2HTMLOPTIONS)
- MPOST=		mpost
- 
- # Definitions for Jade.
- JADEDIR=		/usr/lib/sgml/stylesheets/docbook
- PRINTDOCBOOKDSL=	print/docbook.dsl
- HTMLDOCBOOKDSL=		html/docbook.dsl
- XML=			dtds/decls/xml.dcl
- INDEXOPTIONS=		-t 'Index' -i 'index' -g -p
- 
- CXXFLAGS= -g -Wall -pedantic -W -Wstrict-prototypes -Wpointer-arith -Wbad-function-cast -Wcast-align -Wconversion -Wnested-externs -Wundef -Winline -static
- 
- all: manual.ps
- 
- manual.dvi: manual.xml introduction.xml tutorial.xml concepts.xml glossary.xml
- 
- %.all:	%.ps %.pdf %.html
- 	chmod 644 $*.ps $*.pdf
- 	mv $*.ps $*.pdf $*
- 
- %.dvi:	%.ltx
- 	$(TEX) $<
- 	# bibtex $*
- 	# $(TEX) $<
- 	$(TEX) $<
- 
- %.ps:	%.dvi
- 	dvips -t letter $< -o
- 
- %.pdf.ltx:	%.ltx
- 	sed -e 's/^%\\usepackage{times}/\\usepackage{times}/' $< > $@
- 
- %.pdf:	%.pdf.ps
- 	ps2pdf $< $@
- 
- # This rule assumes index creation.
- %.dvi:	%.xml genindex.sgm
- 	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) $< && jadetex $*.tex && jadetex $*.tex && jadetex $*.tex
- 
- genindex.sgm:
- 	perl collateindex.pl $(INDEXOPTIONS) -N -o $@
- 
- %.html:	%.xml
- 	jade -D$(JADEDIR) -t sgml -d $(HTMLDOCBOOKDSL) $(XML) $<
- 
- %.pdf:	%.xml
- 	jade -D$(JADEDIR) -t tex -d $(PRINTDOCBOOKDSL) $(XML) $< && pdfjadetex $*.tex && pdfjadetex $*.tex
- 
- mproof-%.ps:	%.mp
- 	declare -x TEX=latex && $(MPOST) $< && tex mproof.tex $*.[0-9]* && dvips mproof.dvi -o $@
- 
- %.txt:	%.ltx
- 	detex $< > $@
- 
- clean:
- 	rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.mpx mpxerr.tex HTML.index manual.tex
--- 0 ----
Index: pooma.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/pooma.xml,v
retrieving revision 1.1
diff -c -p -r1.1 pooma.xml
*** pooma.xml	2002/01/31 21:20:27	1.1
--- pooma.xml	2002/02/01 01:53:41
***************
*** 235,269 ****
  
  <!-- 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. -->
  ]>
  
--- 235,269 ----
  
  <!-- External File Entities -->
  <!-- Doof2d Programs -->
! <!ENTITY doof2d-c-element SYSTEM "./programs/Doof2d/Doof2d-C-element-annotated.cpp">
    <!-- hand-coded Doof2d implementation -->
! <!ENTITY doof2d-array-element SYSTEM "./programs/Doof2d/Doof2d-Array-element-annotated.cpp">
    <!-- Array element-wise Doof2d implementation -->
! <!ENTITY doof2d-array-parallel SYSTEM "./programs/Doof2d/Doof2d-Array-parallel-annotated.cpp">
    <!-- Array data-parallel Doof2d implementation -->
! <!ENTITY doof2d-array-stencil SYSTEM "./programs/Doof2d/Doof2d-Array-stencil-annotated.cpp">
    <!-- Array stencil Doof2d implementation -->
! <!ENTITY doof2d-array-distributed SYSTEM "./programs/Doof2d/Doof2d-Array-distributed-annotated.cpp">
    <!-- distributed Array stencil Doof2d implementation -->
! <!ENTITY doof2d-field-parallel SYSTEM "./programs/Doof2d/Doof2d-Field-parallel-annotated.cpp">
    <!-- Field data-parallel Doof2d implementation -->
! <!ENTITY doof2d-field-distributed SYSTEM "./programs/Doof2d/Doof2d-Field-distributed-annotated.cpp">
    <!-- Field data-parallel distributed Doof2d implementation -->
  
  <!-- Sequential Programs -->
! <!ENTITY array-copy SYSTEM "./programs/Sequential/array-copy-annotated.cpp">
    <!-- Illustrate Array reference semantics. -->
! <!ENTITY array-size SYSTEM "./programs/Sequential/array-size-annotated.cpp">
    <!-- Illustrate Array member functions. -->
! <!ENTITY dynamicarray-example SYSTEM "./programs/Sequential/dynamicarray-annotated.cpp">
    <!-- Illustrate using DynamicArray class. -->
! <!ENTITY initialize-finalize SYSTEM "./programs/Sequential/initialize-finalize-annotated.cpp">
    <!-- Illustrate initialize() and finalize(). -->
  
  <!-- Template Programs -->
! <!ENTITY pairs-untemplated SYSTEM "./programs/Sequential/pairs-untemplated-annotated.cpp">
    <!-- Illustrate defining classes with pairs of values of the same type. -->
! <!ENTITY pairs-templated SYSTEM "./programs/Sequential/pairs-templated-annotated.cpp">
    <!-- Illustrate defining a template class with pairs of values of the same type. -->
  ]>
  
Index: programs/Doof2d/Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Doof2d/Makefile,v
retrieving revision 1.1
diff -c -p -r1.1 Makefile
*** programs/Doof2d/Makefile	2002/01/31 22:17:30	1.1
--- programs/Doof2d/Makefile	2002/02/01 01:53:43
***************
*** 7,16 ****
  ## These rules combine executable code, which can be compiled and run,
  ## with DocBook annotations used in the manual to explain the code.
  
! all: Doof2d-C-element-annotated.cpp Doof2d-Array-element-annotated.cpp \
       Doof2d-Array-parallel-annotated.cpp Doof2d-Array-stencil-annotated.cpp \
       Doof2d-Array-distributed-annotated.cpp \
       Doof2d-Field-parallel-annotated.cpp Doof2d-Field-distributed-annotated.cpp
  
! %-annotated.cpp: %-annotated.patch %.cpp
! 	patch -o $@ < $<
--- 7,24 ----
  ## These rules combine executable code, which can be compiled and run,
  ## with DocBook annotations used in the manual to explain the code.
  
! TARGETS= Doof2d-C-element-annotated.cpp Doof2d-Array-element-annotated.cpp \
       Doof2d-Array-parallel-annotated.cpp Doof2d-Array-stencil-annotated.cpp \
       Doof2d-Array-distributed-annotated.cpp \
       Doof2d-Field-parallel-annotated.cpp Doof2d-Field-distributed-annotated.cpp
  
! all: $(TARGETS)
! 
! # directory containing the executable code
! EXECUTABLEDIRECTORY= ../../../../examples/Manual/Doof2d/
! 
! %-annotated.cpp: %-annotated.patch $(EXECUTABLEDIRECTORY)/%.cpp
! 	patch -o $@ $(EXECUTABLEDIRECTORY)/$*.cpp $<
! 
! clean:
! 	rm -f $(TARGETS)
Index: programs/Sequential/Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Sequential/Makefile,v
retrieving revision 1.1
diff -c -p -r1.1 Makefile
*** programs/Sequential/Makefile	2002/01/31 22:20:43	1.1
--- programs/Sequential/Makefile	2002/02/01 01:53:43
***************
*** 7,15 ****
  ## These rules combine executable code, which can be compiled and run,
  ## with DocBook annotations used in the manual to explain the code.
  
! all: array-copy-annotated.cpp dynamicarray-annotated.cpp \
       initialize-finalize-annotated.cpp \
       pairs-templated-annotated.cpp pairs-untemplated-annotated.cpp
  
! %-annotated.cpp: %-annotated.patch %.cpp
! 	patch -o $@ < $<
--- 7,24 ----
  ## These rules combine executable code, which can be compiled and run,
  ## with DocBook annotations used in the manual to explain the code.
  
! TARGETS= array-copy-annotated.cpp array-size-annotated.cpp \
!      dynamicarray-annotated.cpp \
       initialize-finalize-annotated.cpp \
       pairs-templated-annotated.cpp pairs-untemplated-annotated.cpp
  
! all: $(TARGETS)
! 
! # directory containing the executable code
! EXECUTABLEDIRECTORY= ../../../../examples/Manual/Sequential/
! 
! %-annotated.cpp: %-annotated.patch $(EXECUTABLEDIRECTORY)/%.cpp
! 	patch -o $@ $(EXECUTABLEDIRECTORY)/$*.cpp $<
! 
! clean:
! 	rm -f $(TARGETS)

From oldham at codesourcery.com  Fri Feb  1 02:11:13 2002
From: oldham at codesourcery.com (Jeffrey)
Date: Thu, 31 Jan 2002 18:11:13 -0800
Subject: Manual Patch: Tidy Clean Targets
Message-ID: <20020131181113.D29944@vaio.codesourcery.com>

2002-Jan-31  Jeffrey D. Oldham  <oldham at codesourcery.com>

	* Makefile (clean): Also remove *.out files.
	* figures/Makefile (clean): Remove mproof-*.ps files.

Applied to mainline.

(How can one tidy a clean target if it is already clean?)

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.5
diff -c -p -r1.5 Makefile
*** Makefile	2002/02/01 02:00:50	1.5
--- Makefile	2002/02/01 02:06:27
*************** clean:
*** 64,67 ****
  	$(MAKE) -C programs/Doof2d clean
  	$(MAKE) -C programs/Sequential clean
  	$(MAKE) -C figures 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
--- 64,67 ----
  	$(MAKE) -C programs/Doof2d clean
  	$(MAKE) -C programs/Sequential clean
  	$(MAKE) -C figures clean
! 	rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.html *.mpx *.out mpxerr.tex HTML.index $(MANUALNAME).tex genindex.sgm pooma-html.manifest
Index: figures/Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/Makefile,v
retrieving revision 1.1
diff -c -p -r1.1 Makefile
*** figures/Makefile	2002/01/31 21:29:58	1.1
--- figures/Makefile	2002/02/01 02:06:29
*************** introduction-%.png: introduction.%
*** 63,66 ****
--- 63,67 ----
  	$(EPSTOPNG) -p -o $@ $^
  
  clean:
+ 	rm -f $(RESULTS)
  	rm -f *.dvi *.aux *.log *.toc *.bak *.blg *.bbl *.glo *.idx *.lof *.lot *.htm *.mpx mpxerr.tex

From oldham at codesourcery.com  Fri Feb  1 17:35:22 2002
From: oldham at codesourcery.com (Jeffrey Oldham)
Date: Fri, 1 Feb 2002 09:35:22 -0800
Subject: Pooma Manual: Deliverable
Message-ID: <20020201093522.A1988@codesourcery.com>

The attached compressed tar file contains a POOMA manual in three
separate formats:

    PostScript:	pooma.ps
    PDF:		pooma.pdf
    HTML:		pooma.html

To extract the files: tar xzvf pooma-manual-2002Jan31.tgz.

Done,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pooma-manual-2002Jan31.tgz
Type: application/x-gzip
Size: 1691357 bytes
Desc: not available
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20020201/6e5489f8/attachment.bin>

From oldham at codesourcery.com  Fri Feb  1 17:51:40 2002
From: oldham at codesourcery.com (Jeffrey Oldham)
Date: Fri, 1 Feb 2002 09:51:40 -0800
Subject: Manual Patch: Final Manual Patch?
Message-ID: <20020201095140.C1988@codesourcery.com>

This patch moves the POOMA manual toward creation on varying platforms.

2002-Feb-01  Jeffrey D. Oldham  <oldham at codesourcery.com>

	* Makefile (JADEDIR): Revise to more canonical location.
	* README.txt: Explain how to build the POOMA manual.
	* pooma.xml: Revise DocBook XML file to more canonical location.

Applied to	mainline.

Are we done?

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.6
diff -c -p -r1.6 Makefile
*** Makefile	2002/02/01 02:08:07	1.6
--- Makefile	2002/02/01 17:39:04
***************
*** 7,13 ****
  TEX=		latex
  
  # Definitions for Jade.
! JADEDIR=		/usr/lib/sgml/stylesheets/docbook
  PRINTDOCBOOKDSL=	print.dsl # print/docbook.dsl
  HTMLDOCBOOKDSL=		html.dsl # html/docbook.dsl
  XML=			dtds/decls/xml.dcl
--- 7,13 ----
  TEX=		latex
  
  # Definitions for Jade.
! JADEDIR=		/usr/share/sgml/docbook/dsssl-stylesheets-1.64
  PRINTDOCBOOKDSL=	print.dsl # print/docbook.dsl
  HTMLDOCBOOKDSL=		html.dsl # html/docbook.dsl
  XML=			dtds/decls/xml.dcl
Index: README.txt
===================================================================
RCS file: README.txt
diff -N README.txt
*** /dev/null	Fri Mar 23 21:37:44 2001
--- README.txt	Fri Feb  1 10:39:04 2002
***************
*** 0 ****
--- 1,66 ----
+ Oldham, Jeffrey D.
+ 2002Jan31
+ POOMA
+ 
+ Creating the POOMA Manual
+ 
+ 
+ To create the manual,
+ 
+ 	make
+ 
+ If this fails, keep reading.
+ 
+ The POOMA manual source is written in
+   DocBook - for text
+   MetaPost - for figures
+   C++ - for source code.
+ 
+ Creating it requires the following tools:
+ 
+   jade: James's DSSL engine which converts DocBook into HTML, RTF, TeX, ...
+ 
+   jadetex: TeX + special macros for Jade.  Its fixed constants need to
+     be large enough.
+ 
+   pdfjadetex: pdfTeX + special macros for Jade.  Its fixed constants need to
+     be large enough.
+ 
+   mpost: Converts MetaPost source code into EPS figure files.
+ 
+   peps: Converts EPS files to PNG files.
+ 
+   mproof.tex: Used to proof the EPS files.
+ 
+ If you have having trouble with:
+   jade: Modify $(JADEDIR) in Makefile to the directory containing the
+     DocBook stylesheets.
+     Modify pooma.xml's DOCTYPE line to specify the location of the
+     DocBook docbookx.dtd.
+ 
+   jadetex: Ensure it has large enough TeX capacities.  See
+     http://jadetex.sourceforge.net.
+ 
+   peps: Use any tool you desire to convert the EPS files into PNG
+     files.  Specify the tool in figures/Makefile's $(EPSTOPNG).
+     Alternatively, download peps from
+     http://www.whizkidtech.net/peps/.  Be sure to apply the patch
+     below to ensure the resulting figures are not too large.
+ 
+     The invocation assumes 'pnmtopng' is available.
+ 
+   mproof.tex: Download from any CTAN archive, e.g., www.ctan.org.
+ 
+ 
+ *** peps.c	Wed Jul  4 16:59:56 2001
+ --- peps.c	Tue Jan 29 14:42:51 2002
+ ***************
+ *** 359,362 ****
+ --- 359,365 ----
+     }
+   
+ +   hres *= 0.75;
+ +   vres *= 0.75;
+ + 
+     sprintf(buffer, gsargs,
+   	  gab,
Index: pooma.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/pooma.xml,v
retrieving revision 1.2
diff -c -p -r1.2 pooma.xml
*** pooma.xml	2002/02/01 02:00:50	1.2
--- pooma.xml	2002/02/01 17:39:07
***************
*** 1,7 ****
  <?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. -->
--- 1,7 ----
  <?xml version="1.0"?>
  <!-- FIXME: Index this file. -->
  
! <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd" [
  
  <!-- Text to Check, Revise, Replace -->
    <!-- FIXME: Revise before releasing. -->

From toon.knapen at si-lab.org  Sat Feb  2 10:52:48 2002
From: toon.knapen at si-lab.org (Toon Knapen)
Date: Sat, 02 Feb 2002 11:52:48 +0100
Subject: POOMA user-base
Message-ID: <3C5BC500.3090204@si-lab.org>

I'm performing a small survey on the typical user-base of open-source 
scientific software and the relationship with the complexity of the 
project. The results will be used as feedback to the european and local 
authorities concerning the governmental stimulation of open-source 
scientific software.


Preface:
-----------

One can distinguish two types of users for open-source projects : 
end-users and developers.

The number of end-users for a project is heavily influenced by the ease 
of intallation and use of the project. E.g., if installation is more 
complicated as going through the 'configure ; make ; make install' 
cycle, many end-users will abandon the project. Additionally, once 
installed, the software must be easy to use. I believe that if these two 
conditions are met, the complexity of the project itself has no 
influence on the user-base.
An example is for instance 'gcc'. Although this compiler collection is 
internally very complex, millions of people go through the easy 
installation procedure and happily use it because the user-interface is 
well-known to most of us and thus does not scare people away. Maybe 
'gcc' is not a good example though because the gcc end-users are 
generally developers and thus know how to install new software very 
well. An open-source java virtual machine would for instance be a better 
example.

The other group are the developers that are end-users that also want to 
contribute to the code or use the source-code instead of only the final 
executable. The number of developers that contribute to a project is 
heavily influenced by the number of people that are familiar with the 
technology used in the source-code and the problem-domain the code is 
trying to solve (.e.g to a UML package coded in C++ only people will 
contribute who are familiar with C++(technology) and UML(problem domain)).

Our theory:
---------------

Because of the complexity of scientific software, open-source scientific 
projects generally have very few users and developers. The user-base is 
generally smaller compared to the user-base of similar commercial software.

Open-source scientific projects are generally a bit complicated to use 
because they are mainly not conforming to some known standard-interface 
and end-user manuals are scarce. E.g. many people use octave or scilab 
because the interface is easy for all those who know Matlab. But Rheolef 
for instance has apparantly very few users. Commercial soft on the other 
hand has generally very good documentation (I know, you guys are also 
doing a really big effort on the documentation currently ;-)

In open-source scientific software projects, generally all users seem to 
be developers. Only people that can really benefit from using the 
project and are familiar with the technology and problem-domain will 
generally only invest in learning to use the project. E.g. Blitz++ and 
MTL have a large user-base but these users are also all 'domain 
experts', expert in the problem-domain (numerical analysis) and the 
technology (computer science, C++, expression templates).

Projects for a very specific problem-domain (such as Pooma) the maximum 
possible user-base is thus very restricted.


Survey:
----------

To gain some more insight however in these relations between the number 
of end-users, developers, used technology and problem domain, I would 
like to get some more information over the use of Pooma out there :

_ Do you agree with our theory ?
_ Is POOMA currently used for performing simulations by 
organisations/individuals outside of Los Alamos/Codesourcery
_ How many end-users use POOMA and how many developers contribute to POOMA.
_ why do people plan to use / use / never used / abandoned POOMA.


Goal:
-------

The goal of my survey is mainly because we like to provide feedback to 
the Belgian and European government on the optimal stimulation of 
scientific open-source projects.


Results:
----------
I would appreciate all answers. In case your answer would be 
confidential, you can email me directly.
I can also report the results of the survey on the ml (the names related 
to the 'confidential answers' will be removed from the statistics) if 
there would be an interest.






From oldham at codesourcery.com  Thu Feb  7 18:30:56 2002
From: oldham at codesourcery.com (Jeffrey Oldham)
Date: Thu, 7 Feb 2002 10:30:56 -0800
Subject: Pooma License: Up to Date?
Message-ID: <20020207103056.A20441@codesourcery.com>

Do you know if the Pooma license, in the file "LICENSE," contains the
correct license?

At the very least, the contact URLs should be changed.

Thanks for the information,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
----------------------------------------------------------------------
This software and ancillary information (herein called "SOFTWARE")
called POOMA (Parallel Object-Oriented Methods and Applications) is
made available under the terms described here.  The SOFTWARE has been
approved for release with associated LA-CC Number LA-CC-98-65.

Unless otherwise indicated, this SOFTWARE has been authored by an
employee or employees of the University of California, operator of the
Los Alamos National Laboratory under Contract No. W-7405-ENG-36 with
the U.S. Department of Energy.  The U.S. Government has rights to use,
reproduce, and distribute this SOFTWARE. The public may copy, distribute,
prepare derivative works and publicly display this SOFTWARE without 
charge, provided that this Notice and any statement of authorship are 
reproduced on all copies.  Neither the Government nor the University 
makes any warranty, express or implied, or assumes any liability or 
responsibility for the use of this SOFTWARE.

If SOFTWARE is modified to produce derivative works, such modified
SOFTWARE should be clearly marked, so as not to confuse it with the
version available from LANL.

For more information about POOMA, send e-mail to pooma at acl.lanl.gov,
or visit the POOMA web page at http://www.acl.lanl.gov/pooma/.
----------------------------------------------------------------------

From scotth at proximation.com  Thu Feb  7 22:58:12 2002
From: scotth at proximation.com (Scott Haney)
Date: Thu, 7 Feb 2002 15:58:12 -0700 
Subject: Pooma License: Up to Date?
Message-ID: <F871BB04B0EA224A821A5274C31DF31521C1@proxim-sf001.santafe.proximation.com>

Hi Jeffrey,

It did at the time we left the lab; however, what it is now is really a call
for the lab and CodeSourcery. I would suggest consulting with Jeff Brown. My
vote, for what it is worth, is that the parties retain the BSD-style license
from POOMA 2.3. 

Scott

-----Original Message-----
From: Jeffrey Oldham [mailto:oldham at codesourcery.com] 
Sent: Thursday, February 07, 2002 11:31 AM
To: scotth at proximation.com; mark at codesourcery.com
Cc: pooma-dev at pooma.codesourcery.com
Subject: Pooma License: Up to Date?

Do you know if the Pooma license, in the file "LICENSE," contains the
correct license?

At the very least, the contact URLs should be changed.

Thanks for the information,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20020207/ab2a2b80/attachment.html>

From mark at codesourcery.com  Mon Feb 11 09:02:13 2002
From: mark at codesourcery.com (Mark Mitchell)
Date: Mon, 11 Feb 2002 09:02:13 -0000
Subject: Pooma License: Up to Date?
In-Reply-To: <20020207103056.A20441@codesourcery.com>
Message-ID: <4100818567.1013418133@localhost>



--On Thursday, February 07, 2002 10:30 AM -0800 Jeffrey Oldham 
<oldham at codesourcery.com> wrote:

> Do you know if the Pooma license, in the file "LICENSE," contains the
> correct license?

I believe it to be correct.

> At the very least, the contact URLs should be changed.

The problem is that *we* can't do that, at least that's what Beth
thought the last time I asked her.  LANL would have to do that, and
that's a can of worms I'm not particularly interested in opening.

--
Mark Mitchell
CodeSourcery, LLC
mark at codesourcery.com


From jcrotinger at proximation.com  Tue Feb 12 21:23:45 2002
From: jcrotinger at proximation.com (James Crotinger)
Date: Tue, 12 Feb 2002 14:23:45 -0700
Subject: [pooma-dev] Re: Pooma License: Up to Date?
Message-ID: <F871BB04B0EA224A821A5274C31DF3150942A3@proxim-sf001.santafe.proximation.com>

Perhaps you should change it in the READMEs and leave a note there about the
licenses being out of date. 

  Jim

> -----Original Message-----
> From: Mark Mitchell [mailto:mark at codesourcery.com]
> Sent: Monday, February 11, 2002 2:02 AM
> To: Jeffrey Oldham
> Cc: pooma-dev at pooma.codesourcery.com
> Subject: [pooma-dev] Re: Pooma License: Up to Date?
> 
> 
> 
> 
> --On Thursday, February 07, 2002 10:30 AM -0800 Jeffrey Oldham 
> <oldham at codesourcery.com> wrote:
> 
> > Do you know if the Pooma license, in the file "LICENSE," 
> contains the
> > correct license?
> 
> I believe it to be correct.
> 
> > At the very least, the contact URLs should be changed.
> 
> The problem is that *we* can't do that, at least that's what Beth
> thought the last time I asked her.  LANL would have to do that, and
> that's a can of worms I'm not particularly interested in opening.
> 
> --
> Mark Mitchell
> CodeSourcery, LLC
> mark at codesourcery.com
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20020212/308d0b14/attachment.html>

From mark at codesourcery.com  Wed Feb 13 00:08:17 2002
From: mark at codesourcery.com (Mark Mitchell)
Date: Tue, 12 Feb 2002 16:08:17 -0800
Subject: [pooma-dev] Re: Pooma License: Up to Date?
In-Reply-To: <F871BB04B0EA224A821A5274C31DF3150942A3@proxim-sf001.santafe.proximation.com>
Message-ID: <7040000.1013558897@warlock.codesourcery.com>



--On Tuesday, February 12, 2002 02:23:45 PM -0700 James Crotinger 
<jcrotinger at proximation.com> wrote:

>
> Perhaps you should change it in the READMEs and leave a note there about
> the licenses being out of date.

That's a good idea.  Jeffrey, would you take care of that?

-- 
Mark Mitchell                mark at codesourcery.com
CodeSourcery, LLC            http://www.codesourcery.com


From oldham at codesourcery.com  Wed Feb 13 16:03:17 2002
From: oldham at codesourcery.com (Jeffrey Oldham)
Date: Wed, 13 Feb 2002 08:03:17 -0800
Subject: [pooma-dev] Re: Pooma License: Up to Date?
In-Reply-To: <F871BB04B0EA224A821A5274C31DF3150942A3@proxim-sf001.santafe.proximation.com>; from jcrotinger@proximation.com on Tue, Feb 12, 2002 at 02:23:45PM -0700
References: <F871BB04B0EA224A821A5274C31DF3150942A3@proxim-sf001.santafe.proximation.com>
Message-ID: <20020213080317.B14654@codesourcery.com>

Is the attached proposed change to the README file acceptable?

Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com

On Tue, Feb 12, 2002 at 02:23:45PM -0700, James Crotinger wrote:
> Perhaps you should change it in the READMEs and leave a note there about the
> licenses being out of date. 
> 
>   Jim
> 
> > -----Original Message-----
> > From: Mark Mitchell [mailto:mark at codesourcery.com]
> > Sent: Monday, February 11, 2002 2:02 AM
> > To: Jeffrey Oldham
> > Cc: pooma-dev at pooma.codesourcery.com
> > Subject: [pooma-dev] Re: Pooma License: Up to Date?
> > 
> > 
> > 
> > 
> > --On Thursday, February 07, 2002 10:30 AM -0800 Jeffrey Oldham 
> > <oldham at codesourcery.com> wrote:
> > 
> > > Do you know if the Pooma license, in the file "LICENSE," 
> > contains the
> > > correct license?
> > 
> > I believe it to be correct.
> > 
> > > At the very least, the contact URLs should be changed.
> > 
> > The problem is that *we* can't do that, at least that's what Beth
> > thought the last time I asked her.  LANL would have to do that, and
> > that's a can of worms I'm not particularly interested in opening.
> > 
> > --
> > Mark Mitchell
> > CodeSourcery, LLC
> > mark at codesourcery.com
> > 

-- 
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: README
===================================================================
RCS file: /home/pooma/Repository/r2/README,v
retrieving revision 1.61
diff -c -p -r1.61 README
*** README	2001/12/17 17:13:23	1.61
--- README	2002/02/13 16:02:39
***************
*** 1,3 ****
--- 1,21 ----
+ ////////////////////////////////////////////////////////////////////
+ 
+ NOTES v2.4.0 (under development)
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
+ Recent POOMA development has been performed by Proximation LLC
+ (www.proximation.com) and CodeSourcery LLC (www.codesourcery.com).
+ Despite the license's claims, the latest POOMA code base and
+ documentation can be found at the latter's WWW site:
+ www.codesourcery.com/pooma/pooma.
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
+ RELEASE NOTES v2.3.0
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
  /*******************************************************************
   *                                                                 *
   *                      POOMA Release Notes                        *
***************
*** 22,33 ****
   *    For help, reporting bugs, and making suggestions, please     *
   *        send e-mail to pooma at acl.lanl.gov                        *
   *******************************************************************/
- 
- ////////////////////////////////////////////////////////////////////
- 
- RELEASE NOTES v2.3.0
- 
- ////////////////////////////////////////////////////////////////////
  
  MESSAGE-BASED PARALLELISM
  -------------------------
--- 40,45 ----

From jcrotinger at proximation.com  Wed Feb 13 16:06:57 2002
From: jcrotinger at proximation.com (James Crotinger)
Date: Wed, 13 Feb 2002 09:06:57 -0700
Subject: [pooma-dev] Re: Pooma License: Up to Date?
Message-ID: <F871BB04B0EA224A821A5274C31DF3150942A8@proxim-sf001.santafe.proximation.com>

My only comment would be that if we're going to keep www.pooma.com, which I
think we should, then we should list it as the website. It is a redirection
now, but that could change in the future. 

  Jim


> -----Original Message-----
> From: Jeffrey Oldham [mailto:oldham at codesourcery.com]
> Sent: Wednesday, February 13, 2002 9:03 AM
> To: James Crotinger
> Cc: 'Mark Mitchell'; pooma-dev at pooma.codesourcery.com
> Subject: Re: [pooma-dev] Re: Pooma License: Up to Date?
> 
> 
> Is the attached proposed change to the README file acceptable?
> 
> Thanks,
> Jeffrey D. Oldham
> oldham at codesourcery.com
> 
> On Tue, Feb 12, 2002 at 02:23:45PM -0700, James Crotinger wrote:
> > Perhaps you should change it in the READMEs and leave a 
> note there about the
> > licenses being out of date. 
> > 
> >   Jim
> > 
> > > -----Original Message-----
> > > From: Mark Mitchell [mailto:mark at codesourcery.com]
> > > Sent: Monday, February 11, 2002 2:02 AM
> > > To: Jeffrey Oldham
> > > Cc: pooma-dev at pooma.codesourcery.com
> > > Subject: [pooma-dev] Re: Pooma License: Up to Date?
> > > 
> > > 
> > > 
> > > 
> > > --On Thursday, February 07, 2002 10:30 AM -0800 Jeffrey Oldham 
> > > <oldham at codesourcery.com> wrote:
> > > 
> > > > Do you know if the Pooma license, in the file "LICENSE," 
> > > contains the
> > > > correct license?
> > > 
> > > I believe it to be correct.
> > > 
> > > > At the very least, the contact URLs should be changed.
> > > 
> > > The problem is that *we* can't do that, at least that's what Beth
> > > thought the last time I asked her.  LANL would have to do 
> that, and
> > > that's a can of worms I'm not particularly interested in opening.
> > > 
> > > --
> > > Mark Mitchell
> > > CodeSourcery, LLC
> > > mark at codesourcery.com
> > > 
> 
> -- 
> Jeffrey D. Oldham
> oldham at codesourcery.com
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20020213/bfea22ff/attachment.html>

From mark at codesourcery.com  Wed Feb 13 16:29:57 2002
From: mark at codesourcery.com (Mark Mitchell)
Date: Wed, 13 Feb 2002 08:29:57 -0800
Subject: [pooma-dev] Re: Pooma License: Up to Date?
In-Reply-To: <20020213080317.B14654@codesourcery.com>
Message-ID: <52250000.1013617797@warlock.codesourcery.com>



--On Wednesday, February 13, 2002 08:03:17 AM -0800 Jeffrey Oldham 
<oldham at codesourcery.com> wrote:

> Is the attached proposed change to the README file acceptable?

Yes, I think that's good.

-- 
Mark Mitchell                mark at codesourcery.com
CodeSourcery, LLC            http://www.codesourcery.com


From mark at codesourcery.com  Wed Feb 13 16:31:29 2002
From: mark at codesourcery.com (Mark Mitchell)
Date: Wed, 13 Feb 2002 08:31:29 -0800
Subject: [pooma-dev] Re: Pooma License: Up to Date?
In-Reply-To: <F871BB04B0EA224A821A5274C31DF3150942A8@proxim-sf001.santafe.proximation.com>
Message-ID: <54190000.1013617889@warlock.codesourcery.com>



--On Wednesday, February 13, 2002 09:06:57 AM -0700 James Crotinger 
<jcrotinger at proximation.com> wrote:

>
> My only comment would be that if we're going to keep www.pooma.com, which
> I think we should, then we should list it as the website. It is a
> redirection now, but that could change in the future.

Yes, that's OK.

-- 
Mark Mitchell                mark at codesourcery.com
CodeSourcery, LLC            http://www.codesourcery.com


From oldham at codesourcery.com  Wed Feb 13 16:42:29 2002
From: oldham at codesourcery.com (Jeffrey Oldham)
Date: Wed, 13 Feb 2002 08:42:29 -0800
Subject: Patch: Update README to show current URLs
Message-ID: <20020213084229.A18021@codesourcery.com>

2002-Feb-13  Jeffrey D. Oldham  <oldham at codesourcery.com>

	* README: Add an indication of the current POOMA location
	  since we cannot change the license without political action.

Approved by	Jim Crotinger
Applied to	mainline
Not tested.

Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
Index: README
===================================================================
RCS file: /home/pooma/Repository/r2/README,v
retrieving revision 1.61
diff -c -p -r1.61 README
*** README	2001/12/17 17:13:23	1.61
--- README	2002/02/13 16:39:25
***************
*** 1,3 ****
--- 1,22 ----
+ ////////////////////////////////////////////////////////////////////
+ 
+ NOTES v2.4.0 (under development)
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
+ Recent POOMA development has been performed by Proximation LLC
+ (www.proximation.com) and CodeSourcery LLC (www.codesourcery.com).
+ Despite the license's claims, the latest POOMA code base and
+ documentation can be found at the latter's WWW site:
+ 		  www.codesourcery.com/pooma/pooma
+ www.pooma.com is a synonym.
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
+ RELEASE NOTES v2.3.0
+ 
+ ////////////////////////////////////////////////////////////////////
+ 
  /*******************************************************************
   *                                                                 *
   *                      POOMA Release Notes                        *
***************
*** 22,33 ****
   *    For help, reporting bugs, and making suggestions, please     *
   *        send e-mail to pooma at acl.lanl.gov                        *
   *******************************************************************/
- 
- ////////////////////////////////////////////////////////////////////
- 
- RELEASE NOTES v2.3.0
- 
- ////////////////////////////////////////////////////////////////////
  
  MESSAGE-BASED PARALLELISM
  -------------------------
--- 41,46 ----

From jxyh at lanl.gov  Thu Feb 14 22:39:15 2002
From: jxyh at lanl.gov (John Hall)
Date: Thu, 14 Feb 2002 15:39:15 -0700
Subject: Changes to Head Version of Pooma for Tecolote
Message-ID: <a05101203b891b43eb1bc@[128.165.16.39]>

Well:
I have the demo project passing all of the regression tests using the 
head version of Pooma through the PhysicsSupport layer. This was a 
considerable effort, but, things are looking pretty good.

While I was at it, I started with a virgin version of the Pooma Head 
version and found the following 3 problems which everyone must fix 
before we can use the Head version. If these are innocuous enough I 
would like to have them checked in, otherwise, our team will have to 
remember to change them every time we check out from scratch.

The first problem keeps the relations from being sorted by priority 
when they are added. This has not really been tested, since I haven't 
used relation groups yet, but, it appears to be wrong since the test 
will never be true otherwise.

The second problem is a simple typo. Once it was fixed our regression 
tests passed, the Pooma tests never tested this case.

The third set of changes is to make a common interface between 
"DomainLayout" and the other distributed layouts so that one code 
base compiles in both serial and distributed cases. The beginGlobal 
function is being called from the IO stuff Jim wrote. Everything 
seems to work with these changes, but, someone with a clearer overall 
picture should probably check it out. I just copied the "local" 
section and replaced "Local" with "Global".

I hope to have everything moved over to the head version by the end 
of next week. Then we have another effort to finish the physics that 
was not quite done by the end of the "Demo Project". I continue to 
believe that there is a need for this work and I intend to put it 
into reasonable shape so that I can get a group of users and 
re-establish support for what we were doing.

I hope that all of you are doing well and that you will remember us 
when "Numerics/Proximation" and CodeSourcery make you all rich and 
famous. Maybe those of us at the lab can become "your people" so that 
your other rich and famous friends will have someone to call when you 
say "Have your people call my people".

Anyhow, back to the grind. Don't forget, its Valentine's day, so you 
better have something by the time you go home.

John Hall

_________________________________________
Index: src/Field/Relations/RelationList.h
===================================================================
RCS file: /home/pooma/Repository/r2/src/Field/Relations/RelationList.h,v
retrieving revision 1.1
diff -r1.1 RelationList.h
131c131
<           if (data_m[i]->priority() <= data_m[i]->priority())
---
>            if (data_m[i]->priority() <= data_m[i - 1]->priority())

Index: src/Field/Relations/Relations.h
===================================================================
RCS file: /home/pooma/Repository/r2/src/Field/Relations/Relations.h,v
retrieving revision 1.2
diff -r1.2 Relations.h
186c186
<   Relation1(const Target &t, const R1 &r,
---
>    Relation1(const Target &t, const R1 &r1,

Index: src/Layout/DomainLayout.h
===================================================================
RCS file: /home/pooma/Repository/r2/src/Layout/DomainLayout.h,v
retrieving revision 1.25
diff -r1.25 DomainLayout.h
341a342,364
>    // Return begin and end iterators for the list of all global 
>subdomains (there are no others of course)
>
>    inline iterator beginGlobal()
>      {
>        return begin();
>      }
>    inline iterator endGlobal()
>      {
>        return end();
>      }
>    inline const_iterator beginGlobal() const
>      {
>        return begin();
>      }
>    inline const_iterator endGlobal() const
>      {
>        return end();
>      }
>    inline long sizeGlobal() const
>      {
>        return size();
>      }
>

-- 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20020214/de1a593d/attachment.html>

From mark at codesourcery.com  Fri Feb 15 19:45:11 2002
From: mark at codesourcery.com (Mark Mitchell)
Date: Fri, 15 Feb 2002 11:45:11 -0800
Subject: Pooma - FFT Class (fwd)
Message-ID: <30130000.1013802311@gandalf.codesourcery.com>

Jeffrey --

Would you answer this question?

Thanks,

---------- Forwarded Message ----------
Date: Friday, February 15, 2002 10:39:10 AM -0800
From: Timothy William Chevalier <timothyc at stanford.edu>
To: "info at codesourcery.com" <info at codesourcery.com>
Subject: Pooma - FFT Class


Hi,

I have Pooma version 2.3 that I just downloaded.  I read about the
incorporation of an FFT Class in one of the tutorials that can perform
FFT, Cosine and Sine Transforms on Pooma Field Objects (and possibly
Arrays).  I can't seem to find this class anywhere in the source code.  I
assume this class is independent of the optional FFTW wrapper class.  Do
you have any idea where I can get a hold of this class.  I am
primarily interested in the Sine Transform for solving Poisson's equation.
Any help would be greatly appreciated.

Thank you,

Tim Chevalier


---------- End Forwarded Message ----------



--
Mark Mitchell                   mark at codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com



From oldham at codesourcery.com  Wed Feb 27 04:02:12 2002
From: oldham at codesourcery.com (Jeffrey)
Date: Tue, 26 Feb 2002 20:02:12 -0800
Subject: Manual Changes: Preface, Coding Conventions, UML Diagrams
Message-ID: <20020226200212.A9020@vaio.codesourcery.com>

This patch adds

  1) a preface,

  2) a "getting started" chapter explaining how to download source code,
    build the library, and compile a "Hello, Pooma" program,

  3) an overview of the source code and coding conventions, and

  4) a preliminary chapter of UML class diagrams, created at the
    specification, not implementation, level.

2002-Feb-26  Jeffrey D. Oldham  <oldham at codesourcery.com>

	* Makefile (XMLSOURCES): Add preface.xml and code.xml.
	* code.xml: New file/appendix describing source code organization
	and coding conventions.
	* concepts.xml: Fix cross reference whose name changed.
	* pooma.xml: Add entity for dangerous-bend sections, uml, g++.
	Move acknowledgements into the preface.  Move template programming
	chapter to an appendix.  Add "Getting Started" chapter.  Moved
	installation instructions from appendix into "Getting Started"
	chapter.  Added preliminary version of appendix of UML class
	diagrams.
	* preface.xml: New file containing a revised preface.
	* starting.xml: New file/chapter describing building the library
	and compiling a "Hello, Pooma" program.
	* template.xml: Move from a chapter to an appendix.
	* tutorial.xml: Moved Pooma installation to "Getting Started"
	chapter.
	* figures/Makefile: Added support for UML diagrams.
	* figures/array-uml-1.png: New illustration.
	* figures/array-uml-2.png: Likewise.
	* figures/array-uml-3.png: Likewise.
	* figures/array-uml.mp: New file for creating Array UML diagrams.
	* figures/domain-uml-1.png: New illustration.
	* figures/domain-uml.mp: New file for creating Domain UML diagrams.
	* figures/engine-uml-1.png: New illustration.
	* figures/engine-uml-2.png: Likewise.
	* figures/engine-uml-3.png: Likewise.
	* figures/engine-uml-4.png: Likewise.
	* figures/engine-uml.mp: New file for creating Engine UML diagrams.
	* figures/explanation-uml-1.png: New illustration.
	* figures/explanation-uml.mp: New file explaining UML class diagrams.
	* figures/macros.ltx: Added macros for UML diagrams.
	* figures/uml.mp: New file of MetaPost macros for UML diagrams.
	* programs/Sequential/initialize-finalize-annotated.patch: Revised
	this patch to reflect changes in the underlying file.

Applied to mainline.

Thanks,
Jeffrey D. Oldham
oldham at codesourcery.com
-------------- next part --------------
? HTML.index
? arrays-arrays.html
? arrays-arrays_declarations.html
? arrays-arrays_use.html
? arrays-containers.html
? arrays-domains.html
? arrays-dynamic_arrays.html
? arrays.html
? concepts-computation_environment.html
? concepts-computation_modes.html
? concepts-containers.html
? concepts.html
? data_parallel-implementation.html
? data_parallel-multiple_values.html
? data_parallel-use.html
? data_parallel.html
? differences-2002Feb26
? engines-concept.html
? engines-types.html
? engines.html
? genindex.sgm
? glossary.html
? initial-compile.html
? initial-compile_programs.html
? initial-distributed_computing.html
? initial-obtain.html
? initial-quick_start.html
? initial.html
? introduction-goals.html
? introduction-open_source.html
? introduction-pooma_history.html
? introduction.html
? manual-2002Feb26.ChangeLog
? manual-2002Jan31.ChangeLog
? manual-2002Jan31.patch
? pooma-html.manifest
? pooma.aux
? pooma.dvi
? pooma.html
? pooma.log
? pooma.out
? pooma.pdf
? pooma.ps
? pooma.tex
? preface-acknowledgements.html
? preface-downloading.html
? preface-pooma_history.html
? preface-reading_book:.html
? preface.html
? preface.pdf
? preface.ps
? sources-conventions.html
? sources-structure.html
? sources.html
? template_programming-compile_time.html
? template_programming-pooma_implementation.html
? template_programming-template_use.html
? template_programming.html
? tutorial-array_data_parallel.html
? tutorial-array_distributed.html
? tutorial-array_elementwise.html
? tutorial-array_stencil.html
? tutorial-field_data_parallel.html
? tutorial-field_distributed.html
? tutorial-hand_coded.html
? tutorial.html
? uml-arrays.html
? uml-domains.html
? uml-engines.html
? uml.html
? views.html
? wrap-programlisting.pl
? figures/array-uml.1
? figures/array-uml.2
? figures/array-uml.3
? figures/concepts.101
? figures/concepts.111
? figures/concepts.log
? figures/concepts.mpx
? figures/data-parallel.101
? figures/data-parallel.212
? figures/data-parallel.log
? figures/data-parallel.mpx
? figures/distributed.101
? figures/distributed.log
? figures/distributed.mpx
? figures/domain-uml.1
? figures/doof2d.201
? figures/doof2d.202
? figures/doof2d.203
? figures/doof2d.210
? figures/doof2d.211
? figures/doof2d.log
? figures/doof2d.mpx
? figures/engine-uml.1
? figures/engine-uml.2
? figures/engine-uml.3
? figures/engine-uml.4
? figures/explanation-uml.1
? figures/explanation-uml.log
? figures/explanation-uml.mpx
? figures/foo.1
? figures/foo.mp
? figures/introduction.101
? figures/introduction.log
? figures/introduction.mpx
? figures/mproof-array-uml.ps
? figures/mproof-concepts.ps
? figures/mproof-data-parallel.ps
? figures/mproof-distributed.ps
? figures/mproof-domain-uml.ps
? figures/mproof-doof2d.ps
? figures/mproof-engine-uml.ps
? figures/mproof-explanation-uml.ps
? figures/mproof-introduction.ps
? figures/mproof.dvi
? figures/mproof.log
? figures/mproof.ps
? figures/prev
? programs/Doof2d/Doof2d-Array-distributed-annotated.cpp
? programs/Doof2d/Doof2d-Array-element-annotated.cpp
? programs/Doof2d/Doof2d-Array-parallel-annotated.cpp
? programs/Doof2d/Doof2d-Array-stencil-annotated.cpp
? programs/Doof2d/Doof2d-C-element-annotated.cpp
? programs/Doof2d/Doof2d-Field-distributed-annotated.cpp
? programs/Doof2d/Doof2d-Field-parallel-annotated.cpp
? programs/Sequential/array-copy-annotated.cpp
? programs/Sequential/array-size-annotated.cpp
? programs/Sequential/dynamicarray-annotated.cpp
? programs/Sequential/initialize-finalize-annotated.cpp
? programs/Sequential/pairs-templated-annotated.cpp
? programs/Sequential/pairs-untemplated-annotated.cpp
Index: Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/Makefile,v
retrieving revision 1.7
diff -c -p -r1.7 Makefile
*** Makefile	2002/02/01 17:43:13	1.7
--- Makefile	2002/02/27 03:44:23
***************
*** 7,22 ****
  TEX=		latex
  
  # Definitions for Jade.
! JADEDIR=		/usr/share/sgml/docbook/dsssl-stylesheets-1.64
  PRINTDOCBOOKDSL=	print.dsl # print/docbook.dsl
  HTMLDOCBOOKDSL=		html.dsl # html/docbook.dsl
  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 
  
  # Create all versions of the manual.
  all: $(MANUALNAME).ps $(MANUALNAME).pdf $(MANUALNAME).html
--- 7,23 ----
  TEX=		latex
  
  # Definitions for Jade.
! JADEDIR=		/usr/lib/sgml/stylesheets/docbook # /usr/share/sgml/docbook/dsssl-stylesheets-1.64
  PRINTDOCBOOKDSL=	print.dsl # print/docbook.dsl
  HTMLDOCBOOKDSL=		html.dsl # html/docbook.dsl
  XML=			dtds/decls/xml.dcl
  INDEXOPTIONS=		-t 'Index' -i 'index' -g -p
  
  MANUALNAME= pooma
! XMLSOURCES= $(MANUALNAME).xml preface.xml starting.xml \
! 	    introduction.xml tutorial.xml \
              concepts.xml arrays.xml data-parallel.xml glossary.xml \
!             bibliography.xml template.xml code.xml
  
  # Create all versions of the manual.
  all: $(MANUALNAME).ps $(MANUALNAME).pdf $(MANUALNAME).html
Index: code.xml
===================================================================
RCS file: code.xml
diff -N code.xml
*** /dev/null	Fri Mar 23 21:37:44 2001
--- code.xml	Tue Feb 26 20:44:23 2002
***************
*** 0 ****
--- 1,814 ----
+  <appendix id="sources">
+   <title>&danger;: Overview of &pooma; Sources</title>
+ 
+   <para>In this chapter, we outline the &pooma; source code structure
+   and coding conventions for those who are interested in reading the
+   code.</para>
+ 
+   <section id="sources-structure">
+    <title>Structure of the Files</title>
+ 
+    <para>The &poomatoolkit; files are divided into directories
+    according to their purposes.  See <xref
+    linkend="sources-structure-directory_table"></xref>.  In that
+    table, directories and files are categorized:
+    <variablelist>
+      <varlistentry>
+       <term>use</term>
+       <listitem>
+        <para>introductions to the &toolkit;, its installation, and its
+        use</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>user code</term>
+       <listitem>
+        <para>source code for &pooma; programs.  &pooma; users can
+        read these programs as examples how to use the &toolkit;.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>documentation</term>
+       <listitem>
+        <para>user-level explanations of how to use the &toolkit;'s features</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>source code</term>
+       <listitem>
+        <para>&cc; files implementing the &toolkit;.  In their
+        programs, users may need to refer to header files.  Otherwise,
+        these files are mainly read by developers.  Source code
+        subdirectories are described in <xref
+        linkend="sources-structure-src_directory_table"></xref>.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>development</term>
+       <listitem>
+        <para>used by &pooma; developers when writing and
+        preparing &toolkit; files</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>installation</term>
+       <listitem>
+        <para>used when converting the &toolkit; source code into an
+        executable library.  This process can involve architecture- and
+        machine-dependent code.</para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+     The <filename class="directory">src</filename> directory,
+     containing source code, contains many files so it is described in
+     the separate table <xref
+     linkend="sources-structure-src_directory_table"></xref>.
+     <filename class="directory">CVS</filename> subdirectories are
+     scattered throughout the source code.  The <application
+     class="software">Concurrent Versions System</application> is a
+     version control system.  The subdirectories have files storing the
+     <application class="software">CVS</application> state.  Ignore
+     these subdirectories.</para>
+ 
+    <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ 	  orient="port" pgwide="0" id="sources-structure-directory_table">
+     <title>&toolkitcap; Directories and Files</title>
+     
+     <tgroup cols="3" align="left">
+      <thead>
+       <row>
+        <entry>directory or file</entry>
+        <entry>type</entry>
+        <entry>contents</entry>
+       </row>
+      </thead>
+      <tfoot>
+       <row>
+        <entry>Not all directories and files are listed.</entry>
+       </row>
+      </tfoot>
+      <tbody valign="top">
+       <row>
+        <entry><filename class="directory">benchmarks</filename></entry>
+        <entry>user code</entry>
+        <entry>source code for programs used to test the &toolkit;'s speed</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">bin</filename></entry>
+        <entry>development</entry>
+        <entry>scripts useful for creating releases</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">config</filename></entry>
+        <entry>installation</entry>
+        <entry>files used to configure the library</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">config/arch</filename></entry>
+        <entry>installation</entry>
+        <entry>machine- and compiler-specific configuration files</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">config/Shared</filename></entry>
+        <entry>installation</entry>
+        <entry>machine-independent configuration and make files</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">configure</filename></entry>
+        <entry>installation</entry>
+        <entry>script used by user to configure the library</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">docs</filename></entry>
+        <entry>documentation</entry>
+        <entry>documentation describing using the &toolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">docs/manual</filename></entry>
+        <entry>documentation</entry>
+        <entry>documentation describing using the R2.4 &toolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">examples</filename></entry>
+        <entry>user code</entry>
+        <entry>source code for programs used to illustrate using the &toolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">ide</filename></entry>
+        <entry>development</entry>
+        <entry>files to support using integrated development
+        environments to develop &pooma;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">lib</filename></entry>
+        <entry>installation</entry>
+        <entry>directory where &pooma; library is placed</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">LICENSE</filename></entry>
+        <entry>use</entry>
+        <entry>description of rules for using the &poomatoolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">makefile</filename></entry>
+        <entry>installation</entry>
+        <entry>makefile rules to create the &toolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">README</filename></entry>
+        <entry>use</entry>
+        <entry>release notes for various versions</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">scripts</filename></entry>
+        <entry>installation</entry>
+        <entry>scripts to install &pooma; and related libraries</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">src</filename></entry>
+        <entry>source code</entry> <entry>&toolkit; source code.  See
+        <xref
+        linkend="sources-structure-src_directory_table"></xref>.</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+ 
+    <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ 	  orient="port" pgwide="0" id="sources-structure-src_directory_table">
+     <title>Source Code Directories (Within <filename class="directory">src</filename>)</title>
+     
+     <tgroup cols="2" align="left">
+      <thead>
+       <row>
+        <entry><filename class="directory">src</filename> subdirectory</entry>
+        <entry>contents</entry>
+       </row>
+      </thead>
+      <tfoot>
+       <row>
+        <entry>Not all directories and files are listed.</entry>
+       </row>
+      </tfoot>
+      <tbody valign="top">
+       <row>
+        <entry><filename class="directory">arch</filename></entry>
+        <entry>files necessary for using specific architectures or
+        compilers.  Some replace missing header files.  Others modify
+        &pooma; files.</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Array</filename></entry>
+        <entry>declaration and implementation of the <glossterm linkend="glossary-array">&array;</glossterm> container
+        class</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Array/tests</filename></entry>
+        <entry>programs testing the <glossterm linkend="glossary-array">&array;</glossterm> code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">CoordinateSystems</filename></entry>
+        <entry>Cartesian, cylindrical, and spherical coordinate system
+        classes useful with meshes</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Domain</filename></entry>
+        <entry><glossterm linkend="glossary-domain">&domain;</glossterm> declarations and implementations</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Domain/tests</filename></entry>
+        <entry>programs testing the <glossterm linkend="glossary-domain">&domain;</glossterm> code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">DynamicArray</filename></entry>
+        <entry>declaration and implementation of the <glossterm
+        linkend="glossary-dynamicarray">&dynamicarray;</glossterm>
+        container class</entry>
+       </row>
+       <row>
+        <entry><filename
+        class="directory">DynamicArray/tests</filename></entry>
+        <entry>programs testing the <glossterm
+        linkend="glossary-dynamicarray">&dynamicarray;</glossterm> code
+        and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Engine</filename></entry>
+        <entry>declarations and implementations of the <glossterm
+        linkend="glossary-engine">&engine;</glossterm> classes</entry>
+       </row>
+       <row>
+        <entry><filename
+        class="directory">Engine/tests</filename></entry>
+        <entry>programs testing the <glossterm
+        linkend="glossary-engine">&engine;</glossterm> code and
+        features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Evaluator</filename></entry>
+        <entry>classes evaluating expressions quickly.  For example,
+        one <type>Evaluator</type> evaluates data-parallel expressions.</entry>
+ <!-- FIXME: Eventually add a glossary entry for evaluators. -->
+       </row>
+       <row>
+        <entry><filename class="directory">Evaluator/tests</filename></entry>
+        <entry>programs testing the <type>Evaluator</type> code</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Field</filename></entry>
+        <entry>declaration and implementation of the <glossterm
+        linkend="glossary-field">&field;</glossterm> container
+        class</entry>
+       </row>
+       <row>
+        <entry><filename
+        class="directory">Field/DiffOps</filename></entry>
+        <entry>implementation of <glossterm
+        linkend="glossary-field">&field;</glossterm> <glossterm
+        linkend="glossary-stencil">stencils</glossterm></entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Field/Mesh</filename></entry>
+        <entry>declarations and implementations of <glossterm
+        linkend="glossary-mesh">meshes</glossterm>, which
+        specify a <glossterm
+        linkend="glossary-field">field</glossterm>'s spatial extent</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Field/Relations</filename></entry>
+        <entry>declarations and implementations of <glossterm
+        linkend="glossary-relation">relations</glossterm> among
+        &field;s, supporting automatic computation of field values</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Field/tests</filename></entry>
+        <entry>programs testing the <glossterm
+        linkend="glossary-field">&field;</glossterm> code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">FileTemplates</filename></entry>
+        <entry>files illustrating the usual structure of source code files</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Functions</filename></entry>
+        <entry>unsupported files currently under development</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">IO</filename></entry>
+        <entry>declarations and implementation of input-output classes
+        to store containers in files</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">IO/tests</filename></entry>
+        <entry>programs testing the input-output (IO) code</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Layout</filename></entry>
+        <entry>declarations and implementations of the <glossterm
+        linkend="glossary-layout">&layout;</glossterm> classes, which
+        specify the mappings between processors and container
+        values</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Layout/tests</filename></entry>
+        <entry>programs testing the <glossterm linkend="glossary-layout">&layout;</glossterm> code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Particles</filename></entry>
+        <entry>declares and implements the <type>Particles</type>
+        class, which is not currently supported</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Particles/tests</filename></entry>
+        <entry>programs testing the unsupported <type>Particles</type>
+        class code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Partition</filename></entry>
+        <entry>declares and implements <glossterm
+        linkend="glossary-partition">partitions</glossterm>, which
+        specify how a container's domain is split into patches for
+        distributed computation</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Partition/tests</filename></entry>
+        <entry>programs testing partition code and features</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">PETE</filename></entry>
+        <entry>implements the &pete; framework</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Pooma</filename></entry>
+        <entry>header files declaring all user-level classes</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Pooma/PETE</filename></entry>
+        <entry>input files integrating &pooma; containers into the
+        &pete; framework for fast data-parallel expressions</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Pooma/tests</filename></entry>
+        <entry>programs testing simple &pooma; programs</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Threads</filename></entry>
+        <entry>classes integrating &smarts; threads into &pooma;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Tiny</filename></entry>
+        <entry>declarations and implementations of &matrix;, &tensor;,
+        and &vector;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Tiny/tests</filename></entry>
+        <entry>programs testing &matrix;, &tensor;,
+        and &vector; classes</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Tulip</filename></entry>
+        <entry>interface between &pooma; and the &cheetah; messaging library</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Tulip/tests</filename></entry>
+        <entry>programs testing the interface between &pooma; and the 
+        &cheetah; messaging library</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Utilities</filename></entry>
+        <entry>declarations and implementations of classes used
+        throughout the &toolkit;</entry>
+       </row>
+       <row>
+        <entry><filename class="directory">Utilities/tests</filename></entry>
+        <entry>programs testing utility classes</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+ 
+    <para>A filename's suffix indicates its purpose.  See <xref
+    linkend="sources-structure-suffixes_table"></xref>.
+    Implementations of template classes are usually stored in header
+    files so the &cc; compiler can instantiate the classes.  Sometimes
+    some of the implementation of longer functions is stored in
+    <filename class="libraryfile">.cc</filename> files, which are
+    included by the preprocessor in the corresponding header files.
+    When &cc; compilers and linkers fully support template class
+    compilation, the inclusion will no longer be necessary.</para>
+ 
+    <table frame="none" colsep="0" rowsep="0" tocentry="1"
+ 	  orient="port" pgwide="0" id="sources-structure-suffixes_table">
+     <title>Filename Suffixes</title>
+     
+     <tgroup cols="2" align="left">
+      <thead>
+       <row>
+        <entry>filename suffix</entry>
+        <entry>meaning</entry>
+       </row>
+      </thead>
+      <tbody valign="top">
+       <row rowsep="1">
+        <entry>Source Code Files</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.c</filename></entry>
+        <entry>&c;-language file, usually containing an entire &c; program</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.cpp</filename></entry>
+        <entry>&cc;-language file, frequently containing an entire &cc;
+        &pooma; program.  Sometimes these illustrate using &pooma; or
+        test the source code.  Others contain long definitions of
+        template class functions.</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.cmpl.cpp</filename></entry>
+        <entry>&cc; class implementation file to be compiled and
+        included in the &pooma; library.  Only non-templated classes
+        occur in these files.</entry>
+       </row>
+       <row>
+        <entry><filename class="headerfile">.h</filename></entry>
+        <entry>&cc; header file.  Some are included directly in user
+        programs.  Others declare and implement classes, particularly
+        templated classes.  A few are &c; header files.</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.in</filename></entry>
+        <entry>&pete; input file</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.inst.cpp</filename></entry>
+        <entry>preinstantiations of templated &cc; classes.</entry>
+       </row>
+ 
+       <row rowsep="1">
+        <entry>Compilation and Execution Files</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.a</filename></entry>
+        <entry>&pooma; library</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.mk</filename></entry>
+        <entry>file containing &make; rules, typically included within
+        another <filename class="libraryfile">makefile</filename></entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.info</filename></entry>
+        <entry>log file created when compiling &pooma; source</entry>
+       </row>
+ 
+       <row rowsep="1">
+        <entry>Documentation Files</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.dsl</filename></entry>
+        <entry>DSSSL stylesheet used to convert documentation in
+        DocBook format into other formats</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.gif</filename></entry>
+        <entry>Graphics Interchange Format file containing a figure
+        suitable for display via the WWW</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.html</filename></entry>
+        <entry>HTML documentation file suitable for display via the WWW</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.mp</filename></entry>
+        <entry>MetaPost source code for manual illustrations.</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.pdf</filename></entry>
+        <entry>Portable Document Format (PDF) file, usually containing
+        &toolkit; documentation</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.png</filename></entry>
+        <entry>Portable Network Graphics file suitable for display via
+        the WWW</entry>
+       </row>
+       <row>
+        <entry><filename class="libraryfile">.xml</filename></entry>
+        <entry>eXtended Markup Language (XML) file, usually containing
+        &toolkit; documentation</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+   </section>
+ 
+ 
+   <section id="sources-conventions">
+    <title>&pooma; Coding Conventions</title>
+ 
+    <para>&pooma; has been written by several different sets of
+    developers.  We describe the coding conventions generally used
+    throughout the code, but there are, of course, exceptions.  To see
+    the coding conventions in practice, view random files in the
+    <filename class="directory">src</filename> subdirectory.  The
+    <filename class="directory">src/FileTemplates</filename>
+    subdirectory contains very short files illustrating some of the
+    coding conventions.</para>
+ 
+ 
+    <section id="sources-conventions-namespace">
+     <title>&pooma; Namespace</title>
+ 
+     <para>Most implementation functions and classes are placed within
+     the <literal>Pooma</literal> namespace.  Some user-level functions
+     are also within this namespace, e.g.,
+     <function>Pooma::initialize</function> and
+     <function>Pooma::finalize</function>.  This is incompletely
+     implemented because some &cc; compilers did not correctly
+     implement namespaces.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-formatting">
+     <title>Formatting</title>
+ 
+     <para>Indentation follows the <application class="software">GNU
+     Emacs</application>'s &cc; mode guidelines.  Most increases in
+     indentation levels starts two characters to the right.</para>
+ 
+     <para>Most brackets, e.g., in function definitions, occur on
+     separate lines.  Exceptions are for very short functions.</para>
+ 
+     <para>There is no space between a function's name and the left
+     parenthesis starting its parameter list.</para>
+ 
+    </section>
+ 
+ 
+    <section id="sources-conventions-preprocessor">
+     <title>Preprocessor</title>
+ 
+     <section id="sources-conventions-preprocessor-comments">
+      <title>Comments</title>
+ 
+      <para>Almost all comments begin with <literal>//</literal>.
+      <literal>/* &hellip; */</literal> comments occasionally occur
+      when commenting an intraline value.</para>
+ 
+      <para>&c; files, including header files, exclusively use
+      <literal>/* &hellip; */</literal> comments.</para>
+     </section>
+ 
+     <section id="sources-conventions-preprocessor-symbols">
+      <title>Preprocessor Symbols</title>
+ 
+      <para>Preprocessor symbols are used only for preprocessor
+      conditional expressions, not to define constants.  Such symbols
+      consist of all capital letters with underscore symbols separating
+      words.  They begin with a <literal>POOMA_</literal> prefix.  For
+      example, if <literal>POOMA_BOUNDS_CHECK</literal> represents a
+      true value, then conditionally included code to check that
+      indices are within a domain should be included.</para>
+ 
+      <para>Header guards also consist of all capital letters with
+      underscore symbols separating words.  They begin with
+      <literal>POOMA_</literal>, continue with names of directories and
+      files, and end with <literal>_H</literal>.  For example,
+      <literal>POOMA_UTILITIES_MODELELEMENT_H</literal> guards
+      <filename
+      class="headerfile">src/Utilities/ModelElement.h</filename>.</para>
+     </section>
+ 
+     <section id="sources-conventions-preprocessor-macros">
+      <title>Preprocessor Macros</title>
+ 
+      <para>Inline functions are preferred over preprocessor macros.
+      The latter do occasionally occur.  Usually their scope is quite
+      limited (sometimes to just one file), and their purpose is to
+      avoid writing repetitive code.  For example, <filename
+      class="headerfile">src/PETE/PETE.h</filename> defines
+      <function>PETE_EMPTY_CONSTRUCTORS(CLASS)</function> as the three
+      types of constructors for classes with parameterless
+      constructors.</para>
+ 
+      <para>The main other use is to define macros that need access to
+      the <literal>__FILE__</literal> and <literal>__LINE__</literal>
+      preprocessor symbols to produce error messages.  For example,
+      <function>CTAssert</function> in <filename
+      class="libraryfile">src/Utilities/PAssert.h</filename> uses
+      this.</para>
+     </section>
+    </section><!-- preprocessor -->
+ 
+ 
+    <section id="sources-conventions-globals">
+     <title>Global Variables</title>
+ 
+     <para>Global variables are avoided whenever possible.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-classes">
+     <title>Classes</title>
+ 
+     <para>In this section, we describe coding conventions for classes,
+     both templated and not templated.</para>
+ 
+     <para>In files declaring classes, the comments near the beginning
+     frequently begin with a listing of the classes followed by a
+     high-level explanation of the classes' public interface.  A longer
+     explanation including implementation details usually precedes the
+     class declaration.</para>
+ 
+     <para>Class names tend to be concatenations of capitalized words
+     without underscores, e.g., <literal>Field</literal> and
+     <literal>RefCountedPtr</literal>.</para>
+ 
+     <para>Most classes are declared using <literal>class</literal>,
+     not <literal>struct</literal>.  The latter is frequently used for
+     implementation and compile-time classes that have only public
+     members.</para>
+ 
+     <para>Template parameters are declared using the
+     <literal>class</literal> keyword, rather than the
+     <literal>typename</literal> keyword.  The latter is used when
+     required by &cc; to resolve parsing problems.</para>
+ 
+     <para>Default template parameters are sometimes used.</para>
+ 
+     <para>The order of class members is usually:
+      <variablelist>
+       <varlistentry>
+        <term>public</term>
+        <listitem>
+ 	<variablelist>
+ 	 <varlistentry>
+ 	  <term>internal types</term>
+ 	  <listitem>
+ 	   <para>Usually end with <literal>_t</literal>.  Name
+ 	   consists of the concatenation of capitalized words without
+ 	   intervening underscores.</para>
+ 	  </listitem>
+ 	 </varlistentry>
+ 	 <varlistentry>
+ 	  <term>constructors</term>
+ 	  <listitem>
+ 	   <para></para>
+ 	  </listitem>
+ 	 </varlistentry>
+ 	 <varlistentry>
+ 	  <term>destructors</term>
+ 	  <listitem>
+ 	   <para></para>
+ 	  </listitem>
+ 	 </varlistentry>
+ 	 <varlistentry>
+ 	  <term>member functions</term>
+ 	  <listitem>
+ 	   <para>Usually named by the concatenation of capitalized
+ 	   words without intervening underscores but having an
+ 	   uncapitalized first word.</para>
+ 	  </listitem>
+ 	 </varlistentry>
+ 	</variablelist>
+        </listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>protected</term>
+        <listitem>
+ 	<para>This section is frequently empty.  If so, do not list
+ 	the <literal>protected</literal> tag.</para>
+        </listitem>
+       </varlistentry>
+       <varlistentry>
+        <term>private</term>
+        <listitem>
+ 	<para>This section contains private data members and less
+ 	frequently private functions.  If this section is empty, do not
+ 	list the <literal>private</literal> tag.</para>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+ 
+     The order sometimes changes if required to be correct &cc; or
+     eases the ordering.  Two different sections are frequently
+     separated by a one-line comment with seventy-six hyphens.  An
+     explanatory comment usually precedes each member.</para>
+ 
+     <para>Member data is almost always private or protected.  Function
+     accessors permit access.</para>
+ 
+     <para>Names of internal types usually are formed by the
+     concatenation of capitalized words without intervening underscores
+     followed by <literal>_t</literal>.  Names of member functions are
+     similar except the first word is not usually capitalized and they
+     have no suffix.  Names of member data are similar to names of
+     member functions except they end with
+     <literal>_m</literal>.</para>
+ 
+     <para>Most functions are defined directly in the class
+     declaration.  Functions with long function bodies are defined in
+     <filename class="libraryfile">.cpp</filename> files for templated
+     classes and in <filename class="libraryfile">.cmpl.cpp</filename>
+     files for untemplated classes.</para>
+ 
+     <para>Functions make liberal use of <literal>const</literal> both
+     to modify parameters and member functions.</para>
+ 
+     <para>Templated member functions are permitted.</para>
+ 
+     <para>Overloaded member functions are permitted.  Operator
+     overloading is permitted.</para>
+ 
+     <para>Default arguments are permitted.</para>
+ 
+     <para>Many functions are marked <literal>inline</literal>.  This
+     assumes the optimizer can handle a large number of inlined
+     functions.  Even functions defined inside class declarations are
+     marked <literal>inline</literal> even though the &cc; standard
+     requires them to be inlined if possible even if not so marked.
+     This is because some optimizers attempt more aggressive inlining
+     for explicitly marked member functions.</para>
+ 
+     <para>The &pooma; inheritance hierarchy is quite shallow, both
+     from the user's and from the implementation point of view.  A
+     majority of the uses of inheritance are to factor out a common
+     implementation and reduce coding.</para>
+ 
+     <para>Virtual functions are usually avoided because they can
+     execute slowly.</para>
+ 
+    </section><!-- conventions for classes -->
+ 
+ 
+    <section id="sources-conventions-functions">
+     <title>Functions</title>
+ 
+     <para>Class member functions are preferred over global functions
+     when they achieve the same purpose.  Guidelines for global
+     functions are the same as for class member functions: A function
+     name is a concatenation of capitalized words without underscores
+     and with the first word not capitalized.
+     <literal>inline</literal> and <literal>const</literal> are
+     aggressively used.  Templated member functions, overloaded member
+     functions, operator overloading, and default arguments are
+     permitted.</para>
+ 
+     <para>Functions return references and constant references when
+     appropriate.</para>
+ 
+    </section>
+ 
+ 
+    <section id="sources-conventions-friends">
+     <title>Friends</title>
+ 
+     <para>Friend functions are rare and are usually defined directly
+     within the class of which they are a friend.  Friend class
+     declarations do occur.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-compile_time">
+     <title>Compile-Time Programming</title>
+ 
+     <para>Compile-time structures and static functions occur
+     throughout the code.  Most of the classes are
+     <literal>struct</literal>s since they have only public members.
+     The coding conventions follow those for run-time code.
+     Enumerations are a preferred way to declare integral constants.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-constants">
+     <title>Constants</title>
+ 
+     <para>Enumerations are preferred over declaring constant
+     integers.</para>
+ 
+     <para>Use the <literal>const</literal> keyword, not preprocessor
+     definitions, to define constants.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-casting">
+     <title>Type Casting</title>
+ 
+     <para>Type casting usually indicates a design flaw so it is rarely
+     used.  When it is used, use <literal>static_cast</literal>,
+     <literal>dynamic_cast</literal>, or
+     <literal>reinterpret_cast</literal>.</para>
+    </section>
+ 
+ 
+    <section id="sources-conventions-errors">
+     <title>Errors and Exceptions</title>
+ 
+     <para>&pooma; code uses very few exception since not all &cc;
+     compilers adequately support exceptions.  Thus, all uses must also
+     have corresponding code not using exceptions.  See, e.g.,
+     <literal>POOMA_EXCEPTIONS</literal> in the code.</para>
+    </section>
+ 
+   </section><!-- coding conventions -->
+  </appendix><!-- source overview -->
Index: concepts.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/concepts.xml,v
retrieving revision 1.12
diff -c -p -r1.12 concepts.xml
*** concepts.xml	2002/01/30 23:51:45	1.12
--- concepts.xml	2002/02/27 03:44:24
***************
*** 633,639 ****
     Communications Library 
  <!-- FIXME: xref linkend="mpi99" (<ulink url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) -->
     and the &mm; Shared Memory Library.  See <xref
!    linkend="installation-distributed_computing"></xref> for
     details.</para>
    </section>
  </chapter>
--- 633,639 ----
     Communications Library 
  <!-- FIXME: xref linkend="mpi99" (<ulink url="http://www-unix.mcs.anl.gov/mpi/"></ulink>) -->
     and the &mm; Shared Memory Library.  See <xref
!    linkend="initial-distributed_computing"></xref> for
     details.</para>
    </section>
  </chapter>
Index: pooma.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/pooma.xml,v
retrieving revision 1.3
diff -c -p -r1.3 pooma.xml
*** pooma.xml	2002/02/01 17:43:13	1.3
--- pooma.xml	2002/02/27 03:44:27
***************
*** 37,42 ****
--- 37,45 ----
    <!-- Produce a notation for ">>", which frequently occurs with templates.  Without this, TeX produces a shift symbol. -->
  <!ENTITY closecloseclose "&gt;&gap;&gap;&gt;&gap;&gap;&gt;" >
    <!-- Produce a notation for ">>>", which infrequently occurs with templates.  Without this, TeX produces a shift symbol. -->
+ <!ENTITY danger "DANGER" >
+   <!-- Produce a notation for a dangerous section. -->
+   <!-- Modify this to a dangerous-bend symbol. -->
  <!ENTITY dashdash "-&gap;-" >
    <!-- Produce a notation for a double dash.  Without this, TeX produces an en-hyphen. -->
  <!ENTITY dim "D">
***************
*** 50,55 ****
--- 53,60 ----
    <!-- 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 metapost "<application class='software'>MetaPost</application>">
+   <!-- Produce a notation for Bill Hobby's MetaPost graphics program.  -->
  <!ENTITY mm "<application class='software'>MM</application>">
    <!-- Produce a notation for the MM Library.  -->
  <!ENTITY mpi "<application class='software'>MPI</application>">
***************
*** 77,82 ****
--- 82,89 ----
    <!-- Produce a notation for the name of the Pooma software.  -->
  <!ENTITY toolkitcap "Toolkit">
    <!-- Produce a capitalized version of &toolkit;.  -->
+ <!ENTITY uml "<acronym>UML</acronym>">
+   <!-- Produce an acronym for "UML".  -->
  
  <!-- Type Entity Declarations -->
  
***************
*** 175,181 ****
    <!-- 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. -->
--- 182,190 ----
    <!-- a notation for multidimensional space -->
  
  <!-- System and Operating System Entity Declarations -->
! <!ENTITY gcc "<application>gcc</application>">
!   <!-- The generic GNU Compiler Collection compiler. -->
! <!ENTITY gpp "<application>g++</application>">
    <!-- The GNU Compiler Collection C++ compiler. -->
  <!ENTITY kcc "<application>KCC</application>">
    <!-- The KAI C++ compiler. -->
***************
*** 201,206 ****
--- 210,218 ----
  <!-- Spelling and Formatting Decisions -->
  <!ENTITY author "author">
    <!-- A word describing an author xor authors. -->
+ <!ENTITY initialspace "">
+   <!-- Space to indent a verbatim block.  -->
+   <!-- There should be some automatic formatting to do this.  -->
  <!ENTITY naive "na&iuml;ve">
    <!-- The word "na\"{\i}ve." -->
  <!ENTITY naivecap "Na&iuml;ve">
***************
*** 213,218 ****
--- 225,231 ----
    <!-- spelling: multidimensional, not multi-dimensional -->
    <!-- spelling: multiprocessor, not multi-processor -->
    <!-- spelling: nonzero, not non-zero -->
+   <!-- spelling: preinstantiate, not pre-instantiate -->
    <!-- formatting: for sets, no spaces between brackets and entries but spaced between entries -->
  
  <!-- External Chapters -->
***************
*** 220,225 ****
--- 233,240 ----
    <!-- Pooma Arrays chapter -->
  <!ENTITY bibliography-chapter SYSTEM "bibliography.xml">
    <!-- bibliography -->
+ <!ENTITY code-appendix SYSTEM "code.xml">
+   <!-- source code arrangement and coding convention appendix -->
  <!ENTITY concepts-chapter SYSTEM "concepts.xml">
    <!-- Pooma concepts chapter -->
  <!ENTITY data-parallel-chapter SYSTEM "data-parallel.xml">
***************
*** 228,235 ****
    <!-- 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 -->
  
--- 243,254 ----
    <!-- glossary -->
  <!ENTITY introductory-chapter SYSTEM "introduction.xml">
    <!-- Doof2d introductory chapter -->
! <!ENTITY preface-chapter SYSTEM "preface.xml">
!   <!-- preface -->
! <!ENTITY starting-chapter SYSTEM "starting.xml">
!   <!-- getting started chapter -->
! <!ENTITY template-appendix SYSTEM "template.xml">
!   <!-- template programming appendix -->
  <!ENTITY tutorial-chapter SYSTEM "tutorial.xml">
    <!-- Doof2d tutorial programs chapter -->
  
***************
*** 296,412 ****
   <!-- 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&nbsp;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&nbsp;D. Oldham, Ji Qiang, John
-    Reynders, Robert Ryne, Stephen Smith, M.&nbsp;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&nbsp;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;
  
--- 315,332 ----
   <!-- FINISH: May we have a short table of contents followed by a -->
   <!-- complete table of contents? -->
  
!  &preface-chapter;
  
  <![%unfinished;[
   <part id="programming">
    <title>Programming with &pooma;</title>
  
  <!-- FIXME: Add a partintro to the part above? -->
  ]]>  <!-- end unfinished -->
  
!   &starting-chapter;
  
!   &introductory-chapter; 
  
    &tutorial-chapter;
  
*************** a(I,J) = (1.0/9.0) *
*** 828,833 ****
--- 748,754 ----
    </chapter>
  
  
+ 
  <![%unfinished;[
    <chapter id="sequential">
     <title>Writing Sequential Programs</title>
*************** a(I,J) = (1.0/9.0) *
*** 1081,1086 ****
--- 1002,1009 ----
       architecture-specific initialization.  The function always
       returns &true;.</para>
  
+ HERE
+ 
       <para><function>initialize</function>'s alternative form
       assumes the &pooma;-specific and architecture-specific
       command-line arguments have already been removed from
*************** UNFINISHED</para>
*** 2395,2405 ****
  
      <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">
--- 2318,2328 ----
  
      <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">
*************** UNFINISHED</para>
*** 3754,4032 ****
  ]]>  <!-- 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>
  
  
--- 3677,3914 ----
  ]]>  <!-- end unfinished -->
  
  
!  &template-appendix;
  
!  &code-appendix;
  
  
!  <appendix id="uml">
!   <title>&uml; Class Diagrams</title>
  
!   <para>In this chapter, we present Unified Modeling Language (&uml;)
!   class diagrams.  These are created at the
!   <firstterm>specification</firstterm> level, which indicates the
!   software interface, not its implementation.  Readers interested in
!   the implementation are encouraged to read the corresponding source
!   code.  More extensive explanations of these classes appear in the
!   main chapters of this &book;.</para>
! 
!   <figure float="1" id="uml-explanation">
!    <title>Explanation of &uml; Class Diagrams</title>
!    <mediaobject>
!     <imageobject>
!      <imagedata fileref="figures/explanation-uml.1" format="EPS" align="center"></imagedata>
!     </imageobject>
!     <imageobject>
!      <imagedata fileref="figures/explanation-uml-1.png" format="PNG" align="center"></imagedata>
!     </imageobject>
!     <textobject>
!      <phrase>An Explanation of UML Class Diagrams</phrase>
!     </textobject>
!    </mediaobject>
!   </figure>
! 
!   <para><xref linkend="uml-explanation"></xref> illustrates a typical
!   &uml; class diagram.  The diagram has three classes:
!   <type>Classname1</type>, <type>Classname2</type>, and
!   <type>Classname2&lt;1&gt;</type>.  Most classes are represented by
!   three-part boxes.  The top part lists the class's name.  The middle
!   part lists public data members, if any.  Few &pooma; classes have
!   public data members so this section is frequently empty.  The bottom
!   part lists public member functions, if any.
!   <type>Classname2&lt;1&gt;</type> has only one part, not three.  Its
!   three-part box appears in another diagram, presumably because there
!   is not enough room in this one.  Both <type>Classname1</type> and
!   <type>Classname2</type> have template parameters, each named
!   <type>T</type>.  These occur in dashed boxes at the upper-right
!   corner of the class boxes.  Files implementing a class are listed at
!   the lower, right corner of the class's box; this is not standard UML
!   notation.</para>
! 
!   <para>Lines connect classes.  The solid arrow with large triangular
!   arrowhead indicates that <type>Classname2</type> is a subtype of
!   <type>Classname1</type>.  Since this diagram represents the
!   specification level, subtyping does not necessarily correspond to
!   &cc; type inheritance.  Also, subtype class boxes need only list
!   members not available in the supertype.  For this case,
!   <type>Classname2</type> has no new members not provided by
!   <type>Classname1</type>.  A dashed arrow indicates a class formed by
!   a template instantiation.  The class name indicates which template
!   parameters are bound.  For example, <type>Classname2&lt;1&gt;</type>
!   instantiates <type>Classname2</type> with <type>T</type> equal
!   to&nbsp;1.</para>
! 
!   <para>These diagrams omit a lot of details.  Private and protected
!   data members are not listed.  Compile-time types and values are not
!   listed.  No indication is given of the actual implementation.</para>
! 
  
+   <section id="uml-arrays">
+    <title>&array;s</title>
+ 
+    <figure float="1" id="uml-array_dynamicarray">
+     <title>Relationship Between &array; and &dynamicarray;s</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="figures/array-uml.1" format="EPS" align="center"></imagedata>
+      </imageobject>
+      <imageobject>
+       <imagedata fileref="figures/array-uml-1.png" format="PNG" align="center"></imagedata>
+      </imageobject>
+      <textobject>
+       <phrase>&dynamicarray;s are subtypes of &array;s</phrase>
+      </textobject>
+     </mediaobject>
+    </figure>
     
!    <para>Both &array;s and &dynamicarray;s have so many member
!    functions that their class boxes appear in separate diagrams.
!    <xref linkend="uml-array_dynamicarray"></xref> indicates that
!    &dynamicarray;s are subtypes of &array;s.  Both have value type and
!    engine tag template parameters but &dynamicarray;'s dimension must
!    be one.</para>
! 
!    <figure float="1" id="uml-array">
!     <title>&array; Diagram</title>
!     <mediaobject>
!      <imageobject>
!       <imagedata fileref="figures/array-uml.2" format="EPS" align="center"></imagedata>
!      </imageobject>
!      <imageobject>
!       <imagedata fileref="figures/array-uml-2.png" format="PNG" align="center"></imagedata>
!      </imageobject>
!      <textobject>
!       <phrase>&array; Class Diagram</phrase>
!      </textobject>
!     </mediaobject>
!    </figure>
! 
!    <figure float="1" id="uml-dynamicarray">
!     <title>&dynamicarray; Diagram</title>
!     <mediaobject>
!      <imageobject>
!       <imagedata fileref="figures/array-uml.3" format="EPS" align="center"></imagedata>
!      </imageobject>
!      <imageobject>
!       <imagedata fileref="figures/array-uml-3.png" format="PNG" align="center"></imagedata>
!      </imageobject>
!      <textobject>
!       <phrase>&dynamicarray; Class Diagram</phrase>
!      </textobject>
!     </mediaobject>
!    </figure>
!   </section>
  
  
!   <section id="uml-domains">
!    <title>&domain;s</title>
  
!    <para>&domain;s and its subtypes are shown in <xref
!    linkend="uml-domains_figure"></xref>.  All classes are instantiated
!    from or subtypes of &domain;.  As mentioned in <xref
!    linkend="arrays-domains"></xref>, the <type>Domain&lt;1&gt;</type>
!    template instantiation has additional member functions.  It uses
!    the <type>Domain&lt;1&gt;::iterator</type>.  The four &domain;
!    subtypes appear in the bottom half of the figure.  Each requires
!    the same template parameter as &domain;.  Each of these has a
!    template instantiation for the one-dimensional case.  We omit
!    listing their additional member functions since these are the same
!    as for <type>Domain&lt;1&gt;</type>.</para>
! 
!    <figure float="1" id="uml-domains_figure">
!     <title>&domain;s</title>
!     <mediaobject>
!      <imageobject>
!       <imagedata fileref="figures/domain-uml.1" format="EPS" align="center"></imagedata>
!      </imageobject>
!      <imageobject>
!       <imagedata fileref="figures/domain-uml-1.png" format="PNG" align="center"></imagedata>
!      </imageobject>
!      <textobject>
!       <phrase>&domain;s</phrase>
!      </textobject>
!     </mediaobject>
!    </figure>
!    
    </section>
+ 
+ 
+   <section id="uml-engines">
+    <title>&engine;s</title>
+ 
+    <para>&engine;s and its subtypes are shown in <xref
+    linkend="uml-engines-figure"></xref>.  Five subtypes of &engine;s
+    are shown.  Details appear in subsequent diagrams.  The
+    <type>Engine</type> class box shows no members because it has no
+    members.  Only subtypes have members.  More explanation of these
+    classes can be found in <xref linkend="engines"></xref>.  The
+    implementation files in <xref
+    linkend="uml-engines-brick_figure"></xref> use the
+    <literal>[1-7]</literal> regular expression to indicate 1, 2,
+    &hellip;, or&nbsp;7.</para>
+ 
+    <figure float="1" id="uml-engines-figure">
+     <title>&engine;s</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml.1" format="EPS" align="center"></imagedata>
+      </imageobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml-1.png" format="PNG" align="center"></imagedata>
+      </imageobject>
+      <textobject>
+       <phrase>Relationships among &engine;s</phrase>
+      </textobject>
+     </mediaobject>
+    </figure>
+ 
+    <figure float="1" id="uml-engines-brick_figure">
+     <title>&brick; and &compressiblebrick; &engine;s</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml.2" format="EPS" align="center"></imagedata>
+      </imageobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml-2.png" format="PNG" align="center"></imagedata>
+      </imageobject>
+      <textobject>
+       <phrase>&brick; and &compressiblebrick; &engine;s</phrase>
+      </textobject>
+     </mediaobject>
+    </figure>
+ 
+    <figure float="1" id="uml-engines-dynamic_figure">
+     <title>&dynamic; and &multipatch; &engine;s</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml.3" format="EPS" align="center"></imagedata>
+      </imageobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml-3.png" format="PNG" align="center"></imagedata>
+      </imageobject>
+      <textobject>
+       <phrase>&dynamic; and &multipatch; &engine;s</phrase>
+      </textobject>
+     </mediaobject>
+    </figure>
+ 
+    <figure float="1" id="uml-engines-remote_figure">
+     <title>&remote; &engine;s</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml.4" format="EPS" align="center"></imagedata>
+      </imageobject>
+      <imageobject>
+       <imagedata fileref="figures/engine-uml-4.png" format="PNG" align="center"></imagedata>
+      </imageobject>
+      <textobject>
+       <phrase>&remote; &engine;s</phrase>
+      </textobject>
+     </mediaobject>
+    </figure>
+    
+   </section>
+    
   </appendix>
  
  
Index: preface.xml
===================================================================
RCS file: preface.xml
diff -N preface.xml
*** /dev/null	Fri Mar 23 21:37:44 2001
--- preface.xml	Tue Feb 26 20:44:27 2002
***************
*** 0 ****
--- 1,384 ----
+  <preface id="preface">
+   <title>Preface</title>
+ 
+   <para>The &poomatoolkit; enables scientists and engineers to quickly
+   translate scientific algorithms into efficient programs.  The
+   &toolkit;'s containers facilitate storing and computing arrays of
+   values by supporting element-wise, data-parallel, and stencil-based
+   computations.  The &toolkit; automatically handles all
+   interprocessor communication so the same &pooma; program can
+   efficiently execute on a uniprocessor workstation or a supercomputer
+   with thousands of processors.  Thus, its creator can concentrate on
+   the algorithms rather than their implementation details.</para>
+ 
+   <para>&pooma; programs are written in &cc;.  Scientists and
+   engineers can use their existing knowledge of &cc; and need only
+   learn a few &pooma; concepts rather than having to learn a whole new
+   language.  The easy-to-use &pooma; interface hides sophisticated
+   &cc; code.  For example, a &pooma; programmer can use a simple
+   data-parallel statements such as<programlisting>
+ &initialspace;double x; vector<1> v1(10000), v2(10000), v3(10000);
+ &initialspace;x = sum(v1 * sin(v2) - exp(v3));
+ </programlisting>
+   and expect them to run efficiently without ever being aware of the
+   underlying state-of-the-art expression template technology.</para>
+ 
+   <para>This &book; is aimed at scientists and engineers who want to
+   quickly translate scientific algorithms into efficient programs
+   running on one or thousands of processors.  Although we will outline
+   some scientific algorithms, no scientific background is required.
+   Readers will need to be familiar with &cc;, the language in which
+   &pooma; programs are written.  Classes, objects, function objects,
+   template classes, and template functions will all be used.  Appendix
+   <!-- FIXME: Add appendix reference --> FIXME contains a short
+   introduction to template programming.  Readers needing more
+   background material might want to read Koenig and Moo's
+   <emphasis>Accelerated &cc;</emphasis>, Stanley Lippman's
+   <emphasis>&cc; Primer</emphasis>, Bjarne Stroustrup's <emphasis>The
+   &cc; Programming Language</emphasis>, or the first half of Barton
+   and Nackman's <emphasis>Scientific and Engineering &cc;</emphasis>.
+   <!-- FIXME: Add references. -->
+   </para>
+ 
+   <para>Readers of this book will learn how to use the &poomatoolkit;
+   to implement scientific algorithms.  Since &pooma; offers classes
+   and functions corresponding to common scientific concepts, &pooma;
+   users will
+   <itemizedlist>
+     <listitem>
+      <para>spend significantly less time programming,</para>
+     </listitem>
+     <listitem>
+      <para>write programs that are typically one-tenth the length of
+      comparable &c; and &fortran; programs,</para>
+     </listitem>
+     <listitem>
+      <para>require much less time to debug programs, and</para>
+     </listitem>
+     <listitem>
+      <para>will be able to port their programs to a wide variety of
+      platforms without changing them.</para>
+     </listitem>
+   </itemizedlist>
+   Those wishing to learn how to write parallel or distributed programs
+   will learn the fundamental concepts and see how easy it is to write
+   the programs.  Readers interested in advanced &cc; techniques will
+   see how these techniques, theoretically presented elsewhere, are
+   actually used in practice.  We hope all our readers will be
+   intrigued by the power of &pooma;'s technology they will peek under
+   the hood to see how the &toolkit; uses &cc;'s features.</para>
+ 
+ 
+   <section id="preface-reading_book:">
+    <title>How to Read This &bookcap;</title>
+ 
+    <para>Each chapter of this book introduces a new concept, using it
+    to convert an algorithm into a program.  It continues by describing
+    the concept's interface, illustrating these with code fragments or
+    short programs, and concludes with a detailed listing of the
+    classes, functions, member functions, etc.  All too frequently in
+    &cc;, two concepts are interrelated so describing one also requires
+    describing the other.  Thus, these detailed listings may refer to
+    material presented in future chapters.</para>
+ 
+    <para>A few sections marked with <quote>dangerous bend</quote>
+    signs contain advanced material not necessary to understand when
+    initially learning &pooma;.  I recommend skipping these sections on
+    your first reading of this &book;.</para>
+ 
+    <para>One need not read every chapter to write sophisticated
+    &pooma; programs.  Here is a brief sketch of what is in the
+    remaining chapters and appendices:
+    <variablelist>
+      <varlistentry>
+       <term>Getting Started with &pooma;</term>
+       <listitem>
+        <para>describes how to download and compile the
+        &poomatoolkit;.  It then presents a <quote>Hello, &pooma;</quote>
+        program, explaining how to compile and run it.
+        Impatient readers who already have a working &poomatoolkit; may
+        wish to skip this chapter.</para>
+ <!-- dangerous bend: configuration options -->
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>&array; Containers</term>
+       <listitem>
+        <para>implement the concept of a mathematical array which is a
+        map from indices in a domain to values.  This container is
+        the most fundamental &pooma; type.  We explain how to
+        create and use these maps.  All subsequent chapters depend on
+        understanding &array;s.  <!-- dangerous bend: stencils --><!--
+        dangerous bend: DynamicArrays --></para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>&vector;s, &matrix;s, and &tensor;s</term>
+       <listitem>
+        <para>are three classes implementing the corresponding
+        mathematical concepts.  If your algorithm uses these
+        mathematical concepts, read this chapter.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Data-Parallel Expressions</term>
+       <listitem>
+        <para>operate on multiple values.  Many scientific algorithms
+        use these concepts so all &pooma; containers support them.  For
+        example, values in two &array;s <literal>a</literal> and
+        <literal>b</literal> can be added element-wise using an
+        expression as simple as <literal>a+b</literal>, omitting the
+        need for any indexing or loops.  A dangerous-bend section
+        describes the underlying &pete; technology making this
+        possible.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Domains</term>
+       <listitem>
+        <para>specify containers' sets of permitted indices.  They are
+        used when creating new containers and taking views of existing
+        containers.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Container Views</term>
+       <listitem>
+        <para>are themselves containers having domains that are subsets
+        of other containers' domains.  Combining them with
+        data-parallel programs yields &pooma;'s powerful notation to
+        implement algorithms.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>&engine;s</term>
+       <listitem>
+        <para>store and compute data for containers.  If containers are
+        like cars, engines are the things that make them go.  Most
+        &pooma; users need not look under the hood at &engine;s, but
+        those interested in optimizing their use of &pooma; or seeing
+        one of the fundamental &pooma; concepts will be interested.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Distributed Computation</term>
+       <listitem>
+        <para>involves distributing a program's data and computation
+        among all available processors, ranging in number from one to
+        thousands.  We present the &pooma; concepts of partitioning and
+        distributing data while relying on the &toolkit; and a
+        communication library to automatically move all data among
+        processors.  We show that converting a sequential program into
+        a distributed program can be as easy as adding three lines of
+        code.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>&field; Containers</term>
+       <listitem>
+        <para>extend the concept of an &array; to three-dimensional
+        space.  This is the most powerful &pooma; abstraction.
+        Multiple values can be treated as residing at the same
+        location, and relations support lazy evaluation, where one
+        field's values can be automatically updated whenever another
+        field's values change.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Appendix: Template Programming</term>
+       <listitem>
+        <para>describes using &cc; templates in &pooma; programs.  &cc;
+        programmers with little experience in using templates will want
+        to read this appendix before reading about &array;s.  A
+        dangerous-bend section will interest &cc; programmers desiring
+        an overview of all the template programming ideas used to
+        implement &pooma;.</para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
+ 
+   </section>
+ 
+ 
+   <section id="preface-downloading">
+    <title>Obtaining, Using, and Modifying &pooma;</title>
+ 
+    <para>The &poomatoolkit; is open-source software.  Anyone may
+    download, read, redistribute, or modify the &pooma; source code.
+    Here we briefly describe how to download, configure, and compile
+    the &poomatoolkit; for UNIX operating systems.  Instructions for
+    Microsoft Windows and Mac users as well as more details appear in
+    the subsequent chapter.  Those wanting to run distributed &pooma;
+    programs should also read the subsequent chapter.</para>
+ 
+    <para>Obtain the &pooma; source code <filename
+    path="http://www.codesourcery.com/pooma/downloads_folder/">&poomasourcefile;</filename>
+    from the &pooma; download page (&poomadownloadpage;) available off
+    the &pooma; home page (&poomahomepage;).  The <quote>tgz</quote>
+    indicates this is a compressed tar archive file.  To extract the
+    source files, use <command>tar xzvf &poomasourcefile;</command>.
+    Move into the source code directory <filename
+    class="directory">&poomasource;</filename> directory; e.g.,
+    <command>cd &poomasource;</command>.</para>
+ 
+    <para>Configuring the source code determines the file and program
+    names needed for compilation.  First, determine a configuration
+    file in the <filename class="directory">config/arch/</filename>
+    directory corresponding to your operating system and compiler.  For
+    example, <filename class="libraryfile">LINUXgcc.conf</filename>
+    supports compiling under a &linux; operating system with &gpp;,
+    while <filename class="libraryfile">SGI64KCC.conf</filename>
+    supports compiling under a 64-bit <application>SGI</application>
+    Irix operating system <!-- FIXME: Center the following command. -->
+    with &kcc;.  Next, configure the source code:<programlisting>
+ &initialspace;./configure &dashdash;arch LINUXgcc &dashdash;opt &dashdash;suite LINUXgcc-opt
+ </programlisting>.  The architecture argument to the
+    <command>&dashdash;arch</command> option is the name of the
+    corresponding configuration file, omitting its <filename
+    class="libraryfile">.conf</filename> suffix.  The
+    <command>&dashdash;opt</command> indicates the &poomatoolkit; will
+    contain optimized source code, which makes the code run more
+    quickly but may impede debugging.  Alternatively, use the
+    <command>&dashdash;debug</command> option which supports debugging.
+    The <glossterm linkend="glossary-suite_name">suite name</glossterm>
+    can be any arbitrary string.  We chose
+    <command>LINUXgcc-opt</command> to remind us of the architecture
+    and optimization choice.  <filename
+    class="libraryfile">configure</filename> creates subdirectories
+    named <quote>LINUXgcc-opt</quote> for use when compiling the source
+    files.  Comments at the beginning of <filename
+    class="libraryfile">lib/</filename><replaceable>suiteName</replaceable><filename>/PoomaConfiguration.h</filename>
+    record the configuration arguments.</para>
+ 
+    <para>To compile the source code, set the <envar>POOMASUITE</envar>
+    environment variable to the suite name and then type
+    <command>make</command>.  To set the environment variable for the
+    <!-- FIXME: Center the following command. -->
+    <application>bash</application> shell use <programlisting>
+ &initialspace;export POOMASUITE=suiteName
+ </programlisting>substituting the suite name's <replaceable>suiteName</replaceable>.
+    <!-- FIXME: Center the following command. --> For the
+    <application>csh</application> shell, use <programlisting>
+ &initialspace;setenv POOMASUITE LINUXgcc-opt
+ </programlisting>  Issuing the
+    <command>make</command> command compiles the &pooma; source code
+    files to create the &pooma; library.  The &pooma; makefiles assume
+    the <trademark>GNU</trademark> &make; is available so substitute
+    the proper command to run <trademark>GNU</trademark> &make; if
+    necessary.  The &pooma; library can be found in, e.g., <filename
+    class="libraryfile">lib/LINUXgcc-opt/libpooma-gcc.a</filename>.</para>
+ 
+    <para>Anyone may modify the &pooma; source code.  If an application
+    requires a specialized container not already available, any
+    programmer may add it.  Any programmer can extend it to solve
+    problems in previously unsupported domains.  Companies using the
+    &toolkit; can read the source code to ensure it has no security
+    holes.  It may be downloaded at no cost and used for perpetuity.
+    There are no annual licenses and no on-going costs.  Users are
+    guaranteed the software will never disappear.  In summary, the
+    &poomatoolkit; is low-risk software.</para>
+   </section>
+ 
+ 
+   <section id="preface-pooma_history">
+    <title>History of &pooma;</title>
+ 
+    <para>The &poomatoolkit; was developed at Los Alamos National
+    Laboratory to assist nuclear fusion and fission research.
+    In&nbsp;1994, it grew out of the <application
+    class='software'>Object-Oriented Particle Simulation</application>
+    Class Library developed for particle-in-cell simulations.  The
+    goals of the Framework, as it was called at the time, were driven
+    by the Numerical Tokamak's <quote>Parallel Platform
+    Paradox</quote>:<blockquote>
+      <para>The average time required to implement a moderate-sized
+      application on a parallel computer architecture is equivalent to
+      the half-life of the latest parallel supercomputer.</para>
+     </blockquote>The framework's goal of being able to quickly write efficient
+    scientific programs that could be run on a wide variety of platforms
+    remains unchanged today.  Development, mainly at the Advanced
+    Computing Laboratory at Los Alamos, proceeded rapidly.  A matrix
+    solver application was written using the framework.  <!-- FIXME:
+    Add citation to pooma-sc95. --> Support for hydrodynamics, Monte
+    Carlo simulations, and molecular dynamics modeling soon
+    followed.</para>
+ 
+    <para id="preface-pooma_history-asci">By&nbsp;1998, &pooma;
+    was part of the U.S. Department of Energy's Accelerated Strategic
+    Computing Initiative (<acronym>ASCI</acronym>).  The Comprehensive
+    Test Ban Treaty forbid nuclear weapons testing so they were instead
+    simulated using computers.  <acronym>ASCI</acronym>'s goal was to
+    radically advance the state of the art in high-performance
+    computing and numerical simulations so the nuclear weapon
+    simulations could use 100-teraflop parallel computers.  The linear
+    accelerator code <application class='software'>linac</application>
+    and the Monte Carlo neutron transport code <application
+    class='software'>MC++</application> were among the codes written.
+    <!-- FIXME: Add citation to pooma-siam98. --></para>
+ 
+    <para>&pooma;&nbsp;2 involved a new conceptual framework and a
+    complete rewriting of the source code to improve performance.  The
+    <!-- FIXME: Add a citation to iscope98.pdf. --> &array; class was
+    introduced with its use of engines, separating container use from
+    container storage.  A new asynchronous scheduler permitted
+    out-of-order execution to improve cache coherency.  Incorporating
+    the <application class="software">Portable Expression Template
+    Engine</application> (<acronym>PETE</acronym>) permitted faster
+    loop execution.  Soon, container views and
+    <type>ConstantFunction</type> and <type>IndexFunction</type>
+    &engine;s were added.  Release&nbsp;2.1.0 included &field;s with
+    their spatial extent and &dynamicarray;s with the ability to
+    dynamically change domain size.  Support for particles and their
+    interaction with &field;s were added.  The &pooma; messaging
+    implementation was revised in release&nbsp;2.3.0.  Use of the
+    &cheetah; Library separated &pooma; from the actual messaging
+    library used, and support for applications running on clusters of
+    computers was added.  <ulink
+    url="http://www.codesourcery.com/">CodeSourcery, LLC</ulink>, and
+    <ulink url="http://www.proximation.com/">Proximation, LLC</ulink>,
+    took over &pooma; development from Los Alamos National Laboratory.
+    During the past two years, the &field; abstraction and
+    implementation was improved to increase its flexibility, add
+    support for multiple values and materials in the same cell, and
+    permit lazy evaluation.  Simultaneously, the execution speed of the
+    inner loops was greatly increased.</para>
+   </section>
+ 
+ 
+   <section id="preface-acknowledgements">
+    <title>Acknowledgements</title>
+ 
+    <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&nbsp;D. Oldham, Ji Qiang, John
+    Reynders, Robert Ryne, Stephen Smith, M.&nbsp;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, Amit Patel,
+    and Stephen Smith who answered my many questions during the writing
+    of this &book;.  Thanks to Deborah Lafferty of Addison-Wesley
+    Longman, who encouraged me and guided me throughout writing and
+    publishing this &book;.</para>
+ 
+   <!-- We cheat and abuse an epigraph here. -->
+   <epigraph>
+    <attribution>Jeffrey&nbsp;D. Oldham, 2002&nbsp;February</attribution>
+    <para></para>
+   </epigraph>
+ 
+   </section>
+ 
+  </preface>
Index: starting.xml
===================================================================
RCS file: starting.xml
diff -N starting.xml
*** /dev/null	Fri Mar 23 21:37:44 2001
--- starting.xml	Tue Feb 26 20:44:27 2002
***************
*** 0 ****
--- 1,941 ----
+  <chapter id="initial">
+   <title>Getting Started with &pooma;</title>
+ 
+   <para>In this chapter, we describe how to obtain &pooma;, prepare it
+   for use, and then compile a <quote>Hello, &pooma;</quote>
+   program.  Impatient readers will find the first section helpful.
+   Those desiring more details will find this section provides a useful
+   overview of the chapter.</para>
+ 
+ 
+   <section id="initial-quick_start">
+    <title>Getting Started for Impatient Users</title>
+ 
+    <para>This section is designed for impatient, UNIX-literate readers
+    who wish to start using &pooma; as quickly as possible.  We
+    describe how to obtain, configure, compile, and use the
+    &toolkit; with a minimum of explanation.</para>
+ 
+    <variablelist>
+     <varlistentry>
+      <term>Download</term>
+      <listitem>
+       <para>Download <filename
+       path="http://www.codesourcery.com/pooma/downloads_folder/">&poomasourcefile;</filename>
+       from the &pooma; download page (&poomadownloadpage;).
+       Uncompress and extract the source code:<programlisting>
+ &initialspace;tar xzvf &poomasourcefile;
+ </programlisting> Move into the directory containing the source code:<programlisting>
+ &initialspace;cd <filename class="directory">&poomasource;</filename>
+ </programlisting></para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>Configure</term>
+      <listitem>
+       <para>To create files necessary for compiling, use <programlisting>
+ &initialspace;./configure &dashdash;arch <replaceable>architecture</replaceable> &dashdash;opt
+ </programlisting> where <replaceable>architecture</replaceable>
+       indicates the operating system and compiler.  Permitted choices
+       are the names of files in the <filename
+       class="directory">config/arch/</filename> subdirectory omitting
+       the <filename class="libraryfile">.conf</filename> suffix.</para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>Compilation of the Library</term>
+      <listitem>
+       <para>Create the &pooma; library file by first setting the
+       <envar>POOMASUITE</envar> environment variable to the
+       architecture's name and then compiling the source code:<programlisting>
+ &initialspace;export POOMASUITE=<replaceable>architecture</replaceable>
+ &initialspace;make
+ </programlisting></para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>Compiling Programs</term>
+      <listitem>
+       <para>We illustrate compiling the <quote>Hello, &pooma;</quote>
+       program available at <filename
+       class="libraryfile">examples/Manual/Sequential/initialize-finalize.cpp</filename>:<programlisting>
+ &initialspace;export POOMAHOME=/home/oldham/pooma/pooma1
+ &initialspace;g++ -I${POOMAHOME}/src -I${POOMAHOME}/lib/${POOMASUITE} initialize-finalize.cpp -o initialize-finalize -L${POOMAHOME}/lib/${POOMASUITE} -lpooma-gcc
+ </programlisting>
+       The environment variable indicates the location of the &toolkit;
+       header files and the library.</para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </section>
+ 
+ 
+   <section id="initial-obtain">
+    <title>Obtaining &pooma;</title>
+ 
+    <para>&pooma; is open-source software, freely available via the
+    Internet or perhaps packaged with this &book;.  <ulink
+    url="http://www.codesourcery.com/">CodeSourcery, LLC,</ulink>
+    currently hosts the &poomatoolkit; source code.  Download the the
+    &pooma; source code <filename
+    path="http://www.codesourcery.com/pooma/downloads_folder/">&poomasourcefile;</filename>
+    from the &pooma; download page (&poomadownloadpage;) available off
+    the &pooma; home page (&poomahomepage;).  The <quote>tgz</quote>
+    indicates this is a compressed tar archive file.  For a UNIX
+    operating system, one can extract the source files using the
+    command <command>tar xzvf &poomasourcefile;</command>.
+ <!-- FIXME: Make source code available for Windows and Mac users.
+    Describe how to unpack the files. --></para>
+ 
+    <!-- FIXME: Add a dangerous bend section describing how to download
+    sources from CVS. -->
+   </section>
+ 
+ 
+   <section id="initial-compile">
+    <title>Compiling the &pooma; Library</title>
+ 
+    <para>Most of the &poomatoolkit; source code is available in header
+    files containing template class definitions.  A few files are
+    compiled and collected together into the &pooma; library.</para>
+ 
+    <para>Before the &pooma; &toolkit; may be compiled, it must be
+    <firstterm>configured</firstterm>.  Configuration creates files
+    used during compilation that are specific to the particular
+    operating system, compiler, and available libraries that are to be
+    used.  The configuration files in the <filename
+    class="directory">config/arch/</filename> directory correspond to
+    supported operating systems and compilers.  For example, <filename
+    class="libraryfile">LINUXgcc.conf</filename> supports compiling
+    under a Linux operating system with &gcc; (really &gpp;).
+    <filename class="libraryfile">SGI64KCC.conf</filename> supports
+    compiling under a 64-bit <application>SGI</application> Irix
+    operating system with &kcc;.</para>
+ 
+    <para>To configure the source code, use a command
+    like<programlisting> &initialspace;./configure &dashdash;arch
+    LINUXgcc &dashdash;opt &dashdash;suite LINUXgcc-opt
+    </programlisting> The architecture argument to the
+    <command>&dashdash;arch</command> option is the name of the
+    corresponding configuration file, omitting its <filename
+    class="libraryfile">.conf</filename> suffix.  The
+    <command>&dashdash;opt</command> indicates the &poomatoolkit; will
+    contain optimized source code, which makes the code run more
+    quickly but may impede debugging.  Alternatively, use the
+    <command>&dashdash;debug</command> option which supports debugging.
+    The <glossterm linkend="glossary-suite_name">suite name</glossterm>
+    can be any arbitrary string.  We chose
+    <literal>LINUXgcc-opt</literal> to remind us of the architecture
+    and optimization choice.  <filename
+    class="libraryfile">configure</filename> creates subdirectories
+    named <quote>LINUXgcc-opt</quote> for use when compiling the source
+    files.  Comments at the beginning of <filename
+    class="libraryfile">lib/<replaceable>suiteName</replaceable>/PoomaConfiguration.h</filename>
+    record the configuration arguments.</para>
+ 
+    <para>To create the &pooma; library, the &toolkit; source files
+    need to be compiled.  Specify the desired suite by setting the
+    <envar>POOMASUITE</envar> environment variable to the appropriate
+    value.  For example, if using the <application>bash</application>
+    shell, use<programlisting> &initialspace;export
+    POOMASUITE=<replaceable>suiteName</replaceable> </programlisting>
+    substituting the suite name's <replaceable>suiteName</replaceable>.
+    If using the <application>csh</application> shell,
+    use<programlisting> &initialspace;setenv POOMASUITE
+    <replaceable>suiteName</replaceable> </programlisting> In the
+    previous paragraph, the suite name is
+    <literal>LINUXgcc-opt</literal> so we would issue the
+    statement<programlisting> &initialspace;setenv POOMASUITE
+    LINUXgcc-opt </programlisting></para>
+ 
+    <para>Issuing the <command>make</command> command compiles the
+    &pooma; source code files to create the &pooma; library.  The
+    &pooma; makefiles assume the <trademark>GNU</trademark> &make; is
+    available so substitute the proper command to run
+    <trademark>GNU</trademark> &make; if necessary.  As each source
+    file is compiled, a line is printed.  If the compilation succeeds,
+    the &pooma; library can be found in, e.g., <filename
+    class="libraryfile">lib/LINUXgcc-opt/libpooma-gcc.a</filename>.  If
+    it fails, the makefiles will print a line indicating which file
+    failed to compile.  Reading the corresponding <filename
+    class="libraryfile">.info</filename> may indicate what
+    failed.</para>
+ 
+    <para>The same &pooma; source code can support multiple suites as
+    long as different names are used.  For example, we could have
+    <literal>LINUXgcc-opt</literal> and
+    <literal>LINUXgcc-debug</literal> suites.  Both of these might
+    specify use of the Linux operating system and &gcc;, but one could
+    have optimized code corresponding to the configuration option
+    <command>&dashdash;opt</command> and the other could have
+    debuggable code corresponding to the configuration option
+    <command>&dashdash;debug</command>.  When compiling both the
+    library and user code, the <envar>POOMASUITE</envar> environment
+    variable indicates which suite to use.</para>
+ 
+ 
+    <section id="initial-compile-configuration_options">
+     <title>&danger;: Configuration Options</title>
+ 
+     <para>(Are you sure you should be reading this section?  The
+     &danger; in the title is meant to warn you about material that
+     ought to be skipped on the first reading.  And maybe also on the
+     second reading.  The reader-beware paragraphs sometimes refer to
+     concepts that aren't explained until later chapters.  (Thanks to
+     Donald&nbsp;E. Knuth for the concept of &danger; sections and for
+     the preceding text.))</para>
+ 
+     <para>The configuration script supports many more command-line
+     options than the two used above, but few &pooma; users need use
+     them except those using distributed &pooma;, which are described
+     below.  <command>/configure -h</command> yields a complete list.
+     We describe also describe them here.</para>
+ 
+     <table frame="none" colsep="0" rowsep="0" tocentry="1"
+            orient="port" pgwide="0" id="initial-compile-configuration_options-table">
+      <title>Configuration Options</title>
+      
+      <tgroup cols="2" align="left">
+        <thead>
+ 	<row>
+ 	 <entry>option</entry>
+ 	 <entry>description</entry>
+ 	</row>
+        </thead>
+        <tbody valign="top">
+ 	<row rowsep="1">
+ 	 <entry>Architecture and Installation Choices</entry>
+ 	</row>
+ 	<row>
+ 	 <entry><literal>&dashdash;arch <replaceable>architecture</replaceable></literal></entry>
+ 	 <entry>specify the desired operating system and compiler.
+ 	 <replaceable>architecture</replaceable> should correspond to
+ 	 a file in <filename class="directory">config/arch/</filename>
+ 	 omitting the <filename class="libraryfile">.conf</filename> suffix.</entry>
+ 	</row>
+ 	<row>
+ 	 <entry><literal>&dashdash;suite
+ 	 <replaceable>suite</replaceable></literal></entry>
+ 	 <entry>specify a name for the this particular configuration.
+ 	 The environment variable <envar>POOMASUITE</envar>'s value
+ 	 should equal <replaceable>suite</replaceable> when compiling
+ 	 the library.  <replaceable>suite</replaceable> can be any
+ 	 string that an serve as a filename.  If this option is
+ 	 omitted, the <literal>&dashdash;arch</literal> architecture
+ 	 is used.</entry>
+ 	</row>
+        <row>
+ 	<entry><literal>&dashdash;prefix
+ 	 <replaceable>directory</replaceable></literal></entry>
+ 	<entry>indicates the directory where files are installed.
+ 	 <command>make install</command> should be invoked after
+ 	 compiling the library.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Debugging and Optimization Choices</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;opt</literal></entry>
+ 	<entry>causes an optimized library to be built.  Optimized
+ 	code typically runs faster than unoptimized code, but
+ 	debugging can be inhibited.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;debug</literal></entry>
+ 	<entry>causes an debuggable library to be built.  That is, a
+ 	debugger will be able to traverse library code.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Compiler Choices</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;cpp <replaceable>compiler</replaceable></literal></entry>
+ 	<entry>specifies the &cc; compiler to use.  The default value
+ 	is specified by the architecture configuration file.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;c <replaceable>compiler</replaceable></literal></entry>
+ 	<entry>specifies the &c; compiler to use when compiling &c;
+ 	executables.  Such executables usually are example programs.
+ 	The default value is specified by the architecture
+ 	configuration file.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;f77 <replaceable>compiler</replaceable></literal></entry>
+ 	<entry>specifies the &fortran;77 compiler to use.  The default value
+ 	is specified by the architecture configuration file.
+         <!-- FIXME: Where are any such compilers? -->
+         </entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;ar
+ 	<replaceable>archiver</replaceable></literal></entry>
+ 	<entry>specifies the library archiver to use when creating a
+ 	static library.  The default value is specified by the
+ 	architecture configuration file.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;link <replaceable>linker</replaceable></literal></entry>
+ 	<entry>specifies the linker to use when creating &pooma;
+ 	executables.  The default value, usually the same as the &cc;
+ 	compiler, is specified by the architecture configuration
+ 	file.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Compiler Options</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;static</literal></entry>
+ 	<entry>creates a static library that will be directly linked
+ 	into executables, rather than loaded dynamically.  Compare
+ 	with the <literal>&dashdash;shared</literal> option.  This
+ 	option is a default.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;shared</literal></entry>
+ 	<entry>creates a library that will be dynamically loaded when
+ 	a &pooma; executable starts.  It is the executable user's
+ 	responsibility to configure the operating system so the
+ 	library will be found, e.g., by setting the
+ 	<envar>LD_LIBRARY_PATH</envar> environment variable.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;v</literal></entry>
+ 	<entry>enables verbose output from the compiler and linker.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;q</literal></entry>
+ 	<entry>disables verbose output from the compiler and linker.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;strict</literal></entry>
+ 	<entry>enables ANSI &cc; conformance checking by the compiler.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;inc
+ 	<replaceable>directory</replaceable></literal></entry>
+ 	<entry>causes
+ 	<command>-I<replaceable>directory</replaceable></command>
+ 	options to be passed to the compiler.  These indicate
+ 	directories where header files are located.  This option may
+ 	be specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;def <replaceable>definition</replaceable></literal></entry>
+ 	<entry>causes
+ 	<command>-D<replaceable>definition</replaceable></command>
+ 	options to be passed to the compiler.  These define
+ 	preprocessor symbols.  This option may be specified
+ 	repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;cpparg
+ 	<replaceable>arguments</replaceable></literal></entry>
+ 	<entry>specifies &cc; compiler options.  This option may be
+ 	specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;carg
+ 	<replaceable>arguments</replaceable></literal></entry>
+ 	<entry>specifies &c; compiler options.  This option may be
+ 	specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;f77arg
+ 	<replaceable>arguments</replaceable></literal></entry>
+ 	<entry>specifies &fortran;77 compiler options.  This option may be
+ 	specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;ararg
+ 	<replaceable>arguments</replaceable></literal></entry>
+ 	<entry>specifies archiver options.  This option may be
+ 	specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;linkarg
+ 	<replaceable>arguments</replaceable></literal></entry>
+ 	<entry>specifies linker options.  This option may be
+ 	specified repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;oneper</literal></entry>
+         <entry>enables the one-per-template-instantiation compiler
+ 	option.  The &kcc; compiler requires this option to avoid
+         problems from instantiating the same template class
+         repeatedly.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;noonper</literal></entry>
+ 	<entry>disables the one-per-template-instantiation compiler
+ 	option.  See <command>&dashdash;oneper</command>
+ 	description.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Code Checking</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;bounds</literal></entry>
+ 	<entry>turns on bound checking for indexing operations.  That
+ 	is, indexes into a &container; (<literal>a(3,4)</literal>) are
+ 	checked to be in the domain.  This option is not the default
+ 	because it slows each access but is useful when checking
+ 	program correctness.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;insure</literal></entry>
+ 	<entry>enables <application
+ 	class="software">Insure++</application> code checking.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;purify</literal></entry>
+ 	<entry>enables <application
+ 	class="software">Purify</application> code checking.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Language Choices</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;ex</literal></entry>
+ 	<entry>enables use of exceptions if available.  Only one of this
+ 	xor the <command>&dashdash;noex</command> option should be
+ 	specified.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;noex</literal></entry>
+ 	<entry>disables use of exceptions.  Only one of this
+ 	xor the <command>&dashdash;ex</command> option should be
+ 	specified.</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;arch-specific-functions</literal></entry>
+ 	<entry>enables the use of architecture-specific initialization
+ 	functions.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Library Options</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;preinst</literal></entry>
+ 	<entry>causes preinstantiated versions of several templated
+ 	classes to be included in the library.  This may reduce the
+ 	time to compile executables.</entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>&danger;: Option for Distributed Computation</entry>
+        </row>
+        <row>
+ 	<entry><literal>&dashdash;messaging</literal></entry>
+ 	<entry>enables creation of distributed &pooma; executables by
+ 	enabling use of the &cheetah; communications package.  See
+ 	<!-- FIXME: add reference to the distributed configuration
+ 	section. --></entry>
+        </row>
+        <row rowsep="1">
+ 	<entry>Configure Options</entry>
+        </row>
+        <row>
+ 	<entry><literal>-v</literal></entry>
+ 	<entry>turns on verbose output during configuration, showing
+ 	which options are chosen and which are not.</entry>
+        </row>
+        <row>
+ 	<entry><literal>-i</literal></entry>
+         <entry>prevents overwriting existing files during
+ 	configuration without first querying the user.</entry>
+        </row>
+        <row>
+ 	<entry><literal>-f</literal></entry>
+         <entry>forces overwriting existing files during configuration
+ 	without querying the user.  This is the default.</entry>
+        </row>
+        <row>
+ 	<entry><literal>-h</literal></entry>
+ 	<entry>prints the list of configuration options.</entry>
+        </row>
+        <row>
+ 	<entry><literal>-?</literal></entry>
+ 	<entry>prints the list of configuration options.  This is the
+ 	same as <command>-h</command>.</entry>
+        </row>
+        </tbody>
+       </tgroup>
+      </table>
+    </section><!-- danger configuration options -->
+    
+   </section>
+ 
+ 
+   <section id="initial-compile_programs">
+    <title>Writing and Compiling &pooma; Programs</title>
+ 
+    <para>In this section, we describe how to write and compile &pooma;
+    programs.  We illustrate this with a <quote>Hello, &pooma;</quote>
+    program that initializes and de-initializes the &pooma;
+    library.</para>
+ 
+    <example id="initial-compile_programs-hello_pooma">
+     <title>A <quote>Hello, &pooma;</quote> Program</title>
+ 
+ &initialize-finalize;
+     <calloutlist>
+      <callout arearefs="initialize-finalize-program-header_file">
+       <para>This &pooma; header file must be included directly or
+       indirectly in all &pooma; programs.</para>
+      </callout>
+      <callout arearefs="initialize-finalize-program-initialize">
+       <para>Every &pooma; program must initialize the &pooma; library
+       by invoking the <function>initialize</function> function.</para>
+      </callout>
+      <callout arearefs="initialize-finalize-program-finalize">
+       <para>The &poomatoolkit; is shut down by invoking the
+       <function>finalize</function> function, which must be called
+       after all other &pooma; functions.</para>
+      </callout>
+     </calloutlist>
+    </example>
+ 
+    <para>The simplest &pooma; program is available at <filename
+    class="libraryfile">examples/Manual/Sequential/initialize-finalize.cpp</filename>.
+    It is annotated in <xref
+    linkend="initial-compile_programs-hello_pooma"></xref>.  Before its
+    use, the &poomatoolkit; must be initialized by a call to
+    <function>initialize</function>.  This usually occurs in the
+    <function>main</function> function.  After its use, the
+    &poomatoolkit; should be shut down using a call to
+    <function>finalize</function>.  This also usually occurs in the
+    <function>main</function> function.  Both of these functions are
+    declared in <filename class="headerfile">Pooma/Pooma.h</filename>.
+    This header file or another &pooma; header file including it occurs
+    in every &pooma; program.</para>
+ 
+    <para>Compiling this program requires including &pooma; header
+    files and library.  Let us assume that the environment variable
+    <envar>POOMAHOME</envar> describes the location of the &pooma;
+    source code.  For example,<programlisting>
+ &initialspace;export POOMAHOME=/home/user/pooma
+ </programlisting>  We illustrate how to compile the program using the
+    &gpp; compiler:<programlisting>
+ &initialspace;g++ -I${POOMAHOME}/src -I${POOMAHOME}/lib/LINUXgcc initialize-finalize.cpp -o initialize-finalize -L${POOMAHOME}/lib/${POOMASUITE} -lpooma-gcc
+ </programlisting>  We explain the five command-line options:
+     <variablelist>
+      <varlistentry>
+       <term>-I${POOMAHOME}/src</term>
+       <listitem>
+        <para>is the root of a directory tree containing all &pooma;
+        template header files.  For example, the full path name of
+        <filename class="headerfile">Pooma/Pooma.h</filename> is <filename
+        class="headerfile">${POOMAHOME}/src/Pooma/Pooma.h</filename>.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>-I${POOMAHOME}/lib/${POOMASUITE}</term>
+       <listitem>
+        <para>indicates the directory that contains
+        configuration-specific header files.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>initialize-finalize.cpp</term>
+       <listitem>
+        <para>is the source code to compile.  It must have a
+        <function>main</function> function with calls to &pooma;'s
+        <function>initialize</function> and
+        <function>finalize</function>.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>-o initialize-finalize</term>
+       <listitem>
+        <para>determines the name of the resulting executable program.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>-L${POOMAHOME}/lib/${POOMASUITE}</term>
+       <listitem>
+        <para>is the directory containing the &pooma; library file to
+        use.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>-lpooma-gcc</term>
+       <listitem>
+        <para>indicates <filename
+        class="libraryfile">libpooma-gcc.a</filename> is the name of
+        the &pooma; library in the directory specified by the
+        <command>-L</command> option.</para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+     Running the resulting executable prints <quote>Hello,
+     Pooma.</quote>:<screen>
+ &initialspace;$ ./initialize-finalize
+ &initialspace;Hello, Pooma.
+ &initialspace;$</screen>
+     </para>
+ 
+ 
+    <section id="initial-compile_programs-initialize">
+     <title>&danger;: <function>initialize</function> and <function>finalize</function></title>
+ 
+     <para>In this section, we present detailed explanations of
+     <function>initialize</function> and
+     <function>finalize</function>.  Very few &pooma; users ever need
+     to use any form different from that presented in the <quote>Hello,
+     &pooma;</quote> program.</para>
+ 
+     <bridgehead id="initial-compile_programs-initialize-specifications" renderas="sect4">Prototypes</bridgehead>
+ 
+ <programlisting>
+ &initialspace;#include "Pooma/Pooma.h"  // or "Pooma/Arrays.h" or "Pooma/Fields.h" or &hellip;
+ </programlisting>
+ 
+     <funcsynopsis>
+      <funcprototype>
+       <funcdef>bool <function>Pooma::initialize</function></funcdef>
+       <paramdef>
+        <parameter class="function">int &amp;argc,</parameter>
+        <parameter class="function">char ** &amp;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 &amp;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="initial-compile_programs-initialize-explanation" renderas="sect4">Explanation</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>.
+     <!-- FIXME: Write this later?  <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>
+ 
+    </section>
+ 
+   </section>
+ 
+ 
+   <section id="initial-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="initial-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="initial-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; (really &gpp;) 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; (or &gpp;) 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="initial-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><!-- distributed section -->
+  </chapter><!-- "Getting Started" chapter -->
Index: template.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/template.xml,v
retrieving revision 1.6
diff -c -p -r1.6 template.xml
*** template.xml	2002/01/31 21:20:27	1.6
--- template.xml	2002/02/27 03:44:29
***************
*** 1,5 ****
!   <chapter id="template_programming">
!    <title>Programming with Templates</title>
  
     <indexterm zone="template_programming">
      <primary>templates</primary>
--- 1,5 ----
!   <appendix id="template_programming">
!    <title>&danger;: Programming with Templates</title>
  
     <indexterm zone="template_programming">
      <primary>templates</primary>
***************
*** 15,22 ****
     we briefly introduce using templates in &cc; programs by relating
     them to <quote>ordinary</quote> &cc; constructs such as values,
     objects, and classes.  The two main concepts underlying &cc;
!    templates will occur repeatedly:
!    <itemizedlist>
       <listitem>
        <para>Template programming constructs execute at compile time,
        not run time.  That is, template operations occur within the
--- 15,21 ----
     we briefly introduce using templates in &cc; programs by relating
     them to <quote>ordinary</quote> &cc; constructs such as values,
     objects, and classes.  The two main concepts underlying &cc;
!    templates will occur repeatedly:<itemizedlist>
       <listitem>
        <para>Template programming constructs execute at compile time,
        not run time.  That is, template operations occur within the
*************** struct CreateLeaf
*** 1092,1095 ****
      <type>Leaf_t</type>.  Unlike for function objects, the function's
      name within the class must be given a name.</para>
     </section>
!   </chapter>
--- 1091,1094 ----
      <type>Leaf_t</type>.  Unlike for function objects, the function's
      name within the class must be given a name.</para>
     </section>
!   </appendix>
Index: tutorial.xml
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/tutorial.xml,v
retrieving revision 1.11
diff -c -p -r1.11 tutorial.xml
*** tutorial.xml	2002/01/31 21:20:27	1.11
--- tutorial.xml	2002/02/27 03:44:29
***************
*** 111,195 ****
  ]]>  <!-- end unfinished -->
  
  
-  <section id="tutorial-installation">
-   <title>Installing &pooma;</title>
- 
- <![%unfinished;[
-   <para>ADD: How does one install &pooma; using Windows or Mac?</para>
- 
-   <para>UPDATE: Make a more recent &pooma; source code file
-   available on &poomadownloadpage;.  For example,
-   <quote>LINUXgcc.conf</quote> is not available.</para>
- ]]>  <!-- end unfinished -->
- 
-   <para>In this section, we describe how to obtain, build, and
-   install the &poomatoolkit;.  We focus on installing under a
-   Unix-like operating system.
- <![%unfinished;[
-   Instructions for installing on computers
-   running Microsoft Windows or MacOS, as well as more extensive
-   instructions for Unix-like operating systems, appear in <xref
-   linkend="installation"></xref>.
- ]]>  <!-- end unfinished -->
-   </para>
- 
-   <para>Obtain the &pooma; source code <filename
-   path="http://www.codesourcery.com/pooma/downloads_folder/">&poomasourcefile;</filename>
-   from the &pooma; download page (&poomadownloadpage;) available off
-   the &pooma; home page (&poomahomepage;).  The <quote>tgz</quote>
-   indicates this is a compressed tar archive file.  To extract the
-   source files, use <command>tar xzvf &poomasourcefile;</command>.
-   Move into the source code directory <filename
-   class="directory">&poomasource;</filename> directory; e.g.,
-   <command>cd &poomasource;</command>.</para>
- 
-   <para>Configuring the source code determines file names needed for
-   compilation.  First, determine a configuration file in the <filename
-   class="directory">config/arch/</filename> directory corresponding to
-   your operating system and compiler.  For example, <filename
-   class="libraryfile">LINUXgcc.conf</filename> supports compiling
-   under a &linux; operating system with &gcc;, while <filename
-   class="libraryfile">SGI64KCC.conf</filename> supports compiling
-   under a 64-bit <application>SGI</application> Irix operating system
- <!-- FIXME: Center the following command. -->
-   with &kcc;.  Next, configure the source code: <command>./configure
-   &dashdash;arch LINUXgcc &dashdash;opt &dashdash;suite
-   LINUXgcc-opt</command>.  The architecture argument to the
-   <command>&dashdash;arch</command> option is the name of the
-   corresponding configuration file, omitting its <filename
-   class="libraryfile">.conf</filename> suffix.  The
-   <command>&dashdash;opt</command> indicates the &poomatoolkit; will
-   contain optimized source code, which makes the code run more quickly
-   but may impede debugging.  Alternatively, use the
-   <command>&dashdash;debug</command> option which supports debugging.
-   The <glossterm linkend="glossary-suite_name">suite name</glossterm>
-   can be any arbitrary string.  We chose
-   <command>LINUXgcc-opt</command> to remind us of the architecture and
-   optimization choice.  <filename
-   class="libraryfile">configure</filename> creates subdirectories
-   named <quote>LINUXgcc-opt</quote> for use when compiling the source
-   files.  Comments at the beginning of <filename
-   class="libraryfile">lib/<replaceable>suiteName</replaceable>/PoomaConfiguration.h</filename>
-   record the configuration arguments.</para>
- 
-   <para>To compile the source code, set the <envar>POOMASUITE</envar>
-   environment variable to the suite name and then type
-   <command>make</command>.  To set the environment variable for the
- <!-- FIXME: Center the following command. -->
-   <application>bash</application> shell use <command>export
-   POOMASUITE=<replaceable>suiteName</replaceable></command>,
-   substituting the suite name's <replaceable>suiteName</replaceable>.
- <!-- FIXME: Center the following command. -->
-   For the <application>csh</application> shell, use <command>setenv
-   POOMASUITE LINUXgcc-opt</command>.  Issuing the
-   <command>make</command> command compiles the &pooma; source code
-   files to create the &pooma; library.  The &pooma; makefiles assume
-   the <trademark>GNU</trademark> &make; is available so substitute the
-   proper command to run <trademark>GNU</trademark> &make; if
-   necessary.  The &pooma; library can be found in, e.g., <filename
-   class="libraryfile">lib/LINUXgcc-opt/libpooma-gcc.a</filename>.</para>
-  </section>
- 
   <section id="tutorial-hand_coded">
    <title>Hand-Coded Implementation</title>
  
--- 111,116 ----
***************
*** 285,291 ****
    directory.  Ensure the <envar>POOMASUITE</envar> environment
    variable specifies the desired suite name
    <replaceable>suiteName</replaceable>, as we did when compiling
!   &pooma; in <xref linkend="tutorial-installation"></xref>.  Issuing
    the <command>make Doof2d-C-element</command> command creates the
    executable
    <command><replaceable>suiteName</replaceable>/Doof2d-C-element</command>.</para>
--- 206,212 ----
    directory.  Ensure the <envar>POOMASUITE</envar> environment
    variable specifies the desired suite name
    <replaceable>suiteName</replaceable>, as we did when compiling
!   &pooma; in <xref linkend="initial-compile"></xref>.  Issuing
    the <command>make Doof2d-C-element</command> command creates the
    executable
    <command><replaceable>suiteName</replaceable>/Doof2d-C-element</command>.</para>
***************
*** 760,766 ****
    url="http://www.engelschall.com/sw/mm/"></ulink>), communicates
    the available contexts to the executable.  &pooma; must be
    configured for the particular run-time system in use.  See <xref
!   linkend="installation-distributed_computing"></xref>.</para>
  
    <para>A <firstterm>layout</firstterm> combines patches with contexts
    so the program can be executed.  If &distributedtag; is specified,
--- 681,687 ----
    url="http://www.engelschall.com/sw/mm/"></ulink>), communicates
    the available contexts to the executable.  &pooma; must be
    configured for the particular run-time system in use.  See <xref
!   linkend="initial-distributed_computing"></xref>.</para>
  
    <para>A <firstterm>layout</firstterm> combines patches with contexts
    so the program can be executed.  If &distributedtag; is specified,
Index: figures/Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/Makefile,v
retrieving revision 1.2
diff -c -p -r1.2 Makefile
*** figures/Makefile	2002/02/01 02:08:07	1.2
--- figures/Makefile	2002/02/27 03:44:29
*************** MPOST=		mpost
*** 20,28 ****
  EPSTOPNG=	/home/oldham/bin/peps
  
  # MetaPost macro definitions used in multiple files.
! MACRO_SOURCES= box-macros.mp grid-macros.mp
  # These MetaPost files describe the figures.
! SOURCES= concepts.mp data-parallel.mp distributed.mp doof2d.mp introduction.mp
  # MetaPost can produce multiple files per input file.  These multiple
  # files have names %.[0-9]+.  Since make does not deal well with
  # producing an indeterminate number of files from the same rule, we
--- 20,31 ----
  EPSTOPNG=	/home/oldham/bin/peps
  
  # MetaPost macro definitions used in multiple files.
! MACRO_SOURCES= box-macros.mp grid-macros.mp uml.mp
! # These MetaPost files describe the UML class diagrams.
! UML_SOURCES= explanation-uml.mp
  # These MetaPost files describe the figures.
! SOURCES= concepts.mp data-parallel.mp distributed.mp doof2d.mp introduction.mp \
! 	$(UML_SOURCES)
  # MetaPost can produce multiple files per input file.  These multiple
  # files have names %.[0-9]+.  Since make does not deal well with
  # producing an indeterminate number of files from the same rule, we
*************** RESULTS= $(SOURCES:%.mp=mproof-%.ps)
*** 33,38 ****
--- 36,46 ----
  # figures.
  TREE_SOURCES= $(SOURCES) Makefile macros.ltx
  
+ # UML class diagrams that occur in the appendix containing these.
+ UML_DIAGRAMS= explanation-uml-1.png array-uml.1 array-uml.2 array-uml.3 \
+ 	      domain-uml.1 engine-uml.1 engine-uml.2 engine-uml.3 \
+ 	      engine-uml.4
+ 
  # Create all the EPS and PNG files.  The 'mproof-all' target creates
  # the EPS files.  This should happen before trying to create the PNG
  # files, but this rule may not guarantee this ordering.
*************** all: mproof-all \
*** 40,46 ****
  	concepts-101.png concepts-111.png data-parallel-101.png \
  	data-parallel-212.png distributed-101.png \
  	doof2d-201.png doof2d-202.png doof2d-203.png \
! 	doof2d-210.png doof2d-211.png introduction-101.png
  
  mproof-all: $(RESULTS)
  
--- 48,55 ----
  	concepts-101.png concepts-111.png data-parallel-101.png \
  	data-parallel-212.png distributed-101.png \
  	doof2d-201.png doof2d-202.png doof2d-203.png \
! 	doof2d-210.png doof2d-211.png introduction-101.png \
! 	$(UML_DIAGRAMS)
  
  mproof-all: $(RESULTS)
  
*************** distributed-%.png: distributed.%
*** 60,65 ****
--- 69,82 ----
  doof2d-%.png: doof2d.%
  	$(EPSTOPNG) -p -o $@ $^
  introduction-%.png: introduction.%
+ 	$(EPSTOPNG) -p -o $@ $^
+ array-uml-%.png: array-uml.%
+ 	$(EPSTOPNG) -p -o $@ $^
+ domain-uml-%.png: domain-uml.%
+ 	$(EPSTOPNG) -p -o $@ $^
+ engine-uml-%.png: engine-uml.%
+ 	$(EPSTOPNG) -p -o $@ $^
+ explanation-uml-%.png: explanation-uml.%
  	$(EPSTOPNG) -p -o $@ $^
  
  clean:
Index: figures/array-uml-1.png
===================================================================
RCS file: array-uml-1.png
diff -N array-uml-1.png
Binary files /dev/null and array-uml-1.png differ
Index: figures/array-uml-2.png
===================================================================
RCS file: array-uml-2.png
diff -N array-uml-2.png
Binary files /dev/null and array-uml-2.png differ
Index: figures/array-uml-3.png
===================================================================
RCS file: array-uml-3.png
diff -N array-uml-3.png
Binary files /dev/null and array-uml-3.png differ
Index: figures/array-uml.mp
===================================================================
RCS file: array-uml.mp
diff -N array-uml.mp
*** /dev/null	Fri Mar 23 21:37:44 2001
--- array-uml.mp	Tue Feb 26 20:44:31 2002
***************
*** 0 ****
--- 1,338 ----
+ %% Oldham, Jeffrey D.
+ %% 2002Feb19
+ %% POOMA
+ 
+ %% Engine UML Diagram
+ 
+ 
+ %% Assumes TEX=latex.
+ 
+ %% Ensure fonts are included in the output.
+ prologues := 2;			% >= 2 for PostScript
+ 
+ input boxes;
+ input box-macros;
+ input uml;
+ 
+ verbatimtex
+ \documentclass[10pt]{article}
+ \usepackage{amsmath}
+ \input{macros.ltx}
+ \usepackage{times}
+ \usepackage{mathptm}
+ \newlength{\cnw}	% Required to use \classnameWidth and \emptyBox
+ \begin{document}
+ etex
+ 
+ 
+ beginfig(1)
+   %% Create the boxes.
+   % Array
+   boxit.array[0](btex \classnameWidth{Array}{DynamicArray<1,T,Tag>} etex);
+   boxit.array[1](btex etex);
+   boxit.array[2](
+     btex
+     \begin{lists}
+     Array() \\
+     Array(Domain \ldots) \\
+     Array(Domain \ldots, ModelElement<T>) \\
+     Array(Array) \\
+     Array(Array, Domain) \\
+     initialize(Domain \ldots) \\
+     initialize(Domain \ldots, ModelElement<T>) \\
+     read(\ldots) \\
+     operator()(\ldots) \\
+     domain() \\
+     physicalDomain() \\
+     totalDomain() \\
+     first(int) \\
+     last(int) \\
+     length(int) \\
+     firsts() \\
+     lasts() \\
+     lengths() \\
+     size() \\
+     layout() \\
+     engine() \\
+     operator<<
+     \end{lists} etex);
+   boxit.array[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.array[4](
+     btex \begin{files}
+     Array.h \\
+     PrintArray.h
+     \end{files} etex);
+ 
+   % DynamicArray
+   boxit.dynamicarray[0](btex \classnameWidth{DynamicArray<1,T,Tag>}{DynamicArray<1,T,Tag>} etex);
+   boxit.dynamicarray[1](btex etex);
+   boxit.dynamicarray[2](
+     btex
+     \begin{lists}
+     DynamicArray() \\
+     DynamicArray(Domain) \\
+     DynamicArray(Domain, ModelElement<T>) \\
+     DynamicArray(DynamicArray) \\
+     DynamicArray(DynamicArray, Domain) \\
+     initialize(Domain \ldots) \\
+     initialize(Domain \ldots, ModelElement<T>) \\
+     read(\ldots) \\
+     operator()(\ldots) \\
+     domain() \\
+     physicalDomain() \\
+     totalDomain() \\
+     first(int) \\
+     last(int) \\
+     length(int) \\
+     firsts() \\
+     lasts() \\
+     lengths() \\
+     size() \\
+     layout() \\
+     engine() \\
+     operator<< \\
+     array() \\
+     arrayAll() \\
+     create(CreateSize\t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamicarray[3](
+     btex
+     \begin{lists}
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.dynamicarray[4](
+     btex \begin{files}
+     DynamicArray.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the template parameters.
+   forsuffixes $=array,dynamicarray:
+     fixsize($[0]);
+   endfor
+   forsuffixes $=array,dynamicarray:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+ 
+   % Position the UML classes.
+   array[0].c = origin;
+   array[0].s - dynamicarray[0].n = (0, 2yUnit);
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=array,dynamicarray:
+     for t = 0 upto 0:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=array,dynamicarray:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+ 
+   % Draw arrows between classes.
+   drawDiscriminator(array[0].s, 0);
+   z0 = array[0].s - (0,discriminatorScale);
+   draw z0 -- dynamicarray[0].n;
+ endfig;
+ 
+ 
+ %% Draw the Array box.
+ beginfig(2)
+   %% Create the boxes.
+   % Array
+   boxit.array[0](btex \classnameWidth{Array}{DynamicArray<1,T,Tag>} etex);
+   boxit.array[1](btex etex);
+   boxit.array[2](
+     btex
+     \begin{lists}
+     Array() \\
+     Array(Domain \ldots) \\
+     Array(Domain \ldots, ModelElement<T>) \\
+     Array(Array) \\
+     Array(Array, Domain) \\
+     initialize(Domain \ldots) \\
+     initialize(Domain \ldots, ModelElement<T>) \\
+     read(\ldots) \\
+     operator()(\ldots) \\
+     domain() \\
+     physicalDomain() \\
+     totalDomain() \\
+     first(int) \\
+     last(int) \\
+     length(int) \\
+     firsts() \\
+     lasts() \\
+     lengths() \\
+     size() \\
+     layout() \\
+     engine() \\
+     operator<<
+     \end{lists} etex);
+   boxit.array[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.array[4](
+     btex \begin{files}
+     Array.h \\
+     PrintArray.h
+     \end{files} etex);
+   
+   %% Position the boxes.
+   % Position the template parameters.
+   forsuffixes $=array:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   forsuffixes $=array:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=array:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+ 
+   % Position the UML classes.
+   array[0].c = origin;
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=array:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=array:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the implementation files.
+   forsuffixes $=array:
+     drawunboxed($[4]);
+   endfor
+ endfig;
+ 
+ 
+ % Print the DynamicArray class box.
+ beginfig(3)
+   %% Create the boxes.
+   % DynamicArray
+   boxit.dynamicarray[0](btex \classnameWidth{DynamicArray<1,T,Tag>}{DynamicArray<1,T,Tag>} etex);
+   boxit.dynamicarray[1](btex etex);
+   boxit.dynamicarray[2](
+     btex
+     \begin{lists}
+     DynamicArray() \\
+     DynamicArray(Domain) \\
+     DynamicArray(Domain, ModelElement<T>) \\
+     DynamicArray(DynamicArray) \\
+     DynamicArray(DynamicArray, Domain) \\
+     initialize(Domain \ldots) \\
+     initialize(Domain \ldots, ModelElement<T>) \\
+     read(\ldots) \\
+     operator()(\ldots) \\
+     domain() \\
+     physicalDomain() \\
+     totalDomain() \\
+     first(int) \\
+     last(int) \\
+     length(int) \\
+     firsts() \\
+     lasts() \\
+     lengths() \\
+     size() \\
+     layout() \\
+     engine() \\
+     operator<< \\
+     array() \\
+     arrayAll() \\
+     create(CreateSize\t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamicarray[3](
+     btex
+     \begin{lists}
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.dynamicarray[4](
+     btex \begin{files}
+     DynamicArray.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the template parameters.
+   forsuffixes $=dynamicarray:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   forsuffixes $=dynamicarray:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=dynamicarray:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+ 
+   % Position the UML classes.
+   dynamicarray[0].c = origin;
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=dynamicarray:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=dynamicarray:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the implementation files.
+   forsuffixes $=dynamicarray:
+     drawunboxed($[4]);
+   endfor
+ endfig;
+ 
+ bye
Index: figures/domain-uml-1.png
===================================================================
RCS file: domain-uml-1.png
diff -N domain-uml-1.png
Binary files /dev/null and domain-uml-1.png differ
Index: figures/domain-uml.mp
===================================================================
RCS file: domain-uml.mp
diff -N domain-uml.mp
*** /dev/null	Fri Mar 23 21:37:44 2001
--- domain-uml.mp	Tue Feb 26 20:44:33 2002
***************
*** 0 ****
--- 1,230 ----
+ %% Oldham, Jeffrey D.
+ %% 2002Feb18
+ %% POOMA
+ 
+ %% Domain UML Diagram
+ 
+ 
+ %% Assumes TEX=latex.
+ 
+ %% Ensure fonts are included in the output.
+ prologues := 2;			% >= 2 for PostScript
+ 
+ input boxes;
+ input box-macros;
+ input uml;
+ 
+ verbatimtex
+ \documentclass[10pt]{article}
+ \usepackage{amsmath}
+ \input{macros.ltx}
+ \usepackage{times}
+ \usepackage{mathptm}
+ \newlength{\cnw}	% Required to use \classnameWidth and \emptyBox
+ \begin{document}
+ etex
+ 
+ 
+ beginfig(1)
+   %% Create the boxes.
+   % Domain
+   boxit.domain[0](btex \classname{Domain} etex);
+   boxit.domain[1](btex etex);
+   boxit.domain[2](
+     btex \begin{lists}
+     long size() \\
+     bool empty() \\
+     Domain<1> \breakLine operator[](int dim)
+     \end{lists} etex);
+   boxit.domain[3](
+     btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.domain[4](
+     btex \begin{files}
+     Domain.h \\
+     DomainBase.h \\
+     DomainTraits.h
+     \end{files} etex);
+   
+   % Domain<1>
+   boxit.domainOne[0](btex \classname{Domain<1>} etex);
+   boxit.domainOne[1](btex etex);
+   boxit.domainOne[2](
+     btex \begin{lists}
+     long length() \\
+     int first() \\
+     int last() \\
+     int min() \\
+     int max() \\
+     Domain<1>::iter-\breakLine ator begin() \\
+     Domain<1>::iter-\breakLine ator end() \\
+     \end{lists} etex);
+   
+   % Domain<1>::iterator
+   boxit.domainOneIterator[0](btex \classname{Domain<1>::iterator} etex);
+   boxit.domainOneIterator[1](btex etex);
+   boxit.domainOneIterator[2](
+     btex \begin{lists}
+     operator*() \\
+     operator++() \\
+     operator->() \\
+     \end{lists} etex);
+   boxit.domainOneIterator[4](
+     btex \begin{files}
+     DomainIterator.h
+     \end{files} etex);
+ 
+   % Loc
+   boxit.loc[0](btex \classname{Loc} etex);
+   boxit.loc[1](btex \emptyBox{Interval<1>} etex);
+   boxit.loc[2](btex etex);
+   boxit.loc[3](
+     btex \begin{lists}
+     dim D
+     \end{lists} etex);
+   boxit.loc[4](
+     btex \begin{files}
+     Loc.h \\
+     DomainTraits.Loc.h
+     \end{files} etex);
+ 
+   % Loc<1>
+   boxit.locOne[0](btex \classname{Loc<1>} etex);
+   boxit.locOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.locOne[2](btex etex);
+ 
+   % Interval
+   boxit.interval[0](btex \classname{Interval} etex);
+   boxit.interval[1](btex \emptyBox{Interval<1>} etex);
+   boxit.interval[2](btex etex);
+   boxit.interval[3](
+     btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.interval[4](
+     btex \begin{files}
+     Interval.h \\
+     DomainTraits.Interval.h
+     \end{files} etex);
+   
+   % Interval<1>
+   boxit.intervalOne[0](btex \classname{Interval<1>} etex);
+   boxit.intervalOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.intervalOne[2](btex etex);
+ 
+   % Range
+   boxit.rangeBox[0](btex \classname{Range} etex);
+   boxit.rangeBox[1](btex \emptyBox{Interval<1>} etex);
+   boxit.rangeBox[2](btex etex);
+   boxit.rangeBox[3](btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.rangeBox[4](
+     btex \begin{files}
+     Range.h \\
+     DomainTraits.Range.h
+     \end{files} etex);
+ 
+   % Range<1>
+   boxit.rangeOne[0](btex \classname{Range<1>} etex);
+   boxit.rangeOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.rangeOne[2](btex etex);
+ 
+   % Grid
+   boxit.grid[0](btex \classname{Grid} etex);
+   boxit.grid[1](btex \emptyBox{Interval<1>} etex);
+   boxit.grid[2](btex etex);
+   boxit.grid[3](btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.grid[4](
+     btex \begin{files}
+     Grid.h \\
+     DomainTraits.Grid.h
+     \end{files} etex);
+   
+   % Grid<1>
+   boxit.gridOne[0](btex \classname{Grid<1>} etex);
+   boxit.gridOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.gridOne[2](btex etex);
+   
+   %% Position the boxes.
+   % Position the boxes within the UML class diagrams.
+   forsuffixes $=domain, domainOne, domainOneIterator, loc, locOne, interval, intervalOne, rangeBox, rangeOne, grid, gridOne:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   % Position the template parameters.
+   forsuffixes $=domain, loc, interval, rangeBox, grid:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=domain, domainOneIterator, loc, interval, rangeBox, grid:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+   
+   % Position the UML classes.
+   domain[0].c = origin;
+   domainOne[0].nw - domain[0].ne = (xUnit,0);
+   domainOneIterator[0].nw - domainOne[0].ne = (xUnit,0);
+   domain[2].sw - loc[0].nw = (0, yUnit + max(0, ypart(domain[2].s - domainOne[2].s)));
+   loc[2].s - locOne[0].n = (0, yUnit);
+   interval[0].nw - loc[0].ne = (xUnit, 0);
+   interval[2].s - intervalOne[0].n = (0, yUnit);
+   rangeBox[0].nw - interval[0].ne = (2xUnit, 0);
+   rangeBox[2].s - rangeOne[0].n = (0, yUnit);
+   grid[0].nw - rangeBox[0].ne = (xUnit, 0);
+   grid[2].s - gridOne[0].n = (0, yUnit);
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=domain, domainOne, domainOneIterator, loc, locOne, interval, intervalOne, rangeBox, rangeOne, grid, gridOne:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=domain, loc, interval, rangeBox, grid:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the file names.
+   forsuffixes $=domain, domainOneIterator, loc, interval, rangeBox, grid:
+     drawunboxed($[4]);
+   endfor
+   
+   % Draw arrows between classes.
+   drawarrow locOne[0].n -- loc[2].s dashed evenly;
+   drawarrow intervalOne[0].n -- interval[2].s dashed evenly;
+   drawarrow rangeOne[0].n -- rangeBox[2].s dashed evenly;
+   drawarrow gridOne[0].n -- grid[2].s dashed evenly;
+   drawarrow domainOne[1].w -- domain[1].e dashed evenly;
+ 
+   % Draw lines between classes.
+   draw domainOneIterator[1].w -- domainOne[1].e;
+   drawDiscriminator(domain[2].s, 0);
+   numeric foo; foo = 0.7yUnit;
+   forsuffixes $=loc, interval, rangeBox, grid:
+     draw $[0].n -- ($[0].n+(0,foo));
+   endfor
+   draw loc[0].n+(0,foo) -- grid[0].n+(0,foo);
+   z0 = domain[2].s - (0,discriminatorScale);
+   draw z0 -- (x0, ypart(loc[0].n+(0,foo)));
+     
+ endfig;
+ 
+ bye
Index: figures/doof2d.mp
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/doof2d.mp,v
retrieving revision 1.6
diff -c -p -r1.6 doof2d.mp
*** figures/doof2d.mp	2002/01/31 21:29:58	1.6
--- figures/doof2d.mp	2002/02/27 03:44:34
*************** verbatimtex
*** 18,24 ****
  
  etex
  
- 
  input grid-macros;
  
  %% Global Declarations
--- 18,23 ----
Index: figures/engine-uml-1.png
===================================================================
RCS file: engine-uml-1.png
diff -N engine-uml-1.png
Binary files /dev/null and engine-uml-1.png differ
Index: figures/engine-uml-2.png
===================================================================
RCS file: engine-uml-2.png
diff -N engine-uml-2.png
Binary files /dev/null and engine-uml-2.png differ
Index: figures/engine-uml-3.png
===================================================================
RCS file: engine-uml-3.png
diff -N engine-uml-3.png
Binary files /dev/null and engine-uml-3.png differ
Index: figures/engine-uml-4.png
===================================================================
RCS file: engine-uml-4.png
diff -N engine-uml-4.png
Binary files /dev/null and engine-uml-4.png differ
Index: figures/engine-uml.mp
===================================================================
RCS file: engine-uml.mp
diff -N engine-uml.mp
*** /dev/null	Fri Mar 23 21:37:44 2001
--- engine-uml.mp	Tue Feb 26 20:44:36 2002
***************
*** 0 ****
--- 1,996 ----
+ %% Oldham, Jeffrey D.
+ %% 2002Feb19
+ %% POOMA
+ 
+ %% Engine UML Diagram
+ 
+ 
+ %% Assumes TEX=latex.
+ 
+ %% Ensure fonts are included in the output.
+ prologues := 2;			% >= 2 for PostScript
+ 
+ input boxes;
+ input box-macros;
+ input uml;
+ 
+ verbatimtex
+ \documentclass[10pt]{article}
+ \usepackage{amsmath}
+ \input{macros.ltx}
+ \usepackage{times}
+ \usepackage{mathptm}
+ \newlength{\cnw}	% Required to use \classnameWidth and \emptyBox
+ \begin{document}
+ etex
+ 
+ 
+ %% The first figure will show the relationships among the UML classes.
+ %% Subsequent figures will describe the classes.
+ 
+ beginfig(1)
+   %% Create the boxes.
+   % Engine
+   boxit.engine[0](btex \classnameWidth{Engine}{Engine<D,T,Tag>} etex);
+   boxit.engine[1](btex etex);
+   boxit.engine[2](btex etex);
+   boxit.engine[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.engine[4](
+     btex \begin{files}
+     Engine.h
+     \end{files} etex);
+ 
+   % Brick
+   boxit.brick[0](btex \classname{Engine<D,T,Brick>} etex);
+   boxit.brick[1](btex etex);
+ 
+   picture engineOperations;
+   engineOperations =
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout()
+     \end{lists} etex;
+   
+   boxit.brick[2](engineOperations);
+ 
+   picture taggedEngineTemplates;
+   taggedEngineTemplates =
+   btex \begin{lists}
+     dim D \\
+     val type T
+     \end{lists} etex;
+     
+   boxit.brick[3](taggedEngineTemplates);
+   boxit.brick[4](
+     btex \begin{files}
+     BrickEngine.h \\
+     BrickEngine.cpp \\
+     BrickEngine.[1-7].inst.cpp \\
+     BrickBase.h \\
+     BrickBase.cpp \\
+     BrickBase[1-7].cmpl.cpp
+     \end{files} etex);
+ 
+   % CompressibleBrick
+   boxit.compressiblebrick[0](btex \classname{Engine<D,T,CompressibleBrick>} etex);
+   boxit.compressiblebrick[1](btex etex);
+   boxit.compressiblebrick[2](engineOperations);
+   boxit.compressiblebrick[3](taggedEngineTemplates);
+   boxit.compressiblebrick[4](
+     btex \begin{files}
+     CompressibleBrick.h \\
+     CompressibleBlock.h \\
+     CompressedFraction.h
+     \end{files} etex);
+ 
+   % Dynamic
+   boxit.dynamic[0](btex \classname{Engine<1,T,Dynamic>} etex);
+   boxit.dynamic[1](btex etex);
+   boxit.dynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamic[3](
+     btex \begin{lists}
+     val type T
+     \end{lists} etex);
+   boxit.dynamic[4](
+     btex \begin{files}
+     DynamicEngine.h \\
+     DynamicEngine.cpp
+     \end{files} etex);
+ 
+   % MultiPatch
+   boxit.multipatch[0](btex \classname{Engine<D,T,MultiPatch<LT,PT> >} etex);
+   boxit.multipatch[1](btex etex);
+   boxit.multipatch[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     innerDomain() \\
+     layout()
+     \end{lists} etex);
+   boxit.multipatch[3](
+     btex \begin{lists}
+     dim D \\
+     val type T \\
+     layout LT \\
+     patch PT
+     \end{lists} etex);
+   boxit.multipatch[4](
+     btex \begin{files}
+     MultiPatchEngine.h
+     \end{files} etex);
+ 
+   % Remote
+   boxit.remote[0](btex \classname{Engine<D,T,Remote<Tag> >} etex);
+   boxit.remote[1](btex etex);
+   boxit.remote[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain()
+     \end{lists} etex);
+   boxit.remote[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.remote[4](
+     btex \begin{files}
+     RemoteEngine.h
+     \end{files} etex);
+   
+   % RemoteDynamic
+   boxit.remotedynamic[0](btex \classname{Engine<1,T,Remote<Dynamic> >} etex);
+   boxit.remotedynamic[1](btex etex);
+   boxit.remotedynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.remotedynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.remotedynamic[4](
+     btex \begin{files}
+     RemoteDynamicEngine.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the template parameters.
+   forsuffixes $=engine:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   forsuffixes $=engine, brick, compressiblebrick, dynamic, multipatch, remote, remotedynamic:
+     fixsize($[0]);
+   endfor
+   forsuffixes $=engine, brick, compressiblebrick, dynamic, multipatch, remote, remotedynamic:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=engine:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+ 
+   % Position the UML classes.
+   engine[0].c = origin;
+   xpart(brick[0].w) = xpart(dynamic[0].w);
+   xpart(compressiblebrick[3].e) = xpart(multipatch[3].e);
+   ypart(brick[0].n - compressiblebrick[0].n) = 0;
+   ypart(dynamic[0].n - multipatch[0].n) = 0;
+   ypart(compressiblebrick[0].s - multipatch[3].n) = 
+   ypart(remote[0].s - remotedynamic[3].n) =
+   ypart(dynamic[0].s - remote[3].n) = yUnit;
+   numeric leftColumn;
+   leftColumn = max(xpart(brick[3].e),xpart(dynamic[3].e));
+   numeric rightColumn;
+   rightColumn = min(xpart(compressiblebrick[0].w),xpart(multipatch[0].w));
+   rightColumn - leftColumn = xUnit;
+   xpart(remote[0].n) = xpart(remotedynamic[0].n) = 0.5[leftColumn,rightColumn];
+   xpart(engine[2].s) = 0.5[leftColumn,rightColumn];
+   ypart(engine[2].s) = yUnit + max(ypart(brick[3].n),ypart(compressiblebrick[3].n));
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=engine:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   forsuffixes $=engine, brick, compressiblebrick, dynamic, multipatch, remote, remotedynamic:
+     for t = 0 upto 0:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=engine, brick, compressiblebrick, dynamic, multipatch, remote, remotedynamic:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the implementation files.
+   forsuffixes $=engine:
+     drawunboxed($[4]);
+   endfor
+ 
+   % Draw arrows between classes.
+   drawarrow (xpart(remote[0].s), ypart(remotedynamic[0].n)) -- remote[0].s dashed evenly;
+   numeric middleColumn; middleColumn = 0.5[leftColumn,rightColumn];
+   drawarrow multipatch[0].w -- (middleColumn,ypart(multipatch[0].w)) dashed evenly;
+   drawarrow dynamic[0].e -- (middleColumn, ypart(dynamic[0].e)) dashed evenly;
+   drawarrow compressiblebrick[0].w -- (middleColumn,ypart(compressiblebrick[0].w)) dashed evenly;
+   drawarrow brick[0].e -- (middleColumn, ypart(brick[0].e)) dashed evenly;
+   draw compressiblebrick[0].w -- brick[0].e dashed evenly;
+   drawarrow (middleColumn,ypart(multipatch[0].w)) -- engine[2].s
+   dashed evenly;
+   draw remote[0].n .. (middleColumn,ypart(multipatch[0].w)) dashed evenly;
+ 
+ endfig;
+ 
+ 
+ %% Draw the Brick and CompressibleBrick boxes.
+ beginfig(2)
+   %% Create the boxes.
+   % Engine
+   boxit.engine[0](btex \classname{Engine} etex);
+   boxit.engine[1](btex etex);
+   boxit.engine[2](btex etex);
+   boxit.engine[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.engine[4](
+     btex \begin{files}
+     Engine.h
+     \end{files} etex);
+ 
+   % Brick
+   boxit.brick[0](btex \classname{Engine<D,T,Brick>} etex);
+   boxit.brick[1](btex etex);
+ 
+   picture engineOperations;
+   engineOperations =
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout()
+     \end{lists} etex;
+   
+   boxit.brick[2](engineOperations);
+ 
+   picture taggedEngineTemplates;
+   taggedEngineTemplates =
+   btex \begin{lists}
+     dim D \\
+     value type T
+     \end{lists} etex;
+     
+   boxit.brick[3](taggedEngineTemplates);
+   boxit.brick[4](
+     btex \begin{files}
+     BrickEngine.h \\
+     BrickEngine.cpp \\
+     BrickEngine.[1-7].inst.cpp \\
+     BrickBase.h \\
+     BrickBase.cpp \\
+     BrickBase[1-7].cmpl.cpp
+     \end{files} etex);
+ 
+   % CompressibleBrick
+   boxit.compressiblebrick[0](btex \classname{Engine<D,T,CompressibleBrick>} etex);
+   boxit.compressiblebrick[1](btex etex);
+   boxit.compressiblebrick[2](engineOperations);
+   boxit.compressiblebrick[3](taggedEngineTemplates);
+   boxit.compressiblebrick[4](
+     btex \begin{files}
+     CompressibleBrick.h \\
+     CompressibleBlock.h \\
+     CompressedFraction.h
+     \end{files} etex);
+ 
+   % Dynamic
+   boxit.dynamic[0](btex \classname{Engine<1,T,Dynamic>} etex);
+   boxit.dynamic[1](btex etex);
+   boxit.dynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.dynamic[4](
+     btex \begin{files}
+     DynamicEngine.h \\
+     DynamicEngine.cpp
+     \end{files} etex);
+ 
+   % MultiPatch
+   boxit.multipatch[0](btex \classname{Engine<D,T,MultiPatch<LT,PT> >} etex);
+   boxit.multipatch[1](btex etex);
+   boxit.multipatch[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     innerDomain() \\
+     layout()
+     \end{lists} etex);
+   boxit.multipatch[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     layout tag LT \\
+     patch tag PT
+     \end{lists} etex);
+   boxit.multipatch[4](
+     btex \begin{files}
+     MultiPatchEngine.h
+     \end{files} etex);
+ 
+   % Remote
+   boxit.remote[0](btex \classname{Engine<D,T,Remote<Tag> >} etex);
+   boxit.remote[1](btex etex);
+   boxit.remote[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain()
+     \end{lists} etex);
+   boxit.remote[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.remote[4](
+     btex \begin{files}
+     RemoteEngine.h
+     \end{files} etex);
+   
+   % RemoteDynamic
+   boxit.remotedynamic[0](btex \classname{Engine<1,T,Remote<Dynamic> >} etex);
+   boxit.remotedynamic[1](btex etex);
+   boxit.remotedynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.remotedynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.remotedynamic[4](
+     btex \begin{files}
+     RemoteDynamicEngine.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the boxes within the UML class diagrams.
+   forsuffixes $=brick, compressiblebrick:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   % Position the template parameters.
+   forsuffixes $=brick, compressiblebrick:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=brick, compressiblebrick:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+   
+   % Position the UML classes.
+   brick[0].c = origin;
+   xpart(brick[0].w - compressiblebrick[0].w) = 0;
+   ypart(compressiblebrick[3].n - brick[4].s) = -yUnit;
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=brick, compressiblebrick:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=brick, compressiblebrick:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the file names.
+   forsuffixes $=brick, compressiblebrick:
+     drawunboxed($[4]);
+   endfor
+ 
+ endfig;
+ 
+ 
+ %% Draw the Dynamic and MultiPatch boxes.
+ beginfig(3)
+   %% Create the boxes.
+   % Engine
+   boxit.engine[0](btex \classname{Engine} etex);
+   boxit.engine[1](btex etex);
+   boxit.engine[2](btex etex);
+   boxit.engine[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.engine[4](
+     btex \begin{files}
+     Engine.h
+     \end{files} etex);
+ 
+   % Brick
+   boxit.brick[0](btex \classname{Engine<D,T,Brick>} etex);
+   boxit.brick[1](btex etex);
+ 
+   picture engineOperations;
+   engineOperations =
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout()
+     \end{lists} etex;
+   
+   boxit.brick[2](engineOperations);
+ 
+   picture taggedEngineTemplates;
+   taggedEngineTemplates =
+   btex \begin{lists}
+     dim D \\
+     value type T
+     \end{lists} etex;
+     
+   boxit.brick[3](taggedEngineTemplates);
+   boxit.brick[4](
+     btex \begin{files}
+     BrickEngine.h \\
+     BrickEngine.cpp \\
+     BrickEngine.[1-7].inst.cpp \\
+     BrickBase.h \\
+     BrickBase.cpp \\
+     BrickBase[1-7].cmpl.cpp
+     \end{files} etex);
+ 
+   % CompressibleBrick
+   boxit.compressiblebrick[0](btex \classname{Engine<D,T,CompressibleBrick>} etex);
+   boxit.compressiblebrick[1](btex etex);
+   boxit.compressiblebrick[2](engineOperations);
+   boxit.compressiblebrick[3](taggedEngineTemplates);
+   boxit.compressiblebrick[4](
+     btex \begin{files}
+     CompressibleBrick.h \\
+     CompressibleBlock.h \\
+     CompressedFraction.h
+     \end{files} etex);
+ 
+   % Dynamic
+   boxit.dynamic[0](btex \classname{Engine<1,T,Dynamic>} etex);
+   boxit.dynamic[1](btex etex);
+   boxit.dynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.dynamic[4](
+     btex \begin{files}
+     DynamicEngine.h \\
+     DynamicEngine.cpp
+     \end{files} etex);
+ 
+   % MultiPatch
+   boxit.multipatch[0](btex \classname{Engine<D,T,MultiPatch<LT,PT> >} etex);
+   boxit.multipatch[1](btex etex);
+   boxit.multipatch[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     innerDomain() \\
+     layout()
+     \end{lists} etex);
+   boxit.multipatch[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     layout tag LT \\
+     patch tag PT
+     \end{lists} etex);
+   boxit.multipatch[4](
+     btex \begin{files}
+     MultiPatchEngine.h
+     \end{files} etex);
+ 
+   % Remote
+   boxit.remote[0](btex \classname{Engine<D,T,Remote<Tag> >} etex);
+   boxit.remote[1](btex etex);
+   boxit.remote[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain()
+     \end{lists} etex);
+   boxit.remote[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.remote[4](
+     btex \begin{files}
+     RemoteEngine.h
+     \end{files} etex);
+   
+   % RemoteDynamic
+   boxit.remotedynamic[0](btex \classname{Engine<1,T,Remote<Dynamic> >} etex);
+   boxit.remotedynamic[1](btex etex);
+   boxit.remotedynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.remotedynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.remotedynamic[4](
+     btex \begin{files}
+     RemoteDynamicEngine.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the boxes within the UML class diagrams.
+   forsuffixes $=dynamic, multipatch:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   % Position the template parameters.
+   forsuffixes $=dynamic, multipatch:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=dynamic, multipatch:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+   
+   % Position the UML classes.
+   dynamic[0].c = origin;
+   xpart(dynamic[0].w - multipatch[0].w) = 0;
+   ypart(multipatch[3].n - dynamic[4].s) = -yUnit;
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=dynamic, multipatch:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=dynamic, multipatch:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the file names.
+   forsuffixes $=dynamic, multipatch:
+     drawunboxed($[4]);
+   endfor
+ 
+ endfig;
+ 
+ 
+ %% Draw the Remote and Remote<Dynamic> boxes.
+ beginfig(4)
+   %% Create the boxes.
+   % Engine
+   boxit.engine[0](btex \classname{Engine} etex);
+   boxit.engine[1](btex etex);
+   boxit.engine[2](btex etex);
+   boxit.engine[3](
+     btex
+     \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.engine[4](
+     btex \begin{files}
+     Engine.h
+     \end{files} etex);
+ 
+   % Brick
+   boxit.brick[0](btex \classname{Engine<D,T,Brick>} etex);
+   boxit.brick[1](btex etex);
+ 
+   picture engineOperations;
+   engineOperations =
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout()
+     \end{lists} etex;
+   
+   boxit.brick[2](engineOperations);
+ 
+   picture taggedEngineTemplates;
+   taggedEngineTemplates =
+   btex \begin{lists}
+     dim D \\
+     value type T
+     \end{lists} etex;
+     
+   boxit.brick[3](taggedEngineTemplates);
+   boxit.brick[4](
+     btex \begin{files}
+     BrickEngine.h \\
+     BrickEngine.cpp \\
+     BrickEngine.[1-7].inst.cpp \\
+     BrickBase.h \\
+     BrickBase.cpp \\
+     BrickBase[1-7].cmpl.cpp
+     \end{files} etex);
+ 
+   % CompressibleBrick
+   boxit.compressiblebrick[0](btex \classname{Engine<D,T,CompressibleBrick>} etex);
+   boxit.compressiblebrick[1](btex etex);
+   boxit.compressiblebrick[2](engineOperations);
+   boxit.compressiblebrick[3](taggedEngineTemplates);
+   boxit.compressiblebrick[4](
+     btex \begin{files}
+     CompressibleBrick.h \\
+     CompressibleBlock.h \\
+     CompressedFraction.h
+     \end{files} etex);
+ 
+   % Dynamic
+   boxit.dynamic[0](btex \classname{Engine<1,T,Dynamic>} etex);
+   boxit.dynamic[1](btex etex);
+   boxit.dynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     layout() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.dynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.dynamic[4](
+     btex \begin{files}
+     DynamicEngine.h \\
+     DynamicEngine.cpp
+     \end{files} etex);
+ 
+   % MultiPatch
+   boxit.multipatch[0](btex \classname{Engine<D,T,MultiPatch<LT,PT> >} etex);
+   boxit.multipatch[1](btex etex);
+   boxit.multipatch[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     innerDomain() \\
+     layout()
+     \end{lists} etex);
+   boxit.multipatch[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     layout tag LT \\
+     patch tag PT
+     \end{lists} etex);
+   boxit.multipatch[4](
+     btex \begin{files}
+     MultiPatchEngine.h
+     \end{files} etex);
+ 
+   % Remote
+   boxit.remote[0](btex \classname{Engine<D,T,Remote<Tag> >} etex);
+   boxit.remote[1](btex etex);
+   boxit.remote[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain()
+     \end{lists} etex);
+   boxit.remote[3](
+     btex \begin{lists}
+     dim D \\
+     value type T \\
+     engine tag Tag
+     \end{lists} etex);
+   boxit.remote[4](
+     btex \begin{files}
+     RemoteEngine.h
+     \end{files} etex);
+   
+   % RemoteDynamic
+   boxit.remotedynamic[0](btex \classname{Engine<1,T,Remote<Dynamic> >} etex);
+   boxit.remotedynamic[1](btex etex);
+   boxit.remotedynamic[2](
+     btex \begin{lists}
+     Engine() \\
+     Engine(Domain) \\
+     Engine(Domain,T) \\
+     Engine(Layout) \\
+     Engine(Engine) \\
+     read(Loc) \\
+     read(int ...) \\
+     operator()(Loc) \\
+     operator()(int ...) \\
+     domain() \\
+     create(CreateSize\_t) \\
+     destroy(Domain) \\
+     destroy(Iter, Iter)
+     \end{lists} etex);
+   boxit.remotedynamic[3](
+     btex \begin{lists}
+     value type T
+     \end{lists} etex);
+   boxit.remotedynamic[4](
+     btex \begin{files}
+     RemoteDynamicEngine.h
+     \end{files} etex);
+ 
+   
+   %% Position the boxes.
+   % Position the boxes within the UML class diagrams.
+   forsuffixes $=remote, remotedynamic:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   % Position the template parameters.
+   forsuffixes $=remote, remotedynamic:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=remote, remotedynamic:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+   
+   % Position the UML classes.
+   remote[0].c = origin;
+   xpart(remote[0].w - remotedynamic[0].w) = 0;
+   ypart(remotedynamic[3].n - remote[4].s) = -yUnit;
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=remote, remotedynamic:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=remote, remotedynamic:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the file names.
+   forsuffixes $=remote, remotedynamic:
+     drawunboxed($[4]);
+   endfor
+ 
+ endfig;
+ bye
Index: figures/explanation-uml-1.png
===================================================================
RCS file: explanation-uml-1.png
diff -N explanation-uml-1.png
Binary files /dev/null and explanation-uml-1.png differ
Index: figures/explanation-uml.mp
===================================================================
RCS file: explanation-uml.mp
diff -N explanation-uml.mp
*** /dev/null	Fri Mar 23 21:37:44 2001
--- explanation-uml.mp	Tue Feb 26 20:44:37 2002
***************
*** 0 ****
--- 1,246 ----
+ %% Oldham, Jeffrey D.
+ %% 2002Feb26
+ %% POOMA
+ 
+ %% Explanatory UML Diagram
+ 
+ %% This diagram indicates how to read a class UML diagram.
+ 
+ %% Assumes TEX=latex.
+ 
+ %% Ensure fonts are included in the output.
+ prologues := 2;			% >= 2 for PostScript
+ 
+ input boxes;
+ input box-macros;
+ input uml;
+ 
+ verbatimtex
+ \documentclass[10pt]{article}
+ \usepackage{amsmath}
+ \input{macros.ltx}
+ \usepackage{times}
+ \usepackage{mathptm}
+ \newlength{\cnw}	% Required to use \classnameWidth and \emptyBox
+ \begin{document}
+ etex
+ 
+ 
+ beginfig(1)
+   %% Create the boxes.
+   % Domain
+   boxit.domain[0](btex \classname{Classname1} etex);
+   boxit.domain[1](btex etex);
+   boxit.domain[2](
+     btex \begin{lists}
+     member function~1 \\
+     member function~2 \\
+     member function~3
+     \end{lists} etex);
+   boxit.domain[3](
+     btex
+     \begin{lists}
+     template parameter T
+     \end{lists} etex);
+   boxit.domain[4](
+     btex \begin{files}
+     implementation file~1 \\
+     implementation file~2
+     \end{files} etex);
+   
+   % Domain<1>
+   boxit.domainOne[0](btex \classname{Domain<1>} etex);
+   boxit.domainOne[1](btex etex);
+   boxit.domainOne[2](
+     btex \begin{lists}
+     long length() \\
+     int first() \\
+     int last() \\
+     int min() \\
+     int max() \\
+     Domain<1>::iter-\breakLine ator begin() \\
+     Domain<1>::iter-\breakLine ator end() \\
+     \end{lists} etex);
+   
+   % Domain<1>::iterator
+   boxit.domainOneIterator[0](btex \classname{Domain<1>::iterator} etex);
+   boxit.domainOneIterator[1](btex etex);
+   boxit.domainOneIterator[2](
+     btex \begin{lists}
+     operator*() \\
+     operator++() \\
+     operator->() \\
+     \end{lists} etex);
+   boxit.domainOneIterator[4](
+     btex \begin{files}
+     DomainIterator.h
+     \end{files} etex);
+ 
+   % Loc
+   boxit.loc[0](btex \classname{Classname2} etex);
+   boxit.loc[1](btex \emptyBox{Interval<1>} etex);
+   boxit.loc[2](btex etex);
+   boxit.loc[3](
+     btex \begin{lists}
+     template parameter T
+     \end{lists} etex);
+   boxit.loc[4](
+     btex \begin{files}
+     implementation file~a
+     \end{files} etex);
+ 
+   % Loc<1>
+   boxit.locOne[0](btex \classname{Classname2<1>} etex);
+   boxit.locOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.locOne[2](btex etex);
+ 
+   % Interval
+   boxit.interval[0](btex \classname{Interval} etex);
+   boxit.interval[1](btex \emptyBox{Interval<1>} etex);
+   boxit.interval[2](btex etex);
+   boxit.interval[3](
+     btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.interval[4](
+     btex \begin{files}
+     Interval.h \\
+     DomainTraits.Interval.h
+     \end{files} etex);
+   
+   % Interval<1>
+   boxit.intervalOne[0](btex \classname{Interval<1>} etex);
+   boxit.intervalOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.intervalOne[2](btex etex);
+ 
+   % Range
+   boxit.rangeBox[0](btex \classname{Range} etex);
+   boxit.rangeBox[1](btex \emptyBox{Interval<1>} etex);
+   boxit.rangeBox[2](btex etex);
+   boxit.rangeBox[3](btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.rangeBox[4](
+     btex \begin{files}
+     Range.h \\
+     DomainTraits.Range.h
+     \end{files} etex);
+ 
+   % Range<1>
+   boxit.rangeOne[0](btex \classname{Range<1>} etex);
+   boxit.rangeOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.rangeOne[2](btex etex);
+ 
+   % Grid
+   boxit.grid[0](btex \classname{Grid} etex);
+   boxit.grid[1](btex \emptyBox{Interval<1>} etex);
+   boxit.grid[2](btex etex);
+   boxit.grid[3](btex
+     \begin{lists}
+       dim D
+     \end{lists} etex);
+   boxit.grid[4](
+     btex \begin{files}
+     Grid.h \\
+     DomainTraits.Grid.h
+     \end{files} etex);
+   
+   % Grid<1>
+   boxit.gridOne[0](btex \classname{Grid<1>} etex);
+   boxit.gridOne[1](btex \emptyBox{Interval<1>} etex);
+   boxit.gridOne[2](btex etex);
+   
+   %% Position the boxes.
+   % Position the boxes within the UML class diagrams.
+   forsuffixes $=domain, domainOne, domainOneIterator, loc, locOne, interval, intervalOne, rangeBox, rangeOne, grid, gridOne:
+     samewidth($[0],$[1],$[2]);
+     for t = 0 upto 1:
+       $.[t].se = $[t+1].ne;
+       $.[t].sw = $[t+1].nw;
+     endfor
+     fixsize($[0],$[1],$[2]);
+   endfor
+   % Position the template parameters.
+   forsuffixes $=domain, loc, interval, rangeBox, grid:
+     fixsize($[3]);
+     $[0].ne - $[3].sw  =
+     (min(0.5 xpart($[3].ne - $[3].sw), $[0].dx),
+       min(0.5 ypart($[3].ne - $[3].sw), $[0].dy));
+   endfor
+   % Position the implementation files boxes.
+   forsuffixes $=domain, domainOneIterator, loc, interval, rangeBox, grid:
+     fixsize($[4]);
+     $[2].s = $[4].nw;
+   endfor
+   
+   % Position the UML classes.
+   domain[0].c = origin;
+   domainOne[0].nw - domain[0].ne = (xUnit,0);
+   domainOneIterator[0].nw - domainOne[0].ne = (xUnit,0);
+   domain[2].s - loc[0].n = (0, max(0, ypart(domain[2].s - domainOne[2].s)));
+   loc[2].s - locOne[0].n = (0, 2yUnit);
+   interval[0].nw - loc[0].ne = (xUnit, 0);
+   interval[2].s - intervalOne[0].n = (0, yUnit);
+   rangeBox[0].nw - interval[0].ne = (2xUnit, 0);
+   rangeBox[2].s - rangeOne[0].n = (0, yUnit);
+   grid[0].nw - rangeBox[0].ne = (xUnit, 0);
+   grid[2].s - gridOne[0].n = (0, yUnit);
+   
+   %% Draw the boxes.
+   % Draw the UML class boxes.
+   forsuffixes $=domain, loc:
+     for t = 0 upto 2:
+       drawboxed($[t]);
+     endfor
+   endfor
+   forsuffixes $=locOne:
+     for t = 0 upto 0:
+       drawboxed($[t]);
+     endfor
+   endfor
+   % Draw the template parameters.
+   forsuffixes $=domain, loc:
+     unfill bpath($[3]);
+     drawunboxed($[3]);
+     draw bpath($[3]) dashed evenly;
+   endfor
+   % Draw the file names.
+   forsuffixes $=domain, loc:
+     drawunboxed($[4]);
+   endfor
+   
+   % Draw arrows between classes.
+   drawarrow locOne[0].n -- loc[2].s dashed evenly;
+ 
+   % Draw lines between classes.
+   drawDiscriminator(domain[2].s, 0);
+   numeric foo; foo = 0.7yUnit;
+   forsuffixes $=loc:
+     draw $[0].n -- ($[0].n+(0,foo));
+   endfor
+   z0 = domain[2].s - (0,discriminatorScale);
+   draw z0 -- (x0, ypart(loc[0].n+(0,foo)));
+ 
+   % Add explanatory labels.
+   label.rt(btex Public data members, if any, would be listed here. etex,
+     domain[1].e);
+   label.rt(btex Public member functions, if any, are listed here. etex,
+     domain[2].e);
+   label.rt(btex This class adds no new public member functions. etex,
+     loc[2].e);
+   label.lrt(btex Template parameters are listed in dashed boxes. etex,
+     0.4[loc[3].sw,loc[3].s]);
+   label.rt(btex Files implementing the class etex, loc[4].e);
+   label.rt(btex A dashed arrow indicates an instantiated class. etex,
+     0.7[loc[2].s,locOne[0].n]);
+   label.lft(btex \begin{tabular}{l}Class specialization is indicated by\\ an arrow with a large triangle.\end{tabular} etex,
+     0.5[domain[2].s,loc[0].n]);
+   label.rt(btex This class's details are presented elsewhere. etex,
+     locOne[0].e);
+   
+ endfig;
+ 
+ 
+ bye
Index: figures/macros.ltx
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/figures/macros.ltx,v
retrieving revision 1.4
diff -c -p -r1.4 macros.ltx
*** figures/macros.ltx	2002/01/31 21:29:58	1.4
--- figures/macros.ltx	2002/02/27 03:44:37
***************
*** 42,44 ****
--- 42,83 ----
  	% Avoid a problem with dvitomp and ligatures.
  \newcommand{\avoidFi}{F\mbox{}i}%
  	% Avoid a problem with dvitomp and ligatures.
+ 
+ %% UML Macros.
+ 
+ % Produce a class's name, presumbly at the top of a UML class box.
+ % input <- class's name
+ \newcommand{\classname}[1]{\strut\texttt{#1}}
+ 
+ % Produce a class's name, presumbly at the top of a UML class box,
+ % with a width equal to the specified class's name.
+ \newcommand{\classnameWidth}[2]{\strut\settowidth{\cnw}{\classname{#2}}\makebox[\cnw]{\classname{#1}}}%
+ 	% Requires:	1. class's name
+ 	%		2. class name to set the width
+ 
+ % Produce an empty box with width equal to specified class name.
+ \newcommand{\emptyBox}[1]{\settowidth{\cnw}{\classname{#1}}\makebox[\cnw]{\strut}}%
+ 	% Requires:	1. class name to set width
+ 
+ % Produce a list of operations, attributes, or template parameters.
+ % The contents should be acceptable for a tabular{l} environment.
+ % These are displayed in small typewriter text.
+ \newenvironment{lists}%
+   {\ttfamily \small \begin{tabular}{l}}%
+   {\end{tabular}}
+ 
+ % Break one line and indent following line.
+ \newcommand{\breakLine}{\\ \hspace{1ex}}
+ 
+ % Produce a list of files.
+ % The contents should be acceptable for a tabular{l} environment.
+ % These are displayed in scriptsize typewriter text.
+ \newenvironment{files}%
+   {\ttfamily \scriptsize \begin{tabular}{l}}%
+   {\end{tabular}}
+ 
+ 
+ % Print bound parameters.
+ \newcommand{\binder}[1]{\guillemotleft #1\guillemotright}%
+ 	% Requires:	1. bound parameters
+ 	%		inclusion of 'aeguill' package
Index: figures/uml.mp
===================================================================
RCS file: uml.mp
diff -N uml.mp
*** /dev/null	Fri Mar 23 21:37:44 2001
--- uml.mp	Tue Feb 26 20:44:37 2002
***************
*** 0 ****
--- 1,28 ----
+ %% Oldham, Jeffrey D.
+ %% 2002Feb19
+ %% Pooma
+ 
+ %% MetaPost Macros for UML Diagrams
+ 
+ %% Discriminator
+ 
+ %% Connects specialized classes to general class.  The triangle points
+ %% up and may be scaled appropriately.
+ path discriminator;
+ discriminator = origin -- ((1,0) rotated -120) -- ((1,0) rotated -60) -- cycle;
+ 
+ numeric discriminatorScale; discriminatorScale = 0.5cm;
+ 
+ % The location is the top of the triangle
+ vardef drawDiscriminator(expr location, rotation) =
+   draw discriminator scaled discriminatorScale rotated rotation shifted location;
+ enddef;
+ 
+ 
+ %% Spacing definitions
+ numeric unit; unit = 1cm;
+ numeric xUnit; xUnit = unit;
+ numeric yUnit; yUnit = unit;
+   
+ % Arrowhead modifier.
+ ahlength := 2ahlength;
Index: programs/Sequential/initialize-finalize-annotated.patch
===================================================================
RCS file: /home/pooma/Repository/r2/docs/manual/programs/Sequential/initialize-finalize-annotated.patch,v
retrieving revision 1.1
diff -c -p -r1.1 initialize-finalize-annotated.patch
*** programs/Sequential/initialize-finalize-annotated.patch	2002/01/31 22:20:43	1.1
--- programs/Sequential/initialize-finalize-annotated.patch	2002/02/27 03:44:37
***************
*** 1,20 ****
! *** initialize-finalize.cpp	Thu Jan 24 11:14:13 2002
! --- initialize-finalize-annotated.cpp	Thu Jan 24 11:14:17 2002
  ***************
! *** 1,4 ****
!   #include "Pooma/Pooma.h"
  ! #include <iostream>
    
    int main(int argc, char *argv[])
! --- 1,5 ----
! + <programlisting id="initialize-finalize-program" linenumbering="numbered" format="linespecific">
!   #include "Pooma/Pooma.h"
  ! #include &lt;iostream&gt;
    
    int main(int argc, char *argv[])
! ***************
! *** 11,12 ****
! --- 12,14 ----
      return 0;
    }
  + </programlisting>
--- 1,35 ----
! *** /home/oldham/pooma/pooma1/examples/Manual/Sequential/initialize-finalize.cpp	Mon Feb 25 13:11:58 2002
! --- initialize-finalize-annotated.cpp	Mon Feb 25 13:40:48 2002
  ***************
! *** 1,14 ****
! ! #include "Pooma/Pooma.h"
  ! #include <iostream>
    
    int main(int argc, char *argv[])
!   {
!     // Prepare the Pooma library for execution.
! !   Pooma::initialize(argc,argv);
!   
!     std::cout << "Hello, Pooma." << std::endl;
!   
!     // Tell the Pooma library execution has finished.
! !   Pooma::finalize();
!     return 0;
!   }
! --- 1,16 ----
! ! <programlisting id="initialize-finalize-program" linenumbering="numbered" format="linespecific">
! ! #include "Pooma/Pooma.h"  <co id="initialize-finalize-program-header_file"></co>
  ! #include &lt;iostream&gt;
    
    int main(int argc, char *argv[])
!   {
!     // Prepare the Pooma library for execution.
! !   Pooma::initialize(argc,argv);  <co id="initialize-finalize-program-initialize"></co>
!   
!     std::cout << "Hello, Pooma." << std::endl;
!   
!     // Tell the Pooma library execution has finished.
! !   Pooma::finalize();  <co id="initialize-finalize-program-finalize"></co>
      return 0;
    }
  + </programlisting>