Applications

Contributed User Applications

User applications that are not distributed with the ROMS source code are invited here

Changes to the code structure now make it straightforward to confine application-specific options to a small number of files maintained separately from the central code.

This approach has the advantages that:

• users can update their central code, adding newly developed features and fixing reported bugs, without upsetting personal options for a specific project
• users can work on more than one project at once using a single up-to-date code stem
• applications can be shared with colleagues without redistributing the entire source code, thereby fostering user community use of the most up-to-date ROMS release

Most users configuring a typical application of the forward simulation model need only edit:

• a file containing the CPP definitions, e.g. project.h. (The cppdefs.h file in previous ROMS versions has been re-structured to do this).
• an input roms.in script
• initial, forcing and/or boundary netcdf files
• application-specific analytical options following the templates for ana_*.F files in the User/Functionals directory. (The analytical.F subroutine in previous versions has been re-structured to do this).

CBLAST

Configuration and input files for a model of the southeast New England shelf during the ONR Coupled Boundary Layers and Air-Sea Transfer (CBLAST) experiment are provided here as one example of how we recommend users configure realistic applications.

The files required to configure and run ROMS for CBLAST are available for download from www.myroms.org at the Datasets link on the left navigation panel (under the subheading Software), or follow this link [1].

A brief description of the files follows:

cblast.h

This file defines CPP flags (previously in cppdefs.h) that set options for physics, numerical schemes, vertical turbulence closure, open boundary conditions, biology, sediment transport ... and output options (averages, diagnostics, stations, floats) are set in cblast.h.

ocean_cblast.in

This file is the roms.in file for CBLAST that sets values that are defined at execution. Parameters of particular relevance to CBLAST include: timestep, output frequency, open boundary nudging timescales and input netcdf file paths (amongst many others).

In this example we use relative paths to input files that assume the following directory hierarchy:

• cblast/
  • Data/
    • all initial, surface forcing, tides, and other open boundary data
    • the varinfo.dat file that matches model input/output variable names to corresponding netcdf data variables. A varinfo.dat is not included here because we use the default distributed with the code in ROMS/External/varinfo.dat
  • Forward
    • cblast.in
    • ocean_cblast.in

Our choice of this directory hierarchy anticipates other applications with the Adjoint and 4DVAR codes for model sensitivity and data assimilation studies which would require distinct cblast.h files in each subdirectory (all controlled by a master driver script). You can change this organizational structure for files to suit your own requirements - just make the necessary changes in ocean_cblast.in so that ROMS finds the files.

build_cblast.sh

This script is a work in progress. We have already resolved some issues to do with the control of make depend. For now, the script provided here works but will be updated to use new features in the makefile as they evolve and are tested.

This csh shell script serves to illustrate how a specific application can be configured without editing the makefile by using UNIX shell environment variables to over-ride the makefile defaults. If in the makefile a flag is set with the syntax VARIABLE ?= value this indicates its default value, but if VARIABLE is set in the shell that calls the script then the job inherits that value and over-rides the default. Of course, you can also choose to edit that line in the makefile itself and operate in that way. Just remember you did this.

In the example given here we set the variables:

• ROMS_APPLICATION is CBLAST which tells make to look for CPP definitions in a file called cblast.h. See makefile for more information. The value of ROMS_APPLICATION must match the parameter MyAppCPP in roms.in
• MY_HEADER_DIR tells make where to look for the cblast.h CPP defs file.
• MY_ANALYTICAL_DIR sets where ana_*.F files would be located. The CBLAST example here does not require any such files, but this line is left for information.
• BINDIR: Sets where te executable should be placed following sucessful compilation.
  • Not used in this example:
    • SCRATCH_DIR would set the path to a temporary Build subdirectory is created to hold *.f90 and *.o files.
    • setenv MPI on would activiate compilation for parallel execution.
    • If your FORTRAN compiler is not the default in makefile, you could set it here with setenv FORT myF90compilername.

Executing the script build_cblast sets these environment variables to inform make what do when building the CBLAST application. The executable binary will be called oceanM and the model would be run with command like:

 cd MyProjects/cblast/Forward
 ./oceanS < ocean_cblast.in > ocean_cblast.log

This model configuration was used to obtain the results described in:

Wilkin, J., 2006: The summertime heat budget and circulation of southeast New England shelf waters, Journal of Physical Oceanography, 36(11), 1997-2011.

The URL for full text article: http://ams.allenpress.com/perlserv/?request=get-document&doi=10.1175%2FJPO2968.1

A further study using this model set-up considers tidal circulation on the Nantucket Shoals:

He, R. and J. Wilkin, 2006: Barotropic tides on the southeast New England shelf: A view from a hybrid data assimilative modeling approach. Journal of Geophysical Research, 111, C08002, doi:10.1029/2005JC003254.

LATTE

Coming soon.