Difference between revisions of "easygrid"

From WikiROMS
Jump to navigationJump to search
m (Text replacement - "ocean.in" to "roms.in")   (change visibility)
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div class="title">EASYGRID</div>
<div class="title">EASYGRID</div>
 
<br>
{| style="width:98%; background:yellow; margin-top:10px; border:1px solid red;" cellpadding="5" cellspacing="0"
|-
|{{warning}} '''This WikiROMS article is currently under HEAVY construction. This message will be erased when active construction is finished (in 1 or 2 days).'''<br> <small>April 21, 2008 </small>
|}
 
EASYGRID is a simple matlab script to make ROMS grids and initialization files. It is an austere grid-making alternative designed as a beginner's tool, yet capable of making grids for realistic applications. Since most of EASYGRID is in one file (<span class="red">easygrid.m</span>), it is easier to follow and understand the steps required to generate a simple grid (i.e. useful as a learning or teaching tool) and also reduces the required steps to get the software up and running (i.e. downloading and compiling dependencies).
EASYGRID is a simple matlab script to make ROMS grids and initialization files. It is an austere grid-making alternative designed as a beginner's tool, yet capable of making grids for realistic applications. Since most of EASYGRID is in one file (<span class="red">easygrid.m</span>), it is easier to follow and understand the steps required to generate a simple grid (i.e. useful as a learning or teaching tool) and also reduces the required steps to get the software up and running (i.e. downloading and compiling dependencies).


Line 15: Line 10:
{|style="width:100%; font-size:92%;" cellpadding="3"
{|style="width:100%; font-size:92%;" cellpadding="3"
|-
|-
|style="width:25%; background:Honeydew; border:1px solid YellowGreen;" valign="top"|<span class="green">QUICK LINKS:</span><br>[http://easygrid4roms.googlecode.com Hosting page at Google-Code]<br>Discussion Forum (link soon)
|style="width:25%; background:Honeydew; border:1px solid YellowGreen;" valign="top"|<span class="green">QUICK LINKS:</span><br>[https://code.google.com/archive/p/easygrid4roms/ Hosting page at Google-Code]<br>[https://www.myroms.org/forum/viewtopic.php?p=3043#3043 Discussion Forum]
|style="width:2%; background:transparent;"|
|style="width:2%; background:transparent;"|
|style="width:25%; background:LightCyan; border:1px solid Blue;" valign="top"|<span class="blue">NEWS:</span><br>24 April 2008: Version 0 is out
|style="width:25%; background:LightCyan; border:1px solid Blue;" valign="top"|<span class="blue">NEWS:</span><br>24 April 2008: Version 0 is out
|style="width:2%; background:transparent;"|
|style="width:2%; background:transparent;"|
|style="width:46%; background:LightYellow; border:1px solid red;" valign="top"| {{warning}} <span class="red">WARNING:</span><br>EASYGRID v1 is in BETA stage and could have problems. Report HERE (link soon) not only bugs, but <span class="red">also report successful use</span>. Once the bug:success ratio decreases... I will remove this sign.
|style="width:46%; background:LightYellow; border:1px solid red;" valign="top"| {{warning}} <span class="red">WARNING:</span><br>EASYGRID v0 is in BETA stage and could have problems. Report [https://www.myroms.org/forum/viewtopic.php?p=3043#3043 HERE] not only bugs, but <span class="red">also report successful use</span>. Once the bug:success ratio decreases... I will remove this sign.
|}
|}


Line 26: Line 21:


==Download EASYGRID==  
==Download EASYGRID==  
*[http://easygrid4roms.googlecode.com/files/EASYGRID_v0.rar '''Download EASYGRID''']<small> (This download also includes, bathymetry, coastline and other files required for this tutorial)</small>
*[https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/easygrid4roms/EASYGRID_v0.rar '''Download EASYGRID''']<small> (This download also includes the bathymetry and coastline files required for this tutorial)</small>
*Extract (i.e. unzip or unpack) the file in a location where it can stay indefinitely.
*Extract (i.e. unzip or unpack) the file in a location where it can stay indefinitely.
*Add the location where you placed EASYGRID to your Matlab search path <small>(see [[MEXNC#How to install MEXNC?|#5]] as an example).</small>
*Add the location where you placed EASYGRID to your Matlab search path <small>(see [[MEXNC#How to install MEXNC?|#5]] as an example).</small>
*<span class="red">Dependencies:</span> EASYGRID uses [http://mexcdf.sourceforge.net/downloads/ MEXNC, SNCTOOLS] and [http://www.myroms.org/index.php?page=Processing ROMS Matlab tool-kit] (only a few scripts like spheric_dist.m , smth_bath.m , pcolorjw.m).  
*<span class="red">Dependencies:</span> EASYGRID uses [http://mexcdf.sourceforge.net/downloads/ MEXNC, SNCTOOLS] and [http://www.myroms.org/index.php?page=Processing ROMS Matlab tool-kit] (only a few scripts like spheriq_dist.m , smth_bath.m , pcolorjw.m).  
:{{note}} For a '''tutorial''' on how to download/install these dependencies, [[MEXNC|CLICK HERE]].
:{{note}} For a '''tutorial''' on how to download/install these dependencies, [[MEXNC|CLICK HERE]].
<br>
<br>
Line 50: Line 45:




For this tutorial, you will need <span class="red">Fjord_bathy.mat</span> . You probably already have this file since it is included in [http://easygrid4roms.googlecode.com/files/EASYGRID_v1.rar EASYGRID_v0.rar]  (file from the [[#Download EASYGRID|"Download"]] section). I created <span class="red">Fjord_bathy.mat</span> by merging two bathymetry files... one high-resolution digitized from a chart and another coarser-resolution using <span class="red">read_srtm30plus.m</span> (see Figure).
For this tutorial, you will need <span class="red">Fjord_bathy.mat</span>. You probably already have this file since it is included in [https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/easygrid4roms/EASYGRID_v0.rar EASYGRID_v0.rar]  (file from the [[#Download EASYGRID|"Download"]] section). I created <span class="red">Fjord_bathy.mat</span> by merging two bathymetry files... one high-resolution digitized from a chart and another coarser-resolution using <span class="red">read_srtm30plus.m</span> (see Figure).


<div style="clear: both;"></div>


{{note}} If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:
{{note}} If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:
Line 59: Line 55:
  ylabel(<span class="purple">'Latitude'</span>);
  ylabel(<span class="purple">'Latitude'</span>);
  axis <span class="purple">square</span>;
  axis <span class="purple">square</span>;
<br>
 
<br>
 
 


==Getting coastline==
==Getting coastline==
In EASYGRID, the coastline is only used for plotting and it therefore not indispensable. However, it is handy to have a coastline for reference, especially when editing the land/sea mask. For EASYGRID, the coastline should be 2 vectors named "lat" and "lon" (both in units of [http://en.wikipedia.org/wiki/Decimal_degrees decimal degrees]) contained in a .mat file.
In EASYGRID, the coastline is only used for plotting and is therefore not indispensable. However, it is handy to have a coastline for reference, especially when editing the land/sea mask. For EASYGRID, the coastline should be 2 vectors named "lat" and "lon" (both in units of [http://en.wikipedia.org/wiki/Decimal_degrees decimal degrees]) contained in a .mat file.




[[image:Fjord_coast.jpg|left|350px|]]
[[image:Fjord_coast.jpg|left|350px|]]


An easy way to get coastline data is at NOAA's [http://rimmer.ngdc.noaa.gov/coast/ Coastline Extractor]. Remember to select '''Matlab''' as format option (not default). [[seagrid|SEAGRID's WikiROMS page]] has excellent information on how to use the Coastline Extractor, and tools to correct and manipulate coastline data.
One way to get coastline data is at [http://www.soest.hawaii.edu/pwessel/gshhg/ GSHHG]. NOAA's Coastline Extractor is no longer available.






For this tutorial, you will need <span class="red">Fjord_coast.mat</span> . You probably already have this file since it is included in [http://easygrid4roms.googlecode.com/files/EASYGRID_v1.rar EASYGRID_v0.rar]  (file from the [[#Download EASYGRID|"Download"]] section). I created <span class="red">Fjord_coast.mat</span> from the digitized chart I use to make the bathymetry file (see Figure).
For this tutorial, you will need <span class="red">Fjord_coast.mat</span>. You probably already have this file since it is included in [https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/easygrid4roms/EASYGRID_v0.rar EASYGRID_v0.rar]  (file from the [[#Download EASYGRID|"Download"]] section). I created <span class="red">Fjord_coast.mat</span> from the digitized chart I used to make the bathymetry file (see Figure).


<div style="clear: both;"></div>


{{note}} If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:
{{note}} If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:
Line 87: Line 85:
==Making your grid==
==Making your grid==
You probably will need to run EASYGRID several times in a iterative manner to create, smooth and mask-edit your grid. You can turn ON or OFF different functionalities of EASYGRID (like the mask-editing and bathymetry-smoothing routines) using the <span class="green">SWITCHES</span> located in the <span class="green">USER SETTINGS</span> section, which is the first part of script (after the help lines). Below a snippet from EASYGRID's code that contains the <span class="green">SWITCHES</span> section.
You probably will need to run EASYGRID several times in a iterative manner to create, smooth and mask-edit your grid. You can turn ON or OFF different functionalities of EASYGRID (like the mask-editing and bathymetry-smoothing routines) using the <span class="green">SWITCHES</span> located in the <span class="green">USER SETTINGS</span> section, which is the first part of script (after the help lines). Below a snippet from EASYGRID's code that contains the <span class="green">SWITCHES</span> section.
  <span style="color:green; font-size:95%; line-height:99%;">%****************************************************************************************************************************************************
  <span style="color:green; font-size:95%; line-height:99%;">%********************************************************************************************************
  % USER SETTINGS *************************************************************************************************************************************
  % USER SETTINGS *****************************************************************************************
  %****************************************************************************************************************************************************
  %********************************************************************************************************
  %
  %
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
     <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables existing on Workspace)
     <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %  existing on Workspace)
       <span class="black">plot_grid = 1;</span>  % Plot grid
       <span class="black">plot_grid = 1;</span>  % Plot grid
     <span class="black">smooth_grid = 1;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter to the bathymetry
     <span class="black">smooth_grid = 1;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
       <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into land-pixels and vice-versa  
                      %  to the bathymetry
   <span class="black">screen_output = 1;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the ocean.in file     
       <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %  land-pixels and vice-versa  
   <span class="black">screen_output = 1;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file     
       <span class="black">save_grid = 1;</span>  % Save GRID in a NetCDF file
       <span class="black">save_grid = 1;</span>  % Save GRID in a NetCDF file
       <span class="black">save_init = 1;</span>  % Create (and save) INITIAL CONDITIONS (from grid)</span>
       <span class="black">save_init = 1;</span>  % Create (and save) INITIAL CONDITIONS (from grid)</span>
Line 104: Line 105:


<br><br>
<br><br>
'''A typical procedure to create a grid will follow (more or less) these steps:'''
{{note}}'''A typical procedure to create a grid will follow (more or less) these steps:'''
# TURN ON <span class="red">create_grid</span> and <span class="red">plot_grid</span> and run EASYGRID.
# '''TURN ON''' <span class="red">create_grid</span> and <span class="red">plot_grid</span> (and turn off ALL other switches) and run EASYGRID.
# Tune-up Geographical and Grid parameters and run EASYGRID again.
# Tune-up Geographical and Grid parameters and run EASYGRID again.
# Repeat step 2 above until satisfied with the grid location, size and resolution.
# Repeat step 2 above until satisfied with the grid location, size and resolution.
# '''TURN OFF''' <span class="red">create_grid</span> and proceed to smooth bathymetry by turning ON <span class="red">smooth_grid</span> and re-running EASYGRID.
# '''TURN OFF''' <span class="red">create_grid</span> and proceed to smooth bathymetry by turning ON <span class="red">smooth_grid</span> and re-running EASYGRID.
# Tune-up smoothing parameters and repeat the step above as necessary... when finished, turn OFF <span class="red">smooth_grid</span>.
# Tune-up smoothing parameters and repeat the step above as many times as necessary... when finished, turn OFF <span class="red">smooth_grid</span>.
# Edit land/sea mask by turning ON <span class="red">edit_mask</span> and re-running EASYGRID.
# Edit land/sea mask by turning ON <span class="red">edit_mask</span> and re-running EASYGRID.
# Tune-up the land/sea mask as many times as necessary... when done, turn OFF <span class="red">edit_mask</span>.
# Tune-up the land/sea mask as many times as necessary... when done, turn OFF <span class="red">edit_mask</span>.
Line 117: Line 118:


===Setting up USER SETTINGS===
===Setting up USER SETTINGS===
The first thing to do is to edit EASYGRID's <font color="green">USER SETTINGS</font>. To make things easier for you, there are detailed instructions and explanations beside each variable entry line in the <font color="green">USER SETTINGS</font>. In fact, most of the "user-manual" for EASYGRID is included within itself. Therefore I will simply copy-paste below a snippet from EASYGRID's code that contains the USER SETTINGS/instructions section.  
EASYGRID's <font color="green">USER SETTINGS</font> section is where you can change the parameters needed to create your grid and initialization files. To make things easier for you, there are detailed instructions and explanations beside each variable entry line in the <font color="green">USER SETTINGS</font>. In fact, most of the "user-manual" for EASYGRID is included within itself. Therefore I will simply copy-paste below a snippet from EASYGRID's code that contains the USER SETTINGS/instructions section.  


{{note}} '''NOTE:''' The default settings in EASYGRID are for the [[FJORD_TIDAL_CASE|Fjord tidal case]], hence you can just run EASYGRID (using the included <span class="red">Fjord_bathy.mat</span> and <span class="red">Fjord_coast.mat</span> files) to generate the grid and initial-conditions files required for the [[FJORD_TIDAL_CASE|Fjord tidal case]] tutorial.
{{note}} '''NOTE:''' The default settings in EASYGRID are for the [[FJORD_TIDAL_CASE|Fjord tidal case]], hence you can just run EASYGRID (using the included <span class="red">Fjord_bathy.mat</span> and <span class="red">Fjord_coast.mat</span> files) to generate the grid and initial-conditions files required for the [[FJORD_TIDAL_CASE|Fjord tidal case]] tutorial.


  <span style="color:green; font-size:95%; line-height:99%;">%****************************************************************************************************************************************************
  <span style="color:green; font-size:95%; line-height:99%;">%********************************************************************************************************
  % USER SETTINGS *************************************************************************************************************************************
  % USER SETTINGS *****************************************************************************************
  %****************************************************************************************************************************************************
  %********************************************************************************************************
  %
  %
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
    <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables existing on Workspace)
    <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
      <span class="black">plot_grid = 1;</span>  % Plot grid
                      %  existing on Workspace)
    <span class="black">smooth_grid = 1;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter to the bathymetry
      <span class="black">plot_grid = 1;</span>  % Plot grid
      <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into land-pixels and vice-versa  
    <span class="black">smooth_grid = 1;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
  <span class="black">screen_output = 1;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the ocean.in file     
                      %  to the bathymetry
      <span class="black">save_grid = 1;</span>  % Save GRID in a NetCDF file
      <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
      <span class="black">save_init = 1;</span>  % Create (and save) INITIAL CONDITIONS (from grid)
                      %  land-pixels and vice-versa  
                        % ON = 1; OFF = 0
  <span class="black">screen_output = 1;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file     
      <span class="black">save_grid = 1;</span>  % Save GRID in a NetCDF file
      <span class="black">save_init = 1;</span>  % Create (and save) INITIAL CONDITIONS (from grid)
                      % ON = 1; OFF = 0
  %     
  %     
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
Line 142: Line 146:
  %
  %
  % Geographical and Grid parameters --------
  % Geographical and Grid parameters --------
       <span class="black">lat =  44.8125;</span>       % Latitude  (degrees) of the bottom-left corner of the grid.
       <span class="black">lat =  44.8125;</span>         % Latitude  (degrees) of the bottom-left corner of the grid.
       <span class="black">lon = -62.8855;</span>       % Longitude (degrees) of the bottom-left corner of the grid.  
       <span class="black">lon = -62.8855;</span>         % Longitude (degrees) of the bottom-left corner of the grid.  
  %
  %
         <span class="black">X = 9100;</span>           % Width of domain (meters)
         <span class="black">X = 9100;</span>             % Width of domain (meters)
         <span class="black">Y = 2550;</span>           % Length of domain (meters)
         <span class="black">Y = 2550;</span>             % Length of domain (meters)
  <span class="black">rotangle = -43;</span>             % Angle (degrees) to rotate the grid conterclock-wise
  <span class="black">rotangle = -43;</span>               % Angle (degrees) to rotate the grid conterclock-wise
     <span class="black">resol = 100;</span>             % Cell width and height (i.e. Resolution)in meters. Grid cells are forced to be (almost) square.
     <span class="black">resol = 100;</span>               % Cell width and height (i.e. Resolution)in meters. Grid cells are
         <span class="black">N = 10;</span>             % Number of vertical levels
                              %  forced to be (almost) square.
         <span class="black">N = 10;</span>               % Number of vertical levels
  %     
  %     
  %     
  %     
  % Bathymetry -------------- % Bathymetry for ROMS is measured positive downwards (zeros are not allowed) see: https://www.myroms.org/wiki/index.php/Grid_Generation#Bathymetry
  % Bathymetry --------------   % Bathymetry for ROMS is measured positive downwards (zeros are not allowed)
                            % To allow variations in surface elevation (eg. tides) while keeping all depths positive,
                              %  see: https://www.myroms.org/wiki/index.php/Grid_Generation#Bathymetry
                            % an arbitrary offset (see minh below) is added to the depth vector.
                              %   To allow variations in surface elevation (eg. tides) while keeping all
                              %  depths positive, an arbitrary offset (see minh below) is added to the
                              %  depth vector.
  %       
  %       
       <span class="black">hh = nan;</span>             % Analytical Depth (meters) used to create a uniform-depth grid. If using a bathymetry file, leave hh = nan;
       <span class="black">hh = nan;</span>               % Analytical Depth (meters) used to create a uniform-depth grid. If using a
     <span class="black">minh = 4;</span>               % Arbitrary depth offset in meters (see above). minh should be a little more than the maximum expected tidal variation.
                              %  bathymetry file, leave hh = nan;
     <span class="black">Bathy =</span> <span class="purple">'Fjord_bathy.mat'</span>;% Bathymetry file. If using the analytical depth above (i.e. hh ~= nan), then Bathy will not be used.
     <span class="black">minh = 4;</span>                 % Arbitrary depth offset in meters (see above). minh should be a little more
                            % The bathymetry file should be a .mat file containing 3 vectors (xbathy, ybathy and zbathy). where xbathy = Longitude,  
                              %  than the maximum expected tidal variation.
                            % ybathy = Latitude and zbathy = depth (positive, in meters). xbathy and ybathy are in decimal degrees See: http://en.wikipedia.org/wiki/Decimal_degrees
     <span class="black">Bathy =</span> <span class="purple">'Fjord_bathy.mat'</span>; % Bathymetry file. If using the analytical depth above (i.e. hh ~= nan), then
         %Bathymetry smoothing routine...  See "Switches section" (above) to turn this ON or OFF
                              %  Bathy will not be used. The bathymetry file should be a .mat file containing
                              %  3 vectors (xbathy, ybathy and zbathy). where xbathy = Longitude,
                              %   ybathy = Latitude and zbathy = depth (positive, in meters). xbathy and ybathy
                              %  are in decimal degrees See: http://en.wikipedia.org/wiki/Decimal_degrees
         % Bathymetry smoothing routine...  See "Switches section" (above) to turn this ON or OFF
         <span class="blue">if</span> <span class="black">smooth_grid == 1;</span>
         <span class="blue">if</span> <span class="black">smooth_grid == 1;</span>
             <span class="black">order = 2;</span>      % Order of Shapiro filter (2,4,8)... default: 2
             <span class="black">order = 2;</span>      % Order of Shapiro filter (2,4,8)... default: 2
Line 171: Line 183:
  %
  %
  % Coastline ----------------------
  % Coastline ----------------------
     <span class="black">Coast = load(</span><span class="purple">'Fjord_coast.mat'</span><span class="black">);</span> % If there isn't a coastline file... comment-out this line: e.g. %Coast = load('Fjord_coast.mat');
     <span class="black">Coast = load(</span><span class="purple">'Fjord_coast.mat'</span><span class="black">);</span> % If there isn't a coastline file... comment-out this line:
                                    % The coastline is only used for plotting. The coastline .mat file should contain 2 vectors named "lat" and "lon"
                                    %  e.g. %Coast = load('Fjord_coast.mat'); The coastline is only used for
                                    %  plotting. The coastline .mat file should contain 2 vectors named
                                    %  "lat" and "lon"
  %                                     
  %                                     
  %       
  %       
Line 179: Line 193:
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
  <span class="black">Grid_filename = <span class="purple">'Fjord'</span>;</span>   % Filename for grid and initial conditions files (don't include extension).  
  <span class="black">Grid_filename = <span class="purple">'Fjord'</span>;</span>   % Filename for grid and initial conditions files (don't include extension).  
                                % "_grd.nc" is added to grid file and "_ini.nc" is added to initial conditions file
                                    %   "_grd.nc" is added to grid file and "_ini.nc" is added to initial
                                    %  conditions file
  <span class="black">Descrip_grd  = <span class="purple">'Test grid'</span>;</span>              %Description for grid .nc file
  <span class="black">Descrip_grd  = <span class="purple">'Test grid'</span>;</span>              %Description for grid .nc file
  <span class="black">Descrip_ini  = <span class="purple">'Test initial conditions'</span>;</span> %Description for initial conditions .nc file
  <span class="black">Descrip_ini  = <span class="purple">'Test initial conditions'</span>;</span> %Description for initial conditions .nc file
Line 216: Line 232:
  %
  %
  %
  %
  %****************************************************************************************************************************************************
  %********************************************************************************************************
  % END OF USER SETTINGS ******************************************************************************************************************************
  % END OF USER SETTINGS **********************************************************************************
  %****************************************************************************************************************************************************</span>
  %********************************************************************************************************
{{note}} '''NOTE:''' You may want to change the name of <span class="red">easygrid.m</span> to a name more descriptive of your grid (example: <span class="red">easygrid_fjord.m</span>). That way you can keep many copies of <span class="red">easygrid.m</span>, each with the parameters of each of your different projects.
<br>
<br>
<br>
<br>


===Geographical/Grid parameters===
===Geographical/Grid parameters===
After you got the bathymetry and coastline of your study region, now it is time to place a grid on it... In the <span class="green">USER SETTINGS</span> section, you have to specify <span class="red">lat</span>, <span class="red">lon</span>, <span class="red">X</span>, <span class="red">Y</span> and <span class="red">rotangle</span>. This is done in an iterative manner, where first you input your best-guesses, then you plot the grid. From the plot you can adjust your geographical/grid parameters... plot... adjust... plot... adjust... and so on.  
After you got the bathymetry and coastline of your study region, now it is time to place a grid on it... In the <span class="green">USER SETTINGS</span> section, you have to specify <span class="red">lat</span>, <span class="red">lon</span>, <span class="red">X</span>, <span class="red">Y</span> and <span class="red">rotangle</span>. This is done in an iterative manner, where first you input your best-guesses, then you run EASYGRID to plot the grid. From the plot you can adjust your geographical/grid parameters... plot... adjust... plot... adjust... and so on.  


{{note}} '''You may want to turn off some switches (see below) to speed up the plotting process.'''
{{note}} '''You may want to turn off some switches (see below) to speed up the plotting process.'''
Line 229: Line 246:
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
  % -------------------------------------------------------------------------
  % -------------------------------------------------------------------------
     <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables existing on Workspace)
     <span class="black">create_grid = 1;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %  existing on Workspace)
       <span class="black">plot_grid = 1;</span>  % Plot grid
       <span class="black">plot_grid = 1;</span>  % Plot grid
     <span class="black">smooth_grid = 0;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter to the bathymetry
     <span class="black">smooth_grid = 0;</span>  % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
       <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into land-pixels and vice-versa  
                      %  to the bathymetry
   <span class="black">screen_output = 0;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the ocean.in file     
       <span class="black">edit_mask = 0;</span>  % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %  land-pixels and vice-versa  
   <span class="black">screen_output = 0;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file     
       <span class="black">save_grid = 0;</span>  % Save GRID in a NetCDF file
       <span class="black">save_grid = 0;</span>  % Save GRID in a NetCDF file
       <span class="black">save_init = 0;</span>  % Create (and save) INITIAL CONDITIONS (from grid)</span>
       <span class="black">save_init = 0;</span>  % Create (and save) INITIAL CONDITIONS (from grid)</span>
Line 267: Line 287:
<br>
<br>


===Initial Conditions===
ROMS initialization NetCDF files contain information of the spatial distribution of one (or multiple) variable(s) that ROMS uses at the '''START''' of the simulation. The value of each initialization variable is specified for each corresponding cell in the ROMS grid... hence, inside a typical initial-conditions file, there will be one three-dimensional matrix (matching grid dimensions) for each specified variable. EASYGRID can generate Initial-Conditions NetCDF files for ROMS, however, only in a rudimentary manner... the user can only choose a '''single value''' for each initial-condition variable... EASYGRID makes each variable '''CONSTANT''' over the entire grid domain. This may be only useful in some simple cases and to do "quick-tests".


===Editing Masks===
To change the value of a initial-condition variable, simply go to the <font color="green">INITIAL CONDITIONS</font> section in the <font color="green">USER SETTINGS</font> and change the value of the variable of interest.
Since the land/sea mask is automatically created using the bathymetry, it is very likely a few pixels will be wrongly assigned as land or sea. If so, you will need to edit your land/sea mask... and to do this, you can use EASYGRID's ''Mask-Editing interactive plot'', which is a plot of the land/sea mask that lets you (interactive) use your mouse's left-button to toggle land-cells into sea-cells... and vice versa.
<br>
<br>
First, '''TURN ON''' <span class="red">edit_mask</span> and '''TURN OFF''' <span class="red">create_grid</span>.
<span style="color:green; font-size:95%; line-height:99%;">% -------------------------------------------------------------------------
% SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
% -------------------------------------------------------------------------
    <span class="black">create_grid = <span class="red">0</span>;</span>  % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %  existing on Workspace)
      <span class="black">plot_grid = 0;</span>  % Plot grid
    <span class="black">smooth_grid = 0;</span>   % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
                      %  to the bathymetry
      <span class="black">edit_mask = <span class="red">1</span>;</span>   % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %  land-pixels and vice-versa
  <span class="black">screen_output = 0;</span>  % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file   
      <span class="black">save_grid = 0;</span>  % Save GRID in a NetCDF file
      <span class="black">save_init = 0;</span>  % Create (and save) INITIAL CONDITIONS (from grid)</span>


{| style="width:100%; background:LightYellow; margin-top:10px; border:1px solid red;" cellpadding="3" cellspacing="0"
|-
|{{warning}} <span class="red">WARNING:</span> Running EASYGRID with <span class="red">create_grid</span> '''ON''' will reset the land/sea mask, which means you will '''LOOSE''' the manual modifications that you did on your mask.
|}
<br>
<br>
Then, run EASYGRID to launch the ''Mask-Editing interactive plot.'' You can change sea-cells into land-cells (and vice versa) by clicking on them with your mouse's LEFT-BUTTON. When you are done, simple click on your mouse's <span class="red">RIGHT-BUTTON TO FINISH</span> (i.e. exit toggle mode). If you want to return to toggle mode, simple run EASYGRID again.
<br>
<br>
{| style="width:100%; background:LightYellow; margin-top:10px; border:1px solid red;" cellpadding="3" cellspacing="0"
|-
|{{note}} To '''Zoom-In, Zoom-Out or Pan''' your land/sea-mask plot, you have to '''(1)''' exit cell-toggle mode by clicking the RIGHT-BUTTON of your mouse, '''(2)''' zoom-in, zoom-out or pan the plot and '''(3)''' RESUME mask-editing by re-running EASYGRID.
|}
<br>
<br>
====Masking Criteria====


If you need to add another initial-condition variable... (1) add in the <font color="green">INITIAL CONDITIONS</font> section of the <font color="green">USER SETTINGS</font>:
# Mask 1-cell bays (in the figure below, see circles A and B as examples)
new_variable = 0; <span class="green">% Variable description (units)</span>
# Mask disconnected lakes (in the figure below, see circle C as an example)
 
# Although tiny islands apparently don't cause troubles... you may want to unmask "islands" that you consider unrealistic or unnecessary (in the figure below, see circles D and E as examples)
 
and (2) add the following snippet to the '''end''' of the <span class="red">easygrid.m</span> file <small>(substitute the parts in red)</small>
<span class="green">%--------------------------------------------------------------------------</span>
        dims                    = { <span class="purple">'time'; 's_rho'; 'eta_rho'; 'xi_rho'</span>};
        nc{ <span class="red">'newvar'</span>}          = ncdouble(dims);
        nc{ <span class="red">'newvar'</span>}(:,:,:)    = ones(N,Mp,Lp).* <span class="red">'new_variable'</span>;
        nc{ <span class="red">'newvar'</span>}.time      = <span class="purple">'ocean_time'</span> ;


[[image:Fjord_editmask1.jpg]]
<br>
<br>
<br>
{{warning}} <span class="red">WARNING:</span> The dimensions of the new initial-conditions variable should be the same as the grid that will use it. For example, the ''u momentum'' initial-condition matrix should have the same dimensions as the u-grid. In a biological setting however, most of the newly-specified variables are likely to be used by the rho-grid.
<br>
<br>
<br>
<br>
===Parameter output on screen===
===Parameter output on screen===
If screen_output is turned ON (in the <span class="green">USER SETTINGS</span> section), EASYGRID will output some parameters to screen. Make sure you write this numbers (Lm, MM, N and DT) since you will need to enter them in the <span class="red">ocean.in</span> file prior to running ROMS.
If <span class="red">screen_output</span> is turned ON (in the <span class="green">USER SETTINGS</span> section), EASYGRID will output some parameters to screen. Make sure you write this numbers (Lm, MM, N and DT) since you will need to enter them in the <span class="red">roms.in</span> file prior to running ROMS.
  |  COPY-PASTE the following parameters into your ocean.in file
  |  COPY-PASTE the following parameters into your roms.in file
  |  ----------------------------------------------------------------------------------------------
  |  ----------------------------------------------------------------------------------------------
  |
  |
Line 300: Line 345:
  |
  |
  |
  |
  |  Make sure the Baroclinic time-step (DT) in your ocean.in file is less than: 3.3882 seconds
  |  Make sure the Baroclinic time-step (DT) in your roms.in file is less than: 11.2939 seconds
  |  ----------------------------------------------------------------------------------------------
  |  ----------------------------------------------------------------------------------------------
*The parameters <span class="red">Lm</span>, <span class="red">Mm</span> and <span class="red">N</span> are the basically the dimensions of the RHO-grid.  
*The parameters <span class="red">Lm</span>, <span class="red">Mm</span> and <span class="red">N</span> are the basically the dimensions of the RHO-grid.  
*The parameter <span class="red">DT</span> is the baroclinic time-step and it should be less than <span class="red">SQRT( (dx^2+dy^2)/(g*h(x,y) )</span>. EASYGRID solves this equation and tells you the result (3.3882 sec in the case above). You can read a bit more about this in [https://www.myroms.org/forum/viewtopic.php?t=850&postdays=0&postorder=asc&start=0 this forum post] (middle of page).
*The parameter <span class="red">DT</span> is the baroclinic time-step and it should be less than <span class="red">SQRT( (dx^2+dy^2)/(g*h(x,y) )</span>. EASYGRID solves this equation and tells you the result (11.2939 sec in the case above). You can read a bit more about this in [https://www.myroms.org/forum/viewtopic.php?t=850&postdays=0&postorder=asc&start=0 this forum post] (middle of page).
<br>
<br>
<br>
<br>
<br>


===Saving .nc files===
===Saving GRID to .nc file===
Once you got your grid in place, your bathymetry smoothed and your initial-conditions adjusted... it is time to save the NetCDF files for ROMS. To do this, simply turn on ALL the Switches in the <font color="green">USER SETTING</font> section and run EASYGRID. Besides the plot, this time it will also save the grid and initial conditions .nc files. EASYGRID will also output some parameters to screen. {{warning}}Make sure you write down this numbers (Lm, MM, N and DT), since you will need to enter them in the <span class="red">ocean.in</span> file prior to running ROMS.
Once you got your grid in place, your bathymetry smoothed and your land/sea masks edited... it is time to save your grid in a NetCDF file, which is what ROMS reads. To do this, simply '''TURN ON''' <span class="red">save_grid</span> and re-run EASYGRID.<br><br>
 
{{warning}} <span class="red">WARNING:</span> You may want to make sure <span class="red">create_grid</span>, <span class="red">edit_mask</span> and <span class="red">smooth_grid</span> are '''turned OFF''' since this may ERASE or alter your previous mask-editing or your bathymetry. On the other hand, you may want to make sure <span class="red">screen_output</span> is turned ON so that EASYGRID outputs some parameters to screen (Lm, MM, N and DT), which your should write down, since you will need to enter them in the <span class="red">roms.in</span> file prior to running ROMS.
<br>
<br>
<br>
<br>
<br>


==Editing Masks==
==Making Initial-Conditions file==
After you created your grid.nc file, you will likely need to edit the mask. That is, you will need to change some land-pixes of the mask into sea-pixels... and vice versa. To edit your grid's mask, you can use <span class="red">editmask.m</span> , which is a GUI script included in the [[MEXNC#How to install ROMS Matlab tool-kit?|ROMS Matlab tool-kit]] (inside the rmask directory).
ROMS initialization NetCDF files contain information of the spatial distribution of one (or multiple) variable(s) that ROMS uses at the '''START''' of the simulation. The value of each initialization variable is specified for each corresponding cell in the ROMS grid... hence, inside a typical initial-conditions file, there will be one three-dimensional matrix (matching grid dimensions) for each specified variable. EASYGRID can generate Initial-Conditions NetCDF files for ROMS, however, only in a rudimentary manner... the user can only choose a '''single value''' for each initial-condition variable... EASYGRID makes each variable '''CONSTANT''' over the entire grid domain. This may be only useful in some simple cases and to do "quick-tests".
 
To change the value of a initial-condition variable, simply go to the <font color="green">INITIAL CONDITIONS</font> section in the <font color="green">USER SETTINGS</font> and change the value of the variable of interest.
 


{| style="width:100%; background:LightYellow; margin-top:10px; border:1px solid red;" cellpadding="1" cellspacing="0"
If you need to add another initial-condition variable... (1) add in the <font color="green">INITIAL CONDITIONS</font> section of the <font color="green">USER SETTINGS</font>:
|-
new_variable = 0; <span class="green">% Variable description (units)</span>
|{{warning}} The current version of editmask.m (from the ROMS toolkit) doesn't work for me. I included in the [http://easygrid4roms.googlecode.com/files/EASYGRID_v1.rar EASYGRID_v1.rar]  file (that you probably already downloaded) a revised version of <span class="red">editmask.m</span> that works for me.
|}
<br>
<br>


[[image:Fjord_editmask1.jpg|right|800px|]]
'''Here are step-by-step instructions to use <span class="red">editmask.m</span>:'''


*Start the GUI by typing in Matlab's Command Window:
and (2) add the following snippet to the '''end''' of the <span class="green">SAVE INITIAL CONDITIONS FILE</span> section of <span class="red">easygrid.m</span> file <small>(substitute the parts in red)</small>
editmask
<span class="green">%--------------------------------------------------------------------------</span>
* Select the NetCDF grid file to edit (<span class="red">Fjord_grd.nc</span> in this tutorial)
        dims                    = { <span class="purple">'time'; 's_rho'; 'eta_rho'; 'xi_rho'</span>};
* Select the .mat coastline file that corresponds to the grid file (<span class="red">Fjord_coast.mat</span> in this tutorial)
        nc{ <span class="red">'newvar'</span>}          = ncdouble(dims);
* Select "Set Land" ("Edit Mode" section on the right) and <span class="red">mask 1-cell bays</span> like the examples circled in A and B.
        nc{ <span class="red">'newvar'</span>}(:,:,:)    = ones(N,Mp,Lp).* <span class="red">'new_variable'</span>;
* Proceed to <span class="red">mask disconnected lakes</span>, like one in example circled in E.
        nc{ <span class="red">'newvar'</span>}.time      = <span class="purple">'ocean_time'</span> ;
* Although tiny islands apparently don't cause troubles... you may want to select "Set Sea" and unmask "islands" that you consider unrealistic or unnecessary, like the ones circled by C and D.
 
* Once you finished editing the mask, <span class="red">CLICK SAVE</span>. This will update your NetCDF grid file for ROMS.
* Close the GUI.
<br>
<br>
<br>
{{warning}} <span class="red">WARNING:</span> The dimensions of the new initial-conditions variable should be the same as the grid that will use it. For example, the ''u momentum'' initial-condition matrix should have the same dimensions as the u-grid. In a biological setting however, most of the newly-specified variables are likely to be used by the rho-grid.
<br>
<br>
<br>
<br>

Latest revision as of 15:13, 17 July 2019

EASYGRID


EASYGRID is a simple matlab script to make ROMS grids and initialization files. It is an austere grid-making alternative designed as a beginner's tool, yet capable of making grids for realistic applications. Since most of EASYGRID is in one file (easygrid.m), it is easier to follow and understand the steps required to generate a simple grid (i.e. useful as a learning or teaching tool) and also reduces the required steps to get the software up and running (i.e. downloading and compiling dependencies).


This WikiROMS page is mainly a tutorial, where I provide test bathymetry and coastline files so you can experiment with EASYGRID. Also, this page is where I will post news and updates.

QUICK LINKS:
Hosting page at Google-Code
Discussion Forum
NEWS:
24 April 2008: Version 0 is out
Warning WARNING:
EASYGRID v0 is in BETA stage and could have problems. Report HERE not only bugs, but also report successful use. Once the bug:success ratio decreases... I will remove this sign.



Download EASYGRID

  • Download EASYGRID (This download also includes the bathymetry and coastline files required for this tutorial)
  • Extract (i.e. unzip or unpack) the file in a location where it can stay indefinitely.
  • Add the location where you placed EASYGRID to your Matlab search path (see #5 as an example).
  • Dependencies: EASYGRID uses MEXNC, SNCTOOLS and ROMS Matlab tool-kit (only a few scripts like spheriq_dist.m , smth_bath.m , pcolorjw.m).
Note For a tutorial on how to download/install these dependencies, CLICK HERE.



Getting bathymetry

EASYGRID needs a bathymetry .mat file containing 3 vectors (xbathy, ybathy and zbathy), where:

  • xbathy = longitude
  • ybathy = latitude
  • zbathy = depth (positive, in meters... For more information about bathymetry for ROMS, click HERE)
Note NOTE: Vectors xbathy and ybathy are in decimal degrees.


There easiest way to get bathymetry data (that I know) is to use Rich Signell's read_srtm30plus.m Matlab script. Instant bathymetry in 1 line of Matlab code! Click HERE for instructions to get and use read_srtm30plus.m.


Fjord latlon.jpg

The most difficult way to get bathymetry data (that I know) is to scan a chart and then digitize it using your mouse and a digitizing software like Didger (sorry, I am not aware of any good digitizing free software).


For this tutorial, you will need Fjord_bathy.mat. You probably already have this file since it is included in EASYGRID_v0.rar (file from the "Download" section). I created Fjord_bathy.mat by merging two bathymetry files... one high-resolution digitized from a chart and another coarser-resolution using read_srtm30plus.m (see Figure).

Note If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:

load Fjord_bathy.mat
plot(xbathy,ybathy,'.');
xlabel('Longitude');
ylabel('Latitude');
axis square;



Getting coastline

In EASYGRID, the coastline is only used for plotting and is therefore not indispensable. However, it is handy to have a coastline for reference, especially when editing the land/sea mask. For EASYGRID, the coastline should be 2 vectors named "lat" and "lon" (both in units of decimal degrees) contained in a .mat file.


Fjord coast.jpg

One way to get coastline data is at GSHHG. NOAA's Coastline Extractor is no longer available.


For this tutorial, you will need Fjord_coast.mat. You probably already have this file since it is included in EASYGRID_v0.rar (file from the "Download" section). I created Fjord_coast.mat from the digitized chart I used to make the bathymetry file (see Figure).

Note If you want to reproduce this plot as an exercise, copy-paste the following code on Matlab's Command Window:

load Fjord_coast.mat
plot(lon,lat);
xlabel('Longitude');
ylabel('Latitude');
axis square;




Making your grid

You probably will need to run EASYGRID several times in a iterative manner to create, smooth and mask-edit your grid. You can turn ON or OFF different functionalities of EASYGRID (like the mask-editing and bathymetry-smoothing routines) using the SWITCHES located in the USER SETTINGS section, which is the first part of script (after the help lines). Below a snippet from EASYGRID's code that contains the SWITCHES section.

%********************************************************************************************************
% USER SETTINGS *****************************************************************************************
%********************************************************************************************************
%
% -------------------------------------------------------------------------
% SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
% -------------------------------------------------------------------------
   create_grid = 1;   % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %   existing on Workspace)
     plot_grid = 1;   % Plot grid
   smooth_grid = 1;   % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
                      %   to the bathymetry
     edit_mask = 0;   % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %   land-pixels and vice-versa 
 screen_output = 1;   % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file    
     save_grid = 1;   % Save GRID in a NetCDF file
     save_init = 1;   % Create (and save) INITIAL CONDITIONS (from grid)




NoteA typical procedure to create a grid will follow (more or less) these steps:

  1. TURN ON create_grid and plot_grid (and turn off ALL other switches) and run EASYGRID.
  2. Tune-up Geographical and Grid parameters and run EASYGRID again.
  3. Repeat step 2 above until satisfied with the grid location, size and resolution.
  4. TURN OFF create_grid and proceed to smooth bathymetry by turning ON smooth_grid and re-running EASYGRID.
  5. Tune-up smoothing parameters and repeat the step above as many times as necessary... when finished, turn OFF smooth_grid.
  6. Edit land/sea mask by turning ON edit_mask and re-running EASYGRID.
  7. Tune-up the land/sea mask as many times as necessary... when done, turn OFF edit_mask.
  8. When satisfied with the grid, bathymetry and mask... save it all to a GRID NetCDF file by turnning ON save_grid and re-running EASYGRID one more time.



Setting up USER SETTINGS

EASYGRID's USER SETTINGS section is where you can change the parameters needed to create your grid and initialization files. To make things easier for you, there are detailed instructions and explanations beside each variable entry line in the USER SETTINGS. In fact, most of the "user-manual" for EASYGRID is included within itself. Therefore I will simply copy-paste below a snippet from EASYGRID's code that contains the USER SETTINGS/instructions section.

Note NOTE: The default settings in EASYGRID are for the Fjord tidal case, hence you can just run EASYGRID (using the included Fjord_bathy.mat and Fjord_coast.mat files) to generate the grid and initial-conditions files required for the Fjord tidal case tutorial.

%********************************************************************************************************
% USER SETTINGS *****************************************************************************************
%********************************************************************************************************
%
% -------------------------------------------------------------------------
% SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
% -------------------------------------------------------------------------
   create_grid = 1;   % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %   existing on Workspace)
     plot_grid = 1;   % Plot grid
   smooth_grid = 1;   % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
                      %   to the bathymetry
     edit_mask = 0;   % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %   land-pixels and vice-versa 
 screen_output = 1;   % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file    
     save_grid = 1;   % Save GRID in a NetCDF file
     save_init = 1;   % Create (and save) INITIAL CONDITIONS (from grid)
                      % ON = 1; OFF = 0
%    
% -------------------------------------------------------------------------
% GRID SETTINGS -----------------------------------------------------------
% -------------------------------------------------------------------------
%
% Geographical and Grid parameters --------
     lat =  44.8125;          % Latitude  (degrees) of the bottom-left corner of the grid.
     lon = -62.8855;          % Longitude (degrees) of the bottom-left corner of the grid. 
%
       X = 9100;              % Width of domain (meters)
       Y = 2550;              % Length of domain (meters)
rotangle = -43;               % Angle (degrees) to rotate the grid conterclock-wise
   resol = 100;               % Cell width and height (i.e. Resolution)in meters. Grid cells are
                              %   forced to be (almost) square.
       N = 10;                % Number of vertical levels
%    
%     
% Bathymetry --------------   % Bathymetry for ROMS is measured positive downwards (zeros are not allowed)
                              %   see: https://www.myroms.org/wiki/index.php/Grid_Generation#Bathymetry
                              %   To allow variations in surface elevation (eg. tides) while keeping all
                              %   depths positive, an arbitrary offset (see minh below) is added to the
                              %   depth vector.
%      
      hh = nan;               % Analytical Depth (meters) used to create a uniform-depth grid. If using a
                              %   bathymetry file, leave hh = nan;
    minh = 4;                 % Arbitrary depth offset in meters (see above). minh should be a little more
                              %   than the maximum expected tidal variation.
   Bathy = 'Fjord_bathy.mat'; % Bathymetry file. If using the analytical depth above (i.e. hh ~= nan), then
                              %   Bathy will not be used. The bathymetry file should be a .mat file containing
                              %   3 vectors (xbathy, ybathy and zbathy). where xbathy = Longitude,
                              %   ybathy = Latitude and zbathy = depth (positive, in meters). xbathy and ybathy
                              %   are in decimal degrees See: http://en.wikipedia.org/wiki/Decimal_degrees

       % Bathymetry smoothing routine...  See "Switches section" (above) to turn this ON or OFF
       if smooth_grid == 1;
           order = 2;       % Order of Shapiro filter (2,4,8)... default: 2
            rlim = 0.35;    % Maximum r-factor allowed (0.35)... default: 0.35
           npass = 50;      % Maximum number of passes.......... default: 50
       end
%---------------------------------
%                      
%
% Coastline ----------------------
   Coast = load('Fjord_coast.mat'); % If there isn't a coastline file... comment-out this line:
                                    %   e.g. %Coast = load('Fjord_coast.mat'); The coastline is only used for
                                    %   plotting. The coastline .mat file should contain 2 vectors named
                                    %   "lat" and "lon"
%                                    
%      
% -------------------------------------------------------------------------
% OUTPUT: File naming and NetCDF descriptors ------------------------------
% -------------------------------------------------------------------------
Grid_filename = 'Fjord'; 	   % Filename for grid and initial conditions files (don't include extension). 
                                   %   "_grd.nc" is added to grid file and "_ini.nc" is added to initial
                                   %   conditions file

Descrip_grd   = 'Test grid';               %Description for grid .nc file
Descrip_ini   = 'Test initial conditions'; %Description for initial conditions .nc file
Author        = 'John Smith';
Computer      = 'My Computer';
%
% -------------------------------------------------------------------------
% INITIAL CONDITIONS ------------------------------------------------------
% -------------------------------------------------------------------------
if save_init == 1; % See "Switches section" (above) to turn this ON or OFF
    % Initial conditions will be constant throughout the grid domain
    %--------------------------------------------------------------------------
    NH4          = 0.1;     % Ammonium concentration (millimole_NH4 meter-3)
    NO3          = 10;      % Nitrate concentration (millimole_N03 meter-3)
    chlorophyll1 = 0.3;     % Chlorophyll concentration in small phytoplankyon (milligrams_chlorophyll meter-3)
    chlorophyll2 = 0.3;     % Chlorophyll concentration in large phytoplankyon (milligrams_chlorophyll meter-3)
    detritus1    = 0.03;    % Small detritus concentration (millimole_nitrogen meter-3)
    detritus2    = 0.03;    % Large detritus concentration (millimole_nitrogen meter-3)
    detritusC1   = 1;       % Small detritus carbon concentration (millimole_carbon meter-3)
    detritusC2   = 0.2;     % Large detritus carbon concentration (millimole_carbon meter-3)
    phyto1       = 0.02;    % Small phytoplankton concentration (millimole_nitrogen meter-3)
    phyto2       = 0.02;    % Large phytoplankton concentration (millimole_nitrogen meter-3)
    phytoC1      = 0.2;     % Small phytoplankton carbon concentration (millimole_carbon meter-3)
    phytoC2      = 0.1;     % Small phytoplankton carbon concentration (millimole_carbon meter-3)
    salt         = 30;      % Salinity (PSU)
    temp         = 9;       % Potential temperature (Celsius)
    u            = 0;       % u-momentum component (meter second-1)
    ubar         = 0;       % Vertically integrated u-momentum component (meter second-1)
    v            = 0;       % v-momentum component (meter second-1)
    vbar         = 0;       % Vertically integrated v-momentum component (meter second-1)
    zeta         = 0;       % Free-surface (meters)
    zooplankton  = 0.01;    % Zooplankton concentration "millimole_nitrogen meter-3"
    zooplanktonC = 0.5;     % Zooplankton carbon concentration "millimole_carbon meter-3"
    %--------------------------------------------------------------------------
end
%
%
%********************************************************************************************************
% END OF USER SETTINGS **********************************************************************************
%********************************************************************************************************

Note NOTE: You may want to change the name of easygrid.m to a name more descriptive of your grid (example: easygrid_fjord.m). That way you can keep many copies of easygrid.m, each with the parameters of each of your different projects.

Geographical/Grid parameters

After you got the bathymetry and coastline of your study region, now it is time to place a grid on it... In the USER SETTINGS section, you have to specify lat, lon, X, Y and rotangle. This is done in an iterative manner, where first you input your best-guesses, then you run EASYGRID to plot the grid. From the plot you can adjust your geographical/grid parameters... plot... adjust... plot... adjust... and so on.

Note You may want to turn off some switches (see below) to speed up the plotting process.

% -------------------------------------------------------------------------
% SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
% -------------------------------------------------------------------------
   create_grid = 1;   % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %   existing on Workspace)
     plot_grid = 1;   % Plot grid
   smooth_grid = 0;   % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
                      %   to the bathymetry
     edit_mask = 0;   % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %   land-pixels and vice-versa 
 screen_output = 0;   % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file    
     save_grid = 0;   % Save GRID in a NetCDF file
     save_init = 0;   % Create (and save) INITIAL CONDITIONS (from grid)


Fjord NOTsmooth.jpg
This is the resulting grid (without smoothing) if you run EASYGRID with the default settings.
NoteIf you want to see the 4 different grids that ROMS uses, zoom-in (in the grid plot), and then copy-paste the following in Matlab's Command Window:
plot(lon_rho,lat_rho,'r.')
plot(lon_u,lat_u,'bv')
plot(lon_v,lat_v,'g^')
plot(lon_psi,lat_psi,'m+')
  • The rho-grid represents the grid centers (red dots)
  • The u-grid represents the grid East-West sides (blue triangles)
  • The v-grid represents the grid North-South sides (green triangles)
  • The psi-grid represents the grid corners (purple crosses)
Fjord grid.jpg




Bathymetry smoothing

ROMS doesn't like rough bathymetry with abrupt changes in topography. Therefore, after you got your grid where you wanted it to be, the next step is to smooth the bathymetry. Turn ON the smooth_grid variable in the SWITCHES section. Usually simply enabling smoothing (with the default settings) will do a pretty good job. But if unsatisfied, you can iteratively tweak the parameters in the %Bathymetry smoothing section of the USER SETTINGS until obtaining the desired smoothness. Below is a comparison of grids without and with smoothing (default settings).

Fjord NOTsmoothNsmooth.jpg





Editing Masks

Since the land/sea mask is automatically created using the bathymetry, it is very likely a few pixels will be wrongly assigned as land or sea. If so, you will need to edit your land/sea mask... and to do this, you can use EASYGRID's Mask-Editing interactive plot, which is a plot of the land/sea mask that lets you (interactive) use your mouse's left-button to toggle land-cells into sea-cells... and vice versa.

First, TURN ON edit_mask and TURN OFF create_grid.

% -------------------------------------------------------------------------
% SWITCHES ( ON = 1; OFF = 0 ) --------------------------------------------
% -------------------------------------------------------------------------
   create_grid = 0;   % Create GRID. Turn OFF to work with a previously created grid (i.e. grid variables
                      %   existing on Workspace)
     plot_grid = 0;   % Plot grid
   smooth_grid = 0;   % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter
                      %   to the bathymetry
     edit_mask = 1;   % Edit rho-mask using interactive plot. Use this to manually change sea-pixels into
                      %   land-pixels and vice-versa 
 screen_output = 0;   % Displays (on screen) many parameters that need to be copy-pasted in the roms.in file    
     save_grid = 0;   % Save GRID in a NetCDF file
     save_init = 0;   % Create (and save) INITIAL CONDITIONS (from grid)
Warning WARNING: Running EASYGRID with create_grid ON will reset the land/sea mask, which means you will LOOSE the manual modifications that you did on your mask.



Then, run EASYGRID to launch the Mask-Editing interactive plot. You can change sea-cells into land-cells (and vice versa) by clicking on them with your mouse's LEFT-BUTTON. When you are done, simple click on your mouse's RIGHT-BUTTON TO FINISH (i.e. exit toggle mode). If you want to return to toggle mode, simple run EASYGRID again.

Note To Zoom-In, Zoom-Out or Pan your land/sea-mask plot, you have to (1) exit cell-toggle mode by clicking the RIGHT-BUTTON of your mouse, (2) zoom-in, zoom-out or pan the plot and (3) RESUME mask-editing by re-running EASYGRID.



Masking Criteria

  1. Mask 1-cell bays (in the figure below, see circles A and B as examples)
  2. Mask disconnected lakes (in the figure below, see circle C as an example)
  3. Although tiny islands apparently don't cause troubles... you may want to unmask "islands" that you consider unrealistic or unnecessary (in the figure below, see circles D and E as examples)

Fjord editmask1.jpg



Parameter output on screen

If screen_output is turned ON (in the USER SETTINGS section), EASYGRID will output some parameters to screen. Make sure you write this numbers (Lm, MM, N and DT) since you will need to enter them in the roms.in file prior to running ROMS.

|  COPY-PASTE the following parameters into your roms.in file
|  ----------------------------------------------------------------------------------------------
|
|
|     Lm == 90         ! Number of I-direction INTERIOR RHO-points
|     Mm == 24         ! Number of J-direction INTERIOR RHO-points
|      N == 10         ! Number of vertical levels
|
|
|  Make sure the Baroclinic time-step (DT) in your roms.in file is less than: 11.2939 seconds
|  ----------------------------------------------------------------------------------------------
  • The parameters Lm, Mm and N are the basically the dimensions of the RHO-grid.
  • The parameter DT is the baroclinic time-step and it should be less than SQRT( (dx^2+dy^2)/(g*h(x,y) ). EASYGRID solves this equation and tells you the result (11.2939 sec in the case above). You can read a bit more about this in this forum post (middle of page).




Saving GRID to .nc file

Once you got your grid in place, your bathymetry smoothed and your land/sea masks edited... it is time to save your grid in a NetCDF file, which is what ROMS reads. To do this, simply TURN ON save_grid and re-run EASYGRID.

Warning WARNING: You may want to make sure create_grid, edit_mask and smooth_grid are turned OFF since this may ERASE or alter your previous mask-editing or your bathymetry. On the other hand, you may want to make sure screen_output is turned ON so that EASYGRID outputs some parameters to screen (Lm, MM, N and DT), which your should write down, since you will need to enter them in the roms.in file prior to running ROMS.


Making Initial-Conditions file

ROMS initialization NetCDF files contain information of the spatial distribution of one (or multiple) variable(s) that ROMS uses at the START of the simulation. The value of each initialization variable is specified for each corresponding cell in the ROMS grid... hence, inside a typical initial-conditions file, there will be one three-dimensional matrix (matching grid dimensions) for each specified variable. EASYGRID can generate Initial-Conditions NetCDF files for ROMS, however, only in a rudimentary manner... the user can only choose a single value for each initial-condition variable... EASYGRID makes each variable CONSTANT over the entire grid domain. This may be only useful in some simple cases and to do "quick-tests".


To change the value of a initial-condition variable, simply go to the INITIAL CONDITIONS section in the USER SETTINGS and change the value of the variable of interest.


If you need to add another initial-condition variable... (1) add in the INITIAL CONDITIONS section of the USER SETTINGS:

new_variable = 0; % Variable description (units)


and (2) add the following snippet to the end of the SAVE INITIAL CONDITIONS FILE section of easygrid.m file (substitute the parts in red)

%--------------------------------------------------------------------------
       dims                    = { 'time'; 's_rho'; 'eta_rho'; 'xi_rho'};
       nc{ 'newvar'}           = ncdouble(dims);
       nc{ 'newvar'}(:,:,:)    = ones(N,Mp,Lp).* 'new_variable';
       nc{ 'newvar'}.time      = 'ocean_time' ;


Warning WARNING: The dimensions of the new initial-conditions variable should be the same as the grid that will use it. For example, the u momentum initial-condition matrix should have the same dimensions as the u-grid. In a biological setting however, most of the newly-specified variables are likely to be used by the rho-grid.





Note This concludes this tutorial. However, you should consider reviewing the Tidal Fjord TUTORIAL, which uses the grid and initial-condition files generated here to setup a simple tidal realistic application.