\documentclass[12pt]{article}
      
\oddsidemargin=0.4in
\evensidemargin=0.4in
\textwidth=6.0in
\topmargin=-0.6in
\textheight=8.5in
 
\usepackage{psfig}
\usepackage{natbib}
\usepackage{svn}
\usepackage{hyperref}
 
\SVN $Revision$
\SVN $Date$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% proper link to most recent manual %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\manver}{7.12}
\newcommand{\manref}{ww3man2019}
\newcommand{\manregtestsec}{5.6}

\defcitealias{ww3man2019}{WW3DG}

\newcommand{\pstyle}{myheadings}
%\newcommand{\pstyle}{plain}
\newfont{\ff}{cmsl12}

\newcommand{\topline}{\rule{152mm}{0.5mm}}
\newcommand{\botline}{\vspace{1 mm}\rule{152mm}{0.5mm}}

\newcommand{\wwt}{WAVEWATCH III$\:$\textsuperscript\textregistered}
\newcommand{\ww}{WAVEWATCH III}
\newcommand{\ws}{WW3}
\newcommand{\refs}{(\ldots references \ldots)}
\newcommand{\p}{\partial}
\newcommand{\degree}{^{\circ}}
\newcommand{\bk}{\mbox{\bfmath $k$}}
\newcommand{\bc}{\mbox{\bfmath $c$}}
\newcommand{\lae}{$\lambda =$}
\newcommand{\mue}{$\mu =$}
\newcommand{\CCe}{$C =$}

\newcommand{\file}{\sf}
\newcommand{\code}{\tt}
\newcommand{\dir}{\sf}
\newcommand{\F}{\sc}

\newcommand{\command}[1]{\begin{center}{\code #1}\end{center}}

\newcommand{\pb}{\strut \vfill \pagebreak}
\newcommand{\bpage}{\vfill \pagebreak \strut

\vspace{2.5in} \centerline{This page is intentionally left blank.}}
\newcommand{\bpagea}{\strut

\vspace{2.5in} \centerline{This page is intentionally left blank.}}

\newcommand{\newsec}{\setcounter{equation}{0}
                      \setcounter{myfigno}{0}
                      \setcounter{mytabno}{0}}

\newenvironment{flist}{\begin{list}{nofile ?}{\parsep 0mm
            \itemsep 0mm \leftmargin 35mm \labelwidth 25mm
            \rightmargin 10mm}}{\end{list}}
\newcommand{\fit}[2]{\item[{\file{#1}}\hfill]{#2}}

\newcounter{myfigno}[section]
\newenvironment{myfig}[1]{\begin{figure}[#1]
                         \refstepcounter{myfigno}}                       
                        {\end{figure}}
\newenvironment{myfigx}[1]{\begin{figure}[#1]}                       
                        {\end{figure}}
\newcommand{\myfcap}[1]{\begin{list}{\ff Fig. \themyfigno\ :~\hfill}
                       {\rightmargin 8mm \labelsep 0mm
                        \labelwidth 8mm \leftmargin 8mm
                        \topsep 0mm \parskip 0mm \partopsep 0mm }
                        \item \ff #1 \end{list}}
\newcommand{\myfcapc}[1]{\begin{center} \ff Fig. \themyfigno\ :~ #1
                         \end{center}}
\newcommand{\myfcapx}[1]{\begin{center} \ff #1 \end{center}}

\newcounter{mytabno}[section]
\newenvironment{mytab}[1]{\begin{table}[#1]
                         \refstepcounter{mytabno}}                       
                        {\end{table}}
\newcommand{\mytcap}[1]{\begin{list}{\ff Table \themytabno :~\hfill}
                       {\rightmargin 8mm \labelsep 0mm
                        \labelwidth 8mm \leftmargin 8mm
                        \topsep 0mm \parskip 0mm \partopsep 0mm }
                        \item \ff #1 \end{list}
                        \vspace{\baselineskip}}
\newcommand{\mytcapc}[1]{\begin{center} \ff Table \themytabno : #1
                         \end{center} \vspace{\baselineskip}}

\renewcommand{\themyfigno}{\thesection.\arabic{myfigno}}
\renewcommand{\themytabno}{\thesection.\arabic{mytabno}}
\renewcommand{\theequation}{\thesection.\arabic{equation}}

\newcounter{mylistno}

\begin{document}

%--------------------------------------------------------------%
%           Title page                                         %
%--------------------------------------------------------------%

\pagestyle{empty}

\strut \vspace{5mm}

\begin{center} 
U. S. Department of Commerce \\
National Oceanic and Atmospheric Administration \\
National Weather Service \\
National Centers for Environmental Prediction \\
5830 University Research Court \\
College Park, MD 20740

\vspace{15mm}

{\bf Technical Note}

\vspace{15mm}

{\large \wwt\ development best practices $^\dag$.} \\

\vspace{20mm}

Hendrik L. Tolman$^\ddag$ (Editor)
\\
Environmental Modeling Center \\
Marine Modeling and Analysis Branch

\vspace{25mm}

% Version 0.1, May 2010
% Version 1.0, Feb. 2011
% Version 1.1, Mar. 2014
Version 1.2, Feb. 2019 %\today 
%\\ Last Changed Rev: \SVNRevision\ on \SVNDate \\
\vspace{\baselineskip}
\vfill {\sc this is an unreviewed manuscript, primarily
intended for informal exchange of information among ncep staff
members}

\end{center}
\noindent \rule{140mm}{0.5mm} \\
{\small $^\dag$ MMAB Contribution No.~286. \\
$^\ddag$ Contact code manager, e-mail: NCEP.List.WAVEWATCH@NOAA.gov} \\

\bpage

\pagebreak

%\markright{\fbox{\rm{DRAFT}} \hspace{2mm} \today}
\pagestyle{\pstyle}
\pagenumbering{roman}
\setcounter{page}{1}

%--------------------------------------------------------------%
%            Abstract                                          %
%--------------------------------------------------------------%
\addtocontents{toc}{\vspace{\baselineskip}}
\addcontentsline{toc}{section}{Abstract}

\begin{abstract}
This guide describes best practices for code development of \wwt. This
includes guidelines for packaging of codes delivered by general users to NCEP
according to the \ww\ license, as well as instructions for co-developers on
the use of the subversion depository at NCEP. The guide addresses codes,
documentation and manuals.
\end{abstract}

\vspace{\baselineskip}
\vspace{\baselineskip}
\vspace{\baselineskip}

\begin{center}
{\bf Change log} \\
\vspace{\baselineskip}
\begin{tabular}{|c|c|c|l|} \hline
version & svn rev.     & date    & comment    \\ \hline \hline
  0.1   &   7869       & May 14, 2010  & Initial MMAB No. 286.      \\ 
        &              &               & Sec.~\ref{sec:testing} (regression testing) \\
        &              &               & as placeholder only                   \\
  1.0   &  12398       & Feb. 18, 2011 & Adding svn note p.~\pageref{svn_n}.   \\
        &              &               & Adding svn warning p.~\pageref{svn_w}.\\
        &              &               & Section~\ref{sec:testing} updated.    \\
  1.1   &  38155       & Mar. 18, 2014 & Changed address on title page.        \\
        &              &               & Updating most sections.               \\
        &              &               & Adding Sec.~\ref{sec:dist} (code distr.). \\
        &              &               & Finalize for release of v. 4.18.      \\
  1.2   &              & Feb. 26, 2019 & Prepare for release of v. \manver.    \\
\hline \end{tabular}
\end{center}
\vspace{-3mm}
\strut \hspace{60mm} (minor edits included in each new version)

\vfill \pagebreak

%--------------------------------------------------------------%
%            Acknowledgements                                  %
%--------------------------------------------------------------%

\phantomsection
\addcontentsline{toc}{section}{Acknowledgments}

\noindent
{\it Acknowledgments.} Code management for \ww\ is provided by NCEP. Arun
Chawla (NCEP), Henrique Alves (SRG at NCEP), Erick Rogers and Tim Campbell
(NRL Stennis) contributed to this guide.

\vspace{\baselineskip} \noindent
This guide is available as a pdf file from

\vspace{\baselineskip}
\centerline{http://polar.ncep.noaa.gov/waves}


\vfill \pagebreak
%--------------------------------------------------------------%
%            Contents                                          %
%--------------------------------------------------------------%
\phantomsection
\addcontentsline{toc}{section}{Table of contents}

\tableofcontents

\pb
\pagestyle{empty}

\bpagea


\pb
\pagestyle{\pstyle}
\pagenumbering{arabic}
%--------------------------------------------------------------%
% Section : Introduction                                       %
%--------------------------------------------------------------%
\section{Introduction} \label{sec:intro}
\newsec

\noindent
The \wwt\ wind wave model has a history dating back to the second half of the
1980s. It's history started with the development of the WAVEWATCH model at
Delft university of technology \citep{tol:CHGE89, tol:CHGE90, tol:JPO91b}. The
next step of development occurred at NASA, Goddard Space Flight Center in the
early 1990s, with the development of WAVEWATCH II. This model was explicitly
designed for (vector) super computing, and focused on improved numerics
\citep{tol:JPO92, tol:ICCE92}. Development of \ww\ at NCEP started in 1993.
Compared to previous WAVEWATCH models, this model uses modified basic
equations, and introduces the present model architecture. This model utilizes
vector optimization, together with OpenMP or MPI parallel optimization, and
hence can be run efficiently on most modern computer architectures.  With
model version 3.14, \ww\ has been trademarked and copyrighted, and has been
distributed under an open-source style license \citep[see section 1.2 of ][or
the web
site\footnote{~http://polar.ncep.noaa.gov/waves/wavewatch/license.shtml
}]{tol:MMAB09a}. Henceforth, \ww\ will be denoted as \ws.

Five public releases of \ws\ have been made available \citep{tol:OMB99a,
tol:OMB02c, tol:MMAB09a, tol:MMAB14a}, including the current release version 5.16 \citepalias[2016]{ww3man2016}. This best practices guide was first
provided with model versions 3.14 for two reasons. First, coding standards are
needed to foster and support community model development. This has become
particularly important with the National Oceanographic Partnership Program
(NOPP) project to improve all basic wave model source terms, which will run
from 2010 through 2014, and which will use \ws\ as a main development
vehicle. This means that several teams will work simultaneously on the \ws\
code. Second, there is a need for unifying coding approaches within NCEP. A
first set of standards has been developed for the Community Radiative Transfer
Model (CRTM) as presented in \cite{rep:PvD08}. Whereas it is unrealistic to
retrofit all NCEP codes to a completely homogeneous coding standard due to the
shear size of legacy codes, all basic precepts should be the same, and are
consistent between the present guide and \cite{rep:PvD08}.

From the beginning, \ws\ has been envisioned as a modeling framework, with
various options for numerical and physical approaches, both for operational
and research applications. With a focus on operations at NCEP, selections of
numerical and physical approaches are done at the compile level of the
code. This limits the complexity of the source code that is used in
operations. For example, complex exact interaction codes are not compiled into
the operational models at NCEP, and hence do not need to be maintained in the
operational code versions. Compile level code selections are made using the
native \ws\ preprocessor and `switches' in the source code, as described in
full in the \ws\ manuals as identified above.

Starting with the release model version 3.14, we were maintaining the code
using subservion \citep{bk:CSea06} and now are maintaining the code via git. 
The master version of \ws\ will be
maintained and supported at NCEP. With the licensing of model version 3.14,
users that develop code and/or modifications for \ws\ are obligated to offer
these back to NCEP, relative to the most recent version of \ws\ available to
them\footnote{~Public release or research version on svn server, depending on
user access.}. NCEP will then decide if such modifications and additions will
be included in the master version of \ws, and will be responsible for
including it in the authoratitive git repository. 

In this context, coding standards, best practices for upgrading parts of \ws\
and for adding new pieces to \ws, regression testing, and maintenance of
documentation are essential. These issues are approached in
Sections~\ref{sec:style} (also including copyright statements), \ref{sec:add},
\ref{sec:testing}, and \ref{sec:man}, respectively.  Finally,
Section~\ref{sec:svn} discusses standards of code management using the
subversion server at NCEP.

Some formatting practices for the \ws\ manual are used in this guide. The
{\file file} font will be used to identify files, scripts and command line
entries. The {\code CODE} font is used to identify source code. Previous
experience with \ws\ is expected, and the use of, for instance, optional
switches in the code, will not be explained here in detail.


\pb
%--------------------------------------------------------------%
% Section : Programming style                                  %
%--------------------------------------------------------------%
\section{Programming style} \label{sec:style}
\newsec

\ws\ is written in ANSI standard Fortran 90, fully modular, and with an
internal dynamic data structure exclusively using use-associated data modules.
All modules are internally documented with a style of documentation as
illustrated in Fig.~\ref{fig:docu_subr} and \ref{fig:docu_mod} for subroutines
and modules, respectively. Examples of this can be found throughout the source
code, and templates are also provided in `user slot' routines for source terms
and propagation schemes. 

Is should be noted that \ws\ consists of incomplete (`{\file .ftn}') FORTRAN
files that require standard \ws\ preprocessing. All changes and additions
should be made in these files, not in extracted true FORTRAN files (for
details see the manual).

The following is expected of codes provided to NCEP for inclusion in the
official version of \ws :

\begin{list}{\roman{mylistno})}{\usecounter{mylistno} \rightmargin 8mm
                                \leftmargin 10mm \labelsep 2mm}

\item Fully document the code following the outline described above.

\item Follow the coding style of \ws, in particular :

\begin{itemize}
\item For readability, code is written following the use of columns as in
      fixed format Fortran, even though codes are technically written in free
      format. Use typical indent strategies for loops and logical structures.
\item Code intended as permanent code is written in upper case, temporary
      (test) code is written in lower case. Note that we encourage the
      inclusion of permanent test output to be activated at compile time using
      the \ws\ compile switches\footnote{~See manual for details on use of
      compile level switches.} like `{\code !/T}'. The latter test output
      should be coded in upper case as a permanent part of the code.
\end{itemize}

\item Maintain an update log at the top of each module and for each individual
      routine or function, and update the last update date in the header of
      each module, function and routine, as has been done in the distribution
      version of \ws. If a module only contains one program element, only a
      single update log needs to be maintained. This is a legacy from code
      management before using subversion, but will be retained until further
      notice.

\item Each subroutine, function or grouping should be embedded in a module to
      allow for full use association and internal automatic interface checks
      in Fortran compilers. File naming conventions include:

\begin{itemize}
\item File names for elements of the basic wave model should start with {\file
      w3}.
\item Program elements related to the multi-grid capability should start with
      {\file wm}.
\item Module file names should end in {\file md} (before the file extension).
\item Files with main programs should be stored in file names starting with
      {\file ww3\_}.
\item The file extension{\file .ftn} identifies code elements that need to be
      preprocessed by the \ws\ preprocessor {\file w3adc} to activate
      switches.
\item Files with ready-to-use source code (no need for the \ws\ preprocessor)
      are identified by the extension {\file .f90}. This includes external
      packages interfaced to \ws.
\end{itemize}

      As examples {\file w3snl2md.ftn} is a module of the basic wave model
      (one of the $S_{nl}$ source term options) that needs to be preprocessed
      by the \ws\ preprocessor. {\file ww3\_grid.ftn} contains the main
      program for the grid preprocessing. {\file mod\_constants.f90} is a part
      of a user-supplied package that does not require \ws\ code
      preprocessing.  Note that the only file not following the \ws\ naming
      convention is {\file constants.ftn}, which contains a module with
      physical constants.

\item For now, we have been using the Fortran 90 standard. Required coding
      practices include:

\begin{itemize}
\item Use free format with style as described above.
\item Use {\code IMPLICIT NONE} in each module.
\item Do not use {\code COMMON} declarations. Eventually all major data
      structures should become part of the \ws\ dynamical data structures (see
      manual), which are all contained in separate modules, and can be used by
      use association. See section~\ref{sec:add} for suggestions on how to
      deal with these data structures during (initial) code development.
\item Each module used in a given program element will need to be use
      associated with a {\code USE} statement. Where feasible, use

      \centerline {{\code USE {\it module\_name}, ONLY: {\it used names}}}

      to avoid unintended use of variables in modules.
\item For the same reason, use {\code PRIVATE} for general declarations in
      modules. 
\item Declare {\code INTENT} on all dummy argument list items.
\item Do not use tab characters in the code (not in Fortran character set).
\item Name {\code END}s fully both for readability and because several
      compilers will require this.
\item Do not use numbered {\code DO} loops.
\item Use {\code CYCLE} and {\code EXIT} instead of {\code GOTO}.
\item Use {\code CASE} statements with a default rather than {\code IF}
      statements for multiple selection tests.

\item As a holdover of days long gone, short variable names have been used
      throughout the \ws\ code. Although this makes it easy to keep
      documentation readable, it does not necessarily make it easy to
      understand the code at a glance. Feel free to use longer variable names
      to make the code more easily understandable.
\item Up to now, there has been no need for explicit {\code KIND} declarations
      in \ws. If such declarations are needed, follow the standard set in
      \cite{rep:PvD08}.
\end{itemize}

\item Provide documentation for the modules to be included in the \ws\
      manual. The manual is written in \LaTeX. Required manual elements to be
      provided are

\begin{itemize}
\item Description or update of basic equations / physical parameterizations as
      needed.
\item Description or update of numerical approaches as needed.
\item Update of system documentation including description of parameters in
      the dynamical data structure of \ws.
\item Document namelist options as applicable in {\file ww3\_grid} in full
      in the example input file {\file ww3\_grid.inp}. The example file is
      included in full in the manual.
\end{itemize}

\end{list}

\noindent
The coding style does not imply that existing packages that are attached to
\ws\ need to be re-written in this style. However, it is strongly recommended
that any such package should be fully documented inside the code. Typically, a
user provided package will require an interface routine to \ws. Such an
interface routine is expected to conform to the \ws\ coding practices.

Note that the NWS claims copyright for all main elements of \ws, and generally
will claim copyright for interface routines. Providers of packages to be
included with the distribution of \ws\ are encourage to provide copyright
statements and disclaimers in these packages as appropriate (as NWS will not
claim copyright of such packages).

\begin{myfig}{tbp}
\begin{center}
\begin{minipage}[c]{4.5in}
\vspace{-10mm}
\input{docu_subr.tex}
\end{minipage}
\end{center}

\myfcap{Documentation template for subroutines. Note that each subroutine is
        expected to include a call to the {\code STRACE} subroutine to enable
        subroutine tracing inside \ws,}
\label{fig:docu_subr}
\end{myfig}

\begin{myfig}{tbp}
\begin{center}
\begin{minipage}[c]{4.5in}
\vspace{-10mm}
\input{docu_mod.tex}
\end{minipage}
\end{center}

\myfcap{Documentation template for modules. Copyright statement to be adapted
        as appropriate.}
\label{fig:docu_mod}
\end{myfig}

\bpage

\pb
%--------------------------------------------------------------%
% Section : Adding to the model                                %
%--------------------------------------------------------------%
\section{Adding to the model} \label{sec:add}
\newsec

\ws\ is designed as a highly plug-compatible code.  Source term and
propagation approaches can be included as self-contained modules, with limited
changes needed to the interface of routine calls in {\code W3SRCE}, {\code
W3WAVE}, and in the point post-processing programs only. General users can
experiment with new approaches in user slots that are provided as dummy model
slots like {\code W3SNLX} in the file {\file w3snlxmd.ftn} for the nonlinear
interactions. General users are expected to provide these `user slot' routines
to NCEP for inclusion in subsequent versions of \ws, following the instruction
in this guide and in the documentation of routines like {\code W3SNLX}.  Such
codes should be self-contained in the way described below.

When providing a module for a source term like {\code W3SNLX} or for a
propagation scheme the following programming guidelines should be followed:

\begin{list}{\roman{mylistno})}{\usecounter{mylistno} \rightmargin 8mm
                                \leftmargin 10mm \labelsep 2mm}
\item Follow coding guidelines as outlined in the previous section.
\item Provide a file with necessary modifications to {\code W3SRCE} and all
      other routines that require modification.
\item Provide a test case with expected results.
\end{list}

\noindent
Furthermore, the module needs to be self-contained in the following way.

\begin{list}{\roman{mylistno})}{\usecounter{mylistno} \rightmargin 8mm
                                \leftmargin 10mm \labelsep 2mm}
\item All saved variables connected with this source term need to be declared
      in the module header. Upon acceptance as permanent code, they will be
      converted to the \ws\ dynamic data structure.
\item Provide a separate computation and initialization routine.  In the
      submission, the initialization should be called from the computation
      routine upon the first call to the routine. Upon acceptance as permanent
      code, the initialization routine will be moved to a more appropriate
      location in the code (i.e., being absorbed in {\file ww3\_grid} or being
      moved to {\code W3IOGR}).
\end{list}

\noindent
When such packages are provided to NCEP, NCEP may choose to not include the
package, or to provide the package as a `user slot routine' like {\code
W3SNLX}, with some minor work of users required to install these routines, or
may choose to fully integrate the routines as a standard option in \ws.

\vspace{\baselineskip} \noindent Co-developers of \ws\ with access to the
subversion server are expected to fully integrate the new modules in the
experimental versions of \ws, using software selection switches as provided by
the NCEP code managers. It is, nevertheless, strongly recommended that
initially data structures are kept internal to the modules that are being
developed, and that data for the modules are only included in the dynamic data
structure of \ws\ when the module is mature. This will make code development
and unification much easier when multiple developers are working on the code
simultaneously.

\vspace{\baselineskip} \noindent The integration of new modules may involve
adding new software selection switches to the source code. When this happens
it is necessary to also add the new software selection switches to the build
scripts.  Specifically, the new switches must be properly encoded in {\file
  model/bin/make\_file.sh} and {\file model/bin/w3\_new}. This is required so
that switch incompatibilities can be trapped at compile time and source files
affected by changes to {\file model/bin/switch} can be correctly identified
and recompiled. Documentation for new software selection switches must be
added to Chapter 5.4 of the manual.

\vspace{\baselineskip} \noindent The above approach are applicable to
inherently modular elements of \ws\ such as source terms or propagation
schemes. For more intricate changes to the code, please consult the \ws\ code
managers\footnote{~Mail to NCEP.EMC.wavewatch@NOAA.gov} on how to proceed with
developing and providing code upgrades.


\pb
%--------------------------------------------------------------%
% Section : Regression testing                                 %
%--------------------------------------------------------------%
\section{Regression testing} \label{sec:testing}
\newsec

Up to model version 3.14, the wave model was distributed with a suite of test
cases in the {\file tests} directory. This set of tests was inconvenient to
use for regression testing, as it needed manual intervention and compilation
of the code for each individual test. In model version 4.07, an automated
script was introduced by Erick Rogers and Tim Campbell of NRL Stennis to
convert the traditional tests cases to regression tests that could be run in
an automated manner. The automated regression tests were first maintained in
the {\file nrltest} directory, and are now kept in the {\file regtests}
directory.  The previous {\file tests} directory has been removed, moving the
remaining real-world examples in the new {\file cases} directory. A more
complete documentation of the test cases and of the regression test tools can
be found in Section~\manregtestsec\ in \cite{\manref}.  The regression tests
in {\file regtests} cover basic tests to assure that features such as
propagation and source terms work. The following conventions are used in
naming the test cases:

\begin{itemize}

\item {\file ww3\_tp1.{\it n}}: Tests for one-dimensional propagation (regular
       grids). 

\item {\file ww3\_tp2.{\it n}}: Tests for two-dimensional propagation (all
       grids).

\item {\file ww3\_ts{\it n}}: Tests for source term integration (some
       including propagation).

\item {\file ww3\_bt{\it d}.{\it n}}: Tests for wave-bottom  interaction.
       ({\it d} = 1 or 2, indicating one- or two-dimensional test cases.)

\item {\file ww3\_ic{\it d}.{\it n}}: Tests for wave-ice interaction.
       ({\it d} = 1 or 2, indicating one- or two-dimensional test case.)

%\item {\file ww3\_systrk\_test\_{\it nn}}: Test cases for reconstructing full
%        wave fields in space and time from local spectral wave partitions.

\item {\file mww3\_test\_{\it nn}}: Tests cases for the multi-grid wave model.
\end{itemize}

\noindent
these idealized test cases should be used for regression testing when new code
is added to the repository; i.e., these tests should result in different
answers compared to the previous codes only when expected. 

More generally, there are two reasons for providing regression tests. The
first is the responsibility of a code developer not to break previously
existing code. The regression testing gives a developer the tools to check
this systematically and rigorously. The second is to avoid that a contributor
of code has to provide large efforts in keeping the contributed code
functional. By providing a regression testing for your new code, the
responsibility of keeping code function will first and foremost fall on
developers of new code, not on the contributor of already accepted code. As
already outlined above, this implies that developers of new model options
should both run relevant regression tests during development, and provide new
(options for existing) regression tests for their code additions. Some more
details of how and when to regression test will follow below.


To facilitate regression testing, a shell script, {\file
  regtests/bin/run\_test} is provided along with input files for all test
cases. The test cases are organized such that each major test case has its own
directory. Within each test case directory, it is possible to have more test
cases, for instance by compiling the code with different switches, using
different grid configurations, using different model inputs, and running the
code in either a shared or a distributed compute environment. A regression
test is run using command-line commands only. All options can be displayed by
running the script without arguments or with the {\file -h} option
\command{run\_test} \command{run\_test -h} the output of which is displayed in
Fig.~\ref{fig:run_test} at the end of this section.

When editing input files, it is recommended that developers avoid ``checking
in'' trivial changes as updates to the git repository. In the case of {\file
  ww3\_grid.inp} and {\file switch}, this can easily be avoided by keeping
non-version-controlled variants of these files for local editing and accessing
them via the -g and -s switches, respectively.

Most \ws\ developers will not have reason to edit the {\file run\_test} script
itself, i.e. it is treated as a black box. However, developers who would like
to extend the capabilities of the script (e.g. by adding new command line
switches) and commit these changes to the repository for sharing are
encouraged to do so.

\vspace{\baselineskip} \noindent With the set of simple test cases, an a large
number of switch and grid options, several hundred unique regression tests
have been created. A matrix of all possible regression tests can be generated
with the tools provided in the {\file regtests/bin} directory, as described in
Section~\manregtestsec\ in \cite{\manref}. The tools also allow for quickly
sub-setting the full matrix by test case or other filter options. The NCEP
code managers will run the full matrix of regression tests for trunk updates,
running the matrix on both the old trunk, and the proposed new trunk, and
using the tools in {\file regtests/bin} to do bit-wise comparisons of the
model results. As it may take up to 12 hours to run the full matrix on our
supercomputers, it makes no sense to run the full set of regression tests
during development of new options.

During development of code, common sense should prevail. For instance, when
developing a new source term package, it is worth while to regularly run some
of the source term tests to assure that the other source term options are not
broken, and only occasionally run the entire matrix. Note that the NCEP
developers do expect that a branch presented for integration with the trunk
has been tested at least once with the entire matrix of regression tests by
the developer.

There are two basic ways in which the regression testing can be done. One is
to keep copy of the trunk from which the development branch is created, and
have a set of regression tests run for both the trunk and the development
branch, and compare the results with the tools provide. The other is to do the
regression testing ``in place''. In this case, when creating a branch, run the
selected regression test(s) to create a baseline identifying it with a version
identifier. For instance, checking the PR3 and UQ propagation options while
working on another propagation scheme, a baseline could be generated with (and
possibly other command line options) \command{./bin/run\_test -s PR3 -w
  work\_PR3\_OQ\_v4.00 ../. ww3\_tp1.1} and after modifications are made to
the code, the regression test is re-run in a in a different work directory,
e.g., \command{./bin/run\_test -s PR3 -w work\_PR3\_UQ\_v4.01 ../. ww3\_tp1.1}
after which results can be compared using tools provided or with direct Linux
file comparison tools.  Note that for a test case to run to completion is a
necessary but not sufficient indication of success.

Note that {\file run\_test} has utility beyond regression testing. Perhaps the
most useful feature is that it makes it possible to fully document (or
communicate) a model simulation using a single line of text, ``{\file
  ./bin/run\_test} ...'' without ambiguity. Furthermore, the utility allows
for direct comparison of options in the model. For instance, the GSE test can
be used to easily generate GrADS output for all different propagation schemes
on a regular grid with otherwise identical model settings.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Hendrik: took this text out as we have not maintained this well  %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Note, furthermore, that for those who have access, a wiki describing each
% test case has been installed in {\file
%   https://svnemc.ncep.noaa.gov/trac/ww3/wiki/NrlTest }. This also includes
% many examples of {\file run\_test} commands.

\pb

\begin{myfig}{tbp}
\topline
\begin{center}
{\scriptsize \begin{minipage}[c]{4.5in}
%\vspace{-10mm}
\input{run_test.out}
\end{minipage} }
\end{center}
\botline
\myfcapc{Description of arguments for {\file run\_test} script.}
\label{fig:run_test}
\end{myfig}

\clearpage

%\pb
%--------------------------------------------------------------%
% Section : Manual and documentation                           %
%--------------------------------------------------------------%
\section{Manual and documentation} \label{sec:man}
\newsec

The \ws\ manual and other \ws\ documents like this guide are written in
\LaTeX. Since these are dynamic documents, the corresponding files are
maintained in git, together with the \ws\ source code, script and auxiliary
files. Because the manual is rather large, it has been stored in several
{\file .tex} files. During the development of model version 4.18, most
sub-sections were placed in their own file, to minimize conflicts in editing
when many contributors work on the manual simutaneously.  The main files (and
directories) making up the manual are

\begin{flist}
\fit{manual.tex}{Main {\file .tex} file, mainly combining the {\file .tex}
                 files below into the complete manual.}
\fit{defs.tex  }{User defined \LaTeX\ constructs used in the manual.}
\fit{start.tex }{Title page and table of contents set up.}
\fit{intro.tex }{Chapter: Introduction, using directory {\file intro}.}
\fit{eqs.tex   }{Chapter: Governing equations, using directory {\file eqs}.}
\fit{num.tex   }{Chapter: Numerics, using directory {\file num}.}
\fit{run.tex   }{Chapter: Running the model, using directory {\file run}.}
\fit{impl.tex  }{Chapter: Installing the model, using directory {\file impl}.}
\fit{sys.tex   }{Chapter: System documentation, using directory {\file sys}.}
\fit{app.tex   }{Appendices, using directory {\file app}.}
\fit{manual.bib}{BibTex database with references used in the manual.}
\fit{jas.bst   }{Bibliography style file used for the manual.}
\end{flist}

\vspace{\baselineskip} \noindent All files for the main chapters and
appendices manage individual \LaTeX\ files for individual sections
(appendices) in the chapter. This way, new options are documented in their own
sub-file, and can therefore be easily managed. See the main chapter files for
the contents of the chapter directories. Note that the chapter directories
also include files for many individual figures.

\vspace{\baselineskip} \noindent A {\file makefile} is provided to compile the
manual.  The default make target will compile a PDF version of the manual
(manual.pdf).  Other make targets available are: "inp" (create \LaTeX versions
in current directory of the {\file ww3\_*.inp} and {\file gx\_*.inp} input
files), as well as outputs of the {\file ww3\_gspl.sh} and {\file run\_test}
scripts, "clean" (remove all files created during compile of manual).  The
following external programs are required and must be found in the user PATH:
{\file latex}, {\file bibtex} and {\file dvipdf}.

\vspace{\baselineskip} \noindent The example input files ({\file ww3\_*.tex}
and {\file gx\_*.tex}) required for the programs described in {\file run.tex}
are automatically generated during compilation of the manual. The source input
files are copied from {\file \$(INPDIR)}.  The default setting for {\file
  INPDIR}, "../inp", can be overridden by setting {\file INPDIR} either on the
make command-line or in the environment. This method assures that the example
input files provided with the code are the files displayed in the manual.

\vspace{\baselineskip} \noindent Note that the manual consist of both a
conventional manual and a basic system documentation. The following standards
should be used in writing \LaTeX\ contributions to the manual:

\begin{itemize}
\item Use American spelling and grammar.
\item Use dynamic references to equation, chapter and section numbers, etc. Do
      not use any hardwired reference numbers when referring to equations,
      sections etc.
\item Use BibTex exclusively for references to other work. Do not write any
      references directly into the text.
\item Do not use excessive line lengths in the {\file .tex} files. We
      typically use a maximum line length of 78 characters and
      `auto-fill-mode' when writing or updating {\file .tex} files using
      emacs. 
\item When adding contributions to the manual, add a note of the
      update to the introduction, so that users of the public releases
      have a concise log of upgrades since the previous model release.
\item If you have no \LaTeX\ capability or experience, contact the \ws\ code
      managers to determine an acceptable method of delivering contributions
      to the manual.
\end{itemize}

\noindent
For general users we will provide a recent manual package when they are ready
to provide their manual contributions. For co-developers, the most recent
version of the manual will be available on github.

% \vspace{\baselineskip}
% \begin{center}
% \rule[1mm]{55mm}{1.0mm} WARNING \rule[1mm]{55mm}{1.0mm} \\ 
% \vspace{\baselineskip}
% \parbox{120mm}{This guide and other \LaTeX\ \ws\ documents like the manual
%   use the svn package for \LaTeX. This package is generally not
%   automatically installed with \LaTeX\ and therefore might result in failure
%   of compiling the {\file .dvi} files. The package is available from the
%   CTAN web site (http://www.ctan.org).} \\ \vspace{\baselineskip}
% \rule[1mm]{55mm}{1.0mm}
% WARNING \rule[1mm]{55mm}{1.0mm}
% \end{center}


%\bpage
\pb
%--------------------------------------------------------------%
% Section : Subversion repository                              %
%--------------------------------------------------------------%
\section{Git repository} \label{sec:svn}
\newsec

Starting with model version 3.14, the \ws\ model is maintained using
subversion \citep{bk:CSea06}. Now the code is maintained via git 
on github.  Information on how to contibute code and use git will 
now be maintained on the github wiki. Please see the github wiki
for more information. 

\bpage
\pb
%--------------------------------------------------------------%
% Section : Distributing experimental model versions           %
%--------------------------------------------------------------%
%\section{Distributing experimental model versions} \label{sec:dist}
%\newsec
% no longer relavant with move to github

%\bpage

%--------------------------------------------------------------%
%           References                                         %
%--------------------------------------------------------------%
\phantomsection
\addtocontents{toc}{\vspace
{\baselineskip}}
\addcontentsline{toc}{section}{References}
\setcounter{footnote}{0}

\bibliographystyle{jas}
% leave line below, used by Hendrik
%\bibliography{short,articles,books,reports,conf,mine}
\bibliography{guide}


\pagestyle{empty}
\bpagea


\end{document}
