                                 TAU
   
   The files in this anonymous FTP implement the travel time computation
algorithm described by Buland and Chapman (1983) in "The Computation of
Seismic Travel Times", BSSA, v. 73, pp. 1271-1302, for the IASPEI phase
set derived from the IASPEI travel-time model developed by Brian Kennett.
This phase set currently includes:  P, Pdiff, PKP, PKiKP, pP, pPdiff,
pPKP, pPKiKP, sP, sPdiff, sPKP, sPKiKP, PP, P'P', S, Sdiff, SKS, pS,
pSdiff, pSKS, sS, sSdiff, sSKS, SS, S'S', PS, PKS, SP, SKP, SKiKP, PcP,
PcS, ScP, ScS, PKKP, PKKS, SKKP, and SKKS.  The IASPEI model was
developed specifically as a replacement for the Jeffreys-Bullen model for
earthquake location work.  It incorporates a PEM core, a lower mantle 
developed by Ken Toy, and an upper mantle constructed by Brian Kennett.
The phase set was chosen by requiring that the phases be well observed in
some distance range and that they be useful either for earthquake
location or for studies of earth structure.

   This implementation of the travel-time algorithm includes all
refracted arrivals of each phase listed, but only the partial
reflections specifically noted in the phase list.  All total internal
reflections (except at the free surface) have been supressed as they are
almost always tertiary arrivals.  This policy does result in no PS and
SP arrivals in the distance range of about 25-50 degrees.  Phase naming
is derived directly from the model layer in which the phase turns and is
sometimes at odds with various seismological conventions.  In particular,
the lack of a low velocity zone in the upper mantle of the IASPEI model
results in Pn and Sn extending out to about 25 degrees.  Even without the
total reflections, the upper mantle discontinuities and triplications
will typically result in two to four P and S arrivals each in the
distance range of about 17-30 degrees.

   The tables are generated by a two step process which involves running
first program REMODL and then program SETBRN.  REMODL generates the
model by calling routines in EMIASP91.F.  In principle any model may be
used.  However, a range of IASPEI models has actually been tested.
REMODL examines the model and its implications, makes up a best guess at
how to sample slowness, and performs all of the raw integrals.  It writes
its results into the REMODL.HED and REMODL.TBL files.  REMODL1.LIS and
REMODL2.LIS show some of what goes on inside of REMODL and are useful
when REMODL is being converted to a different computer.  SETBRN takes the
results of REMODL from (REMODL.HED AND REMODL.TBL) and constructs the
specific branches desired by the user.  While some attempt has been
made to make SETBRN ``programmable'', care must be taken that phases
added are within the assumptions made by the interpolation routines in
LIBTAU.F.  SETBRN produces the tau-p tables IASP91.HED AND IASP91.TBL.
The access to these tables has been cleaned up so that they are quite
machine independent.  SETBRN also produces internal listing files
SETBRN1.LIS, SETBRN2.LIS, and SETBRN3.LIS.  REMODL and SETBRN (and the
routines they call) use the include file LIMITS.INC.  It is assumed that
the include file is in the directory in which compilation is being done.
These programs are linked with the library LIBTAU.A (which should be
constructed from the source in LIBTAU.F).  REMODL and SETBRN also require
machine dependent routines from either LIBVAX.A or LIBSUN.A (which should
be constructed from the source in LIBVAX.F or LIBSUN.F) depending on the
computer being used.  Note that REMODL and SETBRN are not actually needed
to simply invoke the tau-p tables once generated.  They are only used for
setting up the tables the first time.

   To invoke the travel times, a handful of routines also in the LIBTAU
library need to be called.  An example of how this is done is given in
the program TTIMES.  Note that a different include file, TTLIM.INC is
needed.  Playing with the print flags can give you a feeling for what
TTIMES does, but one of them generates a lot of output (into file
TTIM1.LIS).  The tau interpolation is usually only needed for debugging.
However, the range summary can be very useful as it shows the distance
range over which each branch of each phase will appear.  The BRNSET
routine can be used interactively (as in TTIMES) or hardwired for a
specific set of phases.  It allows the user to select only the phases
of immediate interest.  When running TTIMES, note that at each distance,
all possible arrivals from all branches are given in time order.  The
travel-time is given twice (in seconds and in minutes and seconds).  The
numbers at the end of each line are various derivatives (travel-time
with respect to distance, travel-time with respect to depth and the
second derivative of travel-time with respect to distance).

                                           Ray Buland

P.S. UNIX manual pages generated by Brian Kennett are provided in the file 
     TAU.MAN.

LOCAL CHANGES:

   A subroutine called tptt (code: tptt.f; binary tpttsub.o) is available
to return travel time information (time, dt/ddelta, dt/ddepth, ddelta/dp)
from these tables.  See the code for documentation on use.  (G. Helffrich
Carnegie/DTM 28 Aug. 1991)

   Include files limits.inc and libtau.inc were rationalized so that
   dimensioning dependencies were made explicit.  All declarations changed
   to use parameter values set in limits.inc and libtau.inc.
      G. Helffrich/UB 27 Apr. 1993

   libsun and libvax changed to add evget subroutine.
   ttimes changed to take module name from environment variable if asked.
      G. Helffrich/UB 27 Apr. 1993

   emiasp91.f changed to flip data statements, making modification of parts
   of model possible.
      G. Helffrich/UB 5 June 1994
   
   Discontinuity size in remodl.f changed so that these aren't declared where
   the mismatch is minor between velocities.  This causes trouble with the
   iasp91 model and has been returned to its original size.
      G. Helffrich/UB 5 June 1994
   
   Table writing rearranged so that table size can be checked by ttimes.
   This is to ensure that tables that are too large or even a different
   size may be read in correctly by the program.
      G. Helffrich/UB 13 August 1995

   Modified libtau.f so that PKPbc is also diffracted around the inner core.
      G. Helffrich/UB 3 Dec. 1996
   
   Added code to check for table overflows of various sorts in remodl and
   setbrn.  These mostly result in pause statements executed with cryptic
   comments.
      G. Helffrich/UB 20 Mar. 1998
   
   ***WARNING: This is not a backwards-compatible change.  If you make this
   change, you have to either rebuild all your .hed files, or keep an old
   version of ttimes around capable of reading the old table format. ***
   Modified .hed format so that the ttimes program and friends can determine
   whether the table it will read in is too big to fit.  This permits changes
   to the size of built-in tables without having to change previous versions
   of the tables that ttimes reads in.
      G. Helffrich/UB 29 Mar. 1998
   
   Checked for overflow of temporary storage in fitspl (libtau.f).  Will
   stop with an error message if number of branches exceeds bounds.
      G. Helffrich/UB 1 Aug. 1998

   remodl.f: Fixed bug in findrng which caused division by zero if any value
   in the y table was equal to y(i) in inverse iteration.  Basically caused by
   fact that xmax is real*4 and function arguments are real*8 - so you can get
   no change in xmax for a change in its x value.
      G. Helffrich/UB 6 Aug. 2003

   remodl.f: Added pSKP and sSKP to tabulated phases.
      G. Helffrich/UB 20 Aug. 2005

   Makefile:  Tweak to prevent non-fatal build error messages and to install
   with default model in ttimes.
      G. Helffrich/UB 11 Jan. 2006

   Makefile:  Tweak to fix builds on fast machines -- some models skipped.  Fix
   install-all-models and behavior of simple 'install' with no previous models
   built.
      G. Helffrich/UB 3 Dec. 2006

   tptt.f:  New routine tpttsv to return velocities at source.
      G. Helffrich/UB 13 Oct. 2007

   Makefile.in, configure.ac, utils/install-sh, utils/version, ttimes.f:  Make
   configure-driven. (version 2)
      G. Helffrich/UB 21 Apr. 2008

   Makefile.in, configure.ac, utils/config.guess, utils/config.sub: Version 3
      G. Helffrich/UB 3 Jun. 2008
   1) Improve Mac installation defaults to be more intelligent about choosing
      the man page locations.
   2) Add gtt91 man page (not very useful); edit ttimes man page to be
      consistent about name of program.
   3) Add uninstall option (suggested by Arthur Snoke).
   4) Add range in km option (sugg. by Art Snoke) and terse option.
   5) Add take-off option (sugg. by Art Snoke).

   limits.com, setbrn.f, ttimes.f, configure.ac/configure:  Version 4
      G. Helffrich/UB 7 Jun. 2008
   1) Add PcS, sScS, pScS, sPcP, pPcP phases -- increase limits.inc to
      permit.
   2) Include model name in even terse output (suggested by Arthur Snoke).
   3) Eliminate odd configure complaint (reported by Arthur Snoke).
   4) Correct conversion factors for slowness in km; fix output labels.

   Makefile.in:  Version 5
      G. Helffrich/UB 10 Jun. 2008
   1) Create all directories in $(MANDIR) path (reported by Arthur Snoke).

   Makefile.in:  Version 6
      G. Helffrich/UB 21 Jan. 2010
   1) ttimes.1, ttimes91.1 - fix typos, document behavior.
      G. Helffrich/UB 21 Jan. 2010
   2) ttimes.f, libtau.f, libvax.f, setbrn.f, remodl.f:  Eliminate dasign,
      assign, retrns use; use Fortran constructs instead.  Add die() to
      libvax.f
   3) configure.ac, configure:  Add configure options to eliminate depth
      phases and add extra core phases.  Automatic generation of limits.inc
   4) tptt.f:  Document use of subroutine interface to tables better and the
      tpmod and phgen routines.
