pygmm Documentation Release Albert Kottke

Transcription

1 pygmm Documentation Release Albert Kottke March 16, 2016

2

3 Contents 1 pygmm Features Credits Installation Linux Windows and OS-X Installing pygmm Usage 7 4 Ground motion models Generic Interface Specific Models Contributing Types of Contributions Get Started! Pull Request Guidelines Tips Credits Development Lead Contributors History ( ) References 25 9 Indices and tables 27 Bibliography 29 Python Module Index 31 i

4 ii

5 Contents: Contents 1

6 2 Contents

7 CHAPTER 1 pygmm Ground motion models implemented in Python. Free software: MIT license Documentation: Features Models currently supported: Atkinson & Boore (2006) Abrahamson, Silva, & Kamai (2014) with unit tests Boore, Stewart, Seyhan, & Atkinson (2014) with unit tests Campbell (2003) Campbell & Bozorgnia (2014) with unit tests Chiou & Youngs (2014) with unit tests Idriss (2014) with unit tests Pezeshk, Zandieh, & Tavakoli (2001) Tavakoli & Pezeshk (2005) 1.2 Credits This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template. 3

8 4 Chapter 1. pygmm

9 CHAPTER 2 Installation Prior to using pygmm, Python and the following dependencies need to be installed: matplotlib used for plotting numpy fast vector operations pygmm supports both Python 2.7 and Python Linux Install pygmm dependencies is best accomplished with a package manager. On Arch Linux this can be accomplished with: pacman -S python-numpy python-matplotlib pip 2.2 Windows and OS-X On Windows, installing matplotlib and numpy can be simplified by using Miniconda3. Miniconda3 has installers for Windows 32-bit, Windows 64-bit, and OS-X. After the installer is finished, install the required dependencies by opening a terminal. On Windows, this is best accomplished with Windows Key + r, enter cmd. Next enter the following command: conda install --yes pip setuptools numpy matplotlib On Windows, the text can copied and pasted if Quick Edit mode is enabled. To enable this feature, right click on the icon in the upper left portion of the window, and select Properties, and then check the Quick Edit Mode check box within the Edit Options group. Copy the text, and then paste it by click the right mouse button. 2.3 Installing pygmm After the dependencies have been installed, install or upgrade pygmm using pip: pip install --upgrade pygmm This command can be re-run later to upgrade pygmm to the latest version. 5

10 6 Chapter 2. Installation

11 CHAPTER 3 Usage pygmm is used within Python scripts. Here is a simple example of plotting the influence of V s30 on the Chiou & Youngs (2014) [2] model: #!/usr/bin/env python # -*- coding: utf-8 -*- """Plot influence of V_s30 predicted by CY14 model.""" import matplotlib.pyplot as plt import pygmm fig, ax = plt.subplots() for v_s30 in [300, 600, 900]: m = pygmm.chiouyoungs2014( mag=7, dist_jb=20, dist_x=20, dist_rup=25, dip=90, v_s30=v_s30) ax.plot(m.periods, m.spec_accels, label=str(v_s30)) ax.set_xlabel('period (s)') ax.set_xscale('log') ax.set_ylabel('5%-damped Spectral Accel. (g)') ax.set_yscale('log') ax.grid() ax.legend(title='$v_{s30}$ (m/s)') plt.show() 7

12 5%-Damped Spectral Accel. (g) V s30 (m/s) Period (s) 8 Chapter 3. Usage

13 CHAPTER 4 Ground motion models This part of the documentation covers all the interfaces of pygmm. 4.1 Generic Interface The interfaces for models have been simplified to use same parameter names and values where possible. Abbreviation u ss ns rs Name Unspecified Strike-slip Normal slip Reverse slip All model share the following interface: class pygmm.model.model(**kwds) Abstract class for ground motion prediction models. Compute the response predicted the model. No default implementation. interp_ln_stds(periods) Return the logarithmic standard deviation (σ ln ) of spectral acceleration at the provided damping at specified periods. Parameters period (numpy.array) periods of interest (sec). Returns numpy.array pseudo-spectral accelerations. interp_spec_accels(periods) Return the pseudo-spectral acceleration at the provided damping at specified periods. Parameters period (numpy.array) periods of interest (sec). Returns pseudo-spectral accelerations. Return type (numpy.array) ln_std_pga Logarithmic standard deviation (σ ln ) of the peak ground acceleration computed by the model. Returns float Raises NotImplementedError If model does not provide an estimate. 9

14 ln_std_pgd Logarithmic standard deviation (σ ln ) of the peak ground displacement computed by the model. Returns float Raises NotImplementedError If model does not provide an estimate. ln_std_pgv Logarithmic standard deviation (σ ln ) of the peak ground velocity computed by the model. Returns float Raises NotImplementedError If model does not provide an estimate. ln_stds Logarithmic standard deviation of the pseudo-spectral accelerations. Returns numpy.array periods Periods specified by the model. Returns numpy.array pga Peak ground acceleration (PGA) computed by the model (g). Returns float Raises NotImplementedError If model does not provide an estimate. pgd Peak ground displacement (PGD) computed by the model (cm). Returns float Raises NotImplementedError If model does not provide an estimate. pgv Peak ground velocity (PGV) computed by the model (cm/sec). Returns float Raises NotImplementedError If model does not provide an estimate. spec_accels Pseudo-spectral accelerations computed by the model (g). Returns numpy.array 4.2 Specific Models class pygmm.abrahamsonsilvakamai2014(**kwds) The Abrahamson, Silva, and Kamai (2014) [1] ground motion model for active tectonic regions. init (**kwds) Initialize the model. Keyword Arguments depth_1_0 (Optional[float]) depth to the 1.0 kms shear-wave velocity horizon beneath the site, Z 1.0 in (km). Used to estimate depth_2_5. 10 Chapter 4. Ground motion models

15 depth_2_5 (Optional[float]) depth to the 2.5 kms shear-wave velocity horizon beneath the site, Z 2.5 in (km). If None, then it is computed from depth_1_0 or v_s30 and the region parameter. depth_tor (Optional[float]) depth to the top of the rupture plane (Z tor, km). If None, then the average model is used. depth_bor (Optional[float]) depth to the bottom of the rupture plane (Z bor, km). If None, then the average model is used. dip (float) fault dip angle (φ, deg). dist_jb (float) Joyner-Boore distance to the rupture plane (R JB, km) dist_rup (float) closest distance to the rupture plane (R rup, km) dist_x (float) site coordinate measured perpendicular to the fault strike from the fault line with the down-dip direction being positive (R x, km). dist_y0 (Optional[float]) the horizontal distance off the end of the rupture measured parallel to strike (R y0, km). mag (float) moment magnitude of the event (M w ) mechanism (str) fault mechanism. Valid options: SS, NS, RS. on_hanging_wall (Optional[bool]) If the site is located on the hanging wall of the fault. If None, then False is assumed. region (Optional[str]) region. Valid options: global, california, china, italy, japan, taiwan. If None, then global is used as a default value. v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). vs_source (Optional[str]) source of the v_s30 value. Valid options: measured, inferred width (Optional[float]) Down-dip width of the fault. If None, then the model average is used. static calc_depth_1_0(v_s30, region= california ) Estimate the depth to 1 km/sec horizon (Z 1.0 ) based on V s30 and region. This is based on equations 18 and 19 in the [1] and differs from the equations in the [2]. Parameters v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). Keyword Arguments region (Optional[str]) region of basin model. Valid options: california, japan. If None, then california is used as the default value. Returns depth to a shear-wave velocity of 1,000 m/sec (Z 1.0, km). Return type float static calc_depth_tor(mag) Calculate the depth to top of rupture (km). Parameters mag (float) moment magnitude of the event (M w ) Returns estimated depth (km) Return type float 4.2. Specific Models 11

16 static calc_width(mag, dip) Compute the fault width based on equation in NGW2 spreadsheet. This equation is not provided in the paper. Parameters mag (float) moment magnitude of the event (M w ) dip (float) Fault dip angle (φ, deg) Returns estimated fault width (W, km) Return type float class pygmm.atkinsonboore2006(**kwds) Atkinson and Boore (2006) [3] ground motion prediction model. Developed for the Eastern North America with a reference velocity of 760 or 2000 m/s. init (**kwds) Initialize the model. Parameters mag (float) moment magnitude of the event (M w ) dist_rup (float) Closest distance to the rupture plane (R rup, km) v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). class pygmm.boorestewartseyhanatkinson2014(**kwds) Boore, Stewart, Seyhan, and Atkinson (2014) [4] ground motion model. Developed for the California and other active tectonic environments. The BSSA14 model defines the following distance attenuation models: Name global china_turkey italy_japan Description Global; California and Taiwan China and Turkey Italy and Japan and the following basin region models: Name global japan Description Global / California Japan These are simplified into one regional parameter with the following possibilities: Region Attenuation Basin global global global california global global china china_turkey global italy italy_japan global japan italy_japan japan new zealand italy_japan global taiwan global global turkey china_turkey global init (**kwds) Compute the response predicted the Boore, Stewart, Seyhan, and Atkinson (2014) ground motion model. 12 Chapter 4. Ground motion models

17 Keyword Arguments mag (float) moment magnitude of the event (M w ) depth_1_0 (Optional[float]) depth to the 1.0 kms shear-wave velocity horizon beneath the site, Z 1.0 in (km). If None is specified, then no adjustment is applied. dist_jb (float) Joyner-Boore distance to the rupture plane (R JB, km) v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). mechanism (str) fault mechanism. Valid options: U, SS, NS, RS region (Optional[str]) region for distance attenuation and basin model. Valid options: global, california, china, italy, japan, new_zealand, taiwan, turkey. If None is specified, then global is used as default. class pygmm.campbell2003(**kwds) Campbell (2003) [5] ground motion model for Eastern US. init (**kwds) Initialize the ground motion model. Keyword Arguments mag (float) moment magnitude of the event (M w ) dist_rup (float) closest distance to the rupture plane (R rup, km) class pygmm.campbellbozorgnia2014(**kwds) Campbell and Bozorgnia (2014) [6] ground motion model for active tectonic regions. init (**kwds) Compute the response predicted the Campbell and Bozorgnia (2014) ground motion model. Keyword Arguments depth_1_0 (Optional[float]) depth to the 1.0 kms shear-wave velocity horizon beneath the site, Z 1.0 in (km). Used to estimate depth_2_5. depth_2_5 (Optional[float]) depth to the 2.5 kms shear-wave velocity horizon beneath the site, Z 2.5 in (km). If None, then it is computed from depth_1_0 or v_s30 and the region parameter. depth_tor (Optional[float]) depth to the top of the rupture plane (Z tor, km). If None, then the average model is used. depth_bor (Optional[float]) depth to the bottom of the rupture plane (Z bor, km). If None, then the average model is used. depth_bot (Optional[float]) depth to bottom of seismogenic crust (km). Used to calculate fault width if none is specified. If None, then a value of 15 km is used. depth_hyp (Optional[float]) depth of the hypocenter (km). If None, then the model average is used. dip (float) fault dip angle (φ, deg). dist_jb (float) Joyner-Boore distance to the rupture plane (R JB, km) dist_rup (float) closest distance to the rupture plane (R rup, km) dist_x (float) site coordinate measured perpendicular to the fault strike from the fault line with the down-dip direction being positive (R x, km). mag (float) moment magnitude of the event (M w ) 4.2. Specific Models 13

18 mechanism (str) fault mechanism. Valid values: SS, NS, RS. region (Optional[str]) region. Valid values: california, china, italy, japan. If None, then california is used as a default value. v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). width (Optional[float]) Down-dip width of the fault. If None, then the model average is used. static calc_depth_2_5(v_s30, region= global, depth_1_0=none) Calculate the depth to a shear-wave velocity of 2.5 km/sec (Z 2.5 ). Provide either v_s30 or depth_1_0. Parameters v_s30 (Optional[float]) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). Keyword Arguments region (Optional[str]) region of the basin model. Valid values: california, japan. depth_1_0 (Optional[float]) depth to the 1.0 kms shear-wave velocity horizon beneath the site, Z 1.0 in (km). Returns estimated depth to a shear-wave velocity of 2.5 km/sec (km). Return type float static calc_depth_bor(depth_tor, dip, width) Compute the depth to bottom of the rupture (km). Parameters dip (float) fault dip angle (φ, deg). depth_tor (float) depth to the top of the rupture plane (Z tor, km). width (float) Down-dip width of the fault. Returns depth to bottom of the fault rupture (km) Return type float static calc_depth_hyp(mag, dip, depth_tor, depth_bor) Estimate the depth to hypocenter. Parameters mag (float) moment magnitude of the event (M w ) dip (float) fault dip angle (φ, deg). depth_tor (float) depth to the top of the rupture plane (Z tor, km). depth_bor (float) depth to the bottom of the rupture plane (Z bor, km). Returns estimated hypocenter depth (km) Return type float static calc_width(mag, dip, depth_tor, depth_bot=15.0) Estimate the fault width using Equation (39) of CB14. Parameters mag (float) moment magnitude of the event (M w ) dip (float) fault dip angle (φ, deg). 14 Chapter 4. Ground motion models

19 depth_tor (float) depth to the top of the rupture plane (Z tor, km). Keyword Arguments depth_bot (Optional[float]) depth to bottom of seismogenic crust (km). Used to calculate fault width if none is specified. If None, then a value of 15 km is used. Returns estimated fault width (km) Return type float class pygmm.chiouyoungs2014(**kwds) Chiou and Youngs (2014) [2] model. init (**kwds) Compute the response predicted the Chiou and Youngs (2014) ground motion model. Keyword Arguments depth_1_0 (Optional[float]) depth to the 1.0 kms shear-wave velocity horizon beneath the site, Z 1.0 in (km). Used to estimate depth_2_5. depth_tor (Optional[float]) depth to the top of the rupture plane (Z tor, km). If None, then the average model is used. dist_jb (float) Joyner-Boore distance to the rupture plane (R JB, km) dist_rup (float) closest distance to the rupture plane (R rup, km) dist_x (float) site coordinate measured perpendicular to the fault strike from the fault line with the down-dip direction being positive (R x, km). dip (float) fault dip angle (φ, deg). dpp_centered (Optional[float]) direct point parameter for directivity effect (see Chiou and Spudich (2014)) centered on the earthquake-specific average DPP for California. If None, then value of 0 used to provide the average directivity. mag (float) moment magnitude of the event (M w ) mechanism (str) fault mechanism. Valid options: U, SS, NS, RS. on_hanging_wall (Optional[bool]) If the site is located on the hanging wall of the fault. If None, then False is assumed. region (Optional[str]) region. Valid options: california, china, italy, japan. If None, then california is used as a default value. v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). vs_source (Optional[str]) source of the v_s30 value. Valid options: measured, inferred static calc_depth_1_0(v_s30, region) Calculate an estimate of the depth to 1 km/sec (Z 1.0 ) based on V s30 and region. Parameters v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). region (str) basin region. Valid options: california, japan Returns estimated depth to a shear-wave velocity of 1 km/sec (km) Return type float static calc_depth_tor(mag, mechanism) Calculate an estimate of the depth to top of rupture (km) Specific Models 15

20 Parameters mag (float) moment magnitude of the event (M w ) mechanism (str) fault mechanism. Valid options: U, SS, NS, RS. Returns estimated depth to top of rupture (km) Return type float class pygmm.idriss2014(**kwds) Idriss (2014) [7] ground motion model. init (**kwds) Initialize the ground motion model. Keyword Arguments dist_rup (float) Closest distance to the rupture plane (R rup, km) mag (float) moment magnitude of the event (M w ) mechanism (str) fault mechanism. Valid options: SS, NS, RS. SS and NS mechanism are treated the same with F = 0 in the model. v_s30 (float) time-averaged shear-wave velocity over the top 30 m of the site (V s30, m/s). class pygmm.pezeshkzandiehtavakoli2011(**kwds) Pezeshk, Zandieh, and Tavakoli (2011) [8] ground motion prediction model. Developed for the Eastern North America with a reference velocity of 2000 m/s. init (**kwds) Initialize the model. Keyword Arguments mag (float) moment magnitude of the event (M w ) dist_rup (float) Closest distance to the rupture plane (R rup, km) class pygmm.tavakolipezeshk05(**kwds) Tavakoli and Pezeshk (2005) [9] ground motion prediction model. Developed for the Eastern North America with a reference velocity of 2880 m/s. init (**kwds) Initialize the model. Keyword Arguments mag (float) moment magnitude of the event (M w ) dist_rup (float) Closest distance to the rupture plane (R rup, km) 16 Chapter 4. Ground motion models

21 CHAPTER 5 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: 5.1 Types of Contributions Report Bugs Report bugs at If you are reporting a bug, please include: Your operating system name and version. Any details about your local setup that might be helpful in troubleshooting. Detailed steps to reproduce the bug Fix Bugs Look through the GitHub issues for bugs. Anything tagged with bug is open to whoever wants to implement it Implement Features Look through the GitHub issues for features. Anything tagged with feature is open to whoever wants to implement it Write Documentation pygmm could always use more documentation, whether as part of the official pygmm docs, in docstrings, or even on the web in blog posts, articles, and such Submit Feedback The best way to send feedback is to file an issue at If you are proposing a feature: 17

22 Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Remember that this is a volunteer-driven project, and that contributions are welcome :) 5.2 Get Started! Ready to contribute? Here s how to set up pygmm for local development. 1. Fork the pygmm repo on GitHub. 2. Clone your fork locally: $ git clone git@github.com:your_name_here/pygmm.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv pygmm $ cd pygmm/ $ python setup.py develop 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 pygmm tests $ python setup.py test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: $ git add. $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. 5.3 Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check and make sure that the tests pass for all supported Python versions. 18 Chapter 5. Contributing

23 5.4 Tips To run a subset of tests: $ python -m unittest tests.test_pygmm 5.4. Tips 19

24 20 Chapter 5. Contributing

25 CHAPTER 6 Credits 6.1 Development Lead Albert Kottke <albert.kottke@gmail.com> 6.2 Contributors None yet. Why not be the first? 21

26 22 Chapter 6. Credits

27 CHAPTER 7 History ( ) First release on PyPI. 23

28 24 Chapter 7. History

29 CHAPTER 8 References 25

30 26 Chapter 8. References

31 CHAPTER 9 Indices and tables genindex modindex search 27

32 28 Chapter 9. Indices and tables

33 Bibliography [1] Norman A Abrahamson, Walter J Silva, and Ronnie Kamai. Summary of the ASK14 ground motion relation for active crustal regions. Earthquake Spectra, 30(3): , [2] Brian S-J Chiou and Robert R Youngs. Update of the chiou and youngs NGA model for the average horizontal component of peak ground motion and response spectra. Earthquake Spectra, 30(3): , [3] Gail M Atkinson and David M Boore. Earthquake ground-motion prediction equations for eastern North America. Bulletin of the Seismological Society of America, 96(6): , [4] David M Boore, Jonathan P Stewart, Emel Seyhan, and Gail M Atkinson. NGA-West2 equations for predicting pga, pgv, and 5\% damped psa for shallow crustal earthquakes. Earthquake Spectra, 30(3): , [5] Kenneth W Campbell. Prediction of strong ground motion using the hybrid empirical method and its use in the development of ground-motion (attenuation) relations in eastern North America. Bulletin of the Seismological Society of America, 93(3): , [6] Kenneth W Campbell and Yousef Bozorgnia. NGA-West2 ground motion model for the average horizontal components of pga, pgv, and 5\% damped linear acceleration response spectra. Earthquake Spectra, 30(3): , [7] IM Idriss. An NGA-West2 empirical model for estimating the horizontal spectral values generated by shallow crustal earthquakes. Earthquake Spectra, 30(3): , [8] Shahram Pezeshk, Arash Zandieh, and Behrooz Tavakoli. Hybrid empirical ground-motion prediction equations for eastern North America using NGA models and updated seismological parameters. Bulletin of the Seismological Society of America, 101(4): , [9] Behrooz Tavakoli and Shahram Pezeshk. Empirical-stochastic ground-motion prediction for eastern North America. Bulletin of the Seismological Society of America, 95(6): ,

34 30 Bibliography

35 Python Module Index p pygmm, 10 31

36 32 Python Module Index

37 Index Symbols init () (pygmm.abrahamsonsilvakamai2014 method), 10 init () (pygmm.atkinsonboore2006 method), 12 init () (pygmm.boorestewartseyhanatkinson2014 method), 12 init () (pygmm.campbell2003 method), 13 init () (pygmm.campbellbozorgnia2014 method), 13 init () (pygmm.chiouyoungs2014 method), 15 init () (pygmm.idriss2014 method), 16 init () (pygmm.pezeshkzandiehtavakoli2011 method), 16 init () (pygmm.tavakolipezeshk05 method), 16 A AbrahamsonSilvaKamai2014 (class in pygmm), 10 AtkinsonBoore2006 (class in pygmm), 12 B BooreStewartSeyhanAtkinson2014 (class in pygmm), 12 C calc_depth_1_0() (pygmm.abrahamsonsilvakamai2014 static method), 11 calc_depth_1_0() (pygmm.chiouyoungs2014 static method), 15 calc_depth_2_5() (pygmm.campbellbozorgnia2014 static method), 14 calc_depth_bor() (pygmm.campbellbozorgnia2014 static method), 14 calc_depth_hyp() (pygmm.campbellbozorgnia2014 static method), 14 calc_depth_tor() (pygmm.abrahamsonsilvakamai2014 static method), 11 calc_depth_tor() (pygmm.chiouyoungs2014 static method), 15 calc_width() (pygmm.abrahamsonsilvakamai2014 static method), 11 calc_width() (pygmm.campbellbozorgnia2014 static method), 14 Campbell2003 (class in pygmm), 13 CampbellBozorgnia2014 (class in pygmm), 13 ChiouYoungs2014 (class in pygmm), 15 I Idriss2014 (class in pygmm), 16 interp_ln_stds() (pygmm.model.model method), 9 interp_spec_accels() (pygmm.model.model method), 9 L ln_std_pga (pygmm.model.model attribute), 9 ln_std_pgd (pygmm.model.model attribute), 9 ln_std_pgv (pygmm.model.model attribute), 10 ln_stds (pygmm.model.model attribute), 10 M Model (class in pygmm.model), 9 P periods (pygmm.model.model attribute), 10 PezeshkZandiehTavakoli2011 (class in pygmm), 16 pga (pygmm.model.model attribute), 10 pgd (pygmm.model.model attribute), 10 pgv (pygmm.model.model attribute), 10 pygmm (module), 10 S spec_accels (pygmm.model.model attribute), 10 T TavakoliPezeshk05 (class in pygmm), 16 33