geolysis 0.11.0__tar.gz → 0.13.0__tar.gz

{geolysis-0.11.0 → geolysis-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geolysis
-Version: 0.11.0
+Version: 0.13.0
 Summary: geolysis is an opensource software for geotechnical engineering analysis and modeling.
 Author-email: Patrick Boateng <boatengpato.pb@gmail.com>
 License: MIT License
@@ -57,7 +57,8 @@ The `geolysis` python package is among three other projects, `geolysis.excel`,
 `geolysis.gui`, and `geolysis.ai`. More details about these projects are
 provided [here](https://github.com/geolysis-dev).
 
-`geolysis` has only one project dependency which is [func-validator](https://github.com/patrickboateng/func-validator/)
+`geolysis` has only one project dependency which
+is [func-validator](https://github.com/patrickboateng/func-validator/)
 for validating `function` (and `method`) arguments.
 
 The rest of this **README** provides an overview of the `geolysis` python
@@ -83,58 +84,64 @@ $ pip install geolysis
 
 ## API Reference
 
-- [Python API](https://docs.geolysis.io/en/latest/reference/) 
-    - [geolysis.bearing_capacity.abc](https://docs.geolysis.io/en/latest/reference/allowable_bearing_capacity/) - _Allowable bearing capacity
+- [Python API](https://docs.geolysis.io/en/latest/reference/)
+    - [geolysis.bearing_capacity.abc](https://docs.geolysis.io/en/latest/reference/allowable_bearing_capacity/) -
+      _Allowable bearing capacity
       estimation_
-    - [geolysis.bearing_capacity.ubc](https://docs.geolysis.io/en/latest/reference/ultimate_bearing_capacity/) - _Ultimate bearing capacity
+    - [geolysis.bearing_capacity.ubc](https://docs.geolysis.io/en/latest/reference/ultimate_bearing_capacity/) -
+      _Ultimate bearing capacity
       estimation_
-    - [geolysis.foundation](https://docs.geolysis.io/en/latest/reference/foundation/) - _Foundation Representation_
-    - [geolysis.soil_classifier](https://docs.geolysis.io/en/latest/reference/soil_classifier/) - _Soil classification_
-    - [geolysis.spt](https://docs.geolysis.io/en/latest/reference/spt/) - _Standard Penetration Test (SPT) Analysis_
-    - [geolysis.utils](https://docs.geolysis.io/en/latest/reference/utils/) - _Utilities_
-
+    - [geolysis.foundation](https://docs.geolysis.io/en/latest/reference/foundation/) -
+      _Foundation Representation_
+    - [geolysis.soil_classifier](https://docs.geolysis.io/en/latest/reference/soil_classifier/) -
+      _Soil classification_
+    - [geolysis.spt](https://docs.geolysis.io/en/latest/reference/spt/) -
+      _Standard Penetration Test (SPT) Analysis_
+    - [geolysis.utils](https://docs.geolysis.io/en/latest/reference/utils/) -
+      _Utilities_
 
 ## Imports
 
-- **Bearing Capacity**
-
-    - **Allowable Bearing Capacity (ABC)**
-     
-      ```python
-      from geolysis.bearing_capacity.abc import create_abc_4_cohesionless_soils
-      ```
-        
-    - **Ultimate Bearing Capacity (UBC)**
-     
-      ```python
-      from geolysis.bearing_capacity.ubc import create_ubc_4_all_soil_types
-      ```
-
-- **Foundation**
- 
-  ```python
-  from geolysis.foundation import create_foundation
-  ```
+### Bearing Capacity
+
+- **Allowable Bearing Capacity (ABC)**
+
+    ```python
+    from geolysis.bearing_capacity.abc import create_abc_4_cohesionless_soils
+    ```
 
+- **Ultimate Bearing Capacity (UBC)**
 
-- **Soil Classification**
- 
   ```python
-  from geolysis.soil_classifier import create_uscs_classifier
-  from geolysis.soil_classifier import create_aashto_classifier
+  from geolysis.bearing_capacity.ubc import create_ubc_4_all_soil_types
   ```
- 
-- **Standard Penetration Test (SPT) Analysis**
- 
+
+### Foundation
+
+```python
+from geolysis.foundation import create_foundation
+```
+
+### Soil Classification
+
+```python
+from geolysis.soil_classifier import create_uscs_classifier
+from geolysis.soil_classifier import create_aashto_classifier
+```
+
+### Standard Penetration Test (SPT) Analysis
+
   ```python
   from geolysis.spt import DilatancyCorrection
   from geolysis.spt import EnergyCorrection
   from geolysis.spt import SPT
   from geolysis.spt import create_overburden_pressure_correction
   ```
-  
+
 ## Project Structure
 
+These are the main components of the project structure
+
     .
     ├── .github            # GitHub Actions
     ├── docs               # Documentation files
@@ -154,7 +161,7 @@ $ pip install geolysis
 >>> clf = aashto_clf.classify()
 >>> clf.symbol
 'A-6(4)'
->>> clf.symbol_no_grp_idx
+>>> clf.symbol_no_group_idx
 'A-6'
 >>> clf.group_index
 '4'
@@ -171,7 +178,8 @@ Check out the full [documentation](https://docs.geolysis.io/en/latest/).
 
 ## Contributing
 
-Check out the [contribution guidelines](https://docs.geolysis.io/en/latest/dev_guide/)
+Check out
+the [contribution guidelines](https://docs.geolysis.io/en/latest/dev_guide/)
 
 ## License
 

{geolysis-0.11.0 → geolysis-0.13.0}/README.md

@@ -24,7 +24,8 @@ The `geolysis` python package is among three other projects, `geolysis.excel`,
 `geolysis.gui`, and `geolysis.ai`. More details about these projects are
 provided [here](https://github.com/geolysis-dev).
 
-`geolysis` has only one project dependency which is [func-validator](https://github.com/patrickboateng/func-validator/)
+`geolysis` has only one project dependency which
+is [func-validator](https://github.com/patrickboateng/func-validator/)
 for validating `function` (and `method`) arguments.
 
 The rest of this **README** provides an overview of the `geolysis` python
@@ -50,58 +51,64 @@ $ pip install geolysis
 
 ## API Reference
 
-- [Python API](https://docs.geolysis.io/en/latest/reference/) 
-    - [geolysis.bearing_capacity.abc](https://docs.geolysis.io/en/latest/reference/allowable_bearing_capacity/) - _Allowable bearing capacity
+- [Python API](https://docs.geolysis.io/en/latest/reference/)
+    - [geolysis.bearing_capacity.abc](https://docs.geolysis.io/en/latest/reference/allowable_bearing_capacity/) -
+      _Allowable bearing capacity
       estimation_
-    - [geolysis.bearing_capacity.ubc](https://docs.geolysis.io/en/latest/reference/ultimate_bearing_capacity/) - _Ultimate bearing capacity
+    - [geolysis.bearing_capacity.ubc](https://docs.geolysis.io/en/latest/reference/ultimate_bearing_capacity/) -
+      _Ultimate bearing capacity
       estimation_
-    - [geolysis.foundation](https://docs.geolysis.io/en/latest/reference/foundation/) - _Foundation Representation_
-    - [geolysis.soil_classifier](https://docs.geolysis.io/en/latest/reference/soil_classifier/) - _Soil classification_
-    - [geolysis.spt](https://docs.geolysis.io/en/latest/reference/spt/) - _Standard Penetration Test (SPT) Analysis_
-    - [geolysis.utils](https://docs.geolysis.io/en/latest/reference/utils/) - _Utilities_
-
+    - [geolysis.foundation](https://docs.geolysis.io/en/latest/reference/foundation/) -
+      _Foundation Representation_
+    - [geolysis.soil_classifier](https://docs.geolysis.io/en/latest/reference/soil_classifier/) -
+      _Soil classification_
+    - [geolysis.spt](https://docs.geolysis.io/en/latest/reference/spt/) -
+      _Standard Penetration Test (SPT) Analysis_
+    - [geolysis.utils](https://docs.geolysis.io/en/latest/reference/utils/) -
+      _Utilities_
 
 ## Imports
 
-- **Bearing Capacity**
-
-    - **Allowable Bearing Capacity (ABC)**
-     
-      ```python
-      from geolysis.bearing_capacity.abc import create_abc_4_cohesionless_soils
-      ```
-        
-    - **Ultimate Bearing Capacity (UBC)**
-     
-      ```python
-      from geolysis.bearing_capacity.ubc import create_ubc_4_all_soil_types
-      ```
-
-- **Foundation**
- 
-  ```python
-  from geolysis.foundation import create_foundation
-  ```
+### Bearing Capacity
+
+- **Allowable Bearing Capacity (ABC)**
+
+    ```python
+    from geolysis.bearing_capacity.abc import create_abc_4_cohesionless_soils
+    ```
 
+- **Ultimate Bearing Capacity (UBC)**
 
-- **Soil Classification**
- 
   ```python
-  from geolysis.soil_classifier import create_uscs_classifier
-  from geolysis.soil_classifier import create_aashto_classifier
+  from geolysis.bearing_capacity.ubc import create_ubc_4_all_soil_types
   ```
- 
-- **Standard Penetration Test (SPT) Analysis**
- 
+
+### Foundation
+
+```python
+from geolysis.foundation import create_foundation
+```
+
+### Soil Classification
+
+```python
+from geolysis.soil_classifier import create_uscs_classifier
+from geolysis.soil_classifier import create_aashto_classifier
+```
+
+### Standard Penetration Test (SPT) Analysis
+
   ```python
   from geolysis.spt import DilatancyCorrection
   from geolysis.spt import EnergyCorrection
   from geolysis.spt import SPT
   from geolysis.spt import create_overburden_pressure_correction
   ```
-  
+
 ## Project Structure
 
+These are the main components of the project structure
+
     .
     ├── .github            # GitHub Actions
     ├── docs               # Documentation files
@@ -121,7 +128,7 @@ $ pip install geolysis
 >>> clf = aashto_clf.classify()
 >>> clf.symbol
 'A-6(4)'
->>> clf.symbol_no_grp_idx
+>>> clf.symbol_no_group_idx
 'A-6'
 >>> clf.group_index
 '4'
@@ -138,7 +145,8 @@ Check out the full [documentation](https://docs.geolysis.io/en/latest/).
 
 ## Contributing
 
-Check out the [contribution guidelines](https://docs.geolysis.io/en/latest/dev_guide/)
+Check out
+the [contribution guidelines](https://docs.geolysis.io/en/latest/dev_guide/)
 
 ## License
 

{geolysis-0.11.0 → geolysis-0.13.0}/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-0.11.0 → geolysis-0.13.0}/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-0.13.0/geolysis/bearing_capacity/abc/_cohl/_core.py

@@ -0,0 +1,96 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Annotated
+
+from func_validator import (
+    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,
+    ) -> None:
+        self.corrected_spt_n_value = corrected_spt_n_value
+        self.tol_settlement = tol_settlement
+        self.foundation_size = foundation_size
+
+    @property
+    def corrected_spt_n_value(self) -> float:
+        """Statistical average of corrected SPT N-value."""
+        return self._corrected_spt_n_value
+
+    @corrected_spt_n_value.setter
+    @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:
+        """Tolerable settlement of foundation (mm)."""
+        return self._tol_settlement
+
+    @tol_settlement.setter
+    @validate_params
+    def tol_settlement(
+        self,
+        tol_settlement: Annotated[float, MustBeLessThanOrEqual(25.4)],
+    ):
+        self._tol_settlement = tol_settlement
+
+    def _sr(self) -> float:
+        """Calculate the settlement ratio."""
+        return self.tol_settlement / self.MAX_TOL_SETTLEMENT
+
+    def _fd(self) -> float:
+        """Calculate the depth factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+        return min(1.0 + 0.33 * depth / width, 1.33)
+
+    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 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) -> float: ...

{geolysis-0.11.0 → geolysis-0.13.0}/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-0.11.0 → geolysis-0.13.0}/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-0.11.0 → geolysis-0.13.0}/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.
         """