Site Module

The site module provides classes for defining layered soil profiles and material properties.

Classes

Profile	Soil profile with an infinite halfspace at the base.
Layer	Docstring for Layer.
SoilType	Soiltype that combines nonlinear behavior and material properties.
Location	Location within a profile.
NonlinearCurve	Abstract base class for nonlinear curve with log-linear interpolation.
ModulusReductionCurve	Shear-modulus reduction curve.
DampingCurve	Damping ratio curve.

Site Profile

class pystrata.site.Profile(layers=None, wt_depth=0)

Bases: Container

Soil profile with an infinite halfspace at the base.

classmethod from_dataframe(df, wt_depth=0)

Create a profile based on a table with columns: - thickness (m) - vel_shear (m) - unit_wt (kN/m³) - damping (dec)

copy()

Return a copy of the profile with new Layer instances.

reset_layers()

Set initial properties from the soil types.

auto_discretize(max_freq: float = 50.0, wave_frac: float = 0.2, nonlinear_only: bool = True) → Profile

Subdivide the layers to capture strain variation.

Parameters:

• max_freq (float) – Maximum frequency of interest [Hz].

• wave_frac (float) – Fraction of wavelength required. Typically 1/3 to 1/5.

• max_thick (float optional) – If provided, layers are limited to be at most that thick. This is applied to all layers regardless of nonlinearity.

Returns:

profile – A new profile with modified layer thicknesses

Return type:

Profile

pore_pressure(depth)

Pore pressure at a given depth in [kN//m²].

Parameters:

depth

Return type:

pore_pressure

lookup_depth(depth: float) → tuple[int, float]

Look up the layer and the depth within the layer for a specific depth.

Parameters:

depth (float) – Depth corresponding to the location of interest.

Returns:

• index (int) – Layer index

• depth_within (float) – Depth from the top of the layer to achieve the specific depth.

location(wave_field, depth=None, index=None)

Create a Location for a specific depth.

Parameters:

• wave_field (str) – Wave field. See Location for possible values.

• depth (float, optional) – Depth corresponding to the :class`Location` of interest. If provided, then index is ignored.

• index (int, optional) –

  Index corresponding to layer of interest in Profile. If

  provided, then depth is ignored and location is provided a top of layer.

Returns:

Corresponding Location object.

Return type:

Location

time_average_vel(depth)

Calculate the time-average velocity.

Parameters:

depth (float) – Depth over which the average velocity is computed.

Returns:

avg_vel – Time averaged velocity.

Return type:

float

vs30()

Compute the Vs30 of the profile.

simplified_rayliegh_vel()

Simplified Rayliegh velocity of the site.

This follows the simplifications proposed by Urzua et al. (2017)

Returns:

rayleigh_vel – Equivalent shear-wave velocity.

Return type:

float

Layers and Materials

class pystrata.site.Layer(soil_type: SoilType, thickness: float, shear_vel: float, damping_min: None | float = None)

Bases: object

Docstring for Layer.

copy() → Layer

Return a copy of the Layer instance with previously defined SoilType.

property depth: float

Depth to the top of the layer [m].

property depth_mid: float

Depth to the middle of the layer [m].

property depth_base: float

Depth to the base of the layer [m].

property density: float

Density of soil in [kg/m³].

property damping_min: float

Minimum damping of the soil [dec]

property damping: ndarray | float

Strain-compatible damping.

property initial_shear_mod: float

Initial (small-strain) shear modulus [kN/m²].

property initial_shear_vel: float

Initial (small-strain) shear-wave velocity [m/s].

property comp_shear_mod: complex

Strain-compatible complex shear modulus [kN/m²].

property comp_shear_vel: complex

Strain-compatible complex shear-wave velocity [m/s].

property shear_mod: ndarray | float

Strain-compatible shear modulus [kN//m²].

property shear_vel

Strain-compatible shear-wave velocity [m/s].

property stress_shear_eff

Effective shear stress at layer midpoint.

property stress_shear_max

Maximum shear stress at layer midpoint.

property adjusted_damping_curve: recarray

Return the damping curve adjusted by the layer-specific minimum damping.

property travel_time

Travel time through the layer.

stress_vert(depth_within=0, effective=False)

Vertical stress from the top of the layer [kN//m²].

stress_mean(depth_within=0, effective=False, k0=0.5)

Mean effective stress from the top of the layer [kN//m²].

class pystrata.site.SoilType(name: str = '', unit_wt: float = 0.0, mod_reduc: None | NonlinearCurve = None, damping: float | NonlinearCurve = 0.0)

Bases: object

Soiltype that combines nonlinear behavior and material properties.

Parameters:

• name (str, optional) – used for identification

• unit_wt (float) – unit weight of the material in [kN/m³]

• mod_reduc (NonlinearCurve or None) – shear-modulus reduction curves. If None, linear behavior with no reduction is used

• damping (NonlinearCurve or float) – damping ratio. [decimal] If float, then linear behavior with constant damping is used.

property density: float

Density of the soil in kg/m³.

property damping_min: float

Return the small-strain damping.

property unit_wt: float

Unit weight of the soil in kN/m³.

property is_nonlinear: bool

If nonlinear properties are specified.

Output Locations

class pystrata.site.Location(index, layer, wave_field, depth_within=0)

Bases: object

Location within a profile.

Nonlinear Curves

class pystrata.site.NonlinearCurve(name='', strains=None, values=None, limits=None)

Bases: ABC

Abstract base class for nonlinear curve with log-linear interpolation.

Parameters:

• name (str, optional) – used for identification

• strains (numpy.ndarray, optional) – strains for each of the values [decimal].

• values (numpy.ndarray, optional) – value of the property corresponding to each strain. Damping should be specified in decimal, e.g., 0.05 for 5%.

• limits (tuple, optional) – (min, max) limits for clipping interpolated values

abstract property param: str

Nonlinear parameter name (‘mod_reduc’ or ‘damping’).

classmethod from_published(name: str, param: str)

Create a NonlinearCurve from published curves.

Parameters:

• name (str) – Name of the published curve model

• param (str) – Type of parameter: ‘mod_reduc’ or ‘damping’

Returns:

The appropriate subclass instance

Return type:

ModulusReductionCurve or DampingCurve

__call__(strains)

Return the nonlinear property at a specific strain.

If the strain is within the range of the provided strains, then the value is interpolated in log-space is calculate the value at the requested strain. If the strain falls outside the provided range then the value corresponding to the smallest or largest value is returned.

The interpolation is performed using either a cubic-spline, if enough points are provided, or using linear interpolation.

Parameters:

strains (float or array_like) – Shear strain of interest [decimal].

Returns:

The nonlinear property at the requested strain(s).

Return type:

float or array_like

property strains

Strains [decimal].

property values

Values of either shear-modulus reduction or damping ratio.

class pystrata.site.ModulusReductionCurve(name='', strains=None, values=None, limits=None)

Bases: NonlinearCurve

Shear-modulus reduction curve.

Parameters:

• name (str, optional) – used for identification

• strains (numpy.ndarray, optional) – strains for each of the values [decimal].

• values (numpy.ndarray, optional) – shear-modulus reduction values (G/Gmax) corresponding to each strain.

• limits (tuple, optional) – (min, max) limits for clipping interpolated values. Default: (0.001, 1)

property param: str

Nonlinear parameter name (‘mod_reduc’ or ‘damping’).

class pystrata.site.DampingCurve(name='', strains=None, values=None, limits=None)

Bases: NonlinearCurve

Damping ratio curve.

Parameters:

• name (str, optional) – used for identification

• strains (numpy.ndarray, optional) – strains for each of the values [decimal].

• values (numpy.ndarray, optional) – damping ratio values [decimal] corresponding to each strain.

• limits (tuple, optional) – (min, max) limits for clipping interpolated values. Default: (0, 0.49)

property param: str

Nonlinear parameter name (‘mod_reduc’ or ‘damping’).