bring documentation (which was 6 months or so out of date)

up to date with the code


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/LocalInterp/trunk@135 df1f8a13-aa1d-4dd4-9681-27ded5b42416

1 files changed, 90 insertions, 119 deletions

diff --git a/src/GeneralizedPolynomial-Uniform/template.c b/src/GeneralizedPolynomial-Uniform/template.c
index 1f9fc9e..3eff291 100644
--- a/src/GeneralizedPolynomial-Uniform/template.c
+++ b/src/GeneralizedPolynomial-Uniform/template.c
@@ -75,6 +75,19 @@
 		#define FP_XYZ	fp x, fp y
   @endvar
 
+  @var	    STRIDE_IJK
+  @desc	    A comma-separated list of the (i,j,k) array strides for the
+	    interpolation, e.g.
+		#define STRIDE_IJK	stride_i, stride_j
+  @endvar
+
+  @var	    JACOBIAN_MIJK_STRIDE
+  @desc	    A comma-separated list of the (i,j,k) strides for the
+	    Jacobian, e.g.
+		#define JACOBIAN_MIJK_STRIDE	\
+			Jacobian_mi_stride, Jacobian_mj_stride
+  @endvar
+
   @var	    MOLECULE_MIN_M
   @vdesc    The minimum m coordinate in the molecule, e.g.
 		#define MOLECULE_MIN_M	-1
@@ -98,143 +111,98 @@
   @endvar
 
   @var	    HAVE_OP_{I,DX,DY,DXX,DXY,DYY,...}
-	    Each of these symbols should be defined or not defined
+  @vdesc    Each of these symbols should be defined or not defined
 	    according as if the corresponding derivative operator is
-	    to be supported or not supported by this function.
+	    to be supported or not supported by this function, e.g.
+		#define HAVE_OP_I
+		#define HAVE_OP_DX
+		#define HAVE_OP_DY
+		#define HAVE_OP_DXX
+		#define HAVE_OP_DXY
+		#define HAVE_OP_DYY
+	    if we support all 1st and 2nd derivatives in 2-D.
   @endvar
 
-  @var	    DATA_VAR_DCL_FILE_NAME
-  @vdesc    The name of a file (presumably machine-generated) containing
-	    a sequence of one or more C declarations for a molecule-sized
-	    set of "data variables", eg (for 2D size-3 molecules)
-		fp data_m1_m1;
-		fp data_0_m1;
-		fp data_p1_m1;
-		fp data_m1_0;
-		fp data_0_0;
-		fp data_p1_0;
-		fp data_m1_p1;
-		fp data_0_p1;
-		fp data_p1_p1;
+  @var	    DATA_STRUCT
+  @vdesc    The name of a C struct containing all the data variables,
+	    e.g.
+		#define DATA_STRUCT   data_struct_2d_cube_size3
   @endvar
 
-  @var	    COEFFS_{I,DX,DY,DXX,DXY,DYY,...}_DCL_FILE_NAME
-  @vdesc    Each of these macros should be the name of a file
-	    (presumably machine-generated) containing a sequence
-	    of one or more C declarations for a molecule-sized set
-	    of coefficients for the corresponding derivative operator,
-	    eg (for dx with 2D size-3 molecules)
-		fp coeffs_dx_m1_m1;
-		fp coeffs_dx_0_m1;
-		fp coeffs_dx_p1_m1;
-		fp coeffs_dx_m1_0;
-		fp coeffs_dx_0_0;
-		fp coeffs_dx_p1_0;
-		fp coeffs_dx_m1_p1;
-		fp coeffs_dx_0_p1;
-		fp coeffs_dx_p1_p1;
+  @var	    COEFF_STRUCT
+  @vdesc    The name of a C struct containing all the molecule coefficients,
+	    e.g.
+		#define COEFFS_STRUCT coeffs_struct_2d_cube_size3
   @endvar
 
-  @var	    COEFFS_{I,DX,DY,DXX,DXY,DYY,...}_VAR_STORE_FILE_NAME
-  @vdesc    The name of a file (presumably machine-generated) containing
-	    a sequence of C assignment statements to assign the interpolation
-	    coefficients to the corresponding COEFF(...) expressions,
-	    eg (for 2D size-3 molecules)
-		COEFF(-1,-1) = coeffs_dx_m1_m1;
-		COEFF(0,-1) = coeffs_dx_0_m1;
-		COEFF(1,-1) = coeffs_dx_p1_m1;
-		COEFF(-1,0) = coeffs_dx_m1_0;
-		COEFF(0,0) = coeffs_dx_0_0;
-		COEFF(1,0) = coeffs_dx_p1_0;
-		COEFF(-1,1) = coeffs_dx_m1_p1;
-		COEFF(0,1) = coeffs_dx_0_p1;
-		COEFF(1,1) = coeffs_dx_p1_p1;
+  @var	    FETCH_DATA_{REAL,REAL{4,8,16},COMPLEX,COMPLEX{8,16,32}}
+  @vdesc    The name of a C function to fetch data from the input arrays
+	    into the DATA_STRUCT structure.  Typically these will be
+	    chosem from among the functions defined in
+	    "common/fetch-template.[ch]", e.g.
+		#define FETCH_DATA_REAL		LocalInterp_fetch_2d_cube3_r
+		#define FETCH_DATA_REAL4	LocalInterp_fetch_2d_cube3_r4
+		#define FETCH_DATA_REAL8	LocalInterp_fetch_2d_cube3_r8
+		#define FETCH_DATA_REAL16	LocalInterp_fetch_2d_cube3_r16
+		#define FETCH_DATA_COMPLEX	LocalInterp_fetch_2d_cube3_c
+		#define FETCH_DATA_COMPLEX8	LocalInterp_fetch_2d_cube3_c8
+		#define FETCH_DATA_COMPLEX16	LocalInterp_fetch_2d_cube3_c16
+		#define FETCH_DATA_COMPLEX32	LocalInterp_fetch_2d_cube3_c32
   @endvar
 
-  @var	    DATA_VAR_ASSIGN_FILE_NAME
-  @vdesc    The name of a file (presumably machine-generated) containing
-	    a sequence of C assignment statements to assign DATA(...) to
-	    the corresponding data variables for each molecule component,
-	    eg (for 2D size-3 molecules)
-		data_m1_m1 = DATA(-1,-1);
-		data_0_m1 = DATA(0,-1);
-		data_p1_m1 = DATA(1,-1);
-		data_m1_0 = DATA(-1,0);
-		data_0_0 = DATA(0,0);
-		data_p1_0 = DATA(1,0);
-		data_m1_p1 = DATA(-1,+1);
-		data_0_p1 = DATA(0,+1);
-		data_p1_p1 = DATA(1,+1);
+  @var	    EVALUATE_MOLECULE
+  @vdesc    The name of a C function to evaluate the dot product
+	    of the DATA_STRUCT and COEFF_STRUCT structures.  Typically
+	    these will be chosem from among the functions defined in
+	    "common/evaluate.[ch]", e.g.
+		#define EVALUATE_MOLECULE	LocalInterp_eval_2d_cube6
   @endvar
 
-  @var	    INTERP_{I,DX,DY,DXX,DXY,DYY,...}_COMPUTE_FILE_NAME
-  @vdesc    Each of these macros should be the name of a file
-	    (presumably machine-generated) containing a C assignment
-	    statement (or a sequence of such statements) to compute
-	    the variable  result as the molecule-sized linear combination
-	    of the data variables (cf DATA_VAR_{DCL,ASSIGN}_FILE_NAME)
-	    and the interpolation coefficients
-	    (cf COEFFS_{I,DX,DY,DXX,DXY,DYY,...}_COMPUTE_FILE_NAME),
-	    eg (for 2D size-3 molecules, dx operator)
-		result =
-			coeffs_dx_m1_m1*data_m1_m1
-			+ coeffs_dx_0_m1*data_0_m1
-			+ coeffs_dx_p1_m1*data_p1_m1
-			+ coeffs_dx_p2_m1*data_p2_m1
-			+ coeffs_dx_m1_0*data_m1_0
-			+ coeffs_dx_0_0*data_0_0
-			+ coeffs_dx_p1_0*data_p1_0
-			+ coeffs_dx_p2_0*data_p2_0
-			+ coeffs_dx_m1_p1*data_m1_p1
-			+ coeffs_dx_0_p1*data_0_p1
-			+ coeffs_dx_p1_p1*data_p1_p1
-			+ coeffs_dx_p2_p1*data_p2_p1
-			+ coeffs_dx_m1_p2*data_m1_p2
-			+ coeffs_dx_0_p2*data_0_p2
-			+ coeffs_dx_p1_p2*data_p1_p2
-			+ coeffs_dx_p2_p2*data_p2_p2;
-	    Note that this may *NOT* include any variable declarations;
-	    it should be valid to appear in the middle of a sequence of
-	    C statements.
+  @var	    STORE_COEFFS
+  @vdesc    The name of a C function to store a COEDFF_STRUCT structure
+	    of the DATA_STRUCT and COEFF_STRUCT structures.  Typically
+	    this will be chosem from among the functions defined in
+	    "common/store.[ch]", e.g.
+		#define STORE_COEFFS		LocalInterp_store_2d_cube6
   @endvar
 
   @var	    COEFFS_{I,DX,DY,DXX,DXY,DYY,...}_COMPUTE_FILE_NAME
   @vdesc    Each of these macros should be the name of a file
-	    (presumably machine-generated) containing a sequence of C
-	    assignment statements to compute all the (molecule-sized
-	    set of) interpolation coefficients for the specified
-	    derivative operator, as polynomials in the variables
-	    (x,y,z), eg (for 2D size-3 molecules, dx operator)
-		fp t35,
-		   t42,
-		   t41,
-		   t40,
-		   t39,
-		   t36;
-		      t35 = RATIONAL(1.0,3.0)*x;
-		      t42 = t35+RATIONAL(-1.0,4.0)*y;
-		      t41 = t35+RATIONAL(1.0,4.0)*y;
-		      t40 = RATIONAL(-1.0,6.0);
-		      t39 = RATIONAL(1.0,6.0);
-		      t36 = RATIONAL(-2.0,3.0)*x;
-		      coeffs_dx_m1_m1 = t40+t41;
-		      coeffs_dx_0_m1 = t36;
-		      coeffs_dx_p1_m1 = t39+t42;
-		      coeffs_dx_m1_0 = t40+t35;
-		      coeffs_dx_0_0 = t36;
-		      coeffs_dx_p1_0 = t35+t39;
-		      coeffs_dx_m1_p1 = t40+t42;
-		      coeffs_dx_0_p1 = t36;
-		      coeffs_dx_p1_p1 = t39+t41;
+	    (presumably machine-generated) containing a sequence
+	    of C assignment statements to compute all the coefficients
+	    in a corresponding  coeffs_*  structure as polynomials
+	    in the variables (x,y,z), e.g. (for 2D size-3 molecules,
+	    dx operator)
+		fp t36;
+		fp t42;
+		fp t41;
+		fp t40;
+		fp t39;
+		fp t37;
+		      t36 = RATIONAL(1.0,3.0)*x;
+		      t42 = RATIONAL(1.0,4.0)*y+t36;
+		      t41 = t36+RATIONAL(-1.0,4.0)*y;
+		      t40 = RATIONAL(1.0,6.0);
+		      t39 = RATIONAL(-1.0,6.0);
+		      t37 = RATIONAL(-2.0,3.0)*x;
+		      coeffs_dx->coeff_m1_m1 = t39+t42;
+		      coeffs_dx->coeff_0_m1 = t37;
+		      coeffs_dx->coeff_p1_m1 = t40+t41;
+		      coeffs_dx->coeff_m1_0 = t36+t39;
+		      coeffs_dx->coeff_0_0 = t37;
+		      coeffs_dx->coeff_p1_0 = t36+t40;
+		      coeffs_dx->coeff_m1_p1 = t39+t41;
+		      coeffs_dx->coeff_0_p1 = t37;
+		      coeffs_dx->coeff_p1_p1 = t40+t42;
 
 	    As illustrated, the code may use the macro RATIONAL
 	    (defined later in this file) to represent rational-number
 	    coefficients, and it may also declare temporary variables
 	    as needed.
 
-	    Note that these are the only coefficients which depend
-	    on the actual interpolation scheme used; all the others
-	    just depend on the interpolation dimension and molecule
+	    Note that this is the only included code which depends
+	    on the actual interpolation scheme used; all the rest
+	    just depends on the interpolation dimension and molecule
 	    family and size.
   @endvar
 
@@ -517,18 +485,18 @@ int FUNCTION_NAME(/***** coordinate system *****/
  *				{
  *			case 0:
  *				STORE_COEFFS(1.0, &coeffs_I,
- *					     Jacobian_ptr, JACOBIAN_STRIDE_IJK,
+ *					     Jacobian_ptr, JACOBIAN_MIJK_STRIDE,
  *					     pt, part,
  *				break;
  *			case 1:
  *				STORE_COEFFS(inverse_dx, &coeffs_dx,
- *					     Jacobian_ptr, JACOBIAN_STRIDE_IJK,
+ *					     Jacobian_ptr, JACOBIAN_MIJK_STRIDE,
  *					     pt, part,
  *				break;
  *			...
  *			case 33:
  *				STORE_COEFFS(inverse_dz*inverse_dz, &coeffs_dzz,
- *					     Jacobian_ptr, JACOBIAN_STRIDE_IJK,
+ *					     Jacobian_ptr, JACOBIAN_MIJK_STRIDE,
  *					     pt, part,
  *				break;
  *				}
@@ -1565,6 +1533,9 @@ return 0;						/*** NORMAL RETURN ***/
 	variables, using the machine-generated experessions in the
 	files
 		COEFFS_{I,DX,DY,DXX,DXY,DYY,...}_COMPUTE_FILE_NAME
+
+	These functions *must* be static, because this whole file
+	is #included (and hence compiled) multiple times.
   @enddesc
   @@*/