Difference between revisions of "Matlab Processing Scripts"

From WikiROMS
Jump to navigationJump to search
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div class="title">Matlab Processing Scripts for Nesting</div> __TOC__
<div class="title">Matlab: Processing Scripts for Nesting</div>
 
<!-- Edit Template:Nested_Grids_TOC to modify this Table of Contents-->
<div style="float: left;margin: 0 20px 0 0;">{{Nested Grids TOC}}</div>__TOC__
 
<div style="clear: both"></div>


The Matlab processing scripts for nesting applications are divided in four categories:
The Matlab processing scripts for nesting applications are divided in four categories:
Line 5: Line 10:
* Scripts to aid in the building of nested grids and associated NetCDF files,
* Scripts to aid in the building of nested grids and associated NetCDF files,
* Scripts to process contact regions and contact points and build its associated NetCDF file,
* Scripts to process contact regions and contact points and build its associated NetCDF file,
* Scripts to process initial conditions data and NetCDF files, and
* Scripts to process initial conditions, boundary conditions, and climatology data and NetCDF files,
* Generic support scripts.
* Generic support scripts, and
* Generic NetCDF data processing scripts.


{{note}} '''Notice:''' Starting Matlab version '''2012a''', released on Feb 9, 2012, the '''native''' interface to NetCDF is the preferred method for processing NetCDF data in the scripts distributed in the ROMS repository '''matlab''': <span class="red"><nowiki>https://www.myroms.org/svn/src/matlab</nowiki></span>. The '''native''' interface was introduced in Matlab version '''2008b''' for NetCDF-3 type files.  The NetCDF-4 support started in version '''2010b'''.  The support for HDF5 files was completed in version '''2011a'''.  The OpenDAP support began in version '''2012a'''.  If your Matlab version is older than 2008b, we highly recommend to update to the newest version.  However, in the basic generic scripts we have switches for older versions to activate either the '''MEXNC''' interface for standard NetCDF files and the '''SNCTOOLS''' interface to process NetCDF files on an OpenDAP server.
{{note}} '''Notice:''' Starting Matlab version '''2012a''', released on Feb 9, 2012, the '''native''' interface to NetCDF is the preferred method for processing NetCDF data in the scripts distributed in the ROMS repository '''matlab''': <span class="red"><nowiki>https://www.myroms.org/svn/src/matlab</nowiki></span>. The '''native''' interface was introduced in Matlab version '''2008b''' for NetCDF-3 type files.  The NetCDF-4 support started in version '''2010b'''.  The support for HDF5 files was completed in version '''2011a'''.  The OpenDAP support began in version '''2012a'''.  If your Matlab version is older than 2008b, we highly recommend to update to the newest version.  However, in the basic generic scripts we have switches for older versions to activate either the '''MEXNC''' interface for standard NetCDF files and the '''SNCTOOLS''' interface to process NetCDF files on an OpenDAP server.


{{warning}} '''Caution:''' The ROMS Grid structure used in all the scripts described here is the one returned from by the script <span class="blue">get_roms_grid.m</span>.
{{warning}} '''Caution:''' The ROMS Grid structure used in all the scripts described here is the one returned by the script [[Grid_Processing_Scripts#get_roms_grid|get_roms_grid.m]].


==Nested Grid Generation Scripts==
==Nested Grid Generation Scripts==
Line 17: Line 23:


Two strategies are possible when configuring nested grids for a particular application:
Two strategies are possible when configuring nested grids for a particular application:
#Build an intermediate large coarse resolution grid and extract the composite and/or refinement grids from it using the functions dicussed below. The disadvantage of this approach is that we need work independently each grid for adjustments in the land/sea masking, target smoothed bathymetry, and matching domain volumes.  Additionally, the finer resolution grids bathymetry can be under- or over-estimated due to the original coarser bathymetry.  There is a linear definition of topographic features that are unresolved in the finer grids.
#Build an intermediate large coarse resolution grid and extract the composite and/or refinement grids from it using the functions discussed below. The disadvantage of this approach is that we need to work independently on each grid for adjustments in the land/sea masking, target smoothed bathymetry, and matching domain volumes.  Additionally, the finer resolution grids bathymetry can be under- or over-estimated due to the original coarser bathymetry.  There is a linear definition of topographic features that are unresolved in the finer grids.
#Build an intermediate large very fine resolution grid, work on the desired land/sea masking, and target smoothed bathymetry. The intermediate grid must resolve the smaller resolution desired for a particular application. Then, use the scripts described below to extract the composite and/or refinement grids.  We think that this strategy is advantageous in all aspects.  However, it is cumbersome because we are dealing with a large grid. The land/sea masking maybe tedious.  Anyway, the function [[landsea.m]] can be used to automatize the land/sea masking , but it still needs some hand editing using [[editmask.m]].
#Build an intermediate large very fine resolution grid, work on the desired land/sea masking, and target smoothed bathymetry. The intermediate grid must resolve the smaller resolution desired for a particular application. Then, use the scripts described below to extract the composite and/or refinement grids.  We think that this strategy is advantageous in all aspects.  However, it is cumbersome because we are dealing with a large grid. The land/sea masking maybe tedious.  Anyway, the function [[Land_Sea_Masking_Scripts#landsea|landsea.m]] can be used to automate the land/sea masking, but it still needs some hand editing using [[Land_Sea_Masking_Scripts#editmask|editmask.m]].


The main scripts to carry this tasks are located in the '''matlab/grid''' sub-directory:
The main scripts to carry this tasks are located in the '''matlab/grid''' sub-directory:


;<span id="c_grid"></span><span class="blue">c_grid.m</span>
{{#lst:Grid_Processing_Scripts|c_grid.m}}
:Creates a new ROMS grid NetCDF file or modifies a existing ROMS grid NetCDF file.<br />
{{#lst:Grid_Processing_Scripts|coarse2fine.m}}
::<span class="green">status</span> = <span class="red">c_grid</span> &nbsp;(<span class="green">Lp</span>,<span class="green">Mp</span>, <span class="green">Gname</span>, <span class="green">NewFile</span>, <span class="green">spherical</span>)
{{#lst:Grid_Processing_Scripts|fine2coarse.m}}
:'''On Input:'''
{{#lst:Grid_Processing_Scripts|grid_extract.m}}
::<span class="green">Lp</span>: &nbsp; Number of &rho;-point in the &xi;-direction
{{#lst:Utility_Scripts|sample_grid.m}}
::<span class="green">Mp</span>: &nbsp; Number of &rho;-point in the &eta;-direction
 
::<span class="green">Gname</span>: &nbsp; Grid NetCDF file name (string)
 
::<span class="green">NewFile</span>: &nbsp; Switch to create a new file (logical, optional, default false)
==Contact Regions and Contact Points Scripts==
::<span class="green">spherical</span>: &nbsp; Spherical grid switch (logical, optional, default true)
:'''On Ouput:'''
::<span class="green">status</span>: &nbsp; Error flag


;<span id="coarse2fine"></span><span class="blue">coarse2fine</span>
These functions process the contact points for each contact region. It is an important step in configuring ROMS nesting applications. The objective is to create the contact points NetCDF file to be read by ROMS.  These functions are generic and have been tested extensively.  However, we recommend that users analyze the data in the NetCDF file and activate the plotting switch to examine the contact points.  The plot maybe very dense when the connectivity involves a lot of files.  We need to zoom the plotting frames until they are readable and think carefully. A expertise in ROMS is required to analyze the plots.
:Given a coarse resolution ROMS Grid NetCDF file (<span class="green">Ginp</span>), this function creates a finer resolution grid in the region specified by the coarser grid coordinates (<span class="green">Imin</span>, <span class="green">Jmin</span>) and (<span class="green">Imax</span>, <span class="green">Jmax</span>). Notice that (<span class="green">Imin</span>, <span class="green">Jmin</span>), and (<span class="green">Imax</span>, <span class="green">Jmax</span>) indices are in terms of the &psi;-points because it actually define the physical boundaries of the refined grid. The grid refinement coefficient is specified with <span class="green">Gfactor</span>. <br />
::<span class="green">F</span> = <span class="red">coarse2fine</span> &nbsp;(<span class="green">Ginp</span>,<span class="green">Gout</span>, <span class="green">Gfactor</span>, <span class="green">Imin</span>, <span class="green">Imax</span>, <span class="green">Jmin</span>, <span class="green">Jmax</span>)
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input coarser Grid NetCDF file name (string)
::<span class="green">Gout</span>: &nbsp; Output finer Grid NetCDF file name (string)
::<span class="green">Gfactor</span>: &nbsp; Grid refinement factor (3,5,7,9,11,13,15,...)
::<span class="green">Imin</span>: &nbsp; Coarse grid lower-left  I-coordinate (&psi;-point)
::<span class="green">Imax</span>: &nbsp; Coarse grid upper-right I-coordinate (&psi;-point)
::<span class="green">Jmin</span>: &nbsp; Coarse grid lower-left  J-coordinate (&psi;-point)
::<span class="green">Jmax</span>: &nbsp; Coarse grid upper-right J-coordinate (&psi;-point)
:'''On Ouput:'''
::<span class="green">F</span>: &nbsp; Fine resolution grid structure (struct array)


;<span id="fine2coarse"></span><span class="blue">fine2coarse</span>
These function use the excellent Matlab function <span class="blue">inpolygon</span> to determine if a point (X,Y) is inside a grid perimeter, on the grid perimeter edges, or outside the grid perimeter. In Matlab, we need to account for the zero shift of ROMS indices. The logic is tricky and not that intuitive. We need to take into account ROMS (I,J) indices and fractional coordinates (<math>\xi</math>, <math>\eta</math>).  For example, in Matlab the Imin and Jmin indices correspond to fractional coordinates:
:Given a finer resolution ROMS Grid NetCDF file (<span class="green">Ginp</span>), this function creates a coarser resolution grid in the region specified by the finer grid coordinates (<span class="green">Imin</span>, <span class="green">Jmin</span>) and (<span class="green">Imax</span>, <span class="green">Jmax</span>). Notice that (<span class="green">Imin</span>, <span class="green">Jmin</span>), and (<span class="green">Imax</span>, <span class="green">Jmax</span>) indices are in terms of the &psi;-points because it actually define the physical boundaries of the coarser grid. The grid coarseness coefficient is specified with <span class="green">Gfactor</span>. <br />
::<span class="green">C</span> = <span class="red">fine2coarse</span> &nbsp;(<span class="green">Ginp</span>,<span class="green">Gout</span>, <span class="green">Gfactor</span>, <span class="green">Imin</span>, <span class="green">Imax</span>, <span class="green">Jmin</span>, <span class="green">Jmax</span>)
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input finer Grid NetCDF file name (string)
::<span class="green">Gout</span>: &nbsp; Output coarser Grid NetCDF file name (string)
::<span class="green">Gfactor</span>: &nbsp; Grid coarseness factor (3,5,7,9,11,13,15,...)
::<span class="green">Imin</span>: &nbsp; Finer grid lower-left  I-coordinate (&psi;-point)
::<span class="green">Imax</span>: &nbsp; Finer grid upper-right I-coordinate (&psi;-point)
::<span class="green">Jmin</span>: &nbsp; Finer grid lower-left  J-coordinate (&psi;-point)
::<span class="green">Jmax</span>: &nbsp; Finer grid upper-right J-coordinate (&psi;-point)
:'''On Ouput:'''
::<span class="green">C</span>: &nbsp; Coarser resolution grid structure (struct array)


;<span id="grid_extract"></span><span class="blue">grid_extract</span>
<math display="block">\xi_{\psi}(I_{\psi}) = \xi_{\rho}(I_{\rho})</math>
:Given a larger ROMS Grid NetCDF file (<span class="green">Ginp</span>), this function extracts and creates a sub-domain Grid NetCDF file (<span class="green">Gout</span>) for the sampled region in terms of the larger grid coordinates (<span class="green">Imin</span>, <span class="green">Jmin</span>) and (<span class="green">Imax</span>, <span class="green">Jmax</span>). Notice that the (<span class="green">Imin</span>, <span class="green">Jmin</span>), and (<span class="green">Imax</span>, <span class="green">Jmax</span>) indices are located at &psi;-points. They actually define the physical boundaries of the smaller sub-domain grid.<br />
<math display="block">\eta_{\psi}(J_{\psi}) = \eta_{\rho}(J_{\rho})</math>
::<span class="green">S</span> = <span class="red">grid_extract</span> &nbsp;(<span class="green">Ginp</span>,<span class="green">Gout</span>,  <span class="green">Imin</span>, <span class="green">Imax</span>, <span class="green">Jmin</span>, <span class="green">Jmax</span>)
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input coaser Grid NetCDF file name (string) or an existing grid structure (struct array)
::<span class="green">Gout</span>: &nbsp; Output smaller Grid NetCDF file name (string)
::<span class="green">Gfactor</span>: &nbsp; Grid refinement factor (3,5,7,9,11,13,15,...)
::<span class="green">Imin</span>: &nbsp; Larger grid lower-left  I-coordinate (&psi;-point)
::<span class="green">Imax</span>: &nbsp; Larger grid upper-right I-coordinate (&psi;-point)
::<span class="green">Jmin</span>: &nbsp; Larger grid lower-left  J-coordinate (&psi;-point)
::<span class="green">Jmax</span>: &nbsp; Larger grid upper-right J-coordinate (&psi;-point)
:'''On Ouput:'''
::<span class="green">S</span>: &nbsp; Smaller grid structure (struct array)


==Contact Regions and Contact Points Scripts==
since <math>I_{\psi} = I_{\rho}</math> and <math>J_{\psi} = J_{\rho}</math>.  The number of points in each direction is <math>L_{\rho} = L_{\psi}+1</math> and <math>M_{\rho} = M_{\psi}+1</math>, respectively.  Therefore, the zero shift of <math>\rho</math>-points indices is done at the end.
 
The main scripts to carry this tasks are located in the '''matlab/grid''' sub-directory:
 
{{#lst:Grid_Processing_Scripts|c_contact.m}}
{{#lst:Grid_Processing_Scripts|contact.m}}
{{#lst:Grid_Processing_Scripts|disp_contact.m}}
{{#lst:Grid_Processing_Scripts|grid_connections.m}}
{{#lst:Grid_Processing_Scripts|grid_perimeter.m}}
{{#lst:Grid_Processing_Scripts|plot_contact.m}}
{{#lst:Grid_Processing_Scripts|read_contact.m}}
{{#lst:Grid_Processing_Scripts|write_contact.m}}
 
 
==State Variables Preparation Scripts==
 
The following scripts may be used to prepare initial conditions, lateral boundary conditions, and climatology data and create their associated NetCDF files.  The <span class="blue">TriScatteredInterp</span> function is used when interpolation is required using the <span class="red">natural</span>, <span class="red">linear</span>, or <span class="red">nearest</span> method.  In some applications, the interpolation may yield '''NaN''' values.  If this is the case, an additional interpolation with nearest-neighbor interpolation (<span class="red">nearest</span> method) is carried out to remove such '''NaN''' values on the outlier points. 
 
These scripts are located in either in the '''matlab/initial''' or '''matlab/boundary''' sub-directories:
 
{{#lst:Initial_Conditions_and_Climatology_Scripts|roms2roms.m}}
{{#lst:Lateral_Boundary_Conditions_Scripts|obc_roms2roms.m}}


==Initial Condition Scripts==


==Support Scripts==
==Support Scripts==
There are several generic support scripts that are used to process ROMS nested grids, initial conditions, boundary conditions, climatology, and land/sea masking. Some of the scripts involve the computation of vertical coordinate transformation and we highly encourage everyone to use them for accuracy with ROMS numerical kernel. <br />
These scripts are located in either in the '''matlab/grid''' or '''matlab/utility''' sub-directories:
{{#lst:Utility_Scripts|depths.m}}
{{#lst:Grid_Processing_Scripts|flip_grid.m}}
{{#lst:Utility_Scripts|gcircle.m}}
{{#lst:Grid_Processing_Scripts|get_roms_grid.m}}
{{#lst:Grid_Processing_Scripts|grid_metrics.m}}
{{#lst:Utility_Scripts|set_depth.m}}
{{#lst:Utility_Scripts|stretching.m}}
{{#lst:Grid_Processing_Scripts|uniform_grid.m}}
{{#lst:Utility_Scripts|uv_barotroic.m}}
==NetCDF Data Processing Scripts==
The following NetCDF interface scripts, located in the '''matlab/netcdf''' sub-directory, are used when processing nested grids to read and write data:
{{#lst:NetCDF_Data_Processing_Scripts|nc_attadd.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_cretate.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_check.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_inq.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_interface.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_read.m}}
{{#lst:NetCDF_Data_Processing_Scripts|nc_write.m}}

Latest revision as of 13:50, 4 August 2015

Matlab: Processing Scripts for Nesting
Nested Grids Menu
  1. Introduction
  2. Matlab Processing Scripts

The Matlab processing scripts for nesting applications are divided in four categories:

  • Scripts to aid in the building of nested grids and associated NetCDF files,
  • Scripts to process contact regions and contact points and build its associated NetCDF file,
  • Scripts to process initial conditions, boundary conditions, and climatology data and NetCDF files,
  • Generic support scripts, and
  • Generic NetCDF data processing scripts.

Note Notice: Starting Matlab version 2012a, released on Feb 9, 2012, the native interface to NetCDF is the preferred method for processing NetCDF data in the scripts distributed in the ROMS repository matlab: https://www.myroms.org/svn/src/matlab. The native interface was introduced in Matlab version 2008b for NetCDF-3 type files. The NetCDF-4 support started in version 2010b. The support for HDF5 files was completed in version 2011a. The OpenDAP support began in version 2012a. If your Matlab version is older than 2008b, we highly recommend to update to the newest version. However, in the basic generic scripts we have switches for older versions to activate either the MEXNC interface for standard NetCDF files and the SNCTOOLS interface to process NetCDF files on an OpenDAP server.

Warning Caution: The ROMS Grid structure used in all the scripts described here is the one returned by the script get_roms_grid.m.

Nested Grid Generation Scripts

Currently, it is not our intention to develop a fancy GUI tool to prepare ROMS nested grids. The capability of ROMS nesting is unique and requires special tools since we support mosaics, composite, and refinement grids in a variety of nested classes. Perhaps in the future an expert user will help us develop this GUI. However, the scripts described here are basic and fundamental. They can be used in the future to build a fancier interface.

Two strategies are possible when configuring nested grids for a particular application:

  1. Build an intermediate large coarse resolution grid and extract the composite and/or refinement grids from it using the functions discussed below. The disadvantage of this approach is that we need to work independently on each grid for adjustments in the land/sea masking, target smoothed bathymetry, and matching domain volumes. Additionally, the finer resolution grids bathymetry can be under- or over-estimated due to the original coarser bathymetry. There is a linear definition of topographic features that are unresolved in the finer grids.
  2. Build an intermediate large very fine resolution grid, work on the desired land/sea masking, and target smoothed bathymetry. The intermediate grid must resolve the smaller resolution desired for a particular application. Then, use the scripts described below to extract the composite and/or refinement grids. We think that this strategy is advantageous in all aspects. However, it is cumbersome because we are dealing with a large grid. The land/sea masking maybe tedious. Anyway, the function landsea.m can be used to automate the land/sea masking, but it still needs some hand editing using editmask.m.

The main scripts to carry this tasks are located in the matlab/grid sub-directory:

c_grid.m
Creates a new ROMS grid NetCDF file or modifies an existing ROMS grid NetCDF file.
status = c_grid  (Lp, Mp, Gname, NewFile, spherical)
On Input:
Lp: Number of ρ-points in the ξ-direction
Mp: Number of ρ-points in the η-direction
Gname: Grid NetCDF file name (string)
NewFile: Switch to create a new file (logical, optional, default false)
spherical: Spherical grid switch (logical, optional, default true)
On Output:
status: Error flag
coarse2fine
Given a coarse resolution ROMS Grid NetCDF file (Ginp), this function creates a finer resolution grid in the region specified by the coarser grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that (Imin, Jmin), and (Imax, Jmax) indices are in terms of the ψ-points because it actually defines the physical boundaries of the refined grid. The grid refinement coefficient is specified with Gfactor.
F = coarse2fine  (Ginp, Gout, Gfactor, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input coarser Grid NetCDF file name (string)
Gout: Output finer Grid NetCDF file name (string)
Gfactor: Grid refinement factor (3,5,7,9,11,13,15,...)
Imin: Coarse grid lower-left I-coordinate (ψ-point)
Imax: Coarse grid upper-right I-coordinate (ψ-point)
Jmin: Coarse grid lower-left J-coordinate (ψ-point)
Jmax: Coarse grid upper-right J-coordinate (ψ-point)
On Output:
F: Fine resolution grid structure (struct array)
fine2coarse
Given a finer resolution ROMS Grid NetCDF file (Ginp), this function creates a coarser resolution grid in the region specified by the finer grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that (Imin, Jmin), and (Imax, Jmax) indices are in terms of the ψ-points because it actually defines the physical boundaries of the coarser grid. The grid coarseness coefficient is specified with Gfactor.
C = fine2coarse  (Ginp, Gout, Gfactor, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input finer Grid NetCDF file name (string)
Gout: Output coarser Grid NetCDF file name (string)
Gfactor: Grid coarseness factor (3,5,7,9,11,13,15,...)
Imin: Finer grid lower-left I-coordinate (ψ-point)
Imax: Finer grid upper-right I-coordinate (ψ-point)
Jmin: Finer grid lower-left J-coordinate (ψ-point)
Jmax: Finer grid upper-right J-coordinate (ψ-point)
On Output:
C: Coarser resolution grid structure (struct array)
grid_extract.m
Given a larger ROMS Grid NetCDF file (Ginp), this function extracts and creates a sub-domain Grid NetCDF file (Gout) for the sampled region in terms of the larger grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that the (Imin, Jmin), and (Imax, Jmax) indices are located at ψ-points. They actually define the physical boundaries of the smaller sub-domain grid.
S = grid_extract  (Ginp, Gout, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input coaser Grid NetCDF file name (string) or an existing grid structure (struct array)
Gout: Output smaller Grid NetCDF file name (string)
Imin: Larger grid lower-left I-coordinate (ψ-point)
Imax: Larger grid upper-right I-coordinate (ψ-point)
Jmin: Larger grid lower-left J-coordinate (ψ-point)
Jmax: Larger grid upper-right J-coordinate (ψ-point)
On Output:
S: Smaller grid structure (struct array)
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


Contact Regions and Contact Points Scripts

These functions process the contact points for each contact region. It is an important step in configuring ROMS nesting applications. The objective is to create the contact points NetCDF file to be read by ROMS. These functions are generic and have been tested extensively. However, we recommend that users analyze the data in the NetCDF file and activate the plotting switch to examine the contact points. The plot maybe very dense when the connectivity involves a lot of files. We need to zoom the plotting frames until they are readable and think carefully. A expertise in ROMS is required to analyze the plots.

These function use the excellent Matlab function inpolygon to determine if a point (X,Y) is inside a grid perimeter, on the grid perimeter edges, or outside the grid perimeter. In Matlab, we need to account for the zero shift of ROMS indices. The logic is tricky and not that intuitive. We need to take into account ROMS (I,J) indices and fractional coordinates (, ). For example, in Matlab the Imin and Jmin indices correspond to fractional coordinates:

since and . The number of points in each direction is and , respectively. Therefore, the zero shift of -points indices is done at the end.

The main scripts to carry this tasks are located in the matlab/grid sub-directory:

c_contact.m
Creates a new contact points NetCDF file for a ROMS nesting application. The contact point data is written elsewhere using write_contact.m. If the Ndatum argument is not provided, the datum dimension is unlimited.
c_contact  (ncname, spherical, Ngrids, Ndatum)
On Input:
ncname: Output contact points NetCDF file name (string)
spherical: Spherical grid switch (logical)
Ngrids: Number of nested grids
Ndatum: Total number of contact points (optional)
c_grid.m
Creates a new ROMS grid NetCDF file or modifies an existing ROMS grid NetCDF file.
status = c_grid  (Lp, Mp, Gname, NewFile, spherical)
On Input:
Lp: Number of ρ-points in the ξ-direction
Mp: Number of ρ-points in the η-direction
Gname: Grid NetCDF file name (string)
NewFile: Switch to create a new file (logical, optional, default false)
spherical: Spherical grid switch (logical, optional, default true)
On Output:
status: Error flag
coarse2fine
Given a coarse resolution ROMS Grid NetCDF file (Ginp), this function creates a finer resolution grid in the region specified by the coarser grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that (Imin, Jmin), and (Imax, Jmax) indices are in terms of the ψ-points because it actually defines the physical boundaries of the refined grid. The grid refinement coefficient is specified with Gfactor.
F = coarse2fine  (Ginp, Gout, Gfactor, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input coarser Grid NetCDF file name (string)
Gout: Output finer Grid NetCDF file name (string)
Gfactor: Grid refinement factor (3,5,7,9,11,13,15,...)
Imin: Coarse grid lower-left I-coordinate (ψ-point)
Imax: Coarse grid upper-right I-coordinate (ψ-point)
Jmin: Coarse grid lower-left J-coordinate (ψ-point)
Jmax: Coarse grid upper-right J-coordinate (ψ-point)
On Output:
F: Fine resolution grid structure (struct array)


contact.m
Sets ROMS nested grid contact points for each contact region. The order of the nested grid file names in the input cell array (Gnames) is important. Set the file names in the order of nesting layers and time-stepping in ROMS. The MaskInterp switch is only relevant when processing the contact region of a refinement grid. The setting of land/sea masking in the contact region is critical. Usually, it is better to linearly interpolate the finer grid ψ- u-, and v-masks from coarser grid than recomputing via uvp_masks. The recomputed masks may be one point smaller or larger. Use the MaskInterp switch to either interpolate (true) or use uvp_masks (false). Recall that we are not modifying the original refined grid mask, just computing the mask in the contact region adjacent to the finer grid from the coarser grid mask. This is only relevant when there are land/sea masking features in any of the refinement grid physical boundaries. If so, the user just needs to experiment with MaskInterp and edit such points during post-processing.
[S, G] = contact  (Gnames, Cname, Lmask, MaskInterp, Lplot)
On Input:
Gnames: Input Grid NetCDF full path file names (cell array)
Cname: Output contact points NetCDF file name (string)
Lmask: Switch to remove contact points over land (logical, optional, default false)
MaskInterp: Switch to interpolate ψ-, u- and v-masks (true) or compute from interpolated ρ-mask (false). The default is false (logical, optional).
Lplot: Switch to plot various contact points figures (logical, optional, default false)
On Output:
S: Nested grids contact points structure (struct array)
G: Nested grids structure (1 x Ngrids struct array)


disp_contact.m
Prints the nested grids contact points unique values for each Contact Region. The contact points structure is rich and this simple function facilitates summarizing the contact points values.
disp_contact  (S)
On Input:
ncname: Contact points structure(struct array)


fine2coarse
Given a finer resolution ROMS Grid NetCDF file (Ginp), this function creates a coarser resolution grid in the region specified by the finer grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that (Imin, Jmin), and (Imax, Jmax) indices are in terms of the ψ-points because it actually defines the physical boundaries of the coarser grid. The grid coarseness coefficient is specified with Gfactor.
C = fine2coarse  (Ginp, Gout, Gfactor, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input finer Grid NetCDF file name (string)
Gout: Output coarser Grid NetCDF file name (string)
Gfactor: Grid coarseness factor (3,5,7,9,11,13,15,...)
Imin: Finer grid lower-left I-coordinate (ψ-point)
Imax: Finer grid upper-right I-coordinate (ψ-point)
Jmin: Finer grid lower-left J-coordinate (ψ-point)
Jmax: Finer grid upper-right J-coordinate (ψ-point)
On Output:
C: Coarser resolution grid structure (struct array)


flip_grid.m
Given a ROMS Grid NetCDF file (Ginp), this function creates a new Grid NetCDF file (Gout) with the flipped dimensions, coordinates, and variables.
G = flip_grid  (Ginp, Gout)
On Input:
Ginp: Input ROMS grid NetCDF file name (string)
Gout: Output flipped ROMS grid NetCDF file name (string)
On Output:
Sinp: Flipped Grid structure (struct array)


get_roms_grid.m
Builds or updates a ROMS Grid structure (Gout) containing all the variables associated with the application's horizontal and vertical grids.
Gout = get_roms_grid  (Ginp)
Gout = get_roms_grid  (Ginp, Sinp)
Gout = get_roms_grid  (Ginp, Sinp, Tindex)
Gout = get_roms_grid  (Ginp, Tindex)
On Input:
Ginp: Input ROMS Grid/History NetCDF file/URL name containing all grid variables (string) or an existing grid structure to which the vertical coordinates are added or updated (struct array)
Sinp: ROMS output NetCDF file/URL name from which the vertical coordinates can be determined (string) or a structure containing vertical coordinates stretching parameters (struct array):
Sinp.N number of vertical levels
Sinp.Vtransform vertical transformation equation
Sinp.Vstretching vertical stretching function
Sinp.theta_s surface control parameter
Sinp.theta_b bottom control parameter
Sinp.Tcline surface/bottom stretching width
Sinp.hc stretching width used in ROMS
Tindex Time record index used to process free-surface in the vertical coordinates (scalar; optional):
If Tindex is omitted, zero or empty, it assumes that zeta = 0 yielding unperturbed depths.
Otherwise, the free-surface record in input NetCDF is processed. The free-surface is read from either Ginp (if history file) or Sinp (if provided and history file).
On Output:
Gout: ROMS grid variables structure (struct array)


grid_connections.m
Appends the nested grid connectivity fields between donor and receiver grids for each contact region to the nested grids structure, Sinp.
S = grid_connections  (G, Sinp)
On Input:
G: Nested grids information structure (1 x Ngrids struct array)
Sinp: Nested grids contact points structure (struct array)
On Output:
S: Updated nested grids contact points structure (struct array)


grid_extract.m
Given a larger ROMS Grid NetCDF file (Ginp), this function extracts and creates a sub-domain Grid NetCDF file (Gout) for the sampled region in terms of the larger grid coordinates (Imin, Jmin) and (Imax, Jmax). Notice that the (Imin, Jmin), and (Imax, Jmax) indices are located at ψ-points. They actually define the physical boundaries of the smaller sub-domain grid.
S = grid_extract  (Ginp, Gout, Imin, Imax, Jmin, Jmax)
On Input:
Ginp: Input coaser Grid NetCDF file name (string) or an existing grid structure (struct array)
Gout: Output smaller Grid NetCDF file name (string)
Imin: Larger grid lower-left I-coordinate (ψ-point)
Imax: Larger grid upper-right I-coordinate (ψ-point)
Jmin: Larger grid lower-left J-coordinate (ψ-point)
Jmax: Larger grid upper-right J-coordinate (ψ-point)
On Output:
S: Smaller grid structure (struct array)


grid_metrics.m
Computes horizontal grid spacing metrics from Grid NetCDF file or Grid structure G.
[pm, pn, dndx, dmde] = grid_metrics  (G, GreatCircle)
On Input:
G: Either a ROMS grid NetCDF file name (string) or ROMS grid structure (struct array)
GreatCircle: Switch indicating how to compute the grid distance (logical): true Great-circle distance or false Cartesian distance
On Output:
pm: Curvilinear coordinate metric in the ξ-direction (1/meters; dx = 1/pm)
pn: Curvilinear coordinate metric in the η-direction (1/meters; dy = 1/pn)
dndx: ξ-derivative of inverse metric factor pn, d(1/pn)/d(ξ) (meter)
dmde: η-derivative of inverse metric factor pm, d(1/pm)/d(η) (meter)


grid_perimeter.m
Creates a structure containing information about nested grids perimeters, boundary edges, and other information parameters.
S = grid_perimeter  (Gnames)
On Input:
Gnames: Input Grid NetCDF full path file names (cell array)
On Output:
Sinp: Beginning of contact points structure (struct array)


plot_contact.m
Plots various figures of contact points for each contact region.
plot_contact  (G, S)
On Input:
G: Nested grids structure (1 x Ngrids struct array)
S: Nested grids contact points structure (struct array)


read_contact.m
Reads in the nested grids contact points NetCDF file and loads data into a structure.
[S, G] = read_contact  (ncname)
On Input:
ncname: Nested grids contact points NetCDF file name (string)
On Output:
S: Nested grids contact points structure (struct array)
G: Nested grids structure (1 x Ngrids struct array)


uniform_grid.m
Given the grid spacing (dx, dy) and number of ψ-points (L, M) in the X- and Y-direction, this function sets the ROMS grid Cartesian coordinates and metrics.
G = uniform_grid  (dx, dy, L, M)
On Input:
dx: Grid spacing in the X-direction (meters; scalar)
dy: Grid spacing in the Y-direction (meters; scalar)
L: Number of ψ-points in the X-direction
M: Number of ψ-points in the Y-direction
On Output:
G: Uniform grid coordinates and metrics (struct array):
G.x_psi X-coordinates at ψ-points (meters)
G.y_psi Y-coordinates at ψ-points (meters)
G.x_rho X-coordinates at ρ-points (meters)
G.y_rho Y-coordinates at ρ-points (meters)
G.x_u X-coordinates at u-points (meters)
G.y_u Y-coordinates at u-points (meters)
G.x_v X-coordinates at v-points (meters)
G.y_v Y-coordinates at v-points (meters)
G.pm X-coordinates metric m (1/meters, 1/dx)
G.pn Y-coordinates metric n (1/meters, 1/dy)
G.dndx Inverse metric, d(1/pn)/d(ξ) (meter)
G.dmde Inverse metric, d(1/pm)/d(η) (meter)


write_contact.m
Writes out the nested grids contact points data generated by contact.m or read_contact.m into a NetCDF.
write_contact   (ncname, S, Lcreate)
On Input:
ncname: Nested grids contact points NetCDF file name (string)
S: Nested grids contact points structure (struct array)
Lcreate: Switch to create a new NetCDF file (logical, optional, default true)
contact.m
Sets ROMS nested grid contact points for each contact region. The order of the nested grid file names in the input cell array (Gnames) is important. Set the file names in the order of nesting layers and time-stepping in ROMS. The MaskInterp switch is only relevant when processing the contact region of a refinement grid. The setting of land/sea masking in the contact region is critical. Usually, it is better to linearly interpolate the finer grid ψ- u-, and v-masks from coarser grid than recomputing via uvp_masks. The recomputed masks may be one point smaller or larger. Use the MaskInterp switch to either interpolate (true) or use uvp_masks (false). Recall that we are not modifying the original refined grid mask, just computing the mask in the contact region adjacent to the finer grid from the coarser grid mask. This is only relevant when there are land/sea masking features in any of the refinement grid physical boundaries. If so, the user just needs to experiment with MaskInterp and edit such points during post-processing.
[S, G] = contact  (Gnames, Cname, Lmask, MaskInterp, Lplot)
On Input:
Gnames: Input Grid NetCDF full path file names (cell array)
Cname: Output contact points NetCDF file name (string)
Lmask: Switch to remove contact points over land (logical, optional, default false)
MaskInterp: Switch to interpolate ψ-, u- and v-masks (true) or compute from interpolated ρ-mask (false). The default is false (logical, optional).
Lplot: Switch to plot various contact points figures (logical, optional, default false)
On Output:
S: Nested grids contact points structure (struct array)
G: Nested grids structure (1 x Ngrids struct array)
disp_contact.m
Prints the nested grids contact points unique values for each Contact Region. The contact points structure is rich and this simple function facilitates summarizing the contact points values.
disp_contact  (S)
On Input:
ncname: Contact points structure(struct array)
grid_connections.m
Appends the nested grid connectivity fields between donor and receiver grids for each contact region to the nested grids structure, Sinp.
S = grid_connections  (G, Sinp)
On Input:
G: Nested grids information structure (1 x Ngrids struct array)
Sinp: Nested grids contact points structure (struct array)
On Output:
S: Updated nested grids contact points structure (struct array)
grid_perimeter.m
Creates a structure containing information about nested grids perimeters, boundary edges, and other information parameters.
S = grid_perimeter  (Gnames)
On Input:
Gnames: Input Grid NetCDF full path file names (cell array)
On Output:
Sinp: Beginning of contact points structure (struct array)
plot_contact.m
Plots various figures of contact points for each contact region.
plot_contact  (G, S)
On Input:
G: Nested grids structure (1 x Ngrids struct array)
S: Nested grids contact points structure (struct array)
read_contact.m
Reads in the nested grids contact points NetCDF file and loads data into a structure.
[S, G] = read_contact  (ncname)
On Input:
ncname: Nested grids contact points NetCDF file name (string)
On Output:
S: Nested grids contact points structure (struct array)
G: Nested grids structure (1 x Ngrids struct array)
write_contact.m
Writes out the nested grids contact points data generated by contact.m or read_contact.m into a NetCDF.
write_contact   (ncname, S, Lcreate)
On Input:
ncname: Nested grids contact points NetCDF file name (string)
S: Nested grids contact points structure (struct array)
Lcreate: Switch to create a new NetCDF file (logical, optional, default true)


State Variables Preparation Scripts

The following scripts may be used to prepare initial conditions, lateral boundary conditions, and climatology data and create their associated NetCDF files. The TriScatteredInterp function is used when interpolation is required using the natural, linear, or nearest method. In some applications, the interpolation may yield NaN values. If this is the case, an additional interpolation with nearest-neighbor interpolation (nearest method) is carried out to remove such NaN values on the outlier points.

These scripts are located in either in the matlab/initial or matlab/boundary sub-directories:

roms2roms.m
Interpolates requested 2D or 3D variable between two ROMS application grids. The receiver grid must be inside of the donor grid. This function is intended for down-scaling or nesting applications. The horizontal/vertical coordinates for the donor and the receiver grids are specified with array structures D and R, which are built elsewhere using the script get_roms_grid.m for efficiency and functionality.
V = roms2roms  (ncname, D, R, Vname, Tindex, Rvector, method, offset, RemoveNaN)
On Input:
ncname: Donor grid NetCDF file name containing variable to process (string)
D: Donor grid structure containing all horizontal and vertical variables (struct array)
R: Receiver grid structure containing all horizontal and vertical variables (struct array)
Vname: Field variable name to process (string)
Tindex: Time record index to process (scalar)
Rvector: Switch to Interpolate U- and V-points variables to RHO-points to facilitate rotation in curvilinear grid applications elsewhere (logical)
method: Interpolation method in TriScatteredInterp (string):
natural natural neighbor interpolation
linear linear interpolation (default)
nearest nearest-neighbor interpolation
offset: Number of extra points to use when sampling the donor grid so it is large enough to contain the receiver grid (default 5)
RemoveNaN: Switch to remove NaN values from the interpolated variable with a second interpolation step using the nearest-neighbor method (default false)
On Output:
V: Interpolated requested 2D or 3D variable
obc_roms2roms.m
Interpolates requested 2D or 3D lateral boundary conditions variables between two ROMS application grids. The receiver grid must be inside of the donor grid. This function is intended for down-scaling or nesting applications. The horizontal/vertical coordinates for the donor and the and receiver grids are specified with array structures D and R, which are built elsewhere using script get_roms_grid.m for efficiency and functionality.
B = obc_roms2roms  (ncname, D, R, VarList, Tindex, boundary, method, offset, RemoveNaN)
On Input:
ncname: Donor grid NetCDF file name containing variables to process (string)
D: Donor grid structure containing all horizontal and vertical variables (struct array)
R: Receiver grid structure containing all horizontal and vertical variables (struct array)
VarList: List of variable names to process (cell array)
Tindex: Time record index to process (scalar)
boundary: Lateral boundary condition switches (logicals) of the grid edges to process (struct array):
boundary.west Western edge
boundary.east Eastern edge
boundary.south Southern edge
boundary.north Northern edge
method: Interpolation method in TriScatteredInterp (string):
'natural' natural neighbor interpolation
'linear' linear interpolation (default)
'nearest' nearest-neighbor interpolation
offset: Number of extra points to use when sampling the donor grid so it is large enough to contain the receiver grid (default 5)
RemoveNaN: Switch to remove NaN values from interpolated variable with a second interpolation step using the nearest-neighbor method (default false)
On Output:
B: Interpolated requested 2D or 3D lateral boundary variables (struct array)


Support Scripts

There are several generic support scripts that are used to process ROMS nested grids, initial conditions, boundary conditions, climatology, and land/sea masking. Some of the scripts involve the computation of vertical coordinate transformation and we highly encourage everyone to use them for accuracy with ROMS numerical kernel.

These scripts are located in either in the matlab/grid or matlab/utility sub-directories:

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)
flip_grid.m
Given a ROMS Grid NetCDF file (Ginp), this function creates a new Grid NetCDF file (Gout) with the flipped dimensions, coordinates, and variables.
G = flip_grid  (Ginp, Gout)
On Input:
Ginp: Input ROMS grid NetCDF file name (string)
Gout: Output flipped ROMS grid NetCDF file name (string)
On Output:
Sinp: Flipped Grid structure (struct array)
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)
get_roms_grid.m
Builds or updates a ROMS Grid structure (Gout) containing all the variables associated with the application's horizontal and vertical grids.
Gout = get_roms_grid  (Ginp)
Gout = get_roms_grid  (Ginp, Sinp)
Gout = get_roms_grid  (Ginp, Sinp, Tindex)
Gout = get_roms_grid  (Ginp, Tindex)
On Input:
Ginp: Input ROMS Grid/History NetCDF file/URL name containing all grid variables (string) or an existing grid structure to which the vertical coordinates are added or updated (struct array)
Sinp: ROMS output NetCDF file/URL name from which the vertical coordinates can be determined (string) or a structure containing vertical coordinates stretching parameters (struct array):
Sinp.N number of vertical levels
Sinp.Vtransform vertical transformation equation
Sinp.Vstretching vertical stretching function
Sinp.theta_s surface control parameter
Sinp.theta_b bottom control parameter
Sinp.Tcline surface/bottom stretching width
Sinp.hc stretching width used in ROMS
Tindex Time record index used to process free-surface in the vertical coordinates (scalar; optional):
If Tindex is omitted, zero or empty, it assumes that zeta = 0 yielding unperturbed depths.
Otherwise, the free-surface record in input NetCDF is processed. The free-surface is read from either Ginp (if history file) or Sinp (if provided and history file).
On Output:
Gout: ROMS grid variables structure (struct array)
grid_metrics.m
Computes horizontal grid spacing metrics from Grid NetCDF file or Grid structure G.
[pm, pn, dndx, dmde] = grid_metrics  (G, GreatCircle)
On Input:
G: Either a ROMS grid NetCDF file name (string) or ROMS grid structure (struct array)
GreatCircle: Switch indicating how to compute the grid distance (logical): true Great-circle distance or false Cartesian distance
On Output:
pm: Curvilinear coordinate metric in the ξ-direction (1/meters; dx = 1/pm)
pn: Curvilinear coordinate metric in the η-direction (1/meters; dy = 1/pn)
dndx: ξ-derivative of inverse metric factor pn, d(1/pn)/d(ξ) (meter)
dmde: η-derivative of inverse metric factor pm, d(1/pm)/d(η) (meter)
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)
uniform_grid.m
Given the grid spacing (dx, dy) and number of ψ-points (L, M) in the X- and Y-direction, this function sets the ROMS grid Cartesian coordinates and metrics.
G = uniform_grid  (dx, dy, L, M)
On Input:
dx: Grid spacing in the X-direction (meters; scalar)
dy: Grid spacing in the Y-direction (meters; scalar)
L: Number of ψ-points in the X-direction
M: Number of ψ-points in the Y-direction
On Output:
G: Uniform grid coordinates and metrics (struct array):
G.x_psi X-coordinates at ψ-points (meters)
G.y_psi Y-coordinates at ψ-points (meters)
G.x_rho X-coordinates at ρ-points (meters)
G.y_rho Y-coordinates at ρ-points (meters)
G.x_u X-coordinates at u-points (meters)
G.y_u Y-coordinates at u-points (meters)
G.x_v X-coordinates at v-points (meters)
G.y_v Y-coordinates at v-points (meters)
G.pm X-coordinates metric m (1/meters, 1/dx)
G.pn Y-coordinates metric n (1/meters, 1/dy)
G.dndx Inverse metric, d(1/pn)/d(ξ) (meter)
G.dmde Inverse metric, d(1/pm)/d(η) (meter)


NetCDF Data Processing Scripts

The following NetCDF interface scripts, located in the matlab/netcdf sub-directory, are used when processing nested grids to read and write data:

nc_attadd.m
Adds or modifies a global or variable attribute in a NetCDF file. If the Vname argument is missing, it is assumed that Aname is a global attribute.
status = nc_attadd  (ncfile, Aname, Avalue, Vname)
On Input:
ncfile: NetCDF file name (string)
Aname: Attribute name (string)
Avalue: Attribute value (numeric or string)
Vname: Variable name (string; optional)
On Output:
status: Error flag
nc_check.m
Checks the information structure returned from calls to nc_inq or native ncinfo for compliance and changes new variable types and attributes. For example, it updates the spherical switch to integer and fixes the land/sea masking attributes for compliance. Notice that this information structure is very convenient to create new NetCDF files having the dimensions and variable schema of and old NetCDF file.
I = nc_check  (Info)
On Input:
Info: NetCDF file information structure (struct array)
On Ouput:
I: Updated NetCDF file information structure (struct array)
nc_inq.m
Inquires about the contents of a NetCDF file: dimensions, global attributes, and variables.
I = nc_inq  (ncfile, Lprint)
On Input:
ncfile: NetCDF file name or URL file name (string)
Lprint: Switch to print information (optional; default false)
On Output:
I: NetCDF information (struct array):
I.Filename NetCDF file name (string)
I.Attributes NetCDF global attributes (struct array):
I.Attributes(:).Name
I.Attributes(:).Value
I.Dimensions NetCDF file dimensions (struct array):
I.Dimensions(:).Name
I.Dimensions(:).Length
I.Dimensions(:).Unlimited
I.Variables(:).Dimensions variable dimensions (struct array):
I.Variables(:).Dimensions(:).Name
I.Variables(:).Dimensions(:).Length
I.Variables(:).Dimensions(:).Unlimited
I.Variables(:).Size variable size (double array)
I.Variables(:).Attributes variable attributes (struct array):
I.Variables(:).Attributes(:).Name
I.Variables(:).Attributes(:).Value
I.Variables(:).Cgridtype stagged C-grid type (struct array):
I.Variables(:).Cgridtype.Name
I.Variables(:).Cgridtype.Value
I.Variables(:).Datatype original variable data type (string)
I.Variables(:).ncType NetCDF data type (numeric)
nc_interface.m
Determines the interface to use when processing a NetCDF file. The strategy is to always use the 'native' method when possible. It was introduced in Matlab version 2008b for NetCDF-3 type files. The NetCDF-4 support was introduced in version 2010b. The support for HDF5 files was completed in version 2011a. The OpenDAP support started in version 2012a. The MEXNC and SNCTOOLS interfaces are becoming obsolete. The MEXNC is the oldest interface. It is no longer developed and only has support for NetCDF-3 and NetCDF-4 classic files. It does not have Java support for OpenDAP files. The SNCTOOLS have support for NetCDF-3, NetCDF-4, HDF5, and a Java interface for OpenDAP files.
[method, url, ftype] = nc_interface  (ncfile)
On Input:
ncfile : NetCDF file name or URL name (string)
On Output:
method : NetCDF interface for Matlab (string):
'native' Native Matlab interface
'mexnc' MEXNC interface
'java' SNCTOOLS Java interface
url: Switch indicating an OpenDAP file (logical)
ftype: File type (string)
'NetCDF' Classic NetCDF-3 file
'NetCDF4' NetCDF-4/HDF5 file
'OpenDAP' OpenDAP file
nc_read.m
Reads in a generic variable from a NetCDF file. If only the water points are available, this function fill the land areas with zero and returns the full field.
f = nc_read  (ncfile, Vname, Tindex, ReplaceValue, PreserveType)
On Input:
ncfile: NetCDF file name or URL name (string)
Vname: NetCDF variable name to read (string)
Tindex: Time record index to read (scalar). If Tindex is provided, only the requested time record is processed when the variable has the unlimited dimension or the word time in any of its dimension names. Otherwise, provide an empty [ ] argument.
ReplaceValue: Value to use when _FillValue or missing_value attribute is found in variable. If not provided, a zero value will used. In some instances, like plotting, it is advantageous to use NaN to better visualize the land masking or the missing data.
PreserveType: Switch to preserve numerical data type (logical). If false, convert numerical data to double precision. It has no effect on data that is already in double precision.
On Output:
f: Field (scalar or array)
nc_write.m
Writes a generic variable into a NetCDF file.
status = nc_read  (ncfile, Vname, f, Tindex)
On Input:
ncfile: NetCDF file name or URL name (string)
Vname: NetCDF variable name to read (string)
f: variable values (scalar or array)
Tindex: If Tindex is not provided as an argument during function call, it is assumed that the entire variable is to be written. If the variable has an unlimited record dimension, Tindex can be used to increase that dimension or replace an existing record. If the variable has the word time in its dimension name, Tindex can be used to write at the specified the time record.
On Output:
status: Error flag
Retrieved from "https://www.myroms.org/wiki/index.php?title=Matlab_Processing_Scripts&oldid=5128"