geolysis 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

geolysis/__init__.py

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

geolysis/bearing_capacity/abc/__init__.py

@@ -0,0 +1,21 @@
+from ._cohl import (
+    ABCType,
+    create_abc_4_cohesionless_soils,
+    BowlesABC4PadFoundation,
+    BowlesABC4MatFoundation,
+    MeyerhofABC4MatFoundation,
+    MeyerhofABC4PadFoundation,
+    TerzaghiABC4MatFoundation,
+    TerzaghiABC4PadFoundation,
+)
+
+__all__ = [
+    "create_abc_4_cohesionless_soils",
+    "ABCType",
+    "BowlesABC4PadFoundation",
+    "BowlesABC4MatFoundation",
+    "MeyerhofABC4PadFoundation",
+    "MeyerhofABC4MatFoundation",
+    "TerzaghiABC4PadFoundation",
+    "TerzaghiABC4MatFoundation",
+]

geolysis/bearing_capacity/abc/_cohl/__init__.py

@@ -0,0 +1,109 @@
+import enum
+from typing import Optional, Annotated
+
+from func_validator import MustBeMemberOf, validate_func_args
+
+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
+from .terzaghi_abc import TerzaghiABC4MatFoundation, TerzaghiABC4PadFoundation
+
+
+class ABCType(AbstractStrEnum):
+    """Enumeration of allowable bearing capacity calculation methods.
+
+    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"""
+
+    MEYERHOF = enum.auto()
+    """Meyerhof's method for calculating allowable bearing capacity"""
+
+    TERZAGHI = enum.auto()
+    """Terzaghi's method for calculating allowable bearing capacity"""
+
+
+@validate_func_args
+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",
+) -> AllowableBearingCapacity:
+    r"""A factory function that encapsulate the creation of  allowable
+     bearing capacities.
+
+    :param corrected_spt_n_value: The corrected SPT N-value.
+    :param tol_settlement: Tolerable settlement of foundation (mm).
+    :param depth: Depth of foundation (m).
+    :param width: Width of foundation footing (m).
+    :param length: Length of foundation footing (m).
+    :param eccentricity: The deviation of the foundation load from the
+                         center of gravity of the foundation footing (m).
+    :param ground_water_level: Depth of water below ground level (m).
+    :param shape: Shape of foundation footing
+    :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)
+
+    # exception from create_foundation will automaatically propagate
+    # no need to catch and handle it.
+    fnd_size = create_foundation(
+        depth=depth,
+        width=width,
+        length=length,
+        eccentricity=eccentricity,
+        ground_water_level=ground_water_level,
+        foundation_type=foundation_type,
+        shape=shape,
+    )
+
+    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 → _cohl}/_core.py

@@ -1,16 +1,25 @@
 from abc import ABC, abstractmethod
+from typing import Annotated
+
+from func_validator import (
+    validate_func_args,
+    MustBeNonNegative,
+    MustBeLessThanOrEqual,
+)
 
 from geolysis.foundation import Foundation
-from geolysis.utils import validators
 
 
 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) -> None:
+    def __init__(
+            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
         self.foundation_size = foundation_size
@@ -21,8 +30,8 @@ class AllowableBearingCapacity(ABC):
         return self._corrected_spt_n_value
 
     @corrected_spt_n_value.setter
-    @validators.ge(0.0)
-    def corrected_spt_n_value(self, val: float) -> None:
+    @validate_func_args
+    def corrected_spt_n_value(self, val: Annotated[float, MustBeNonNegative]):
         self._corrected_spt_n_value = val
 
     @property
@@ -31,8 +40,10 @@ class AllowableBearingCapacity(ABC):
         return self._tol_settlement
 
     @tol_settlement.setter
-    @validators.le(25.4)
-    def tol_settlement(self, tol_settlement: float) -> None:
+    @validate_func_args
+    def tol_settlement(
+            self, tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)]
+    ):
         self._tol_settlement = tol_settlement
 
     def _sr(self) -> float:
@@ -45,5 +56,11 @@ 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 {
+            "bearing_capacity": self.bearing_capacity(),
+            "depth_factor": self._fd(),
+        }
+
     @abstractmethod
     def bearing_capacity(self): ...

geolysis/bearing_capacity/abc/_cohl/bowles_abc.py

@@ -0,0 +1,103 @@
+from geolysis.foundation import Foundation
+from geolysis.utils import round_
+
+from ._core import AllowableBearingCapacity
+
+
+class BowlesABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless
+    soils according to `Bowles (1997)`.
+
+    $$
+     q_a(kPa) = 19.16(N_1)_{55} f_d\left(\dfrac{S}{25.4}\right),
+                \ B \ \le \ 1.2m
+     $$
+
+     $$
+     q_a(kPa) = 11.98(N_1)_{55}\left(\dfrac{3.28B + 1}{3.28B} \right)^2
+                     f_d \left(\dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+     $$
+
+     $$
+     f_d = 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+     $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+
+    """
+
+    def __init__(
+            self,
+            corrected_spt_n_value: float,
+            tol_settlement: float,
+            foundation_size: Foundation,
+    ) -> None:
+        """
+        :param corrected_spt_n_value: Statistical average of corrected
+                                      SPT N-value (55% energy with
+                                      overburden pressure correction)
+                                      within the foundation influence
+                                      zone i.e `0.5B` to `2B`.
+        :param tol_settlement: Tolerable settlement of foundation (mm).
+        :param foundation_size: Size of the foundation.
+        """
+        super().__init__(
+            corrected_spt_n_value=corrected_spt_n_value,
+            tol_settlement=tol_settlement,
+            foundation_size=foundation_size,
+        )
+
+    @round_(ndigits=2)
+    def bearing_capacity(self) -> float:
+        """
+        Calculate the allowable bearing capacity of the pad foundation.
+        """
+        n_corr = self.corrected_spt_n_value
+        width = self.foundation_size.width
+
+        if width <= 1.2:
+            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()
+        )
+
+
+class BowlesABC4MatFoundation(BowlesABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless
+    soils according to `Bowles (1997)`.
+
+    $$
+     q_a(kPa) = 11.98(N_1)_{55}f_d\left(\dfrac{S}{25.4}\right)
+    $$
+
+    $$
+    f_d = 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+    $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+    """
+
+    @round_(ndigits=2)
+    def bearing_capacity(self) -> float:
+        """
+        Calculate the allowable bearing capacity of the mat foundation.
+        """
+        n_corr = self.corrected_spt_n_value
+        return 11.98 * n_corr * self._fd() * self._sr()

geolysis/bearing_capacity/abc/_cohl/meyerhof_abc.py

@@ -0,0 +1,100 @@
+from geolysis.foundation import Foundation
+from geolysis.utils import round_
+
+from ._core import AllowableBearingCapacity
+
+
+class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless
+    soils according to `Meyerhof (1956)`.
+
+    $$
+     q_a(kPa) = 12N f_d\left(\dfrac{S}{25.4}\right), \ B \ \le 1.2m
+     $$
+
+     $$
+     q_a(kPa) = 8N\left(\dfrac{3.28B + 1}{3.28B} \right)^2 f_d\left(
+                \dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+     $$
+
+     $$
+     f_d = 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+     $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+
+    """
+
+    def __init__(
+            self,
+            corrected_spt_n_value: float,
+            tol_settlement: float,
+            foundation_size: Foundation,
+    ):
+        """
+        :param corrected_spt_n_value: Average uncorrected SPT N-value
+                                      (60% energy with dilatancy (water)
+                                      correction if applicable) within
+                                      the foundation influence zone i.e.
+                                      $D_f$ to $D_f + 2B$.
+        :param tol_settlement: Tolerable settlement of foundation (mm).
+        :param foundation_size: Size of the foundation.
+        """
+        super().__init__(
+            corrected_spt_n_value=corrected_spt_n_value,
+            tol_settlement=tol_settlement,
+            foundation_size=foundation_size,
+        )
+
+    @round_(ndigits=2)
+    def bearing_capacity(self):
+        """
+        Calculates the allowable bearing capacity of the pad foundation.
+        """
+        n_corr = self.corrected_spt_n_value
+        width = self.foundation_size.width
+
+        if width <= 1.2:
+            return 12 * n_corr * self._fd() * self._sr()
+
+        return (
+                8
+                * n_corr
+                * ((3.28 * width + 1) / (3.28 * width)) ** 2
+                * self._fd()
+                * self._sr()
+        )
+
+
+class MeyerhofABC4MatFoundation(MeyerhofABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless
+    soils according to `Meyerhof (1956)`.
+
+    $$
+     q_a(kPa) = 8 N f_d\left(\dfrac{S}{25.4}\right)
+    $$
+
+    $$
+     f_d = 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+    $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+    """
+
+    @round_(ndigits=2)
+    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

@@ -0,0 +1,148 @@
+from geolysis.foundation import Foundation
+from geolysis.utils import round_
+
+from ._core import AllowableBearingCapacity
+
+
+class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless
+    soils according to `Terzaghi & Peck (1948)`.
+
+    $$
+     q_a(kPa) = 12N \dfrac{1}{c_w f_d}\left(\dfrac{S}{25.4}\right),
+                 \ B \ \le 1.2m
+    $$
+
+    $$
+     q_a(kPa) = 8N\left(\dfrac{3.28B + 1}{3.28B} \right)^2\dfrac{1}
+                 {c_w f_d}\left(\dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+    $$
+
+    $$
+     f_d = 1 + 0.25 \cdot \frac{D_f}{B} \le 1.25
+    $$
+
+    $$
+     c_w = 2 - \frac{D_w}{2B} \le 2, D_w \gt D_f
+    $$
+
+    $$
+     c_w = 2 - \frac{D_f}{2B} \le 2, D_w \le D_f
+    $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $c_w$: Water correction factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+
+    """
+
+    def __init__(
+            self,
+            corrected_spt_n_value: float,
+            tol_settlement: float,
+            foundation_size: Foundation,
+    ) -> None:
+        """
+        :param corrected_spt_n_value: Lowest (or average) uncorrected
+                                      SPT N-value (60% energy) within
+                                      the foundation influence zone i.e.
+                                      $D_f$ to $D_f + 2B$
+        :param tol_settlement: Tolerable settlement of foundation (mm).
+        :param foundation_size: Size of the foundation.
+        """
+        super().__init__(
+            corrected_spt_n_value=corrected_spt_n_value,
+            tol_settlement=tol_settlement,
+            foundation_size=foundation_size,
+        )
+
+    def _fd(self) -> float:
+        """Calculate the depth factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+
+        return min(1.0 + 0.25 * depth / width, 1.25)
+
+    def _cw(self):
+        """Calculate the water correction factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+        water_level = self.foundation_size.ground_water_level
+
+        if water_level is None:
+            return 2.0
+
+        if water_level <= depth:
+            cw = 2.0 - depth / (2.0 * width)
+        else:
+            cw = 2.0 - water_level / (2.0 * width)
+
+        return min(cw, 2.0)
+
+    @round_(ndigits=2)
+    def bearing_capacity(self):
+        """
+        Calculates the allowable bearing capacity of the pad foundation.
+        """
+        n_corr = self.corrected_spt_n_value
+        width = self.foundation_size.width
+
+        if width <= 1.2:
+            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()
+        )
+
+    def bearing_capacity_results(self) -> dict:
+        res = super().bearing_capacity_results()
+        res["water_correction_factor"] = self._cw()
+        return res
+
+
+class TerzaghiABC4MatFoundation(TerzaghiABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless
+    soils according to `Terzaghi & Peck (1948)`.
+
+    $$
+     q_a(kPa) = 8N\dfrac{1}{c_w f_d}\left(\dfrac{S}{25.4}\right)
+    $$
+
+    $$
+     f_d = 1 + 0.25 \cdot \frac{D_f}{B} \le 1.25
+    $$
+
+    $$
+     c_w = 2 - \frac{D_w}{2B} \le 2, D_w \gt D_f
+    $$
+
+    $$
+     c_w = 2 - \frac{D_f}{2B} \le 2, D_w \le D_f
+    $$
+
+    - $q_a$ (kPa): Allowable bearing capacity
+    - $N$: Corrected SPT N-value
+    - $f_d$: Depth factor
+    - $c_w$: Water correction factor
+    - $S$ (mm): Tolerable settlement
+    - $B$ (m): Width of foundation footing
+    - $D_f$ (m): Depth of foundation footing
+    - $D_w$ (m): Depth of water below ground level
+    """
+
+    @round_(ndigits=2)
+    def bearing_capacity(self):
+        """
+        Calculates the allowable bearing capacity of the mat foundation.
+        """
+        n_corr = self.corrected_spt_n_value
+        return 8 * n_corr * (1 / (self._cw() * self._fd())) * self._sr()