Manual Changes: Preface, Coding Conventions, UML Diagrams
Jeffrey
oldham at codesourcery.com
Wed Feb 27 04:02:12 UTC 2002
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>/* … */</literal> comments occasionally occur
+ when commenting an intraline value.</para>
+
+ <para>&c; files, including header files, exclusively use
+ <literal>/* … */</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 ">⪆⪆>⪆⪆>" >
<!-- 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 "-⪆-" >
<!-- 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ïve">
<!-- The word "na\"{\i}ve." -->
<!ENTITY naivecap "Naï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 D.</primary></indexterm></para>
!
! <section id="preface-notation">
! <title>Notation</title>
!
! <para>UNFINISHED</para>
! </section>
!
!
! <section id="preface-reading_book:">
! <title>How to Read This &bookcap;</title>
!
! <para>FINISH: Write this section in a style similar to Lamport's
! LaTeX section 1.2. FINISH: Fix the book title and the section
! number.</para>
! </section>
!
!
! <section id="preface-downloading">
! <title>Obtaining &pooma; and Sample Programs</title>
!
! <para>Available for free from what WWW site? Include what portions
! of <filename class="libraryfile">LICENSE</filename>? Be sure to
! include CVS instructions as well.</para>
!
! <para>Which additional packages are necessary and when?</para>
!
! </section>
!
!
! <section id="preface-using_modifying">
! <title>Using and Modifying &pooma;</title>
!
! <para>&pooma; is available under open source license. It can be
! used and modified by anyone, anywhere. Can it be sold? Include
! <filename class="libraryfile">LICENSE</filename>.</para>
!
! <para>QUESTION: How do developers contribute code?</para>
!
! </section>
-
- <section id="preface-acknowledgements">
- <title>Acknowledgements</title>
- ]]> <!-- end unfinished -->
-
- <![%temporary;[
- <preface id="acknowledgements">
- <title>Acknowledgements</title>
- ]]> <!-- end temporary -->
-
- <para>This &book; would not have been completed without the help
- and encouragement of a lot of people and organizations. Los Alamos
- National Laboratory funded the writing of this manual and the
- development of the &poomatoolkit;. John Reynders conceived,
- advocated, and headed &pooma; development in its early days, and
- Scott Haney continued the leadership. Susan Atlas, Subhankar
- Banerjee, Timothy Cleland, Julian Cummings, James Crotinger, David
- Forslund, Salman Habib, Scott Haney, Paul Hinker, William Humphrey,
- Steve Karmesin, Graham Mark, Jeffrey D. Oldham, Ji Qiang, John
- Reynders, Robert Ryne, Stephen Smith, M. Srikant, Marydell
- Tholburn, and Timothy Williams all helped develop &pooma;. Rod
- Oldehoeft and Jeff Brown of Los Alamos National Laboratory
- supported CodeSourcery's and Proximation's work, including the
- development of this manual. John Hall, Don Marshall, Jean
- Marshall, and the rest of the BLANCA team at Los Alamos worked
- closely with the developers and provided valuable suggestions for
- improvements.</para>
-
- <para>I am grateful to James Crotinger, Mark Mitchell, and Stephen
- Smith who answered my many questions during the writing of this
- &book;.</para>
-
- <!-- We cheat and abuse an epigraph here. -->
- <epigraph>
- <attribution>Jeffrey D. Oldham, 2002 January</attribution>
- <para></para>
- </epigraph>
-
- <![%temporary;[
- </preface>
- ]]> <!-- end temporary -->
-
<![%unfinished;[
- </section>
-
- </preface>
- ]]> <!-- end unfinished -->
-
-
- <![%unfinished;[
<part id="programming">
<title>Programming with &pooma;</title>
<!-- FIXME: Add a partintro to the part above? -->
]]> <!-- end unfinished -->
! &introductory-chapter;
! &template-chapter;
&tutorial-chapter;
--- 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>¨ Class Diagrams</title>
! <para>In this chapter, we present Unified Modeling Language (¨)
! 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 ¨ 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
! ¨ class diagram. The diagram has three classes:
! <type>Classname1</type>, <type>Classname2</type>, and
! <type>Classname2<1></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<1></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<1></type>
! instantiates <type>Classname2</type> with <type>T</type> equal
! to 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<1></type>
! template instantiation has additional member functions. It uses
! the <type>Domain<1>::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<1></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,
+ …, or 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 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 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; 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 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 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 D. Oldham, Ji Qiang, John
+ Reynders, Robert Ryne, Stephen Smith, M. Srikant, Marydell
+ Tholburn, and Timothy Williams all helped develop &pooma;. Rod
+ Oldehoeft and Jeff Brown of Los Alamos National Laboratory
+ supported CodeSourcery's and Proximation's work, including the
+ development of this manual. John Hall, Don Marshall, Jean
+ Marshall, and the rest of the BLANCA team at Los Alamos worked
+ closely with the developers and provided valuable suggestions for
+ improvements.</para>
+
+ <para>I am grateful to James Crotinger, Mark Mitchell, 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 D. Oldham, 2002 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 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 …
+ </programlisting>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>Pooma::initialize</function></funcdef>
+ <paramdef>
+ <parameter class="function">int &argc,</parameter>
+ <parameter class="function">char ** &argv,</parameter>
+ <parameter class="function">bool initRTS = true,</parameter>
+ <parameter class="function">bool getCLArgsArch = true,</parameter>
+ <parameter class="function">bool initArch = true</parameter>
+ </paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::initialize</function></funcdef>
+ <paramdef>
+ <parameter class="function">Pooma::Options &opts,</parameter>
+ <parameter class="function">bool initRTS = true,</parameter>
+ <parameter class="function">bool initArch = true</parameter>
+ </paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::finalize</function></funcdef>
+ <void></void>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>bool <function>Pooma::finalize</function></funcdef>
+ <paramdef>
+ <parameter class="function">bool quitRTS,</parameter>
+ <parameter class="function">bool quitArch</parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <bridgehead id="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 <iostream>
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 <iostream>
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>
More information about the pooma-dev
mailing list