.\" Man page generated from reStructuredText.
.
.TH "GMTPMODELER" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
gmtpmodeler \- Evaluate a plate motion model at given locations
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgmtpmodeler\fP \fItable\fP  \fB\-E\fP\fIrot_file\fP \fB\-S\fP\fIflags\fP
[  \fB\-F\fP\fIpolygonfile\fP ]
[  \fB\-T\fP\fIage\fP ]
[  \fB\-V\fP[\fIlevel\fP] ]
[ \fB\-b\fPbinary ]
[ \fB\-d\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-o\fPflags ]
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgmtpmodeler\fP reads a table with \fIlon\fP, \fIlat\fP and optionally \fIage\fP triplets
and a plate motion model
and evaluates one of several model predictions. Optionally, the user may
supply a clipping polygon in multiple\-segment format; then, only the
part of the points inside the polygon are used to determine the model
prediction.  The results are written to standard output.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
Name of one or more tables with geographical (lon, lat) coordinates and optionally
a third column with ages in Myr.  If no file is given then we read from standard input.
.UNINDENT
.INDENT 0.0
.TP
\fB\-E\fP\fIrotfile\fP
Give file with rotation parameters. This file must contain one
record for each rotation; each record must be of the following
format:
.sp
\fIlon lat tstart [tstop] angle\fP [ \fIkhat a b c d e f g df\fP ]
.sp
where \fItstart\fP and \fItstop\fP are in Myr and \fIlon lat angle\fP are in
degrees. \fItstart\fP and \fItstop\fP are the ages of the old and young ends
of a stage. If \fItstop\fP is not present in the record then a total
reconstruction rotation is expected and \fItstop\fP is implicitly set to
0 and should not be specified for any of the records in the file. If
a covariance matrix \fBC\fP for the rotation is available it must be
specified in a format using the nine optional terms listed in
brackets. Here, \fBC\fP = (\fIg\fP/\fIkhat\fP)*[ \fIa b d; b c e; d e f\fP ]
which shows \fBC\fP made up of three row vectors. If the degrees of
freedom (\fIdf\fP) in fitting the rotation is 0 or not given it is set
to 10000. Blank lines and records whose first column contains # will
be ignored. You may prepend a leading + to the filename to indicate
you wish to invert the rotations.
Alternatively, give the filename composed of two plate IDs
separated by a hyphen (e.g., PAC\-MBL) and we will instead extract
that rotation from the GPlates rotation database. We return an error
if the rotation cannot be found.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP\fIflags\fP
Type of model prediction(s). Append one or more items: choose from \fBa\fP for plate motion
azimuth, \fBd\fP for great\-circle distance between current location and its
origin at the ridge (in km), \fBs\fP for plate motion model stage ID (1 is youngest),
\fBv\fP for plate motion rate (in mm/yr),
\fBw\fP for plate rotation rate (degree/Myr), \fBx\fP for change in
longitude relative to location of crust formation, \fBy\fP for change in
latitude relative to location of crust formation, \fBX\fP for longitude of
crust formation, and \fBY\fP for latitude of crust formation.
If no arguments are given we default to all [\fBadsvwxyXY\fP].
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-F\fP\fIpolygonfile\fP
Specify a multisegment closed polygon file that describes the
area where the model should be evaluated; points outside
will be skipped [use all data points].
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP\fIage\fP
Use a fixed age for model evaluation (i.e., override the ages given in the
input table). This lets you evaluate the model at a snapshot in time, and is
a required option if the input table does not contain ages.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2 input columns].
.UNINDENT
.INDENT 0.0
.TP
\fB\-d\fP[\fBi\fP|\fBo\fP]\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN and do the reverse on output.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP] (more ...)
Select input columns and transformations (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-o\fP\fIcols\fP[,...] (more ...)
Select output columns (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH GEODETIC VERSUS GEOCENTRIC COORDIINATES
.sp
All spherical rotations are applied to geocentric coordinates.
This means that incoming data points and grids are considered
to represent geodetic coordinates and must first
be converted to geocentric coordinates. Rotations are then applied, and the
final reconstructed points are converted back to geodetic
coordinates.  This default behavior can be bypassed if the
ellipsoid setting PROJ_ELLIPSOID
is changed to Sphere.

.sp
.ce
----

.ce 0
.sp
.SH EXAMPLES
.sp
We will use a table with locations and ages of Pacific crust (pac_age.txt), a plate motion
model (Pac_APM.txt), and a polygon that contains the outline of the
present Pacific plate (pac_clip_path.txt). To evaluate the plate motion
azimuths at the present time for the Pacific, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt gmtpmodeler pac_age.txt \-EPac_APM.txt \-V \-Fpac_clip_path.txt \e
                 \-Sa \-T0 > pac_dir_0.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To determine the changes in latitude since crust formation for the
entire Pacific, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt gmtpmodeler pac_age.txt \-EPac_APM.txt \-V \-Fpac_clip_path.txt \e
                \-Sy > pac_dlat.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To determine the plate motion velocities in effect when the Pacific crust was
formed, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt gmtpmodeler pac_age.txt \-EPac_APM.txt \-V \-Fpac_clip_path.txt \e
                \-Sv > pac_vel.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To determine how far the crust has moved since formation, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt gmtpmodeler pac_age.txt \-EPac_APM.txt \-V \-Fpac_clip_path.txt \e
                \-Sd > pac_dist.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To save the coordinates of the crust\(aqs formation, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt gmtpmodeler pac_age.txt \-EPac_APM.txt \-V \-Fpac_clip_path.txt \e
                \-SXY > ac_origin_xy.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH NOTES
.sp
GMT distributes the EarthByte rotation model Global_EarthByte_230\-0Ma_GK07_AREPS.rot.
To use an alternate rotation file, create an environmental parameters named
\fBGPLATES_ROTATIONS\fP that points to an alternate rotation file.
.SH SEE ALSO
.sp
backtracker,
grdpmodeler,
grdrotater,
grdspotter,
hotspotter,
originator,
rotconverter
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.