shortcut to the format reference
The .nd file format is based on the "named discontinuity" format used by the TauP Toolkit (Crotwell et al., 1999). It is a human readable ASCII format which defines velocity, density and Q factor at discrete depths, with linear interpolation implied.
For TTBOX, the format has been extended a little: it is now possible to store the planetary radius, the model name, and the year in which the model was published.
The Routines MKREADND and MKWRITEND read and write .nd-files from disk.
The Format consists of the following elementary building blocks:
Here comes a simple example of a .nd file, which demonstrates all features:
/* Simple sample Model */ !year 2002 !radius 6375 // The Radius! 0.0 5.0 3.0 2.7 20 5.0 3.0 2.7 100 20 6.5 3.7 2.9 200 300 33 6.5 3.7 2.9 mantle # this is the Moho 33 7.8 4.4 3.3 410 8.9 4.7 3.5 # here is an unnamed discontinuity! 410 9.1 4.9 3.7 // some parms in here # and complicated comment 670 10.2 5.5 4.0 670 10.7 5.9 4.4 # some complicated comment // after the parms 2891 13.7 7.2 5.6 outer-core // here begins the outer core 2891 8.0 0.0 9.9 5149.5 10.3 0.0 12.2 inner-core 5149.5 11 3.5 12.7 6371 11.3 3.7 13
As you see, there are different (but equal) ways to define a comment. Comments may start right in the middle of a line. Undefined Parameters may be omitted.
The following sections describe the building blocks of .nd-files in detail:
Data Lines are, of course, the most important building block in .nd files. The use of the MatLab functions strtok and str2num allows a very flexible formatting, which makes file reading and editing much easier for humans.
The following example gives some layers of a PREM (Dziewonski & Anderson, 1981) like model. In PREM, all six of the quantities representable in .nd files are given.
0.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 24.400 6.80000 3.90000 2.90000 1345.91217 600.00000
(Note that the formatting of this example is just chosen to enhance the readability. It is not necessary to have all decimal points in the same positions or use only one space as separator!)
Many models, like IASP91 (Kennet & Engdahl, 1991) do not specify some quantities. If the missing quantities are at the end of the line, you may simply omit them: IASP91 does not specify density and Q factors. The Data Lines in an .nd file may look like this:
35.000 8.04000 4.47000 77.500 8.04500 4.48500 120.000 8.05000 4.50000 165.000 8.17500 4.50900 210.000 8.30000 4.51800 210.000 8.30000 4.52200 260.000 8.48250 4.60900 310.000 8.66500 4.69600
This will be interpreted as depth in the first column, vp in the second column and vs in the third column.
If, for example, the S wave velocity vp is undefined but a density given, the Data Lines have to look like this:
0.000 5.80000 -1 2.60000 15.000 5.80000 -1 2.60000 15.000 5.80000 -1 2.60000 24.400 6.80000 -1 2.90000
This will be interpreted as depth in the first column, vp in the second column, vs undefined and density in the fourth column. The "-1" entries define the respective quantity as unknown.
Omitting entries in the middle of the line as in
0.000 5.80000 2.60000 15.000 5.80000 2.60000 15.000 5.80000 2.60000 24.400 6.80000 2.90000
Would again be interpreted as depth in the first column, vp in the second column and vs in the third column. Since an arbitrary number of white space is allowed as separator between entries, the longer gap between the second and third column wouldn't be interpreted as missing value!
First order Discontinuities may be named for later association with specific effects. This property gives the format its name.
Discontinuity | TTBOX name | Explanation |
---|---|---|
Conrad D. | 'conrad' | Boundary between upper and lower crust, not always present |
Mohorovicic D. | 'moho' or 'mantle' |
Boundary between crust and mantle |
Olivine-&alpha to β-Spinel phase transition, "410" | 'olivine alpha beta' or 'transition zone' |
Beginning of the mantle transition zone |
β-Spinel to &gamma-Spinel phase transition, "520" | 'olivine beta gamma' | |
Spinel-Perowskite Transition, "660" | 'olivine gamma perovskite' or 'lower mantle' |
Boundary between upper and lower mantle |
Core-mantle-Boundary, "CMB" | 'outer core' or 'outer-core' |
Boundary between Mantle and Core |
Inner core Boundary, "ICB" | 'inner core' or 'inner-core' |
Boundary between liquid outer and solid inner core. |
The following example shows the definition of a Moho within a PREM-like model:
0.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 24.400 6.80000 3.90000 2.90000 1345.91217 600.00000 mantle 24.4 8.11062 4.49100 3.38075 1441.7098 600 40.000 8.10097 4.48526 3.37905 1441.96734 600.00000 60.000 8.08861 4.47789 3.37688 1442.29855 600.00000
Values of physical parameters are defined above and below the discontinuity at the same depth (24.4km in the above example). The insertion of the predefined name causes MKREADND to store the depth of the Moho in the .moho-field of the model-structure.
PREM defines a Low velocity zone, which does not exist in all earth models. The beginning of this zone may be indicated by a non-predefined discontinuity name:
80.000 8.07625 4.47052 3.37471 1442.63089 600.00000 115.000 8.05461 4.45762 3.37090 195.43033 80.00000 150.000 8.03298 4.44472 3.36710 195.51154 80.00000 185.000 8.01134 4.43182 3.36329 195.59324 80.00000 220.000 7.98971 4.41892 3.35949 195.67543 80.00000 LVZ 220 8.55895 4.6439 3.43578 362.6702 143 265.000 8.64552 4.67540 3.46265 365.06069 143.00000
This Name and the associated depth (220 km) are stored in the .dz- and .dname-fields of the model-structure.
Discontinuities may also remain unnamed as in the following example from IASP91:
77.500 8.04500 4.48500 -1.00000 -1.00000 -1.00000 120.000 8.05000 4.50000 -1.00000 -1.00000 -1.00000 165.000 8.17500 4.50900 -1.00000 -1.00000 -1.00000 210.000 8.30000 4.51800 -1.00000 -1.00000 -1.00000 210.000 8.30000 4.52200 -1.00000 -1.00000 -1.00000 260.000 8.48250 4.60900 -1.00000 -1.00000 -1.00000 310.000 8.66500 4.69600 -1.00000 -1.00000 -1.00000
The discontinuity at 210km depth will be ignored in the sense that no special treatment of it is possible. Its depth is not stored within the .dz-field of the model-structure.
Keyword Lines are used to store data other than velocity, density and Q-factors.
Keyword | Type | Explanation |
---|---|---|
!radius' | numeric | Planetary Radius in km. If not defined within the file, the largst depth value used in a Data Line will be used. |
!year | numeric | Year of Publication of model |
!name | string | Name of model, without any whitespace |
In an .nd-file for the IASP91 model you might define
!name IASP91 !radius 6371 !year 1991
For the Moon Model by Nakamura (1983), the respective lines would be
!radius 1738 !year 1983 !name Nakamura83
Comments are useful to give additional information to human readers, but are not evaluated during file reading.
The following example contains several types of legal comments:
// This is a discrete version of PREM // values at lower side of moho are computed for 24.40001km !name PREM // Preliminary Reference Earth Model 0.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 24.400 6.80000 3.90000 2.90000 1345.91217 600.00000 Moho # here begins the mantle 24.4 8.11062 4.49100 3.38075 /* I have deleted Q factors here 40.000 8.10097 4.48526 3.37905 60.000 8.08861 4.47789 3.37688
The first two lines will be ignored completely. The model name will be identified as "PREM", the name of the discontinuity at 24.4km as "Moho".
The following example demonstrates several types of (currently) illegal commenting:
/* This is a discrete version of PREM values at lower side of moho are computed for 24.40001km */ !name PREM / Preliminary Reference Earth Model 0.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 15.000 5.80000 3.20000 2.60000 1451.91656 600.00000 24.400 6.80000 3.90000 2.90000 1345.91217 600.00000 Moho 24.4 8.11062 4.49100 3.38075 /* here follows Q */ 1441.7098 600