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

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,124 +26,77 @@ 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"""
-
-        - $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
-        - $L$ (m): Length of foundation footing
-        - $N_c$, $N_q$, $N_{\gamma}$: Bearing capacity 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 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:
-        r"""Bearing capacity factor $N_c$.
-
-        $$N_c = \cot(\phi) \cdot (N_q - 1)$$
-        """
+        r"""Bearing capacity factor $N_c$."""
         return TerzaghiBearingCapacityFactors.n_c(self.friction_angle)
 
     @property
     def n_q(self) -> float:
-        r"""Bearing capacity factor $N_q$.
-
-        $$
-        N_q = \dfrac{e^{(\frac{3\pi}{2} - \phi)\tan\phi}}
-                    {2\cos^2(45 + \frac{\phi}{2})}
-        $$
-        """
+        r"""Bearing capacity factor $N_q$."""
         return TerzaghiBearingCapacityFactors.n_q(self.friction_angle)
 
     @property
     def n_gamma(self) -> float:
-        r"""Bearing capacity factor $N_{\gamma}$.
-
-        $$N_{\gamma} =  (N_q - 1) \cdot \tan(1.4\phi)$$
-        """
+        r"""Bearing capacity factor $N_{\gamma}$."""
         return TerzaghiBearingCapacityFactors.n_gamma(self.friction_angle)
 
 
 class TerzaghiUBC4StripFooting(TerzaghiUltimateBearingCapacity):
-    r"""Ultimate bearing capacity for strip footing according to
+    """Ultimate bearing capacity for strip footing according to
     `Terzaghi 1943`.
 
-    $$q_u = cN_c + qN_q + 0.5 \gamma BN_{\gamma}$$
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#terzaghi-bearing-capacity-for-strip-footing)
+    for more details on bearing capacity equation used.
     """
 
     @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)
         )
 
 
 class TerzaghiUBC4CircularFooting(TerzaghiUltimateBearingCapacity):
-    r"""Ultimate bearing capacity for circular footing according to
+    """Ultimate bearing capacity for circular footing according to
     `Terzaghi 1943`.
 
-    $$q_u = 1.3cN_c + qN_q + 0.3 \gamma BN_{\gamma}$$
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#terzaghi-bearing-capacity-for-circular-footing)
+    for more details on bearing capacity equation used.
     """
 
     @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)
         )
 
 
@@ -145,14 +104,12 @@ class TerzaghiUBC4RectangularFooting(TerzaghiUltimateBearingCapacity):
     r"""Ultimate bearing capacity for rectangular footing according to
     `Terzaghi 1943`.
 
-    $$
-    q_u = \left(1 + 0.3 \dfrac{B}{L} \right) c N_c + qN_q
-          + \left(1 - 0.2 \dfrac{B}{L} \right) 0.5 B \gamma N_{\gamma}
-    $$
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#terzaghi-bearing-capacity-for-rectangular-footing)
+    for more details on bearing capacity equation used.
     """
 
     @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
@@ -160,19 +117,20 @@ 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):
-    r"""Ultimate bearing capacity for square footing according to
+    """Ultimate bearing capacity for square footing according to
     `Terzaghi 1943``.
 
-    $$q_u = 1.3cN_c + qN_q + 0.4 \gamma BN_{\gamma}$$
+    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):
+    def _bearing_capacity(self):
         """Calcalates ultimate bearing capacity for square footing."""
-        return super().bearing_capacity()
+        return super()._bearing_capacity()

geolysis/bearing_capacity/ubc/_vesic_ubc.py

@@ -1,5 +1,5 @@
 from geolysis.foundation import Shape
-from geolysis.utils import isclose, round_, sin, tan
+from geolysis.utils import isclose, round_, sindeg, tandeg, atan, add_repr
 from ._core import UltimateBearingCapacity
 from ._hansen_ubc import HansenBearingCapacityFactors
 
@@ -24,31 +24,29 @@ class VesicBearingCapacityFactors:
         return (
             2.0
             * (VesicBearingCapacityFactors.n_q(friction_angle) + 1.0)
-            * tan(friction_angle)
+            * tandeg(friction_angle)
         )
 
 
 class VesicShapeFactors:
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def s_c(
         friction_angle: float,
         f_width: float,
         f_length: float,
         f_shape: Shape,
     ) -> float:
-        _n_q = VesicBearingCapacityFactors.n_q(friction_angle)
-        _n_c = VesicBearingCapacityFactors.n_c(friction_angle)
+        n_q = VesicBearingCapacityFactors.n_q(friction_angle)
+        n_c = VesicBearingCapacityFactors.n_c(friction_angle)
 
         if f_shape == Shape.STRIP:
             return 1.0
-        elif f_shape == Shape.RECTANGLE:
-            return 1.0 + (f_width / f_length) * (_n_q / _n_c)
-        else:  # SQUARE, CIRCLE
-            return 1.0 + (_n_q / _n_c)
+        else:
+            return 1.0 + (f_width / f_length) * (n_q / n_c)
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def s_q(
         friction_angle: float,
         f_width: float,
@@ -57,38 +55,70 @@ class VesicShapeFactors:
     ) -> float:
         if f_shape == Shape.STRIP:
             return 1.0
-        elif f_shape == Shape.RECTANGLE:
-            return 1.0 + (f_width / f_length) * tan(friction_angle)
-        else:  # SQUARE, CIRCLE
-            return 1.0 + tan(friction_angle)
+        else:
+            return 1.0 + (f_width / f_length) * tandeg(friction_angle)
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def s_gamma(f_width: float, f_length: float, f_shape: Shape) -> float:
         if f_shape == Shape.STRIP:
             return 1.0
-        elif f_shape == Shape.RECTANGLE:
+        else:
             return 1.0 - 0.4 * (f_width / f_length)
-        else:  # SQUARE, CIRCLE
-            return 0.6
 
 
 class VesicDepthFactors:
 
     @staticmethod
-    @round_(ndigits=2)
-    def d_c(f_depth: float, f_width: float) -> float:
-        return 1.0 + 0.4 * f_depth / f_width
+    def _d_c(friction_angle: float, f_depth: float, f_width: float) -> float:
+        d_q = VesicDepthFactors.d_q(friction_angle, f_depth, f_width)
+        n_c = VesicBearingCapacityFactors.n_c(friction_angle)
+        return d_q - ((1.0 - d_q) / (n_c * tandeg(friction_angle)))
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
+    def d_c(friction_angle: float, f_depth: float, f_width: float) -> float:
+        d2w = round(f_depth / f_width, 1)
+
+        if d2w <= 1.0:
+            if isclose(friction_angle, 0.0):
+                _d_c = 1.0 + 0.4 * d2w
+            else:
+                _d_c = VesicDepthFactors._d_c(friction_angle, f_depth, f_width)
+        else:
+            if isclose(friction_angle, 0.0):
+                _d_c = 1.0 + 0.4 * atan(d2w)
+            else:
+                _d_c = VesicDepthFactors._d_c(friction_angle, f_depth, f_width)
+
+        return _d_c
+
+    @staticmethod
+    @round_(ndigits=3)
     def d_q(friction_angle: float, f_depth: float, f_width: float) -> float:
-        return 1.0 + 2.0 * tan(friction_angle) * (1.0 - sin(friction_angle)) ** 2.0 * (
-            f_depth / f_width
-        )
+        d2w = f_depth / f_width
+
+        if d2w <= 1.0:
+            if isclose(friction_angle, 0.0):
+                _d_q = 1.0
+            else:
+                _d_q = (
+                    1.0
+                    + 2
+                    * tandeg(friction_angle)
+                    * (1 - sindeg(friction_angle)) ** 2
+                    * d2w
+                )
+        else:
+            if isclose(friction_angle, 0.0):
+                _d_q = 1.0
+            else:
+                _d_q = 1.0 + (
+                    2.0 * tandeg(friction_angle) * (1 - sindeg(friction_angle)) ** 2
+                ) * atan(d2w)
+        return _d_q
 
     @staticmethod
-    @round_(ndigits=2)
     def d_gamma() -> float:
         return 1.0
 
@@ -96,158 +126,92 @@ class VesicDepthFactors:
 class VesicInclinationFactors:
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def i_c(load_angle: float) -> float:
         return (1.0 - load_angle / 90.0) ** 2.0
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def i_q(load_angle: float) -> float:
         return VesicInclinationFactors.i_c(load_angle)
 
     @staticmethod
-    @round_(ndigits=2)
+    @round_(ndigits=3)
     def i_gamma(friction_angle: float, load_angle: float) -> float:
         if isclose(friction_angle, 0.0):
             return 1.0
         return (1.0 - load_angle / friction_angle) ** 2.0
 
 
+@add_repr
 class VesicUltimateBearingCapacity(UltimateBearingCapacity):
-    """Ultimate bearing capacity for soils according to `Vesic (1973)`."""
+    """Ultimate bearing capacity for soils according to `Vesic (1973)`.
+
+    See [implementation](../formulas/ultimate-bearing-capacity.md/#vesic-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 VesicBearingCapacityFactors.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 VesicBearingCapacityFactors.n_q(self.friction_angle)
 
     @property
     def n_gamma(self) -> float:
-        r"""Bearing capacity factor $N_{\gamma}$.
-
-        $$N_{\gamma} = 2(N_q + 1) \tan(\phi)$$
-        """
+        r"""Bearing capacity factor $N_{\gamma}$."""
         return VesicBearingCapacityFactors.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 + \dfrac{B}{L} \cdot \dfrac{N_q}{N_c} \rightarrow
-                 \text{Rectangular footing}
-        $$
-
-        $$
-        s_c &= 1 + \dfrac{N_q}{N_c} \rightarrow
-                \text{Square or circular footing}
-        $$
-        """
+        r"""Shape factor $S_c$."""
         width, length, shape = self.foundation_size.footing_params()
         return VesicShapeFactors.s_c(self.friction_angle, 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 + \dfrac{B}{L} \cdot \tan(\phi) \rightarrow
-                     \text{Rectangular footing}
-        $$
-
-        $$
-        s_q = 1 + \tan(\phi) \rightarrow \text{Square or circular footing}
-        $$
-        """
+        r"""Shape factor $S_q$."""
         width, length, shape = self.foundation_size.footing_params()
         return VesicShapeFactors.s_q(self.friction_angle, 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 \dfrac{B}{L} \rightarrow
-                        \text{Rectangular footing}
-        $$
-
-        $$
-        s_{\gamma} = 0.6 \rightarrow \text{Square or circular footing}
-        $$
-        """
+        r"""Shape factor $S_{\gamma}$."""
         width, length, shape = self.foundation_size.footing_params()
         return VesicShapeFactors.s_gamma(width, length, shape)
 
     @property
     def d_c(self) -> float:
-        r"""Depth factor $D_c$.
-
-        $$d_c = 1 + 0.4 \dfrac{D_f}{B}$$
-        """
+        r"""Depth factor $D_c$."""
         depth, width = self.foundation_size.depth, self.foundation_size.width
-        return VesicDepthFactors.d_c(depth, width)
+        return VesicDepthFactors.d_c(self.friction_angle, depth, width)
 
     @property
     def d_q(self) -> float:
-        r"""Depth factor $D_q$.
-
-        $$
-        d_q = 1 + 2 \tan(\phi) \cdot (1 - \sin(\phi))^2
-              \cdot \dfrac{D_f}{B}
-        $$
-        """
+        r"""Depth factor $D_q$."""
         depth, width = self.foundation_size.depth, self.foundation_size.width
         return VesicDepthFactors.d_q(self.friction_angle, depth, width)
 
     @property
     def d_gamma(self) -> float:
-        r"""Depth factor $D_{\gamma}$.
-
-        $$d_{\gamma} = 1.0$$
-        """
+        r"""Depth factor $D_{\gamma}$."""
         return VesicDepthFactors.d_gamma()
 
     @property
     def i_c(self) -> float:
-        r"""Inclination factor $I_c$.
-
-        $$i_c = (1 - \dfrac{\alpha}{90})^2$$
-        """
+        r"""Inclination factor $I_c$."""
         return VesicInclinationFactors.i_c(self.load_angle)
 
     @property
     def i_q(self) -> float:
-        r"""Inclination factor $I_q$.
-
-        $$i_q = (1 - \dfrac{\alpha}{90})^2$$
-        """
+        r"""Inclination factor $I_q$."""
         return VesicInclinationFactors.i_q(self.load_angle)
 
     @property
     def i_gamma(self) -> float:
-        r"""Inclination factor $I_{\gamma}$.
-
-        $$i_{\gamma} = \left(1 - \dfrac{\alpha}{\phi} \right)^2$$
-        """
+        r"""Inclination factor $I_{\gamma}$."""
         return VesicInclinationFactors.i_gamma(self.friction_angle, self.load_angle)

geolysis/foundation.py

@@ -1,5 +1,7 @@
 import enum
+import math
 from abc import ABC, abstractmethod
+from math import isinf
 from typing import Optional, TypeVar, Annotated
 
 from func_validator import (
@@ -10,7 +12,7 @@ from func_validator import (
     MustBeMemberOf,
 )
 
-from .utils import AbstractStrEnum, inf, isclose
+from .utils import AbstractStrEnum, inf, isclose, pi, round_, add_repr
 
 __all__ = [
     "create_foundation",
@@ -29,10 +31,10 @@ T = TypeVar("T")
 class Shape(AbstractStrEnum):
     """Enumeration of foundation shapes.
 
-     Each member represents a standard geometric shape commonly used
-     in foundation design, which can affect bearing capacity and
-     settlement calculations.
-     """
+    Each member represents a standard geometric shape commonly used
+    in foundation design, which can affect bearing capacity and
+    settlement calculations.
+    """
 
     STRIP = enum.auto()
     """Strip (or continuous) foundation, typically long and narrow."""
@@ -92,12 +94,16 @@ class FootingSize(ABC):
     def length(self, value: float):
         raise NotImplementedError
 
+    def area(self) -> float:
+        raise NotImplementedError
+
     @property
     def shape(self) -> Shape:
         """Return the shape of the foundation footing."""
         return self._SHAPE
 
 
+@add_repr
 class StripFooting(FootingSize):
     """A class representation of strip footing."""
 
@@ -131,7 +137,14 @@ class StripFooting(FootingSize):
     def length(self, val: Annotated[float, MustBePositive]) -> None:
         self._length = val
 
+    def area(self) -> float:
+        """Area of strip footing ($m \text{or} m^2$)."""
+        if math.isinf(self.length):
+            return self.width
+        return self.width * self.length
+
 
+@add_repr
 class CircularFooting(FootingSize):
     """A class representation of circular footing.
 
@@ -180,7 +193,12 @@ class CircularFooting(FootingSize):
     def length(self, val: float):
         self.diameter = val
 
+    def area(self) -> float:
+        """Area of circular footing ($m^2$)."""
+        return pi * self.diameter ** 2 / 4
 
+
+@add_repr
 class SquareFooting(FootingSize):
     """A class representation of square footing."""
 
@@ -212,7 +230,12 @@ class SquareFooting(FootingSize):
     def length(self, val):
         self.width = val
 
+    def area(self) -> float:
+        """Area of square footing ($m^2$)."""
+        return self.width ** 2
+
 
+@add_repr
 class RectangularFooting(FootingSize):
     """A class representation of rectangular footing."""
 
@@ -246,7 +269,12 @@ class RectangularFooting(FootingSize):
     def length(self, val: Annotated[float, MustBePositive]) -> None:
         self._length = val
 
+    def area(self) -> float:
+        """Area of rectangular footing ($m^2$)."""
+        return self.width * self.length
 
+
+@add_repr
 class Foundation:
     """A simple class representing a foundation structure."""
 
@@ -360,6 +388,11 @@ class Foundation:
     ):
         self._foundation_type = val
 
+    @round_(2)
+    def foundation_area(self) -> float:
+        """Returns the area of the foundation footing ($m^2$)."""
+        return self.footing_size.area()
+
     @property
     def effective_width(self) -> float:
         """Returns the effective width of the foundation footing (m)."""
@@ -370,7 +403,7 @@ class Foundation:
         of the foundation footing.
         """
         width, length, shape = (
-            self.effective_width, self.length, self.footing_shape)
+        self.effective_width, self.length, self.footing_shape)
 
         if not isclose(width, length) and shape != Shape.STRIP:
             shape = Shape.RECTANGLE
@@ -382,10 +415,10 @@ class Foundation:
 def create_foundation(
         depth: float,
         width: float,
-        length: Optional[float] = None,
+        length: float = inf,
         eccentricity: float = 0.0,
         load_angle: float = 0.0,
-        ground_water_level: Optional[float] = None,
+        ground_water_level: Optional[float] = inf,
         foundation_type: FoundationType = "pad",
         shape: Annotated[Shape | str, MustBeMemberOf(Shape)] = "square",
 ) -> Foundation:
@@ -423,7 +456,7 @@ def create_foundation(
     elif shape is Shape.CIRCLE:
         footing_size = CircularFooting(diameter=width)
     else:  # RECTANGLE
-        if not length:
+        if isinf(length):
             msg = "Length of rectangular footing must be provided."
             raise ValueError(msg)
         footing_size = RectangularFooting(width=width, length=length)