sph2grd

Compute grid from spherical harmonic coefficients

Synopsis

gmt sph2grd [ table ] -Ggrdfile -Iincrement -Rregion [ -D[g|n] ] [ -E ] [ -F[k]filter ] [ -Ng|m|s ] [ -Q ] [ -V[level] ] [ -bibinary ] [ -hheaders ] [ -iflags ] [ -rreg ] [ -x[[-]n] ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

sph2grd reads a spherical harmonics coefficient table with records of L, M, C[L,M], S[L,M] and evaluates the spherical harmonic model on the specified grid [Holmes and Featherstone, 2002].

Required Arguments

table

One or more ASCII [or binary, see -bi] files holding the spherical harmonic coefficients. We expect the first four columns to hold the degree L, the order M, followed by the cosine and sine coefficients.

-Goutgrid[=ID][+ddivisor][+ninvalid][+ooffset|a][+sscale|a][:driver[dataType][+coptions]]

Optionally, append =ID for writing a specific file format. The following modifiers are supported:

  • +d - Divide data values by given divisor [Default is 1].

  • +n - Replace data values matching invalid with a NaN.

  • +o - Offset data values by the given offset, or append a for automatic range offset to preserve precision for integer grids [Default is 0].

  • +s - Scale data values by the given scale, or append a for automatic scaling to preserve precision for integer grids [Default is 1].

Note: Any offset is added before any scaling. +sa also sets +oa (unless overridden). To write specific formats via GDAL, use =gd and supply driver (and optionally dataType) and/or one or more concatenated GDAL -co options using +c. See the “Writing grids and images” cookbook section for more details.

-Ix_inc[+e|n][/y_inc[+e|n]]

Set the grid spacing as x_inc [and optionally y_inc].

Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among:

  • d - Indicate arc degrees

  • m - Indicate arc minutes

  • s - Indicate arc seconds

If one of e (meter), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), the the increment will be converted to the equivalent degrees longitude at the middle latitude of the region (the conversion depends on PROJ_ELLIPSOID). If y_inc is not given or given but set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude.

All coordinates: The following modifiers are supported:

  • +e - Slightly adjust the max x (east) or y (north) to fit exactly the given increment if needed [Default is to slightly adjust the increment to fit the given domain].

  • +n - Define the number of nodes rather than the increment, in which case the increment is recalculated from the number of nodes, the registration (see GMT File Formats), and the domain. Note: If -Rgrdfile is used then the grid spacing and the registration have already been initialized; use -I and -R to override these values.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See technical reference).

Optional Arguments

-D[g|n]

Will evaluate a derived field from a geopotential model. Choose between Dg which will compute the gravitational field or Dn to compute the geoid [Add -E for anomalies on the ellipsoid].

-E

Evaluate expansion on the current ellipsoid [Default is sphere].

-F[k]filter

Filter coefficients according to one of two kinds of filter specifications:. Select -Fk if values are given in km [Default is coefficient harmonic degree L]. a) Cosine band-pass: Append four wavelengths lc/lp/hp/hc. Coefficients outside lc/hc are cut; those inside lp/hp are passed, while the rest are tapered. Replace wavelength by - to skip, e.g., -F-/-/50/75 is a low-pass filter. b) Gaussian band-pass: Append two wavelengths lo/hi where filter amplitudes = 0.5. Replace wavelength by - to skip, e.g., -F70/- is a high-pass Gaussian filter.

-Ng|m|s

Normalization used for coefficients. Choose among these directives:

  • g: Geodesy normalization - inner products summed over surface equal \(4\pi\).

  • m: Mathematical normalization - inner products summed over surface equal 1 [Default].

  • s: Schmidt normalization - as used in geomagnetism.

-Q

Coefficients have phase convention from physics, i.e., the \((-1)^m\) factor.

-V[level]

Select verbosity level [w]. (See full description) (See technical reference).

-birecord[+b|l] (more …)

Select native binary format for primary table input. [Default is 4 input columns].

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s). Not used with binary data.

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …)

Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-r[g|p] (more …)

Set node registration [gridline].

-x[[-]n] (more …)

Limit number of cores used in multi-threaded algorithms. Multi-threaded behavior is enabled by default. That covers the modules that implement the OpenMP API (required at compiling stage) and GThreads (Glib) for the grdfilter module.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Grid Values Precision

Regardless of the precision of the input data, GMT programs that create grid files will internally hold the grids in 4-byte floating point arrays. This is done to conserve memory and furthermore most if not all real data can be stored using 4-byte floating point values. Data with higher precision (i.e., double precision values) will lose that precision once GMT operates on the grid or writes out new grids. To limit loss of precision when processing data you should always consider normalizing the data prior to processing.

Geographical And Time Coordinates

When the output grid type is netCDF, the coordinates will be labeled “longitude”, “latitude”, or “time” based on the attributes of the input data or grid (if any) or on the -f or -R options. For example, both -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid. When the x, y, or z coordinate is time, it will be stored in the grid as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH in the gmt.conf file or on the command line. In addition, the unit attribute of the time variable will indicate both this unit and epoch.

Examples

To create a 1 x 1 degree global grid file from the ASCII coefficients in the remote file EGM96_to_36.txt, use

gmt sph2grd @EGM96_to_36.txt -GEGM96_to_36.nc -Rg -I1 -V

References

Holmes, S. A., and Featherstone, W. E., 2002, A unified approach to the Clenshaw summation and the recursive computation of very high degree and order normalized associated Legendre functions: J. Geodesy, v. 76, p. 279-299.

See Also

gmt, grdfft, grdmath