moved parts of the HOWTO into the PETSc Thornguide

git-svn-id: http://svn.cactuscode.org/arrangements/CactusElliptic/EllPETSc/trunk@43 1d96b42b-98df-4a6a-9d84-1b24288d4588

1 files changed, 78 insertions, 0 deletions

diff --git a/doc/ThornGuide.tex b/doc/ThornGuide.tex
index 743066e..c434f20 100644
--- a/doc/ThornGuide.tex
+++ b/doc/ThornGuide.tex
@@ -99,6 +99,84 @@ The sizes of the arrays {\tt Mlinear} for the coefficient matrix and
 variables are of a sized greater 1. In this case, the array can be
 accessed.
 
+\section{General remarks: PETSc within Cactus}
+
+\subsection{PETSc in src code}
+Use PETSc as normal, Use the PUGH communicator if a routine needs a
+communictor. 
+On first pass, you need to make a call to PETScSetCommWorld()
+and PetscInitialize() to set the PETSc communicator and initialize
+PETSc.
+
+
+This could be a seperate routine scheduled early in schedule.ccl at
+BASEGRID eg. PetscInitialize() requires the commandline parameters
+as input. It allows you to pass through the flags, etc. (I have not 
+ried this feature.) Initialize the PETSc communicator with the Cactus
+communicator. You end up having code like this:
+
+\begin{verbatim}  
+  /* The pugh Extension handle */	
+  pGH *pughGH;
+  
+  /* Get the link to pugh Extension */
+  pughGH = (pGH*)GH->extensions[CCTK_GHExtensionHandle("PUGH")];
+
+  if (first_trip==0) 
+  {
+    int argc;
+    char **argv;
+
+    /* Get the commandline arguments */
+    argc = CCTK_CommandLine(&argv);
+
+    /* Set the PETSc communicator to set of 
+       PUGH and initialize PETSc */
+    ierr = PetscSetCommWorld(pughGH->PUGH_COMM_WORLD); CHKERRA(ierr);
+    PetscInitialize(&argc,&argv,NULL,NULL);
+    
+    CCTK_INFO("PETSc initialized");
+  }
+\end{verbatim}
+
+\subsection{make.code.defn}
+You need to tell Cactus to look for the PETSc includes: 
+In the file make.code.defn define the SRCS (sources) as explained in
+the dcoumentation and add a lien for SUS\_INC\_DIR which lets Cactus
+look for additional includes, eg.:
+\begin{verbatim}
+SYS_INC_DIRS += $(PETSC_DIR) $(PETSC_DIR)/include  \
+                $(PETSC_DIR)/bmake/$(PETSC_ARCH)
+\end{verbatim}
+
+\subsection{make.configuration.defn}
+This file is not created by the when you use Cactus to create a new
+thorn by "gmake newthorn". For a template PETSc configuration file,
+have a look in ./CactusElliptic/EllPETSc/src/make.configuration.defn.
+
+The first section checks if PETSC\_DIR/PETSC\_LIB are set. If they are
+not, the configuration process will be interrupted (otherwise you have 
+to wait to the end of the compilation to find out that your program
+won't link). 
+
+Second section specifies the standard PETSc libs. eg.:
+\begin{verbatim}
+PETSC_LIB_DIR = $(PETSC_DIR)/lib/libg/$(PETSC_ARCH)
+PETSC_LIBS    = petscts petscsnes petscsles petscdm
+\end{verbatim}
+
+Third section adds platform dependent file, by checking  
+PETSC\_ARCH and assigning the appropriate libs.
+
+In the end the variables are assigned to the variables that Cactus
+make process is using (note the incremental assignment "+=")
+
+\begin{verbatim}
+LIBDIRS    += $(PETSC_LIB_DIR) $(X_LIB_DIR)
+LIBS       += $(PETSC_LIBS) $(PLATFORM_LIBS) X11
+EXTRAFLAGS += -I$(PETSC_DIR)/include
+\end{verbatim} 
+
 %\section{My own section}
 
 % Automatically created from the ccl files