Provided by: gmt_4.5.11-1build1_amd64 #### NAME

```       grdmath - Reverse Polish Notation calculator for grid files

```

#### SYNOPSIS

```       grdmath   [   -F   ]   [   -Ixinc[unit][=|+][/yinc[unit][=|+]]   ]   [  -M  ]  [  -N  ]  [
-Rwest/east/south/north[r] ] [ -V ]  [  -bi[s|S|d|D[ncol]|c[var1/...]]  ]  [  -fcolinfo  ]
operand [ operand ] OPERATOR [ operand ] OPERATOR ... = outgrdfile

```

#### DESCRIPTION

```       grdmath  will  perform  operations like add, subtract, multiply, and divide on one or more
grid files or constants using Reverse Polish Notation (RPN) syntax (e.g.,  Hewlett-Packard
calculator-style).   Arbitrarily  complicated  expressions may therefore be evaluated; the
final result is written to an output grid file.  When two grids are  on  the  stack,  each
element  in  file  A  is  modified  by the corresponding element in file B.  However, some
operators only require one operand (see  below).   If  no  grid  files  are  used  in  the
expression  then  options  -R,  -I  must  be  set  (and  optionally -F).  The expression =
outgrdfile can occur as many times as the depth of the stack allows.

operand
If operand can be opened as a file it will be read as a grid file.  If not a  file,
it is interpreted as a numerical constant or a special symbol (see below).

outgrdfile
The  name  of  a  2-D  grid  file  that will hold the final result.  (See GRID FILE
FORMATS below).

OPERATORS
Choose among the following 145 operators. "args" are the number of input and output
arguments.

Operator  args Returns

ABS       1 1  abs (A).
ACOS      1 1  acos (A).
ACOSH     1 1  acosh (A).
ACOT      1 1  acot (A).
ACSC      1 1  acsc (A).
ADD       2 1  A + B.
AND       2 1  NaN if A and B == NaN, B if A == NaN, else A.
ASEC      1 1  asec (A).
ASIN      1 1  asin (A).
ASINH     1 1  asinh (A).
ATAN      1 1  atan (A).
ATAN2     2 1  atan2 (A, B).
ATANH     1 1  atanh (A).
BEI       1 1  bei (A).
BER       1 1  ber (A).
CAZ       2 1  Cartesian azimuth from grid nodes to stack x,y.
CBAZ      2 1  Cartesian backazimuth from grid nodes to stack x,y.
CDIST     2 1  Cartesian distance between grid nodes and stack x,y.
CEIL      1 1  ceil (A) (smallest integer >= A).
CHICRIT    2 1  Critical value for chi-squared-distribution, with alpha = A and n =
B.
CHIDIST   2 1  chi-squared-distribution P(chi2,n), with chi2 = A and n = B.
CORRCOEFF 2 1  Correlation coefficient r(A, B).
COS       1 1  cos (A) (A in radians).
COSD      1 1  cos (A) (A in degrees).
COSH      1 1  cosh (A).
COT       1 1  cot (A) (A in radians).
COTD      1 1  cot (A) (A in degrees).
CPOISS    2 1  Cumulative Poisson distribution F(x,lambda), with x = A and lambda =
B.
CSC       1 1  csc (A) (A in radians).
CSCD      1 1  csc (A) (A in degrees).
CURV      1 1  Curvature of A (Laplacian).
D2DX2     1 1  d^2(A)/dx^2 2nd derivative.
D2DXY     1 1  d^2(A)/dxdy 2nd derivative.
D2DY2     1 1  d^2(A)/dy^2 2nd derivative.
D2R       1 1  Converts Degrees to Radians.
DDX       1 1  d(A)/dx Central 1st derivative.
DDY       1 1  d(A)/dy Central 1st derivative.
DILOG     1 1  dilog (A).
DIV       2 1  A / B.
DUP       1 2  Places duplicate of A on the stack.
EQ        2 1  1 if A == B, else 0.
ERF       1 1  Error function erf (A).
ERFC      1 1  Complementary Error function erfc (A).
ERFINV    1 1  Inverse error function of A.
EXCH      2 2  Exchanges A and B on the stack.
EXP       1 1  exp (A).
EXTREMA    1 1  Local Extrema: +2/-2 is max/min, +1/-1 is saddle with max/min in x,
0 elsewhere.
FACT      1 1  A! (A factorial).
FCRIT     3 1  Critical value for F-distribution, with alpha = A, n1 = B, and n2  =
C.
FDIST     3 1  F-distribution Q(F,n1,n2), with F = A, n1 = B, and n2 = C.
FLIPLR    1 1  Reverse order of values in each row.
FLIPUD    1 1  Reverse order of values in each column.
FLOOR     1 1  floor (A) (greatest integer <= A).
FMOD      2 1  A % B (remainder after truncated division).
GE        2 1  1 if A >= B, else 0.
GT        2 1  1 if A > B, else 0.
HYPOT     2 1  hypot (A, B) = sqrt (A*A + B*B).
I0        1 1  Modified Bessel function of A (1st kind, order 0).
I1        1 1  Modified Bessel function of A (1st kind, order 1).
IN        2 1  Modified Bessel function of A (1st kind, order B).
INRANGE   3 1  1 if B <= A <= C, else 0.
INSIDE    1 1  1 when inside or on polygon(s) in A, else 0.
INV       1 1  1 / A.
ISNAN     1 1  1 if A == NaN, else 0.
J0        1 1  Bessel function of A (1st kind, order 0).
J1        1 1  Bessel function of A (1st kind, order 1).
JN        2 1  Bessel function of A (1st kind, order B).
K0        1 1  Modified Kelvin function of A (2nd kind, order 0).
K1        1 1  Modified Bessel function of A (2nd kind, order 1).
KEI       1 1  kei (A).
KER       1 1  ker (A).
KN        2 1  Modified Bessel function of A (2nd kind, order B).
KURT      1 1  Kurtosis of A.
LDIST     1 1  Compute distance from lines in multi-segment ASCII file A.
LE        2 1  1 if A <= B, else 0.
LMSSCL    1 1  LMS scale estimate (LMS STD) of A.
LOG       1 1  log (A) (natural log).
LOG10     1 1  log10 (A) (base 10).
LOG1P     1 1  log (1+A) (accurate for small A).
LOG2      1 1  log2 (A) (base 2).
LOWER     1 1  The lowest (minimum) value of A.
LRAND     2 1  Laplace random noise with mean A and std. deviation B.
LT        2 1  1 if A < B, else 0.
MAD       1 1  Median Absolute Deviation (L1 STD) of A.
MAX       2 1  Maximum of A and B.
MEAN      1 1  Mean value of A.
MED       1 1  Median value of A.
MIN       2 1  Minimum of A and B.
MOD       2 1  A mod B (remainder after floored division).
MODE      1 1  Mode value (Least Median of Squares) of A.
MUL       2 1  A * B.
NAN       2 1  NaN if A == B, else A.
NEG       1 1  -A.
NEQ       2 1  1 if A != B, else 0.
NOT       1 1  NaN if A == NaN, 1 if A == 0, else 0.
NRAND     2 1  Normal, random values with mean A and std. deviation B.
OR        2 1  NaN if A or B == NaN, else A.
PDIST     1 1  Compute distance from points in ASCII file A.
PLM       3 1  Associated Legendre polynomial P(A) degree B order C.
PLMg       3  1  Normalized  associated  Legendre  polynomial P(A) degree B order C
(geophysical convention).
POP       1 0  Delete top element from the stack.
POW       2 1  A ^ B.
PQUANT    2 1  The B'th Quantile (0-100%) of A.
PSI       1 1  Psi (or Digamma) of A.
PV        3 1  Legendre function Pv(A) of degree v = real(B) + imag(C).
QV        3 1  Legendre function Qv(A) of degree v = real(B) + imag(C).
R2        2 1  R2 = A^2 + B^2.
R2D       1 1  Convert Radians to Degrees.
RAND      2 1  Uniform random values between A and B.
RINT      1 1  rint (A) (nearest integer).
ROTX      2 1  Rotate A by the (constant) shift B in x-direction.
ROTY      2 1  Rotate A by the (constant) shift B in y-direction.
SAZ       2 1  Spherical azimuth from grid nodes to stack x,y.
SBAZ      2 1  Spherical backazimuth from grid nodes to stack x,y.
SDIST     2 1  Spherical (Great circle) distance (in degrees)  between  grid  nodes
and stack lon,lat (A, B).
SEC       1 1  sec (A) (A in radians).
SECD      1 1  sec (A) (A in degrees).
SIGN      1 1  sign (+1 or -1) of A.
SIN       1 1  sin (A) (A in radians).
SINC      1 1  sinc (A) (sin (pi*A)/(pi*A)).
SIND      1 1  sin (A) (A in degrees).
SINH      1 1  sinh (A).
SKEW      1 1  Skewness of A.
SQR       1 1  A^2.
SQRT      1 1  sqrt (A).
STD       1 1  Standard deviation of A.
STEP      1 1  Heaviside step function: H(A).
STEPX     1 1  Heaviside step function in x: H(x-A).
STEPY     1 1  Heaviside step function in y: H(y-A).
SUB       2 1  A - B.
TAN       1 1  tan (A) (A in radians).
TAND      1 1  tan (A) (A in degrees).
TANH      1 1  tanh (A).
TCRIT      2 1  Critical value for Student's t-distribution, with alpha = A and n =
B.
TDIST     2 1  Student's t-distribution A(t,n), with t = A, and n = B.
TN        2 1  Chebyshev polynomial Tn(-1<t<+1,n), with t = A, and n = B.
UPPER     1 1  The highest (maximum) value of A.
XOR       2 1  0 if A == NaN and B == NaN, NaN if B == NaN, else A.
Y0        1 1  Bessel function of A (2nd kind, order 0).
Y1        1 1  Bessel function of A (2nd kind, order 1).
YLM       2 2  Re and Im orthonormalized spherical harmonics degree A order B.
YLMg      2 2  Cos  and  Sin  normalized  spherical  harmonics  degree  A  order  B
(geophysical convention).
YN        2 1  Bessel function of A (2nd kind, order B).
ZCRIT     1 1  Critical value for the normal-distribution, with alpha = A.
ZDIST     1 1  Cumulative normal-distribution C(x), with x = A.

SYMBOLS
The following symbols have special meaning:

PI   3.1415926...
E    2.7182818...
EULER     0.5772156...
XMIN      Minimum x value
XMAX      Maximum x value
XINC      x increment
NX   The number of x nodes
YMIN      Minimum y value
YMAX      Maximum y value
YINC      y increment
NY   The number of y nodes
X    Grid with x-coordinates
Y    Grid with y-coordinates
Xn   Grid with normalized [-1 to +1] x-coordinates
Yn   Grid with normalized [-1 to +1] y-coordinates

```

#### OPTIONS

```       -F     Force   pixel   node   registration  [Default  is  gridline  registration].   (Node
registrations are defined in GMT Cookbook Appendix B on grid file  formats.)   Only
used with -R -I.

-I     x_inc  [and  optionally  y_inc]  is  the  grid spacing. Optionally, append a suffix
modifier.  Geographical (degrees) coordinates: Append m to indicate arc minutes  or
c  to indicate arc seconds.  If one of the units e, k, i, or n is appended instead,
the increment is assumed to be given  in  meter,  km,  miles,  or  nautical  miles,
respectively,  and  will  be  converted  to the equivalent degrees longitude at the
middle latitude of the region (the conversion depends on ELLIPSOID).  If /y_inc  is
given  but set to 0 it will be reset equal to x_inc; otherwise it will be converted
to degrees latitude.  All coordinates: If = is appended then the corresponding  max
x  (east)  or y (north) may be slightly adjusted to fit exactly the given increment
[by default the increment may be  adjusted  slightly  to  fit  the  given  domain].
Finally, instead of giving an increment you may specify the number of nodes desired
by appending + to the supplied integer argument; the increment is then recalculated
from  the number of nodes and the domain.  The resulting increment value depends on
whether you have selected  a  gridline-registered  or  pixel-registered  grid;  see
Appendix  B  for details.  Note: if -Rgrdfile is used then grid spacing has already
been initialized; use -I to override the values.

-M     By default any derivatives calculated are in z_units/ x(or y)_units.  However,  the
user  may choose this option to convert dx,dy in degrees of longitude,latitude into
meters using a flat Earth approximation, so that gradients are in z_units/meter.

-N     Turn off strict domain match checking when multiple grids are manipulated  [Default
will  insist  that  each grid domain is within 1e-4 * grid_spacing of the domain of
the first grid listed].

-R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
these limits correspond to west, east, south, and north and you may specify them in
decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if  lower  left
and  upper  right map coordinates are given instead of w/e/s/n.  The two shorthands
-Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
with  -90/+90  in  latitude).   Alternatively, specify the name of an existing grid
file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
(relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
-JX|x),  or  (b)  absolute time of the form [date]T[clock] (append T to -JX|x).  At
least one of date and clock must be present; the T is always  required.   The  date
string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
(ISO week calendar), while the clock string must be  of  the  form  hh:mm:ss[.xxx].
The  use  of  delimiters  and their type and positions must be exactly as indicated
(however, input, output and plot formats are customizable; see gmtdefaults).

-V     Selects verbose mode, which will send progress  reports  to  stderr  [Default  runs
"silently"].

-bi    Selects  binary  input.   Append  s  for  single precision [Default is d (double)].
Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
columns  in your binary input file if it exceeds the columns needed by the program.
Or append c if the input  file  is  netCDF.  Optionally,  append  var1/var2/...  to
specify the variables to be read.  The binary input option only applies to the data
files needed by operators LDIST, PDIST, and INSIDE.

-f     Special formatting of input and/or output  columns  (time  or  geographical  data).
Specify  i  or  o  to  make  this apply only to input or output [Default applies to
both].  Give one or more columns (or column ranges) separated by commas.  Append  T
(absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
(longitude), y (latitude), or f (floating point) to each  column  or  column  range
item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

```

#### NOTESONOPERATORS

```       (1)  The operator SDIST calculates spherical distances between the (lon, lat) point on the
stack and all node positions in the grid.  The grid domain and the (lon,  lat)  point  are
expected  to  be  in  degrees.   Similarly, the SAZ and SBAZ operators calculate spherical
azimuth and back-azimuths in degrees, respectively.  A few operators  (PDIST,  LDIST,  and
INSIDE)  expects  their  argument  to  be  a  single file with points, lines, or polygons,
respectively.  Be aware that LDIST in particular can be slow for large grids and  numerous
line segments.  Note: If the current ELLIPSOID is not spherical then geodesics are used in
the calculations.

(2) The operator PLM calculates the associated Legendre polynomial of degree L and order M
(0  <=  M  <= L), and its argument is the sine of the latitude.  PLM is not normalized and
includes the Condon-Shortley phase (-1)^M.  PLMg is normalized in the  way  that  is  most
commonly  used  in  geophysics.   The C-S phase can be added by using -M as argument.  PLM
will overflow at higher degrees, whereas PLMg is stable until ultra high degrees (at least
3000).

(3)  The  operators YLM and YLMg calculate normalized spherical harmonics for degree L and
order M (0 <= M <= L) for all positions in the grid, which is assumed to  be  in  degrees.
YLM  and  YLMg  return  two grids, the real (cosine) and imaginary (sine) component of the
complex spherical harmonic.  Use the POP operator (and EXCH) to get rid of one of them, or
save both by giving two consecutive = file.grd calls.
The  orthonormalized  complex  harmonics  YLM  are  most  commonly  used  in  physics  and
seismology.  The square of YLM integrates to 1 over a  sphere.   In  geophysics,  YLMg  is
normalized  to  produce  unit power when averaging the cosine and sine terms (separately!)
over a sphere (i.e., their squares each integrate to 4  pi).   The  Condon-Shortley  phase
(-1)^M is not included in YLM or YLMg, but it can be added by using -M as argument.

(4)  All  the  derivatives  are based on central finite differences, with natural boundary
conditions.

(5) Files that have the same names as some operators, e.g., ADD, SIGN, =, etc.  should  be
identified by prepending the current directory (i.e., ./LOG).

(6) Piping of files is not allowed.

(7) The stack depth limit is hard-wired to 100.

(8)  All  functions  expecting  a  positive  radius  (e.g., LOG, KEI, etc.) are passed the
absolute value of their argument.

```

#### GRIDVALUESPRECISION

```       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.

```

#### GRIDFILEFORMATS

```       By default GMT writes out grid as single precision floats  in  a  COARDS-complaint  netCDF
file  format.  However, GMT is able to produce grid files in many other commonly used grid
file formats and also facilitates so called "packing" of grids, writing out floating point
data as 2- or 4-byte integers. To specify the precision, scale and offset, the user should
add the suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of  the  grid
type  and  precision,  and  scale  and  offset  are optional scale factor and offset to be
applied to all grid values, and nan is the value used  to  indicate  missing  data.   When
reading  grids,  the format is generally automatically recognized. If not, the same suffix
can be added to input grid file names.  See grdreformat(1) and Section  4.17  of  the  GMT

When  reading  a  netCDF file that contains multiple grids, GMT will read, by default, the
first 2-dimensional grid that can find in that file. To  coax  GMT  into  reading  another
multi-dimensional  variable  in  the  grid  file,  append ?varname to the file name, where
varname is the name of the variable. Note that you may need to escape the special  meaning
of  ?  in  your  shell  program  by  putting a backslash in front of it, or by placing the
filename and suffix between quotes or double quotes.  The ?varname suffix can also be used
for  output  grids  to  specify  a  variable  name  different  from the default: "z".  See
grdreformat(1) and Section 4.18 of the GMT  Technical  Reference  and  Cookbook  for  more
information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

```

#### GEOGRAPHICALANDTIMECOORDINATES

```       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 -R 90w/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 .gmtdefaults
file or on the command line.  In addition, the unit attribute of the  time  variable  will
indicate both this unit and epoch.

```

#### EXAMPLES

```       To take log10 of the average of 2 files, use

grdmath file1.grd file2.grd ADD 0.5 MUL LOG10 = file3.grd

Given the file ages.grd, which holds seafloor ages in m.y., use the relation depth(in m) =
2500 + 350 * sqrt (age) to estimate normal seafloor depths:

grdmath ages.grd SQRT 350 MUL 2500 ADD = depths.grd

To find the angle a (in degrees) of the largest principal stress from  the  stress  tensor
given by the three files s_xx.grd s_yy.grd, and s_xy.grd from the relation tan (2*a) = 2 *
s_xy / (s_xx - s_yy), use

grdmath 2 s_xy.grd MUL s_xx.grd s_yy.grd SUB DIV ATAN2 2 DIV = direction.grd

To calculate the fully normalized spherical harmonic of degree 8 and order 4 on a 1  by  1
degree world map, using the real amplitude 0.4 and the imaginary amplitude 1.1:

grdmath -R 0/360/-90/90 -I 1 8 4 YML 1.1 MUL EXCH 0.4 MUL ADD = harm.grd

To extract the locations of local maxima that exceed 100 mGal in the file faa.grd:

grdmath faa.grd DUP EXTREMA 2 EQ MUL DUP 100 GT MUL 0 NAN = z.grd
grd2xyz z.grd -S > max.xyz

```

#### REFERENCES

```       Abramowitz,  M.,  and  I.  A.  Stegun,  1964,  Handbook of Mathematical Functions, Applied
Mathematics Series, vol. 55, Dover, New York.
Holmes, S. A., and W. E. Featherstone, 2002, A unified approach to the Clenshaw  summation
and the recursive computation of very high degree and order normalised associated Legendre
functions.  Journal of Geodesy, 76, 279-299.
Press, W. H.,  S. A. Teukolsky, W. T. Vetterling, and  B.  P.  Flannery,  1992,  Numerical
Recipes, 2nd edition, Cambridge Univ., New York.
Spanier, J., and K. B. Oldman, 1987, An Atlas of Functions, Hemisphere Publishing Corp.

```

#### SEEALSO

```       GMT(1), gmtmath(1), grd2xyz(1), grdedit(1), grdinfo(1), xyz2grd(1)
```