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

geolysis/__init__.py

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

geolysis/bearing_capacity/abc/__init__.py

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

geolysis/bearing_capacity/abc/_cohl/_core.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from typing import Annotated
 
 from func_validator import (
@@ -8,17 +9,26 @@ from func_validator import (
 )
 
 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
@@ -42,7 +52,8 @@ class AllowableBearingCapacity(ABC):
     @tol_settlement.setter
     @validate_func_args
     def tol_settlement(
-            self, tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)]
+        self,
+        tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
     ):
         self._tol_settlement = tol_settlement
 
@@ -56,11 +67,24 @@ 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(),
-        }
+    def bearing_capacity_results(self) -> AllowableBearingCapacityResult:
+        """Return a dictionary of 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):
+        """Calculates the allowable bearing capacity.
+
+        !!! info "Added in v0.12.0"
+        """
+        return self._bearing_capacity()
 
     @abstractmethod
-    def bearing_capacity(self): ...
+    def _bearing_capacity(self): ...

geolysis/bearing_capacity/abc/_cohl/bowles_abc.py

@@ -8,35 +8,16 @@ 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
+    See [implementation](../formulas/allowable-bearing-capacity.md/#bowles-bearing-capacity-for-pad-foundation)
+    for more details on bearing capacity equation used.
 
     """
 
     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
@@ -54,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.
         """
@@ -65,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()
         )
 
 
@@ -77,25 +58,13 @@ 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
-    $$
+    See [implementation](../formulas/allowable-bearing-capacity.md/#bowles-bearing-capacity-for-mat-foundation)
+    for more details on bearing capacity equation used.
 
-    - $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:
+    def _bearing_capacity(self) -> float:
         """
         Calculate the allowable bearing capacity of the mat foundation.
         """

geolysis/bearing_capacity/abc/_cohl/meyerhof_abc.py

@@ -5,37 +5,19 @@ from ._core import AllowableBearingCapacity
 
 
 class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
-    r"""Allowable bearing capacity for pad foundation on cohesionless
+    """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
+    See [implementation](../formulas/allowable-bearing-capacity.md/#meyerhof-bearing-capacity-for-pad-foundation)
+    for more details on bearing capacity equation used.
 
     """
 
     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
@@ -53,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.
         """
@@ -64,37 +46,25 @@ 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()
         )
 
 
 class MeyerhofABC4MatFoundation(MeyerhofABC4PadFoundation):
-    r"""Allowable bearing capacity for mat foundation on cohesionless
+    """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
-    $$
+    See [implementation](../formulas/allowable-bearing-capacity.md/#meyerhof-bearing-capacity-for-mat-foundation)
+    for more details on bearing capacity equation used.
 
-    - $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):
+    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

@@ -5,47 +5,19 @@ from ._core import AllowableBearingCapacity
 
 
 class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
-    r"""Allowable bearing capacity for pad foundation on cohesionless
+    """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
+    See [implementation](../formulas/allowable-bearing-capacity.md/#terzaghi-bearing-capacity-for-pad-foundation)
+    for more details on bearing capacity equation used.
 
     """
 
     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
@@ -85,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.
         """
@@ -96,11 +68,11 @@ 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:
@@ -110,37 +82,16 @@ class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
 
 
 class TerzaghiABC4MatFoundation(TerzaghiABC4PadFoundation):
-    r"""Allowable bearing capacity for mat foundation on cohesionless
+    """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
+    See [implementation](../formulas/allowable-bearing-capacity.md/#terzaghi-bearing-capacity-for-mat-foundation)
+    for more details on bearing capacity equation used.
+
     """
 
     @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

@@ -16,13 +16,13 @@ from ._terzaghi_ubc import (
 from ._vesic_ubc import VesicUltimateBearingCapacity
 
 __all__ = [
-    "UBCType",
     "TerzaghiUBC4StripFooting",
     "TerzaghiUBC4CircularFooting",
     "TerzaghiUBC4RectangularFooting",
     "TerzaghiUBC4SquareFooting",
     "HansenUltimateBearingCapacity",
     "VesicUltimateBearingCapacity",
+    "UBCType",
     "create_ubc_4_all_soil_types",
 ]
 
@@ -52,12 +52,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,
         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 +71,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).
@@ -108,6 +110,7 @@ def create_ubc_4_all_soil_types(
         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,
     )