[seiscomp, scanloc] Install, add .gitignore
This commit is contained in:
470
share/doc/seiscomp/html/_sources/apps/global_hypo71.rst.txt
Normal file
470
share/doc/seiscomp/html/_sources/apps/global_hypo71.rst.txt
Normal file
@ -0,0 +1,470 @@
|
||||
.. _global_hypo71:
|
||||
|
||||
######
|
||||
Hypo71
|
||||
######
|
||||
|
||||
The traditional Hypo71PC locator with SeisComP.
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
The Hypo71 locator algorithm by Fred Klein locator (:cite:t:`lee-1975`) has
|
||||
been implemented into |scname| through the plugin mechanism. The plugin *hypo71*
|
||||
contains the LocatorInterface implementation for Hypo71.
|
||||
This plugin uses a slightly modified Hypo71 version from Alexandre Nercessian (IPGP)
|
||||
which allows negative earthquake depth (above sea level) and negative stations
|
||||
altitude (below sea level - OBS).
|
||||
|
||||
The development of this plugin was co-financed by the European Union and
|
||||
`le Ministère de l'Ecologie, du Développement Durable, des Transports et du Logement
|
||||
<http://www.developpement-durable.gouv.fr>`_
|
||||
and developed by :cite:t:`ovsm` / :cite:t:`ipgp`.
|
||||
|
||||
|
||||
How it works
|
||||
============
|
||||
|
||||
When receiving a list of arrivals to locate, the plugin builds a Hypo71 input
|
||||
file with informations from the station inventory and configured profile.
|
||||
It then runs Hypo71, reads the output file and sends the results (location,
|
||||
uncertainties, RMS, pick residuals ...) to |scname|.
|
||||
|
||||
If several trial depths are configured, the plugin will run as many Hypo71
|
||||
rushes as configured depths.
|
||||
Then all the results are read, and a decision is made on the best one, based on
|
||||
location RMS and uncertainty.
|
||||
A final run is then made with the best result depth as trial depth.
|
||||
|
||||
|
||||
Profiles
|
||||
========
|
||||
|
||||
The plugin allows the user to set up as many profiles as needed.
|
||||
A profile contains all the information relative to the velocity model and
|
||||
Hypo71 iteration parameters.
|
||||
|
||||
This allows the user to tune the behaviour of Hypo71 to what he needs.
|
||||
If no profiles are set-up, the plugin will use default Hypo71 profile, according
|
||||
to example shown in Hypo71 first publication.
|
||||
Some of this default Hypo71 parameters have been altered to allow more and finer
|
||||
iteration, since computer power is now far above what was available in the 1970's.
|
||||
|
||||
|
||||
Error measures
|
||||
==============
|
||||
|
||||
After running Hypo71, the output is converted into a |scname| origin (:term:`SCML`)
|
||||
object including some error measures. The following table shows how
|
||||
the Hypo71 error measures are mapped to the |scname| data model:
|
||||
|
||||
========================================================= =====================================================
|
||||
|scname| Hypo71
|
||||
========================================================= =====================================================
|
||||
Origin.latitude.uncertainty ERH/sqrt(2)
|
||||
Origin.longitude.uncertainty ERH/sqrt(2)
|
||||
Origin.depth.uncertainty ERZ
|
||||
Origin.originQuality.standardError _
|
||||
Origin.originQuality.secondaryAzimuthalGap _
|
||||
Origin.originQuality.usedStationCount usedStationCount
|
||||
Origin.originQuality.associatedStationCount associatedStationCount
|
||||
Origin.originQuality.associatedPhaseCount associatedPhaseCount
|
||||
Origin.originQuality.usedPhaseCount associatedPhaseCount
|
||||
Origin.originQuality.depthPhaseCount depthPhaseCount
|
||||
Origin.originQuality.minimumDistance km2deg(Tdist.front)
|
||||
Origin.originQuality.maximumDistance km2deg(Tdist.back)
|
||||
Origin.originQuality.medianDistance km2deg(~Tdist)
|
||||
Origin.originQuality.groundTruthLevel QUALITY
|
||||
Origin.originUncertainty.horizontalUncertainty _
|
||||
Origin.originUncertainty.minHorizontalUncertainty _
|
||||
Origin.originUncertainty.maxHorizontalUncertainty _
|
||||
Origin.originUncertainty.azimuthMaxHorizontalUncertainty _
|
||||
ConfidenceEllipsoid.semiMajorAxisLength _
|
||||
ConfidenceEllipsoid.semiMinorAxisLength _
|
||||
ConfidenceEllipsoid.semiIntermediateAxisLength _
|
||||
ConfidenceEllipsoid.majorAxisPlunge _
|
||||
ConfidenceEllipsoid.majorAxisAzimuth _
|
||||
ConfidenceEllipsoid.majorAxisRotation _
|
||||
========================================================= =====================================================
|
||||
|
||||
|
||||
Plugin
|
||||
======
|
||||
|
||||
The *hypo71* plugin is installed under :file:`share/plugins/hypo71.so`.
|
||||
It provides a new implementation of the LocatorInterface with the name Hypo71.
|
||||
|
||||
To add the plugin to a module add it to the modules configuration, either
|
||||
:file:`modulename.cfg` or :file:`global.cfg`:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
plugins = ${plugins}, hypo71
|
||||
|
||||
Basically it can be used by two |scname| modules: :ref:`screloc` and :ref:`scolv`.
|
||||
|
||||
|
||||
Output
|
||||
======
|
||||
|
||||
All output is stored in the configured :confval:`HYPO71ROOT`.
|
||||
|
||||
The following file are stored:
|
||||
|
||||
- Input file (input)
|
||||
- Input configuration (.INP)
|
||||
- Hypo71 location header (.OUT)
|
||||
- Hypo71 location results (.PRT)
|
||||
- Hypo71 ZTR evalutation log (.LOG)
|
||||
|
||||
In addition to the native Hypo71 outp ut a |scname| origin object is created and
|
||||
returned to the calling instance. Usually this object is then sent via messaging.
|
||||
|
||||
In addition, the stdout output of the locator is redirected to |scname| output at
|
||||
INFO level. Each line is identified by leading "Hypo71PC:", e.g.: ::
|
||||
|
||||
12:02:25 [info] Hypo71PC: Date Heure Minute Seconde
|
||||
12:02:25 [info] Hypo71PC: 90113 22 48 3.78 Nb Iterations : 3
|
||||
|
||||
To view this output on the command line add *--debug* to your application when executing on
|
||||
the command line. Increasing logging level of the module which executes the plugin
|
||||
allows to read the output in the log file: ::
|
||||
|
||||
loggging.level = 3
|
||||
|
||||
|
||||
Configuration example
|
||||
=====================
|
||||
|
||||
To add the plugin to an application such as scolv or screloc, add the plugin
|
||||
name to the list of plugins that are loaded (e.g. :file:`scolv.cfg`):
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
plugins = ${plugins}, hypo71
|
||||
|
||||
Futhermore add the plugin configuration (e.g. :file:`scolv.cfg`):
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
########################################################
|
||||
############# Hypo71 plugin configuration ##############
|
||||
########################################################
|
||||
|
||||
# Hypo71 input file to process (generated by plugin)
|
||||
hypo71.inputFile = @DATADIR@/hypo71/HYPO71.INP
|
||||
|
||||
# Hypo71 log file to store ZTR calculation and final results
|
||||
hypo71.logFile = @LOGDIR@/HYPO71.LOG
|
||||
|
||||
# Hypo71 output file to read results from (generated by binary)
|
||||
hypo71.outputFile = @DATADIR@/hypo71/HYPO71.PRT
|
||||
|
||||
# Hypo71 script called by plugin
|
||||
hypo71.hypo71ScriptFile = @DATADIR@/hypo71/run.sh
|
||||
|
||||
# Hypo71 default profile
|
||||
hypo71.defaultControlFile = @DATADIR@/hypo71/profiles/default.hypo71.conf
|
||||
|
||||
# Hypo71 origin patternID
|
||||
hypo71.publicID = Hypo71.@time/%Y%m%d%H%M%S.%f@.@id@
|
||||
|
||||
# Should we use the custom patternID ?
|
||||
hypo71.useHypo71PatternID = false
|
||||
|
||||
# Hypo71 custom profiles examples
|
||||
hypo71.profiles = ModelA
|
||||
hypo71.profile.ModelA.earthModelID = "My Velocity Model A"
|
||||
hypo71.profile.ModelA.methodID = Hypo71PC
|
||||
hypo71.profile.ModelA.controlFile = @DATADIR@/hypo71/profiles/profile.a.conf
|
||||
|
||||
Verify that everything is properly set up in the script :file:`@DATADIR@/hypo71/run.sh`
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
#!/bin/bash
|
||||
HYPO71PC_BINARY=Hypo71PC
|
||||
HYPO71PC_HOME=`dirname $0`
|
||||
|
||||
# Jumping into the right directory
|
||||
cd ${HYPO71PC_HOME}/
|
||||
|
||||
# Executing binary with input file as argument
|
||||
${SEISCOMP_ROOT}/bin/$HYPO71PC_BINARY < input
|
||||
|
||||
Verify that everything is properly set up in the file :file:`${SEISCOMP_ROOT}/share/hypo71/input`
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
HYPO71.INP
|
||||
HYPO71.PRT
|
||||
HYPO71.OUT
|
||||
|
||||
|
||||
.. important ::
|
||||
|
||||
There must be 3 blank lines at the end of the :file:`input` file, those are not to be removed.
|
||||
|
||||
Finally set-up your Hypo71 profile (e.g. :file:`${SEISCOMP_ROOT}/share/hypo71/profiles/profile.a.conf`)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
############################################################
|
||||
## HYPO71 SeisComP Plugin ##
|
||||
## @OVSM-IPGP ##
|
||||
## ##
|
||||
############################################################
|
||||
|
||||
## This profile is based on Dorel velocity model for French Antilles
|
||||
## It allows several iterations at different starting depth for deep and crustal earthquakes
|
||||
|
||||
##############
|
||||
# Reset List #
|
||||
##############
|
||||
TEST(01) = .1 # sec # cutoff RMS value under which Jeffrey's weghting of residuals is not used
|
||||
TEST(02) = 50. # km #
|
||||
TEST(03) = 0.2 # critical F-value for the stepwise multiple regression
|
||||
TEST(04) = .01 # km # adjustment value under which Geiger's iteration is terminated
|
||||
TEST(05) = 5. # km # focal-depth value above which DZ is rest to DZ / (K+1)
|
||||
TEST(06) = 4. # regression TEST(03)/TEST(06) coefficient value if no significant variable is found in the stepwise multiple regression
|
||||
TEST(10) = 2. # km # coefficient value J = D/TEST(10) used for resetting DX and DY
|
||||
TEST(11) = 999. # maximum number of iterations in the hypocentral adjustment
|
||||
TEST(12) = .5 # coefficient value DZ = -Z*TEST(12) used for resetting DZ when hypocenter is placed in the air
|
||||
TEST(13) = 1. # km # standard error value of hypocentral optionally calculated RMS
|
||||
|
||||
## The following values are only available with the Hypo71PC version modified by Alexandre Nercessian (IPGP) which is included with this plugin
|
||||
TEST(15) = -2. # km # maximum altitude of earthquake in km (down is positive)
|
||||
TEST(20) = 1. # used altitude = read altitude * TEST(20) - for example, -2500 = -250 * 10
|
||||
|
||||
|
||||
######################
|
||||
# Crustal Model List #
|
||||
######################
|
||||
CRUSTAL_VELOCITY_MODEL = 3.50, 6.00, 7.00, 8.00
|
||||
CRUSTAL_DEPTH_MODEL = 0.00, 3.00, 15.00, 30.00
|
||||
|
||||
|
||||
################
|
||||
# Control Card #
|
||||
################
|
||||
# MANDATORY
|
||||
ZTR = 5, 20, 40, 60, 80, 100, 150, 200 # km # trial focus depth, at least two
|
||||
# MANDATORY
|
||||
XNEAR = 200. # km # distance from epicenter up to which the distance weighting is 1
|
||||
# MANDATORY
|
||||
XFAR = 450. # km # distance from epicenter beyond which the distance weighting is 0
|
||||
# MANDATORY
|
||||
POS = 1.76 # ratio of P-velocity to S-velocity
|
||||
|
||||
KAZ = 1 # 1 or blank # apply azimuthal weighting of stations ?
|
||||
KSORT = 1 # 1 or blank # sort stations by distance in the output ?
|
||||
|
||||
# Use the position obtained from the best ZTR value ?
|
||||
USE_TRIAL_POSITION = false
|
||||
|
||||
|
||||
####################
|
||||
# Instruction Card #
|
||||
####################
|
||||
KNST = 1 # use S data ?
|
||||
INST = 0 # fix depth ?
|
||||
|
||||
#####################################
|
||||
# Optionnal Weighting Look-Up Table #
|
||||
#####################################
|
||||
# Uncomment if you want to disable dynamic weighting and use those uncertainties as
|
||||
# boundaries for weighting (e.g. a pick with +-0.02 will have a weight of 0)
|
||||
#WEIGHT_UNCERTAINTY_BOUNDARIES = 0.1, 0.2, 0.5, 1.0
|
||||
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Locator
|
||||
-------
|
||||
|
||||
The usage of the new Hypo71 plugin is straight forward. Once loaded successfully
|
||||
the new locator shows up in the lower left corners combo box.
|
||||
|
||||
.. figure:: media/hypo71/locator_selection_small.png
|
||||
:align: center
|
||||
|
||||
Select the new Hypo71 locator and a profile from the pre-configured list.
|
||||
|
||||
.. figure:: media/hypo71/locator_profile_selection_small.png
|
||||
:align: center
|
||||
|
||||
The Hypo71 implementation doesn't provide a virtual profile automatically but the
|
||||
plugins ships with some example profiles.
|
||||
|
||||
If an origin has been relocated the method should be set to "Hypo71" and
|
||||
the earth model contains the name of the profile used to perform this localization.
|
||||
|
||||
.. figure:: media/hypo71/origin_information.png
|
||||
:align: center
|
||||
|
||||
|
||||
Settings
|
||||
--------
|
||||
|
||||
The Hypo71 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.
|
||||
|
||||
.. figure:: media/hypo71/locator_settings.png
|
||||
:align: center
|
||||
|
||||
Then the Hypo71 selected profile parameters show up.
|
||||
|
||||
.. figure:: media/hypo71/hypo71_settings.png
|
||||
:align: center
|
||||
|
||||
|
||||
More
|
||||
====
|
||||
|
||||
* Take a look at Fred Klein HYPOINVERSE Earthquake Location software (:cite:t:`klein-2002`),
|
||||
* Hypo71PC original manual and binary are available on USGS website (:cite:t:`lee-1975`).
|
||||
|
||||
.. _global_hypo71_configuration:
|
||||
|
||||
Module Configuration
|
||||
====================
|
||||
|
||||
|
||||
.. note::
|
||||
**hypo71.\***
|
||||
*Locator parameters: Hypo71*
|
||||
|
||||
|
||||
|
||||
.. confval:: hypo71.logFile
|
||||
|
||||
Default: ``@LOGDIR@/HYPO71.LOG``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Temporary file used by Hypo71 to store calculation logs.
|
||||
|
||||
|
||||
.. confval:: hypo71.inputFile
|
||||
|
||||
Default: ``@DATADIR@/hypo71/HYPO71.INP``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Temporary file to write Hypo71 input data to.
|
||||
|
||||
|
||||
.. confval:: hypo71.outputFile
|
||||
|
||||
Default: ``@DATADIR@/hypo71/HYPO71.PRT``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Temporary output file to read Hypo71 location data from.
|
||||
|
||||
|
||||
.. confval:: hypo71.defaultControlFile
|
||||
|
||||
Default: ``@DATADIR@/hypo71/profiles/default.hypo71.conf``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Hypo71 default profile.
|
||||
If no custom profile is specified, this profile will be used by the plugin when proceeding to a localization.
|
||||
|
||||
|
||||
.. confval:: hypo71.hypo71ScriptFile
|
||||
|
||||
Default: ``@DATADIR@/hypo71/run.sh``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Bash script executed when calling the Hypo71 locator plugin for locating the earthquake.
|
||||
|
||||
|
||||
.. confval:: hypo71.profiles
|
||||
|
||||
Type: *list:string*
|
||||
|
||||
Hypo71 profile name.
|
||||
Multiples names may be set. They must be separated by comma.
|
||||
Each profile can have different velocity or parameters.
|
||||
|
||||
|
||||
.. confval:: hypo71.publicID
|
||||
|
||||
Type: *string*
|
||||
|
||||
Custom patternID to use when generating origin publicID
|
||||
|
||||
|
||||
.. confval:: hypo71.useHypo71PatternID
|
||||
|
||||
Type: *boolean*
|
||||
|
||||
Specifies if the given publicD should be used for generating origin publicID
|
||||
|
||||
|
||||
.. note::
|
||||
**hypo71.profile.\***
|
||||
*Profiles containing the profile-specific velocity model and the Hypo71 parameters.*
|
||||
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
**hypo71.profile.$name.\***
|
||||
$name is a placeholder for the name to be used and needs to be added to :confval:`hypo71.profiles` to become active.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
hypo71.profiles = a,b
|
||||
hypo71.profile.a.value1 = ...
|
||||
hypo71.profile.b.value1 = ...
|
||||
# c is not active because it has not been added
|
||||
# to the list of hypo71.profiles
|
||||
hypo71.profile.c.value1 = ...
|
||||
|
||||
|
||||
.. confval:: hypo71.profile.$name.earthModelID
|
||||
|
||||
Type: *string*
|
||||
|
||||
Profile's velocity model name.
|
||||
|
||||
|
||||
.. confval:: hypo71.profile.$name.methodID
|
||||
|
||||
Default: ``Hypo71``
|
||||
|
||||
Type: *string*
|
||||
|
||||
Profile's method.
|
||||
It is generally the locator's name \(Hypo71\).
|
||||
|
||||
|
||||
.. confval:: hypo71.profile.$name.controlFile
|
||||
|
||||
Type: *string*
|
||||
|
||||
File containing the profile parameters.
|
||||
|
||||
|
||||
.. confval:: hypo71.profile.$name.fixStartDepthOnly
|
||||
|
||||
Default: ``false``
|
||||
|
||||
Type: *boolean*
|
||||
|
||||
If the depth is requested to be fixed \(e.g. by ticking the option
|
||||
in scolv\) the plugin performs only one location starting at
|
||||
specified depth but with free depth evaluation. This option
|
||||
defines whether it should really fix the depth \(false\) or
|
||||
use this fixed depth only as starting point \(true\).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user