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

geolysis/__init__.py

@@ -1,5 +1,5 @@
 from . import bearing_capacity, foundation, soil_classifier, spt
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = ["foundation", "soil_classifier", "spt", "bearing_capacity"]

geolysis/bearing_capacity/abc/_cohl/_core.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from typing import Annotated
 
 from func_validator import (
@@ -8,17 +9,26 @@ from func_validator import (
 )
 
 from geolysis.foundation import Foundation
+from geolysis.utils import round_, add_repr
 
 
+@dataclass
+class AllowableBearingCapacityResult:
+    allowable_bearing_capacity: float
+    depth_factor: float
+    water_correction_factor: float = 1.0
+
+
+@add_repr
 class AllowableBearingCapacity(ABC):
     #: Maximum tolerable foundation settlement (mm).
     MAX_TOL_SETTLEMENT = 25.4
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         self.corrected_spt_n_value = corrected_spt_n_value
         self.tol_settlement = tol_settlement
@@ -42,8 +52,8 @@ class AllowableBearingCapacity(ABC):
     @tol_settlement.setter
     @validate_func_args
     def tol_settlement(
-            self,
-            tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
+        self,
+        tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
     ):
         self._tol_settlement = tol_settlement
 
@@ -57,17 +67,24 @@ class AllowableBearingCapacity(ABC):
         width = self.foundation_size.width
         return min(1.0 + 0.33 * depth / width, 1.33)
 
-    def bearing_capacity_results(self) -> dict:
+    def bearing_capacity_results(self) -> AllowableBearingCapacityResult:
         """Return a dictionary of bearing capacity results with
         intermediate calculations.
 
         !!! info "Added in v0.11.0"
+        """
+        return AllowableBearingCapacityResult(
+            allowable_bearing_capacity=self.allowable_bearing_capacity(),
+            depth_factor=self._fd(),
+        )
+
+    @round_(ndigits=1)
+    def allowable_bearing_capacity(self):
+        """Calculates the allowable bearing capacity.
 
+        !!! info "Added in v0.12.0"
         """
-        return {
-            "bearing_capacity": self.bearing_capacity(),
-            "depth_factor": self._fd(),
-        }
+        return self._bearing_capacity()
 
     @abstractmethod
-    def bearing_capacity(self): ...
+    def _bearing_capacity(self): ...

geolysis/bearing_capacity/abc/_cohl/bowles_abc.py

@@ -14,10 +14,10 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         """
         :param corrected_spt_n_value: Statistical average of corrected
@@ -35,7 +35,7 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
         )
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """
         Calculate the allowable bearing capacity of the pad foundation.
         """
@@ -46,11 +46,11 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
             return 19.16 * n_corr * self._fd() * self._sr()
 
         return (
-                11.98
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * self._fd()
-                * self._sr()
+            11.98
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * self._fd()
+            * self._sr()
         )
 
 
@@ -64,7 +64,7 @@ class BowlesABC4MatFoundation(BowlesABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """
         Calculate the allowable bearing capacity of the mat foundation.
         """

geolysis/bearing_capacity/abc/_cohl/meyerhof_abc.py

@@ -14,10 +14,10 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ):
         """
         :param corrected_spt_n_value: Average uncorrected SPT N-value
@@ -35,7 +35,7 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
         )
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the pad foundation.
         """
@@ -46,11 +46,11 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
             return 12 * n_corr * self._fd() * self._sr()
 
         return (
-                8
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * self._fd()
-                * self._sr()
+            8
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * self._fd()
+            * self._sr()
         )
 
 
@@ -64,7 +64,7 @@ class MeyerhofABC4MatFoundation(MeyerhofABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """Calculate the allowable bearing capacity of the mat foundation."""
         n_corr = self.corrected_spt_n_value
         return 8 * n_corr * self._fd() * self._sr()

geolysis/bearing_capacity/abc/_cohl/terzaghi_abc.py

@@ -14,10 +14,10 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         """
         :param corrected_spt_n_value: Lowest (or average) uncorrected
@@ -57,7 +57,7 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
         return min(cw, 2.0)
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the pad foundation.
         """
@@ -68,11 +68,11 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
             return 12 * n_corr * (1 / (self._cw() * self._fd())) * self._sr()
 
         return (
-                8
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * (1 / (self._cw() * self._fd()))
-                * self._sr()
+            8
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * (1 / (self._cw() * self._fd()))
+            * self._sr()
         )
 
     def bearing_capacity_results(self) -> dict:
@@ -91,7 +91,7 @@ class TerzaghiABC4MatFoundation(TerzaghiABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the mat foundation.
         """

geolysis/bearing_capacity/ubc/__init__.py

@@ -46,18 +46,19 @@ class UBCType(AbstractStrEnum):
 
 @validate_func_args
 def create_ubc_4_all_soil_types(
-    friction_angle: float,
-    cohesion: float,
-    moist_unit_wgt: float,
-    depth: float,
-    width: float,
-    length: Optional[float] = None,
-    eccentricity: float = 0.0,
-    ground_water_level: Optional[float] = None,
-    load_angle: float = 0.0,
-    apply_local_shear: bool = False,
-    shape: Shape | str = "square",
-    ubc_type: Annotated[UBCType | str, MustBeMemberOf(UBCType)] = "hansen",
+        friction_angle: float,
+        cohesion: float,
+        moist_unit_wgt: float,
+        depth: float,
+        width: float,
+        length: Optional[float] = None,
+        saturated_unit_wgt: float = 20.5,
+        eccentricity: float = 0.0,
+        ground_water_level: Optional[float] = None,
+        load_angle: float = 0.0,
+        apply_local_shear: bool = False,
+        shape: Shape | str = "square",
+        ubc_type: Annotated[UBCType | str, MustBeMemberOf(UBCType)] = "vesic",
 ) -> UltimateBearingCapacity:
     r"""A factory function that encapsulate the creation of ultimate
     bearing capacity.
@@ -70,6 +71,7 @@ def create_ubc_4_all_soil_types(
     :param depth: Depth of foundation (m).
     :param width: Width of foundation footing (m).
     :param length: Length of foundation footing (m).
+    :param saturated_unit_wgt: Saturated unit weight of soil ($kN/m^3$).
     :param eccentricity: The deviation of the foundation load from the
                          center of gravity of the foundation footing.
     :param ground_water_level: Depth of water below ground level (m).
@@ -101,12 +103,14 @@ def create_ubc_4_all_soil_types(
         shape=shape,
     )
 
-    ubc_class = _get_ultimate_bearing_capacity(ubc_type, fnd_size.footing_shape)
+    ubc_class = _get_ultimate_bearing_capacity(ubc_type,
+                                               fnd_size.footing_shape)
 
     return ubc_class(
         friction_angle=friction_angle,
         cohesion=cohesion,
         moist_unit_wgt=moist_unit_wgt,
+        saturated_unit_wgt=saturated_unit_wgt,
         foundation_size=fnd_size,
         apply_local_shear=apply_local_shear,
     )

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,17 +9,38 @@ 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"""
         :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,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
@@ -64,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
@@ -87,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."""
@@ -135,84 +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:
+    def bearing_capacity_results(self) -> UltimateBearingCapacityResult:
         """Return a dictionary of bearing capacity results with
         intermediate calculations.
 
         !!! info "Added in v0.11.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,
-        }
+        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,23 +23,24 @@ class HansenBearingCapacityFactors:
     def n_c(friction_angle: float) -> float:
         if isclose(friction_angle, 0.0):
             return 5.14
-        return cot(friction_angle) * (
-                HansenBearingCapacityFactors.n_q(friction_angle) - 1.0
+        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)
     def n_gamma(friction_angle: float) -> float:
         return (
-                1.8
-                * (HansenBearingCapacityFactors.n_q(friction_angle) - 1.0)
-                * tan(friction_angle)
+            1.8
+            * (HansenBearingCapacityFactors.n_q(friction_angle) - 1.0)
+            * tandeg(friction_angle)
         )
 
 
@@ -91,17 +102,17 @@ class HansenInclinationFactors:
     @staticmethod
     @round_(ndigits=2)
     def i_c(
-            cohesion: float,
-            load_angle: float,
-            f_width: float,
-            f_length: float,
+        cohesion: float,
+        load_angle: float,
+        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)
@@ -109,6 +120,7 @@ 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)`.