NonLinLoc implementation for SeisComP3

Contributor: Funded by SED/ETH Zurich, developed by gempa GmbH.
Required SC3 version: Release Potsdam 2010 and above

The NonLinLoc (NLL) locator algorithm has been implemented into SeisComP3 through the plugin mechanism. A new plugin locnll contains the LocatorInterface implementation for NonLinLoc.

The implementation bundles the NonLinLoc source files required to use the library function calls. The following source files are included:

 GridLib.c
 GridLib.h
 GridMemLib.c
 GridMemLib.h
 NLLocLib.h
 NLLoc1.c
 NLLocLib.c
 calc_crust_corr.c
 calc_crust_corr.h
 crust_corr_model.h 
 crust_type_key.h
 crust_type.h
 loclist.c
 octtree.h
 octtree.c
 phaseloclist.h
 phaselist.c
 geo.c
 geo.h
 geometry.h
 map_project.c
 map_project.h 
 otime_limit.c
 otime_limit.h
 ran1.c
 ran1.h
 velmod.c
 velmod.h
 util.h
 util.c
 alomax_matrix/alomax_matrix.c
 alomax_matrix/alomax_matrix.h
 alomax_matrix/alomax_matrix_svd.c
 alomax_matrix/alomax_matrix_svd.h

Error measures

After running NonLinLoc the output is converted into a SC3 (QuakeML) origin object including all available error measures. The following table shows how the NLL error measures are mapped to the SC3 data model:

Plugin: locnll

The NonLinLoc plugin is installed under

$SEISCOMP3_ROOT/trunk/share/plugins/locnll.so

It provides a new implementation for the LocatorInterface with the name NonLinLoc.

To add the plugin to a module add it to the modules configuration, either modulename.cfg or global.cfg:

plugins = ${plugins}, locnll

Basically it can be used by two modules: screloc and scolv.

Configuration

The locnll does not use a dedicated configuration file. Instead it uses the applications configuration it has been loaded into.

NonLinLoc.controlFile

Define the default control file if no profile specific control file is defined. The plugin always appends to the NLL control buffer LOCHYPOUT NONE and overrides an existing value. The output of NLL results is handled by the plugin itself.

NonLinLoc.publicID

Configurable publicID creation pattern for newly created origins. The default value is

  NLL.@time/%Y%m%d%H%M%S.%f@.@id@

NonLinLoc.outputPath

Defines the output path of NLL hypo files and grids. The default path is

  /tmp/sc3.nll

NonLinLoc.defaultPickError

The default pick error in seconds passed to NonLinLoc if a SC3 pick object does not provide pick time uncertainties. The default value is 0.5.

NonLinLoc.fixedDepthGridSpacing

Since NLL does not support fixing the depth natively so this feature is emulated by settings the Z grid very tight around the depth to be fixed. This value sets the Z grid spacing. The default value is 0.1.

NonLinLoc.allowMissingStations

Specifies the behaviour if an unknown station is given. The default is true and means that unknown stations are going to be ignored and removed from the solution. If false is defined and an unknown station is passed the call will abort and throw an exception.

NonLinLoc.enableSEDParameters

Enables the output of SED (Swiss Seismological Service) specific NonLinLoc result attributes: quality and diffMaxLikeExpect. Both attributes are not part of the internal SC3 datamodel and are stored as comments within an origin:

• Comment {id = "SED.quality", text = value}
• Comment {id = "SED.diffMaxLikeExpect", text = value}

The default value is false.

NonLinLoc.profiles

Defines the list of available locator profiles. The order of given profiles defines also the priority. A profile contains a NLL configuration file and a region it is defined for. When an origin is going to be relocated the implementation goes through all available profiles and selects the first matching one.

All parameters of a profile are configured with the prefix 'NonLinLoc.profile.[name]'.

NonLinLoc.profile.[name].earthModelID

Defines a string of the earthModelID that is written into the SC3 origin object.

NonLinLoc.profile.[name].methodID

Defines a string of the methodID that is written into the SC3 origin object. One can encode the NLL algorithm used, e.g. "NonLinLoc(EDT)". The default methodID is "NonLinLoc".

NonLinLoc.profile.[name].tablePath

Defines the path to the NLL velocity tables for a particular profile. This path is directly passed to NonLinLoc.

NonLinLoc.profile.[name].region

Defines a profile's region as a list of 4 values: lat_min, lon_min, lat_max, lon_max. If the region is omitted then a global region is assumed and a "1" is appended to the NLL control parameter LOCFILES and TRANS GLOBAL is passed as well to the NLL control buffer.

NonLinLoc.profile.[name].controlFile

Defines the NLL control file that passed to NLL when using a particular profile.

Output

All output is stored in the configured NonLinLoc.outputPath. The file prefix for a location is the originID (NonLinLoc.publicID).

The following file are stored:

• Input observations (.obs)
• Input configuration (.conf)
• NLL location (.loc.hyp)
• NLL 3D grid header (.loc.hdr)
• NLL octree (.loc.octree)
• NLL scatter file (.loc.scat)

In addition to the native NLL output a SC3 origin object is created and returned to the calling instance. Usually this object is then sent via the messaging.

screloc

screloc is an automatic relocator that receives origins from the real-time locator (e.g. scautoloc) and relocates them with a configurable locator. To run screloc along with all processing modules add it to the list of clients in the seiscomp configuration frontend.

screloc does not yet listen to event information and skips origins for that a more recent one exists. Instead any incoming automatic origin is processed.

The following example configuration show how to setup screloc for NonLinLoc.

plugins = ${plugins}, locnll

# Define the locator algorithm to use
reloc.locator = NonLinLoc

########################################################
################ NonLinLoc configuration################
########################################################
NLLROOT = ${HOME}/nll/data

NonLinLoc.outputPath = ${NLLROOT}/output/

# Define the default control file if no profile specific
# control file is defined.
NonLinLoc.controlFile = ${NLLROOT}/NLL.default.conf

# Set the default pick error in seconds passed to NonLinLoc
# if no SC3 pick uncertainty is available.
NonLinLoc.defaultPickError = 0.1

# Define the available NonLinLoc location profiles. The order
# implicitly defines the priority for overlapping regions
#NonLinLoc.profiles = swiss_3d, swiss_1d, global
NonLinLoc.profiles = swiss_3d, global

# The earthModelID is copied to earthModelID attribute of the
# resulting origin
NonLinLoc.profile.swiss_1d.earthModelID = "swiss regional 1D"

# Specify the velocity model table path as used by NonLinLoc
NonLinLoc.profile.swiss_1d.tablePath = ${NLLROOT}/time_1d_regio/regio

# Specify the region valid for this profile
NonLinLoc.profile.swiss_1d.region = 41.2, 3.8, 50.1, 16.8
                                                           
# The NonLinLoc default control file to use for this profile
NonLinLoc.profile.swiss_1d.controlFile = ${NLLROOT}/NLL.swiss_1d.conf

# Configure the swiss_3d profile
NonLinLoc.profile.swiss_3d.earthModelID = "swiss regional 3D"
NonLinLoc.profile.swiss_3d.tablePath = ${NLLROOT}/time_3d/ch
NonLinLoc.profile.swiss_3d.region = 45.15, 5.7, 48.3, 11.0
NonLinLoc.profile.swiss_3d.controlFile = ${NLLROOT}/NLL.swiss_3d.conf

# And the global profile
NonLinLoc.profile.global.earthModelID = iaspei91
NonLinLoc.profile.global.tablePath = ${NLLROOT}/iasp91/iasp91
NonLinLoc.profile.global.controlFile = ${NLLROOT}/NLL.global.conf

Options

screloc supports commandline options as well as configuration files (screloc.cfg).

The default operation mode of screloc is to listen to origins and to sent relocated versions.

Commandline

-O, --origin-id <originID>

Relocate the origin with the given ID and send the result back unless --test has been given as well. screloc will immediately return afterwards.

--test

Do not send any messages.

--locator

Sets the locator to be used. This setting overrides the reloc.locator configuration parameter.

Configuration

Users configuration file: $HOME/.seiscomp3/screloc.cfg

reloc.locator = <string>

Specify the locator to be used. Example:

  reloc.locator = NonLinLoc

Note: The locator implementation must be loaded before usable. Make sure to load the corresponding plugin as well.

scolv

Configuration

To add the new locator to scolv almost the same configuration is used as for screloc except the reloc.locator parameters:

1. Load the NLL plugin

   plugins = ${plugins}, locnll
   

2. Configure NLL

   ########################################################
   ################ NonLinLoc configuration################
   ########################################################
   NLLROOT = ${HOME}/nll/data
   
   NonLinLoc.outputPath = ${NLLROOT}/output/
   
   # Define the default control file if no profile specific
   # control file is defined.
   NonLinLoc.controlFile = ${NLLROOT}/NLL.default.conf
   
   # Set the default pick error in seconds passed to NonLinLoc
   # if no SC3 pick uncertainty is available.
   NonLinLoc.defaultPickError = 0.1
   
   # Define the available NonLinLoc location profiles. The order
   # implicitly defines the priority for overlapping regions
   #NonLinLoc.profiles = swiss_3d, swiss_1d, global
   NonLinLoc.profiles = swiss_3d, global
   
   # The earthModelID is copied to earthModelID attribute of the
   # resulting origin
   NonLinLoc.profile.swiss_1d.earthModelID = "swiss regional 1D"
   
   # Specify the velocity model table path as used by NonLinLoc
   NonLinLoc.profile.swiss_1d.tablePath = ${NLLROOT}/time_1d_regio/regio
   
   # Specify the region valid for this profile
   NonLinLoc.profile.swiss_1d.region = 41.2, 3.8, 50.1, 16.8
                                                              
   # The NonLinLoc default control file to use for this profile
   NonLinLoc.profile.swiss_1d.controlFile = ${NLLROOT}/NLL.swiss_1d.conf
   
   # Configure the swiss_3d profile
   NonLinLoc.profile.swiss_3d.earthModelID = "swiss regional 3D"
   NonLinLoc.profile.swiss_3d.tablePath = ${NLLROOT}/time_3d/ch
   NonLinLoc.profile.swiss_3d.region = 45.15, 5.7, 48.3, 11.0
   NonLinLoc.profile.swiss_3d.controlFile = ${NLLROOT}/NLL.swiss_3d.conf
   
   # And the global profile
   NonLinLoc.profile.global.earthModelID = iaspei91
   NonLinLoc.profile.global.tablePath = ${NLLROOT}/iasp91/iasp91
   NonLinLoc.profile.global.controlFile = ${NLLROOT}/NLL.global.conf
   

Usage

Locator

The usage of the new NLL plugin is straight forward. Once loaded successfully the new locator shows up in the lower left corners combo box.

Select the new NonLinLoc locator and the configured profiles will be loaded into the combo box right of it.

The NonLinLoc implementation provides a virtual profile automatic. This emulates the complete automatic case and selects the best matching configured profiles based on the initial location.

If an origin has been relocated the method should be set to "NonLinLoc" and the earth model contains the string NonLinLoc.profile.[name].earthModelID configured for the selected profile.

Settings

The NLL locator implementation supports to override configured settings or control parameters for a session. Those changes are not persistent and lost if the locator is changed to another one or the profile has been changed.

To open the settings dialog press the button right to the locator selection combo box.

Then the NLL specific parameters show up.

Each parameter can be edited by double clicking into the value (2nd) column. Press Enter to apply the settings. When done press Ok. The next locator run will use the new settings. The format of the NonLinLoc settings is exactly the same as for NonLinLoc control files.

This option is meant for fine tuning the locator interactively and to apply the parameters then to the profiles control file persistently.

Seismicity Viewer

scolv provides two additional configurable buttons. To bind Seismicity Viewer to the first one the following configuration can be used:

button0 = "Seismicity Viewer"
scripts.script0 = @CONFIGDIR@/scripts/sv

A small wrapper script sv has been created that calls Seismicity Viewer based on the origin ID passed to the script.

#!/bin/sh
FILE=$HOME/nll/data/output/$1.loc.hyp
java -classpath $HOME/nll/bin/SeismicityViewer50.jar net.alomax.seismicity.Seismicity $FILE

This examples assumes that Seismicity Viewer has been installed in $HOME/nll/bin.

Attachments

• locator_profile_selection_small.png (10.8 KB) - added by jabe
• locator_selection_small.png (10.0 KB) - added by jabe
• locator_settings.png (9.8 KB) - added by jabe
• NLL_settings.png (29.1 KB) - added by jabe
• origin_information.png (30.9 KB) - added by jabe