[pooma-dev] [PATCH] Reference documentation structure
James Crotinger
jcrotinger at proximation.com
Mon Feb 10 05:48:35 UTC 2003
Hi Richard,
Is this structure a rearrangement of the source? I do not think this would
be a good idea since CVS doesn't support moving files, and losing the
history is bad.
Jim
-----Original Message-----
From: Richard Guenther [mailto:rguenth at tat.physik.uni-tuebingen.de]
Sent: Saturday, February 08, 2003 4:20 PM
To: Jeffrey Oldham
Cc: pooma-dev at pooma.codesourcery.com
Subject: [pooma-dev] [PATCH] Reference documentation structure
The following patch will introduce a structure for grouping source files.
The result will look like the modules page you can find here:
http://www.tat.physik.uni-tuebingen.de/~rguenth/pooma/reference/modules.html
I include below the summaries of the groups for which I added one.
2003Feb09 Richard Guenther <richard.guenther at uni-tuebingen.de>
* docs/reference/array.doxygen: new file.
docs/reference/connect.doxygen: new file.
docs/reference/databrowser.doxygen: new file.
docs/reference/domain.doxygen: new file.
docs/reference/engine.doxygen: new file.
docs/reference/evaluator.doxygen: new file.
docs/reference/field.doxygen: new file.
docs/reference/internal.doxygen: new file.
docs/reference/io.doxygen: new file.
docs/reference/layout.doxygen: new file.
docs/reference/objects.doxygen: new file.
docs/reference/particles.doxygen: new file.
docs/reference/partition.doxygen: new file.
docs/reference/pete.doxygen: new file.
docs/reference/pooma.doxygen: new file.
docs/reference/threads.doxygen: new file.
docs/reference/tiny.doxygen: new file.
docs/reference/tulip.doxygen: new file.
docs/reference/unused.doxygen: new file.
docs/reference/utility.doxygen: new file.
/**
* @defgroup Connect
* @ingroup Utilities
* Classes/Files for managing connections to external agents such as
* visualization tools.
*
* Support for using the PAWS library is available. PAWS provides a
* mechanism for sharing multidimensional array and simple scalar
* variables between separate parallel programs.
*
* Support for using the Lux library for run-time visualization is
* available.
*
*/
/**
* @defgroup Lux
* @ingroup Connect
*
* Support for using the Lux library for run-time visualization.
*
*/
/**
* @defgroup Paws
* @ingroup Connect
*
* Support for using the PAWS library. PAWS provides a
* mechanism for sharing multidimensional array and simple scalar
* variables between separate parallel programs.
*
*/
/**
* @defgroup Domain Domain Objects and Modifiers
* @ingroup Structuring
* These are classes which handle specifying a domain and modifying it.
*
* The types of domains can be divided into two classes, namely integer
* domains and continuous domains.
*
* Integer domains include
* - int
* - Loc<Dim>
* - Interval<Dim>
* - Range<Dim>
* - Grid<Dim>
*
* The only continuous domain class is Region<Dim>. There are a few special
* domain classes, namely NullDomain, AllDomain and ErrorDomain.
*
* All domain classes come with their corresponding traits class
* DomainTraits<class> which is used to manage operations on domains
* such as
* - splitting domains with the split function
* - querying if domains overlap using the touches function
* - querying the intersection of two domains using the intersect function
* - growing/shrinking Interval<Dim> using the shrinkRight, growRight,
* shrinkLeft and growLeft functions
* - finding the equivalent subset for a domain from a given transformation
* using the equivSubset function
* - remove the overlap between two Interval<Dim> and return a vector of the
* resulting domain using the DomainRemoveOverlap function
* - querying if one domain contains another using the contains function
*
* Domains can be modified by arithmetic operations and new domains can
* be constructed using the helper classes in NewDomain.h and the LeftDomain
* and RightDomain wildcard classes.
*
* You can iterate through domains by FIXME.
*
* Some domains can be sliced FIXME.
*
*/
/**
* @defgroup Engine Engines
* @ingroup Objects
*
* Engine related classes/files.
*
* Engines provide the storage for Arrays and Fields and handle
* domain decomposition, taking subviews and accessing components
* transparently by providing a common interface to their users.
*
* Engine are usually defined recursively. Engines categorize into
* engines allocating storage for data, engines that provide access
* to computed data and engines providing modified access to other
* engines.
*
* For the first category, the storage engines, the following are
* evailable:
* - Engine < Dim, T, Brick >
* - Engine < Dim, T, CompressibleBrick >
* - Engine < Dim, T, Dynamic >
* - Engine < Dim, T, ConstantFunction >
*
* For the second category, the computation engines, the following
* are available:
* - Engine < Dim, T, IndexFunction < Functor > >
* - Engine < Dim, T, StencilEngine < Function, Expression > >
* - Engine < Dim, T, UserFunctionEngine < UserFunction, Expression > >
* - Engine < Dim, T, ExpressionTag < Expr > >
*
* For the second category the most important engine types include:
* - Engine < Dim, T, Remote < Tag > >
* - Engine < Dim, T, MultiPatch < LayoutTag, PatchTag > >
* - Engine < Dim, T, CompFwd < Eng, N > >
* - Engine < Dim, T, IndirectionTag < A1, A2 > >
* - Engines of the category
* Engine < Dim, T, ViewEngineType >, where
* ViewEngineType is one of
* BrickView,
* MultiPatchView<LayoutTag, PatchTag, Dim>,
* DynamicView
* and ViewEngine<OriginalDim, ViewedEngineTag>
*
* Views of Engines can be constructed by using the NewEngine<> traits
* class which takes the to be viewed engine type and the subsetting
* domain type as template parameters. NewEngine<> then defines the type
* of the ViewEngine as Type_t typedef member.
*
* FIXME: Introduce NewEngineEngine<>, NewEngineDomain<> and
* newEngineEngine() and newEngineDomain() with their concepts.
*/
/**
* @defgroup Evaluator
* @ingroup Objects
*
* The evaluators present different ways to operate on Arrays and Fields.
*
* This includes fortran-like manual looping over the patches of the
* data using the PatchFunction<> mechanism which supports multiple
* input data but only one output. (PatchFunction.h, PatchKernel.h)
*
* Another way to operate is using the ScalarCode<> facility which
* presents something like a n-argument stencil operation with some
* of the arguments being the output. (ScalarCode.h, ScalarCodeInfo.h,
* MultiArgKernel.h, MultiArgEvaluator.h)
*
* Evaluating a functor at a whole domain is done using the
LoopApplyEvaluator.
* (LoopApply.h)
*
* The most simple way is to use POOMA expressions who are evaluated
* via ExpressioKernel objects. (ExpressionKernel.h)
*
* The internal evaluator objects are templated on the patch type which
* gets constructed from the expression node types using the
* EvaluatorCombine<> traits class and produce the tags
* RemoteMultiPatchEvaluatorTag, MultiPatchEvaluatorTag,
RemoteSinglePatchEvaluatorTag
* and SinglePatchEvaluatorTag. The MainEvaluatorTag specialized class is
* the root of any evaluation.
*
*/
/**
* @defgroup Field Fields
* @ingroup Objects
*
* Field related classes/files. Important classes include Field, FieldEngine
* Centering and CanonicalCentering.
*
*/
/**
* @defgroup Mesh Field Meshes
* @ingroup Field
*
* Meshes provide a way to attach coordinate information to the
* vertices of a grid. You can choose between different mesh types
* which constrain positions in a different way. All available meshes
* are rectilinear, i.e. are constructed as outer product of spacing
* vectors.
*
* To query a mesh for its positions or similar properties use the
* functions positions(), outwardNormals(), coordinateNormals(),
cellVolumes(),
* faceAreas() and edgeLengths().
*
* Predefined mesh types are:
* - UniformRectilinearMesh which defines a uniformly spaced rectilinear
mesh,
* - RectilinearMesh which defines a arbitrarily spaced rectilinear mesh,
* - NoMesh which defines a mesh without a mesh.
*
* Meshes are completed by one of Cartesian, Cylindrical or Spherical
* coordinate system classes. Complete types for mesh can be constructed
* using the MeshTraits traits class and the appropriate tag classes for
* the mesh type and the coordinate system type.
*
*/
/**
* @defgroup DiffOps
* @ingroup Field
*
*/
/**
* @defgroup Relations Field Relations
* @ingroup Field
*
* Relations are FIXME.
*
* Usable predefined relations include boundary conditions of which
* the following are available:
* - ConstantFaceBC
* - PeriodicFaceBC
* - PosReflectFaceBC
*
*/
/**
* @defgroup Layout Layouts - Laying out Domains
* @ingroup Structuring
*
* A layout combines domain information and guard cell (both internal
* and external) information and maps the domain to a specified partition.
* So related topics are the \ref Domain and \ref Partition groups.
*
* All layouts operate with domains based on Interval<Dim>, i.e. a
* continuous integer domain. This domain gets distributed/tiled in a
* different way for different layout classes, namely
* - DomainLayout does not tile/distribute the domain, hence it is
applicable
* for local computation only
* - GridLayout tiles/distributes the Dim-dimensional domain by constructing
* a (possibly) non-uniform rectilinear grid of subdomains (GridTag)
* - UniformGridLayout tiles/distributes the domain using a uniform
rectilinear
* grid of subdomains (UniformTag)
* - SparseTileLayout tiles/distributes the domain using non-overlapping
* subdomains that need not cover the whole domain (SparseTileTag)
* - DynamicLayout tiles/distributes the domain using a grid partition and
* handles dynamic domains such as coming from DynamicArray (DynamicTag)
*
* For actually using any of the above layout on a MultiPatch engine you
need
* to specify appropriate grid tags which are one of those specified above
* alongst the layout classes.
*
* Specifying the actual tiling is done by several constructors dealing with
* the most important tiling types. The generic way to specify tiling is to
* use a partitioner, see \ref Partition for reference.
*
* Mapping the domain to the tiling can be done in two different ways,
* namely distributed and replicated which is specified using an instance
* of the DistributedTag and ReplicatedTag classes to the layout
constructors.
* Distributed means the domain is distributed over the tiling, replicated
* means the entire domain is replicated over the tiling. Note that remote
* engines do not make sense in conjunction with replicated layouts, and
this
* will trigger a runtime error.
*
*/
/**
* @defgroup Objects Data object and container classes
* Objects for storing data and for doing computation with.
*
* Note that for complex objects like Fields and Arrays placed inside
* structures the compiler will generate default copy constructors and
* assignment operators that usually violate the principle of least
* surprise in that they will invoke the objects assignment operator
* which will cause a PETE expression to be evalutated and this may
* lead to cryptic compiler error messages for for example IndexFunction
* engine objects. To work around this you need to explicitly provide
* copy constructors and assignment operators that use obj.initialize()
* instead of an assignment. This will catch you if you are using
* IndexFunction like objects, such as Stencils and FieldStencils. For
* writable objects be prepared to get assertion failures because of
* unitialized objects created by a default constructors are later
* initialized by default copy/assignment.
*/
/**
* @defgroup Partition Partitioning Domains
* @ingroup Structuring
*
* These files deal with domain partitioning and mapping the partition
* to computation nodes. The following partitioners are available:
* - GridPartition
* - UniformGridPartition
* - TilePartition
*
* You usually dont need to interact with the mappers, which are
* LocalMapper, ContextMapper, BisectionMapper, ContiguousMapper,
* DistributedMapper and UniformMapper. They deal with mapping patches
* to nodes, where LocalMapper is used for ReplicatedTag tagged layouts
* and the others, derived from the base ContextMapper, for DistributedTag
* tagged layouts.
*
*/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://sourcerytools.com/pipermail/pooma-dev/attachments/20030209/c71899f4/attachment.html>
More information about the pooma-dev
mailing list