geolysis 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

geolysis/bearing_capacity/ubc/_core.py

@@ -1,24 +1,46 @@
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from typing import Annotated
 
 from func_validator import (
-    validate_func_args,
+    validate_params,
     MustBeNonNegative,
     MustBePositive,
 )
 
 from geolysis.foundation import Foundation
-from geolysis.utils import arctan, round_, tan
+from geolysis.utils import arctandeg, round_, tandeg, isinf
+
+
+@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"""
         :param friction_angle: Internal angle of friction for general
@@ -26,6 +48,9 @@ class UltimateBearingCapacity(ABC):
         :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.
@@ -34,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
@@ -49,33 +76,34 @@ 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
-    @validate_func_args
-    def friction_angle(self, val: Annotated[float, MustBeNonNegative]):
-        self._friction_angle = val
+    @validate_params
+    def friction_angle(
+        self,
+        friction_angle: Annotated[float, MustBeNonNegative],
+    ):
+        self._friction_angle = friction_angle
 
     @property
     def cohesion(self) -> float:
-        r"""Return cohesion for local shear in the case of local shear failure
-        or general shear in the case of general shear failure.
+        r"""Return cohesion for local shear in the case of local shear
+        failure or general shear in the case of general shear failure.
 
         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
         return self._cohesion
 
     @cohesion.setter
-    @validate_func_args
-    def cohesion(self, val: Annotated[float, MustBeNonNegative]):
-        self._cohesion = val
+    @validate_params
+    def cohesion(self, cohesion: Annotated[float, MustBeNonNegative]):
+        self._cohesion = cohesion
 
     @property
     def moist_unit_wgt(self) -> float:
@@ -83,9 +111,22 @@ class UltimateBearingCapacity(ABC):
         return self._moist_unit_wgt
 
     @moist_unit_wgt.setter
-    @validate_func_args
-    def moist_unit_wgt(self, val: Annotated[float, MustBePositive]):
-        self._moist_unit_wgt = val
+    @validate_params
+    def moist_unit_wgt(self, moist_unit_wgt: Annotated[float, MustBePositive]):
+        self._moist_unit_wgt = moist_unit_wgt
+
+    @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_params
+    def saturated_unit_wgt(
+        self,
+        saturated_unit_wgt: Annotated[float, MustBePositive],
+    ):
+        self._saturated_unit_wgt = saturated_unit_wgt
 
     @property
     def load_angle(self):
@@ -134,85 +175,107 @@ class UltimateBearingCapacity(ABC):
     def _surcharge_term(self) -> float:
         depth = self.foundation_size.depth
         water_level = self.foundation_size.ground_water_level
+        unit_wgt = self.moist_unit_wgt
+        eop = unit_wgt * depth
 
-        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
+        if not isinf(water_level):
+            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:
+    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"
         """
-        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,
-        }
+        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/_terzaghi_ubc.py

@@ -1,6 +1,14 @@
-from abc import ABC
-
-from geolysis.utils import cos, cot, deg2rad, exp, isclose, pi, round_, tan
+from geolysis.utils import (
+    cosdeg,
+    cotdeg,
+    deg2rad,
+    exp,
+    isclose,
+    pi,
+    round_,
+    tandeg,
+    add_repr,
+)
 from ._core import UltimateBearingCapacity
 
 __all__ = [
@@ -10,8 +18,6 @@ __all__ = [
     "TerzaghiUBC4RectangularFooting",
 ]
 
-from geolysis.foundation import Foundation
-
 
 class TerzaghiBearingCapacityFactors:
 
@@ -20,54 +26,27 @@ class TerzaghiBearingCapacityFactors:
     def n_c(friction_angle: float) -> float:
         if isclose(friction_angle, 0.0):
             return 5.7
-        return cot(friction_angle) * (
-                TerzaghiBearingCapacityFactors.n_q(friction_angle) - 1.0
+        return cotdeg(friction_angle) * (
+            TerzaghiBearingCapacityFactors.n_q(friction_angle) - 1.0
         )
 
     @staticmethod
     @round_(ndigits=2)
     def n_q(friction_angle: float) -> float:
-        return exp((3.0 * pi / 2.0 - deg2rad(friction_angle)) * tan(
-            friction_angle)) / (
-                2.0 * (cos(45.0 + friction_angle / 2.0)) ** 2.0
-        )
+        return exp(
+            (3.0 * pi / 2.0 - deg2rad(friction_angle)) * tandeg(friction_angle)
+        ) / (2.0 * (cosdeg(45.0 + friction_angle / 2.0)) ** 2.0)
 
     @staticmethod
     @round_(ndigits=2)
     def n_gamma(friction_angle: float) -> float:
-        return (TerzaghiBearingCapacityFactors.n_q(
-            friction_angle) - 1.0) * tan(
+        return (TerzaghiBearingCapacityFactors.n_q(friction_angle) - 1.0) * tandeg(
             1.4 * friction_angle
         )
 
 
-class TerzaghiUltimateBearingCapacity(UltimateBearingCapacity, ABC):
-
-    def __init__(
-            self,
-            friction_angle: float,
-            cohesion: float,
-            moist_unit_wgt: float,
-            foundation_size: Foundation,
-            apply_local_shear: bool = False,
-    ) -> None:
-        r"""
-        :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 apply_local_shear: Indicate whether bearing capacity
-                                  failure is general shear or local
-                                  shear failure.
-        """
-        super().__init__(
-            friction_angle=friction_angle,
-            cohesion=cohesion,
-            moist_unit_wgt=moist_unit_wgt,
-            foundation_size=foundation_size,
-            apply_local_shear=apply_local_shear,
-        )
+@add_repr
+class TerzaghiUltimateBearingCapacity(UltimateBearingCapacity):
 
     @property
     def n_c(self) -> float:
@@ -94,12 +73,12 @@ class TerzaghiUBC4StripFooting(TerzaghiUltimateBearingCapacity):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """Calculates ultimate bearing capacity for strip footing."""
         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)
         )
 
 
@@ -112,12 +91,29 @@ class TerzaghiUBC4CircularFooting(TerzaghiUltimateBearingCapacity):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """Calculates ultimate bearing capacity for circular footing."""
         return (
-                self._cohesion_term(1.3)
-                + self._surcharge_term()
-                + self._embedment_term(0.3)
+            self._cohesion_term(1.3)
+            + self._surcharge_term()
+            + self._embedment_term(0.3)
+        )
+
+
+class TerzaghiUBC4SquareFooting(TerzaghiUltimateBearingCapacity):
+    """Ultimate bearing capacity for square footing according to
+    `Terzaghi 1943``.
+
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#terzaghi-bearing-capacity-for-square-footing)
+    for more details on bearing capacity equation used.
+    """
+
+    def _bearing_capacity(self):
+        """Calcalates ultimate bearing capacity for square footing."""
+        return (
+            self._cohesion_term(1.3)
+            + self._surcharge_term()
+            + self._embedment_term(0.4)
         )
 
 
@@ -130,7 +126,7 @@ class TerzaghiUBC4RectangularFooting(TerzaghiUltimateBearingCapacity):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """Calculates ultimate bearing capacity for rectangular footing."""
         width = self.foundation_size.width
         length = self.foundation_size.length
@@ -138,20 +134,7 @@ class TerzaghiUBC4RectangularFooting(TerzaghiUltimateBearingCapacity):
         emb_coef = (1.0 - 0.2 * (width / length)) / 2.0
 
         return (
-                self._cohesion_term(coh_coef)
-                + self._surcharge_term()
-                + self._embedment_term(emb_coef)
+            self._cohesion_term(coh_coef)
+            + self._surcharge_term()
+            + self._embedment_term(emb_coef)
         )
-
-
-class TerzaghiUBC4SquareFooting(TerzaghiUBC4RectangularFooting):
-    """Ultimate bearing capacity for square footing according to
-    `Terzaghi 1943``.
-
-    See [implementation](../formulas/ultimate-bearing-capacity.md/#terzaghi-bearing-capacity-for-square-footing)
-    for more details on bearing capacity equation used.
-    """
-
-    def bearing_capacity(self):
-        """Calcalates ultimate bearing capacity for square footing."""
-        return super().bearing_capacity()