wiki:nll_mgr

Version 6 (modified by branden, 8 years ago) (diff)

--

Earthworm Module: nll_mgr

Contributed by: Anthony Lomax

Function

Relocates earthquakes using NonLinLoc from Anthony Lomax (tail of mega-module) (New in 7.5)

Details

nll_mgr is an Earthworm program which calls an encapsulated version of the probabilistic, global-search location program NLLoc in the NonLinLoc package (NLL), written by Anthony Lomax. nll_mgr gets "arc messages", containing associated picks, via a pipe from another program. nll_mgr call NonLinLoc with the contents of the "arc message". NonLinLoc locates the event using parameters from the nll_mgr EW Configuration File and from a static NLL control file, and writes standard NLL ouptut to disk files. nll_mgr then creates a new "arc message" with the location results from NonLinLoc and sends that arc message to an Earthworm transport ring.

The NLL location program (NLLoc) performs probabilistic, non-linear, global-search earthquake location in 1D and 3D structures. Travel-times and location are performed in a 3D Grid structure which defines a specific, gridded, rectangular volume (Non-GLOBAL mdoe) or spherical section (GLOBAL mode). A good working knowledge of the NLL package including the setting up of travel-time grids is essential before attempting to configure nll_mgr and use NLLoc within EW. See http://www.alomax.net/nlloc for an overview, download information and sample location tutorials.

nll_mgr is written in C, as is the NonLinLoc package

Disclaimer: The NonLinLoc algorithm makes relatively intense usage of the CPU, depending on number of observations, program parameters, and other factors. Since the "sausage" schema uses eqbuf to hold the next earthquake(s) in buffers until the previous location processing is completed, the intense usage of the CPU will introduce additional delays in event throughput.

Documentation on the NonLinLoc package and the NLL control file parameters is available at the web site: http://www.alomax.net/nlloc -> Control File

Configuration File Commands

EXAMPLE CONFIGURATION FILE

 #
#               nll_mgr's Configuration File
#
MyModuleId MOD_EQPRELIM_NLL   # module id to label outgoing messages with.
                              # Note: nll_mgr is part of a mega-module which is
                              # ultimately started by the program eqproc.  All
                              # child processes of this mega-module need to use the
                              # same module id (thus use eqproc's module id).
RingName   HYPO_RING          # The transport ring to write output to,
LogFile    2                  # 0=no log; 1=errors; 2=errors and hypocenters
SourceCode W                  # character to label summary cards with to
                              # identify them as coming from Earthworm
NllCtrlFile /ew/nll/earthworm.in
                              # NLL control file name with full path (see www.alomax.net/nlloc -> Control File)
                              # This files must exist.
                              # (The NLL LOCFILES statement will be overwritten by nll_mgr)
NllStaFile  /ew/nll/sta_list.in
                              # NLL file containing station coordinates in NLL GTSRCE format
                              # This file must exist.
                              # Use an existing, empty file if station GTSRCE statements
                              # are inside NllCtrlFile
NllTimePath /ew/nll/taup/ak135/ak135
                              # NLL travel-time grid files path/root (see NLL LOCFILES statement)
                              # These files must exist.
NllTimeSwap 1                 # iSwapBytesOnInput value from NLL LOCFILES statement
                              # (0 = NO, 1 = YES) flag to indicate if hi and low
                              # bytes of input time grid files should be swapped. Allows reading of travel time
                              # grids generated with a different binary, floating point byte order than on the
                              # computer running EW.
NllOutPath  /ew/nll/out/nll_mgr0
                              # NLL output file path without NLL "root name"
                              # This directory must exist.
                              # IMPORTANT! - this path should be different from
                              # the path used by any other
                              # instances of modules containing nll_mgr.
                              # NLL output to this path will only be overwritten
                              # by output from subsequent events with same output name
                              # (i.e. same first phase time).

NLL_MGR COMMAND LINE ARGUMENTS

An example command line to start nll_mgr may look like this:

	nll_mgr nll_mgr.d
	argv[0]  argv[1] 
argv[0] is the name of the executable.

argv[1] is the name of nll_mgr's own configuration file which it reads on startup. 

In this file, lines may begin with a valid nll_mgr command, described later in this document, or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).

@  allows control files to be nested; one control file can be
   accessed from another with the command "@" followed by
   a string representing the path name of the next control file
   (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

FUNCTIONAL COMMAND LISTING

Below are the commands recognized by nll_mgr, grouped by the function they influence. All of the commands are required; they must be specified in the configuration file in order for nll_mgr to operate.

	Earthworm system setup:
 		MyModuleId	required
		RingName	required

	Output Control:
		LogFile		required

	Miscellaneous:
		SourceCode	required

	NonLinLoc specific:
		NllCtrlFile	required
		NllStaFile	required
		NllTimePath	required
		NllTimeSwap	required
		NllOutPath	required

ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and the values used by Calnet are listed after each command description.

The following list is organized by:

command [argument here]

LogFile [switch]
Processed by: nll_mgr_config
Function: output

Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is non-zero, nll_mgr will write daily log file(s) called nll_mgrxx.log_yymmdd where xx is nll_mgr's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). The level of output written to the file is controlled by the value of switch:

    switch = 0  no log file is written
             1  write errors to log file
             2  write errors and hypocenters to log file
Default:  none

MyModuleId [mod_id]
Processed by: nll_mgr_config
Function: Earthworm setup

Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number.

NOTE: nll_mgr is part of a mega-module which is ultimately started by the program eqproc. All sub-modules of this megamodule should be given the same module id.

Default:  none				Calnet:  MyModuleId MOD_EQPROC

NllCtrlFile [filename]
Processed by: nll_mgr_config
Function: NonLinLoc

NLL control file name with full path. The specified file must exist. This control statements in this file will be used by NLL when called from EW, except for certain control statements (including LOCFILES) which are automatically set or use parameters from the other nll_mgr configuration file NonLinLoc commands. See www.alomax.net/nlloc -> Control File for a complete description of NLL control file format and statements.

Default:  none				Example:  NllCtrlFile /ew/nll/earthworm.in

NllOutPath [label]
Processed by: nll_mgr_config
Function: NonLinLoc

NLL output file path without NLL "root name" (see NLL LOCFILES statement). This directory must exist. IMPORTANT! - this path should be different from the path used by any other instances of modules containing nll_mgr. NLL output to this path will only be overwritten by output from subsequent events with same output name (i.e. same first phase time).

Default:  none				Example:  NllOutPath /ew/nll/out/nll_mgr0

NllStaFile [filename]
Processed by: nll_mgr_config
Function: NonLinLoc

NLL file containing station coordinates in NLL GTSRCE format. This file must exist. Use an existing, empty file if all station GTSRCE statements are in the file specified by NllCtrlFile. NLL will only use stations whose coordinates are specified by a GRSRCE statement (usually NLL GLOBAL mode location) or for which individaul station travel-time grid files exist on the NllTimePath (usually NLL non-GLOBAL mode location).

Default:  none				Example:  NllStaFile /ew/nll/sta_list.in

NllTimePath [label]
Processed by: nll_mgr_config
Function: NonLinLoc

NLL travel-time grid files path/root (see NLL LOCFILES statement). These files must exist. For NLL GLOBAL mode location there will normally be travel-time grid files for each phase type, for NLL non-GLOBAL mode location, there will normally be a travel-time grid file for each station, either P phase only or P and S phase.

Default:  none				Example:  NllTimePath /ew/nll/taup/ak135/ak135

NllTimeSwap [label]
Processed by: nll_mgr_config
Function: NonLinLoc

iSwapBytesOnInput value from NLL LOCFILES statement. (0 = NO, 1 = YES) flag to indicate if hi and low bytes of input time grid files should be swapped. Allows reading of travel time grids generated with a different binary, floating point byte order than on the computer running EW.

Default:  none				Example:  NllTimeSwap 0

RingName [ring]
Processed by: nll_mgr_config
Function: Earthworm setup

Tells nll_mgr which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

Default:  none				Calnet:  RingName HYPO_RING

SourceCode [label]
Processed by: nll_mgr_config
Function: miscellaneous

Reads in a single character label to write in column 80 of the hypo71-format summary messages output by nll_mgr. This label identifies the source of the hypocenter as the Earthworm system. These summary messages are placed on the output shared memory region.

Default:  none				Calnet:  SourceCode W

Helpful Hints