geolysis 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

geolysis/bearing_capacity/ubc/__init__.py

@@ -1,152 +1,131 @@
-""" 
-This package provides a factory function and utilities for creating ultimate 
-bearing capacity calculations using methods like Hansen, Terzaghi, and Vesic 
-for various foundation shapes.
-"""
 import enum
-from typing import Optional
+from typing import Optional, Annotated
 
-from geolysis.foundation import Shape, create_foundation
-from geolysis.utils import enum_repr
-from geolysis.utils.exceptions import ErrorMsg, ValidationError
+from func_validator import MustBeMemberOf, validate_func_args
 
+from geolysis.foundation import Shape, create_foundation
+from geolysis.utils import AbstractStrEnum
 from ._core import UltimateBearingCapacity
-from .hansen_ubc import HansenUltimateBearingCapacity
-from .terzaghi_ubc import (TerzaghiUBC4CircularFooting,
-                           TerzaghiUBC4RectangularFooting,
-                           TerzaghiUBC4SquareFooting, TerzaghiUBC4StripFooting)
-from .vesic_ubc import VesicUltimateBearingCapacity
-
-__all__ = ["UBCType",
-           "TerzaghiUBC4StripFooting",
-           "TerzaghiUBC4CircularFooting",
-           "TerzaghiUBC4RectangularFooting",
-           "TerzaghiUBC4SquareFooting",
-           "HansenUltimateBearingCapacity",
-           "VesicUltimateBearingCapacity",
-           "create_ultimate_bearing_capacity"]
-
-
-@enum_repr
-class UBCType(enum.StrEnum):
-    """Enumeration of available ultimate bearing capacity types."""
+from ._hansen_ubc import HansenUltimateBearingCapacity
+from ._terzaghi_ubc import (
+    TerzaghiUBC4CircularFooting,
+    TerzaghiUBC4RectangularFooting,
+    TerzaghiUBC4SquareFooting,
+    TerzaghiUBC4StripFooting,
+)
+from ._vesic_ubc import VesicUltimateBearingCapacity
+
+__all__ = [
+    "UBCType",
+    "TerzaghiUBC4StripFooting",
+    "TerzaghiUBC4CircularFooting",
+    "TerzaghiUBC4RectangularFooting",
+    "TerzaghiUBC4SquareFooting",
+    "HansenUltimateBearingCapacity",
+    "VesicUltimateBearingCapacity",
+    "create_ubc_4_all_soil_types",
+]
+
+
+class UBCType(AbstractStrEnum):
+    """Enumeration of available ultimate bearing capacity methods.
+
+    Each member represents a different method for determining
+    the ultimate bearing capacity of soil.
+    """
+
     HANSEN = enum.auto()
-    TERZAGHI = enum.auto()
-    VESIC = enum.auto()
+    """Hansen's method for calculating ultimate bearing capacity."""
 
+    TERZAGHI = enum.auto()
+    """Terzaghi's method for calculating ultimate bearing capacity."""
 
-ubc_classes = {
-    UBCType.HANSEN: HansenUltimateBearingCapacity,
-    UBCType.TERZAGHI: {Shape.STRIP: TerzaghiUBC4StripFooting,
-                       Shape.CIRCLE: TerzaghiUBC4CircularFooting,
-                       Shape.SQUARE: TerzaghiUBC4SquareFooting,
-                       Shape.RECTANGLE: TerzaghiUBC4RectangularFooting},
-    UBCType.VESIC: VesicUltimateBearingCapacity,
-}
-
-
-def create_ultimate_bearing_capacity(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 = Shape.SQUARE,
-                                     ubc_type: Optional[UBCType | str] = None,
-                                     ) -> UltimateBearingCapacity:
-    r"""A factory function that encapsulate the creation of ultimate bearing
-    capacity.
+    VESIC = enum.auto()
+    """Vesic's method for calculating ultimate bearing capacity."""
+
+
+@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",
+) -> UltimateBearingCapacity:
+    r"""A factory function that encapsulate the creation of ultimate
+    bearing capacity.
 
     :param friction_angle: Internal angle of friction for general shear
                            failure (degree).
-    :type friction_angle: float
-
-    :param cohesion: Cohesion of soil (:math:`kPa`).
-    :type cohesion: float
-
-    :param moist_unit_wgt: Moist unit weight of soil (:math:`kN/m^3`).
-    :type moist_unit_wgt: float
 
+    :param cohesion: Cohesion of soil ($kPa$).
+    :param moist_unit_wgt: Moist unit weight of soil ($kN/m^3$).
     :param depth: Depth of foundation (m).
-    :type depth: float
-
     :param width: Width of foundation footing (m).
-    :type width: float
-
     :param length: Length of foundation footing (m).
-    :type length: float, optional
-
     :param eccentricity: The deviation of the foundation load from the
-                         center of gravity of the foundation footing,
-                         defaults to 0.0 (m). This means that the foundation
-                         load aligns with the center of gravity of the
-                         foundation footing.
-    :type eccentricity: float, optional
-
+                         center of gravity of the foundation footing.
     :param ground_water_level: Depth of water below ground level (m).
-    :type ground_water_level: float, optional
-
     :param load_angle: Inclination of the applied load with the  vertical
-                       (:math:`\alpha^{\circ}`), defaults to 0.0.
-    :type load_angle: float, optional
-
-    :param apply_local_shear: Indicate whether bearing capacity failure is
-                              general or local shear failure, defaults to
-                              False.
-    :type apply_local_shear: bool, optional
-
-    :param shape: Shape of foundation footing, defaults to
-                  :attr:`~geolysis.foundation.Shape.SQUARE`.
-    :type shape: Shape | str, optional
-
-    :param ubc_type: Type of allowable bearing capacity calculation to apply.
-                     Available values are: :attr:`~UBCType.HANSEN`,
-                     :attr:`~UBCType.TERZAGHI`, and :attr:`~UBCType.VESIC`
-                     defaults to None.
-    :type ubc_type:  UBCType | str, optional
-
-    :raises ValueError: Raised if ubc_type is not supported.
-    :raises ValueError: Raised when length is not provided for a rectangular
-                        footing.
-    :raises ValueError: Raised if an invalid footing shape is provided.
+                       ($\alpha^{\circ}$).
+    :param apply_local_shear: Indicate whether bearing capacity failure
+                              is general or local shear failure.
+    :param shape: Shape of foundation footing.
+    :param ubc_type: Type of allowable bearing capacity calculation to
+                     apply.
+
+    :raises ValidationError: Raised if ubc_type is not supported.
+    :raises ValidationError: Raised if an invalid footing shape is
+                             provided.
+    :raises ValueError: Raised when length is not provided for a
+                        rectangular footing.
     """
-
-    msg = ErrorMsg(param_name="ubc_type",
-                   param_value=ubc_type,
-                   symbol="in",
-                   param_value_bound=list(UBCType))
-
-    if ubc_type is None:
-        raise ValidationError(msg)
-
-    try:
-        ubc_type = UBCType(str(ubc_type).casefold())
-    except ValueError as e:
-        raise ValidationError(msg) from e
+    ubc_type = UBCType(ubc_type)
 
     # exception from create_foundation will automatically propagate
     # no need to catch and handle it.
-    fnd_size = create_foundation(depth=depth,
-                                 width=width,
-                                 length=length,
-                                 eccentricity=eccentricity,
-                                 load_angle=load_angle,
-                                 ground_water_level=ground_water_level,
-                                 shape=shape)
-
+    fnd_size = create_foundation(
+        depth=depth,
+        width=width,
+        length=length,
+        eccentricity=eccentricity,
+        load_angle=load_angle,
+        ground_water_level=ground_water_level,
+        shape=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,
+        foundation_size=fnd_size,
+        apply_local_shear=apply_local_shear,
+    )
+
+
+def _get_ultimate_bearing_capacity(ubc_type: UBCType, foundation_shape: Shape):
+    ubc_classes = {
+        UBCType.HANSEN: HansenUltimateBearingCapacity,
+        UBCType.TERZAGHI: {
+            Shape.STRIP: TerzaghiUBC4StripFooting,
+            Shape.CIRCLE: TerzaghiUBC4CircularFooting,
+            Shape.SQUARE: TerzaghiUBC4SquareFooting,
+            Shape.RECTANGLE: TerzaghiUBC4RectangularFooting,
+        },
+        UBCType.VESIC: VesicUltimateBearingCapacity,
+    }
     if ubc_type == UBCType.TERZAGHI:
-        ubc_class = ubc_classes[ubc_type][fnd_size.footing_shape]
+        ubc_class = ubc_classes[ubc_type][foundation_shape]
     else:
         ubc_class = ubc_classes[ubc_type]
-
-    ubc = ubc_class(friction_angle=friction_angle,
-                    cohesion=cohesion,
-                    moist_unit_wgt=moist_unit_wgt,
-                    foundation_size=fnd_size,
-                    apply_local_shear=apply_local_shear)
-    return ubc
+    return ubc_class

geolysis/bearing_capacity/ubc/_core.py

@@ -1,34 +1,50 @@
 from abc import ABC, abstractmethod
+from typing import Annotated
+
+from func_validator import (
+    validate_func_args,
+    MustBeNonNegative,
+    MustBePositive,
+)
 
 from geolysis.foundation import Foundation
-from geolysis.utils import arctan, round_, tan, validators
+from geolysis.utils import arctan, round_, tan
 
 
 class UltimateBearingCapacity(ABC):
-    def __init__(self, friction_angle: float,
-                 cohesion: float,
-                 moist_unit_wgt: float,
-                 foundation_size: Foundation,
-                 # load_angle: float = 0.0,
-                 apply_local_shear: bool = False) -> None:
+    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).
-        :type friction_angle: float
-
-        :param cohesion: Cohesion of soil (:math:`kPa`).
-        :type cohesion: float
-
-        :param moist_unit_wgt: Moist unit weight of soil (:math:`kN/m^3`).
-        :type moist_unit_wgt: float
 
+        $$
+        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.
-        :type foundation_size: Foundation
-
-        :param apply_local_shear: Indicate whether bearing capacity failure is
-                                  general shear or local shear failure,
-                                  defaults to False.
-        :type apply_local_shear: bool, optional
+        :param apply_local_shear: Indicate whether bearing capacity
+                                  failure is general shear or local
+                                  shear failure.
         """
         self.friction_angle = friction_angle
         self.cohesion = cohesion
@@ -41,13 +57,11 @@ class UltimateBearingCapacity(ABC):
         r"""Return friction angle for local shear in the case of local shear
         failure or general shear in the case of general shear failure.
 
-        :Equation:
-
         In the case of local shear failure:
 
-        .. math::
-
-           \phi' = \tan^{-1} \left(\frac{2}{3} \tan \phi\right)
+        $$
+        \phi' = \tan^{-1} \left(\frac{2}{3} \tan \phi\right)
+        $$
 
         """
         if self.apply_local_shear:
@@ -55,8 +69,8 @@ class UltimateBearingCapacity(ABC):
         return self._friction_angle
 
     @friction_angle.setter
-    @validators.ge(0.0)
-    def friction_angle(self, val: float):
+    @validate_func_args
+    def friction_angle(self, val: Annotated[float, MustBeNonNegative]):
         self._friction_angle = val
 
     @property
@@ -64,31 +78,29 @@ class UltimateBearingCapacity(ABC):
         r"""Return cohesion for local shear in the case of local shear failure
         or general shear in the case of general shear failure.
 
-        :Equation:
-
         In the case of local shear failure:
 
-        .. math::
-
-            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
-    @validators.ge(0.0)
-    def cohesion(self, val: float):
+    @validate_func_args
+    def cohesion(self, val: Annotated[float, MustBeNonNegative]):
         self._cohesion = val
 
     @property
     def moist_unit_wgt(self) -> float:
-        """Moist unit weight of soil (:math:`kN/m^3`)."""
+        """Moist unit weight of soil ($kN/m^3$)."""
         return self._moist_unit_wgt
 
     @moist_unit_wgt.setter
-    @validators.gt(0.0)
-    def moist_unit_wgt(self, val: float):
+    @validate_func_args
+    def moist_unit_wgt(self, val: Annotated[float, MustBePositive]):
         self._moist_unit_wgt = val
 
     @property
@@ -98,47 +110,38 @@ class UltimateBearingCapacity(ABC):
 
     @property
     def s_c(self) -> float:
-        """Shape factor :math:`S_c`"""
         return 1.0
 
     @property
     def s_q(self) -> float:
-        """Shape factor :math:`S_q`"""
         return 1.0
 
     @property
     def s_gamma(self) -> float:
-        r"""Shape factor :math:`S_{\gamma}`"""
         return 1.0
 
     @property
     def d_c(self) -> float:
-        """Depth factor :math:`d_c`"""
         return 1.0
 
     @property
     def d_q(self) -> float:
-        """Depth factor :math:`d_q`"""
         return 1.0
 
     @property
     def d_gamma(self) -> float:
-        r"""Depth factor :math:`d_{\gamma}`"""
         return 1.0
 
     @property
     def i_c(self) -> float:
-        """Inclination factor :math:`i_c`"""
         return 1.0
 
     @property
     def i_q(self) -> float:
-        """Inclination factor :math:`i_q`"""
         return 1.0
 
     @property
     def i_gamma(self) -> float:
-        r"""Inclination factor :math:`i_{\gamma}`"""
         return 1.0
 
     def _cohesion_term(self, coef: float = 1.0) -> float:
@@ -172,15 +175,42 @@ class UltimateBearingCapacity(ABC):
             b = max(water_level - depth, 0)
             water_corr = min(0.5 + 0.5 * b / width, 1)
 
-        return (coef * self.moist_unit_wgt * width * self.n_gamma
-                * self.s_gamma * self.d_gamma * self.i_gamma * water_corr)
+        return (
+                coef
+                * self.moist_unit_wgt
+                * width
+                * self.n_gamma
+                * self.s_gamma
+                * self.d_gamma
+                * self.i_gamma
+                * water_corr
+        )
 
     @round_(ndigits=2)
     def bearing_capacity(self) -> float:
         """Calculates the ultimate bearing capacity."""
-        return (self._cohesion_term(1.0)
+        return (
+                self._cohesion_term(1.0)
                 + self._surcharge_term()
-                + self._embedment_term(0.5))
+                + 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,
+        }
 
     @property
     @abstractmethod