| 1 |
<HTML> |
|---|
| 2 |
<HEAD> |
|---|
| 3 |
|
|---|
| 4 |
</HEAD> |
|---|
| 5 |
<BODY TEXT="#FFFFFF" |
|---|
| 6 |
BGCOLOR="#000000" |
|---|
| 7 |
LINK="#0000EE" |
|---|
| 8 |
VLINK="#551A8B" |
|---|
| 9 |
ALINK="#FF0000"> |
|---|
| 10 |
|
|---|
| 11 |
<TITLE>FDCONT Version 1.0 (Beta) Documentation Pages</TITLE> |
|---|
| 12 |
|
|---|
| 13 |
|
|---|
| 14 |
<B><font color="#ff0000" size=+2>FDCONT 1.0 </font> - a finite difference |
|---|
| 15 |
based contouring and vector plotting facility |
|---|
| 16 |
for FEM 2-D scalar and vector fields for the DARTMOUTH series of |
|---|
| 17 |
finite element shallow water models.</B> |
|---|
| 18 |
|
|---|
| 19 |
<br><br><br><br> |
|---|
| 20 |
|
|---|
| 21 |
<table border=0 cellspacing=1 width=800> |
|---|
| 22 |
<tr> |
|---|
| 23 |
<td width=50%> |
|---|
| 24 |
<p> |
|---|
| 25 |
One problem with generating colorbanded contour plots in MATLAB |
|---|
| 26 |
is that the resolution of typical FEM meshes tends to burden MATLAB |
|---|
| 27 |
when it comes to producing a postscript version of the figure. Each |
|---|
| 28 |
element in the grid is rendered as a patch object, and if shading |
|---|
| 29 |
is turned on, the rendered postscript file actually looks bad. |
|---|
| 30 |
There is no reasonable way to subsample the FEM nodes. |
|---|
| 31 |
|
|---|
| 32 |
The purpose of FDCONT is to provide contouring and vector plotting |
|---|
| 33 |
routines that map FEM node-based data to a finite-difference grid that |
|---|
| 34 |
covers the FEM domain at an arbitrary level of resolution. The |
|---|
| 35 |
resulting figure is better handled by MATLAB regarding postscript |
|---|
| 36 |
printing, and the results are "publication quality". |
|---|
| 37 |
|
|---|
| 38 |
<td> |
|---|
| 39 |
<IMG SRC="fig.gif" ALIGN=center> |
|---|
| 40 |
|
|---|
| 41 |
</table> |
|---|
| 42 |
|
|---|
| 43 |
<P> FDCONT is written by Dr. Christopher E. Naimie and Brian |
|---|
| 44 |
O. Blanton, is implemented entirely in MATLAB5.1 or higher, and is based |
|---|
| 45 |
on Christopher E. Naimie's hybrid FORTRAN/MATLAB colorbanding routines. |
|---|
| 46 |
|
|---|
| 47 |
<P> FDCONT is packaged separately from the rest of OPNML/MATLAB, but |
|---|
| 48 |
it <font color="#FF0000">REQUIRES</font> several routines from the latest |
|---|
| 49 |
OPNML toolbox. Go to the <a |
|---|
| 50 |
href="http://www.opnml.unc.edu/OPNML_Matlab/index.html">OPNML/MATLAB</a> webpabes |
|---|
| 51 |
for downloading information. |
|---|
| 52 |
|
|---|
| 53 |
|
|---|
| 54 |
<p>These web pages describe the FDCONT routines and provide a |
|---|
| 55 |
brief demonstration and an example that generates a figure silimar to |
|---|
| 56 |
the one above. |
|---|
| 57 |
Familiarity with the OPNML/MATLAB routines is assumed, which uses |
|---|
| 58 |
MATLAB5's structure facility for the grid information i |
|---|
| 59 |
(<tt>‹fem_grid_struct></tt>). |
|---|
| 60 |
|
|---|
| 61 |
<p> See a |
|---|
| 62 |
<a |
|---|
| 63 |
href="http://www-nml.dartmouth.edu/~naimie/NML_REPORTS/NML-98-10/NML-98-10.html" |
|---|
| 64 |
>webpage</a> |
|---|
| 65 |
of Chris's for figures generated with these tools. |
|---|
| 66 |
|
|---|
| 67 |
<hr> |
|---|
| 68 |
<h4> FDCONT function descriptions</h4> |
|---|
| 69 |
<b><pre> |
|---|
| 70 |
FDVECTOR - plot vectors from a bfd sampling. |
|---|
| 71 |
FDCONTOUR - contour FE scalar on FD grid |
|---|
| 72 |
FE2FD - interpolate FE data to FD nodes contained in bfd array |
|---|
| 73 |
GENBFD - generate a "basis function data" file for FD contouring |
|---|
| 74 |
LNDFILL - draw land polygons for FEM domain |
|---|
| 75 |
LNDMAKE - create land masking information for FD CONTOURING |
|---|
| 76 |
READ_BEL - read a FEM domain .bel file |
|---|
| 77 |
</pre></b> |
|---|
| 78 |
<p> |
|---|
| 79 |
<b>Synopsis:</b> |
|---|
| 80 |
FDCONT works as follows: an evenly spaced grid is placed on top of |
|---|
| 81 |
the FEM domain, the FEM-based fields are interpolated to these |
|---|
| 82 |
FD points, vectors are plotted, contours are drawn, and then the |
|---|
| 83 |
FD points that lie outside the FEM domain are masked out by a |
|---|
| 84 |
polygon that describes where the FEM boundary lies. |
|---|
| 85 |
|
|---|
| 86 |
<hr> |
|---|
| 87 |
|
|---|
| 88 |
<h2><b> Preliminary Steps:</b></h2> The contouring in FDCONT works by |
|---|
| 89 |
interpolating the FEM data to the regular grid, contouring with |
|---|
| 90 |
CONTOURF, and then covering up the part of the figure that lies outside |
|---|
| 91 |
of the FEM domain. The first step is thus to generate the information |
|---|
| 92 |
needed by FDCONTOUR to mask out the exterior of the FEM domain. |
|---|
| 93 |
|
|---|
| 94 |
<p><b>LNDMAKE</b> |
|---|
| 95 |
<table border=0 cellspacing=7 width=800> |
|---|
| 96 |
<tr> |
|---|
| 97 |
<td> |
|---|
| 98 |
The function LNDMAKE |
|---|
| 99 |
takes as input a <tt>fem_grid_struct</tt> and a <tt>.bel</tt> filename (QUODDY |
|---|
| 100 |
boundary element file) and outputs to disk two files, |
|---|
| 101 |
<tt>‹gridname>.lnd</tt> |
|---|
| 102 |
and <tt>‹gridname>.lbe</tt>. These files are node and element lists for a polygon |
|---|
| 103 |
that encloses the FEM domain and need only be generated once per |
|---|
| 104 |
domain. They can be placed in the standard location for the given grid, |
|---|
| 105 |
since the OPNML/MATLAB function LOADGRID now searches for these files along |
|---|
| 106 |
with the standard grid files. Alternatively, LOADGRID will search the |
|---|
| 107 |
current working directory for <tt> ‹gridname>.lnd.lnd</tt> and |
|---|
| 108 |
<tt>‹gridname>.lnd.lbe</tt> in case the |
|---|
| 109 |
user chooses to keep these new file locally. LOADGRID attaches two new |
|---|
| 110 |
fields to the <tt>fem_grid_struct</tt>, |
|---|
| 111 |
<tt>fem_grid_struct.lnd</tt> and <tt>fem_grid_struct.lbe</tt>. |
|---|
| 112 |
Subsequent calls to FDCONTOUR require that the land description fields of the |
|---|
| 113 |
<tt>‹fem_grid_struct></tt> be filled. |
|---|
| 114 |
At present. the <tt>.bel</tt> file must be ordered with the exterior |
|---|
| 115 |
boundary counterclockwise, starting from the western-most |
|---|
| 116 |
boundary node. Islands follow, connected. The OPNML boundary |
|---|
| 117 |
file generator (as well as the fortran code CONVCODES) outputs |
|---|
| 118 |
the .bel file in this order. If the resulting figure looks |
|---|
| 119 |
wrong, then read the .bel file into GENBEL and output is to |
|---|
| 120 |
a new file name. Pass this new file namd to LNDMAKE. |
|---|
| 121 |
This requirement will be removed in future versions of FDCONT. |
|---|
| 122 |
|
|---|
| 123 |
|
|---|
| 124 |
<td> |
|---|
| 125 |
|
|---|
| 126 |
<img src="fig2.gif" ALIGN=right> |
|---|
| 127 |
</table> |
|---|
| 128 |
<p> |
|---|
| 129 |
Assuming we have a FEM domain loaded into the structure variable |
|---|
| 130 |
<tt>g2s</tt>, then to generate the land description for the long/lat g2s.5b |
|---|
| 131 |
FEM domain, where <tt>g2sll</tt> is the <tt>fem_grid_struct</tt> for the FEM domain, and |
|---|
| 132 |
<tt>g2s.5bll.tides.bel</tt> is a boundary element file for the |
|---|
| 133 |
<tt>g2s.5b</tt> |
|---|
| 134 |
grid, type: |
|---|
| 135 |
<pre> |
|---|
| 136 |
>> lndmake(g2sll,'g2s.5bll.tides.bel') |
|---|
| 137 |
</pre> |
|---|
| 138 |
LNDMAKE writes the files <tt>g2s.5b.lnd</tt> and <tt>g2s.5b.lbe</tt> to the current |
|---|
| 139 |
working directory and displays the land polygons in a figure like the one |
|---|
| 140 |
above. |
|---|
| 141 |
|
|---|
| 142 |
<hr> |
|---|
| 143 |
<H2>Loading the Land Description files</h2> |
|---|
| 144 |
Consider that the above LNDMAKE procedure is done only once per grid. |
|---|
| 145 |
The next time the grid is loaded with LOADGRID, the new land description |
|---|
| 146 |
fields will be filled. (Notice that the |
|---|
| 147 |
<tt>fem_grid_struct</tt> <tt>g2s</tt> now contains the new fields .lnd and .lbe): |
|---|
| 148 |
<pre> |
|---|
| 149 |
>> g2s=loadgrid('g2s.5bll') |
|---|
| 150 |
Searching locally ... |
|---|
| 151 |
Got g2s.5bll.nod |
|---|
| 152 |
Got g2s.5bll.ele |
|---|
| 153 |
Got g2s.5bll.bat |
|---|
| 154 |
g2s.5bll.bnd not found; computing from g2s.5bll.ele. |
|---|
| 155 |
Got g2s.5bll.lnd |
|---|
| 156 |
Got g2s.5bll.lbe |
|---|
| 157 |
</pre> |
|---|
| 158 |
|
|---|
| 159 |
<hr> |
|---|
| 160 |
<H2>FD node generation: GENBFD</h2> |
|---|
| 161 |
The contouring routine FDCONTOUR needs basis function information |
|---|
| 162 |
for each FD node. This information is contained in a "bfd" array, |
|---|
| 163 |
for <font color="#ff0000">b</font>asis <font color="#ff0000">f</font>unction |
|---|
| 164 |
<font color="#ff0000">d</font>ata. GENBFD generates this array, given a |
|---|
| 165 |
FEM domain and discretization levels. Optionally, GENBFD outputs |
|---|
| 166 |
the array to disk since once an interpolation resolution is |
|---|
| 167 |
decided upon, the basis information does not change. Deciding on |
|---|
| 168 |
the final resolution is up to the user. |
|---|
| 169 |
|
|---|
| 170 |
<pre> |
|---|
| 171 |
>> bfd=genbfd(fem_grid_struct,[nx ny],outflag); |
|---|
| 172 |
</pre> |
|---|
| 173 |
<table border=0 cellspacing=7 width=800> |
|---|
| 174 |
<tr> |
|---|
| 175 |
<td> |
|---|
| 176 |
<p> GENBFD is called as: |
|---|
| 177 |
where <tt>[nx ny]</tt> are the number of FD nodes in the x,y directions |
|---|
| 178 |
with which to cover the FEM domain. If only one integer is passed in |
|---|
| 179 |
([nx] as opposed to [nx ny]), then GENBFD generates equally spaced |
|---|
| 180 |
nodes, which is preferable for subsampling vector fields (see below). |
|---|
| 181 |
(Type <tt>>> help genbfd</tt> for more |
|---|
| 182 |
information on the options to GENBFD.) If <tt>outflag==1</tt>, the bfd array is |
|---|
| 183 |
written to disk as gridname.bfd. It is a "flat" file, and an be loaded |
|---|
| 184 |
as <tt>load gridname.bfd</tt>. For example, <tt>>> bfd=genbfd(g2s,[25 25],0)</tt> |
|---|
| 185 |
generates a bfd array called <tt>bfd</tt> from the g2s FEM domain structure, |
|---|
| 186 |
with 25 x 25 nodes, and does NOT output the bfd array to disk. A figure |
|---|
| 187 |
similar to the one on the right is plotted to show the level of discretization. |
|---|
| 188 |
<td> |
|---|
| 189 |
<img src="fig3.gif"> |
|---|
| 190 |
|
|---|
| 191 |
</table> |
|---|
| 192 |
|
|---|
| 193 |
<hr> |
|---|
| 194 |
<h2> FDCONTOUR </h2> Now that we have a bfd array, we can contour something. |
|---|
| 195 |
Assume we have some scalar field (from an .s2r file, for example) called |
|---|
| 196 |
<tt>sfe</tt>. Our bfd array is called <tt>bfd</tt>. FDCONTOUR requires |
|---|
| 197 |
the user to think about the range of the data and the colorband |
|---|
| 198 |
increment; the default is 8 colorbands between <tt>min(sfe)</tt> and |
|---|
| 199 |
<tt>max(sfe)</tt> may not be very satisfactory. |
|---|
| 200 |
These are specified as <tt>qmin, qmax, dq</tt>. Call FDCONTOUR as: |
|---|
| 201 |
<pre> |
|---|
| 202 |
>> fdcontour(bfd,sfe,27,36,1,1) |
|---|
| 203 |
</pre> |
|---|
| 204 |
|
|---|
| 205 |
<table border=0 cellspacing=7 width=800> |
|---|
| 206 |
<tr> |
|---|
| 207 |
<td> |
|---|
| 208 |
The above command tells FDCONTOUR to use the basis information in bfd to interpolate the |
|---|
| 209 |
FE-based array <tt>sfe</tt> (this one happens to be salinity) over the range |
|---|
| 210 |
27-36 at 1 psu increments, and to include a colorbar on the axes. The result: |
|---|
| 211 |
<td> |
|---|
| 212 |
<img src="fig4.gif" ALIGN=center> |
|---|
| 213 |
|
|---|
| 214 |
<tr> |
|---|
| 215 |
|
|---|
| 216 |
<td> |
|---|
| 217 |
Now, recall that the basis information was computed for points that lie |
|---|
| 218 |
OUTSIDE of the FEM domain, so there is information where it isn't supposed |
|---|
| 219 |
to be. Hence the need to mask out the exterior of the FEM grid. This is |
|---|
| 220 |
why we precomputed the land description information. Call the function |
|---|
| 221 |
LNDFILL to get the figure on the right: |
|---|
| 222 |
<pre> |
|---|
| 223 |
>> lndfill(g2s,[1 1 1]*.75) |
|---|
| 224 |
</pre> |
|---|
| 225 |
<td> |
|---|
| 226 |
<img src="fig5.gif" ALIGN=center> |
|---|
| 227 |
|
|---|
| 228 |
<tr> |
|---|
| 229 |
|
|---|
| 230 |
<td> |
|---|
| 231 |
Lastly, overlay the FEM boundary to outline the exterior and |
|---|
| 232 |
island segments (<tt>>> plotbnd(g2s)</tt>): |
|---|
| 233 |
<td> |
|---|
| 234 |
<img src="fig6.gif" ALIGN=center> |
|---|
| 235 |
|
|---|
| 236 |
</table> |
|---|
| 237 |
|
|---|
| 238 |
FDCONTOUR optionally returns handles [c,h,hcb] to the patch and colorbar |
|---|
| 239 |
axes objects, |
|---|
| 240 |
as well as the contour matrix generated by CONTOURF. This latter array |
|---|
| 241 |
can be passed to CLABEL to label the contours. Call as: <tt>clabel(c,h)</tt>. |
|---|
| 242 |
This MUST be done before the land mask is applied. |
|---|
| 243 |
<hr> |
|---|
| 244 |
|
|---|
| 245 |
<table border=0 cellspacing=7 width=800> |
|---|
| 246 |
<tr> |
|---|
| 247 |
<td> |
|---|
| 248 |
|
|---|
| 249 |
<h2>FDVECTOR</H2> |
|---|
| 250 |
FDVECTOR is a front-end to VECPLOT2, which |
|---|
| 251 |
handles the extraction and interpolation of the FEM (u,v) |
|---|
| 252 |
data onto the FD points in bfd. FDVECTOR behaves the same as VECPLOT2, |
|---|
| 253 |
except that the (x,y) vector origins are contained in the bfd file, supplied |
|---|
| 254 |
to FDVECTOR as the first argument. Suppose we have a depth-averaged |
|---|
| 255 |
velocity stored in <tt> ufe vfe </tt>. Then FDVECTOR is called as: |
|---|
| 256 |
<pre> |
|---|
| 257 |
>> fdvector(bfd,ufe,vfe) |
|---|
| 258 |
</pre> |
|---|
| 259 |
<td> |
|---|
| 260 |
<img src="fig7.gif" ALIGN=right> |
|---|
| 261 |
</table> |
|---|
| 262 |
|
|---|
| 263 |
<hr> |
|---|
| 264 |
<H2>Final Example</h2> |
|---|
| 265 |
Suppose that we are unhappy with the resolution above. Here is the |
|---|
| 266 |
sequence of MATLAB commands that generates a nicer figure. GENBFD is |
|---|
| 267 |
recalled with higher (equally spaced) resolution. |
|---|
| 268 |
|
|---|
| 269 |
<table border=0 cellspacing=7 width=800> |
|---|
| 270 |
<tr> |
|---|
| 271 |
<td> |
|---|
| 272 |
|
|---|
| 273 |
<font> |
|---|
| 274 |
<pre> |
|---|
| 275 |
>> bfd=genbfd(g2s,[100],0); |
|---|
| 276 |
>> [c,h]=fdcontour(bfd,sfe,27,36,.5,1); |
|---|
| 277 |
>> clabel(c,h) |
|---|
| 278 |
>> h=lndfill(g2s,[.75 .75 .75]); |
|---|
| 279 |
>> hb=plotbnd(g2s); |
|---|
| 280 |
>> hvec=fdvector(bfd,ufe,vfe,.75,2,... |
|---|
| 281 |
'cm/s',-62,39); |
|---|
| 282 |
>> xlabel('Longitude') |
|---|
| 283 |
>> ylabel('Latitude') |
|---|
| 284 |
</pre></font> |
|---|
| 285 |
<td> |
|---|
| 286 |
<img src="fig8.gif" ALIGN=left> |
|---|
| 287 |
|
|---|
| 288 |
</table> |
|---|
| 289 |
|
|---|
| 290 |
<HR WIDTH="100%">Maintained by: <FONT SIZE=+1>Brian Blanton</FONT> |
|---|
| 291 |
<BR><A HREF="mailto:blanton@marine.unc.edu"> |
|---|
| 292 |
MAIL: |
|---|
| 293 |
blanton@marine.unc.edu</a> |
|---|
| 294 |
<BR> |
|---|
| 295 |
<BR> |
|---|
| 296 |
</BODY> |
|---|
| 297 |
</HTML> |
|---|
