base.py

subsurfaceio.functions.base

Base functions.

Functions:

Name	Description
`get_below_water_table`	Calculation function.
`get_coefficient_of_consolidation__terzaghi1925principles`	Calculation function.
`get_coefficient_of_earth_pressure_at_rest__mayne1982ko`	Calculation function.
`get_consolidation_state`	Calculation function.
`get_depth_middle`	Calculation function.
`get_effective_stress`	Calculation function.
`get_elasticity_modulus_from_shear_modulus`	Calculation function.
`get_elevation`	Calculation function.
`get_overconsolidation_ratio__ladd1991stability`	Calculation function.
`get_pore_water_pressure`	Calculation function.
`get_shear_strength__terzaghi1943theoretical`	Calculation function.
`get_shear_velocity__landau1959theory`	Calculation function.
`get_small_strain_shear_modulus__landau1959theory`	Calculation function.
`get_soil_type`	Calculation function.
`get_soil_type2`	Calculation function.
`get_soil_type3`	Calculation function.
`get_thickness`	Calculation function.
`get_total_stress`	Calculation function.
`get_undrained_shear_strength_ratio`	Calculation function.

get_below_water_table

get_below_water_table(
    depth, water_table_present, water_table=float("nan")
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_below\_water\_table}(z, z_{w\ present}, z_w) \\ \hspace{1em} \mathrm{below\_water\_table} \gets \mathrm{np}.\mathrm{full\_like} \mathopen{}\left( z, \mathrm{False} \mathclose{}\right) \\ \hspace{1em} \mathbf{if} \ z_{w\ present} \\ \hspace{2em} \mathbf{if} \ \mathrm{np}.\mathrm{isnan} \mathopen{}\left( z_w \mathclose{}\right) \\ \hspace{3em} \mathrm{raise\_value\_error} \mathopen{}\left( \textrm{"water\_table missing"} \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{2em} \mathrm{np}.\mathrm{putmask} \mathopen{}\left( \mathrm{below\_water\_table}, z > z_w, \mathrm{True} \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ \mathrm{below\_water\_table} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`depth`	`float`	Depth below ground surface to bottom of layer	required
`water_table_present`	`bool`	Indicates presence of water table	required
`water_table`	`float`	Depth to water table below ground surface	`float('nan')`

Returns:

Name	Type	Description
`below_water_table`	`bool`	Indicates if soil layer is below water table

get_coefficient_of_consolidation__terzaghi1925principles

get_coefficient_of_consolidation__terzaghi1925principles(
    permeability, constrained_modulus
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_coefficient\_of\_consolidation\_\_terzaghi1925principles}(k, M) \\ \hspace{1em} C_v \gets 31536000 \cdot \frac{1000 k \cdot M}{g} \\ \hspace{1em} \mathbf{return} \ C_v \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`permeability`	`float`	Soil permeability	required
`constrained_modulus`	`float`	Constrained modulus of soil	required

Returns:

Name	Type	Description
`coefficient_of_consolidation`	`float`	Coefficient of consolidation for soil

get_coefficient_of_earth_pressure_at_rest__mayne1982ko

get_coefficient_of_earth_pressure_at_rest__mayne1982ko(
    friction_angle,
    peak_friction_angle,
    overconsolidation_ratio,
    is_fine_soil,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_coefficient\_of\_earth\_pressure\_at\_rest\_\_mayne1982ko}(ϕ, ϕ', OCR, \mathrm{is\_fine\_soil}) \\ \hspace{1em} ϕ \gets \mathrm{np}.\mathrm{copy} \mathopen{}\left( ϕ \mathclose{}\right) \\ \hspace{1em} OCR \gets \mathrm{np}.\mathrm{copy} \mathopen{}\left( OCR \mathclose{}\right) \\ \hspace{1em} \mathrm{np}.\mathrm{putmask} \mathopen{}\left( ϕ, \mathrm{is\_fine\_soil}, ϕ' \mathclose{}\right) \\ \hspace{1em} \mathrm{np}.\mathrm{putmask} \mathopen{}\left( OCR, \mathrm{np}.\mathrm{isnan} \mathopen{}\left( OCR \mathclose{}\right) \mathbin{\&} \mathord{\sim} \mathrm{is\_fine\_soil}, 1 \mathclose{}\right) \\ \hspace{1em} K_o \gets \mathopen{}\left( 1 - \mathrm{sindg} \mathopen{}\left( ϕ \mathclose{}\right) \mathclose{}\right) OCR^{\mathrm{sindg} \mathopen{}\left( ϕ \mathclose{}\right)} \\ \hspace{1em} K_o \gets \mathrm{np}.\mathrm{nan\_to\_num} \mathopen{}\left( K_o \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ K_o \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`friction_angle`	`float`	Friction angle of soil	required
`peak_friction_angle`	`float`	Peak friction angle of soil	required
`overconsolidation_ratio`	`float`	Overconsolidation ratio of soil	required
`is_fine_soil`	`bool`	Indicates if soil is fine-grained	required

Returns:

Name	Type	Description
`coefficient_of_earth_pressure_at_rest`	`float`	Coefficient of lateral earth pressure at rest

get_consolidation_state

get_consolidation_state(overconsolidation_ratio)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_consolidation\_state}(OCR) \\ \hspace{1em} \mathrm{consolidation\_state} \gets \mathrm{parameter\_registry}.\mathrm{bin\_data} \mathopen{}\left( \textrm{"overconsolidation\_ratio"}, OCR, \textrm{"consolidation\_state"} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{consolidation\_state} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`overconsolidation_ratio`	`float`	Overconsolidation ratio of soil	required

Returns:

Name	Type	Description
`consolidation_state`	`str`	Soil consolidation state description

get_depth_middle

get_depth_middle(depth, thickness)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_depth\_middle}(z, H) \\ \hspace{1em} z_{middle} \gets z - \frac{H}{2} \\ \hspace{1em} \mathbf{return} \ z_{middle} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`depth`	`float`	Depth below ground surface to bottom of layer	required
`thickness`	`float`	Thickness of soil layer	required

Returns:

Name	Type	Description
`depth_middle`	`float`	Depth below ground surface to middle of layer

get_effective_stress

get_effective_stress(total_stress, pore_water_pressure)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_effective\_stress}(σ_v, u_0) \\ \hspace{1em} σ_v' \gets σ_v - u_0 \\ \hspace{1em} \mathbf{return} \ σ_v' \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`total_stress`	`float`	Total vertical stress in soil	required
`pore_water_pressure`	`float`	Pore water pressure in soil	required

Returns:

Name	Type	Description
`effective_stress`	`float`	Effective vertical stress in soil

get_elasticity_modulus_from_shear_modulus

get_elasticity_modulus_from_shear_modulus(
    small_strain_shear_modulus, poisson_ratio
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_elasticity\_modulus\_from\_shear\_modulus}(G_o, ν) \\ \hspace{1em} E_s \gets 2 G_o \cdot \mathopen{}\left( 1 + ν \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ E_s \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`small_strain_shear_modulus`	`float`	Small strain shear modulus of soil	required
`poisson_ratio`	`float`	Poisson’s ratio of soil	required

Returns:

Name	Type	Description
`elasticity_modulus`	`float`	Modulus of elasticity of soil

get_elevation

get_elevation(depth, surface_elevation=0.0)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_elevation}(z, \mathrm{surface\_elevation}) \\ \hspace{1em} \mathrm{elevation} \gets \mathrm{surface\_elevation} - z \\ \hspace{1em} \mathbf{return} \ \mathrm{elevation} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`depth`	`float`	Depth below ground surface to bottom of layer	required
`surface_elevation`	`float`	Ground surface elevation	`0.0`

Returns:

Name	Type	Description
`elevation`	`float`	Elevation of soil layer bottom depth

get_overconsolidation_ratio__ladd1991stability

get_overconsolidation_ratio__ladd1991stability(
    undrained_shear_strength,
    effective_stress,
    is_fine_soil,
    shansep_method_s=0.22,
    shansep_method_m=0.8,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_overconsolidation\_ratio\_\_ladd1991stability}(S_u, σ_v', \mathrm{is\_fine\_soil}, s, m) \\ \hspace{1em} OCR \gets \mathopen{}\left( \frac{S_u}{σ_v' \cdot s} \mathclose{}\right)^{\frac{1}{m}} \\ \hspace{1em} OCR \gets \mathrm{np}.\mathrm{asarray} \mathopen{}\left( OCR \mathclose{}\right) \\ \hspace{1em} \mathrm{np}.\mathrm{putmask} \mathopen{}\left( OCR, \mathord{\sim} \mathrm{is\_fine\_soil}, \mathrm{np}.\mathrm{nan} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ OCR \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`undrained_shear_strength`	`float`	Undrained shear strength of soil	required
`effective_stress`	`float`	Effective vertical stress in soil	required
`is_fine_soil`	`bool`	Indicates if soil is fine-grained	required
`shansep_method_s`	`float`	SHANSEP method s parameter	`0.22`
`shansep_method_m`	`float`	SHANSEP method m parameter	`0.8`

Returns:

Name	Type	Description
`overconsolidation_ratio`	`float`	Overconsolidation ratio of soil

get_pore_water_pressure

get_pore_water_pressure(
    water_table_present,
    water_table=float("nan"),
    depth=float("nan"),
    water_unit_weight=9.81,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_pore\_water\_pressure}(z_{w\ present}, z_w, z, γ_w) \\ \hspace{1em} \mathbf{if} \ z_{w\ present} \\ \hspace{2em} \mathbf{if} \ \mathrm{np}.\mathrm{isnan} \mathopen{}\left( z_w \mathclose{}\right) \\ \hspace{3em} \mathrm{raise\_value\_error} \mathopen{}\left( \textrm{"null water\_table"} \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{2em} \mathbf{if} \ z_w < 0 \\ \hspace{3em} \mathrm{raise\_value\_error} \mathopen{}\left( \textrm{"negative water\_table not supported"} \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{2em} u_0 \gets \mathopen{}\left( z - z_w \mathclose{}\right) γ_w \\ \hspace{2em} u_0 \gets \mathrm{np}.\mathrm{clip} \mathopen{}\left( u_0, 0, \mathrm{None} \mathclose{}\right) \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} u_0 \gets \mathrm{np}.\mathrm{zeros\_like} \mathopen{}\left( z \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ u_0 \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`water_table_present`	`bool`	Indicates presence of water table	required
`water_table`	`float`	Depth to water table below ground surface	`float('nan')`
`depth`	`float`	Depth below ground surface to bottom of layer	`float('nan')`
`water_unit_weight`	`float`	Unit weight of water	`9.81`

Returns:

Name	Type	Description
`pore_water_pressure`	`float`	Pore water pressure in soil

get_shear_strength__terzaghi1943theoretical

get_shear_strength__terzaghi1943theoretical(
    undrained_shear_strength,
    effective_stress,
    friction_angle,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_shear\_strength\_\_terzaghi1943theoretical}(S_u, σ_v', ϕ) \\ \hspace{1em} τ \gets \mathrm{np}.\mathrm{nan\_to\_num} \mathopen{}\left( S_u \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ τ \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`undrained_shear_strength`	`float`	Undrained shear strength of soil	required
`effective_stress`	`float`	Effective vertical stress in soil	required
`friction_angle`	`float`	Friction angle of soil	required

Returns:

Name	Type	Description
`shear_strength`	`float`	Shear strength of soil

get_shear_velocity__landau1959theory

get_shear_velocity__landau1959theory(
    small_strain_shear_modulus, unit_weight
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_shear\_velocity\_\_landau1959theory}(G_o, γ) \\ \hspace{1em} V_s \gets \mathopen{}\left( \frac{g \cdot 1000 G_o}{γ} \mathclose{}\right)^{0.5} \\ \hspace{1em} \mathbf{return} \ V_s \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`small_strain_shear_modulus`	`float`	Small strain shear modulus of soil	required
`unit_weight`	`float`	Unit weight of soil	required

Returns:

Name	Type	Description
`shear_velocity`	`float`	Shear wave velocity of soil

get_small_strain_shear_modulus__landau1959theory

get_small_strain_shear_modulus__landau1959theory(
    unit_weight, shear_velocity
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_small\_strain\_shear\_modulus\_\_landau1959theory}(γ, V_s) \\ \hspace{1em} G_o \gets \frac{\frac{γ}{g} \cdot V_s^{2}}{1000} \\ \hspace{1em} \mathbf{return} \ G_o \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`unit_weight`	`float`	Unit weight of soil	required
`shear_velocity`	`float`	Shear wave velocity of soil	required

Returns:

Name	Type	Description
`small_strain_shear_modulus`	`float`	Small strain shear modulus of soil

get_soil_type

get_soil_type(uscs_symbol)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_soil\_type}(\mathrm{uscs\_symbol}) \\ \hspace{1em} \mathrm{soil\_type} \gets \mathrm{replace\_from\_mapping} \mathopen{}\left( \mathrm{uscs\_symbol}, \mathrm{ReferenceDataSets}.\mathrm{USCSSoilTypes}.\mathrm{to\_index\_map} \mathopen{}\left( \textrm{"key"}, \textrm{"soil\_type"} \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{soil\_type} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`uscs_symbol`	`str`	Unified Soil Classification System symbol	required

Returns:

Name	Type	Description
`soil_type`	`str`	Primary soil type description

get_soil_type2

get_soil_type2(uscs_symbol)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_soil\_type2}(\mathrm{uscs\_symbol}) \\ \hspace{1em} \mathrm{soil\_type2} \gets \mathrm{replace\_from\_mapping} \mathopen{}\left( \mathrm{uscs\_symbol}, \mathrm{ReferenceDataSets}.\mathrm{USCSSoilTypes}.\mathrm{to\_index\_map} \mathopen{}\left( \textrm{"key"}, \textrm{"soil\_type2"} \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{soil\_type2} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`uscs_symbol`	`str`	Unified Soil Classification System symbol	required

Returns:

Name	Type	Description
`soil_type2`	`str`	Secondary soil type description

get_soil_type3

get_soil_type3(uscs_symbol)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_soil\_type3}(\mathrm{uscs\_symbol}) \\ \hspace{1em} \mathrm{soil\_type3} \gets \mathrm{replace\_from\_mapping} \mathopen{}\left( \mathrm{uscs\_symbol}, \mathrm{ReferenceDataSets}.\mathrm{USCSSoilTypes}.\mathrm{to\_index\_map} \mathopen{}\left( \textrm{"key"}, \textrm{"soil\_type3"} \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{soil\_type3} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`uscs_symbol`	`str`	Unified Soil Classification System symbol	required

Returns:

Name	Type	Description
`soil_type3`	`str`	Tertiary soil type description

get_thickness

get_thickness(depth)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_thickness}(z) \\ \hspace{1em} \mathbf{if} \ \mathrm{np}.\mathrm{ndim} \mathopen{}\left( z \mathclose{}\right) = 0 \\ \hspace{2em} H \gets z \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} H \gets \mathrm{np}.\mathrm{diff} \mathopen{}\left( \mathrm{np}.\mathrm{r\_}_{\mathopen{}\left( 0, z \mathclose{}\right)} \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ H \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`depth`	`float`	Depth below ground surface to bottom of layer	required

Returns:

Name	Type	Description
`thickness`	`float`	Thickness of soil layer

get_total_stress

get_total_stress(
    unit_weight,
    thickness,
    default_unit_weight=16.0,
    total_stress_inc=0.0,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_total\_stress}(γ, H, γ_{default}, σ_{v\ inc}) \\ \hspace{1em} \mathbf{if} \ \mathrm{np}.\mathrm{any} \mathopen{}\left( \mathrm{np}.\mathrm{isnan} \mathopen{}\left( γ \mathclose{}\right) \mathclose{}\right) \\ \hspace{2em} \mathrm{warnings}.\mathrm{warn} \mathopen{}\left( \textrm{"total\_stress: null unit\_weight values found, will be replaced by \{\}"}.\mathrm{format} \mathopen{}\left( γ_{default} \mathclose{}\right) \mathclose{}\right) \\ \hspace{2em} γ \gets \mathrm{np}.\mathrm{nan\_to\_num} \mathopen{}\left( γ \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} σ_v \gets \mathrm{np}.\mathrm{cumsum} \mathopen{}\left( H \cdot γ \mathclose{}\right) + σ_{v\ inc} \\ \hspace{1em} \mathbf{if} \ \mathrm{np}.\mathrm{ndim} \mathopen{}\left( H \cdot γ \mathclose{}\right) = 0 \\ \hspace{2em} σ_v \gets σ_v.\mathrm{item} \mathopen{}\left( \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ σ_v \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`unit_weight`	`float`	Unit weight of soil	required
`thickness`	`float`	Thickness of soil layer	required
`default_unit_weight`	`float`	Unit weight used for missing or undefined values	`16.0`
`total_stress_inc`	`float`	Total stress in soil increment	`0.0`

Returns:

Name	Type	Description
`total_stress`	`float`	Total vertical stress in soil

get_undrained_shear_strength_ratio

get_undrained_shear_strength_ratio(
    undrained_shear_strength, effective_stress
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_undrained\_shear\_strength\_ratio}(S_u, σ_v') \\ \hspace{1em} S_{u\ ratio} \gets \frac{S_u}{σ_v'} \\ \hspace{1em} \mathbf{return} \ S_{u\ ratio} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
`undrained_shear_strength`	`float`	Undrained shear strength of soil	required
`effective_stress`	`float`	Effective vertical stress in soil	required

Returns:

Name	Type	Description
`undrained_shear_strength_ratio`	`float`	Undrained shear strength to effective stress ratio