Difference between revisions of "easygrid"
m (Text replacement - "ocean.in" to "roms.in") (change visibility) |
|||
(3 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
<div class="title">EASYGRID</div> | <div class="title">EASYGRID</div> | ||
<br> | <br> | ||
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 11: | 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>[ | |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 | ||
Line 22: | Line 21: | ||
==Download EASYGRID== | ==Download EASYGRID== | ||
*[ | *[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 | *<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 46: | 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 [ | 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 55: | 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>; | ||
==Getting coastline== | ==Getting coastline== | ||
In EASYGRID, the coastline is only used for plotting and | 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|]] | ||
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 [ | 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 83: | 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 | <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 117: | Line 122: | ||
{{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">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">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_init = 1;</span> % Create (and save) INITIAL CONDITIONS (from grid) | |||
% ON = 1; OFF = 0 | |||
% | % | ||
% ------------------------------------------------------------------------- | % ------------------------------------------------------------------------- | ||
Line 138: | Line 146: | ||
% | % | ||
% Geographical and Grid parameters -------- | % Geographical and Grid parameters -------- | ||
<span class="black">lat = 44.8125;</span> | <span class="black">lat = 44.8125;</span> % Latitude (degrees) of the bottom-left corner of the grid. | ||
<span class="black">lon = -62.8855;</span> | <span class="black">lon = -62.8855;</span> % Longitude (degrees) of the bottom-left corner of the grid. | ||
% | % | ||
<span class="black">X = 9100;</span> | <span class="black">X = 9100;</span> % Width of domain (meters) | ||
<span class="black">Y = 2550;</span> | <span class="black">Y = 2550;</span> % Length of domain (meters) | ||
<span class="black">rotangle = -43;</span> | <span class="black">rotangle = -43;</span> % Angle (degrees) to rotate the grid conterclock-wise | ||
<span class="black">resol = 100;</span> | <span class="black">resol = 100;</span> % Cell width and height (i.e. Resolution)in meters. Grid cells are | ||
<span class="black">N = 10;</span> | % 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) | ||
% 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. | |||
% | % | ||
<span class="black">hh = nan;</span> | <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> | % 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 | ||
% than the maximum expected tidal variation. | |||
<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 167: | 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: | ||
% 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 175: | 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 | |||
<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 212: | Line 232: | ||
% | % | ||
% | % | ||
% | %******************************************************************************************************** | ||
% END OF USER SETTINGS | % END OF USER SETTINGS ********************************************************************************** | ||
%******************************************************************************************************** | %******************************************************************************************************** | ||
{{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. | {{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> | ||
Line 226: | 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 | <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 273: | Line 296: | ||
% SWITCHES ( ON = 1; OFF = 0 ) -------------------------------------------- | % 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">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">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">smooth_grid = 0;</span> % Smooth bathymetry using H. Arango's smth_bath.m , which applies a Shapiro filter | ||
<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 | % to the bathymetry | ||
<span class="black">screen_output = 0;</span> % Displays (on screen) many parameters that need to be copy-pasted in the | <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_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 309: | Line 335: | ||
===Parameter output on screen=== | ===Parameter output on screen=== | ||
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"> | 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 | | COPY-PASTE the following parameters into your roms.in file | ||
| ---------------------------------------------------------------------------------------------- | | ---------------------------------------------------------------------------------------------- | ||
| | | | ||
Line 319: | Line 345: | ||
| | | | ||
| | | | ||
| Make sure the Baroclinic time-step (DT) in your | | 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. | ||
Line 329: | Line 355: | ||
===Saving GRID to .nc file=== | ===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''' <span class="red">save_grid</span> and re-run EASYGRID.<br><br> | 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"> | {{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> |
Latest revision as of 15:13, 17 July 2019
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 |
![]() 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).
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: 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.
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).
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.
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).
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)
A typical procedure to create a grid will follow (more or less) these steps:
- TURN ON create_grid and plot_grid (and turn off ALL other switches) and run EASYGRID.
- Tune-up Geographical and Grid parameters and run EASYGRID again.
- Repeat step 2 above until satisfied with the grid location, size and resolution.
- TURN OFF create_grid and proceed to smooth bathymetry by turning ON smooth_grid and re-running EASYGRID.
- Tune-up smoothing parameters and repeat the step above as many times as necessary... when finished, turn OFF smooth_grid.
- Edit land/sea mask by turning ON edit_mask and re-running EASYGRID.
- Tune-up the land/sea mask as many times as necessary... when done, turn OFF edit_mask.
- 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: 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: 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.
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)
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).
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)
![]() |
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.
Masking Criteria
- Mask 1-cell bays (in the figure below, see circles A and B as examples)
- 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)
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: 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: 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.
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.