geolysis 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

geolysis/foundation.py

@@ -1,40 +1,74 @@
-"""This module provides classes and utilities for modeling various foundation
-footing types, their dimensions, and properties."""
 import enum
 from abc import ABC, abstractmethod
-from typing import Optional, TypeVar
+from typing import Optional, TypeVar, Annotated
+
+from func_validator import (
+    validate_func_args,
+    MustBePositive,
+    MustBeNonNegative,
+    MustBeBetween,
+    MustBeMemberOf,
+)
+
+from .utils import AbstractStrEnum, inf, isclose
+
+__all__ = [
+    "create_foundation",
+    "Foundation",
+    "FoundationType",
+    "Shape",
+    "StripFooting",
+    "CircularFooting",
+    "SquareFooting",
+    "RectangularFooting",
+]
 
-from .utils import enum_repr, inf, isclose, validators
-from .utils.exceptions import ErrorMsg, ValidationError
+T = TypeVar("T")
 
-__all__ = ["create_foundation",
-           "FoundationSize",
-           "FoundationType",
-           "Shape",
-           "StripFooting",
-           "CircularFooting",
-           "SquareFooting",
-           "RectangularFooting"]
 
-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.
+     """
 
-@enum_repr
-class Shape(enum.StrEnum):
-    """Enumeration of foundation shapes."""
     STRIP = enum.auto()
+    """Strip (or continuous) foundation, typically long and narrow."""
+
     CIRCLE = enum.auto()
+    """Circular foundation, often used for columns or piers."""
+
     SQUARE = enum.auto()
+    """Square foundation, commonly used for isolated footings."""
+
     RECTANGLE = enum.auto()
+    """Rectangular foundation, used when length and width differ significantly."""
 
 
-@enum_repr
-class FoundationType(enum.StrEnum):
-    """Enumeration of foundation types."""
+class FoundationType(AbstractStrEnum):
+    """
+    Enumeration of foundation types.
+
+    Each member represents a common type of foundation used in
+    geotechnical engineering. Some members have aliases for
+    alternative naming conventions.
+    """
+
     PAD = enum.auto()
+    """Pad foundation, a small, isolated footing supporting a single column."""
+
     ISOLATED = PAD
+    """Alias for PAD foundation (isolated footing)."""
+
     MAT = enum.auto()
+    """Mat foundation, a large, continuous slab supporting multiple columns or 
+    walls.
+    """
+
     RAFT = MAT
+    """Alias for MAT foundation (raft foundation)."""
 
 
 class FootingSize(ABC):
@@ -69,13 +103,10 @@ class StripFooting(FootingSize):
 
     _SHAPE = Shape.STRIP
 
-    def __init__(self, width: float, length: float = inf) -> None:
+    def __init__(self, width: float, length: float = inf):
         """
         :param width: Width of foundation footing (m).
-        :type width: float
-
-        :param float length: Length of foundation footing, defaults to inf (m).
-        :type length: float
+        :param length: Length of foundation footing (m).
         """
         self.width = width
         self.length = length
@@ -86,8 +117,8 @@ class StripFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validators.gt(0.0)
-    def width(self, val: float):
+    @validate_func_args
+    def width(self, val: Annotated[float, MustBePositive]) -> None:
         self._width = val
 
     @property
@@ -96,17 +127,17 @@ class StripFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validators.ge(0.0)
-    def length(self, val: float):
+    @validate_func_args
+    def length(self, val: Annotated[float, MustBePositive]) -> None:
         self._length = val
 
 
 class CircularFooting(FootingSize):
     """A class representation of circular footing.
 
-    .. note::
+    !!! note
 
-        The ``width`` and ``length`` properties refer to the diameter of the
+        The `width` and `length` properties refer to the diameter of the
         circular footing. This is to make it compatible with the protocol
         square and rectangular footing follow.
     """
@@ -115,7 +146,7 @@ class CircularFooting(FootingSize):
 
     def __init__(self, diameter: float):
         """
-        :param float diameter: Diameter of foundation footing (m).
+        :param diameter: Diameter of foundation footing (m).
         """
         self.diameter = diameter
 
@@ -125,8 +156,8 @@ class CircularFooting(FootingSize):
         return self._diameter
 
     @diameter.setter
-    @validators.gt(0.0)
-    def diameter(self, val: float):
+    @validate_func_args
+    def diameter(self, val: Annotated[float, MustBePositive]) -> None:
         self._diameter = val
 
     @property
@@ -134,10 +165,12 @@ class CircularFooting(FootingSize):
         """Diameter of foundation footing (m)."""
         return self.diameter
 
+    # Not checking for positive as diameter setter already does that
     @width.setter
     def width(self, val: float):
         self.diameter = val
 
+    # Not checking for positive as diameter setter already does that
     @property
     def length(self):
         """Diameter of foundation footing (m)."""
@@ -165,8 +198,8 @@ class SquareFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validators.gt(0)
-    def width(self, val):
+    @validate_func_args
+    def width(self, val: Annotated[float, MustBePositive]) -> None:
         self._width = val
 
     @property
@@ -174,6 +207,7 @@ class SquareFooting(FootingSize):
         """Width of foundation footing (m)."""
         return self.width
 
+    # Not checking for positive as width setter already does that
     @length.setter
     def length(self, val):
         self.width = val
@@ -187,10 +221,7 @@ class RectangularFooting(FootingSize):
     def __init__(self, width: float, length: float):
         """
         :param width: Width of foundation footing (m).
-        :type width: float
-
         :param length: Length of foundation footing (m).
-        :type length: float
         """
         self.width = width
         self.length = length
@@ -201,8 +232,8 @@ class RectangularFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validators.gt(0.0)
-    def width(self, val):
+    @validate_func_args
+    def width(self, val: Annotated[float, MustBePositive]) -> None:
         self._width = val
 
     @property
@@ -211,47 +242,42 @@ class RectangularFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validators.gt(0.0)
-    def length(self, val):
+    @validate_func_args
+    def length(self, val: Annotated[float, MustBePositive]) -> None:
         self._length = val
 
 
-class FoundationSize:
+class Foundation:
     """A simple class representing a foundation structure."""
 
-    def __init__(self, depth: float,
-                 footing_size: FootingSize,
-                 eccentricity: float = 0.0,
-                 ground_water_level: Optional[float] = None,
-                 foundation_type: FoundationType = FoundationType.PAD) -> None:
-        """
+    def __init__(
+            self,
+            depth: float,
+            footing_size: FootingSize,
+            eccentricity: float = 0.0,
+            load_angle: float = 0.0,
+            ground_water_level: Optional[float] = None,
+            foundation_type: FoundationType = FoundationType.PAD,
+    ) -> None:
+        r"""
         :param depth: Depth of foundation (m).
-        :type depth: float
-
         :param footing_size: Represents the size of the foundation footing.
-        :type footing_size: FootingSize
-
-        :param eccentricity: The deviation of the foundation load from the
-                             center of gravity of the foundation footing (m),
-                             defaults to 0.0. This means that the foundation 
-                             load aligns with the center of gravity of the 
-                             foundation footing.
-        :type eccentricity: float, optional
-
-        :param ground_water_level: Depth of the water below ground level (m),
-                                   defaults to None.
-        :type ground_water_level: float, optional
-
-        :param foundation_type: Type of foundation, defaults to
-                                :py:enum:mem:`~FoundationType.PAD`
-        :type foundation_type: FoundationType, optional
+        :param eccentricity: The deviation of the foundation load from
+                             the center of gravity of the foundation
+                             footing (m).
+        :param load_angle: Inclination of the applied load with the
+                           vertical ($\alpha^{\circ}$)
+        :param ground_water_level: Depth of the water below ground level
+                                   (m).
+        :param foundation_type: Type of foundation.
         """
         self.depth = depth
         self.footing_size = footing_size
         self.eccentricity = eccentricity
+        self.load_angle = load_angle
 
         self._ground_water_level = ground_water_level
-        self._foundation_type = foundation_type
+        self.foundation_type = foundation_type
 
     @property
     def depth(self) -> float:
@@ -259,8 +285,8 @@ class FoundationSize:
         return self._depth
 
     @depth.setter
-    @validators.gt(0.0)
-    def depth(self, val: float) -> None:
+    @validate_func_args
+    def depth(self, val: Annotated[float, MustBePositive]) -> None:
         self._depth = val
 
     @property
@@ -269,7 +295,7 @@ class FoundationSize:
         return self.footing_size.width
 
     @width.setter
-    def width(self, val: float):
+    def width(self, val: Annotated[float, MustBePositive]):
         self.footing_size.width = val
 
     @property
@@ -278,7 +304,7 @@ class FoundationSize:
         return self.footing_size.length
 
     @length.setter
-    def length(self, val: float):
+    def length(self, val: Annotated[float, MustBePositive]):
         self.footing_size.length = val
 
     @property
@@ -288,24 +314,37 @@ class FoundationSize:
 
     @property
     def eccentricity(self) -> float:
-        """The deviation of the foundation load from the center of gravity of
-        the foundation footing (m).
+        """The deviation of the foundation load from the center of
+        gravity of the foundation footing (m).
         """
         return self._eccentricity
 
     @eccentricity.setter
-    @validators.ge(0.0)
-    def eccentricity(self, val: float) -> None:
+    @validate_func_args
+    def eccentricity(self, val: Annotated[float, MustBeNonNegative]) -> None:
         self._eccentricity = val
 
+    @property
+    def load_angle(self) -> float:
+        """Inclination of the applied load with the  vertical."""
+        return self._load_angle
+
+    @load_angle.setter
+    @validate_func_args
+    def load_angle(
+            self,
+            val: Annotated[float, MustBeBetween(min_value=0.0, max_value=90.0)]
+    ) -> None:
+        self._load_angle = val
+
     @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
-    @validators.ge(0.0)
-    def ground_water_level(self, val: float) -> None:
+    @validate_func_args
+    def ground_water_level(self, val: Annotated[float, MustBePositive]):
         self._ground_water_level = val
 
     @property
@@ -313,18 +352,25 @@ class FoundationSize:
         """Type of foundation."""
         return self._foundation_type
 
+    @foundation_type.setter
+    @validate_func_args
+    def foundation_type(
+            self,
+            val: Annotated[FoundationType, MustBeMemberOf(FoundationType)]
+    ):
+        self._foundation_type = val
+
     @property
     def effective_width(self) -> float:
         """Returns the effective width of the foundation footing (m)."""
         return self.width - 2.0 * self.eccentricity
 
     def footing_params(self) -> tuple[float, float, Shape]:
-        """Returns the :attr:`effective_width`, :attr:`length`, and
-        :attr:`footing_shape` of the foundation footing.
+        """Returns the `effective_width`, `length`, and `footing_shape`
+        of the foundation footing.
         """
-        width, length, shape = (self.effective_width,
-                                self.length,
-                                self.footing_shape)
+        width, length, shape = (
+            self.effective_width, self.length, self.footing_shape)
 
         if not isclose(width, length) and shape != Shape.STRIP:
             shape = Shape.RECTANGLE
@@ -332,57 +378,43 @@ class FoundationSize:
         return width, length, shape
 
 
-def create_foundation(depth: float,
-                      width: 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.
+@validate_func_args
+def create_foundation(
+        depth: float,
+        width: float,
+        length: Optional[float] = None,
+        eccentricity: float = 0.0,
+        load_angle: float = 0.0,
+        ground_water_level: Optional[float] = None,
+        foundation_type: FoundationType = "pad",
+        shape: Annotated[Shape | str, MustBeMemberOf(Shape)] = "square",
+) -> Foundation:
+    r"""A factory function that encapsulate the creation of a foundation.
 
     :param depth: Depth of foundation (m).
-    :type depth: float
-
     :param width: Width of foundation footing. In the case of a circular
                   footing, it refers to the footing diameter (m).
-    :type width: float
-
     :param length: Length of foundation footing (m), defaults to None.
-    :type length: float, optional
-
     :param eccentricity: The deviation of the foundation load from the
                          center of gravity of the foundation footing (m),
                          defaults to 0.0. This means that the foundation
                          load aligns with the center of gravity of the
                          foundation footing .
-    :type eccentricity: float, optional
-
+    :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.
-    :type ground_water_level: float, optional
-
     :param foundation_type: Type of foundation footing, defaults to
                             :py:enum:mem:`~FoundationType.PAD`.
-    :type foundation_type: FoundationType, optional
-
-    :param shape: Shape of foundation footing, defaults to 
+    :param shape: Shape of foundation footing, defaults to
                   :py:enum:mem:`~Shape.SQUARE`
-    :type shape: Shape | str, optional
-
-    :raises ValueError: Raised when length is not provided for a rectangular
-                        footing.
-    :raises ValueError: Raised if an invalid footing shape is provided.
+    :raises ValueError: Raised when length is not provided for a
+                        rectangular footing.
+    :raises ValidationError: Raised if an invalid footing shape is
+                             provided.
     """
 
-    try:
-        shape = Shape(str(shape).casefold())
-    except ValueError as e:
-        msg = ErrorMsg(param_name="shape",
-                       param_value=shape,
-                       symbol="in",
-                       param_value_bound=list(Shape))
-        raise ValidationError(msg) from e
+    shape = Shape(str(shape).casefold())
 
     if shape is Shape.STRIP:
         footing_size = StripFooting(width=width)
@@ -392,14 +424,15 @@ def create_foundation(depth: float,
         footing_size = CircularFooting(diameter=width)
     else:  # RECTANGLE
         if not length:
-            msg = ErrorMsg(param_name="length",
-                           param_value=length,
-                           msg="Length of footing must be provided.")
-            raise ValidationError(msg)
+            msg = "Length of rectangular footing must be provided."
+            raise ValueError(msg)
         footing_size = RectangularFooting(width=width, length=length)
 
-    return FoundationSize(depth=depth,
-                          eccentricity=eccentricity,
-                          ground_water_level=ground_water_level,
-                          foundation_type=foundation_type,
-                          footing_size=footing_size)
+    return Foundation(
+        depth=depth,
+        eccentricity=eccentricity,
+        load_angle=load_angle,
+        ground_water_level=ground_water_level,
+        foundation_type=foundation_type,
+        footing_size=footing_size,
+    )