Difference between revisions of "Grid Processing Scripts"

From WikiROMS
Jump to navigationJump to search
 
(14 intermediate revisions by 2 users not shown)
Line 2: Line 2:


This page describes several Matlab scripts to process ROMS grid.  
This page describes several Matlab scripts to process ROMS grid.  


<!-- Edit Template:Matlab_Scripts_TOC to modify this Table of Contents-->
<!-- Edit Template:Matlab_Scripts_TOC to modify this Table of Contents-->
Line 10: Line 11:


<section begin=c_contact.m />;<span id="c_contact"></span><span class="blue">c_contact.m</span>
<section begin=c_contact.m />;<span id="c_contact"></span><span class="blue">c_contact.m</span>
:Creates a new contact coints NetCDF file for a ROMS nesting application. The contact point data is written elsewhere using [[Matlab_Processing_Scripts#write_contact|write_contact.m]]. if the <span class="green">Ndatum</span> argument is not provided, the '''datum''' dimension is '''unlimited'''.<br />
:Creates a new contact points NetCDF file for a ROMS nesting application. The contact point data is written elsewhere using [[Matlab_Processing_Scripts#write_contact|write_contact.m]]. If the <span class="green">Ndatum</span> argument is not provided, the '''datum''' dimension is '''unlimited'''.<br />
::<span class="red">c_contact</span> &nbsp;(<span class="green">ncname</span>, <span class="green">spherical</span>, <span class="green">Ngrids</span>, <span class="green">Ndatum</span>)
::<span class="red">c_contact</span> &nbsp;(<span class="green">ncname</span>, <span class="green">spherical</span>, <span class="green">Ngrids</span>, <span class="green">Ndatum</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">ncname</span>: &nbsp;  Ouptut contact points NetCDF file name (string)
::{| class="matlab"
::<span class="green">spherical</span>: &nbsp; Spherical grid switch (logical)
|-
::<span class="green">Ngrids</span>: &nbsp; Number of nested grids
|<span class="green">ncname</span>:
::<span class="green">Ndatum</span>: &nbsp; Total number of contact points (optional)<section end=c_contact.m />
|Output contact points NetCDF file name (string)
|-
|<span class="green">spherical</span>:
|Spherical grid switch (logical)
|-
|<span class="green">Ngrids</span>:
|Number of nested grids
|-
|<span class="green">Ndatum</span>:
|Total number of contact points (optional)
|-
|}


<section begin=c_grid.m />;<span id="c_grid"></span><span class="blue">c_grid.m</span>
<section begin=c_grid.m />;<span id="c_grid"></span><span class="blue">c_grid.m</span>
:Creates a new ROMS grid NetCDF file or modifies a existing ROMS grid NetCDF file.<br />
:Creates a new ROMS grid NetCDF file or modifies an existing ROMS grid NetCDF file.<br />
::<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>)
::<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>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">Lp</span>: &nbsp; Number of &rho;-point in the &xi;-direction
::{| class="matlab"
::<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">Lp</span>:
::<span class="green">NewFile</span>: &nbsp; Switch to create a new file (logical, optional, default false)
|Number of &rho;-points in the &xi;-direction
::<span class="green">spherical</span>: &nbsp; Spherical grid switch (logical, optional, default true)
|-
:'''On Ouput:'''
|<span class="green">Mp</span>:
::<span class="green">status</span>: &nbsp; Error flag<section end=c_grid.m />
|Number of &rho;-points in the &eta;-direction
|-
|<span class="green">Gname</span>:
|Grid NetCDF file name (string)
|-
|<span class="green">NewFile</span>:
|Switch to create a new file (logical, optional, default false)
|-
|<span class="green">spherical</span>:
|Spherical grid switch (logical, optional, default true)
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">status</span>:
|Error flag
|-
|}<section end=c_grid.m />


<section begin=coarse2fine.m />;<span id="coarse2fine"></span><span class="blue">coarse2fine</span>
<section begin=coarse2fine.m />;<span id="coarse2fine"></span><span class="blue">coarse2fine</span>
: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 />
: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 defines 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>)
::<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:'''
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input coarser Grid NetCDF file name (string)
::{| class="matlab"
::<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">Ginp</span>:
::<span class="green">Imin</span>: &nbsp; Coarse grid lower-left  I-coordinate (&psi;-point)
|Input coarser Grid NetCDF file name (string)
::<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">Gout</span>:
::<span class="green">Jmax</span>: &nbsp; Coarse grid upper-right J-coordinate (&psi;-point)
|Output finer Grid NetCDF file name (string)
:'''On Ouput:'''
|-
::<span class="green">F</span>: &nbsp; Fine resolution grid structure (struct array)<section end=coarse2fine.m />
|<span class="green">Gfactor</span>:
|Grid refinement factor (3,5,7,9,11,13,15,...)
|-
|<span class="green">Imin</span>:
|Coarse grid lower-left  I-coordinate (&psi;-point)
|-
|<span class="green">Imax</span>:
|Coarse grid upper-right I-coordinate (&psi;-point)
|-
|<span class="green">Jmin</span>:
|Coarse grid lower-left  J-coordinate (&psi;-point)
|-
|<span class="green">Jmax</span>:
|Coarse grid upper-right J-coordinate (&psi;-point)
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">F</span>:  
|Fine resolution grid structure (struct array)
|-
|}<section end=coarse2fine.m />
 


<section begin=contact.m />;<span id="contact"></span><span class="blue">contact.m</span>
<section begin=contact.m />;<span id="contact"></span><span class="blue">contact.m</span>
: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 <span class="green">MaskInterp</span> 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 &psi;- u-, and v-masks from coarser grid than recomputing via [[uvp_masks]]. The recomputed masks may be one point smaller or larger. Use the <span class="green">MaskInterp</span> switch to either interpolate (true) or use [[uvp_masks]] (false).  Recall that we are not modifying the original refined grid mask, but just computing the mask in the contact region adjacent to finer grid from the coarser grid mask. This is only relevant when there is a land/sea masking features in any of the refinement grid physical boundary. If so, the user just need to experiment with <span class="green">MaskInterp</span> and edit such points during post-processing.<br />
: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 <span class="green">MaskInterp</span> 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 &psi;- u-, and v-masks from coarser grid than recomputing via [[Land_Sea_Masking_Scripts#uvp_masks|uvp_masks]]. The recomputed masks may be one point smaller or larger. Use the <span class="green">MaskInterp</span> switch to either interpolate (true) or use [[Land_Sea_Masking_Scripts#uvp_masks|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 <span class="green">MaskInterp</span> and edit such points during post-processing.<br />
::[<span class="green">S</span>, <span class="green">G</span>] = <span class="red">contact</span> &nbsp;(<span class="green">Gnames</span>, <span class="green">Cname</span>, <span class="green">Lmask</span>, <span class="green">MaskInterp</span>, <span class="green">Lplot</span>)
::[<span class="green">S</span>, <span class="green">G</span>] = <span class="red">contact</span> &nbsp;(<span class="green">Gnames</span>, <span class="green">Cname</span>, <span class="green">Lmask</span>, <span class="green">MaskInterp</span>, <span class="green">Lplot</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">Gnames</span>: &nbsp; Input Grid NetCDF full path file names  (cell array)
::{| class="matlab"
::<span class="green">Cname</span>: &nbsp; Ouptut contact points NetCDF file name (string)
|-
::<span class="green">Lmask</span>: &nbsp; Switch to remove contact points over land (logical, optional, default false)
|<span class="green">Gnames</span>:
::<span class="green">MaskInterp</span>: &nbsp; Switch to interpolate &psi;-, u- and v-masks (true) or compute from interpolated &rho;-mask (false). The default is false (logical, optional).
|Input Grid NetCDF full path file names  (cell array)
::<span class="green">Cname</span>: &nbsp; Switch to plot various contact points figures (logical, optional, default true)
|-
:'''On Ouput:'''
|<span class="green">Cname</span>:
::<span class="green">S</span>: &nbsp; Nested grids contact points structure (struct array)
|Output contact points NetCDF file name (string)
::<span class="green">G</span>: &nbsp; Nested grids structure (1 x Ngrids struct array)<section end=contact.m />
|-
|<span class="green">Lmask</span>:
|Switch to remove contact points over land (logical, optional, default false)
|-
|<span class="green">MaskInterp</span>:
|Switch to interpolate &psi;-, u- and v-masks (true) or compute from interpolated &rho;-mask (false). The default is false (logical, optional).
|-
|<span class="green">Lplot</span>:
|Switch to plot various contact points figures (logical, optional, default false)
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">S</span>:
|Nested grids contact points structure (struct array)
|-
|<span class="green">G</span>:
|Nested grids structure (1 x Ngrids struct array)
|-
|}<section end=contact.m />
 


<section begin=disp_contact.m />;<span id="disp_contact"></span><span class="blue">disp_contact.m</span>
<section begin=disp_contact.m />;<span id="disp_contact"></span><span class="blue">disp_contact.m</span>
:Prints the nested grids contact points unique values for each Contact Region. The contact points structure is rich and this simple function facilitates to summarize the contact points values.<br />
: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.<br />
::<span class="red">disp_contact</span> &nbsp;(<span class="green">S</span>)
::<span class="red">disp_contact</span> &nbsp;(<span class="green">S</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">ncname</span>: &nbsp;  Contact points structure(struct array)<section end=disp_contact.m />
::{| class="matlab"
|-
|<span class="green">ncname</span>:
|Contact points structure(struct array)
|-
|}<section end=disp_contact.m />
 


<section begin=fine2coarse.m />;<span id="fine2coarse"></span><span class="blue">fine2coarse</span>
<section begin=fine2coarse.m />;<span id="fine2coarse"></span><span class="blue">fine2coarse</span>
: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 />
: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 defines 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>)
::<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:'''
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input finer Grid NetCDF file name (string)
::{| class="matlab"
::<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">Ginp</span>:
::<span class="green">Imin</span>: &nbsp; Finer grid lower-left  I-coordinate (&psi;-point)
|Input finer Grid NetCDF file name (string)
::<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">Gout</span>:
::<span class="green">Jmax</span>: &nbsp; Finer grid upper-right J-coordinate (&psi;-point)
|Output coarser Grid NetCDF file name (string)
:'''On Ouput:'''
|-
::<span class="green">C</span>: &nbsp; Coarser resolution grid structure (struct array)<section end=fine2coarse.m />
|<span class="green">Gfactor</span>:
|Grid coarseness factor (3,5,7,9,11,13,15,...)
|-
|<span class="green">Imin</span>:
|Finer grid lower-left  I-coordinate (&psi;-point)
|-
|<span class="green">Imax</span>:
|Finer grid upper-right I-coordinate (&psi;-point)
|-
|<span class="green">Jmin</span>:
|Finer grid lower-left  J-coordinate (&psi;-point)
|-
|<span class="green">Jmax</span>:
|Finer grid upper-right J-coordinate (&psi;-point)
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">C</span>:
|Coarser resolution grid structure (struct array)
|-
|}<section end=fine2coarse.m />
 


<section begin=flip_grid.m />;<span id="flip_grid"></span><span class="blue">flip_grid.m</span>
<section begin=flip_grid.m />;<span id="flip_grid"></span><span class="blue">flip_grid.m</span>
:Given a ROMS Grid NetCDF file (<span class="green">Ginp</span>), this function creates a new Grid NetCDF (<span class="green">Gout</span>) with the flipped dimensions, coordinates, and variables. <br />
:Given a ROMS Grid NetCDF file (<span class="green">Ginp</span>), this function creates a new Grid NetCDF file (<span class="green">Gout</span>) with the flipped dimensions, coordinates, and variables. <br />
::<span class="green">G</span> = <span class="red">flip_grid</span> &nbsp;(<span class="green">Ginp</span>, <span class="green">Gout</span>)
::<span class="green">G</span> = <span class="red">flip_grid</span> &nbsp;(<span class="green">Ginp</span>, <span class="green">Gout</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">Ginp</span>: &nbsp; Input ROMS grid NetCDF file name (string)
::{| class="matlab"
::<span class="green">Gout</span>: &nbsp;  Output flipped ROMS grid NetCDF file name (string)
|-
|<span class="green">Ginp</span>:
|Input ROMS grid NetCDF file name (string)
|-
|<span class="green">Gout</span>:
|Output flipped ROMS grid NetCDF file name (string)
|-
|}
:'''On Output:'''
:'''On Output:'''
::<span class="green">Sinp</span>: &nbsp;  Flipped Grid structure (struct array)<section end=flip_grid.m />
::{| class="matlab"
|-
|<span class="green">Sinp</span>:
|Flipped Grid structure (struct array)
|-
|}<section end=flip_grid.m />
 
 
<section begin=get_roms_grid.m />;<span id="get_roms_grid"></span><span class="blue">get_roms_grid.m</span>
: Builds or updates a ROMS Grid structure (<span class="green">Gout</span>) containing all the variables associated with the application's horizontal and vertical grids. <br />
::<span class="green">Gout</span> = <span class="red">get_roms_grid</span> &nbsp;(<span class="green">Ginp</span>)
::<span class="green">Gout</span> = <span class="red">get_roms_grid</span> &nbsp;(<span class="green">Ginp</span>, <span class="green">Sinp</span>)
::<span class="green">Gout</span> = <span class="red">get_roms_grid</span> &nbsp;(<span class="green">Ginp</span>, <span class="green">Sinp</span>, <span class="green">Tindex</span>)
::<span class="green">Gout</span> = <span class="red">get_roms_grid</span> &nbsp;(<span class="green">Ginp</span>, <span class="green">Tindex</span>)
:'''On Input:'''
::{| class="matlab"
|-
|<span class="green">Ginp</span>:
|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)
|-
|<span class="green">Sinp</span>:
|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):
|-
|}
:::{| class="matlab"
|-
|<span class="green">Sinp.N</span>
|number of vertical levels
|-
|<span class="green">Sinp.Vtransform</span>
|vertical transformation equation
|-
|<span class="green">Sinp.Vstretching</span>
|vertical stretching function
|-
|<span class="green">Sinp.theta_s</span>
|surface control parameter
|-
|<span class="green">Sinp.theta_b</span>
|bottom control parameter
|-
|<span class="green">Sinp.Tcline</span>
|surface/bottom stretching width
|-
|<span class="green">Sinp.hc</span>
|stretching width used in ROMS
|-
|}
::{| class="matlab"
|-
|<span class="green">Tindex</span>
|Time record index used to process free-surface in the vertical coordinates (scalar; optional):<br />If <span class="green">Tindex</span> is omitted, zero or empty, it assumes that '''zeta = 0''' yielding unperturbed depths.<br />Otherwise, the free-surface record in input NetCDF is processed.  The free-surface is read from either <span class="green">Ginp</span> (if history file) or <span class="green">Sinp</span> (if provided and history file).
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">Gout</span>:
|ROMS grid variables structure (struct array)
|-
|}<section end=get_roms_grid.m />
 


<section begin=grid_connections.m />;<span id="grid_connections"></span><span class="blue">grid_connections.m</span>
<section begin=grid_connections.m />;<span id="grid_connections"></span><span class="blue">grid_connections.m</span>
Line 90: Line 261:
::<span class="green">S</span> = <span class="red">grid_connections</span> &nbsp;(<span class="green">G</span>, <span class="green">Sinp</span>)
::<span class="green">S</span> = <span class="red">grid_connections</span> &nbsp;(<span class="green">G</span>, <span class="green">Sinp</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">G</span>: &nbsp;  Nested grids information structure (1 x Ngrids struct array)
::{| class="matlab"
::<span class="green">Sinp</span>: &nbsp;  Nested grids contact points structure (struct array)
|-
|<span class="green">G</span>:
|Nested grids information structure (1 x Ngrids struct array)
|-
|<span class="green">Sinp</span>:
|Nested grids contact points structure (struct array)
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">S</span>:
|Updated nested grids contact points structure (struct array)
|-
|}<section end=grid_connections.m />
 
 
<section begin=grid_extract.m />;<span id="grid_extract"></span><span class="blue">grid_extract.m</span>
: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 />
::<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:'''
::{| class="matlab"
|-
|<span class="green">Ginp</span>:
|Input coaser Grid NetCDF file name (string) or an existing grid structure (struct array)
|-
|<span class="green">Gout</span>:
|Output smaller Grid NetCDF file name (string)
|-
|<span class="green">Imin</span>:
|Larger grid lower-left  I-coordinate (&psi;-point)
|-
|<span class="green">Imax</span>:
|Larger grid upper-right I-coordinate (&psi;-point)
|-
|<span class="green">Jmin</span>:
|Larger grid lower-left  J-coordinate (&psi;-point)
|-
|<span class="green">Jmax</span>:
|Larger grid upper-right J-coordinate (&psi;-point)
|-
|}
:'''On Output:'''
:'''On Output:'''
::<span class="green">Sinp</span>: &nbsp;  Outdated Nested grids contact points structure (struct array)<section end=grid_connections.m />
::{| class="matlab"
|-
|<span class="green">S</span>:
|Smaller grid structure (struct array)
|-
|}<section end=grid_extract.m />


<section begin=grid_perimenter.m />;<span id="grid_perimeter"></span><span class="blue">grid_perimeter.m</span>
 
<section begin=grid_metrics.m />;<span id="grid_metrics"></span><span class="blue">grid_metrics.m</span>
:Computes horizontal grid spacing metrics from Grid NetCDF file or Grid structure <span class="green">G</span>. <br />
::[<span class="green">pm</span>, <span class="green">pn</span>, <span class="green">dndx</span>, <span class="green">dmde</span>] = <span class="red">grid_metrics</span> &nbsp;(<span class="green">G</span>, <span class="green">GreatCircle</span>)
:'''On Input:'''
::{| class="matlab"
|-
|<span class="green">G</span>:
|Either a ROMS grid NetCDF file name (string) or ROMS grid structure (struct array)
|-
|<span class="green">GreatCircle</span>:
|Switch indicating how to compute the grid distance (logical): '''true''' Great-circle distance or '''false''' Cartesian distance
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">pm</span>:
|Curvilinear coordinate metric in the &xi;-direction (1/meters; '''dx = 1/pm''')
|-
|<span class="green">pn</span>:
|Curvilinear coordinate metric in the &eta;-direction (1/meters; '''dy = 1/pn''')
|-
|<span class="green">dndx</span>:
|&xi;-derivative  of inverse metric factor <span class="green">pn</span>, '''d(1/pn)/d(&xi;)''' (meter)
|-
|<span class="green">dmde</span>:
|&eta;-derivative  of inverse metric factor <span class="green">pm</span>, '''d(1/pm)/d(&eta;)''' (meter)
|-
|}<section end=grid_metrics.m />
 
 
<section begin=grid_perimeter.m />;<span id="grid_perimeter"></span><span class="blue">grid_perimeter.m</span>
:Creates a structure containing information about nested grids perimeters, boundary edges, and other information parameters. <br />
:Creates a structure containing information about nested grids perimeters, boundary edges, and other information parameters. <br />
::<span class="green">S</span> = <span class="red">grid_perimeter</span> &nbsp;(<span class="green">Gnames</span>)
::<span class="green">S</span> = <span class="red">grid_perimeter</span> &nbsp;(<span class="green">Gnames</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">Gnames</span>: &nbsp; Input Grid NetCDF full path file names  (cell array)
::{| class="matlab"
|-
|<span class="green">Gnames</span>:
|Input Grid NetCDF full path file names  (cell array)
|-
|}
:'''On Output:'''
:'''On Output:'''
::<span class="green">Sinp</span>: &nbsp;  Beginning of contact points structure (struct array)<section end=grid_perimeter.m />
::{| class="matlab"
|-
|<span class="green">Sinp</span>:
|Beginning of contact points structure (struct array)
|-
|}<section end=grid_perimeter.m />


<section begin=grid_extract.m />;<span id="grid_extract"></span><span class="blue">grid_extract.m</span>
: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 />
::<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">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)<section end=grid_extract.m />


<section begin=plot_contact.m />;<span id="plot_contact"></span><span class="blue">plot_contact.m</span>
<section begin=plot_contact.m />;<span id="plot_contact"></span><span class="blue">plot_contact.m</span>
Line 120: Line 367:
::<span class="red">plot_contact</span> &nbsp;(<span class="green">G</span>, <span class="green">S</span>)
::<span class="red">plot_contact</span> &nbsp;(<span class="green">G</span>, <span class="green">S</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">G</span>: &nbsp; Nested grids structure (1 x Ngrids struct array)
::{| class="matlab"
::<span class="green">S</span>: &nbsp; Nested grids contact points structure (struct array)<section end=plot_contact.m />
|-
|<span class="green">G</span>:
|Nested grids structure (1 x Ngrids struct array)
|-
|<span class="green">S</span>:
|Nested grids contact points structure (struct array)
|-
|}<section end=plot_contact.m />
 


<section begin=read_contact.m />;<span id="read_contact"></span><span class="blue">read_contact.m</span>
<section begin=read_contact.m />;<span id="read_contact"></span><span class="blue">read_contact.m</span>
Line 127: Line 382:
::[<span class="green">S</span>, <span class="green">G</span>] = <span class="red">read_contact</span> &nbsp;(<span class="green">ncname</span>)
::[<span class="green">S</span>, <span class="green">G</span>] = <span class="red">read_contact</span> &nbsp;(<span class="green">ncname</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">ncname</span>: &nbsp; Nested grids contact points NetCDF file name  (string)
::{| class="matlab"
|-
|<span class="green">ncname</span>:
|Nested grids contact points NetCDF file name  (string)
|-
|}
:'''On Output:'''
:'''On Output:'''
::<span class="green">S</span>: &nbsp; Nested grids contact points structure (struct array)
::{| class="matlab"
::<span class="green">G</span>: &nbsp; Nested grids structure (1 x Ngrids struct array)<section end=read_contact.m />
|-
|<span class="green">S</span>:
|Nested grids contact points structure (struct array)
|-
|<span class="green">G</span>:
|Nested grids structure (1 x Ngrids struct array)
|-
|}<section end=read_contact.m />
 
 
<section begin=uniform_grid.m />;<span id="uniform_grid"></span><span class="blue">uniform_grid.m</span>
:Given the grid spacing (<span class="green">dx</span>, <span class="green">dy</span>) and number of &psi;-points (<span class="green">L</span>, <span class="green">M</span>) in the X- and Y-direction, this function sets the ROMS grid Cartesian coordinates and metrics. <br />
::<span class="green">G</span> = <span class="red">uniform_grid</span> &nbsp;(<span class="green">dx</span>, <span class="green">dy</span>, <span class="green">L</span>, <span class="green">M</span>)
:'''On Input:'''
::{| class="matlab"
|-
|<span class="green">dx</span>:
|Grid spacing in the X-direction (meters; scalar)
|-
|<span class="green">dy</span>:
|Grid spacing in the Y-direction (meters; scalar)
|-
|<span class="green">L</span>:
|Number of &psi;-points in the X-direction
|-
|<span class="green">M</span>:
|Number of &psi;-points in the Y-direction
|-
|}
:'''On Output:'''
::{| class="matlab"
|-
|<span class="green">G</span>:
|Uniform grid coordinates and metrics (struct array):
|-
|}
:::{| class="matlab"
|-
|<span class="green">G.x_psi</span>
|X-coordinates at &psi;-points (meters)
|-
|<span class="green">G.y_psi</span>
|Y-coordinates at &psi;-points (meters)
|-
|<span class="green">G.x_rho</span>
|X-coordinates at &rho;-points (meters)
|-
|<span class="green">G.y_rho</span>
|Y-coordinates at &rho;-points (meters)
|-
|<span class="green">G.x_u</span>
|X-coordinates at u-points (meters)
|-
|<span class="green">G.y_u</span>
|Y-coordinates at u-points (meters)
|-
|<span class="green">G.x_v</span>
|X-coordinates at v-points (meters)
|-
|<span class="green">G.y_v</span>
|Y-coordinates at v-points (meters)
|-
|<span class="green">G.pm</span>
|X-coordinates metric '''m''' (1/meters, '''1/dx''')
|-
|<span class="green">G.pn</span>
|Y-coordinates metric '''n''' (1/meters, '''1/dy''')
|-
|<span class="green">G.dndx</span>
|Inverse metric, '''d(1/pn)/d(&xi;)''' (meter)
|-
|<span class="green">G.dmde</span>
|Inverse metric, '''d(1/pm)/d(&eta;)''' (meter)
|-
|}<section end=uniform_grid.m />
 


<section begin=write_contact.m />;<span id="write_contact"></span><span class="blue">write_contact.m</span>
<section begin=write_contact.m />;<span id="write_contact"></span><span class="blue">write_contact.m</span>
:Writes out the nested grids contact points data generated by [[Matlab_Processing_Scripts#contact|contact.m]] or [[Matlab_Processing_Scripts#read_contact|read_contact.m]] into a NetCDF. <br />
:Writes out the nested grids contact points data generated by [[Grid_Processing_Scripts#contact|contact.m]] or [[Grid_Processing_Scripts#read_contact|read_contact.m]] into a NetCDF. <br />
::<span class="red">write_contact</span> &nbsp; (<span class="green">ncname</span>, <span class="green">S</span>, <span class="green">Lcreate</span>)
::<span class="red">write_contact</span> &nbsp; (<span class="green">ncname</span>, <span class="green">S</span>, <span class="green">Lcreate</span>)
:'''On Input:'''
:'''On Input:'''
::<span class="green">ncname</span>: &nbsp; Nested grids contact points NetCDF file name (string)
::{| class="matlab"
::<span class="green">S</span>: &nbsp; Nested grids contact points structure (struct array)
|-
::<span class="green">Lcreate</span>: &nbsp; Switch to create a new NetCDF file (logical, optional, default true)<section end=write_contact.m />
|<span class="green">ncname</span>:
|Nested grids contact points NetCDF file name (string)
|-
|<span class="green">S</span>:
|Nested grids contact points structure (struct array)
|-
|<span class="green">Lcreate</span>:
|Switch to create a new NetCDF file (logical, optional, default true)
|-
|}<section end=write_contact.m />

Latest revision as of 15:57, 18 April 2014

Matlab: Grid Processing Scripts

This page describes several Matlab scripts to process ROMS grid.



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)