geolysis 0.4.4__py3-none-any.whl → 0.4.5__py3-none-any.whl

geolysis/bearing_capacity/ubc/_core.py

@@ -0,0 +1,192 @@
+from abc import ABC, abstractmethod
+
+from geolysis.foundation import FoundationSize
+from geolysis.utils import arctan, round_, tan, validators
+
+
+class UltimateBearingCapacity(ABC):
+    def __init__(self, friction_angle: float,
+                 cohesion: float,
+                 moist_unit_wgt: float,
+                 foundation_size: FoundationSize,
+                 load_angle=0.0,
+                 apply_local_shear=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
+
+        :param foundation_size: Size of the foundation.
+        :type foundation_size: FoundationSize
+
+        :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 shear or local shear failure,
+                                  defaults to False.
+        :type apply_local_shear: bool, optional
+        """
+        self.friction_angle = friction_angle
+        self.cohesion = cohesion
+        self.moist_unit_wgt = moist_unit_wgt
+        self.load_angle = load_angle
+        self.foundation_size = foundation_size
+        self.apply_local_shear = apply_local_shear
+
+    @property
+    def friction_angle(self) -> float:
+        """Return friction angle for local shear in the case of local shear
+        failure or general shear in the case of general shear failure.
+        """
+        if self.apply_local_shear:
+            return arctan((2 / 3) * tan(self._friction_angle))
+        return self._friction_angle
+
+    @friction_angle.setter
+    @validators.ge(0.0)
+    def friction_angle(self, val: float):
+        self._friction_angle = val
+
+    @property
+    def cohesion(self) -> float:
+        """Return cohesion for local shear in the case of local shear failure
+        or general shear in the case of general shear failure.
+        """
+        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):
+        self._cohesion = val
+
+    @property
+    def moist_unit_wgt(self) -> float:
+        """Moist unit weight of soil (:math:`kN/m^3`)."""
+        return self._moist_unit_wgt
+
+    @moist_unit_wgt.setter
+    @validators.gt(0.0)
+    def moist_unit_wgt(self, val: float):
+        self._moist_unit_wgt = val
+
+    @property
+    def load_angle(self) -> float:
+        """Inclination of the applied load with the  vertical."""
+        return self._load_angle
+
+    @load_angle.setter
+    @validators.le(90.0)
+    @validators.ge(0.0)
+    def load_angle(self, val: float):
+        self._load_angle = val
+
+    @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:
+        return coef * self.cohesion * self.n_c * self.s_c * self.d_c * self.i_c
+
+    def _surcharge_term(self) -> float:
+        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
+
+    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)
+
+        return (coef * self.moist_unit_wgt * width * self.n_gamma
+                * self.s_gamma * self.d_gamma * self.i_gamma * water_corr)
+
+    @round_
+    def bearing_capacity(self):
+        """Calculates the ultimate bearing capacity."""
+        return (self._cohesion_term(1.0)
+                + self._surcharge_term()
+                + self._embedment_term(0.5))
+
+    @property
+    @abstractmethod
+    def n_c(self) -> float:
+        ...
+
+    @property
+    @abstractmethod
+    def n_q(self) -> float:
+        ...
+
+    @property
+    @abstractmethod
+    def n_gamma(self) -> float:
+        ...

geolysis/bearing_capacity/ubc/hansen_ubc.py

@@ -8,10 +8,11 @@ Classes
 
     HansenUltimateBearingCapacity
 """
-from geolysis.bearing_capacity.ubc import UltimateBearingCapacity
-from geolysis.foundation import FoundationSize, Shape
+from geolysis.foundation import Shape
 from geolysis.utils import cos, cot, exp, isclose, pi, round_, sin, tan
 
+from ._core import UltimateBearingCapacity
+
 __all__ = ["HansenUltimateBearingCapacity"]
 
 

geolysis/bearing_capacity/ubc/terzaghi_ubc.py

@@ -13,9 +13,10 @@ Classes
 """
 from abc import ABC
 
-from geolysis.bearing_capacity.ubc import UltimateBearingCapacity
 from geolysis.utils import cos, cot, deg2rad, exp, isclose, pi, round_, tan
 
+from ._core import UltimateBearingCapacity
+
 __all__ = ["TerzaghiUBC4StripFooting",
            "TerzaghiUBC4CircularFooting",
            "TerzaghiUBC4SquareFooting",

geolysis/bearing_capacity/ubc/vesic_ubc.py

@@ -8,11 +8,12 @@ Classes
 
     VesicUltimateBearingCapacity
 """
-from geolysis.bearing_capacity.ubc import UltimateBearingCapacity
-from geolysis.bearing_capacity.ubc import hansen_ubc
-from geolysis.foundation import FoundationSize, Shape
+from geolysis.foundation import Shape
 from geolysis.utils import isclose, round_, sin, tan
 
+from . import hansen_ubc
+from ._core import UltimateBearingCapacity
+
 __all__ = ["VesicUltimateBearingCapacity"]
 
 

geolysis/foundation.py

@@ -35,7 +35,7 @@ import enum
 from abc import ABC, abstractmethod
 from typing import Optional, TypeVar
 
-from geolysis.utils import enum_repr, inf, isclose, validators
+from .utils import enum_repr, inf, isclose, validators
 
 __all__ = ["create_foundation",
            "FoundationSize",
@@ -66,7 +66,7 @@ class FoundationType(enum.StrEnum):
 
 
 class FootingSize(ABC):
-    SHAPE: Shape
+    _SHAPE: Shape
 
     @property
     @abstractmethod
@@ -88,13 +88,14 @@ class FootingSize(ABC):
 
     @property
     def shape(self) -> Shape:
-        return self.SHAPE
+        """Return the shape of the foundation footing."""
+        return self._SHAPE
 
 
 class StripFooting(FootingSize):
     """A class representation of strip footing."""
 
-    SHAPE = Shape.STRIP
+    _SHAPE = Shape.STRIP
 
     def __init__(self, width: float, length: float = inf) -> None:
         """
@@ -109,6 +110,7 @@ class StripFooting(FootingSize):
 
     @property
     def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -118,6 +120,7 @@ class StripFooting(FootingSize):
 
     @property
     def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self._length
 
     @length.setter
@@ -136,7 +139,7 @@ class CircularFooting(FootingSize):
         square and rectangular footing follow.
     """
 
-    SHAPE = Shape.CIRCLE
+    _SHAPE = Shape.CIRCLE
 
     def __init__(self, diameter: float):
         """
@@ -146,6 +149,7 @@ class CircularFooting(FootingSize):
 
     @property
     def diameter(self) -> float:
+        """Diameter of foundation footing (m)."""
         return self._diameter
 
     @diameter.setter
@@ -155,6 +159,7 @@ class CircularFooting(FootingSize):
 
     @property
     def width(self):
+        """Diameter of foundation footing (m)."""
         return self.diameter
 
     @width.setter
@@ -163,6 +168,7 @@ class CircularFooting(FootingSize):
 
     @property
     def length(self):
+        """Diameter of foundation footing (m)."""
         return self.diameter
 
     @length.setter
@@ -173,7 +179,7 @@ class CircularFooting(FootingSize):
 class SquareFooting(FootingSize):
     """A class representation of square footing."""
 
-    SHAPE = Shape.SQUARE
+    _SHAPE = Shape.SQUARE
 
     def __init__(self, width: float):
         """
@@ -183,6 +189,7 @@ class SquareFooting(FootingSize):
 
     @property
     def width(self):
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -192,6 +199,7 @@ class SquareFooting(FootingSize):
 
     @property
     def length(self):
+        """Width of foundation footing (m)."""
         return self.width
 
     @length.setter
@@ -202,7 +210,7 @@ class SquareFooting(FootingSize):
 class RectangularFooting(FootingSize):
     """A class representation of rectangular footing."""
 
-    SHAPE = Shape.RECTANGLE
+    _SHAPE = Shape.RECTANGLE
 
     def __init__(self, width: float, length: float):
         """
@@ -217,6 +225,7 @@ class RectangularFooting(FootingSize):
 
     @property
     def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -226,6 +235,7 @@ class RectangularFooting(FootingSize):
 
     @property
     def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self._length
 
     @length.setter
@@ -240,7 +250,8 @@ class FoundationSize:
     def __init__(self, depth: float,
                  footing_size: FootingSize,
                  eccentricity: float = 0.0,
-                 ground_water_level: Optional[float] = None) -> None:
+                 ground_water_level: Optional[float] = None,
+                 foundation_type: FoundationType = FoundationType.PAD) -> None:
         """
         :param depth: Depth of foundation (m).
         :type depth: float
@@ -258,14 +269,21 @@ class FoundationSize:
         :param ground_water_level: Depth of the water below ground level (m),
                                    defaults to inf.
         :type ground_water_level: float, optional
+
+        :param foundation_type: Type of foundation, defaults to
+                                :attr:`FoundationType.PAD`
+        :type foundation_type: FoundationType, optional
         """
         self.depth = depth
         self.footing_size = footing_size
         self.eccentricity = eccentricity
+
         self._ground_water_level = ground_water_level
+        self._foundation_type = foundation_type
 
     @property
     def depth(self) -> float:
+        """Depth of foundation (m)."""
         return self._depth
 
     @depth.setter
@@ -274,7 +292,8 @@ class FoundationSize:
         self._depth = val
 
     @property
-    def width(self):
+    def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self.footing_size.width
 
     @width.setter
@@ -282,7 +301,8 @@ class FoundationSize:
         self.footing_size.width = val
 
     @property
-    def length(self):
+    def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self.footing_size.length
 
     @length.setter
@@ -290,11 +310,15 @@ class FoundationSize:
         self.footing_size.length = val
 
     @property
-    def footing_shape(self):
+    def footing_shape(self) -> Shape:
+        """Shape of foundation footing."""
         return self.footing_size.shape
 
     @property
     def eccentricity(self) -> float:
+        """The deviation of the foundation load from the center of gravity of
+        the foundation footing.
+        """
         return self._eccentricity
 
     @eccentricity.setter
@@ -304,6 +328,7 @@ class FoundationSize:
 
     @property
     def ground_water_level(self) -> Optional[float]:
+        """Depth of the water below ground level (m)."""
         return self._ground_water_level
 
     @ground_water_level.setter
@@ -311,16 +336,19 @@ class FoundationSize:
     def ground_water_level(self, val: float) -> None:
         self._ground_water_level = val
 
+    @property
+    def foundation_type(self) -> FoundationType:
+        """Type of foundation."""
+        return self._foundation_type
+
     @property
     def effective_width(self) -> float:
         """Returns the effective width of the foundation footing."""
         return self.width - 2.0 * self.eccentricity
 
     def footing_params(self) -> tuple[float, float, Shape]:
-        """Returns the ``width``, ``length``, and ``shape`` of the
-        foundation footing.
-
-        .. note:: "width" is the effective width of the foundation footing.
+        """Returns the :attr:`effective_width`, :attr:`length`, and
+        :attr:`footing_shape` of the foundation footing.
         """
         width, length, shape = self.effective_width, self.length, self.footing_shape
 
@@ -335,6 +363,7 @@ def create_foundation(depth: float,
                       length: Optional[float] = None,
                       eccentricity: float = 0.0,
                       ground_water_level: Optional[float] = None,
+                      foundation_type: FoundationType = FoundationType.PAD,
                       shape: Shape | str = Shape.SQUARE) -> FoundationSize:
     """A factory function that encapsulate the creation of a foundation.
 
@@ -359,8 +388,12 @@ def create_foundation(depth: float,
                                defaults to None.
     :type ground_water_level: float, optional
 
+    :param foundation_type: Type of foundation footing, defaults to
+                            FoundationType.PAD.
+    :type foundation_type: FoundationType, optional
+
     :param shape: Shape of foundation footing, defaults to :class:`Shape.SQUARE`
-    :type shape: Shape | str
+    :type shape: Shape | str, optional
 
     :raises ValueError: Raised when length is not provided for a rectangular
                         footing.
@@ -371,7 +404,7 @@ def create_foundation(depth: float,
     try:
         shape = Shape(shape)
     except ValueError as e:
-        msg = (f"{shape = } is not supported, Supported "
+        msg = (f"{shape=} is not supported, Supported "
                f"types are: {list(Shape)}")
 
         raise ValueError(msg) from e
@@ -390,4 +423,5 @@ def create_foundation(depth: float,
     return FoundationSize(depth=depth,
                           eccentricity=eccentricity,
                           ground_water_level=ground_water_level,
+                          foundation_type=foundation_type,
                           footing_size=footing_size)

geolysis/soil_classifier.py

@@ -15,7 +15,7 @@ Enums
     :toctree: _autosummary
     :nosignatures:
 
-    CLF_TYPE
+    ClfType
     USCSSymbol
     AASHTOSymbol
 
@@ -44,7 +44,7 @@ from typing import NamedTuple, Optional, Protocol, Sequence
 
 from .utils import enum_repr, isclose, round_, validators
 
-__all__ = ["CLF_TYPE",
+__all__ = ["ClfType",
            "AtterbergLimits",
            "PSD",
            "AASHTO",
@@ -162,6 +162,7 @@ class AtterbergLimits:
 
     @property
     def liquid_limit(self) -> float:
+        """Water content beyond which soils flows under their own weight (%)."""
         return self._liquid_limit
 
     @liquid_limit.setter
@@ -171,6 +172,7 @@ class AtterbergLimits:
 
     @property
     def plastic_limit(self) -> float:
+        """Water content at which plastic deformation can be initiated (%)."""
         return self._plastic_limit
 
     @plastic_limit.setter
@@ -195,9 +197,7 @@ class AtterbergLimits:
 
     @property
     def fine_material_type(self) -> USCSSymbol:
-        """
-        Checks whether the soil is either clay or silt.
-        """
+        """Checks whether the soil is either clay or silt."""
         return USCSSymbol.CLAY if self.above_A_LINE() else USCSSymbol.SILT
 
     def above_A_LINE(self) -> bool:
@@ -439,6 +439,7 @@ class AASHTO:
 
     @property
     def fines(self) -> float:
+        """Percentage of fines in soil sample (%)."""
         return self._fines
 
     @fines.setter
@@ -682,18 +683,18 @@ class USCS:
                 f"{coarse_material_type}{fine_material_type}")
 
 
+class SoilClassifier(Protocol):
+    @abstractmethod
+    def classify(self) -> SoilClf: ...
+
+
 @enum_repr
-class CLF_TYPE(enum.StrEnum):
+class ClfType(enum.StrEnum):
     """Enumeration of soil classification types."""
     AASHTO = enum.auto()
     USCS = enum.auto()
 
 
-class SoilClassifier(Protocol):
-    @abstractmethod
-    def classify(self) -> SoilClf: ...
-
-
 def create_soil_classifier(liquid_limit: float,
                            plastic_limit: float,
                            fines: float,
@@ -701,7 +702,7 @@ def create_soil_classifier(liquid_limit: float,
                            d_10: float = 0, d_30: float = 0, d_60: float = 0,
                            add_group_idx: bool = True,
                            organic: bool = False,
-                           clf_type: Optional[CLF_TYPE | str] = None
+                           clf_type: Optional[ClfType | str] = None
                            ) -> SoilClassifier:
     """ A factory function that encapsulates the creation of a soil classifier.
 
@@ -721,17 +722,18 @@ def create_soil_classifier(liquid_limit: float,
                   soil sample passing through No. 200 sieve (0.075mm).
     :type fines: float
 
-    :param sand: Percentage of sand in soil sample (%).
-    :type sand: float
+    :param sand: Percentage of sand in soil sample (%). This is optional for
+                 :class:`AASHTO` classification.
+    :type sand: float, optional
 
     :param d_10: Diameter at which 10% of the soil by weight is finer.
-    :type d_10: float
+    :type d_10: float, optional
 
     :param d_30: Diameter at which 30% of the soil by weight is finer.
-    :type d_30: float
+    :type d_30: float, optional
 
     :param d_60: Diameter at which 60% of the soil by weight is finer.
-    :type d_60: float
+    :type d_60: float, optional
 
     :param add_group_idx: Used to indicate whether the group index should
                           be added to the classification or not, defaults to
@@ -743,28 +745,28 @@ def create_soil_classifier(liquid_limit: float,
 
     :param clf_type: Used to indicate which type of soil classifier should be
                      used, defaults to None.
-    :type clf_type: CLF_TYPE | str
+    :type clf_type: ClfType | str
 
     :raises ValueError: Raises ValueError if ``clf_type`` is  not supported or
                         None
     :raises ValueError: Raises ValueError if ``sand`` is not provided for
                         :class:`USCS` classification.
     """
-    msg = (f"{clf_type = } is not supported, Supported "
-           f"types are: {list(CLF_TYPE)}")
+    msg = (f"{clf_type=} is not supported, Supported "
+           f"types are: {list(ClfType)}")
 
     if clf_type is None:
         raise ValueError(msg)
 
     try:
-        clf_type = CLF_TYPE(str(clf_type).casefold())
+        clf_type = ClfType(str(clf_type).casefold())
     except ValueError as e:
         raise ValueError(msg) from e
 
     atterberg_lmts = AtterbergLimits(liquid_limit=liquid_limit,
                                      plastic_limit=plastic_limit)
 
-    if clf_type == CLF_TYPE.AASHTO:
+    if clf_type == ClfType.AASHTO:
         clf = AASHTO(atterberg_limits=atterberg_lmts,
                      fines=fines,
                      add_group_idx=add_group_idx)