Calls the weighting function corresponding to the current value of weighting_type in the solution structure. After weighting has been done this function calculates sigma - a weighted measure of standard deviation of residuals that is used in iteration control in function decide_iter. This function also records the values of alpha (which is calculated in the weighting function itself) and sigma from the previous iteration as prev_alpha and prev_sigma. These are compared with the current values in function decide_iter to tell if the solution is converged or diverging.
change_weighting.html 0100644 0002000 0001751 00000004713 07636626364 0015543 0 ustar 00richard dev 0000270 0000002struct phase_weight_rec phase_weight[2] = {
{ "P", 0, 20, 1 },
{ "P", 20, 100, 0.5 },
}struct phase_map_rec phase_map[2] = {
{"p" , "P" },
{"P" , "P" },
}#define statement at the top of main. This file informs the program where to write its error messages,
log file, and data output as well as containing a number of seismological
constants used in the solution. Each line in config.txt corresponds
to an external variable which is assigned in read_config
and which can be declared in any function that needs to know its value.
The options concerning input and output are listed here. Other
constants and options are dealt with elsewhere, when discussing those parts
of the program where the values become important.echo '1759325 depth=NEIC location=NEIC time=NEIC' | location
echo '1759325 time=NEIC' | isclocecho '1759325 depth=33 location='NEIC' | isclocecho 'filename=cannikin.isf seed=IASPEI' | isclocecho 'filename=nevada.isf lat=37.17 lon=-116.45 depth=18.7' | isclocoracle_conn
oracle_disconn
sql_error
Read filenames, options, and constants from configuration file. [read_config]
Open output stream for log of actions. Open output stream for ISF events. (optional)
Event loop - repeated for each line of instructions received
Read instruction line. [read_instruction]
Read in data for next event from database or ISF file. [get_data or read_isf_event]
Use instructions to update event structure. [init_event]
Rank hypocentres for use as seeds. [rank_hyp]
Option loop - repeated for each option or until convergenceExit event loop
Set number of unknowns for this option.Exit option loop if convergence or all options tried
Seed loop - repeated for each hypocentre or until convergence
Reset solution structure for new seed. [init_sol]Exit seed loop if convergence or all seeds tried
Reset purged flag in phase structures.
Solution loop - repeated until convergence/divergence
Calculate delta and azimuth for each phase. [calc_delaz]Exit solution loop if convergence or diverging or max_iter reached
Calculate depth phase depth [calc_depdp] if required to fix solution.
Choose ISC phase code for each phase. [id_pha]
Set weight_factor for each phase. [get_weight_factor]
Recognise duplicate phases and flag them accordingly. [mark_duplicates]
Obtain residual and derivatives for suitable phases. [calc_resid]
Set weight for each phase. [calc_weight]
Solve equations and update solution structure. [solve]
If first convergence
Change weighting scheme (optional) [change_weighting]
Remove phases with large residuals (optional) [purge_pha]
Continue in solution loop if either of the above carried out.
If convergence
Calculate delta and azimuth for each phase. [calc_delaz]
Choose ISC phase code for each phase. [id_pha]
Obtain final residual for all phases. [calc_resid]
Calculate errors for solution. [calc_error]
Calculate magnitudes. [calc_netmag]
Calculate depth phase depth [calc_depdp]
Write solution to database (optional) [put_data]
Write solution to ISF file (optional) [write_isf_event]
pP_duplicates.html 0100644 0002000 0001751 00000002313 07636626367 0015042 0 ustar 00richard dev 0000270 0000002pP_duplicates
Called by: calc_depdp
Includes: iscloc.h
Input arguments:
Pointer to solution structure.
Array of phase structures.
Structure members updated: weight_factor in phase structure.
Return: 0/1 for success/failure.
This function assigns a weight_factor to each pP phase. pP_weight is multiplied by this factor before it is used in solve_depdp. The weight_factor depends purely on how many depth phases have been reported for a given station. If two agencies reported readings with P and pP for the same station print_hyp.html 0100644 0002000 0001751 00000001577 07636626367 0014275 0 ustar 00richard dev 0000270 0000002print_hyp print_hyp
Called by: main at the start of each event.
Includes: iscloc.h
Input arguments:
Pointer to event structure.
Array of hypocentre structures.
Calls: Function write_time from utils .
Structure members updated: none.
Return: 0/1 for success/failure.
This function writes a table of information about the existing hypocentres for an event to the logfile output stream.
nt">event structure.
Array of hypocentre structures.
Calls:purge_pha.html 0100644 0002000 0001751 00000007720 07636626367 0014227 0 ustar 00richard dev 0000270 0000002purge_pha purge_pha
Called by: main after convergence has been reached.
Includes: iscloc.h
External: purge_resid set in read_config.
Input arguments:
Pointer to event structure.
Pointer to solution structure.
Array of phase structures.
Calls: print_pha if diagnostic is on.
Structure members updated:
purged in phase structure.
phases_purged in solution structure.
converged in solution structure.
Return: 0/1 for success/failure.
This function will do nothing unless phases_purged in the solution structure is set to 0. phases_purged may be 1 for two reasons - either the operator gave the no_purge_phase instruction, in which case purge_phase in the event structure will be 0 and phases_purged is set to 1 by init_sol, or phase purging has already been carried out. Once this function has been called once it will set phases_purged to 1 so that it will not do anything if it is called again.
Phases are purged, i.e. the value of purged in a phase structure is set to 1, if they have a residual and its absolute value is greater than purge_resid, a threshold set in config.txt. In addition phases without a residual will be purged if another phase from their reading has been purged and no phases form that reading are being used. This is done to allow whole readings to be unassociated if all the phases with residuals have been purged. If every phase form a reading has been purged then purged is set to 2 for all of them - this is used to exclude these phases during data output so that they can potentially be reused in another event.
If any phases have been purged by this function it will set converged in the solution structure to 0 so that the iteration process will restart with the most recent solution as a starting point and without the purged phases. Note that the iteration process may be restarted after the first convergence regardless of whether any phases have been purged or not because weighting_type may have been changed in function change_weighting, which also updates converged in the solution structure if it does anything.
put_data.html 0100644 0002000 0001751 00000002166 07636626367 0014055 0 ustar 00richard dev 0000270 0000002put_data put_data
Called by: main
Includes: iscloc.h
Input arguments:
Pointer to event structure.
Pointer to solution structure.
Array of phase structures.
Calls: put_event , put_hyp and put_pha .
Structure members updated: none.
Return: 0/1 for success/failure.
If the update_db flag is set in the configuration file then this function will be called once a solution has been found for an event. It calls Pro*C functions that update and insert rows in an ORACLE database with the schema used at the ISC.
put_event.html 0100644 0002000 0001751 00000001755 07636626367 0014270 0 ustar 00richard dev 0000270 0000002put_event put_event
Called by: put_data
Includes: iscloc.h
Input arguments:
Pointer to event structure.
Pointer to solution structure.
Calls: sql_error in oracle_funcs .
Structure members updated: none.
Return: 0/1 for success/failure.
Written in ORACLE Pro*C this function needs to be precompiled to get C code.
This function updates the prime_hyp field of the EVENT row corresponding to this event in the ISC database so that it points to the new hypocentre.
put_hyp.html 0100644 0002000 0001751 00000002522 07636626367 0013740 0 ustar 00richard dev 0000270 0000002put_hyp put_hyp
Called by: put_data
Includes: iscloc.h
External: repid and out_agency set in read_config .
Input arguments:
Pointer to event structure.
Pointer to solution structure.
Calls:
sql_error in oracle_funcs
ORACLE package rn
Structure members updated: none.
Return: 0/1 for success/failure.
Written in ORACLE Pro*C this function needs to be precompiled to get C code.
This function inserts a row into the HYPOCENTER table of the ISC database with the solution found by the iscloc program. It will also add rows to the NETMAG table for any magnitudes calculated for this solution. This new hypocentre and magnitudes will have reporter and author set to repid and out_agency respectively, two variables assigned in the configuration file.
pid and out_agency set in read_config .
Input arguments:
Pointer to event structuput_pha.html 0100644 0002000 0001751 00000003012 07636626370 0013675 0 ustar 00richard dev 0000270 0000002put_pha put_pha
Called by: put_data
Includes: iscloc.h
External: repid and out_agency set in read_config .
Input arguments:
Pointer to solution structure.
Array of phase structures.
Calls:
purge_reading, deprecate_reading, update_reading from this file.
sql_error in oracle_funcs
ORACLE package rn.
Structure members updated: none.
Return: 0/1 for success/failure.
Written in ORACLE Pro*C this function needs to be precompiled to get C code.
This function inserts ASSOCIATION rows into the ISC database to associate the phases used to locate an event with the solution. Purged and duplicate readings are not associated. Purged readings have pref_rd set to rdid so that no link with the event remains. Duplicate readings have pref_rd set equal to the rdid of a reading that is associated. STAMAG rows are also inserted into the database for phases that have had them calculated unless the phases have been purged.
rank_hyp.html 0100644 0002000 0001751 00000003725 07636626370 0014063 0 ustar 00richard dev 0000270 0000002rank_hyp rank_hyp
Called by: main once for each event.
Includes: iscloc.h
Input arguments:
Pointer to event structure.
Array of hypocentre structures.
Array of phase structures.
Calls: Function calc_gap
Structure members updated: rank in hypocentre structure.
Return: 0/1 for success/failure.
Most events relocated at the ISC will have been reported by more than one agency, each of which will have sent a hypocentre and, possibly associated phase picks. Of these reported hypocentres it is important to use the better ones first as starting points for the ISC solution. The first hypocentre to be used as starting point can be set on the instruction line using the format seed=AGENCY, otherwise the first seed will be chosen automatically. In any case, the second and subsequent starting points (for the case when no convergence is reached with the first) will be chosen automatically.
The criteria used to decide the order in which hypocentres will be used are the azimuthal gap and the number of contributing stations/arrivals. If the closest station contributing to a solution is less than 5 degrees away then this is also considered to be in that hypocentre's favour. Each hypocentre is scored with the better hypocentres having the highest scores. The exact scoring method was developed so that hypocentres from test events ended up in the read_config.html 0100644 0002000 0001751 00000006344 07636626370 0014510 0 ustar 00richard dev 0000270 0000002read_config read_config
Called by: main once.
Includes: iscloc.h
External:
instructfile, logfile, errfile, isf_outfile, update_db, repid, out_agency
isf_stafile, default_depth, max_err_factor
min_phases, weighting1, weighting2, sigma_start, mu, init_max_resid, max_resid, purge_resid
max_iter, avg_weight_thresh, alpha_thresh, dalpha_thresh, dsigma_low, dsigma_high
crust_corr_on, elev_corr_on
body_mag_min_dist, body_mag_max_dist, surf_mag_min_dist, surf_mag_max_dist
body_mag_min_per, body_mag_max_per, surf_mag_min_per, surf_mag_max_per
mag_range_warn_thresh
Input arguments: Path/name of configuration file.
Structure members updated: none.
Return: 0/1 for success/failure.
This function reads the configuration file named as its argument and assigns values to external variables that can be used in other functions. It reads the file a line at a time, skipping blank lines. Non blank lines are expected to contain information in the format parameter = value with at least one unit of white space either side of the equals sign. Anything after a # character is treated as a comment and not read. Each parameter read is compared against the list of external variables declared at the top of the function and if it matches one of them then that external variable is assigned the corresponding value.
read_instruction.html 0100644 0002000 0001751 00000005421 07636626370 0015617 0 ustar 00richard dev 0000270 0000002read_instruction read_instruction
Called by: main once for each line present on input stream instructfile.
Includes: iscloc.h
Input arguments:
Single instruction line read by main.
Pointer to event structure.
String declared in main to hold the filename of an ISF input file.
Structure members updated:
evid, seed_agency, depth_agency, location_agency, time_agency, fixed_depth, fixed_lat, fixed_lon, fixed_time, reid_phase, purge_phase, and fix_on_depdp in event structure.
Return: 0/1 for success/failure.
This function parses a single line, splitting its contents into words separated by white space. If a word is a bare integer then it is taken as the evid of the next event to be input from the database, otherwise it is expected to either be one of the recognised flags or of the format parameter=value, in which case the parameter part is checked against a list of expected parameters.
The flags recognised are: no_reid_phase, no_purge_phase, and fix_on_depdp.
Parameters are expected to be followed by = and a value. The recognised ones are: filename, seed, depth, location, lat, lon, and time.
There must be at least one word on each line and this must be either an evid or a filename. Only one of these two options can be present on a single line. If an evid is given then this is stored in the event structure to be read by get_data. If a filename is given then the corresponding file is expected to contain ISF event data and it is passed back to main by assigning it to the character pointer sent to this function as an argument.
Any additional options are used to assign values to members of the event structure. These either concern the selection of starting point and number of unknowns read_isf_event.html 0100644 0002000 0001751 00000007463 07636626370 0015230 0 ustar 00richard dev 0000270 0000002read_isf_event read_isf_event
Called by: main for each event that is requested with a filename on the instruction line.
Includes: iscloc.h, isf_bul.h
External:
MAXSTA, the maximum allowed number of station codes.
Definition of sta_rec structure to hold station location information.
Array of sta_rec structures, stalist.
The number of rows in the stalist array, numsta.
Input arguments:
File pointer to ISF data.
Pointer to event structure.
Pointer to the address of the hypocentre structure array.
Pointer to the address of the phase structure array.
Calls:
Function read_stafile
Functions join_time and print_pha from utils
Functions from isf_read.
Structure members updated:
evid, numhyps and numphas in event structure.
time, lat, lon, depth, depfix, epifix, timfix, nsta, ndefsta, ndef, mindist, maxdist, azimgap, etype, agency, minax, majax, theta, stime, sdepth, sdobs in hypocentre structures.
hypid, phid, rdid, pref_rd, time, init, rep_phase, net, sta, slow, azim, comp, sp_fm, detchar, sta_lat, sta_lon, sta_elev, dircos, and a in phase structures.
Return: 0/1 for success/failure.
This function reads an ISF bulletin format file one line at a time and sends the lines to functions from read_isf, part of a collection of ISF utilities written separately from iscloc. It stores hypocentre and phase parameters in temporary arrays until it is known how many of each are included in the event. Memory is then allocated for arrays of the correct number of hypocentre and phase structures and the values copied to the members of these structures.
Note that the phases in the event are taken as being associated with the top hypocentre. This means that, unless they are given in the origin block, the top hypocentre will be the only one to have values for ndefsta, ndef, mindist, and azimgap and that it will very likely be chosen by rank_hyp as the first seed unless the operator instructs otherwise.
The first time that this function is called (i.e. the first time that an event is read in from file, rather than the database) a function read_stafile is called, which fills an external array of station information structures and allows phase members sta_lat, sta_lon and sta_elev to be assigned by this function without connecting to the database.
read_jb.html 0100644 0002000 0001751 00000023252 07636626370 0013633 0 ustar 00richard dev 0000270 0000002read_jb read_jb
Called by: read_ttime
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Depth of current solution.
Pointer to a phase structure.
Structure members updated: ttime, dtdh, and dtdd in the phase structure.
Calls: ps_g, ps_star, ps_crust, ps_short, ps, pdiff, other_phase all in the same file.
Return: 0/1/2 for success/failure/warning.
This function selects which function to call to read the Jeffreys - Bullen tables for a given phase and enters the values returned by this function for travel time and derivatives into the phase structure. For a P or S wave there are 3 possible functions: ps_short, if delta is less than 1.3 degrees, ps_crust, if the source is above the Moho and ps for anything else. Otherwise the function used depends solely on the phase being considered.
ps
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Pointer to a structure with the correct travel time table. (Could be P, S, PKP, or SKS table)
Distance between station and source in degrees.
Depth of current solution.
Pointers to variables for returning travel time, dt/dh and dt/dd.
Calls:
Function fill_matrix from this file.
Functions interpol and int_diff from this file.
Return: 0 / 1 / 2 for success / failure / warning.
This function looks up the travel time table identified by its first argument. It retrieves a 3x3 matrix of values from the table surrounding the given distance and source depth and then carries out an interpolation to get the required ttime and derivatives.
ps_crust
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
A single character, either P or S
Distance between station and source in degrees.
Depth of current solution.
Pointers to variables for returning travel time, dt/dh and dt/dd.
Calls: Functions interpol and int_diff from this file.
Return: 0/1 for success/failure.
This function looks up travel time tables for a source above the Moho. Because Pg/Sg and Pb/Sb times are found using other functions this function is used for either Pn/Sn or P or S phases when delta is greater than 8 or 10 degrees. Travel times are read from the tables for the 3 columns of the top row surrounding the required delta. These times are then interpolated and the resulting travel time and derivatives corrected for the real source depth.
ps_short
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Pointer to a structure with the correct travel time table. (Could be P short or S short)
Distance between station and source in degrees.
Depth of current solution.
Pointers to variables for returning travel time, dt/dh and dt/dd.
Calls: Functions interpol and int_diff from this file.
Return: 0/1 for success/failure.
This function looks up the 'Short Epicentral Distances' tables to get the 9 travel times surrounding the given distance and source depth. These values are then interpolated to get the required travel time and derivatives.
ps_g
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
A single character, either P or S
Distance between station and source in degrees.
Depth of current solution.
Pointers to variables for returning travel time, dt/dh and dt/dd.
Return: 0/1 for success/failure.
This function calculates the travel time and derivatives for a Pg or Sg phase in the upper crust using the velocities stored in jb_model.h.
ps_star
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
A single character, either P or S
Distance between station and source in degrees.
Depth of current solution.
Pointers to variables for returning travel time, dt/dh and dt/dd.
Return: 0/1 for success/failure.
This function calculates the travel time and derivatives for a Pb or Sb phase. If the source is above the Conrad then the velocities stored in jb_model.h are used to calculate the travel time for the head wave. If the source is in the lower crust then the point where the ray crosses the Conrad is found by iterating to find the smallest possible travel time.
pdiff
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Pointer to structure with P travel time table
Distance between station and source in degrees.
Depth of current solution.
Pointer to variable for returning travel time. (no derivatives)
Return: 0/1 for success/failure.
This function calculates diffracted P travel times using the final row of the P table as a starting point and adding 4.4 seconds per degree over that.
other_phase
Called by: read_jb
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Pointer to structure with a surface focus travel time table.
Distance between station and source in degrees.
Depth of current solution.
Pointer to variable for returning travel time (no derivatives)
Return: 0/1 for success/failure.
This function is used to return a travel time for such phases as PcP, ScS, PP, SS etc. First it looks up the surface focus table that is identified by its first argument to get a travel time as if the source were at the surface. It then corrects for the actual depth using a depth allowance table, the pointer to which is stored in the first table structure.
jb_pP_P
Called by: read_pP_P
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Distance between station and source in degrees.
Depth of current solution.
Pointer to variables for returning difference in travel times and dt/dh
Calls: Functions interpol and int_diff from this file.
Return: 0/1 for success/failure.
This function looks up the Jeffreys - Bullen table for the difference in arrival times between P and pP. It interpolates values either side of the given depth and delta to get the required time difference and derivative, which are passed back to the calling function using the pointers passed as arguments.
interpol
Called by: ps, ps_crust, ps_short, jb_pP_P
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Fraction of table interval.
3 table entries either side of value being looked up.
Return: Interpolated value.
This function carries out Newton Gregory interpolation from three points.
int_diff
Called by: ps, ps_crust, ps_short, jb_pP_P
Includes: iscloc.h, jb_model.h, jb_tables.h
Input arguments:
Fraction of table interval.
3 table entries either side of value being looked up.
Return: Interpolated difference.
This function carries out Newton Gregory difference interpolation from three points.
read_pP_P.html 0100644 0002000 0001751 00000002330 07636626370 0014070 0 ustar 00richard dev 0000270 0000002read_pP_P read_pP_P
Called by: find_pP , calc_pP_resid and solve_depdp.
Includes: iscloc.h
Input arguments:
Depth of current solution.
Pointer to a phase structure.
Calls: Function jb_pP_P from read_jb
Structure members updated: none
Return: 0/1 for success/failure.
This function is a wrapper designed to separate the model dependent function that looks up the relevant pP - P tables, from functions that need to know the times. It allows the Earth model in use to be changed without editing all such functions and, if need be, acts as the interface with functions in a different language such as Fortran. It passes each phase it is given on to the appropriate function and passes back the return status
read_stafile.html 0100644 0002000 0001751 00000003076 07636626370 0014671 0 ustar 00richard dev 0000270 0000002read_stafile read_stafile
Called by: read_isf_event
Includes: iscloc.h, isf_bul.h
External:
Definition of sta_rec structure to hold station location information.
isf_stafile set in read_config
Input arguments: Array of sta_rec structures.
Calls: read_sta from isf_sta.
Structure members updated: net, sta, lat, lon, and elev in sta_rec structures.
Return: number of stations in array of sta_rec structures.
If data is being read from file then it must be assumed that there is no database available. This means that station locations must also be read in from file. This function reads a file in ISF station data_type format and stores the station list in memory. The name of the file to be read must be given in the configuration file and is stored as external variable isf_stafile by read_config. The file is read one line at a time and parsed by function read_sta from isf_sta, part of a collection of ISF utilities written separately from location.
read_ttime.html 0100644 0002000 0001751 00000004450 07636626370 0014361 0 ustar 00richard dev 0000270 0000002read_ttime read_ttime
Called by:
calc_resid for each phase it decides to calculate a residual for.
Phase identification function [ id_jb ]
mark_duplicates
Includes: iscloc.h, model header file [ jb_model.h ]
External: max_depth set here to communicate table specific value back to calc_resid
Input arguments:
Pointer to solution structure.
Pointer to phase structure.
Calls:
Appropriate function for model in use [ read_jb ]
correct_ttime
add_to_error from utils
Return: 0/1/2 for success/failure/warning
This function is a wrapper designed to separate the model dependent function that looks up the relevant travel time tables, or whatever, from functions that need to know travel times. It allows the Earth model in use to be changed without editing all such functions and, if need be, acts as the interface with functions in a different language such as Fortran. It passes each phase it is given on to the appropriate function and passes back the return status (which in the case of read_jb includes a warning status.) It also calls correct_ttime for each phase and would probably need to do this whatever the travel time function in use was.
The header file specific to the Earth model in use is included by this function so that it can set an external variable max_depth to be read by calc_resid and other functions. This informs those functions of the greatest depth allowed for in the model in use and allows them to avoid error messages by not calling read_ttime if the current solution is too deep.
residuals.html 0100644 0002000 0001751 00000011507 07636626370 0014240 0 ustar 00richard dev 0000270 0000002residuals Travel Time Residual Calculation
Each iteration the travel time residual for every defining phase is calculated with respect to the last solution found. This must done after phases have been reidentified in the light of the current source location (id_pha) and before weighting (calc_weight). The function responsible for giving residuals to those phases that will contribute to the next solution is calc_resid . (This function is also called in a different mode after a final convergence to give residuals to all possible phases, whether they were used or not.) Function calc_resid steps through the phases calculating the observed travel time and calling function read_ttime to get the model travel time, it then subtracts the second from the first to get the residual. To simplify the use of different methods to calculate residuals the function read_ttime is just an interface for a model specific travel time function, see the section on changing travel time models. In addition to calling a travel time function function read_ttime calls a function correct_ttime that can be used to apply corrections based on station elevation or crustal model. These corrections can be turned on or off in the configuration file.
Each phase structure has 11 members related to the calculation of the residual and derivatives used in each solution:
- sta_lat - latitude of the station recording the arrival in degrees. Set in whatever function is being used for data input.
- sta_lon - longitude of the station recording the arrival in degrees. Set in whatever function is being used for data input.
- sta_elev - elevation of the station above the geoid in metres. Set in whatever function is being used for data input.
- dircos - array of direction cosines of the station location. Set in whatever function is being used for data input.
- delta - distance between the station and the current epicentre in degrees. Set in function calc_delaz.
- esaz - back azimuth between station and current epicentre in degrees. Set in function calc_delaz.
- time - arrival time of the phase in seconds since the epoch defined in iscloc.h. Set in whatever function is being used for data input.
- ttime - theoretical travel time for the phase in seconds. Set in the travel time function called by function read_ttime.
- resid - difference between observed travel time and time from tables for the phase in seconds. Set in calc_resid.
- dtdh - derivative of time with respect to distance in seconds per degree. Set in the travel time function called by function read_ttime.
- dtdd - derivative of time with respect to depth in seconds per kilometre. Set in the travel time function called by function read_ttime.
There are two external variables related to the calculation of travel times assigned in read_config and corresponding to lines in config.txt:
- crust_corr_on - either 0 or 1. Switch for correction of travel times for separate crustal model. If set to 1 correction will be done.
a different mode after a final convergence to give residuals to all possible phases, whether they were used or not.) Function calc_resid steps thrsolve.html 0100644 0002000 0001751 00000005225 07636626370 0013375 0 ustar 00richard dev 0000270 0000002
- elev_corr_on - either 0 or 1. Switch for correction of travel times for station elevation. If set to 1 correction will be done.
solve solve
Called by: main each iteration.
Includes: iscloc.h
External: max_err_factor set in read_config.
Input arguments:
Pointer to solution structure.
Array of phase structures.
Structure members updated:
time, lat, lon, dircos, depth and covar in solution structure.
Return: 0/1 for success/failure.
This function solves a set of simultaneous equations, one for each defining phase, and stores the results as the current solution. The equation of condition between each arrival and the source in terms of members of a phase structure is:
- x.sin(esaz).dtdd - y.cos(esaz).dtdd + z.dtdh + t = residWhere x,y,z and t are the amounts that the source longitude, latitude, depth, and time need to be altered by to conform with the observed arrival time. These equations constitute a least squares problem and are solved using the method of normal equations, LU decomposition and back substitution for both the 4 unknowns and the covariance matrix. To avoid pivoting problems the diagonal elements of the matrix of normal equations are checked to make sure that none of them approach zero too closely. This is done by comparing them with a threshold calculated using a value assigned in the configuration file max_err_factor. Once x,y,z and t have been found they are used to correct lon, lat, depth and time in the solution structure. The 4x4 covariance matrix is saved as covar in the solution structure so that standard errors can be calculated for the final solution.
solve_depdp.html 0100644 0002000 0001751 00000002651 07636626371 0014552 0 ustar 00richard dev 0000270 0000002solve_depdp solve_depdp
Called by: calc_depdp
Includes: iscloc.h
External:
init_max_resid set by read_config
XSQ_LIM - maximum exponent part of weight for useful phase.
MIN_TOTAL_WEIGHT - minimum total weight required to calculate a depth.
Input arguments:
Pointer to solution structure.
Array of phase structures.
Calls: Function read_pP_P
Structure members updated: depdp and depdp_error in solution structure.
Return: 0/1 for success/failure.
This function uses the residual in pP - P times for depth phases associated with an event to calculate the shift in depth with respect to the current solution depth that would minimize these residuals. It then shifts starting_point.html 0100644 0002000 0001751 00000025737 07636626371 0015324 0 ustar 00richard dev 0000270 0000002starting_point Selection of Starting Point and Number of Unknowns
The starting point used to begin the iterative solution process can make a big difference as to whether convergence is reached or not. The iscloc program uses each of the hypocentres input for an event in turn as a seed hypocentre until one of them converges. The user can choose on the instruction line which hypocentre to use as the first starting point, otherwise they are ranked automatically. By default an attempt is made to solve for the depth, location, and time of an event but it is possible to fix one or more parameters on the instruction line so that they are not solved for - i.e. the number of unknowns has been reduced.
Each hypocentre structure has 7 members related to the choice of starting point and the number of unknowns:
- nsta - number of stations from which phases have been associated with this hypocentre. Set in whatever function is being used for data input or in function calc_gap
- ndefsta - number of stations from which phases were used to solve for this hypocentre. Set in whatever function is being used for data input.
- nass - number of phases associated with this hypocentre. Set in whatever function is being used for data input.
- ndef - number of phases used to solve for this hypocentre. Set in whatever function is being used for data input.
- mindist - distance in degrees between the epicentre and the closest station for which a phase was used in the solution. Set in whatever function is being used for data input or in function calc_gap.
- azimgap - azimuthal gap. Set in whatever function is being used for data input or in function calc_gap
- rank - score given to hypocentre in function rank_hyp. The hypocentre with the highest value will be used as the first seed, then the next highest and so on.
Each phase structure has 1 member related to the ranking of hypocentres:
- hypid - the ID of the hypocentre that the reporting agency associated this phase with. Set in whatever function is being used for data input.
The event structure has 10 members related to the choice of starting point and the number of unknowns:
- seed_agency - agency code of the hypocentre to be used as the first starting point. Set in function read_instruction from instruction seed=AGENCY. Can be reset in function init_event.
- depth_agency - agency code of the hypocentre to take depth from as fixed depth. Set in function read_instruction from instruction depth=AGENCY.
- location_agency- agency code of the hypocentre to take latitude, longitude, and probably depth from to fix location and depth. Set in function read_instruction from instruction location=AGENCY.
- time_agency - agency code of the hypocentre to take time, and probably location and depth from to fix time, location, and depth. Set in function read_instruction from instruction time=AGENCY.
- fixed_depth - depth to fix solution to. Set in function read_instruction from instruction depth=value. Can be reset in function init_event if depth_agency, location_agency or time_agency were set in function read_instruction .
- fixed_lat - latitude to fix solution to. Set in function read_instruction from instruction lat=value. Can be reset in function init_event if location_agency or time_agency were set in function read_instruction .
- fixed_lon - longitude to fix solution to. Set in function read_instruction from instruction lon=value. Can be reset in function init_event if location_agency or time_agency were set in function read_instruction .
- fixed_time - time to fix solution to. Set in function read_instruction from instruction time=value. Can be reset in function init_event if time_agency were set in function read_instruction .
- fix_on_depdp - either 0 or 1. Set in function read_instruction . Will be 0 unless fix_on_depdp is included on the instruction line for this event by the operator.
There is one member of the solution structure related to the number of unknowns:
- number_of_unkowns - 0,1,3, or 4. Number of unfixed solution parameters. Set in main depending on option.
There is one external variable related to the choice of starting point and the number of unknowns assigned in read_config and corresponding to a line in config.txt:
- default_depth - Starting point depth if the hypocentre being used as seed does not have a depth. Also the depth that a solution will be fixed to if the location is explicitly fixed but the depth is not.
After an event and its corresponding instructions have been read function init_event is called to set members of the event structure. These members control the starting option and, if a smaller number of unknowns is required, the values that parameters will be fixed to. Function rank_hyp is then called and gives every hypocentre a ranking. The highest ranked hypocentre will be used as the first starting point for each option, followed by the next highest and so on.
It is also possible to fix the depth of a solution by giving instruction fix_on_depdp. If this is done then solution starts using option 1 and function calc_depdp is called for each hypocentre to calculate a depth phase depth assuming the source to be at the location given by that hypocentre. The solution depth is then fixed to the resulting depth phase depth. If depth instruction is also given then the depth phase depth calculation will be done with a starting depth set to this value.
Loops for option and starting point
The iscloc program loops over all possible hypocentres using each as a starting point or seed until convergence is reached or no more hypocentres remain. It will first use each starting point to try and solve for all 4 parameters (option 0) and then, if none of the seeds converge, it will go back to the first hypocentre and try to solve for location and time using each seed in turn, fixing the depth (option 1). If that fails then a series of attempts is made to solve solely for the source time (option 2). It is possible for the operator to explicitly fix one or more parameters and so skip a set of solution attempts, going directly to a later option. However, the order in which the options are tried is not adjustable - to fix the latitude and longitude the operator must also fix the depth.
Here are some of the loop control lines from main.c
/* Option loop */
/* option 0 is free depth , option 1 is fixed depth, option 2 is fixed depth and location. */
for (option=0;option<3;option++){
/* No free depth pass if fixed depth instruction. */
if (e.fixed_depth != NULLVAL || e.fix_on_depdp)
option++;
/* If location is fixed then depth will always be fixed. */
if (e.fixed_lat != NULLVAL)
option++;
/* Seed loop */
hyp=0;
while (hyp<e.numhyps){
/* Unless convergence has been */
/* reached try another seed. */
if (s.converged)
break;
hyp++;
}
/* Don't need another option if converged already. */
if (s.converged)
break;
}
structures.html 0100644 0002000 0001751 00000031726 07636626371 0014476 0 ustar 00richard dev 0000270 0000002structures Principal Structures
In the iscloc program variables are passed between functions using structures or arrays of structures. There are 5 structures used and these are defined in iscloc.h and the members are listed here:
phase
amplitude
event
hypocentre
solution
phase
- hypid - numerical ID of hypocentre that reporter associated this phase with.
- phid - numerical ID of phase.
- rdid - numerical ID of reading.
- pref_rd - preferred reading ID.
- init - flag set to 1 if this phases is the initial phase in its reading.
- rep_phase - code for phase assigned by the reporter.
- phase - internal phase code.
- net - network code of station.
- sta - station code.
- sta_lat - latitude of station (degrees).
- sta_lon - longitude of station (degrees).
- sta_elev - elevation of station (m).
- dircos - array of direction cosines giving station location.
- time - arrival time of phase (seconds since epoch).
- slow - slowness at station measured for phase (seconds/degree).
- azim - azimuth at station measured for phase (degrees).
- esaz - azimuth between current solution and station (degrees).
- delta - distance between station and current solution (degrees).
- numamps - number of amplitudes measured for this phase and stored in the array a.
- a - array of structures containing amplitude information.
- comp - seismometer component that this phase was picked on.
- sp_fm - short period first motion.
- detchar - [i]mpulsive or [e]mergent
- weight - phase weight.
- weight_factor - 1 for fully weighted phase. 0 for unwanted phase.
- purged - flag set to 1 for phase to be excluded from subsequent iterations.
- duplicate - flag set to 1 for all but one of a set of exact duplicates.
- ttime - travel time (seconds).
- dtdd - derivative of time with delta (seconds/degree).
- dtdh - derivative of time with depth (seconds/km).
- resid - residual (seconds).
- pP_weight - depth phase weight.
- pP_resid - depth phase residual (seconds).
- pP_dtdh - depth phase derivative of time with depth (seconds/km).
- pP_P_time - time between P and pP arrivals (seconds)
- bodymag - station body wave magnitude calculated using this phase.
- surfmag - station surface wave magnitude calculated using this phase.
amplitude
- amp - amplitude in nm.
- per - period in seconds.
- logat - log10 of of amplitude divided by period if this is the value reported.
- comp - component that amplitude was measured on.
event
- evid - numerical ID of event.
- prime - hypid of prime hypocentre for this event in the ISC database.
- isc_hypid - hypid of the ISC hypocentre for this event.
- etype - event type.
- numhyps - number of hypocentres in this event.
- numphas - number of phases associated with hypocentres in this event.
- seed_agency - instruction to use this agency's hypocentre as the first starting point.
- depth_agency - instruction to fix solution depth to that of this agency's hypocentre.
- location_agency - instruction to fix solution latitude and longitude to that of this agency's hypocentre.
- time_agency - instruction to fix solution time to that of this agency's hypocentre.
- fixed_depth - value of depth that solution will be fixed to.
- fixed_lat - value of latitude that solution will be fixed to.
- fixed_lon - value of longitude that solution will be fixed to.
- fixed_time - value of time that solution will be fixed to.
- reid_phase - instruction to reidentify phases that don't fit the model being used. Defaults to 1 or on.
- purge_phase - instruction to purge phases that have large residuals after a first convergence. Defaults to 1 or on.
- fix_on_depdp - instruction to calculate a depth phase depth for each seed hypocentre and then fix on it. Defaults to 0 or off.
hypocentre
- hypid - numerical ID of hypocentre.
- time - source time (seconds since epoch).
- lat - source latitude (degrees).
- lon - source longitude (degrees).
- dircos - array of direction cosines giving source location.
- depth - depth of source (km).
- nsta - number of stations with associated phases.
- ndefsta - number of stations with defining phases.
- nass - number of associated phases.
- ndef - number of defining phases.
- mindist - distance to closest station (degrees).
- maxdist - distance to furthest station (degrees). Not used or effected by program - just input and output as part of this hypocentre.
- azimgap - maximum azimuthal gap between stations (degrees).
- etype - reported event type.
- agency - code of agency that reported this hypocentre.
- sdobs - reported measure of misfit. Not used or effected by program - just input and output as part of this hypocentre.
- stime - reported error in source time. Not used or effected by program - just input and output as part of this hypocentre.
- sdepth - reported error in source depth. Not used or effected by program - just input and output as part of this hypocentre.
- minax - reported minor axis of error ellipse. Not used or effected by program - just input and output as part of this hypocentre.
- majax - reported major axis of error ellipse. Not used or effected by program - just input and output as part of this hypocentre.
- theta - reported azimuth of error ellipse. Not used or effected by program - just input and output as part of this hypocentre.
- depfix - depth fixed flag. Not used or effected by program - just input and output as part of this hypocentre.
- epifix - epicentre fixed flag. Not used or effected by program - just input and output as part of this hypocentre.
- timfix - time fixed flag. Not used or effected by program - just input and output as part of this hypocentre.
- rank - number indicating suitability of hypocentre to act as starting point for solution. Higher ranked hypocentres get used as seeds first.
solution
ut one of a set of exact duplicates.
- iteration - number of current iteration.
- converged - 0/1. 1 if solution has converged.
- diverging - 0/1. 1 if solution is diverging.
- number_of_unknowns - number of unknowns for the current option.
- weighting_type - weighting function in use.
- numphas - number of phases associated with this solution.
- phases_purged - 0/1. 1 if phase purging has already been done or is not required at all.
- hypid - numerical ID assigned to the final solution before it is output.
- time - source time (seconds since epoch).
- lat - source latitude (degrees).
- lon - source longitude (degrees).
- dircos - array of direction cosines giving source location.
- depth - depth of source (km).
- depdp - depth phase depth (km).
- depdp_error - standard error in depth phase depth (km).
- alpha - measure of average weighted residual
- prev_alpha - alpha from previous iteration.
- sigma - measure of deviation of weighted residuals.
- prev_sigma - sigma from previous iteration.
- covar - covariance matrix for solution.
- error - array of standard errors for solution.
- majax - major axis of error ellipse (km).
- minax - minor axis of error ellipse (km).
- theta - azimuth of error ellipse.
- sdobs - measure of standard deviation of weighted residuals.
- mindist - distance to closest station (degrees).
- maxdist - distance to furthest station (degrees).
- azimgap - maximum azimuthal gap between stations (degrees).
- nsta - number of stations with associated phases.
- ndefsta - number of stations with defining phases.
- nass - number of associated phases.
- ndef - number of defining phases.
- bodymag - network body wave magnitude.
- surfmag - network surface wave magnitude.
- nsta_mb - number of stations contributing to body wave magnitude.
- nsta_ms - number of stations contributing to surface wave magnitude.
- mb_id - numerical ID for body wave magnitude, assigned for writing to database.
- ms_id - numerical ID for surface wave magnitude, assigned for writing to database.
print_sol
print_pha
calc_delta
calc_esaz
calc_dircos
dsort
read_time
write_time
split_time
join_time
add_to_error
handle_error
Each phase
structure has 3 members related to phase identification:
Each phase
structure has three members weighting:
In order for a particular type of phase to be used it must be present
in two arrays of structures initialised at the top of of two different functions:
phase_map initialised in function
id_pha
If a phase code is missing from the phase_map array then any arrival with
that operator code will have phase
set to "" and so will end up with a weight_factor
of 0 and not contribute to the solution.
struct phase_map_rec phase_map[2] = {
{"p" , "P" },
{"P" , "P" },
}
Would set phase
to "P" if rep_phase
for an arrival were either "p" or "P". Arrivals with all other phase
codes would have phase
set to "".
Unless the no_reid_phase instruction has been given by the operator
id_pha
also calls a function (e.g. id_jb) to check that an arrival's phase code is consistent with the earth model
being used, the distance between the station and the source, and the source
depth. In the example above this would mean that even an arrival with
rep_phase
"P" would have
phase
set to "" if
delta
were too great for the P travel time tables being used. In practice
a "P" could also be reidentified as "Pg" at certain values of
delta
and source depth but it is an error for the phase identifying function to
assign a value to
phase
not present on the right side of the phase_map array.
phase_weight initialised in function
get_weight_factor
An arrival with a value of phase
that is not present in the phase_weight array will be given a
weight_factor
of 0 and not contribute to the solution. If it has a non null
phase
it will still have a residual calculated for it at the end of the solution
process, after final convergence has been reached.
If an arrival has a value of phase
that is present in the phase_weight array then the
weight_factor
it will be given depends on the distance between the station where it was
recorded and the current solution,
delta. This is why weight_factor
is recalculated every iteration.
struct phase_weight_rec phase_weight[2] = {
{ "P", 0, 20, 1 },
{ "P", 20, 100, 0.5 },
}
Would weight local P arrivals fully while weighting down teleseismic P.
A P arrival from a source more than 100 degrees away would not get a weight
and neither would any other type of arrival.
Two constants weighting1
and weighting2
can be set in config.txt
for a particular run of the iscloc program. weighting1
must equal a name that corresponds to an existing weighting function (although
one of the functions provided is no_weight
which just multiplies the weight_factor
of each phase by 1 to get its weight). weighting2
may or may not be set. If it is set then if convergence is reached
the weighting function in use will be changed to that corresponding to
weighting2
and iteration reinitiated using the result of the first convergence as a
starting point.
weighting1 = huber
weighting2 = buland
If these lines were present in config.txt
then a solution would first be attempted using Huber-t weighting as implemented
in the function huber_weight. If convergence were reached then further iterations would be made
using the function buland_weight
until final convergence was reached (or failed to be reached). The
weighting function currently in use is stored as
weighting_type
in the solution
structure. If weighting2
is set then weighting_type
will be reset by the function change_weighting
after the first convergence.
The three weighting functions provided so far and the corresponding names
that would need to be added to config.txt are:
huber_weight
(huber)
buland_weight
(buland)
no_weight
(none)
To use another function it would be necessary to add an else if block to
the function calc_weight
and provide a new function with the correct input arguments. For example:
# include "iscloc.h"
int new_weight (struct sol_rec *sp, struct pha_rec p[])
{
uction line for this event by the operator.