Additions to Interface section

git-svn-id: http://svn.cactuscode.org/flesh/trunk@173 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 132 insertions, 2 deletions

diff --git a/doc/UsersGuide/UsersGuide.tex b/doc/UsersGuide/UsersGuide.tex
index c01a9cf3..efba5b53 100644
--- a/doc/UsersGuide/UsersGuide.tex
+++ b/doc/UsersGuide/UsersGuide.tex
@@ -503,8 +503,8 @@ is to do.)
 
 {\q Tom, this is for you}
 
-	b) Make methodology (dependencies,libraries, thorn make files
-	etc)
+        b) Make methodology (dependencies,libraries, thorn make files
+        etc)
 
       d) Configuration options
 
@@ -602,7 +602,137 @@ thorn into it.
 \chapter{Using TAGS}
     \section{TAGS with emacs}
     \section{TAGS with vi}
+
+
 \chapter{Configuration file syntax}
+    
+\section{General Concepts}
+
+Each thorn is configured by three compulsory files in the top level thorn
+directory:
+\begin{itemize}
+\item{} interface.ccl
+\item{} param.ccl
+\item{} schedule.ccl
+\end{itemize}
+
+\section{interface.ccl}
+
+The interface configuration file consists of a header block giving details 
+of the thorns relationship with other thorns, and then a series of blocks 
+listing the thorn's global variables.
+The header block has the form:
+{\t 
+\begin{verbatim}
+implements: <implementation>
+[inherits: <implementation>, <implementation>]
+[friend: <implentation>, <implementation>]
+\end{verbatim}
+}
+where
+\begin{itemize}
+\item{} The implentation name must be unique among all thorns, unless ????.
+\item{} Inheriting from another implentation makes all that implentations public 
+        variables and parameters available to your thorn. At least one thorn 
+        providing any inherited implentation must be present at compile time.
+        A thorn cannot inherit from itself. Inheritance is associative, but not
+        commutative.
+\item{} Being a friend of another implementation makes all that implementations 
+        protected and public (????)
+        variables and parameters available to your thorn. A friend is not required 
+        for compilation. A thorn cannot be its own friend. Friendship is 
+        associative and commutative.
+\end{itemize} 
+
+The thorn's variables are defined by:
+{\t
+\begin{verbatim}
+[<access>:]
+
+VTYPE <group name> [TYPE=<gtype>] [DIM=<dim>] 
+[{
+   <variable name>[,]<variable name>
+   <variable name>
+}]
+\end{verbatim}}
+
+\begin{itemize}
+\item{} {\t access} defines which thorns have can use the following 
+        groups, and can be either {\t public}, {\t protected} or {\t private}.
+\item{} {\t VTYPE} defines the data type of the variables in the group.
+Supported data types are {\t LOGICAL}, {\t INTEGER}, {\t CHAR} and {\t REAL}.
+\item{} {\t group name} must be a alpha-numeric name which is unique 
+within the scope of the thorn. A group name is compulsory.
+\item{} {\t TYPE} designates the kind of variables held by the group.
+The choices are {\t GF}, {\t ARRAY} or {\t SCALAR}. This field is 
+optional, with the default variable type being {\t SCALAR}.
+\item{} {\t DIM} defines the spatial dimension if the group is of type
+{\t ARRAY} or {\t GF}, and can take the value {\t 1}, {\t 2}, or {\t 3}.
+The default value is {\t DIM=3}.
+\item{} The block following the group declaration line contains a list of
+        variables contained in the group. All variables in a group have 
+        the same data type, variable type and dimension. The list can be 
+        separated by spaces, commas, or new lines. The variable names 
+        must be unique within the scope of the thorn. 
+        A variable can only be a member of 
+        one group. The block must be delimited by brackets on new lines.
+        If no block is given after a group declaration line, a 
+        variable with the same name as the group is created.
+\end{itemize} 
+
+\section{param.ccl}
+
+\section{schedule.ccl}
+
+The schedule configuration files consists of 
+\begin{itemize}
+\item{} assignments to switch on storage and communications 
+        for array variables at the start of program execution.
+\item{} {\it schedule blocks} which schedule a subroutine from the
+        thorn to be called at a specified time during program 
+        executation. Statements within the schedule block can
+        be used to switch on storage and communication for groups
+        of variables during the duration that the subroutine is called.
+\item{} Conditional statements
+\end{itemize}
+
+{\it assignments statements} have the form:
+{\t
+\begin{verbatim}
+[STORAGE: <group>, <group>]
+[COMMUNICATION: <group>, <group>]
+\end{verbatim}
+}
+
+Each {\it schedule block} in the file {\t schedule.ccl} must have
+the syntax:
+{\t
+\begin{verbatim}
+schedule [<function name>] at <time>
+{
+  [LANG: <language>]
+  [STORAGE: <group>,<group>]
+  [COMMUNICATION: <group>,<group>]
+  [TRIGGER: <grid function>,<grid function>]
+}
+\end{verbatim}
+}
+
+Any schedule block or assignment statements can be optionally 
+surrounded by conditional {\t if-elseif-else}
+constructs using the parameter data base. These can be nested,
+and have the general form:
+{\t
+\begin{verbatim}
+if (CCTK_Equals(<parameter>,<string>)) 
+{
+  [<assignments>]
+  [<schedule blocks>]
+}
+\end{verbatim}
+Conditional constructs cannot be used inside of a schedule block.
+
+
 \chapter{CCTK Parameters}
 \chapter{Thorn-Flesh Interface}