.clr file format

Introduction

The .clr or Continuous Layer Representation file format is an ASCII format to store velocity models that are continuously defined by radius or depth dependent functions and their parameters. Prominent examples for such models are PREM (Dziewonski & Anderson, 1981) and IASP92 (Kennett & Engdahl, 1991). The advantage of such model definition is that the model is uniquely defined at any depth and that there is no discussion about which kind of interpolation to use. A layering with first order discontinuities is still possible, since each polynomial has a well defined range of depth in which it is valid. The planet may consist of an arbitrary amount of such layers (what even allows a cubic spline representation of arbitrary velocity profiles).

The .clr format is a human readable ASCII format which is based on the Keyword Line concept used for some data in the .nd format. The .clr format is much more flexible than the .nd format and probably easier to read and write for humans. But as the .nd format, the .clr format is a line oriented format: Information is subdivided into blocks which are on separate lines.

Information is tagged by Keywords and Modifiers which define the type of information given in a line. This allows a very flexible file formatting.

The format definition is somewhat lengthy, but the resulting syntax and structure is quite simple and straight forward.

Units

Since an explicit declaration of physical units would imply that there is some unit conversion code in the file reader program, the physical units of quantities specified in a .clr file are not declared explicitly.

Instead, it is assumed that quantities are declared in the following units:

Units used
Quantity Unit
Depths, Radius km
Velocity km/s
Density g/cm3
Q-factors dimensionless
General File Structure
layers nicht notwendigerweise in reihenfolge der tiefe radius definition nicht notwendigerweise vor layer/disc definition - statt dessen umwandlung von radien in tiefen erst nach auslesen des kompletten files diskontinuitaeten-definitionen nicht notwendigerweise zwischen den durch die diskontinuitaeten getrennten layern prinzip der filestruktur: alles kann in beliebiger reihenfolge kommen! deswegen hat man ja die keywords! (nur bei layern muss man natuerlich blocks bilden) -->

The Keyword concept allows a very flexible file structuring: it is not necessary to give the separate pieces of information in a certain sequence. Layers need not be defined in the sequence given by depth (or radius). Discontinuities need not be defined between the layers they separate. The planets radius does not have to be defined first. Comments may be nearly everywhere. Enjoy!

The only important point is that layers are defined by a couple of lines which are grouped by start and end Modifiers. This is necessary to ake sure that velocities, densities etc. are connected in the right way.

It is important to understand that the .clr file format is not organized by format strings. Instead, a .clr file consist of lines, and lines consist of tokens, separated by whitespace.

General Line Syntax

A Line in a .clr file is either empty or consists of the following elements:

  1. Evaluated content:
    1. Keyword
    2. Modifier
    3. Parameter List
  2. non-evaluated content
    1. Comment

You may omit either the evaluated content or the non-evaluated content or both.

This means thayt you can have empty lines (useful for a visual structuring of files), lines that contain only comments, lines that contain only data, or lines that contain commented data.

All comments are stripped off before a line is evaluated.

The evaluated content is a series of whitespace-separated tokens (by whitespace, the space character [ASCII 32] and Tab stops [ASCII 9] are meant).

Keywords and Modifiers are preceeded by exclamation marks to distinguish them from parameters.

Numerical Parameters may be given in floating point format (e.g. 314.159) or fixed point format (e.g. 3.14159e+2).

String Parameters are not case sensitive, any string is transformed to lower case during file read.

Keywords

Each line of a .clr file consists of either a comment, or a keyword and its parameters.

A Keyword Line consist of several tokens (strings or numbers) that are separated by whitespace (the space character [ASCII 32] or Tab stops [ASCII 9]). The line begins with the Keyword itself, which may be followed by a Keyword Modifier and then a number of Keyword Parameters:

!Keyword !Modifier parameter parameter parameter

The Exclamation mark "!" is used to distinguish Keywords and Modifiers from parameters. The possible Modifiers and the allowed number of parameters depend on the Keyword.

A simple example is

!name IASP91

where "name" is the keyword and "IASP91" is a string parameter. A Modifier is not present. This example line defines the model name to be "IASP91".

A more advanced example is

!layer !depth 0 20

Where "layer" is the keyword, "depth" is a modifier and "0" and "20" are the parameters. This example defines a layer to reach from depth 0km to depth 20km.

An alternative definition of the same depth range is

!layer !radius 6351 6371

which, of course, implies that the planetary radius is defined as 6371km.

The following tables give a list of all Keywords, their Modifiers and the specified Parameters.

List of all Keywords:

  1. name
  2. year
  3. planet
  4. layer
  5. discon
  6. usertag
keyword: name
Modifier Parameter Type Explanation
- model name string Velocity models usually have names like "IASP91" or "PREM".
keyword: year
Modifier Parameter Type Explanation
- model publication year numeric The year in which the model was first published.
keyword: planet
Modifier Parameter Type Explanation
name planet name string The planet's name ("earth", "moon" etc.). This is an informational parameter which helps to avoid confusion, but is not evaluated.
radius planetary radius numeric The radius of the planet for which this model is constructed.
keyword: layer
Modifier Parameter Type Explanation
start name string Layer start mark. The description of a new layer begins here. The layer name parameter is optional and may be omitted.
depth 1. depth of layer top
2. depth of layer bottom
numeric Parameter polynomials of this layer are valid from top depth to bottom depth.
radius 1. radius of layer bottom
2. radius of layer top
numeric Parameter polynomials of this layer are valid from bottom radius to top radius.
end - - Layer end mark. The description of the current layer ends here.
vp 1. constant term of layer polynomial
2. 1st order coefficient of layer polynomial
3. 2nd order coefficient of layer polynomial
...
n. n-th order coefficient of layer polynomial
numeric P wave velocity polynomial. Physical properties of layers are defined by n-th degree polynomials. The degree of the polynomial is implied by the number of coefficients given.
vs 1. constant term of layer polynomial
2. 1st order coefficient of layer polynomial
3. 2nd order coefficient of layer polynomial
...
n. n-th order coefficient of layer polynomial
numeric S wave velocity polynomial. Physical properties of layers are defined by n-th degree polynomials. The degree of the polynomial is implied by the number of coefficients given.
rho 1. constant term of layer polynomial
2. 1st order coefficient of layer polynomial
3. 2nd order coefficient of layer polynomial
...
n. n-th order coefficient of layer polynomial
numeric Density polynomial. Physical properties of layers are defined by n-th degree polynomials. The degree of the polynomial is implied by the number of coefficients given.
qp 1. constant term of layer polynomial
2. 1st order coefficient of layer polynomial
3. 2nd order coefficient of layer polynomial
...
n. n-th order coefficient of layer polynomial
numeric P wave quality factor polynomial. Physical properties of layers are defined by n-th degree polynomials. The degree of the polynomial is implied by the number of coefficients given.
qp 1. constant term of layer polynomial
2. 1st order coefficient of layer polynomial
3. 2nd order coefficient of layer polynomial
...
n. n-th order coefficient of layer polynomial
numeric Q wave quality factor polynomial. Physical properties of layers are defined by n-th degree polynomials. The degree of the polynomial is implied by the number of coefficients given.
keyword: discon
Modifier Parameter Type Explanation
depth 1. discontinuity depth
2. discontinuity name
1. numeric
2. string
Depth and name of a discontinuity
radius 1. discontinuity radius
2. discontinuity name
1. numeric
2. string
Radius and name of a discontinuity
keyword: usertag
Modifier Parameter Type Explanation
- User Tag string An arbitrary string may be used as an additional information. Might be useful when generating files automatically.
Definition of Layers

A single layer is defined by a block of lines with layer-Keywords. Since a layer consists of up to six different physical parameters and a depth range, some means to group these informations into a layer. For this purpose, the start and end modifiers of the layer keyword have been introduced.

A full-featured layer definition then looks like this:

!layer !start LayerName
!layer !depth p1 p2
!layer !vp p1 p2 p3 ... pn
!layer !vs p1 p2 p3 ... pn
!layer !rho p1 p2 p3 ... pn
!layer !qp p1 p2 p3 ... pn
!layer !qs p1 p2 p3 ... pn
!layer !end

Where the pn are the coefficients of the respective layer polynomials. (Except for the !depth declaration, where p1 and p2 give the top and bottom depth of the layer.)

Instead by depths measured from the surface, the vertical extent of the layer may also be defined by two radius values, measured from the planet's center. The first value is the smaller one in both cases.

Different layers may use different vertical coordinates: it is possible to define one layer in terms of depth and another one in terms of radius.

If one of the parameters is not defined in the model (IASP91, for example, does not define densities and quality factors), simply omit the respective line. Undefined parameters will result in NaN output of the reding routine.

The definition of the IASP91 transition zone, for example, may look like this:

!layer !start Transition Zone
!layer !vp    29.38896 -21.40656
!layer !vs    17.70732 -13.50652
!layer !depth 410 660
!layer !end

NOTE that, although the layer is named "Transition Zone", this layer definition does not imply a definition of discontinuities at 410km and 660km depth! There will be discontinuities at these depths at which rays are refracted, but a programm will not be able to recognize these discontinuities as those delimiting the transition zone. This requires extra definitions of discontinuities.

If there are multiple lines in a layer definition block which define the same quantity, the last one of them will overwrite all previous ones.

Definition of Discontinuities

A named discontinuity is declared by the discon Keyword.

Assigning a name is useful in order to evaluate seismic phase names of in which these discontinuities are referred. In order to compute a PcP travel time, for example, you need to know where the core mantle boundary is.

A discontinuity declaration looks like this:

!discon !depth 2890 outer core

This line declares the core-mantle boundary to be at 2890km depth.

Instead of depth, it is also possible to use the radius:

!discon !radius 3481 outer core

defines the same core mantle boundary (if the radius is 6371km).

There are predefined names for standard discontinuities which should be used properly:

Discontinuity .clr format 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.

Discontinuity declarations may be grouped somewhere in the .clr file, or may be given between the declaration of the layers they separate - just as you like.

If there are multiple discontinuity declarations for the same position (irrespective of using depth or radius coordinates), the last one will override all previous ones.

Comments

eof.