COD Class Examples

ROMS examples for Coastal Ocean Dynamics

Introduction

The page describes idealized configurations of ROMS that are used in Rutgers course 16:712:503 Coastal Ocean Dynamics to illustrate various aspects of ocean dynamics studied in lectures.

Obtaining the source code for examples

In almost all instances the ROMS files that have been customized for these examples are on the Rutgers OARC Amarel cluster amarel.rutgers.edu in directory /projects/dmcs_1/courses/cod. Users must be a member of group dmcs_1 to access these files.

To get started, copy all the files in /projects/dmcs_1/courses/cod to the working directory where you are locally compiling and running ROMS> This is the directory where you ran the UPWELLING test case.

Verify you are in your working directory with

pwd

Then copy everything with a command like this:

cp /projects/dmcs_1/courses/cod/* .

The * is the wildcard for all files in /projects/dmcs_1/courses/cod, and the dot . signifies that the target directory is the directory you are in.

Later in the class some of these files will be updated, and new files added, and when you copy them you will want to be more selective than using the * wildcard if you don't want to overwrite files you have modified for your own work.

What are these files?

cod_*.h files

Each class example has its own cod_*.h file that will be activated to control compilation by setting ROMS_APPLICATION in your personal build_bash.sh script. For example, for COD_1DMIX, you will edit build_bash.sh to set:

export ROMS_APPLICATION=COD_1DMIX

instead of the case UPWELLING that you had when you first ran ROMS.

Once you have copied the cod_*.h file to your working directory, and modified build_bash.sh, recompile by running the build script as you did before, e.g.

./build_bash.sh -j 4

This will create a new romsM executable file to run the COD example.

ana_*.h files

The analytical files are new versions of files in the ROMS/Functionals subdirectory that you downloaded with svn that have been modified to have blocks of code for each of the class examples. The modifications are marked by C-PreProcessor (CPP) directives such as, for example:

#ifdef COD_1DMIX
...
#endif

which will cause that section of code to be compiled when option COD_1DMIX is defined.

This is the way in which we modify ROMS for our own purposes. We can safely have the code for all the COD examples in one version of each ana_*.h file because the code segments are selectively activated with CPP directives.

Some of the class examples use default settings in the analytical files and do not need special instructions.

cod_*.in files

Each class example has its own roms_cod_*.in file that ROMS will read at run-time. This is equivalent to the file roms_upwelling.in that you used when you first ran ROMS.

The job.sh script you use to submit the class examples to the SLURM scheduler with the command sbatch job.sh will have to be modified (at the srun command) to use the appropriate roms_cod*.in file. For example:

srun --mpi=pmi2 ./romsM roms_cod_1dmix.in

Configuring your working directory files

For each class example you will go through the following steps to start.

Refer back to the instructions above for guidance:

1. Copy the necessary COD example case files to your working directory.
2. Modify build_bash.sh to set ROMS_APPLICATION=, for example COD_1DMIX
3. Compile ROMS, i.e. run build_bash.sh
4. Modify your job.sh script to pass the correct input file, for example roms_cod_1dmix.in, to the srun command
   Notice: You must also modify job.sh to request the appropriate number of tasks. Review the entries for NtileI and NtileJ in roms_cod_*.in file and set the correct values.
5. Submit the job to SLURM with sbatch
6. Check for the creation of the netcdf output files.
7. View the output and error log files, i.e. the files named something like out.hal0007.12345678.log and err.hal0007.12345678.log to verify the run was successful, or diagnose the problem.

In these examples certain parameters are set in roms_cod_*.in to allow you to easily vary the configuration and explore how the ocean responds by re-running the example without recompiling.

Example COD_1DMIX

Experimental design

This example has been configured as a 3x3 horizontal grid points doubly-periodic domain. The restrictive number of horizontal points and the double periodicity causes the solution to degenerate to one that can only vary in the vertical.

Certain parameters of the configuration set in roms_cod_1dmix.in in a block of code headed Generic User parameters

! Generic User parameters, [1:NUSER].

NUSER = 8
! user parameters for COD 1DMIX case

! Coriolis depth wind heat strat press tidal wave ! f h stress flux dTdz grad period dissip ! simple steady wind

USER = 1.0d-04 20.0d0 0.06d0 0.0d0 0.5d0 0.0d0 12.42d0 0.01d0

The comment header lines indicate briefly what easy USER parameter sets:

• USER(1) = Coriolis frequency (s^-1)
• USER(2) = water depth (m)
• USER(3) = steady surface wind stress (Pa)
• USER(4) = surface heat flux (W m^-2)
• USER(5) = initial temperature stratification (^oC m^-1)
• USER(6) = magnitude of the oscillating body force pressure gradient forcing
• USER(7) = period of the oscillating body force pressure gradient forcing (hours)
• USER(8) = added turbulence at the sea surface due to wave breaking

The default configuration has an initial thermal stratification and imposes a steady wind stress starting at time = 0. This causes turbulent mixing from the surface downward into the water column, working against the thermal and hence density stratification. Once the stress reaches the seafloor, bottom drag begins to drive turbulent mixing in a bottom boundary layer.

Other parameters in any roms_cod_*.in you might want to alter are:

• NTIMES which sets the number of time steps to run for
  
• Hout and Aout, etc. logical flags that control what output is written to the NetCDF files
  
• GLS_* generic length-turbulence closure parameters. See the (long) GLOSSARY at the bottom of the file for guidance on how to set these for a different closure scheme.
  
• HISNAME, AVGNAME, etc. which set the names of the output files

Loading 1DMIX output in a Jupyter notebook

The xroms package greatly facilitates working with ROMS output because it interprets the coordinate systems that are recorded inside ROMS NetCDF files following CF (Climate-Forecasting) and CDM (Common Data Model) metadata conventions.

You can get started with this minimal example of using xroms to plot at time versus depth ribbon of the temperature

This is more than you need to import, but it's all here for future reference:

import xarray as xr
import numpy as np
import hvplot.xarray
import matplotlib.pyplot as plt
import matplotlib.cm as cm
import matplotlib
%matplotlib inline
import xroms
import cmocean.cm as cmo import xcmocean

Open the NetCDF "history" file with xroms

hfile = 'his_cod_1dmix.nc'
ds = xroms.open_netcdf(hfile)

Plot a 2-D ribbon in time versus depth of temperature, at just one i,j grid cell. It would make no difference to choose xi_rho or eta_rho index of = 0,1,2.

Here, the x,y, plot coordinates are given explicitly, otherwise Python chooses to plot then the other way around, which is not very physical to an oceanographer.

ds.temp.isel(xi_rho=1,eta_rho=1).plot(x="ocean_time",y="s_rho")

This is still somewhat unsatisfactory because the vertical coordinate, s_rho, is the non-dimensional ROMS s-coordinate, whereas we want to see this in physical space, z, in meters.

If you examine the description of this DataArray for variable temp (temperature)

ds.temp.cf.describe()

you will see that xroms has created generic CF Axes X, Y, Z, T and generic CF Coordinates appropriate to the data; here, vertical and time.

Remember, ROMS uses a staggered such that temperature, u and v are at different coordinate locations, with different names. xroms is making it easy for you so you don't have to use different coordinate names every time you plot a different variable.

So, you can plot like this:

ds.temp.cf.isel(X=1,Y=1).cf.plot(x="time",y="vertical")

Notice: To use the generic Axes X,Y there is a .cf before isel, and to use the generic Coordinates there is a .cf before plot.

If you change temp to some other variable, this should also work.

Analysis exercise

Explore the dynamics of this mixing example by plotting time series and vertical profiles of some of the output, especially the netcdf variables named:

• temperature (temp),
• velocity (u,v),
• bottom stress (bustr,bvstr),
• vertical turbulent viscosity (AKv),
• vertical turbulent diffusivity (AKt),
• turbulent kinetic energy (tke),
• GLS closure length scale parameter (gls) - figure out how to get length scale from gls and tke

For example, try plotting time series of temperature at two different depths, say s_rho = 29 (the surface) and s_rho = 18.

You should see the curves approach each other and become identical.

Plot time series also for velocity u and viscosity AKv.

What's going on?