geolysis 0.10.3__py3-none-any.whl → 0.12.0__py3-none-any.whl

geolysis/bearing_capacity/ubc/_core.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
-from typing import Annotated
+from dataclasses import dataclass
+from typing import Annotated, Optional
 
 from func_validator import (
     validate_func_args,
@@ -8,40 +9,48 @@ from func_validator import (
 )
 
 from geolysis.foundation import Foundation
-from geolysis.utils import arctan, round_, tan
+from geolysis.utils import arctandeg, round_, tandeg
+
+
+@dataclass(frozen=True, slots=True)
+class UltimateBearingCapacityResult:
+    ultimate_bearing_capacity: float
+    allowable_bearing_capacity: float
+    allowable_applied_load: float
+    n_c: float
+    n_q: float
+    n_gamma: float
+    s_c: float
+    s_q: float
+    s_gamma: float
+    d_c: float
+    d_q: float
+    d_gamma: float
+    i_c: float
+    i_q: float
+    i_gamma: float
 
 
 class UltimateBearingCapacity(ABC):
     def __init__(
-            self,
-            friction_angle: float,
-            cohesion: float,
-            moist_unit_wgt: float,
-            foundation_size: Foundation,
-            apply_local_shear: bool = False,
+        self,
+        friction_angle: float,
+        cohesion: float,
+        moist_unit_wgt: float,
+        foundation_size: Foundation,
+        saturated_unit_wgt: float = 20.5,
+        apply_local_shear: bool = False,
+        factor_of_safety: float = 3.0,
     ) -> None:
         r"""
-
-        $$
-        q_u = cN_c s_c d_c i_c + qN_q s_q d_q i_q
-              + 0.5 \gamma B N_{\gamma} s_{\gamma} d_{\gamma} i_{\gamma}
-        $$
-
-        - $q_u$ (kPa): Ultimate bearing capacity
-        - $c$ (kPa): Cohesion of soil
-        - $q$ (kPa): Overburden pressure of soil
-        - $\gamma$ (kN/m³): Unit weight of soil
-        - $B$ (m): Width of foundation footing
-        - $N_c$, $N_q$, $N_{\gamma}$: Bearing capacity factors
-        - $s_c$, $s_q$, $s_{\gamma}$: Shape factors
-        - $d_c$, $d_q$, $d_{\gamma}$: Depth factors
-        - $i_c$, $i_q$, $i_{\gamma}$: Inclination factors
-
         :param friction_angle: Internal angle of friction for general
                                shear failure (degrees).
         :param cohesion: Cohesion of soil ($kPa$).
         :param moist_unit_wgt: Moist unit weight of soil ($kN/m^3$).
         :param foundation_size: Size of the foundation.
+        :param saturated_unit_wgt: Saturated unit weight of soil ($kN/m^3$).
+        :param factor_of_safety: Factor of safety against bearing
+                                 capacity failure. Added in v0.12.0.
         :param apply_local_shear: Indicate whether bearing capacity
                                   failure is general shear or local
                                   shear failure.
@@ -50,6 +59,8 @@ class UltimateBearingCapacity(ABC):
         self.cohesion = cohesion
         self.moist_unit_wgt = moist_unit_wgt
         self.foundation_size = foundation_size
+        self.saturated_unit_wgt = saturated_unit_wgt
+        self.factor_of_safety = factor_of_safety
         self.apply_local_shear = apply_local_shear
 
     @property
@@ -65,7 +76,7 @@ class UltimateBearingCapacity(ABC):
 
         """
         if self.apply_local_shear:
-            return arctan((2.0 / 3.0) * tan(self._friction_angle))
+            return arctandeg((2.0 / 3.0) * tandeg(self._friction_angle))
         return self._friction_angle
 
     @friction_angle.setter
@@ -80,9 +91,7 @@ class UltimateBearingCapacity(ABC):
 
         In the case of local shear failure:
 
-        $$
-        C^{'} = \dfrac{2}{3} \cdot C
-        $$
+        $$C^{'} = \dfrac{2}{3} \cdot C$$
         """
         if self.apply_local_shear:
             return (2.0 / 3.0) * self._cohesion
@@ -103,6 +112,16 @@ class UltimateBearingCapacity(ABC):
     def moist_unit_wgt(self, val: Annotated[float, MustBePositive]):
         self._moist_unit_wgt = val
 
+    @property
+    def saturated_unit_wgt(self) -> float:
+        """Saturated unit weight of soil ($kN/m^3$)."""
+        return self._saturated_unit_wgt
+
+    @saturated_unit_wgt.setter
+    @validate_func_args
+    def saturated_unit_wgt(self, val: Annotated[float, MustBePositive]):
+        self._saturated_unit_wgt = val
+
     @property
     def load_angle(self):
         """Inclination of the applied load with the  vertical."""
@@ -151,78 +170,107 @@ class UltimateBearingCapacity(ABC):
         depth = self.foundation_size.depth
         water_level = self.foundation_size.ground_water_level
 
-        if water_level is None:
-            water_corr = 1.0  # water correction
-        else:
-            # water level above the base of the foundation
-            a = max(depth - water_level, 0.0)
-            water_corr = min(1 - 0.5 * a / depth, 1)
-
-        # effective overburden pressure (surcharge)
-        eop = self.moist_unit_wgt * depth
-        return eop * self.n_q * self.s_q * self.d_q * self.i_q * water_corr
+        unit_wgt = self.moist_unit_wgt
+        eop = unit_wgt * depth
+        if water_level is not None:
+            if water_level < depth:
+                d_1 = water_level
+                d_2 = depth - d_1
+                unit_wgt = self.saturated_unit_wgt - 9.81
+                eop = self.moist_unit_wgt * d_1 + unit_wgt * d_2
+        return eop * self.n_q * self.s_q * self.d_q * self.i_q
 
     def _embedment_term(self, coef: float = 0.5) -> float:
         depth = self.foundation_size.depth
         width = self.foundation_size.effective_width
         water_level = self.foundation_size.ground_water_level
 
-        if water_level is None:
-            # water correction
-            water_corr = 1.0
-        else:
-            #: b -> water level below the base of the foundation
-            b = max(water_level - depth, 0)
-            water_corr = min(0.5 + 0.5 * b / width, 1)
+        unit_wgt = self.moist_unit_wgt
+
+        if water_level is not None:
+            wgt = self.saturated_unit_wgt - 9.81
+            if water_level < depth:
+                unit_wgt = wgt
+            else:
+                d = water_level - depth
+                if d <= width:
+                    unit_wgt = wgt + (d / width) * (self.moist_unit_wgt - wgt)
 
         return (
-                coef
-                * self.moist_unit_wgt
-                * width
-                * self.n_gamma
-                * self.s_gamma
-                * self.d_gamma
-                * self.i_gamma
-                * water_corr
+            coef
+            * unit_wgt
+            * width
+            * self.n_gamma
+            * self.s_gamma
+            * self.d_gamma
+            * self.i_gamma
         )
 
-    @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
-        """Calculates the ultimate bearing capacity."""
+    def _bearing_capacity(self) -> float:
         return (
-                self._cohesion_term(1.0)
-                + self._surcharge_term()
-                + self._embedment_term(0.5)
+            self._cohesion_term(1.0)
+            + self._surcharge_term()
+            + self._embedment_term(0.5)
         )
 
-    def bearing_capacity_results(self) -> dict:
-        return {
-            "bearing_capacity": self.bearing_capacity(),
-            "n_c": self.n_c,
-            "n_q": self.n_q,
-            "n_gamma": self.n_gamma,
-            "s_c": self.s_c,
-            "s_q": self.s_q,
-            "s_gamma": self.s_gamma,
-            "d_c": self.d_c,
-            "d_q": self.d_q,
-            "d_gamma": self.d_gamma,
-            "i_c": self.i_c,
-            "i_q": self.i_q,
-            "i_gamma": self.i_gamma,
-        }
+    def bearing_capacity_results(self) -> UltimateBearingCapacityResult:
+        """Return a dictionary of bearing capacity results with
+        intermediate calculations.
+
+        !!! info "Added in v0.11.0"
+
+        """
+        return UltimateBearingCapacityResult(
+            ultimate_bearing_capacity=self.ultimate_bearing_capacity(),
+            allowable_bearing_capacity=self.allowable_bearing_capacity(),
+            allowable_applied_load=self.allowable_applied_load(),
+            n_c=self.n_c,
+            n_q=self.n_q,
+            n_gamma=self.n_gamma,
+            s_c=self.s_c,
+            s_q=self.s_q,
+            s_gamma=self.s_gamma,
+            d_c=self.d_c,
+            d_q=self.d_q,
+            d_gamma=self.d_gamma,
+            i_c=self.i_c,
+            i_q=self.i_q,
+            i_gamma=self.i_gamma,
+        )
+
+    @round_(ndigits=1)
+    def ultimate_bearing_capacity(self) -> float:
+        """Calculates the ultimate bearing capacity.
+
+        !!! info "Added in v0.12.0"
+        """
+        return self._bearing_capacity()
+
+    @round_(ndigits=1)
+    def allowable_bearing_capacity(self) -> float:
+        """Calculates the allowable bearing capacity.
+
+        !!! info "Added in v0.12.0"
+        """
+        return self._bearing_capacity() / self.factor_of_safety
+
+    @round_(ndigits=1)
+    def allowable_applied_load(self) -> float:
+        """Calculates the allowable applied load.
+
+        !!! info "Added in v0.12.0"
+        """
+        area = self.foundation_size.foundation_area()
+        return self.allowable_bearing_capacity() * area
 
     @property
     @abstractmethod
-    def n_c(self) -> float:
-        ...
+    def n_c(self) -> float: ...
 
     @property
     @abstractmethod
-    def n_q(self) -> float:
-        ...
+    def n_q(self) -> float: ...
 
     @property
     @abstractmethod
-    def n_gamma(self) -> float:
-        ...
+    def n_gamma(self) -> float: ...

geolysis/bearing_capacity/ubc/_hansen_ubc.py

@@ -1,5 +1,15 @@
 from geolysis.foundation import Shape
-from geolysis.utils import cos, cot, exp, isclose, pi, round_, sin, tan
+from geolysis.utils import (
+    cosdeg,
+    cotdeg,
+    exp,
+    isclose,
+    pi,
+    round_,
+    sindeg,
+    tandeg,
+    add_repr,
+)
 
 from ._core import UltimateBearingCapacity
 
@@ -13,14 +23,16 @@ class HansenBearingCapacityFactors:
     def n_c(friction_angle: float) -> float:
         if isclose(friction_angle, 0.0):
             return 5.14
-        return cot(friction_angle) * (
+        return cotdeg(friction_angle) * (
             HansenBearingCapacityFactors.n_q(friction_angle) - 1.0
         )
 
     @staticmethod
     @round_(ndigits=2)
     def n_q(friction_angle: float) -> float:
-        return tan(45.0 + friction_angle / 2.0) ** 2.0 * exp(pi * tan(friction_angle))
+        return tandeg(45.0 + friction_angle / 2.0) ** 2.0 * exp(
+            pi * tandeg(friction_angle)
+        )
 
     @staticmethod
     @round_(ndigits=2)
@@ -28,7 +40,7 @@ class HansenBearingCapacityFactors:
         return (
             1.8
             * (HansenBearingCapacityFactors.n_q(friction_angle) - 1.0)
-            * tan(friction_angle)
+            * tandeg(friction_angle)
         )
 
 
@@ -95,12 +107,12 @@ class HansenInclinationFactors:
         f_width: float,
         f_length: float,
     ) -> float:
-        return 1.0 - sin(load_angle) / (2.0 * cohesion * f_width * f_length)
+        return 1.0 - sindeg(load_angle) / (2.0 * cohesion * f_width * f_length)
 
     @staticmethod
     @round_(ndigits=2)
     def i_q(load_angle: float) -> float:
-        return 1.0 - (1.5 * sin(load_angle)) / cos(load_angle)
+        return 1.0 - (1.5 * sindeg(load_angle)) / cosdeg(load_angle)
 
     @staticmethod
     @round_(ndigits=2)
@@ -108,143 +120,70 @@ class HansenInclinationFactors:
         return HansenInclinationFactors.i_q(load_angle) ** 2.0
 
 
+@add_repr
 class HansenUltimateBearingCapacity(UltimateBearingCapacity):
-    r"""Ultimate bearing capacity for soils according to `Hansen (1961)`."""
+    r"""Ultimate bearing capacity for soils according to `Hansen (1961)`.
+
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#hansen-bearing-capacity)
+    for more details on bearing capacity equation used.
+
+    """
 
     @property
     def n_c(self) -> float:
-        r"""Bearing capacity factor $N_c$.
-
-        $$
-        N_c = \cot(\phi) \left(N_q - 1\right)
-        $$
-        """
+        r"""Bearing capacity factor $N_c$."""
         return HansenBearingCapacityFactors.n_c(self.friction_angle)
 
     @property
     def n_q(self) -> float:
-        r"""Bearing capacity factor $N_q$.
-
-        $$
-        N_q = \tan^2\left(45 + \frac{\phi}{2}\right) \cdot e^{\pi \tan(\phi)}
-        $$
-        """
+        r"""Bearing capacity factor $N_q$."""
         return HansenBearingCapacityFactors.n_q(self.friction_angle)
 
     @property
     def n_gamma(self) -> float:
-        r"""Bearing capacity factor $N_{\gamma}$.
-
-        $$
-        N_{\gamma} = 1.8 \left(N_q - 1\right) \tan(\phi)
-        $$
-        """
+        r"""Bearing capacity factor $N_{\gamma}$."""
         return HansenBearingCapacityFactors.n_gamma(self.friction_angle)
 
     @property
     def s_c(self) -> float:
-        r"""Shape factor $S_c$.
-
-        $$
-        s_c = 1.0 \rightarrow \text{Strip footing}
-        $$
-
-        $$
-        s_c = 1.0 + 0.2 \frac{B}{L} \rightarrow \text{Rectangular footing}
-        $$
-
-        $$
-        s_c = 1.3 \rightarrow \text{Square or circular footing}
-        $$
-        """
+        r"""Shape factor $S_c$."""
         width, length, shape = self.foundation_size.footing_params()
         return HansenShapeFactors.s_c(width, length, shape)
 
     @property
     def s_q(self) -> float:
-        r"""Shape factor $S_q$.
-
-        $$
-        s_q = 1.0 \rightarrow \text{Strip footing}
-        $$
-
-        $$
-        s_q = 1.0 + 0.2 \cdot \frac{B}{L} \rightarrow \text{Rectangular footing}
-        $$
-
-        $$
-        s_q = 1.2 \rightarrow \text{Square or circular footing}
-        $$
-        """
+        r"""Shape factor $S_q$."""
         width, length, shape = self.foundation_size.footing_params()
         return HansenShapeFactors.s_q(width, length, shape)
 
     @property
     def s_gamma(self) -> float:
-        r"""Shape factor $S_{\gamma}$.
-
-        $$
-        s_{\gamma} = 1.0 \rightarrow \text{Strip footing}
-        $$
-
-        $$
-        s_{\gamma} = 1.0 - 0.4 \frac{B}{L} \rightarrow
-                      \text{Rectangular footing}
-        $$
-
-        $$
-        s_{\gamma} = 0.8 \rightarrow \text{Square footing}
-        $$
-
-        $$
-        s_{\gamma} = 0.6 \rightarrow \text{Circular footing}
-        $$
-        """
+        r"""Shape factor $S_{\gamma}$."""
         width, length, shape = self.foundation_size.footing_params()
         return HansenShapeFactors.s_gamma(width, length, shape)
 
     @property
     def d_c(self) -> float:
-        r"""Depth factor $D_c$.
-
-        $$
-        d_c = 1.0 + 0.35 \cdot \frac{D_f}{B}
-        $$
-        """
+        r"""Depth factor $D_c$."""
         depth = self.foundation_size.depth
         width = self.foundation_size.width
         return HansenDepthFactors.d_c(depth, width)
 
     @property
     def d_q(self) -> float:
-        r"""Depth factor $D_q$.
-
-        $$
-        d_q = 1.0 + 0.35 \cdot \frac{D_f}{B}
-        $$
-        """
+        r"""Depth factor $D_q$."""
         depth = self.foundation_size.depth
         width = self.foundation_size.width
         return HansenDepthFactors.d_q(depth, width)
 
     @property
     def d_gamma(self) -> float:
-        r"""Depth factor $D_{\gamma}$.
-
-        $$
-        d_{\gamma} = 1.0
-        $$
-        """
+        r"""Depth factor $D_{\gamma}$."""
         return HansenDepthFactors.d_gamma()
 
     @property
     def i_c(self) -> float:
-        r"""Inclination factor $I_c$.
-
-        $$
-        I_c = 1 - \frac{\sin(\alpha)}{2cBL}
-        $$
-        """
+        r"""Inclination factor $I_c$."""
         width, length = self.foundation_size.width, self.foundation_size.length
         return HansenInclinationFactors.i_c(
             self.cohesion, self.load_angle, width, length
@@ -252,20 +191,10 @@ class HansenUltimateBearingCapacity(UltimateBearingCapacity):
 
     @property
     def i_q(self) -> float:
-        r"""Inclination factor $I_q$.
-
-        $$
-        I_q = 1 - \frac{1.5 \sin(\alpha)}{\cos(\alpha)}
-        $$
-        """
+        r"""Inclination factor $I_q$."""
         return HansenInclinationFactors.i_q(self.load_angle)
 
     @property
     def i_gamma(self) -> float:
-        r"""Inclination factor $I_{\gamma}$.
-
-        $$
-        I_{\gamma} = I_q^2
-        $$
-        """
+        r"""Inclination factor $I_{\gamma}$."""
         return HansenInclinationFactors.i_gamma(self.load_angle)