RegCM-ROMS Tutorial:

Introduction to ROMS Ocean Model

Ufuk Utku Turuncoglu
ICTP (International Center for Theoretical Physics)
Earth System Physics Section

- Outline

Outline
Introduction
Grid generation and smoothing
Input files
Forcing, initial, boundary conditions etc.
Getting ROMS code
Configuration of the model
Installation
Namelist file and running in standalone mode

- Introduction (1/2)

Basics of the ROMS ocean model

ROMS
Primitive equations with potential temperature, salinity, and an
equation of state
Hydrostatic and Boussinesq approximations
It supports different advection and mixing schemes
It supports point sources and sinks (i.e. river discharge)
It has version that is coupled with ice model
Horizontal Grid
Arakawa C
Orthogonal-curvilinear coordinates (with masking of land areas)
Support for closed basins (like lakes, inland waters etc.) and domains
with periodic and also open boundary conditions
Vertical Grid
Terrain following sigma coordinate
Free surface

- Introduction (2/2)

Steps to create an application (standalone ROMS)

Create input files (also can be generated analytically by Fortran code)
Independent from
Grid
Forcing (atmospheric, river etc.) vertical coordinates
Boundary Condition (BC) - if domain has open boundaries

create these

Initial Condition (IC)

coordinates

Climatology - if nudging and/or relaxation are activated

Create configuration file (*.h)

changed

files after vertical

A set of CPP option must be defined such as advection, mixing, flux

calculation etc.
Create namelist file (*.in)
User needs to edit namelist file based on the created application
(additional namelist file exist for ICE model).
Run
Edit machine specific definitions (Build/*.mk and build.sh)
Run the model

- Grid Generation (1/7)

Grid Generation Tools

complex grid

Simpler
grid

Matlab (w and w/o GUI)

SEAGRID, GRIDGEN, EASYGRID etc.
More info: https://www.myroms.org/wiki/index.php/Grid_Generation
Python
pyroms: https://github.com/kshedstrom
has several different versions. It can be also used to create input files

- Grid Generation (2/7)

Grid Generation Example (with pyroms)

Caspian Sea Grid
There is no open boundary
ETOPO-1 is used for bathymetry
Horizontal resolution is ~10 km with 32 sigma layers (theta-s = 7.0,
theta-b = 0.2, hmin = 5 m)

- Grid Generation (3/7)

Grid Generation Example (with pyroms)

- Grid Generation (4/7)

Grid Generation Example (with pyroms)

- Grid Generation (5/7)

Grid Generation Example (with pyroms)

Grid Stiffness Ratios (indicator for PGE and CFL error)

Beckman & Haidvogel Number (1993)

" hi hi1 % Reduced by smoothing. The

" h %
rxo = max $ ' = max $
' value should be < 0.25
# 2h &
# hi + hi1 ) &
Haney Number (1991)

"z z
% Reduced by smoothing and
i, j,k
i1, j,k + zi, j,k1 zi1, j,k1
rx1 = max $$
'' vertical coordinate mod. The
# zi, j,k + zi1, j,k zi, j,k1 zi1, j,k1 & value should be < 6.0

- Grid Generation (6/7)

Grid Generation Example (with pyroms)

The Matlab smoothing toolbox

(LP_Bathymetry) can be also
used to fix the bathymetry
http://drobilica.irb.hr/~mathieu/
Bathymetry/

- Grid Generation (7/7)

Grid Generation Example (with pyroms)

Vertical Coordinates
Vertical Transformation (opt: 1-2)

h ( x, y) z ( x, y, , t )
Vertical Stretching Functions (opt: 1-4)
2 higher resolution at the surface
3 for shallow applications
4 default in current version of ROMS, user can control stretching both
in surface and bottom
https://www.myroms.org/wiki/index.php/Vertical_S-coordinate

- Creating Forcing, Initial and Boundary Condition (1/6)

ROMS Input Requirements

Atmospheric Forcing
Surface atmospheric conditions are needed to drive the ocean model
These variables are used to calculate heat, momentum and
momentum fluxes over the ROMS domain
Fields must be interpolated into ROMS grid. The wind components
must be rotated to destination grid (in this case ROMS). Unit
conversion might be needed
Initial Conditions (IC)
Initial condition (T,S,U,V) must be given to ocean model. The model
can be started from simple vertical temperature and salinity profile with
no motion (spin-up run needed and length depends on the application)
Boundary Conditions (BC)
If domain has open boundary conditions like Mediterranean Sea
Input for nudging and/or relaxation
Temperature and salinity observations must be interpolated into ROMS
ocean model grid. The model try to minimize the difference !!!

- Creating Forcing, Initial and Boundary Condition (2/6)

ROMS Input Requirements

Input files and the required fields can change based on selected CPP
options in *.h file.
LONGWAVE_OUT: net shortwave flux, downwelling longwave flux,
surface temperature, mixing ratio and pressure, wind components, rain
LONGWAVE: net longwave flux rather than downwelling longwave flux
w/o BULK_FLUXES: wind stress, net heat fluxes, fresh water flux
ALBEDO and/or CLOUD: needs cloud fraction as input
*_TIDES: needs tidal forcing file
with point sources (i.e. rivers)
UV_PSOURCE, Q_PSOURCE: needs extra NetCDF forcing files
with RegCM coupling
BULK_FLUXES+LONGWAVE_OUT+REGCM_COUPLING must be
defined for coupled mode (RegCM+ROMS).
with nudging and/or relaxation
Needs four-dimensional (x,y,z,t) temperature and salinity fields

- Creating Forcing, Initial and Boundary Condition (3/6)

Tools to create input files

3d interpolation
2d interpolation
Matlab
ROMS Matlab Package: http://www.myroms.org/software/Processing/
Python
pyroms: https://github.com/kshedstrom
ESMF Python Interface: http://earthsystemcog.org/projects/esmp/
NCL (now supports ESMF offline re-gridding)

- Creating Forcing, Initial and Boundary Condition (4/6)

Initial condition file (with pyroms)

2d interpolation
3d interpolation

The original pyroms python module does not support AGrid (but it could
be generated using logic of the BGrid python files)
The interpolation weight files are created by SCRIP toolbox (it has a
Python wrapper) but it can be modified to use ESMP
Info about SCRIP toolbox: http://climate.lanl.gov/Software/SCRIP/
Image - Arakawa Grid Types - http://trac.mcs.anl.gov/projects/parvis/wiki/Discretizations

- Creating Forcing, Initial and Boundary Condition (5/6)

Initial condition file (with pyroms)

It basically creates the NCO commands to merge the variables into a

single file.
NCO must be installed before using this method to merge data !!!
More information about NCO: http://nco.sourceforge.net/

- Creating Forcing, Initial and Boundary Condition (6/6)

Creating interpolation weight matrix (with pyroms)

It creates the interpolation weight matrix. This can be done outside of

the pyroms but in this case grid definition netcdf files must be created by
user.

- Getting ROMS Code (1/1)

Getting ROMS code

Register
New users must be register via following web site.
https://www.myroms.org/index.php?page=login
Download Source Code via SVN
SVN is a version control system
SVN must be installed
List of tagged versions: svn ls https://www.myroms.org/svn/src/tags
Checkout: svn co --username [YOUR_USER_NAME] https://
www.myroms.org/svn/src/tags/roms-3.5 roms-3.5
Ice branch is in the https://github.com/kshedstrom but there is no
tagged version.
Notes
The coupled modeling system currently uses ROMS version 3.5 and
user needs to apply small patch to enable coupling.
The same patch can be used to create patch for ice version of ROMS

- Configuration of the Model (1/1)

Header file (*.h)

cas.h

Ice model
related definitions

No open boundary
E/N/S/W closed

The file includes set of preprocessor (CPP) flag to activate specific part
of the code.
The whole list of the available CPP options - ROMS/Include/cppdefs.h

- Installation (1/2)

Steps
Edit machine specific file (*.mk)
Files is in the Compilers/ directory

Linux+Intel Fortran Compiler

Create case directory

This directory is used to run the model
The required files *.h (header file)
Copy build script (build.sh) from ROMS/Bin directory to case directory
Edit build.sh (specify source path, case name, compiler and MPI types
etc.)
Install ROMS using ./build.sh command (this will create oceanM file, if
debug option is specified the file name will be oceanG)
Create input and output directories under case directory
Copy grid, forcing, initial and boundary forcing files to input directory

- Installation (2/2)

build.sh

- Running ROMS (1/3)

Editing namelist file (*.in)

cas.in
domain size and
number of vertical
layer

Domain decomposition
parameters, must be consistent
with job submission script !!!
option for restart,
NRREC = -1 is
fresh run

option for output

interval

- Running ROMS (2/3)

Editing namelist file (*.in)

cas.in
Height of surface
atmospheric data
Jerlow water type.
Related with
turbidity and
shortwave rad.
penetration. 5 is
more turbid
Vertical grid
definition, it must
be consistent with
input files !!!

There are options for input files

Options for horizontal and vertical mixing coefficents
Options for output fields
Options for open boundary conditions

- Running ROMS (1/1)

Creating run script

PBS

roms.job

Job can be submitted via qsub roms.job command

LSF

roms.lsf

Job can be submitted via bsub < roms.lsf command

- End of ROMS Tutorial

Last words
ROMS is one of the most advanced and complex numerical models in
the world. The learning Curve is very steep but it is our experience that
the model grows on the user when he/she realizes its capabilities.
from user registration form

Facts and Suggestions:

There is no single tool to create all the input files and setup an
application. This needs an additional learning curve and everybody has
its own way.
Some nice tools are available and can be used but you might need to
modify them !!!
The ROMS code getting very complex and user needs some
experience about ocean modeling.
Run the application in standalone mode (only ocean model) and tune
it. Do some long run and check the drift !!! After that you can go one
step further and couple RegCM-ROMS.