Release Notes for Freeze 03.07.2007

Since the 02052004 version (more than two years ago now), many things have been changed and, hopefully, improved. Almost all routines of TTBOX have experienced minor or major modifications, up to complete rewriting. Most changes affect speed (faster now) and robustness (bug fixes and general smartness). I must admit that I lost track of all the changes but try to recollect them here.

The patch of 27.08.2004 is incorporated into this new version.

This document is divided into the following sections:

  1. Incredible New Features
  2. New/Modified Documentation
  3. New Routines
  4. Modified Routines
  5. Modified Data Structures
  6. Deprecated Routines
Incredible New Features
Arbitrary Surface Reflections
A new handling of multiple phases has been introduced. TTBOX can now handle arbitrary surface multiples of the form Xn, where X is any seismic phase name recognized by the program and n an arbitrary integer number. Just try, for example, mkrayfan('PKP2',iasp91,0); (this does not yet work for phases like P5KP: the entire phase is repeated, not only parts of it)
New Shooting
An entirely new shooting method has been implemented (see routine MKSHOOTRAY). It relies on a careful analysis of the velocity model to determine critical distances, e.g. beginnings and ends of triplications or shadow zones. The old shooting, based on a brute force approach, had difficulties to find all possible rays at distances corresponding to such critical distances, and the new method is also faster, especially for densely sampled velocity models.
Better Ray Plots
The plots of MKRAYFAN now consist of as few line segments as possible, which results in faster rendering and easier post-processing of plots. The "UserData" field of the line object's properties (accessible via set/get or the MatLab property editor) now contain phase name, epicentral distance, ray parameter and maximum depth of each ray, allowing to analyze the ploted ray fan. It is now also possible to define the ray color prior to plotting using an additional optional input parameter
.nd to .clr conversion
A limited conversion of models given in .nd files into .clr files is now possible, but only for models that consist of constant-velocity layers (MKND2CLR routine)
New/Modified Documentation
Origin of the Residuals
A new sub-section "Origin of the Residuals" is included into the validation section. The formerly unresolved reasons for the differences between TTBOX result and printed IASPEI 1991 seismological tables (Kennett, 1991) is explained here, as investigated by Knapmeyer (2005).
Good & Bad Depth Sampling
A sufficient depth sampling is the prerequisite of accurate ray geometry and travel time computations. But what is "sufficient"? This section demonstrates some effects of insufficient sampling tu guide the user.
Layout
The content frame of the online documentation now covers the entire width of the browser window (except the toc frame), instead of only 40em of it.
New error messages
Since I have introduced new routines, the section describing the TTBOX error messages also needed an update.
New Routines

A lot of new routines has been written. Most of them are part of the computational engine and will not be explained further in the list below. The interested reader is referred to the help lines contained in the respective m-files.

mkanalytictimes
mkanalytictimes computes travel times for PcP, PKIKP, PKiKP and other phases at 0° or 180° distance. The routine is intended mainly as part of the validation.
mk2ptinterp
Linear Interpolation between two points
mkderive
mkdepthbydist
This routine plots the ray turning point (or reflection) depth of a given phase and focal depth as function of epicentral distance. In such plots, the spatial extent of travel time triplications can be investigated easily, and they're useful to test the quality of the model's depth sampling.
mkdetectdiscon
mkemptypscan
Provides an empty PSCAN structure with all necessary fields.
mkemptymodel
Provides an empty MODEL structure with all necessary fields.
mkfalseposition
mkfindextremedists
mkfumblep
mkfzeronest
mkimprovemodel
This routine analyses the velocity model and adds a few new depth samples at critical depths (e.g. slightly above and below first order discontinuities), in order to improve both shooting and travel time accuracy.
mkisextreme
mklvzanalysis
mklvzsmp
mknanfreepscan
mknd2clr
This is for for the conversion from models in named discontinuity format into CLR format. Currently, it just reproduces the layers as given in ND representation exactly, i.e. under the assumption of all parameters being constant between the given depths.
mkpolarframe
This routine previously was a part of mkraydiagram. It plots the polar diagram used e.g. by mkrayfan to plot seismic rays and is now a highly versatile routine for drawing nice polar coordinate frames. The routine now produces fewer line objects than before in order to make a posteriori modifications easier.
mkpsampler
The new shooting uses this routine instead of pscan to investigate the Δ(p) (epicentral distance as function of ray parameter) function. mkpsampler produces an irregular sampling adapted to the shape of the function and thus needs fewer samples to determine the ray parameter and take off angle necessary to reach a given epicentral distance. As mkscanp, this routine returns a pscan structure.
mkscanp
This routine previously was a part of the now deprecated mkfindp routine, which was the main routine of the old shooting mechanism. It is not used by TTBOX routines any longer but can be useful e.g for producing highly precise plots of the Δ(p) function. The new data structure pscan has been introduced to collect the output of this routine.
mkshootray
This is the main routine of the new shooting mechanism. To find out what ray parameter and take off angle you need to reach a given epicentral distance with with a given seismic phase, you call mkshootray.
mkstriprepetitions
This is a part of the handling of multiples.
mkuniquesamples
Modified Routines

Almost all routines have been modified at all scales from minor bug fixes to complete rewriting, but I took special care to keep the calling sequences compatible to the previous version. So usually, you can ignore all these changes (but you may appreciate them as my effort to improve the product)

mkangle2rayp
bug fixed: if the source is at a discontinuity, different velocities must be used for upgoing and downgoing rays.
mkclr2model
Now uses mkemptymodel
mkgv0
The previous version was fully vectorized, but TTBOX did not use this, so I de-vectrorized the routine in order to speed it up.
mkinterpmodel
several bug fixes:
mkraydepth
This routine has been rewritten entirely, because the old version was slow, complicated and incorrect, especially with total reflections, at discontinuities and low velocity zones.
mkraydepthinv
Two exceptions in which NaN must be returned have been added.
mkrayfan
mkrayp2angle
This routine has been vectorized in both ray parameter and velocity: now one can submit lists of ray paremeters, and two velocities for upper/lower side of discontinuities can be given.
mkreadnd
The struct-to-double assignment bug, which generates warnings in MatLab R14 and later, has been repaired.
mksmarttakeoff
mksynopsis
mksynopsis now uses the new shooting method.
mktim4p
mktp
A bug in MKTP is fixed which caused the travel time for some phases to be inf, although there was no problem in ray geometry. The problem was the handling of a singularity in the argument of atanh().
mktpsum
Some invalid rays excluded from result.
mkttboxvalid
The routine now uses the new shooting method.
mkttime
The routine now uses the new shooting method. mkttime now catches the p=NaN output of mkshootray (and previously mkfindp) for non existing phases.
mkx4p
mkxpsum
The constrution of vertical coordinates of ray segments in MKXPSUM has been improved. An indexing error sometimes caused the z coordinate vector to be longer than the x coordinate vector. (Only in exotic models, I hope...). This is now fixed.
New/Modified Data Structures
model
The model structure as it's delivered by MKREADND has not changed, but the new routine MKIMPROVEMODEL adds some fields that are required by the new shooting method. This is done one the fly if necessary (but you can also provide model structs that already contain it) and you don't need to care for this. The new fields are described in the section on Model Data Structure.
Deprecated Routines

Some routines, mostly those of the old shooting method, are not needed any longer and their use is deprecated. If you wrote any program using one of the folloqing routines, you should revise them in order to use the appropriate new routines.

Most important is that you replace any call to MKFINDP by calls to MKSHOOTRAY. The calling sequence of the two routines is identical, it should be sufficient just to rename the call.

mkfindp
mkfindp is the main routine of the old shooting mechanism. It has been replaced by mkshootray and must not be used any more, because the new shooting does anything faster, better and more robust.
mkfindzeros
mkfindzeros is part of the old shooting mechanism. It is an implementation of an ad hoc 1D optimization method which should not be used anyway...

eof.