1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
|
.. index:: ! gmtmath
*******
gmtmath
*******
.. only:: not man
gmtmath - Reverse Polish Notation (RPN) calculator for data tables
Synopsis
--------
.. include:: common_SYN_OPTs.rst_
**gmtmath** [ |-A|\ *t_f(t).d*\ [**+e**]\ [**+s**\ \|\ **w**] ]
[ |-C|\ *cols* ]
[ |-E|\ *eigen* ] [ |-I| ]
[ |-N|\ *n\_col*\ [/*t_col*] ]
[ |-Q| ] [ |-S|\ [**f**\ \|\ **l**] ]
[ |-T|\ *t\_min*/*t_max*/*t_inc*\ [**+**\ ]\|\ *tfile* ]
[ |SYN_OPT-V| ]
[ |SYN_OPT-b| ]
[ |SYN_OPT-d| ]
[ |SYN_OPT-f| ]
[ |SYN_OPT-g| ]
[ |SYN_OPT-h| ]
[ |SYN_OPT-i| ]
[ |SYN_OPT-o| ]
[ |SYN_OPT-s| ]
*operand* [ *operand* ] **OPERATOR** [ *operand* ] **OPERATOR** ...
**=** [ *outfile* ]
|No-spaces|
Description
-----------
**gmtmath** will perform operations like add, subtract, multiply, 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 expressions may therefore be evaluated; the
final result is written to an output file [or standard output]. Data
operations are element-by-element, not matrix manipulations (except
where noted). Some operators only require one operand (see below). If no
data tables are used in the expression then options **-T**, **-N** can
be set (and optionally **-bo** to indicate the
data type for binary tables). If STDIN is given, the standard input will
be read and placed on the stack as if a file with that content had been
given on the command line. By default, all columns except the "time"
column are operated on, but this can be changed (see **-C**).
Complicated or frequently occurring expressions may be coded as a macro
for future use or stored and recalled via named memory locations.
Required Arguments
------------------
*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). The special argument STDIN means that *stdin*
will be read and placed on the stack; STDIN can appear more than
once if necessary.
*outfile*
The name of a table data file that will hold the final result. If
not given then the output is sent to stdout.
Optional Arguments
------------------
.. _-A:
**-A**\ *t_f(t).d*\ [**+e**]\ [**+r**]\ [**+s**\ \|\ **w**]
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**). Append **+r** to only place *f(t)* and leave the left
hand side of the matrix equation alone. If used with operators LSQFIT and SVDFIT you can
optionally append the modifier **+e** which will instead evaluate
the solution and write a data set with four columns: t, f(t), the
model solution at t, and the the residuals at t, respectively
[Default writes one column with model coefficients]. Append **+w**
if *t_f(t).d* has a third column with weights, or append **+s** if
*t_f(t).d* has a third column with 1-sigma. In those two cases we
find the weighted solution. The weights (or sigmas) will be output
as the last column when **+e** is in effect.
.. _-C:
**-C**\ *cols*
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, including time column, while **-Cr** reverses (toggles) the
current choices. When **-C** is in effect it also controls which
columns from a file will be placed on the stack.
.. _-E:
**-E**\ *eigen*
Sets the minimum eigenvalue used by operators LSQFIT and SVDFIT [1e-7].
Smaller eigenvalues are set to zero and will not be considered in the
solution.
.. _-I:
**-I**
Reverses the output row sequence from ascending time to descending [ascending].
.. _-N:
**-N**\ *n_col*\ [/*t_col*]
Select the number of columns and optionally the column number that
contains the "time" variable [0]. Columns are numbered starting at 0
[2/0]. If input files are specified then **-N** will add any missing
columns.
.. _-Q:
**-Q**
Quick mode for scalar calculation. Shorthand for **-Ca** **-N**\ 1/0 **-T**\ 0/0/1.
.. _-S:
**-S**\ [**f**\ \|\ **l**]
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
numerous records with identical values. Append **l** to get the last
row and **f** to get the first row only [Default].
.. _-T:
**-T**\ *t_min*/*t_max*/*t_inc*\ [**+**\ ]\|\ *tfile*
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**). Append **+** if you are specifying
the number of equidistant points instead. 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:
.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_
.. |Add_-bi| unicode:: 0x20 .. just an invisible code
.. include:: explain_-bi.rst_
.. |Add_-bo| replace:: [Default is same as input, but see **-o**]
.. include:: explain_-bo.rst_
.. |Add_-d| unicode:: 0x20 .. just an invisible code
.. include:: explain_-d.rst_
.. |Add_-f| unicode:: 0x20 .. just an invisible code
.. include:: explain_-f.rst_
.. |Add_-g| unicode:: 0x20 .. just an invisible code
.. include:: explain_-g.rst_
.. |Add_-h| unicode:: 0x20 .. just an invisible code
.. include:: explain_-h.rst_
.. include:: explain_-icols.rst_
.. include:: explain_-ocols.rst_
.. include:: explain_-s.rst_
.. include:: explain_help.rst_
Operators
---------
Choose among the following 176 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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ACSC** | 1 1 | acsc (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ACOT** | 1 1 | acot (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ADD** | 2 1 | A + B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **AND** | 2 1 | 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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BCDF** | 3 1 | Binomial cumulative distribution function for p = A, n = B, and x = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BPDF** | 3 1 | Binomial probability density function for p = A, n = B, and x = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BEI** | 1 1 | bei (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BER** | 1 1 | ber (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITAND** | 2 1 | A & B (bitwise AND operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITLEFT** | 2 1 | A << B (bitwise left-shift operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITNOT** | 1 1 | ~A (bitwise NOT operator, i.e., return two's complement) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITOR** | 2 1 | A \| B (bitwise OR operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITRIGHT** | 2 1 | A >> B (bitwise right-shift operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITTEST** | 2 1 | 1 if bit B of A is set, else 0 (bitwise TEST operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **BITXOR** | 2 1 | A ^ B (bitwise XOR operator) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CEIL** | 1 1 | ceil (A) (smallest integer >= A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CHICRIT** | 2 1 | Chi-squared distribution critical value for alpha = A and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CHICDF** | 2 1 | Chi-squared cumulative distribution function for chi2 = A and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CHIPDF** | 2 1 | Chi-squared probability density function for chi2 = A and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **COL** | 1 1 | Places column A on the stack |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **COMB** | 2 1 | Combinations n_C_r, with n = A and r = 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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CSC** | 1 1 | csc (A) (A in radians) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **CSCD** | 1 1 | csc (A) (A in degrees) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DDT** | 1 1 | d(A)/dt Central 1st derivative |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **D2DT2** | 1 1 | d^2(A)/dt^2 2nd derivative |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **D2R** | 1 1 | Converts Degrees to Radians |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DENAN** | 2 1 | Replace NaNs in A with values from B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DILOG** | 1 1 | dilog (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DIFF** | 1 1 | Forward difference between adjacent elements of A (A[1]-A[0], A[2]-A[1], ..., NaN) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DIV** | 2 1 | A / B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **DUP** | 1 2 | Places duplicate of A on the stack |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ECDF** | 2 1 | Exponential cumulative distribution function for x = A and lambda = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ECRIT** | 2 1 | Exponential distribution critical value for alpha = A and lambda = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **EPDF** | 2 1 | Exponential probability density function for x = A and lambda = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ERF** | 1 1 | Error function erf (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ERFC** | 1 1 | Complementary Error function erfc (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ERFINV** | 1 1 | Inverse error function of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **EQ** | 2 1 | 1 if A == B, else 0 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **EXCH** | 2 2 | Exchanges A and B on the stack |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **EXP** | 1 1 | exp (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FACT** | 1 1 | A! (A factorial) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FCDF** | 3 1 | F cumulative distribution function for F = A, nu1 = B, and nu2 = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FCRIT** | 3 1 | F distribution critical value for alpha = A, nu1 = B, and nu2 = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FLIPUD** | 1 1 | Reverse order of each column |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FLOOR** | 1 1 | floor (A) (greatest integer <= A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FMOD** | 2 1 | A % B (remainder after truncated division) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **FPDF** | 3 1 | F probability density function for F = A, nu1 = B, and nu2 = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **IFELSE** | 3 1 | B if A != 0, else C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **IN** | 2 1 | Modified Bessel function of A (1st kind, order B) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **INRANGE** | 3 1 | 1 if B <= A <= C, else 0 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **INT** | 1 1 | Numerically integrate A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **INV** | 1 1 | 1 / A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ISFINITE** | 1 1 | 1 if A is finite, else 0 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **KN** | 2 1 | Modified Bessel function of A (2nd kind, order B) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **KEI** | 1 1 | kei (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **KER** | 1 1 | ker (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **KURT** | 1 1 | Kurtosis of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LCDF** | 1 1 | Laplace cumulative distribution function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LCRIT** | 1 1 | Laplace distribution critical value for alpha = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LE** | 2 1 | 1 if A <= B, else 0 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LMSSCL** | 1 1 | LMS scale estimate (LMS STD) of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LMSSCLW** | 2 1 | Weighted LMS scale estimate (LMS STD) of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LPDF** | 1 1 | Laplace probability density function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LRAND** | 2 1 | Laplace random noise with mean A and std. deviation B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LSQFIT** | 1 0 | Let current table be [A \| b] return least squares solution x = A \\ b |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **LT** | 2 1 | 1 if A < B, else 0 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MAD** | 1 1 | Median Absolute Deviation (L1 STD) of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MADW** | 2 1 | Weighted Median Absolute Deviation (L1 STD) of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MAX** | 2 1 | Maximum of A and B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MEAN** | 1 1 | Mean value of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MEANW** | 2 1 | Weighted mean value of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MEDIAN** | 1 1 | Median value of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MEDIANW** | 2 1 | Weighted median value of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **MODEW** | 2 1 | Weighted mode value (Least Median of Squares) of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **NORM** | 1 1 | Normalize (A) so max(A)-min(A) = 1 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 B == NaN, else A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **PCDF** | 2 1 | Poisson cumulative distribution function for x = A and lambda = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **PERM** | 2 1 | Permutations n_P_r, with n = A and r = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **PPDF** | 2 1 | Poisson distribution P(x,lambda), with x = A and lambda = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **PQUANTW** | 3 1 | The C'th weighted quantile (0-100%) of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **RCDF** | 1 1 | Rayleigh cumulative distribution function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **RCRIT** | 1 1 | Rayleigh distribution critical value for alpha = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **RINT** | 1 1 | rint (A) (round to integral value nearest to A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **RMS** | 1 1 | Root-mean-square of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **RPDF** | 1 1 | Rayleigh probability density function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ROLL** | 2 0 | Cyclicly shifts the top A stack items by an amount B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ROTT** | 2 1 | Rotate A by the (constant) shift B in the t-direction |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **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 |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **STDW** | 2 1 | Weighted standard deviation of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **STEP** | 1 1 | Heaviside step function H(A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **STEPT** | 1 1 | Heaviside step function H(t-A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **SUB** | 2 1 | A - B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **SUM** | 1 1 | Cumulative sum of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TAN** | 1 1 | tan (A) (A in radians) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TAND** | 1 1 | tan (A) (A in degrees) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TANH** | 1 1 | tanh (A) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TAPER** | 1 1 | Unit weights cosine-tapered to zero within A of end margins |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TN** | 2 1 | Chebyshev polynomial Tn(-1<A<+1) of degree B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TCRIT** | 2 1 | Student's t distribution critical value for alpha = A and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TPDF** | 2 1 | Student's t probability density function for t = A, and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **TCDF** | 2 1 | Student's t cumulative distribution function for t = A, and nu = B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **UPPER** | 1 1 | The highest (maximum) value of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **VAR** | 1 1 | Variance of A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **VARW** | 2 1 | Weighted variance of A for weights in B |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **WCDF** | 3 1 | Weibull cumulative distribution function for x = A, scale = B, and shape = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **WCRIT** | 3 1 | Weibull distribution critical value for alpha = A, scale = B, and shape = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **WPDF** | 3 1 | Weibull density distribution P(x,scale,shape), with x = A, scale = B, and shape = C |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **XOR** | 2 1 | B if A == 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) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **YN** | 2 1 | Bessel function of A (2nd kind, order B) |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ZCDF** | 1 1 | Normal cumulative distribution function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ZPDF** | 1 1 | Normal probability density function for z = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ZCRIT** | 1 1 | Normal distribution critical value for alpha = A |
+-----------------+--------+--------------------------------------------------------------------------------------------+
| **ROOTS** | 2 1 | Treats col A as f(t) = 0 and returns its roots |
+-----------------+--------+--------------------------------------------------------------------------------------------+
Symbols
-------
The following symbols have special meaning:
+-------------+-----------------------------------------+
| **PI** | 3.1415926... |
+-------------+-----------------------------------------+
| **E** | 2.7182818... |
+-------------+-----------------------------------------+
| **EULER** | 0.5772156... |
+-------------+-----------------------------------------+
| **EPS_F** | 1.192092896e-07 (sgl. prec. eps) |
+-------------+-----------------------------------------+
| **EPS_D** | 2.2204460492503131e-16 (dbl. prec. eps) |
+-------------+-----------------------------------------+
| **TMIN** | Minimum t value |
+-------------+-----------------------------------------+
| **TMAX** | Maximum t value |
+-------------+-----------------------------------------+
| **TRANGE** | Range of t values |
+-------------+-----------------------------------------+
| **TINC** | t increment |
+-------------+-----------------------------------------+
| **N** | The number of records |
+-------------+-----------------------------------------+
| **T** | Table with t-coordinates |
+-------------+-----------------------------------------+
| **TNORM** | Table with normalized t-coordinates |
+-------------+-----------------------------------------+
| **TROW** | Table with row numbers 1, 2, ..., N-1 |
+-------------+-----------------------------------------+
.. include:: explain_precision.rst_
Notes On Operators
------------------
1. The operators **PLM** and **PLMg** calculate the associated Legendre
polynomial of degree L and order M in x which must satisfy -1 <= x <= +1
and 0 <= M <= L. x, L, and M are the three arguments preceding the
operator. **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).
2. Files that have the same names as some operators, e.g., **ADD**,
**SIGN**, **=**, etc. should be identified by prepending the current
directory (i.e., ./).
3. The stack depth limit is hard-wired to 100.
4. All functions expecting a positive radius (e.g., **LOG**, **KEI**,
etc.) are passed the absolute value of their argument.
5. The **DDT** and **D2DT2** functions only work on regularly spaced data.
6. All derivatives are based on central finite differences, with
natural boundary conditions.
7. **ROOTS** must be the last operator on the stack, only followed by **=**.
.. include:: explain_sto_rcl_clr.rst_
8. The bitwise operators
(**BITAND**, **BITLEFT**, **BITNOT**, **BITOR**, **BITRIGHT**,
**BITTEST**, and **BITXOR**) convert a tables's double precision values
to unsigned 64-bit ints to perform the bitwise operations. Consequently,
the largest whole integer value that can be stored in a double precision
value is 2^53 or 9,007,199,254,740,992. Any higher result will be masked
to fit in the lower 54 bits. Thus, bit operations are effectively limited
to 54 bits. All bitwise operators return NaN if given NaN arguments or
bit-settings <= 0.
9. TAPER will interpret its argument to be a width in the same units as
the time-axis, but if no time is provided (i.e., plain data tables) then
the width is taken to be given in number of rows.
Macros
------
Users may save their favorite operator combinations as macros via the
file *gmtmath.macros* in their current or user directory. The file may contain
any number of macros (one per record); comment lines starting with # are
skipped. The format for the macros is **name** = **arg1 arg2 ... arg2**
[ : *comment*] where **name** is how the macro will be used. When this
operator appears on the command line we simply replace it with the
listed argument list. No macro may call another macro. As an example,
the following macro expects that the time-column contains seafloor ages
in Myr and computes the predicted half-space bathymetry:
**DEPTH** = **SQRT 350 MUL 2500 ADD NEG** : *usage: DEPTH to return
half-space seafloor depths*
Note: Because geographic or time constants may be present in a macro, it
is required that the optional comment flag (:) must be followed by a space.
As another example, we show a macro **GPSWEEK** which determines which GPS week
a timestamp belongs to:
**GPSWEEK** = 1980-01-06T00:00:00 SUB 86400 DIV 7 DIV FLOOR : GPS week without rollover
Active Column Selection
-----------------------
When **-C**\ *cols* is set then any operation, including loading of data from files, will
restrict which columns are affected.
To avoid unexpected results, note that if you issue a **-C**\ *cols* option before you load
in the data then only those columns will be updated, hence the unspecified columns will be zero.
On the other hand, if you load the file first and then issue **-C**\ *cols* then the unspecified
columns will have been loaded but are then ignored until you undo the effect of **-C**.
Examples
--------
To take the square root of the content of the second data column being
piped through **gmtmath** by process1 and pipe it through a 3rd process, use
::
process1 | gmt math STDIN SQRT = | process3
To take log10 of the average of 2 data files, use
::
gmt math 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:
::
gmt math 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
::
gmt math -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
::
gmt set mode_age = `gmt math -S -T ages.d MODE =`
To evaluate the dilog(x) function for coordinates given in the file t.d:
::
gmt math -Tt.d T DILOG = dilog.d
To demonstrate the use of stored variables, consider this sum of the
first 3 cosine harmonics where we store and repeatedly recall the
trigonometric argument (2\*pi\*T/360):
::
gmt math -T0/360/1 2 PI MUL 360 DIV T MUL STO@kT COS @kT 2 MUL COS ADD \
@kT 3 MUL COS ADD = harmonics.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 = `gmt math -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
operator **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 1 and your observed y(t) in column 3. The
calculation becomes
::
gmt math -N4/1 -Aty.d -C0 1 ADD -C2 1.55 STEPT ADD -Ca LSQFIT = solution.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 (col
numbers 1 and 3) are preloaded with t and y(t), respectively, the other
columns are zero. If you already have a pre-calculated table with the
augmented matrix [ A \| b ] in a file (say lsqsys.d), the least squares
solution is simply
::
gmt math -T lsqsys.d LSQFIT = solution.d
Users must be aware that when **-C** controls which columns are to be
active the control extends to placing columns from files as well.
Contrast the different result obtained by these very similar commands:
::
echo 1 2 3 4 | gmt math STDIN -C3 1 ADD =
1 2 3 5
versus
::
echo 1 2 3 4 | gmt math -C3 STDIN 1 ADD =
0 0 0 5
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 normalized 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
--------
:doc:`gmt`,
:doc:`grdmath`
|
