earthtide

Compute grids or time-series of solid Earth tides

Synopsis

gmt earthtide -T[min/max/]inc[+i|n] |-Tfile|list -Goutgrid [ -Cx|e,y|n,z|v ] [ -Iincrement ] [ -Llon/lat ] [ -Rregion ] [ -S ] [ -V[level] ] [ -rreg ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

Compute the three components of solid Earth tides as time-series or grids. Optionally compute also Sun and Moon position in (lon, lat). The output can be either in the form of a grid or as a table printed to standard output. The format of the table data is: time north east vertical in units of meters.

Required Arguments

Either -G, -S or -L must be provided.

-Goutgrid[=ID][+ddivisor][+ninvalid][+ooffset|a][+sscale|a][:driver[dataType][+coptions]]

Optionally, append =ID for writing a specific file format. The following modifiers are supported:

+d - Divide data values by given divisor [Default is 1].

+n - Replace data values matching invalid with a NaN.

+o - Offset data values by the given offset, or append a for automatic range offset to preserve precision for integer grids [Default is 0].

+s - Scale data values by the given scale, or append a for automatic scaling to preserve precision for integer grids [Default is 1].

Note: Any offset is added before any scaling. +sa also sets +oa (unless overridden). To write specific formats via GDAL, use =gd and supply driver (and optionally dataType) and/or one or more concatenated GDAL -co options using +c. See the “Writing grids and images” cookbook section for more details.

-S: Output position of Sun and Moon in geographical coordinates plus distance in meters. Output is a Mx7 matrix where M is the number of times (set by -T) and columns are time, sun_lon, sun_lat, sun_dist moon_lon, moon_lat, moon_dist

-Llon/lat: Geographical coordinate of the location where to compute a time-series. Coordinates are geodetic (ellipsoidal) latitude and longitude. GRS80 ellipsoid is used. (Which can be considered equivalent to the WGS84 ellipsoid at the sub-millimeter level.)

Optional Arguments

-Cx|e,y|n,z|v: Select which component to write to individual grids. Requires -G. Append comma-separated codes for available components: x or e for the east component; y or n for the north component; and z or v for the vertical component. For example, -Ce,v, will write 2 grids. One with east and other with the vertical components. If -G is set but not -C then the default is to write the vertical component.

-Ix_inc[+e|n][/y_inc[+e|n]]

Set the grid spacing as x_inc [and optionally y_inc].

Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among:

d - Indicate arc degrees

m - Indicate arc minutes

s - Indicate arc seconds

If one of e (meter), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), the increment will be converted to the equivalent degrees longitude at the middle latitude of the region (the conversion depends on PROJ_ELLIPSOID). If y_inc is not given or given but set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude.

All coordinates: The following modifiers are supported:

+e - Slightly adjust the max x (east) or y (north) to fit exactly the given increment if needed [Default is to slightly adjust the increment to fit the given domain].

+n - Define the number of nodes rather than the increment, in which case the increment is recalculated from the number of nodes, the registration (see GMT File Formats), and the domain. Note: If -Rgrdfile is used then the grid spacing and the registration have already been initialized; use -I and -R to override these values.

-Rxmin/xmax/ymin/ymax[+r][+uunit]: Specify the region of interest. (See full description) (See technical reference).

-T[min/max/]inc[+i|n] |-Tfile|list: Make evenly spaced time-steps from min to max by inc. Append +i to indicate the reciprocal increment was given, or append +n to indicate inc is the number of t-values to produce over the range instead. Append a valid time unit (d|h|m|s) to the increment. If only min is given then we use that date and time for the calculations. If no -T is provided get current time in UTC from the computer clock. If no -G or -S are provided then -T is interpreted to mean compute a time-series at the location specified by -L, thus then -L becomes mandatory. When -G and -T, only first time T series is considered. Finally, dates may range from 1901 through 2099. For details on array creation, see Generate 1-D Array.

-borecord[+b|l] (more …): Select native binary format for table output.

-ocols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …): Select output columns and transformations (0 is first column, t is trailing text, append word to write one word only).

-r[g|p] (more …): Set node registration [gridline].

-V[level]: Select verbosity level [w]. (See full description) (See technical reference).

-^ or just -: Print a short message about the syntax of the command, then exit (Note: on Windows just use -).
-+ or just +: Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Generate 1-D Array

We will demonstrate the use of options for creating 1-D arrays via math. Make an evenly spaced coordinate array from min to max in steps of inc, e.g.:

gmt math -o0 -T3.1/4.2/0.1 T =
1
2
3
4
5
6
7
...

Append +b if we should take \(\log_2\) of min and max, get their nearest integers, build an equidistant \(\log_2\)-array using inc integer increments in \(\log_2\), then undo the \(\log_2\) conversion. E.g., -T3/20/1+b will produce this sequence:

gmt math -o0 -T3/20/1+b T =
4
8
16

Append +l if we should take \(\log_{10}\) of min and max and build an array where inc can be 1 (every magnitude), 2, (1, 2, 5 times magnitude) or 3 (1-9 times magnitude). E.g., -T7/135/2+l will produce this sequence:

gmt math -o0 -T7/135/2+l T =
10
20
50
100

For output values less frequently than every magnitude, use a negative integer inc:

gmt math -o0 -T1e-4/1e4/-2+l T =
0.0001
0.01
1
100
10000

Append +i if inc is a fractional number and it is cleaner to give its reciprocal value instead. To set up times for a 24-frames per second animation lasting 1 minute, run:

gmt math -o0 -T0/60/24+i T =
0
0.0416666666667
0.0833333333333
0.125
0.166666666667
...

Append +n if inc is meant to indicate the number of equidistant coordinates instead. To have exactly 5 equidistant values from 3.44 and 7.82, run:

gmt math -o0 -T3.44/7.82/5+n T =
44
535
63
725
82

Alternatively, let inc be a file with output coordinates in the first column, or provide a comma-separated list of specific coordinates, such as the first 6 Fibonacci numbers:

gmt math -o0 -T0,1,1,2,3,5 T =
0
1
1
2
3
5

Notes: (1) If you need to pass the list nodes via a dataset file yet be understood as a list (i.e., no interpolation), then you must set the file header to contain the string “LIST”. (2) Should you need to ensure that the coordinates are unique and sorted (in case the file or list are not sorted or have duplicates) then supply the +u modifier.

If you only want a single value then you must append a comma to distinguish the list from the setting of an increment.

If the module allows you to set up an absolute time series, append a valid time unit from the list year, month, day, hour, minute, and second to the given increment; add +t to ensure time column (or use -f). Note: The internal time unit is still controlled independently by TIME_UNIT. The first 7 days of March 2020:

gmt math -o0 -T2020-03-01T/2020-03-07T/1d T =
2020-03-01T00:00:00
2020-03-02T00:00:00
2020-03-03T00:00:00
2020-03-04T00:00:00
2020-03-05T00:00:00
2020-03-06T00:00:00
2020-03-07T00:00:00

A few modules allow for +a which will paste the coordinate array to the output table.

Likewise, if the module allows you to set up a spatial distance series (with distances computed from the first two data columns), specify a new increment as inc with a geospatial distance unit from the list degree (arc), minute (arc), second (arc), meter, foot, kilometer, Miles (statute), nautical miles, or survey foot; see -j for calculation mode. To interpolate Cartesian distances instead, you must use the special unit c.

Finally, if you are only providing an increment and will obtain min and max from the data, then it is possible (max - min)/inc is not an integer, as required. If so, then inc will be adjusted to fit the range. Alternatively, append +e to keep inc exact and adjust max instead (keeping min fixed).

Examples

To compute a global grid of the vertical component with a grid step of 30m at noon of 18 Jun 2018, (note: we are using the defaults for -R and -I) try

gmt earthtide -T2018-06-18T12:00:00 -Gsolid_tide_up.grd

To obtain a one day long time-series, starting at same date, at the -7 W, 37 N and 1 minute interval, try

gmt earthtide -T2018-06-18T/2018-06-19T/1m -L-7/37 > solid_tide.txt

The get the Sun and Moon position in geographical coordinates at the now time

gmt earthtide -S

Notes

All times, both input and output, are in UTC.

References

http://geodesyworld.github.io/SOFTS/solid.htm