Variation Module

The variation module provides tools for parameter variation and uncertainty analysis.

Classes

ToroVelocityVariation

Toro (1995) [T95] velocity variation model.

SpidVariation

Variation defined by the EPRI SPID (2013) and documented in PNNL (2014).

SoilTypeVariation

Base class for soil-type (modulus-reduction and damping) variation.

Velocity Variations

class pystrata.variation.ToroVelocityVariation(ln_std: float, rho_0: float, delta: float, rho_200: float, h_0: float, b: float, vary_bedrock: bool = False)[source]

Bases: VelocityVariation

Toro (1995) [T95] velocity variation model.

Default values can be selected with generic_model().

Parameters:

  • ln_std (float, optional) – \(\sigma_{ln}\) model parameter.

  • rho_0 (float, optional) – \(ρ_0\) model parameter.

  • delta (float, optional) – \(\Delta\) model parameter.

  • rho_200 (float, optional) – \(ρ_200\) model parameter.

  • h_0 (float, optional) – \(h_0\) model parameter.

  • b (float, optional) – \(b\) model parameter.

  • vary_bedrock (bool, optional) – If the velocity of the bedrock (half-space) should be varied.

classmethod generic_model(site_class, **kwds)[source]

Use generic model parameters based on site class.

Parameters:

site_class (str) –

Site classification. Possible options are:

  • Geomatrix AB

  • Geomatrix CD

  • USGS AB

  • USGS CD

  • USGS A

  • USGS B

  • USGS C

  • USGS D

See the report for definitions of the Geomatrix site classication. USGS site classification is based on \(V_{s30}\):

Site Class

\(V_{s30}\) (m/s)

A

>750 m/s

B

360 to 750 m/s

C

180 to 360 m/s

D

<180 m/s

Returns:

Initialized ToroVelocityVariation with generic parameters.

Return type:

ToroVelocityVariation

class pystrata.variation.SpidVariation(correlation, limits_mod_reduc=[0, 1], limits_damping=[0, 0.15], std_mod_reduc=0.15, std_damping=0.3, sample_mode='random', percentiles=None)[source]

Bases: SoilTypeVariation

Variation defined by the EPRI SPID (2013) and documented in PNNL (2014).

EPRI SPID (2013): https://www.nrc.gov/docs/ML1233/ML12333A170.pdf

Soil Type Variations

class pystrata.variation.SoilTypeVariation(correlation, limits_mod_reduc=[0.05, 1], limits_damping=[0, 0.15], vary_bedrock=False, sample_mode='random', percentiles=None)[source]

Bases: object

Base class for soil-type (modulus-reduction and damping) variation.

Parameters:

  • correlation (float) – Correlation coefficient between the modulus-reduction and damping random variables.

  • limits_mod_reduc (list[float], optional) – [min, max] clipping bounds for modulus reduction.

  • limits_damping (list[float], optional) – [min, max] clipping bounds for damping.

  • vary_bedrock (bool, optional) – Whether to include the half-space in the variation.

  • sample_mode ({'random', 'fixed_percentiles'}, optional) –

    How samples are drawn when iter_varied_profiles() iterates:

    • 'random' (default) — each call draws an independent random realisation from the truncated-normal distribution.

    • 'fixed_percentiles' — each call uses a pre-specified percentile supplied via sample_index so that the same index always produces an identical realisation. The percentile is selected as percentiles[sample_index % len(percentiles)], so the list cycles when count is a multiple of its length. The caller must pass the sample_index keyword argument to __call__(), and iter_varied_profiles() does this automatically.

  • percentiles (list[float] | None, optional) – Ordered sequence of quantiles in (0, 1) used in 'fixed_percentiles' mode. The sequence cycles: iteration i draws percentiles[i % len(percentiles)]. Required (and only used) when sample_mode is 'fixed_percentiles'.

__call__(soil_type, sample_index=None)[source]

Return a single varied realisation of soil_type.

Parameters:

  • soil_type (site.SoilType) – The nominal (seed) soil type to vary.

  • sample_index (int | None, optional) – Index into percentiles used when sample_mode='fixed_percentiles'. Ignored in 'random' mode. Must be provided (and within range) in 'fixed_percentiles' mode.

vary_profile(profile: Profile, sample_index: int | None = None)[source]

Return a profile with varied soil types.

Parameters:

  • profile (site.Profile) – Input profile to vary.

  • sample_index (int | None, optional) – Index into percentiles for sample_mode='fixed_percentiles'. Ignored in 'random' mode.

property sample_mode

'random' or 'fixed_percentiles'.

Type:

Sampling mode

property percentiles

Percentile list used in 'fixed_percentiles' mode, or None.