geolysis 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

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,8 +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
@@ -364,7 +363,7 @@ class _SizeDistribution:
 
     @property
     def coeff_of_curvature(self) -> float:
-        return (self.d_30 ** 2.0) / (self.d_60 * self.d_10)
+        return (self.d_30**2.0) / (self.d_60 * self.d_10)
 
     @property
     def coeff_of_uniformity(self) -> float:
@@ -390,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
@@ -397,12 +402,12 @@ class PSD:
     """
 
     def __init__(
-            self,
-            fines: float,
-            sand: float,
-            d_10: float = 0,
-            d_30: float = 0,
-            d_60: float = 0,
+        self,
+        fines: float,
+        sand: float,
+        d_10: float = nan,
+        d_30: float = nan,
+        d_60: float = nan,
     ):
         """
         :param fines: Percentage of fines in soil sample (%) i.e. The
@@ -460,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
@@ -474,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
@@ -528,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:
@@ -620,7 +625,7 @@ class AASHTO:
         return soil_clf
 
 
-@dataclass
+@dataclass(frozen=True, slots=True)
 class USCSResult:
     symbol: str
     description: str
@@ -649,10 +654,10 @@ class USCS:
     """
 
     def __init__(
-            self,
-            atterberg_limits: AtterbergLimits,
-            psd: PSD,
-            organic=False,
+        self,
+        atterberg_limits: AtterbergLimits,
+        psd: PSD,
+        organic=False,
     ):
         """
         :param atterberg_limits: Atterberg limits of the soil.
@@ -673,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
@@ -779,9 +785,9 @@ class USCS:
 
 
 def create_aashto_classifier(
-        liquid_limit: float,
-        plastic_limit: float,
-        fines: float,
+    liquid_limit: float,
+    plastic_limit: float,
+    fines: float,
 ) -> AASHTO:
     """A helper function that encapsulates the creation of a AASHTO
     classifier.
@@ -791,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).
@@ -806,14 +810,14 @@ def create_aashto_classifier(
 
 
 def create_uscs_classifier(
-        liquid_limit: float,
-        plastic_limit: float,
-        fines: float,
-        sand: float,
-        d_10: float = 0,
-        d_30: float = 0,
-        d_60: float = 0,
-        organic: bool = False,
+    liquid_limit: float,
+    plastic_limit: float,
+    fines: float,
+    sand: float,
+    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
     classifier.
@@ -823,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)

geolysis/spt.py

@@ -3,7 +3,7 @@ from abc import abstractmethod
 from typing import Annotated, Final, Sequence
 
 from func_validator import (
-    validate_func_args,
+    validate_params,
     MustBeBetween,
     MustBePositive,
     MustBeMemberOf,
@@ -61,9 +61,9 @@ class SPT:
     """
 
     def __init__(
-            self,
-            corrected_spt_n_values: Sequence[float],
-            method: SPTDesignMethod.WEIGHTED = "wgt",
+        self,
+        corrected_spt_n_values: Sequence[float],
+        method: SPTDesignMethod.WEIGHTED = "wgt",
     ):
         """
         :param corrected_spt_n_values: Corrected SPT N-values within the
@@ -80,14 +80,14 @@ class SPT:
         return self._corrected_spt_n_values
 
     @corrected_spt_n_values.setter
-    @validate_func_args
+    @validate_params
     def corrected_spt_n_values(
-            self,
-            corrected_spt_n_values: Annotated[
-                Sequence[float],
-                MustHaveLengthGreaterThan(1),
-                MustHaveValuesBetween(min_value=1.0, max_value=100.0),
-            ],
+        self,
+        corrected_spt_n_values: Annotated[
+            Sequence[float],
+            MustHaveLengthGreaterThan(1),
+            MustHaveValuesBetween(min_value=1.0, max_value=100.0),
+        ],
     ) -> None:
         self._corrected_spt_n_values = corrected_spt_n_values
 
@@ -96,9 +96,9 @@ class SPT:
         return self._method
 
     @method.setter
-    @validate_func_args
-    def method(self, val: Annotated[str, MustBeMemberOf(SPTDesignMethod)]):
-        self._method = val
+    @validate_params
+    def method(self, method: Annotated[str, MustBeMemberOf(SPTDesignMethod)]):
+        self._method = method
 
     @staticmethod
     def _avg_spt_n_design(vals) -> float:
@@ -111,15 +111,15 @@ class SPT:
     @staticmethod
     def _wgt_spt_n_design(vals):
 
-        sum_total = 0.0
-        sum_wgts = 0.0
+        total_wgted_spt = 0.0
+        total_wgt = 0.0
 
         for i, corr_spt_n_val in enumerate(vals, start=1):
-            wgt = 1 / i ** 2
-            sum_total += wgt * corr_spt_n_val
-            sum_wgts += wgt
+            wgt = 1 / i**2
+            total_wgted_spt += wgt * corr_spt_n_val
+            total_wgt += wgt
 
-        return sum_total / sum_wgts
+        return total_wgted_spt / total_wgt
 
     @round_(ndigits=1)
     def n_design(self):
@@ -220,14 +220,14 @@ class EnergyCorrection:
     }
 
     def __init__(
-            self,
-            recorded_spt_n_value: int,
-            *,
-            energy_percentage=0.6,
-            borehole_diameter=65.0,
-            rod_length=3.0,
-            hammer_type=HammerType.DONUT_1,
-            sampler_type=SamplerType.STANDARD,
+        self,
+        recorded_spt_n_value: int,
+        *,
+        energy_percentage=0.6,
+        borehole_diameter=65.0,
+        rod_length=3.0,
+        hammer_type=HammerType.DONUT_1,
+        sampler_type=SamplerType.STANDARD,
     ):
         """
         :param recorded_spt_n_value: Recorded SPT N-value from field.
@@ -252,12 +252,12 @@ class EnergyCorrection:
         return self._recorded_spt_value
 
     @recorded_spt_n_value.setter
-    @validate_func_args
+    @validate_params
     def recorded_spt_n_value(
-            self,
-            val: Annotated[int, MustBeBetween(min_value=0, max_value=100)]
+        self,
+        recorded_spt_n_value: Annotated[int, MustBeBetween(min_value=0, max_value=100)],
     ) -> None:
-        self._recorded_spt_value = val
+        self._recorded_spt_value = recorded_spt_n_value
 
     @property
     def energy_percentage(self) -> float:
@@ -265,12 +265,14 @@ class EnergyCorrection:
         return self._energy_percentage
 
     @energy_percentage.setter
-    @validate_func_args
+    @validate_params
     def energy_percentage(
-            self,
-            val: Annotated[float, MustBeBetween(min_value=0.0, max_value=1.0)]
+        self,
+        energy_percentage: Annotated[
+            float, MustBeBetween(min_value=0.0, max_value=1.0)
+        ],
     ) -> None:
-        self._energy_percentage = val
+        self._energy_percentage = energy_percentage
 
     @property
     def borehole_diameter(self) -> float:
@@ -278,12 +280,14 @@ class EnergyCorrection:
         return self._borehole_diameter
 
     @borehole_diameter.setter
-    @validate_func_args
+    @validate_params
     def borehole_diameter(
-            self, val: Annotated[
-                float, MustBeBetween(min_value=65.0, max_value=200.0)]
+        self,
+        borehole_diameter: Annotated[
+            float, MustBeBetween(min_value=65.0, max_value=200.0)
+        ],
     ) -> None:
-        self._borehole_diameter = val
+        self._borehole_diameter = borehole_diameter
 
     @property
     def rod_length(self) -> float:
@@ -291,19 +295,19 @@ class EnergyCorrection:
         return self._rod_length
 
     @rod_length.setter
-    @validate_func_args
-    def rod_length(self, val: Annotated[float, MustBePositive]):
-        self._rod_length = val
+    @validate_params
+    def rod_length(self, rod_length: Annotated[float, MustBePositive]):
+        self._rod_length = rod_length
 
     @property
     def hammer_type(self) -> HammerType:
         return self._hammer_type
 
     @hammer_type.setter
-    @validate_func_args
+    @validate_params
     def hammer_type(
-            self,
-            hammer_type: Annotated[HammerType, MustBeMemberOf(HammerType)]
+        self,
+        hammer_type: Annotated[HammerType, MustBeMemberOf(HammerType)],
     ):
         self._hammer_type = hammer_type
 
@@ -312,10 +316,11 @@ class EnergyCorrection:
         return self._sampler_type
 
     @sampler_type.setter
-    @validate_func_args
-    def sampler_type(self,
-                     val: Annotated[SamplerType, MustBeMemberOf(SamplerType)]):
-        self._sampler_type = val
+    @validate_params
+    def sampler_type(
+        self, sampler_type: Annotated[SamplerType, MustBeMemberOf(SamplerType)]
+    ):
+        self._sampler_type = sampler_type
 
     @property
     def hammer_efficiency(self) -> float:
@@ -362,10 +367,10 @@ class EnergyCorrection:
         `ENERGY`: 0.6, 0.55, etc
         """
         numerator = (
-                self.hammer_efficiency
-                * self.borehole_diameter_correction
-                * self.sampler_correction
-                * self.rod_length_correction
+            self.hammer_efficiency
+            * self.borehole_diameter_correction
+            * self.sampler_correction
+            * self.rod_length_correction
         )
         return numerator / self.energy_percentage
 
@@ -393,10 +398,10 @@ class OPC:
         return self._eop
 
     @eop.setter
-    @validate_func_args
-    def eop(self, val: Annotated[float, MustBeNonNegative]):
+    @validate_params
+    def eop(self, eop: Annotated[float, MustBeNonNegative]):
         """Effective overburden pressure ($kPa$)."""
-        self._eop = val
+        self._eop = eop
 
     @property
     def std_spt_n_value(self) -> float:
@@ -404,12 +409,14 @@ class OPC:
         return self._std_spt_n_value
 
     @std_spt_n_value.setter
-    @validate_func_args
+    @validate_params
     def std_spt_n_value(
-            self, val: Annotated[
-                float, MustBeBetween(min_value=0.0, max_value=100.0)]
+        self,
+        std_spt_n_value: Annotated[
+            float, MustBeBetween(min_value=0.0, max_value=100.0)
+        ],
     ):
-        self._std_spt_n_value = val
+        self._std_spt_n_value = std_spt_n_value
 
     @round_(ndigits=1)
     def corrected_spt_n_value(self) -> float:
@@ -435,10 +442,12 @@ class GibbsHoltzOPC(OPC):
         return self._eop
 
     @eop.setter
-    @validate_func_args
-    def eop(self, val: Annotated[
-        float, MustBeBetween(min_value=0.0, max_value=280.0)]):
-        self._eop = val
+    @validate_params
+    def eop(
+        self,
+        eop: Annotated[float, MustBeBetween(min_value=0.0, max_value=280.0)],
+    ):
+        self._eop = eop
 
     def correction(self) -> float:
         r"""SPT Correction."""
@@ -476,9 +485,9 @@ class PeckOPC(OPC):
         return self._eop
 
     @eop.setter
-    @validate_func_args
-    def eop(self, val: Annotated[float, MustBeGreaterThanOrEqual(24.0)]):
-        self._eop = val
+    @validate_params
+    def eop(self, eop: Annotated[float, MustBeGreaterThanOrEqual(24.0)]):
+        self._eop = eop
 
     def correction(self) -> float:
         r"""SPT Correction."""
@@ -527,12 +536,14 @@ class DilatancyCorrection:
         return self._corr_spt_n_value
 
     @corr_spt_n_value.setter
-    @validate_func_args
+    @validate_params
     def corr_spt_n_value(
-            self, val: Annotated[
-                float, MustBeBetween(min_value=0.0, max_value=100.0)]
+        self,
+        corr_spt_n_value: Annotated[
+            float, MustBeBetween(min_value=0.0, max_value=100.0)
+        ],
     ):
-        self._corr_spt_n_value = val
+        self._corr_spt_n_value = corr_spt_n_value
 
     @round_(ndigits=1)
     def corrected_spt_n_value(self) -> float:
@@ -574,11 +585,11 @@ _opctypes = {
 }
 
 
-@validate_func_args
+@validate_params
 def create_overburden_pressure_correction(
-        std_spt_n_value: float,
-        eop: float,
-        opc_type: Annotated[OPCType | str, MustBeMemberOf(OPCType)] = "gibbs",
+    std_spt_n_value: float,
+    eop: float,
+    opc_type: Annotated[OPCType | str, MustBeMemberOf(OPCType)] = "gibbs",
 ):
     """A factory function that encapsulates the creation of overburden
     pressure correction.

geolysis/{utils.py → utils/__init__.py}

@@ -1,31 +1,11 @@
 import enum
 import functools
-import math
-from math import exp, inf, isclose, log10, pi, sqrt
-from statistics import fmean as mean
 from typing import Callable
 
-from func_validator import ValidationError
-
-__all__ = [
-    "AbstractStrEnum",
-    "ValidationError",
-    "inf",
-    "pi",
-    "deg2rad",
-    "rad2deg",
-    "tan",
-    "cot",
-    "sin",
-    "cos",
-    "arctan",
-    "round_",
-    "mean",
-    "exp",
-    "isclose",
-    "log10",
-    "sqrt",
-]
+from .math import *
+from . import math as m
+
+__all__ = ["AbstractStrEnum", "ValidationError", "add_repr", "round_"] + m.__all__
 
 
 class StrEnumMeta(enum.EnumMeta):
@@ -46,39 +26,21 @@ class AbstractStrEnum(enum.StrEnum, metaclass=StrEnumMeta):
     """
 
 
-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 add_repr(cls):
+    """A class decorator that adds a __repr__ method to the class."""
 
+    def __repr__(self) -> str:
+        inst_attrs = self.__dict__
+        attrs = (f"{key.strip('_')}={val}" for key, val in inst_attrs.items())
+        return f"{type(self).__name__}({', '.join(attrs)})"
 
-def cos(x: float, /) -> float:
-    """Return the cosine of x (measured in degrees)."""
-    return math.cos(deg2rad(x))
+    def __str__(self) -> str:
+        return repr(self)
 
+    cls.__repr__ = __repr__
+    cls.__str__ = __str__
 
-def arctan(x: float, /) -> float:
-    """Return the arc tangent (measured in degrees) of x."""
-    return rad2deg(math.atan(x))
+    return cls
 
 
 def round_(ndigits: int) -> Callable:

geolysis/utils/math.py

@@ -0,0 +1,59 @@
+import math
+from math import exp, inf, isclose, log10, pi, sqrt, isinf, atan, nan, isnan
+from statistics import fmean as mean
+
+__all__ = [
+    "atan",
+    "inf",
+    "isinf",
+    "pi",
+    "deg2rad",
+    "rad2deg",
+    "tandeg",
+    "cotdeg",
+    "sindeg",
+    "cosdeg",
+    "arctandeg",
+    "mean",
+    "exp",
+    "isclose",
+    "log10",
+    "sqrt",
+    "nan",
+    "isnan",
+]
+
+
+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 tandeg(x: float, /) -> float:
+    """Return the tangent of x (measured in degrees)."""
+    return math.tan(deg2rad(x))
+
+
+def cotdeg(x: float, /) -> float:
+    """Return the cotangent of x (measured in degrees)."""
+    return 1 / tandeg(x)
+
+
+def sindeg(x: float, /) -> float:
+    """Return the sine of x (measured in degrees)."""
+    return math.sin(deg2rad(x))
+
+
+def cosdeg(x: float, /) -> float:
+    """Return the cosine of x (measured in degrees)."""
+    return math.cos(deg2rad(x))
+
+
+def arctandeg(x: float, /) -> float:
+    """Return the arc tangent (measured in degrees) of x."""
+    return rad2deg(math.atan(x))