calc_crust_corr.html010064400020000001751000000042540763662636300154170ustar00richarddev00002700000002 calc_crust_corr
contents

calc_crust_corr

Called by:  correct_ttime for each phase if crust_corr_on =1.

Includes:   iscloc.h, jb_model.h, crust_type.h, crust_type_key.h.

Input arguments
:
Character indicating whether the phase is P or S.
Latitude of either source or station.
Longitude of either source or station.
Depth of source. 0 for station.
Elevation of station if elev_corr_on =1.  NULLVAL otherwise and for source.
dt/dd for the phase.

Structure members updated:   None.

Return:   Travel time correction in seconds.

Gabi  Laski  has made available on the REM web site a global crustal model on a 2 x 2 degree grid.  (http://mahi.ucsd.edu/Gabi/rem.html or
Bassin, C., Laske, G. and Masters, G., The Current Limits of Resolution for Surface Wave Tomography in North America, EOS Trans AGU, 81, F897, 2000.)  Each 2x2 degree 'tile' of the Earth's surface is assigned one of 360 crustal structures each made up of 7 layers.  Each layer has a P velocity, an S velocity and a density.

Here, the crust types are stored in crust_type.h in a two dimensional array which has indexes corresponding to latitude and longitude.  The velocity profiles for each crust type are stored in crust_type_key.h in an array of suitable structures.  For each phase the time to traverse the crust of the homogenious earth model in use is subtracted from the travel time and the time taken to traverse the crust from this model is added on.  This is done for both the source and the station, taking the depth of the former into account and allowing for non-radial take off angle.







calc_delaz.html010064400020000001751000000025560763662636300143340ustar00richarddev00002700000002calc_delaz
contents

calc_delaz

Called by:   main each iteration.

Includes:   iscloc.h

Input arguments:
Pointer to solution structure.
Array of phase structures.

Calls:
calc_delta from utils
calc_esaz from utils
print_pha if diagnostic is on.

Structure members updated:   delta and esaz in each phase structure.

Return:   0/1 for success/failure.

Loops over all the phases contributing to an event and for each initial phase calculates delta and esaz for that reading.  The values are stored in every phase structure but not recalculated for secondary phases.

calc_depdp.html010064400020000001751000000026050763662636300143240ustar00richarddev00002700000002calc_depdp
contents

calc_depdp 

Called by:   main

Includes:   iscloc.h

Input arguments:
Pointer to solution structure.
Array of phase structures.

Calls:   Functions find_pP, pP_duplicates, calc_pP_resid, and solve_depdp.

Structure members updated:  none.

Return:   0/1 for success/failure.

This function calls a sequence of other functions to identify depth phases, calculate pP - P residuals for them and then use the residuals to calculate a depth phase depth.  This function needs to be called after id_pha so that pP phases reported with other names (e.g. AP) have been identified.  If this function is run each iteration, as when the fix_on_depdp flag is set, then id_pha must also be run afterwards as the depth will have changed and the previous identifications are now out of date.
calc_elev_corr.html010064400020000001751000000021510763662636300152040ustar00richarddev00002700000002 calc_elev_corr
contents

calc_elev_corr

Called by:  correct_ttime for each phase if elev_corr_on=1 and crust_corr_on=0.

Includes:   iscloc.h, jb_model.h

Input arguments:  Pointer to a phase structure.

Structure members updated:   None.

Return:  Travel time correction in seconds for elevation of station.

Calculates the extra time spent by a phase to traverse the crust between the geoid and the surface.  Does so by dividing the station elevation by the upper crust velocity for the model in use and by a factor that accounts for non vertical incidence.



calc_error.html010064400020000001751000000066710763662636400143710ustar00richarddev00002700000002calc_error
contents

calc_error

Called by:  main

Includes:   iscloc.h

Input arguments:
Pointer to solution structure.
Pointer to array of phase structures.

Calls: Functions get_fact and get_fact2 from this file.

Structure members updated:  nass, ndef, nsta, ndefsta, sdobs, mindist, maxdist, azimgap, error[], majax, minax, and theta

Return:   0/1 for success/failure.

This function calculates the standard errors and error ellipse for a final solution using the covariance matrix stored by function solve.  It also calculates the final azimuthal gap and the number of stations and phases that were used in the solution.



There are 12 members of the solution structure used to store errors and other information for the final solution.
calc_gap.html010064400020000001751000000050370763662636400140020ustar00richarddev00002700000002calc_gap
contents

calc_gap

Called by:   rank_hyp once for each event.

Includes:   iscloc.h

Input arguments:
Pointer to event structure.
Array of hypocentre structures.
Array of phase structures.

Calls:   calc_delta , calc_esaz, dsort   from utils

Structure members updated:  nsta, azimgap, and mindist in hypocentre structure.

Return:   0/1 for success/failure.

The 3 parameters nsta, azimgap, and mindist are used to order hypocentres in the sequence that they will be used as starting points for the solution process.  These parameters may or may not be provided by the reporting agency, depending on the format that they use and the completeness of their reports.  If any of the parameters are not provided then they are calculated from the phases that the reporting agency associated with their hypocentre. (This may not result in the same values as the agency would have given, as some agencies use more phases in their solution than they send to the ISC but is the best that can be done.)

This function loops over all the hypocentre structures for an event and checks whether nsta, azimgap, and mindist are present for each.  If any value is missing for a hypocentre then this function loops over the phases, if any, associated by the agency that reported this hypocentre.  For each phase nsta is incremented and delta and esaz are calculated.  When all the phases have been counted the azimuthal gap is calculated from the esaz values.
calc_geoid_corr.html010064400020000001751000000035160763662636400153470ustar00richarddev00002700000002 calc_geoid_corr
contents

calc_geoid_corr

Called by:  correct_ttime for each phase.

Includes:   iscloc.h

External:   Array of deltas at which the correction is incremented delta_step[].

Input arguments:
Latitude of the current solution.
Pointer to a phase structure

Calls:   height_above_mean_sphere from this file.

Structure members updated:   None.

Return:   Travel time correction in seconds for height of geoid above mean sphere.

Corrects for the difference in distance travelled between a ray in a spherical Earth, as assumed by the tables, and in a more accurately shaped Earth.  Multiplies the height above the mean sphere of both the station and the source by an average velocity that depends on the distance between the two.  This velocity is stored at 10 delta intervals in the array delta_step[], declared at the top of this file.



height_above_mean_sphere

Called by:  calc_geoid_corr for station and source.

Input arguments: Latitude in radians.

Structure members updated:   None.

Return:   Height above mean sphere in km.

calc_netmag.html010064400020000001751000000035260763662636400145070ustar00richarddev00002700000002calc_netmag
contents

calc_netmag

Called by:  main

Includes:   iscloc.h

External:  mag_range_warn_thresh set in read_config.

Input arguments:
Pointer to solution structure.
Pointer to array of phase structures.

Calls:  Functions calc_sta_mb and calc_sta_ms.

Structure members updated:
bodymag, surfmag, nsta_mb, nsta_ms in the solution structure.

Return:   0/1 for success/failure.

This function loops over all associated phases calling calc_sta_mb for each phase and calc_sta_ms for each reading.  Any station magnitudes found are averaged to give two network magnitudes, one for body waves and the other for surface waves.  These two averages are stored, along with the number of stations that contribute to them, in the solution structure for output to file or database.  If the difference between the two magnitudes is greater than the number entered in the configuration file as mag_range_warn_thresh then a warning is written to the logfile output stream.

calc_pP_resid.html010064400020000001751000000027470763662636400150050ustar00richarddev00002700000002calc_pP_resid
contents

calc_pP_resid

Called by:   calc_depdp

Includes:   iscloc.h

Input arguments:
Pointer to solution structure.
Array of phase structures.

Calls:
Function read_pP_P
add_to_error and handle_error from utils

Structure members updated:  pP_resid in phase structure.

Return:   0/1 for success/failure.

This function calculates a pP - P residual for each arrival with a phase of pP that was reported in a reading with a P phase.  It does this by calculating the difference in arrival times for the two phases and subtracting the theoretical difference returned by function read_pP_P, which looks it up in tables.  The resulting residual is stored in the phase structure as member pP_resid.
calc_resid.html010064400020000001751000000065740763662636400143500ustar00richarddev00002700000002 calc_resid
contents

calc_resid

Called by:   main each iteration and after convergence.

Includes:   iscloc.h

External: max_depth  set in read_ttime

Input arguments:
Pointer to solution structure.
Array of phase structures.
A string, mode, set to "all" if require residuals for all phases,  "use" if only want residuals that will be used in solution.

Calls:
function read_ttime
functions add_to_error and handle_error from utils

Structure members updated:  resid in phase structure.

Return:   0/1 for success/failure.

First this function checks the depth of the current solution against max_depth, a value passed as an external variable by function read_ttime for the earth model in use.  If the source depth is greater than the maximum depth allowed for by the model then no residuals can be calculated and the function returns early.

Next it loops over all associated phases and calculates residuals for those applicable.  Each iteration this function is called with mode="use" and only calculates residuals for those phases with weight_factor > 0 , i.e. those that will be used in the solution.  After convergence this function is called one last time with mode="all" and calculates residuals with respect to the final solution for all recognised phases.  For each applicable phase the observed travel time is calculated and then the model travel time and derivatives are added to the phase structure by calling function read_ttime.  The residual is calculated by subtracting the model time from the observed time and is also added to the structure.

Note:  The ultimate calculation of residuals with respect to the final solution can be confusing.  It is possible for the solution to alter sufficiently in the final iteration that it is impossible to calculate residuals for phases that were used in that final iteration.  For example, if the depth of the solution changed form above the Conrad discontinuity to below it then Pg and Sg phases that contributed to the hypocentre can not have residuals with respect to it.  In such cases a warning is written to logfile , weight_factor for the phase is set to 0 and phase to "".  The effect is that ndef will be less than it should be and the phases concerned will not be included in the calculation of sdobs or mindist .
calc_sta_mb.html010064400020000001751000000025560763662636400145030ustar00richarddev00002700000002 calc_sta_mb
contents

calc_sta_mb

Called by:  calc_netmag

Includes:   iscloc.h, bodymag_cor.h

External:
body_mag_min_dist , body_mag_max_dist , body_mag_min_per , body_mag_max_per set in read_config .

Input arguments:
Pointer to solution structure.
Pointer to phase structure.

Structure members updated:  bodymag in the phase structure.

Return:  0/1 for success/failure.

This function calculates a body wave magnitude for P phases recorded at a suitable distance with an amplitude at a suitable period.  The magnitude is calculated using a table of corrections included as bodymag_cor.h.
calc_sta_ms.html010064400020000001751000000055020763662636400145160ustar00richarddev00002700000002calc_sta_ms
contents

calc_sta_ms

Called by:  calc_netmag

Includes:   iscloc.h

External:
surf_mag_min_dist, surf_mag_max_dist, surf_mag_min_per, surf_mag_max_per set in read_config.

Input arguments:
Array of phase structures.
Array of indexes of the phase structure array making up one reading.
Number of entries in the reading array.

Structure members updated:  surfmag in the phases that contributed to it.

Return:  MS for the reading or 0 if there is none.

Note:  ISF bulletin format does not include component information so MS can not be calculated for data read in from ISF file.

This function goes through the phases of one reading and looks for amplitudes recorded at a suitable distance and with suitable periods for surface wave magnitude calculation.  If a vertical amplitude is given then MSZ is calculated and if amplitudes on both horizontal components are given at a similar period to each other then MSH is calculated.  MS for the reading is set to either MSZ or MSH or the average of the two if both are available.

Any phase with phase ="" is considered, as surface wave codes do not get mapped in id_pha .  Multiple amplitudes for one reading can either be on separate phases or attached to one phase as rows in the amplitude array a.  In either case the surfmag written to the phase structure needs to be that calculated using amplitude(s) from that phase.  Therefore if there are 3 orthogonal amplitudes for a reading then either two phases with horizontal amplitudes could have surfmag=MSH and a phase with a vertical amplitude have surfmag=MSZ or a single phase with 3 amplitudes could have surfmag=MS.  Because some phases in the reading may not have a surfmag while others do and because the MS for the reading may not be stored with any of the phases the value of MS is returned back to the calling function so that it can be used in network magnitude calculation.



calc_weight.html010064400020000001751000000041520763662636400145170ustar00richarddev00002700000002 calc_weight
contents

calc_weight

Called by:   main each iteration.

Includes:   iscloc.h

Input arguments:
Pointer to solution structure.
Array of phase structures.

Calls:
Weighting function that depends on weighting_type in the solution structure.
print_pha if diagnostic is on.

Structure members updated:
prev_alpha, prev_sigma, and sigma in  solution structure.

Return:   0/1 for success/failure.

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.html010064400020000001751000000047130763662636400155430ustar00richarddev00002700000002 change_weighting
contents

change_weighting

Called by:   main after convergence has been reached.

Includes:   iscloc.h

External:
weighting1   set in read_config
weighting2   set in read_config

Input arguments:
Pointer to solution structure.

Structure members updated:
weighting_type in solution structure.
converged  in solution structure.

Return:   0/1 for success/failure.

If a parameter weighting2 is present in config.txt then an external variable weighting2 will have been initialised in read_config.  If this is the case and weighting_type in the  solution structure is currently set to the value of weighting1 (i.e. this function has not been called before) then this function sets  weighting_type to weighting2 and converged to 0.  This has the effect of restarting the iteration process with the most recent solution as a starting point and using a different weighting function.

Note that the iteration process may be restarted after the first convergence even if no change is made to the weighting function because phases may have been purged in function purge_pha, which also updates converged in the solution structure if it does anything.  


changing_model.html010064400020000001751000000073740763662636400152150ustar00richarddev00002700000002 changing_model.html
contents

Changing the Earth Model in Use


The iscloc program is designed to make it as simple as possible to change the method employed to calculate the travel times that are compared with observed travel times to get the residuals used in solution of hypocentre locations.  Travel times themselves are returned by the function read_ttime, which calls a model specific function read_jb.  This separates residual calculation from the method used to estimate travel times and it is possible to alter read_ttime to call a different function that calculates travel times in a different way.  Any part of the program that needs to know travel times (e.g. functions calc_resid , mark_duplicates) can call read_ttime and so remain unchanged.  It would be possible to use read_ttime to check that phases are identified consistently with the model in use, but in practice it is much more efficient to use a set of simple rules to check the majority of phase identifications.  These rules are, of course, specific to the model in use and so an alternative function would have to be called to do this job if a different travel time method was required.  A similar method to that for travel times has been used to buffer the calculation of pP - P differential travel times from from the calculation of pP - P residuals and the solution of depth phase depth.

There are three functions that need to be replaced if a different earth model is used to replace Jeffreys - Bullen. These are:
The functions that call these functions will then need to be edited to call the new functions instead.  The calling functions are
In function id_pha it will also probably be necessary to alter the phase_map structure to reflect the phase names used in the model being used.  In the same way it may be necessary to change the phase_weight structure in function get_weight_factor.

In function calc_resid the maximum depth allowed by the model is required and read in from an external variable . This variable is set in function read_ttime so read_ttime must include the relevant definition.  This is conveniently done for JB by including the header file, jb_model.h,  used by the model specific functions.  Other functions that need to know some details of the model in use also include this header file.

If the model were changed then the include statements in these functions would need to be updated:
correct_ttime.html010064400020000001751000000053760763662636400151220ustar00richarddev00002700000002 correct_ttime
contents

correct_ttime

Called by:   read_ttime for each phase after getting travel time.

Includes:   iscloc.h

External:
Threshold for applying crustal correction CRUST_CORR_MIN_DELTA.
crust_corr_on and elev_corr_on set in read_config
Input arguments:
Pointer to solution structure.
Pointer to phase structure.

Calls:
calc_geoid_corr
calc_elev_corr if elev_corr_on = 1 and crust_corr_on = 0
calc_crust_corr if crust_corr_on = 1

Structure members updated:   None.

Return:   Travel time correction in seconds.

Calls functions to make corrections to the travel time for a particular phase.  In all cases will make a correction for the true shape of the Earth by calling calc_geoid_corr.  Whether any other correction is made depends on the value of two configuration values read from config.txt by read_config.

If crust_corr_on is set then function calc_crust_corr is called which replaces the effect of a constant crust from the earth model with the effect of a laterally varying crust. calc_crust_corr will also make a correction for station elevation using the appropriate crustal velocity if it is provided with an elevation value and so this function only sends such an elevation if elev_corr_on is also set.

If crust_corr_on is not set but elev_corr_on is set then function calc_elev_corr is called to correct for the elevation of the station using the upper crustal velocity from the earth model in use.

data_input.html010064400020000001751000000053410763662636400143770ustar00richarddev00002700000002 data_input
contents

Data Input


Each event structure has 5 members related to inputting data:



The iscloc program is designed to input data in one of two ways, either from an ORACLE database with the same schema as used at the ISC or form text files with events in ISF bulletin format.  The mode of input depends on the instruction line:
Because a new instruction line is read in for each event it is possible to mix database and file input as well as to read from more than one file.

The data input functions are responsible for dynamically allocating memory for the arrays of hypocentre and phase structures that they insert data into.
>contents

Data Input


Each event structure has 5 members related to inputting data: