[PATCH] Sync some toplevel documentation

[Richard Guenther <rguenth@xxxxxxxxxxxxxxxxxxxxxxxxxxx>]

Hi!

I just looked around for uncommitted deltas in my closest-to-CVS
repository and came along the following documentation update.

Ok?

Richard.


2004Jul20  Richard Guenther <richard.guenther@xxxxxxxxxxxxxxxx>

	* docs/reference/array.doxygen: add summary.
	docs/reference/field.doxygen: extend summaries, remove mentioning
	of MeshTraits, document Relations.
	docs/reference/particles.doxygen: add summary.

Index: array.doxygen
===================================================================
RCS file: /home/pooma/Repository/r2/docs/reference/array.doxygen,v
retrieving revision 1.1
diff -u -u -r1.1 array.doxygen
--- array.doxygen	10 Oct 2003 17:33:40 -0000	1.1
+++ array.doxygen	20 Jul 2004 09:15:29 -0000
@@ -2,4 +2,7 @@
  * @defgroup Array Arrays
  * @ingroup Objects
  *
+ * Arrays are simple multi-dimensional indexable data containers.  Data is
+ * managed using the various engines (\ref Engine) and the related layouts
+ * (\ref Layout).
  */
Index: field.doxygen
===================================================================
RCS file: /home/pooma/Repository/r2/docs/reference/field.doxygen,v
retrieving revision 1.1
diff -u -u -r1.1 field.doxygen
--- field.doxygen	10 Oct 2003 17:33:40 -0000	1.1
+++ field.doxygen	20 Jul 2004 09:15:30 -0000
@@ -2,9 +2,16 @@
  * @defgroup Field Fields
  * @ingroup Objects
  *
- * Field related classes/files. Important classes include Field, FieldEngine
- * Centering and CanonicalCentering.
- *
+ * Fields as opposed to Arrays are compound objects out of possibly multiple
+ * sub-fields spreading data over multiple centering points per cell and/or to
+ * multiple materials.  Fields come with the notion of a Mesh which adds
+ * coordinate information to the indices and can be linked together using
+ * \ref Relations to automate updates of field dependencies.  \ref Relations
+ * are also used to implement automatic boundary conditions.
+ *
+ * The Fields engine, FieldEngine, is composed of a \ref Mesh, Centering information
+ * and a list of \ref Relations.  Further it contains references to possibly
+ * multiple engines representing Fields data or expression.
  */
 
 /** 
@@ -26,24 +33,44 @@
  *  - 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
  *
+ * A simple stencil implementation for (single-centered) Fields,
+ * FieldStencilSimple, and example divergence and gradient operators.
  */
 
 /** 
  * @defgroup Relations Field Relations
  * @ingroup Field
  *
- * Relations are FIXME.
+ * Relations are a way to couple fields via expressions.  That is, you define
+ * a relation of a Field A (LHS) to one or more Fields B, C, ... (RHS).  Think
+ * of it as a definition like A := F(B, C, ...) where A gets updated using the
+ * relation F if one of the arguments to F has changed since the last read of
+ * A.
+ *
+ * Relations are defined via Pooma::newRelation() which takes a relation functor
+ * as its first argument followed by the LHS and one or multiple RHS fields.  Look
+ * at the Pooma::functionPtr and Pooma::memberPtr for how to supply global functions
+ * or class members as the relation function.
+ *
+ * A relation functor needs to include a default constructor, a copy constructor
+ * with an extra LHS typed argument and an operator() for evaluation.  An example
+ * would look like
+<PRE>
+struct MyFunctor {
+  MyFunctor() {}
+  MyFunctor(const MyFunctor&, const LHS&) {}
+  void operator()(const LHS& lhs, const RHS1& rhs1, const RHS2& rhs2) {
+    lhs.all() = (rhs1 + rhs2).all();
+  }
+};
+</PRE>
+ * and be initialized with Pooma::newRelation(MyFunctor(), lhs, rhs1, rhs2).
  *
  * Usable predefined relations include boundary conditions of which
  * the following are available:
Index: particles.doxygen
===================================================================
RCS file: /home/pooma/Repository/r2/docs/reference/particles.doxygen,v
retrieving revision 1.1
diff -u -u -r1.1 particles.doxygen
--- particles.doxygen	10 Oct 2003 17:33:40 -0000	1.1
+++ particles.doxygen	20 Jul 2004 09:15:30 -0000
@@ -2,6 +2,12 @@
  * @defgroup Particles Particles (partly pre-r2)
  * @ingroup Objects
  *
- * Particles files/classes.
+ * Particle support concentrates on PIC (Particle In Cell) like operation
+ * which means particle interaction is done via Fields.  Unlike particle
+ * methods like SPH (Smoothed Particle Hydrodynamics) there are no ghost particles,
+ * but parallelization works through Field guard cells.
+ *
+ * Main mechanisms for Particle - Field interaction are the gather and scatter
+ * operations together with various predefined interpolation methods.
  *
  */