Contribution to Thorn Guide

The LaTeX file, doc/documentation.tex, is included in Thorn Guides built by the Cactus make system. (e.g. by gmake 4#4config5#5-ThornGuide). Ideally this file should contain complete (and up-to-date) details about the thorn, exactly what is relevant is for the authors to decide, but remember that the Cactus make system automatically parses the thorn CCL files to include information about all parameters, variables and scheduling. Suggested sections include:

• Model. A description of the system which the thorn is modelling, including the equations, etc., which are being solved or implemented.

• Numerical implementation. Details about how the model is numerically implemented in the thorn.

• Using the thorn. Any special details needed for using the thorn, tricky parameters, particular operating systems or additional required software, interactions with other thorns and examples of use.

• History. Here is where you should describe why the thorn was written, any previous software or experience which was made use of, the authors of the thorn source code and documentation, how to get hold of the thorn, etc.

• References. A bibliography can be included, referencing papers published using or about this thorn, or additional information about the model or numerics used.

A LaTeX template for the Thorn Guide documentation can be found in the flesh distribution at

doc/ThornGuide/template.tex,

this file is automatically copied to the correct location in a new thorn which is created with gmake newthorn.

Since Cactus scripts need to parse this documentation, and since the LaTeX document should be consistent across all thorns included in a Thorn Guide, please follow the guidelines below when filling in the documentation:

• Use the Cactus Thorn Guide style file, located in the flesh distribution at doc/latex/cactus.sty. This should be included using a relative link, so that updates to the style file are applied to all thorns.

  \usepackage{../../../../doc/latex/cactus}
  

• Aside from the date, author, and title fields, all of the documentation to be included in a Thorn Guide should be placed between the lines

  % START CACTUS THORNGUIDE

  and

  % END CACTUS THORNGUIDE

• The command 11#11def can be used to define macros, but all such definitions must lie between the START and END line. Do not redefine any standard LaTeX command

• Do not use the 11#11appendix command, instead include any appendices you have as standard sections.

• We only support PDF (.pdf) figures. Graphics figures should be included using the includegraphics command (not epsffig), with no file extension specified. For example,

  \begin{figure}[ht]
    \begin{center}
      \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
    \end{center}
    \caption{Illustration of this and that}
    \label{MyArrangement_MyThorn_MyLabel}
  \end{figure}
  

• All labels, citations, references, and graphic images names should conform to the following guidelines: ARRANGEMENT_THORN_LABEL. For instance, if you arrangement is called CactusWave, your thorn WaveToyC, and your original image blackhole.eps, you should rename your image to be CactusWave_WaveToyC_blackhole.eps

• References should be formatted with the standard LaTeX bibitem command, for example, a bibliography section should look like:

  \begin{thebibliography}{9}
    \bibitem{MyArrangement_MyThorn_Author99}
    {J. Author, \textit{The Title of the Book, Journal, or periodical}, 1 (1999),
    1--16. \url{http://www.nowhere.com/}}
  \end{thebibliography}