NAME

     surface - adjustable tension  continuous  curvature  surface
     gridding algorithm


SYNOPSIS

     surface       [       xyzfile       ]       -Goutputfile.grd
     -Ix_inc[m|c][/y_inc[m|c]]    -Rwest/east/south/north[r]    [
     -Aaspect_ratio ] [ -Cconvergence_limit  ]  [  -H[nrec]  ]  [
     -Lllower  ]  [  -Luupper  ]  [  -Nmax_iterations  ] [ -Q ] [
     -Ssearch_radius[m] ] [ -Ttension_factor[ib] ] [  -V[l]  ]  [
     -Zover-relaxation_factor ] [ -: ] [ -bi[s][n] ]


DESCRIPTION

     surface reads randomly-spaced (x,y,z) triples from  standard
     input  [or xyzfile] and produces a binary grdfile of gridded
     values z(x,y) by solving:

          (1 - T) * L (L (z)) + T * L (z) = 0

     where T is a tension factor between 0 and 1, and L indicates
     the Laplacian operator.  T = 0 gives the "minimum curvature"
     solution which is equivalent to SuperMISP and the ISM  pack-
     ages.   Minimum  curvature  can cause undesired oscillations
     and false local maxima or  minima  (See  Smith  and  Wessel,
     1990),  and  you  may  wish  to  use T > 0 to suppress these
     effects.  Experience suggests T ~ 0.25  usually  looks  good
     for  potential  field data and T should be larger (T ~ 0.35)
     for steep topography data.  T = 1 gives a  harmonic  surface
     (no  maxima  or  minima  are possible except at control data
     points).  It is recommended that the  user  pre-process  the
     data with blockmean, blockmedian, or blockmode to avoid spa-
     tial aliasing and eliminate redundant data.  You may  impose
     lower  and/or  upper  bounds  on the solution.  These may be
     entered in the form of a fixed value, a grdfile with values,
     or simply be the minimum/maximum input data values.

     xyzfile
          3 column ASCII file [or binary, see -b] holding (x,y,z)
          data  values.   If  no  file is specified, surface will
          read from standard input.

     -G   Output file name.  Output is a binary 2-D .grd file.

     -I   x_inc [and  optionally  y_inc]  is  the  grid  spacing.
          Append m to indicate minutes or c to indicate seconds.

     -R   west, east, south, and  north  specify  the  Region  of
          interest.  To specify boundaries in degrees and minutes
          [and seconds], use the dd:mm[:ss] format.  Append r  if
          lower  left  and  upper right map coordinates are given
          instead of wesn.


OPTIONS

     -A   Aspect ratio.  If desired, grid anisotropy can be added
          to  the equations.  Enter aspect_ratio, where dy = dx /
          aspect_ratio relates the grid dimensions.  [Default = 1
          assumes isotropic grid.]

     -C   Convergence limit.  Iteration is assumed to  have  con-
          verged  when  the  maximum  absolute change in any grid
          value is less than convergence_limit.  (Units  same  as
          data  z  units).   [Default is scaled to 0.1 percent of
          typical gradient in input data.]

     -H   Input file(s) has Header record(s).  Number  of  header
          records  can  be  changed  by editing your .gmtdefaults
          file.  If used, GMT default is 1  header  record.   Not
          used with binary data.

     -L   Impose limits on the output solution.  llower sets  the
          lower  bound.   lower can be the name of a grdfile with
          lower bound values, a fixed value, d to set to  minimum
          input  value, or u for unconstrained [Default].  uupper
          sets the upper bound and can be the name of  a  grdfile
          with  upper  bound  values,  a fixed value, d to set to
          maximum input value, or u for unconstrained [Default].

     -N   Number  of  iterations.   Iteration  will  cease   when
          convergence_limit  is  reached or when number of itera-
          tions reaches max_iterations. [Default is 250.]

     -Q   Suggest grid dimensions which have a  highly  composite
          greatest  common  factor.  This  allows  surface to use
          several intermediate steps in  the  solution,  yielding
          faster  run  times  and  better results. The sizes sug-
          gested by -Q can be achieved by altering -R and/or  -I.
          You  can  recover the -R and -I you want later by using
          grdsample or grdcut on the output of surface.

     -S   Search radius.  Enter search_radius in  same  units  as
          x,y  data;  append m to indicate minutes.  This is used
          to initialize the grid before the first  iteration;  it
          is  not worth the time unless the grid lattice is prime
          and cannot have regional stages.  [Default = 0.0 and no
          search is made.]

     -T   Tension factor[s].  These must  be  between  0  and  1.
          Tension  may  be  used  in the interior solution (above
          equation, where it  suppresses  spurious  oscillations)
          and in the boundary conditions (where it tends to flat-
          ten the solution approaching the  edges).   Using  zero
          for  both values results in a minimum curvature surface
          with free edges, i.e. a natural  bicubic  spline.   Use
          -Ttension_factori   to   set   interior   tension,  and
          -Ttension_factorb to set boundary tension.  If  you  do
          not  append i or b, both will be set to the same value.
          [Default = 0 for both  gives  minimum  curvature  solu-
          tion.]

     -V   Selects verbose mode, which will send progress  reports
          to  stderr  [Default runs "silently"].  -Vl will report
          the convergence after each iteration;  -V  will  report
          only after each regional grid is converged.

     -Z   Over-relaxation factor.   This  parameter  is  used  to
          accelerate  the  convergence;  it is a number between 1
          and 2.  A value of 1 iterates  the  equations  exactly,
          and  will  always  assure  stable  convergence.  Larger
          values overestimate the incremental changes during con-
          vergence,  and  will  reach a solution more rapidly but
          may become unstable.  If you use a large value for this
          factor,  it  is  a  good idea to monitor each iteration
          with the -Vl option.  [Default = 1.4 converges  quickly
          and is almost always stable.]

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -bi  Selects binary input.  Append s  for  single  precision
          [Default  is  double].   Append  n  for  the  number of
          columns in the binary file(s).   [Default  is  3  input
          columns].


EXAMPLES

     To grid 5 by 5 minute gravity block  means  from  the  ASCII
     data  in  hawaii_5x5.xyg,  using  a tension_factor = 0.25, a
     convergence_limit = 0.1 milligal, writing the  result  to  a
     file  called  hawaii_grd.grd, and monitoring each iteration,
     try:

     surface hawaii_5x5.xyg -R198/208/18/25 -I5m -Ghawaii_grd.grd
     -T0.25 -C0.1 -VL


BUGS

     surface will complain when more than one data point is found
     for  any  node  and  suggest  that you run blockmean, block-
     median, or blockmode first.  If  you  did  run  blockm*  and
     still get this message it usually means that your grid spac-
     ing is so small that you need more decimals  in  the  output
     format used by blockm*.  You may specify more decimal places
     by editing the parameter D_FORMAT in your .gmtdefaults  file
     prior to running blockm*, or choose binary input and/or out-
     put using single or double precision storage.



SEE ALSO

     blockmean(l),    blockmedian(l),    blockmode(l),    gmt(l),
     nearneighbor(l), triangulate(l)


REFERENCES

     Smith, W. H. F, and P. Wessel, 1990, Gridding with  continu-
     ous curvature splines in tension, Geophysics, 55, 293-305.