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:
- Incredible New Features
- New/Modified Documentation
- New Routines
- Modified Routines
- Modified Data Structures
- Deprecated Routines
- 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)
- 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.
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
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:
- mkinterpmodel now uses "pchip" interpolation instead of "spline" interpolation, since the latter produced artifact low velocity zones at corners of the original model. "pchip" avoids that.
- The handling of discontinuities has been improved.
- MatLab 7 required an update, since interp1 is now more sensitive for NaN elements. The new
version of interp1 crashed mkinterpmodel when interpolating for a single depth
value. mkinterpmodel has been modified to avoid this.
- I had forgotten to copy the year field into the interpolated model
structure. Now it's included.
- 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
-
- MKRAYFAN now generates much less graphic objects, which means that ray fan plots render much faster and can be manipulated easily using the property editor. While doing this, I also repaired the problem of the sometimes missing ray ends and "color overshooting" at the CMB. So ray fan plots are better, smaller, faster now. Additionally, the plot objects contain more information: the user data field of each ray's line object now contains the takeoff angle, the deepest depth reached, and the epicentral distance at which the ray arrives.
- MKRAYFAN does not adjust the figure window size any longer - I found that too confusing.
- 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
-
- The routine has been rewritten entirely to fix all kinds of bugs and imprecisions. It can now also handle depth phases and multiple surface reflections.
- MKSMARTTAKEOFF now returns empty if the quake focus is at a depth where vs==0. This is needed when grid search location programs accidentally generate test foci in the core, for example.
- mksynopsis
- mksynopsis now uses the new shooting method.
- mktim4p
-
- many minor bugs have been fixed.
- The handling of PS and SP in MKTIM4P was severely erroneous and has been repaired
- surface reflections (multiples) of arbitrary degree
- generation of ScS in S case suppressed
- special handling for takeoff angles 90 in P, PP, PPP, S, SS SSS
- takoff==NaN caught, no PS or SP construction if second leg returns NaN distance
- depth phase reflection angle bug repaired
- removed P vertext bullshit from ScS, ray parameter too large, exception removed from ScS, because unnecessary
- 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
-
- Many minor bugs have been fixed.
- SP nonsense repaired
- check for complex takeoff
- SKS SEGX/SEGZ dioscrepancy repaired
- Handling of surface reflections of arbitrary degree (multiples)
- generation of ScS in S code supressed
- takeoff==90 requires special handling in P, PP, PPP as well
as in S, SS, SSS,
- takeoff==NaN caught, no SP or PS construction if second leg is NaN.
- depth phase reflection angle bug repaired
- P vertex bullshit in ScS removed, ray parameter too large
exception removed from ScS, because unnecessary,
- A new exception is caught: p==inf may occur when tracing S waves through liquid media, which is nonsense. MKX4P now returns a NaN distance in that case to signal a problem. (This problem occurred when using TTBOX in Genetic Algorithm optimizations - the GA can produce rather weird velocity models...)
- 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.
- 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.
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.