NAME

     gmtmath - Reverse Polish Notation calculator for data tables


SYNOPSIS

     gmtmath [ -Ccols ] [ -Hnrec ] [ -Nn_col/t_col ]  [  -Q  ]  [
     -Tt_min/t_max/t_inc  ]  [  -V  ]  [  -bi[s][n]  ] [ -bo[s] ]
     operand [ operand ] OPERATOR [ operand ] OPERATOR  ...  =  [
     outfile ]


DESCRIPTION

     gmtmath will perform operations like add,  subtract,  multi-
     ply, and divide on one or more table data files or constants
     using Reverse Polish Notation (RPN) syntax  (e.g.,  Hewlett-
     Packard  calculator-style).  Arbitrarily complicated expres-
     sions may therefore be evaluated; the final result is  writ-
     ten  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  is 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).


not given

     outfile is a table data file that will hold the final result.  If
          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).  ATANH     1    atanh (A).
          BEI       1    bei (A).
          BER       1    ber (A).
          CEIL      1    ceil (A) (smallest integer >= A).
          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.
          EXCH      2    Exchanges A and B on the stack.
          EXP       1    exp (A).
          ERF       1    Error function of A.
          ERFC      1    Complimentory Error function of A.
          ERFINV         1    Inverse error function of A.
          FLOOR          1    floor (A) (greatest integer <= A).
          FMOD      2    A % B (remainder).
          HYPOT          2    hypot (A, 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).
          INV       1    1 / A.
          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).
          LOG       1    log (A) (natural log).
          LOG10          1    log10 (A).
          LOG1P          1    log (1+A) (accurate for small 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.
          MUL(x)         2    A * B.
          NEG       1    -A.
          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.
          RINT      1    rint (A) (nearest integer).
          SIGN      1    sign (+1 or -1) of A.
          SIN       1    sin (A) (A in radians).
          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(t-A).
          SUB(-)         2    A - B.
          TAN       1    tan (A) (A in radians).
          TAND      1    tan (A) (A in degrees).
          TANH      1    tanh (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).

     SYMBOLS
          The following symbols have special meaning:

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


OPTIONS

     -C   Select the columns that will be operated on until  next
          occurrence  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, inluding
          time column.

     -H   Input file(s) has Header record(s).  Number  of  header
          records  can  be  changed  by editing your .gmtdefaults
          file.  If used, GMT default is 1 header record.

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

     -T   Required when no input files are given.   Sets  the  t-
          coordinates  of  the  first  and  last  point  and  the
          equidistant sampling interval  for  the  "time"  column
          (see -N).

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


BEWARE

     The operator PLM calculates the associated Legendre  polyno-
     mial 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 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 cal-
     culate  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
     =`


BUGS

     Files that has 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  are  not  allowed  on
     input,  but  the  output  can  be sent to stdout.  The stack
     limit is hard-wired to 50.  Bessel and error  functions  may
     not  be  available  on all systems.  The Kelvin-Bessel func-
     tions (bei, ber, kei,  ker)  are  based  on  the  polynomial
     approximations  by  Abramowitz  and  Stegun for r <= 8.  All
     functions expecting a positive radius (e.g., log, kei, etc.)
     are passed the absolute value of their argument.


REFERENCES

     Abramowitz,  M.,  and  I.  A.  Stegun,  1964,  Handbook   of
     Mathematical Functions, 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)