Program notes on CHEEP (version 1.0)
by
John Douglas[1],
Department of Civil & Environmental Engineering,
Imperial College London,
South Kensington Campus,
London,
SW7 2AZ,
United Kingdom.
Hilmar Bungum (),
NORSAR,
POB 53,
N-2027 Kjeller,
Norway.
Frank Scherbaum (),
Inst. Geowissenshcaften,
Universität Potsdam,
P.O. Box 601553,
D-14415,
Potsdam,
Germany
Introduction
This user manual describes the structure and use of the FORTRAN program, CHEEP, developed for the article ‘Ground-motion prediction equations for southern Spain and southern Norway obtained using the composite model perspective’ by Douglas et al. (2005). The purpose of this program is to allow the user to implement the procedure described in ‘Composite ground-motion models and logic trees: methodology, sensitivities, and uncertainties’ by Scherbaum et al. (2005a) for their own target region. This program was used to compute the composite models derived by Douglas et al. (2005) for southern Spain and southern Norway.
The program computes a composite ground motion model for rock sites by first computing ground motions estimated via a number of commonly-used equations having first converted the user-specified magnitude and distance into the magnitude scale and distance metric required by the equation. This conversion is performed using a Monte Carlo simulation that retains the scatter introduced by undertaking these conversions. Then these estimates are scaled to account for differences in the method for combining the two horizontal components and for the required style-of-faulting. These estimated ground motions are then scaled using the ratio of the estimated host-to-target conversion factors derived using the stochastic method as implement in SMSIM (Boore, 2003). In addition the converted aleatory uncertainties are computed. The program can compute composite models for a range of magnitude and distances in order to cover the magnitude-distance space of interest.
We place the CHEEP code that we have written in the public domain.
Disclaimer
We provide absolutely no warranty of any kind either expressed or implied, including but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should this program prove defective, you assume the cost of all necessary servicing, repair or correction.
In no event shall Imperial College of Science, Technology and Medicine, NORSAR or Universität Potsdam (or BRGM) or any of their component institutions be liable to you for damages, including any lost profits, lost monies, or other special, incidental or consequential damages arising out of the use or inability to use (including but not limited to loss of data or its analysis being rendered inaccurate or losses sustained by third parties) the program.
(Above NO WARRANTY modified from the RANDLIB NO WARRANTY statement.)
Compiling and running program
The main CHEEP Fortran file is called cheep.f. This contains the main subroutine, the subroutine for making the conversions (conver), the subroutine for the interpolation of the ground motion prediction equations’ coefficients (linint), the subroutine for the branching in the logic tree (branch) and the subroutines for each of the ground motion prediction equations (see below).
For making the host-to-target conversions based on the stochastic method modified versions of SMSIM (Boore, 2003) files were used. The subroutines used are: rvsmsim_sub.f (which is a modified version of tmrdrvrr.for), sasmsim_sub.f (which is a modified version of site_amp.for), rv_subs.for (which is unmodified) and rvtdsubs.for (which is rvtdsubs.for with the addition of a subroutines get_params_single and get_params_cheep, which are modified versions of get_params). We thank Dr D. M. Boore for giving us permission to disseminate these modified subroutines.
To compute the host-to-target conversion factors the program uses the random vibration theory part of SMSIM (Boore, 2003), which uses a number of subroutines (or slightly modified subroutines) from the book Numerical Recipes in Fortran (Press et al., 1992). The subroutines required are: qromb.f, trapzd.f, polint.f, locate.f, odeint.f, rkqs.f and rkck.f. These subroutines cannot be supplied with this program because they are covered by copyright. Therefore they must be obtained from elsewhere and then modified in the way mentioned in the SMSIM documentation.
The Monte Carlo procedure adopted requires the computation of random numbers coming from a number of different distributions. These random numbers are generating using subroutines from the randlib library (Brown et al., 1997). The subroutines required are: gennor.f, genunf.f, gengam.f, sgamma.f, sexpo.f, snorm.f, ranf.f, ignlgi.f, qrgnin.f, inrgcm.f, setall.f, getcgn.f, mltmod.f and initgn.f.
The programs can be compiled using the provided Makefile and then run by executing the cheep executable. Compilation has been tested using Sun and GNU Fortran compilers (f77 and g77) and it has been run on Sun workstations and a Linux cluster.
Outline of procedure followed in program
Required input files
Input file containing run-time parameters
The input file called input.dat contains the run-time parameters including the target regions parameters. This should be placed in the directory containing the program (this can be changed by modifying the cheep.f program). The lines of the input file are:
Line no. / Parameter / Format1 / Stem of output filename / A
2 / Directory where coefficient and host SMSIM files are / A
3 / Name of input file for SMSIM parameters of target region / A
4 / Name of input file containing representative shear-wave velocity profile for target region / A
5 / Name of input file containing coefficients for distance conversion / A
6 / Depth to top of seismogenic layer for use in the conversion to hypocentral distance / F4.1
7 / Total number of samples generated / I5
8 / Number of periods at which to compute ground motions (nT) / I3
9 / First period at which ground motion is predicted / F4.2
... / nth period at which ground motion is predicted / F4.2
8+nT / Last period at which ground motion is predicted / F4.2
9+nT / Magnitude scale used for target region (Ms for surface-wave magnitude, Mw for moment magnitude) / A2
10+nT / Minimum magnitude at which to compute ground motions / F4.2
11+nT / Maximum magnitude at which to compute ground motions / F4.2
12+nT / Magnitude step between minimum and magnitude magnitude at which to compute ground motions / F4.2
13+nT / Mechanism for which to compute ground motions (N for normal, S for strike-slip and R for reverse) / A1
14+nT / Distance metric used for target region (de for epicentral distance, df for distance to surface projection of rupture, dh for hypocentral distance, dr for rupture distance and ds is seismogenic distance) / A2
15+nT / Number of distances at which to compute ground motions (nd) / I3
16+nT / First distance at which to compute ground motions / F5.1
... / nth distance at which to compute ground motions / F5.1
15+nT+nd / Last distance at which to compute ground motions / F5.1
16+nT+nd / Method used to combine horizontal components in target region (bo for both components, gm for geometric mean, le for larger envelope, lp for larger PGA) / A2
Input files containing coefficients of equations
A number of files are required for the computation of the predicted ground motions given by the different ground motion prediction equations. These files contain the coefficients of the equations at each of the periods or frequencies specified by the authors of the equation. These files are:
Equation / FilesAbrahamson & Silva (1997) / cas97h.txt
Ambraseys & Douglas (2003) / cad03h.txt
Ambraseys et al. (1996) / caetal96h.txt
Atkinson & Boore (1997) / cab97h.txt
Berge-Thierry et al. (2003) / cbtetal03h.txt
Boore et al. (1997) / cbetal97h.txt
Campbell (1997) / cc97h.txt
Campbell & Bozorgnia (2003a,b) / ccb03h.txt
Lussou et al. (2001) / cletal01h.txt
Sabetta & Pugliese (1996) / csp96h.txt
Sadigh et al. (1997) / csetal97h1.txt and csetal97h2.txt
Somerville et al. (2001) / csetal01nrh.txt and csetal01hnru.txt
Spudich et al. (1999) / csetal99h.txt
Toro et al. (1997) / ctetal97hmmw.txt, ctetal97hmdaummw.txt and ctetal97hddaum.txt
The factors required for the conversion between ground motions predicted using different methods for combining the horizontal components and those required for the conversion for style-of-faulting are contained within data statements in the conver subroutine and were taken from Bommer et al. (2005) and Bommer et al. (2003), respectively.
All these files should be stored in a single directory specified in the input.dat file.
Input files containing parameters for SMSIM calculation
A number of files are required for the computation of the estimated ground motions, using SMSIM, for the host regions associated with the different ground motion prediction equations. These files were computed by Scherbaum et al. (2005b) and contain the 100 best-fitting models. These models are sampled randomly by CHEEP. Because Scherbaum et al. (2005b) found that hypocentral distance generally gave the best match between the stochastic and empirical estimates for the host regions these were used here. These files are listed below.
Equation / FileAbrahamson & Silva (1997) / Abrahamson & Silva 1997_RHYP.txt
Ambraseys & Douglas (2003) / Ambraseys & Douglas 2003_RHYP.txt
Ambraseys et al. (1996) / Ambraseys et al. 1996_RHYP.txt
Atkinson & Boore (1997) / Atkinson & Boore 1997_RHYP.txt
Berge-Thierry et al. (2003) / Berge-Thierry et al. 2000_RHYP.txt
Boore et al. (1997) / Boore et al. 1997_RHYP.txt
Campbell & Bozorgnia (2003a,b) / Campbell & Bozorgnia 2002_RHYP.txt
Lussou et al. (2001) / Lussou et al. 2001_RHYP.txt
Sabetta & Pugliese (1996) / Sabetta & Pugliese 1996_RHYP.txt
Spudich et al. (1999) / SEA 99_RHYP.txt
Toro et al. (1997) / Toro et al. 1997_RHYP.txt
All these files should be stored in the same directory as the coefficient files. A file called smsimchost.dat, which holds the parameters for SMSIM that are common for all of the host equations is also required.
Input files containing parameters for local site amplification calculation
A number of files are required for the computation of the local site amplifcation factors, using site_amp from SMSIM, for the host regions associated with the different ground motion prediction equations. They correspond to generic site models based on the Vs,30 estimates for the host region. They are taken from Cotton et al. (2005). These files contain the required parameters for making such simulations in the format required by the modified site_amp subroutine. These files are: VS30_1000.vmod, VS30_1100.vmod, VS30_1200.vmod, VS30_1300.vmod, VS30_1400.vmod, VS30_1500.vmod, VS30_2000.vmod, VS30_2284.26.vmod, VS30_2600.vmod, VS30_2800.vmod, VS30_3000.vmod, VS30_350.vmod, VS30_400.vmod, VS30_450.vmod, VS30_500.vmod, VS30_550.vmod, VS30_600.vmod, VS30_620.vmod, VS30_650.vmod, VS30_700.vmod, VS30_750.vmod, VS30_800.vmod, VS30_850.vmod, VS30_900.vmod, VS30_950.vmod, where the number after the _ corresponds to the Vs,30 value.
All these files should be stored in the same directory as the coefficient files.
Output file
Output is sent to the file specified in the input file with the period (first four integers generated from the period at which computation is performed), magnitude (next three integers) and distance (next three integers) bin numbers appended to the end and with extension .dat. Therefore the output files have name such as t0100001002.dat for a computation for T=0.100s and for the first magnitude and the second distance. The generated output file has two header lines. The first line gives the target parameters (T, magnitude scale, magnitude, distance metric, distance, combination of components, mechanism, the name of the target SMSIM input file and the name of the shear-wave velocity profile input file) and the total number of samples generated. The second line gives the labels of the following lines. For each sample an output line is generated with 21 numbers (equation number, magnitude in scale appropriate for equation, distance in metric appropriate for equation, style-of-faulting factor applied, the index of the logic tree branch followed for FR:SS, the index of the logic tree branch followed for FN:SS, the component combination factor applied, the branch of logic tree branch followed for the component combination factor (-9 means no correction needed), the number of the stochastic model used for the host equation [see files from Scherbaum et al. (2005b)], the estimated ground motion in the host region using the stochastic method, the estimated ground motion in the target region using the stochastic method, the host-to-target factor from SMSIM, the number of the branch used for the source spectrum type, the number of the branch used for the stress drop, the number of the branch used for the geometrical spreading function, the number of the branch used for the path attenuation, the number of the branch used for the path duration, the number of the branch used for the site diminution, the estimated ground motion using the equation and no correction factors (except those for distance and magnitude), estimated ground motion for the target having applied all correction factors) and the aleatory uncertainty for the empirical estimate for the host region (sigma from host equation).
Adding new equations
To add new equations to the program a number of minor changes need to be made. Firstly, the variable numeq needs to be increased to equal to the new number of equations. Secondly, a new else if block of the form:
else if(eqno.eq.15) then
call xyz03(cdir,T(l),M,d,epsilon,pn,pr,eqorss,mag,comp,dis,host,yorig,sigma)
needs to be added within the first if ... end if block in the main loop of the program. Thirdly, another else if block of the form:
else if(eqno.eq.15) then
call xyz03 (cdir,T(l),Mconv,dconv,epsilon,pn,pr,eqorss,mag,comp,dis,host,y,sigma)
needs to be added within the second if ... end if block in the main loop of the program. A subroutine for computation of the predicted ground motion in terms of spectral acceleration and m/s2 given by the equation xyz03 needs to be added to the program. This subroutine should be based on the subroutines included for the inbuilt equations. It is recommended that the coefficients of the ground motion prediction equation are given in an ASCII file in the same directory as the other coefficient files. A parameter file in the format required by CHEEP (see files like Abrahamson & Silva 1997_RHYP.txt) needs to be created for the stochastic simulation required for the host-to-target conversion (note that shear-wave velocity profiles for the host region must be specified by their value of Vs,30 and in the same format as those currently used by CHEEP). These file must be in the same directory as the coefficient files and their names need to be specified in the equation subroutine (host for the SMSIM parameters).
Changing style-of-faulting factors
The factors used for converting between ground motions predicted for earthquakes with different styles-of-faulting are taken from Bommer et al. (2003) who have taken their average factor FR:SS from Boore et al. (1997) and the upper and lower factors are the average factors ±10%. The factor FN:SS is 0.95 for all periods and the upper and lower factors are 1.00 and 0.90 respectively. These factors are specified in the series of seven data statements at the top of the subroutine conver. Tgiven specifies the periods at which the factors are given (these periods should be monotonic increasing), frssu, frssa and fnssl give the upper, average and lower FN:SS estimates respectively. These data statements can be changed if different factors are required.