# earthtide¶

Compute grids or time-series of solid Earth tides

## Synopsis¶

**gmt earthtide**
**-T**[*min/max*/]*inc*[**+i**|**n**] |**-T***file*|*list*
**-G***outgrid*
[ **-C***x|e,y|n,z|v* ]
[ **-I***increment* ]
[ **-L***lon/lat* ]
[ **-R***region* ]
[ **-S** ]
[ **-V**[*level*] ]
[ **-r**reg ]
[ **--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 stdout. 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.

**-G***outgrid*[=*ID*][**+d***divisor*][**+n***invalid*]
[**+o***offset*|**a**][**+s***scale*|**a**]
[:*driver*[*dataType*][**+c***options*]]

Write one or more tide component directly to grids; no table data are written to standard output. If more than one component are specified via

-Cthenoutgridmust contain the format flag %s so that we can embed the component code in the file names (nfor north;efor east andvfor vertical). If only one component is selected with-Cthan no code is appended to grid name (and no need to set the format flag %s). The grid(s) are computed at the time set by-T, if that option is used, or at thenowtime calculated in UTC from the computer clock. Optionally, append =IDfor writing a specific file format (See full description). The following modifiers are supported:

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

+n- Replace data values matchinginvalidwith a NaN.

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

+s- Scale data values by the givenscale, or appendafor automatic scaling to preserve precision for integer grids [Default is 1].Note: Any offset is added before any scaling.

+saalso sets+oa(unless overridden). To write specific formats via GDAL, use =gdand supplydriver(and optionallydataType) and/or one or more concatenated GDAL-cooptions 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

**-L***lon/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¶

**-C****x**|**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.

**-I***x_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:**m**to indicate arc minutes**s**to indicate arc seconds**e**(meter),**f**(foot),**k**(km),**M**(mile),**n**(nautical mile) or**u**(US survey foot), in which case 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 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**to 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**to 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**-R***grdfile*is used then the grid spacing and the registration have already been initialized; use**-I**and**-R**to override these values.

**-R***xmin*/*xmax*/*ymin*/*ymax*[**+r**][**+u***unit*]Specify the region of interest. (See full description) (See cookbook information).

**-T**[*min/max*/]*inc*[**+i**|**n**] |**-T***file*|*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 1D Array.

**-bo***record*[**+b**|**l**] (more …)Select native binary format for table output.

**-o***cols*[,…][,**t**[*word*]] (more …)Select output columns (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 cookbook information).

**-^**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 argumentsPrint 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 1D Array¶

We will demonstrate the use of options for creating 1-D arrays via gmtmath.
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 =
3.1
3.2
3.3
3.4
3.5
3.6
3.7
```

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

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

Append **+l** if we should take log10 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., **-T**7/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 =
3.44
4.535
5.63
6.725
7.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
```

**Note**: 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
**y**ear, m**o**nth, **d**ay, **h**our, **m**inute, and **s**econd
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
**d**egree (arc), **m**inute (arc), **s**econd (arc), m**e**ter, **f**oot, **k**ilometer,
**M**iles (statute), **n**autical miles, or s**u**rvey 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.dat
```

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.