sl.grid.readFESOM: Read FESOM Grid

In helgegoessling/spheRlab: Spherical Geometry, Analysis, and Plotting of Geoscientific Data on Arbitrary Grids

Read FESOM Grid

Description

Read and analyse a FESOM1 or FESOM2 grid from ascii '.out' files.

Usage

sl.grid.readFESOM(griddir, rot = FALSE, rot.invert = FALSE, rot.abg, threeD = TRUE, remove.emptylev = TRUE, read.boundary = TRUE, reorder.ccw = TRUE, maxmaxneigh = 12, findneighbours.maxiter = 10, repeatlastpoint = TRUE, onlybaryc = FALSE, omitcoastnds = FALSE, calcpolyareas = TRUE, Rearth = 6371000, basicreadonly = FALSE, fesom2 = TRUE, verbose = TRUE)

Arguments

griddir	a character specifying the path to the FESOM grid directory.
rot	a logical value indicating whether or not to rotate the grid.
rot.invert	a logical value indicating whether or not to invert the rotation.
rot.abg	a vector of length 3 specifying the alpha, beta, and gamma parameters for the rotation. See sl.lonlatrot2abg for details.
threeD	a logical value indicating whether or not to read 3D grid information. If FALSE, only surface information is read. Default is TRUE.
remove.emptylev	a logical value indicating whether or not to remove empty bottom levels from the 3D grid. Only used if threeD=TRUE. Default is FALSE.
read.boundary	a logical value indicating whether or not to read info on which 3D nodes are at horizontal or vertical boundaries. Only used if threeD=TRUE.
reorder.ccw	a logical value indicating whether or not to reorder the triangular surface elements counterclockwise.
maxmaxneigh	an integer specifying an upper limit for the expected maximum number of neighbours for a surface node. For a typical (close to orthogonal) triangular mesh, there are 6 neighbours per node on average; the default value maxmaxneigh=12 is relatively safe. A too small value results in an error. A larger value implies more memory usage.
findneighbours.maxiter	an integer specifying the maximum number of iterations used to order the neighbours of each surface node. The default max.iter=10 should be on the safe side.
repeatlastpoint	a logical value indicating whether or not to pad the rows of the 'stamp polygon' matrices stamppoly.lon and stamppoly.lat (for surface nodes that have below-maximum polygon vertices) by repeating the last polygon vertex. If repeatlastpoint=FALSE, equidistant points along the line connecting the last and the first vertex will be inserted using sl.fillequidist.
onlybaryc	a logical value indicating whether or not to use only the barycenters (centroids) of the triangular surface elements for the stamp polygons, that is, to omit the edge medians inbetween. For a perfectly orthogonal grid the result will be identical as the lines connecting the centroids intersect the edge medians, but for non-orthogonal grids this introduces an inaccuracy.
omitcoastnds	a logical value indicating whether or not to omit coastal surface nodes from their corresponding stamp polygons. Usually the default omitcoastnds=FALSE is appropriate.
calcpolyareas	a logical value indicating whether or not to compute the areas of the triangular surface elements and of the stamp polygons.
Rearth	a scalar specifying the radius of the sphere - in case of FESOM the Earth. Used only if calcpolyareas=TRUE.
basicreadonly	a logical value indicating whether or not only to read grid data without analysing neighborhood information etc. Reading is even faster with rot, reorder.ccw, and threeD all set to FALSE.
fesom2	a logical value indicating whether the grid to be read is a FESOM2 grid. If FALSE, the grid is assumed to be a FESOM1 grid. Default is TRUE.
verbose	a logical value indicating whether or not print statements shall report on the function progess.

Details

This is a FESOM-specific function to read grid information from the standard FESOM1 and FESOM2 ascii '.out' files.

Value

a spheRlab grid list with the following elements:

N	an integer specifying the number of surface nodes.
Nlev	an integer specifying the number of vertical levels.
N3D	an integer specifying the number of 3D nodes (only counting wet nodes).
lon	a vector of length N with the surface node (grid point) longitudes.
lat	a vector of length N with the surface node (grid point) latitudes.
elem	an Nex3 matrix with the surface node indices of the triangular surface elements in rows.
coast	a vector of length N with logical values indicating whether or not surface nodes are coastal.
neighnodes	an NxM matrix with each row containing all neighbours of one node. The neighbours are arranged in clockwise or counterclockwise order, depending on the direction of rotation provided in elem (which is influenced by the argument reorder.ccw). M is the maximum number of neighbours actually found for a node (M<=maxmaxneigh).
neighelems	an NxM matrix with each row containing all triangular elements (identified by the row indices in elem) adjacent to one node. The elements are arranged in clockwise or counterclockwise order, depending on the direction of rotation provided in elem (which is influenced by the argument reorder.ccw). M is the maximum number of neighbours actually found for a node (M<=maxmaxneigh).
stamppoly.lon	an NxP matrix with each row containing the longitudes of all stamp polygon vertices of one node. If onlybaryc=FALSE (default) then the polygons (of internal nodes) consist of the edge medians (of which there are as many as neighbour nodes) and of the same number of triangle barycenters (centroids) inbetween, giving P=2M. Otherwise the edge medians are omitted and P=M. If omitcoastnds=FALSE (default) then coastal stamp polygons include the coastal node itself as vertex.
stamppoly.lat	as stamppoly.lon, but with latitudes.
baryc.lon	a vector of length Ne with the surface node (grid point) longitudes.
baryc.lat	a vector of length Ne with the surface node (grid point) latitudes.
cellareas	a vector of length N with the areas of the stamp polygons.
elemareas	a vector of length Ne with the areas of the triangular elements.
depth	a vector of length Nlev with the depth of the vertical levels (commonly in meters).
depth.bounds	a vector of length Nlev+1 with the depth bounds of the vertical levels (commonly in meters).
depth.lev	an integer vector of length N with the depth underneath each surface node in terms of vertical levels.
boundary	an integer vector of length N3D specifying which 3D nodes are located at boundaries: the first digit encodes the vertical dimension (1=surface, 2=interior, 3=bottom), and the second digit encodes the horizontal dimension (0=interior, 1=coast). Note that this information is retrieved directly from 'nod3d.out' rather than derived from 3d element information. Not yet implemented for FESOM2; in this case NULL is returned.

Note

It would probably make sense to split this function further as it consists of a number of well-defined blocks that might also be useful in other circumstances where the remainder of this function is not needed. The separate functions could be named consistenty sl.grid.SOMETHING.

The 3D functionality is incomplete; e.g., no 3d-element information is considered. The functionality can be extended when needed.

Author(s)

Helge Goessling

See Also

sl.grid.writeFESOM, sl.grid.writeCDO, sl.grid.writeZAXIS

Examples

## Not run: 
# In this example a 'backward rotation' is performed, assuming that the original mesh coordinates are rotated;
# if that's not the case (which is now default), set 'rot=FALSE' or leave it unspecified (default is FALSE).
grid = sl.grid.readFESOM(griddir="PATH-TO-YOUR-FESOM-GRID",rot=TRUE,rot.invert=TRUE,rot.abg=c(50,15,-90))

# Write a grid description that is valid for quantities defined at nodes:
sl.grid.writeCDO(grid,ofile="~/sl.grid.scalars.nc")

# Write a grid description that is valid for quantities defined at element centers (or representative for elements):
sl.grid.writeCDO(grid,ofile="~/sl.grid.vectors.nc",fesom2velocities=TRUE)

## End(Not run)

helgegoessling/spheRlab documentation built on April 8, 2024, 8:34 a.m.