liquepy.trigger

Stress-based triggering method

liquepy.trigger.boulanger_and_idriss_2014

class liquepy.trigger.boulanger_and_idriss_2014.BoulangerIdriss2014(depth, q_c, f_s, u_2, cpt_gwl=None, pga=0.25, m_w=None, gwl=None, a_ratio=0.8, cfc=0.0, **kwargs)

Bases: liquepy.trigger.boulanger_and_idriss_2014.BoulangerIdriss2014CPT

class liquepy.trigger.boulanger_and_idriss_2014.BoulangerIdriss2014CPT(cpt, gwl=None, pga=0.25, m_w=None, cfc=0.0, **kwargs)

Bases: object

property gammas

property magnitude

class liquepy.trigger.boulanger_and_idriss_2014.BoulangerIdriss2014SoilProfile(sp, pga=0.25, m_w=None, **kwargs)

Bases: object

liquepy.trigger.boulanger_and_idriss_2014.calc_b_from_msf_max_bi2014(msf_max)

Equivalent b value for a given magnitude scaling factor from Fig A.16 in BI2014

Where b is the power coefficient for the CSR-vs-n_cycles liquefaction resistance relationship

Parameters

msf_max –

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_big_q_values(qt, sigma_v, sigma_veff, p_a, n_val=0.5)

Eq. 2.26 :param c_n: CN :param qt: :param sigmav: :return:

liquepy.trigger.boulanger_and_idriss_2014.calc_cn_values(m, sigma_veff)

CN parameter from CPT, Eq 2.15a

liquepy.trigger.boulanger_and_idriss_2014.calc_crr_m7p5_from_n1_60cs(n1_60cs, c_0=2.8)

Calculation of cyclic resistance ratio for Magnitude 7.5 earthquake from SPT

n1_60cs: float or array_like

Clean-sand equivalent, normalised SPT blow count

c_0: float (default=2.8)

Empirical fitting parameter.

• 2.8=16th percentile (commonly used)

• 2.6=median response

liquepy.trigger.boulanger_and_idriss_2014.calc_crr_m7p5_from_qc1ncs(q_c1n_cs, c_0=2.8)

Calculation of cyclic resistance ratio for Magnitude 7.5 earthquake

q_c1n_cs: float or array_like

Clean-sand equivalent, normalised cone tip resistance

c_0: float (default=2.8)

Empirical fitting parameter.

• 2.8=16th percentile (commonly used)

• 2.6=median response

liquepy.trigger.boulanger_and_idriss_2014.calc_crr_m7p5_from_qc1ncs_capped(q_c1n_cs, gwl, depth, i_c, i_c_limit=2.6, c_0=2.8)

cyclic resistance from CPT, Eq. 2.24 it’s not possible to have liquefaction above water table

liquepy.trigger.boulanger_and_idriss_2014.calc_crr_n15_from_n1_60cs(n1_60cs, c_0=2.8)

liquepy.trigger.boulanger_and_idriss_2014.calc_crr_n15_from_qc1ncs(q_c1ncs, c_0=2.8)

liquepy.trigger.boulanger_and_idriss_2014.calc_csr(sigma_veff, sigma_v, pga, rd, gwl, depth)

Cyclic stress ratio from CPT, Eq 2.2,

liquepy.trigger.boulanger_and_idriss_2014.calc_delta_q_c1n(q_c1n, fc)

delta q_c1n from CPT, Eq 2.22

liquepy.trigger.boulanger_and_idriss_2014.calc_f_ic_values(fs, qt, sigma_v)

liquepy.trigger.boulanger_and_idriss_2014.calc_fc(ic, cfc)

liquepy.trigger.boulanger_and_idriss_2014.calc_i_c(big_q, big_f)

Calculates the index parameter of the soil

Eq. 2.26

Parameters

• big_q – float or array,

• big_f – float or array,

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_k_sigma(sigma_eff, q_c1ncs, pa=100)

Overburden correction factor, K_sigma

Equation 2.16a

Parameters

• sigma_eff – vertical effective stress

• q_c1ncs – clean sand-corrected normalised cone tip resistance

• pa – atmospheric pressure in kPa

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_k_sigma_w_n1_60cs(sigma_eff, n1_60cs, pa=100)

Overburden correction factor, K_sigma

Equation 2.16a

sigma_eff: float or array_like

Vertical effective stress

n1_60cs: float or array_like

Clean-sand equivalent, normalised SPT blow count

pa: float

Atmospheric pressure in kPa

liquepy.trigger.boulanger_and_idriss_2014.calc_lrc_from_qc1ncs_bi2014(q_c1n_cs, n_cycles)

liquepy.trigger.boulanger_and_idriss_2014.calc_m(q_c1ncs)

m parameter from CPT, Eq 2.15b

liquepy.trigger.boulanger_and_idriss_2014.calc_msf(magnitude, q_c1ncs)

Magnitude scaling factor to correct the cyclic resistance ratio

Eq. 2.19

Parameters

• magnitude – earthquake m_w

• q_c1ncs – clean sand-corrected normalised cone tip resistance

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_n1_60cs_from_crr_m7p5(crr_7p5, c_0=2.8)

Solves the closed form solution to a quartic to invert the CRR_7p5-vs-N1_60_cs relationship

crr_7p5: float or array_like

values of cyclic resistance ratio at m_w 7.5

c_0: float (default=2.8)

Empirical fitting parameter.

• 2.8=16th percentile (commonly used)

• 2.6=median response

float or array_like

value of normalised blow-count corrected to clean sand behaviour

liquepy.trigger.boulanger_and_idriss_2014.calc_n_cycles_at_m7p5_bi2014(b)

Number of equivalent cycles for Magnitude 7.5 from Fig A.15 in BI2014

Parameters

b –

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_pore_pressure(depth, gwl, unit_water_wt)

liquepy.trigger.boulanger_and_idriss_2014.calc_q_c1n(q_c, c_n)

qc1n from CPT, Eq 2.4

liquepy.trigger.boulanger_and_idriss_2014.calc_q_c1n_cs_from_crr_m7p5(crr_7p5, c_0=2.8)

Solves the closed form solution to a quartic to invert the CRR_7p5-vs-q_c1n_cs relationship

crr_7p5: float or array_like

values of cyclic resistance ratio at m_w 7.5

c_0: float (default=2.8)

Empirical fitting parameter.

• 2.8=16th percentile (commonly used)

• 2.6=median response

float or array_like

value of normalised cone tip resistance corrected to clean sand behaviour

liquepy.trigger.boulanger_and_idriss_2014.calc_q_c1ncs(q_c1n, delta_q_c1n)

q_c1ncs from CPT, Eq 2.10

liquepy.trigger.boulanger_and_idriss_2014.calc_qc_1ncs_from_crr_m7p5(crr_7p5, c_0=2.8)

liquepy.trigger.boulanger_and_idriss_2014.calc_qt(qc, ar, u2)

Parameters

• qc – kPa, cone tip resistance

• ar – -, area ratio

• u2 – kPa, water pressure beneath cone tip

Returns

liquepy.trigger.boulanger_and_idriss_2014.calc_rd(depth, magnitude)

rd from CPT, Eq 2.14a

liquepy.trigger.boulanger_and_idriss_2014.calc_sigma_v(depths, gammas, gamma_predrill=17.0)

Calculates the vertical stress

Note: properties are forward projecting

liquepy.trigger.boulanger_and_idriss_2014.calc_sigma_veff(sigma_v, pore_pressure)

liquepy.trigger.boulanger_and_idriss_2014.calc_unit_dry_weight(fs, q_t, p_a, unit_water_wt)

Estimate the unit weight of the soil.

Ref: https://www.cpt-robertson.com/PublicationsPDF/Unit%20Weight%20Rob%20%26%20Cabal%20CPT10.pdf

fs: array_like

CPT skin friction (kPa)

q_t: array_like

CPT cone tip resistance (kPa)

p_a: float

Atmospheric pressure (kPa)

unit_water_wt: float

Unit weght of water

liquepy.trigger.boulanger_and_idriss_2014.calc_unit_weight(e_curr, specific_gravity, saturation, pw)

liquepy.trigger.boulanger_and_idriss_2014.calc_void_ratio(unit_dry_weight, specific_gravity, pw)

liquepy.trigger.boulanger_and_idriss_2014.calculate_qc_1ncs_from_crr_7p5(crr_7p5)

liquepy.trigger.boulanger_and_idriss_2014.crr_m(ksigma, msf, crr_m7p5)

Cyclic resistance ratio corrected for m_w and confining stress

liquepy.trigger.boulanger_and_idriss_2014.run_bi2014(cpt, pga, m_w, gwl=None, p_a=101.0, cfc=0.0, i_c_limit=2.6, gamma_predrill=17.0, c_0=2.8, unit_wt_method='robertson2009', s_g=2.65, s_g_water=1.0, saturation=None)

Runs the Boulanger and Idriss (2014) triggering method.

cpt: liquepy.field.CPT,

ground water level below the surface

pga: float, g,

peak ground acceleration

m_w: float, -,

Earthquake magnitude

gwl: float, m,

depth to ground water from surface at time of earthquake

p_a: float, kPa, default=101

Atmospheric pressure

cfc: float, -, default=0.0

Fines content correction factor for Eq 2.29

i_c_limit: float, -, default=2.6

Limit of liquefiable material

gamma_predrill: float, kN/m3, default=17.0

Unit weight of soil above pre-drill depth

c_0: float, -, default=2.8

Factor that adjusts the CRR-vs-qc1ncs relationship

unit_wt_method: str, -, default=’robertson2009’

Method used to determine unit weight

s_g: float or array_like, -, default=2.65

Specific gravity

s_g_water: float, -, default=1.0

Specific gravity of water

saturation: array_like or None

Saturation ratio for each depth increment

BoulangerIdriss2014CPT()

Calculation of shear strain

liquepy.trigger.shear_strain.calc_fixed_dr_gamma_max(fs, relative_density)

liquepy.trigger.shear_strain.calc_relative_density_tasuoka_1990(q_c, esig_v0, dr_min=0.0, dr_max=1.0)

Calculates the relative density according to Tasuoka et al. (1990)

q_c1n esig_v0 dr_min dr_max

liquepy.trigger.shear_strain.calc_relative_density_zhang_2002(q_c1n, dr_min=0.0, dr_max=1.0)

Calculates the relative density (Eq. 2) [Zhang:2004el]

q_c1n: Normalised cone tip resistance

liquepy.trigger.shear_strain.calc_shear_strain(fs, d_r)

liquepy.trigger.shear_strain.calc_shear_strain_zhang_2004(fs, d_r)

Calculates the shear strain (not in percentage)

fs d_r: float or array_like, [dec]

Relative density of soil

liquepy.trigger.shear_strain.calc_single_shear_strain(fs, d_r)

liquepy.trigger.shear_strain.calculate_shear_strain(fos, relative_density)

Calculation of volumetric strain

liquepy.trigger.volumetric_strain.calc_volumetric_strain(factor_of_safety, q_c1n_cs)

liquepy.trigger.volumetric_strain.calc_volumetric_strain_zhang_2004(factor_of_safety, q_c1n_cs)

Calculates the Volumetric strain according to Zhang et al. (2002)

Note: strain is not as a percentage

doi: 10.1139/t02-047

Parameters

• factor_of_safety – float or array, factor of safety against liquefaction triggering

• q_c1n_cs – float, or array, corrected normalised clean sand cone tip resistance

Returns

strain as decimal (not percentage)

liquepy.trigger.volumetric_strain.calculate_volumetric_strain(factor_of_safety, q_c1n_cs)

Liquefaction triggering measures

liquepy.trigger.triggering_measures.calc_ldi(e_s, depth, z_max=None)

Calculates the Lateral Displacement Index [Zhang:2004el]

e_s depth z_max

liquepy.trigger.triggering_measures.calc_ldi_increments(e_s, depth)

Calculates the Lateral Displacement Index [Zhang:2004el]

e_s depth

liquepy.trigger.triggering_measures.calc_lpi(liq_factor_of_safety, depths)

Formulation from ‘Soil Dynamics and earthquake engineering’, eq. page 317

liquepy.trigger.triggering_measures.calc_lpi_increments(liq_factor_of_safety, depth)

formulation from ‘Soil Dynamics and earthquake engineering’, eq. page 317

liquepy.trigger.triggering_measures.calc_lsn(e_v, depth)

Calculates the liquefaction severity number (LSN)

doi: 10.1016/j.soildyn.2015.09.016

Parameters

• e_v – array, volumetric strain in percentage

• depth – array, depth from surface

Returns

float, LSN for profile

liquepy.trigger.triggering_measures.calc_lsn_increments(e_v, depth)

Calculates the liquefaction severity number (LSN)

doi: 10.1016/j.soildyn.2015.09.016

Parameters

• e_v – array, volumetric strain

• depth – array, depth from surface

Returns

array, lsn increment at depth

liquepy.trigger.triggering_measures.calculate_lsn(e_v, depth)

liquepy.trigger.triggering_measures.calculate_lsn_increments(e_v, depth)

Deprecated: see calc_lsn_increments

liquepy.trigger.nses

Nodal surface energy spectrum methods

class liquepy.trigger.nses.TimeShiftProfile(sp, asig, ys, g_mod_red=1.0, period=0.5, exact=False, in_loc=1)

Bases: object

property exact

get_cake(xi, trim=False, start=False, g_scale_limit=1.0)

get_case(xi, trim=False, start=False, g_scale_limit=1.0)

get_kinetic_energy(xi, trim=False, start=False, g_scale_limit=1.0)

get_red_factors(xi)

get_strain_energy(xi, trim=False, start=False, g_scale_limit=1.0)

get_unit_energy_series(xi, energy)

trim_to_length(out, trim=False, start=False)

liquepy.trigger.nses.calc_energy_ratio_w_time(xi, total_time, time, av_period)

liquepy.trigger.nses.calc_time_surf_to_depth(sp, depth)

liquepy.trigger.nses.est_case_1d_millen_et_al_2019(sp, asig, depth, xi, g_mod_red=1.0, trim=False, start=False, period=0.5, exact=False, in_loc=1, g_scale_limit=1000.0, nodal=True, cace=True)

Calculates the Cumulative absolute change in strain energy according to Millen et al. (2019)

sp: sfsimodels.SoilProfile object asig: eqsig.AccSignal object

upward propagating wave at base of profile

depth: the distance from the surface where energy should be estimated xi: float

approximate viscous damping of whole soil profile

g_mod_red: float

reduction factor to apply to shear modulus

trim: bool

If true to return CASE with same length as asig.npts

start: bool,

if True then accounts for travel time from input location to depth

period: float

The average energy period of the ground motion

exact: bool,

If exact then assume wave is sine wave and reduce upward and downward components

in_loc: int

Location of input motion, base=1, surface=0

g_scale_limit: int or float

Limiting ratio that CASE can be scaled by when changing shear wave velocity

nodal: bool

If true then surface is a nodal (zero stress), if false then surface is anti-nodal (zero displacement)

Returns