Provided by: gmt_4.5.11-1build1_amd64 bug

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

NOTES ON OPERATORS

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

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.

GRID FILE FORMATS

       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
       Technical Reference and Cookbook for more information.

       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.

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

SEE ALSO

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