PM_tools

These are tools for the preparation of ROMS configuration and forcing files, currently focused on the RISE ROMS 2.2 simulations. In general these are NetCDF files.

most recently edited 9/17/07

OVERVIEW: These are designed to work in MATLAB, and live in a directory called "PM_tools." They are in part based on the ROMS-AGRIF Roms_Tools created by Perrick Peneven, particularly the code that begins with "ZPP." The overall idea is that we are creating the grid file, forcing files (atmospheric, tides, and rivers), and climatology files (climatology, initial, and boundary). All are NetCDF files, so you need to have the netcdf toolbox installed so it works in MATLAB. These files almost completely define a ROMS run, and you need only edit a few other ROMS files, as described at the end. We avoid the use of analytical.F here. Work in MATLAB, in the PM_tools directory. All files that begin with "Z" live in the Functions directory.

The files are stored on our server.

STEP 1. Create the grid file

• CODE TO EXECUTE: PM_make_grid.m. This will prompt you to choose from a short list of named things like "cr5." This is called the "basename" or [b] in the following.
• INPUT FILES: e.g. Topo/cr5.mat is a topography file that has the appropriate coverage and resolution for a given basename. I've been making these from the GEODAS dataset. cr5.mat has the regional bathymetry at 6 second (~200 m) resolution. The finest available from GEODAS is 3 second.
• OUTPUT FILES: [b]/[b]_grd.nc. The directory [b]/ is created if it did not exist.
• THINGS TO EDIT: The grid extent, stretching properties and minimum depth for a given basename are defined in Z_get_gridinfo.m. To make a new basename you edit this file. It also calls Z_edit_topo.m which is where you can edit the grid by hand to make a river channel. You also can edit PM_make_grid.m around lines 81-85 to set the topographic smoothing parameter. By default it is set to 0.3, which is standard (smaller number= smoother) but maybe not required. I use 0.8 in cr8 to try to keep the CR channels deeper.
• NOTES: Each basename is defined by a "plaid" (meaning something you could create in matlab using the meshgrid command) lat, lon spherical grid that can stretch in both directions. PM_make_grid.m also calls some ZPP functions to set up the grid netcdf file (ZPP_rho2uvp.m, ZPP_create_grid.m, ZPP_get_metrics.m), do some initial editing of the landmask (ZPP_process_mask.m and ZPP_uvp_mask.m), and smooth the grid (ZPP_smoothgrid.m). For the new grid "cr10" with has better resolution of the CR, Willapa, and Grays estuaries we also have the code Functions/add_CR_thalweg.m to carve a more accurate southern channel in the CR, and replace_mask_cr10_from_cr8.m which keeps us from having to re-edit the landmask.

STEP 2. Edit the landmask by hand, if desired

• CODE TO EXECUTE: PM_editmask.m.
• INPUT FILES: Choose [b]/[b]_grd.nc and Coastlines/coastline_detailed_3.mat when prompted. This coastline file has a bit I added for the south CR jetty.
• OUTPUT FILES:[b]/[b]_grd.nc (now with a modified landmask)
• NOTES: You can look at the mask, grid, bathymetry, and the effects of smoothing, using Look_grid.m.

STEP 3 (any order). Make the tidal forcing

• CODE TO EXECUTE: PM_make_tides.m. This will prompt you for the basename and the year (2004-2006).
• INPUT FILES: Tides/TPXO6.nc and [b]/[b]_grd.nc
• OUTPUT FILES: [b]/Forcing/[b]_[year]_tides.nc
• THINGS TO EDIT: You have to set the run start time in PM_make_tides.m, which is covered by the switch around line 40. For a standard 2004 run I start it at June 3, 2004, hour 00:00, GMT, which translates to day 154.0 when you are setting up your ROMS .in file (referenced to the start of 2004). The MM5 atmospheric forcing actually starts at 7 AM the previous day.
• NOTES: This relies on a lot of Peneven code contained in the directory Tides. Deep within these in egbert_correc.m you set the reference time for the tidal phase, and this happens to be 1/1/1992. This ends up being used in your .in file to set the parameter TIDE_START. For example, if in your ROMS .in file you use TIME_REF = 20040101.00 then you would set TIDE_START = -4383.0d0 which is the same as what you get in matlab from datenum(1991,1,1) - datenum(2004,1,1).

STEP 3 (any order). Make the river forcing

• CODE TO EXECUTE: PM_make_rivers.m. This will prompt for the basename and the year (2004-2006).
• INPUT FILES: Rivers/CR_flow_[year].mat which I made using USGS data from the Beaver station (has both temperature and flow rate, daily). It also reads in the gridfile.
• OUTPUT FILES: [b]/Forcing/[b]_[year]_rivers.nc
• THINGS TO EDIT: Around lines 90-95 in PM_make_rivers.m you have to set the S-coordinate parameters, the same as they will be set in your ROMS .in file, e.g. N=20, theta_s=5, theta_b=0.8, Tcline = 0.
• NOTES: This currently sets the river location AUTOMATICALLY (lines ~194-201) by looking for the gap in the landmask at the Eastern boundary.

STEP 3 (any order). Make the atmospheric surface forcing

• CODE TO EXECUTE: PM_make_surface_forcing.m which will prompt for the basename and year (2004-2006).
• INPUT FILES: The gridfile and mm5_extractor/mm5_[year]/interpolated_t/[var1].mat which has been created out of hourly MM5 fields (time gaps interpolated over using the "Darr method" which preserves that daily cycle of shortwave rediation). Note that [var1] is a list of different properties, each of which ends up in its own file, and which will be renamed for ROMS as [var2]. These are: [var1/var2] = [PSFC/Pair, RAIN_CON/rain, SWDOWN/swrad, LWDOWN/lwrad_down, T2/Tair, Qair/Qair, U10/Uwind, V10/Vwind].
• OUTPUT FILES: [b]/Forcing/[b]_[year]_[var2].nc
• THINGS TO EDIT: You can do some scaling in PM_make_surface_forcing.m, e.g. we decrease the downward shortwave radiation by about 14% to account for average surface albedo, and we set the rain to zero.
• NOTES: For our current highest-resolution grid, cr8, this takes about 30 minutes and makes 6.5 Gb of files on my laptop. This is for 3 months of hourly 2004 data. You can edit around line 58 of PM_make_surface_forcing.m to limit or subsample the times it will use.

STEP 4 (THREE PARTS!). Make the climatology, boundary, and initial files

• CODE TO EXECUTE #1: PM_make_clim_ver4.m which will prompt for the basename and the year (2004 or 2005, still no NCOM files for 2006). This makes the (potentially big) x,y,z,t climatology file from NCOM-CCS 9 km model fields.
• INPUT FILES: The gridfile and NCOM/Data/NCOM1_[S,T,U,V,SSH]_[year]_[months].nc which were created using PM_preprocess_clim_ver5.m (still has to be run for 2005). These have fields every 12 hours (GMT I assume) for 4 months (06_09 for 2004) or 6 months (04_09 for 2005). Note that "ver5" includes the capability to use HYCOM forcing (by Yonggang).
• OUTPUT FILES: [b]/Climatology/[b]_[year]_clm.nc = (*)
• THINGS TO EDIT: You have to set the S-coordinate parameters in PM_make_clim_ver4.m around lines 42-46 (line number out of date for ver4).
• NOTES: You can edit PM_make_clim_ver4.m around line 174 (line number out of date for ver4) to limit or subsample the times it will use. For our current highest resolution grid, cr8, this code took 115 minutes for the 4 months of 2004, subsampled to every 4th point (so data every two days, at midnight) and the resulting file was 2 Gb in size. You can look at a bit of the climatology file using Look_clim.m (not very well developed yet). The new versions (by Yonggang) such as PM_make_clim_ver4.m and PM_preprocess_clim_ver5.m fix a bug in the time subsampling.
• CODE TO EXECUTE #2: PM_clm2ini.m
• INPUT FILES: (*)
• OUTPUT FILES: [b]/Climatology/[b]_[year]_ini.nc
• THINGS TO EDIT: You have to set the start time (e.g. 6/3/2004 00:00) as you did for the tides.
• CODE TO EXECUTE #3: PM_clm2bry.m
• INPUT FILES: (*)
• OUTPUT FILES: [b]/Climatology/[b]_[year]_bry.nc

THEN YOU'RE DONE! A useful tool is the low resolution test run whose basename is cr6. You can make the forcing files for this in just a few minutes, and it runs for 3 months of model time in just ~30 minutes on my laptop. The cppdefs.h flag for this run is TPLUME, and suitable Include/cppdefs.h and External/ocean_tplume.in files are included in the directory cr6_ROMS_files. There you will also find a copy of the only other two files that (I think) have to be edited differently from the release version of ROMS 2.2). One is Utility/set_nudgcof.F where we set the region and strength of the region of nudging to climatology. The other is Modules/mod_param.F where you have to set the grid size. Note that if your basic rho-grid has size [R,C] e.g. as reported by the tool nc_info.m, then in mod_param.F you have to set Lm = C-2 and Rm = R-2.