.nd file format

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:

  1. data lines to specify velocity, density and Q factor at depth
  2. discontinuity name lines to specify the depth of prominent 1st order discontinuities
  3. Unnamed Discontinuities
  4. comments to give arbitrary additional information (which is not evaluated during file reading)
  5. keyword lines to specify planet radius, model name, and year of model publication

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

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!

Discontinuity Name Lines

First order Discontinuities may be named for later association with specific effects. This property gives the format its name.

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.

Unnamed Discontinuities

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

Keyword Lines are used to store data other than velocity, density and Q-factors.

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

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

eof.