You are on page 1of 36

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

Technical Note

R
development best practices .
WAVEWATCH III

Hendrik L. Tolman (Editor)


Environmental Modeling Center
Marine Modeling and Analysis Branch

Version 1.1, Mar. 2014

this is an unreviewed manuscript, primarily intended for informal


exchange of information among ncep staff members

MMAB Contribution No. 286.


e-mail: Hendrik.Tolman@NOAA.gov

This page is intentionally left blank.

Abstract
This guide describes best practices for code development of WAVEWATCH
R
III
. This includes guidelines for packaging of codes delivered by general users
to NCEP according to the WAVEWATCH III license, as well as instructions
for co-developers on the use of the subversion depository at NCEP. The guide
addresses codes, documentation and manuals.

Change log
version
0.1

svn rev.
7869

1.0

12398

1.1

38155

date
May 14, 2010

comment
Initial MMAB No. 286.
Sec. 4 (regression testing)
as placeholder only
Feb. 18, 2011 Adding svn note p. 25.
Adding svn warning p. 25.
Section 4 updated.
Mar. 18, 2014 Changed address on title page.
Updating most sections.
Adding Sec. 7 (code distr.).
Finalize for release of v. 4.18.
(minor edits included in each new version)

Acknowledgments. Code management for WAVEWATCH III is provided by NCEP.


Arun Chawla (NCEP), Henrique Alves (SRG at NCEP), Erick Rogers and Tim Campbell (NRL Stennis) contributed to this guide.
This guide is available as a pdf file from
http://polar.ncep.noaa.gov/waves

ii

Contents
Abstract

Acknowledgments

ii

Table of contents

iii

1 Introduction

2 Programming style

3 Adding to the model

4 Regression testing

11

5 Manual and documentation

15

6 Subversion repository
6.1 Server directory structure . . .
6.2 Installing from the svn server .
6.3 Permissions and responsibilities
6.4 The trac wiki . . . . . . . . . .

17
17
19
23
24

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

7 Distributing experimental model versions

27

References

29

iii

This page is intentionally left blank.

Introduction

R
wind wave model has a history dating back to the second
The WAVEWATCH III
half of the 1980s. Its history started with the development of the WAVEWATCH
model at Delft university of technology (Tolman, 1989, 1990, 1991). 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 (Tolman, 1992a,b).
Development of WAVEWATCH III 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, WAVEWATCH III
has been trademarked and copyrighted, and has been distributed under an opensource style license (see section 1.2 of Tolman, 2009, or the web site1 ). Henceforth,
WAVEWATCH III will be denoted as WW3.
Four public releases of WW3 have been made available (Tolman, 1999, 2002,
R
Development Group, 2014). This best
2009; Tolman and The WAVEWATCH III
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 WW3 as a main development
vehicle. This means that several teams will work simultaneously on the WW3 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 Van Delst (2008). 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 Van Delst (2008).
From the beginning, WW3 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 WW3 preprocessor and switches in the source
code, as described in full in the WW3 manuals as identified above.
Starting with the release model version 3.14, we are maintaining the code using subservion (Collins-Sussmann et al., 2004). The master version of WW3 will be

http://polar.ncep.noaa.gov/waves/wavewatch/license.shtml

maintained and supported at NCEP. With the licensing of model version 3.14, users
that develop code and/or modifications for WW3 are obligated to offer these back
to NCEP, relative to the most recent version of WW3 available to them2 . NCEP
will then decide if such modifications and additions will be included in the master
version of WW3, and will be responsible for including it in the subversion depository.
Alternatively, collaborators on well defined projects and with proven development
capability will be considered as co-developers, and will be given direct access to
our subversion server, and thus to developmental version of WW3. NCEP will invite collaborators to become co-developers, and will considered requests to become
co-developers.
In this context, coding standards, best practices for upgrading parts of WW3 and
for adding new pieces to WW3, regression testing, and maintenance of documentation
are essential. These issues are approached in Sections 2 (also including copyright
statements), 3, 4, and 5, respectively. Finally, Section 6 discusses standards of code
management using the subversion server at NCEP.
Some formatting practices for the WW3 manual are used in this guide. The file
font will be used to identify files, scripts and command line entries. The CODE font is
used to identify source code. Previous experience with WW3 is expected, and the use
of, for instance, optional switches in the code, will not be explained here in detail.

Public release or research version on svn server, depending on user access.

Programming style

WW3 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. 2.1
and 2.2 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 WW3 consists of incomplete (.ftn) FORTRAN files that
require standard WW3 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 WW3:
i) Fully document the code following the outline described above.
ii) Follow the coding style of WW3, in particular :
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.
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 WW3 compile switches3 like !/T. The latter test output should
be coded in upper case as a permanent part of the code.
iii) 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
WW3. 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.
iv) 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:
File names for elements of the basic wave model should start with w3.
Program elements related to the multi-grid capability should start with
wm.
3

See manual for details on use of compile level switches.

Module file names should end in md (before the file extension).


Files with main programs should be stored in file names starting with
ww3 .
The file extension.ftn identifies code elements that need to be preprocessed by the WW3 preprocessor w3adc to activate switches.
Files with ready-to-use source code (no need for the WW3 preprocessor) are identified by the extension .f90. This includes external
packages interfaced to WW3.
As examples w3snl2md.ftn is a module of the basic wave model (one of the
Snl source term options) that needs to be preprocessed by the WW3 preprocessor. ww3 grid.ftn contains the main program for the grid preprocessing.
mod constants.f90 is a part of a user-supplied package that does not require
WW3 code preprocessing. Note that the only file not following the WW3
naming convention is constants.ftn, which contains a module with physical
constants.
v) For now, we have been using the Fortran 90 standard. Required coding
practices include:
Use free format with style as described above.
Use IMPLICIT NONE in each module.
Do not use COMMON declarations. Eventually all major data structures
should become part of the WW3 dynamical data structures (see manual), which are all contained in separate modules, and can be used
by use association. See section 3 for suggestions on how to deal with
these data structures during (initial) code development.
Each module used in a given program element will need to be use
associated with a USE statement. Where feasible, use
USE module name, ONLY: used names
to avoid unintended use of variables in modules.
For the same reason, use PRIVATE for general declarations in modules.
Declare INTENT on all dummy argument list items.
Do not use tab characters in the code (not in Fortran character set).
Name ENDs fully both for readability and because several compilers
will require this.
Do not use numbered DO loops.
Use CYCLE and EXIT instead of GOTO.
4

Use CASE statements with a default rather than IF statements for


multiple selection tests.
As a holdover of days long gone, short variable names have been used
throughout the WW3 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.
Up to now, there has been no need for explicit KIND declarations in
WW3. If such declarations are needed, follow the standard set in
Van Delst (2008).
vi) Provide documentation for the modules to be included in the WW3 manual.
The manual is written in LATEX. Required manual elements to be provided
are
Description or update of basic equations / physical parameterizations
as needed.
Description or update of numerical approaches as needed.
Update of system documentation including description of parameters
in the dynamical data structure of WW3.
Document namelist options as applicable in ww3 grid in full in the
example input file ww3 grid.inp. The example file is included in full in
the manual.
The coding style does not imply that existing packages that are attached to WW3
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 WW3. Such an interface routine is expected
to conform to the WW3 coding practices.
Note that the NWS claims copyright for all main elements of WW3, and generally
will claim copyright for interface routines. Providers of packages to be included
with the distribution of WW3 are encourage to provide copyright statements and
disclaimers in these packages as appropriate (as NWS will not claim copyright of
such packages).

!/ ------------------------------------------------------------------SUBROUTINE W3XXXX
!/
!/
+-----------------------------------+
!/
| WAVEWATCH III
NOAA/NCEP |
!/
|
John Doe
|
!/
|
FORTRAN 90 |
!/
| Last update :
01-Jan-2010 |
!/
+-----------------------------------+
!/
!/
01-Jan-2010 : Origination.
( version 4.xx
!/
! 1. Purpose :
! 2. Method :
! 3. Parameters :
!
!
Parameter list
!
---------------------------------------------------------------!
---------------------------------------------------------------!
! 4. Subroutines used :
!
!
Name
Type Module
Description
!
---------------------------------------------------------------!
STRACE
Subr. W3SERVMD Subroutine tracing.
!
---------------------------------------------------------------!
! 5. Called by :
!
!
Name
Type Module
Description
!
---------------------------------------------------------------!
---------------------------------------------------------------!
! 6. Error messages :
! 7. Remarks
! 8. Structure :
! 9. Switches :
!
!
!/S Enable subroutine tracing.
!
! 10. Source code :
!
!/ ------------------------------------------------------------------!/S
USE W3SERVMD, ONLY: STRACE
!/
IMPLICIT NONE
!/
!/ ------------------------------------------------------------------!/ Parameter list
!/
!/ ------------------------------------------------------------------!/ Local parameters
!/
!/S
INTEGER, SAVE
:: IENT = 0
!/
!/ ------------------------------------------------------------------!/
!/S
CALL STRACE (IENT, W3XXXX)
....
!/
!/ End of W3XXXX ----------------------------------------------------!/
END SUBROUTINE INSBTX

Fig. 2.1 : Documentation template for subroutines. Note that each subroutine
is expected to include a call to the STRACE subroutine to enable subroutine
tracing inside WW3,
6

!/ ------------------------------------------------------------------MODULE W3XXXXMD
!/
+-----------------------------------+
!/
| WAVEWATCH III
NOAA/NCEP |
!/
|
John Doe
|
!/
|
FORTRAN 90 |
!/
| Last update :
01-Jan-2010 |
!/
+-----------------------------------+
!/
!/
01-Jan-2010 : Origination.
( version 4.xx
!/
!/
Copyright 2010 National Weather Service (NWS),
!/
National Oceanic and Atmospheric Administration. All rights
!/
reserved. WAVEWATCH III is a trademark of the NWS.
!/
No unauthorized use without permission.
!/
! 1. Purpose :
! 2. Variables and types :
!
!
Name
Type Scope
Description
!
---------------------------------------------------------------!
---------------------------------------------------------------!
! 3. Subroutines and functions :
!
!
Name
Type Scope
Description
!
---------------------------------------------------------------!
W3XXXX
Subr. Public
........
!
---------------------------------------------------------------!
! 4. Subroutines and functions used :
!
!
Name
Type Module
Description
!
---------------------------------------------------------------!
STRACE
Subr. W3SERVMD Subroutine tracing.
!
---------------------------------------------------------------!
! 5. Remarks :
! 6. Switches :
!
!
!/S Enable subroutine tracing.
!
! 7. Source code :
!/
!/ ------------------------------------------------------------------!/
PRIVATE
!/
CONTAINS
!/ ------------------------------------------------------------------SUBROUTINE W3XXXX
.....
!/
!/ End of w3XXXX ----------------------------------------------------!/
END SUBROUTINE W3XXXX
!/
!/ End of module W3XXXXMD -------------------------------------------!/
END MODULE W3XXXXMD

Fig. 2.2 : Documentation template for modules.


adapted as appropriate.

Copyright statement to be

This page is intentionally left blank.

Adding to the model

WW3 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 W3SRCE, 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 W3SNLX in the 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 WW3, following the instruction in
this guide and in the documentation of routines like W3SNLX. Such codes should be
self-contained in the way described below.
When providing a module for a source term like W3SNLX or for a propagation
scheme the following programming guidelines should be followed:
i) Follow coding guidelines as outlined in the previous section.
ii) Provide a file with necessary modifications to W3SRCE and all other routines
that require modification.
iii) Provide a test case with expected results.
Furthermore, the module needs to be self-contained in the following way.
i) 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 WW3 dynamic data structure.
ii) 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 ww3 grid or being moved to W3IOGR).
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 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 WW3.
Co-developers of WW3 with access to the subversion server are expected to fully
integrate the new modules in the experimental versions of WW3, 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 WW3 when the module is mature. This will make code development and unification much easier when multiple developers are working on the code
simultaneously.
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 model/bin/make file.sh and model/bin/w3 new. This is required so
that switch incompatibilities can be trapped at compile time and source files affected
by changes to 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.
The above approach are applicable to inherently modular elements of WW3 such as
source terms or propagation schemes. For more intricate changes to the code, please
consult the WW3 code managers4 on how to proceed with developing and providing
code upgrades.

Mail to NCEP.EMC.wavewatch@NOAA.gov

10

Regression testing

Up to model version 3.14, the wave model was distributed with a suite of test cases
in the 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 nrltest directory, and are now kept in the regtests
directory. The previous tests directory has been removed, moving the remaining
real-world examples in the new cases directory. A more complete documentation
of the test cases and of the regression test tools can be found in Section 5.6 in
R
Tolman and The WAVEWATCH III
Development Group (2014). The regression
tests in 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:
ww3 tp1.n: Tests for one-dimensional propagation (regular grids).
ww3 tp2.n: Tests for two-dimensional propagation (all grids).
ww3 tsn: Tests for source term integration (some including propagation).
ww3 btd.n: Tests for wave-bottom interaction. (d = 1 or 2, indicating one- or
two-dimensional test cases.)
ww3 icd.n: Tests for wave-ice interaction. (d = 1 or 2, indicating one- or twodimensional test case.)
ww3 systrk test nn: Test cases for reconstructing full wave fields in space and
time from local spectral wave partitions.
mww3 test nn: Tests cases for the multi-grid wave model.
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)
11

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, 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 -h option
run test
run test -h
the output of which is displayed in Fig. 4.1 at the end of this section.
When editing input files, it is recommended that developers avoid checking in
trivial changes as updates to the svn repository. In the case of ww3 grid.inp and
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 WW3 developers will not have reason to edit the 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.
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 regtests/bin directory, as deR
Development Group
scribed in Section 5.6 in Tolman and The WAVEWATCH III
(2014). 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 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.

12

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)
./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.,
./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 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, ./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.

13

Usage: run_test [options] source_dir test_name


Required:
source_dir : path to top-level of WW3 source
test_name : name of test case (directory)
Options:
-a ww3_env
: use WW3 environment setup file <ww3_env>
:
*default is <source_dir>/wwatch3.env
:
*file will be created if it does not already exist
-c cmplr
: setup comp & link files for specified cmplr
-e
: prompt for changes to existing WW3 environment
-f
: force pre- and post-processing programs to be compiled
: non-MPI (i.e., with SHRD switch); default is all programs
: compiled with unmodified switch settings
-g grid_string
: use ww3_grid_<grid_string>.inp
-G
: create GrADS data files using gx_outX.inp
-h
: print usage and exit
-i inpdir
: use inputs in test_name/<inpdir> (default test_name/input)
-m grid_set
: execute multi-model test
:
*grid names are obtained from input/<grid_set>
:
*ww3_multi_<grid_set> will execute instead of ww3_shell
:
*to execute a single model test case with ww3_multi use
:
grid_set = none
-n nproc
: specify <nproc> processors for parallel run
:
*some <runcmd> programs do not require <nproc>
:
*ignored if -p <runcmd> or -O is not specified
-o outopt
: limit output post-processing based on <outopt>
:
native : post-process only native output
:
netcdf : post-process only NetCDF output
:
both
: post-process both native and NetCDF output
:
* default is native
:
* note that required input files must be present for
:
selected output post-processing to occur
-O
: parallel run using OpenMP paradigm and OMP_NUM_THREADS
environment variable and number of processors defined with
the -n np option
-p runcmd
: run in parallel using <runcmd> to start program
:
*MPICH or OpenMPI: mpirun or mpiexec (default <nproc> = 1)
:
*IBM with Loadleveler: poe (no <nproc> required)
:
*LSF: mpirun.lsf (no <nproc> required)
-q program
: exit script after program <program> executes
-r program
: only execute program <program>
-s switch_string : use switch_<switch_string>
-S
: create stub file <finished>. with end data and time.
tests not executed if file is found.
-w work_dir
: run test case in test_name/work_dir (default test_name/work)

Fig. 4.1 : Description of arguments for run test script.

14

Manual and documentation

The WW3 manual and other WW3 documents like this guide are written in LATEX.
Since these are dynamic documents, the corresponding files are maintained in svn,
together with the WW3 source code, script and auxiliary files. Because the manual is
rather large, it has been stored in several .tex files. During the development of model
version 4.18, most ub-sections were places 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
manual.tex
defs.tex
start.tex
intro.tex
eqs.tex
num.tex
run.tex
impl.tex
sys.tex
app.tex
manual.bib
jas.bst

Main .tex file, mainly combining the .tex files below into the
complete manual.
User defined LATEX constructs used in the manual.
Title page and table of contents set up.
Chapter: Introduction, using directory intro.
Chapter: Governing equations, using directory eqs.
Chapter: Numerics, using directory num.
Chapter: Running the model, using directory run.
Chapter: Installing the model, using directory impl.
Chapter: System documentation, using directory sys.
Appendices, using directory app.
BibTex database with references used in the manual.
Bibliography style file used for the manual.

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.
A 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 LATEXversions in current directory of the ww3 *.inp and gx *.inp input files),
as well as outputs of the ww3 gspl.sh and 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: latex, bibtex and dvipdf.
The example input files (ww3 *.tex and gx *.tex) required for the programs described
in run.tex are automatically generated during compilation of the manual. The source
input files are copied from $(INPDIR). The default setting for INPDIR, ../inp, can be
overridden by setting INPDIR either on the make command-line or in the environment.

15

This method assures that the example input files provided with the code are the files
displayed in the manual.
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:
Use American spelling and grammar.
Use dynamic references to equation, chapter and section numbers, etc. Do not
use any hardwired reference numbers when referring to equations, sections etc.
Use BibTex exclusively for references to other work. Do not write any references
directly into the text.
Do not use excessive line lengths in the .tex files. We typically use a maximum
line length of 78 characters and auto-fill-mode when writing or updating .tex
files using emacs.
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.
If you have no LATEX capability or experience, contact the WW3 code managers
to determine an acceptable method of delivering contributions to the manual.
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 the svn server.

16

Subversion repository

Starting with model version 3.14, the WW3 model is maintained using subversion
(Collins-Sussmann et al., 2004). The subversion (svn) system has three components.
One is the svn repository maintained at NCEP. The second is the svn client that has
to be installed at your own machine. A third component is a wiki called trac, which
is semlessly linked to the svn server, and provides a full account of code changes with
diff capabilities, records all changes in the form of time lines, stores log messages and
also allow the creation of tickets for tasks to be done, which can be cross-references
with time line and log entries.
The svn server is where codes are stored and shared between collaborators. The
subversion client allows you interact with the server to obtain codes, and to submit
(share and backup) your own modifications to the code. The server and client communicate through svn commands, mostly as command line actions from the client
side5 . Putting data from your local system into the server will always require command line action from the client side (i.e., is the responsibility of, and is under full
control of the co-developer). For examples of how to work with the serve and client,
see the tutorials on the wiki page mentioned below.
All EMC codes are now in the EMC subversion server
https://svnemc.ncep.noaa.gov
Access to this server requires an account and password. The WW3 model is maintained in
https://svnemc.ncep.noaa.gov/projects/ww3

6.1

Server directory structure

In the WW3 directory, the conventional trunk, branches and tags directories have been
created, The trunk directory contains the main model development, tags contains
model releases (formal, internal and beta testing), and branches contains work space
for developers (as well as maintenance of released versions). All branches reflect the
type of work being performed, and names are given accordingly. A single developer
may have several branches, if he/she is working on different features of the code.
This approach allows the development community to have ready features added to
the main trunk without the risk of also loading unfinished work.
For instance, extension of output fields is found in the branch:
5

You can access code on the server directly though the web interface, but this bypasses all tools
available in svn and and should NEVER be practiced.

17

https://svnemc.ncep.noaa.gov/projects/ww3/branches/output fields
whereas a bugfix may be found in a branch named after what the bug fix is about,
and/or a ticket number:
https://svnemc.ncep.noaa.gov/projects/ww3/branches/BUGFIX gxoutp
Co-developers will get read access to the trunk and tags, and write access to their
designated directory in branches. In trunk (and tags), we have set up directories
model
manual
guide
regtests
cases

Model files as previously distributed as .tar files.


LATEXfiles and graphics files for the manual.
LATEXfile for this guide.
LATEXRegression tests.
LATEXLarger regression test cases.

In the model directory, subdirectories aux, bin, ftn, inp and test are created, containing
the same files as in the previous model distributions. To install WW3 from the
subversion repository, a new script
install ww3 svn
has been created, which replaces the script install wwatch3 used to install the model
from .tar files. This script will first create a svn directory which will be filled with the
five directories svn/aux through svn/cases with all the files from the svn repository,
and will then continue to set up the model identical to the model setup from the tar
files. This means that symbolic links will be created for directories at the same tree
level as the svn directory. These will contain links to the actual files in the latter.
This structure is adopted so that the user or developer can make changes and
create temporary files without affecting or creating junk in the area that will be
synced with the svn server. Of course, changes made to linked files will reflect on the
actual files. On the other hand, files that are added on the local work copy area and
that are not linked into the svn repository will be ignored. Of course if the intention
is to have added files loaded to the svn server, the developer will have to manually
add the to the svn diretory area, in their proper place, then instruct the svn server
that a new file must be added, as the location of the new file (in teh svn directory
area):
svn add newfile.ftn
Whenever changes are made to files in the local svn directory, these changes are
only added to the actual svn server after the user commits. Thus,
18

svn commit
called from the svn directory will update the repository with changes made in the
local copy. We stress here that this implies that new files need to be added in the svn
directory first, and then need to be added as links in the conventional directory.
After changes are made to the repository, even if these were made in a local copy,
the user or developer must rerun the script install ww3 svn, since this will restablsih all
links, and remove any orphaned files etc. This is the only way to ensure consistency,
and is the best practice for updating the working copies from the svn repository, and
for updating links to the local svn directory.

6.2

Installing from the svn server

Any installation of the code from the svn repository must start with the script install ww3 svn. This needs to be exported from the svn server into the main WW3
work area/directory. For this to happen, the user or developer must export the file
making first to simplify:
SVN=https://svnemc.ncep.noaa.gov/projects/ww3
then,
svn export $SVN/trunk/model/bin/install ww3 svn
or, if the file is from a specific branch, say, output fields:
svn export $SVN/branches/output fields/model/bin/install ww3 svn
If this script is found to be identical to the local work copy in the local svn/bin
directory, it will be replaced with a link to the latter, so that modifications to the
script will also be version controlled with svn.
The installation process will require some decisions to be made. After exporting
the install script from the svn server, check for executable status, if the file is not
executable, do:
chmod 744 install ww3 svn
Then execute the install script. The following sequence needs to be followed. The
most crucial option is if a local or generic install is to be performed. The type of
install deals with where to save the the traditional wwatch3.env file, containing the
general user-dependent directory and basic FORTRAN and C compiler choices. The
local install will save this at the same location as the package is being installed, which
19

is the main WW3 directory. This results in a standalone version that allows multiple
installations (or other branches or the trunk) to co-exist without interference. The
general install means wwatch.env will be save in the users home directory in the
form $HOME/.wwatch3.env, and that this will be the main or central installation in
that work area. The existence of a general install does not preclude the existence of
multiple local installs, but the user has to be mindful of which code is being invoked
when using the general install (things can get very confusing if not kept explicitly on
track).
Figure 6.2 provides a run down of how the installation process from the svn server
using install ww3 svn looks like. We reproduce only the part of the process that
requires feedback from the user. If proper answers have been provided at the prompts,
the remaining steps of the installation process will be screen output of following the
options selected in the sections above, and indicating what the installation scrtipt is
performing (checking out from server, copying files, linking, compiling etc).

20

PROMPT :: SVN=https://svnemc.ncep.noaa.gov/projects/ww3
PROMPT :: svn export \$SVN/branches/doc_edit/model/bin/install_ww3_svn
A
install_ww3_svn
Export complete.
PROMPT :: ls -l
total 52
-rwx------. 1 user group 55555 Mar

5 12:19 install_ww3_svn

PROMPT :: ./install_ww3_svn

===================================
------ Installing WAVEWATCH III v.4 -----===================================
Script for installing package from Subversion server source.
Requires user/pass access to NCEP Subversion server.
Continue? [y|n] y

===================================
------ Installing WAVEWATCH III v.4 -----===================================
from svn source
This installation requires a configuration file (wwatch3.env).
The current version allows two types of env files:
- A local [L] wwatch3.env (Allowing multiple independent installations).
- A generic [G] dot-file .wwatch3.env (Old-fashioned option).
[L] Installs new, uses existing or updates env file in current directory.
[G] Installs new, uses existing or updates env file in home directory,
(home is presumably /export/emc-lw-jhalves/wd20ha}).

Type your choice now: L


Creating new env file from scratch.

Installing in
/export/emc-lw-jhalves/wd20ha/WW3_GUIDE
OK ? [y/n] y
Setting up environment variables.

21

Previous setup file not found. Variables will be set to defaults.


(User must check to see if these setting are appropriate.)
Creating wwatch3.env locally (also in home if G option chosen).
Printer (listings)
: printer
FORTRAN comp. (aux only) : f77
C Compiler (aux only)
: cc
Scratch directory
: /export/emc-lw-jhalves/wd20ha/WW3_GUIDE/tmp
Save source code
: yes
Save listings
: yes
Update settings ? [y/n] y
Modifying set-up
Type n new settings, or press ENTER to keep [current ones]:
Printer for listings [printer] :
Compiler for aux. [f77] : gfortran
Compiler for aux. [cc] : gcc
Scratch space [/export/emc-lw-jhalves/wd20ha/WW3_GUIDE/tmp] :
Save source code files (*.f) [yes] :
Save listing files [yes] :
Modified settings:
Printer (listings)
FORTRAN comp. (aux only)
C Compiler (aux only)
Scratch directory
Save sources
Save listings
New settings OK ? [y/n]

:
:
:
:
:
:

printer
gfortran
gcc
/export/emc-lw-jhalves/wd20ha/WW3_GUIDE/tmp
yes
yes

Continue with actual implementation ? [y/n] y


Starting actual implementation ...
Use Ctrl-C to terminate program ...
===================================
------ Setup or update WAVEWATCH III -----===================================
Using svn source
Directory /export/emc-lw-jhalves/wd20ha/WW3_GUIDE/svn

This is a new installation. Create new svn directory [y/-] ? y


Install from trunk [T], branches [B] or tags [A]?
Enter [T] or [B] or [A] now : B
Enter branch name now : doc_edit
Installing from: :
https://svnemc.ncep.noaa.gov/projects/ww3/branches/doc_edit
Is this OK [y/-] ? y

Fig. 6.2 : Example of running the install script install ww3 svn.

22

6.3

Permissions and responsibilities

Co-developers will have read access to the trunk and tags, and will have read and
write permission to their workspace in the branches. Read access to the latter work
space will be set as requested by the co-developer. NCEP code managers will have
read access throughout, and will be responsible for merging mature codes into the
trunk. As mentioned above, co-developer will be responsible for providing mature
upgrades relative to the most recent upgrade of the trunk.
To fully use the potential of subversion, it is critical that detailed commit logs
are maintained. As with the CRTM, WW3 commit logs should follow the GNU
ChangeLog format6 . An example of a log entry is given in Fig. 6.3. The log entry
should start with a reference to the area and directory being changed (Branch output: or Trunk:) and then should mention each file that has been changed. The
first line of each block should contain the subdirectory name. The log entry should
mention every file that has been changed. For every file, every procedure changed
should be named in full (no wildcard) to enable searching the log. We are aware
that some duplicity is introduced by also asking for a change log entry in the actual
source files. The latter is typically only a one-line cryptic description. For now, this
change log will also be maintained because it refers to the WW3 version number. If
the commit logs are properly maintained, the ChangeLog will be provided with future
releases, at which time we may discontinue the habit of providing simple change logs
in the source files.
6

http://www.gnu.org/prep/standards/standards.html#Change-Logs
ww3/branches/hendrik/workcopy/model/aux subdirectory
* spec_ids: File removed, as it was eroneously added to the repository with
the initial import of model version 3.14.
ww3/branches/hendrik/workcopy/model/bin subdirectory
* install_ww3_svn: New script to install wave model from svn reporitory.
ww3/branches/hendrik/workcopy/guide subdirectry (new subdirectory)
* guide.tex: the latex file with the guide
* guide.bib: bibtex bibliography information for guide
ww3/branches/hendrik/workcopy/model/ftn subdirectory
* w3sbtxmd.ftn: added copyright statement
(w3sbtx): cosmetic changes
(insbtx): cleared typos from documentation

Fig. 6.3 : Example of commit log entry following the GNU ChangeLog format.

23

6.4

The trac wiki

Finally, we are using Trac7 as a web-based management tool for the development of
WAVEWATCH III. The Trac pages are found at
https://svnemc.ncep.noaa.gov/trac/ww3
and are accessed with the user name and password of the svn pages. The front page
is a wiki page. Trac gives a web-based way to access files in subversion, including
a time line of submissions to subversion. Additional tools include a road map with
milestones, and a ticket system to track bugs and their fixes, and to manage code
development for WAVEWATCH III among co-developers. Trac will be accessible to
all those with accounts for our subversion server.

http://trac.edgewall.org/

24

NOTE
To assure that codes can be maintained effectively with subversion,
make sure that work copies in your branch are created using an svn
copy or svn cp command from the trunk, and not by checking in
new code form outside the repository. The first approach will allow
you to easily keep your copy synchronized with the trunk, the latter
approach will require much manual labor to achieve this. Synchronizing a properly generated work copy with the trunk require the
following steps:
Check out a work copy from your branch in the repository to
a work space on your local machine.
Merge this copy with the trunk using svn merge . . .
Resolve conflicts and test as needed.
Commit merged version to your work space in the repository.
This version is now up to date with the trunk and also includes
your changes, if conflict resolution is done properly.
As a general rule, do not create branches from branches if you do
not want to create much work to stay synchronized with trunk.
NOTE

WARNING
NCEP code managers WILL NOT accept branches for merge with
the trunk if the branch does not originate from an svn copy from
the trunk, as NCEP does not have the resources to manually merge
each submitted code.
NEVER download code directly from the web interface to the svn
server at NCEP as this bypasses all svn code management tools.
All interactions with the server other than looking around should
be done through command lines at the svn client. ALWAYS use
svn commands to manage local codes (e.g., copies, moves, adding
files) rather than use Unix/Linux commands.
WARNING

25

This page is intentionally left blank.

26

Distributing experimental model versions

With the relatively long period between formal releases of WW3, there is an ongoing
issue with making experimental code available to those who could benefit from these
codes. Per WW3 license, individual developers cannot redistribute the code. After
extensive discussions at NCEP, we have come up with the following solution, which is
consistent with the licensing, and satisfies early distribution needs. If requests come
in for distributing developmental code to individuals, NCEP will provide alpha
versions of the new code through the web site, which then will be made available on a
case-by-case basis under the alpha code distribution agreement provided below. Note
that this is intended for users, not developers. The latter should be requesting joint
access to the svn server. In principle, we prefer to generate alpha versions from the
trunk. This implies that
If you want an early release of your contributions, it should be ready for, and
integrated into the trunk (or make the case to us to do this differently).
If you leave your contributions in your branch, there is no way it can accidentally be distributed.
Now that we have implemented this early distribution mechanism, there will be a
zero tolerance policy for those who violate the license and distribute the code on
their own. Individual distribution of the code will result in an immediate removal of
svn privileges at NCEP, and may result in NCEP involving the Office of the General
Council (OGC, i.e., the NOAA lawyers). Distributing information of branches that
are not your own will be considered as breach of copyright.
Alpha (beta) code access:
Upon individual request, user will be given access to alpha versions of the WW3 code
under the following conditions:
The code and manuals are provided with the understanding that both may be
incomplete. NCEP will not provide additional support to run the codes, with
the exception of working with the developers on bug fixes, and moving these
into updated model versions.
The user will update to the formal release as soon as reasonably possible, and
not maintain alpha versions after a formal code release.
The WW3 license covers alpha model versions (registered WW3 users only).
Where reasonably possible, reference will be made to formal versions of model
documentation and existing papers, not to draft documentation versions that
are distributed with the code.
27

NCEP needs to be contacted for obtaining explicit permission for commercial


use. NCEP will consult with contributors to the trunk in case of such requests.
Future beta versions of the code will be distributed under the same arrangement,
with the exception that NCEP will actively solicit beta users.

28

References
Collins-Sussmann, B., B. W. Fitzpatrick and C. M. Pilato, 2004: Version control with
subversion. OReilly, 320 pp.1
Tolman, H. L., 1989: The numerical model WAVEWATCH: a third generation model
for the hindcasting of wind waves on tides in shelf seas. Communications on Hydraulic and Geotechnical Engineering 89-2, Delft Universtity of Technology, ISSN
01696548, 72 pp.
Tolman, H. L., 1990: Wind wave propagation in tidal seas. Communications on Hydraulic and Geotechnical Engineering 90-1, Delft Universtity of Technology, ISSN
01696548, 135 pp. (Doctoral Thesis).
Tolman, H. L., 1991: A third-generation model for wind waves on slowly varying,
unsteady and inhomogeneous depths and currents. J. Phys. Oceanogr., 21, 782
797.
Tolman, H. L., 1992a: Effects of numerics on the physics in a third-generation windwave model. J. Phys. Oceanogr., 22, 1,0951,111.
Tolman, H. L., 1992b: Effects of the Gulf Stream on wind waves in SWADE. in Proc.
23rd Int. Conf. Coastal Eng., Venice, Italy, pp. 712725. ASCE.
Tolman, H. L., 1999: User manual and system documentation of WAVEWATCH III
version 1.18. Tech. Note 166, NOAA/NWS/NCEP/OMB, 110 pp.
Tolman, H. L., 2002: User manual and system documentation of WAVEWATCH III
version 2.22. Tech. Note 222, NOAA/NWS/NCEP/MMAB, 133 pp.
Tolman, H. L., 2009: User manual and system documentation of WAVEWATCH
III TM version 3.14. Tech. Note 276, NOAA/NWS/NCEP/MMAB, 194 pp. + Appendices.
R
Development Group, 2014: User manual
Tolman, H. L. and The WAVEWATCH III
R
version 4.18. Tech. Note 316,
and system documentation of WAVEWATCH III
NOAA/NWS/NCEP/MMAB, 282 pp. + Appendices.
Van Delst, P., 2008: CRTM: Fortran95 coding guidelines. Technical report, Joint
Center for Satellite Data Assimilation.

Updated versions available online at http://subversion.tigris.org/.

29

This page is intentionally left blank.

You might also like