## NAME

           gmtmath - Reverse Polish Notation calculator for data tables

## SYNOPSIS

           gmtmath [ -At_f(t).d ] [ -Ccols ] [ -Hnrec ] [ -Nn_col/t_col ] [ -Q ]
            [  -S[f|l]  ][  -Tt_min/t_max/t_inc|tfile  ]  [  -V  ] [ -bi[s][n] ] [
           -bo[s][n] ] operand [ operand ] OPERATOR [ operand ] OPERATOR ...  =  [
           outfile ]

## DESCRIPTION

           gmtmath  will  perform  operations  like  add,  subtract, multiply, and
           divide on one or more table data files or constants using Reverse  Pol-
           ish  Notation  (RPN)  syntax  (e.g., Hewlett-Packard calculator-style).
           Arbitrarily complicated expressions may  therefore  be  evaluated;  the
           final  result  is  written to an output file [or standard output]. When
           two data tables 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 data  tables  are  used  in  the
           expression  then  options  -T,  -N  must be set (and optionally -b). By
           default, all columns except the "time" column are operated on, but this
           can be changed (see -C).

           operand
                  If  operand  can be opened as a file it will be read as an ASCII
                  (or binary, see -bi) table data file.  If  not  a  file,  it  is
                  interpreted  as  a  numerical  constant or a special symbol (see
                  below).

           outfile is a table data file that will hold the final  result.  If  not
           given then
                  the output is sent to stdout.

           OPERATORS
                  Choose among the following operators:
                  Operator n_args Returns

                  ABS 1 abs (A).
                  ACOS 1 acos (A).
                  ACOSH 1 acosh (A).
                  ADD(+) 2 A + B.
                  AND 2 NaN if A and B == NaN, B if A == NaN, else A.
                  ASIN 1 asin (A).
                  ASINH 1 asinh (A).
                  ATAN 1 atan (A).
                  ATAN2 2 atan2 (A, B).
                  ATANH 1 atanh (A).
                  BEI 1 bei (A).
                  BER 1 ber (A).
                  CEIL 1 ceil (A) (smallest integer >= A).
                  CHICRIT 2  Critical  value  for  chi-squared-distribution,  with
                  alpha = A and n = B.
                  CHIDIST  2 chi-squared-distribution P(chi2,n), with chi2 = A and
                  n = B.
                  COL 1 Places column A on the stack.
                  COS 1 cos (A) (A in radians).
                  COSD 1 cos (A) (A in degrees).
                  COSH 1 cosh (A).
                  D2DT2 1 d^2(A)/dt^2 2nd derivative.
                  D2R 1 Converts Degrees to Radians.
                  DILOG 1 dilog (A).
                  DIV(/) 2 A / B.
                  DDT 1 d(A)/dt 1st derivative.
                  DUP 1 Places duplicate of A on the stack.
                  ERF 1 Error function erf (A).
                  ERFC 1 Complementary Error function erfc (A).
                  ERFINV 1 Inverse error function of A.
                  EQ 2 1 if A == B, else 0.
                  EXCH 2 Exchanges A and B on the stack.
                  EXP 1 exp (A).
                  FCRIT 3 Critical value for F-distribution, with alpha = A, n1  =
                  B, and n2 = C.
                  FDIST  3 F-distribution Q(F,n1,n2), with F = A, n1 = B, and n2 =
                  C.
                  FLIPUD 1 Reverse order of each column
                  FLOOR 1 floor (A) (greatest integer <= A).
                  FMOD 2 A % B (remainder).
                  GE 2 1 if A >= B, else 0.
                  GT 2 1 if A > B, else 0.
                  HYPOT 2 hypot (A, B) = sqrt (A*A + B*B).
                  I0 1 Modified Bessel function of A (1st kind, order 0).
                  I1 1 Modified Bessel function of A (1st kind, order 1).
                  IN 2 Modified Bessel function of A (1st kind, order B).
                  INT 1 Numerically integrate A.
                  INV 1 1 / A.
                  ISNAN 1 1 if A == NaN, else 0.
                  J0 1 Bessel function of A (1st kind, order 0).
                  J1 1 Bessel function of A (1st kind, order 1).
                  JN 2 Bessel function of A (1st kind, order B).
                  K0 1 Modified Kelvin function of A (2nd kind, order 0).
                  K1 1 Modified Bessel function of A (2nd kind, order 1).
                  KN 2 Modified Bessel function of A (2nd kind, order B).
                  KEI 1 kei (A).
                  KER 1 ker (A).
                  LE 2 1 if A <= B, else 0.
                  LMSSCL 1 LMS scale estimate (LMS STD) of A.
                  LOG 1 log (A) (natural log).
                  LOG10 1 log10 (A) (base 10).
                  LOG1P 1 log (1+A) (accurate for small A).
                  LOG2 1 log2 (A) (base 2).
                  LOWER 1 The lowest (minimum) value of A.
                  LRAND 2 Laplace random noise with mean A and std. deviation B.
                  LSQFIT 1 Let current table be [A  |  b];  return  least  squares
                  solution x = A \ b.
                  LT 2 1 if A < B, else 0.
                  MAD 1 Median Absolute Deviation (L1 STD) of A.
                  MAX 2 Maximum of A and B.
                  MEAN 1 Mean value of A.
                  MED 1 Median value of A.
                  MIN 2 Minimum of A and B.
                  MODE 1 Mode value (Least Median of Squares) of A.
                  MUL(x) 2 A * B.
                  NAN 2 NaN if A == B, else A.
                  NEG 1 -A.
                  NEQ 2 1 if A != B, else 0.
                  NRAND  2 Normal, random values with mean A and std. deviation B.
                  OR 2 NaN if A or B == NaN, else A.
                  PLM 3 Associated Legendre polynomial P(-1<A<+1) degree  B  order
                  C.
                  POP 1 Delete top element from the stack.
                  POW(^) 2 A ^ B.
                  R2 2 R2 = A^2 + B^2.
                  R2D 1 Convert Radians to Degrees.
                  RAND 2 Uniform random values between A and B.
                  RINT 1 rint (A) (nearest integer).
                  ROOTS 2 Treats col A as f(t) = 0 and returns its roots
                  ROTT 2 Rotate A by the (constant) shift B in the t-direction.
                  SIGN 1 sign (+1 or -1) of A.
                  SIN 1 sin (A) (A in radians).
                  SINC 1 sinc (A) (sin (pi*A)/(pi*A)).
                  SIND 1 sin (A) (A in degrees).
                  SINH 1 sinh (A).
                  SQRT 1 sqrt (A).
                  STD 1 Standard deviation of A.
                  STEP 1 Heaviside step function H(A).
                  STEPT 1 Heaviside step function H(t-A).
                  SUB(-) 2 A - B.
                  SUM 1 Cumulative sum of A
                  TAN 1 tan (A) (A in radians).
                  TAND 1 tan (A) (A in degrees).
                  TANH 1 tanh (A).
                  TCRIT  2 Critical value for Student’s t-distribution, with alpha
                  = A and n = B.
                  TDIST 2 Student’s t-distribution A(t,n), with t = A, and n =  B.
                  UPPER 1 The highest (maximum) value of A.
                  XOR 2 B if A == NaN, else A.
                  Y0 1 Bessel function of A (2nd kind, order 0).
                  Y1 1 Bessel function of A (2nd kind, order 1).
                  YN 2 Bessel function of A (2nd kind, order B).
                  ZCRIT 1 Critical value for the normal-distribution, with alpha =
                  A.

           SYMBOLS
                  The following symbols have special meaning:

                  PI 3.1415926...
                  E  2.7182818...
                  T  Table with t-coordinates

## OPTIONS

           -A     Requires -N and will partially initialize a  table  with  values
                  from  the given file containing t and f(t) only. The t is placed
                  in column t_col while f(t) goes into column n_col - 1 (see  -N).

           -C     Select  the  columns  that will be operated on until next occur-
                  rence of -C.  List columns  separated  by  commas;  ranges  like
                  1,3-5,7 are allowed. -C (no arguments) resets the default action
                  of using all columns except time column (see -N).   -Ca  selects
                  all columns, including time column, while -Cr reverses (toggles)
                  the current choices.

           -H     Input file(s) has Header record(s). Number of header records can
                  be  changed  by  editing  your  .gmtdefaults4 file. If used, GMT
                  default is 1 header record. Use -Hi if only  input  data  should
                  have  header  records  [Default will write out header records if
                  the input data have them].

           -N     Select the number of columns and the column number that contains
                  the "time" variable. Columns are numbered starting at 0 [2/0].

           -Q     Quick  mode  for  scalar  calculation.  Shorthand  for -Ca -N1/0
                  -T0/0/1.

           -S     Only report the first or last row of the results [Default is all
                  rows].  This is useful if you have computed a statistic (say the
                  MODE) and only want to report a single number instead of  numer-
                  ous records with identical values.  Append l to get the last row
                  and f to get the first row only [Default].

           -T     Required when no input files are given. Sets  the  t-coordinates
                  of  the first and last point and the equidistant sampling inter-
                  val for the "time" column (see -N).  If there is no time  column
                  (only  data  columns),  give  -T  with  no  arguments; this also
                  implies -Ca. Alternatively, give the name of a file whose  first
                  column   contains   the   desired  t-coordinates  which  may  be
                  irregular.

           -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
                  double].  Append n for the  number  of  columns  in  the  binary
                  file(s).

           -bo    Selects binary output. Append s for single precision [Default is
                  double].  Append n for the  number  of  columns  in  the  binary
                  file(s).

## BEWARE

           The  operator  PLM  calculates  the  associated  Legendre polynomial of
           degree L and order M, and its argument is the cosine of the  colatitude
           which must satisfy -1 <= x <= +1. PLM is not normalized.
           All  derivatives  are based on central finite differences, with natural
           boundary conditions.

## EXAMPLES

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

           gmtmath file1.d file2.d ADD 0.5 MUL LOG10 = file3.d

           Given the file  samples.d,  which  holds  seafloor  ages  in  m.y.  and
           seafloor  depth  in m, use the relation depth(in m) = 2500 + 350 * sqrt
           (age) to print the depth anomalies:

           gmtmath samples.d T SQRT 350 MUL 2500 ADD SUB = | lpr

           To take the average of columns  1  and  4-6  in  the  three  data  sets
           sizes.1, sizes.2, and sizes.3, use

           gmtmath -C1,4-6 sizes.1 sizes.2 ADD sizes.3 ADD 3 DIV = ave.d

           To  take the 1-column data set ages.d and calculate the modal value and
           assign it to a variable, try

           set mode_age = ‘gmtmath -S -T ages.d MODE =‘

           To evaluate the dilog(x) function for coordinates  given  in  the  file
           t.d:

           gmtmath -Tt.d T DILOG = dilog.d

           To use gmtmath as a RPN Hewlett-Packard calculator on scalars (i.e., no
           input files) and calculate arbitrary expressions, use  the  -Q  option.
           As  an  example, we will calculate the value of Kei (((1 + 1.75)/2.2) +
           cos (60)) and store the result in the shell variable z:

           set z = ‘gmtmath -Q 1 1.75 ADD 2.2 DIV 60 COSD ADD KEI =‘

           To use gmtmath as a general least squares equation solver, imagine that
           the  current  table  is the augmented matrix [ A | b ] and you want the
           least squares solution x to the matrix equation A * x = b.  The  opera-
           tor  LSQFIT  does this; it is your job to populate the matrix correctly
           first. The -A option will facilitate this. Suppose you have a  2-column
           file  ty.d with t and b(t) and you would like to fit a the model y(t) =
           a + b*t + c*H(t-t0), where H is the Heaviside step function for a given
           t0  = 1.55.  Then, you need a 4-column augmented table loaded with t in
           column 0 and your observed y(t) in column 3.  The calculation becomes

           gmtmath -N4/1 -Aty.d -C0 1 ADD -C2 1.55 STEPT ADD -Ca  LSQFIT  =  solu-
           tion.d

           Note  we  use  the -C option to select which columns we are working on,
           then make active all the columns we need (here all of them,  with  -Ca)
           before calling LSQFIT. The second and fourth columns are preloaded with
           t and y(t), respectively, the other columns are zero.  If  you  already
           have  a  precalculated  table  with the augmented matrix [ A | b ] in a
           file (say lsqsys.d), the least squares solution is simply

           gmtmath -T lsqsys.d LSQFIT = solution.d

## BUGS

           Files that have the same name as some operators, e.g.,  ADD,  SIGN,  =,
           etc.  cannot  be read and must not be present in the current directory.
           Piping of files is not allowed on input, but the output can be sent  to
           stdout.   The stack limit is hard-wired to 50.  All functions expecting
           a positive radius (e.g., LOG, KEI, etc.) are passed the absolute  value
           of  their  argument. The DDT and D2DT2 functions only work on regularly
           spaced data.  ROOTS must be the last operator on the stack,  only  fol-
           lowed by =.

## REFERENCES

           Abramowitz,  M., and I. A. Stegun, 1964, Handbook of Mathematical Func-
           tions, Applied Mathematics Series, vol. 55, Dover, New York.
           Press, W. H., S. A. Teukolsky, W. T. Vetterling, B. P. Flannery,  1992,
           Numerical Recipes, 2nd edition, Cambridge Univ., New York.

## SEE ALSO

           gmt(l), grd2xyz(l), grdedit(l), grdinfo(l), grdmath(l), xyz2grd(l)

    GMT4.0                            1 Oct 2004                        GMTMATH(l)