This document contains the needed information to mark-up WW3 source files with
doxygen tags. The main task for this is adding headers for
each Fortran90 component (FILE,MODULE,SUBROUTINE,FUNCTION,PROGRAM). Examples
are provided with input from existing code, and the html output shown as it will look from the browser. Additionally,
inline documentation for MODULE variables is required (these variables are listed after the
MODULE declaration statement, but before the CONTAINS statement). Lastly, the shell commands for
building the doxygen documentation and displaying it in a browser are also given.
These header should be placed directly above the Fortran90 component declaration.
!> @file
!> @brief
!>
!> @author
!> @date
!>
!>
!> @brief
!>
!> @details
!>
!> @author
!> @date
!>
!> @copyright Copyright 2009-2022 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.
!>
!>
!> @brief
!>
!> @details
!>
!> @param[inout]
!>
!> @author
!> @date
!>
!>
!> @brief
!>
!> @details
!>
!> @param
!> @returns
!>
!> @author
!> @date
!>
!>
!> @brief
!>
!> @details
!>
!> @author
!> @date
!>
!> @copyright Copyright 2009-2022 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.
!>
!> @file
!> @brief Contains driver program for multi-grid, W3MLTI.
!>
!> @author H. L. Tolman @date 29-May-2009
#include "w3macros.h"
!/ ------------------------------------------------------------------- /
!!>
!> @brief Mean wave parameter computation for case without input and
!> dissipation.
!>
!> @author H. L. Tolman @date 29-May-2009
!>
!> @copyright Copyright 2009-2022 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.
!>
!/ ------------------------------------------------------------------- /
MODULE W3SRC0MD
!/
!/ +-----------------------------------+
!/ | WAVEWATCH III NOAA/NCEP |
!/ | H. L. Tolman |
!/ | FORTRAN 90 |
!/ | Last update : 29-May-2009 |
!/ +-----------------------------------+
!/
!/ 05-Jul-2006 : Origination. ( version 3.09 )
!/ 29-May-2009 : Preparing distribution version. ( version 3.14 )
!/
!/ Copyright 2009 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 :
!
! Mean wave parameter computation for case without input and
! dissipation.
!
! 2. Variables and types :
!
! 3. Subroutines and functions :
!
! Name Type Scope Description
! ----------------------------------------------------------------
! W3SPR0 Subr. Public Mean parameters from spectrum.
! ----------------------------------------------------------------
!
! 4. Subroutines and functions used :
!
! Name Type Module Description
! ----------------------------------------------------------------
! W3SPR0 Subr. Public Mean parameters from spectrum.
! ----------------------------------------------------------------
!
! 4. Subroutines and functions used :
!
! Name Type Module Description
! ----------------------------------------------------------------
! STRACE Subr. W3SERVMD Subroutine tracing. ( !/S )
! ----------------------------------------------------------------
!
! 5. Remarks :
!
! 6. Switches :
!
! !/S Enable subroutine tracing.
! !/T Test output, see subroutines.
!
! 7. Source code :
!
!/ ------------------------------------------------------------------- /
!/
PUBLIC!> @brief Interface to watershed partitioning routines.
!>
!> @details Watershed Algorithm of Vincent and Soille, 1991,
!> implemented by Barbara Tracy (USACE/ERDC) for NOAA/NCEP.
!>
!> This version of W3PART contains alternate Met Office partitioning
!> methods, selected at runtime using the \c PTMETH namlist variable:
!> -# Standard WW3 partitioning, as per original method described
!> by Barbary Tracy.
!> -# Met Office extended partitioning using split-partitions
!> (removes the wind sea part of any swell partiton and combines
!> with total wind sea partition).
!> -# Met Office "wave systems" - no classification or combining of
!> wind sea partitions. All partitions output and ordered simply
!> by wave height.
!> -# Classic, simple wave age based partitioning generating
!> a single wind sea and swell partition.
!> -# 2-band partitioning; produces hi and low freqency band partitions
!> using a user-defined cutoff frequency (\c PTFCUT).
!>
!> @remarks
!> - \c DIMXP will always be of size 2 when using \c PTMETH 4 or 5.
!>
!> - To achieve minimum storage but guaranteed storage of all
!> partitions <tt>DIMXP = ((NK+1)/2) * ((NTH-1)/2)</tt>
!> unless specified otherwise below.
!>
!> @param[in] SPEC 2-D spectrum E(f,theta)
!> @param[in] UABS Wind speed
!> @param[in] UDIR Wind direction
!> @param[in] DEPTH Water depth
!> @param[in] WN Wavenumebers for each frequency
!> @param[out] NP Number of partitions found
!> (-1=Spectrum without minumum energy;
!> 0=Spectrum with minumum energy but no partitions)
!> @param[out] XP Parameters describing partitions.
!> Entry '0' contains entire spectrum
!> @param[in] DIMXP Second dimension of XP
!>
!> @author Barbara Tracey, H. L. Tolman, M. Szyszka, Chris Bunney
!> @date 23 Jul 2018
!>
SUBROUTINE W3PART ( SPEC, UABS, UDIR, DEPTH, WN, NP, XP, DIMXP )
!/
!/ +-----------------------------------+
!/ | WAVEWATCH III USACE/NOAA |
!/ | Barbara Tracy |
!/ | H. L. Tolman |
!/ | FORTRAN 90 |
!/ | Last update : 02-Dec-2010 |
!/ +-----------------------------------+
!/
!/ 28-Oct-2006 : Origination. ( version 3.10 )
!/ 02-Dec-2010 : Adding a mapping PMAP between ( version 3.14 )
!/ original and combined partitions
!/ ( M. Szyszka )
!/
! 1. Purpose :
!
! Interface to watershed partitioning routines.
!
! 2. Method :
!
! Watershed Algorithm of Vincent and Soille, 1991, implemented by
! Barbara Tracy (USACE/ERDC) for NOAA/NCEP.
!
! 3. Parameters :
!
! Parameter list
! ----------------------------------------------------------------
! SPEC R.A. I 2-D spectrum E(f,theta).
! UABS Real I Wind speed.
! UDIR Real I Wind direction.
! DEPTH Real I Water depth.
! WN R.A. I Wavenumebers for each frequency.
! NP Int. O Number of partitions.
! -1 : Spectrum without minumum energy.
! 0 : Spectrum with minumum energy.
! but no partitions.
! XP R.A. O Parameters describing partitions.
! Entry '0' contains entire spectrum.
! DIMXP Int. I Second dimension of XP.
! ----------------------------------------------------------------
!
! 4. Subroutines used :
!
! Name Type Module Description
! ----------------------------------------------------------------
! STRACE Sur. W3SERVMD Subroutine tracing.
! ----------------------------------------------------------------
!
! 5. Called by :
!
! 6. Error messages :
!
! 7. Remarks :
!
! - To achieve minimum storage but guaranteed storage of all
! partitions DIMXP = ((NK+1)/2) * ((NTH-1)/2) unless specified
! otherwise below.
!
! This version of W3PART contains alternate Met Office partitioning
! methods, selected at runtime using the PTMETH namlist variable:
! 1) Standard WW3 partitioning
! 2) Met Office extended partitioning using split-partitions
! (removes the wind sea part of any swell partiton and combines
! with total wind sea partition).
! 3) Met Office "wave systems" - no classification or combining of
! wind sea partitions. All partitions output and ordered simply
! by wave height.
! 4) Classic, simple wave age based partitioning generating
! a single wind sea and swell partition. [DIMXP = 2]
! 5) 2-band partitioning; produces hi and low freqency band partitions
! using a user-defined cutoff frequency (PTFCUT). [DIMXP = 2]
!
! (Chris Bunney, UK Met Office, Jul 2018)
!
! 8. Structure :
!
! 9. Switches :
!
! !/S Enable subroutine tracing.
! !/T Enable test output
!
!
! 10. Source code :
!
!/ ------------------------------------------------------------------- /
!/!>
!> @brief Perform interpolation from regular to curvilinear grid
!> for a scalar field.
!>
!> @details This function uses bilinear interpolation to
!> estimate the value of a function f at point (x,y). f is assumed
!> to be on a regular grid, with the grid x values specified by
!> xarray with dimension x_len and the grid y values specified by
!> yarray with dimension y_len.
!>
!> @param X_LEN Dimension in X
!> @param XARRAY 1D array for Longitudes
!> @param Y_LEN Dimension in Y
!> @param YARRAY 1D array for Latitudes
!> @param FUNC 1D Field
!> @param X Long for point in the curv grid
!> @param Y Lat for point in the curv grid
!> @param DELTA Threshold to determine if two values are equal
!>
!> @returns INTERPOLATE
!>
!> @author H. L. Tolman @date 25-Jul-2019
!>
REAL FUNCTION INTERPOLATE(X_LEN,XARRAY,Y_LEN,YARRAY,FUNC, &
X,Y,DELTA)
X,Y,DELTA)
!/
!/ +-----------------------------------+
!/ | WAVEWATCH III NOAA/NCEP |
!/ | H. L. Tolman |
!/ | FORTRAN 90 |
!/ | Last update : 25-July-2019 |
!/ +-----------------------------------+
!/
!/ (R. Padilla-Hernandez, EMC/NOAA)
!/
!/ 29-July-2019 : ( version 7.13 )
!/
! 1. Purpose :
!
! Perform interpolation from regular to curvilinear grid for a
! scalar field. THIS FUNCTION USES BILINEAR INTERPOLATION TO
! ESTIMATE THE VALUE OF A FUNCTION F AT POINT (X,Y) F IS ASSUMED
! TO BE ON A REGULAR GRID, WITH THE GRID X VALUES SPECIFIED BY
! XARRAY WITH DIMENSION X_LEN AND THE GRID Y VALUES SPECIFIED BY
! YARRAY WITH DIMENSION Y_LEN
!
! 2. Parameters :
!
! Parameter list
! ----------------------------------------------------------------
! X_LEN Int. Dimension in X
! XARRAY Int. 1D array for Longitudes
! Y_LEN Int. Dimension in Y
! YARRAY Int. 1D array for Latitudes
! FUNC Int. 1D Field
! X,Y Real Long-Lat for point in the curv grid
! DELTA Real Threshold to determine if two values are equal
! ----------------------------------------------------------------
!
! Internal parameters
! ----------------------------------------------------------------
! INX Int. Index in X on the rectiliniear grid that is
! closest to, but less than, the given value for a
! point in the curvilinear grid.
! JNX Int. Idem INX for for Y.
! X1,Y1 Real (Long, Lat) left-bottom corner for the square in
! regular grid, where the given value for the point
! in the curvilinear grid lies
! X2,Y2 Real (Long, Lat) right-upper corner for the square in
! regular grid, where the given value for the point
! in the curvilinear grid lies
! ----------------------------------------------------------------
!
! 3. Subroutines used :
!
! Name Type Module Description
! ----------------------------------------------------------------
! XYCURVISEARCH Func. wmupdtmd Look for indexes in 1D array.
! ----------------------------------------------------------------
!
! 4. Called by :
!
! Main program in which it is contained.
! Main program in which it is contained.
!
! 5. Error messages :
!
! None.
!
! 6. Remarks :
!
! -
!
! 7. Structure :
!
! See source code.
!
! 8. Switches :
!
! -
! !> @brief Preprocessing of input data.
!>
!> @details Pre-processing of the input water level, current, wind, ice
!> fields, momentum and air density, as well as assimilation data
!> for the generic shell W3SHEL (ww3_shel.ftn).
!>
!> @author H. L. Tolman
!> @date 22-Mar-2021
!>
!> @copyright Copyright 2009-2022 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.
!
PROGRAM W3PREP
!/
!/ +-----------------------------------+
!/ | WAVEWATCH III NOAA/NCEP |
!/ | H. L. Tolman |
!/ | A. Chawla |
!/ | FORTRAN 90 |
!/ | Last update : 22-Mar-2021 |
!/ +-----------------------------------+
!/
!/ 14-Jan-1999 : Final FORTRAN 77 ( version 1.18 )
!/ 18-Jan-2000 : Upgrade to FORTRAN 90 ( version 2.00 )
!/ 11-Jan-2001 : Flat grid option added ( version 2.06 )
!/ 17-Jul-2001 : Clean-up ( version 2.11 )
!/ 24-Jan-2002 : Add data for data assimilation. ( version 2.17 )
!/ 30-Apr-2002 : Fix 'AI' bug for 1-D fields. ( version 2.20 )
!/ 24-Apr-2003 : Fix bug for NDAT = 0 in data. ( version 3.03 )
!/ 24-Dec-2004 : Multiple grid version. ( version 3.06 )
!/ 28-Jun-2006 : Adding file name preamble. ( version 3.09 )
!/ 25-Sep-2007 : Switch header of file on or off, ( version 3.13 )
!/ Times to file (!/O15) (A. Chawla)
!/ 29-May-2009 : Preparing distribution version. ( version 3.14 )
!/ 30-Oct-2009 : Implement run-time grid selection. ( version 3.14 )
!/ (W. E. Rogers & T. J. Campbell, NRL)
!/ 30-Oct-2009 : Implement curvilinear grid type. ( version 3.14 )
!/ (W. E. Rogers & T. J. Campbell, NRL)
!/ 15-May-2010 : Add ISI (icebergs and sea ice). ( version 3.14.4 )
!/ 29-Oct-2010 : Implement unstructured grids ( version 3.14.4 )
!/ (A. Roland and F. Ardhuin)
!/ 06-Dec-2010 : Change from GLOBAL (logical) to ICLOSE (integer) to
!/ specify index closure for a grid. ( version 3.14 )
!/ (T. J. Campbell, NRL)
!/ 1-Apr-2011 : Fix bug GLOBX forcing with unst. ( version 3.14.4 )
!/ 19-Sep-2011 : Fix bug prep forcing with unst. ( version 4.04 )
!/ 26-Dec-2012 : Modified obsolete declarations. ( version 4.OF )
!/ 3-Mar-2013 : Allows for longer input file name ( version 4.09 )
!/ 11-Nov-2013 : Allows for input binary files to be of WAVEWATCH
!/ type (i.e. accounts for the header) ( version 4.13 )
!/ 20-Jan-2017 : Update to new W3GSRUMD APIs ( version 6.02 )
!/ 22-Mar-2021 : Add momentum and air density ( version 7.13 )
!/
!/ Copyright 2009-2012 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 :
!
! Pre-processing of the input water level, current, wind, ice
! fields, momentum and air density, as well as assimilation data
! for the generic shell W3SHEL (ww3_shel.ftn).
!
! 2. Method :
!
! See documented input file.
!
! 3. Parameters :
!
! Local parameters.
! ----------------------------------------------------------------
! NDSI Int. Input unit number ("ww3_prep.inp").
! NDSLL Int. Unit number(s) of long-lat file(s)
! NDSF I.A. Unit number(s) of input file(s).
! NDSDAT Int. Unit number for output data file.
! IFLD Int. Integer input type.
! ITYPE Int. Integer input 'format' type.
! NFCOMP Int. Number of partial input to be processed.
! FLTIME Log. Time flag for input fields, if false, single
! field, time read from NDSI.
! IDLALL Int. Layout indicator used by INA2R. +
! IDFMLL Int. Id. FORMAT indicator. |
! FORMLL C*16 Id. FORMAT. | Long-lat
! FROMLL C*4 'UNIT' / 'NAME' indicator | file(s)
! NAMELL C*65 Name of long-lat file(s) +
! IDLAF I.A. +
! IDFMF I.A. |
! FORMLL C*16 Id. FORMAT. | Long-lat
! FROMLL C*4 'UNIT' / 'NAME' indicator | file(s)
! NAMELL C*65 Name of long-lat file(s) +
! IDLAF I.A. +
! IDFMF I.A. |
! FORMF C.A. | Idem. fields file(s)
! FROMF C*4 |
! NAMEF C*65 +
! FORMT C.A. Format or time in field.
! XC R.A. Components of input vector field or first
! input scalar field
! YC R.A. Components of input vector field or second
! input scalar field
! FX,FY R.A. Output fields.
! ACC Real Required interpolation accuracy.
! ----------------------------------------------------------------
!
! 4. Subroutines used :
!
! Name Type Module Description
! ----------------------------------------------------------------
! W3NMOD Subr. W3GDATMD Set number of model.
! W3SETG Subr. Id. Point to selected model.
! W3NDAT Subr. W3WDATMD Set number of model for wave data.
! W3SETW Subr. Id. Point to selected model for wave data.
! W3NOUT Subr. W3ODATMD Set number of model for output.
! W3SETO Subr. Id. Point to selected model for output.
! ITRACE Subr. W3SERVMD Subroutine tracing initialization.
! STRACE Subr. Id. Subroutine tracing.
! NEXTLN Subr. Id. Get next line from input filw
! EXTCDE Subr. Id. Abort program as graceful as possible.
! STME21 Subr. W3TIMEMD Convert time to string.
! INAR2R Subr. W3ARRYMD Read in an REAL array.
! INAR2I Subr. Id. Read in an INTEGER array.
! PRTBLK Subr. Id. Print plot of array.
! W3IOGR Subr. W3IOGRMD Reading/writing model definition file.
! W3FLDO Subr. W3FLDSMD Opening of WAVEWATCH III generic shell
! data file.
! W3FLDP Subr. Id. Prepare interp. from arbitrary grid.
! W3FLDG Subr. Id. Reading/writing shell input data.
! W3FLDD Subr. Id. Reading/writing shell assim. data.
! W3GSUC Func. W3GSRUMD Create grid-search-utility object
! W3GSUD Subr. W3GSRUMD Destroy grid-search-utility object
! W3GRMP Func. W3GSRUMD Compute interpolation weights
! ----------------------------------------------------------------
!
! 5. Called by :
!
! None, stand-alone program.
!
! 6. Error messages :
!
! - Checks on files and reading from file.
! - Checks on validity of input parameters.
!
! 7. Remarks :
!
! - Input fields need to be continuous in longitude and latitude.
! - Longitude - latitude grid (Section 4.a) : program attempts to
! detect closure type (ICLO) using longitudes of the grid. Thus,
! it does not allow the user to specify the closure type, and so
! tripole closure is not supported.
! - Grid(s) from file (Section 4.a) : program reads logical variable
! CLO(J) from .inp file. Thus, it does not allow the user to
! specify more than two closure type (SMPL or NONE), and so
! tripole closure is not supported.
! 8. Structure :
!
! ----------------------------------------------------
! 1.a Number of models.
! ( W3NMOD , W3NOUT , W3SETG , W3SETO )
! b I-O setup.
! c Print heading(s).
! 2. Read model definition file. ( W3IOGR )
! 3.a Read major types from input file.
! b Check major types.
! c Additional input format types and time.
! 4. Prepare interpolation.
! a Longitude - latitude grid
! b Grid(s) from file. ( W3FLDP )
! c Initialize fields.
! d Input location and format.
! 5 Prepare input and output files.
! a Open input file
! b Open and prepare output file ( W3FLDO )
! 6 Until end of file
! a Read new time and fields
! b Interpolate fields
! c Write fields ( W3FLDG )
! ----------------------------------------------------
!
! 9. Switches :
!
! !/WNT0 = !/WNT1
! !/WNT1 Correct wind speeds to (approximately) conserve the wind
! speed over the interpolation box.
! !/WNT2 Id. energy (USE ONLY ONE !)
! !/CRT1 Like !/WNT1 for currents.
! !/CRT2 Like !/WNT2 for currents.
!
! !/O3 Additional output in fields processing loop.
! !/O15 Generate file with the times of the processed fields.
!
! !/S Enable subroutine tracing.
! !/T Enable test output,
! !/T1 Full interpolation data.
! !/T1a Echo of lat-long data in type Fn
! !/T2 Full input data.
! !/T3 Print-plot of output data.
!
! !/NCO NCEP NCO modifications for operational implementation.
!
! 10. Source code :
!
!/ ------------------------------------------------------------------- / Module variables, which occur between the keywords MODULE and CONTAINS, must be declared individually and have an inline
doxygen comment for documentation. Local variables (in SUBROUTINE, FUNCTION, PROGRAM) are not documented with a doxygen comment.
Unlike the headers, no doxygen tags are needed for inline documentation. Instead you include !< followed by the documentation directly
after the variable declaration. If more than one line is needed, you can continue to put additional !< on blank lines that follow with
the rest of the documentation.
module m_constants
!------------------------------------------------------------------------------
!
! physical constants
!
real grav !< gravitational acceleration
real sqrtg !< square root of grav
real gsq !< square of grav
real nu !< kinematic viscosity of water
!
real d_water !< density of water
real d_air !< density of air
!
! mathematical constants
!
real pi !< circular constant, 3.1415...
real pi2 !< 2*pi
real pih !< pi/2
real dera !< conversion from degrees to radians
real rade !< conversion from radians to degrees
real expmin !< min argument for exp. function to avoid underflow
real expmax !< max argument for exp. function to avoid overflow
real sqrt2 !< square root of 2 ~ 1.41
!
contains
!
!------------------------------------------------------------------------------ From the commandline, issue the following command from the WW3 root directory to build the doxygen documentation
doxygen ./docs/Doxyfile.inNote: use doxygen version 1.8.17.
The html output can be displayed in a browser by issuing this command from the WW3 root directory
firefox ./docs/html/index.htmlFirefox is used here as an example, but can be the browser of your choice.