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

geolysis/foundation.py

@@ -1,18 +1,17 @@
 import enum
-import math
 from abc import ABC, abstractmethod
-from math import isinf
-from typing import Optional, TypeVar, Annotated
+from typing import Optional, TypeAlias, TypeVar, Annotated
 
 from func_validator import (
-    validate_func_args,
+    validate_params,
     MustBePositive,
     MustBeNonNegative,
     MustBeBetween,
     MustBeMemberOf,
+    DependsOn,
 )
 
-from .utils import AbstractStrEnum, inf, isclose, pi, round_, add_repr
+from .utils import AbstractStrEnum, inf, isclose, pi, round_, add_repr, isinf
 
 __all__ = [
     "create_foundation",
@@ -82,7 +81,7 @@ class FootingSize(ABC):
         raise NotImplementedError
 
     @width.setter
-    def width(self, value: float):
+    def width(self, width: float):
         raise NotImplementedError
 
     @property
@@ -91,7 +90,7 @@ class FootingSize(ABC):
         raise NotImplementedError
 
     @length.setter
-    def length(self, value: float):
+    def length(self, length: float):
         raise NotImplementedError
 
     def area(self) -> float:
@@ -123,9 +122,8 @@ class StripFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self) -> float:
@@ -133,13 +131,12 @@ class StripFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validate_func_args
-    def length(self, val: Annotated[float, MustBePositive]) -> None:
-        self._length = val
+    def length(self, length: float) -> None:
+        self._length = length
 
     def area(self) -> float:
         """Area of strip footing ($m \text{or} m^2$)."""
-        if math.isinf(self.length):
+        if isinf(self.length):
             return self.width
         return self.width * self.length
 
@@ -169,9 +166,8 @@ class CircularFooting(FootingSize):
         return self._diameter
 
     @diameter.setter
-    @validate_func_args
-    def diameter(self, val: Annotated[float, MustBePositive]) -> None:
-        self._diameter = val
+    def diameter(self, diameter: float) -> None:
+        self._diameter = diameter
 
     @property
     def width(self):
@@ -180,8 +176,8 @@ class CircularFooting(FootingSize):
 
     # Not checking for positive as diameter setter already does that
     @width.setter
-    def width(self, val: float):
-        self.diameter = val
+    def width(self, width: float):
+        self.diameter = width
 
     # Not checking for positive as diameter setter already does that
     @property
@@ -190,8 +186,8 @@ class CircularFooting(FootingSize):
         return self.diameter
 
     @length.setter
-    def length(self, val: float):
-        self.diameter = val
+    def length(self, length: float):
+        self.diameter = length
 
     def area(self) -> float:
         """Area of circular footing ($m^2$)."""
@@ -216,9 +212,8 @@ class SquareFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self):
@@ -227,8 +222,8 @@ class SquareFooting(FootingSize):
 
     # Not checking for positive as width setter already does that
     @length.setter
-    def length(self, val):
-        self.width = val
+    def length(self, length: float):
+        self.width = length
 
     def area(self) -> float:
         """Area of square footing ($m^2$)."""
@@ -255,9 +250,8 @@ class RectangularFooting(FootingSize):
         return self._width
 
     @width.setter
-    @validate_func_args
-    def width(self, val: Annotated[float, MustBePositive]) -> None:
-        self._width = val
+    def width(self, width: float) -> None:
+        self._width = width
 
     @property
     def length(self) -> float:
@@ -265,9 +259,8 @@ class RectangularFooting(FootingSize):
         return self._length
 
     @length.setter
-    @validate_func_args
-    def length(self, val: Annotated[float, MustBePositive]) -> None:
-        self._length = val
+    def length(self, length: float) -> None:
+        self._length = length
 
     def area(self) -> float:
         """Area of rectangular footing ($m^2$)."""
@@ -284,7 +277,7 @@ class Foundation:
             footing_size: FootingSize,
             eccentricity: float = 0.0,
             load_angle: float = 0.0,
-            ground_water_level: Optional[float] = None,
+            ground_water_level: Optional[float] = inf,
             foundation_type: FoundationType = FoundationType.PAD,
     ) -> None:
         r"""
@@ -304,7 +297,7 @@ class Foundation:
         self.eccentricity = eccentricity
         self.load_angle = load_angle
 
-        self._ground_water_level = ground_water_level
+        self.ground_water_level = ground_water_level
         self.foundation_type = foundation_type
 
     @property
@@ -313,9 +306,9 @@ class Foundation:
         return self._depth
 
     @depth.setter
-    @validate_func_args
-    def depth(self, val: Annotated[float, MustBePositive]) -> None:
-        self._depth = val
+    @validate_params
+    def depth(self, depth: Annotated[float, MustBePositive]) -> None:
+        self._depth = depth
 
     @property
     def width(self) -> float:
@@ -323,8 +316,8 @@ class Foundation:
         return self.footing_size.width
 
     @width.setter
-    def width(self, val: Annotated[float, MustBePositive]):
-        self.footing_size.width = val
+    def width(self, width: Annotated[float, MustBePositive]):
+        self.footing_size.width = width
 
     @property
     def length(self) -> float:
@@ -332,8 +325,8 @@ class Foundation:
         return self.footing_size.length
 
     @length.setter
-    def length(self, val: Annotated[float, MustBePositive]):
-        self.footing_size.length = val
+    def length(self, length: Annotated[float, MustBePositive]):
+        self.footing_size.length = length
 
     @property
     def footing_shape(self) -> Shape:
@@ -348,9 +341,10 @@ class Foundation:
         return self._eccentricity
 
     @eccentricity.setter
-    @validate_func_args
-    def eccentricity(self, val: Annotated[float, MustBeNonNegative]) -> None:
-        self._eccentricity = val
+    @validate_params
+    def eccentricity(self, eccentricity: Annotated[
+        float, MustBeNonNegative]) -> None:
+        self._eccentricity = eccentricity
 
     @property
     def load_angle(self) -> float:
@@ -358,12 +352,13 @@ class Foundation:
         return self._load_angle
 
     @load_angle.setter
-    @validate_func_args
+    @validate_params
     def load_angle(
             self,
-            val: Annotated[float, MustBeBetween(min_value=0.0, max_value=90.0)]
+            load_angle: Annotated[
+                float, MustBeBetween(min_value=0.0, max_value=90.0)],
     ) -> None:
-        self._load_angle = val
+        self._load_angle = load_angle
 
     @property
     def ground_water_level(self) -> Optional[float]:
@@ -371,9 +366,12 @@ class Foundation:
         return self._ground_water_level
 
     @ground_water_level.setter
-    @validate_func_args
-    def ground_water_level(self, val: Annotated[float, MustBePositive]):
-        self._ground_water_level = val
+    @validate_params
+    def ground_water_level(
+            self,
+            ground_water_level: Annotated[float, MustBePositive],
+    ):
+        self._ground_water_level = ground_water_level
 
     @property
     def foundation_type(self) -> FoundationType:
@@ -381,12 +379,13 @@ class Foundation:
         return self._foundation_type
 
     @foundation_type.setter
-    @validate_func_args
+    @validate_params
     def foundation_type(
             self,
-            val: Annotated[FoundationType, MustBeMemberOf(FoundationType)]
+            foundation_type: Annotated[
+                FoundationType, MustBeMemberOf(FoundationType)],
     ):
-        self._foundation_type = val
+        self._foundation_type = foundation_type
 
     @round_(2)
     def foundation_area(self) -> float:
@@ -403,7 +402,10 @@ class Foundation:
         of the foundation footing.
         """
         width, length, shape = (
-        self.effective_width, self.length, self.footing_shape)
+            self.effective_width,
+            self.length,
+            self.footing_shape,
+        )
 
         if not isclose(width, length) and shape != Shape.STRIP:
             shape = Shape.RECTANGLE
@@ -411,11 +413,11 @@ class Foundation:
         return width, length, shape
 
 
-@validate_func_args
+@validate_params
 def create_foundation(
         depth: float,
         width: float,
-        length: float = inf,
+        length: Annotated[float, DependsOn(shape=Shape.RECTANGLE)] = None,
         eccentricity: float = 0.0,
         load_angle: float = 0.0,
         ground_water_level: Optional[float] = inf,
@@ -434,31 +436,25 @@ def create_foundation(
                          load aligns with the center of gravity of the
                          foundation footing .
     :param load_angle: Inclination of the applied load with the  vertical
-                           (:math:`\alpha^{\circ}`), defaults to 0.0.
-    :param ground_water_level: Depth of the water below ground level (m),
-                               defaults to None.
-    :param foundation_type: Type of foundation footing, defaults to
-                            :py:enum:mem:`~FoundationType.PAD`.
-    :param shape: Shape of foundation footing, defaults to
-                  :py:enum:mem:`~Shape.SQUARE`
-    :raises ValueError: Raised when length is not provided for a
-                        rectangular footing.
-    :raises ValidationError: Raised if an invalid footing shape is
+                       (:math:`\alpha^{\circ}`).
+    :param ground_water_level: Depth of the water below ground level (m)
+    :param foundation_type: Type of foundation footing.
+    :param shape: Shape of foundation footing
+
+    :raises ValidationError: Raised when length is not provided for a
+                             rectangular footing or an invalid shape is
                              provided.
     """
-
+    footing_size: FootingSize
     shape = Shape(str(shape).casefold())
 
-    if shape is Shape.STRIP:
+    if shape == Shape.STRIP:
         footing_size = StripFooting(width=width)
-    elif shape is Shape.SQUARE:
+    elif shape == Shape.SQUARE:
         footing_size = SquareFooting(width=width)
-    elif shape is Shape.CIRCLE:
+    elif shape == Shape.CIRCLE:
         footing_size = CircularFooting(diameter=width)
     else:  # RECTANGLE
-        if isinf(length):
-            msg = "Length of rectangular footing must be provided."
-            raise ValueError(msg)
         footing_size = RectangularFooting(width=width, length=length)
 
     return Foundation(

geolysis/soil_classifier.py

@@ -2,9 +2,9 @@ import enum
 from dataclasses import dataclass
 from typing import Annotated, Sequence
 
-from func_validator import validate_func_args, MustBeNonNegative
+from func_validator import validate_params, MustBeNonNegative
 
-from .utils import isclose, round_
+from .utils import isclose, round_, nan, isnan
 
 __all__ = [
     "AtterbergLimits",
@@ -256,9 +256,9 @@ class AtterbergLimits:
         return self._liquid_limit
 
     @liquid_limit.setter
-    @validate_func_args
-    def liquid_limit(self, val: Annotated[float, MustBeNonNegative]):
-        self._liquid_limit = val
+    @validate_params
+    def liquid_limit(self, liquid_limit: Annotated[float, MustBeNonNegative]):
+        self._liquid_limit = liquid_limit
 
     @property
     def plastic_limit(self) -> float:
@@ -268,16 +268,16 @@ class AtterbergLimits:
         return self._plastic_limit
 
     @plastic_limit.setter
-    @validate_func_args
-    def plastic_limit(self, val: Annotated[float, MustBeNonNegative]):
-        if self.liquid_limit < val:
+    @validate_params
+    def plastic_limit(self, plastic_limit: Annotated[float, MustBeNonNegative]):
+        if self.liquid_limit < plastic_limit:
             msg = (
-                f"plastic_limit: {val} cannot be greater than "
+                f"plastic_limit: {plastic_limit} cannot be greater than "
                 f"liquid_limit: {self.liquid_limit}"
             )
             raise ValueError(msg)
 
-        self._plastic_limit = val
+        self._plastic_limit = plastic_limit
 
     @property
     @round_(2)
@@ -353,7 +353,7 @@ class _SizeDistribution:
     Features obtained from the Particle Size Distribution graph.
     """
 
-    def __init__(self, d_10: float = 0.0, d_30: float = 0.0, d_60: float = 0.0):
+    def __init__(self, d_10: float, d_30: float, d_60: float):
         self.d_10 = d_10
         self.d_30 = d_30
         self.d_60 = d_60
@@ -389,6 +389,12 @@ class _SizeDistribution:
             grade = USCSSymbol.POORLY_GRADED
         return grade
 
+    def has_particle_sizes(self) -> bool:
+        """Checks if particle sizes are provided."""
+        if isnan(self.d_10) or isnan(self.d_30) or isnan(self.d_60):
+            return False
+        return True
+
 
 class PSD:
     """Quantitative proportions by mass of various sizes of particles
@@ -399,9 +405,9 @@ class PSD:
         self,
         fines: float,
         sand: float,
-        d_10: float = 0,
-        d_30: float = 0,
-        d_60: float = 0,
+        d_10: float = nan,
+        d_30: float = nan,
+        d_60: float = nan,
     ):
         """
         :param fines: Percentage of fines in soil sample (%) i.e. The
@@ -459,7 +465,7 @@ class PSD:
 
     def has_particle_sizes(self) -> bool:
         """Checks if soil sample has particle sizes."""
-        return any(self.size_dist)
+        return self.size_dist.has_particle_sizes()
 
     def grade(self) -> USCSSymbol:
         r"""Return the grade of the soil sample, either well graded or
@@ -473,7 +479,7 @@ class PSD:
         return self.size_dist.grade(coarse_soil=self.coarse_material_type)
 
 
-@dataclass
+@dataclass(frozen=True, slots=True)
 class AASHTOResult:
     symbol: str
     symbol_no_group_idx: str
@@ -527,9 +533,9 @@ class AASHTO:
         return self._fines
 
     @fines.setter
-    @validate_func_args
-    def fines(self, val: Annotated[float, MustBeNonNegative]):
-        self._fines = val
+    @validate_params
+    def fines(self, fines: Annotated[float, MustBeNonNegative]):
+        self._fines = fines
 
     @round_(ndigits=0)
     def group_index(self) -> float:
@@ -619,7 +625,7 @@ class AASHTO:
         return soil_clf
 
 
-@dataclass
+@dataclass(frozen=True, slots=True)
 class USCSResult:
     symbol: str
     description: str
@@ -672,7 +678,8 @@ class USCS:
 
         if isinstance(soil_clf, USCSSymbol):
             soil_clf = USCSResult(
-                symbol=soil_clf.symbol, description=soil_clf.description
+                symbol=soil_clf.symbol,
+                description=soil_clf.description,
             )
         else:
             # Handling tuple or list case for dual classification
@@ -790,12 +797,10 @@ def create_aashto_classifier(
                          the minimum moisture content at which a soil
                          flows upon application of a very small shear
                          force.
-
     :param plastic_limit: Water content at which plastic deformation can
                           be initiated (%). It is also the minimum water
                           content at which soil can be rolled into a
                           thread 3mm thick (molded without breaking).
-
     :param fines: Percentage of fines in soil sample (%) i.e. The
                   percentage of soil sample passing through No. 200
                   sieve (0.075mm).
@@ -809,9 +814,9 @@ def create_uscs_classifier(
     plastic_limit: float,
     fines: float,
     sand: float,
-    d_10: float = 0,
-    d_30: float = 0,
-    d_60: float = 0,
+    d_10: float = nan,
+    d_30: float = nan,
+    d_60: float = nan,
     organic: bool = False,
 ):
     """A helper function that encapsulates the creation of a USCS
@@ -822,24 +827,17 @@ def create_uscs_classifier(
                          the minimum moisture content at which a soil
                          flows upon application of a very small shear
                          force.
-
     :param plastic_limit: Water content at which plastic deformation can
                           be initiated (%). It is also the minimum water
                           content at which soil can be rolled into a
                           thread 3mm thick. (molded without breaking)
-
     :param fines: Percentage of fines in soil sample (%) i.e. The
                   percentage of soil sample passing through No. 200
                   sieve (0.075mm).
-
     :param sand: Percentage of sand in soil sample (%).
-
     :param d_10: Diameter at which 10% of the soil by weight is finer.
-
     :param d_30: Diameter at which 30% of the soil by weight is finer.
-
     :param d_60: Diameter at which 60% of the soil by weight is finer.
-
     :param organic: Indicates whether soil is organic or not.
     """
     atterberg_lmts = AtterbergLimits(liquid_limit, plastic_limit)