PySeismoSoil

---

Table of Contents

• 1. Functionalities
  • 1.1. Site-response simulations
  • 1.2. Sediment velocity model (SVM)
  • 1.3. Site amplification factors
  • 1.4. Useful utilities for ground motion analysis
• 2. Copyright and license
• 3. Authors
• 4. Installation
• 5. API Documentation
• 6. Examples
• 7. Knowledge base
• 8. Report issues
• 9. How to cite this library
• 10. How to contribute to this library

---

PySeismoSoil is a Python library for performing 1D seismic site response analysis.

1. Functionalities

1.1. Site-response simulations

• Linear simulations, which assumes viscoelastic wave propagation through 1D soil profile. Suitable for very weak motions.
• Equivalent linear simulations, which updates the shear modulus and the damping to the strain the motion produces (using G/G_max and damping curves as "look up tables"), and iterates until the response and the soil properties converge. Suitable for moderate ground motions.
• Nonlinear simulations, which utilizes advanced constitutive models and propagates waves in the time domain. PySeismoSoil implements the hybrid hyperbolic (HH) model (Shi & Asimaki, 2017), which describes both the small-strain stiffness and the large-strain strength from a velocity profile alone, or the MKZ (modified Kondner and Zelasko, 1963) model.

1.2. Sediment velocity model (SVM)

Oftentimes, only the V_S30 of a site is known, rather than its detailed V_S profile.

The sediment velocity model (SVM) by Shi & Asimaki (2018) turns V_S30, and optionally the depth to V_S=1,000 m/s soil, into a one-dimensional profile for California basin sediments. It also draws randomized profiles that stay consistent with that V_S30 and basin depth, for calculations that need a suite of profiles rather than one.

1.3. Site amplification factors

A database of site amplification factors (both amplitude and phase shift), conditioned on on V_S30, basin depth (z₁), and PGA of the input ground motion. They were pre-calculated using nonlinear simulation with the HH (hybrid hyperbolic) constitutive model by Shi & Asimaki (2017).

PySeismoSoil offers functions to apply these amplification factors to input motions.

1.4. Useful utilities for ground motion analysis

• Ground motions. Read an accelerogram, baseline-correct it, filter it, and compute its response spectrum.
• Fourier spectra. Work with the amplitude and phase of a motion, including smoothing and the fundamental frequency.
• V_S profiles. Plot a profile, query V_S at a depth, and compute z₁ and the linear transfer function.
• Modulus and damping curves. Store G/G_max and damping versus strain, including curves calibrated from a V_S profile for the HH model.
• Goodness-of-fit scores. Compare a simulated motion with a recording.

2. Copyright and license

Copyright (c) 2024, California Institute of Technology, based on research supported by the National Science Foundation (NSF) Cooperative Agreement EAR-1033462 and the U.S. Geological Survey (USGS) Cooperative Agreement G12AC20038. All rights reserved.

Please carefully read the license here for the terms and conditions of using this library.

3. Authors

The authors of this library are the current and past members of the Geoquake Research Group of the California Institute of Technology: Jian Shi, Domniki Asimaki, Wei Li, and Flora Xia.

4. Installation

Install most recent stable version:

pip install PySeismoSoil

If you already have an older version installed and want to upgrade to the newest version, use pip install --upgrade PySeismoSoil.

5. API Documentation

The HTML documentation is published at https://caltech-geoquake.github.io/PySeismoSoil/.

• Utility classes
• Helper modules

6. Examples

The notebooks in examples/ walk through each piece of the library: ground motions, Vs profiles, curves, the HH calibration, linear, equivalent-linear, and nonlinear runs, batch simulations, the sediment velocity model, site factors, site-effect adjustment, and goodness-of-fit scores.

7. Knowledge base

The models and algorithms used in this library mainly come from these research papers:

1. J. Shi (2019) "Improving Site Response Analysis for Earthquake Ground Motion Modeling." Dissertation (Ph.D.), California Institute of Technology. doi:10.7907/X5NZ-DQ21. [URL]

2. J. Shi, D. Asimaki (2018) "A Generic Velocity Profile for Basin Sediments in California Conditioned on Vs30." Seismological Research Letters, 89 (4), 1397-1409. [URL]

3. J. Shi, D. Asimaki (2017) "From stiffness to strength: Formulation and validation of a hybrid hyperbolic nonlinear soil model for site-response analyses." Bulletin of the Seismological Society of America, 107 (3), 1336-1355. [URL]

4. W. Li, D. Assimaki (2010) "Site- and motion-dependent parametric uncertainty of site-response analyses in earthquake simulations." Bulletin of the Seismological Society of America, 100 (3), 954-968. [URL]

5. D. Asimaki, W. Li, J. Steidl, J. Schmedes (2008) "Quantifying nonlinearity susceptibility via site-response modeling uncertainty at three sites in the Los Angeles Basin." Bulletin of the Seismological Society of America, 98 (5), 2364-2390. [URL]

8. Report issues

To report bugs and submit suggestions, please use the "Issues" section of this GitHub repository.

9. How to cite this library

To cite this library, please include this DOI in your publication: .

10. How to contribute to this library

Please read the contributing instructions to get started.