pyelogp 0.1.1__tar.gz

pyelogp-0.1.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DongDong
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyelogp-0.1.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: pyelogp
+Version: 0.1.1
+Summary: A lightweight Python library to estimate preconsolidation pressure using volumetric strain energy method with knee detection in the e-log(P) space.
+Project-URL: Homepage, https://github.com/liangchow/pyelogp
+Project-URL: Issues, https://github.com/liangchow/pyelogp/issues
+Author-email: Liang Chern Chow <liangchern@gmail.com>, Thierno Kane <tkane83@gmail.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: consolidation,geotechnical,settlement
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: kneed>=0.8.0
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Description-Content-Type: text/markdown
+
+# PyelogP
+
+"Py e-log(P)" is a lightweight Python library for estimating the preconsolidation pressure (*P'c*) of oedometer test data using the strain-energy method with knee-point detection and thresholding in the e-log(P) space.
+
+![San Francisco Bay Mud (Bonaparte & Mitchell, 1976)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/sfbaymud.png)<br/>
+![Wallaceburg clay (Becker et al., 1987)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/wallaceburgclay.png)<br/>
+![Louiseville clay (TPM, 1996)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/louisevilleclay.png)
+
+## Features
+
+- Manual data input or import from a `.csv` file.
+- Automatic removal of unload–reload cycles from input data.
+- (*Beta*) Threshold-based fitting range selection for S-shaped curves.
+
+## Installation
+
+```bash
+pip install pyelogp
+```
+
+### Clone from GitHub
+
+```bash
+git clone https://github.com/liangchow/pyelogp.git
+cd pyelogp
+python -m venv .venv           # Recommended to use venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Quick start
+
+See `run.py` for a full example, including loading data from a CSV file via `Data.from_csv`.
+
+```python
+from pyelogp import Data
+
+# Louiseville clay
+pressure = [59, 90, 120, 150, 165, 172, 184, 222, 300, 400]
+void_ratio = [2.115, 2.113, 2.098, 2.083, 2.055, 2, 1.8, 1.5, 1.3, 1.193]
+e0 = 1.21 (Optional)
+
+d = Data(pressure=pressure, void_ratio=void_ratio, e0=e0)
+
+# Run analysis
+result = d.find_pc()
+print(f"Pc  = {result.pc:.1f}")
+print(f"e @ Pc = {result.e_pc:.4f}")
+print(f"R²(seg1) = {result.r2_seg1:.4f}")
+print(f"R²(seg2) = {result.r2_seg2:.4f}")
+
+# Return
+Preconsolidation pressure (Pc): 164.49
+Void ratio at pc (e_pc): 2.0573
+R² segment 1: 0.893768
+R² segment 2: 0.96937
+```
+
+## Contributing
+
+Contributions are welcome, please refer to [CONTRIBUTING](https://github.com/liangchow/pyelogp/blob/main/CONTRIBUTING.md)
+to learn more about how to contribute.
+
+## References
+
+Becker, D. E., Crooks, J. H. A., Been, K., & Jefferies, M. G. (1987).
+*Work as a Criterion for Determining in situ and Yield Stresses in Clays.*
+Canadian Geotechnical Journal, 24(4), 549–564.
+
+Bonaparte, R. and Mitchell, J.K. (1979).
+*The Properties of San Francisco Bay Mud at Hamilton Air Force Base, California.* 
+Geotechnical Engineering Report, University of California, Berkeley, April 1979.
+
+Satopa, V., Albrecht, J., Irwin, D., and Raghavan, B. (2011). 
+*Finding a 'Kneedle' in a Haystack: Detecting Knee Points in System Behavior.* 
+31st International Conference on Distributed Computing Systems Workshops, 166-171.
+
+Terzaghi, K., Peck, R.B., & Mesri, G. (1996). 
+*Soil Mechanics in Engineering Practice (3rd ed.).* 
+John Wiley & Sons, Inc.

pyelogp-0.1.1/README.md

@@ -0,0 +1,80 @@
+# PyelogP
+
+"Py e-log(P)" is a lightweight Python library for estimating the preconsolidation pressure (*P'c*) of oedometer test data using the strain-energy method with knee-point detection and thresholding in the e-log(P) space.
+
+![San Francisco Bay Mud (Bonaparte & Mitchell, 1976)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/sfbaymud.png)<br/>
+![Wallaceburg clay (Becker et al., 1987)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/wallaceburgclay.png)<br/>
+![Louiseville clay (TPM, 1996)](https://raw.githubusercontent.com/liangchow/PyelogP/main/images/louisevilleclay.png)
+
+## Features
+
+- Manual data input or import from a `.csv` file.
+- Automatic removal of unload–reload cycles from input data.
+- (*Beta*) Threshold-based fitting range selection for S-shaped curves.
+
+## Installation
+
+```bash
+pip install pyelogp
+```
+
+### Clone from GitHub
+
+```bash
+git clone https://github.com/liangchow/pyelogp.git
+cd pyelogp
+python -m venv .venv           # Recommended to use venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Quick start
+
+See `run.py` for a full example, including loading data from a CSV file via `Data.from_csv`.
+
+```python
+from pyelogp import Data
+
+# Louiseville clay
+pressure = [59, 90, 120, 150, 165, 172, 184, 222, 300, 400]
+void_ratio = [2.115, 2.113, 2.098, 2.083, 2.055, 2, 1.8, 1.5, 1.3, 1.193]
+e0 = 1.21 (Optional)
+
+d = Data(pressure=pressure, void_ratio=void_ratio, e0=e0)
+
+# Run analysis
+result = d.find_pc()
+print(f"Pc  = {result.pc:.1f}")
+print(f"e @ Pc = {result.e_pc:.4f}")
+print(f"R²(seg1) = {result.r2_seg1:.4f}")
+print(f"R²(seg2) = {result.r2_seg2:.4f}")
+
+# Return
+Preconsolidation pressure (Pc): 164.49
+Void ratio at pc (e_pc): 2.0573
+R² segment 1: 0.893768
+R² segment 2: 0.96937
+```
+
+## Contributing
+
+Contributions are welcome, please refer to [CONTRIBUTING](https://github.com/liangchow/pyelogp/blob/main/CONTRIBUTING.md)
+to learn more about how to contribute.
+
+## References
+
+Becker, D. E., Crooks, J. H. A., Been, K., & Jefferies, M. G. (1987).
+*Work as a Criterion for Determining in situ and Yield Stresses in Clays.*
+Canadian Geotechnical Journal, 24(4), 549–564.
+
+Bonaparte, R. and Mitchell, J.K. (1979).
+*The Properties of San Francisco Bay Mud at Hamilton Air Force Base, California.* 
+Geotechnical Engineering Report, University of California, Berkeley, April 1979.
+
+Satopa, V., Albrecht, J., Irwin, D., and Raghavan, B. (2011). 
+*Finding a 'Kneedle' in a Haystack: Detecting Knee Points in System Behavior.* 
+31st International Conference on Distributed Computing Systems Workshops, 166-171.
+
+Terzaghi, K., Peck, R.B., & Mesri, G. (1996). 
+*Soil Mechanics in Engineering Practice (3rd ed.).* 
+John Wiley & Sons, Inc.

pyelogp-0.1.1/data/example.csv

@@ -0,0 +1,14 @@
+# Below is an example data of Wallaceburg Clay (Becker et al., 1987) with a "," delimeter.
+# e0 = 1.24
+# pressure, void ratio
+10.0, 1.212
+24.6, 1.180
+48.5, 1.148
+97.2, 1.098
+189.2, 1.005
+382.3, 0.871
+755.8, 0.756
+1493.6, 0.647
+386.0, 0.687
+96.4, 0.743
+10.0, 0.849

pyelogp-0.1.1/pyelogp/__init__.py

@@ -0,0 +1,5 @@
+from .data    import Data
+from .find_pc import FindPc, PcResult
+
+__all__ = ["Data", "FindPc", "PcResult"]
+__version__ = "0.1.1"

pyelogp-0.1.1/pyelogp/data.py

@@ -0,0 +1,202 @@
+"""
+pyelogp.data
+============
+Data ingestion and pre-processing for consolidation test analysis.
+
+Typical usage
+-------------
+>>> from pyelogp import Data
+>>> d = Data(
+    pressure=[59, 90, 120, 150, 165, 172, 184, 222, 300, 400], 
+    void_ratio=[2.115, 2.113, 2.098, 2.083, 2.055, 2, 1.8, 1.5, 1.3, 1.193])
+>>> d.log_p          # log10 of pressure (1-D ndarray)
+>>> result = d.find_pc()
+>>> print(result.pc)
+"""
+
+import numpy as np
+
+DATA_DTYPE = np.dtype([
+    ("idx",     np.intp),
+    ("p",       np.float64),
+    ("log_p",   np.float64),
+    ("e",       np.float64),
+    ("epsilon", np.float64),
+    ("dwork",   np.float64),
+    ("work",    np.float64),
+])
+
+class Data:
+    """
+    Container and pre-processor for a consolidation test dataset.
+
+    Parameters
+    ----------
+    pressure : array-like
+        Applied vertical effective stress values (any consistent pressure unit).
+        Must be non-negative. Zero is allowed and is handled internally.
+    void_ratio : array-like
+        Measured void ratios corresponding to each pressure step.
+    e0 : float, optional
+        Initial void ratio at the start of the test.  Defaults to
+        ``void_ratio[0]`` when not supplied.
+
+    Attributes (available after construction)
+    -----------------------------------------
+    dc : NDArray
+        Full structured array for the entire dataset (all loading/unloading
+        steps), fields: idx, p, log_p, e, epsilon, dwork, work.
+    lc : NDArray
+        Loading-curve only; unloading–reloading rows removed and rows with
+        non-finite log_p dropped.
+
+    Column accessors (dot-access shortcuts on `dc`)
+    ------------------------------------------------
+    p, log_p, e, epsilon, dwork, work
+        Each returns the corresponding column of ``dc`` as a plain ndarray.
+    """
+
+    def __init__(self, pressure, void_ratio, e0=None):
+        x = np.asarray(pressure, dtype=np.float64)
+        y = np.asarray(void_ratio, dtype=np.float64)
+
+        if x.shape != y.shape:
+            raise ValueError("pressure and void_ratio must have the same length.")
+        if np.any(x < 0):
+            raise ValueError("All pressure values must be non-negative.")
+        
+        self.e0 = float(y[0]) if e0 is None else float(e0)
+        self.dc = self._preprocess(x, y, self.e0)
+        self.lc = self._remove_loginf_rl_unl_rows(self.dc)
+
+    def __getattr__(self, name):
+        if name in DATA_DTYPE.names:
+            return self.dc[name]
+        raise AttributeError(f"'Data' object has no attribute '{name}'")
+
+    def find_pc(self, **kwargs):
+        from .find_pc import FindPc
+        return FindPc(self, **kwargs).run()
+
+    @classmethod
+    def from_csv(cls, path, pressure_col=0, void_ratio_col=1, delimiter=",", e0=None):
+        """
+        Construct a Data instance from a CSV file.
+
+        Parameters
+        ----------
+        path : str
+            Path to the CSV file (e.g. ``"data/example.csv"``).
+        pressure_col : int, optional
+            Column index for pressure values. Default is 0 (first column).
+        void_ratio_col : int, optional
+            Column index for void-ratio values. Default is 1 (second column).
+        delimiter : str, optional
+            Field delimiter. Default is ``","``.
+        e0 : float, optional
+            Initial void ratio. Defaults to ``void_ratio[0]`` when not supplied.
+
+        Returns
+        -------
+        Data
+
+        Examples
+        --------
+        >>> d = Data.from_csv("data/example.csv")
+        >>> d = Data.from_csv("data/example.csv", pressure_col=0, void_ratio_col=1)
+        """
+        raw = np.loadtxt(path, delimiter=delimiter)
+
+        if raw.ndim != 2:
+            raise ValueError(
+                f"Expected a 2-D array from '{path}', got shape {raw.shape}. "
+                "Check your delimiter settings."
+            )
+
+        n_cols = raw.shape[1]
+        for col_name, col_idx in (("pressure_col", pressure_col), ("void_ratio_col", void_ratio_col)):
+            if col_idx >= n_cols:
+                raise ValueError(
+                    f"{col_name}={col_idx} is out of range — file only has {n_cols} column(s)."
+                )
+
+        return cls(
+            pressure=raw[:, pressure_col],
+            void_ratio=raw[:, void_ratio_col],
+            e0=e0,
+        )
+
+    @staticmethod
+    def vol_strain_work(p, epsilon):
+        """
+        Compute incremental and cumulative volumetric strain work.
+        """
+        dwork = 0.5 * (epsilon[1:] - epsilon[:-1]) * (p[1:] + p[:-1])
+        dwork = np.hstack((0.0, dwork))
+        work  = np.cumsum(dwork)
+        return dwork, work
+
+    @staticmethod
+    def _preprocess(x, y, e0):
+        """
+        Build the internal structured array from raw pressure / void-ratio arrays.
+        """
+        if e0 is None:
+            e0 = float(y[0])
+
+        n = len(x)
+        if n == 0:
+            return np.array([], dtype=DATA_DTYPE)
+
+        # Check order of magnitude of p
+        rx    = float(np.max(x) - np.min(x))
+        order = int(np.floor(np.log10(rx))) if rx > 0 else 0
+
+        log_p = np.full(n, np.nan, dtype=np.float64)
+
+        if order > 2:
+            # Large range: treat 0 as NaN (filtered later); keep 0 < x ≤ 1 as-is
+            mask = x > 0
+            log_p[mask] = np.log10(x[mask])
+        else:
+            # Small range: shift zero by half the next step
+            if x[0] == 0:
+                c = np.min(x[x > 0]) / 2
+                log_p = np.log10(np.where(x > 0, x, np.nan))
+                log_p[0] = np.log10(c)
+            else:
+                log_p = np.log10(x)
+
+        epsilon        = (e0 - y) / (1.0 + e0)
+        dwork, work    = Data.vol_strain_work(x, epsilon)
+
+        data            = np.empty(n, dtype=DATA_DTYPE)
+        data["idx"]     = np.arange(n)
+        data["p"]       = x
+        data["log_p"]   = log_p
+        data["e"]       = np.round(y, 4)
+        data["epsilon"] = np.round(epsilon, 5)
+        data["dwork"]   = dwork
+        data["work"]    = work
+
+        return data
+
+    @staticmethod
+    def _remove_loginf_rl_unl_rows(data):
+        """
+        Strip unloading–reloading rows and non-finite log_p entries.
+
+        A row is considered part of the primary loading curve when its
+        pressure strictly exceeds all previously seen pressure values.
+        """
+        max_p   = -np.inf
+        loading = []
+
+        for i, row in enumerate(data):
+            if row["p"] > max_p:
+                max_p = float(row["p"])
+                loading.append(i)
+
+        result = data[loading]
+        mask   = np.isfinite(result["log_p"])
+        return result[mask]

pyelogp-0.1.1/pyelogp/find_pc.py

@@ -0,0 +1,316 @@
+"""
+pyelogp.find_pc
+===============
+Preconsolidation pressure estimation using bilinear fitting in work-p
+space (Becker et al., 1987) with a knee-point detected in e–log(P) space.
+
+Typical usage (via Data)
+------------------------
+>>> from pyelogp import Data
+>>> d = Data.from_csv("data/example.csv")
+>>> result = d.find_pc()
+>>> print(result.pc)          # preconsolidation pressure
+
+Direct usage
+------------
+>>> from pyelogp import Data, FindPc
+>>> d = Data(pressure=[...], void_ratio=[...])
+>>> result = d.find_pc()
+>>> print(result.pc)
+"""
+
+import numpy as np
+from scipy.interpolate import CubicSpline
+from kneed import KneeLocator
+
+class BilinearResult:
+    """
+    Internal result container for :meth:`FindPc._bilinear_w_knee`.
+    """
+    def __init__(self, x_int, y_int, seg1, seg2, r2_seg1, r2_seg2):
+        self.x_int = x_int
+        self.y_int = y_int
+        self.seg1 = seg1
+        self.seg2 = seg2
+        self.r2_seg1 = r2_seg1
+        self.r2_seg2 = r2_seg2
+
+class PcResult:
+    """
+    Final output of :meth:`FindPc.run`.
+
+    Attributes
+    ----------
+    pc : float
+        Estimated preconsolidation pressure.
+    e_pc : float
+        Void ratio at ``pc``. ``nan`` when ``pc`` could not be validated
+        (see ``warnings``).
+    seg1 : list of tuple
+        ``(x, y_fit)`` pairs describing the fitted segment-1 line.
+    seg2 : list of tuple
+        ``(x, y_fit)`` pairs describing the fitted segment-2 line.
+    r2_seg1 : float
+        Coefficient of determination (R2) for segment 1.
+    r2_seg2 : float
+        Coefficient of determination (R2) for segment 2.
+    warnings : list of str
+        Non-fatal issues encountered while producing this result (e.g. a
+        non-physical ``pc``). Empty when none occurred.
+    """
+    def __init__(self, pc, e_pc, seg1, seg2, r2_seg1, r2_seg2, warnings=None):
+        self.pc = pc
+        self.e_pc = e_pc
+        self.seg1 = seg1
+        self.seg2 = seg2
+        self.r2_seg1 = r2_seg1
+        self.r2_seg2 = r2_seg2
+        self.warnings = warnings if warnings is not None else []
+
+# ---------------------------------------------------------------------------
+# Main analysis class
+# ---------------------------------------------------------------------------
+class FindPc:
+    """
+    Estimate the preconsolidation pressure.
+
+    Algorithm summary
+    -----------------
+    1. Fit a cubic spline to the primary loading curve in e–log(P) space.
+    2. Locate the knee of the e–log(P) curve using :class:`kneed.KneeLocator`.
+    3. Perform a bilinear least-squares fit in work–pressure (W–P) space,
+       splitting at the detected knee.
+    4. Compute the intersection of the two lines → preconsolidation pressure (yield stress).
+
+    Parameters
+    ----------
+    data : Data
+        Pre-processed consolidation dataset.
+    n_spline_points : int, optional
+        Number of points used when evaluating the cubic spline for knee
+        detection.  Default is 50.
+    """
+    def __init__(self, data, n_spline_points=50):
+        self._data = data
+        self._n_spline_points = n_spline_points
+
+    def run(self):
+        """
+        Execute the full analysis pipeline and return a :class:`PcResult`.
+
+        Raises
+        ------
+        ValueError
+            If the dataset is too small or the fitting fails.
+        """
+        warnings = []
+        lc = self._data.lc
+
+        if len(lc) < 6:
+            raise ValueError("At least 6 valid loading-curve points are required.")
+
+        cs_fit, cs_curve, log_p_max_d2y = self._cs_profile(
+            lc["log_p"], lc["e"], n_points=self._n_spline_points
+        )
+        p_threshold = np.floor(np.power(10, log_p_max_d2y))
+
+        kl = self._find_knee(lc, cs_curve)
+        if kl.knee is None:
+            raise ValueError("Could not detect a knee in the e–log(P) curve.")
+        knee = np.power(10, kl.knee)
+
+        fit = self._bilinear_w_knee(lc["p"], lc["work"], knee, threshold=p_threshold)
+
+        pc = fit.x_int
+
+        if not np.isfinite(pc) or pc <= 0:
+            warnings.append(
+                f"Computed pc={pc} is non-physical (must be > 0); "
+                "e_pc could not be determined."
+            )
+            e_pc = np.nan
+        else:
+            e_pc = self._find_e(lc, cs_fit, pc)
+
+        def _to_pairs(seg):
+            return [(x, y) for x, y in zip(seg["x"], seg["y_fit"])]
+
+        return PcResult(
+            pc=pc,
+            e_pc=e_pc,
+            seg1=_to_pairs(fit.seg1),
+            seg2=_to_pairs(fit.seg2),
+            r2_seg1=fit.r2_seg1,
+            r2_seg2=fit.r2_seg2,
+            warnings=warnings,
+        )
+
+    @staticmethod
+    def _r2(y_actual, y_pred):
+        """
+        Coefficient of determination (R2).
+        """
+        ss_res = np.sum((y_actual - y_pred) ** 2)
+        ss_tot = np.sum((y_actual - np.mean(y_actual)) ** 2)
+        return (1.0 - ss_res / ss_tot) if ss_tot != 0 else 1.0
+
+    @staticmethod
+    def _find_e(lc, cs, sigma_v):
+        """
+        Interpolate void ratio at ``sigma_v`` using the cubic spline ``cs``.
+
+        Falls back to linear extrapolation when ``sigma_v`` is below the
+        spline's fitted range.
+
+        Parameters
+        ----------
+        lc : NDArray
+            Loading-curve structured array.
+        cs : CubicSpline
+            Spline fitted in log(P) space.
+        sigma_v : float
+            Target pressure.
+
+        Returns
+        -------
+        float
+        """
+        x = np.log10(sigma_v)
+        x_min, x_max = cs.x[0], cs.x[-1]
+
+        if x < x_min:
+            # Linear extrapolation from the first two LC points
+            p0, p1 = lc["p"][:2]
+            e0, e1 = lc["e"][:2]
+            slope  = (e1 - e0) / (p1 - p0)
+            e      = e0 + slope * (sigma_v - p0)
+        else:
+            e = cs(np.clip(x, x_min, x_max))
+
+        return np.round(e, 4)
+
+    @staticmethod
+    def _cs_profile(x, y, n_points=50):
+        """
+        Fit a cubic spline and return curvature information.
+
+        Parameters
+        ----------
+        x : ndarray
+            log(P) values of the loading curve.
+        y : ndarray
+            Void-ratio values.
+        n_points : int
+            Evaluation density for the dense curve.
+
+        Returns
+        -------
+        cs : CubicSpline
+        cs_curve : ndarray, shape (n_points, 5)
+            Columns: x_dense, y_dense
+        log_p_max_d2y : float
+            log(P) at the location of maximum second derivative.
+        """
+        order  = np.argsort(x)
+        x_fit, y_fit = x[order], y[order]
+
+        cs       = CubicSpline(x_fit, y_fit)
+        x_dense  = np.linspace(x_fit.min(), x_fit.max(), n_points)
+        y_dense  = cs(x_dense)
+        d2y      = cs(x_dense, 2)
+
+        idx_max_d2y    = int(np.argmax(d2y))
+        log_p_max_d2y  = x_dense[idx_max_d2y]
+
+        return cs, np.column_stack((x_dense, y_dense)), log_p_max_d2y
+
+    @staticmethod
+    def _find_knee(lc, cs_curve, min_len=10):
+        """
+        Locate the knee of the e–log(P) curve.
+
+        Uses the dense spline curve for small datasets and the raw loading-curve
+        data for larger ones.
+
+        Parameters
+        ----------
+        lc : NDArray
+            Loading-curve structured array.
+        cs_curve : ndarray
+            Dense curve array from :meth:`_cs_profile`.
+        min_len : int
+            Dataset-length threshold for switching strategy.
+
+        Returns
+        -------
+        KneeLocator
+        """
+        x, y = lc["log_p"], lc["e"]
+
+        if len(lc) <= min_len:
+            kl = KneeLocator(
+                cs_curve[:, 0], cs_curve[:, 1],
+                curve="concave", direction="decreasing", online=True
+            )
+            if kl.knee is not None and kl.knee != cs_curve[:, 0][-1]:
+                return kl
+
+        return KneeLocator(x, y, curve="concave", direction="decreasing", online=True)
+
+    @staticmethod
+    def _bilinear_w_knee(x, y, knee, threshold=None):
+        """
+        Bilinear least-squares fit split at the knee point.
+
+        Parameters
+        ----------
+        x : ndarray
+            Pressure values of the loading curve.
+        y : ndarray
+            Cumulative work values.
+        knee : float
+            Pressure value of the detected knee (in native pressure units).
+        threshold : float, optional
+            Upper pressure limit for segment 2 (uses max curvature location).
+
+        Returns
+        -------
+        BilinearResult
+
+        Raises
+        ------
+        ValueError
+            When segments contain too few points or the lines are parallel.
+        """
+        knee_idx = int(np.searchsorted(x, knee, side="right") - 1)
+
+        if knee_idx < 1:
+            raise ValueError("Not enough points in segment 1.")
+        best_k = knee_idx + 1
+
+        if best_k > len(x) - 2:
+            raise ValueError(
+                "Not enough points in segment 2; the detected knee is too close "
+                "to the end of the dataset."
+            )
+
+        end_k = min(len(x), max(int(np.searchsorted(x, threshold, side="right")) if threshold is not None else len(x), best_k + 3))
+
+        coeffs1 = np.polyfit(x[:best_k], y[:best_k], deg=1)
+        coeffs2 = np.polyfit(x[best_k:end_k], y[best_k:end_k], deg=1)
+
+        dslope = coeffs1[0] - coeffs2[0]
+
+        if np.isclose(dslope, 0, atol=1e-10):
+            raise ValueError("Lines are parallel; cannot determine intersection.")
+
+        x_int = (coeffs2[1] - coeffs1[1]) / dslope
+        
+        return BilinearResult(
+            x_int=np.round(x_int, 2), y_int=np.polyval(coeffs1, x_int),
+            seg1={"x": np.array([x[0], x_int]), "y_fit": np.polyval(coeffs1, np.array([x[0], x_int]))},
+            seg2={"x": np.array([x_int, x[end_k - 1]]), "y_fit": np.polyval(coeffs2, np.array([x_int, x[end_k - 1]]))},
+            r2_seg1=np.round(FindPc._r2(y[:best_k], np.polyval(coeffs1, x[:best_k])), 6),
+            r2_seg2=np.round(FindPc._r2(y[best_k:end_k], np.polyval(coeffs2, x[best_k:end_k])), 6),
+        )
+

pyelogp-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyelogp"
+version = "0.1.1"
+authors = [
+    {name="Liang Chern Chow", email="liangchern@gmail.com"},
+    {name="Thierno Kane", email="tkane83@gmail.com"}
+]
+description = "A lightweight Python library to estimate preconsolidation pressure using volumetric strain energy method with knee detection in the e-log(P) space."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+keywords = [
+    "geotechnical",
+    "consolidation",
+    "settlement",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "numpy>=1.21.0",
+    "scipy>=1.7.0",
+    "kneed>=0.8.0",
+    "matplotlib>=3.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/liangchow/pyelogp"
+Issues = "https://github.com/liangchow/pyelogp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pyelogp"]

pyelogp-0.1.1/requirements.txt

@@ -0,0 +1,4 @@
+numpy>=1.21.0
+scipy>=1.7.0
+kneed>=0.8.0
+matplotlib>=3.10

pyelogp-0.1.1/run.py

@@ -0,0 +1,40 @@
+from pyelogp import Data
+
+# Example 1 --- Run analysis on .csv file.
+# Becker et al. (1987): Wallaceburg Clay, P'c (Casangrade)=115 kPa, P'vy=120 kPa, OCR=1.33
+# See data/example.csv
+d1 = Data.from_csv("data/example.csv", e0=1.24)
+result = d1.find_pc()
+
+print("Preconsolidation pressure (Pc):", result.pc)
+print("Void ratio at pc (e_pc):", result.e_pc)
+print("R² segment 1:", result.r2_seg1)
+print("R² segment 2:", result.r2_seg2)
+
+
+# Example 2 --- Run analysis directly on pressure and void_ratio arrays.
+# TPM (1996): Louiseville Clay, P'c=165 kPa, OCR=2.8
+pressure = [59, 90, 120, 150, 165, 172, 184, 222, 300, 400]
+void_ratio = [2.115, 2.113, 2.098, 2.083, 2.055, 2, 1.8, 1.5, 1.3, 1.193]
+e0=1.21
+
+d2 = Data(pressure=pressure, void_ratio=void_ratio, e0=e0)
+result = d2.find_pc()
+
+print("Preconsolidation pressure (Pc):", result.pc)
+print("Void ratio at pc (e_pc):", result.e_pc)
+print("R² segment 1:", result.r2_seg1)
+print("R² segment 2:", result.r2_seg2)
+
+# returns:
+# Wallaceburg Clay:
+# Pc = 113.86
+# e_pc = 1.0804
+# R2,seg1 = 0.983665
+# R2,seg2 = 0.998988
+
+# Louiseville Clay:
+# Pc = 164.49
+# e_pc = 2.0573
+# R2,seg1 = 0.89377
+# R2,seg2 = 0.96937

pyelogp-0.1.1/tests/test_core.py

@@ -0,0 +1,283 @@
+import warnings
+import pytest
+import numpy as np
+from pyelogp import Data
+from pyelogp.find_pc import FindPc
+
+# ---------------------------------------------------------------------------
+# Original tests
+# ---------------------------------------------------------------------------
+
+def test_data_initialization():
+    """Verify that Data object calculates expected columns."""
+    pressure = [10, 20, 40, 80, 160]
+    void_ratio = [1.2, 1.1, 1.0, 0.9, 0.8]
+    d = Data(pressure, void_ratio)
+
+    # Check if dot access works
+    assert len(d.log_p) == 5
+    assert isinstance(d.dc, np.ndarray)
+
+def test_data_initialization_w_e0():
+    """Verify that Data object calculates expected columns."""
+    pressure = [10, 20, 40, 80, 160]
+    void_ratio = [1.2, 1.1, 1.0, 0.9, 0.8]
+    e0 = 1.21
+    d = Data(pressure, void_ratio, e0)
+
+    # Check if dot access works
+    assert len(d.log_p) == 5
+    assert isinstance(d.dc, np.ndarray)
+
+
+def test_find_pc_logic():
+    """Verify find_pc runs without error on valid input."""
+    pressure = [10, 20, 40, 80, 160, 320, 640]
+    void_ratio = [1.2, 1.12, 1.03, 0.93, 0.81, 0.68, 0.54]
+
+    d = Data(pressure, void_ratio)
+    result = d.find_pc()
+
+    # Check if a result object is returned
+    assert result.pc > 0
+    assert result.e_pc > 0
+
+
+def test_insufficient_data_raises_error():
+    """Verify that too few points raise a ValueError."""
+    pressure = [10, 20]
+    void_ratio = [1.2, 1.1]
+
+    d = Data(pressure, void_ratio)
+    with pytest.raises(ValueError, match="At least 6 valid loading-curve points are required."):
+        d.find_pc()
+
+
+# ---------------------------------------------------------------------------
+# Shared fixtures: shape-preserving datasets scaled to span a "small" range
+# (0-10) and a "large" range (0-10,000+), each including pressure points
+# between 0 and 1 (with decimals), and each starting at exactly 0.
+#
+# Both datasets are derived from the same known-good e-log(P) shape used in
+# test_find_pc_logic above, just rescaled, so the underlying curvature/knee
+# behavior is preserved and find_pc() is expected to converge cleanly.
+# ---------------------------------------------------------------------------
+
+_BASE_P = np.array([10.0, 20.0, 40.0, 80.0, 160.0, 320.0, 640.0])
+_BASE_E = [1.20, 1.12, 1.03, 0.93, 0.81, 0.68, 0.54]
+
+
+@pytest.fixture
+def small_range_data():
+    """Pressure spans 0 -> 10, including sub-1 decimal points."""
+    pressure = [0, 0.05] + (_BASE_P / 64.0).tolist()
+    void_ratio = [1.205, 1.203] + _BASE_E
+    return pressure, void_ratio
+
+
+@pytest.fixture
+def large_range_data():
+    """Pressure spans 0 -> ~10,240, including sub-1 decimal points."""
+    pressure = [0, 0.5, 1] + (_BASE_P * 16.0).tolist()
+    void_ratio = [1.205, 1.203, 1.201] + _BASE_E
+    return pressure, void_ratio
+
+
+# ---------------------------------------------------------------------------
+# Small pressure range (0-10), with decimal points between 0 and 1
+# ---------------------------------------------------------------------------
+
+class TestSmallPressureRange:
+
+    def test_initializes_and_preserves_point_count(self, small_range_data):
+        pressure, void_ratio = small_range_data
+        d = Data(pressure, void_ratio)
+        assert len(d.dc) == len(pressure)
+        assert isinstance(d.dc, np.ndarray)
+
+    def test_decimal_points_below_one_are_finite_in_loading_curve(self, small_range_data):
+        pressure, void_ratio = small_range_data
+        d = Data(pressure, void_ratio)
+        # every pressure < 1 in the input (0.05, 0.15625, 0.3125, 0.625) must
+        # survive into the loading curve with a finite log_p
+        sub_one = [p for p in pressure if 0 < p < 1]
+        assert len(sub_one) > 0
+        assert np.all(np.isfinite(d.lc["log_p"]))
+        lc_p = set(np.round(d.lc["p"], 6))
+        for p in sub_one:
+            assert round(p, 6) in lc_p
+
+    def test_zero_pressure_point_is_retained_via_shift_trick(self, small_range_data):
+        pressure, void_ratio = small_range_data
+        d = Data(pressure, void_ratio)
+        # in the "small range" branch (order <= 2), a leading zero pressure
+        # is NOT dropped: log_p[0] is computed via a half-step shift
+        # (log10(x[1] / 2)), so it survives into the loading curve with a
+        # finite log_p -- unlike the large-range branch (see
+        # TestLargePressureRange.test_zero_pressure_point_is_dropped_from_loading_curve)
+        assert 0.0 in d.lc["p"]
+        assert np.isfinite(d.dc["log_p"][0])
+
+    def test_find_pc_runs_and_returns_physical_result(self, small_range_data):
+        pressure, void_ratio = small_range_data
+        d = Data(pressure, void_ratio)
+        result = d.find_pc()
+        assert result.pc > 0
+        assert result.pc < max(pressure)
+        assert not np.isnan(result.e_pc)
+        assert 0 < result.e_pc < void_ratio[0]
+
+    def test_work_is_monotonically_nondecreasing(self, small_range_data):
+        pressure, void_ratio = small_range_data
+        d = Data(pressure, void_ratio)
+        # cumulative volumetric strain work should never decrease for a
+        # consolidating (compressing) loading curve
+        assert np.all(np.diff(d.lc["work"]) >= -1e-9)
+
+
+# ---------------------------------------------------------------------------
+# Large pressure range (0-10,000+), with decimal points between 0 and 1
+# ---------------------------------------------------------------------------
+
+class TestLargePressureRange:
+
+    def test_initializes_and_preserves_point_count(self, large_range_data):
+        pressure, void_ratio = large_range_data
+        d = Data(pressure, void_ratio)
+        assert len(d.dc) == len(pressure)
+        assert isinstance(d.dc, np.ndarray)
+
+    def test_decimal_points_below_one_are_finite_in_loading_curve(self, large_range_data):
+        pressure, void_ratio = large_range_data
+        d = Data(pressure, void_ratio)
+        sub_one = [p for p in pressure if 0 < p < 1]
+        assert len(sub_one) > 0
+        assert np.all(np.isfinite(d.lc["log_p"]))
+        lc_p = set(np.round(d.lc["p"], 6))
+        for p in sub_one:
+            assert round(p, 6) in lc_p
+
+    def test_zero_pressure_point_is_dropped_from_loading_curve(self, large_range_data):
+        pressure, void_ratio = large_range_data
+        d = Data(pressure, void_ratio)
+        assert 0.0 not in d.lc["p"]
+
+    def test_find_pc_runs_and_returns_physical_result(self, large_range_data):
+        pressure, void_ratio = large_range_data
+        d = Data(pressure, void_ratio)
+        result = d.find_pc()
+        assert result.pc > 0
+        assert result.pc < max(pressure)
+        assert not np.isnan(result.e_pc)
+        assert 0 < result.e_pc < void_ratio[0]
+
+    def test_large_and_small_range_use_different_log_p_strategies(
+        self, small_range_data, large_range_data
+    ):
+        # documents the order > 2 branch split in Data._preprocess: large
+        # range data must NOT use the index-0 zero-shift trick the small
+        # range branch uses, since order = floor(log10(rx)) > 2 here
+        s_pressure, s_void = small_range_data
+        l_pressure, l_void = large_range_data
+        d_small = Data(s_pressure, s_void)
+        d_large = Data(l_pressure, l_void)
+        # small range's first (zero) point gets a finite shifted log_p
+        assert np.isfinite(d_small.dc["log_p"][0])
+        # large range's first (zero) point is NaN by design (mask = x > 0)
+        assert np.isnan(d_large.dc["log_p"][0])
+
+
+# ---------------------------------------------------------------------------
+# Cross-cutting / shared behavior across both ranges
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("range_fixture", ["small_range_data", "large_range_data"])
+def test_e0_defaults_to_first_void_ratio(range_fixture, request):
+    pressure, void_ratio = request.getfixturevalue(range_fixture)
+    d = Data(pressure, void_ratio)
+    assert d.e0 == pytest.approx(void_ratio[0])
+
+
+@pytest.mark.parametrize("range_fixture", ["small_range_data", "large_range_data"])
+def test_explicit_e0_overrides_default(range_fixture, request):
+    pressure, void_ratio = request.getfixturevalue(range_fixture)
+    d = Data(pressure, void_ratio, e0=2.0)
+    assert d.e0 == 2.0
+    assert d.dc["epsilon"][0] != pytest.approx((void_ratio[0] - void_ratio[0]) / (1 + void_ratio[0]))
+
+
+@pytest.mark.parametrize("range_fixture", ["small_range_data", "large_range_data"])
+def test_mismatched_lengths_raise_value_error(range_fixture, request):
+    pressure, void_ratio = request.getfixturevalue(range_fixture)
+    with pytest.raises(ValueError, match="same length"):
+        Data(pressure, void_ratio[:-1])
+
+
+@pytest.mark.parametrize("range_fixture", ["small_range_data", "large_range_data"])
+def test_negative_pressure_raises_value_error(range_fixture, request):
+    pressure, void_ratio = request.getfixturevalue(range_fixture)
+    bad_pressure = list(pressure)
+    bad_pressure[1] = -bad_pressure[1] - 0.01 if bad_pressure[1] != 0 else -1.0
+    with pytest.raises(ValueError, match="non-negative"):
+        Data(bad_pressure, void_ratio)
+
+
+# ---------------------------------------------------------------------------
+# Fixed issues (regression tests).
+#
+# These tests previously pinned buggy behavior (see git history / CHANGELOG).
+# The underlying bugs have since been fixed in find_pc.py; these tests now
+# pin the corrected behavior so any regression is caught.
+# ---------------------------------------------------------------------------
+
+class TestFixedIssues:
+
+    def test_knee_at_last_point_raises_value_error_gracefully(self):
+        """
+        FIXED: when the detected knee lands on (or one point before) the
+        final loading-curve sample, segment 2 of the bilinear fit would
+        become empty and np.polyfit raised an unhandled TypeError. This is
+        now caught early and raised as a clean, documented ValueError.
+        """
+        x = np.array([1.0, 2, 4, 8, 16, 32])
+        y = np.array([0, 0.5, 1.5, 3.5, 8, 20.0])
+        knee = 32.0  # forces knee_idx = len(x) - 1
+        with pytest.raises(ValueError, match="Not enough points in segment 2"):
+            FindPc._bilinear_w_knee(x, y, knee, threshold=None)
+
+    def test_threshold_of_exactly_zero_is_respected(self):
+        """
+        FIXED: `if threshold else len(x)` treated a legitimate
+        threshold of 0.0 the same as no threshold (falsy check instead of
+        `is not None`). Now `threshold=0.0` is honored and produces a
+        different, tighter segment-2 boundary than `threshold=None`.
+        """
+        x = np.array([1.0, 2, 4, 8, 16, 32, 64, 128])
+        y = np.array([0, 0.5, 1.5, 3.5, 8, 20, 50, 130.0])
+        knee = 8.0
+        result_zero = FindPc._bilinear_w_knee(x, y, knee, threshold=0.0)
+        result_none = FindPc._bilinear_w_knee(x, y, knee, threshold=None)
+        assert not np.allclose(result_zero.seg2["x"], result_none.seg2["x"])
+        # threshold=0.0 forces the earliest possible split (best_k + 3)
+        assert result_zero.seg2["x"][-1] == pytest.approx(64.0)
+        assert result_none.seg2["x"][-1] == pytest.approx(128.0)
+
+    def test_negative_pc_is_validated_and_recorded_as_warning(self):
+        """
+        FIXED: when the bilinear intersection extrapolates to a negative
+        pressure, find_pc() now validates `pc` before computing `e_pc`,
+        avoiding the invalid `log10` call and recording the issue in
+        `result.warnings` instead of silently returning a corrupted,
+        unexplained `nan`.
+        """
+        pressure = [0, 0.5, 1, 10, 100, 500, 1000, 2500, 5000, 10000]
+        void_ratio = [1.50, 1.498, 1.495, 1.48, 1.40, 1.10, 0.85, 0.70, 0.60, 0.52]
+        d = Data(pressure, void_ratio)
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", RuntimeWarning)
+            result = d.find_pc()
+        assert result.pc < 0
+        assert np.isnan(result.e_pc)
+        assert len(result.warnings) == 1
+        assert "non-physical" in result.warnings[0]
+