path: root/doc/UsersGuide/Appendices.tex

\part{Appendices}

\appendix

\chapter{Configuration file syntax}
\label{sec:cofisy}    

\section{General Concepts}
\label{sec:geco}

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}
These files are written in the {\it Cactus Configuration Language} which is
case insensitive.

\section{interface.ccl}
\label{sec:in}

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, except between 
        thorns which have the same public and protected variables and 
        parameters.
\item{} Inheriting from another implentation makes all that implentations 
        public variables 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 and 
        recursive, but not commutative.
\item{} Being a friend of another implementation makes all that 
        implementations 
        protected variables available to your thorn. At least one thorn
        providing an implementation for each friend must be present at
        compile time. A thorn cannot be its own friend. Friendship is 
        associative and commutative. Note that your thorn is also a friend
        of all your thorns friend's friends.
\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>
}] [``<group description>'']
\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}.
(In the future {\t COMPLEX} will also be supported.)
\item{} {\t group name} must be a alpha-numeric name (which may also 
contain underscores) 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.
\item{} An optional description of the group can be given on the last line, 
        at the moment this description is not used for any purpose.
\end{itemize} 

\section{param.ccl}
\label{sec:pa}

The parameter configuration file consists of a list of 
{\it parameter object specification items} (OSIs) giving the type and
range of the parameter separated by optional
{\it parameter data scoping items} (DSIs) which detail access to the
parameter.

\subsection{Parameter Data Scoping Items}
{\t
\begin{verbatim}
<access>:
\end{verbatim}
}
The key word {\t access} designates that all parameter object specification
items up to the next parameter data scoping item are in the same 
protection or scoping class. {\t access} can take the values:
\begin{itemize}
\item{} {\t public} --- all thorns have access to public parameters
\item{} {\t protected} --- other thorns can have access to these 
                           parameters if they specifically request
                           it in their own param.ccl
\item{} {\t private} --- only your thorn has access to private parameters
\item{} {\t friend} --- in this case an {\t implementation} name must follow
                        the colon. It declare that all the parameters in 
                        the following scoping block are protected variables
                        from the specified {\t implementation}.
\end{itemize}


\subsection{Parameter Object Specification Items}
\label{sec:paobspit}

{\t
\begin{verbatim}
[EXTENDS] <parameter type> <parameter name> ``<parameter description>'' 
{
  <PARAMETER VALUES>
} <default value>
\end{verbatim}
}
\begin{itemize}
\item{} Allowed {\t parameter types} are 
  \begin{itemize}
     \item{} {\t INTEGER} The specification of parameter values takes 
     the form of any number of comma-separated blocks of the form:
{\t
\begin{verbatim}
[<low-range>][:[<high-range>][:[<step>]]][::``<range description>'']
\end{verbatim}
}
Where an empty field, or a {\t *} in the place of {\t low-range} or
{\t high-range} indicates $-\infty$ and $\infty$ respectively. The 
default value for {\t step} is 1. A number by itself denotes that
this number is the only acceptable value.
     \item{} {\t REAL} The range specification is the same as integers,
             except that here, no {\t step} implies a continuum of values.
     \item{} {\t KEYWORD} Each entry in the list of acceptable values 
             for a keyword has the form 
{\t
\begin{verbatim}
``<keyword value>'', ``<keyword value>'' :: ``<description>''
\end{verbatim}
}
     \item{} {\t STRING}  No allowed values should be specified for a logical 
             parameter.
     \item{} {\t LOGICAL} No allowed values should be specified for a logical 
             parameter. The default value for a logical can be 
        \begin{itemize}
           \item{} True: {\t 1}, {\t yes}, {\t y}, {\t t}, {\t true}
           \item{} False: {\t 0}, {\t no}, {\t n}, {\t f}, {\t false}
        \end{itemize}
  \end{itemize}

\item{} The {\t parameter name} must be unique within the scope of the thorn.

\item{} A thorn can declare that it {\t EXTENDS} a parameter that it is a 
        friend of. This allows it to declare additional acceptable values.
        By default it is acceptable for two thorns to declare the same 
        value as acceptable. 
\end{itemize}


\section{schedule.ccl}
\label{sec:sc}

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>]
} ``Description of 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}
\label{sec:ccpa}

\chapter{Using GNATS}
\label{sec:usgn}

\chapter{Using CVS}
\label{sec:uscv}

\chapter{Using TAGS}
\label{sec:usta}
Finding your way around in the Cactus structure can be pretty
difficult to handle. To make life easier there is support for TAGS,
which lets you browse the code easily from within Emacs/XEmacs or vi. 
A TAGS database can be generated with by gmake:

\section{TAGS with emacs}
\label{sec:tawiem}

{\tt gmake TAGS} will create a database for a routine reference
table to be used within Emacs. This database can be accessed within
emacs if you add either of the following lines to your {\tt .emacs} file:\\
{\tt (setq tags-file-name "CCTK\_dir/TAGS")} XOR \\
{\tt (setq tag-table-alist '(("CCTK\_dir" . "CCTK\_dir/TAGS")))}\\
where {\tt CCTK\_dir } is your CCTK directory.\\

You can now easily navigate the CCTK and Toolkits by searching for
functions or ``tags'':
\begin{enumerate}
\item \textbf{ Alt.} will find a tag
\item \textbf{ Alt,} will find the next matching tag
\item \textbf{ Alt*} will go back to the last matched tag
\end{enumerate}
If you add the following lines to your {\tt .emacs} file, the
files found with TAGS will opened in {\em read-only} mode:
\begin{verbatim}
(defun find-tag-readonly (&rest a)
  (interactive)
  (call-interactively `find-tag a)
  (if (eq nil buffer-read-only) (setq buffer-read-only t))  )

(defun find-tag-readonly-next (&rest a)
  (interactive)
  (call-interactively `tags-loop-continue a)
  (if (eq nil buffer-read-only) (setq buffer-read-only t))  )

(global-set-key [(control meta \.)] 'find-tag-readonly)
(global-set-key [(control meta \,)] 'find-tag-readonly-next)
\end{verbatim}
The Key strokes to use when you want to browse in read-only mode are:
\begin{enumerate}
\item{CTRL Alt.} will find a tag and open the file in read-only mode
\item{CTRL Alt,} will find the next matching tag in read-only mode
\end{enumerate}

\section{TAGS with vi}
\label{sec:tawivi}

The commands available are highly dependent upon the version of {\bf vi}, but
the following is a selection of commands which may work.


\begin{enumerate}

\item \textbf{vi -t tag} 
Start vi and position the cursor at  the  file and line where `tag' is defined.

\item \textbf{Control-]} 
Find the tag under the cursor.

\item \textbf{:ta tag} 
Find a tag.

\item \textbf{:tnext} 
Find the next matching tag.

\item \textbf{:pop} 
Return to previous location before jump to tag.

\item \textbf{Control-T} 
Return to previous location before jump to tag (not widely implemented).

\end{enumerate}



\chapter{Thorn-Flesh Interface}
\label{sec:thflin}