Working with Ground Motions

Ground motions are the input to site response analysis, representing the seismic excitation at the base of the soil profile. PyStrata supports several motion types and formats to accommodate different analysis workflows.

Motion Types

PyStrata provides several motion classes for different types of seismic input:

Time Series Motions

Direct representation of ground motion as acceleration, velocity, or displacement time series

Random Vibration Theory (RVT) Motions

Frequency-domain representation using Fourier amplitude spectra and duration

Source-Based Motions

Theoretical motions generated from earthquake source parameters

Time Series Motions

The most common input format is acceleration time series from recorded or simulated earthquakes.

Loading from Files

PyStrata supports several standard formats:

# AT2 format (common in earthquake engineering)
motion = pystrata.motion.TimeSeriesMotion.load_at2_file("motion.at2")

# SMC format (from CESMD/COSMOS)
motion = pystrata.motion.TimeSeriesMotion.load_smc_file("motion.smc")

Manual Creation

You can also create time series motions directly:

motion = pystrata.motion.TimeSeriesMotion(
    filename="custom_motion",
    description="Custom acceleration time series",
    time_step=0.01,  # seconds
    accels=[0.1, 0.2, 0.15, 0.05, ...]  # acceleration values in g
)

Properties and Methods

Time series motions provide several useful properties:

motion.duration        # Total duration (s)
motion.time_step       # Time step (s)
motion.times           # Time vector
motion.accels          # Acceleration values (g)
motion.freqs           # Frequency vector
motion.fourier_amps    # Fourier amplitude spectrum

Random Vibration Theory Motions

RVT motions are defined by their Fourier amplitude spectrum and strong motion duration. They are computationally efficient for parametric studies.

Source-Based RVT Motions

Generate theoretical motions from earthquake source parameters:

motion = pystrata.motion.SourceTheoryRvtMotion(
    magnitude=6.5,          # Moment magnitude
    distance=20,            # Source-to-site distance (km)
    region="wna",           # Western North America attenuation
    stress_drop=100         # Stress drop (bars), optional
)

Custom RVT Motions

Define motions from Fourier amplitude spectra:

motion = pystrata.motion.RvtMotion(
    freqs=[0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0],
    fourier_amps=[0.01, 0.02, 0.05, 0.08, 0.06, 0.03, 0.01],
    duration=20.0,          # Strong motion duration (s)
    peak_factor=2.5         # Peak factor for conversion
)

Motion Processing

Frequency Domain Calculations

All motions provide access to frequency domain representations:

# Compute Fourier amplitude spectrum
motion.calc_fourier_amps()

# Access frequency domain data
freqs = motion.freqs
fourier_amps = motion.fourier_amps

Response Spectra

Compute response spectra for any motion:

periods = [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0]
damping = 0.05  # 5% damping

resp_spec = motion.calc_response_spectrum(periods, damping)

Intensity Measures

Common intensity measures are available:

motion.pga             # Peak ground acceleration
motion.pgv             # Peak ground velocity (if available)
motion.arias_intensity # Arias intensity
motion.significant_duration  # Duration for 5-95% of Arias intensity

File Format Details

AT2 Format

AT2 is a text format commonly used in earthquake engineering:

FILENAME.AT2
Description line
NPTS=  1000, DT= 0.005 SEC
acceleration_value_1  acceleration_value_2  acceleration_value_3
acceleration_value_4  acceleration_value_5  acceleration_value_6
...

Units and Conventions

  • Time: seconds

  • Acceleration: g (acceleration of gravity)

  • Frequency: Hz

  • Fourier Amplitudes: g·s

Best Practices

Motion Selection

  • Use motions appropriate for your site’s seismic hazard level

  • Consider frequency content compatibility with site characteristics

  • For probabilistic analyses, use suites of motions rather than single records

Quality Control

  • Verify motion properties (duration, peak values, frequency content)

  • Check for processing artifacts (baseline shifts, filtering effects)

  • Ensure appropriate units and sign conventions

Computational Efficiency

  • Use RVT motions for parametric studies when appropriate

  • Consider motion truncation for very long records

  • Pre-compute Fourier spectra for repeated analyses

Common Issues

File Format Problems

  • Ensure proper line endings (Unix vs. Windows)

  • Check for missing header information

  • Verify numerical precision and formatting

Physical Reasonableness

  • Check for realistic peak acceleration values

  • Verify frequency content is appropriate for earthquake size and distance

  • Ensure motion duration is consistent with magnitude

Memory and Performance

  • Very long time series can consume significant memory

  • High sample rates may not be necessary for all analyses

  • Consider resampling for computational efficiency