# Hyp71_mgr Configuration File Commands

(last revised July 12, 2011)
Page Index:
1. Example configuration file
2. Hyp71_mgr command line arguments
3. Functional command listing
4. Alphabetic command listing & description

For extended documentation on Hypo71PC, please refer to original documentation (which can be found on this web page).

## 1. EXAMPLE CONFIGURATION FILE

    #
    #                    hyp71_mgr's Configuration File
    #
    MyModuleId MOD_EQPROC_TEST   # Label outgoing messages with this module id.
                            # This program is part of a mega-module which is
                            # started by eqproc or eqprelim.  All child
                            # processes of eqproc/eqprelim should use the
                            # same module id.

    RingName   HYPO_RING    # Write output to this transport ring

    LogFile    2            # 0=no log; 1=errors; 2=errors & hypocenters

    SourceCode T            # Label summary cards with this character to
                            # identify them as coming from Earthworm

    #HYPO71PC path - REQUIRED
    #If the path is correctly set up, only the name of the binary is necessary
    #Otherwise, provides the full path to the executable
    HYPO71PC_bin "HYPO71PC"

    #Station list - REQUIRED
    site_file "hypo_sta.list"

    #Velocity model - REQUIRED (at least one layer)
    #Same syntax and usage as in binder
    #@binder_model.d
    lay   0.0     3.5
    lay   3.0     6.0
    lay   15.0    7.00
    lay   30.0    8.00

    #P/S velocity ratio - OPTIONNAl (default = 1.78)
    psratio 1.76		# Default 1.78

    #Hypo71PC Test parameters (MAX 15) - OPTIONNAL
    #See Hypo71 Manual for explanations
    Test 02  50
    Test 03  0.2
    Test 04  0.010
    Test 05  5
    Test 07  -0.87
    Test 08  2.00
    Test 09  0.0035
    Test 10  5
    Test 11  999.0

    #Hypo71PC "distance taper" parameter (control card) - OPTIONNAL
    Xnear	200		# Default 200km - distance at which weight begins to decrease
    Xfar	450		# Default 450km - distance at which weight is null

    #Hypo71PC trial focal depth (control card) - OPTIONNAL
    #List of trial depths (MAX 15) to search before the final run
    #Setting this will result in several runs, each time changing the trial depth
    #And a final run with trial depth and a-priori location been the depth and location
    #Corresponding to the lowest RMS and lowest sqrt(ERH*ERH+ERZ*ERZ) (ie most stable solution)
    #If only one value is set, only one run is performed
    TrialDepth 	50	# Default, only one run, 50km trial focal depth

    #Directory to archive HYPO71PC.INP input files and hypo71PC sreen output
    #May be usefull for debugging - OPTIONNAL
    #Directory must be created manually
    #ArchiveDirectory "hypo71_output"	# Default none, no archiving

    #Localmag file to compute local magnitude - OPTIONNAL
    #If not set, the magnitude is the duration magnitude computed by Hypo71PC based on coda duration
    #If set, localmag magnitude is computed using "standalone" mode of localmag, and the configured localmag.d.
    #If localmag doesn't find any local magnitude, duration magnitude is set on the output
    #Example localmag .d file is included
    #LocalmagFile "localmag.d"

    #Turning Debug messages on - OPTIONNAL
    #Debug 1

    #Test with this hypo2000arc file (turns TestMode on) - OPTIONNAL
    #TestMode runs the module reading an hypo2000_arc message in the file Hypo2000_Test_File and exits
    #There are no interactions with any RingBuffers, either on input or output
    #Everything else behaves normally
    #Hypo2000_Test_File "hypo2000_test_1"

## 2. HYP71_MGR COMMAND LINE ARGUMENTS

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

    	hyp71_mgr hyp71_mgr.d < ncal.hyp
    	argv[0]  argv[1]    <  argv[2]

- argv[0] is the name of the executable.

- argv[1] is the name of hyp71_mgr's own configuration file which it reads on startup. In this file, lines may begin with a valid hypo_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!).

- argv[2] is the name of a file containing an arc2000 type message. hyp71_mgr parses this file and launch Hypo71, before parsing its results and outputing the earthquake location.

## 3. FUNCTIONAL COMMAND LISTING

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

    	Earthworm system setup:
     		MyModuleId		required
    		RingName		required

    	Output Control:
    		LogFile			required
    		Debug
    		ArchiveDirectory

    	Hypo71 Control:
    		HYPO71PC_bin		required
    		Test
    		Xnear
    		Xfar
    		TrialDepth

    	Seismic network/model definition:
    		lay			required
    		psratio
    		site_file		required

    	Miscellaneous:
    		SourceCode		required
    		LocalmagFile
    		Hypo2000_Test_File

## 4. 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.

    command arg1				processed by		function

    ArchiveDirectory path				hyp71_mgr		output

> If set, the path points to the directory where input and output Hypo71 files will be saved for every EQ processed.
> This may be usefull to tweak the parameters and check hyp71_mgr behaviour.

>     Default:  none

    Debug debug				hyp71_mgr		output

> If debug is set to one, then extra debug informations are printed by hyp71_mgr.

>     Default:  none

    Hypo2000_Test_File filename				hyp71_mgr		miscellaneous

> If set, hyp71_mgr will read filename as input message, process it and end.
> This is used only in debug mode when running hyp71_mgr in command line mode. The filename should contain a valid arc2000 message.

>     Default:  none

    HYPO71PC_bin binary				hyp71_mgr		Hypo71

> After parsing the arc2000 input messages, hyp71_mgr calls binary to process the event. This should be the Hypo71PC binary name. If the path is correctly set up, only the name of the binary is necessary, otherwise, provide the full path to the executable.

>     Default:  Hypo71PC (included in the distribution)

    lay depth velocity			t_com			model

> Defines the layered velocity structure to be used for calculating travel times. depth is the distance (km) to the top of the layer, and velocity is the seismic P-wave velocity (km/sec) within that layer. No default velocity structure is defined; therefore, the user must always supply one in the control file. Up to 20 layers can be specified, and they should be listed in order of increasing depth.

>     Default:  none				OVSM  :  lay   0.0  3.5
>     						 lay   3.0  6.0
>     						 lay  15.0  7.0
>      						 lay  30.0  8.0

    LocalmagFile filename				hyp71_mgr		miscellaneous

> Defines the filename of the localmag config file to be used. Setting this variables allows hyp71_mgr to call for localmag to compute local magnitude and include it in the arc2000 output message. If not set, no local magnitude is computed and only the duration magnitude is computed.

>     Default:  none				OVSM:	LocalmagFile	localmag.d

    LogFile switch				hyp71_mgr		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, hyp71_mgr will write daily log file(s) called hypo_mgrxx.log_yymmdd where xx is hyp71_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			hyp71_mgr		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: hyp71_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				OVSM:  MyModuleId MOD_EQPROC

    psratio value				t_com			model

> Sets the value of the P/S seismic velocity ratio.

>     Default:  psratio  1.78			OVSM:	 psratio  1.78

    RingName ring				hyp71_mgr		Earthworm setup

> Tells hypo_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				OVSM:  RingName HYPO_RING

    site_file filename			site_com		model

> Enters site codes and station locations (up to 250) into the site table by reading a HYPOINVERSE format station file called filename. In this file, stations are described by a 5-letter site name, a 2-letter network code and a 3-letter component code. The picker must also be using this station-naming convention. The format of the file is described under "HYPOINVERSE STATION FILE FOR FULL 12-LETTER (S-N-C-L) CHANNEL NAMES". Use either one "site_file" command or multiple "site" commands to load the station list into binder_ew.

    SourceCode label			hyp71_mgr		miscellaneous

> Reads in a single character label to write in column 80 of the hypo71-format summary messages output by hyp71_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				OVSM:	SourceCode W

    Test number value				hyp71_mgr		Hypo71

> Allows to override default Hypo71 parameters.
> Two TEST values have been added by Alexandre Nercessian (IPGP - France) from original Hypo71PC :
> - TEST(15) is the maximum altitude to expect earthquake in km (negative number);
> - TEST(20) is the coefficient by which Hypo71PC multiply altitude readings to obtain then in meter.
> RESET TEST(15)=-2 -> no earthquakes are expected above 2km above sea level.
> RESET TEST(20)=1 -> altitude readings are in meters.
> RESET TEST(20)=10 -> altitude readings are in 10'th of meters. This allow to have sea bottom station (altitude of -245 is a seismometer at 2450m below sea level).
> Test number value is translated in RESET TEST(number)=value in the Hypo71 input file.

>     Default:  none				OVSM:	Test 02  50
>     						Test 03  0.2
>     						Test 04  0.010
>     						Test 05  5
>     						Test 07  -0.87
>     						Test 08  2.00
>     						Test 09  0.0035
>     						Test 10  5
>     						Test 11  999.0

    TrialDepth depth				hyp71_mgr		Hypo71

> List the different (if needed) trial depth for hyp71_mgr depth search iterations.
> For each TrialDepth depth entry, hyp71_mgr will call for Hypo71. Then it will compare the differents result and choose the one with lowest RMS and lowest ERH and ERZ. Finally, it will call Hypo71 with TrialDepth set to the best found.
> If only one value is passed, then only one Hypo71 call is made.

>     Default:  50				OVSM:	TrialDepth	50
>     						TrialDepth	100
>     						TrialDepth	150
>     						TrialDepth	200

    Xfar distance				hyp71_mgr		Hypo71

> Defines the distance taper end.
> At distance km from the epicenter, the station weigh is 0, meaning the phase reading doesn't count in the location process.

>     Default:  450				OVSM:	Xfar	450

    Xnear distance				hyp71_mgr		Hypo71

> Defines the distance taper begin.
> At distance km from the epicenter, the station weigh is 1, meaning the phase reading are not altered.
> Until Xfar, a linear taper is applied on the phase weights.

>     Default:  200				OVSM:	Xnear	200

Module Index | Hyp71_mgr Overview