Shallow foundation capacity

class groundhog.shallowfoundations.capacity.ShallowFoundationCapacityUndrained(title)

__init__(title)

Generates a ShallowFoundationCapacity object. All shared functionality for drained and undrained analysis is set in this class. The drained and undrained capacity analyses inherit from this class. :param title: Title for the analysis

calculate_bearing_capacity(**kwargs)

Calculates the vertical bearing capacity for undrained (short term) conditions :param kwargs: Additional arguments for the verticalcapacity_undrained_api function (see function documentation) :return: capacity attribute contains the results of the analysis, ultimate_capacity gives the ultimate capacity in kN, net_bearing_pressure gives the net ultimate bearing pressure \(q_u\) in kPa

calculate_envelope(factor_sliding=1.5, factor_bearing=2, **kwargs)

Calculates the bearing capacity envelope for undrained (short term conditions). This envelope describes the interaction between vertical and horizontal load and the resulting VH capacity. The envelope is factored with a factor for vertical bearing capacity (default=2) and a factor for sliding capacity (default=1.5).

This method applied the envelope_undrained_api function.

Parameters:

• factor_sliding – Safety factor for vertical bearing capacity (default=2)

• factor_bearing – Safety factor for sliding capacity (default=1.5)

• kwargs – Optional keyword arguments for the envelope_undrained_api function

Returns:

Sets a number of attributes

• envelope_V_unfactored: V points for the unfactored envelope [kN]

• envelope_H_unfactored: H points for the unfactored envelope [kN]

• envelope_V_factored: V points for the factored envelope [kN]

• envelope_H_factored: H points for the factored envelope [kN]

• envelope_V_uncorrected: V points for the uncorrected envelope (not accounting for effective area component only) [kN]

• envelope_H_uncorrected: H points for the uncorrected envelope (not accounting for effective area component only) [kN]

calculate_sliding_capacity(**kwargs)

Calculates the sliding capacity for undrained (short term) conditions :param kwargs: Additional arguments for the slidingcapacity_undrained_api function (see function documentation) :return: sliding attribute contains the results of the analysis, sliding_base_only gives the sliding capacity at the foundation base \(H_d\) in kN, sliding_full gives the ultimate sliding resistance considering both base sliding and passive resistance \(H_d + \Delta H\) in kN

plot_envelope(showfig=True, plot_title='Undrained bearing capacity envelope', **kwargs)

Plot the undrained bearing capacity envelope using Plotly.

Supplements the method from the parent class with specific statements for undrained conditions.

set_soilparameters_undrained(unit_weight, su_base, su_increase=0.0, su_above_base=nan)

Sets the soil parameters for undrained vertical bearing capacity and horizontal sliding analysis. Note that unit weight is used to assess the stress at base level, so the average unit weight above base level should be used

If the average undrained shear strength above base level is unspecified, the undrained shear strength at base level is used.

Parameters:

• unit_weight – Unit weight of the soil, used to calculate stress at base level (\(\gamma\)) [\(kN/m3\)] - Suggested range: 12<=unit_weight<=22

• su_base – Undrained shear strength at foundation base level (\(S_{uo}\)) [\(kPa\)] - Suggested range: 0.0<=su_base

• su_increase – Linear increase in undrained shear strength (\(\kappa\)) [\(kPa/m\)] (optional, default=0.0) - Suggested range: 0.0<=su_increase

• su_above_base – Average undrained shear strength above base level (\(s_{u,ave}\)) [\(kPa\)] (optional, default=np.nan) - Suggested range: 0.0<=su_above_base

Returns:

Sets the soil parameters for the analysis

class groundhog.shallowfoundations.capacity.ShallowFoundationCapacityDrained(title)

__init__(title)

Generates a ShallowFoundationCapacity object. All shared functionality for drained and undrained analysis is set in this class. The drained and undrained capacity analyses inherit from this class. :param title: Title for the analysis

calculate_bearing_capacity(**kwargs)

Calculates the vertical bearing capacity for drained (long term) conditions :param kwargs: Additional arguments for the verticalcapacity_drained_api function (see function documentation) :return: capacity attribute contains the results of the analysis, ultimate_capacity gives the ultimate capacity in kN, net_bearing_pressure gives the net ultimate bearing pressure \(q_u\) in kPa

calculate_envelope(factor_sliding=1.5, factor_bearing=2, **kwargs)

Calculates the bearing capacity envelope for drained (long term conditions). This envelope describes the interaction between vertical and horizontal load and the resulting VH capacity. The envelope is factored with a factor for vertical bearing capacity (default=2) and a factor for sliding capacity (default=1.5).

This method applied the envelope_drained_api function.

Parameters:

• factor_sliding – Safety factor for vertical bearing capacity (default=2)

• factor_bearing – Safety factor for sliding capacity (default=1.5)

• kwargs – Optional keyword arguments for the envelope_undrained_api function

Returns:

Sets a number of attributes

• envelope_V_unfactored: V points for the unfactored envelope [kN]

• envelope_H_unfactored: H points for the unfactored envelope [kN]

• envelope_V_factored: V points for the factored envelope [kN]

• envelope_H_factored: H points for the factored envelope [kN]

• envelope_V_uncorrected: V points for the uncorrected envelope (not accounting for effective area component only) [kN]

• envelope_H_uncorrected: H points for the uncorrected envelope (not accounting for effective area component only) [kN]

• sliding_cutoff_V: V points for the sliding cutoff [kN]

• sliding_cutoff_H: H points for the sliding cutoff [kN]

• sliding_cutoff_V_factored: V points for the sliding cutoff factored [kN]

• sliding_cutoff_H_factored: H points for the sliding cutoff factored [kN]

calculate_sliding_capacity(vertical_load, interface_frictionangle=nan, **kwargs)

Calculates the sliding capacity for drained (long term) conditions :param kwargs: Additional arguments for the slidingcapacity_drained_api function (see function documentation) :return: sliding attribute contains the results of the analysis, sliding_base_only gives the sliding capacity at the foundation base \(H_d\) in kN, sliding_full gives the ultimate sliding resistance considering both base sliding and passive resistance \(H_d + \Delta H\) in kN

plot_envelope(showfig=True, show_cutoff=True, plot_title='Drained bearing capacity envelope', **kwargs)

Plot the drained bearing capacity envelope using Plotly.

Supplements the method from the parent class with specific statements for undrained conditions.

set_soilparameters_drained(effective_unit_weight, friction_angle, effective_stress_base)

Sets the soil parameters for drained vertical bearing capacity and horizontal sliding analysis. Note that effective unit weight is used. Because the vertical effective stress at base level can be different from the virgin effective stress, it is specified directly

Parameters:

• effective_unit_weight – Effective unit weight of the soil (\(\gamma^{\prime}\)) [\(kN/m3\)] - Suggested range: 2<=effective_unit_weight<=12

• friction_angle – Effective friction angle for the soil below foundation base level (\(\varphi^{\prime}\)) [\(deg\)] - Suggested range: 20<=friction_angle<=50

• effective_stress_base – Vertical effective stress at base (or skirt tip) level (\(\sigma_{v0}^{\prime}\)) [\(kPa\)] - Suggested range: 0.0<=effective_stress_base

Returns:

Sets the soil parameters for the analysis

groundhog.shallowfoundations.capacity.effectivearea_circle_api(foundation_radius, vertical_load=nan, overturning_moment=nan, eccentricity=nan, **kwargs)

Calculates the reduced area for a circular foundation to account for load eccentricity. Eccentricity can either be specified through an overturning moment or with direct specification of eccentricity.

NOTE: In the assessment of eccentricity for shallow foundations on undrained soil, the V can include the weight of soil plug inside the skirts

Parameters:

• foundation_radius – Radius of the circular foundation (\(R\)) [\(m\)] - Suggested range: 0.01<=foundation_radius

• vertical_load – Actual vertical load during relevant loading condition (\(Q\)) [\(kN\)] (optional, default=np.nan) - Suggested range: 0.01<=vertical_load

• overturning_moment – Overturning moment acting on the foundation (\(M\)) [\(kNm\)] (optional, default=np.nan) - Suggested range: 0.0<=overturning_moment

• eccentricity – Eccentricity (direct specification) (\(e_2\)) [\(m\)] (optional, default=np.nan) - Suggested range: 0.0<=eccentricity

\[ \begin{align}\begin{aligned}A^{\prime} = 2s=B^{\prime} L^{\prime}\\L^{\prime}=\left( 2s \sqrt{\frac{R+e_2}{R-e_2}} \right)^{1/2}\\B^{\prime} = L^{\prime} \sqrt{\frac{R-e_2}{R+e_2}}\\s = \frac{\pi R^2}{2}-[e_2 \cdot (\sqrt{R^2-e_2^2}) + R^2 \arcsin(\frac{e_2}{R})]\end{aligned}\end{align} \]

Returns:

Effective area used for capacity calculation (\(A^{\prime}\)) [\(m2\)], Effective length (\(L^{\prime}\)) [\(m\)], Effective width (\(B^{\prime}\)) [\(m\)], Parameter s (\(s\)) [\(m2\)], Eccentricity used for the calculation (\(e_2\)) [\(m\)]

Return type:

Python dictionary with keys [‘effective_area [m2]’,’effectve length [m]’,’effective_width [m]’,’s [m2]’,’eccentricity [m]’]

Reduced area for a circular foundation

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.effectivearea_rectangle_api(length, width, vertical_load=nan, moment_length=nan, moment_width=nan, eccentricity_length=nan, eccentricity_width=nan, **kwargs)

Calculates the reduced area of a rectangular footing to account for eccentricty of the load. Eccentricities can either be specified from a moment or defined directly.

NOTE: In the assessment of eccentricity for shallow foundations on undrained soil, the V can include the weight of soil plug inside the skirts

Parameters:

• length – Longest foundation dimension (\(L\)) [\(m\)] - Suggested range: 0.0<=length

• width – Shortest foundation dimension (\(B\)) [\(m\)] - Suggested range: 0.0<=width

• vertical_load – Actual vertical load during relevant loading condition (\(Q\)) [\(kN\)] (optional, default=np.nan) - Suggested range: 0.001<=vertical_load

• moment_length – Overturning moment aligned with longest foundation dimension (\(M_1\)) [\(kNm\)] (optional, default=np.nan) - Suggested range: 0.0<=moment_length

• moment_width – Overturning moment aligned with shortest foundation dimension (\(M_2\)) [\(kNm\)] (optional, default=np.nan) - Suggested range: 0.0<=moment_width

• eccentricity_length – Eccentricity (direct specification) in the longest foundation direction (\(e_1\)) [\(m\)] (optional, default=np.nan) - Suggested range: 0.0<=eccentricity_length

• eccentricity_width – Eccentricity (direct specification) in the shortest foundation direction (\(e_2\)) [\(m\)] (optional, default=np.nan) - Suggested range: 0.0<=eccentricity_width

\[ \begin{align}\begin{aligned}e_1 = \frac{M_1}{Q}\\e_2 = \frac{M_2}{Q}\\L^{\prime} = L - 2 \cdot e_1\\B^{\prime} = B - 2 \cdot e_2\\A^{\prime} = B^{\prime} \cdot L^{\prime}\end{aligned}\end{align} \]

Returns:

Effective area used to calculate mudmat capacity (\(A^{\prime}\)) [\(m2\)], Effective length (\(L^{\prime}\)) [\(m\)], Effective width (\(B^{\prime}\)) [\(m\)], Eccentricity in the length direction (\(e_1\)) [\(m\)], Eccentricity in the width direction (\(e_2\)) [\(m\)]

Return type:

Python dictionary with keys [‘effective_area [m2]’,’effective_length [m]’,’effective_width [m]’,’eccentricity_length [m]’,’eccentricity_width [m]’]

Effective area of a rectangular mudmat

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.envelope_drained_api(vertical_effective_stress, effective_friction_angle, effective_unit_weight, effective_length, effective_width, full_area, factor_sliding=1.5, factor_bearing=2.0, effective_friction_angle_sliding=nan, **kwargs)

Calculates a drained failure envelope for shallow foundations according to API RP 2GEO. Note that optional keyword arguments can be specified as documented in the function verticalcapacity_drained_api.

The envelope is calculated be varying the inclination of the load. Note that the equation for inclination factor will become negative for large inclinations. These values are filtered from the envelope.

We derive the ultimate horizontal load in bearing from the equation for inclination but need to remember that this should only account for the horizontal capacity on the effective area.

A sliding cut-off is also calculated based on the ultimate sliding resistance.

Parameters:

• vertical_effective_stress – Vertical effect stress at depth corresponding to foundation base (\(p_o^{\prime}\)) [\(kPa\)] - Suggested range: 0.0<=vertical_effective_stress

• effective_friction_angle – Effective friction angle for bearing failure (for appropriate stress level at foundation base) (\(\phi^{\prime}\)) [\(deg\)] - Suggested range: 20.0<=effective_friction_angle<=50.0

• effective_unit_weight – Effective unit weight at foundation base (\(\gamma^{\prime}\)) [\(kN/m3\)] - Suggested range: 3.0<=effective_unit_weight<=12.0

• effective_length – Effective length of the footing (\(L^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_length

• effective_width – Minimum effective lateral dimension (\(B^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_width

• full_area – Full base area of the foundation (\(A_b\)) [\(m^2\)] - Suggested range: 0.0<=full_area

• width – Minimum true lateral dimension (\(B\)) [\(m\)] - Suggested range: 0.0<=width

• factor_sliding – Resistance factor for sliding, applied to the H component of the sliding cutoff (\(\gamma_{sliding}\)) [\(-\)] - Suggested range: factor_sliding >= 1.0 (optional, default= 1.5)

• factor_bearing – Resistance factor for bearing failure, applied to the V component of the envelope (\(\gamma_{bearing}\)) [\(-\)] - Suggested range: factor_bearing >= 1.0 (optional, default= 2.0)

• effective_friction_angle_sliding – Effective friction angle for sliding failure (for appropriate stress level at foundation base). If unspecified, the effective friction angle of soil - 5° is used (\(\delta^{\prime}\)) [\(deg\)] - Suggested range: 15.0<=effective_friction_angle<=45.0

\[\tan(\text{inclination}) = \frac{H_{eff}}{Q} = \frac{H - H_{\text{outside eff}} - \Delta H}{Q}\]

Returns:

Dictionary with the following keys:

• ’Envelope V unfactored [kN]’: Unfactored vertical capacities for the envelope (\(V\)) [\(kN\)]

• ’Envelope H unfactored [kN]’: Unfactored horizontal capacities for the envelope (\(H^{\prime}\)) [\(kN\)]

• ’Envelope V factored [kN]’: Factored vertical capacities for the envelope (\(V / \gamma_v\)) [\(kN\)]

• ’Envelope H factored [kN]’: Factored horizontal capacities for the envelope (\(H / \gamma_h\)) [\(kN\)]

• ’Envelope V uncorrected [kN]’: Vertical capacities for the envelope without accounting for effective area component only (\(V\)) [\(kN\)]

• ’Envelope H uncorrected [kN]’: Horizontal capacities for the envelope without accounting for effective area component only (\(H\)) [\(kN\)]

• ’Sliding cutoff V [kN]’: Vertical capacities for sliding cutoff [\(kN\)]

• ’Sliding cutoff H [kN]’: Horizontal capacities for sliding cutoff [\(kN\)]

Reference - API RP 2GEO

groundhog.shallowfoundations.capacity.envelope_undrained_api(su_base, full_area, effective_length, effective_width, factor_sliding=1.5, factor_bearing=2.0, **kwargs)

Calculates the undrained failure envelope according to API RP 2GEO. It is important to note than only the horizontal load acting on the effective area is taken into account for the envelope. To achieve this, the horizontal load points for the envelope are selected between 0 and the total horizontal capacity (including contributions from skirt resistance and total base area).

Subsequently, a load inclination is calculated using only the effective area component of this horizontal load (subtract skirt resistance and horizontal capacity outside effective area). This inclination is used in the vertical capacity equation (through the inclination factor).

The envelope is calculated twice, first without correction for additional eccentricity at base level and next with a correction for this additional eccentricity. This two step approach is required since the load inclination is not known a priori.

To override the behaviour of the bearing and sliding capacity functions, use the optional keywords arguments defined in the function definitions of slidingcapacity_undrained_api and verticalcapacity_undrained_api

Parameters:

• su_base – Undrained shear strength at the foundation base (\(S_{uo}\)) [\(kPa\)] - Suggested range: 0.0 <= su_base <= 1000.0

• full_area – Total area at the base length (\(A_b\)) [\(m^2\)] - Suggested range: full_area >= 0.0

• effective_length – Effective length (\(L^{\prime}\)) [\(m\)] - Suggested range: effective_length >= 0.0

• effective_width – Effective width (\(B^{\prime}\)) [\(m\)] - Suggested range: effective_width >= 0.0

• factor_sliding – Resistance factor for sliding, applied to the H component of the envelope (\(\gamma_{sliding}\)) [\(-\)] - Suggested range: factor_sliding >= 1.0 (optional, default= 1.5)

• factor_bearing – Resistance factor for bearing failure, applied to the V component of the envelope (\(\gamma_{bearing}\)) [\(-\)] - Suggested range: factor_bearing >= 1.0 (optional, default= 2.0)

\[\Delta e = D \cdot \tan \theta\]

Returns:

Dictionary with the following keys:

• ’Envelope V unfactored [kN]’: List with unfactored vertical capacities for the envelope (\(V\)) [\(kN\)]

• ’Envelope H unfactored [kN]’: List with unfactored horizontal capacities for the envelope (\(H\)) [\(kN\)]

• ’Envelope V factored [kN]’: List with factored vertical capacities for the envelope (\(V_{factored}\)) [\(kN\)]

• ’Envelope H factored [kN]’: List with factored horizontal capacities for the envelope (\(H_{factored}\)) [\(kN\)]

• ’Envelope V uncorrected [kN]’: List with vertical capacities for the envelope, not corrected for the additional eccentricity (\(V_{uncorrected}\)) [\(kN\)]

• ’Envelope H uncorrected [kN]’: List with horizontal capacities for the envelope, not corrected for the additional eccentricity (\(H_{uncorrected}\)) [\(kN\)]

• ’Sliding capacity’: Dictionary with details for the sliding capacity calculation

• ’Bearing capacity’: Dictionary with details for the bearing capacity calculation for purely vertical load

Undrained failure envelope

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.failuremechanism_prandtl(friction_angle, width, showfig=True, **kwargs)

Calculates the shape of the Prandtl failure mechanism for a given friction angle. The failure mechanisms consists of a cone-shaped wedge which is pushed into the soil and a log-spiral extending from the edge of the cone to a line perpendicular to it. Another triangular wedge is formed between the log-spiral and the surface.

This procedure calculates the failure mechanism as a series of (X, Y) points. Only the outer edge for the right-hand side of the figure is taken. The left-hand side can easily be obtained by flipping the figure along the Y-axis.

A Plotly plot with fixed aspect ratio is shown by default but the generation of this plot can be disables using the showfig boolean.

Parameters:

• friction_angle – Sand angle of internal friction (\(\varphi^{\prime}\)) [\(deg\)] - Suggested range: 0.0 <= friction_angle <= 60.0

• width – Width of the footing (full width) (\(B\)) [\(m\)] - Suggested range: width >= 0.0

• showfig – Boolean determining whether the plot of the failure surface is shown (optional, default= True)

\[ \begin{align}\begin{aligned}\theta = \frac{\pi}{4} + \frac{\varphi^{\prime}}{2}\\r = r_0 \cdot e^{\frac{\pi}{2} \tan \varphi^{\prime}}\end{aligned}\end{align} \]

Returns:

Dictionary with the following keys:

• ’X [m]’: List with X-coordinates of the points forming the failure surface (\(X\)) [\(m\)]

• ’Y [m]’: List with Y-coordinates of the points forming the failure surface (\(Y\)) [\(m\)]

• ’fig’: Plotly figure showing the failure surface

Prandtl failure surface (after Budhu, 2010)

Reference - Budhu (2010). Soil Mechanics and Foundations

groundhog.shallowfoundations.capacity.ngamma_frictionangle_davisbooker(friction_angle, roughness_factor, multiplier_smooth=0.0663, multiplier_rough=0.1054, multiplier_exp_smooth=9.3, multiplier_exp_rough=9.6, **kwargs)

Calculates the bearing capacity factor Ngamma according to the equation proposed by Davis and Booker (1971). This formulation is based on a more refined plasticity method and takes the roughness into account. This method is preferred in principle.

Parameters:

• friction_angle – Peak drained friction angle (\(\phi_p^{\prime}\)) [\(deg\)] - Suggested range: 20.0 <= friction_angle <= 50.0

• roughness_factor – Footing roughness factor where 0 is fully smooth and 1 is fully rough (\(R_{inter}\)) [\(-\)] - Suggested range: 0.0 <= roughness_factor <= 1.0

• multiplier_smooth – Multiplier for smooth footings (\(\alpha_1\)) [\(-\)] (optional, default= 0.0663)

• multiplier_rough – Multiplier for rough footings (\(\alpha_2\)) [\(-\)] (optional, default= 0.1054)

• multiplier_exp_smooth – Multiplier on exponential term for smooth footings (\(\alpha_3\)) [\(-\)] (optional, default= 9.3)

• multiplier_exp_rough – Multiplier on exponential term for roughfootings (\(\alpha_4\)) [\(-\)] (optional, default= 9.6)

\[\begin{split}N_{\gamma} = \begin{cases} 0.1054 \exp (9.6 \phi_p^{\prime}) & \quad \text{for rough footings}\\ 0.0663 \exp(9.3 \phi_p^{\prime}) & \quad \text{for smooth footings} \end{cases}\end{split}\]

Returns:

Dictionary with the following keys:

• ’Ngamma [-]’: Bearing capacity factor (\(N_{\gamma}\)) [\(-\)]

• ’Ngamma_smooth [-]’: Bearing capacity factor for smooth footing (\(N_{\gamma,smooth}\)) [\(-\)]

• ’Ngamma_rough [-]’: Bearing capacity factor for rough footing (\(N_{\gamma,rough}\)) [\(-\)]

Reference - Budhu (2011) Introduction to soil mechanics and foundations

groundhog.shallowfoundations.capacity.ngamma_frictionangle_meyerhof(friction_angle, frictionangle_multiplier=1.4, **kwargs)

Calculates the bearing capacity factor Ngamma according to the equation proposed by Meyerhof (1976). This formulation is more conservative compared to the Vesic formulation.

Parameters:

• friction_angle – Peak drained friction angle (\(\phi_p^{\prime}\)) [\(deg\)] - Suggested range: 20.0 <= friction_angle <= 50.0

• frictionangle_multiplier – Multiplier on the friction angle (\(\alpha_1\)) [\(-\)] (optional, default= 1.4)

\[N_{\gamma} = (N_q - 1) \tan (1.4 \phi_p^{\prime})\]

Returns:

Dictionary with the following keys:

• ’Ngamma [-]’: Bearing capacity factor (\(N_{\gamma}\)) [\(-\)]

Reference - Budhu (2011) Introduction to soil mechanics and foundations

groundhog.shallowfoundations.capacity.ngamma_frictionangle_vesic(friction_angle, **kwargs)

Calculates the bearing capacity factor Ngamma according to the equation proposed by Vesic (1973). Note that alternative formulations are available.

Parameters:

friction_angle – Peak drained friction angle (\(\phi_p^{\prime}\)) [\(deg\)] - Suggested range: 20.0 <= friction_angle <= 50.0

\[N_{\gamma} = 2 (N_q + 1) \tan \phi_p^{\prime}\]

Returns:

Dictionary with the following keys:

• ’Ngamma [-]’: Bearing capacity factor (\(N_{\gamma}\)) [\(-\)]

Reference - Budhu (2011) Introduction to soil mechanics and foundations

groundhog.shallowfoundations.capacity.nq_frictionangle_sand(friction_angle, **kwargs)

Calculate the bearing capacity factor Nq from the friction angle

Parameters:

friction_angle – Peak effective friction angle (\(\phi_p^{\prime}\)) [\(deg\)] - Suggested range: 20.0 <= friction_angle <= 50.0

\[N_q = e^{\pi \tan \phi_p^{\prime}} \tan^2 \left( 45^{\circ} + \frac{ \phi_p^{\prime}}{2} \right)\]

Returns:

Dictionary with the following keys:

• ’Nq [-]’: Bearing capacity factor (\(N_q\)) [\(-\)]

Reference - Budhu (2011) Introduction to soil mechanics and foundations

groundhog.shallowfoundations.capacity.slidingcapacity_drained_api(vertical_load, effective_friction_angle, effective_unit_weight, embedded_section_area=0.0, depth_to_base=0.0, reaction_factor_override=nan, **kwargs)

Calculates the drained sliding capacity for a shallow foundation. The base resistance is increased for passive and active soil resistance derived from skirts.

Parameters:

• vertical_load – Actual vertical load during relevant loading condition (\(Q\)) [\(kN\)] - Suggested range: 0.0<=vertical_load

• effective_friction_angle – Effective friction angle (for appropriate stress level at foundation base) (\(\phi^{\prime}\)) [\(deg\)] - Suggested range: 20.0<=effective_friction_angle<=50.0

• effective_unit_weight – Effective unit weight (\(\gamma^{\prime}\)) [\(kN/m3\)] - Suggested range: 3.0<=effective_unit_weight<=12.0

• embedded_section_area – Embedded vertical cross-sectional area of foundation (\(A_h\)) [\(m2\)] (optional, default=0.0) - Suggested range: 0.0<=embedded_section_area

• depth_to_base – Depth below seafloor to base level (\(D_b\)) [\(m\)] (optional, default=0.0) - Suggested range: 0.0<=depth_to_base

• reaction_factor_override – Drained horizontal reaction factor (\(K_{rd}\)) [\(-\)] (optional, default=np.nan) - Suggested range: 0.0<=reaction_factor_override

\[ \begin{align}\begin{aligned}H_d^{\prime} = Q \cdot \tan \phi^{\prime}\\\Delta H = 0.5 \cdot K_{rd} \cdot \gamma^{\prime} \cdot D_b \cdot A_h\\K_{rd} = K_p - (1/K_p)\\K_p = \tan^2 (45^{\circ} + 0.5 \phi^{\prime})\end{aligned}\end{align} \]

Returns:

Combined sliding capacity due to base and skirt resistance (\(H_d + \Delta H\)) [\(kN\)], Sliding resistance due to base friction (\(H_d\)) [\(kN\)], Sliding resistance due to active and passive resistance of the skirts (\(\Delta H\)) [\(kN\)], Reaction factor (\(K_{rd}\)) [\(-\)], Passive resistance factor (\(K_p\)) [\(-\)]

Return type:

Python dictionary with keys [‘sliding_capacity [kN]’,’base_capacity [kN]’,’skirt_capacity [kN]’,’K_rd [-]’,’K_p [-]’]

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.slidingcapacity_undrained_api(su_base, foundation_area, su_above_base=0.0, embedded_section_area=0.0, soil_reaction_coefficient=4.0, **kwargs)

Calculates the undrained sliding capacity for a shallow foundation on clay, the contribution of skirt resistance is taken into account.

Parameters:

• su_base – Undrained shear strength at foundation base level (\(S_{uo}\)) [\(kPa\)] - Suggested range: 0.0<=su_base

• foundation_area – Actual foundation area (not the effective area!) (\(A\)) [\(m2\)] - Suggested range: 0.0<=foundation_area

• su_above_base – Average undrained shear strength along the skirt depth (\(S_{u,ave}\)) [\(kPa\)] (optional, default=0.0) - Suggested range: 0.0<=su_skirts

• embedded_section_area – Embedded vertical cross-sectional area of foundation (\(A_h\)) [\(m2\)] (optional, default=0.0) - Suggested range: 0.0<=embedded_section_area

• soil_reaction_coefficient – Soil reaction coefficient Kru. A value of 4 is recommended for full contact. If active soil resistance cannot be relied upon, the factor should be reduced to 2 (\(K_{ru}\)) [\(-\)] (optional, default=4.0) - Suggested range: 1.0<=soil_reaction_coefficient<=6.0

\[ \begin{align}\begin{aligned}H_d = S_{uo} \cdot A\\\Delta H = K_{ru} \cdot (S_{u,ave}) \cdot A_h\end{aligned}\end{align} \]

Returns:

Sliding capacity (combined) (\(H_d + \Delta H\)) [\(kN\)], Sliding resistance on the foundation base (\(H_d\)) [\(kN\)], Sliding resistance due to active and passive resistance of the skirts (\(\Delta H\)) [\(kN\)]

Return type:

Python dictionary with keys [‘sliding_capacity [kN]’,’base_resistance [kN]’,’skirt_resistance [kN]’]

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.verticalcapacity_drained_api(vertical_effective_stress, effective_friction_angle, effective_unit_weight, effective_length, effective_width, base_depth=0.0, skirted=True, load_inclination=0.0, foundation_inclination=0.0, ground_surface_inclination=0.0, **kwargs)

Calculates the vertical capacity for a shallow foundation in sand with effective friction angle characterized from drained triaxial tests. For constructing an envelope, this value needs to be multiplied by the tangent of the inclination to obtain the H-coordinate of the envelope point.

The correction factor consists of a shape factor, a depth factor and three inclination factors for both \(K_q\) and \(K_gamma\).

NOTE: \(H/Q\) corresponds to the tangent of the load inclination. For constructing an envelope, load inclinations should be varied from 0.0 to 90.0

NOTE: The relevancy of using the depth factors should be evaluated in each case. If the installation procedure and/or other foundation aspects, such as scour, do not allow for the required mobilization of shear stresses in the soil above foundation base level, it is recommended that depth factors are set to zero. In particular, it is recommended that d = 0 if the horizontal load leads to mobilization of significant passive earth pressure between seafloor and foundation base level.

NOTE: \(H\) in the equation for inclination factor refers to the load applied to the effective area component of the base only. This corresponds to the total lateral load applied to the foundation minus any soil resistance acting on the foundation above skirt tip level as outlined in A.7.2.1, and minus any lateral resistance that may be carried by shearing at skirt tip level outside the effective area.

NOTE: For embedded foundations, the eccentricity is affected by the load inclination and increases with embedment. The modified eccentricity is found by calculating the intersection between the loading direction and the base depth level.

NOTE: For non-skirted, base embedded foundations, the contribution of overburden pressure needs to be taken into account. In the equations in the standard, (Nq - 1) needs to be replaced by Nq

Parameters:

• vertical_effective_stress – Vertical effect stress at depth corresponding to foundation base (\(p_o^{\prime}\)) [\(kPa\)] - Suggested range: 0.0<=vertical_effective_stress

• effective_friction_angle – Effective friction angle (for appropriate stress level at foundatoin base) (\(\phi^{\prime}\)) [\(deg\)] - Suggested range: 20.0<=effective_friction_angle<=50.0

• effective_unit_weight – Effective unit weight at foundation base (\(\gamma^{\prime}\)) [\(kN/m3\)] - Suggested range: 3.0<=effective_unit_weight<=12.0

• effective_length – Effective length of the footing (\(L^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_length

• effective_width – Minimum effective lateral dimension (\(B^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_width

• base_depth – Depth of the foundation base (\(D\)) [\(m\)] (optional, default=0.0) - Suggested range: 0.0<=base_depth

• skirted – Determines whether a foundation is skirted or base-embedded without skirts (optional, default=True)

• load_inclination – Inclination of the load taking into account horizontal load on effective area of base only (\(H^{\prime}\)) [\(deg\)] (optional, default=0.0) - Suggested range: 0.0<=load_inclination

• foundation_inclination – Foundation inclination as defined in figure (\(\nu\)) [\(deg\)] (optional, default=0.0) - Suggested range: -90.0<=foundation_inclination<=90.0

• ground_surface_inclination – Ground surface inclination as defined in figure (\(\beta\)) [\(deg\)] (optional, default=0.0) - Suggested range: -90.0<=ground_surface_inclination<=90.0

\[ \begin{align}\begin{aligned}q_u = p_o^{\prime} (N_q - 1) K_q + 0.5 \gamma^{\prime} B^{\prime} N_{\gamma} K_{\gamma}\\Q_d^{\prime} = \left[ p_o^{\prime} (N_q - 1) K_q + 0.5 \gamma^{\prime} B^{\prime} N_{\gamma} K_{\gamma} \right] A^{\prime}\\\text{Use } N_q \text{ instead of } (N_q - 1) \text{ for non-skirted, base embedded foundations}\\N_q = \exp \left [ \pi \tan \phi^{\prime} \right ] (\tan^2 (45^{\circ} + \phi^{\prime}/2))\\N_{\gamma} = 1.5 \left ( N_q - 1 \right) \tan \phi^{\prime}\\K_q = i_q \cdot s_q \cdot d_q \cdot b_q \cdot g_q\\K_{\gamma} = i_{\gamma} \cdot s_{\gamma} \cdot d_{\gamma} \cdot b_{\gamma} \cdot g_{\gamma}\\i_q = \left [ 1 -0.5 (H/Q) \right]^5\\i_{\gamma} = \left[ 1-0.7 (H/Q) \right]^5\\s_q = 1+i_q ( B^{\prime} / L^{\prime} ) \sin \phi^{\prime}\\s_{\gamma} = 1 - 0.4 i_{\gamma} ( B^{\prime} / L^{\prime} )\\d_q = 1 + 1.2 (D/B^{\prime}) \tan \phi^{\prime} (1 - \sin \phi^{\prime})^2\\d_{\gamma} = 1\\b_q = e^{-2 \nu \tan \phi^{\prime}}\\b_{\gamma} = e^{-2.7 \nu \tan \phi^{\prime}}\\g_q = g_{\gamma} = (1 - 0.5 \tan \beta)^5\end{aligned}\end{align} \]

Returns:

Vertical capacity of the footing (\(Q_d\)) [\(kN\)], Bearing capacity factor for frictional resistance (\(N_q\)) [\(-\)], Bearing capacity factor for unit weight (\(N_{\gamma}\)) [\(-\)], Combined correction factor for frictional resistance (\(K_q\)) [\(-\)], Combined correction factor for unit weight (\(K_{\gamma}\)) [\(-\)], Shape factor frictional (\(s_q\)) [\(-\)], Shape factor unit weight (\(s_{\gamma}\)) [\(-\)], Depth factor frictional (\(d_q\)) [\(-\)], Depth factor unit weight (\(d_{\gamma}\)) [\(-\)], Inclination factor frictional (\(i_q\)) [\(-\)], Inclination factor unit weight (\(i_{\gamma}\)) [\(-\)], Foundation inclination factor frictional (\(b_q\)) [\(-\)], Foundation inclination factor unit weight (\(b_{\gamma}\)) [\(-\)], Soil surface inclination factor frictional (\(g_q\)) [\(-\)], Soil surface inclination factor unit weight (\(g_gamma\)) [\(-\)]

Return type:

Python dictionary with keys [‘vertical_capacity [kN]’,’N_q [-]’,’N_gamma [-]’,’K_q [-]’,’K_gamma [-]’,’s_q [-]’,’s_gamma [-]’,’d_q [-]’,’d_gamma [-]’,’i_q [-]’,’i_gamma [-]’,’b_q [-]’,’b_gamma [-]’,’g_q [-]’,’g_gamma [-]’]

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations

groundhog.shallowfoundations.capacity.verticalcapacity_undrained_api(effective_length, effective_width, su_base, su_increase=0.0, su_above_base=nan, base_depth=0.0, skirted=True, base_sigma_v=0.0, roughness=0.67, horizontal_load=0.0, foundation_inclination=0.0, ground_surface_inclination=0.0, bearing_capacity_factor=5.14, factor_f_override=nan, **kwargs)

Calculates the vertical capacity for a shallow foundation in clay with constant or linearly increasing undrained shear strength according to API RP 2GEO.

The correction factor consists of a shape factor, a depth factor and three inclination factors. In the case of linearly increasing shear strenght, an additional factor F is used which can either be calculated from the foundation roughness (default) or specified directly.

NOTE: The relevancy of using the depth factor (\(d_c\)) should be evaluated in each case. If the installation procedure and/or other foundation aspects, such as scour, do not allow for the required mobilization of shear stresses in the soil above foundation base level, it is recommended that (\(d_c\)) = 0. In particular, it is recommended that (\(d_c\)) = 0 if the horizontal load leads to mobilization of significant passive earth pressure between seafloor and foundation base level.

NOTE: (\(H^{\prime}\)) in the equation for inclination factor refers to the load applied to the effective area component of the base only. This corresponds to the total lateral load applied to the foundation minus any soil resistance acting on the foundation above skirt tip level as outlined in A.7.2.1, and minus any lateral resistance that may be carried by shearing at skirt tip level outside the effective area. This value is an input to the function.

NOTE: For embedded foundations, the eccentricity is affected by the load inclination and increases with embedment. The modified eccentricity is found by calculating the intersection between the loading direction and the base depth level.

NOTE: For skirted foundations, a separate assessment is required to check whether the skirt spacing is small enough to rely on the undrained shear strenght at skirt tip level.

NOTE: In the assessment for non-skirted, base embedded foundation, the overburden pressure needs to be included in the vertical capacity assessment

Parameters:

• effective_length – Effective length of the foundation (\(L^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_length

• effective_width – Minimum effective lateral dimension (\(B^{\prime}\)) [\(m\)] - Suggested range: 0.0<=effective_width

• su_base – Undrained shear strength at foundation base level (\(S_{uo}\)) [\(kPa\)] - Suggested range: 0.0<=su_base

• su_increase – Linear increase in undrained shear strength (\(\kappa\)) [\(kPa/m\)] (optional, default=0.0) - Suggested range: 0.0<=su_increase

• su_above_base – Average undrained shear strength above base level (\(s_{u,ave}\)) [\(kPa\)] (optional, default=np.nan) - Suggested range: 0.0<=su_above_base

• base_depth – Depth to the base of the foundation (\(D\)) [\(m\)] (optional, default=0.0) - Suggested range: 0.0<=base_depth

• skirted – Determines whether a foundation is skirted or base-embedded without skirts (optional, default=True)

• base_sigma_v – Vertical total stress at base level. Only used for non-skirted base-embedded foundations (\(\sigma_{vo}\)) [\(kPa\)] (optional, default=0.0)

• roughness – Value for roughness (0.0 for fully smooth, 1.0 for fully rough) (\(-\)) [\(-\)] (optional, default=0.67) - Suggested range: 0.0<=roughness<=1.0

• horizontal_load – Horizontal load acting on effective area of foundation (\(H^{\prime}\)) [\(kN\)] (optional, default=0.0) - Suggested range: 0.0<=horizontal_load

• foundation_inclination – Foundation inclination as defined in figure (\(\nu\)) [\(deg\)] (optional, default=0.0) - Suggested range: -90.0<=foundation_inclination<=90.0

• ground_surface_inclination – Ground surface inclination as defined in figure (\(\beta\)) [\(deg\)] (optional, default=0.0) - Suggested range: -90.0<=ground_surface_inclination<=90.0

• bearing_capacity_factor – Bearing capacity factor (\(N_c\)) [\(-\)] (optional, default=5.14) - Suggested range: 3.0<=bearing_capacity_factor<=12.0

• factor_f_override – Direct specification of the factor F (\(F\)) [\(-\)] (optional, default=np.nan) - Suggested range: 0.0<=factor_f_override<=2.0

\[ \begin{align}\begin{aligned}q_u = s_u \cdot N_c \cdot K_c \quad \text{ (constant)}\\q_u = F \cdot \left( s_{uo} \cdot N_c + \frac{\kappa \cdot B^{\prime}}{4} \right) \cdot K_c \quad \text{ (linearly increasing) }\\Q_d = (s_u \cdot N_c \cdot K_c + \sigma_{vo}) \cdot A^{\prime} \quad \text{ (constant)}\\Q_d = \left[ F \cdot \left( s_{uo} \cdot N_c + \frac{\kappa \cdot B^{\prime}}{4} \right) \cdot K_c + \sigma_{vo} \right] \cdot A^{\prime} \quad \text{ (linearly increasing) }\\\text{Exclude the } \sigma_{vo} \text{ term for skirted foundations}\\K_c = 1 + s_c + d_c - i_c - b_c - g_c\\\text{Correction factors constant undrained shear strength}\\s_c = 0.18 \cdot (1 - 2 \cdot i_c) \cdot (B^{\prime} / L^{\prime})\\d_c = 0.3 \cdot \arctan ( D / B^{\prime})\\i_c = 0.5 - 0.5 \cdot [1 - H^{\prime} / (A^{\prime} \cdot s_u)]^{0.5}\\b_c = 2 \cdot \nu / (\pi + 2) \approx 0.4 \cdot \nu\\g_c = 2 \cdot \beta / (\pi + 2) \approx 0.4 \cdot \beta\\\text{Correction factors linearly increasing undrained shear strength}\\F \approx a + b \cdot x - ((c + b \cdot x)^2 + d^2)^{0.5}\\x = \frac{\kappa \cdot B^{\prime}}{s_{uo}}\\s_c = s_{cv} (1 - 2 \cdot i_c) (B^{\prime} / L^{\prime})\\d_c = 0.3 \cdot (s_{u,ave} / s_{u,2}) \cdot \arctan( D / B^{\prime})\\s_{u,2} = F \cdot (N_c \cdot s_{uo} + \kappa \cdot B^{\prime} / 4) / N_c\\i_c = 0.5 - 0.5 \cdot [1 -H^{\prime}/(A^{\prime} \cdot s_u)]^{0.5}\\b_c = 2 \cdot \nu / (\pi + 2) \approx 0.4 \cdot \nu\\g_c = 2 \cdot \beta / (\pi + 2) \approx 0.4 \cdot \beta\\\text{Correction for horizontal load}\\H^{\prime} = H_{total} - H_{d,outside} / \gamma_{sliding} - \Delta H / \gamma_{sliding}\end{aligned}\end{align} \]

Returns:

Net bearing pressure (\(q_u\)) [\(kPa\)], Vertical capacity (\(Q_d\)) [\(kN\)], Combined correction factor (\(K_c\)) [\(-\)], Shape factor (\(s_c\)) [\(-\)], Depth factor (\(d_c\)) [\(-\)], Load inclination factor (\(i_c\)) [\(-\)], Foundation inclination factor (\(b_c\)) [\(-\)], Ground inclination factor (\(g_c\)) [\(-\)], Correction factor for shear strength increase (\(F\)) [\(-\)]

Return type:

Python dictionary with keys [‘qu [kPa]’, ‘vertical_capacity [kN]’,’K_c [-]’,’s_c [-]’,’d_c [-]’,’i_c [-]’,’b_c [-]’,’g_c [-]’,’F [-]’]

API correction factors for linear shear strength increase

API inclination factor definition

Reference - API RP 2GEO, 2011. API RP 2GEO Geotechnical and Foundation Design Considerations