\documentclass[a4paper]{article}
\usepackage{hevea}
\usepackage{color}
\usepackage{graphicx}
\usepackage{gfs}

\oddsidemargin=4mm
\evensidemargin=-1mm
\topmargin=-7mm
\textwidth=15.42cm
\textheight=23.2cm

\renewcommand{\cuttingunit}{subsection}

\title{Gerris examples}

\begin{document}

\mbox{}\vspace{1cm}
\begin{center}
{\huge Gerris examples}\\
{\large Version GFS_VERSION\\
\vspace{5mm}
\today}
\vspace{1cm}
\end{center}

\tableofcontents

\section{Introduction}

This document is a collection of examples contributed by Gerris users and intended to illustrate the range of applications where Gerris is applicable. It should also serve as a useful starting point for customised applications.

The sections in this document are a rough classification of the various applications. In particular, an example appearing in a subsection usually indicates that this example is a relatively small incremental change over the parent example appearing in the section above it.

Gerris parameter files are commented and cross-linked with the \htmladdnormallinkfoot{Object Hierarchy}{\gfsweb/wiki/index.php/Object\_hierarchy} documentation. As a rule, the first examples in the document contain comments for most of the instructions in the parameter file. Latter examples only contain comments for the relevant new instructions or for more complex usage of already introduced instructions.

The indicative running times given are representative of the running time on an Intel 2.4 GHz processor.

The usefulness and quality of this document very much depend on the contributions of users. If you think you have used Gerris in an interesting way which is not already covered by the existing examples, you are very welcome to contribute. Have a look at section \ref{howto} for instructions on how to do so.

\section{2D}

\test{cylinder}
\test{cylinder/heated}
\test{cylinder/parallel}
\test{rt}
\test{boussinesq}
\test{logo}
\test{column}
\test{starting}
\test{viscmix}
\test{bubble}

\section{3D}

\test{tangaroa}
\test{plateau}
\test{atomisation}
\test{ship}
\test{forcedturbulence}
\test{wingtip}

\section{Shallow-water}

\test{tides}

\section{Saint-Venant (non-linear shallow-water)}

\test{dam}
\test{hump}
\test{shock}
\test{monai}
\test{tsunami}

\section{Waves}

\test{garden}
\test{cyclone}

\section{\label{howto}How to write examples}

This document is generated automatically using self-documenting Gerris parameter files. If you look at \htmladdnormallinkfoot{any}{cylinder/cylinder.gfs} of the {\tt .gfs} files in this document you will see that apart from comments on specific instructions, the top of the file contains fields which describe the simulation. They are:
\begin{description}
\item[Title:] the title of the simulation.
\item[Description:] a Latex block of text describing the simulation. It can contain figures, tables, equations etc\dots
\item[Author:] you.
\item[Command:] the exact command needed to run the example.
\item[Version:] the version of Gerris you used (output of {\tt gerris2D -V}).
\item[Required files:] any file (e.g. GTS files etc\dots) other than the Gerris simulation file required to run the simulation. Try to keep the total size of these files reasonable.
\item[Running time:] the approximate total running time of the simulation. This is of course machine-dependent but must be appropriately scaled to be representative of the running time on an Intel 2.4 GHz processor.
\item[Generated files:] any file (movies, images, curves etc\dots) generated by the simulation.
\end{description}
Apart from the ``Description:'' field all the fields must fit on a single line just after the field name.

Any extra data you need for the description (e.g. figures as EPS files) must be generated by the simulation. Have a look at other examples to see how this can be done.

Once you have an initial draft for your documented parameter file, you need to package it like this:
\begin{enumerate}
\item Choose a short name for your example. This short name should not already be used by any of the examples in this document. Let's say {\tt myexample}.
\item Create a directory {\tt myexample}.
\item Copy your parameter file in {\tt myexample/myexample.gfs}. You must use the same name for the directory and the parameter file.
\item Copy any other file you need (as listed in the ``Required files:'' field) in {\tt myexample}.
\item Cd to {\tt myexample} and re-run the simulation (using the command listed in the ``Command:'' field) or alternatively copy the previously generated files listed in the ``Generated files:'' field into {\tt myexample}.
\item Cd to {\tt myexample/..}
\item\label{gendoc} Generate the HTML and PDF documentation for your example using:
\begin{verbatim}
% gfs2doc myexample
\end{verbatim}
Note that this script requires \footahref{http://pauillac.inria.fr/\~maranget/hevea/index.html}{hevea}.
\item Check that the {\tt myexample\_html/index.html} and {\tt myexample.pdf} files are to your liking. If they are not, edit your parameter file and return to \ref{gendoc}.
\item Send me ({\tt s.popinet at gmail.com}) your example ({\tt myexample.tgz} as an attachment). Tell me which section, subsection you think it would most naturally fit in (or request a new section). I will then review it and integrate it in this document.
\end{enumerate}

\bibliographystyle{plain}
\bibliography{gerris}

\end{document}
