geolysis 0.4.3__py3-none-any.whl → 0.4.4__py3-none-any.whl

geolysis/bearing_capacity/ubc/terzaghi_ubc.py

@@ -0,0 +1,258 @@
+""" Terzaghi ultimate bearing capacity module.
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
+
+    TerzaghiUBC4StripFooting
+    TerzaghiUBC4CircularFooting
+    TerzaghiUBC4SquareFooting
+    TerzaghiUBC4RectangularFooting
+"""
+from abc import ABC
+
+from geolysis.bearing_capacity.ubc import UltimateBearingCapacity
+from geolysis.utils import cos, cot, deg2rad, exp, isclose, pi, round_, tan
+
+__all__ = ["TerzaghiUBC4StripFooting",
+           "TerzaghiUBC4CircularFooting",
+           "TerzaghiUBC4SquareFooting",
+           "TerzaghiUBC4RectangularFooting"]
+
+
+@round_
+def n_c(friction_angle: float) -> float:
+    if isclose(friction_angle, 0.0):
+        return 5.7
+    return cot(friction_angle) * (n_q(friction_angle) - 1.0)
+
+
+@round_
+def n_q(friction_angle: float) -> float:
+    return (exp((3.0 * pi / 2.0 - deg2rad(friction_angle))
+                * tan(friction_angle))
+            / (2.0 * (cos(45.0 + friction_angle / 2.0)) ** 2.0))
+
+
+@round_
+def n_gamma(friction_angle: float) -> float:
+    return (n_q(friction_angle) - 1.0) * tan(1.4 * friction_angle)
+
+
+class TerzaghiUltimateBearingCapacity(UltimateBearingCapacity, ABC):
+
+    @property
+    def n_c(self) -> float:
+        r"""Bearing capacity factor :math:`N_c`.
+
+        :Equation:
+
+        .. math:: N_c = \cot(\phi) \cdot (N_q - 1)
+        """
+        return n_c(self.friction_angle)
+
+    @property
+    def n_q(self) -> float:
+        r"""Bearing capacity factor :math:`N_q`.
+
+        :Equation:
+
+        .. math::
+
+            N_q = \dfrac{e^{(\frac{3\pi}{2} - \phi)\tan\phi}}
+                      {2\cos^2(45 + \frac{\phi}{2})}
+        """
+        return n_q(self.friction_angle)
+
+    @property
+    def n_gamma(self) -> float:
+        r"""Bearing capacity factor :math:`N_{\gamma}`.
+
+        :Equation:
+
+        .. math:: N_{\gamma} &=  (N_q - 1) \cdot \tan(1.4\phi)
+        """
+        return n_gamma(self.friction_angle)
+
+
+class TerzaghiUBC4StripFooting(TerzaghiUltimateBearingCapacity):
+    r"""Ultimate bearing capacity for strip footing according to
+    ``Terzaghi 1943``.
+
+    :Equation:
+
+    .. math:: q_u = cN_c + qN_q + 0.5 \gamma BN_{\gamma}
+
+    .. list-table::
+       :widths: auto
+       :header-rows: 1
+
+       * - Symbol
+         - Description
+         - Unit
+       * - :math:`q_u`
+         - Ultimate bearing capacity
+         - :math:`kPa`
+       * - :math:`c`
+         - Cohesion of soil
+         - :math:`kPa`
+       * - :math:`q`
+         - Overburden pressure of soil
+         - :math:`kPa`
+       * - :math:`\gamma`
+         - Unit weight of soil
+         - :math:`kN/m^3`
+       * - :math:`B`
+         - Width of foundation footing
+         - :math:`m`
+       * - :math:`N_c`, :math:`N_q`, :math:`N_{\gamma}`
+         - Bearing capacity factors
+         - —
+    """
+
+    @round_
+    def bearing_capacity(self) -> float:
+        """Calculates ultimate bearing capacity for strip footing."""
+        return (self._cohesion_term(1.0)
+                + self._surcharge_term()
+                + self._embedment_term(0.5))
+
+
+class TerzaghiUBC4CircularFooting(TerzaghiUltimateBearingCapacity):
+    r"""Ultimate bearing capacity for circular footing according to
+    ``Terzaghi 1943``.
+
+    :Equation:
+
+    .. math:: q_u = 1.3cN_c + qN_q + 0.3 \gamma BN_{\gamma}
+
+    .. list-table::
+       :widths: auto
+       :header-rows: 1
+
+       * - Symbol
+         - Description
+         - Unit
+       * - :math:`q_u`
+         - Ultimate bearing capacity
+         - :math:`kPa`
+       * - :math:`c`
+         - Cohesion of soil
+         - :math:`kPa`
+       * - :math:`q`
+         - Overburden pressure of soil
+         - :math:`kPa`
+       * - :math:`\gamma`
+         - Unit weight of soil
+         - :math:`kN/m^3`
+       * - :math:`B`
+         - Width of foundation footing
+         - :math:`m`
+       * - :math:`N_c`, :math:`N_q`, :math:`N_{\gamma}`
+         - Bearing capacity factors
+         - —
+    """
+
+    @round_
+    def bearing_capacity(self) -> float:
+        """Calculates ultimate bearing capacity for circular footing."""
+        return (self._cohesion_term(1.3)
+                + self._surcharge_term()
+                + self._embedment_term(0.3))
+
+
+class TerzaghiUBC4RectangularFooting(TerzaghiUltimateBearingCapacity):
+    r"""Ultimate bearing capacity for rectangular footing according to
+    ``Terzaghi 1943``.
+
+    :Equation:
+
+    .. math::
+
+            q_u = \left(1 + 0.3 \dfrac{B}{L} \right) c N_c + qN_q
+                  + \left(1 - 0.2 \dfrac{B}{L} \right) 0.5 B \gamma N_{\gamma}
+
+    .. list-table::
+       :widths: auto
+       :header-rows: 1
+
+       * - Symbol
+         - Description
+         - Unit
+       * - :math:`q_u`
+         - Ultimate bearing capacity
+         - :math:`kPa`
+       * - :math:`c`
+         - Cohesion of soil
+         - :math:`kPa`
+       * - :math:`q`
+         - Overburden pressure of soil
+         - :math:`kPa`
+       * - :math:`\gamma`
+         - Unit weight of soil
+         - :math:`kN/m^3`
+       * - :math:`B`
+         - Width of foundation footing
+         - :math:`m`
+       * - :math:`L`
+         - Length of foundation footing
+         - :math:`m`
+       * - :math:`N_c`, :math:`N_q`, :math:`N_{\gamma}`
+         - Bearing capacity factors
+         - —
+    """
+
+    @round_
+    def bearing_capacity(self) -> float:
+        """Calculates ultimate bearing capacity for rectangular footing."""
+        width = self.foundation_size.width
+        length = self.foundation_size.length
+        coh_coef = 1.0 + 0.3 * (width / length)
+        emb_coef = (1.0 - 0.2 * (width / length)) / 2.0
+
+        return (self._cohesion_term(coh_coef)
+                + self._surcharge_term()
+                + self._embedment_term(emb_coef))
+
+
+class TerzaghiUBC4SquareFooting(TerzaghiUBC4RectangularFooting):
+    r"""Ultimate bearing capacity for square footing according to 
+    ``Terzaghi 1943``.
+
+    :Equation:
+
+    .. math:: q_u = 1.3cN_c + qN_q + 0.4 \gamma BN_{\gamma}
+
+    .. list-table::
+       :widths: auto
+       :header-rows: 1
+
+       * - Symbol
+         - Description
+         - Unit
+       * - :math:`q_u`
+         - Ultimate bearing capacity
+         - :math:`kPa`
+       * - :math:`c`
+         - Cohesion of soil
+         - :math:`kPa`
+       * - :math:`q`
+         - Overburden pressure of soil
+         - :math:`kPa`
+       * - :math:`\gamma`
+         - Unit weight of soil
+         - :math:`kN/m^3`
+       * - :math:`B`
+         - Width of foundation footing
+         - :math:`m`
+       * - :math:`N_c`, :math:`N_q`, :math:`N_{\gamma}`
+         - Bearing capacity factors
+         - —
+    """
+
+    def bearing_capacity(self):
+        """Calcalates ultimate bearing capacity for square footing.
+        """
+        return super().bearing_capacity()

geolysis/bearing_capacity/ubc/vesic_ubc.py

@@ -0,0 +1,302 @@
+"""Vesic ultimate bearing capacity module.
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
+
+    VesicUltimateBearingCapacity
+"""
+from geolysis.bearing_capacity.ubc import UltimateBearingCapacity
+from geolysis.bearing_capacity.ubc import hansen_ubc
+from geolysis.foundation import FoundationSize, Shape
+from geolysis.utils import isclose, round_, sin, tan
+
+__all__ = ["VesicUltimateBearingCapacity"]
+
+
+@round_
+def n_c(friction_angle: float) -> float:
+    return hansen_ubc.n_c(friction_angle)
+
+
+@round_
+def n_q(friction_angle: float) -> float:
+    return hansen_ubc.n_q(friction_angle)
+
+
+@round_
+def n_gamma(friction_angle: float) -> float:
+    return 2.0 * (n_q(friction_angle) + 1.0) * tan(friction_angle)
+
+
+@round_
+def s_c(friction_angle: float,
+        f_width: float,
+        f_length: float,
+        f_shape: Shape) -> float:
+    _n_q = n_q(friction_angle)
+    _n_c = 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)
+
+
+@round_
+def s_q(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)
+
+
+@round_
+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:
+        return 1.0 - 0.4 * (f_width / f_length)
+    else:  # SQUARE, CIRCLE
+        return 0.6
+
+
+@round_
+def d_c(f_depth: float, f_width: float) -> float:
+    return 1.0 + 0.4 * f_depth / f_width
+
+
+@round_
+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))
+
+
+@round_
+def d_gamma() -> float:
+    return 1.0
+
+
+@round_
+def i_c(load_angle: float) -> float:
+    return (1.0 - load_angle / 90.0) ** 2.0
+
+
+@round_
+def i_q(load_angle: float) -> float:
+    return i_c(load_angle)
+
+
+@round_
+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
+
+
+class VesicUltimateBearingCapacity(UltimateBearingCapacity):
+    r"""Ultimate bearing capacity for soils according to ``Vesic (1973)``.
+
+    :Equation:
+
+    .. math::
+
+            q_u = cN_c s_c d_c i_c + qN_q s_q d_q i_q
+                  + 0.5 \gamma B N_{\gamma} s_{\gamma} d_{\gamma} i_{\gamma}
+
+    .. list-table::
+       :widths: auto
+       :header-rows: 1
+
+       * - Symbol
+         - Description
+         - Unit
+       * - :math:`q_u`
+         - Ultimate bearing capacity
+         - :math:`kPa`
+       * - :math:`c`
+         - Cohesion of soil
+         - :math:`kPa`
+       * - :math:`q`
+         - Overburden pressure of soil
+         - :math:`kPa`
+       * - :math:`\gamma`
+         - Unit weight of soil
+         - :math:`kN/m^3`
+       * - :math:`B`
+         - Width of foundation footing
+         - :math:`m`
+       * - :math:`N_c`, :math:`N_q`, :math:`N_{\gamma}`
+         - Bearing capacity factors
+         - —
+       * - :math:`s_c`, :math:`s_q`, :math:`s_{\gamma}`
+         - Shape factors
+         - —
+       * - :math:`d_c`, :math:`d_q`, :math:`d_{\gamma}`
+         - Depth factors
+         - —
+       * - :math:`i_c`, :math:`i_q`, :math:`i_{\gamma}`
+         - Inclination factors
+         - —
+    """
+
+    @property
+    def n_c(self) -> float:
+        r"""Bearing capacity factor :math:`N_c`.
+
+        :Equation:
+
+        .. math:: N_c = \cot(\phi) \left(N_q - 1\right)
+        """
+        return n_c(self.friction_angle)
+
+    @property
+    def n_q(self) -> float:
+        r"""Bearing capacity factor :math:`N_q`.
+
+        :Equation:
+
+        .. math:: N_q = \tan^2\left(45 + \frac{\phi}{2}\right) \cdot
+                      e^{\pi \tan(\phi)}
+        """
+        return n_q(self.friction_angle)
+
+    @property
+    def n_gamma(self) -> float:
+        r"""Bearing capacity factor :math:`N_{\gamma}`.
+
+        :Equation:
+
+        .. math:: N_{\gamma} = 2(N_q + 1) \tan(\phi)
+        """
+        return n_gamma(self.friction_angle)
+
+    @property
+    def s_c(self) -> float:
+        r"""Shape factor :math:`S_c`.
+
+        :Equation:
+
+        .. math::
+
+             s_c &= 1.0 \rightarrow \text{Strip footing}
+
+             s_c &= 1 + \dfrac{B}{L} \cdot \dfrac{N_q}{N_c} \rightarrow
+                     \text{Rectangular footing}
+
+             s_c &= 1 + \dfrac{N_q}{N_c} \rightarrow
+                       \text{Square or circular footing}
+        """
+        width, length, shape = self.foundation_size.footing_params()
+        return s_c(self.friction_angle, width, length, shape)
+
+    @property
+    def s_q(self) -> float:
+        r"""Shape factor :math:`S_q`.
+
+        :Equation:
+
+        .. math::
+
+             s_q &= 1.0 \rightarrow \text{Strip footing}
+
+             s_q &= 1 + \dfrac{B}{L} \cdot \tan(\phi) \rightarrow
+                    \text{Rectangular footing}
+
+             s_q &= 1 + \tan(\phi) \rightarrow \text{Square or circular footing}
+        """
+        width, length, shape = self.foundation_size.footing_params()
+        return s_q(self.friction_angle, width, length, shape)
+
+    @property
+    def s_gamma(self) -> float:
+        r"""Shape factor :math:`S_{\gamma}`.
+
+        :Equation:
+
+        .. math::
+
+             s_{\gamma} &= 1.0 \rightarrow \text{Strip footing}
+
+             s_{\gamma} &= 1.0 - 0.4 \dfrac{B}{L} \rightarrow
+                          \text{Rectangular footing}
+
+             s_{\gamma} &= 0.6 \rightarrow \text{Square or circular footing}
+        """
+        width, length, shape = self.foundation_size.footing_params()
+        return s_gamma(width, length, shape)
+
+    @property
+    def d_c(self) -> float:
+        r"""Depth factor :math:`D_c`.
+
+        :Equation:
+
+        .. math:: d_c = 1 + 0.4 \dfrac{D_f}{B}
+        """
+        depth, width = self.foundation_size.depth, self.foundation_size.width
+        return d_c(depth, width)
+
+    @property
+    def d_q(self) -> float:
+        r"""Depth factor :math:`D_q`.
+
+        :Equation:
+
+        .. math::
+
+            d_q = 1 + 2 \tan(\phi) \cdot (1 - \sin(\phi))^2
+                  \cdot \dfrac{D_f}{B}
+        """
+        depth, width = self.foundation_size.depth, self.foundation_size.width
+        return d_q(self.friction_angle, depth, width)
+
+    @property
+    def d_gamma(self) -> float:
+        r"""Depth factor :math:`D_{\gamma}`.
+
+        :Equation:
+
+        .. math:: d_{\gamma} = 1.0
+        """
+        return d_gamma()
+
+    @property
+    def i_c(self) -> float:
+        r"""Inclination factor :math:`I_c`.
+
+        :Equation:
+
+        .. math:: i_c = (1 - \dfrac{\alpha}{90})^2
+        """
+        return i_c(self.load_angle)
+
+    @property
+    def i_q(self) -> float:
+        r"""Inclination factor :math:`I_q`.
+
+        :Equation:
+
+        .. math:: i_q = (1 - \dfrac{\alpha}{90})^2
+        """
+        return i_q(self.load_angle)
+
+    @property
+    def i_gamma(self) -> float:
+        r"""Inclination factor :math:`I_{\gamma}`.
+
+        :Equation:
+
+        .. math:: i_{\gamma} = \left(1 - \dfrac{\alpha}{\phi} \right)^2
+        """
+        return i_gamma(self.friction_angle, self.load_angle)

geolysis/foundation.py

@@ -35,7 +35,7 @@ import enum
 from abc import ABC, abstractmethod
 from typing import Optional, TypeVar
 
-from geolysis.utils import inf, enum_repr, isclose, validators
+from geolysis.utils import enum_repr, inf, isclose, validators
 
 __all__ = ["create_foundation",
            "FoundationSize",

geolysis/soil_classifier.py

@@ -40,10 +40,9 @@ Functions
 """
 import enum
 from abc import abstractmethod
-from typing import Protocol
-from typing import NamedTuple, Optional, Sequence
+from typing import NamedTuple, Optional, Protocol, Sequence
 
-from geolysis.utils import enum_repr, isclose, round_, validators
+from .utils import enum_repr, isclose, round_, validators
 
 __all__ = ["CLF_TYPE",
            "AtterbergLimits",

geolysis/spt.py

@@ -29,8 +29,7 @@ import enum
 from abc import abstractmethod
 from typing import Final, Sequence
 
-from geolysis.utils import isclose, log10, mean, round_, sqrt, validators, \
-    enum_repr
+from .utils import enum_repr, isclose, log10, mean, round_, sqrt, validators
 
 __all__ = ["SPTNDesign",
            "HammerType",

geolysis/utils/__init__.py

@@ -0,0 +1,100 @@
+import functools
+import math
+from math import exp, inf, isclose, log10, pi, sqrt
+from statistics import fmean as mean
+from typing import Callable, SupportsRound
+
+from . import validators
+
+__all__ = ["enum_repr",
+           "inf",
+           "pi",
+           "deg2rad",
+           "rad2deg",
+           "tan",
+           "cot",
+           "sin",
+           "cos",
+           "arctan",
+           "round_",
+           "mean",
+           "exp",
+           "isclose",
+           "log10",
+           "sqrt",
+           "validators"]
+
+
+def deg2rad(x: float, /) -> float:
+    """Convert angle x from degrees to radians."""
+    return math.radians(x)
+
+
+def rad2deg(x: float, /) -> float:
+    """Convert angle x from radians to degrees."""
+    return math.degrees(x)
+
+
+def tan(x: float, /) -> float:
+    """Return the tangent of x (measured in degrees)."""
+    return math.tan(deg2rad(x))
+
+
+def cot(x: float, /) -> float:
+    """Return the cotangent of x (measured in degrees)."""
+    return 1 / tan(x)
+
+
+def sin(x: float, /) -> float:
+    """Return the sine of x (measured in degrees)."""
+    return math.sin(deg2rad(x))
+
+
+def cos(x: float, /) -> float:
+    """Return the cosine of x (measured in degrees)."""
+    return math.cos(deg2rad(x))
+
+
+def arctan(x: float, /) -> float:
+    """Return the arc tangent (measured in degrees) of x."""
+    return rad2deg(math.atan(x))
+
+
+def enum_repr(cls):
+    cls.__repr__ = lambda self: f"{self.value}"
+    return cls
+
+
+def round_(ndigits: int | Callable[..., SupportsRound]) -> Callable:
+    """A decorator that rounds the result of a callable to a specified number
+    of decimal places.
+
+    The returned value of the callable should support the ``__round__`` dunder
+    method and should be a numeric value. ``ndigits`` can either be an int
+    which will indicate the number of decimal places to round to or a
+    callable. If ``ndigits`` is callable the default decimal places is 2.
+
+    TypeError is raised when ``ndigits`` is neither an int nor a callable.
+    """
+
+    default_dp = 2
+
+    def dec(fn) -> Callable[..., float]:
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs) -> float:
+            dp = ndigits if not callable(ndigits) else default_dp
+            res = fn(*args, **kwargs)
+            return round(res, ndigits=dp)
+
+        return wrapper
+
+    # See if we're being called as @round_ or @round_().
+    # We're called with parens.
+    if isinstance(ndigits, int):
+        return dec
+
+    # We're called as @round_ without parens.
+    if callable(ndigits):
+        return dec(ndigits)
+
+    raise TypeError("ndigits must be an int or a callable")