View source for Matlab Processing Scripts

<div class="title">Matlab: Processing Scripts for Nesting</div> __TOC__

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''': <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>.

==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_Grids#Nested_Grids_Classes|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:
#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 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 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 [[Matlab_Processing_Scripts#landsea|landsea.m]] can be used to automatize the land/sea masking , but it still needs some hand editing using [[Matlab_Processing_Scripts#editmask|editmask.m]].

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

{{#lst:Grid_Processing_Scripts|c_grid.m}}
{{#lst:Grid_Processing_Scripts|coarse2fine.m}}
{{#lst:Grid_Processing_Scripts|fine2coarse.m}}
{{#lst:Grid_Processing_Scripts|grid_extract.m}}
{{#lst:Utility_Scripts|sample_grid.m}}


==Contact Regions and Contact Points Scripts==
<wikitex>
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 users to analyzed the data in the NetCDF file and activate the plotting switch to examine the contact point.  The plot maybe very dense when the connectivity involves a lot of files.  We need to zoom the plotting frames until there are readable and think carefully.  A expertise in ROMS is required to analyze the plots.

These function use the excellent Matlab function <span class="blue">inpolygon</span> to find 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 ($\xi$, $\eta$).  For example, in Matlab the Imin and Jmin indices correspond to fractional coordinates:

$$\xi_{\psi}(I_{\psi}) = \xi_{\rho}(I_{\rho})$$
$$\eta_{\psi}(J_{\psi}) = \eta_{\rho}(J_{\rho})$$

since $I_{\psi} = I_{\rho}$ and $J_{\psi} = J_{\rho}$.  The number of points in each direction is $L_{\rho} = L_{\psi}+1$ and $M_{\rho} = M_{\psi}+1$, respectively.  Therefore, the zero shift of &rho;-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}}
</wikitex>

==State Variables Preparation Scripts==

The following scripts may be used to prepare initial conditions, lateral boundary conditions, and climatology data and create its associated NetCDF files.  The <span class="blue">TriScatteredInterp</span> function is used when interpolation is required using <span class="red">natural</span>, <span class="red">linear</span>, or <span class="red">nearest</span> method.  In some application, 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}}


==Support Scripts==
<wikitex>
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 />

{{#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}}
</wikitex>

==NetCDF Data Processing Scripts==