Utility Scripts

Matlab: Utility Scripts

This page describes several Matlab scripts in the matlab/utility repository sub-directory which are used for various purposes.

depths.m

Computes the depths at the requested staggered C-grid. If the time record (Tindex) is not provided, a zero free-surface is assumed and the unperturbed depths are returned.

z = depths  (Fname, Gname, igrid, idims, Tindex)

On Input:

Fname:	ROMS NetCDF data file name (string)
Gname:	ROMS NetCDF grid file name (string)
igrid:	Staggered grid C-type (integer):

igrid=1 - density points

igrid=2 - stream-function points

igrid=3 - u-velocity points

igrid=4 - v-velocity points

igrid=5 - w-velocity points

idims:

Depths dimension order switch (integer):

idims=0 - (i,j,k) column-major order (Fortran and Matlab order)

idims=1 - (j,i,k) row-major (C-language order)

Tindex:

Time index for free-surface (integer)

On Output:

z:	Depths (3D array; meters, negative)

gcircle.m

Computes great circle distance and initial bearing between two longitude and latitude points. The Earth is assumed to be a sphere. This approximation is valid for short distances. Longitude is positive to the east and negative to the west. Latitude is positive to the north and negative to the south.

[dist, bearing] = gcircle  (lon1, lat1,lon2, lat2, BEARING)

On Input:

lon1:	longitude point 1 (decimal degrees)
lat1:	latitude point 1 (decimal degrees)
lon2:	longitude point 2 (decimal degrees)
lat2:	latitude point 2 (decimal degrees)
BEARING:	Switch to compute bearing angle (logical)

On Output:

dist:	Great circle distance between point 1 and point 2 (kilometers)
bearing:	Azimuth from point 1 to point 2 counterclockwise from true EAST (decimal degrees)

sample_grid.m

Computes the donor grid indices range of the polygon that tightly contains the target grid. This is done to sample the donor grid to accelerate the interpolation of fields for the receiver grid. The input coordinates can be either in terms of Cartesian or spherical coordinates

[Istr, Iend, Jstr, Jend] = sample_grid  (XD, YD, XR, YR, offset, plt)

On Input:

XD:	Donor grid X-coordinates (2D array)
YD:	Donor grid Y-coordinates (2D array)
XR:	Receiver grid X-coordinates (2D array)
YR:	Receiver grid Y-coordinates (2D array)
offset:	Number of extra points used to sample the donor grid so it is large enough to contain the target grid (optional; default 5)
plt:	Switch to plot parent and target grids (logical; optional; default false)

On Ouput:

Istr:	Donor grid starting I-index for sampling
Iend:	Donor grid ending   I-index for sampling
Jstr:	Donor grid starting J-index for sampling
Jend:	Donor grid ending   J-index for sampling

set_depth.m

Given a batymetry (h), free-surface (zeta) and terrain-following parameters, this function computes the 3D depths for the requested C-grid location. If the free-surface is not provided, a zero value is assumed resulting in unperturbed depths. This function can be used when generating initial conditions or climatology data for an application. Check this page for details.

z = set_depth  (Vtransform, Vstretching, theta_s, theta_b, hc, N, igrid, h, zeta, report)

On Input:

Vtransform:

Vertical transformation equation (integer)

Vtransform = 1

original transformation

z(x,y,s,t) = Zo(x,y,s) + zeta(x,y,t) * [1+Zo(x,y,s)/h(x,y)]

Zo(x,y,s) = hc * s + [h(x,y) - hc] * C(s)

Vtransform = 2

new transformation

z(x,y,s,t) = zeta(x,y,t) + [zeta(x,y,t) + h(x,y)] * Zo(x,y,s)

Zo(x,y,s) = [hc * s(k)+h(x,y) * C(k)] / [hc + h(x,y)]

Vstretching:

Vertical stretching function (integer):

Vstretching = 1	original (Song and Haidvogel, 1994)
Vstretching = 2	A. Shchepetkin (UCLA-ROMS, 2005)
Vstretching = 3	R. Geyer BBL refinement
Vstretching = 4	A. Shchepetkin (UCLA-ROMS, 2010)

theta_s:	S-coordinate surface control parameter (scalar)
theta_b:	S-coordinate bottom control parameter (scalar)
hc:	Width (meter) of surface or bottom boundary layer in which higher vertical resolution is required during stretching (scalar)
N:	Number of vertical levels (scalar)
igrid:	Staggered grid C-type (integer):

igrid=1	density points
igrid=2	stream-function points
igrid=3	u-velocity points
igrid=4	v-velocity points
igrid=5	w-velocity points

h:	Bottom depth at RHO-points, h(1:L+1,1:M+1) (2D array; meter; positive)
zeta:	Free-surface at RHO-points, zeta(1:L+1,1:M+1) (2D array; meter; optional)
report:	Switch to report detailed information (logical; optional; default false)

On Output:

z:	Depths (3D array; meter; negative)

stretching.m

Given the vertical terrain-following vertical stretching parameters, this routine computes the vertical stretching function used in ROMS vertical coordinate transformation. Check this page for details.

[s, C] = stretching  (Vstretching, theta_s, theta_b, hc, N, kgrid, report)

On Input:

Vstretching:   Vertical stretching function (integer):

Vstretching = 1,   original (Song and Haidvogel, 1994)

Vstretching = 2,   A. Shchepetkin (UCLA-ROMS, 2005)

Vstretching = 3,   R. Geyer BBL refinement

Vstretching = 4,   A. Shchepetkin (UCLA-ROMS, 2010)

theta_s:   S-coordinate surface control parameter (scalar)

theta_b:   S-coordinate bottom control parameter (scalar)

hc:   Width (meter) of surface or bottom boundary layer in which higher vertical resolution is required during stretching (scalar)

N:   Number of vertical levels (scalar)

kgrid:   Depth grid type flag:

kgrid=0,   stretching at ρ-points

kgrid=1,   stretching at w-points

report:   Switch to report detailed information (logical; optional; default false)

On Output:

s:   S-coordinate independent variable, [-1 <= s <= 0] at vertical ρ- or w-points (vector)

C:   Nondimensional, monotonic, vertical stretching function, C(s), [-1 <= C(s) <= 0] (1D array)

uv_barotropic.m

Computes vertically integrated (barotropic) velocity components for ROMS full grid or boundary edges.

[ubar, vbar] = uv_barotropic  (u, v, Hz, boundary)

On Input:

u:   U-component velocity (array or structure, u-points)

v:   V-component velocity (array or structure, v-points)

Hz:   Vertical level thicknesses (meter) at ρ-points (3D array)

boundary:   Open boundary switch (1D array, optional):

boundary(1),   Process western boundary

boundary(2),   Process eastern boundary

boundary(3),   Process southern boundary

boundary(4),   Process northern boundary

On Output:

ubar:   Vertically integrated u-velocity (array or structure)

vbar:   Vertically integrated v-velocity (array or structure)