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

geolysis/__init__.py

@@ -1,5 +1,5 @@
 from . import bearing_capacity, foundation, soil_classifier, spt
 
-__version__ = "0.11.0"
+__version__ = "0.13.0"
 
 __all__ = ["foundation", "soil_classifier", "spt", "bearing_capacity"]

geolysis/bearing_capacity/abc/_cohl/__init__.py

@@ -1,10 +1,11 @@
 import enum
 from typing import Optional, Annotated
 
-from func_validator import MustBeMemberOf, validate_func_args
+from func_validator import MustBeMemberOf, validate_params
 
 from geolysis.foundation import FoundationType, Shape, create_foundation
 from geolysis.utils import AbstractStrEnum, inf
+
 from ._core import AllowableBearingCapacity
 from .bowles_abc import BowlesABC4MatFoundation, BowlesABC4PadFoundation
 from .meyerhof_abc import MeyerhofABC4MatFoundation, MeyerhofABC4PadFoundation
@@ -16,7 +17,7 @@ class ABCType(AbstractStrEnum):
 
     Each member represents a different method for determining
     the allowable bearing capacity of soil.
-   """
+    """
 
     BOWLES = enum.auto()
     """Bowles's method for calculating allowable bearing capacity"""
@@ -28,20 +29,34 @@ class ABCType(AbstractStrEnum):
     """Terzaghi's method for calculating allowable bearing capacity"""
 
 
-@validate_func_args
+abc_classes = {
+    ABCType.BOWLES: {
+        FoundationType.PAD: BowlesABC4PadFoundation,
+        FoundationType.MAT: BowlesABC4MatFoundation,
+    },
+    ABCType.MEYERHOF: {
+        FoundationType.PAD: MeyerhofABC4PadFoundation,
+        FoundationType.MAT: MeyerhofABC4MatFoundation,
+    },
+    ABCType.TERZAGHI: {
+        FoundationType.PAD: TerzaghiABC4PadFoundation,
+        FoundationType.MAT: TerzaghiABC4MatFoundation,
+    },
+}
+
+
+@validate_params
 def create_abc_4_cohesionless_soils(
-        corrected_spt_n_value: float,
-        tol_settlement: float,
-        depth: float,
-        width: float,
-        length: Optional[float] = None,
-        eccentricity: float = 0.0,
-        ground_water_level: float = inf,
-        shape: Shape | str = "square",
-        foundation_type: Annotated[
-            FoundationType | str, MustBeMemberOf(FoundationType)
-        ] = "pad",
-        abc_type: Annotated[ABCType | str, MustBeMemberOf(ABCType)] = "bowles",
+    corrected_spt_n_value: float,
+    tol_settlement: float,
+    depth: float,
+    width: float,
+    length: Optional[float] = None,
+    eccentricity: float = 0.0,
+    ground_water_level: float = inf,
+    shape: Shape | str = "square",
+    foundation_type: FoundationType | str = "pad",
+    abc_type: Annotated[ABCType | str, MustBeMemberOf(ABCType)] = "bowles",
 ) -> AllowableBearingCapacity:
     r"""A factory function that encapsulate the creation of  allowable
      bearing capacities.
@@ -58,13 +73,6 @@ def create_abc_4_cohesionless_soils(
     :param foundation_type: Type of foundation.
     :param abc_type: Type of allowable bearing capacity calculation to
                      apply.
-
-    :raises ValidationError: Raised if `abc_type` or `foundation_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.
     """
     abc_type = ABCType(abc_type)
     foundation_type = FoundationType(foundation_type)
@@ -80,30 +88,10 @@ def create_abc_4_cohesionless_soils(
         foundation_type=foundation_type,
         shape=shape,
     )
+    abc_class = abc_classes[abc_type][foundation_type]
 
-    abc_class = _get_allowable_bearing_capacity(abc_type,
-                                                fnd_size.foundation_type)
     return abc_class(
         corrected_spt_n_value=corrected_spt_n_value,
         tol_settlement=tol_settlement,
         foundation_size=fnd_size,
     )
-
-
-def _get_allowable_bearing_capacity(abc_type: ABCType,
-                                    foundation_type: FoundationType):
-    abc_classes = {
-        ABCType.BOWLES: {
-            FoundationType.PAD: BowlesABC4PadFoundation,
-            FoundationType.MAT: BowlesABC4MatFoundation,
-        },
-        ABCType.MEYERHOF: {
-            FoundationType.PAD: MeyerhofABC4PadFoundation,
-            FoundationType.MAT: MeyerhofABC4MatFoundation,
-        },
-        ABCType.TERZAGHI: {
-            FoundationType.PAD: TerzaghiABC4PadFoundation,
-            FoundationType.MAT: TerzaghiABC4MatFoundation,
-        },
-    }
-    return abc_classes[abc_type][foundation_type]

geolysis/bearing_capacity/abc/_cohl/_core.py

@@ -1,24 +1,34 @@
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from typing import Annotated
 
 from func_validator import (
-    validate_func_args,
+    validate_params,
     MustBeNonNegative,
     MustBeLessThanOrEqual,
 )
 
 from geolysis.foundation import Foundation
+from geolysis.utils import round_, add_repr
 
 
+@dataclass
+class AllowableBearingCapacityResult:
+    allowable_bearing_capacity: float
+    depth_factor: float
+    water_correction_factor: float = 1.0
+
+
+@add_repr
 class AllowableBearingCapacity(ABC):
     #: Maximum tolerable foundation settlement (mm).
     MAX_TOL_SETTLEMENT = 25.4
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         self.corrected_spt_n_value = corrected_spt_n_value
         self.tol_settlement = tol_settlement
@@ -30,9 +40,12 @@ class AllowableBearingCapacity(ABC):
         return self._corrected_spt_n_value
 
     @corrected_spt_n_value.setter
-    @validate_func_args
-    def corrected_spt_n_value(self, val: Annotated[float, MustBeNonNegative]):
-        self._corrected_spt_n_value = val
+    @validate_params
+    def corrected_spt_n_value(
+        self,
+        corrected_spt_n_value: Annotated[float, MustBeNonNegative],
+    ):
+        self._corrected_spt_n_value = corrected_spt_n_value
 
     @property
     def tol_settlement(self) -> float:
@@ -40,10 +53,10 @@ class AllowableBearingCapacity(ABC):
         return self._tol_settlement
 
     @tol_settlement.setter
-    @validate_func_args
+    @validate_params
     def tol_settlement(
-            self,
-            tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
+        self,
+        tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
     ):
         self._tol_settlement = tol_settlement
 
@@ -57,17 +70,27 @@ class AllowableBearingCapacity(ABC):
         width = self.foundation_size.width
         return min(1.0 + 0.33 * depth / width, 1.33)
 
-    def bearing_capacity_results(self) -> dict:
-        """Return a dictionary of bearing capacity results with
-        intermediate calculations.
+    def bearing_capacity_results(self) -> AllowableBearingCapacityResult:
+        """Return bearing capacity results with intermediate calculations.
 
         !!! info "Added in v0.11.0"
+        """
+        return AllowableBearingCapacityResult(
+            allowable_bearing_capacity=self.allowable_bearing_capacity(),
+            depth_factor=self._fd(),
+        )
+
+    @round_(ndigits=1)
+    def allowable_bearing_capacity(self) -> float:
+        """Calculates the allowable bearing capacity.
 
+        !!! info "Added in v0.12.0"
         """
-        return {
-            "bearing_capacity": self.bearing_capacity(),
-            "depth_factor": self._fd(),
-        }
+        return self._bearing_capacity()
+
+    def allowable_applied_load(self) -> float:
+        """Calculate the allowable applied load on the foundation."""
+        return self._bearing_capacity() * self.foundation_size.foundation_area()
 
     @abstractmethod
-    def bearing_capacity(self): ...
+    def _bearing_capacity(self) -> float: ...

geolysis/bearing_capacity/abc/_cohl/bowles_abc.py

@@ -14,10 +14,10 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         """
         :param corrected_spt_n_value: Statistical average of corrected
@@ -35,7 +35,7 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
         )
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """
         Calculate the allowable bearing capacity of the pad foundation.
         """
@@ -46,11 +46,11 @@ class BowlesABC4PadFoundation(AllowableBearingCapacity):
             return 19.16 * n_corr * self._fd() * self._sr()
 
         return (
-                11.98
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * self._fd()
-                * self._sr()
+            11.98
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * self._fd()
+            * self._sr()
         )
 
 
@@ -64,7 +64,7 @@ class BowlesABC4MatFoundation(BowlesABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self) -> float:
+    def _bearing_capacity(self) -> float:
         """
         Calculate the allowable bearing capacity of the mat foundation.
         """

geolysis/bearing_capacity/abc/_cohl/meyerhof_abc.py

@@ -14,10 +14,10 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ):
         """
         :param corrected_spt_n_value: Average uncorrected SPT N-value
@@ -35,7 +35,7 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
         )
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the pad foundation.
         """
@@ -46,11 +46,11 @@ class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
             return 12 * n_corr * self._fd() * self._sr()
 
         return (
-                8
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * self._fd()
-                * self._sr()
+            8
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * self._fd()
+            * self._sr()
         )
 
 
@@ -64,7 +64,7 @@ class MeyerhofABC4MatFoundation(MeyerhofABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """Calculate the allowable bearing capacity of the mat foundation."""
         n_corr = self.corrected_spt_n_value
         return 8 * n_corr * self._fd() * self._sr()

geolysis/bearing_capacity/abc/_cohl/terzaghi_abc.py

@@ -1,7 +1,7 @@
 from geolysis.foundation import Foundation
-from geolysis.utils import round_
+from geolysis.utils import round_, isinf
 
-from ._core import AllowableBearingCapacity
+from ._core import AllowableBearingCapacity, AllowableBearingCapacityResult
 
 
 class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
@@ -14,10 +14,10 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
     """
 
     def __init__(
-            self,
-            corrected_spt_n_value: float,
-            tol_settlement: float,
-            foundation_size: Foundation,
+        self,
+        corrected_spt_n_value: float,
+        tol_settlement: float,
+        foundation_size: Foundation,
     ) -> None:
         """
         :param corrected_spt_n_value: Lowest (or average) uncorrected
@@ -46,7 +46,7 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
         width = self.foundation_size.width
         water_level = self.foundation_size.ground_water_level
 
-        if water_level is None:
+        if isinf(water_level):
             return 2.0
 
         if water_level <= depth:
@@ -57,7 +57,7 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
         return min(cw, 2.0)
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the pad foundation.
         """
@@ -68,16 +68,16 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
             return 12 * n_corr * (1 / (self._cw() * self._fd())) * self._sr()
 
         return (
-                8
-                * n_corr
-                * ((3.28 * width + 1) / (3.28 * width)) ** 2
-                * (1 / (self._cw() * self._fd()))
-                * self._sr()
+            8
+            * n_corr
+            * ((3.28 * width + 1) / (3.28 * width)) ** 2
+            * (1 / (self._cw() * self._fd()))
+            * self._sr()
         )
 
-    def bearing_capacity_results(self) -> dict:
+    def bearing_capacity_results(self) -> AllowableBearingCapacityResult:
         res = super().bearing_capacity_results()
-        res["water_correction_factor"] = self._cw()
+        res.water_correction_factor = self._cw()
         return res
 
 
@@ -91,7 +91,7 @@ class TerzaghiABC4MatFoundation(TerzaghiABC4PadFoundation):
     """
 
     @round_(ndigits=2)
-    def bearing_capacity(self):
+    def _bearing_capacity(self):
         """
         Calculates the allowable bearing capacity of the mat foundation.
         """

geolysis/bearing_capacity/ubc/__init__.py

@@ -1,12 +1,12 @@
 import enum
 from typing import Optional, Annotated
 
-from func_validator import MustBeMemberOf, validate_func_args
+from func_validator import MustBeMemberOf, validate_params
 
 from geolysis.foundation import Shape, create_foundation
-from geolysis.utils import AbstractStrEnum
+from geolysis.utils import AbstractStrEnum, inf
+
 from ._core import UltimateBearingCapacity
-from ._hansen_ubc import HansenUltimateBearingCapacity
 from ._terzaghi_ubc import (
     TerzaghiUBC4CircularFooting,
     TerzaghiUBC4RectangularFooting,
@@ -20,7 +20,6 @@ __all__ = [
     "TerzaghiUBC4CircularFooting",
     "TerzaghiUBC4RectangularFooting",
     "TerzaghiUBC4SquareFooting",
-    "HansenUltimateBearingCapacity",
     "VesicUltimateBearingCapacity",
     "UBCType",
     "create_ubc_4_all_soil_types",
@@ -44,7 +43,18 @@ class UBCType(AbstractStrEnum):
     """Vesic's method for calculating ultimate bearing capacity."""
 
 
-@validate_func_args
+ubc_classes = {
+    UBCType.TERZAGHI: {
+        Shape.STRIP: TerzaghiUBC4StripFooting,
+        Shape.CIRCLE: TerzaghiUBC4CircularFooting,
+        Shape.SQUARE: TerzaghiUBC4SquareFooting,
+        Shape.RECTANGLE: TerzaghiUBC4RectangularFooting,
+    },
+    UBCType.VESIC: VesicUltimateBearingCapacity,
+}
+
+
+@validate_params
 def create_ubc_4_all_soil_types(
     friction_angle: float,
     cohesion: float,
@@ -52,12 +62,13 @@ def create_ubc_4_all_soil_types(
     depth: float,
     width: float,
     length: Optional[float] = None,
+    saturated_unit_wgt: float = 20.5,
     eccentricity: float = 0.0,
-    ground_water_level: Optional[float] = None,
+    ground_water_level: Optional[float] = inf,
     load_angle: float = 0.0,
     apply_local_shear: bool = False,
     shape: Shape | str = "square",
-    ubc_type: Annotated[UBCType | str, MustBeMemberOf(UBCType)] = "hansen",
+    ubc_type: Annotated[UBCType | str, MustBeMemberOf(UBCType)] = "vesic",
 ) -> UltimateBearingCapacity:
     r"""A factory function that encapsulate the creation of ultimate
     bearing capacity.
@@ -70,6 +81,7 @@ def create_ubc_4_all_soil_types(
     :param depth: Depth of foundation (m).
     :param width: Width of foundation footing (m).
     :param length: Length of foundation footing (m).
+    :param saturated_unit_wgt: Saturated unit weight of soil ($kN/m^3$).
     :param eccentricity: The deviation of the foundation load from the
                          center of gravity of the foundation footing.
     :param ground_water_level: Depth of water below ground level (m).
@@ -84,8 +96,8 @@ def create_ubc_4_all_soil_types(
     :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.
+    :raises ValidationError: Raised when length is not provided for a
+                             rectangular footing.
     """
     ubc_type = UBCType(ubc_type)
 
@@ -100,31 +112,16 @@ def create_ubc_4_all_soil_types(
         ground_water_level=ground_water_level,
         shape=shape,
     )
+    ubc_class = ubc_classes[ubc_type]
 
-    ubc_class = _get_ultimate_bearing_capacity(ubc_type, fnd_size.footing_shape)
+    if ubc_type == UBCType.TERZAGHI:
+        ubc_class = ubc_classes[ubc_type][fnd_size.footing_shape]
 
     return ubc_class(
         friction_angle=friction_angle,
         cohesion=cohesion,
         moist_unit_wgt=moist_unit_wgt,
+        saturated_unit_wgt=saturated_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][foundation_shape]
-    else:
-        ubc_class = ubc_classes[ubc_type]
-    return ubc_class