```

```

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

be  changed  by  editing  your  .gmtdefaults4 file. If used, GMT
default is 1 header record. Use -Hi if only  input  data  should
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

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.

```

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