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

geolysis/bearing_capacity/ubc/_vesic_ubc.py

@@ -1,7 +1,16 @@
 from geolysis.foundation import Shape
-from geolysis.utils import isclose, round_, sin, tan
+from geolysis.utils import (
+    isclose,
+    round_,
+    sindeg,
+    tandeg,
+    atan,
+    add_repr,
+    cotdeg,
+    exp,
+    pi,
+)
 from ._core import UltimateBearingCapacity
-from ._hansen_ubc import HansenBearingCapacityFactors
 
 __all__ = ["VesicUltimateBearingCapacity"]
 
@@ -11,85 +20,120 @@ class VesicBearingCapacityFactors:
     @staticmethod
     @round_(ndigits=2)
     def n_c(friction_angle: float) -> float:
-        return HansenBearingCapacityFactors.n_c(friction_angle)
+        if isclose(friction_angle, 0.0):
+            return 5.14
+        return cotdeg(friction_angle) * (
+            VesicBearingCapacityFactors.n_q(friction_angle) - 1.0
+        )
 
     @staticmethod
     @round_(ndigits=2)
     def n_q(friction_angle: float) -> float:
-        return HansenBearingCapacityFactors.n_q(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 (
-                2.0
-                * (VesicBearingCapacityFactors.n_q(friction_angle) + 1.0)
-                * tan(friction_angle)
+            2.0
+            * (VesicBearingCapacityFactors.n_q(friction_angle) + 1.0)
+            * 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,
+        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,
-            f_length: float,
-            f_shape: Shape,
+        friction_angle: float,
+        f_width: float,
+        f_length: float,
+        f_shape: Shape,
     ) -> 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
 
@@ -97,23 +141,24 @@ 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)`.
 
@@ -158,7 +203,7 @@ class VesicUltimateBearingCapacity(UltimateBearingCapacity):
     def d_c(self) -> float:
         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:
@@ -184,5 +229,4 @@ class VesicUltimateBearingCapacity(UltimateBearingCapacity):
     @property
     def i_gamma(self) -> float:
         r"""Inclination factor $I_{\gamma}$."""
-        return VesicInclinationFactors.i_gamma(self.friction_angle,
-                                               self.load_angle)
+        return VesicInclinationFactors.i_gamma(self.friction_angle, self.load_angle)

geolysis/foundation.py

@@ -1,16 +1,17 @@
 import enum
 from abc import ABC, abstractmethod
-from typing import Optional, TypeVar, Annotated
+from typing import Optional, TypeAlias, TypeVar, Annotated
 
 from func_validator import (
-    validate_func_args,
+    validate_params,
     MustBePositive,
     MustBeNonNegative,
     MustBeBetween,
     MustBeMemberOf,
+    DependsOn,
 )
 
-from .utils import AbstractStrEnum, inf, isclose
+from .utils import AbstractStrEnum, inf, isclose, pi, round_, add_repr, isinf
 
 __all__ = [
     "create_foundation",
@@ -29,10 +30,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."""
@@ -80,7 +81,7 @@ class FootingSize(ABC):
         raise NotImplementedError
 
     @width.setter
-    def width(self, value: float):
+    def width(self, width: float):
         raise NotImplementedError
 
     @property
@@ -89,7 +90,10 @@ class FootingSize(ABC):
         raise NotImplementedError
 
     @length.setter
-    def length(self, value: float):
+    def length(self, length: float):
+        raise NotImplementedError
+
+    def area(self) -> float:
         raise NotImplementedError
 
     @property
@@ -98,6 +102,7 @@ class FootingSize(ABC):
         return self._SHAPE
 
 
+@add_repr
 class StripFooting(FootingSize):
     """A class representation of strip footing."""
 
@@ -117,9 +122,8 @@ class StripFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self) -> float:
@@ -127,11 +131,17 @@ class StripFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validate_func_args
-    def length(self, val: Annotated[float, MustBePositive]) -> None:
-        self._length = val
+    def length(self, length: float) -> None:
+        self._length = length
+
+    def area(self) -> float:
+        """Area of strip footing ($m \text{or} m^2$)."""
+        if isinf(self.length):
+            return self.width
+        return self.width * self.length
 
 
+@add_repr
 class CircularFooting(FootingSize):
     """A class representation of circular footing.
 
@@ -156,9 +166,8 @@ class CircularFooting(FootingSize):
         return self._diameter
 
     @diameter.setter
-    @validate_func_args
-    def diameter(self, val: Annotated[float, MustBePositive]) -> None:
-        self._diameter = val
+    def diameter(self, diameter: float) -> None:
+        self._diameter = diameter
 
     @property
     def width(self):
@@ -167,8 +176,8 @@ class CircularFooting(FootingSize):
 
     # Not checking for positive as diameter setter already does that
     @width.setter
-    def width(self, val: float):
-        self.diameter = val
+    def width(self, width: float):
+        self.diameter = width
 
     # Not checking for positive as diameter setter already does that
     @property
@@ -177,10 +186,15 @@ class CircularFooting(FootingSize):
         return self.diameter
 
     @length.setter
-    def length(self, val: float):
-        self.diameter = val
+    def length(self, length: float):
+        self.diameter = length
 
+    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."""
 
@@ -198,9 +212,8 @@ class SquareFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self):
@@ -209,10 +222,15 @@ class SquareFooting(FootingSize):
 
     # Not checking for positive as width setter already does that
     @length.setter
-    def length(self, val):
-        self.width = val
+    def length(self, length: float):
+        self.width = length
+
+    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."""
 
@@ -232,9 +250,8 @@ class RectangularFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self) -> float:
@@ -242,11 +259,15 @@ class RectangularFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validate_func_args
-    def length(self, val: Annotated[float, MustBePositive]) -> None:
-        self._length = val
+    def length(self, length: float) -> None:
+        self._length = length
+
+    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."""
 
@@ -256,7 +277,7 @@ class Foundation:
             footing_size: FootingSize,
             eccentricity: float = 0.0,
             load_angle: float = 0.0,
-            ground_water_level: Optional[float] = None,
+            ground_water_level: Optional[float] = inf,
             foundation_type: FoundationType = FoundationType.PAD,
     ) -> None:
         r"""
@@ -276,7 +297,7 @@ class Foundation:
         self.eccentricity = eccentricity
         self.load_angle = load_angle
 
-        self._ground_water_level = ground_water_level
+        self.ground_water_level = ground_water_level
         self.foundation_type = foundation_type
 
     @property
@@ -285,9 +306,9 @@ class Foundation:
         return self._depth
 
     @depth.setter
-    @validate_func_args
-    def depth(self, val: Annotated[float, MustBePositive]) -> None:
-        self._depth = val
+    @validate_params
+    def depth(self, depth: Annotated[float, MustBePositive]) -> None:
+        self._depth = depth
 
     @property
     def width(self) -> float:
@@ -295,8 +316,8 @@ class Foundation:
         return self.footing_size.width
 
     @width.setter
-    def width(self, val: Annotated[float, MustBePositive]):
-        self.footing_size.width = val
+    def width(self, width: Annotated[float, MustBePositive]):
+        self.footing_size.width = width
 
     @property
     def length(self) -> float:
@@ -304,8 +325,8 @@ class Foundation:
         return self.footing_size.length
 
     @length.setter
-    def length(self, val: Annotated[float, MustBePositive]):
-        self.footing_size.length = val
+    def length(self, length: Annotated[float, MustBePositive]):
+        self.footing_size.length = length
 
     @property
     def footing_shape(self) -> Shape:
@@ -320,9 +341,10 @@ class Foundation:
         return self._eccentricity
 
     @eccentricity.setter
-    @validate_func_args
-    def eccentricity(self, val: Annotated[float, MustBeNonNegative]) -> None:
-        self._eccentricity = val
+    @validate_params
+    def eccentricity(self, eccentricity: Annotated[
+        float, MustBeNonNegative]) -> None:
+        self._eccentricity = eccentricity
 
     @property
     def load_angle(self) -> float:
@@ -330,12 +352,13 @@ class Foundation:
         return self._load_angle
 
     @load_angle.setter
-    @validate_func_args
+    @validate_params
     def load_angle(
             self,
-            val: Annotated[float, MustBeBetween(min_value=0.0, max_value=90.0)]
+            load_angle: Annotated[
+                float, MustBeBetween(min_value=0.0, max_value=90.0)],
     ) -> None:
-        self._load_angle = val
+        self._load_angle = load_angle
 
     @property
     def ground_water_level(self) -> Optional[float]:
@@ -343,9 +366,12 @@ class Foundation:
         return self._ground_water_level
 
     @ground_water_level.setter
-    @validate_func_args
-    def ground_water_level(self, val: Annotated[float, MustBePositive]):
-        self._ground_water_level = val
+    @validate_params
+    def ground_water_level(
+            self,
+            ground_water_level: Annotated[float, MustBePositive],
+    ):
+        self._ground_water_level = ground_water_level
 
     @property
     def foundation_type(self) -> FoundationType:
@@ -353,12 +379,18 @@ class Foundation:
         return self._foundation_type
 
     @foundation_type.setter
-    @validate_func_args
+    @validate_params
     def foundation_type(
             self,
-            val: Annotated[FoundationType, MustBeMemberOf(FoundationType)]
+            foundation_type: Annotated[
+                FoundationType, MustBeMemberOf(FoundationType)],
     ):
-        self._foundation_type = val
+        self._foundation_type = foundation_type
+
+    @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:
@@ -370,7 +402,10 @@ 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
@@ -378,14 +413,14 @@ class Foundation:
         return width, length, shape
 
 
-@validate_func_args
+@validate_params
 def create_foundation(
         depth: float,
         width: float,
-        length: Optional[float] = None,
+        length: Annotated[float, DependsOn(shape=Shape.RECTANGLE)] = None,
         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:
@@ -401,31 +436,25 @@ def create_foundation(
                          load aligns with the center of gravity of the
                          foundation footing .
     :param load_angle: Inclination of the applied load with the  vertical
-                           (:math:`\alpha^{\circ}`), defaults to 0.0.
-    :param ground_water_level: Depth of the water below ground level (m),
-                               defaults to None.
-    :param foundation_type: Type of foundation footing, defaults to
-                            :py:enum:mem:`~FoundationType.PAD`.
-    :param shape: Shape of foundation footing, defaults to
-                  :py:enum:mem:`~Shape.SQUARE`
-    :raises ValueError: Raised when length is not provided for a
-                        rectangular footing.
-    :raises ValidationError: Raised if an invalid footing shape is
+                       (:math:`\alpha^{\circ}`).
+    :param ground_water_level: Depth of the water below ground level (m)
+    :param foundation_type: Type of foundation footing.
+    :param shape: Shape of foundation footing
+
+    :raises ValidationError: Raised when length is not provided for a
+                             rectangular footing or an invalid shape is
                              provided.
     """
-
+    footing_size: FootingSize
     shape = Shape(str(shape).casefold())
 
-    if shape is Shape.STRIP:
+    if shape == Shape.STRIP:
         footing_size = StripFooting(width=width)
-    elif shape is Shape.SQUARE:
+    elif shape == Shape.SQUARE:
         footing_size = SquareFooting(width=width)
-    elif shape is Shape.CIRCLE:
+    elif shape == Shape.CIRCLE:
         footing_size = CircularFooting(diameter=width)
     else:  # RECTANGLE
-        if not length:
-            msg = "Length of rectangular footing must be provided."
-            raise ValueError(msg)
         footing_size = RectangularFooting(width=width, length=length)
 
     return Foundation(