Overview

Definitions

Generic Control Statements

Vel2Grid Program

Grid2Time Program

Time2EQ Program

NLLoc Program

[NonLinLoc Home]
Overview
The various NonLinLoc programs all use the same control file syntax and share some "generic" control statements. The control statements for all the NonLinLoc programs for a project (a study with common "generic" control statements) may be combined into one file without conflicts.
The basic control file statement syntax consists of a control keyword followed by one or more parameters on a single line (except when a newline is explicitely required).
KEYWORD parameter1 parameter2 ...
The keyword must begin in the first column and is always in upper case. Keywords and parameters must be separated by one or more spaces or tabs. A required newline in a parameter list is indicated by [newline]
.
Blank lines and lines with #
in the first column are ignored. Use #
in the first column for comments and to "comment out" a statement.
Definitions
Statement Priority
required  must be present in control file to run the coressponding program
optional  optional in control file
repeatable  may be present multiple times in control file
ignored  may be present but is not used by program under certain conditions
Datatypes
integer decimal integer ( i.e.
0, 5, 285
)
float  decimal floating point number (i.e.
1.0, 3.68, 4.5, 5.4e6
)
chars  sequence of characters without spaces (i.e.
NO_SAVE, abcdef, /data/bigevent.dat
)
string  sequence of characters which is read until the end of line, spaces are allowed (i.e.
The biggest earthquake sequence in history
)
choice  selection from a fixed list of items (i.e.
SAVE NO_SAVE
)
Miscellaneous
default:  indicates default values for parameters when an optional control statement is not present in the control file
min: max:  indicates minimum and maximum allowed values for parameters
VERY_LARGE_DOUBLE  a large floating point value (typically 1.0e+30)
Generic Control Statements
The generic control file statements may be used by one or more of the programs in the
NonLinLoc package. The statements
TRANS
and
MAPLINE
and their parameters must be the same for all programs runs for a given location project.
INCLUDE

CONTROL

TRANS

MAPLINE


MAPGRID

[Top]  [NonLinLoc Home]
INCLUDE  Include
optional, repeatable
Syntax 1: INCLUDE
includeFile
Inserts text from another file at current positon in control file.
includeFile
(string) path and name of file to include
Notes:
1. This statement is implemented only for NonLinLoc programs Vel2Grid, Grid2Time, Time2EQ and NLLoc.
2.
The included text must contain only valid NonLinLoc control statements, blank lines or comment lines, but may not have another
INCLUDE
statement.
CONTROL  Control
required, nonrepeatable
Syntax 1: CONTROL
messageFlag randomNumberSeed
Sets various general program control parameters.
messageFlag
(integer, min:1
, default:1
)
sets the verbosity level for messages printed to the terminal (
1
= completely silent,
0
= error messages only,
1
=
0
+ higherlevel warning and progress messages,
2
and higher
=
1
+ lowerlevel warning and progress messages + information messages, ...)
randomNumberSeed
(integer) integer seed value for generating random number sequences (used by program NLLoc to generate Metropolis samples and by program Time2EQ to generate noisy time picks)
TRANS  Geographic Transformation
required, nonrepeatable
Syntax 1: TRANS
GLOBAL
Syntax 2: TRANS
SIMPLE latOrig longOrig rotAngle
Syntax 3: TRANS
NONE
Syntax 4: TRANS
SDC latOrig longOrig rotAngle
Syntax 5: TRANS
LAMBERT refEllipsoid latOrig longOrig firstStdParal secondStdParal rotAngle
Sets geographic to working coordinates transformation parameters.
The GLOBAL
option SIMPLE
, SDC
and
LAMBERT
options make transformations of geographic coordinates into a Cartesian/rectangular system. The NONE
transformation performs no geographic conversion.
latOrig
(float, min:90.0
, max:90.0
) latitude in decimal degrees of the rectangular coordinates origin
longOrig
(float, min:180.0
, max:180.0
) longitude in decimal degrees of the rectangular coordinates origin
rotAngle
(float, min:360.0
, max:360.0
) rotation angle of geographic north in degrees clockwise relative to the rectangular coordinates system Yaxis
refEllipsoid
(choice: WGS84 GRS80 WGS72 Australian Krasovsky International Hayford1909 Clarke1880 Clarke1866 Airy Bessel Hayford1830 Sphere
)
reference ellipsoid name
latOrig
(float, min:90.0
, max:90.0
) latitude in decimal degrees of the rectangular coordinates origin
longOrig
(float, min:180.0
, max:180.0
) longitude in decimal degrees of the rectangular coordinates origin
firstStdParal secondStdParal
(float, min:90.0
, max:90.0
) first and second standard parallels (meridians) in decimal degrees
rotAngle
(float, min:360.0
, max:360.0
) rotation angle of geographic north in degrees clockwise relative to the rectangular coordinates system Yaxis
Notes:
1.
rotAngle
=
0
gives North along the positive Yaxis,
rotAngle
=
30
gives North along the axis 30 deg counterclockwise from the positive Yaxis of the rotated, rectangular system.
2.
The
GLOBAL
mode
3.
The SIMPLE
transformation only corrects longitudinal distances as a function of latitude
Algorithm:
x = (long  longOrig) * 111.111 * cos(lat_radians);
y = (lat  latOrig) * 111.111;
lat = latOrig + y / 111.111;
long = longOrig + x / (111.111 * cos(lat_radians));
4.
The NONE
transformation performs no geographic conversion, The input, cartesian/rectangular XYZ coordinates are used throughout
5.
The SDC
transformation is a "Short Distance Conversion" projection indended for use with very small study regions. For algorithm details see MAP_TRANS_SDC
in GridLib.c
6.
The LAMBERT
transformation is adapted from the source code of the
GMT plotting package
MAPLINE  Geographic Maplines
optional, repeatable
Syntax 1: MAPLINE
formatType name red green blue lineStyle
Specifies a file and drawing parameters for geographic line data.
formatType
(choice: GMT_LATLON GMT_LONLAT XY_LONLAT GMT_LONLATDEPTH GMT_LONLATELEV_M GMT_GRD
)
line file format or GMT grd file format
name
(string) full path and file name
red green blue
(float, min:0.0
, max:1.0
) red, green and blue intensities (0.01.0) (not implemented)
lineStyle
(choice: SOLID DASHED DOTTED DASHDOT
)
line style (not implemented)
Notes:
1.
All formats except GMT_GRD
specify 2D or 3D line files.
Use GMT_GRD
to specify GMT grd files, these will be plotted as a
background image with a greengreyscale by default. If a GMT cpt file exists with the same path and name as the
GMT grd file, but ending with ".cpt", it will be used to determine the color scale.
2.
A GMT grid (GMT_GRD
) cannot be used with a rotated coordinate system.
MAPTRANS  Geographic Transformation for Grid2GMT plot output
optional, nonrepeatable
Syntax 1:
Sets geographic to working coordinates transformation parameters for Grid2GMT plotting output. See TRANS
above for syntax (replacing TRANS
by MAPTRANS
).
Notes:
1.
MAPTRANS
specifies the transformation for Grid2GMT output to GMT plotting.
2.
MAPTRANS
superseeds any other TRANS
statement in the control file for Grid2GMT output.
MAPGRID  Grid Description for Grid2GMT plot output
optional, nonrepeatable
Syntax 1: MAPGRID
xNum yNum zNum xOrig yOrig zOrig dx dy dz gridType
Specifies the size and type of the 3D GMT plotting grid.
xNum yNum zNum
(integer, min:2
) number of grid nodes in the x, y and z directions
xOrig yOrig zOrig
(float) x, y and z location of the grid origin in km relative to the geographic origin.
dx dy dz
(float) grid node spacing in kilometers along the x, y and z axes
gridType
(choice: XXX
)
grid type (ignored).
Notes:
1. The 3D grid dimensions are in kilometers with Z positive down (lefthanded coordinate system).
2.
The grid is
dx*(xNum1)
km long in the x direction, and similarly for y and z.
3.
MAPGRID
specifies the plot region for GRid2GMT output to GMT plotting.
MAPGRID
superseeds any other xxxGRID
statements in the control file.
Vel2Grid Program
VGOUT

VGTYPE

VGGRID

LAYER

2DTO3DTRANS

VERTEX

EDGE

POLYGON2

[Top]  [NonLinLoc Home]
VGOUT  Output File Root Name
required, nonrepeatable
Syntax 1: VGOUT
fileRoot
Specifies the directory path and file
root
name (no extension) for the output velocity grid.
fileRoot
(string)
full or relative path and file
root
name (no extension) for output
Notes:
1.
The 3D velocity grid ouput files have names of the form:
fileRoot.waveType.mod
.
FileExtension
.buf
or
.hdr
.
VGTYPE  Wave Type
required, repeatable
Syntax 1: VGTYPE
waveType
Specifies the physical wave type for a velocity grid.
waveType
(choice: P S
)
wave type
VGGRID  Grid Description
required, nonrepeatable
Syntax 1: VGGRID
xNum yNum zNum xOrig yOrig zOrig dx dy dz gridType
Specifies the size and type of the 3D velocity grid.
xNum yNum zNum
(integer, min:2
) number of grid nodes in the x, y and z directions
xOrig yOrig zOrig
(float) x, y and z location of the grid origin in km relative to the geographic origin.
dx dy dz
(float) grid node spacing in kilometers along the x, y and z axes
gridType
(choice: VELOCITY VELOCITY_METERS SLOWNESS VEL2 SLOW2 SLOW_2_METERS SLOW_LEN
)
physical quantity to store on grid (
VELOCITY
= km/s,
VELOCITY_METERS
= m/s,
SLOWNESS
= s/km,
VEL2
= vel**2,
SLOW2
= (s/km)**2,
SLOW_2_METERS
= slow**2 ((s/m)**2),
SLOW_LEN
= slow*dx (sec)).
Notes:
1. The 3D grid dimensions are in kilometers with Z positive down (lefthanded coordinate system).
2.
The grid is
dx*(xNum1)
km long in the x direction, and similarly for y and z.
LAYER  Velocity Model  Layer
optional, repeatable
Syntax 1: LAYER
depth VpTop VpGrad VsTop VsGrad rhoTop rhoGrad
Specifies a constant or gradient velocity layer.
depth
(float) depth to top of layer (use negative values for layers above z=0)
VpTop VsTop rhoTop
(float) P velocity, and S velocity in km/s and density in kg/m**3 at the top of the layer.
VpGrad VsGrad rhoGrad
(float) Linear P velocity and S velocity gradients in km/s/km and density gradient in kg/m**3/km increasing directly downwards from the top of the layer.
Notes:
1. Multiple layers must be specified in order of increasing depth of top of layer.
2. The layer with the deepest top extends implicitly to infinite depth.
2DTO3DTRANS  Velocity Model  2D model to 3D model transformation
optional, nonrepeatable
Syntax 1: 2DTO3DTRANS
xOrig yOrig rotation
xOrig yOrig
(float) x and y coordinates in kilometers of the center of rotation in the 3D model.
rotation
(float, min:360.0
, max:360.0
) rotation angle in degreees COUNTERCLOCKWISE.
Notes:
1.
The 2D to 3D transformation is applied after the general geographic transformation specified by the Generic control statement
TRANS
.
2.
With
rotation
=0 the 2D model section will be parallel to the
x
direction in the 3D model, and the 2D model will be extended along the
y
direction in the 3D model.
VERTEX  Velocity Model  Vertex
optional, repeatable
Syntax 1: VERTEX
id_num zloc xloc yloc
Specifies a vertex in 2D or 3D space.
id_num
(integer) vertex identification number (must be unique)
zloc xloc yloc
(float)
z (positive DOWN), x and y location in kilometers of vertex (
yloc
ignored for 2D models)
Notes:
1. A single vertex may be used in the definitions of multiple edges (see EDGE).
EDGE  Velocity Model  Edge
optional, repeatable
Syntax 1: EDGE
id_num vertex1 vertex2
id_num
(integer) edge identification number (must be unique)
POLYGON2  Velocity Model  2D polygon
optional, repeatable
Syntax 1: POLYGON2
id_num n_edges depth Vp_top Vp_grad Vs_top Vs_grad p_top p_grad
[NEW_LINE]
edge1, edge2, ...
id_num
(integer) polygon identification number (must be unique)
n_edges
(integer, min:0
) the number of edges defining this polygon
depth
(float) reference depth for velocity and density (use negative values for depths above z=0)
VpTop VsTop rhoTop
(float)
P velocity, and S velocity in km/s and density in kg/m**3 at the reference depth (
depth
).
VpGrad VsGrad rhoGrad
(float)
Linear P velocity and S velocity gradients in km/s/km and density gradient in kg/m**3/km increasing directly downwards from the reference depth (
depth
).
edge1, edge2, ...
(integer) new line containing list of edge indexes defining this polygon
Notes:
1. A 2D polygon may share edges with other 2D polygons.
2.
The reference depth (
depth
) may be above, within, or below the polygon.
Grid2Time Program
GTFILES

GTMODE

GTSRCE

GT_PLFD

[Top]  [NonLinLoc Home]
GTFILES  Input and Output File Root Name
required, nonrepeatable
Syntax 1: GTFILES
ttimeFileRoot outputFileRoot waveType iSwapBytesOnInput
Specifies the directory path and file
root
name (no extension), and the wave type identifier for the input velocity grid and output time grids.
ttimeFileRoot
(string)
full or relative path and file
root
name (no extension) for input velocity grid (generated by program Vel2Grid)
outputFileRoot
(string)
full or relative path and file
root
name (no extension) for output traveltime and takeoff angle grids
waveType
(choice: P S
)
wave type
iSwapBytesOnInput
(integer, min:0
, max:1
, default:0
)
flag to indicate if hi and low bytes of input velocity grid file should be swapped
Notes:
1.
The
ttimeFileRoot
and
outputFileRoot
are appended with
.
waveType
2.
The 3D time grid ouput files have names of the form:
outputFileRoot.waveType
.
label
.
gridType
.
FileExtension
time
or
angle
,
FileExtension
is
.buf
or
.hdr
.
GTMODE  Program Modes
required, nonrepeatable
Syntax 1: GTMODE
gridMode angleMode
Specifies several program run modes.
gridMode
(choice: GRID3D GRID2D
)
grid type (
GRID3D
for a 3D, Nx*Ny*Nz grid or
GRID2D
for a 2D, 2*Ny*Nz grid)
angleMode
(choice: ANGLES_YES ANGLES_NO
)
sets if takeoff angles are calculated and an angles grid is output (
ANGLES_YES
for angles calulcation or
ANGLES_NO
for no angles calculation)
GTSRCE  Source Description
required, repeatable
Syntax 1: GTSRCE
label XYZ xSrce ySrce zSrce elev
Syntax 2: GTSRCE
label LATLON latSrce longSrce zSrce elev
Syntax 3: GTSRCE
label LATLONDM latDegSrce latMinSrce latDir longDegSrce longMinSrce longDir zSrce elev
Syntax 4: GTSRCE
label LATLONDS latDegSrce latMinSrce latSecSrce latDir longDegSrce longMinSrce longSecSrce longDir zSrce elev
Specifies a source location. One time grid and one angles grid (if requested) will be generated for each source. Four formats are supported:
XYZ
(rectangular grid coordinates),
LATLON
(decimal degrees for latitude/longitude),
LATLONDM
(degrees + decimal minutes for latitude/longitude) and
LATLONDS
(degrees + minutes + decimal seconds for latitude/longitude).
label
(string)
source label (
i.e.
a station code:
ABC
)
xSrce ySrce
(float) x and y grid positions relative to geographic origin in kilometers for source
zSrce
(float) z grid position (depth, positive DOWN) in kilometers for source
elev
(float) elevation above z grid position (positive UP) in kilometers for source
latSrce
(float, min:90.0
, max:90.0
) latitude in decimal degrees for source (pos = North)
longSrce
(float, min:180.0
, max:180.0
) longitude in decimal degrees for source (pos = East)
latDegSrce latMinSrce latSecSrce
(float) latitude degrees, minutes and seconds for source
longDegSrce longMinSrce longSecSrce
(float) longitude degrees, minutes and seconds for source
latDir
(choice: N S
)
geographic direction
longDir
(choice: W E
)
geographic direction
GT_PLFD  Podvin and Lecomte Finite Difference
required, nonrepeatable, for Podvin and Lecomte finite difference, must not be present otherwise
Syntax 1: GT_PLFD
hs_eps_init message_flag
Selects Podvin and Lecomte finite difference method and specifies method parameters.
hs_eps_init
(float, min:0.0
) fraction (typically 1.0E3) defining the tolerated model inhomogeneity for exact initialization. A tolerance larger than 0.01 will potentially create errors larger than those involved by the F.D. scheme without any exact initialization.
message_flag
(integer, min:0
, max:2
) Message flag (0:silent, 1:few messages, 2:verbose) A negative value inhibits "clever" initialization.
Notes:
1.
See Podvin and Lecomte finite difference source code and
Podvin and Lecomte, 1991
for more information.
Time2EQ Program
EQFILES

EQEVENT

EQSTA

EQSRCE

EQMECH

EQMODE

EQQUAL2ERR

EQVPVS

[Top]  [NonLinLoc Home]
EQFILES  Input and Output File Root Name
required, nonrepeatable
Syntax 1: EQFILES
ttimeFileRoot outputFileName
Specifies the directory path and file
root
name (no extension) for the input time grids, and the path and filename for the output phase/observation file.
ttimeFileRoot
(string)
full or relative path and file
root
name (no extension) for input time grids (generated by program Grid2Time)
outputFileName
(string) full or relative path and name for output phase/observation file
Notes:
1.
The
ttimeFileRoot
should not include the standardized phase code (
i.e.
P
or
S
).
EQEVENT  Hypocenter parameters
optional, repeatable
Syntax 1: EQEVENT
label xEvent yEvent zEvent originSeconds
label
(string) event identification label
xEvent yEvent zEvent
(float) x, y and z grid coordinates of hypocenter
originSeconds
(float) origin time in seconds
Notes:
1.
The the origin time
originSeconds
is added to the traveltime read from the time grid to get the synthetic phase time.
EQSTA  Station List
required, repeatable
Syntax 1: EQSTA
label phase errorType error errorReportType errorReport probActive
Specifies a station, phase and timing error to use to generate a synthetic phase reading.
label
(string)
station label (
i.e.
a station code:
ABC
)
phase
(string)
phase type (
i.e.
P
or
S
)
errorType
(choice: GAU BOX FIX NONE
)
calculated random timing error type (
GAU
for normal deviate with zero mean and variance =
error
, or
BOX
for boxcar deviate with zero mean and width = 2 *
error
, or
FIX
for time error/static =
error
, or
NONE
0.0
)
error
(float) error magnitude in seconds
errorReportType
(choice: GAU
)
timing error type to write to output phase/observation file
Err
field (The current version of NLLoc recognizes only
GAU
)
errorReport
(float)
error magnitude in seconds to write to output phase/observation file
ErrMag
field.
probActive
(float, default:1.0
) Probability (01) that a time for this station/phase should be created.
Notes:
1.
The
label
and
phase
when concatenated to the
ttimeFileRoot
(i.e.
ttimeFileRoot.label.phase
) should correspond to the path and root name of an existing, traveltime grid file.
2.
The error is calculated stochastically and added to the traveltime. Use
error
= 0.0
to obtain exact synthetic traveltimes.
EQSRCE  Source Description
optional, repeatable
Syntax 1: EQSRCE
label XYZ xSrce ySrce zSrce elev
Syntax 2: EQSRCE
label LATLON latSrce longSrce zSrce elev
Syntax 3: EQSRCE
label LATLONDM latDegSrce latMinSrce latDir longDegSrce longMinSrce longDir zSrce elev
Syntax 4: EQSRCE
label LATLONDS latDegSrce latMinSrce latSecSrce latDir longDegSrce longMinSrce longSecSrce longDir zSrce elev
Specifies a source location. Four formats are supported:
XYZ
(rectangular grid coordinates),
LATLON
(decimal degrees for latitude/longitude),
LATLONDM
(degrees + decimal minutes for latitude/longitude) and
LATLONDS
(degrees + minutes + decimal seconds for latitude/longitude).
label
(string)
source label (
i.e.
a station code:
ABC
)
xSrce ySrce
(float) x and y grid positions relative to geographic origin in kilometers for source
zSrce
(float) z grid position (depth, positive DOWN) in kilometers for source
elev
(float) elevation above z grid position (positive UP) in kilometers for source
latSrce
(float) latitude in decimal degrees for source (pos = North)
longSrce
(float) longitude in decimal degrees for source (pos = East)
latDegSrce latMinSrce latSecSrce
(float) latitude degrees, minutes and seconds for source
longDegSrce longMinSrce longSecSrce
(float) longitude degrees, minutes and seconds for source
latDir
(choice: N S
)
geographic direction
longDir
(choice: W E
)
geographic direction
EQMECH  Event mechanism description
optional, nonrepeatable
Syntax 1: EQMECH
mechType strike dip rake
Specifies the mechanism parameters for synthetic first motion calculations.
mechType
(choice: DOUBLE ISO NONE
, default:NONE
)
source mechanism type (
DOUBLE
for double couple, or
ISO
for isotropic/explosion, or
NONE
for no first motion calculation)
strike
(float, min:0.0
, max:360.0
)
strike of fault plane in degrees (0,360) clockwise from North in the Geographic reference frame (any
rotAngle
specified in the generic control statement
GTSRCE
will be added to
strike
).
dip
(float, min:0.0
, max:90.0
) dip of the fault plane in degrees (0,90) down from the horizontal.
rake
(float, min:180.0
, max:180.0
) angle in degrees (180,180) on the fault plane between the strike direction and the slip direction.
Notes:
1.
The the origin time
originSeconds
is added to the traveltime read from the time grid to get the synthetic phase time.
EQMODE  Select Mode: sta>source or source>station
optional, nonrepeatable
Syntax 1: EQMODE
mode
Selects calculation of times from single source to multiple stations, or from multiple sources to single station. The phase labels in the output phase/observation file are set to the station labels or to the source labels, depending on the mode.
mode
(choice: SRCE_TO_STA STA_TO_SRCE
, default:SRCE_TO_STA
)
SRCE_TO_STA
for single sources to multiple stations or
STA_TO_SRCE
for single station to multiple sources.
EQQUAL2ERR  Quality to Error Mapping
required, nonrepeatable
Syntax 1: EQQUAL2ERR
Err0 ... ... ... ...
Specifies the mapping of error to phase pick quality for output of phase/observations in HYPO71 file format (which does not include time uncertainties) (
i.e.
time uncertainties in seconds (
i.e.
0.01
or
0.5
) to quality
0,1,2,3
or
4
).
Err0 ... ErrN
(float, min:0.0
)
one time uncertainty value for each quality level that may be output to the phase/observation file. Synthetic errors less than or equal to the first value
Err0
are output with quality
0
, less than or equal to the second are output with
1
, etc.
EQVPVS  P Velocity to S Velocity Ratio
optional, nonrepeatable (ver 2.0)
Syntax 1: EQVPVS
VpVsRatio
Specifies the P velocity to S velocity ratio to calculate S phase traveltimes.
VpVsRatio
(float)
P velocity to S velocity ratio. If
VpVsRatio
> 0.0 then only P phase traveltimes grids are read and
VpVsRatio
is used to calculate S phase traveltimes. If
VpVsRatio
< 0.0 then S phase traveltimes grids are used.
NLLoc Program
LOCSIG

LOCCOM

LOCSRCE

LOCFILES

LOCHYPOUT

LOCSEARCH

LOCMETH

LOCGAU

LOCGAU2

LOCPHASEID

LOCQUAL2ERR

LOCGRID

LOCPHSTAT

LOCANGLES

LOCMAG

LOCCMP

LOCALIAS

LOCEXCLUDE

LOCDELAY

LOCELEVCORR

LOCTOPO_SURFACE

LOCSTAWT

[Top]  [NonLinLoc Home]
LOCSIG  Signature text
optional, nonrepeatable
Syntax 1: LOCSIG
signature
Identification of an individual, institiution or other entity  written in some output files.
signature
(line) signature text
LOCCOM  Comment text
optional, nonrepeatable
Syntax 1: LOCCOM
comment
Comment about location run  written in some output files.
comment
(line) comment text
LOCSRCE  Source Description
optional, repeatable (ver 3.0)
Syntax 1: LOCSRCE
...
Duplicate of statement GTSRCE  Source Description.
Allows specification of a station location when using "DEFAULT" traveltime grids during TRANS GLOBAL mode location.
(If for a given station there is no traveltime file containing the station's code in its file name,
and there is a LOCSRCE entry for this station code,
then NLLoc will look for a traveltime file containing "DEFAULT" as station code in its file name to use for this station.
The phase code in the traveltime file names must match that for the station's phase reading.)
LOCFILES  Input and Output File Root Name
required, nonrepeatable
Syntax 1: LOCFILES
obsFiles obsFileType ttimeFileRoot outputFileRoot iSwapBytes
Specifies the directory path and filename for the phase/observation files, and the file
root
names (no extension) for the input time grids and the output files.
obsFiles
(string)
full or relative path and name for phase/observations files, mulitple files may be
specified with standard UNIX "wildcard" characters (
*
and
?
)
obsFileType
(choice: NLLOC_OBS HYPO71 HYPOELLIPSE NEIC CSEM_ALERT SIMULPS HYPOCENTER HYPODD SEISAN NORDIC NCSN_Y2K_5 NCEDC_UCB ETH_LOC RENASS_WWW RENASS_DEP INGV_BOLL INGV_BOLL_LOCAL INGV_ARCH
)
format type for phase/observations files (see
Phase File Formats)
ttimeFileRoot
(string)
full or relative path and file
root
name (no extension) for input time grids (generated by program Grid2Time, edu.sc.seis.TauP.TauP_Table_NLL, or other software.
outputFileRoot
(string)
full or relative path and file
root
name (no extension) for output files
iSwapBytes
(integer, min:0
, max:1
, default:0
)
flag to indicate if hi and low bytes of input time grid files should be swapped. Allows reading of traveltime grids from different computer architecture platforms during TRANS GLOBAL mode location.
LOCHYPOUT  Output File Types
optional, nonrepeatable
Syntax 1: LOCHYPOUT
fileType1 ... ... ... ... ...
Specifies the filetypes to be used for output.
fileType1 ... fileTypeN
(choice: SAVE_NLLOC_ALL SAVE_NLLOC_SUM NLL_FORMAT_VER_2 FILENAME_DEC_SEC SAVE_HYPOELL_ALL SAVE_HYPOELL_SUM SAVE_HYPO71_ALL SAVE_HYPO71_SUM SAVE_HYPOINV_SUM SAVE_HYPOINVERSE_Y2000_ARC SAVE_NLLOC_OCTREE
, default:SAVE_NLLOC_ALL SAVE_HYPOINVERSE_Y2000_ARC
)
File format types to be output:
SAVE_NLLOC_ALL
= save summary and event files of type
NLLoc HypocenterPhase file
,
Phase Statistics file
,
Scatter file
and
Confidence Level file
;
SAVE_NLLOC_SUM
= save summary file only of type
NLLoc HypocenterPhase file
;
NLL_FORMAT_VER_2
= save NLLoc HypocenterPhase files in new format (WARNING: this new output format is currently under development and subject to modification.)
NLLoc HypocenterPhase file
,
Phase Statistics file
,
Scatter file
and
Confidence Level file
;
FILENAME_DEC_SEC
= output file named with 2 decimal second precision instead of default integer second precision  avoids overwriting of output files for multiple events or multiple locations with earliest observation time in same second
;
SAVE_HYPOELL_ALL
= save summary and event files of type
QuasiHYPOELLIPSE file
;
SAVE_HYPOELL_SUM
= save summary file only of type
QuasiHYPOELLIPSE file
;
SAVE_HYPO71_ALL
= save summary and event files of type
HYPO71 Hypocenter/Station file
;
SAVE_HYPO71_SUM
= save summary file only of type
HYPO71 Hypocenter/Station file
;
SAVE_HYPOINV_SUM
= save summary file only of type
HypoInverse Archive file
;
SAVE_HYPOINVERSE_Y2000_ARC
= save summary file only of type
HypoInverse Y2000 Archive file
;
SAVE_NLLOC_OCTREE
= saving of octtree structure to disk file when LOCSEARCH OCT used
)
Notes:
1.
The
HypoInverse Archive
format serves as input to the program
FPFIT (Reasenberg
et al.
, 1985)
for gridsearch determination of focal mechanism solutions.
LOCSEARCH  Search Type
required, nonrepeatable
Syntax 1: LOCSEARCH
GRID numSamplesDraw
Syntax 2: LOCSEARCH
MET numSamples numLearn numEquil numBeginSave numSkip stepInit stepMin stepFact probMin
Syntax 3: LOCSEARCH
OCT initNumCells_x initNumCells_y initNumCells_z minNodeSize maxNumNodes numScatter useStationsDensity stopOnMinNodeSize
Specifies the search type and search parameters. The possible search types are
GRID
(grid search),
MET
(Metropolis), and
OCT
(Octtree).
numSamplesDraw
(integer)
specifies the number of scatter samples to draw from each saved PDF grid (
i.e.
grid with
gridType
=
PROB_DENSITY
and
saveFlag
=
SAVE
) No samples are drawn if
saveFlag
< 0.
numSamples
(integer, min:0
) total number of accepted samples to obtain
numLearn
(integer, min:0
) number of accepted samples for learning stage of search
numEquil
(integer, min:0
) number of accepted samples for equilibration stage of search
numBeginSave
(integer, min:0
) number of accepted samples after which to begin saving stage of search, denotes end of equilibration stage
numSkip
(integer, min:1
)
number of accepted samples to skip between saves (
numSkip
=
1
saves every accepted sample)
stepInit
(float)
initial step size in km for the learning stage (
stepInit
<
0.0
gives automatic step size selection. If the search takes too long, the initial step size may be too large; this may be the case if the search region is very large relative to the volume of the high confidence region for the locations.)
stepMin
(float, min:0.0
) minimum step size allowed during any search stage (This parameter should not be critical, set it to a low value.)
stepFact
(float, min:0.0
) step factor for scaling step size during equilibration stage (Try a value of 8.0 to start.)
probMin
(float) minimum value of the maximum probability (likelihood) that must be found by the end of learning stage, if this value is not reached the search is aborted (This parameters allows the filtering of locations outside of the search grid and locations with large residuals.)
initNumCells_x initNumCells_y initNumCells_z
(integer) initial number of octtree cells in the x, y, and z directions
minNodeSize
(float) smallest octtree node side length to process, the octree search is terminated
after a node with a side smaller than this length is generated
maxNumNodes
(integer) total number of nodes to process
numScatter
(integer) the number of scatter samples to draw from the octtree results
useStationsDensity
(integer, min:0
, max:1
, default:0
) flag, if 1 weights octtree cell probability values used for subdivide decision
in proportion to number of stations in octtree cell;
gives higher search priority to cells containing stations,
stablises convergence to local events when global search used
with dense cluster of local stations
stopOnMinNodeSize
(integer, min:0
, max:1
, default:1
) flag, if 1, stop search when first min_node_size reached, if 0 stop subdividing a given cell when min_node_size reached
Notes:
1.
See NLLoc Program
OctTree Algorithm
,
GridSearch Algorithm
and
Metropolis Sampling Algorithm
for more information.
2.
Samples are saved to a binary, event Scatter file (see
Scatter file formats
). For the gridsearch, because the samples are drawn stochastically, the number of samples actually obtained my differ slightly from the requested number.
3. If a large number of samples are saved, the spatial density of samples will be proportional to the PDF.
4. The scatter samples are useful for plotting the PDF as a transparent "cloud" and for relatively compact disk storage of the PDF.
LOCMETH  Location Method
required, nonrepeatable
Syntax 1: LOCMETH
method maxDistStaGrid minNumberPhases maxNumberPhases minNumberSphases VpVsRatio maxNum3DGridMemory
Specifies the location method (algorithm) and method parameters.
method
(choice: GAU_ANALYTIC EDT EDT_OT_WT EDT_OT_WT_ML
)
location method/algorithm (
GAU_ANALYTIC
= the inversion approach of
Tarantola and Valette (1982) with L2RMS likelihood function.
EDT
= Equal Differential Time likelihood function cast into the inversion approach of
Tarantola and Valette (1982)
EDT_OT_WT
= Weights EDTsum probabilities by the variance of origintime estimates over all pairs of readings. This reduces the probability (PDF values) at points with inconsistent OT estimates, and leads to more compact location PDF's.
EDT_OT_WT_ML
= version of EDT_OT_WT with EDT origintime weighting applied using a gridsearch, maximumlikelihood estimate of the origin time. Less efficient than EDT_OT_WT which uses simple statistical estimate of the origin time.)
maxDistStaGrid
(float) maximum distance in km between a station and the center of the initial search grid; phases from stations beyond this distance will not be used for event location
minNumberPhases
(integer) minimum number of phases that must be accepted before event will be located
maxNumberPhases
(integer)
maximum number of accepted phases that will be used for event location; only the first
maxNumberPhases
read from the phase/observations file are used for location
minNumberSphases
(integer) minimum number of S phases that must be accepted before event will be located
VpVsRatio
(float)
P velocity to S velocity ratio. If
VpVsRatio
> 0.0 then only P phase traveltimes grids are read and
VpVsRatio
is used to calculate S phase traveltimes. If
VpVsRatio
< 0.0 then S phase traveltimes grids are used.
maxNum3DGridMemory
(integer)
maximum number of 3D traveltime grids to attempt to read into memory for MetropolisGibbs search. This helps to avoid timeconsuming memory swapping that occurs if the total size of grids read exceeds the real memory of the computer. 3D grids not in memory are read directly from disk. If
maxNum3DGridMemory
< 0 then NLLoc attempts to read all grids into memory.
minDistStaGrid
(float) minimum distance in km between a station and the center of the initial search grid; phases from stations closer than this distance will not be used for event location
Notes:
1.
See NLLoc Program
Inversion Approach
for more information on the
GAU_ANALYTIC
method.
2.
See NLLoc Program
EDT likelihood function
for more information on the
EDT
method.
3. Phases that are not used for location are written to output files and are used for calculating average residuals.
LOCGAU  Gaussian Model Errors
required, nonrepeatable
Syntax 1: LOCGAU
SigmaTime CorrLen
Specifies parameters for Gaussian modelisationerror covariances
Covariance
_{ij}
between stations
i
and
j
using the relation (
Tarantola and Valette, 1982
):
Covariance
_{ij}
=
SigmaTime
^{2}
exp(0.5(Dist
^{2}
_{ij}
)/
CorrLen
^{2}
)
Dist
is the distance in km between stations
i
and
j
.
SigmaTime
(float, min:0.0
) typical error in seconds for traveltime to one station due to model errors
CorrLen
(float, min:0.0
)
correllaton length that controls covariance between stations (
i.e.
may be related to a characteristic scale length of the medium if variations on this scale are not included in the velocity model)
LOCGAU2  TravelTime Dependent Model Errors
optional, nonrepeatable
Syntax 1: LOCGAU2
SigmaTfraction SigmaTmin SigmaTmax
Specifies parameters for traveltime dependent modelisationerror. Sets the traveltime error in proportion to the traveltime, thus giving effectively a stationdistance weighting, which was not included in the standard Tarantola and Valette formulation used by LOCGAU. This is important with velocity model errors, because nearby stations would usually have less absolute error than very far stations, and in general it is probably more correct that traveltime error is a percentage of the traveltime. Preliminary results using LOCGAU2 indicate that this way of setting traveltime errors gives visible improvement in hypocenter clustering. (can currently only be used with the EDT location methods)
SigmaTfraction
(float, min:0.0
, max:1.0
) fraction of of traveltime to use as error
SigmaTmin
(float, min:0.0
)
minimum travetime error in seconds
SigmaTmax
(float, min:0.0
)
maximum travetime error in seconds
LOCPHASEID  Phase Identifier Mapping
optional, repeatable
Syntax 1: LOCPHASEID
stdPhase phaseCode1 ... ... ... ... ...
Specifies the mapping of phase codes in the phase/observation file (
i.e.
pg
or
Sn
) to standardized phase codes (
i.e.
P
or
S
).
stdPhase
(string) standardized phase code (used to generate timegrid file names)
phaseCode1 ... phaseCodeN
(string)
one or more phase codes that may be present in a phase/observation file that should be mapped to the
stdPhase
.
Notes:
1.
In the current version of NLLoc, it is assumed for some processing (such as the calculation of average P and S station residuals) that the standardized phase codes are
P
and
S
. Thus it is important to use these codes, if possible.
2.
A phase/observation file code will be used unchanged if no
LOCPHASEID
statement is specified, or the code is not present in any
LOCPHASEID
statement.
LOCQUAL2ERR  Quality to Error Mapping
required, nonrepeatable, for phase/observation file formats that do not include time uncertainties ; ignored, nonrepeatable, otherwise
Syntax 1: LOCQUAL2ERR
Err0 ... ... ... ...
Specifies the mapping of phase pick qualities phase/observation file (
i.e.
0,1,2,3
or
4
) to time uncertainties in seconds (
i.e.
0.01
or
0.5
).
Err0 ... ErrN
(float, min:0.0
)
one time uncertainty value for each quality level that may be used in a phase/observation file. The first value
Err0
is assigned to picks with quality
0
, the second to picks with quality
1
, etc.
Notes:
1.
NLLoc requires Gaussian timing error estimates in seconds for the data (phase picks), the
LOCQUAL2ERR
statement allows a conversion of commonly used integer quality codes to
float
time values.
2.
Use a large, positive value (
i.e.
99999.9
) to indicate a phase pick that should have zero weight (infinite uncertainty).
LOCGRID  Search Grid Description
required, repeatable
Syntax 1: LOCGRID
xNum yNum zNum xOrig yOrig zOrig dx dy dz gridType saveFlag
Specifies the size and other parameters of an initial or nested 3D search grid. The order of
LOCGRID
statements is critical (see Notes).
xNum yNum zNum
(integer, min:2
) number of grid nodes in the x, y and z directions
xOrig yOrig zOrig
(float)
x, y and z location of the grid origin in km relative to the geographic origin. Use a large, negative value (
i.e.
1.0e30
) to indicate automatic positioning of grid along corressponding direction (valid for nested grids only, may not be used for initial grid).
dx dy dz
(float) grid node spacing in kilometers along the x, y and z axes
gridType
(choice: MISFIT PROB_DENSITY
)
statistical quantity to calculate on grid
saveFlag
(choice: SAVE NO_SAVE
)
specifies if the results of the search over this grid should be saved to disk
Notes:
1.
The order of
LOCGRID
statements is critical: the first
LOCGRID
is the initial search grid which may not have automatic positionig along any axes. The succeeding
LOCGRID
statements may specify automatic positioning along one or more axes (
xOrig, yOrig, zOrig
=
1.0e30
), but must all be sized (
i.e.
dx*(xNum1)
, etc.) so that they can be fully contained within the preceeding grid. The NLLoc program will attempt to translate a nested grid that intersects a boundary of the initial grid so that it is contained inside of the initial grid; if this is not possible the location will be terminated prematurely.
2.
With automatic positioning (
xOrig, yOrig, zOrig
=
1.0e30
), a grid is shifted in x/y/z so that it is centered on the minimum misfit hypocenter x/y/z of the preceeding grid.
3.
Each search over a grid with
gridType
=
PROB_DENSITY
is time consuming and should generally only be used for a nested grid on which the full PDF is required and will be saved to disk. Use
gridType
=
MISFIT
for the initial grid, for larger nested grids, and for smaller nested grids in maximumlikelihood hypocenter searches (
i.e.
where the PDF is not if interest).
4. The 3D grid dimensions are in kilometers with Z positive down (lefthanded coordinate system).
5.
The grid is
dx*(xNum1)
km long in the x direction, and similarly for y and z.
LOCPHSTAT  Phase Statistics parameters
optional, nonrepeatable
Syntax 1: LOCPHSTAT
RMS_Max NRdgs_Min Gap_Max P_ResidualMax S_ResidualMax Ell_Len3_Max Hypo_Depth_Min Hypo_Depth_Max Hypo_Dist_Max
Specifies selection criteria for phase residuals to be included in calculation of average P and S station residuals. The average residuals are saved to a summary, phase statistics file (see
Phase Statistics file formats
).
RMS_Max
(float, default:VERY_LARGE_DOUBLE
) the maximum allowed hypocenter RMS in seconds
NRdgs_Min
(integer, default:1
) the minimum allowed hypocenter number of readings
Gap_Max
(float, default:VERY_LARGE_DOUBLE
) the maximum allowed hypocenter gap in degrees
P_ResidualMax S_ResidualMax
(float, default:VERY_LARGE_DOUBLE
) the maximum allowed residual in seconds for a P or S phase
Ell_Len3_Max
(float, default:VERY_LARGE_DOUBLE
) the maximum allowed ellipsoid major semiaxis length (km)
Hypo_Depth_Min Hypo_Depth_Max
(float, default:VERY_LARGE_DOUBLE
) the minimum and maximum allowed maximum likelihood hypocenter depth (km)
Hypo_Dist_Max
(float, default:VERY_LARGE_DOUBLE
) the maximum allowed maximum likelihood hypocenter distance (km)
Notes:
1. Because the maximum residual cutoff is abrupt, it should be chosen and used with care.
2.
In the current version of NLLoc, it is assumed in the calculation of average P and S station residuals that the standardized phase codes are
P
and
S
. Thus it is important to use these codes, if possible.
LOCANGLES  Takeoff Angles parameters
optional, nonrepeatable
Syntax 1: LOCANGLES
angleMode qualtiyMin
Specifies whether to determine takeoff angles for the maximum likelihood hypocenter and sets minimum quality cutoff for saving angles and corresponding phases to the
HypoInverse Archive file
.
angleMode
(choice: ANGLES_YES ANGLES_NO
, default:ANGLES_YES
)
sets if takeoff angles are read from angles grid files and output to locations files. (
ANGLES_YES
for angles determination or
ANGLES_NO
for no angles determination)
qualtiyMin
(integer, default:5
)
sets the minimum quality (see
TakeOff Angles Algorithm
) for writing takeoff angles and corresponding phase to the
HypoInverse Archive file
. (
0
to
10
)
LOCMAG  Magnitude Calculation Method
optional, nonrepeatable
Syntax 1: LOCMAG
ML_HB f n K Ro Mo
Syntax 2: LOCMAG
MD_FMAG c1 c2 c3 c4 c5
Specifies the magnitude calculation type and parameters. The possible magnitude types are:
ML_HB
(Local (Richter) magnitudeM_{L}fromHutton and Boore (1987)),
MD_FMAG
(Duration magnitudeM_{L}fromLahr, J.C., (1989) HYPOELLIPSE),
f
(float, min:0.0
)
scaling factor to convertAto an equivalent WoodAnderson amplitude.
n
(float)
n from Hutton and Boore (1987), related to geometrical spreading.
K
(float)
K from Hutton and Boore (1987).
Ro
(float, default:100
)
Optional Reference distance (km) from Hutton and Boore (1987).
Mo
(float, default:3.0
)
Optional Reference magnitude from Hutton and Boore (1987).
c1 c2 c3 c4 c5
(float)
c1 c2 c3 c4 c5 from Lahr, J.C., (1989) HYPOELLIPSE
LOCCMP  Magnitude Calculation Component
optional, repeatable
Syntax 1: LOCCMP
label inst comp ampFactor sta_corr_ml_hb sta_corr_fd_fmag
label
(string)
station label (
i.e.
a station code:
ABC
)
inst
(string)
instrument identification (
i.e.
SP, BRB, VBB
) If inst begins with *
, then arrival is taken as having no absolute timing
(can currently only be used with the EDT location methods)
comp
(string)
component identification (
i.e.
Z, N, E, H
)
ampFactor
(float, min:0.0
)
amplitude factor, amplitude read from phase file is multiplied by
ampFactor
to obtain the amplitude used for magnitude calculation.
sta_corr_ml_hb
(float)
ML_HB
station correction, from Hutton and Boore (1987)
sta_corr_fd_fmag
(float)
FD_FMAG
station correction, from Lahr, J.C., (1989) HYPOELLIPSE
Notes:
1.
Component specific paramaters are applied to all phase observations with matching label, instrument and component. Use
?
or
*
to disable matching of label, instrument or component.
LOCALIAS  Station Code Alias
optional, repeatable
Syntax 1: LOCALIAS
code alias yearStart monthStart dayStart yearEnd monthEnd dayEnd
Specifies (1) an alias (mapping) of station codes, and (2) start and end dates of validity of the alias. Allows (1) station codes that vary over time or in different pick files to be homogenized to match codes in time grid files, and (2) allows selection of station data by time.
code
(string) station code (or station name or source label) as read from the phase/observation files, or from the result of another alias evaluation
alias
(string)
new station code which will replace
code
if the relevant phase pick time falls within the start and end dates of validity of the alias
yearStart monthStart dayStart
(integer)
year (including century), month and day of start date of validity of the alias (
0 0 0
= no start date)
yearEnd monthEnd dayEnd
(integer)
year (including century), month and day of end date of validity of the alias (
9999 99 99
= no end date)
Notes:
1.
In NLLoc, the alias evaluation is applied recursively, regardless of the order of the
LOCALIAS
statements. Thus, when selecting and specifying alias names, beware of infinite recursion.
2.
A trailing underscore "_" in an alias will only be used for time grid identification, not for output. This allows, for example, a station name
ABC
to be aliases to the name
ABC_
to enforce certain dates of validity for the station, this requires that the time grids generated by Grid2Time use the station code
ABC_
; in all NLLoc output, the code
ABC
will be used.
LOCEXCLUDE  Exclude Observations
optional, repeatable (ver 2.0)
Syntax 1: LOCEXCLUDE
name phase
name
(string)
station label (
i.e.
a station code:
ABC
) identifier after application of any alias
phase
(string)
phase code beofore mapping by
LOCPHASEID
(
P
,
S
,
PN
, etc).
Notes:
1. Excluded station/phase observations are weighted to 0 and so will not be used for location. The residual is calculated for these observations and they are written to output files, if a traveltime is available.
LOCDELAY  Phase Time Delays
optional, repeatable
Syntax 1: LOCDELAY
code phase numReadings delay
Specifies P and S delays (station corrections) to be subtracted from observed P and S times.
code
(string) station code (after all alias evaluations)
phase
(string)
phase type (
P
or
S
)
numReadings
(integer) number of residuals used to calculate mean residual/delay (not used by NLLoc, included for compatibility with the format of a summary, phase statistics file)
delay
(float) delay in seconds, subtracted from observed time
Notes:
1.
The body of a summary, phase statistics file (see
Phase Statistics file formats
) can be used directly as a set of
LOCDELAY
statements. Thus the average phase residuals from a run of NLLoc can be used as the station corrections for later runs of NLLoc.
LOCELEVCORR  Simple, vertical ray elevation correction
optional, nonrepeatable
Syntax 1: LOCELEVCORR
flag velP velS
Calculates a simple elevation correction using the traveltime of a vertical ray from elev 0 to the elevation of the station. This control statement is mean to be used in GLOBAL mode with TauP or other time grids which use elevation 0 for the station elevation.
flag
(integer, min:0
, max:1
, default:0
) flag to set activation of simple elevation correction (0=NO, 1=Yes)
velP
(float) sets the P velocity to use for calculation of the elevation correction for P type phases (last leg of phase is P or p)
velS
(float) sets the S velocity to use for calculation of the elevation correction for S type phases (last leg of phase is S or s)
LOCTOPO_SURFACE  Topographic mask for location search region
optional, nonrepeatable
Syntax 1: LOCTOPO_SURFACE
gmtGrdFile flagDumpDecimation
Uses a topographic surface file in GMT ascii GRD format to mask prior search volume to the halfspace below the topography.
gmtGrdFile
(string) path and file name of a GMT grd file defining the topographic surface in coordinates lat(deg)/long(deg)/elev(m)
flagDumpDecimation
(integer) if flagDumpDecimation
> 0 write surface data to xyzelev file using decimation factor flagDumpDecimation
. Output file is in
NLL Scatter file format; this format can be plotted in SeismicityViewer.
LOCSTAWT  Station distribution weighting
optional, nonrepeatable
Syntax 1: LOCSTAWT
flag cutoffDist
Calculates a weight for each station that is a function of the average distance between all stations used for location. This helps to correct for irregular station distribution, i.e. a high density of stations in regions such as Europe and North America and few or no stations in regions such as oceans. The relative weight for station i is:
flag
(integer, min:0
, max:1
, default:0
) flag to set activation of station distribution weighting (0=NO, 1=Yes)
cutoffDist
(float) sets the cutoff distance for weighting calculation. cutoffDist
< 0.0
sets automatic cutoff distance: equal to the mean distance between all pairs of stations used for location.