on the way to elliptic

git-svn-id: http://svn.cactuscode.org/arrangements/CactusElliptic/EllBase/trunk@6 57bc7290-fb3d-4efd-a9b1-28e84cce6043

3 files changed, 46 insertions, 6 deletions

diff --git a/src/Ell_Interface.c b/src/Ell_Interface.c
index 1ddca73..78058e7 100644
--- a/src/Ell_Interface.c
+++ b/src/Ell_Interface.c
@@ -12,32 +12,54 @@
 static pNamedData *LinConfMetricSolverDB;
 static pNamedData *LinMetricSolverDB;
 
+/* Elliptic Equation class: LinEllConfMetric */
+
+/* Registers the Equation class wrapper (the function which is called for a
+   specific class of problems by passing all the necessay arguments PLUS
+   the name of the desired solver */
 void Ell_LinConfMetricRegistry(void (*function), const char *sname) {
   StoreNamedData(&LinConfMetricSolverDB,sname,(void*)function);
 }
 
+/* The Equation class wrapper, for the ellitpic class LinConfMetric 
+   (linar elliptic problem that requires the metric plus a
+   conformal factor). It derives the function to call from the 
+   passed registration name of the solver "sname".
+   Specifically it takes:
+   grid hierarchy, integer array of the metric+conf.factor indeces, 
+   field index, Mindex, Nindex, real array for absolute tolerances 
+   and relative tolerances, the registration name of the solver */
 void Ell_LinConfMetricSolver(cGH *GH, int *MetricPsi, int *FieldIndex, 
-               int *MIndex, int *NIndex, int *AbsTol, int *RelTol, const char *sname) {
-
+			     int *MIndex, int *NIndex, 
+			     CCTK_REAL *AbsTol, CCTK_REAL *RelTol, 
+			     const char *sname) {
+  /* prototype for the equation class wrapper */
   void (*fn)(cGH *GH,int *MetricPsi, int *FieldIndex, 
-               int *MIndex, int *NIndex, int *AbsTol, int *RelTol);
-  
+	     int *MIndex, int *NIndex, 
+	     int *AbsTol, int *RelTol);
+ 
+  /* derive the fucntion name from the requested name and hope it is there */
   fn = (void(*))GetNamedData(LinConfMetricSolverDB,sname);
   if (!fn) CCTK_WARN(0,"Cannot find solver! ");
   
+  /* Call the solver and pass through all the necessary arguments */
   fn(GH, MetricPsi, FieldIndex, MIndex, NIndex, AbsTol, RelTol);
 }
 
+
+/* Fortran wrappr for the routine Ell_LinConfMetricSolver */
 void FMODIFIER FORTRAN_NAME(Ell_LinConfMetricSolver)
      (cGH *GH, int *MetricPsi, int *FieldIndex, 
       int *MIndex, int *NIndex, int *AbsTol, int *RelTol, ONE_FORTSTRING_ARG) {
   ONE_FORTSTRING_CREATE(sname); 
-  Ell_LinConfMetricSolver(GH, MetricPsi, FieldIndex, MIndex, NIndex, AbsTol, RelTol, sname);
+  Ell_LinConfMetricSolver(GH, MetricPsi, FieldIndex, MIndex, NIndex, 
+			  AbsTol, RelTol, sname);
   free(sname);
 }
 
 
-
+/* Elliptic Equation class: LinEllMetric */
+/* sam idea as described above */
 void Ell_LinMetricRegistry(void (*function), const char *sname) {
   StoreNamedData(&LinMetricSolverDB,sname,(void*)function);
 }
diff --git a/src/Ell_Register.c b/src/Ell_Register.c
index 80d568e..ae1d061 100644
--- a/src/Ell_Register.c
+++ b/src/Ell_Register.c
@@ -10,10 +10,24 @@
 
 static pNamedData *EqNameDB;
 
+/* Ell_RegisterEq takes a routine ("function") and registers that routi  ne 
+   under the name "eqname" in the EqNameDB"
+   Application: Call Ell_Register with the routine that registers a solver 
+   for a elliptic equation class. */
 void Ell_RegisterEq(void *(function)(const char *, void*), const char *eqname) {
     StoreNamedData(&EqNameDB, eqname, (void*)function);
 }
 
+/* Ell_RegistersSolver takes a routine ("function") and registers that 
+   routine under the name  "sname" with the database specified by "eqname".
+   So, how do we get to the database, after all it needs to be hardcoded
+   as pNamedData ? Well, we know its name and in Ell_RegisterEq we have 
+   registered a function under the equation class name. 
+   We now get that function and use that function to register the solver.
+   Sounds confusing, well it is. The advantage is, that somebody can come 
+   up with a new equation class and can keep the database (the pNamedData
+   declaration) in his own routine and does not have to put it in a central
+   place. Amen*/
 
 void Ell_RegisterSolver(void (*function),  const char *sname, const char *eqname) {
   void (*fn)(void *, const char *);
diff --git a/src/Startup.c b/src/Startup.c
index 71dce6b..02ac4d2 100644
--- a/src/Startup.c
+++ b/src/Startup.c
@@ -5,6 +5,10 @@
 #include "cctk.h"
 #include "cctk_parameters.h"
 
+/* At Startup, EllBase registers the elliptic equation classes for which 
+   it provides solvers. Other routines, which may come up with new classes, 
+   can registers the classes in their own thorns. */
+
 void Ell_RegisterBaseEqTypes(cGH *GH) {
   void Ell_RegisterEq(void (*function),const char *);
   void Ell_LinConfMetricRegistry(void (*function),const char *);