geolysis 0.8.0__tar.gz → 0.10.0__tar.gz

geolysis-0.10.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: geolysis
+Version: 0.10.0
+Summary: geolysis is an opensource software for geotechnical engineering analysis and modeling.
+Author-email: Patrick Boateng <boatengpato.pb@gmail.com>
+License: MIT License
+Project-URL: Homepage, https://docs.geolysis.io
+Project-URL: Documentation, https://docs.geolysis.io
+Project-URL: Repository, https://github.com/patrickboateng/geolysis
+Project-URL: Discussions, https://github.com/patrickboateng/geolysis/discussions
+Project-URL: Issue Tracker, https://github.com/patrickboateng/geolysis/issues
+Keywords: geotechnical-engineering,soil-classification,bearing-capacity-analysis,standard-penetration-test-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/patrickboateng/geolysis/main/docs/assets/pkg-logo.svg" 
+alt="logo" width="30%" height="30%" />
+</div><br>
+
+<div align="center">
+
+[![PyPI Latest Release](https://img.shields.io/pypi/v/geolysis?style=flat&logo=pypi)](https://pypi.org/project/geolysis/)
+[![PyPI Downloads](https://static.pepy.tech/badge/geolysis)](https://pepy.tech/projects/geolysis)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/geolysis.svg?logo=python&style=flat)](https://pypi.python.org/pypi/geolysis/)
+[![license](https://img.shields.io/pypi/l/geolysis?style=flat&logo=opensourceinitiative)](https://opensource.org/license/mit/)
+
+![Coveralls Status](https://img.shields.io/coverallsCoverage/github/patrickboateng/geolysis?logo=coveralls)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/17f88084c6a84a08a20f9d8da1438107)](https://app.codacy.com/gh/patrickboateng/geolysis/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Unit-Tests](https://github.com/patrickboateng/geolysis/actions/workflows/geolysis-unit-tests.yml/badge.svg)](https://github.com/patrickboateng/geolysis/actions/workflows/geolysis-unit-tests.yml)
+[![Documentation Status](https://readthedocs.org/projects/geolysis/badge/?version=latest)](https://geolysis.readthedocs.io/en/latest/?badge=latest)
+
+</div>
+
+`geolysis` is an open-source python package (library) for geotechnical analysis
+and modeling.
+
+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).
+
+The rest of this **README** provides an overview of the `geolysis` python
+package.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [API Reference](#api-reference)
+- [Imports](#imports)
+- [Project Structure](#project-structure)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Contact](#contact)
+
+## Installation
+
+```shell
+$ 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
+      estimation_
+    - [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_
+
+
+## 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
+  ```
+
+
+- **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
+
+    .
+    ├── .github            # GitHub Actions
+    ├── docs               # Documentation files
+    ├── geolysis           # Source files
+    ├── tests              # Automated tests
+    ├── pyproject.toml     # Project configuration file
+    └── README.md          # Project README file
+
+## Usage
+
+```python
+
+>>> from geolysis.soil_classifier import create_aashto_classifier
+>>> aashto_clf = create_aashto_classifier(liquid_limit=34.1,
+...                                       plastic_limit=21.1,
+...                                       fines=47.88, )
+>>> clf = aashto_clf.classify()
+>>> clf.symbol
+'A-6(4)'
+>>> clf.symbol_no_grp_idx
+'A-6'
+>>> clf.group_index
+'4'
+>>> clf.description
+'Clayey soils'
+
+```
+
+Check out more [examples](https://docs.geolysis.io/en/latest/usage/)
+
+## Documentation
+
+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/)
+
+## License
+
+This project is licensed under the MIT License - see the
+[LICENSE](https://github.com/patrickboateng/geolysis/blob/main/LICENSE.txt)
+file for more details.
+
+## Contact
+
+For questions or feedback, please
+contact [patrickboateng at patrickboateng dot tech](mailto:patrickboateng@patrickboateng.tech)

geolysis-0.10.0/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+<img src="https://raw.githubusercontent.com/patrickboateng/geolysis/main/docs/assets/pkg-logo.svg" 
+alt="logo" width="30%" height="30%" />
+</div><br>
+
+<div align="center">
+
+[![PyPI Latest Release](https://img.shields.io/pypi/v/geolysis?style=flat&logo=pypi)](https://pypi.org/project/geolysis/)
+[![PyPI Downloads](https://static.pepy.tech/badge/geolysis)](https://pepy.tech/projects/geolysis)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/geolysis.svg?logo=python&style=flat)](https://pypi.python.org/pypi/geolysis/)
+[![license](https://img.shields.io/pypi/l/geolysis?style=flat&logo=opensourceinitiative)](https://opensource.org/license/mit/)
+
+![Coveralls Status](https://img.shields.io/coverallsCoverage/github/patrickboateng/geolysis?logo=coveralls)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/17f88084c6a84a08a20f9d8da1438107)](https://app.codacy.com/gh/patrickboateng/geolysis/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Unit-Tests](https://github.com/patrickboateng/geolysis/actions/workflows/geolysis-unit-tests.yml/badge.svg)](https://github.com/patrickboateng/geolysis/actions/workflows/geolysis-unit-tests.yml)
+[![Documentation Status](https://readthedocs.org/projects/geolysis/badge/?version=latest)](https://geolysis.readthedocs.io/en/latest/?badge=latest)
+
+</div>
+
+`geolysis` is an open-source python package (library) for geotechnical analysis
+and modeling.
+
+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).
+
+The rest of this **README** provides an overview of the `geolysis` python
+package.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [API Reference](#api-reference)
+- [Imports](#imports)
+- [Project Structure](#project-structure)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Contact](#contact)
+
+## Installation
+
+```shell
+$ 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
+      estimation_
+    - [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_
+
+
+## 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
+  ```
+
+
+- **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
+
+    .
+    ├── .github            # GitHub Actions
+    ├── docs               # Documentation files
+    ├── geolysis           # Source files
+    ├── tests              # Automated tests
+    ├── pyproject.toml     # Project configuration file
+    └── README.md          # Project README file
+
+## Usage
+
+```python
+
+>>> from geolysis.soil_classifier import create_aashto_classifier
+>>> aashto_clf = create_aashto_classifier(liquid_limit=34.1,
+...                                       plastic_limit=21.1,
+...                                       fines=47.88, )
+>>> clf = aashto_clf.classify()
+>>> clf.symbol
+'A-6(4)'
+>>> clf.symbol_no_grp_idx
+'A-6'
+>>> clf.group_index
+'4'
+>>> clf.description
+'Clayey soils'
+
+```
+
+Check out more [examples](https://docs.geolysis.io/en/latest/usage/)
+
+## Documentation
+
+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/)
+
+## License
+
+This project is licensed under the MIT License - see the
+[LICENSE](https://github.com/patrickboateng/geolysis/blob/main/LICENSE.txt)
+file for more details.
+
+## Contact
+
+For questions or feedback, please
+contact [patrickboateng at patrickboateng dot tech](mailto:patrickboateng@patrickboateng.tech)

geolysis-0.10.0/geolysis/__init__.py

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

geolysis-0.10.0/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-0.10.0/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-0.8.0/geolysis/bearing_capacity/abc/cohl → geolysis-0.10.0/geolysis/bearing_capacity/abc/_cohl}/_core.py

@@ -1,17 +1,25 @@
 from abc import ABC, abstractmethod
+from typing import Annotated
 
-from geolysis.foundation import FoundationSize
-from geolysis.utils import exceptions as exc
-from geolysis.utils import validators
+from func_validator import (
+    validate_func_args,
+    MustBeNonNegative,
+    MustBeLessThanOrEqual,
+)
+
+from geolysis.foundation import Foundation
 
 
 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: FoundationSize) -> 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
@@ -22,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
@@ -32,8 +40,10 @@ class AllowableBearingCapacity(ABC):
         return self._tol_settlement
 
     @tol_settlement.setter
-    @validators.le(25.4, exc_type=exc.SettlementError)
-    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:

geolysis-0.10.0/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()