Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       grdpmodeler - Evaluate a plate model on a geographic grid

SYNOPSIS

       grdpmodeler agegrdfile rot_file -Sflags [ polygonfile ] [ outgrdfile ] [ age ] [ [level] ]
       [ -b<binary> ] [ -d<nodata> ] [ -h<headers> ] [ -i<flags> ] [ -:[i|o] ]

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

DESCRIPTION

       grdpmodeler reads a geographical age grid 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 grid inside the  polygon  is  used  to
       determine the model prediction; the remainder of the grid is set to NaN.

REQUIRED ARGUMENTS

       ingrdfile
              Name of a grid file in geographical (lon, lat) coordinates with ages in Myr.

       -Erotfile
              Give  file  with  rotation  parameters.  This file must contain one record for each
              rotation; each record must be of the following format:

              lon lat tstart [tstop] angle [ khat a b c d e f g df ]

              where tstart and tstop are in Myr and lon lat angle  are  in  degrees.  tstart  and
              tstop are the ages of the old and young ends of a stage. If tstop is not present in
              the record then a total reconstruction rotation is expected and tstop is implicitly
              set  to  0  and  should  not  be specified for any of the records in the file. If a
              covariance matrix C for the rotation is available it must be specified in a  format
              using  the  nine optional terms listed in brackets. Here, C = (g/khat)*[ a b d; b c
              e; d e f ] which shows C made up of three row vectors. If the  degrees  of  freedom
              (df)  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.

       -Sflags
              Type of model prediction(s). Append one or more items:  choose  from  a  for  plate
              motion azimuth, d for great-circle distance between current location and its origin
              at the ridge (in km), s for plate motion model stage ID  (1  is  youngest),  v  for
              plate  motion rate (in mm/yr), w for plate rotation rate (degree/Myr), x for change
              in longitude relative to location of crust formation,  y  for  change  in  latitude
              relative  to location of crust formation, X for longitude of crust formation, and Y
              for latitude of crust formation.  If no arguments  are  given  we  default  to  all
              [adsvwxyXY].

OPTIONAL ARGUMENTS

       -Fpolygonfile
              Specify  a  multisegment  closed polygon file that describes the inside area of the
              grid where the model should be evaluated; the outside will be set to  NaN  [Default
              evaluates model on the entire grid].

       -Goutgrdfile
              Name  of  output  grid.  This  is  the  grid  with  the model predictions given the
              specified rotations. Note: If you specified more than one model  prediction  in  -S
              then  the  filename  must  be  a template that contains the format %s; this will be
              replaced with the corresponding tags az, dist, stage, vel, omega, dlon, dlat,  lon,
              lat.   If  the -G option is not used then we create no grids and instead write lon,
              lat, age, predictions records to standard output.

       -Tage  Use a fixed age for model evaluation (i.e., override the ages  in  the  age  grid).
              This lets you evaluate the model at a snapshot in time.

       -V[level] (more ...)
              Select verbosity level [c].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -d[i|o]nodata (more ...)
              Replace input columns that equal nodata with NaN and do the reverse on output.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (0 is first column).

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              use just -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print  a  complete usage (help) message, including the explanation of options, then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

GEODETIC VERSUS GEOCENTRIC COORDIINATES

       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.

EXAMPLES

       We will use a grid with Pacific crust ages (pac_age.nc), a plate motion model (Pac_APM.d),
       and a polygon that contains the outline of the present Pacific plate (pac_clip_path.d). To
       evaluate the plate motion azimuths at the present time for the Pacific, try

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d \
                              -Gpac_dir_0.nc -Sa -T0

       To determine the changes in latitude since crust formation for the entire Pacific, try

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d \
                              -Gpac_dlat.nc -Sy

       To determine the plate motion velocities in effect when the Pacific crust was formed, try

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d \
                              -Gpac_vel.nc -Sv

       To determine how far the crust has moved since formation, try

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d \
                              -Gpac_dist.nc -Sd

       To save the coordinates of the crust's formation to separate grids, try

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d \
                              -Gpac_origin_%s.nc -SXY

       To repeat the same exercise but save output lon,lat,age,xorigin,yorigin to a table, use

              gmt grdpmodeler pac_age.nc -EPac_APM.d -V -Fpac_clip_path.d -SXY > origin.txt

NOTES

       GMT distributes the EarthByte rotation model Global_EarthByte_230-0Ma_GK07_AREPS.rot.   To
       use an alternate rotation file, create an environmental parameters named GPLATES_ROTATIONS
       that points to an alternate rotation file.

SEE ALSO

       backtracker, grdrotater, grdspotter, hotspotter, originator, rotconverter

COPYRIGHT

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe