WW3 model adapter

Wavewatch 3

WaveWatch3 is a full-spectral third-generation wind-wave model, developed at the Marine Modeling and Analysis Branch (MMAB) of the Environmental Modeling Center (EMC) of the National Centers for Environmental Prediction (NCEP). It is based on WAVEWATCH I and WAVEWATCH II as developed at Delft University of Technology, and NASA Goddard Space Flight Center, respectively. WAVEWATCH III differs from its predecessors in all major aspects; i.e., governing equations, program structure, numerical and physical approaches.

Running wavewatch3 models: http://polar.ncep.noaa.gov/waves/workshop/pdfs/wwws_2013_running.pdf

Wavewatch3 manual: http://polar.ncep.noaa.gov/mmab/papers/tn276/MMAB_276.pdf

Wavewatch 3 Model Adapter - summary

This page describes the WW3 module adapter, its functions, and provides an example for configuring a WW3 run in FEWS.

The pre-adapter creates the model specific output by replacing tags in template files:

• ww3_shell.inp.template for run information file ww3_shell.inp
• gx_outf.inp.template for grid output processing file gx_outf.inp
• ww3_out.inp.template for point output processing file ww3_out.inp

Furthermore, it writes log messages to a log file called xbeach.log.

The post-adapter converts the 2D spectra model output from the model native format to NetCDf.

WW3 pre-adapter

Model pre-adapter for running a Wavewatch 3 model from Delft-FEWS.

Class name: nl.deltares.wavewatch.PreWWIIIAdapter

Properties

Notes for users

• For all files that are written by this adapter, if the file to be written already exists, then it will be overwritten.
• This program assumes that the model always runs in time zone GMT.
• This program writes log messages to a log file called preww3.log.
• This program uses the information in the specified netcdf run file as input and uses this information to do the following actions:
  1. Copy template file ww3_shell.inp.template to create the shell input file ww3_shell.inp
  2. Copy template file gx_outf.inp.template to create the grid output post-processing file: gx_outf.inp

  3. Copy template file ww3_out.inp.template to create the point output post-processing file: ww3_out.inp
     In the input files the following tags will be replaced with the corresponding values:

     $STARTTIME$	Start time of the model run.
     $ENDTIME$	End time of the model run.
     $TIMESTEP$	Time step of the model in seconds
     $NSTEP$	Number of time steps to write as output calculated as a function of STARTTIME, ENDTIME, and TIMESTEP.

Example template files: ww3_outp.inp.template; gx_outf.inp.template; ww3_shel.inp.template

System requirements

• This program needs Java version 8 or higher.
• This program needs the following Java libraries:
  • castor-0.9.5.jar
  • commons-httpclient-3.0.1.jar
  • Delft_FEWS.jar
  • Delft_FEWS_DataStore.jar
  • Delft_PI.jar
  • Delft_PI_castor.jar
  • Delft_Util.jar
  • fews-wavewatch-adapter.jar
  • grib-8.0
  • log4j-1.2.14.jar
  • netcdf-4.2.jar
  • slf4j-api-1.5.6.jar
  • slf4j-log4j12-1.5.6.jar
  • TimeSeriesImport.jar
  • xercesImpl.jar

WW3 post-adapter

Model post-adapter for running a Wavewatch 3 model from Delft-FEWS.

Class name: nl.deltares.wavewatch.PostWWIIIAdapter

Notes for users

• For all files that are written by this adapter, if the file to be written already exists, then it will be overwritten.
• This program assumes that the model always runs in time zone GMT.
• It converts ww3.YYMMDDHH.spc 2D spectra model output file to NetCDf format.
• This program writes log messages to a log file called postww3.log.

System requirements

• This program needs Java version 8 or higher.
• This program needs the same Java libraries as the pre-adapter.

Running a WaveWatch 3 model

WW3 makes use of auxiliary programs which are described in the WW3 manual: http://polar.ncep.noaa.gov/mmab/papers/tn276/MMAB_276.pdf

• ww3_grid.exe (grid pre-processor, page 75 of the manual)
• ww3_prep.exe (wind field pre-processor for the generic shell, page 86)
• ww3_shel.exe (model executable or generic shell, page 89)
• ww3_outp.exe (point output post-processor, page 100)
  • Input
    • ww3_outp.inp
    • mod_def.ww3 (binary file, created by ww3)
    • out_pnt.ww3 (raw point output data)
  • Output
    • tabnn.ww3, table of mean parameters where nn is a two-digit integer)
    • ww3.YYMMDDHH.spc file, with the 2D spectra in an ASCII format. The post-adapter will convert this to a ww3.nc file, which FEWS can import in the importActivities.
• gx_outf.exe (gridded output post-processor for GrADS, page 107. Output ww3.grads)
  • Input
    • gx_outf.inp
    • mod_def.ww3
    • out_grd.ww3 (raw gridded output data)
  • Output
    • ww3.grads

To run these programs, you need some model definition files as input. This is described at the same locations in the manual. With the Risc-Kit config we make use of the following files (see also Risc-kit\ModuleDataSetFilesUnzip\WaveWatchIII_global_nomads\model\)

• ww3_grid.inp
• ww3_prep.inp
• ww3_shel.inp (among other things, it has the list of locations for which model output can be generated)
• gx_outf.inp
• ww3_outp.inp (selection of locations specified in ww3_shel.inp, for which point output will be created)
• <model_name>.bot
• <mode_name>.obs

(Some of these are template files in FEWS, because FEWS will edit the $TAGS$ before it passes the file to WW3)

Example Configuration generalAdapterRun

The following gives an example of how to set up the GeneralAdapterRun file for Wavewatch 3 in FEWS using the WW3 model pre and post-adapters.  The GeneralAdapterRun file follows the general structure as described here.

general

In this section general information regarding the module such as version number, file directories, missing values, and time zone information can be specified.

<general>
		<description>WaveWatch Model run</description>
		<piVersion>1.8</piVersion>
		<rootDir>%REGION_HOME%/Modules/WavewatchIII/$MODEL$/$METEO$_hindcast</rootDir>
		<workDir>%ROOT_DIR%/workDir</workDir>
		<exportDir>%ROOT_DIR%/input</exportDir>
		<exportDataSetDir>%ROOT_DIR%/</exportDataSetDir>
		<exportIdMap>IdExport_wavewatchIII</exportIdMap>
		<importDir>%ROOT_DIR%/output</importDir>
		<importIdMap>IdImport_wavewatchIII</importIdMap>
		<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
		<dumpDir>%ROOT_DIR%/diagnostics/</dumpDir>
		<diagnosticFile>%ROOT_DIR%/diagnostics/diagnostics.xml</diagnosticFile>
		<missVal>NaN</missVal>
		<timeZone>
			<timeZoneName>GMT+0:00</timeZoneName>
		</timeZone>
</general>

startUpActivities

It may be useful to clear the model working directory of any previous runs before starting a new run.

<startUpActivities>
	<purgeActivity>
		<filter>%ROOT_DIR%/workDir/*</filter>
	</purgeActivity>
</startUpActivities>

exportActivities

In this section the data to be exported from FEWS as input to the module is specified. Data to export to WW3 generally includes:

• Model state (restartn.ww3, where n represents a single digit integer number)
• Model data set
• Input data (i.e. wind, water levels, wave spectra)
• Run file

The run file contains information regarding the input file names, start and stop times, and time step. Additional properties can be passed using the run file as listed above under Properties. 

<exportActivities>
			<exportStateActivity>
				<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
				<stateExportDir>%ROOT_DIR%/workDir</stateExportDir>
				<stateSelection>
					<warmState>
						<stateSearchPeriod unit="hour" start="-72" end="-24"/>
					</warmState>
				</stateSelection>
			</exportStateActivity>
			<exportDataSetActivity>
				<moduleInstanceId>WavewatchIII_$MODEL$_$METEO$</moduleInstanceId>
			</exportDataSetActivity>
			<exportNetcdfActivity>
				<exportFile>$METEO$.nc</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>Import_$METEO$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wind.u.simulated</parameterId>
						<locationId>$METEO$</locationId>
						<timeSeriesType>external historical</timeSeriesType>
						<timeStep unit="hour" multiplier="3"/>
						<relativeViewPeriod unit="day" start="-3" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>Import_$METEO$</moduleInstanceId>
						<valueType>grid</valueType>
						<parameterId>Wind.v.simulated</parameterId>
						<locationId>$METEO$</locationId>
						<timeSeriesType>external historical</timeSeriesType>
						<timeStep unit="hour" multiplier="3"/>
						<relativeViewPeriod unit="day" start="-3" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportNetcdfActivity>
			<exportNetcdfRunFileActivity>
				<exportFile>%ROOT_DIR%/runinfo.nc</exportFile>
				<properties>
					<string value="3600" key="TIMESTEP"/>
				</properties>
			</exportNetcdfRunFileActivity>
		</exportActivities>

executeActivites

WW3 makes use of auxiliary programs which are described in the WW3 manual: http://polar.ncep.noaa.gov/mmab/papers/tn276/MMAB_276.pdf
This section calls the WW3 pre and post-adapters as well as the WW3 executables. Note that the run file must be passed as an argument to the WW3 pre and post-adapters. Also note that several executable must be called in the order as described in the example.

<executeActivities>
	<executeActivity>
		<description>WavewatchIII pre-adapter</description>
		<command>
			<className>nl.deltares.wavewatch.PreWWIIIAdapter</className>
			<binDir>%ROOT_DIR%/../../../bin/WavewatchIII_adapter</binDir>
		</command>
		<arguments>
			<argument>%ROOT_DIR%/runinfo.nc</argument>
		</arguments>
		<timeOut>10800000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>ww3_grid</description>
		<command>
			<executable>%ROOT_DIR%/../../../bin/WavewatchIII/ww3_grid.exe</executable>
		</command>
		<timeOut>90000000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>ww3_prep</description>
		<command>
			<executable>%ROOT_DIR%/../../../bin/WavewatchIII/ww3_prep.exe</executable>
		</command>
		<timeOut>90000000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>ww3_shel</description>
		<command>
			<executable>%ROOT_DIR%/../../../bin/WavewatchIII/ww3_shel.exe</executable>
		</command>
		<timeOut>90000000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>Run WavewatchIII</description>
		<command>
			<executable>%ROOT_DIR%/../../../bin/WavewatchIII/gx_outf.exe</executable>
		</command>
		<timeOut>90000000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>Collect output WavewatchIII</description>
		<command>
			<executable>%ROOT_DIR%/../../../bin/WavewatchIII/ww3_outp.exe</executable>
		</command>
		<timeOut>90000000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
	<executeActivity>
		<description>WavewatchIII post-adapter</description>
		<command>
			<className>nl.deltares.wavewatch.PostWWIIIAdapter</className>
			<binDir>%ROOT_DIR%/../../../bin/WavewatchIII_adapter</binDir>
		</command>
		<arguments>
			<argument>%ROOT_DIR%/runinfo.nc</argument>
		</arguments>
		<timeOut>10800000</timeOut>
		<ignoreDiagnostics>true</ignoreDiagnostics>
	</executeActivity>
</executeActivities>

importActivities

In this section the data to be imported into FEWS as output from the module is specified. Data to import from WW3 generally includes:

• Model state
• Output data (i.e. 2D wave spectra)

<importActivities>
			<importStateActivity>
				<stateFile>
					<importFile>%ROOT_DIR%/workDir/restart1.ww3</importFile>
					<relativeExportFile>restart.ww3</relativeExportFile>
				</stateFile>
				<expiryTime unit="day" multiplier="3"/>
			</importStateActivity>
			<importNetcdfActivity>
				<importFile>ww3.nc</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>Wave.variancedensity2D.simulated</parameterId>
						<domainParameterId>f</domainParameterId>
						<domainParameterId>dir</domainParameterId>
						<locationSetId>wavewatchIII</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
				<maximumSnapDistance>100</maximumSnapDistance>
			</importNetcdfActivity>
		</importActivities>